@zadq/x402 0.0.0-stage → 0.2.0

package/dist/holder/killswitch.js

@@ -0,0 +1,257 @@
+// The kill switch: the seller's holder revokes its own credential without
+// naming it, through the network's privacy relay, and confirms the record
+// on the chain itself. Restated from MintID's self-revocation relay contract
+// (v0, provisional) and the holder library's confirmation rule, both cited
+// by name. Runs where the key is — the seller's middleware host — never at
+// the verification service, which holds no key and sees none of this.
+//
+// What leaves this host: the five fields of the self-revocation message,
+// to the relay, over a connection of its own (never the one that talks to
+// the issuer); and one question to a node of the chain that names the
+// issuer only. What comes back from the relay is never the receipt: the
+// credential is reported revoked or pending only once the chain shows the
+// record, and unconfirmed otherwise, with the reason — resubmitting is
+// safe (a record the chain already holds confirms the same way).
+//
+// Nothing here logs. The report is value-free: states, reason codes, the
+// transaction hash and height the chain published anyway — never the
+// revocation value, never the proof.
+//
+// CONTRACT POINT: the relay's path, answer shapes and reason
+// codes handled in `submitSelfRevocation`, and the name of the material the
+// issuer serves with a witness answer (`self_revoke_context`, holder.ts),
+// are restated from MintID's relay contract v0 and holder-library rule and
+// are to be confirmed against MintID's self-contained attachment on the
+// card that tracks this integration, before the first live run.
+import { HolderError, HolderStepError } from "./errors.js";
+import { readRecordedNullifiers } from "./chain.js";
+/** The relay's submission path (relay contract v0). */
+export const RELAY_SUBMIT_PATH = '/v1/self-revocations';
+/** Environment variables the middleware host is configured with. */
+export const RELAY_URL_ENV = 'MINTID_RELAY_URL';
+export const CHAIN_RPC_ENV = 'MINTID_CHAIN_RPC';
+export const CHAIN_ID_ENV = 'MINTID_CHAIN_ID';
+/** A random delay before the revocation is built and sent: up to a minute by default. */
+export const DEFAULT_JITTER_MS = 60_000;
+/** The confirmation read: about one block, in a few short reads. */
+export const CONFIRM_ATTEMPTS = 4;
+export const CONFIRM_INTERVAL_MS = 750;
+/**
+ * The published effect bound, restated from the substrate's operational
+ * rules: a status root every 30 s, a root accepted for at most 180 s (a
+ * presentation against an older root is refused, so a recorded revocation
+ * is effective everywhere within that bound once the issuer folds it at
+ * its next root); a revoked principal's agents follow over the next roots,
+ * about four minutes.
+ */
+export const EFFECT_BOUND = {
+    statusRootSeconds: 30,
+    rootAcceptedSeconds: 180,
+    agentCascadeSeconds: 240,
+};
+/** A relay refusal: the contract's bare reason code and stage, nothing of the message. */
+export class RelayRefusedError extends HolderError {
+    status;
+    code;
+    stage;
+    /** Worth a retry, here or at another relay (`busy`, `chain_unavailable`, caps). */
+    retryable;
+    retryAfterMs;
+    constructor(status, code, stage, retryAfterMs) {
+        super(`relay refused (${stage}): ${code}`);
+        this.status = status;
+        this.code = code;
+        this.stage = stage;
+        this.retryable = status === 429 || status === 503;
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * Hands the self-revocation to the privacy relay: `{message}` with the five
+ * message fields only, no header beyond the content type. The relay checks
+ * the proof with the chain's rules, pays for the transaction and submits
+ * it; this side signs nothing and holds no account. `RelayRefusedError` on
+ * a refusal; every accepted answer (recorded, queued, already recorded,
+ * already in flight, broadcast but not yet seen) still needs the chain read.
+ */
+export async function submitSelfRevocation(relayUrl, revocation, options = {}) {
+    const fetchImpl = options.fetch ?? fetch;
+    const m = revocation.message;
+    const body = {
+        message: {
+            issuer_id: m.issuer_id,
+            nullifier: m.nullifier,
+            status_epoch: m.status_epoch,
+            zk_authorization_proof: m.zk_authorization_proof,
+            proof_system_version: m.proof_system_version,
+        },
+    };
+    let response;
+    try {
+        response = await fetchImpl(relayUrl.replace(/\/+$/, '') + RELAY_SUBMIT_PATH, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(options.timeoutMs ?? 60_000),
+        });
+    }
+    catch {
+        throw new RelayRefusedError(0, 'relay_unreachable', 'relay');
+    }
+    let answer = {};
+    try {
+        const text = await response.text();
+        answer = text ? JSON.parse(text) : {};
+    }
+    catch {
+        answer = {};
+    }
+    const error = typeof answer['error'] === 'string' ? answer['error'] : '';
+    switch (response.status) {
+        case 200:
+            if (answer['status'] === 'recorded') {
+                const out = { outcome: 'recorded' };
+                if (typeof answer['tx_hash'] === 'string')
+                    out.txHash = answer['tx_hash'];
+                if (typeof answer['height'] === 'number')
+                    out.height = answer['height'];
+                return out;
+            }
+            break;
+        case 202:
+            return { outcome: 'queued' };
+        case 409:
+            if (error === 'nullifier_recorded' || error === 'duplicate_submission') {
+                return { outcome: error };
+            }
+            break;
+        case 504:
+            return { outcome: 'inclusion_timeout' };
+    }
+    const retryAfter = Number(response.headers.get('retry-after') ?? '');
+    throw new RelayRefusedError(response.status, error || 'unexpected_answer', typeof answer['stage'] === 'string' ? answer['stage'] : 'relay', Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : undefined);
+}
+/**
+ * Asks a node of the chain whether the revocation is there — for about one
+ * block — reading the issuer's recorded set and finding the holder's own
+ * value locally, so the node never learns which one. `pending` once
+ * recorded, `folded` once the issuer's next root has folded it; otherwise
+ * `unconfirmed` with the reason (no node named, node unreachable, not
+ * recorded yet).
+ */
+export async function confirmSelfRevocation(rpcUrl, revocation, options = {}) {
+    if (!rpcUrl)
+        return { state: 'unconfirmed', reason: 'no_chain_endpoint' };
+    const attempts = Math.max(1, options.attempts ?? CONFIRM_ATTEMPTS);
+    const interval = options.intervalMs ?? CONFIRM_INTERVAL_MS;
+    const sleep = options.sleep ?? defaultSleep;
+    const value = revocation.nullifier || revocation.message.nullifier;
+    let reason = 'chain_unreachable';
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        if (attempt > 0)
+            await sleep(interval);
+        let recorded;
+        try {
+            recorded = await readRecordedNullifiers(rpcUrl, revocation.message.issuer_id, options.fetch ? { fetch: options.fetch } : {});
+        }
+        catch (err) {
+            if (!(err instanceof HolderStepError))
+                throw err;
+            reason = 'chain_unreachable';
+            continue;
+        }
+        const state = recorded.get(value);
+        if (state)
+            return { state };
+        reason = 'not_recorded';
+    }
+    return { state: 'unconfirmed', reason };
+}
+/**
+ * The product kill switch, end to end, where the key is:
+ *
+ * 1. a random delay, so the moment the seller decided is not the moment
+ *    the chain records (the relay shuffles what it holds; this adds the
+ *    seller's own slack);
+ * 2. a fresh witness from the issuer, so the self-revocation is built
+ *    against the root the chain currently holds (the material comes with
+ *    the witness answer; no other call);
+ * 3. the self-revocation, built by the holder library — from that moment
+ *    the holder refuses to present, also after a reload from custody;
+ * 4. the submission through the privacy relay; a refusal for a root the
+ *    chain no longer holds rebuilds against the current one, once;
+ * 5. the confirmation read on the chain, issuer-scoped.
+ *
+ * Configuration: `relayUrl` (or `MINTID_RELAY_URL`), `chainRpc` (or
+ * `MINTID_CHAIN_RPC`; without it the report is `unconfirmed`,
+ * `no_chain_endpoint`), `chainId` (or `MINTID_CHAIN_ID`, else the issuer's
+ * public build information). The client never bypasses the relay to the
+ * chain: it holds no account and signs nothing.
+ */
+export async function revokeCredential(holder, options = {}) {
+    const relayUrl = options.relayUrl ?? process.env[RELAY_URL_ENV];
+    if (!relayUrl)
+        throw new HolderError(`no privacy relay configured (${RELAY_URL_ENV})`);
+    const chainRpc = options.chainRpc ?? process.env[CHAIN_RPC_ENV];
+    const sleep = options.sleep ?? defaultSleep;
+    const random = options.random ?? secureRandom;
+    const jitter = options.jitterMs ?? DEFAULT_JITTER_MS;
+    if (jitter > 0)
+        await sleep(Math.floor(random() * jitter));
+    const chainId = options.chainId ?? process.env[CHAIN_ID_ENV] ?? (await holder.chainId());
+    const build = async () => {
+        await holder.refreshWitness();
+        return holder.selfRevoke({ chain_id: chainId });
+    };
+    const submitOptions = options.relayFetch ? { fetch: options.relayFetch } : {};
+    let revocation = await build();
+    let relay;
+    try {
+        relay = await submitSelfRevocation(relayUrl, revocation, submitOptions);
+    }
+    catch (err) {
+        if (!(err instanceof RelayRefusedError) || err.code !== 'unknown_root')
+            throw err;
+        // The root the message names has left the chain's ring: once more,
+        // against the root it holds now.
+        revocation = await build();
+        relay = await submitSelfRevocation(relayUrl, revocation, submitOptions);
+    }
+    const confirmOptions = { sleep };
+    if (options.chainFetch)
+        confirmOptions.fetch = options.chainFetch;
+    if (options.confirmAttempts !== undefined)
+        confirmOptions.attempts = options.confirmAttempts;
+    if (options.confirmIntervalMs !== undefined)
+        confirmOptions.intervalMs = options.confirmIntervalMs;
+    const confirmation = await confirmSelfRevocation(chainRpc, revocation, confirmOptions);
+    const report = {
+        state: confirmation.state === 'folded'
+            ? 'revoked'
+            : confirmation.state === 'pending'
+                ? 'pending'
+                : 'unconfirmed',
+        relay: relay.outcome,
+        chain: confirmation.state === 'unconfirmed'
+            ? confirmation.reason === 'not_recorded'
+                ? 'not_recorded'
+                : 'unread'
+            : confirmation.state,
+        holderRefusesToPresent: true,
+        effect: EFFECT_BOUND,
+    };
+    if (confirmation.state === 'unconfirmed')
+        report.reason = confirmation.reason;
+    if (relay.txHash !== undefined)
+        report.txHash = relay.txHash;
+    if (relay.height !== undefined)
+        report.height = relay.height;
+    return report;
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function secureRandom() {
+    const [word] = globalThis.crypto.getRandomValues(new Uint32Array(1));
+    return (word ?? 0) / 0x1_0000_0000;
+}

package/dist/holder/process.d.ts

@@ -0,0 +1,31 @@
+/** Environment variable locating the binary when no path is given. */
+export declare const HOLDER_BINARY_ENV = "MINTID_HOLDER_BIN";
+/** The holder process protocol this module was written against (`version` op). */
+export declare const HOLDER_PROTOCOL: {
+    readonly holder: "mintid-holder";
+    readonly storageVersion: 1;
+};
+export type HolderParams = Record<string, unknown>;
+export interface HolderRpc {
+    /** One op; resolves to `result`, rejects with `HolderLibraryError`. */
+    call(op: string, params?: HolderParams): Promise<Record<string, unknown>>;
+    close(): Promise<void>;
+}
+export declare class HolderProcess implements HolderRpc {
+    private readonly child;
+    private readonly lines;
+    private readonly pending;
+    private next;
+    private exited;
+    private constructor();
+    /**
+     * Launch the holder library process. No path: `$MINTID_HOLDER_BIN`, then
+     * `mintid-holder` on PATH. Its stderr is inherited (diagnostics only; the
+     * library writes no secret there).
+     */
+    static start(binary?: string, args?: string[]): HolderProcess;
+    call(op: string, params?: HolderParams): Promise<Record<string, unknown>>;
+    private onLine;
+    /** End the process; every credential it held is gone with its secret. */
+    close(): Promise<void>;
+}

package/dist/holder/process.js

@@ -0,0 +1,84 @@
+// The holder library as a child process: MintID's `mintid-holder` binary
+// speaks one JSON request per line on stdin and answers one JSON line on
+// stdout (its `version` op names the holder and proof-core pins; custody
+// storage version 1). This module is transport only — the link secret lives
+// in the child process' memory and reaches this side only inside the custody
+// encoding, on request. Zero runtime dependencies (node:child_process).
+//
+// `HolderRpc` is the seam: `HolderProcess` spawns the real binary, tests
+// inject a scripted one.
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { HolderLibraryError } from "./errors.js";
+/** Environment variable locating the binary when no path is given. */
+export const HOLDER_BINARY_ENV = 'MINTID_HOLDER_BIN';
+/** The holder process protocol this module was written against (`version` op). */
+export const HOLDER_PROTOCOL = { holder: 'mintid-holder', storageVersion: 1 };
+export class HolderProcess {
+    child;
+    lines;
+    pending = new Map();
+    next = 1;
+    exited = null;
+    constructor(child) {
+        this.child = child;
+        this.lines = createInterface({ input: child.stdout });
+        this.lines.on('line', (line) => this.onLine(line));
+        const fail = (error) => {
+            this.exited = error;
+            for (const p of this.pending.values())
+                p.reject(error);
+            this.pending.clear();
+        };
+        child.on('error', (e) => fail(new HolderLibraryError('process', e.message)));
+        child.on('exit', () => fail(new HolderLibraryError('process', 'holder process exited')));
+    }
+    /**
+     * Launch the holder library process. No path: `$MINTID_HOLDER_BIN`, then
+     * `mintid-holder` on PATH. Its stderr is inherited (diagnostics only; the
+     * library writes no secret there).
+     */
+    static start(binary, args = []) {
+        const path = binary || process.env[HOLDER_BINARY_ENV] || 'mintid-holder';
+        const child = spawn(path, args, { stdio: ['pipe', 'pipe', 'inherit'] });
+        return new HolderProcess(child);
+    }
+    call(op, params = {}) {
+        if (this.exited)
+            return Promise.reject(this.exited);
+        const id = this.next++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { op, resolve, reject });
+            this.child.stdin.write(JSON.stringify({ ...params, id, op }) + '\n');
+        });
+    }
+    onLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const id = typeof msg.id === 'number' ? msg.id : -1;
+        const pending = this.pending.get(id);
+        if (!pending)
+            return;
+        this.pending.delete(id);
+        if (msg.ok === true) {
+            pending.resolve((msg.result ?? {}));
+        }
+        else {
+            pending.reject(new HolderLibraryError(pending.op, String(msg.error ?? '')));
+        }
+    }
+    /** End the process; every credential it held is gone with its secret. */
+    async close() {
+        if (this.exited)
+            return;
+        const done = new Promise((resolve) => this.child.once('exit', () => resolve()));
+        this.child.stdin.end();
+        await done;
+        this.lines.close();
+    }
+}

