@tinycloud/node-sdk 3.6.0-beta.3 → 3.6.0-beta.5

package/dist/credentials-core.d.cts

@@ -0,0 +1,337 @@
+import { CredentialFlowDescriptor, CredentialRequirement, CredentialHolderBinding, IssuedCredentialEnvelope, CredentialIssuerMetadata, ClientSession, IKVService, StoredCredentialRecord, VerifiedCredential, CredentialProgressEvent, CredentialStorageReceipt, UnifiedPolicyV2, UnifiedPolicyCapability, PolicyCredentialAdmissionV3 } from '@tinycloud/sdk-core';
+import { V as ValidatedRuntimeDelegation } from './delegation-0LKZkmP2.cjs';
+
+interface CredentialClient {
+    readonly sessionDid: string;
+    readonly credentialHolderDid: string;
+    readonly credentialHolderKid: string;
+    session(): ClientSession | undefined;
+    signSessionBytes(bytes: Uint8Array): Promise<Uint8Array>;
+    autoSignCredentialBytes?(bytes: Uint8Array): Promise<Uint8Array | undefined>;
+    approveCredentialBytes?(bytes: Uint8Array): Promise<Uint8Array>;
+    activateCompactRuntimeDelegation?(input: {
+        readonly authorization: string;
+        readonly cid: string;
+        readonly host: string;
+    }): Promise<ValidatedRuntimeDelegation>;
+    ensureOwnedSpaceHosted(name: string): Promise<string>;
+    credentialSpaceOwnerDid(spaceId: string): string;
+    kvForSpace(spaceId: string): IKVService;
+    /**
+     * Root authorization CID of the active account session. Exposed here rather
+     * than on {@link ClientSession} so the CID stays out of the public session.
+     */
+    accountAuthorizationCid(): string;
+    /** Receiver-local credential custody. Its presence selects accountless mode. */
+    readonly receiverCredentialCustody?: ReceiverCredentialCustody;
+}
+interface ReceiverCredentialCustody {
+    find(input: {
+        readonly requirement: CredentialRequirement;
+        readonly requirementDigest: string;
+        readonly holderDid: string;
+        readonly now?: Date;
+    }): Promise<StoredCredentialRecord | undefined>;
+    store(input: {
+        readonly verified: VerifiedCredential;
+        readonly requirement: CredentialRequirement;
+        readonly requirementDigest: string;
+        readonly holderDid: string;
+        readonly now?: Date;
+    }): Promise<StoredCredentialRecord>;
+}
+/** Holder key the witness verifies against. Sent on the wire with the holder signature. */
+interface HolderSignatureKey {
+    readonly alg: "EdDSA";
+    readonly kid: string;
+}
+interface CredentialSigningAdapter {
+    /** Return undefined when the existing exact-request auto-sign policy does not apply. */
+    readonly autoSign?: (binding: CredentialHolderBinding, bytes: Uint8Array, signal?: AbortSignal) => Promise<Uint8Array | undefined>;
+    /** Invoke the normal OpenKey approval surface. */
+    readonly requestApproval?: (binding: CredentialHolderBinding, bytes: Uint8Array, signal?: AbortSignal) => Promise<Uint8Array>;
+    /** Wire identity for the holder signature. Omitted by root callers: the transport then sends EdDSA with the did:key kid. */
+    readonly holderKey?: HolderSignatureKey;
+}
+type PrimitiveStepResult = Readonly<Record<string, string | boolean>>;
+type PrimitiveStepHandler = (input: {
+    readonly descriptor: CredentialFlowDescriptor;
+    readonly requirement: CredentialRequirement;
+    readonly stepId: string;
+    readonly constraints: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}) => Promise<PrimitiveStepResult>;
+/**
+ * The bounded view a host-owned inline surface may receive. It deliberately
+ * excludes requirement values, which can contain private policy inputs.
+ */
+interface InlineCredentialProofRequest {
+    readonly stepId: string;
+    readonly constraints: Readonly<Record<string, unknown>>;
+    readonly display: {
+        readonly title: string;
+        readonly description: string;
+        readonly consent: string;
+        readonly progressLabel: string;
+        readonly errorLiveRegion: "assertive";
+    };
+    readonly inputs: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly schema: CredentialFlowDescriptor["inputs"][number]["schema"];
+    }[];
+    /** Present when this step's previous proof was rejected and may be retried. */
+    readonly feedback?: {
+        readonly kind: "rejected";
+        readonly attemptsRemaining: number;
+    };
+    readonly signal?: AbortSignal;
+}
+/**
+ * The mailbox a `mailbox_otp` code is sent to, copied from the digest-bound
+ * credential requirement. Only the SDK-owned inline view receives it; host
+ * proof handlers never see requirement values.
+ */
+interface CredentialProofSubject {
+    readonly kind: "email";
+    readonly value: string;
+}
+type InlineCredentialProofHandler = (input: InlineCredentialProofRequest) => Promise<PrimitiveStepResult>;
+type CredentialInteractionKind = "popup" | "redirect" | "headless" | "inline";
+interface CredentialInteractionSurface {
+    readonly wake: () => Promise<void>;
+    readonly close: () => void;
+    readonly closed: () => boolean;
+    /**
+     * A bounded, local UI callback for a declared primitive step. The adapter
+     * returns user-entered proof bytes to the SDK; it never receives an
+     * acquisition locator, request verifier, or transport capability.
+     */
+    readonly requestProof?: InlineCredentialProofHandler;
+    /**
+     * Collects descriptor inputs the requirement does not already supply, such
+     * as the recipient's own mailbox for an email-domain requirement. It
+     * receives only the input schema and the public domain constraint.
+     */
+    readonly requestInputs?: (request: CredentialInputRequest) => Promise<Readonly<Record<string, string>>>;
+}
+interface CredentialInputRequest {
+    readonly inputs: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly schema: CredentialFlowDescriptor["inputs"][number]["schema"];
+    }[];
+    /** The exact canonical domain the entered mailbox must belong to. */
+    readonly mailboxDomain?: string;
+    readonly signal?: AbortSignal;
+}
+/** A browser-owned interaction that navigates to the OpenCredentials locator. */
+interface CredentialBrowserInteractionAdapter {
+    readonly kind: Exclude<CredentialInteractionKind, "inline">;
+    start(input: {
+        readonly interaction: CredentialFlowDescriptor["interaction"];
+        readonly locator: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CredentialInteractionSurface>;
+}
+/**
+ * A host-owned, in-page acquisition surface. It intentionally receives no
+ * OpenCredentials locator, request verifier, or transport capability. The SDK
+ * owns every OpenCredentials request, including submission of returned proof.
+ */
+interface CredentialInlineInteractionAdapter {
+    readonly kind: "inline";
+    start(input: {
+        readonly signal?: AbortSignal;
+    }): Promise<CredentialInteractionSurface>;
+}
+type CredentialInteractionAdapter = CredentialBrowserInteractionAdapter | CredentialInlineInteractionAdapter;
+interface CredentialRedirectResumeState {
+    readonly type: "TinyCloudCredentialRedirectResume";
+    readonly version: 1;
+    readonly requestId: string;
+    readonly locator: string;
+    readonly verifier: string;
+    readonly expiresAt: string;
+    readonly correlationId: string;
+    readonly holderDid: string;
+    readonly descriptorDigest: string;
+    readonly requirementDigest: string;
+    readonly openerOrigin: string;
+}
+interface CredentialRedirectStore {
+    load(): Promise<CredentialRedirectResumeState | undefined>;
+    save(state: CredentialRedirectResumeState): Promise<void>;
+    clear(): Promise<void>;
+}
+interface CredentialRequestState {
+    readonly type: "OpenCredentialsAcquisitionState";
+    readonly version: 1;
+    readonly requestId: string;
+    readonly transitionId: string;
+    readonly state: "pending" | "ready_to_issue" | "issued" | "complete" | "expired" | "canceled" | "issuer_unready";
+    readonly nextStep?: {
+        readonly id: string;
+        readonly type: "collect_input" | "mailbox_otp" | "holder_signature";
+        readonly version: 1;
+        readonly constraints: Readonly<Record<string, unknown>>;
+    };
+    readonly retryAfterMs?: number;
+    readonly correlationId: string;
+}
+interface CredentialAcquisitionTransport {
+    create(input: {
+        readonly descriptor: CredentialFlowDescriptor;
+        readonly descriptorDigest: string;
+        readonly requirement: CredentialRequirement;
+        readonly requirementDigest: string;
+        readonly holderDid: string;
+        readonly openerOrigin: string;
+        readonly completionVerifierChallenge: string;
+        readonly inputs?: Readonly<Record<string, string>>;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly requestId: string;
+        readonly locator: string;
+        readonly expiresAt: string;
+        readonly correlationId: string;
+    }>;
+    state(requestId: string, verifier: string, signal?: AbortSignal): Promise<CredentialRequestState>;
+    beginStep(requestId: string, verifier: string, stepId: "collect_input" | "mailbox_otp", signal?: AbortSignal): Promise<void>;
+    submitStep(requestId: string, verifier: string, stepId: string, proof: PrimitiveStepResult, signal?: AbortSignal): Promise<void>;
+    holderBinding(requestId: string, verifier: string, signal?: AbortSignal): Promise<CredentialHolderBinding>;
+    submitHolderSignature(requestId: string, verifier: string, signature: string, signal?: AbortSignal, key?: HolderSignatureKey): Promise<void>;
+    issue(requestId: string, verifier: string, signal?: AbortSignal): Promise<void>;
+    result(requestId: string, verifier: string, signal?: AbortSignal): Promise<IssuedCredentialEnvelope>;
+    issuerMetadata(signal?: AbortSignal): Promise<CredentialIssuerMetadata>;
+    checkStatus(status: IssuedCredentialEnvelope["status"], signal?: AbortSignal): Promise<boolean>;
+}
+interface CredentialsOperationOptions {
+    readonly descriptor?: CredentialFlowDescriptor;
+    readonly discoveryUrl?: string;
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly onProgress?: (event: CredentialProgressEvent) => void;
+    readonly now?: () => Date;
+}
+interface CredentialsAcquireOptions extends CredentialsOperationOptions {
+    /**
+     * `inline` mounts the first-party TinyCloud element unless a bounded local
+     * proof adapter is explicitly supplied.
+     */
+    readonly interaction?: CredentialInteractionKind;
+    readonly browser?: CredentialInteractionAdapter;
+    /** Presentation-only tokens. Security-critical copy and proof order are fixed by the descriptor. */
+    readonly theme?: CredentialAcquisitionTheme;
+    readonly transport?: CredentialAcquisitionTransport;
+    readonly signing?: CredentialSigningAdapter;
+    readonly stepHandlers?: Partial<Record<"collect_input" | "mailbox_otp", PrimitiveStepHandler>>;
+    readonly openerOrigin?: string;
+    /** Same-origin, request-scoped persistence used to resume a full-page redirect. */
+    readonly redirectStore?: CredentialRedirectStore;
+    /**
+     * Acquisition inputs the requirement does not carry (for example a
+     * recipient-chosen mailbox for an email-domain requirement). When omitted,
+     * an inline surface collects them.
+     */
+    readonly inputs?: Readonly<Record<string, string>>;
+}
+interface CredentialAcquisitionTheme {
+    readonly accentColor?: string;
+    readonly backgroundColor?: string;
+    readonly textColor?: string;
+}
+interface CredentialsEnsureOptions extends CredentialsAcquireOptions {
+}
+interface CredentialsEnsureResult {
+    readonly status: "reused" | "acquired";
+    readonly credential: VerifiedCredential;
+    readonly record: StoredCredentialRecord;
+    readonly receipt?: CredentialStorageReceipt;
+}
+interface CredentialsPolicyAdmissionOptions {
+    readonly ensured: CredentialsEnsureResult;
+    readonly policy: UnifiedPolicyV2;
+    readonly policyCid: string;
+    readonly policyRootCid: string;
+    readonly enforcementRootCid: string;
+    readonly requirement: CredentialRequirement;
+    readonly requestedCapabilities: readonly UnifiedPolicyCapability[];
+    readonly nodeOrigin: string;
+    /** How long the minted session should last; see `admitPolicyCredentialV3`. */
+    readonly requestedExpiresAt?: string | null;
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+    readonly now?: Date;
+    readonly jti?: string;
+}
+interface CredentialsPolicyAdmissionResult extends PolicyCredentialAdmissionV3 {
+    readonly installed: ValidatedRuntimeDelegation;
+}
+
+/** The mailbox named by an email requirement, which the issuer delivers the code to. */
+declare function mailboxSubject(requirement: CredentialRequirement): CredentialProofSubject | undefined;
+/** Finite step interpreter. Dispatch is exclusively by registered primitive and version. */
+declare function interpretCredentialFlow(input: {
+    readonly descriptor: CredentialFlowDescriptor;
+    readonly requirement: CredentialRequirement;
+    readonly requestId: string;
+    readonly verifier: string;
+    readonly holderDid: string;
+    readonly descriptorDigest: string;
+    readonly requirementDigest: string;
+    readonly openerOrigin: string;
+    readonly transport: CredentialAcquisitionTransport;
+    readonly signing: CredentialSigningAdapter;
+    /**
+     * Fallback for a host-owned surface. It receives every declared proof step,
+     * including primitives added by a later protocol version.
+     */
+    readonly proofHandler?: InlineCredentialProofHandler;
+    readonly handlers?: Partial<Record<"collect_input" | "mailbox_otp", PrimitiveStepHandler>>;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (event: CredentialProgressEvent) => void;
+    readonly onWait?: () => Promise<void>;
+}): Promise<void>;
+
+declare class OpenCredentialsHttpTransport implements CredentialAcquisitionTransport {
+    private readonly descriptor;
+    private readonly fetchFn;
+    private readonly options;
+    private readonly nonces;
+    private readonly bindings;
+    constructor(descriptor: CredentialFlowDescriptor, fetchFn?: typeof fetch, options?: {
+        readonly honorServerRecoverable?: boolean;
+    });
+    private url;
+    private request;
+    create(input: {
+        descriptor: CredentialFlowDescriptor;
+        descriptorDigest: string;
+        requirement: CredentialRequirement;
+        requirementDigest: string;
+        holderDid: string;
+        openerOrigin: string;
+        completionVerifierChallenge: string;
+        inputs?: Readonly<Record<string, string>>;
+        signal?: AbortSignal;
+    }): Promise<{
+        requestId: string;
+        locator: string;
+        expiresAt: string;
+        correlationId: string;
+    }>;
+    private proofStep;
+    state(id: string, verifier: string, signal?: AbortSignal): Promise<CredentialRequestState>;
+    beginStep(id: string, verifier: string, stepId: "collect_input" | "mailbox_otp", signal?: AbortSignal): Promise<void>;
+    submitStep(id: string, verifier: string, stepId: string, proof: PrimitiveStepResult, signal?: AbortSignal): Promise<void>;
+    holderBinding(id: string, verifier: string, signal?: AbortSignal): Promise<CredentialHolderBinding>;
+    submitHolderSignature(id: string, verifier: string, signature: string, signal?: AbortSignal, key?: HolderSignatureKey): Promise<void>;
+    issue(id: string, verifier: string, signal?: AbortSignal): Promise<void>;
+    result(id: string, verifier: string, signal?: AbortSignal): Promise<IssuedCredentialEnvelope>;
+    issuerMetadata(signal?: AbortSignal): Promise<CredentialIssuerMetadata>;
+    checkStatus(status: IssuedCredentialEnvelope["status"], _signal?: AbortSignal): Promise<boolean>;
+}
+
+export { type CredentialAcquisitionTheme, type CredentialAcquisitionTransport, type CredentialBrowserInteractionAdapter, type CredentialClient, type CredentialInlineInteractionAdapter, type CredentialInputRequest, type CredentialInteractionAdapter, type CredentialInteractionKind, type CredentialInteractionSurface, type CredentialProofSubject, type CredentialRedirectResumeState, type CredentialRedirectStore, type CredentialRequestState, type CredentialSigningAdapter, type CredentialsAcquireOptions, type CredentialsEnsureOptions, type CredentialsEnsureResult, type CredentialsOperationOptions, type CredentialsPolicyAdmissionOptions, type CredentialsPolicyAdmissionResult, type HolderSignatureKey, type InlineCredentialProofHandler, type InlineCredentialProofRequest, OpenCredentialsHttpTransport, type PrimitiveStepHandler, type PrimitiveStepResult, type ReceiverCredentialCustody, interpretCredentialFlow, mailboxSubject };

package/dist/credentials-core.d.ts

@@ -0,0 +1,337 @@
+import { CredentialFlowDescriptor, CredentialRequirement, CredentialHolderBinding, IssuedCredentialEnvelope, CredentialIssuerMetadata, ClientSession, IKVService, StoredCredentialRecord, VerifiedCredential, CredentialProgressEvent, CredentialStorageReceipt, UnifiedPolicyV2, UnifiedPolicyCapability, PolicyCredentialAdmissionV3 } from '@tinycloud/sdk-core';
+import { V as ValidatedRuntimeDelegation } from './delegation-0LKZkmP2.js';
+
+interface CredentialClient {
+    readonly sessionDid: string;
+    readonly credentialHolderDid: string;
+    readonly credentialHolderKid: string;
+    session(): ClientSession | undefined;
+    signSessionBytes(bytes: Uint8Array): Promise<Uint8Array>;
+    autoSignCredentialBytes?(bytes: Uint8Array): Promise<Uint8Array | undefined>;
+    approveCredentialBytes?(bytes: Uint8Array): Promise<Uint8Array>;
+    activateCompactRuntimeDelegation?(input: {
+        readonly authorization: string;
+        readonly cid: string;
+        readonly host: string;
+    }): Promise<ValidatedRuntimeDelegation>;
+    ensureOwnedSpaceHosted(name: string): Promise<string>;
+    credentialSpaceOwnerDid(spaceId: string): string;
+    kvForSpace(spaceId: string): IKVService;
+    /**
+     * Root authorization CID of the active account session. Exposed here rather
+     * than on {@link ClientSession} so the CID stays out of the public session.
+     */
+    accountAuthorizationCid(): string;
+    /** Receiver-local credential custody. Its presence selects accountless mode. */
+    readonly receiverCredentialCustody?: ReceiverCredentialCustody;
+}
+interface ReceiverCredentialCustody {
+    find(input: {
+        readonly requirement: CredentialRequirement;
+        readonly requirementDigest: string;
+        readonly holderDid: string;
+        readonly now?: Date;
+    }): Promise<StoredCredentialRecord | undefined>;
+    store(input: {
+        readonly verified: VerifiedCredential;
+        readonly requirement: CredentialRequirement;
+        readonly requirementDigest: string;
+        readonly holderDid: string;
+        readonly now?: Date;
+    }): Promise<StoredCredentialRecord>;
+}
+/** Holder key the witness verifies against. Sent on the wire with the holder signature. */
+interface HolderSignatureKey {
+    readonly alg: "EdDSA";
+    readonly kid: string;
+}
+interface CredentialSigningAdapter {
+    /** Return undefined when the existing exact-request auto-sign policy does not apply. */
+    readonly autoSign?: (binding: CredentialHolderBinding, bytes: Uint8Array, signal?: AbortSignal) => Promise<Uint8Array | undefined>;
+    /** Invoke the normal OpenKey approval surface. */
+    readonly requestApproval?: (binding: CredentialHolderBinding, bytes: Uint8Array, signal?: AbortSignal) => Promise<Uint8Array>;
+    /** Wire identity for the holder signature. Omitted by root callers: the transport then sends EdDSA with the did:key kid. */
+    readonly holderKey?: HolderSignatureKey;
+}
+type PrimitiveStepResult = Readonly<Record<string, string | boolean>>;
+type PrimitiveStepHandler = (input: {
+    readonly descriptor: CredentialFlowDescriptor;
+    readonly requirement: CredentialRequirement;
+    readonly stepId: string;
+    readonly constraints: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}) => Promise<PrimitiveStepResult>;
+/**
+ * The bounded view a host-owned inline surface may receive. It deliberately
+ * excludes requirement values, which can contain private policy inputs.
+ */
+interface InlineCredentialProofRequest {
+    readonly stepId: string;
+    readonly constraints: Readonly<Record<string, unknown>>;
+    readonly display: {
+        readonly title: string;
+        readonly description: string;
+        readonly consent: string;
+        readonly progressLabel: string;
+        readonly errorLiveRegion: "assertive";
+    };
+    readonly inputs: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly schema: CredentialFlowDescriptor["inputs"][number]["schema"];
+    }[];
+    /** Present when this step's previous proof was rejected and may be retried. */
+    readonly feedback?: {
+        readonly kind: "rejected";
+        readonly attemptsRemaining: number;
+    };
+    readonly signal?: AbortSignal;
+}
+/**
+ * The mailbox a `mailbox_otp` code is sent to, copied from the digest-bound
+ * credential requirement. Only the SDK-owned inline view receives it; host
+ * proof handlers never see requirement values.
+ */
+interface CredentialProofSubject {
+    readonly kind: "email";
+    readonly value: string;
+}
+type InlineCredentialProofHandler = (input: InlineCredentialProofRequest) => Promise<PrimitiveStepResult>;
+type CredentialInteractionKind = "popup" | "redirect" | "headless" | "inline";
+interface CredentialInteractionSurface {
+    readonly wake: () => Promise<void>;
+    readonly close: () => void;
+    readonly closed: () => boolean;
+    /**
+     * A bounded, local UI callback for a declared primitive step. The adapter
+     * returns user-entered proof bytes to the SDK; it never receives an
+     * acquisition locator, request verifier, or transport capability.
+     */
+    readonly requestProof?: InlineCredentialProofHandler;
+    /**
+     * Collects descriptor inputs the requirement does not already supply, such
+     * as the recipient's own mailbox for an email-domain requirement. It
+     * receives only the input schema and the public domain constraint.
+     */
+    readonly requestInputs?: (request: CredentialInputRequest) => Promise<Readonly<Record<string, string>>>;
+}
+interface CredentialInputRequest {
+    readonly inputs: readonly {
+        readonly id: string;
+        readonly label: string;
+        readonly schema: CredentialFlowDescriptor["inputs"][number]["schema"];
+    }[];
+    /** The exact canonical domain the entered mailbox must belong to. */
+    readonly mailboxDomain?: string;
+    readonly signal?: AbortSignal;
+}
+/** A browser-owned interaction that navigates to the OpenCredentials locator. */
+interface CredentialBrowserInteractionAdapter {
+    readonly kind: Exclude<CredentialInteractionKind, "inline">;
+    start(input: {
+        readonly interaction: CredentialFlowDescriptor["interaction"];
+        readonly locator: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CredentialInteractionSurface>;
+}
+/**
+ * A host-owned, in-page acquisition surface. It intentionally receives no
+ * OpenCredentials locator, request verifier, or transport capability. The SDK
+ * owns every OpenCredentials request, including submission of returned proof.
+ */
+interface CredentialInlineInteractionAdapter {
+    readonly kind: "inline";
+    start(input: {
+        readonly signal?: AbortSignal;
+    }): Promise<CredentialInteractionSurface>;
+}
+type CredentialInteractionAdapter = CredentialBrowserInteractionAdapter | CredentialInlineInteractionAdapter;
+interface CredentialRedirectResumeState {
+    readonly type: "TinyCloudCredentialRedirectResume";
+    readonly version: 1;
+    readonly requestId: string;
+    readonly locator: string;
+    readonly verifier: string;
+    readonly expiresAt: string;
+    readonly correlationId: string;
+    readonly holderDid: string;
+    readonly descriptorDigest: string;
+    readonly requirementDigest: string;
+    readonly openerOrigin: string;
+}
+interface CredentialRedirectStore {
+    load(): Promise<CredentialRedirectResumeState | undefined>;
+    save(state: CredentialRedirectResumeState): Promise<void>;
+    clear(): Promise<void>;
+}
+interface CredentialRequestState {
+    readonly type: "OpenCredentialsAcquisitionState";
+    readonly version: 1;
+    readonly requestId: string;
+    readonly transitionId: string;
+    readonly state: "pending" | "ready_to_issue" | "issued" | "complete" | "expired" | "canceled" | "issuer_unready";
+    readonly nextStep?: {
+        readonly id: string;
+        readonly type: "collect_input" | "mailbox_otp" | "holder_signature";
+        readonly version: 1;
+        readonly constraints: Readonly<Record<string, unknown>>;
+    };
+    readonly retryAfterMs?: number;
+    readonly correlationId: string;
+}
+interface CredentialAcquisitionTransport {
+    create(input: {
+        readonly descriptor: CredentialFlowDescriptor;
+        readonly descriptorDigest: string;
+        readonly requirement: CredentialRequirement;
+        readonly requirementDigest: string;
+        readonly holderDid: string;
+        readonly openerOrigin: string;
+        readonly completionVerifierChallenge: string;
+        readonly inputs?: Readonly<Record<string, string>>;
+        readonly signal?: AbortSignal;
+    }): Promise<{
+        readonly requestId: string;
+        readonly locator: string;
+        readonly expiresAt: string;
+        readonly correlationId: string;
+    }>;
+    state(requestId: string, verifier: string, signal?: AbortSignal): Promise<CredentialRequestState>;
+    beginStep(requestId: string, verifier: string, stepId: "collect_input" | "mailbox_otp", signal?: AbortSignal): Promise<void>;
+    submitStep(requestId: string, verifier: string, stepId: string, proof: PrimitiveStepResult, signal?: AbortSignal): Promise<void>;
+    holderBinding(requestId: string, verifier: string, signal?: AbortSignal): Promise<CredentialHolderBinding>;
+    submitHolderSignature(requestId: string, verifier: string, signature: string, signal?: AbortSignal, key?: HolderSignatureKey): Promise<void>;
+    issue(requestId: string, verifier: string, signal?: AbortSignal): Promise<void>;
+    result(requestId: string, verifier: string, signal?: AbortSignal): Promise<IssuedCredentialEnvelope>;
+    issuerMetadata(signal?: AbortSignal): Promise<CredentialIssuerMetadata>;
+    checkStatus(status: IssuedCredentialEnvelope["status"], signal?: AbortSignal): Promise<boolean>;
+}
+interface CredentialsOperationOptions {
+    readonly descriptor?: CredentialFlowDescriptor;
+    readonly discoveryUrl?: string;
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly onProgress?: (event: CredentialProgressEvent) => void;
+    readonly now?: () => Date;
+}
+interface CredentialsAcquireOptions extends CredentialsOperationOptions {
+    /**
+     * `inline` mounts the first-party TinyCloud element unless a bounded local
+     * proof adapter is explicitly supplied.
+     */
+    readonly interaction?: CredentialInteractionKind;
+    readonly browser?: CredentialInteractionAdapter;
+    /** Presentation-only tokens. Security-critical copy and proof order are fixed by the descriptor. */
+    readonly theme?: CredentialAcquisitionTheme;
+    readonly transport?: CredentialAcquisitionTransport;
+    readonly signing?: CredentialSigningAdapter;
+    readonly stepHandlers?: Partial<Record<"collect_input" | "mailbox_otp", PrimitiveStepHandler>>;
+    readonly openerOrigin?: string;
+    /** Same-origin, request-scoped persistence used to resume a full-page redirect. */
+    readonly redirectStore?: CredentialRedirectStore;
+    /**
+     * Acquisition inputs the requirement does not carry (for example a
+     * recipient-chosen mailbox for an email-domain requirement). When omitted,
+     * an inline surface collects them.
+     */
+    readonly inputs?: Readonly<Record<string, string>>;
+}
+interface CredentialAcquisitionTheme {
+    readonly accentColor?: string;
+    readonly backgroundColor?: string;
+    readonly textColor?: string;
+}
+interface CredentialsEnsureOptions extends CredentialsAcquireOptions {
+}
+interface CredentialsEnsureResult {
+    readonly status: "reused" | "acquired";
+    readonly credential: VerifiedCredential;
+    readonly record: StoredCredentialRecord;
+    readonly receipt?: CredentialStorageReceipt;
+}
+interface CredentialsPolicyAdmissionOptions {
+    readonly ensured: CredentialsEnsureResult;
+    readonly policy: UnifiedPolicyV2;
+    readonly policyCid: string;
+    readonly policyRootCid: string;
+    readonly enforcementRootCid: string;
+    readonly requirement: CredentialRequirement;
+    readonly requestedCapabilities: readonly UnifiedPolicyCapability[];
+    readonly nodeOrigin: string;
+    /** How long the minted session should last; see `admitPolicyCredentialV3`. */
+    readonly requestedExpiresAt?: string | null;
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+    readonly now?: Date;
+    readonly jti?: string;
+}
+interface CredentialsPolicyAdmissionResult extends PolicyCredentialAdmissionV3 {
+    readonly installed: ValidatedRuntimeDelegation;
+}
+
+/** The mailbox named by an email requirement, which the issuer delivers the code to. */
+declare function mailboxSubject(requirement: CredentialRequirement): CredentialProofSubject | undefined;
+/** Finite step interpreter. Dispatch is exclusively by registered primitive and version. */
+declare function interpretCredentialFlow(input: {
+    readonly descriptor: CredentialFlowDescriptor;
+    readonly requirement: CredentialRequirement;
+    readonly requestId: string;
+    readonly verifier: string;
+    readonly holderDid: string;
+    readonly descriptorDigest: string;
+    readonly requirementDigest: string;
+    readonly openerOrigin: string;
+    readonly transport: CredentialAcquisitionTransport;
+    readonly signing: CredentialSigningAdapter;
+    /**
+     * Fallback for a host-owned surface. It receives every declared proof step,
+     * including primitives added by a later protocol version.
+     */
+    readonly proofHandler?: InlineCredentialProofHandler;
+    readonly handlers?: Partial<Record<"collect_input" | "mailbox_otp", PrimitiveStepHandler>>;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (event: CredentialProgressEvent) => void;
+    readonly onWait?: () => Promise<void>;
+}): Promise<void>;
+
+declare class OpenCredentialsHttpTransport implements CredentialAcquisitionTransport {
+    private readonly descriptor;
+    private readonly fetchFn;
+    private readonly options;
+    private readonly nonces;
+    private readonly bindings;
+    constructor(descriptor: CredentialFlowDescriptor, fetchFn?: typeof fetch, options?: {
+        readonly honorServerRecoverable?: boolean;
+    });
+    private url;
+    private request;
+    create(input: {
+        descriptor: CredentialFlowDescriptor;
+        descriptorDigest: string;
+        requirement: CredentialRequirement;
+        requirementDigest: string;
+        holderDid: string;
+        openerOrigin: string;
+        completionVerifierChallenge: string;
+        inputs?: Readonly<Record<string, string>>;
+        signal?: AbortSignal;
+    }): Promise<{
+        requestId: string;
+        locator: string;
+        expiresAt: string;
+        correlationId: string;
+    }>;
+    private proofStep;
+    state(id: string, verifier: string, signal?: AbortSignal): Promise<CredentialRequestState>;
+    beginStep(id: string, verifier: string, stepId: "collect_input" | "mailbox_otp", signal?: AbortSignal): Promise<void>;
+    submitStep(id: string, verifier: string, stepId: string, proof: PrimitiveStepResult, signal?: AbortSignal): Promise<void>;
+    holderBinding(id: string, verifier: string, signal?: AbortSignal): Promise<CredentialHolderBinding>;
+    submitHolderSignature(id: string, verifier: string, signature: string, signal?: AbortSignal, key?: HolderSignatureKey): Promise<void>;
+    issue(id: string, verifier: string, signal?: AbortSignal): Promise<void>;
+    result(id: string, verifier: string, signal?: AbortSignal): Promise<IssuedCredentialEnvelope>;
+    issuerMetadata(signal?: AbortSignal): Promise<CredentialIssuerMetadata>;
+    checkStatus(status: IssuedCredentialEnvelope["status"], _signal?: AbortSignal): Promise<boolean>;
+}
+
+export { type CredentialAcquisitionTheme, type CredentialAcquisitionTransport, type CredentialBrowserInteractionAdapter, type CredentialClient, type CredentialInlineInteractionAdapter, type CredentialInputRequest, type CredentialInteractionAdapter, type CredentialInteractionKind, type CredentialInteractionSurface, type CredentialProofSubject, type CredentialRedirectResumeState, type CredentialRedirectStore, type CredentialRequestState, type CredentialSigningAdapter, type CredentialsAcquireOptions, type CredentialsEnsureOptions, type CredentialsEnsureResult, type CredentialsOperationOptions, type CredentialsPolicyAdmissionOptions, type CredentialsPolicyAdmissionResult, type HolderSignatureKey, type InlineCredentialProofHandler, type InlineCredentialProofRequest, OpenCredentialsHttpTransport, type PrimitiveStepHandler, type PrimitiveStepResult, type ReceiverCredentialCustody, interpretCredentialFlow, mailboxSubject };