vta-service 0.62.0

//! `POST /bootstrap/request` — TEE first-boot sealed-bootstrap endpoint.
//!
//! This endpoint only handles **Mode B**: a fresh TEE VTA that has no admin
//! yet. The server generates an attestation quote committing to the client
//! pubkey, nonce, and its own ephemeral producer pubkey, mints an Admin
//! credential, and closes the first-boot carve-out permanently. The bundle's
//! assertion is `Attested(quote)` so the consumer can verify end-to-end
//! without any prior shared secret.
//!
//! The former Mode A (token-gated online bootstrap for non-TEE VTAs) was
//! removed: non-TEE clients now use `pnm setup`'s unified temp-did:key
//! flow (client mints locally, admin grants via `vta acl create`, PNM
//! rotates on first authenticated connect).
//!
//! Only the holder of the VTA's configured `tee.bootstrap_claim_did` may
//! claim: the request must name it as `client_did` and be signed by its key.
//! Anyone else is refused before anything is minted, even if the carve-out
//! sentinel has gone missing (a host forging its absence, or a lost write).

use axum::Json;
use axum::extract::State;
use axum::response::IntoResponse;
#[cfg(feature = "tee")]
use base64::Engine;
#[cfg(feature = "tee")]
use base64::engine::general_purpose::URL_SAFE_NO_PAD as B64URL;
use serde::{Deserialize, Serialize};

#[cfg(feature = "tee")]
use sha2::{Digest, Sha256};
#[cfg(feature = "tee")]
use tracing::info;
#[cfg(feature = "tee")]
use vta_sdk::credentials::CredentialBundle;
#[cfg(feature = "tee")]
use vta_sdk::sealed_transfer::{
    AssertionProof, AttestationQuoteAssertion, ProducerAssertion, SealedPayloadV1, armor,
    bundle_digest, generate_ed25519_keypair, seal_payload,
};

#[cfg(feature = "tee")]
use crate::acl::delete_acl_entry;
#[cfg(feature = "tee")]
use crate::acl::store_acl_entry;
#[cfg(feature = "tee")]
use crate::acl::{AclEntry, Role};
#[cfg(feature = "tee")]
use crate::audit::audit;
use crate::auth::session::now_epoch;
use crate::error::AppError;
#[cfg(feature = "tee")]
use crate::sealed_nonce_store::PersistentNonceStore;
use crate::server::AppState;

/// Maximum length (in bytes) of the operator-supplied bootstrap label.
/// The wire body is already capped globally, but the label is the only
/// free-form attacker-controlled string in this DTO and ends up in audit
/// logs — keep it short so an aggressive logger can't spill MBs.
const MAX_LABEL_LEN: usize = 256;

/// Request body. `#[serde(deny_unknown_fields)]` so a client cannot smuggle
/// in `requested_role` / `allowed_contexts` — minting parameters are
/// determined entirely by attestation policy.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
#[derive(utoipa::ToSchema)]
pub struct BootstrapRequestBody {
    /// Wire-format version. Currently 1.
    pub version: u8,
    /// Consumer's ephemeral `did:key` (Ed25519). The server derives the
    /// X25519 pubkey from this for the HPKE seal.
    pub client_did: String,
    /// Random 16-byte nonce, base64url-no-pad. Becomes the bundle_id.
    pub nonce: String,
    /// Optional human-readable label (operator-visible only). Echoed into
    /// server-side audit logs. Wire field stays present on non-TEE builds so
    /// older clients keep deserializing; the value is only consumed by the
    /// TEE first-boot path. Bounded length protects audit log size from a
    /// hostile caller submitting an MB-scale string.
    #[serde(default, deserialize_with = "deserialize_bounded_label")]
    #[cfg_attr(not(feature = "tee"), allow(dead_code))]
    pub label: Option<String>,
    /// Ed25519 signature by `client_did` proving control of it,
    /// base64url-no-pad (see `vta_sdk::sealed_transfer::claim_signing_input`).
    /// Required on TEE builds.
    #[serde(default)]
    #[cfg_attr(not(feature = "tee"), allow(dead_code))]
    pub claim_signature: Option<String>,
}

