canic_core/api/auth/

mod.rs

use crate::{
    access::auth::validate_delegated_session_subject,
    cdk::types::Principal,
    dto::{
        auth::{
            AttestationKeySet, DelegatedToken, DelegatedTokenClaims, DelegationAdminCommand,
            DelegationAdminResponse, DelegationCert, DelegationProof,
            DelegationProofInstallRequest, DelegationProvisionResponse, DelegationProvisionStatus,
            DelegationProvisionTargetKind, DelegationRequest, DelegationVerifierProofPushRequest,
            RoleAttestationRequest, SignedRoleAttestation,
        },
        error::{Error, ErrorCode},
        rpc::{Request as RootRequest, Response as RootCapabilityResponse},
    },
    error::InternalErrorClass,
    log,
    log::Topic,
    ops::{
        auth::DelegatedTokenOps,
        config::ConfigOps,
        ic::IcOps,
        rpc::RpcOps,
        runtime::env::EnvOps,
        runtime::metrics::auth::{
            DelegationInstallNormalizationRejectReason, DelegationInstallValidationFailureReason,
            VerifierProofCacheEvictionClass, record_attestation_refresh_failed,
            record_delegation_install_fanout_bucket,
            record_delegation_install_normalization_rejected,
            record_delegation_install_normalized_target_count, record_delegation_install_total,
            record_delegation_install_validation_failed, record_delegation_provision_complete,
            record_delegation_verifier_target_count, record_delegation_verifier_target_failed,
            record_delegation_verifier_target_missing, record_session_bootstrap_rejected_disabled,
            record_session_bootstrap_rejected_replay_conflict,
            record_session_bootstrap_rejected_replay_reused,
            record_session_bootstrap_rejected_subject_mismatch,
            record_session_bootstrap_rejected_subject_rejected,
            record_session_bootstrap_rejected_token_invalid,
            record_session_bootstrap_rejected_ttl_invalid,
            record_session_bootstrap_rejected_wallet_caller_rejected,
            record_session_bootstrap_replay_idempotent, record_session_cleared,
            record_session_created, record_session_pruned, record_session_replaced,
            record_signer_issue_without_proof, record_verifier_proof_cache_eviction,
            record_verifier_proof_cache_stats,
        },
        storage::{
            auth::{DelegatedSession, DelegatedSessionBootstrapBinding, DelegationStateOps},
            directory::subnet::SubnetDirectoryOps,
            registry::subnet::SubnetRegistryOps,
        },
    },
    protocol,
    workflow::{auth::DelegationWorkflow, rpc::request::handler::RootResponseWorkflow},
};
use sha2::{Digest, Sha256};

mod metadata;
mod verify_flow;

///
/// DelegationApi
///
/// Requires auth.delegated_tokens.enabled = true in config.
///

pub struct DelegationApi;

struct PreparedDelegationVerifierPush {
    proof: DelegationProof,
    verifier_targets: Vec<Principal>,
    intent: crate::dto::auth::DelegationProofInstallIntent,
}

impl PreparedDelegationVerifierPush {
    fn into_command(self) -> DelegationAdminCommand {
        let request = DelegationVerifierProofPushRequest {
            proof: self.proof,
            verifier_targets: self.verifier_targets,
        };
        match self.intent {
            crate::dto::auth::DelegationProofInstallIntent::Prewarm => {
                DelegationAdminCommand::PrewarmVerifiers(request)
            }
            crate::dto::auth::DelegationProofInstallIntent::Repair => {
                DelegationAdminCommand::RepairVerifiers(request)
            }
            crate::dto::auth::DelegationProofInstallIntent::Provisioning => {
                unreachable!("provisioning does not use explicit admin push")
            }
        }
    }
}

impl DelegationApi {
    const DELEGATED_TOKENS_DISABLED: &str =
        "delegated token auth disabled; set auth.delegated_tokens.enabled=true in canic.toml";
    const MAX_DELEGATED_SESSION_TTL_SECS: u64 = 24 * 60 * 60;
    const SESSION_BOOTSTRAP_TOKEN_FINGERPRINT_DOMAIN: &[u8] =
        b"canic-session-bootstrap-token-fingerprint:v1";

    fn map_delegation_error(err: crate::InternalError) -> Error {
        match err.class() {
            InternalErrorClass::Infra | InternalErrorClass::Ops | InternalErrorClass::Workflow => {
                Error::internal(err.to_string())
            }
            _ => Error::from(err),
        }
    }

