@zadq/x402 0.2.0 → 0.3.0

package/README.md

@@ -30,8 +30,30 @@ When the service serves its own statement about the seller's guarantee deposit
 beside the verdict, `readDepositDeclaration(verdict)` returns it — a state and
 a level band, never an amount — and `null` otherwise.
 
-Subpath exports: `verdict`, `extension`, `header`, `receipt`, `explorer`,
-`keys`, `webhook`, `holder` (Node only) — or everything from the root. The
+```ts
+import { embedVerificationBadge } from '@zadq/x402/badge';
+
+// Always renders: `human-backed · ≥ G`, `revoked` or `unknown`; never rejects.
+await embedVerificationBadge(document.getElementById('badge')!, {
+  baseUrl: 'https://api.zadq.net',
+  subject: { chain: 'base', payTo: '0x…', resourceUrl: 'https://…' },
+});
+```
+
+A fetched verdict is structurally checked and must be about the subject asked;
+anything else is no verdict, which every helper shows as `unknown`. The
+signature check never throws (`valid`, `invalid` or `unverifiable`); keys are
+selected by `keyId` from the published set, so a verdict signed before a key
+rotation keeps verifying. An inline verdict on a 402 is projected to the
+canonical v0 fields, so the emitted `identityPolicy` always fits MintID's closed
+schema.
+
+Subpath exports: `verdict`, `extension` (also as `payment-required`), `header`
+(also as `x-payment`), `receipt`, `badge`, `explorer`, `keys`, `webhook`, `client`,
+`holder` (Node only) — or everything from the root. The byte forms of the
+signed verdict, the `X-PAYMENT-IDENTITY` envelope and the issuer receipt are
+pinned by vectors in the test suite; a change to any of them is a major
+version. The
 contracts each module honours are documented at
 <https://zadq.info/docs/sdk>; the modules are also available as copy-in files
 in the repository's `snippets/` folder for integrators who prefer to vendor.

package/dist/badge.d.ts

@@ -0,0 +1,51 @@
+import { type Verdict, type VerdictSubject } from './verdict.js';
+/** What the badge shows. Everything uncertain is "unknown". */
+export type BadgeState = 'human-backed' | 'revoked' | 'unknown';
+/** The tooltip when no verification signal is available. */
+export declare const NO_SIGNAL_TITLE = "No verification signal available \u2014 nothing in this flow depends on it.";
+/**
+ * The state a verdict maps to: `human_backed` → `human-backed`, `revoked` →
+ * `revoked`; `stale`, `no_signal`, no verdict and anything that is not a
+ * structurally valid verdict → `unknown`. Pure; never throws.
+ */
+export declare function badgeState(verdict: Verdict | undefined | null): BadgeState;
+/**
+ * The badge's text: `human-backed · ≥ <assuranceLevel>` (U+00B7, U+2265,
+ * single spaces) for the positive claim with a grade; otherwise the state
+ * itself (`human-backed`, `revoked`, `unknown`).
+ */
+export declare function badgeLabel(state: BadgeState, verdict?: Verdict | null): string;
+/**
+ * The badge's tooltip: `Verified at <verifiedAt> · re-checked every <N> h`
+ * (the time as transported, and the cadence promise the verdict carries),
+ * plus ` · re-check overdue` when the verdict is older than its promise. With
+ * no verdict, or no `verifiedAt`, the no-signal sentence (`NO_SIGNAL_TITLE`).
+ */
+export declare function badgeTitle(verdict: Verdict | undefined | null, now?: Date): string;
+export type BadgeOptions = {
+    /** Base URL of the verification service (its free path is used). */
+    baseUrl: string;
+    /** The endpoint the badge speaks about. */
+    subject: VerdictSubject;
+    /**
+     * Optional verification public key (base64, 32 raw bytes). When given, a
+     * positive claim whose signature is `invalid` renders "unknown"; one the
+     * runtime cannot check (`unverifiable`) is shown as delivered.
+     */
+    publicKey?: string;
+    /** Fetch timeout in milliseconds (default 3000). */
+    timeoutMs?: number;
+};
+/**
+ * Fetches the endpoint's verdict and renders the badge into `container`: one
+ * `<span>` with the label as its text, the tooltip as its `title`,
+ * `data-verification-badge="<state>"` and an inline pill style, replacing the
+ * container's children. Resolves to the state shown. Never rejects: whatever
+ * the service answers — or if it does not — a badge is rendered.
+ */
+export declare function embedVerificationBadge(container: Element, options: BadgeOptions): Promise<BadgeState>;
+/**
+ * Renders a badge for a verdict the caller already holds (inline in a 402,
+ * from a webhook, from the explorer client). Same element as the embed.
+ */
+export declare function renderBadge(container: Element, state: BadgeState, verdict?: Verdict | null): void;