fn deserialize_bounded_label<'de, D>(de: D) -> Result<Option<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let s: Option<String> = Option::deserialize(de)?;
    if let Some(label) = &s
        && label.len() > MAX_LABEL_LEN
    {
        return Err(serde::de::Error::custom(format!(
            "label exceeds {MAX_LABEL_LEN} bytes"
        )));
    }
    Ok(s)
}

/// Response body — a single armored sealed bundle as UTF-8 text, plus the
/// canonical SHA-256 digest so clients can optionally anchor on it.
#[derive(Debug, Serialize, utoipa::ToSchema)]
pub struct BootstrapResponseBody {
    pub bundle: String,
    pub digest: String,
}

/// `POST /bootstrap/request`
#[utoipa::path(
    post, path = "/bootstrap/request", tag = "bootstrap",
    request_body = BootstrapRequestBody,
    responses(
        (status = 200, description = "Armored sealed admin bundle + digest", body = BootstrapResponseBody),
        (status = 400, description = "Unsupported version or malformed client_did/nonce"),
        (status = 403, description = "TEE first-boot unavailable, or caller is not the configured bootstrap claim DID"),
        (status = 410, description = "Carve-out already used — this VTA already has an admin"),
    ),
)]
pub async fn request(
    State(state): State<AppState>,
    Json(req): Json<BootstrapRequestBody>,
) -> Result<Json<BootstrapResponseBody>, AppError> {
    if req.version != 1 {
        return Err(AppError::Validation(format!(
            "unsupported bootstrap request version: {}",
            req.version
        )));
    }

    let client_ed25519_pub = decode_client_did(&req.client_did)?;
    let bundle_id = decode_nonce(&req.nonce)?;
    let now = now_epoch();

    #[cfg(feature = "tee")]
    verify_claim_proof(&req)?;

    #[cfg(feature = "tee")]
    let bundle = mint_mode_b(&state, &client_ed25519_pub, bundle_id, now).await?;

    #[cfg(not(feature = "tee"))]
    {
        let _ = (state, client_ed25519_pub, bundle_id, now);
        Err(AppError::Forbidden(
            "bootstrap request requires TEE first-boot attestation, which is not available on \
             this VTA build. Non-TEE VTAs use the `pnm setup` temp-did:key + ACL flow instead."
                .into(),
        ))
    }

    #[cfg(feature = "tee")]
    {
        let digest = bundle_digest(&bundle);
        let armored = armor::encode(&bundle);

        // Log a SHA-256 prefix of the operator-supplied label rather than
        // the raw string. Labels are free-form and often carry PII
        // ("glenn's iphone", "alice@example.com") — a hash preserves
        // "same label → same identifier" for operational correlation
        // without leaking the plaintext into log aggregators.
        info!(
            client_label_hash = %label_hash_prefix(req.label.as_deref()),
            "TEE first-boot bootstrap completed"
        );
        audit!(
            "bootstrap.swap",
            actor = "bootstrap-endpoint",
            resource = "bootstrap",
            outcome = "success"
        );
        let _ = crate::audit::record(
            &state.audit_sink,
            "bootstrap.swap",
            "bootstrap-endpoint",
            None,
            "success",
            Some("rest"),
            None,
        )
        .await;

        Ok(Json(BootstrapResponseBody {
            bundle: armored,
            digest,
        }))
    }
}

/// Process-wide lock that serializes the carve-out check-and-set. The
/// keyspace exposes no compare-and-swap, so two concurrent requests can
/// each pass the `is_some()` check, mint admins, and write distinct ACL
/// rows before either writes the closed-sentinel. A `tokio::sync::Mutex`
/// held across the whole sequence collapses that window — the second
/// request waits, then sees the sentinel and is refused. The mint flow
/// is single-use and rare, so contention is irrelevant.
#[cfg(feature = "tee")]
static MODE_B_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());

