vta-service 0.35.0

mod acl;
#[cfg(feature = "tee")]
mod attestation;
mod audit;
mod auth;
mod auth_portal;
mod backup;
mod backup_blob;
mod bootstrap;
mod cache;
mod config;
mod contexts;
mod did_templates;
#[cfg(feature = "webvh")]
mod did_webvh;
mod health;
pub mod keys;
#[cfg(feature = "webvh")]
mod passkey_vms;
#[cfg(feature = "webvh")]
mod protocol;
pub mod rate_limit;
#[cfg(feature = "webvh")]
mod self_hosted_did;
mod vta;

use std::time::Duration;

use axum::Router;
use axum::extract::DefaultBodyLimit;
use axum::http::{HeaderName, HeaderValue, Method};
use axum::routing::{get, post};
use ipnetwork::IpNetwork;
use tower_http::cors::{AllowOrigin, CorsLayer};
use tower_http::timeout::TimeoutLayer;
use utoipa::OpenApi;
use utoipa_axum::router::OpenApiRouter;
use utoipa_axum::routes;

use crate::server::AppState;

pub use rate_limit::{Limiter, Quota, QuotaSource, RateLimits};

/// OpenAPI document root for the VTA REST surface.
///
/// The router is the single source of truth for *paths* — every handler
/// annotated with `#[utoipa::path]` and registered via `routes!()` on the
/// [`OpenApiRouter`] contributes its operation here, so the served
/// `/openapi.json` cannot drift from the wired routes. This struct only seeds
/// the document-level metadata (title/version) and the security scheme; it
/// declares no `paths` of its own.
#[derive(OpenApi)]
#[openapi(
    info(
        title = "Verifiable Trust Agent (VTA) API",
        description = "Key-management, DID-webvh, provisioning, and runtime \
                       service-management REST surface of a Verifiable Trust Agent.",
        version = env!("CARGO_PKG_VERSION"),
    ),
    modifiers(&SecurityAddon),
)]
pub struct ApiDoc;

/// Registers the `bearer_jwt` HTTP-bearer security scheme referenced by
/// authenticated operations' `security(("bearer_jwt" = []))`.
struct SecurityAddon;

impl utoipa::Modify for SecurityAddon {
    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
        use utoipa::openapi::security::{HttpAuthScheme, HttpBuilder, SecurityScheme};
        let components = openapi.components.get_or_insert_with(Default::default);
        components.add_security_scheme(
            "bearer_jwt",
            SecurityScheme::Http(
                HttpBuilder::new()
                    .scheme(HttpAuthScheme::Bearer)
                    .bearer_format("JWT")
                    .build(),
            ),
        );
    }
}

/// Serve the assembled OpenAPI document as JSON at `GET /openapi.json`.
///
/// Unauthenticated by design — the document describes the API *shape*, not any
/// secret, and black-box conformance/fuzz tooling (schemathesis, RESTler)
/// fetches it before it holds a token.
async fn serve_openapi(api: utoipa::openapi::OpenApi) -> axum::Json<utoipa::openapi::OpenApi> {
    axum::Json(api)
}

/// Maximum request body size (1 MB). Protects against memory exhaustion,
/// especially critical in TEE deployments where enclave memory is limited.
const MAX_BODY_SIZE: usize = 1024 * 1024;

/// Tighter body cap for unauthenticated endpoints that drive expensive
/// crypto on attacker-controlled bytes (DIDComm `pack`/`unpack`,
/// signature verify, sealed-transfer parse). Sized to fit a generous
/// JWE / sealed-transfer payload but reject 1 MB blob floods that the
/// rate limiter alone cannot starve out.
const UNAUTH_BODY_SIZE: usize = 64 * 1024;

/// Body-size cap for the backup-descriptor blob endpoints. The whole
/// point of the descriptor pattern is to escape the trust-task
/// envelope's 1 MB cap, so this needs a much larger budget. 100 MB
/// covers a typical-to-large VTA's full backup (keys + ACL +
/// contexts + WebVH DID logs + audit). A future enhancement could
/// make this config-driven, but baking the conservative ceiling in
/// avoids an operator footgun (set-to-10-GB).
///
/// `pub(super)` so the blob route handler can pass it to
/// `axum::body::to_bytes` — the per-handler cap is the canonical
/// source of truth; the router-level layer is disabled (see
/// `backup_blob_router` construction below).
pub(super) const BACKUP_BLOB_BODY_SIZE: usize = 100 * 1024 * 1024;

/// Global per-request timeout. The REST surface runs on a current-thread
/// runtime, so a handler that stalls on network I/O (a dead mediator, a
/// slow remote DID host) would otherwise hold its connection — and a
/// caller's patience — indefinitely. Generous on purpose: longer than any
/// legitimate single request (local-fast backups, self-limiting mediator
/// handshakes, a 100 MB blob transfer at modest bandwidth) but bounded, so
/// "indefinite" becomes "120 s then 408". Not a substitute for the
/// handshake/op-specific timeouts, which stay; this is the backstop.
const REQUEST_TIMEOUT: Duration = Duration::from_secs(120);