    /// Full delegation proof verification (structure + signature).
    ///
    /// Purely local verification; does not read certified data or require a
    /// query context.
    pub fn verify_delegation_proof(
        proof: &DelegationProof,
        authority_pid: Principal,
    ) -> Result<(), Error> {
        DelegatedTokenOps::verify_delegation_proof(proof, authority_pid)
            .map_err(Self::map_delegation_error)
    }

    #[cfg(canic_test_delegation_material)]
    #[must_use]
    pub fn current_signing_proof_for_test() -> Option<DelegationProof> {
        DelegationStateOps::latest_proof_dto()
    }

    async fn sign_token(
        claims: DelegatedTokenClaims,
        proof: DelegationProof,
    ) -> Result<DelegatedToken, Error> {
        DelegatedTokenOps::sign_token(claims, proof)
            .await
            .map_err(Self::map_delegation_error)
    }

    /// Issue a delegated token using a reusable local proof when possible.
    ///
    /// If the proof is missing or no longer valid for the requested claims, this
    /// performs canonical shard-initiated setup and retries with the refreshed proof.
    pub async fn issue_token(claims: DelegatedTokenClaims) -> Result<DelegatedToken, Error> {
        let proof = Self::ensure_signing_proof(&claims).await?;
        Self::sign_token(claims, proof).await
    }

    /// Full delegated token verification (structure + signature).
    ///
    /// Purely local verification; does not read certified data or require a
    /// query context.
    pub fn verify_token(
        token: &DelegatedToken,
        authority_pid: Principal,
        now_secs: u64,
    ) -> Result<(), Error> {
        DelegatedTokenOps::verify_token(token, authority_pid, now_secs, IcOps::canister_self())
            .map(|_| ())
            .map_err(Self::map_delegation_error)
    }

    /// Verify a delegated token and return verified contents.
    ///
    /// This is intended for application-layer session construction.
    /// It performs full verification and returns verified claims and cert.
    pub fn verify_token_verified(
        token: &DelegatedToken,
        authority_pid: Principal,
        now_secs: u64,
    ) -> Result<(DelegatedTokenClaims, DelegationCert), Error> {
        DelegatedTokenOps::verify_token(token, authority_pid, now_secs, IcOps::canister_self())
            .map(|verified| (verified.claims, verified.cert))
            .map_err(Self::map_delegation_error)
    }

    /// Canonical shard-initiated delegation request (user_shard -> root).
    ///
    /// Caller must match shard_pid and be registered to the subnet.
    pub async fn request_delegation(
        request: DelegationRequest,
    ) -> Result<DelegationProvisionResponse, Error> {
        let request = metadata::with_root_request_metadata(request);
        if EnvOps::is_root() {
            let response = RootResponseWorkflow::response(RootRequest::issue_delegation(request))
                .await
                .map_err(Self::map_delegation_error)?;

            return match response {
                RootCapabilityResponse::DelegationIssued(response) => Ok(response),
                _ => Err(Error::internal(
                    "invalid root response type for delegation request",
                )),
            };
        }

        let root_pid = EnvOps::root_pid().map_err(Error::from)?;
        RpcOps::call_rpc_result(root_pid, protocol::CANIC_REQUEST_DELEGATION, request)
            .await
            .map_err(Self::map_delegation_error)
    }

    pub async fn request_role_attestation(
        request: RoleAttestationRequest,
    ) -> Result<SignedRoleAttestation, Error> {
        let request = metadata::with_root_attestation_request_metadata(request);
        let response = RootResponseWorkflow::response(RootRequest::issue_role_attestation(request))
            .await
            .map_err(Self::map_delegation_error)?;

        match response {
            RootCapabilityResponse::RoleAttestationIssued(response) => Ok(response),
            _ => Err(Error::internal(
                "invalid root response type for role attestation request",
            )),
        }
    }

    pub async fn attestation_key_set() -> Result<AttestationKeySet, Error> {
        DelegatedTokenOps::attestation_key_set()
            .await
            .map_err(Self::map_delegation_error)
    }