/// Mode B: TEE first-boot sealed bootstrap. No token; the attestation quote
/// is the sole authorization anchor.
///
/// On success, closes the first-boot carve-out permanently by writing the
/// `BOOTSTRAP_CARVEOUT_CLOSED_KEY` sentinel. Any subsequent request is
/// rejected with [`carve_out_closed_error`] (410 Gone) — the carve-out is
/// consumed, not merely disallowed for this caller, which is what
/// distinguishes it from a 403.
#[cfg(feature = "tee")]
async fn mint_mode_b(
    state: &AppState,
    client_ed25519_pub: &[u8; 32],
    bundle_id: [u8; 16],
    now: u64,
) -> Result<vta_sdk::sealed_transfer::SealedBundle, AppError> {
    use crate::tee::admin_bootstrap::{BOOTSTRAP_CARVEOUT_CLOSED_KEY, LEGACY_ADMIN_CREDENTIAL_KEY};

    let tee_state =
        state.tee.as_ref().map(|tc| &tc.state).ok_or_else(|| {
            AppError::Forbidden("TEE first-boot is not available on this VTA".into())
        })?;

    // Serialize the carve-out check-and-set across all concurrent requests.
    // The lock is released when this function returns, by which point the
    // sentinel has been written (success path) or nothing has been written
    // (early-error path), so subsequent requests see a consistent view.
    let _carve_out_guard = MODE_B_LOCK.lock().await;

    // Before the carve-out check, so a stranger learns nothing about its state.
    authorize_claimant(
        state.config.read().await.tee.bootstrap_claim_did.as_deref(),
        client_ed25519_pub,
    )?;

    // Carve-out active ⇔ neither the closed-sentinel nor the legacy
    // admin-credential row is present. (The latter is a transitional case —
    // startup migration rewrites it into the closed-sentinel before this
    // handler ever runs, but we check here too to keep the handler correct
    // even without startup migration.)
    if state
        .keys_ks
        .get_raw(BOOTSTRAP_CARVEOUT_CLOSED_KEY)
        .await?
        .is_some()
        || state
            .keys_ks
            .get_raw(LEGACY_ADMIN_CREDENTIAL_KEY)
            .await?
            .is_some()
    {
        return Err(carve_out_closed_error());
    }

    let cfg = state.config.read().await;
    let vta_did = cfg
        .vta_did
        .as_ref()
        .ok_or_else(|| AppError::Internal("VTA DID not configured".into()))?
        .clone();
    let vta_url = cfg.public_url.clone();
    drop(cfg);

    // Per-request ephemeral producer Ed25519 keypair. The did:key bytes are
    // bound into the attestation `user_data` alongside the client's did:key
    // bytes + nonce so the consumer can recompute against DID-visible data.
    let (_producer_seed, producer_ed_pub) = generate_ed25519_keypair();
    let producer_did = affinidi_crypto::did_key::ed25519_pub_to_did_key(&producer_ed_pub);

    // Attestation user_data binds DID-layer bytes end-to-end:
    //   SHA256(client_ed25519 || bundle_id || producer_ed25519)
    // Both halves match what the consumer sees via the `client_did` it sent
    // and the `producer_did` in the returned `ProducerAssertion`.
    let mut hasher = Sha256::new();
    hasher.update(client_ed25519_pub);
    hasher.update(bundle_id);
    hasher.update(producer_ed_pub);
    let user_data = hasher.finalize();

    // Attestation nonce: reuse the client nonce for freshness.
    let report = tee_state
        .provider
        .attest(user_data.as_slice(), &bundle_id)
        .map_err(|e| AppError::Internal(format!("tee attest failed: {e}")))?;

    let (did, private_key_multibase) = crate::auth::credentials::generate_did_key();

    let credential = CredentialBundle {
        did: did.clone(),
        private_key_multibase,
        vta_did,
        vta_url,
    };

    let assertion = ProducerAssertion {
        producer_did,
        proof: AssertionProof::Attested(AttestationQuoteAssertion {
            format: format!("{}", report.tee_type),
            quote_b64: report.evidence,
        }),
    };

    // HPKE targets the consumer's derived X25519 pubkey; the DID layer is
    // invisible to the cipher. Any decoding error here should be impossible
    // (the handler already validated `client_did`), so surface as 500.
    let client_x25519_pub =
        affinidi_crypto::did_key::ed25519_pub_to_x25519_bytes(client_ed25519_pub)
            .map_err(|e| AppError::Internal(format!("client_did X25519 derivation: {e}")))?;

    // Seal FIRST, before touching any carve-out state. A seal failure
    // here must leave the carve-out open and retryable — no ACL, no
    // sentinel written.
    let nonce_store = PersistentNonceStore::new(state.sealed_nonces_ks.clone());
    let payload = SealedPayloadV1::AdminCredential(Box::new(credential));
    let bundle = seal_payload(
        &client_x25519_pub,
        bundle_id,
        assertion,
        &payload,
        &nonce_store,
    )
    .await
    .map_err(|e| AppError::Internal(format!("sealed-transfer seal failed: {e}")))?;

    // Now commit the carve-out. Ordering and durability are load-bearing
    // (P0.8):
    //
    //   1. ACL entry is written to the journal BEFORE the sentinel, so a
    //      torn fsync recovers to {ACL, no sentinel} — a safe, self-
    //      healing reopen (no bundle was delivered) — rather than
    //      {sentinel, no ACL}, which would brick the VTA (carve-out
    //      closed, no admin).
    //   2. The sentinel is claimed with `insert_raw_if_absent`: even if a
    //      future refactor breaks the `MODE_B_LOCK` guard above, a
    //      concurrent request's claim returns `false` and fails closed,
    //      so exactly one admin is ever minted. (Defence-in-depth — the
    //      lock already serializes; this no longer relies on it.)
    //   3. `persist()` fsyncs the ACL + sentinel + replay nonce together
    //      BEFORE the bundle is returned. This is the security barrier:
    //      the admin credential never leaves the enclave until the
    //      carve-out is durably closed, so a power loss after delivery
    //      cannot reopen it and mint a second admin.
    let entry = AclEntry::new(did.clone(), Role::Admin, "tee:mode-b")
        .with_label(Some("TEE first-boot admin".to_string()))
        .with_created_at(now);
    store_acl_entry(&state.acl_ks, &entry).await?;

    if !state
        .keys_ks
        .insert_raw_if_absent(BOOTSTRAP_CARVEOUT_CLOSED_KEY, did.as_bytes().to_vec())
        .await?
    {
        // Lost the carve-out race (only reachable if MODE_B_LOCK were
        // bypassed). Roll back the ACL we just wrote so it does not
        // linger as an admin entry for an undeliverable DID, and refuse.
        let _ = delete_acl_entry(&state.acl_ks, &did).await;
        return Err(carve_out_closed_error());
    }

    // Durability barrier: do not return the bundle until the carve-out
    // close is on disk.
    state.keys_ks.persist().await?;

    // Re-seal the TEE integrity manifest now that the carve-out is closed, so a
    // subsequent boot detects any parent attempt to reopen it (P0.2a). The
    // carve-out sentinel write above is a direct `insert_raw_if_absent`, not an
    // ACL/counter chokepoint, so it needs its own reseal. No-op outside a TEE.
    vti_common::integrity::reseal_if_active().await?;

    info!("TEE first-boot carve-out consumed — closed for good");
    Ok(bundle)
}

