API Reference

def validate_developer_credential(
    input: dict
) -> ValidationResult[DeveloperCredential]

def validate_agent_credential(
    input: dict
) -> ValidationResult[AgentCredential]

def is_developer_credential(credential: dict) -> bool

def is_agent_credential(credential: dict) -> bool

def sign_credential(
    credential: dict,
    private_key: CryptoKey,
    options: SignOptions
) -> str

def generate_key_pair(
    algorithm: Literal["EdDSA", "ES256"]
) -> tuple[CryptoKey, CryptoKey]

def import_key_from_pem(
    pem: bytes,
    algorithm: Literal["EdDSA", "ES256"],
    private: bool = False
) -> CryptoKey

def export_key_to_pem(
    key: CryptoKey,
    private: bool = False
) -> bytes

def export_public_key(key: CryptoKey) -> dict

def import_public_key(
    jwk: dict,
    algorithm: Literal["EdDSA", "ES256"]
) -> CryptoKey

async def verify_credential(
    token: str,
    options: VerifyOptions
) -> VerifiedCredential

def decode_token(token: str) -> DecodedToken

def get_credential_type(
    token: str
) -> Literal["developer", "agent"] | None

async def verify_agent_trust_chain(
    agent_token: str,
    options: TrustChainOptions
) -> TrustChainResult

def decode_status_list(encoded_list: str) -> bytes

def is_bit_set(bitstring: bytes, index: int) -> bool

async def check_status_list_2021(
    status_list_url: str,
    status_list_index: int
) -> CredentialStatus

def parse_status_entry(
    credential_status: dict | None
) -> StatusEntry | None

class StatusListCache:
    def __init__(self, ttl_ms: int = 300000): ...
    async def fetch(self, url: str) -> bytes: ...
    def clear(self) -> None: ...

async def sign_http_request(
    request: HttpRequestInfo,
    options: HttpSignOptions
) -> HttpSignatureHeaders

async def create_signed_request(
    request: HttpRequestInfo,
    options: HttpSignOptions
) -> dict

def compute_jwk_thumbprint(jwk: dict) -> str

def compute_content_digest(body: bytes) -> str

def generate_nonce() -> str

async def verify_http_signature(
    request: IncomingHttpRequest,
    options: HttpVerifyOptions
) -> HttpVerificationResult

async def fetch_key_directory(url: str) -> KeyDirectory

def find_key_by_thumbprint(
    directory: KeyDirectory,
    thumbprint: str
) -> dict | None

def create_default_key_resolver() -> Callable

def verify_content_digest(body: bytes, header: str) -> bool

def generate_key_directory(
    options: GenerateDirectoryOptions
) -> dict

async def sign_directory_response(
    directory: dict,
    options: SignDirectoryOptions
) -> SignedDirectoryResponse

async def generate_web_bot_auth_setup(
    base_url: str | None = None
) -> dict

class InMemoryJtiStore:
    def __init__(self, ttl_seconds: int = 300): ...
    async def has(self, jti: str) -> bool: ...
    async def add(self, jti: str, exp: int) -> None: ...
    async def cleanup(self) -> None: ...

class ReplayDetectedError(BelticError):
    jti: str
    first_seen: datetime

def compute_content_hash(
    content: bytes,
    algorithm: ContentHashAlgorithm = "sha-256"
) -> bytes

def verify_content_hash(
    content: bytes,
    hash: bytes,
    algorithm: ContentHashAlgorithm = "sha-256"
) -> bool

def create_hash_claim(
    content: bytes,
    algorithm: ContentHashAlgorithm = "sha-256"
) -> dict

def verify_hash_claim(content: bytes, claim: dict) -> bool

class CredentialChain:
    def __init__(self): ...
    def add(self, credential: dict, token: str) -> ChainEntry: ...
    def get_proof(self) -> ChainProof: ...
    def verify(self) -> bool: ...
    def __len__(self) -> int: ...

def compute_chain_hash(
    credential_hash: bytes,
    previous_hash: bytes | None
) -> bytes

def verify_chain_integrity(entries: list[ChainEntry]) -> bool

class MultiSigCredential:
    def __init__(self, credential: dict): ...
    async def add_signature(
        self,
        private_key: CryptoKey,
        signer_id: str,
        options: SignOptions
    ) -> None: ...
    def get_signatures(self) -> list[SignatureEntry]: ...
    async def verify_all(
        self,
        key_resolver: MultiSigKeyResolver
    ) -> MultiSigVerificationResult: ...

async def add_signature(
    credential: MultiSigCredential,
    private_key: CryptoKey,
    signer_id: str,
    options: SignOptions
) -> None