    /// Execute explicit root-controlled delegation repair/prewarm operations.
    pub async fn admin(cmd: DelegationAdminCommand) -> Result<DelegationAdminResponse, Error> {
        let cfg = ConfigOps::delegated_tokens_config().map_err(Error::from)?;
        if !cfg.enabled {
            return Err(Error::forbidden(Self::DELEGATED_TOKENS_DISABLED));
        }
        if !EnvOps::is_root() {
            return Err(Error::forbidden("delegation admin requires root canister"));
        }

        let prepared = match cmd {
            DelegationAdminCommand::PrewarmVerifiers(request) => {
                record_delegation_install_total(
                    crate::dto::auth::DelegationProofInstallIntent::Prewarm,
                );
                Self::prepare_explicit_verifier_push(
                    request,
                    crate::dto::auth::DelegationProofInstallIntent::Prewarm,
                )
                .await?
            }
            DelegationAdminCommand::RepairVerifiers(request) => {
                record_delegation_install_total(
                    crate::dto::auth::DelegationProofInstallIntent::Repair,
                );
                Self::prepare_explicit_verifier_push(
                    request,
                    crate::dto::auth::DelegationProofInstallIntent::Repair,
                )
                .await?
            }
        };

        DelegationWorkflow::handle_admin(prepared.into_command())
            .await
            .map_err(Self::map_delegation_error)
    }

    pub fn replace_attestation_key_set(key_set: AttestationKeySet) {
        DelegatedTokenOps::replace_attestation_key_set(key_set);
    }

    pub async fn verify_role_attestation(
        attestation: &SignedRoleAttestation,
        min_accepted_epoch: u64,
    ) -> Result<(), Error> {
        let configured_min_accepted_epoch = ConfigOps::role_attestation_config()
            .map_err(Error::from)?
            .min_accepted_epoch_by_role
            .get(attestation.payload.role.as_str())
            .copied();
        let min_accepted_epoch = verify_flow::resolve_min_accepted_epoch(
            min_accepted_epoch,
            configured_min_accepted_epoch,
        );

        let caller = IcOps::msg_caller();
        let self_pid = IcOps::canister_self();
        let now_secs = IcOps::now_secs();
        let verifier_subnet = Some(EnvOps::subnet_pid().map_err(Error::from)?);
        let root_pid = EnvOps::root_pid().map_err(Error::from)?;

        let verify = || {
            DelegatedTokenOps::verify_role_attestation_cached(
                attestation,
                caller,
                self_pid,
                verifier_subnet,
                now_secs,
                min_accepted_epoch,
            )
            .map(|_| ())
        };
        let refresh = || async {
            let key_set: AttestationKeySet =
                RpcOps::call_rpc_result(root_pid, protocol::CANIC_ATTESTATION_KEY_SET, ()).await?;
            DelegatedTokenOps::replace_attestation_key_set(key_set);
            Ok(())
        };

        match verify_flow::verify_role_attestation_with_single_refresh(verify, refresh).await {
            Ok(()) => Ok(()),
            Err(verify_flow::RoleAttestationVerifyFlowError::Initial(err)) => {
                verify_flow::record_attestation_verifier_rejection(&err);
                verify_flow::log_attestation_verifier_rejection(
                    &err,
                    attestation,
                    caller,
                    self_pid,
                    "cached",
                );
                Err(Self::map_delegation_error(err.into()))
            }
            Err(verify_flow::RoleAttestationVerifyFlowError::Refresh { trigger, source }) => {
                verify_flow::record_attestation_verifier_rejection(&trigger);
                verify_flow::log_attestation_verifier_rejection(
                    &trigger,
                    attestation,
                    caller,
                    self_pid,
                    "cache_miss_refresh",
                );
                record_attestation_refresh_failed();
                log!(
                    Topic::Auth,
                    Warn,
                    "role attestation refresh failed local={} caller={} key_id={} error={}",
                    self_pid,
                    caller,
                    attestation.key_id,
                    source
                );
                Err(Self::map_delegation_error(source))
            }
            Err(verify_flow::RoleAttestationVerifyFlowError::PostRefresh(err)) => {
                verify_flow::record_attestation_verifier_rejection(&err);
                verify_flow::log_attestation_verifier_rejection(
                    &err,
                    attestation,
                    caller,
                    self_pid,
                    "post_refresh",
                );
                Err(Self::map_delegation_error(err.into()))
            }
        }
    }