/// The consumed-carve-out refusal, shared by both places `mint_mode_b` can
/// discover the sentinel is already set (the up-front check, and the
/// defensive `insert_raw_if_absent` loss on the commit path).
///
/// Rendered as **410 Gone**, not 403: the carve-out is not a permission this
/// caller lacks (a 403 would suggest a *different* caller or a *later*
/// retry might succeed) — it is a single-use resource that has been
/// permanently, irreversibly consumed for this VTA. `vta_sdk::error::VtaError`
/// keys its `Gone` variant (and CLI hint) off this exact status.
#[cfg(feature = "tee")]
fn carve_out_closed_error() -> AppError {
    AppError::Gone("TEE first-boot carve-out has already been used".into())
}

/// Refuse a request not signed by its own `client_did`'s key.
#[cfg(feature = "tee")]
fn verify_claim_proof(req: &BootstrapRequestBody) -> Result<(), AppError> {
    vta_sdk::sealed_transfer::BootstrapRequest {
        version: req.version,
        client_did: req.client_did.clone(),
        nonce: req.nonce.clone(),
        label: None,
        claim_signature: req.claim_signature.clone(),
    }
    .verify_claim_signature()
    .map_err(|e| {
        AppError::Forbidden(format!(
            "bootstrap claim must be signed by the client_did's key: {e}"
        ))
    })
}