package/dist/holder/types.d.ts

@@ -0,0 +1,108 @@
+/** One entry of a challenge's claim policy (contract v1 `ClaimPredicate`). */
+export type ClaimPredicate = {
+    claim: string;
+    value: string | number | boolean;
+    operator?: '>=' | '<=' | '==';
+};
+/** The signed presentation request a verifier issues (contract v1, schema-exact key names). */
+export type PresentationRequest = {
+    session_id: string;
+    nonce: string;
+    verifier_id: string;
+    audience: string;
+    request_key_id: string;
+    /** Unix seconds; a presentation lives ten seconds. */
+    expires_at: number;
+    finalized_chain_height: number;
+    issuer_policy: {
+        accepted_issuer_ids?: string[];
+        issuer_state_minimum?: string;
+    };
+    claim_policy: ClaimPredicate[];
+    same_credential_required: boolean;
+    profile?: 'agent_v1';
+};
+/** The verifier's `createChallenge` answer, forwarded to the holder byte for byte. */
+export type IssuedChallenge = {
+    request: PresentationRequest;
+    signature_hex: string;
+};
+/** The holder's answer: opaque proof plus public outputs. Never personal data. */
+export type PresentationEnvelope = {
+    proof_hex: string;
+    issuer_id: string;
+    status_root: string;
+    claimed_predicates: string[];
+};
+/** The holder's own view of its credential: never the link secret, never a date of birth. */
+export type HolderInfo = {
+    issuer_id: string;
+    grade: number;
+    issued_at_epoch: number;
+    expires_at_epoch: number;
+    credential_id: string;
+    accumulator_leaf: string;
+    root_height: number | null;
+    status_root: string | null;
+    witness_endpoint: string;
+    profile?: 'identity_v1' | 'agent_v1';
+    /** Set once the holder self-revoked: it refuses to present from then on. */
+    self_revoked?: boolean;
+};
+/** What a witness refresh learned from the issuer. */
+export type WitnessState = {
+    status: string;
+    usable: boolean;
+    refreshed: boolean;
+    rootHeight: number | null;
+    statusRoot: string | null;
+};
+/**
+ * The issuer's self-revocation material for a finalized root the credential
+ * is a member of, exactly as the issuer serves it with every usable witness
+ * (`self_revoke_context`): its anchored definition with the digest-leaf
+ * witness, the profile's self-revocation encryption key with its witness,
+ * and the root they name. Public material, the same for every holder of
+ * the issuer — nothing per credential.
+ */
+export type SelfRevokeMaterial = Record<string, unknown> & {
+    status_root?: string;
+};
+/**
+ * What a self-revocation needs: the chain id and the issuer's anchoring
+ * material for a finalized root the credential is a member of. Omitted, the
+ * material cached by the last witness refresh is used.
+ */
+export type SelfRevokeContext = {
+    chain_id: string;
+    anchoring?: SelfRevokeMaterial;
+    status_root?: string;
+};
+/**
+ * The self-revocation message the holder library builds for a privacy
+ * relay: it names neither the holder nor the credential. Building it
+ * revokes nothing by itself — a relay submits it and the chain records it.
+ */
+export type SelfRevocation = {
+    message: {
+        issuer_id: string;
+        nullifier: string;
+        status_epoch: number;
+        zk_authorization_proof: string;
+        proof_system_version: string;
+    };
+    nullifier: string;
+    ciphertext: string;
+};
+/** What the presentation endpoint answers the verification service with. */
+export type ChallengeAnswer = {
+    status: 200;
+    body: PresentationEnvelope;
+} | {
+    status: 400 | 409 | 503;
+    body: {
+        error: string;
+        reason: string;
+        detail?: string;
+    };
+};

