@trustlayer-foundation/aria-sdk 0.0.0-stage → 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,435 @@
+/** A trust level an issuer may assert. */
+type TrustLevel = 'L0' | 'L1' | 'L2' | 'L3';
+/** A `did:aria` identifier. */
+type Did = `did:aria:${string}`;
+/** The exact issued document a result is about: never the agent's DID alone. */
+interface CredentialBinding {
+    /** The credential's top-level `id`. */
+    readonly credentialId: string;
+    /** `sha-256=:<base64>:` of the document's canonical bytes. */
+    readonly digest: string;
+    /** The trust profile it was verified under. */
+    readonly profile: string;
+}
+
+/** Type-only mark of values the SDK produces. The runtime boundary is the verifier's own record of each result. */
+declare const produced: unique symbol;
+type Produced<K extends string> = {
+    readonly [produced]: K;
+};
+/** Parsed fields of a credential nobody has verified. */
+interface Inspection {
+    readonly kind: 'inspection';
+    /** Always false: inspection never establishes anything. */
+    readonly verified: false;
+    readonly did: string | null;
+    readonly credentialId: string | null;
+    readonly issuer: string | null;
+    readonly specVersion: string | null;
+    readonly trustLevel: string | null;
+    readonly scopes: readonly string[];
+    readonly validFrom: string | null;
+    readonly validUntil: string | null;
+    /** Why parsing stopped, when it did. */
+    readonly problem?: 'not_json' | 'not_a_credential';
+}
+/** Why a credential is not verified. Fixed names; no caller-supplied text. */
+type CredentialFailure = 
+/** Not a JSON object within the size bound, or not valid against the schema of its `spec_version`. */
+'malformed' | 'unsupported_version'
+/** Proof metadata is not the trust profile's. Checking it does not make it signed. */
+ | 'unsupported_proof' | 'untrusted_issuer'
+/** The level is above what the issuer's trust profile may assert. */
+ | 'level_not_trusted'
+/** Either half of the composite issuer signature fails. */
+ | 'signature_invalid' | 'not_yet_valid' | 'expired'
+/** A validity bound is not an instant, or the bounds are inverted. */
+ | 'invalid_validity'
+/** Not the 32 raw bytes of an Ed25519 key, the ARIA 1.0 compatibility encoding, or not the subject's. */
+ | 'holder_key_invalid'
+/** Valid against its schema but not its rules, e.g. `hitlRequired` outside `scope`. */
+ | 'semantic_invalid'
+/** It names a status list its trust profile does not publish. */
+ | 'status_list_untrusted';
+interface Principal {
+    readonly did: string;
+    readonly type: 'organization' | 'individual';
+    /** An organization's asserted name; never a natural person's. */
+    readonly legalName: string | null;
+    readonly jurisdiction: string | null;
+    readonly verificationStatus: 'self-declared' | 'registry-confirmed' | 'legal-verified';
+}
+/**
+ * One exact issued document that conforms to its `spec_version`, is within its
+ * validity interval and verifies under a trusted issuer. It says nothing about
+ * who presents it, nor about its current status.
+ *
+ * A frozen view: the verifier that produced it keeps the authoritative copy, and
+ * accepts this exact object only. A copy or an altered one is refused.
+ */
+interface VerifiedCredential extends Produced<'credential'> {
+    readonly kind: 'verified-credential';
+    readonly binding: CredentialBinding;
+    /** The agent's stable identity. */
+    readonly did: Did;
+    readonly issuer: Did;
+    readonly specVersion: '1.0';
+    readonly trustLevel: TrustLevel;
+    readonly scopes: readonly string[];
+    /** Scopes the receiver must not act on without a human's approval; a declaration, not an approval. */
+    readonly hitlRequired: readonly string[];
+    readonly delegationDepth: number;
+    readonly principal: Principal;
+    /** `id` and the key as published (multibase); the verifier keeps the decoded 32 bytes. */
+    readonly holderKey: {
+        readonly id: string;
+        readonly publicKeyMultibase: string;
+    };
+    /** Signed validity bounds (RFC 3339). There is no issuance time: `proof.created` is outside the signature. */
+    readonly validFrom: string;
+    readonly validUntil: string;
+    /** Signed predecessor reference, as data. Verification never fetches it. */
+    readonly previousCredentialId: string | null;
+    readonly statusEntry: {
+        readonly list: string;
+        readonly index: number;
+    };
+    /** Local time of this verification. */
+    readonly verifiedAt: string;
+}
+/**
+ * What a verifier established about one of its own credential results, read
+ * through `Verifier.facts` from its record, never from the view. A fresh copy at
+ * each call, holder key bytes included. Data, not evidence: no entry point of this
+ * SDK or of ARIA AP accepts it in place of a result.
+ */
+interface CredentialFacts {
+    readonly binding: CredentialBinding;
+    readonly did: Did;
+    readonly issuer: Did;
+    readonly trustLevel: TrustLevel;
+    readonly scopes: readonly string[];
+    readonly hitlRequired: readonly string[];
+    readonly delegationDepth: number;
+    /** The 32 raw bytes, already accepted by the strict key rule; a copy the caller owns. */
+    readonly holderKey: {
+        readonly id: string;
+        readonly publicKey: Uint8Array;
+    };
+    readonly validFrom: string;
+    readonly validUntil: string;
+}
+type CredentialResult = {
+    readonly ok: true;
+    readonly credential: VerifiedCredential;
+} | {
+    readonly ok: false;
+    readonly reason: CredentialFailure;
+    readonly path?: string;
+};
+/**
+ * A retained document that verifies under a trusted issuer as `verifyCredential`
+ * checks it, except against the current time: what past statements are checked
+ * against. It is not a verified credential: `facts`, `standing`, `checkStatus`
+ * and ARIA AP's admission refuse it, so it never authorizes anything now.
+ */
+interface AuthenticCredential extends Produced<'authentic-credential'> {
+    readonly kind: 'authentic-credential';
+    readonly binding: CredentialBinding;
+    readonly did: Did;
+    readonly issuer: Did;
+    readonly holderKey: {
+        readonly id: string;
+        readonly publicKeyMultibase: string;
+    };
+    /** Signed validity bounds (RFC 3339), reported and not judged. */
+    readonly validFrom: string;
+    readonly validUntil: string;
+    readonly statusEntry: {
+        readonly list: string;
+        readonly index: number;
+    };
+}
+/** Why a retained document is not authentic: the credential failures without the current time. */
+type AuthenticityFailure = Exclude<CredentialFailure, 'not_yet_valid' | 'expired'>;
+type AuthenticityResult = {
+    readonly ok: true;
+    readonly credential: AuthenticCredential;
+} | {
+    readonly ok: false;
+    readonly reason: AuthenticityFailure;
+    readonly path?: string;
+};
+/**
+ * What a verifier established about one of its authentic credentials, read through
+ * `Verifier.historicalFacts`, with what a retained list said about it. Data for
+ * checking past statements; nothing accepts it as a result.
+ */
+interface HistoricalFacts {
+    readonly binding: CredentialBinding;
+    readonly did: Did;
+    readonly issuer: Did;
+    /** The 32 raw bytes, already accepted by the strict key rule; a copy the caller owns. */
+    readonly holderKey: {
+        readonly id: string;
+        readonly publicKey: Uint8Array;
+    };
+    readonly validFrom: string;
+    readonly validUntil: string;
+    /** From `readRetainedStatus` when given: the list's statement and its own validity. */
+    readonly retainedStatus: {
+        readonly state: 'active' | 'revoked';
+        readonly validFrom: string;
+        readonly validUntil: string;
+    } | null;
+}
+
+/** Why the status of a credential could not be established. */
+type StatusUnavailable = 
+/** No fetch policy: the verifier is offline. */
+'offline'
+/** The trust profile names no online status endpoint. */
+ | 'no_online_endpoint' | 'origin_not_allowed' | 'fetch_failed' | 'too_large' | 'malformed' | 'signature_invalid' | 'wrong_issuer'
+/** Outside its signed validity, or a validity window longer than 24 hours. */
+ | 'not_valid_now'
+/** The signed list is older than the verifier's maximum age, counted from its own `validFrom`. */
+ | 'stale';
+interface StatusBase extends Produced<'status'> {
+    readonly kind: 'status-evidence';
+    /** The exact document this evidence is about. */
+    readonly credential: CredentialBinding;
+    /** Local time the evidence was obtained (RFC 3339). Fetching an old list does not make it new. */
+    readonly fetchedAt: string;
+}
+/**
+ * Status of one exact credential. Only the signed list carries signed times; an
+ * online answer carries none and is only as strong as TLS to the configured
+ * endpoint. `superseded` comes only from an online answer that names another
+ * current document: a revocation bit cannot say why.
+ */
+type StatusEvidence = (StatusBase & {
+    readonly source: 'status-list';
+    readonly state: 'active' | 'revoked';
+    readonly list: {
+        readonly url: string;
+        readonly index: number;
+        readonly validFrom: string;
+        readonly validUntil: string;
+    };
+}) | (StatusBase & {
+    readonly source: 'online';
+    readonly state: 'active' | 'revoked' | 'superseded';
+    /** The current document, when the answer names another one. */
+    readonly currentCredentialId?: string;
+}) | (StatusBase & {
+    readonly source: 'status-list' | 'online';
+    readonly state: 'unavailable';
+    readonly reason: StatusUnavailable;
+});
+/** The judgment itself, without its time. */
+type StandingState = {
+    readonly state: 'good';
+    readonly source: 'status-list' | 'online';
+}
+/** Outside its signed validity at the moment judged: expired, or not yet valid. */
+ | {
+    readonly state: 'not_valid_now';
+} | {
+    readonly state: 'revoked';
+} | {
+    readonly state: 'superseded';
+} | {
+    readonly state: 'unknown';
+    /** No evidence, evidence past its validity or maximum age, or evidence about another verified result. */
+    readonly reason: 'unavailable' | 'stale' | 'other_document';
+};
+/**
+ * Whether one exact credential stands now, from `Verifier.standing`: judged at
+ * the call under the verifier's own clock and freshness rules. A judgment, not
+ * evidence: no entry point of this SDK or of ARIA AP accepts it as input.
+ */
+type Standing = StandingState & {
+    readonly kind: 'standing';
+    /** When it was judged (RFC 3339, the verifier's clock). */
+    readonly judgedAt: string;
+};
+/** Why a retained status list says nothing about a credential. */
+type RetainedStatusFailure = 'malformed' | 'signature_invalid' | 'wrong_issuer'
+/** A validity bound is not an instant, the bounds are inverted, or longer than 24 hours. */
+ | 'invalid_validity';
+/**
+ * What a retained, signed status list said about one authentic credential, during
+ * the list's own validity. Never judged against the current time and never
+ * accepted by `standing`: history, not current status.
+ */
+interface RetainedStatus extends Produced<'retained-status'> {
+    readonly kind: 'retained-status';
+    readonly credential: CredentialBinding;
+    readonly state: 'active' | 'revoked';
+    readonly list: {
+        readonly url: string;
+        readonly index: number;
+        readonly validFrom: string;
+        readonly validUntil: string;
+    };
+}
+type RetainedStatusResult = {
+    readonly ok: true;
+    readonly status: RetainedStatus;
+} | {
+    readonly ok: false;
+    readonly reason: RetainedStatusFailure;
+};
+interface StatusOptions {
+    /** `status-list` (default) tells the issuer nothing about which credential is checked. */
+    readonly via?: 'status-list' | 'online';
+}
+
+/** One issuer the verifier trusts. Its `id` is a label for results, never a trust identity. */
+interface TrustProfile {
+    /** E.g. `demo` or `production`. */
+    readonly id: string;
+    readonly issuer: Did;
+    /** The DID URL the issuer's proofs name, e.g. `did:aria:registry.aria.bar#key-1`. */
+    readonly verificationMethod: string;
+    readonly keys: {
+        readonly mldsa65: Uint8Array;
+        readonly ed25519: Uint8Array;
+    };
+    /** Highest level this profile may assert; a credential claiming more fails. */
+    readonly maxLevel: TrustLevel;
+    /** Status lists this issuer publishes; a credential naming another fails. */
+    readonly statusLists: readonly string[];
+    /** The issuer's online status endpoint, to which the DID is appended, e.g. `https://api.aria.bar/v1/verify/`. */
+    readonly onlineStatus?: string;
+}
+/** Bounds on everything the SDK fetches. Without it the verifier is offline and status is `unavailable`. */
+interface FetchPolicy {
+    /** Exact origins it may fetch from; redirects are never followed. */
+    readonly allowedOrigins: readonly string[];
+    /** Default 5000. */
+    readonly timeoutMs?: number;
+    /** Default 262144; the decompressed status list is bounded separately. */
+    readonly maxBytes?: number;
+    /** The fetch implementation; the global one by default. */
+    readonly fetch?: typeof fetch;
+}
+/** Trusted configuration: everything here comes from the adopter, never from a message. It is copied when the verifier is created. */
+interface VerifierConfig {
+    readonly trust: readonly TrustProfile[];
+    readonly fetch?: FetchPolicy;
+    readonly clock?: () => Date;
+    /** Maximum age of signed status-list evidence, from the list's own `validFrom`. Default 3600. */
+    readonly statusMaxAgeSeconds?: number;
+    /** Maximum age of an online status answer when admission uses it, from when it was fetched. Default 60. */
+    readonly onlineStatusMaxAgeSeconds?: number;
+    /** Tolerated clock skew on validity bounds. Default 5. */
+    readonly skewSeconds?: number;
+}
+/**
+ * A verifier with its own, fixed trust. Two verifiers never affect each other;
+ * nothing in the package is configured globally. Results are accepted only by the
+ * verifier that produced them, as the exact objects it returned.
+ */
+interface Verifier {
+    /** Verifies one document. Says nothing about who presents it or its status. */
+    verifyCredential(document: unknown): CredentialResult;
+    /** Status of the credential's exact document. */
+    checkStatus(credential: VerifiedCredential, options?: StatusOptions): Promise<StatusEvidence>;
+    /**
+     * What this verifier established about `credential`, from its own record: a
+     * fresh copy, holder key bytes included. This is how packages built on this one
+     * (ARIA AP) read a credential. Throws `AriaUsageError` for anything this verifier
+     * did not produce: a copy, an altered or hand-made object, another verifier's result.
+     */
+    facts(credential: VerifiedCredential): CredentialFacts;
+    /**
+     * Whether `credential` stands now: inside its signed validity, with `status`
+     * being this verifier's evidence about that same result, still fresh under its
+     * rules. Judged at every call with this verifier's clock. Throws like `facts`.
+     */
+    standing(credential: VerifiedCredential, status: StatusEvidence): Standing;
+    /**
+     * Verifies a retained document as `verifyCredential` does, except against the
+     * current time: an expired document can be authentic. The result is not a
+     * verified credential, and nothing that authorizes accepts it.
+     */
+    verifyAuthenticity(document: unknown): AuthenticityResult;
+    /**
+     * What a retained, signed status list (as a parsed object or JSON text) said about
+     * `credential`, offline: same issuer, the exact list it names, both signatures.
+     * The list's validity is reported, never judged against the current time.
+     */
+    readRetainedStatus(credential: AuthenticCredential, list: unknown): Promise<RetainedStatusResult>;
+    /**
+     * What this verifier established about an authentic credential and, when given,
+     * what a retained list said about it: a fresh copy, holder key bytes included.
+     * Throws `AriaUsageError` for anything this verifier did not produce, and for a
+     * retained status about another document.
+     */
+    historicalFacts(credential: AuthenticCredential, status?: RetainedStatus): HistoricalFacts;
+}
+/** Creates a verifier from a copy of `config`; later changes to `config` or its keys do not reach it. */
+declare function createVerifier(config: VerifierConfig): Verifier;
+/** Parses a credential without verifying anything. Its result cannot be passed where verification is required. */
+declare function inspectCredential(document: unknown): Inspection;
+
+/**
+ * ARIA canonical JSON (INVARIANTS §3): keys sorted at every level, no whitespace,
+ * `JSON.stringify` escaping. The same function as `@aria-registry/verify`'s, so the
+ * bytes match what the authority signs. It is not generic JCS; the closed AID
+ * schema keeps it out of the cases where the two differ.
+ */
+declare function canonicalJson(value: unknown): string;
+
+declare const LEVELS: readonly TrustLevel[];
+
+/**
+ * The `did:aria` identifier grammar (specification §3.1): four shapes, two subject
+ * kinds crossed with two anchoring modes. The same rules as the authority's parser
+ * and the shared vectors (`conformance/vectors/abnf-cases.json`).
+ *
+ * Verifying a credential does not apply it: a signed 1.0 document is read under its
+ * own schema. Use it for identifiers being created or compared.
+ */
+type ParsedDid = 
+/** An agent under a domain its principal has verified. */
+{
+    readonly shape: 'agent-domain-form';
+    readonly did: Did;
+    readonly domain: string;
+    readonly slug: string;
+}
+/** An agent under a registry namespace. */
+ | {
+    readonly shape: 'agent-registry-form';
+    readonly did: Did;
+    readonly host: string;
+    readonly account: string;
+    readonly slug: string;
+}
+/** An organization that has verified a domain. */
+ | {
+    readonly shape: 'principal-domain-form';
+    readonly did: Did;
+    readonly domain: string;
+}
+/** An organization without a verified domain: no host, so it survives a registry move. */
+ | {
+    readonly shape: 'principal-registry-form';
+    readonly did: Did;
+    readonly account: string;
+};
+/** The parts of a `did:aria` identifier, or `null` when it is not one. */
+declare function parseDid(value: unknown): ParsedDid | null;
+
+/**
+ * A value that this verifier did not produce was passed where one of its results
+ * is required: a copy, an altered object, a result of another verifier, or a
+ * hand-made one. A programming error, never a verification outcome.
+ */
+declare class AriaUsageError extends TypeError {
+    constructor(message: string);
+}
+
+export { AriaUsageError, type AuthenticCredential, type AuthenticityFailure, type AuthenticityResult, type CredentialBinding, type CredentialFacts, type CredentialFailure, type CredentialResult, type Did, type FetchPolicy, type HistoricalFacts, type Inspection, type ParsedDid, type Principal, type Produced, type RetainedStatus, type RetainedStatusFailure, type RetainedStatusResult, type Standing, type StandingState, type StatusEvidence, type StatusOptions, type StatusUnavailable, LEVELS as TRUST_LEVELS, type TrustLevel, type TrustProfile, type VerifiedCredential, type Verifier, type VerifierConfig, canonicalJson, createVerifier, inspectCredential, parseDid };