package/dist/badge.js

@@ -0,0 +1,103 @@
+// Badge snippet — the verification badge an explorer, a listing or a seller's
+// own page shows next to an x402 endpoint.
+//
+// Vendor this file with verdict.ts. Zero runtime dependencies; the DOM embed
+// uses only `ownerDocument.createElement` and `replaceChildren`.
+//
+// Graceful degradation, by design: the badge always renders. No verdict, a
+// malformed answer, an unreachable service or a positive claim whose
+// signature does not check all render the "unknown" badge, and the rest of
+// the page is unaffected — the embed never rejects.
+import { BADGE_CLIENT } from "./client.js";
+import { fetchVerdict, freshness, isVerdict, verifyVerdictSignature, } from "./verdict.js";
+/** The tooltip when no verification signal is available. */
+export const NO_SIGNAL_TITLE = 'No verification signal available — nothing in this flow depends on it.';
+/**
+ * The state a verdict maps to: `human_backed` → `human-backed`, `revoked` →
+ * `revoked`; `stale`, `no_signal`, no verdict and anything that is not a
+ * structurally valid verdict → `unknown`. Pure; never throws.
+ */
+export function badgeState(verdict) {
+    if (!isVerdict(verdict))
+        return 'unknown';
+    if (verdict.outcome === 'human_backed')
+        return 'human-backed';
+    if (verdict.outcome === 'revoked')
+        return 'revoked';
+    return 'unknown';
+}
+/**
+ * The badge's text: `human-backed · ≥ <assuranceLevel>` (U+00B7, U+2265,
+ * single spaces) for the positive claim with a grade; otherwise the state
+ * itself (`human-backed`, `revoked`, `unknown`).
+ */
+export function badgeLabel(state, verdict) {
+    const grade = isVerdict(verdict) ? verdict.assuranceLevel : undefined;
+    if (state === 'human-backed' && grade !== undefined) {
+        return `human-backed · ≥ ${grade}`;
+    }
+    return state;
+}
+/**
+ * The badge's tooltip: `Verified at <verifiedAt> · re-checked every <N> h`
+ * (the time as transported, and the cadence promise the verdict carries),
+ * plus ` · re-check overdue` when the verdict is older than its promise. With
+ * no verdict, or no `verifiedAt`, the no-signal sentence (`NO_SIGNAL_TITLE`).
+ */
+export function badgeTitle(verdict, now = new Date()) {
+    if (!isVerdict(verdict) || verdict.verifiedAt === undefined)
+        return NO_SIGNAL_TITLE;
+    const base = `Verified at ${verdict.verifiedAt} · re-checked every ${verdict.recheckEveryHours} h`;
+    return freshness(verdict, now) === 'overdue' ? `${base} · re-check overdue` : base;
+}
+const COLOURS = {
+    'human-backed': '#1a7f37',
+    revoked: '#b42318',
+    unknown: '#6b7280',
+};
+/**
+ * Fetches the endpoint's verdict and renders the badge into `container`: one
+ * `<span>` with the label as its text, the tooltip as its `title`,
+ * `data-verification-badge="<state>"` and an inline pill style, replacing the
+ * container's children. Resolves to the state shown. Never rejects: whatever
+ * the service answers — or if it does not — a badge is rendered.
+ */
+export async function embedVerificationBadge(container, options) {
+    let shown;
+    try {
+        shown = await fetchVerdict(options.baseUrl, options.subject, {
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            client: BADGE_CLIENT,
+        });
+        if (shown?.outcome === 'human_backed' && options.publicKey !== undefined) {
+            if ((await verifyVerdictSignature(shown, options.publicKey)) === 'invalid') {
+                shown = undefined;
+            }
+        }
+    }
+    catch {
+        shown = undefined;
+    }
+    const state = badgeState(shown);
+    try {
+        renderBadge(container, state, shown);
+    }
+    catch {
+        // A container that cannot take children leaves the page as it was.
+    }
+    return state;
+}
+/**
+ * Renders a badge for a verdict the caller already holds (inline in a 402,
+ * from a webhook, from the explorer client). Same element as the embed.
+ */
+export function renderBadge(container, state, verdict) {
+    const span = container.ownerDocument.createElement('span');
+    span.textContent = badgeLabel(state, verdict);
+    span.title = badgeTitle(verdict);
+    span.setAttribute('data-verification-badge', state);
+    span.setAttribute('style', 'display:inline-block;padding:0.125em 0.6em;border-radius:999px;' +
+        'font:500 0.75rem/1.5 system-ui,sans-serif;color:#fff;white-space:nowrap;' +
+        `background:${COLOURS[state]}`);
+    container.replaceChildren(span);
+}

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+/** This library's version, as its package manifest states it (a test keeps them equal). */
+export declare const SDK_VERSION = "0.3.0";
+/** The service's own clients. */
+export declare const CLIENT_CLASSES: readonly ["sdk", "mcp", "badge"];
+export type ClientClass = (typeof CLIENT_CLASSES)[number];
+/** Which client is calling: its class and its version (`major.minor.patch`). */
+export type ClientDeclaration = {
+    client: ClientClass;
+    version: string;
+};
+/** The library's own declaration, the default for every helper that calls the service. */
+export declare const SDK_CLIENT: ClientDeclaration;
+/** The library's badge (`badge.ts`): its own class, the library's version. */
+export declare const BADGE_CLIENT: ClientDeclaration;
+/** The header that carries the declaration. */
+export declare const CLIENT_HEADER = "user-agent";
+/**
+ * `<brand>-<class>/<version>`, e.g. the SDK's `…-sdk/0.2.0`; `undefined`
+ * for a class outside the enumeration or a version that is not three
+ * dot-separated numbers — nothing else can be carried.
+ */
+export declare function clientUserAgent(declaration?: ClientDeclaration): string | undefined;
+/** True where the runtime owns its User-Agent; false in a browser (window or worker). */
+export declare function runtimeDeclaresClient(): boolean;
+/** The headers a request to the service carries for the declaration: one, or none. */
+export declare function clientHeaders(declaration?: ClientDeclaration): Record<string, string>;