    /// Persist a temporary delegated session subject for the caller wallet.
    pub fn set_delegated_session_subject(
        delegated_subject: Principal,
        bootstrap_token: DelegatedToken,
        requested_ttl_secs: Option<u64>,
    ) -> Result<(), Error> {
        let cfg = ConfigOps::delegated_tokens_config().map_err(Error::from)?;
        if !cfg.enabled {
            record_session_bootstrap_rejected_disabled();
            return Err(Error::forbidden(Self::DELEGATED_TOKENS_DISABLED));
        }

        let wallet_caller = IcOps::msg_caller();
        if let Err(reason) = validate_delegated_session_subject(wallet_caller) {
            record_session_bootstrap_rejected_wallet_caller_rejected();
            return Err(Error::forbidden(format!(
                "delegated session wallet caller rejected: {reason}"
            )));
        }

        if let Err(reason) = validate_delegated_session_subject(delegated_subject) {
            record_session_bootstrap_rejected_subject_rejected();
            return Err(Error::forbidden(format!(
                "delegated session subject rejected: {reason}"
            )));
        }

        let issued_at = IcOps::now_secs();
        let authority_pid = EnvOps::root_pid().map_err(Error::from)?;
        let self_pid = IcOps::canister_self();
        let verified =
            DelegatedTokenOps::verify_token(&bootstrap_token, authority_pid, issued_at, self_pid)
                .map_err(|err| {
                record_session_bootstrap_rejected_token_invalid();
                Self::map_delegation_error(err)
            })?;

        if verified.claims.sub != delegated_subject {
            record_session_bootstrap_rejected_subject_mismatch();
            return Err(Error::forbidden(format!(
                "delegated session subject mismatch: requested={} token_subject={}",
                delegated_subject, verified.claims.sub
            )));
        }

        let configured_max_ttl_secs = cfg
            .max_ttl_secs
            .unwrap_or(Self::MAX_DELEGATED_SESSION_TTL_SECS);
        let expires_at = Self::clamp_delegated_session_expires_at(
            issued_at,
            verified.claims.exp,
            configured_max_ttl_secs,
            requested_ttl_secs,
        )
        .inspect_err(|_| record_session_bootstrap_rejected_ttl_invalid())?;

        let token_fingerprint =
            Self::delegated_session_bootstrap_token_fingerprint(&bootstrap_token)
                .inspect_err(|_| record_session_bootstrap_rejected_token_invalid())?;

        if Self::enforce_bootstrap_replay_policy(
            wallet_caller,
            delegated_subject,
            token_fingerprint,
            issued_at,
        )? {
            return Ok(());
        }

        let had_active_session =
            DelegationStateOps::delegated_session(wallet_caller, issued_at).is_some();

        DelegationStateOps::upsert_delegated_session(
            DelegatedSession {
                wallet_pid: wallet_caller,
                delegated_pid: delegated_subject,
                issued_at,
                expires_at,
                bootstrap_token_fingerprint: Some(token_fingerprint),
            },
            issued_at,
        );
        DelegationStateOps::upsert_delegated_session_bootstrap_binding(
            DelegatedSessionBootstrapBinding {
                wallet_pid: wallet_caller,
                delegated_pid: delegated_subject,
                token_fingerprint,
                bound_at: issued_at,
                expires_at: verified.claims.exp,
            },
            issued_at,
        );

        if had_active_session {
            record_session_replaced();
        } else {
            record_session_created();
        }

        Ok(())
    }

    /// Remove the caller's delegated session subject.
    pub fn clear_delegated_session() {
        let wallet_caller = IcOps::msg_caller();
        let had_active_session =
            DelegationStateOps::delegated_session(wallet_caller, IcOps::now_secs()).is_some();
        DelegationStateOps::clear_delegated_session(wallet_caller);
        if had_active_session {
            record_session_cleared();
        }
    }

    /// Read the caller's active delegated session subject, if configured.
    #[must_use]
    pub fn delegated_session_subject() -> Option<Principal> {
        let wallet_caller = IcOps::msg_caller();
        DelegationStateOps::delegated_session_subject(wallet_caller, IcOps::now_secs())
    }

    /// Prune all currently expired delegated sessions.
    #[must_use]
    pub fn prune_expired_delegated_sessions() -> usize {
        let now_secs = IcOps::now_secs();
        let removed = DelegationStateOps::prune_expired_delegated_sessions(now_secs);
        let _ = DelegationStateOps::prune_expired_delegated_session_bootstrap_bindings(now_secs);
        if removed > 0 {
            record_session_pruned(removed);
        }
        removed
    }

