@zadq/x402 0.2.0 → 0.3.0

package/dist/holder/killswitch.js

@@ -17,44 +17,131 @@
 // 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.
+// The contracts, as MintID delivered them on 2026-10-07 (cited by name):
+// the self-revocation privacy relay v0, provisional 0.1.0 (`POST
+// /v1/self-revocations`, anonymous, no CORS, the closed reason vocabulary,
+// `Retry-After` per answer); the holder library's `self_revoke` op (the
+// relay's body is its `message`, unchanged); the chain's issuer-scoped
+// `RecordedNullifiers` read (chain.ts); and the published effect bound per
+// path (the network's revocation rule): a recorded self-revocation is
+// effective everywhere within G + A + K = 245 s of the chain recording it.
 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';
+/** The relay contract this module implements (`X-Relay-Api-Version` on every answer). */
+export const RELAY_API_VERSION = '0.1.0';
+/** The relay's body cap: 16 KiB. A larger body is refused here, before it travels. */
+export const RELAY_BODY_CAP_BYTES = 16 * 1024;
 /** 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';
+/**
+ * The relay's closed reason vocabulary (relay contract v0 0.1.0): its own
+ * codes, the shape and lookup codes, the proof-check codes and the chain's
+ * `selfrevoke` codes (any other chain code arrives as `chain_refused`). An
+ * answer naming anything else is read as `unexpected_answer`.
+ */
+export const RELAY_REASON_CODES = [
+    // the relay's own
+    'request_too_large',
+    'malformed_json',
+    'duplicate_submission',
+    'busy',
+    'chain_unavailable',
+    'inclusion_timeout',
+    'chain_refused',
+    'proof_refused',
+    'not_found',
+    'method_not_allowed',
+    'internal_error',
+    // shape and lookups
+    'proof_system_version',
+    'msg_shape',
+    'nullifier',
+    'nullifier_recorded',
+    'unknown_root',
+    // the proof check
+    'wire_version',
+    'schema',
+    'wire_shape',
+    'path_depth',
+    'anchor_definition',
+    'anchor_encryption_key',
+    'definition_shape',
+    'encoding',
+    'identity_point',
+    'bbs_schnorr',
+    'bbs_pairing',
+    'acc_schnorr',
+    'acc_pairing',
+    've_c1',
+    've_c2',
+    // the chain (codespace selfrevoke, codes 30–36)
+    'selfrevoke_disabled',
+    'block_cap',
+    'issuer_state',
+    'issuer_cap',
+    'pending_cap',
+    'tx_shape',
+    'params',
+];
+/** True for a code of the relay's closed vocabulary. */
+export function isRelayReasonCode(value) {
+    return typeof value === 'string' && RELAY_REASON_CODES.includes(value);
+}
+/**
+ * The contract's `Retry-After` table, by code — used only when an answer
+ * that should carry the header does not (the header, when present, wins):
+ * `429 busy` 2 or 5 s, `503 chain_unavailable` 5 or 10 s, `503 block_cap` /
+ * `issuer_cap` 10 s, `503 busy` 10 s, `503 pending_cap` 60 s. The fallback
+ * takes the longer value of each row.
+ */
+export const RELAY_RETRY_AFTER_SECONDS = {
+    busy: 10,
+    chain_unavailable: 10,
+    block_cap: 10,
+    issuer_cap: 10,
+    pending_cap: 60,
+};
+/** A relay that cannot be reached is tried again after this long. */
+export const RELAY_UNREACHABLE_RETRY_SECONDS = 5;
+/** The kill switch's submission attempts at one relay (the primitive's default is one). */
+export const DEFAULT_RELAY_ATTEMPTS = 3;
+/** No single wait is longer than the contract's longest `Retry-After` (pending_cap). */
+export const MAX_RETRY_AFTER_MS = 60_000;
 /** 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.
+ * The published effect bound (the network's revocation rule, per path; the
+ * same parameters on production and the public testnet): a holder
+ * self-revocation — the kill switch — is effective everywhere within
+ * G + A + K = 245 s of the chain recording it (fold grace 60 s, a root
+ * accepted for at most 180 s, 5 s of future skew; a root every 30 s). A
+ * revoked principal's agents follow within 7·H + A + K = 395 s of the root
+ * that carries the trigger. The bound is the guarantee: a measured figure
+ * is only ever quoted next to it.
  */
 export const EFFECT_BOUND = {
-    statusRootSeconds: 30,
-    rootAcceptedSeconds: 180,
-    agentCascadeSeconds: 240,
+    boundSeconds: 245,
+    countedFrom: 'recorded_on_chain',
+    principalCascadeSeconds: 395,
+    rootPeriodSeconds: 30,
+    acceptanceWindowSeconds: 180,
+    futureSkewSeconds: 5,
+    foldGraceSeconds: 60,
 };
