vta-service 0.36.0

//! Offline state-assembly helpers.
//!
//! Read the VTA's local keystore / context / ACL / webvh state directly and
//! produce the same wire-shape bundles that the equivalent `VtaClient` flows
//! build over REST. Used by on-host `vta context reprovision` and
//! `vta keys bundle` CLIs — the cold-start / air-gapped case where PNM
//! cannot reach the VTA over the network.
//!
//! The output shapes (`DidSecretsBundle`, `ContextProvisionBundle`) are
//! identical to what `VtaClient::fetch_did_secrets_bundle` and
//! `vta_cli_common::commands::contexts::cmd_context_reprovision` produce,
//! so downstream `vta_cli_common::sealed_producer::emit_did_secrets_bundle` /
//! `emit_context_provision_bundle` seal + print them the same way.
//!
//! All functions here are pure reads — they do not mutate state. The only
//! write path used by the reprovision flow (creating an ACL entry for the
//! admin DID if none exists) is done via `super::acl::create_acl` in the
//! caller, kept out of this module so its boundaries stay "fetch state".

use std::sync::Arc;

use tracing::debug;

use crate::auth::AuthClaims;
use crate::error::AppError;
use crate::keys::seed_store::SeedStore;
use crate::store::KeyspaceHandle;
use vta_sdk::context_provision::ContextProvisionBundle;
#[cfg(feature = "webvh")]
use vta_sdk::context_provision::ProvisionedDid;
use vta_sdk::credentials::CredentialBundle;
use vta_sdk::did_secrets::{DidSecretsBundle, SecretEntry, select_secret_kid};
use vta_sdk::keys::KeyStatus;

/// Dependencies for the offline state-assembly helpers.
///
/// Borrowed from `AppState` (or built directly from a CLI-opened store)
/// so the caller doesn't have to thread eight keyspaces through every
/// signature.
pub struct ExportDeps<'a> {
    pub keys_ks: &'a KeyspaceHandle,
    pub contexts_ks: &'a KeyspaceHandle,
    pub imported_ks: &'a KeyspaceHandle,
    pub audit: &'a vta_audit::SharedAuditSink,
    pub acl_ks: &'a KeyspaceHandle,
    #[cfg(feature = "webvh")]
    pub webvh_ks: &'a KeyspaceHandle,
    pub seed_store: &'a Arc<dyn SeedStore>,
}

/// Every private key of `context_id`'s own DID, for the service that operates it.
///
/// # Why this exists as one operation
///
/// A service that the VTA holds an identity for has to hold that DID's private keys to
/// decrypt what is addressed to it — it cannot ask the VTA per frame. So it fetches them at
/// startup. Assembling that bundle used to mean listing the context's keys and then calling
/// the per-key export once each, and *that* export was gated on the global Admin role — so
/// being a service required authority over the whole VTA.
///
/// One call, one authorization decision, about the one thing being decided: may this caller
/// act in this context.
///
/// # Application, not Admin, and what makes that safe
///
/// Reading the keys of the DID you already operate is not an administrative act. What keeps
/// the lower role sound is that it is scoped twice, and neither check is this function being
/// careful — both are checks the keys surface already makes:
///
/// - [`AuthClaims::require_context`], inside [`build_did_secrets_bundle`], on the context
///   asked for — so naming somebody else's context is refused before a single key is read,
///   and before the context is even looked up. A caller not entitled to an id is therefore
///   refused for that reason whether or not the id exists, and "not found" is only ever said
///   to a caller already entitled to hear it;
/// - [`super::keys::get_key_secret`]'s own per-key context gate, which would refuse a key
///   that somehow did not belong to the context it was listed under.
///
/// A caller with `Application` in context A therefore gets A's keys and no others, and a
/// caller with no context at all gets nothing. Asserted in the tests rather than trusted.
///
/// # Why it delegates
///
/// [`build_did_secrets_bundle`] is the whole of the traversal, and the only thing that
/// differs between its two callers is the role floor: the offline export path runs as a
/// local super-admin, while `vta/contexts/secrets/1.0` is reachable by an `Application`. A
/// second traversal here would be a second set of rules to keep in step — which key ids are
/// verification methods of the DID, which secrets are excluded, how the pages are walked —
/// and those rules are exactly the part that must not drift.
pub async fn get_context_secrets(
    deps: &ExportDeps<'_>,
    auth: &AuthClaims,
    context_id: &str,
    channel: &str,
) -> Result<DidSecretsBundle, AppError> {
    // The role floor. Application or higher — a Reader may see that keys exist and a Monitor
    // may not even do that, and neither may hold one. The scope check is the delegate's.
    auth.require_write()?;
    let bundle = build_did_secrets_bundle(deps, auth, context_id, channel).await?;
    tracing::info!(
        channel,
        context = %context_id,
        did = %bundle.did,
        keys = bundle.secrets.len(),
        "context secrets released to the service that operates them"
    );
    Ok(bundle)
}

