oas-lineage · error

#[derive(Debug, Error)]
pub enum LineageError {
    /// A non-root entity is missing its required lineage section.
    ///
    /// Per OAS Spec §8.3 rule 1, every non-root entity MUST have lineage.
    #[error("non-root entity missing required lineage section (DID: {did})")]
    MissingLineage {
        /// The DID of the entity missing lineage.
        did: String,
    },

    /// The `humanRootChain` array is empty.
    #[error("human root chain is empty for entity {did}")]
    EmptyChain {
        /// The DID of the entity with an empty chain.
        did: String,
    },

    /// The lineage chain does not terminate at an HMR, MHR, or ENR entity.
    ///
    /// Per OAS Spec §8.3 rule 2.
    #[error("chain does not terminate at human root: last DID is '{last_did}'; expected kind 'hmr', 'mhr', or 'enr'")]
    ChainNotTerminatingAtRoot {
        /// The last DID in the chain (which should be an HMR, MHR, or ENR).
        last_did: String,
    },

    /// The generation field does not match `humanRootChain.len() - 1`.
    ///
    /// Per OAS Spec §8.3 rule 3.
    #[error("generation {generation} does not match chain length minus one ({expected})")]
    GenerationMismatch {
        /// The declared generation value.
        generation: u32,
        /// The expected value (`humanRootChain.len() - 1`).
        expected: usize,
    },

    /// The lineage chain exceeds the configured maximum generation depth.
    ///
    /// Per OAS Spec §8.3 rule 6.
    #[error("generation depth {depth} exceeds maximum allowed depth {max_depth}")]
    ChainTooDeep {
        /// The actual generation depth.
        depth: u32,
        /// The configured maximum.
        max_depth: u32,
    },

    /// A parent document could not be resolved during chain verification.
    ///
    /// Per OAS Spec Appendix C, step 6.
    #[error("cannot resolve parent document '{parent_did}': {reason}")]
    ResolutionFailed {
        /// The parent DID that failed to resolve.
        parent_did: String,
        /// The reason resolution failed.
        reason: String,
    },

    /// A parent entity in the chain has been revoked.
    ///
    /// Per OAS Spec §8.3 rule 5 (revocation cascades).
    #[error("parent entity is revoked: {parent_did}")]
    ParentRevoked {
        /// The revoked parent DID.
        parent_did: String,
    },

    /// A parent document's signature is invalid.
    #[error("parent document signature invalid for '{parent_did}': {reason}")]
    ParentSignatureInvalid {
        /// The parent DID with the invalid signature.
        parent_did: String,
        /// Details of the signature failure.
        reason: String,
    },

    /// The terminal root is not authorized by verifier-controlled policy.
    #[error("root '{root_did}' is not trusted by verifier policy: {reason}")]
    UntrustedRoot {
        /// The untrusted root DID.
        root_did: String,
        /// Details of the trust-anchor failure.
        reason: String,
    },

    /// A document is revoked.
    #[error("document is revoked: {did}")]
    DocumentRevoked {
        /// DID of the revoked document.
        did: String,
    },

    /// A document is outside its configured validity window.
    #[error("document is not currently valid: {did}")]
    DocumentInactive {
        /// DID of the inactive document.
        did: String,
    },

    /// The derivation proof type is not `AgentLineageProof2025`.
    #[error("unknown proof type '{found}'; expected 'AgentLineageProof2025'")]
    UnknownProofType {
        /// The unexpected proof type.
        found: String,
    },

    /// The proof's `parentDid` does not match the expected parent in the chain.
    #[error("proof parent DID mismatch: proof contains '{proof_parent}' but chain expects '{chain_parent}'")]
    ProofParentMismatch {
        /// The parentDid from the proof.
        proof_parent: String,
        /// The expected parent from the chain.
        chain_parent: String,
    },

    /// The proof's `childDid` does not match the expected child in the chain.
    #[error("proof child DID mismatch: proof contains '{proof_child}' but chain expects '{chain_child}'")]
    ProofChildMismatch {
        /// The childDid from the proof.
        proof_child: String,
        /// The expected child from the chain.
        chain_child: String,
    },

