"""ACT-specific exception types.

All exceptions defined in this module correspond to specific failure
modes in the Agent Compact Token lifecycle as defined in
draft-nennemann-act-00.

Reference: ACT §8 (Verification Procedure), §6 (Delegation Chain),
§7 (DAG Structure), §10 (Audit Ledger Interface).
"""

from __future__ import annotations


class ACTError(Exception):
    """Base exception for all ACT operations.

    All ACT-specific exceptions inherit from this class, allowing
    callers to catch any ACT error with a single except clause.

    Reference: draft-nennemann-act-00.
    """


class ACTValidationError(ACTError):
    """Malformed token structure or invalid field values.

    Raised when an ACT fails structural validation: missing required
    claims, invalid claim types, unsupported algorithm ("none", HS*),
    or invalid typ header.

    Reference: ACT §4 (Token Format), §8.1 steps 2-3, 11.
    """


class ACTSignatureError(ACTError):
    """Signature verification failed.

    Raised when a JWS signature cannot be verified against the
    resolved public key, or when a Phase 2 token is signed by the
    wrong key (e.g., iss key instead of sub key).

    Reference: ACT §8.1 step 5, §8.2 step 17.
    """


class ACTExpiredError(ACTError):
    """Token has expired.

    Raised when the current time exceeds exp + clock_skew_tolerance.
    The default clock skew tolerance is 300 seconds.

    Reference: ACT §8.1 step 6.
    """


class ACTAudienceMismatchError(ACTError):
    """The aud claim does not contain the verifier's identity.

    Reference: ACT §8.1 step 8.
    """


class ACTCapabilityError(ACTError):
    """No matching capability or exec_act not in cap actions.

    Raised when exec_act does not match any cap[].action value,
    or when a requested action is not authorized by any capability.

    Reference: ACT §8.2 step 13, §4.2.2 (cap).
    """


class ACTDelegationError(ACTError):
    """Delegation chain is invalid.

    Raised when delegation chain verification fails: depth > max_depth,
    chain length != depth, or any chain entry signature fails.

    Reference: ACT §6 (Delegation Chain), §8.1 step 12.
    """


class ACTDAGError(ACTError):
    """DAG validation failed.

    Raised on cycle detection, missing parent jti, temporal ordering
    violations, or traversal limit exceeded.

    Reference: ACT §7 (DAG Structure and Causal Ordering).
    """


class ACTPhaseError(ACTError):
    """Wrong phase for the requested operation.

    Raised when a mandate is used where a record is expected, or
    vice versa. Phase is determined by the presence of exec_act.

    Reference: ACT §3 (Lifecycle), §8.
    """


class ACTKeyResolutionError(ACTError):
    """Cannot resolve kid to a public key.

    Raised when the kid in the JOSE header cannot be resolved to a
    public key via any configured trust tier (pre-shared, PKI, DID).

    Reference: ACT §5 (Trust Model), §8.1 step 4.
    """


class ACTLedgerImmutabilityError(ACTError):
    """Attempt to modify or delete a ledger record.

    The audit ledger enforces append-only semantics. Once appended,
    a record cannot be modified or deleted.

    Reference: ACT §10 (Audit Ledger Interface).
    """


class ACTPrivilegeEscalationError(ACTError):
    """Delegated capability exceeds parent capability.

    Raised when a delegated ACT contains actions not present in the
    parent ACT's cap array, or when constraints are less restrictive
    than the parent's constraints.

    Reference: ACT §6.2 (Privilege Reduction Requirements).
    """