132 lines
3.5 KiB
Python
132 lines
3.5 KiB
Python
"""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).
|
|
"""
|