    /// The Ed25519 signature on a lineage proof is invalid.
    #[error("lineage proof signature invalid at generation {generation}: {reason}")]
    ProofSignatureInvalid {
        /// The generation index where verification failed.
        generation: usize,
        /// Details of the signature failure.
        reason: String,
    },

    /// A legacy proof omits mandatory signed security bindings.
    #[error("legacy lineage proof is non-authorizing: {reason}")]
    LegacyInsecureProof {
        /// The missing or insecure legacy binding.
        reason: String,
    },

    /// The proof algorithm is not supported by the strict verifier.
    #[error("unsupported lineage proof algorithm '{found}'")]
    UnsupportedProofAlgorithm {
        /// The unsupported algorithm.
        found: String,
    },

    /// The canonicalization profile is not supported by the strict verifier.
    #[error("unsupported lineage canonicalization profile '{found}'")]
    UnsupportedCanonicalization {
        /// The unsupported canonicalization profile.
        found: String,
    },

    /// The proof purpose is not supported by the strict verifier.
    #[error("unsupported lineage proof purpose '{found}'")]
    UnsupportedProofPurpose {
        /// The unsupported proof purpose.
        found: String,
    },

    /// A lineage proof key is not the referenced authorized parent key.
    #[error(
        "lineage proof key does not match parent document '{parent_did}' method '{verification_method}'"
    )]
    ParentKeyMismatch {
        /// The parent DID.
        parent_did: String,
        /// Verification method referenced by the proof.
        verification_method: String,
    },

    /// A lineage proof does not bind the child's verification key.
    #[error(
        "lineage proof child key does not match child document '{child_did}' method '{verification_method}'"
    )]
    ChildKeyMismatch {
        /// The child DID.
        child_did: String,
        /// Verification method referenced by the proof.
        verification_method: String,
    },

    /// A lineage proof does not bind the resolved parent document state.
    #[error("lineage proof parent document binding mismatch for '{parent_did}': {reason}")]
    ParentDocumentMismatch {
        /// The parent DID.
        parent_did: String,
        /// Details of the mismatch.
        reason: String,
    },

    /// A verification method is not authorized for lineage delegation.
    #[error(
        "verification method '{verification_method}' is not authorized for lineage delegation by '{parent_did}'"
    )]
    InvalidKeyPurpose {
        /// The parent DID.
        parent_did: String,
        /// Verification method lacking the required relationship.
        verification_method: String,
    },

    /// The declared lineage contains a repeated DID.
    #[error("lineage chain contains a cycle at '{did}'")]
    ChainCycle {
        /// The repeated DID.
        did: String,
    },

    /// Resolved lineage metadata does not continue the declared chain.
    #[error("lineage chain continuity failed at '{did}': {reason}")]
    ChainContinuity {
        /// DID at which continuity failed.
        did: String,
        /// Details of the discontinuity.
        reason: String,
    },

    /// The total timeout for lineage verification was exceeded.
    ///
    /// Per OAS Spec §8.3 rule 7.
    #[error("lineage verification total timeout exceeded after {elapsed_secs:.1}s (limit: {limit_secs}s)")]
    TotalTimeout {
        /// Elapsed time in seconds.
        elapsed_secs: f64,
        /// Configured limit in seconds.
        limit_secs: f64,
    },

    /// A non-root entity's lineage section is missing its derivation proof.
    #[error("derivation proof is missing for entity '{did}'")]
    MissingDerivationProof {
        /// The DID of the entity without a proof.
        did: String,
    },

    /// The parent's public key referenced by the proof was not found in
    /// the parent's verification methods.
    #[error("parent public key not found in parent document '{parent_did}'")]
    ParentKeyNotFound {
        /// The parent DID.
        parent_did: String,
    },

    /// An underlying cryptographic error occurred.
    #[error("cryptographic error: {0}")]
    Crypto(#[from] oas_crypto::CryptoError),
}