    pub async fn store_proof(
        request: DelegationProofInstallRequest,
        kind: DelegationProvisionTargetKind,
    ) -> Result<(), Error> {
        let cfg = ConfigOps::delegated_tokens_config().map_err(Error::from)?;
        if !cfg.enabled {
            return Err(Error::forbidden(Self::DELEGATED_TOKENS_DISABLED));
        }

        let root_pid = EnvOps::root_pid().map_err(Error::from)?;
        let caller = IcOps::msg_caller();
        if caller != root_pid {
            return Err(Error::forbidden(
                "delegation proof store requires root caller",
            ));
        }

        let proof = request.proof;
        let intent = request.intent;

        DelegatedTokenOps::cache_public_keys_for_cert(&proof.cert)
            .await
            .map_err(Self::map_delegation_error)?;
        if let Err(err) = DelegatedTokenOps::verify_delegation_proof(&proof, root_pid) {
            let local = IcOps::canister_self();
            log!(
                Topic::Auth,
                Warn,
                "delegation proof rejected intent={:?} kind={:?} local={} shard={} issued_at={} expires_at={} error={}",
                intent,
                kind,
                local,
                proof.cert.shard_pid,
                proof.cert.issued_at,
                proof.cert.expires_at,
                err
            );
            return Err(Self::map_delegation_error(err));
        }

        let outcome = DelegationStateOps::upsert_proof_from_dto(proof.clone(), IcOps::now_secs())
            .map_err(Self::map_delegation_error)?;
        if kind == DelegationProvisionTargetKind::Verifier {
            Self::record_verifier_cache_install_outcome(outcome);
        }
        let local = IcOps::canister_self();
        log!(
            Topic::Auth,
            Info,
            "delegation proof stored intent={:?} kind={:?} local={} shard={} issued_at={} expires_at={}",
            intent,
            kind,
            local,
            proof.cert.shard_pid,
            proof.cert.issued_at,
            proof.cert.expires_at
        );

        Ok(())
    }

    /// Install delegation proof and key material directly, bypassing management-key lookups.
    ///
    /// This is intended for controlled root-driven test flows where deterministic
    /// key material is used instead of chain-key ECDSA.
    // Compiled only for controlled test canister builds.
    #[cfg(canic_test_delegation_material)]
    pub fn install_test_delegation_material(
        proof: DelegationProof,
        root_public_key: Vec<u8>,
        shard_public_key: Vec<u8>,
    ) -> Result<(), Error> {
        let root_pid = EnvOps::root_pid().map_err(Error::from)?;
        let caller = IcOps::msg_caller();
        if caller != root_pid {
            return Err(Error::forbidden(
                "test delegation material install requires root caller",
            ));
        }

        if proof.cert.root_pid != root_pid {
            return Err(Error::invalid(format!(
                "delegation proof root mismatch: expected={} found={}",
                root_pid, proof.cert.root_pid
            )));
        }

        if root_public_key.is_empty() || shard_public_key.is_empty() {
            return Err(Error::invalid("delegation public keys must not be empty"));
        }

        DelegationStateOps::set_root_public_key(root_public_key);
        DelegationStateOps::set_shard_public_key(proof.cert.shard_pid, shard_public_key);
        let outcome = DelegationStateOps::upsert_proof_from_dto(proof, IcOps::now_secs())
            .map_err(Self::map_delegation_error)?;
        Self::record_verifier_cache_install_outcome(outcome);
        Ok(())
    }

    fn require_proof() -> Result<DelegationProof, Error> {
        let cfg = ConfigOps::delegated_tokens_config().map_err(Error::from)?;
        if !cfg.enabled {
            return Err(Error::forbidden(Self::DELEGATED_TOKENS_DISABLED));
        }

        DelegationStateOps::latest_proof_dto().ok_or_else(|| {
            record_signer_issue_without_proof();
            Error::not_found("delegation proof not installed")
        })
    }

    // Resolve a proof that is currently usable for token issuance.
    async fn ensure_signing_proof(claims: &DelegatedTokenClaims) -> Result<DelegationProof, Error> {
        let now_secs = IcOps::now_secs();

        match Self::require_proof() {
            Ok(proof) if !Self::proof_is_reusable_for_claims(&proof, claims, now_secs) => {
                Self::setup_delegation(claims).await
            }
            Ok(proof) => Ok(proof),
            Err(err) if err.code == ErrorCode::NotFound => Self::setup_delegation(claims).await,
            Err(err) => Err(err),
        }
    }

    // Provision a fresh delegation from root, then resolve the latest locally stored proof.
    async fn setup_delegation(claims: &DelegatedTokenClaims) -> Result<DelegationProof, Error> {
        let request = Self::delegation_request_from_claims(claims)?;
        let required_verifier_targets = request.verifier_targets.clone();
        let response = Self::request_delegation(request).await?;
        Self::ensure_required_verifier_targets_provisioned(&required_verifier_targets, &response)?;
        Self::require_proof()
    }