/// Admit only the configured claim DID. Unset admits nobody (fail closed).
#[cfg(feature = "tee")]
fn authorize_claimant(
    configured: Option<&str>,
    client_ed25519_pub: &[u8; 32],
) -> Result<(), AppError> {
    let configured = configured.ok_or_else(|| {
        AppError::Forbidden(
            "this VTA has no tee.bootstrap_claim_did configured, so no first-boot admin claim \
             is accepted"
                .into(),
        )
    })?;
    let authorized = affinidi_crypto::did_key::did_key_to_ed25519_pub(configured).map_err(|e| {
        AppError::Internal(format!(
            "configured tee.bootstrap_claim_did is not an Ed25519 did:key: {e}"
        ))
    })?;
    if &authorized != client_ed25519_pub {
        return Err(AppError::Forbidden(
            "client_did is not this VTA's bootstrap claim DID".into(),
        ));
    }
    Ok(())
}

/// Decode the consumer's `did:key` (Ed25519) to its raw 32-byte pubkey.
/// X25519 derivation happens inside `mint_mode_b` where HPKE is actually
/// invoked; the Ed25519 pubkey is separately bound into the attestation
/// `user_data` so the consumer can verify against did:key-visible bytes.
fn decode_client_did(did: &str) -> Result<[u8; 32], AppError> {
    affinidi_crypto::did_key::did_key_to_ed25519_pub(did)
        .map_err(|e| AppError::Validation(format!("invalid client_did: {e}")))
}

/// SHA-256 the operator-supplied label, return the first 16 hex chars
/// (64 bits — enough to tell distinct labels apart in practice). When
/// no label is supplied, return `"none"` so the log field is always
/// populated.
///
/// The point is to keep free-form strings (potentially carrying PII
/// like "alice@example.com" or a device name) out of the log
/// aggregator while preserving "same label → same hash" for operator
/// correlation across requests.
#[cfg(feature = "tee")]
fn label_hash_prefix(label: Option<&str>) -> String {
    match label {
        Some(s) => {
            let digest = Sha256::digest(s.as_bytes());
            let mut hex = String::with_capacity(16);
            for b in &digest[..8] {
                hex.push_str(&format!("{b:02x}"));
            }
            hex
        }
        None => "none".to_string(),
    }
}

#[cfg(feature = "tee")]
fn decode_nonce(s: &str) -> Result<[u8; 16], AppError> {
    let raw = B64URL
        .decode(s)
        .map_err(|e| AppError::Validation(format!("invalid nonce base64: {e}")))?;
    raw.try_into()
        .map_err(|_| AppError::Validation("nonce must be 16 bytes".into()))
}