/// Build a [`DidSecretsBundle`] for `context_id` by enumerating active
/// keys in the local store and loading each secret.
///
/// Mirrors [`vta_sdk::client::VtaClient::fetch_did_secrets_bundle`] —
/// same traversal (context → active keys → secret per key), same kid
/// selection via [`vta_sdk::did_secrets::select_secret_kid`]. Secrets
/// that aren't verification methods of the context DID (admin `did:key`
/// rolled into the same context, free-text-labelled records) are
/// excluded; including them would corrupt the operating-secret set the
/// mediator matches inbound JWE recipients against.
pub async fn build_did_secrets_bundle(
    deps: &ExportDeps<'_>,
    auth: &AuthClaims,
    context_id: &str,
    channel: &str,
) -> Result<DidSecretsBundle, AppError> {
    auth.require_context(context_id)?;

    let ctx = crate::contexts::get_context(deps.contexts_ks, context_id)
        .await?
        .ok_or_else(|| AppError::NotFound(format!("context not found: {context_id}")))?;
    let did = ctx.did.clone().ok_or_else(|| {
        AppError::Validation(format!("context '{context_id}' has no DID assigned"))
    })?;

    // Page through active keys in the context. `list_keys` already
    // applies context-access gating based on `auth`; we only traverse
    // what the caller is allowed to see.
    let mut secrets = Vec::new();
    let page_size = 100u64;
    let mut offset = 0u64;
    loop {
        let page = super::keys::list_keys(
            deps.keys_ks,
            auth,
            super::keys::ListKeysParams {
                offset: Some(offset),
                limit: Some(page_size),
                status: Some(KeyStatus::Active),
                context_id: Some(context_id.to_string()),
            },
            channel,
        )
        .await?;
        if page.keys.is_empty() {
            break;
        }
        for key in &page.keys {
            let secret = super::keys::get_key_secret(
                deps.keys_ks,
                deps.imported_ks,
                deps.seed_store,
                deps.audit,
                auth,
                &key.key_id,
                channel,
            )
            .await?;
            // The kid a mediator matches inbound JWE recipients against MUST be
            // a verification-method id of *this* context's DID. Resolve it from
            // the authoritative store key_id (falling back to the label only
            // when the label is itself a strict VM id); drop anything that
            // isn't a VM id of `did`. Identical contract to the online
            // `VtaClient::fetch_did_secrets_bundle` — shared helper.
            match select_secret_kid(&did, &secret.key_id, key.label.as_deref()) {
                Some(key_id) => secrets.push(SecretEntry {
                    key_id,
                    key_type: secret.key_type,
                    private_key_multibase: secret.private_key_multibase,
                }),
                None => {
                    debug!(
                        channel,
                        %context_id,
                        %did,
                        key_id = %secret.key_id,
                        label = key.label.as_deref().unwrap_or(""),
                        "excluding secret from did-secrets bundle: not a verification \
                         method of the context DID (e.g. an admin did:key minted into \
                         this context, or a free-text-labelled key). Including it would \
                         corrupt the DIDComm operating-secret set and break the \
                         mediator's exact-match recipient lookup."
                    );
                }
            }
        }
        offset += page.keys.len() as u64;
        if offset >= page.total {
            break;
        }
    }

    debug!(channel, %context_id, %did, secret_count = secrets.len(), "built did-secrets bundle from local store");
    Ok(DidSecretsBundle { did, secrets })
}