    // Build a canonical delegation request from token claims.
    fn delegation_request_from_claims(
        claims: &DelegatedTokenClaims,
    ) -> Result<DelegationRequest, Error> {
        let ttl_secs = claims.exp.saturating_sub(claims.iat);
        if ttl_secs == 0 {
            return Err(Error::invalid(
                "delegation ttl_secs must be greater than zero",
            ));
        }

        let signer_pid = IcOps::canister_self();
        let root_pid = EnvOps::root_pid().map_err(Error::from)?;
        let verifier_targets = Self::derive_required_verifier_targets_from_aud(
            &claims.aud,
            signer_pid,
            root_pid,
            Self::is_registered_canister,
        )?;

        Ok(DelegationRequest {
            shard_pid: signer_pid,
            scopes: claims.scopes.clone(),
            aud: claims.aud.clone(),
            ttl_secs,
            verifier_targets,
            include_root_verifier: true,
            metadata: None,
        })
    }

    // Validate required verifier fanout and fail closed when any required target is missing/failing.
    fn ensure_required_verifier_targets_provisioned(
        required_targets: &[Principal],
        response: &DelegationProvisionResponse,
    ) -> Result<(), Error> {
        let mut checked = Vec::new();
        for target in required_targets {
            if checked.contains(target) {
                continue;
            }
            checked.push(*target);
        }
        record_delegation_verifier_target_count(checked.len());

        for target in &checked {
            let Some(result) = response.results.iter().find(|entry| {
                entry.kind == DelegationProvisionTargetKind::Verifier && entry.target == *target
            }) else {
                record_delegation_verifier_target_missing();
                return Err(Error::internal(format!(
                    "delegation provisioning missing verifier target result for '{target}'"
                )));
            };

            if result.status != DelegationProvisionStatus::Ok {
                record_delegation_verifier_target_failed();
                let detail = result
                    .error
                    .as_ref()
                    .map_or_else(|| "unknown error".to_string(), ToString::to_string);
                return Err(Error::internal(format!(
                    "delegation provisioning failed for required verifier target '{target}': {detail}"
                )));
            }
        }

        record_delegation_provision_complete();
        Ok(())
    }

    // Normalize and verify an explicit verifier-push request before workflow fanout.
    async fn prepare_explicit_verifier_push(
        request: DelegationVerifierProofPushRequest,
        intent: crate::dto::auth::DelegationProofInstallIntent,
    ) -> Result<PreparedDelegationVerifierPush, Error> {
        let request = Self::normalize_explicit_verifier_push_request_with(
            request,
            intent,
            EnvOps::root_pid().map_err(Error::from)?,
            Self::is_registered_canister,
        )?;
        record_delegation_install_normalized_target_count(intent, request.verifier_targets.len());
        record_delegation_install_fanout_bucket(intent, request.verifier_targets.len());
        Self::prepare_explicit_verifier_push_proof(&request.proof, intent).await?;

        Ok(PreparedDelegationVerifierPush {
            proof: request.proof,
            verifier_targets: request.verifier_targets,
            intent,
        })
    }

    // Normalize explicit verifier push targets with root/signer/registration guards.
    fn normalize_explicit_verifier_push_request_with<F>(
        request: DelegationVerifierProofPushRequest,
        intent: crate::dto::auth::DelegationProofInstallIntent,
        root_pid: Principal,
        mut is_valid_target: F,
    ) -> Result<DelegationVerifierProofPushRequest, Error>
    where
        F: FnMut(Principal) -> bool,
    {
        let signer_pid = request.proof.cert.shard_pid;
        let mut verifier_targets = Vec::new();

        for principal in request.verifier_targets {
            if principal == signer_pid {
                record_delegation_install_normalization_rejected(
                    intent,
                    DelegationInstallNormalizationRejectReason::SignerTarget,
                );
                return Err(Error::invalid(
                    "delegation verifier target must not match signer shard",
                ));
            }
            if principal == root_pid {
                record_delegation_install_normalization_rejected(
                    intent,
                    DelegationInstallNormalizationRejectReason::RootTarget,
                );
                return Err(Error::invalid(
                    "delegation verifier target must not match root canister",
                ));
            }
            if !is_valid_target(principal) {
                record_delegation_install_normalization_rejected(
                    intent,
                    DelegationInstallNormalizationRejectReason::UnregisteredTarget,
                );
                return Err(Error::invalid(format!(
                    "delegation verifier target '{principal}' is not registered"
                )));
            }
            if !verifier_targets.contains(&principal) {
                verifier_targets.push(principal);
            }
        }

        Ok(DelegationVerifierProofPushRequest {
            proof: request.proof,
            verifier_targets,
        })
    }