package/dist/holder/types.js

@@ -0,0 +1,5 @@
+// Wire shapes the seller's holder exchanges, restated from MintID's frozen
+// verifier-service contract v1 (bIP-0001) and the holder library's process
+// protocol. Key names are the contract's; 32-byte fields are lowercase hex.
+// Nothing here carries an attribute of the accountable party.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { BRAND, VERDICT_EXTENSION_KEY } from './brand.js';
+export { CHAINS, DEFAULT_TIMEOUT_MS, DEPOSIT_DECLARATION_STATES, DEPOSIT_LEVELS, canonicalPayTo, canonicalSubject, canonicalVerdictPayload, fetchVerdict, freshness, isChain, keyIdFor, readDepositDeclaration, verifyVerdictSignature, type Chain, type DepositDeclaration, type DepositDeclarationState, type DepositLevel, type Freshness, type SignatureCheck, type Verdict, type VerdictOutcome, type VerdictReason, type VerdictSubject, } from './verdict.js';
+export { IDENTITY_POLICY_EXTENSION, MINTID_IDENTITY_EXTENSION, PERIMETER_EXTENSION, readIdentityPolicy, readMintidIdentity, readPerimeterInvitation, withIdentityPolicy, withMintidIdentity, withPerimeterInvitation, withSellerIdentity, type ClaimPolicyEntry, type CredentialState, type IdentityPolicy, type MintidIdentityPolicy, type PaymentRequiredBody, type PerimeterInvitation, type SellerIdentity, } from './extension.js';
+export { X_PAYMENT_HEADER, X_PAYMENT_IDENTITY_HEADER, attachIdentityProof, readIdentityProof, type IdentityProof, } from './header.js';
+export { ATTESTATION_RECEIPT_FORMAT, attestationReceiptProof, canonicalJson, isReceipt, readAttestationReceipt, receiptSigningInput, verifyAttestationReceipt, type AttestationReceipt, type ReceiptCheck, } from './receipt.js';
+export { UNKNOWN_SIGNAL, createVerificationClient, toSignal, type VerificationClient, type VerificationClientOptions, type VerificationSignal, } from './explorer.js';
+export { fetchVerificationKeys, findKey, type VerificationKey } from './keys.js';
+export { SIGNATURE_HEADER, SIGNATURE_KEY_HEADER, WEBHOOK_VERSION, WEBHOOK_VERSION_HEADER, parseVerdictEvent, verifyWebhookSignature, webhookKeyId, type VerdictEvent, } from './webhook.js';
+export * from './holder/index.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+// x402 extension helpers and explorer integration code (Apache-2.0). No
+// default exports; every module is strict TypeScript with zero runtime
+// dependencies and carries the graceful-degradation pattern: an integration
+// keeps working when no verification response is available.
+//
+// Transport follows the bIP-0002 x402 profile of the MintID identity network
+// (cited by name): identity policy in a `PaymentRequired` extension, proof alongside
+// the `X-PAYMENT` header.
+export { BRAND, VERDICT_EXTENSION_KEY } from "./brand.js";
+export { CHAINS, DEFAULT_TIMEOUT_MS, DEPOSIT_DECLARATION_STATES, DEPOSIT_LEVELS, canonicalPayTo, canonicalSubject, canonicalVerdictPayload, fetchVerdict, freshness, isChain, keyIdFor, readDepositDeclaration, verifyVerdictSignature, } from "./verdict.js";
+export { IDENTITY_POLICY_EXTENSION, MINTID_IDENTITY_EXTENSION, PERIMETER_EXTENSION, readIdentityPolicy, readMintidIdentity, readPerimeterInvitation, withIdentityPolicy, withMintidIdentity, withPerimeterInvitation, withSellerIdentity, } from "./extension.js";
+export { X_PAYMENT_HEADER, X_PAYMENT_IDENTITY_HEADER, attachIdentityProof, readIdentityProof, } from "./header.js";
+export { ATTESTATION_RECEIPT_FORMAT, attestationReceiptProof, canonicalJson, isReceipt, readAttestationReceipt, receiptSigningInput, verifyAttestationReceipt, } from "./receipt.js";
+export { UNKNOWN_SIGNAL, createVerificationClient, toSignal, } from "./explorer.js";
+export { fetchVerificationKeys, findKey } from "./keys.js";
+export { SIGNATURE_HEADER, SIGNATURE_KEY_HEADER, WEBHOOK_VERSION, WEBHOOK_VERSION_HEADER, parseVerdictEvent, verifyWebhookSignature, webhookKeyId, } from "./webhook.js";
+// The seller-side holder module (Node-only: it spawns MintID's holder
+// library process). Import it from './holder/index.ts' directly in a
+// platform-neutral build; it is re-exported here for Node integrations.
+export * from "./holder/index.js";