/// Health-check route — served without the request/response trace layer.
/// Minimal response only; detailed info requires authentication.
pub fn health_router() -> Router<AppState> {
    Router::new().route("/health", get(health::health))
}

/// Health-check route with the same CORS policy as the API surface.
///
/// `/health` is deliberately kept out of the trace + metrics layers
/// (it's a high-frequency liveness probe and would swamp the logs),
/// which is why `server.rs` merges it *after* those layers are applied
/// to the main router. CORS, however, must still cover it: browser
/// tools (e.g. `examples/vta-auth-demo`) probe `/health` cross-origin
/// as their first connectivity check, and without an
/// `Access-Control-Allow-Origin` header the browser blocks the read
/// with an opaque "Failed to fetch". Apply the same origin allowlist
/// here so the probe works whenever the API CORS is configured; an
/// empty allowlist yields no layer (legacy no-cross-origin behaviour).
pub fn health_router_with_cors(allowed_origins: &[String]) -> Router<AppState> {
    let router = health_router();
    match build_cors_layer(allowed_origins) {
        Some(cors) => router.layer(cors),
        None => router,
    }
}

/// Build a CORS layer from a list of allowed origins. Returns
/// `None` when the list is empty — the caller must skip the layer
/// in that case so a fresh-install VTA keeps the legacy
/// no-cross-origin behaviour.
///
/// Cross-origin requests with `Authorization` headers don't carry
/// browser credentials (no `allow_credentials`), so the bearer
/// token is the only client-side state in the cross-origin path.
/// Wildcard origins are deliberately not accepted — every allowed
/// origin must be explicit so a misconfiguration can't let
/// arbitrary sites borrow operator tokens.
fn build_cors_layer(allowed_origins: &[String]) -> Option<CorsLayer> {
    if allowed_origins.is_empty() {
        return None;
    }
    // Filter:
    //   - `*` — tower-http's `AllowOrigin::list` panics on the
    //     wildcard. We deliberately don't fall through to
    //     `AllowOrigin::any()` either; explicit origins only.
    //   - malformed values that can't be parsed as a header value.
    let parsed: Vec<HeaderValue> = allowed_origins
        .iter()
        .filter(|o| !o.is_empty() && *o != "*")
        .filter_map(|o| HeaderValue::from_str(o).ok())
        .collect();
    if parsed.is_empty() {
        // Either an operator passed only invalid entries (a
        // typo'd config that should be visible in startup logs)
        // or the original list was filtered down to nothing. Skip
        // the layer rather than partially-apply CORS — a
        // half-configured CORS surface is worse than none.
        return None;
    }
    Some(
        CorsLayer::new()
            .allow_origin(AllowOrigin::list(parsed))
            .allow_methods([Method::GET, Method::POST, Method::DELETE, Method::PATCH])
            .allow_headers([
                HeaderName::from_static("content-type"),
                HeaderName::from_static("authorization"),
                HeaderName::from_static("x-backup-token"),
            ])
            .max_age(std::time::Duration::from_secs(60)),
    )
}

pub fn router() -> Router<AppState> {
    router_with_cors(&[], &[], QuotaSource::Fixed(RateLimits::default()))
}