    // Validate/caches proof dependencies once before explicit fanout.
    async fn prepare_explicit_verifier_push_proof(
        proof: &DelegationProof,
        intent: crate::dto::auth::DelegationProofInstallIntent,
    ) -> Result<(), Error> {
        let root_pid = EnvOps::root_pid().map_err(Error::from)?;
        DelegatedTokenOps::cache_public_keys_for_cert(&proof.cert)
            .await
            .map_err(|err| {
                record_delegation_install_validation_failed(
                    intent,
                    DelegationInstallValidationFailureReason::CacheKeys,
                );
                Self::map_delegation_error(err)
            })?;
        Self::verify_delegation_proof(proof, root_pid).inspect_err(|_| {
            record_delegation_install_validation_failed(
                intent,
                DelegationInstallValidationFailureReason::VerifyProof,
            );
        })?;

        if intent == crate::dto::auth::DelegationProofInstallIntent::Repair {
            Self::ensure_repair_push_proof_is_locally_available(proof)?;
        }

        Ok(())
    }

    // Enforce repair as redistribution of already-installed proof state only.
    fn ensure_repair_push_proof_is_locally_available(proof: &DelegationProof) -> Result<(), Error> {
        Self::ensure_repair_push_proof_is_locally_available_with(proof, |candidate| {
            DelegationStateOps::matching_proof_dto(candidate).map_err(Self::map_delegation_error)
        })
    }

    // Check repair preconditions using an injectable lookup for unit tests.
    fn ensure_repair_push_proof_is_locally_available_with<F>(
        proof: &DelegationProof,
        lookup: F,
    ) -> Result<(), Error>
    where
        F: FnOnce(&DelegationProof) -> Result<Option<DelegationProof>, Error>,
    {
        let Some(stored) = lookup(proof)? else {
            record_delegation_install_validation_failed(
                crate::dto::auth::DelegationProofInstallIntent::Repair,
                DelegationInstallValidationFailureReason::RepairMissingLocal,
            );
            return Err(Error::not_found(
                "delegation repair requires an existing local proof",
            ));
        };

        if stored != *proof {
            record_delegation_install_validation_failed(
                crate::dto::auth::DelegationProofInstallIntent::Repair,
                DelegationInstallValidationFailureReason::RepairLocalMismatch,
            );
            return Err(Error::invalid(
                "delegation repair proof must match the existing local proof",
            ));
        }

        Ok(())
    }

    // Record verifier-cache occupancy/utilization and any eviction caused by install.
    fn record_verifier_cache_install_outcome(
        outcome: crate::ops::storage::auth::DelegationProofUpsertOutcome,
    ) {
        record_verifier_proof_cache_stats(
            outcome.stats.size,
            outcome.stats.active_count,
            outcome.stats.capacity,
            outcome.stats.profile,
            outcome.stats.active_window_secs,
        );

        if let Some(class) = outcome.evicted {
            let class = match class {
                crate::ops::storage::auth::DelegationProofEvictionClass::Cold => {
                    VerifierProofCacheEvictionClass::Cold
                }
                crate::ops::storage::auth::DelegationProofEvictionClass::Active => {
                    VerifierProofCacheEvictionClass::Active
                }
            };
            record_verifier_proof_cache_eviction(class);
        }
    }

    // Derive required verifier targets from audience with strict filtering/validation.
    fn derive_required_verifier_targets_from_aud<F>(
        audience: &[Principal],
        signer_pid: Principal,
        root_pid: Principal,
        mut is_valid_target: F,
    ) -> Result<Vec<Principal>, Error>
    where
        F: FnMut(Principal) -> bool,
    {
        let mut verifier_targets = Vec::new();
        for principal in audience {
            if *principal == signer_pid || *principal == root_pid {
                continue;
            }

            if !is_valid_target(*principal) {
                return Err(Error::invalid(format!(
                    "delegation audience principal '{principal}' is invalid for canonical verifier provisioning"
                )));
            }

            if !verifier_targets.contains(principal) {
                verifier_targets.push(*principal);
            }
        }

        Ok(verifier_targets)
    }