/// Derive an admin [`CredentialBundle`] from an existing key in the
/// store. The key's private seed is loaded; the bundle + derived
/// `did:key` come from the shared
/// [`CredentialBundle::from_ed25519_seed_multibase`] helper so this
/// and the online path in
/// `vta-cli-common::commands::contexts::credential_from_key` can't
/// drift in their encoding choices.
///
/// Returns `(credential, admin_did)` where `admin_did` is the derived
/// `did:key:z6Mk...` string.
pub async fn credential_from_key_offline(
    deps: &ExportDeps<'_>,
    auth: &AuthClaims,
    key_id: &str,
    vta_did: &str,
    vta_url: Option<&str>,
    channel: &str,
) -> Result<(CredentialBundle, String), AppError> {
    let secret = super::keys::get_key_secret(
        deps.keys_ks,
        deps.imported_ks,
        deps.seed_store,
        deps.audit,
        auth,
        key_id,
        channel,
    )
    .await?;
    CredentialBundle::from_ed25519_seed_multibase(&secret.private_key_multibase, vta_did, vta_url)
        .map_err(|e| AppError::Internal(format!("decode admin key secret: {e}")))
}

/// Inputs to [`build_context_provision_bundle`].
///
/// `key_id` names the existing key whose seed backs the exported admin
/// credential. The CLI caller is responsible for resolving it (explicit
/// `--key` flag, interactive prompt, or single-key auto-select) before
/// calling this function — the library stays UI-agnostic.
pub struct ContextReprovisionInputs {
    pub context_id: String,
    pub key_id: String,
}

/// Build a [`ContextProvisionBundle`] for an existing context.
///
/// Mirrors the online `cmd_context_reprovision` flow (minus the
/// interactive prompt): fetch context, build credential from the named
/// key, fetch the DID log + secrets when the context has a DID, stitch
/// together the bundle. The caller must separately ensure an ACL entry
/// exists for the derived `admin_did` via `super::acl::create_acl` when
/// the bundle is about to be sealed for a new admin.
///
/// `vta_did` and `vta_url` come from the caller's `AppConfig` — they
/// are metadata woven into the bundle so the consumer can reconnect
/// over REST/DIDComm after installing.
pub async fn build_context_provision_bundle(
    deps: &ExportDeps<'_>,
    auth: &AuthClaims,
    inputs: ContextReprovisionInputs,
    vta_did: &str,
    vta_url: Option<&str>,
    channel: &str,
) -> Result<ContextProvisionBundle, AppError> {
    let ContextReprovisionInputs { context_id, key_id } = inputs;
    auth.require_context(&context_id)?;

    let ctx = crate::contexts::get_context(deps.contexts_ks, &context_id)
        .await?
        .ok_or_else(|| AppError::NotFound(format!("context not found: {context_id}")))?;

    let (credential, admin_did) =
        credential_from_key_offline(deps, auth, &key_id, vta_did, vta_url, channel).await?;

    // Gather DID material when the context has a DID registered.
    #[cfg(feature = "webvh")]
    let provisioned_did = match ctx.did.as_deref() {
        Some(did_id) => {
            Some(fetch_did_material_offline(deps, auth, did_id, &context_id, channel).await?)
        }
        None => None,
    };
    #[cfg(not(feature = "webvh"))]
    let provisioned_did = None;

    Ok(ContextProvisionBundle {
        context_id,
        context_name: ctx.name,
        vta_url: vta_url.map(String::from),
        vta_did: Some(vta_did.to_string()),
        credential,
        admin_did,
        did: provisioned_did,
    })
}