/// Assemble the VTA REST surface as an [`OpenApiRouter`] — the single source
/// of truth for both the wired routes and the served OpenAPI document. Routes
/// registered via `routes!()` contribute their `#[utoipa::path]` operation;
/// routes still on plain `.route(...)` are served but not yet described. Global
/// layers (body cap, timeout, CORS) and the `/openapi.json` route are applied
/// by [`router_with_cors`] after splitting.
///
/// `trust_xff_cidrs` selects the rate limiter's IP-attribution strategy. Empty
/// (the default) keys on the socket peer — spoof-proof, and correct whenever
/// clients reach the VTA directly. A non-empty list names the reverse proxies
/// in front of the VTA, and only for a request whose peer is one of them does
/// the limiter read `X-Forwarded-For`; see
/// [`vti_common::rate_limit::TrustedProxyKeyExtractor`] for what that list
/// asserts about the deployment, and `docs/02-vta/rate-limiting.md` for the
/// operator view.
///
/// The router assembled here deliberately carries **no** synthetic-`ConnectInfo`
/// middleware. A request with no peer has no un-spoofable anchor and must be
/// refused, not attributed to a placeholder — a placeholder inside a trusted
/// CIDR would hand the request its own `X-Forwarded-For`. `server::run` serves
/// through `into_make_service_with_connect_info`, so a real peer is always
/// present; only `tower::oneshot` test callers need one synthesised, and they
/// layer it themselves (`test_support::build_test_app_with`).
///
/// `quotas` is where the per-IP limiters on the unauthenticated endpoints read
/// their quotas (see [`rate_limit`] for which routes sit behind which). The
/// running service passes [`QuotaSource::Live`] over the shared config, so a
/// runtime `config/patch` of a rate-limit key applies without rebuilding this
/// router; callers with no config (the OpenAPI spec builder) pass
/// [`QuotaSource::Fixed`].
fn build_api_router(trust_xff_cidrs: &[IpNetwork], quotas: QuotaSource) -> OpenApiRouter<AppState> {
    // Per-IP rate limiters on the unauthenticated endpoints, one bucket set
    // per branch: `auth` (crypto on caller input), `did-log` (public log
    // reads), `backup-blob`. Authenticated routes stay unthrottled — JWT auth
    // is itself a gate, and legitimate operator traffic against the
    // management plane shouldn't be rate-limited.
    let unauth = OpenApiRouter::new()
        // Sealed-transfer bootstrap (token or attestation gated inside)
        .routes(routes!(bootstrap::request))
        // Passkey login (DID-VM-resolved WebAuthn assertions).
        // Trust-task URIs: vta/auth/passkey-login-{start,finish}/1.0.
        // Unauthenticated — the user has no session before
        // passkey-login-finish issues the JWT.
        .routes(routes!(auth::passkey_login_start))
        .routes(routes!(auth::passkey_login_finish))
        // Auth flow entry points
        .routes(routes!(auth::challenge))
        .routes(routes!(auth::authenticate))
        .routes(routes!(auth::refresh));
    // Public, unauthenticated TEE attestation endpoints. These take no
    // auth extractor and run crypto on caller input (report generation),
    // so they MUST sit on the rate-limited + body-capped unauth branch —
    // not the main router, where they previously bypassed both. The
    // super-admin `/attestation/mnemonic` routes stay on the authed
    // router (JWT is their gate).
    #[cfg(feature = "tee")]
    let unauth = unauth
        .routes(routes!(attestation::status))
        .routes(routes!(
            attestation::cached_report,
            attestation::generate_report
        ))
        .routes(routes!(attestation::config_report));
    // Tighter body cap on unauth endpoints — see UNAUTH_BODY_SIZE.
    // Applied after ALL auth-branch routes (including the cfg-gated ones) are
    // registered so every POST on this branch (auth, attestation report)
    // gets the 64 KB ceiling, not just the base set. Layered here (not
    // globally) so authenticated endpoints keep MAX_BODY_SIZE for backup
    // import etc.
    let unauth = unauth.layer(DefaultBodyLimit::max(UNAUTH_BODY_SIZE));
    let unauth = rate_limit::apply(unauth, Limiter::Auth, trust_xff_cidrs, &quotas);

    // Public DID-log retrieval, on its own per-IP limiter. Resolving the
    // VTA's DID precedes every client command and the mediator + readiness
    // gate fetch the log too, while serving it is a store read with no crypto
    // — so it must not spend the auth branch's budget (see `rate_limit`).
    // Still unauthenticated, still rate-limited, still body-capped.
    #[allow(unused_mut)]
    let mut did_log = OpenApiRouter::new();
    // TEE auto-generated did.jsonl — the same public log model.
    #[cfg(feature = "tee")]
    {
        did_log = did_log.routes(routes!(attestation::did_log));
    }
    #[cfg(feature = "webvh")]
    {
        did_log = did_log
            // Public did.jsonl retrieval — matches webvh's world-readable
            // log model, security is cryptographic not access-gated.
            .routes(routes!(did_webvh::get_did_log_public_handler))
            // The VTA's own self-hosted did.jsonl at the canonical resolver
            // paths (see `routes::self_hosted_did` for the security model).
            .routes(routes!(self_hosted_did::get_vta_well_known_did_log_handler))
            // Catch-all canonical did:webvh retrieval for pathful DIDs:
            // `/<path>/did.jsonl`. Returns a bare 404 for every non-canonical
            // path, so it is safe as an unauth fallback-style route.
            //
            // INVARIANT: this must stay the ONLY root-level wildcard route — a
            // second `/{*...}` or an overlapping root `nest()` would conflict in
            // axum's matcher. Static routes keep precedence, so real endpoints
            // are never shadowed.
            .route(
                "/{*did_log_path}",
                get(self_hosted_did::get_vta_canonical_did_log_handler),
            );
    }
    // Same unauth body cap as the auth branch — these are GETs, so any body
    // at all is unexpected.
    let did_log = did_log.layer(DefaultBodyLimit::max(UNAUTH_BODY_SIZE));
    let did_log = rate_limit::apply(did_log, Limiter::DidLog, trust_xff_cidrs, &quotas);

    // Auth portal — same-origin popup target for cross-origin WebAuthn
    // flows. Sits on its own router branch so:
    //  - It's NOT behind the rate-limit layer (operator may refresh
    //    repeatedly while testing).
    //  - It's NOT behind UNAUTH_BODY_SIZE (the HTML response is
    //    bigger than that; the cap is for inbound bodies but separate
    //    branches keep the contract obvious).
    //  - It's NOT behind CORS itself — the response is meant to be
    //    loaded directly into a popup window same-origin, not fetched
    //    cross-origin.
    // See `routes::auth_portal` for the full security model.
    let auth_portal_router =
        OpenApiRouter::new().route("/auth/portal", get(auth_portal::portal_handler));

    // Authenticated provision-integration (context-admin gated). Kept
    // separate from `unauth` so the rate-limiter doesn't apply — the
    // endpoint already hard-gates on `AdminAuth`.
    #[cfg(feature = "webvh")]
    let auth_provision = OpenApiRouter::new().routes(routes!(bootstrap::provision_integration));

    let router = OpenApiRouter::with_openapi(ApiDoc::openapi())
        .merge(unauth)
        .merge(did_log);
    #[cfg(feature = "webvh")]
    let router = router.merge(auth_provision);
    let router = router.merge(auth_portal_router);

    let router = router
        .routes(routes!(auth::session_list, auth::revoke_sessions_by_did))
        .routes(routes!(auth::revoke_session))
        // Trust-task envelope dispatcher (per
        // docs/05-design-notes/trust-task-uri-registry.md). Phase 2
        // scaffold; handlers register per Phase 3 slice. Not yet documented
        // in OpenAPI (dynamic envelope payload).
        // Two paths, one dispatcher, and the second is the conformant one.
        //
        // The HTTPS binding POSTs to `<serviceEndpoint>/trust-tasks`, where
        // `serviceEndpoint` is what the VTA advertises on its Trust-Task
        // service entry. Every deployment example advertises an ORIGIN
        // (`https://trust.example.com`), so a client built from the published
        // binding asks for `/trust-tasks` and, until now, got a 404 — while
        // `vta-sdk` worked only because it hardcodes the same `/api` prefix
        // this service happens to serve. Two implementations agreeing by
        // convention is not a contract; it just hides its absence from the
        // people who wrote both ends.
        //
        // Serving both makes every existing advertisement conformant without
        // an operator touching it: for an origin-advertising VTA the
        // Trust-Task base IS the origin. `/api/trust-tasks` stays for deployed
        // clients and is marked superseded, so the same metric that governs
        // every other retired route decides when it goes.
        .route(
            "/trust-tasks",
            post(crate::trust_tasks::dispatch_trust_task),
        )
        .route(
            "/api/trust-tasks",
            post(crate::trust_tasks::dispatch_trust_task),
        )
        .routes(routes!(config::get_config, config::update_config))
        .routes(routes!(keys::list_keys, keys::create_key))
        .routes(routes!(
            keys::get_key,
            keys::invalidate_key,
            keys::rename_key
        ))
        .routes(routes!(keys::get_key_secret))
        .routes(routes!(keys::sign_with_key))
        .routes(routes!(keys::derive_and_sign_key))
        .routes(routes!(keys::derive_and_sign_document_key))
        .routes(routes!(keys::get_wrapping_key))
        .routes(routes!(keys::import_key))
        .routes(routes!(keys::list_seeds))
        .routes(routes!(keys::rotate_seed))
        // Context routes
        .routes(routes!(
            contexts::list_contexts_handler,
            contexts::create_context_handler
        ))
        .routes(routes!(
            contexts::get_context_handler,
            contexts::update_context_handler,
            contexts::delete_context_handler
        ))
        .routes(routes!(contexts::update_context_did_handler))
        .routes(routes!(contexts::preview_delete_context_handler))
        // DID template routes (global scope — Phase 2)
        .routes(routes!(
            did_templates::list_handler,
            did_templates::create_handler
        ))
        .routes(routes!(
            did_templates::get_handler,
            did_templates::update_handler,
            did_templates::delete_handler
        ))
        .routes(routes!(did_templates::render_handler))
        // DID templates — context scope (Phase 3)
        .routes(routes!(
            did_templates::list_context_handler,
            did_templates::create_context_handler
        ))
        .routes(routes!(
            did_templates::get_context_handler,
            did_templates::update_context_handler,
            did_templates::delete_context_handler
        ))
        .routes(routes!(did_templates::render_context_handler))
        // ACL routes (flattened for consistency)
        .routes(routes!(acl::list_acl, acl::create_acl))
        // Static segment registered before `/acl/{did}` so it isn't captured
        // as a DID. Self-service key rotation (any authenticated caller).
        .routes(routes!(acl::swap_acl))
        .routes(routes!(acl::get_acl, acl::update_acl, acl::delete_acl))
        .routes(routes!(acl::change_role))
        // Audit log routes
        .routes(routes!(audit::list_audit_logs))
        .routes(routes!(audit::get_retention, audit::update_retention))
        // Cache routes (token caching / key-value store)
        .routes(routes!(
            cache::get_cached,
            cache::put_cached,
            cache::delete_cached
        ));

    // TEE attestation routes (feature-gated). The unauthenticated ones
    // (`status`, `report`, `did-log`) live on the rate-limited `unauth`
    // branch above; only the super-admin-gated mnemonic export stays on
    // the authed router (JWT is its gate, so it's intentionally off the
    // rate limiter like every other authed route).
    #[cfg(feature = "tee")]
    let router = router.routes(routes!(
        attestation::mnemonic_status,
        attestation::mnemonic_export
    ));
    // `GET /attestation/admin-credential` retired in Phase 3 —
    // sealed-bootstrap Mode B replaces it via `POST /bootstrap/request`.

    // Protocol management routes (DIDComm enable/disable/migrate;
    // spec docs/05-design-notes/didcomm-protocol-management.md).
    // Plus the symmetric REST routes (spec
    // docs/05-design-notes/runtime-service-management.md §3.4).
    #[cfg(feature = "webvh")]
    let router = router
        .routes(routes!(protocol::enable_rest_handler))
        .routes(routes!(protocol::update_rest_handler))
        .routes(routes!(protocol::disable_rest_handler))
        .routes(routes!(protocol::rollback_rest_handler))
        .routes(routes!(protocol::enable_tsp_handler))
        .routes(routes!(protocol::update_tsp_handler))
        .routes(routes!(protocol::disable_tsp_handler))
        .routes(routes!(protocol::rollback_tsp_handler))
        .routes(routes!(protocol::enable_webauthn_handler))
        .routes(routes!(protocol::update_webauthn_handler))
        .routes(routes!(protocol::disable_webauthn_handler))
        .routes(routes!(protocol::rollback_webauthn_handler))
        .routes(routes!(protocol::list_services_handler))
        .routes(routes!(protocol::mediator_report_handler));

    // The DIDComm half of service management — enable/disable/update/rollback
    // plus the drain surface, which is DIDComm-only (REST and TSP have no
    // drain window). Absent from a TSP-only build, along with the operations
    // behind them; `services {rest,tsp,webauthn} …` above stay mounted.
    #[cfg(all(feature = "webvh", feature = "didcomm"))]
    let router = router
        .routes(routes!(protocol::enable_didcomm_handler))
        .routes(routes!(protocol::get_didcomm_status_handler))
        .routes(routes!(protocol::disable_didcomm_handler))
        // GET list-drain + POST cancel share /services/didcomm/drain.
        .routes(routes!(
            protocol::list_drain_handler,
            protocol::drain_cancel_handler
        ))
        .routes(routes!(protocol::update_didcomm_handler))
        .routes(routes!(protocol::rollback_didcomm_handler))
        // Alias mount of the drain-cancel handler; its #[utoipa::path] lives on
        // the canonical /services/didcomm/drain entry above, so this stays a
        // plain (undocumented) route to avoid a duplicate operation.
        .route(
            "/mediators/drain/cancel",
            post(protocol::drain_cancel_handler),
        );

    // WebVH routes (feature-gated)
    #[cfg(feature = "webvh")]
    let router = router
        .routes(routes!(
            did_webvh::list_servers_handler,
            did_webvh::add_server_handler
        ))
        .routes(routes!(
            did_webvh::update_server_handler,
            did_webvh::remove_server_handler
        ))
        .routes(routes!(did_webvh::list_server_domains_handler))
        .routes(routes!(did_webvh::reconcile_server_dids_handler))
        .routes(routes!(
            did_webvh::list_dids_handler,
            did_webvh::create_did_handler
        ))
        .routes(routes!(
            did_webvh::get_did_handler,
            did_webvh::delete_did_handler
        ))
        .routes(routes!(did_webvh::get_did_log_handler))
        .routes(routes!(did_webvh::register_did_with_server_handler))
        .routes(routes!(did_webvh::update_did_handler))
        .routes(routes!(did_webvh::rotate_did_keys_handler))
        .routes(routes!(did_webvh::realign_did_keys_handler))
        // Passkey-as-verificationMethod enrolment. See
        // `docs/02-vta/passkey-verification-methods.md` (forthcoming).
        // First-time enrolment expects a short-lived enrolment-scope
        // JWT minted by `pnm passkey-enroll-token`; subsequent calls
        // use a passkey-derived session JWT.
        .routes(routes!(passkey_vms::enroll_challenge_handler))
        .routes(routes!(
            passkey_vms::enroll_submit_handler,
            passkey_vms::list_passkeys_handler
        ))
        .routes(routes!(passkey_vms::revoke_passkey_handler));

    // VTA management routes
    let router = router
        .routes(routes!(vta::restart))
        .routes(routes!(vta::metrics))
        .routes(routes!(backup::export))
        .routes(routes!(backup::import));

    // Backup-descriptor blob endpoints. NOT JWT-gated — the
    // `X-Backup-Token` header IS the credential (one-shot for
    // GET, bound to bundle_id, hashed server-side). Justified
    // in `docs/05-design-notes/backup-descriptor-pattern.md`
    // §"Auth model".
    //
    // Body limit: an explicit `BACKUP_BLOB_BODY_SIZE` (100 MB) layer —
    // NOT `disable()`. The global `MAX_BODY_SIZE` (1 MB) is too small for
    // backups (10s of MB), but `disable()` meant any future handler added
    // to this branch silently inherited an *unlimited* body. The layer is
    // a branch backstop at the same value the handler already enforces via
    // `axum::body::to_bytes` (both at `BACKUP_BLOB_BODY_SIZE`, so they
    // agree — no ambiguous override).
    //
    // Rate-limited like the unauth branch: the token gate is real, but
    // without throttling an attacker replaying/guessing bundle_ids gets
    // free 100 MB disk-write attempts and free SHA-256 over 100 MB bodies.
    let backup_blob_router = OpenApiRouter::new()
        .routes(routes!(backup_blob::get_blob, backup_blob::post_blob))
        .layer(DefaultBodyLimit::max(BACKUP_BLOB_BODY_SIZE));
    let backup_blob_router = rate_limit::apply(
        backup_blob_router,
        Limiter::BackupBlob,
        trust_xff_cidrs,
        &quotas,
    );
    let router = router.merge(backup_blob_router);

    // Authenticated health details.
    //
    // `GET /capabilities` used to sit here too. It was removed in #1039: nothing
    // consumed it — `VtaClient::capabilities` goes over `rpc_tt` like every
    // other task — and a REST route running parallel to a Trust Task is exactly
    // the shape #1020 removed everywhere else. Capability discovery is
    // `spec/trust-task-discovery/0.1`; the VTA's deployment inventory is
    // `spec/vta/discovery/capabilities/1.0`. Both reachable on every transport,
    // including this one, via `POST <base>/trust-tasks`.
    router.route("/health/details", get(health::health_details))
}