#[cfg(not(feature = "tee"))]
fn decode_nonce(_s: &str) -> Result<[u8; 16], AppError> {
    // Non-TEE builds never reach the seal path; the handler returns Forbidden
    // before calling this. Keep a stub with the right signature so the
    // top-level handler compiles without ballooning the conditional code.
    Err(AppError::Forbidden(
        "bootstrap request requires TEE first-boot attestation".into(),
    ))
}

impl IntoResponse for BootstrapResponseBody {
    fn into_response(self) -> axum::response::Response {
        Json(self).into_response()
    }
}

#[cfg(all(test, feature = "tee"))]
mod tests {
    use super::*;

    #[test]
    fn label_hash_prefix_is_stable_and_truncated() {
        // Same label → same hash. Different labels → different hashes
        // (collision at 16 hex chars is 1-in-2^64, not worth guarding).
        // None → "none" so the log field is never empty.
        let a1 = label_hash_prefix(Some("alice@example.com"));
        let a2 = label_hash_prefix(Some("alice@example.com"));
        let b = label_hash_prefix(Some("bob@example.com"));
        assert_eq!(a1, a2, "same label produces same hash");
        assert_ne!(a1, b, "different labels produce different hashes");
        assert_eq!(a1.len(), 16, "prefix is 16 hex chars (64 bits)");
        assert!(
            a1.chars().all(|c| c.is_ascii_hexdigit()),
            "hash prefix is hex"
        );
        assert_eq!(label_hash_prefix(None), "none");
    }

    #[test]
    fn label_hash_prefix_does_not_leak_raw_label() {
        // Defence-in-depth: the returned string should not contain any
        // substring of the original label. A regression here would mean
        // the hash helper got replaced with an echo / truncation by
        // someone not thinking about PII.
        let raw = "glenn's iphone";
        let hashed = label_hash_prefix(Some(raw));
        for substr_len in 3..=raw.len() {
            for start in 0..=(raw.len() - substr_len) {
                let needle = &raw[start..start + substr_len];
                assert!(
                    !hashed.contains(needle),
                    "hashed output '{hashed}' must not contain raw substring '{needle}'"
                );
            }
        }
    }

    /// Concurrency contract for the carve-out close (P0.8).
    ///
    /// Property under test: when N concurrent `mint_mode_b`-style
    /// sequences race against the same keyspace, exactly one claims the
    /// carve-out sentinel; the others see the atomic claim fail and
    /// refuse. Each task takes `MODE_B_LOCK` (the primary serializer)
    /// and then claims the sentinel via `insert_raw_if_absent` (the
    /// mechanism `mint_mode_b` now uses) — so the claim is correct
    /// *even if a future refactor drops the lock*, which is the
    /// defence-in-depth P0.8 strengthened.
    ///
    /// This is the safety invariant CLAUDE.md highlights as load-bearing
    /// — two concurrent `/bootstrap/request` calls that both minted an
    /// admin would be a privilege-escalation hole. Uses the actual
    /// `MODE_B_LOCK` static and the actual sentinel key constant so a
    /// refactor that relocates either is caught here.
    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    async fn carveout_claim_admits_exactly_one_concurrent_minter() {
        use crate::tee::admin_bootstrap::BOOTSTRAP_CARVEOUT_CLOSED_KEY;
        use std::sync::atomic::{AtomicUsize, Ordering};
        use std::time::Duration;
        use vti_common::config::StoreConfig;
        use vti_common::store::Store;

        let dir = tempfile::tempdir().expect("tempdir");
        let store_config = StoreConfig {
            data_dir: dir.path().to_path_buf(),
        };
        let store = Store::open(&store_config).expect("open store");
        let keys_ks = store.keyspace(crate::keyspaces::KEYS).expect("keyspace");

        let n_tasks: usize = 16;
        let successes = std::sync::Arc::new(AtomicUsize::new(0));

        let mut handles = Vec::with_capacity(n_tasks);
        for i in 0..n_tasks {
            let ks = keys_ks.clone();
            let successes = std::sync::Arc::clone(&successes);
            handles.push(tokio::spawn(async move {
                // Same shape as `mint_mode_b`: take MODE_B_LOCK, do
                // "work" (the yield models the TEE attestation + seal
                // window), then claim the sentinel atomically. The
                // atomic claim is what guarantees exactly-one even
                // without the lock.
                let _guard = MODE_B_LOCK.lock().await;
                tokio::time::sleep(Duration::from_millis(2)).await;
                let claimed = ks
                    .insert_raw_if_absent(
                        BOOTSTRAP_CARVEOUT_CLOSED_KEY,
                        format!("admin-{i}").into_bytes(),
                    )
                    .await
                    .expect("claim sentinel");
                if claimed {
                    ks.persist().await.expect("persist carve-out");
                    successes.fetch_add(1, Ordering::SeqCst);
                }
            }));
        }

        for h in handles {
            h.await.expect("task joined");
        }

        assert_eq!(
            successes.load(Ordering::SeqCst),
            1,
            "exactly one task may claim the carve-out sentinel; got {} successes",
            successes.load(Ordering::SeqCst),
        );
        assert!(
            keys_ks
                .get_raw(BOOTSTRAP_CARVEOUT_CLOSED_KEY)
                .await
                .unwrap()
                .is_some(),
            "sentinel must be set after the run"
        );
    }