async def verify_multi_signatures(
    credential: MultiSigCredential,
    key_resolver: MultiSigKeyResolver
) -> MultiSigVerificationResult

class AuditLogger:
    def __init__(self): ...
    def add_handler(self, handler: AuditHandler) -> None: ...
    def log(self, event: AuditEvent) -> None: ...

@dataclass
class AuditEvent:
    type: AuditEventType
    timestamp: datetime
    credential_id: str | None
    action: str
    actor: str | None
    details: dict

class AuditEventType(Enum):
    CREDENTIAL_ISSUED = "credential_issued"
    CREDENTIAL_VERIFIED = "credential_verified"
    CREDENTIAL_REVOKED = "credential_revoked"
    SIGNATURE_CREATED = "signature_created"
    SIGNATURE_VERIFIED = "signature_verified"
    TRUST_CHAIN_VERIFIED = "trust_chain_verified"
    POLICY_VIOLATION = "policy_violation"

class ConsoleAuditHandler(AuditHandler):
    def handle(self, event: AuditEvent) -> None: ...

class FileAuditHandler(AuditHandler):
    def __init__(self, path: str): ...
    def handle(self, event: AuditEvent) -> None: ...

class InMemoryAuditHandler(AuditHandler):
    events: list[AuditEvent]
    def handle(self, event: AuditEvent) -> None: ...
    def clear(self) -> None: ...

class LocalSigner(CloudSigner):
    def __init__(
        self,
        private_key: CryptoKey,
        algorithm: Literal["EdDSA", "ES256"]
    ): ...
    async def sign(self, data: bytes) -> bytes: ...
    def get_info(self) -> SignerInfo: ...

class CloudSigner(ABC):
    @abstractmethod
    async def sign(self, data: bytes) -> bytes: ...
    @abstractmethod
    def get_info(self) -> SignerInfo: ...

async def create_sd_jwt(
    credential: dict,
    private_key: CryptoKey,
    options: CreateSdJwtOptions
) -> SDJwt

def create_presentation(
    sd_jwt: SDJwt,
    disclosed_paths: list[str]
) -> str

async def verify_sd_jwt(
    presentation: str,
    options: VerifySdJwtOptions
) -> SdJwtVerificationResult

def create_disclosure(
    salt: str,
    claim_name: str,
    claim_value: Any
) -> Disclosure

def decode_disclosure(encoded: str) -> Disclosure

class BelticError(Exception):
    code: str
    message: str

class ValidationError(BelticError):
    issues: list[ValidationErrorDetail]
    
    def format(self) -> str: ...
    def by_path(self) -> dict[str, list[ValidationErrorDetail]]: ...

class SignatureError(BelticError):
    step: Literal["PARSE", "KEY_RESOLUTION", "SIGNATURE", "CLAIMS", "SCHEMA"]
    code: str

class TrustChainError(BelticError):
    step: str
    agent_credential: dict | None
    developer_credential: dict | None

class PolicyViolationError(BelticError):
    violations: list[PolicyViolation]
    
    def has_type(self, violation_type: str) -> bool: ...

@dataclass
class SignOptions:
    alg: Literal["EdDSA", "ES256"]
    issuer_did: str
    subject_did: str
    key_id: str | None = None
    audience: str | None = None

@dataclass
class VerifyOptions:
    key_resolver: Callable[[KeyResolverInput], Awaitable[CryptoKey]]
    expected_issuer: str | None = None
    expected_audience: str | None = None
    allowed_algorithms: list[str] | None = None

@dataclass
class TrustChainOptions:
    key_resolver: Callable[[KeyResolverInput], Awaitable[CryptoKey]]
    fetch_developer_credential: Callable[[str], Awaitable[str]]
    check_status: Callable[[StatusCheckInput], Awaitable[CredentialStatus]] | None = None
    policy: TrustPolicy | None = None

@dataclass
class TrustPolicy:
    min_kyb_tier: str | None = None
    min_prompt_injection_score: int | None = None
    min_pii_leakage_score: int | None = None
    min_tool_abuse_score: int | None = None
    min_harm_refusal_score: int | None = None
    min_verification_level: str | None = None
    prohibited_data_categories: list[str] | None = None

@dataclass
class HttpRequestInfo:
    method: str
    url: str
    headers: dict[str, str] = field(default_factory=dict)
    body: bytes | None = None

@dataclass
class HttpSignOptions:
    private_key: CryptoKey
    key_id: str
    key_directory_url: str
    components: list[str] | None = None
    expires_in: int = 60