/// The assembled OpenAPI 3.1 document describing the VTA REST surface.
///
/// Built from the same [`build_api_router`] assembly that wires the live
/// routes, so the document cannot drift from what the service actually serves.
/// Exposed for tests and offline emission; the running service serves this at
/// `GET /openapi.json`.
pub fn openapi_spec() -> utoipa::openapi::OpenApi {
    // CORS attribution doesn't affect the documented surface; build with the
    // safe default.
    build_api_router(&[], QuotaSource::Fixed(RateLimits::default()))
        .split_for_parts()
        .1
}

/// Build the router and conditionally apply a CORS layer for the given list of
/// allowed origins. Wraps [`build_api_router`] for callers (production VTA
/// front-ends) that already hold a config; empty list = no layer = legacy
/// behaviour.
pub fn router_with_cors(
    allowed_origins: &[String],
    trust_xff_cidrs: &[IpNetwork],
    quotas: QuotaSource,
) -> Router<AppState> {
    // Finalise the OpenAPI document from the assembled router (paths come from
    // the `routes!()` registrations) and recover a plain axum `Router` to layer
    // + serve. Splitting here, *before* the global layers, lets `/openapi.json`
    // be added as a sibling that the same global layers then wrap.
    let (router, api) = build_api_router(trust_xff_cidrs, quotas).split_for_parts();
    let router = router.route("/openapi.json", get(move || serve_openapi(api.clone())));

    // Apply global request body size limit to protect enclave memory,
    // plus the global request timeout backstop (no handler may hold a
    // connection indefinitely). The blob branch's own 100 MB body limit,
    // applied inner to this 1 MB global one, still wins for that branch
    // (the inner layer sets the limit extension last).
    // Tag responses from REST routes a Trust-Task has superseded, and count
    // them. Inside the body-limit and timeout layers so it sees the response a
    // route actually produced; see `crate::deprecation` for why removal is
    // gated on this metric reaching zero rather than on a calendar date.
    let router = router.layer(axum::middleware::from_fn(
        crate::deprecation::mark_superseded,
    ));

    let router =
        router
            .layer(DefaultBodyLimit::max(MAX_BODY_SIZE))
            .layer(TimeoutLayer::with_status_code(
                axum::http::StatusCode::REQUEST_TIMEOUT,
                REQUEST_TIMEOUT,
            ));

    // Apply CORS conditionally — empty origin list = no layer at all
    // (preserves the legacy no-cross-origin behaviour for production
    // deployments that don't need browser-side fetch). CORS stays
    // outermost so preflight handling and headers wrap the timeout.
    match build_cors_layer(allowed_origins) {
        Some(cors) => router.layer(cors),
        None => router,
    }
}