-/** A relay refusal: the contract's bare reason code and stage, nothing of the message. */
+/** A relay refusal: the bare reason code and stage, nothing of the message. */
 export class RelayRefusedError extends HolderError {
     status;
     code;
+    /** `client`: decided on this side (unreachable, outside the contract, refused before sending). */
     stage;
-    /** Worth a retry, here or at another relay (`busy`, `chain_unavailable`, caps). */
+    /** Worth a retry, here or at another relay (`busy`, `chain_unavailable`, caps, unreachable). */
     retryable;
     retryAfterMs;
     constructor(status, code, stage, retryAfterMs) {
@@ -62,22 +149,57 @@ export class RelayRefusedError extends HolderError {
         this.status = status;
         this.code = code;
         this.stage = stage;
-        this.retryable = status === 429 || status === 503;
+        this.retryable = status === 429 || status === 503 || code === 'relay_unreachable';
         this.retryAfterMs = retryAfterMs;
     }
 }
+const HEX = /^([0-9a-f]{2})*$/;
+const hexOf = (v, min, max) => typeof v === 'string' && HEX.test(v) && v.length >= min && v.length <= max;
+/** The relay's `Message` schema (five fields), checked before anything travels. */
+function messageShapeOk(m) {
+    return (hexOf(m.issuer_id, 64, 64) &&
+        hexOf(m.nullifier, 64, 64) &&
+        !/^0+$/.test(m.nullifier) &&
+        Number.isSafeInteger(m.status_epoch) &&
+        m.status_epoch >= 0 &&
+        hexOf(m.zk_authorization_proof, 2, 9216) &&
+        m.proof_system_version === '01');
+}
 /**
  * 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.
+ * the proof against the issuer's anchored root, pays for the transaction
+ * and submits it; this side signs nothing and holds no account.
+ * `RelayRefusedError` on a refusal (the code from the closed vocabulary);
+ * every accepted answer (recorded, queued, already recorded, already in
+ * flight, broadcast but not yet seen) still needs the chain read. With
+ * `attempts` above one, a retryable refusal (429, 503, unreachable) is
+ * tried again after the relay's `Retry-After` (or the contract's table).
  */
 export async function submitSelfRevocation(relayUrl, revocation, options = {}) {
+    const attempts = Math.max(1, options.attempts ?? 1);
+    const sleep = options.sleep ?? defaultSleep;
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await submitOnce(relayUrl, revocation, options);
+        }
+        catch (err) {
+            if (!(err instanceof RelayRefusedError) || !err.retryable || attempt >= attempts)
+                throw err;
+            await sleep(Math.min(MAX_RETRY_AFTER_MS, err.retryAfterMs ??
+                1000 *
+                    (err.code === 'relay_unreachable'
+                        ? RELAY_UNREACHABLE_RETRY_SECONDS
+                        : (RELAY_RETRY_AFTER_SECONDS[err.code] ?? RELAY_UNREACHABLE_RETRY_SECONDS))));
+        }
+    }
+}
+async function submitOnce(relayUrl, revocation, options) {
     const fetchImpl = options.fetch ?? fetch;
     const m = revocation.message;
-    const body = {
+    if (!messageShapeOk(m))
+        throw new RelayRefusedError(0, 'msg_shape', 'client');
+    const body = JSON.stringify({
         message: {
             issuer_id: m.issuer_id,
             nullifier: m.nullifier,
@@ -85,28 +207,33 @@ export async function submitSelfRevocation(relayUrl, revocation, options = {}) {
             zk_authorization_proof: m.zk_authorization_proof,
             proof_system_version: m.proof_system_version,
         },
-    };
+    });
+    if (Buffer.byteLength(body) > RELAY_BODY_CAP_BYTES) {
+        throw new RelayRefusedError(0, 'request_too_large', 'client');
+    }
     let response;
     try {
         response = await fetchImpl(relayUrl.replace(/\/+$/, '') + RELAY_SUBMIT_PATH, {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(body),
+            body,
             signal: AbortSignal.timeout(options.timeoutMs ?? 60_000),
         });
     }
     catch {
-        throw new RelayRefusedError(0, 'relay_unreachable', 'relay');
+        throw new RelayRefusedError(0, 'relay_unreachable', 'client');
     }
     let answer = {};
     try {
         const text = await response.text();
-        answer = text ? JSON.parse(text) : {};
+        const parsed = text ? JSON.parse(text) : {};
+        if (typeof parsed === 'object' && parsed !== null)
+            answer = parsed;
     }
     catch {
         answer = {};
     }
-    const error = typeof answer['error'] === 'string' ? answer['error'] : '';
+    const error = isRelayReasonCode(answer['error']) ? answer['error'] : undefined;
     switch (response.status) {
         case 200:
             if (answer['status'] === 'recorded') {
@@ -115,29 +242,40 @@ export async function submitSelfRevocation(relayUrl, revocation, options = {}) {
                     out.txHash = answer['tx_hash'];
                 if (typeof answer['height'] === 'number')
                     out.height = answer['height'];
+                const state = answer['nullifier_state'];
+                if (state === 'pending' || state === 'folded')
+                    out.relayNullifierState = state;
                 return out;
             }
             break;
         case 202:
-            return { outcome: 'queued' };
+            if (answer['status'] === 'queued')
+                return { outcome: 'queued' };
+            break;
         case 409:
             if (error === 'nullifier_recorded' || error === 'duplicate_submission') {
                 return { outcome: error };
             }
             break;
         case 504:
-            return { outcome: 'inclusion_timeout' };
+            if (error === 'inclusion_timeout')
+                return { outcome: 'inclusion_timeout' };
+            break;
     }
     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);
+    const stage = answer['stage'];
+    if (!error) {
+        throw new RelayRefusedError(response.status, 'unexpected_answer', 'client');
+    }
+    throw new RelayRefusedError(response.status, error, stage === 'precheck' || stage === 'chain' ? 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).
+ * Asks a node of the chain whether the revocation is there, 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 has folded it (or, after an earlier sighting, once the chain has
+ * pruned it); otherwise `unconfirmed` with the reason (no node named, node
+ * unreachable, not recorded yet). The relay's answer never enters here.
  */
 export async function confirmSelfRevocation(rpcUrl, revocation, options = {}) {
     if (!rpcUrl)
@@ -146,6 +284,7 @@ export async function confirmSelfRevocation(rpcUrl, revocation, options = {}) {
     const interval = options.intervalMs ?? CONFIRM_INTERVAL_MS;
     const sleep = options.sleep ?? defaultSleep;
     const value = revocation.nullifier || revocation.message.nullifier;
+    let seen = options.seen;
     let reason = 'chain_unreachable';
     for (let attempt = 0; attempt < attempts; attempt++) {
         if (attempt > 0)
@@ -161,32 +300,55 @@ export async function confirmSelfRevocation(rpcUrl, revocation, options = {}) {
             continue;
         }
         const state = recorded.get(value);
-        if (state)
+        if (state === 'folded')
             return { state };
+        if (state === 'pending') {
+            seen = 'pending';
+            if (options.until !== 'folded')
+                return { state };
+            continue;
+        }
+        if (seen)
+            return { state: 'folded', pruned: true };
         reason = 'not_recorded';
     }
+    if (seen === 'pending')
+        return { state: 'pending' };
     return { state: 'unconfirmed', reason };
 }
+/**
+ * What the seller path answers for an agent credential: agent credentials
+ * are revoked through the verification service's agent kill route (the
+ * operator console's kill action), which keeps the operator view's state —
+ * never through this path.
+ */
+export const AGENT_CREDENTIAL_REFUSAL = 'an agent credential: revoke it with the operator console kill action ' +
+    '(POST /v0/agent-operators/{ref}/agents/{id}/kill), not with the seller kill switch';
 /**
  * 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.
+ *    the chain records (the relay adds its own 0–6 s and shuffles each
+ *    block's batch; this adds the seller's slack);
+ * 2. a fresh witness from the issuer, whose answer carries the root's
+ *    `self_revoke_context` (no other call);
+ * 3. the holder library's `self_revoke` — `context = {chain_id,
+ *    status_root, anchoring}` with `anchoring` the served context without
+ *    `status_root` — and from that moment the holder refuses to present,
+ *    also after a reload from custody;
+ * 4. the submission through the privacy relay, `Retry-After` honoured; a
+ *    refusal for a root the chain no longer holds (`unknown_root`)
+ *    rebuilds the context once from a fresh witness;
+ * 5. the confirmation read on the chain, issuer-scoped — the relay's
+ *    answer is never the receipt.
  *
- * 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.
+ * The seller's own credential only: an agent credential is refused
+ * (`AGENT_CREDENTIAL_REFUSAL`). 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];
@@ -195,6 +357,8 @@ export async function revokeCredential(holder, options = {}) {
     const chainRpc = options.chainRpc ?? process.env[CHAIN_RPC_ENV];
     const sleep = options.sleep ?? defaultSleep;
     const random = options.random ?? secureRandom;
+    if ((await holder.info()).profile === 'agent_v1')
+        throw new HolderError(AGENT_CREDENTIAL_REFUSAL);
     const jitter = options.jitterMs ?? DEFAULT_JITTER_MS;
     if (jitter > 0)
         await sleep(Math.floor(random() * jitter));
@@ -203,7 +367,12 @@ export async function revokeCredential(holder, options = {}) {
         await holder.refreshWitness();
         return holder.selfRevoke({ chain_id: chainId });
     };
-    const submitOptions = options.relayFetch ? { fetch: options.relayFetch } : {};
+    const submitOptions = {
+        attempts: options.relayAttempts ?? DEFAULT_RELAY_ATTEMPTS,
+        sleep,
+    };
+    if (options.relayFetch)
+        submitOptions.fetch = options.relayFetch;
     let revocation = await build();
     let relay;
     try {
@@ -213,7 +382,7 @@ export async function revokeCredential(holder, options = {}) {
         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.
+        // against the root the issuer serves now.
         revocation = await build();
         relay = await submitSelfRevocation(relayUrl, revocation, submitOptions);
     }
@@ -224,7 +393,18 @@ export async function revokeCredential(holder, options = {}) {
         confirmOptions.attempts = options.confirmAttempts;
     if (options.confirmIntervalMs !== undefined)
         confirmOptions.intervalMs = options.confirmIntervalMs;
-    const confirmation = await confirmSelfRevocation(chainRpc, revocation, confirmOptions);
+    let confirmation = await confirmSelfRevocation(chainRpc, revocation, confirmOptions);
+    const waitMs = options.waitForFoldMs ?? 0;
+    if (confirmation.state === 'pending' && waitMs > 0) {
+        const interval = options.confirmIntervalMs ?? EFFECT_BOUND.rootPeriodSeconds * 1000;
+        confirmation = await confirmSelfRevocation(chainRpc, revocation, {
+            ...confirmOptions,
+            intervalMs: interval,
+            attempts: Math.max(1, Math.ceil(waitMs / interval)),
+            until: 'folded',
+            seen: 'pending',
+        });
+    }
     const report = {
         state: confirmation.state === 'folded'
             ? 'revoked'

package/dist/holder/process.d.ts

@@ -1,5 +1,14 @@
 /** Environment variable locating the binary when no path is given. */
 export declare const HOLDER_BINARY_ENV = "MINTID_HOLDER_BIN";
+/**
+ * The identity network's public release this module is built against, and
+ * what its holder binary's `version` op answers (the binary is built from
+ * that public tag; no release artefact is published).
+ */
+export declare const HOLDER_RELEASE: {
+    readonly tag: "public-v2026-10-07.1";
+    readonly holder: "mintid-holder 0.4.0";
+};
 /** The holder process protocol this module was written against (`version` op). */
 export declare const HOLDER_PROTOCOL: {
     readonly holder: "mintid-holder";

package/dist/holder/process.js

@@ -12,6 +12,15 @@ 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 identity network's public release this module is built against, and
+ * what its holder binary's `version` op answers (the binary is built from
+ * that public tag; no release artefact is published).
+ */
+export const HOLDER_RELEASE = {
+    tag: 'public-v2026-10-07.1',
+    holder: 'mintid-holder 0.4.0',
+};
 /** The holder process protocol this module was written against (`version` op). */
 export const HOLDER_PROTOCOL = { holder: 'mintid-holder', storageVersion: 1 };
 export class HolderProcess {

package/dist/holder/types.d.ts

@@ -58,30 +58,66 @@ export type WitnessState = {
     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.
+ * One anchored leaf of the issuer's anchoring material, with its path to the
+ * served root (identity-status ring): the definition's digest leaf, or the
+ * self-revocation encryption key's. Public material.
  */
-export type SelfRevokeMaterial = Record<string, unknown> & {
-    status_root?: string;
+export type AnchoredLeafWitness = {
+    status: string;
+    ref: string;
+    value: string;
+    status_epoch: number;
+    root: string;
+    index: number;
+    path: string[];
+};
+/**
+ * The issuer's anchoring material a self-revocation is built against — the
+ * holder library's `self_revoke` `context.anchoring`: the anchored issuer
+ * definition with its digest-leaf witness, and the profile's
+ * self-revocation encryption key with its witness. Public, the same for
+ * every holder of the issuer — nothing per credential.
+ */
+export type SelfRevokeAnchoring = {
+    issuer_definition: string;
+    definition_witness: AnchoredLeafWitness;
+    selfrevoke_encryption_key: {
+        version: number;
+        public_key: string;
+    };
+    selfrevoke_encryption_key_witness: AnchoredLeafWitness;
+};
+/**
+ * `self_revoke_context` exactly as the issuer serves it with a witness
+ * answer (`GET /v1/credentials/{id}/witness`): the anchoring plus the root
+ * it names (`status_root`, the served root). The issuer serves `null`
+ * unless the witness is usable and the anchoring names exactly that root;
+ * for an agent credential it is the agent anchoring, for an identity
+ * credential the identity anchoring — the route picks the right one.
+ */
+export type SelfRevokeMaterial = SelfRevokeAnchoring & {
+    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.
+ * What a self-revocation needs: the network's chain id and the issuer's
+ * anchoring for a finalized root the credential is a member of. Omitted,
+ * the material cached by the last witness refresh is used. A served
+ * `self_revoke_context` may be passed as is: its `status_root` is moved out
+ * of the anchoring, where the holder library does not take it.
  */
 export type SelfRevokeContext = {
     chain_id: string;
-    anchoring?: SelfRevokeMaterial;
+    anchoring?: SelfRevokeAnchoring | SelfRevokeMaterial;
+    /** Optional; when given it must equal the root both witnesses name. */
     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.
+ * The holder library's `self_revoke` output: `message` is the relay's body
+ * (`MsgHolderSelfRevoke` fields 1–5) and names neither the holder nor the
+ * credential; `nullifier` and `ciphertext` are what the holder keeps (the
+ * nullifier is how the holder finds its own record in the chain read).
+ * Building it revokes nothing by itself — a relay submits it and the chain
+ * records it — but from then on the holder refuses to present.
  */
 export type SelfRevocation = {
     message: {
@@ -89,6 +125,7 @@ export type SelfRevocation = {
         nullifier: string;
         status_epoch: number;
         zk_authorization_proof: string;
+        /** `"01"` in relay contract v0 0.1.0. */
         proof_system_version: string;
     };
     nullifier: string;

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 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 { BADGE_CLIENT, CLIENT_CLASSES, CLIENT_HEADER, SDK_CLIENT, SDK_VERSION, clientHeaders, clientUserAgent, runtimeDeclaresClient, type ClientClass, type ClientDeclaration, } from './client.js';
+export { CHAINS, DEFAULT_TIMEOUT_MS, DEPOSIT_DECLARATION_STATES, DEPOSIT_LEVELS, VERDICT_OUTCOMES, VERDICT_REASONS, canonicalPayTo, canonicalSubject, canonicalVerdictPayload, fetchVerdict, freshness, isChain, isVerdict, keyIdFor, readDepositDeclaration, subjectMatches, 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, canonicalInlineVerdict, 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, identityProofHeaderValue, 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 { fetchVerificationKeys, findKey, keyFor, type VerificationKey } from './keys.js';
+export { NO_SIGNAL_TITLE, badgeLabel, badgeState, badgeTitle, embedVerificationBadge, renderBadge, type BadgeOptions, type BadgeState, } from './badge.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

@@ -7,12 +7,14 @@
 // (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 { BADGE_CLIENT, CLIENT_CLASSES, CLIENT_HEADER, SDK_CLIENT, SDK_VERSION, clientHeaders, clientUserAgent, runtimeDeclaresClient, } from "./client.js";
+export { CHAINS, DEFAULT_TIMEOUT_MS, DEPOSIT_DECLARATION_STATES, DEPOSIT_LEVELS, VERDICT_OUTCOMES, VERDICT_REASONS, canonicalPayTo, canonicalSubject, canonicalVerdictPayload, fetchVerdict, freshness, isChain, isVerdict, keyIdFor, readDepositDeclaration, subjectMatches, verifyVerdictSignature, } from "./verdict.js";
+export { IDENTITY_POLICY_EXTENSION, canonicalInlineVerdict, MINTID_IDENTITY_EXTENSION, PERIMETER_EXTENSION, readIdentityPolicy, readMintidIdentity, readPerimeterInvitation, withIdentityPolicy, withMintidIdentity, withPerimeterInvitation, withSellerIdentity, } from "./extension.js";
+export { X_PAYMENT_HEADER, X_PAYMENT_IDENTITY_HEADER, attachIdentityProof, identityProofHeaderValue, 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 { fetchVerificationKeys, findKey, keyFor } from "./keys.js";
+export { NO_SIGNAL_TITLE, badgeLabel, badgeState, badgeTitle, embedVerificationBadge, renderBadge, } from "./badge.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

package/dist/keys.d.ts

@@ -1,3 +1,5 @@
+import type { ClientDeclaration } from './client.js';
+import { type Verdict } from './verdict.js';
 /** One published verification key. */
 export type VerificationKey = {
     /** First 8 bytes of the public key's SHA-256, hex — matches `Verdict.keyId`. */
@@ -5,6 +7,12 @@ export type VerificationKey = {
     algorithm: 'Ed25519';
     /** Raw 32-byte public key, base64. */
     publicKey: string;
+    /**
+     * `current` signs new verdicts; `previous` keys stay published for at least
+     * the re-check window after a rotation, so verdicts signed before it keep
+     * verifying. Select by `keyId` (`findKey`), never by position or status.
+     */
+    status?: 'current' | 'previous';
 };
 /**
  * Fetches the published verification keys. Resolves to `undefined` — never
@@ -12,6 +20,19 @@ export type VerificationKey = {
  */
 export declare function fetchVerificationKeys(baseUrl: string, options?: {
     timeoutMs?: number;
+    client?: ClientDeclaration;
 }): Promise<VerificationKey[] | undefined>;
-/** Picks the key a verdict was signed with, by `keyId`. */
+/**
+ * Picks the key a verdict was signed with, by `keyId` — never by position:
+ * after a rotation the `previous` key is still the right one for a verdict
+ * signed before it.
+ */
 export declare function findKey(keys: readonly VerificationKey[] | undefined, keyId: string | undefined): VerificationKey | undefined;
+/**
+ * The published key a verdict names (`verdict.keyId`), as its base64 public
+ * key — `undefined` when the verdict names none or a key that is not
+ * published. A positive claim that names an unpublished key cannot be
+ * checked against the published set: a consumer that holds the set treats it
+ * as `invalid` (the explorer client does).
+ */
+export declare function keyFor(verdict: Pick<Verdict, 'keyId'> | undefined, keys: readonly VerificationKey[] | undefined): string | undefined;