    // Return true when a principal is a provisionable verifier canister target.
    fn is_registered_canister(principal: Principal) -> bool {
        if SubnetRegistryOps::is_registered(principal) {
            return true;
        }

        SubnetDirectoryOps::data()
            .entries
            .iter()
            .any(|(_, pid)| *pid == principal)
    }

    // Check whether a proof can be reused safely for the requested claims.
    fn proof_is_reusable_for_claims(
        proof: &DelegationProof,
        claims: &DelegatedTokenClaims,
        now_secs: u64,
    ) -> bool {
        if now_secs > proof.cert.expires_at {
            return false;
        }

        if claims.shard_pid != proof.cert.shard_pid {
            return false;
        }

        if claims.iat < proof.cert.issued_at || claims.exp > proof.cert.expires_at {
            return false;
        }

        Self::is_principal_subset(&claims.aud, &proof.cert.aud)
            && Self::is_string_subset(&claims.scopes, &proof.cert.scopes)
    }

    // Return true when every principal in `subset` is present in `superset`.
    fn is_principal_subset(
        subset: &[crate::cdk::types::Principal],
        superset: &[crate::cdk::types::Principal],
    ) -> bool {
        subset.iter().all(|item| superset.contains(item))
    }

    // Return true when every scope in `subset` is present in `superset`.
    fn is_string_subset(subset: &[String], superset: &[String]) -> bool {
        subset.iter().all(|item| superset.contains(item))
    }

    fn delegated_session_bootstrap_token_fingerprint(
        token: &DelegatedToken,
    ) -> Result<[u8; 32], Error> {
        let token_bytes = crate::cdk::candid::encode_one(token).map_err(|err| {
            Error::internal(format!("bootstrap token fingerprint encode failed: {err}"))
        })?;
        let mut hasher = Sha256::new();
        hasher.update(Self::SESSION_BOOTSTRAP_TOKEN_FINGERPRINT_DOMAIN);
        hasher.update(token_bytes);
        Ok(hasher.finalize().into())
    }

    // Enforce replay policy for delegated-session bootstrap by token fingerprint.
    fn enforce_bootstrap_replay_policy(
        wallet_caller: Principal,
        delegated_subject: Principal,
        token_fingerprint: [u8; 32],
        issued_at: u64,
    ) -> Result<bool, Error> {
        let Some(binding) =
            DelegationStateOps::delegated_session_bootstrap_binding(token_fingerprint, issued_at)
        else {
            return Ok(false);
        };

        if binding.wallet_pid == wallet_caller && binding.delegated_pid == delegated_subject {
            let active_same_session =
                DelegationStateOps::delegated_session(wallet_caller, issued_at).is_some_and(
                    |session| {
                        session.delegated_pid == delegated_subject
                            && session.bootstrap_token_fingerprint == Some(token_fingerprint)
                    },
                );

            if active_same_session {
                record_session_bootstrap_replay_idempotent();
                return Ok(true);
            }

            record_session_bootstrap_rejected_replay_reused();
            return Err(Error::forbidden(
                "delegated session bootstrap token replay rejected; use a fresh token",
            ));
        }

        record_session_bootstrap_rejected_replay_conflict();
        Err(Error::forbidden(format!(
            "delegated session bootstrap token already bound (wallet={} delegated_subject={})",
            binding.wallet_pid, binding.delegated_pid
        )))
    }

    fn clamp_delegated_session_expires_at(
        now_secs: u64,
        token_expires_at: u64,
        configured_max_ttl_secs: u64,
        requested_ttl_secs: Option<u64>,
    ) -> Result<u64, Error> {
        if configured_max_ttl_secs == 0 {
            return Err(Error::invariant(
                "delegated session configured max ttl_secs must be greater than zero",
            ));
        }

        if let Some(ttl_secs) = requested_ttl_secs
            && ttl_secs == 0
        {
            return Err(Error::invalid(
                "delegated session requested ttl_secs must be greater than zero",
            ));
        }

        let mut expires_at = token_expires_at;
        expires_at = expires_at.min(now_secs.saturating_add(configured_max_ttl_secs));
        if let Some(ttl_secs) = requested_ttl_secs {
            expires_at = expires_at.min(now_secs.saturating_add(ttl_secs));
        }

        if expires_at <= now_secs {
            return Err(Error::forbidden(
                "delegated session bootstrap token is expired",
            ));
        }

        Ok(expires_at)
    }
}

#[cfg(test)]
mod tests;