#[cfg(test)]
mod cors_tests {
    use super::*;

    #[test]
    fn empty_list_disables_cors_entirely() {
        assert!(build_cors_layer(&[]).is_none());
    }

    #[test]
    fn explicit_origin_produces_layer() {
        let layer = build_cors_layer(&["http://localhost:8000".to_string()]);
        assert!(layer.is_some());
    }

    #[test]
    fn invalid_origin_filtered_out_and_empty_result_returns_none() {
        // `\n` is invalid in a header value. If it's the only entry,
        // the filter empties the list and we end up at the
        // no-layer branch — a fresh-install VTA shouldn't get a
        // partially-applied CORS surface just because a config typo
        // got past serde.
        let bad_origin = "http://localhost:8000\n".to_string();
        assert!(build_cors_layer(&[bad_origin]).is_none());
    }

    #[test]
    fn wildcard_alone_yields_no_layer() {
        // tower-http's `AllowOrigin::list` PANICS on the literal
        // `*`. The build_cors_layer filter strips wildcards
        // explicitly so an operator typo can't bring down the
        // VTA at startup. (Wildcards would also expose bearer
        // tokens to any origin, which is exactly the kind of
        // config error we want to refuse — better empty than
        // permissive.)
        assert!(
            build_cors_layer(&["*".to_string()]).is_none(),
            "wildcard must be filtered to None, never partial-applied"
        );
    }