    /// Simulated-TEE app state whose configured claim DID is `claim_pub`'s.
    async fn claim_state(claim_pub: Option<&[u8; 32]>) -> AppState {
        use crate::config::{TeeConfig, TeeMode};
        use crate::server::TeeContext;

        let (_app, ctx) = crate::test_support::build_test_app().await;
        let tee_state = crate::tee::init_tee(&TeeConfig {
            mode: TeeMode::Simulated,
            ..Default::default()
        })
        .expect("init simulated tee")
        .expect("simulated tee state present");

        let mut state = ctx.state.clone();
        state.tee = Some(TeeContext {
            state: tee_state,
            mnemonic_guard: None,
        });
        state.config.write().await.tee.bootstrap_claim_did =
            claim_pub.map(affinidi_crypto::did_key::ed25519_pub_to_did_key);
        state
    }

    /// Nothing minted: the carve-out sentinel was not written.
    async fn assert_nothing_minted(state: &AppState) {
        use crate::tee::admin_bootstrap::BOOTSTRAP_CARVEOUT_CLOSED_KEY;
        assert!(
            state
                .keys_ks
                .get_raw(BOOTSTRAP_CARVEOUT_CLOSED_KEY)
                .await
                .unwrap()
                .is_none(),
            "the carve-out sentinel must not be written for a refused claim"
        );
    }

    /// The API-contract regression this module exists to close: a consumed
    /// Mode B carve-out must render **410 Gone**, not 403. A 403 tells the
    /// caller "you specifically are not authorized" — which is wrong here,
    /// since *no* caller, with *any* credentials, can ever succeed again.
    /// The second request comes from the authorized claim key with a fresh
    /// nonce, so it is neither a replay nor an unauthorized caller.
    #[tokio::test]
    async fn consumed_carveout_returns_410_gone_not_403() {
        let (_seed, claim_pub) = generate_ed25519_keypair();
        let state = claim_state(Some(&claim_pub)).await;
        let now = now_epoch();

        mint_mode_b(&state, &claim_pub, [1u8; 16], now)
            .await
            .expect("first bootstrap mints an admin");

        let err = mint_mode_b(&state, &claim_pub, [2u8; 16], now)
            .await
            .expect_err("second bootstrap must be refused");

        assert!(
            matches!(err, AppError::Gone(_)),
            "consumed carve-out must map to AppError::Gone, got {err:?}"
        );
        assert_eq!(
            err.into_response().status(),
            axum::http::StatusCode::GONE,
            "consumed carve-out must render as HTTP 410, not 403/409"
        );
    }