/// Load the DID document + log entry + all active-key secrets for a
/// DID that is registered in a context. Used by
/// [`build_context_provision_bundle`] when the context has a DID.
///
/// The key secrets come from [`build_did_secrets_bundle`] applied to
/// the same context, ensuring exact parity with the online path.
#[cfg(feature = "webvh")]
async fn fetch_did_material_offline(
    deps: &ExportDeps<'_>,
    auth: &AuthClaims,
    did: &str,
    context_id: &str,
    channel: &str,
) -> Result<ProvisionedDid, AppError> {
    // Fetch the raw did.jsonl log from the local webvh store. `get_did_webvh`
    // with `include_log` returns a record whose `log` field holds the
    // serialized log string; parse it to extract the latest document
    // state.
    let log_result =
        super::did_webvh::get_did_webvh(deps.webvh_ks, auth, did, channel, true).await?;
    let log_entry = log_result.log;
    let did_document = log_entry
        .as_deref()
        .and_then(|log_str| serde_json::from_str::<serde_json::Value>(log_str).ok())
        .and_then(|v| v.get("state").cloned());

    let secrets_bundle = build_did_secrets_bundle(deps, auth, context_id, channel).await?;
    Ok(ProvisionedDid {
        id: did.to_string(),
        did_document,
        log_entry,
        secrets: secrets_bundle.secrets,
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::StoreConfig;
    use crate::keys::seed_store::PlaintextSeedStore;
    use crate::store::{KeyspaceHandle, Store};
    use std::path::PathBuf;

    struct TestEnv {
        _dir: tempfile::TempDir,
        _store: Store,
        contexts_ks: KeyspaceHandle,
        keys_ks: KeyspaceHandle,
        imported_ks: KeyspaceHandle,
        audit: vta_audit::SharedAuditSink,
        acl_ks: KeyspaceHandle,
        #[cfg(feature = "webvh")]
        webvh_ks: KeyspaceHandle,
        seed_store: Arc<dyn SeedStore>,
        data_dir: PathBuf,
    }

    async fn open_env() -> TestEnv {
        let dir = tempfile::tempdir().expect("temp dir");
        let data_dir = dir.path().to_path_buf();
        let store = Store::open(&StoreConfig {
            data_dir: data_dir.clone(),
        })
        .expect("open store");
        TestEnv {
            contexts_ks: store.keyspace(crate::keyspaces::CONTEXTS).unwrap(),
            keys_ks: store.keyspace(crate::keyspaces::KEYS).unwrap(),
            imported_ks: store.keyspace(crate::keyspaces::IMPORTED_SECRETS).unwrap(),
            audit: vta_audit::shared_keyspace_sink(
                store.keyspace(crate::keyspaces::AUDIT).unwrap(),
            ),
            acl_ks: store.keyspace(crate::keyspaces::ACL).unwrap(),
            #[cfg(feature = "webvh")]
            webvh_ks: store.keyspace(crate::keyspaces::WEBVH).unwrap(),
            seed_store: Arc::new(PlaintextSeedStore::new(&data_dir)),
            _dir: dir,
            _store: store,
            data_dir,
        }
    }

    fn deps_of(env: &TestEnv) -> ExportDeps<'_> {
        ExportDeps {
            keys_ks: &env.keys_ks,
            contexts_ks: &env.contexts_ks,
            imported_ks: &env.imported_ks,
            audit: &env.audit,
            acl_ks: &env.acl_ks,
            #[cfg(feature = "webvh")]
            webvh_ks: &env.webvh_ks,
            seed_store: &env.seed_store,
        }
    }

    fn super_admin() -> AuthClaims {
        AuthClaims {
            did: "did:key:zTestCli".into(),
            role: crate::acl::Role::Admin,
            allowed_contexts: Vec::new(),
            session_id: "test-session".into(),
            access_expires_at: 0,
            issued_at: 0,
            amr: Vec::new(),
            acr: String::new(),
        }
    }

    /// A caller with a role and a set of contexts it may act in.
    ///
    /// The pair is the whole of the authorization model this task turns on:
    /// `role` is the floor and `allowed_contexts` is the scope, and a non-empty
    /// scope narrows even [`Role::Admin`] (only an *empty* list means "all").
    fn scoped(role: crate::acl::Role, contexts: &[&str]) -> AuthClaims {
        AuthClaims {
            did: "did:key:zTestCaller".into(),
            role,
            allowed_contexts: contexts.iter().map(|c| (*c).to_string()).collect(),
            session_id: "test-session".into(),
            access_expires_at: 0,
            issued_at: 0,
            amr: Vec::new(),
            acr: String::new(),
        }
    }

    #[tokio::test]
    async fn build_did_secrets_rejects_missing_context() {
        let env = open_env().await;
        let auth = super_admin();
        let err = build_did_secrets_bundle(&deps_of(&env), &auth, "nope", "test")
            .await
            .unwrap_err();
        assert!(matches!(err, AppError::NotFound(_)), "got: {err:?}");
        let msg = err.to_string();
        assert!(msg.contains("nope"), "got: {msg}");
    }

    #[tokio::test]
    async fn build_did_secrets_rejects_context_without_did() {
        let env = open_env().await;
        let auth = super_admin();
        // Create a context but leave its DID field unset.
        crate::contexts::create_context(&env.contexts_ks, "no-did", "No DID Ctx")
            .await
            .expect("create context");

        let err = build_did_secrets_bundle(&deps_of(&env), &auth, "no-did", "test")
            .await
            .unwrap_err();
        assert!(matches!(err, AppError::Validation(_)), "got: {err:?}");
        assert!(err.to_string().contains("no DID assigned"));
    }

    #[tokio::test]
    async fn build_context_provision_requires_existing_context() {
        let env = open_env().await;
        let auth = super_admin();
        let err = build_context_provision_bundle(
            &deps_of(&env),
            &auth,
            ContextReprovisionInputs {
                context_id: "missing".into(),
                key_id: "did:key:zFake#zFake".into(),
            },
            "did:key:zVta",
            None,
            "test",
        )
        .await
        .unwrap_err();
        assert!(matches!(err, AppError::NotFound(_)), "got: {err:?}");
        assert!(err.to_string().contains("missing"));
    }

    // Keep this warning silenced: `data_dir` is only read in the
    // happy-path test hooks that land once a seed-bootstrap helper is
    // available to the test module.
    #[allow(dead_code)]
    fn _unused_data_dir(env: &TestEnv) -> &PathBuf {
        &env.data_dir
    }

    /// The DID a seeded context is given. Every operating key below is a
    /// verification method of it.
    const SEEDED_DID: &str = "did:webvh:QmScid:mediator.example.com:med";

    /// Stand up one context holding the three key records the bundle logic has
    /// to tell apart: two operating keys whose ids ARE verification methods of
    /// [`SEEDED_DID`], and an admin `did:key` minted into the same context whose
    /// VM id belongs to a *different* DID and whose label is free text.
    ///
    /// Shared by the kid-selection test and the authorization tests so the two
    /// cannot disagree about what a correctly-populated context looks like.
    async fn seed_context_with_keys(env: &TestEnv, context_id: &str) -> String {
        use crate::keys::paths::allocate_path;
        use crate::keys::{KeyRecord, store_key};
        use chrono::Utc;
        use vta_sdk::keys::{KeyOrigin, KeyStatus, KeyType};

        // Seed the external store so derived keys can be minted + read back.
        env.seed_store
            .set(&[0xABu8; 32])
            .await
            .expect("seed the store");

        crate::contexts::create_context(&env.contexts_ks, context_id, "Mediator Ctx")
            .await
            .expect("create context");
        let mut rec = crate::contexts::get_context(&env.contexts_ks, context_id)
            .await
            .expect("get context")
            .expect("context exists");
        rec.did = Some(SEEDED_DID.to_string());
        crate::contexts::store_context(&env.contexts_ks, &rec)
            .await
            .expect("store did on context");

        // Mint a key record the way internal DID provisioning does: an
        // allocated path + a directly-written KeyRecord. VM-shaped key_ids are
        // exclusive to this internal path — the public create_key/import_key ops
        // reject them at validation. The stored public_key is not consulted by
        // the bundle (secrets are re-derived from the path), so a placeholder is
        // fine here.
        async fn mint_internal(
            env: &TestEnv,
            context_id: &str,
            base_path: &str,
            kid: &str,
            kt: KeyType,
            label: Option<&str>,
        ) {
            let path = allocate_path(&env.keys_ks, base_path)
                .await
                .expect("allocate path");
            let now = Utc::now();
            let record = KeyRecord {
                exportable: None,
                key_id: kid.to_string(),
                derivation_path: path,
                key_type: kt,
                status: KeyStatus::Active,
                public_key: "zPlaceholderNotUnderTest".into(),
                label: label.map(String::from),
                context_id: Some(context_id.to_string()),
                seed_id: None,
                origin: KeyOrigin::Derived,
                created_at: now,
                updated_at: now,
            };
            env.keys_ks
                .insert(store_key(kid), &record)
                .await
                .expect("store key record");
        }

        for (suffix, kt) in [("#key-0", KeyType::Ed25519), ("#key-1", KeyType::X25519)] {
            mint_internal(
                env,
                context_id,
                &rec.base_path,
                &format!("{SEEDED_DID}{suffix}"),
                kt,
                None,
            )
            .await;
        }
        mint_internal(
            env,
            context_id,
            &rec.base_path,
            &format!("{ADMIN_DID_KEY}#z6Mkt6eNM38RhFfjSdmXBtT1SRL7sPgPZD1MkXZbwjYBhTLf"),
            KeyType::Ed25519,
            Some("admin DID for context med-ctx"),
        )
        .await;

        SEEDED_DID.to_string()
    }

    /// An admin `did:key` that gets minted into a service context in practice.
    /// Not a verification method of [`SEEDED_DID`], so it belongs in no bundle.
    const ADMIN_DID_KEY: &str = "did:key:z6Mkt6eNM38RhFfjSdmXBtT1SRL7sPgPZD1MkXZbwjYBhTLf";

    /// Happy-path coverage for the kid-selection contract: the offline
    /// bundle must carry exactly the keys whose ids are verification
    /// methods of the context DID, and must drop an admin `did:key`
    /// minted into the same context (a different DID, free-text label).
    ///
    /// Locks the wiring of [`select_secret_kid`] into the offline path —
    /// the per-decision rules are unit-tested in
    /// `vta_sdk::did_secrets`, but this proves `build_did_secrets_bundle`
    /// feeds it the authoritative store `key_id` (and the label) so a
    /// refactor can't silently re-include non-VM secrets and re-brick the
    /// mediator's exact-match recipient lookup (the storm.ws outage).
    #[tokio::test]
    async fn build_did_secrets_excludes_non_vm_admin_did_key() {
        let env = open_env().await;
        let did = seed_context_with_keys(&env, "med-ctx").await;

        let bundle = build_did_secrets_bundle(&deps_of(&env), &super_admin(), "med-ctx", "test")
            .await
            .expect("bundle builds");

        assert_eq!(bundle.did, did);
        let expect_0 = format!("{did}#key-0");
        let expect_1 = format!("{did}#key-1");
        let mut kids: Vec<&str> = bundle.secrets.iter().map(|s| s.key_id.as_str()).collect();
        kids.sort_unstable();
        assert_eq!(
            kids,
            vec![expect_0.as_str(), expect_1.as_str()],
            "only the two VM-id operating keys belong in the bundle; the admin \
             did:key minted into the context must be excluded"
        );
        assert!(
            !bundle
                .secrets
                .iter()
                .any(|s| s.key_id.contains(ADMIN_DID_KEY)),
            "admin did:key must not appear in the operating-secret bundle"
        );
    }

    // ---------------------------------------------------------------------
    // `get_context_secrets` — the Trust Task path, and the loosening it makes.
    //
    // This is the only operation that hands private keys to an `Application`.
    // What makes that sound is that the entitlement is a *scope* and not a
    // *rank*, so the tests below are written to fail if anyone ever implements
    // it the other way round.
    // ---------------------------------------------------------------------

    /// The point of the task: a service holding a context gets that context's
    /// DID and its operating keys, at `Application` — not `Admin`.
    #[tokio::test]
    async fn an_application_fetches_its_own_contexts_secrets() {
        let env = open_env().await;
        let did = seed_context_with_keys(&env, "med-ctx").await;
        let auth = scoped(crate::acl::Role::Application, &["med-ctx"]);

        let bundle = get_context_secrets(&deps_of(&env), &auth, "med-ctx", "test")
            .await
            .expect("an application may read the keys of the context it operates");

        assert_eq!(bundle.did, did);
        let mut kids: Vec<&str> = bundle.secrets.iter().map(|s| s.key_id.as_str()).collect();
        kids.sort_unstable();
        assert_eq!(kids, vec![format!("{did}#key-0"), format!("{did}#key-1")]);
    }

    /// The check the loosening rests on. An `Application` entitled to one
    /// context reaches nothing in another, and the refusal is about access
    /// rather than existence.
    #[tokio::test]
    async fn an_application_cannot_reach_another_contexts_secrets() {
        let env = open_env().await;
        seed_context_with_keys(&env, "med-ctx").await;
        let auth = scoped(crate::acl::Role::Application, &["some-other-ctx"]);

        let err = get_context_secrets(&deps_of(&env), &auth, "med-ctx", "test")
            .await
            .expect_err("a context you do not hold is not yours to read keys from");
        assert!(matches!(err, AppError::Forbidden(_)), "got: {err:?}");
    }

    /// Scope, not rank. `Admin` is the highest role there is, and it still
    /// reaches nothing outside its `allowed_contexts` — because only an *empty*
    /// list means "all contexts". A reimplementation that treated the
    /// entitlement as a privilege level would hand this caller every context's
    /// key material, so this test is the guard against that specific mistake.
    #[tokio::test]
    async fn an_admin_of_another_context_cannot_either() {
        let env = open_env().await;
        seed_context_with_keys(&env, "med-ctx").await;
        let auth = scoped(crate::acl::Role::Admin, &["some-other-ctx"]);

        let err = get_context_secrets(&deps_of(&env), &auth, "med-ctx", "test")
            .await
            .expect_err("admin of another context is still not this context's service");
        assert!(matches!(err, AppError::Forbidden(_)), "got: {err:?}");
    }

    /// The role floor is real and sits below the scope check. A `Reader`
    /// entitled to exactly this context is still refused: seeing that keys
    /// exist is not holding them.
    #[tokio::test]
    async fn a_reader_of_this_very_context_is_below_the_role_floor() {
        let env = open_env().await;
        seed_context_with_keys(&env, "med-ctx").await;
        let auth = scoped(crate::acl::Role::Reader, &["med-ctx"]);

        let err = get_context_secrets(&deps_of(&env), &auth, "med-ctx", "test")
            .await
            .expect_err("a reader may see that keys exist, never hold one");
        assert!(matches!(err, AppError::Forbidden(_)), "got: {err:?}");
    }

    /// The non-leak claim the spec makes about `notFound`: entitlement is
    /// checked before existence, so a caller who is not entitled to an id gets
    /// the *same* refusal whether or not that id exists. Comparing the two
    /// against each other is what makes this an assertion about
    /// indistinguishability rather than about either case alone.
    #[tokio::test]
    async fn entitlement_is_checked_before_existence() {
        let env = open_env().await;
        seed_context_with_keys(&env, "med-ctx").await;
        let auth = scoped(crate::acl::Role::Application, &["some-other-ctx"]);

        let real = get_context_secrets(&deps_of(&env), &auth, "med-ctx", "test")
            .await
            .expect_err("exists, not yours");
        let imaginary = get_context_secrets(&deps_of(&env), &auth, "no-such-ctx", "test")
            .await
            .expect_err("does not exist, and not yours either");

        assert!(matches!(real, AppError::Forbidden(_)), "got: {real:?}");
        assert!(
            matches!(imaginary, AppError::Forbidden(_)),
            "an id that does not exist must not be distinguishable from one that \
             does but is not the caller's — got: {imaginary:?}"
        );
        assert_eq!(
            real.to_string().replace("med-ctx", "<id>"),
            imaginary.to_string().replace("no-such-ctx", "<id>"),
            "the two refusals must differ only in the id echoed back"
        );
    }
}