    #[test]
    fn wildcard_mixed_with_explicit_origins_drops_wildcard_keeps_others() {
        // Defensive: a mixed list shouldn't break the layer
        // build — the wildcard is dropped and the explicit
        // entries remain.
        let layer = build_cors_layer(&["*".to_string(), "http://localhost:8000".to_string()]);
        assert!(layer.is_some());
    }

    #[test]
    fn empty_origin_string_filtered() {
        // Operator pastes a blank line into config — should be
        // skipped, not turned into an empty header value.
        let layer = build_cors_layer(&["".to_string(), "http://x".to_string()]);
        assert!(layer.is_some());
    }

    #[test]
    fn openapi_spec_describes_registered_routes() {
        let spec = openapi_spec();
        // The document-level metadata + security scheme are seeded by ApiDoc.
        assert_eq!(spec.info.title, "Verifiable Trust Agent (VTA) API");
        let schemes = &spec
            .components
            .as_ref()
            .expect("components present once a route contributes a schema")
            .security_schemes;
        assert!(
            schemes.contains_key("bearer_jwt"),
            "bearer_jwt security scheme must be registered"
        );
        // `/capabilities` was this assertion's subject — the first route
        // migrated to OpenAPI-aware registration — and the route is gone
        // (#1039). Pin a different migrated route rather than deleting the
        // check: what it is really asserting is that `routes!()` registration
        // still lands operations in the served document, and that property did
        // not go away with the route.
        let challenge = spec
            .paths
            .paths
            .get("/auth/challenge")
            .expect("/auth/challenge operation must be in the spec");
        assert!(
            challenge.post.is_some(),
            "/auth/challenge must document a POST operation"
        );
    }