    #[tokio::test]
    async fn caller_without_the_claim_did_is_refused_without_minting() {
        let (_, claim_pub) = generate_ed25519_keypair();
        let (_, stranger_pub) = generate_ed25519_keypair();
        let state = claim_state(Some(&claim_pub)).await;

        let err = mint_mode_b(&state, &stranger_pub, [1u8; 16], now_epoch())
            .await
            .expect_err("a stranger must not claim admin");
        assert!(matches!(err, AppError::Forbidden(_)), "got {err:?}");
        assert_nothing_minted(&state).await;
    }

    #[tokio::test]
    async fn no_configured_claim_did_admits_nobody() {
        let (_, caller_pub) = generate_ed25519_keypair();
        let state = claim_state(None).await;

        let err = mint_mode_b(&state, &caller_pub, [1u8; 16], now_epoch())
            .await
            .expect_err("without a claim DID no one may claim");
        assert!(matches!(err, AppError::Forbidden(_)), "got {err:?}");
        assert_nothing_minted(&state).await;
    }

    /// The carve-out sentinel vanishes after a successful claim (a lost write,
    /// or a host deleting it — which the TEE integrity manifest catches at the
    /// next boot, not here). A stranger is still refused: the claim DID, not the
    /// sentinel, is what keeps an anonymous caller out.
    #[tokio::test]
    async fn missing_sentinel_does_not_admit_a_stranger() {
        use crate::tee::admin_bootstrap::BOOTSTRAP_CARVEOUT_CLOSED_KEY;

        let (_, claim_pub) = generate_ed25519_keypair();
        let (_, stranger_pub) = generate_ed25519_keypair();
        let state = claim_state(Some(&claim_pub)).await;

        mint_mode_b(&state, &claim_pub, [1u8; 16], now_epoch())
            .await
            .expect("first bootstrap mints an admin");
        state
            .keys_ks
            .remove(BOOTSTRAP_CARVEOUT_CLOSED_KEY)
            .await
            .unwrap();

        let err = mint_mode_b(&state, &stranger_pub, [2u8; 16], now_epoch())
            .await
            .expect_err("a stranger must not walk through a reopened window");
        assert!(matches!(err, AppError::Forbidden(_)), "got {err:?}");
    }

    fn body_from(req: vta_sdk::sealed_transfer::BootstrapRequest) -> BootstrapRequestBody {
        BootstrapRequestBody {
            version: req.version,
            client_did: req.client_did,
            nonce: req.nonce,
            label: req.label,
            claim_signature: req.claim_signature,
        }
    }

    #[test]
    fn claim_proof_requires_a_signature_by_client_did() {
        use vta_sdk::sealed_transfer::BootstrapRequest;

        let (seed, pubkey) = generate_ed25519_keypair();
        verify_claim_proof(&body_from(BootstrapRequest::new_signed_claim(
            &seed, [1u8; 16], None,
        )))
        .expect("signed claim verifies");

        let unsigned = body_from(BootstrapRequest::new(pubkey, [1u8; 16], None));
        assert!(matches!(
            verify_claim_proof(&unsigned),
            Err(AppError::Forbidden(_))
        ));

        // Someone who knows the public claim DID but not its key.
        let (other_seed, _) = generate_ed25519_keypair();
        let mut forged = body_from(BootstrapRequest::new_signed_claim(
            &other_seed,
            [1u8; 16],
            None,
        ));
        forged.client_did = affinidi_crypto::did_key::ed25519_pub_to_did_key(&pubkey);
        assert!(matches!(
            verify_claim_proof(&forged),
            Err(AppError::Forbidden(_))
        ));
    }
}