package/dist/client.js

@@ -0,0 +1,46 @@
+// The client class: the service's own clients say which one they are, so
+// the free path's aggregate counters can tell the SDK, the MCP server and
+// the badge apart from any other caller. The declaration is a fixed
+// User-Agent, `<brand>-<class>/<version>` — the client's name and version
+// and nothing else: never an identifier of the integrator, the page, the
+// agent or the person, and never anything a caller could fill in (the
+// class is a closed enumeration and the version is digits and dots).
+//
+// Browsers are left alone: there a User-Agent set by script is ignored or,
+// cross-origin, turns a simple request into a CORS preflight, so the
+// declaration is sent only where the runtime owns its User-Agent (Node,
+// Deno, Bun, edge workers). Nothing depends on it: a request without it is
+// answered exactly the same, and every helper still degrades to "unknown".
+import { BRAND } from "./brand.js";
+/** This library's version, as its package manifest states it (a test keeps them equal). */
+export const SDK_VERSION = '0.3.0';
+/** The service's own clients. */
+export const CLIENT_CLASSES = ['sdk', 'mcp', 'badge'];
+/** The library's own declaration, the default for every helper that calls the service. */
+export const SDK_CLIENT = { client: 'sdk', version: SDK_VERSION };
+/** The library's badge (`badge.ts`): its own class, the library's version. */
+export const BADGE_CLIENT = { client: 'badge', version: SDK_VERSION };
+/** The header that carries the declaration. */
+export const CLIENT_HEADER = 'user-agent';
+/**
+ * `<brand>-<class>/<version>`, e.g. the SDK's `…-sdk/0.2.0`; `undefined`
+ * for a class outside the enumeration or a version that is not three
+ * dot-separated numbers — nothing else can be carried.
+ */
+export function clientUserAgent(declaration = SDK_CLIENT) {
+    if (!CLIENT_CLASSES.includes(declaration.client))
+        return undefined;
+    if (!/^\d{1,4}\.\d{1,4}\.\d{1,4}$/.test(declaration.version))
+        return undefined;
+    return `${BRAND.toLowerCase()}-${declaration.client}/${declaration.version}`;
+}
+/** True where the runtime owns its User-Agent; false in a browser (window or worker). */
+export function runtimeDeclaresClient() {
+    const ua = globalThis.navigator?.userAgent;
+    return !(typeof ua === 'string' && ua.startsWith('Mozilla/'));
+}
+/** The headers a request to the service carries for the declaration: one, or none. */
+export function clientHeaders(declaration = SDK_CLIENT) {
+    const ua = clientUserAgent(declaration);
+    return ua !== undefined && runtimeDeclaresClient() ? { [CLIENT_HEADER]: ua } : {};
+}