    #[test]
    fn openapi_spec_covers_the_route_groups() {
        let spec = openapi_spec();
        let paths = &spec.paths.paths;
        // A representative path from each major route group must be documented.
        for p in [
            "/auth/challenge",
            "/keys",
            "/keys/{key_id}",
            "/contexts",
            "/acl",
            "/acl/{did}",
            "/did-templates",
            "/audit/logs",
            "/cache/{key}",
            "/config",
            "/vta/restart",
            "/backup/export",
            "/backup/blob/{bundle_id}",
            // webvh (default feature) groups
            "/services/didcomm/enable",
            "/services",
            "/webvh/dids",
            "/webvh/servers",
            "/did/verification-methods/passkey",
            "/.well-known/did.jsonl",
        ] {
            assert!(paths.contains_key(p), "spec missing documented path {p}");
        }
        // The full surface should be substantial — guard against a regression
        // that silently drops the bulk of the routes.
        assert!(
            paths.len() >= 60,
            "expected the documented surface to be >= 60 paths, got {}",
            paths.len()
        );
    }

    #[test]
    fn health_router_with_cors_builds_both_branches() {
        // Both the with-origins (layer applied) and empty (no layer)
        // branches must construct without panicking. `.layer(cors)`
        // on a wildcard would panic inside tower-http, but
        // `build_cors_layer` filters wildcards to `None` first — this
        // guards the wiring that depends on that invariant.
        let _with = health_router_with_cors(&["http://localhost:8000".to_string()]);
        let _without = health_router_with_cors(&[]);
        let _wildcard_only = health_router_with_cors(&["*".to_string()]);
    }

    #[test]
    fn build_api_router_accepts_custom_rate_limit() {
        // Constructing with non-default quotas must not panic.
        let _ = build_api_router(
            &[],
            QuotaSource::Fixed(RateLimits::new(Quota::new(50, 100), Quota::new(2, 500))),
        );
        let _ = build_api_router(
            &["127.0.0.1/32".parse().unwrap()],
            QuotaSource::Fixed(RateLimits::new(Quota::new(1000, 2000), Quota::new(1, 1))),
        );
    }

    #[test]
    fn router_with_cors_passes_rate_limit_through() {
        // The full router assembly with custom rate limits must not panic.
        let _ = router_with_cors(
            &[],
            &[],
            QuotaSource::Fixed(RateLimits::new(Quota::new(50, 100), Quota::new(3, 30))),
        );
    }

