attestix 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,580 @@
+interface AttestixOptions {
+    /** Base URL of the Attestix API server */
+    baseUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+interface Identity {
+    agent_id: string;
+    name: string;
+    type: string;
+    did?: string;
+    capabilities?: string[];
+    metadata?: Record<string, unknown>;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateIdentityParams {
+    name: string;
+    type: string;
+    capabilities?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface ListIdentitiesParams {
+    skip?: number;
+    limit?: number;
+    type?: string;
+    status?: string;
+}
+interface PurgeResult {
+    agent_id: string;
+    deleted_counts: Record<string, number>;
+    message: string;
+}
+interface Credential {
+    credential_id: string;
+    issuer: string;
+    subject: string;
+    type: string;
+    claims: Record<string, unknown>;
+    status: string;
+    issued_at: string;
+    expires_at?: string;
+    revoked_at?: string;
+    revocation_reason?: string;
+}
+interface IssueCredentialParams {
+    issuer: string;
+    subject: string;
+    type: string;
+    claims: Record<string, unknown>;
+    expires_in_days?: number;
+}
+interface ListCredentialsParams {
+    skip?: number;
+    limit?: number;
+    issuer?: string;
+    subject?: string;
+    type?: string;
+    status?: string;
+}
+interface Presentation {
+    presentation_id: string;
+    holder: string;
+    credential_ids: string[];
+    verifiable_credentials: Record<string, unknown>[];
+    created_at: string;
+}
+interface CreatePresentationParams {
+    holder: string;
+    credential_ids: string[];
+}
+interface ComplianceProfile {
+    profile_id: string;
+    name: string;
+    framework: string;
+    requirements: ComplianceRequirement[];
+    agent_id?: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+interface ComplianceRequirement {
+    requirement_id: string;
+    name: string;
+    description: string;
+    category: string;
+    status: string;
+}
+interface CreateComplianceProfileParams {
+    name: string;
+    framework: string;
+    agent_id?: string;
+    requirements?: ComplianceRequirement[];
+}
+interface ComplianceStatus {
+    profile_id: string;
+    overall_status: string;
+    completion_percentage: number;
+    requirements_met: number;
+    requirements_total: number;
+    last_assessed: string;
+}
+interface Assessment {
+    assessment_id: string;
+    profile_id: string;
+    requirement_id: string;
+    status: string;
+    evidence?: string;
+    assessed_at: string;
+    assessed_by: string;
+}
+interface RecordAssessmentParams {
+    profile_id: string;
+    requirement_id: string;
+    status: string;
+    evidence?: string;
+    assessed_by: string;
+}
+interface Declaration {
+    declaration_id: string;
+    profile_id: string;
+    framework: string;
+    content: string;
+    generated_at: string;
+}
+interface GenerateDeclarationParams {
+    profile_id: string;
+    format?: string;
+}
+interface ReputationScore {
+    agent_id: string;
+    overall_score: number;
+    interaction_count: number;
+    positive_count: number;
+    negative_count: number;
+    categories?: Record<string, number>;
+    last_updated: string;
+}
+interface RecordInteractionParams {
+    agent_id: string;
+    counterparty_id: string;
+    interaction_type: string;
+    outcome: string;
+    score?: number;
+    metadata?: Record<string, unknown>;
+}
+interface QueryReputationParams {
+    min_score?: number;
+    max_score?: number;
+    min_interactions?: number;
+    skip?: number;
+    limit?: number;
+}
+interface ProvenanceEntry {
+    entry_id: string;
+    agent_id: string;
+    type: string;
+    data: Record<string, unknown>;
+    recorded_at: string;
+}
+interface RecordTrainingDataParams {
+    agent_id: string;
+    dataset_name: string;
+    dataset_version: string;
+    source: string;
+    license?: string;
+    metadata?: Record<string, unknown>;
+}
+interface RecordModelLineageParams {
+    agent_id: string;
+    model_name: string;
+    model_version: string;
+    parent_model?: string;
+    training_data_ids?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface AuditEntry {
+    entry_id: string;
+    agent_id: string;
+    action: string;
+    details: Record<string, unknown>;
+    timestamp: string;
+    anchor_id?: string;
+}
+interface LogActionParams {
+    agent_id: string;
+    action: string;
+    details: Record<string, unknown>;
+}
+interface AuditTrailParams {
+    agent_id?: string;
+    action?: string;
+    start_time?: string;
+    end_time?: string;
+    skip?: number;
+    limit?: number;
+}
+interface Delegation {
+    delegation_id: string;
+    delegator: string;
+    delegate: string;
+    scope: string[];
+    constraints?: Record<string, unknown>;
+    token: string;
+    status: string;
+    created_at: string;
+    expires_at?: string;
+}
+interface CreateDelegationParams {
+    delegator: string;
+    delegate: string;
+    scope: string[];
+    constraints?: Record<string, unknown>;
+    expires_in_hours?: number;
+}
+interface ListDelegationsParams {
+    delegator?: string;
+    delegate?: string;
+    status?: string;
+    skip?: number;
+    limit?: number;
+}
+interface DIDDocument {
+    id: string;
+    type: string;
+    controller?: string;
+    verification_method?: VerificationMethod[];
+    authentication?: string[];
+    assertion_method?: string[];
+    created: string;
+}
+interface VerificationMethod {
+    id: string;
+    type: string;
+    controller: string;
+    public_key_multibase?: string;
+    public_key_jwk?: Record<string, unknown>;
+}
+interface AnchorReceipt {
+    anchor_id: string;
+    type: string;
+    target_id: string;
+    chain: string;
+    transaction_hash?: string;
+    block_number?: number;
+    status: string;
+    anchored_at: string;
+}
+interface AnchorVerification {
+    anchor_id: string;
+    verified: boolean;
+    chain: string;
+    transaction_hash?: string;
+    block_number?: number;
+    data_integrity: boolean;
+    verified_at: string;
+}
+interface CostEstimate {
+    chain: string;
+    estimated_gas: number;
+    estimated_cost_usd: number;
+    currency: string;
+}
+interface VerificationResult {
+    valid: boolean;
+    checks: VerificationCheck[];
+    verified_at: string;
+}
+interface VerificationCheck {
+    name: string;
+    passed: boolean;
+    message?: string;
+}
+interface ErrorResponse {
+    detail: string;
+    status_code: number;
+}
+
+declare class AttestixClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(options: AttestixOptions);
+    createIdentity(params: CreateIdentityParams): Promise<Identity>;
+    getIdentity(agentId: string): Promise<Identity>;
+    listIdentities(params?: ListIdentitiesParams): Promise<Identity[]>;
+    verifyIdentity(agentId: string): Promise<VerificationResult>;
+    translateIdentity(agentId: string, format: string): Promise<Record<string, unknown>>;
+    revokeIdentity(agentId: string, reason?: string): Promise<Identity>;
+    purgeAgentData(agentId: string): Promise<PurgeResult>;
+    issueCredential(params: IssueCredentialParams): Promise<Credential>;
+    getCredential(credentialId: string): Promise<Credential>;
+    listCredentials(params?: ListCredentialsParams): Promise<Credential[]>;
+    verifyCredential(credentialId: string): Promise<VerificationResult>;
+    verifyExternalCredential(credential: Record<string, unknown>): Promise<VerificationResult>;
+    revokeCredential(credentialId: string, reason?: string): Promise<Credential>;
+    createPresentation(params: CreatePresentationParams): Promise<Presentation>;
+    createComplianceProfile(params: CreateComplianceProfileParams): Promise<ComplianceProfile>;
+    getComplianceProfile(profileId: string): Promise<ComplianceProfile>;
+    listComplianceProfiles(): Promise<ComplianceProfile[]>;
+    getComplianceStatus(profileId: string): Promise<ComplianceStatus>;
+    recordAssessment(params: RecordAssessmentParams): Promise<Assessment>;
+    generateDeclaration(params: GenerateDeclarationParams): Promise<Declaration>;
+    recordInteraction(params: RecordInteractionParams): Promise<void>;
+    getReputation(agentId: string): Promise<ReputationScore>;
+    queryReputation(params?: QueryReputationParams): Promise<ReputationScore[]>;
+    recordTrainingData(params: RecordTrainingDataParams): Promise<ProvenanceEntry>;
+    recordModelLineage(params: RecordModelLineageParams): Promise<ProvenanceEntry>;
+    logAction(params: LogActionParams): Promise<AuditEntry>;
+    getProvenance(agentId: string): Promise<ProvenanceEntry[]>;
+    getAuditTrail(params?: AuditTrailParams): Promise<AuditEntry[]>;
+    createDelegation(params: CreateDelegationParams): Promise<Delegation>;
+    listDelegations(params?: ListDelegationsParams): Promise<Delegation[]>;
+    verifyDelegation(token: string): Promise<VerificationResult>;
+    revokeDelegation(delegationId: string): Promise<void>;
+    createDidKey(): Promise<DIDDocument>;
+    createDidWeb(domain: string): Promise<DIDDocument>;
+    resolveDid(did: string): Promise<DIDDocument>;
+    anchorIdentity(agentId: string): Promise<AnchorReceipt>;
+    anchorCredential(credentialId: string): Promise<AnchorReceipt>;
+    anchorAuditBatch(entryIds?: string[]): Promise<AnchorReceipt>;
+    verifyAnchor(anchorId: string): Promise<AnchorVerification>;
+    getAnchorStatus(anchorId: string): Promise<AnchorReceipt>;
+    estimateAnchorCost(): Promise<CostEstimate>;
+    private request;
+    private requestWithRetry;
+    private handleErrorResponse;
+    private buildQuery;
+    private sleep;
+}
+
+/**
+ * Canonical JSON serialization matching the Python Attestix engine's
+ * `auth.crypto.canonicalize_json`.
+ *
+ * This is NOT strict RFC 8785 — it is byte-for-byte compatible with what the
+ * Python engine actually produces:
+ *   json.dumps(normalize(obj), sort_keys=True, separators=(",",":"),
+ *              ensure_ascii=False).encode("utf-8")
+ *
+ * Rules (see SPEC.md §3):
+ *  - object keys sorted by Unicode code point (Python default string sort)
+ *  - compact separators: "," and ":"
+ *  - non-ASCII emitted as raw UTF-8 (NOT \uXXXX escapes)
+ *  - every string NFC-normalized
+ *  - whole-valued floats coerced to integers (1.0 -> 1)
+ *  - control chars U+0000–U+001F escaped as \b \t \n \f \r or \u00xx (lowercase)
+ *  - "/", "<", ">", "&" NOT escaped; U+007F emitted raw
+ *
+ * Numbers that would serialize differently in JS vs Python (exponential
+ * notation, signed zero, NaN/Infinity) are rejected up front with
+ * {@link JcsUnsupportedValueError} so a verifier never produces silently-wrong
+ * canonical bytes. These never occur in real Attestix payloads.
+ */
+/** Thrown when a value cannot be canonicalized to match the Python engine. */
+declare class JcsUnsupportedValueError extends Error {
+    constructor(message: string);
+}
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Serialize a JSON value to its canonical string form (matching Python).
+ * Use {@link canonicalize} to get the UTF-8 bytes for signing/verification.
+ */
+declare function canonicalizeToString(value: JsonValue): string;
+/**
+ * Produce canonical UTF-8 bytes for a JSON value, byte-identical to the Python
+ * engine's `canonicalize_json`.
+ */
+declare function canonicalize(value: JsonValue): Uint8Array;
+
+/**
+ * base64url decoding that accepts both the url-safe (`-_`) and standard
+ * (`+/`) alphabets, with or without `=` padding. The Python engine emits
+ * url-safe WITH padding (base64.urlsafe_b64encode); JWS emits url-safe
+ * WITHOUT padding. Both are accepted.
+ */
+declare function base64urlDecode(input: string): Uint8Array;
+
+/**
+ * did:key encode/decode for Ed25519 keys, matching the Python engine's
+ * `auth.crypto.public_key_to_did_key` / `did_key_to_public_key`.
+ *
+ *   did:key:z<base58btc(0xED01 || raw_pubkey_32)>
+ *
+ * Multibase prefix: literal 'z' (base58btc). Multicodec prefix for
+ * ed25519-pub: bytes 0xED 0x01.
+ */
+/** Multicodec prefix for Ed25519 public key (varint 0xed01). */
+declare const ED25519_MULTICODEC_PREFIX: Uint8Array<ArrayBuffer>;
+/** Encode bytes as base58btc (Bitcoin alphabet), preserving leading zeros. */
+declare function base58btcEncode(bytes: Uint8Array): string;
+/** Decode a base58btc string to bytes, preserving leading '1' -> 0x00. */
+declare function base58btcDecode(str: string): Uint8Array;
+/** Encode a raw 32-byte Ed25519 public key as a did:key identifier. */
+declare function publicKeyToDidKey(rawPublicKey: Uint8Array): string;
+/**
+ * Extract the raw 32-byte Ed25519 public key from a did:key identifier.
+ * Throws if the DID is not a did:key, lacks the 'z' multibase prefix, or does
+ * not carry the Ed25519 multicodec prefix (0xED01).
+ */
+declare function didKeyToPublicKey(did: string): Uint8Array;
+/**
+ * Resolve the issuer DID from a proof's verificationMethod (the part before
+ * '#'), matching the Python engine's `vm.split("#")[0]`.
+ */
+declare function didFromVerificationMethod(vm: string): string;
+
+/**
+ * Ed25519 signature verification (RFC 8032 / PureEdDSA), Node + browser
+ * compatible, backed by the audited @noble/curves implementation.
+ */
+/**
+ * Verify an Ed25519 signature.
+ *
+ * @param signature 64-byte raw Ed25519 signature.
+ * @param message   the exact bytes that were signed.
+ * @param publicKey 32-byte raw Ed25519 public key.
+ * @returns true iff the signature is valid; never throws on bad input — a
+ *          malformed signature/key is treated as a failed verification.
+ */
+declare function verifyEd25519(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
+
+/**
+ * Offline verification of Attestix W3C Verifiable Credentials and Verifiable
+ * Presentations. Reproduces the Python engine's signing rules (see SPEC.md
+ * §5/§6): the signature covers the credential object with `proof` and
+ * `credentialStatus` removed, canonicalized via the JCS rules, verified with
+ * the issuer's did:key Ed25519 public key.
+ */
+/** Per-check booleans mirroring the Python verifier's `checks` object. */
+interface CredentialChecks {
+    structure_valid: boolean;
+    signature_valid: boolean;
+    not_expired: boolean;
+    /** Revocation cannot be confirmed offline; true unless embedded status says revoked. */
+    not_revoked: boolean;
+}
+interface VerifyCredentialResult {
+    valid: boolean;
+    reason?: string;
+    checks: CredentialChecks;
+    issuer?: string;
+    subject?: string;
+    type?: string[];
+}
+interface VerifyCredentialOptions {
+    /** Override "now" for expiry checks (ms epoch). Defaults to Date.now(). */
+    now?: number;
+    /** If false, skip the expirationDate check. Default true. */
+    checkExpiry?: boolean;
+}
+/**
+ * Verify a single VC's Ed25519 proof, structure, expiry, and embedded
+ * revocation status — without contacting the Attestix API.
+ */
+declare function verifyCredential(credential: unknown, options?: VerifyCredentialOptions): VerifyCredentialResult;
+interface VerifyPresentationResult {
+    valid: boolean;
+    reason?: string;
+    holder?: string;
+    vpSignatureValid: boolean;
+    credentialCount: number;
+    credentialResults: VerifyCredentialResult[];
+}
+/**
+ * Verify a Verifiable Presentation: the holder's proof (signed payload is the
+ * VP minus `proof` only) plus every embedded credential.
+ */
+declare function verifyPresentation(presentation: unknown, options?: VerifyCredentialOptions): VerifyPresentationResult;
+
+/**
+ * Offline verification of Attestix UCAN-style delegation chains.
+ *
+ * Delegations are EdDSA-signed JWTs (see SPEC.md §7). A token is a compact JWS:
+ *   base64url(header) "." base64url(payload) "." base64url(signature)
+ * The signature is Ed25519 over the ASCII signing input
+ * `b64url(header).b64url(payload)`, verified with the `iss` did:key's public
+ * key. The proof chain lives in the `prf` claim (a list of parent JWT strings).
+ *
+ * This reproduces `DelegationService.verify_delegation` (recursive prf
+ * verification + cycle detection + expiry) AND the capability-attenuation rule
+ * that the Python engine enforces at creation time
+ * (`create_delegation`): a child's `att` must be a subset of every parent's
+ * `att`. An offline verifier re-checks attenuation because it cannot trust that
+ * the creation-time guard ran.
+ */
+interface DelegationClaims {
+    iss: string;
+    aud?: string;
+    sub?: string;
+    delegator?: string;
+    iat?: number;
+    nbf?: number;
+    exp?: number;
+    jti?: string;
+    att: string[];
+    prf: string[];
+    typ?: string;
+    [key: string]: unknown;
+}
+interface DelegationLinkResult {
+    jti?: string;
+    issuer: string;
+    delegator?: string;
+    audience?: string;
+    capabilities: string[];
+    signatureValid: boolean;
+    expired: boolean;
+    notYetValid: boolean;
+}
+interface VerifyDelegationResult {
+    valid: boolean;
+    reason?: string;
+    /** Per-link results, leaf first (matching the order the chain is walked). */
+    links: DelegationLinkResult[];
+    /** The capabilities held by the leaf (effective granted set). */
+    capabilities: string[];
+}
+interface VerifyDelegationOptions {
+    /** Override "now" in unix seconds. Defaults to current time. */
+    now?: number;
+    /** Clock skew tolerance in seconds for exp/nbf. Default 0. */
+    clockToleranceSeconds?: number;
+}
+/**
+ * Verify a delegation token and its full proof chain.
+ *
+ * @param token Either a single leaf JWT string (its `prf` chain is walked
+ *   internally) or an array of JWT strings ordered leaf..root. When an array
+ *   is given, the leaf's `prf` linkage is still validated against the provided
+ *   parents.
+ */
+declare function verifyDelegationChain(token: string | string[], options?: VerifyDelegationOptions): VerifyDelegationResult;
+/** Decode a delegation JWT's claims WITHOUT verifying the signature. */
+declare function decodeDelegationUnsafe(token: string): DelegationClaims;
+
+/**
+ * Base error class for all Attestix SDK errors.
+ */
+declare class AttestixError extends Error {
+    readonly statusCode: number;
+    readonly detail: string;
+    constructor(message: string, statusCode: number, detail?: string);
+}
+/**
+ * Thrown when the API returns a 401 Unauthorized response.
+ * Indicates an invalid or missing API key.
+ */
+declare class AttestixAuthError extends AttestixError {
+    constructor(detail?: string);
+}
+/**
+ * Thrown when the API returns a 404 Not Found response.
+ * The requested resource does not exist.
+ */
+declare class AttestixNotFoundError extends AttestixError {
+    constructor(detail?: string);
+}
+/**
+ * Thrown when the API returns a 400 Bad Request response.
+ * The request parameters failed validation.
+ */
+declare class AttestixValidationError extends AttestixError {
+    constructor(detail?: string);
+}
+/**
+ * Thrown when the API returns a 429 Too Many Requests response.
+ * The client has exceeded the rate limit.
+ */
+declare class AttestixRateLimitError extends AttestixError {
+    readonly retryAfter: number | null;
+    constructor(detail?: string, retryAfter?: number);
+}
+
+export { type AnchorReceipt, type AnchorVerification, type Assessment, AttestixAuthError, AttestixClient, AttestixError, AttestixNotFoundError, type AttestixOptions, AttestixRateLimitError, AttestixValidationError, type AuditEntry, type AuditTrailParams, type ComplianceProfile, type ComplianceRequirement, type ComplianceStatus, type CostEstimate, type CreateComplianceProfileParams, type CreateDelegationParams, type CreateIdentityParams, type CreatePresentationParams, type Credential, type CredentialChecks, type DIDDocument, type Declaration, type Delegation, type DelegationClaims, type DelegationLinkResult, ED25519_MULTICODEC_PREFIX, type ErrorResponse, type GenerateDeclarationParams, type Identity, type IssueCredentialParams, JcsUnsupportedValueError, type JsonValue, type ListCredentialsParams, type ListDelegationsParams, type ListIdentitiesParams, type LogActionParams, type Presentation, type ProvenanceEntry, type PurgeResult, type QueryReputationParams, type RecordAssessmentParams, type RecordInteractionParams, type RecordModelLineageParams, type RecordTrainingDataParams, type ReputationScore, type VerificationCheck, type VerificationMethod, type VerificationResult, type VerifyCredentialOptions, type VerifyCredentialResult, type VerifyDelegationOptions, type VerifyDelegationResult, type VerifyPresentationResult, base58btcDecode, base58btcEncode, base64urlDecode, canonicalize, canonicalizeToString, decodeDelegationUnsafe, didFromVerificationMethod, didKeyToPublicKey, publicKeyToDidKey, verifyCredential, verifyDelegationChain, verifyEd25519, verifyPresentation };