package/dist/explorer.d.ts

@@ -1,3 +1,5 @@
+import type { ClientDeclaration } from './client.js';
+import { type VerificationKey } from './keys.js';
 import { type Freshness, type Verdict, type VerdictSubject } from './verdict.js';
 /** Display signal for one endpoint row. Everything uncertain is "unknown". */
 export type VerificationSignal = {
@@ -23,10 +25,19 @@ export type VerificationClientOptions = {
      * as delivered — the listing keeps working either way.
      */
     publicKey?: string;
+    /**
+     * Optional published key set (`fetchVerificationKeys`), used instead of
+     * `publicKey`: each positive claim is checked with the key its `keyId`
+     * names, `current` or `previous`. A positive claim naming no published key
+     * is demoted to "unknown".
+     */
+    keys?: readonly VerificationKey[];
     /** Fetch timeout in milliseconds (default 3000). */
     timeoutMs?: number;
     /** In-memory cache TTL in milliseconds (default 5 minutes; 0 disables). */
     cacheTtlMs?: number;
+    /** Which of the service's clients is calling (default: this library). See client.ts. */
+    client?: ClientDeclaration;
 };
 export type VerificationClient = {
     /** Resolves the display signal for one endpoint. Never rejects. */
@@ -40,8 +51,10 @@ export type VerificationClient = {
 export declare function createVerificationClient(options: VerificationClientOptions): VerificationClient;
 /**
  * Maps a verdict (or its absence) to the display signal, optionally checking
- * the signature of positive claims locally. Exported for callers that already
- * hold a verdict — e.g. one delivered inline in a `PaymentRequired` extension
- * (extension.ts) or by a webhook.
+ * the signature of positive claims locally — against one public key (base64)
+ * or against a published key set, selected by the verdict's `keyId`. Exported
+ * for callers that already hold a verdict — e.g. one delivered inline in a
+ * `PaymentRequired` extension (extension.ts) or by a webhook. Anything that is
+ * not a structurally valid verdict maps to "unknown"; never rejects.
  */
-export declare function toSignal(verdict: Verdict | undefined, publicKey?: string): Promise<VerificationSignal>;
+export declare function toSignal(verdict: Verdict | undefined | null, key?: string | readonly VerificationKey[]): Promise<VerificationSignal>;

package/dist/explorer.js

@@ -5,7 +5,8 @@
 // for. Graceful degradation, by design: a listing keeps rendering exactly as
 // before when no verification response is available — the signal degrades to
 // "unknown", it never becomes an error state, a spinner or a blocked row.
-import { canonicalPayTo, fetchVerdict, freshness, verifyVerdictSignature, } from "./verdict.js";
+import { keyFor } from "./keys.js";
+import { canonicalPayTo, fetchVerdict, freshness, isVerdict, verifyVerdictSignature, } from "./verdict.js";
 /** The signal rendered when no verdict is available. Rendering never blocks on it. */
 export const UNKNOWN_SIGNAL = { state: 'unknown', freshness: 'unknown' };
 /**
@@ -17,8 +18,11 @@ export function createVerificationClient(options) {
     const ttl = options.cacheTtlMs ?? 300_000;
     const cache = new Map();
     async function resolve(subject) {
-        const verdict = await fetchVerdict(options.baseUrl, subject, options.timeoutMs === undefined ? undefined : { timeoutMs: options.timeoutMs });
-        return toSignal(verdict, options.publicKey);
+        const verdict = await fetchVerdict(options.baseUrl, subject, {
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.client === undefined ? {} : { client: options.client }),
+        });
+        return toSignal(verdict, options.keys ?? options.publicKey);
     }
     return {
         async signalFor(subject) {
@@ -43,16 +47,24 @@ export function createVerificationClient(options) {
 }
 /**
  * Maps a verdict (or its absence) to the display signal, optionally checking
- * the signature of positive claims locally. Exported for callers that already
- * hold a verdict — e.g. one delivered inline in a `PaymentRequired` extension
- * (extension.ts) or by a webhook.
+ * the signature of positive claims locally — against one public key (base64)
+ * or against a published key set, selected by the verdict's `keyId`. Exported
+ * for callers that already hold a verdict — e.g. one delivered inline in a
+ * `PaymentRequired` extension (extension.ts) or by a webhook. Anything that is
+ * not a structurally valid verdict maps to "unknown"; never rejects.
  */
-export async function toSignal(verdict, publicKey) {
-    if (verdict === undefined) {
+export async function toSignal(verdict, key) {
+    if (!isVerdict(verdict)) {
         return UNKNOWN_SIGNAL;
     }
-    if (verdict.outcome === 'human_backed' && publicKey !== undefined) {
-        const check = await verifyVerdictSignature(verdict, publicKey);
+    if (verdict.outcome === 'human_backed' && key !== undefined) {
+        const publicKey = typeof key === 'string' ? key : keyFor(verdict, key);
+        // A signed positive claim naming no published key cannot match the set.
+        const check = publicKey !== undefined
+            ? await verifyVerdictSignature(verdict, publicKey)
+            : verdict.signature === undefined
+                ? 'unverifiable'
+                : 'invalid';
         if (check === 'invalid') {
             // An unverified positive claim is not displayed; the row still renders.
             return UNKNOWN_SIGNAL;

package/dist/extension.d.ts

@@ -1,4 +1,4 @@
-import type { Verdict } from './verdict.js';
+import { type Verdict } from './verdict.js';
 /**
  * The identity policy a seller advertises on its 402 response, following the
  * bIP-0002 profile — sub-profile `bip-0002/0-seller`, the canonical v0 seller
@@ -59,17 +59,31 @@ export declare const IDENTITY_POLICY_EXTENSION = "identityPolicy";
 export declare const PERIMETER_EXTENSION = "trustPerimeter";
 /**
  * Seller side: returns a copy of the 402 body with the identity policy
- * attached under `extensions.identityPolicy`. Existing extensions are
- * preserved. Only the canonical fields are emitted, so the object always
- * validates against the closed v0 seller schema whatever else the caller's
- * policy value carried.
+ * attached under `extensions.identityPolicy`. The input is not mutated;
+ * existing extensions are preserved and `x402Version`, `error` and `accepts`
+ * are never touched. Only the canonical fields are emitted — the inline
+ * verdict projected by `canonicalInlineVerdict` — so the object validates
+ * against the closed v0 seller schema whatever else the caller's policy value
+ * carried, a live verdict's `extensions` included.
  */
 export declare function withIdentityPolicy<T extends PaymentRequiredBody>(body: T, policy: IdentityPolicy): T;
+/**
+ * The inline verdict reduced to the fields of the canonical v0 seller object:
+ * `outcome`, `reason` (never beside `human_backed`), `subject` {chain, payTo,
+ * resourceUrl}, `assuranceLevel`, `verifiedAt`, `recheckEveryHours`,
+ * `signature` and `keyId`. Everything else — the verifying party's own
+ * `extensions` beside the verdict included — is dropped, so a verdict taken
+ * straight from the free path keeps the closed schema valid; the signed bytes
+ * are all kept, so it verifies exactly as the fetched one does. Anything that
+ * is not a structurally valid verdict gives `undefined` (no inline verdict).
+ */
+export declare function canonicalInlineVerdict(verdict: unknown): Verdict | undefined;
 /**
  * Counterparty side: reads the identity policy from a 402 body, if present
  * and well-formed. Returns `undefined` otherwise — an absent or malformed
  * policy is a normal state, and the payment flow proceeds unchanged. Fields
- * outside the canonical object are dropped, never fatal.
+ * outside the canonical object are dropped, never fatal; an inline verdict
+ * that is not structurally valid is dropped and the policy kept.
  */
 export declare function readIdentityPolicy(body: PaymentRequiredBody): IdentityPolicy | undefined;
 /**

package/dist/extension.js

@@ -10,16 +10,19 @@
 // and with no round-trip, or later via the free verification path. Absence of
 // the extension, of a verdict, or of any verification response changes
 // nothing in either party's flow.
+import { isVerdict } from "./verdict.js";
 /** Extension key defined by the bIP-0002 profile for the identity policy. */
 export const IDENTITY_POLICY_EXTENSION = 'identityPolicy';
 /** The vendor-owned extension key the trust-perimeter invitation rides under. */
 export const PERIMETER_EXTENSION = 'trustPerimeter';
 /**
  * Seller side: returns a copy of the 402 body with the identity policy
- * attached under `extensions.identityPolicy`. Existing extensions are
- * preserved. Only the canonical fields are emitted, so the object always
- * validates against the closed v0 seller schema whatever else the caller's
- * policy value carried.
+ * attached under `extensions.identityPolicy`. The input is not mutated;
+ * existing extensions are preserved and `x402Version`, `error` and `accepts`
+ * are never touched. Only the canonical fields are emitted — the inline
+ * verdict projected by `canonicalInlineVerdict` — so the object validates
+ * against the closed v0 seller schema whatever else the caller's policy value
+ * carried, a live verdict's `extensions` included.
  */
 export function withIdentityPolicy(body, policy) {
     const canonical = {
@@ -27,20 +30,59 @@ export function withIdentityPolicy(body, policy) {
         assuranceAtLeast: policy.assuranceAtLeast,
         verifyUrl: policy.verifyUrl,
     };
-    if (policy.verdict !== undefined)
-        canonical.verdict = policy.verdict;
+    const verdict = canonicalInlineVerdict(policy.verdict);
+    if (verdict !== undefined)
+        canonical.verdict = verdict;
     return {
         ...body,
         extensions: { ...body.extensions, [IDENTITY_POLICY_EXTENSION]: canonical },
     };
 }
+/**
+ * The inline verdict reduced to the fields of the canonical v0 seller object:
+ * `outcome`, `reason` (never beside `human_backed`), `subject` {chain, payTo,
+ * resourceUrl}, `assuranceLevel`, `verifiedAt`, `recheckEveryHours`,
+ * `signature` and `keyId`. Everything else — the verifying party's own
+ * `extensions` beside the verdict included — is dropped, so a verdict taken
+ * straight from the free path keeps the closed schema valid; the signed bytes
+ * are all kept, so it verifies exactly as the fetched one does. Anything that
+ * is not a structurally valid verdict gives `undefined` (no inline verdict).
+ */
+export function canonicalInlineVerdict(verdict) {
+    if (!isVerdict(verdict))
+        return undefined;
+    const out = {
+        outcome: verdict.outcome,
+        subject: {
+            chain: verdict.subject.chain,
+            payTo: verdict.subject.payTo,
+            resourceUrl: verdict.subject.resourceUrl,
+        },
+        recheckEveryHours: verdict.recheckEveryHours,
+    };
+    if (verdict.reason !== undefined && verdict.outcome !== 'human_backed') {
+        out.reason = verdict.reason;
+    }
+    if (verdict.assuranceLevel !== undefined)
+        out.assuranceLevel = verdict.assuranceLevel;
+    if (verdict.verifiedAt !== undefined)
+        out.verifiedAt = verdict.verifiedAt;
+    if (verdict.signature !== undefined)
+        out.signature = verdict.signature;
+    if (verdict.keyId !== undefined)
+        out.keyId = verdict.keyId;
+    return out;
+}
 /**
  * Counterparty side: reads the identity policy from a 402 body, if present
  * and well-formed. Returns `undefined` otherwise — an absent or malformed
  * policy is a normal state, and the payment flow proceeds unchanged. Fields
- * outside the canonical object are dropped, never fatal.
+ * outside the canonical object are dropped, never fatal; an inline verdict
+ * that is not structurally valid is dropped and the policy kept.
  */
 export function readIdentityPolicy(body) {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
     const raw = body.extensions?.[IDENTITY_POLICY_EXTENSION];
     if (typeof raw !== 'object' || raw === null) {
         return undefined;
@@ -56,10 +98,11 @@ export function readIdentityPolicy(body) {
         assuranceAtLeast: policy['assuranceAtLeast'],
         verifyUrl: policy['verifyUrl'],
     };
-    const verdict = policy['verdict'];
-    if (typeof verdict === 'object' && verdict !== null) {
+    // An inline verdict that is not structurally valid is dropped, the policy
+    // kept; a valid one is read back in its canonical fields only.
+    const verdict = canonicalInlineVerdict(policy['verdict']);
+    if (verdict !== undefined)
         read.verdict = verdict;
-    }
     return read;
 }
 /**
@@ -83,6 +126,8 @@ export function withPerimeterInvitation(body, invitation) {
  * exactly as before.
  */
 export function readPerimeterInvitation(body) {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
     const raw = body.extensions?.[PERIMETER_EXTENSION];
     if (typeof raw !== 'object' || raw === null)
         return undefined;

package/dist/header.d.ts

@@ -17,14 +17,24 @@ export type IdentityProof = {
 };
 type HeaderRecord = Record<string, string>;
 /**
- * Sender side: attaches the identity proof next to `X-PAYMENT`. Returns the
- * same headers object/record for chaining.
+ * The exact header value for a proof: base64url without padding (RFC 4648
+ * §5) of the compact UTF-8 JSON `{"version":1,"format":…,"payload":…}`, keys
+ * in that order and nothing else. Any change to these bytes is a major
+ * version of the package.
+ */
+export declare function identityProofHeaderValue(proof: IdentityProof): string;
+/**
+ * Sender side: attaches the identity proof next to `X-PAYMENT` (which is
+ * never read or modified). Mutates and returns the same headers
+ * object/record for chaining.
  */
 export declare function attachIdentityProof<T extends Headers | HeaderRecord>(headers: T, proof: IdentityProof): T;
 /**
- * Receiver side: reads the identity proof, if present and well-formed.
- * Returns `undefined` otherwise — an absent or malformed proof is a normal
- * state; handle the request exactly as you would without the header.
+ * Receiver side: reads the identity proof, if present and well-formed — the
+ * header name case-insensitively, the value with or without padding. Returns
+ * `undefined` otherwise — an absent or malformed proof is a normal state;
+ * handle the request exactly as you would without the header. Only the three
+ * envelope fields are returned.
  */
 export declare function readIdentityProof(headers: Headers | HeaderRecord): IdentityProof | undefined;
 export {};

package/dist/header.js

@@ -16,11 +16,21 @@ export const X_PAYMENT_HEADER = 'X-PAYMENT';
 /** Companion header defined by the bIP-0002 profile for the identity proof. */
 export const X_PAYMENT_IDENTITY_HEADER = 'X-PAYMENT-IDENTITY';
 /**
- * Sender side: attaches the identity proof next to `X-PAYMENT`. Returns the
- * same headers object/record for chaining.
+ * The exact header value for a proof: base64url without padding (RFC 4648
+ * §5) of the compact UTF-8 JSON `{"version":1,"format":…,"payload":…}`, keys
+ * in that order and nothing else. Any change to these bytes is a major
+ * version of the package.
+ */
+export function identityProofHeaderValue(proof) {
+    return base64UrlEncode(JSON.stringify({ version: proof.version, format: proof.format, payload: proof.payload }));
+}
+/**
+ * Sender side: attaches the identity proof next to `X-PAYMENT` (which is
+ * never read or modified). Mutates and returns the same headers
+ * object/record for chaining.
  */
 export function attachIdentityProof(headers, proof) {
-    const value = base64UrlEncode(JSON.stringify(proof));
+    const value = identityProofHeaderValue(proof);
     if (headers instanceof Headers) {
         headers.set(X_PAYMENT_IDENTITY_HEADER, value);
     }
@@ -30,25 +40,28 @@ export function attachIdentityProof(headers, proof) {
     return headers;
 }
 /**
- * Receiver side: reads the identity proof, if present and well-formed.
- * Returns `undefined` otherwise — an absent or malformed proof is a normal
- * state; handle the request exactly as you would without the header.
+ * Receiver side: reads the identity proof, if present and well-formed — the
+ * header name case-insensitively, the value with or without padding. Returns
+ * `undefined` otherwise — an absent or malformed proof is a normal state;
+ * handle the request exactly as you would without the header. Only the three
+ * envelope fields are returned.
  */
 export function readIdentityProof(headers) {
-    const value = headers instanceof Headers
-        ? headers.get(X_PAYMENT_IDENTITY_HEADER)
-        : findHeader(headers, X_PAYMENT_IDENTITY_HEADER);
-    if (value === null || value === undefined || value === '') {
-        return undefined;
-    }
     try {
+        const value = headers instanceof Headers
+            ? headers.get(X_PAYMENT_IDENTITY_HEADER)
+            : findHeader(headers, X_PAYMENT_IDENTITY_HEADER);
+        if (typeof value !== 'string' || value === '') {
+            return undefined;
+        }
         const parsed = JSON.parse(base64UrlDecode(value));
-        if (parsed['version'] !== 1 ||
-            typeof parsed['format'] !== 'string' ||
-            typeof parsed['payload'] !== 'string') {
+        if (typeof parsed !== 'object' || parsed === null)
+            return undefined;
+        const p = parsed;
+        if (p['version'] !== 1 || typeof p['format'] !== 'string' || typeof p['payload'] !== 'string') {
             return undefined;
         }
-        return parsed;
+        return { version: 1, format: p['format'], payload: p['payload'] };
     }
     catch {
         return undefined;

package/dist/holder/chain.d.ts

@@ -1,5 +1,7 @@
 /** The chain query path of the issuer-scoped read. */
 export declare const RECORDED_NULLIFIERS_QUERY = "/identity.v1.selfrevoke.Query/RecordedNullifiers";
+/** After how long the chain prunes a record (`retention_seconds`, both networks). */
+export declare const RECORD_RETENTION_SECONDS = 3600;
 /** A recorded self-revocation's state on the chain, by revocation value (hex). */
 export type RecordedState = 'pending' | 'folded';
 export type ChainReadOptions = {
@@ -12,7 +14,10 @@ export declare function bytesField(field: number, value: Uint8Array): Uint8Array
 export declare function varintField(field: number, value: number): Uint8Array;
 export declare function hexToBytes(hex: string): Uint8Array;
 export declare function bytesToHex(bytes: Uint8Array): string;
-/** `QueryRecordedNullifiersRequest{issuer_id = 1}` — names no revocation value. */
+/**
+ * `QueryRecordedNullifiersRequest{issuer_id = 1}` — `0a20‖issuer_id`; names
+ * no revocation value. The issuer id is exactly 32 bytes.
+ */
 export declare function encodeIssuerQuery(issuerIdHex: string): Uint8Array;
 /**
  * `QueryRecordedNullifiersResponse{repeated RecordedNullifier records = 1}`