    /// A `0` in any of the four `[server]` rate-limit keys reaches the
    /// limiters, where a zero period or burst has no governor quota — the
    /// `.expect()` building one would panic the REST thread. This asserts the
    /// production clamp (`Quota::new`), not a test helper's: it goes through
    /// the real router builders on both `trust_xff_cidrs` branches (empty and
    /// non-empty), from a real `ServerConfig`. (The live path re-reads config
    /// per request and clamps the same way; `rate_limit::tests` covers it.)
    #[test]
    fn zero_rate_limit_config_is_clamped_not_panicked() {
        let server = crate::config::ServerConfig {
            rate_limit_interval_secs: 0,
            rate_limit_burst: 0,
            did_log_rate_limit_interval_secs: 0,
            did_log_rate_limit_burst: 0,
            ..Default::default()
        };
        let limits = QuotaSource::Fixed(RateLimits::from_server_config(&server));
        let _ = build_api_router(&[], limits.clone());
        let _ = build_api_router(&["127.0.0.1/32".parse().unwrap()], limits.clone());
        let _ = router_with_cors(&[], &[], limits);
    }
}

/// Pins the meaning of the two `[server]` rate-limit knobs against
/// `tower_governor` itself: `per_second(n)` is a *replenishment interval*
/// (one token every `n` seconds), and `burst_size(b)` is how many requests
/// get through back-to-back before throttling starts.
///
/// This exercises `tower_governor` directly rather than [`rate_limit::apply`]:
/// the production limiter is now our own middleware over the same `governor`
/// quota (`Quota::with_period(interval).allow_burst(burst)`), and these pin
/// the semantics that construction inherits. The wrapper (branch
/// independence, the 429 contract) is covered in `rate_limit::tests`, the
/// end-to-end wiring by the harness test
/// `unauth_endpoint_rate_limit_returns_429_after_burst`, and the clamp by
/// `cors_tests::zero_rate_limit_config_is_clamped_not_panicked` above.
#[cfg(test)]
mod rate_limit_tests {
    use std::sync::Arc;

    use axum::http::{Request, StatusCode};
    use axum::routing::get;
    use tower::ServiceExt;
    use tower_governor::GovernorLayer;
    use tower_governor::governor::GovernorConfigBuilder;

    async fn handler() -> &'static str {
        "ok"
    }

    /// Build a minimal rate-limited router (no AppState needed). Deliberately
    /// does *not* clamp — clamping is the production path's job and is
    /// asserted there, so a helper that repeated it would hide a regression.
    fn limited_router(interval_secs: u64, burst: u32) -> axum::Router {
        let cfg = Arc::new(
            GovernorConfigBuilder::default()
                .per_second(interval_secs)
                .burst_size(burst)
                .key_extractor(tower_governor::key_extractor::SmartIpKeyExtractor)
                .finish()
                .unwrap(),
        );
        axum::Router::new()
            .route("/test", get(handler))
            .layer(GovernorLayer::new(cfg))
    }

    #[tokio::test]
    async fn burst_2_rejects_third_request() {
        let app = limited_router(60, 2);

        let mut statuses = Vec::new();
        for _ in 0..4 {
            let req = Request::builder()
                .uri("/test")
                .header("x-forwarded-for", "10.0.0.1")
                .body(axum::body::Body::empty())
                .unwrap();
            let resp = app.clone().oneshot(req).await.unwrap();
            statuses.push(resp.status());
        }
        assert_eq!(statuses[0], StatusCode::OK);
        assert_eq!(statuses[1], StatusCode::OK);
        assert_eq!(
            statuses[2],
            StatusCode::TOO_MANY_REQUESTS,
            "third request must be rejected when burst=2"
        );
    }

    #[tokio::test]
    async fn burst_5_allows_five_then_rejects() {
        let app = limited_router(60, 5);

        let mut ok_count = 0u32;
        let mut rejected = false;
        for _ in 0..8 {
            let req = Request::builder()
                .uri("/test")
                .header("x-forwarded-for", "10.0.0.1")
                .body(axum::body::Body::empty())
                .unwrap();
            let resp = app.clone().oneshot(req).await.unwrap();
            if resp.status() == StatusCode::OK {
                ok_count += 1;
            } else if resp.status() == StatusCode::TOO_MANY_REQUESTS {
                rejected = true;
                break;
            }
        }
        assert_eq!(ok_count, 5, "expected exactly 5 OK before rejection");
        assert!(rejected, "expected 429 after burst exhausted");
    }

    /// The reason the production path clamps: a zero period or burst makes
    /// `finish()` return `None`, so an unclamped `.expect()` would panic.
    #[test]
    fn zero_period_or_burst_has_no_governor_config() {
        // Same builder chain as `rate_limit::apply`, minus the clamp.
        let zero_period = GovernorConfigBuilder::default()
            .per_second(0)
            .burst_size(10)
            .key_extractor(tower_governor::key_extractor::SmartIpKeyExtractor)
            .finish();
        assert!(zero_period.is_none(), "zero period must not yield a config");

        let zero_burst = GovernorConfigBuilder::default()
            .per_second(5)
            .burst_size(0)
            .key_extractor(tower_governor::key_extractor::SmartIpKeyExtractor)
            .finish();
        assert!(zero_burst.is_none(), "zero burst must not yield a config");
    }
}