package/dist/keys.d.ts

@@ -0,0 +1,17 @@
+/** One published verification key. */
+export type VerificationKey = {
+    /** First 8 bytes of the public key's SHA-256, hex — matches `Verdict.keyId`. */
+    keyId: string;
+    algorithm: 'Ed25519';
+    /** Raw 32-byte public key, base64. */
+    publicKey: string;
+};
+/**
+ * Fetches the published verification keys. Resolves to `undefined` — never
+ * rejects — on timeout, network failure, a non-OK response or a malformed body.
+ */
+export declare function fetchVerificationKeys(baseUrl: string, options?: {
+    timeoutMs?: number;
+}): Promise<VerificationKey[] | undefined>;
+/** Picks the key a verdict was signed with, by `keyId`. */
+export declare function findKey(keys: readonly VerificationKey[] | undefined, keyId: string | undefined): VerificationKey | undefined;

package/dist/keys.js

@@ -0,0 +1,45 @@
+// Verification keys — the public half of the verdict-signing key, served on
+// the free path (GET /v0/verification-keys) so any party can check verdict
+// signatures locally with verdict.ts#verifyVerdictSignature.
+//
+// Graceful degradation, by design: an unreachable service resolves to
+// `undefined` — never an exception. Without a key, a signature is simply
+// "unverifiable" and your integration keeps working as before.
+import { DEFAULT_TIMEOUT_MS } from "./verdict.js";
+/**
+ * Fetches the published verification keys. Resolves to `undefined` — never
+ * rejects — on timeout, network failure, a non-OK response or a malformed body.
+ */
+export async function fetchVerificationKeys(baseUrl, options) {
+    try {
+        const res = await fetch(new URL('/v0/verification-keys', baseUrl), {
+            signal: AbortSignal.timeout(options?.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            return undefined;
+        }
+        const body = (await res.json());
+        if (!Array.isArray(body.keys)) {
+            return undefined;
+        }
+        return body.keys.filter(isVerificationKey);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Picks the key a verdict was signed with, by `keyId`. */
+export function findKey(keys, keyId) {
+    if (keys === undefined || keyId === undefined) {
+        return undefined;
+    }
+    return keys.find((k) => k.keyId === keyId);
+}
+function isVerificationKey(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v['keyId'] === 'string' &&
+        v['algorithm'] === 'Ed25519' &&
+        typeof v['publicKey'] === 'string');
+}

package/dist/receipt.d.ts

@@ -0,0 +1,50 @@
+import { type IdentityProof } from './header.js';
+/** Format tag of the v0 seller-side proof. */
+export declare const ATTESTATION_RECEIPT_FORMAT = "attestation-ref/v0";
+/** The issuer's receipt, byte-shaped as the canonical payload (snake_case). */
+export type AttestationReceipt = {
+    /** 32-byte opaque reference, hex. */
+    attestation_ref: string;
+    /** 32-byte issuer identifier, hex. */
+    issuer_id: string;
+    /** Chain-qualified rail identifier as the issuer recorded it. */
+    chain: string;
+    pay_to: string;
+    resource_url: string;
+    /** Substrate grade 1..4 (the public form is the single letter G). */
+    assurance_grade: number;
+    issued_at_unix: number;
+    /** Ed25519 by the issuer's registered status signing key, hex (64 bytes). */
+    signature: string;
+};
+/** Sender side: the companion-header proof carrying this receipt. */
+export declare function attestationReceiptProof(receipt: AttestationReceipt): IdentityProof;
+/**
+ * Receiver side: decodes a receipt from a companion-header proof. Returns
+ * `undefined` for any other format or a malformed payload — a normal state;
+ * proceed as without the header.
+ */
+export declare function readAttestationReceipt(proof: IdentityProof | undefined): AttestationReceipt | undefined;
+/** Structural check against the canonical payload schema (closed object). */
+export declare function isReceipt(value: unknown): value is AttestationReceipt;
+/** Outcome of a local receipt check. */
+export type ReceiptCheck = 'valid' | 'invalid' | 'unverifiable';
+/**
+ * Verifies the issuer's signature locally: Ed25519 over
+ * `"mintid/seller-attestation/v0" || 0x00 || SHA-256(canonical JSON of the
+ * seven signed fields)` with the issuer's registered status signing key (raw
+ * 32 bytes, hex). The key is read from the substrate's issuer registry and
+ * pinned by the consumer — never hard-coded here, never taken from the
+ * receipt itself.
+ *
+ * `valid` proves issuance by that key. It says nothing about standing.
+ */
+export declare function verifyAttestationReceipt(receipt: AttestationReceipt, issuerPublicKeyHex: string): Promise<ReceiptCheck>;
+/** The exact bytes the issuer signed (domain-separated digest of the canonical payload). */
+export declare function receiptSigningInput(receipt: AttestationReceipt): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Canonical JSON as the issuer produces it: keys sorted by code point, no
+ * whitespace, every non-ASCII code unit escaped as lowercase `\uXXXX`
+ * (the form Python's json.dumps emits with sort_keys and compact separators).
+ */
+export declare function canonicalJson(value: Record<string, string | number>): string;