@zadq/x402 0.1.0 → 0.3.0

package/dist/keys.js

@@ -5,36 +5,54 @@
 // 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";
+import { freePathRequest } 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),
-        });
+        const res = await fetch(new URL('/v0/verification-keys', baseUrl), freePathRequest(options?.timeoutMs, options?.client));
         if (!res.ok) {
             return undefined;
         }
         const body = (await res.json());
-        if (!Array.isArray(body.keys)) {
+        if (body === null || typeof body !== 'object' || !Array.isArray(body.keys)) {
             return undefined;
         }
-        return body.keys.filter(isVerificationKey);
+        return body.keys.filter(isVerificationKey).map(project);
     }
     catch {
         return 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 function findKey(keys, keyId) {
     if (keys === undefined || keyId === undefined) {
         return undefined;
     }
     return keys.find((k) => k.keyId === keyId);
 }
+/**
+ * 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 function keyFor(verdict, keys) {
+    return findKey(keys, verdict?.keyId)?.publicKey;
+}
+function project(k) {
+    const out = { keyId: k.keyId, algorithm: 'Ed25519', publicKey: k.publicKey };
+    if (k.status === 'current' || k.status === 'previous')
+        out.status = k.status;
+    return out;
+}
 function isVerificationKey(value) {
     if (typeof value !== 'object' || value === null)
         return false;

package/dist/receipt.d.ts

@@ -43,8 +43,13 @@ export declare function verifyAttestationReceipt(receipt: AttestationReceipt, is
 /** 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).
+ * Canonical JSON as the issuer produces it — Python's
+ * `json.dumps(sort_keys=True, separators=(',', ':'), ensure_ascii=True)`:
+ * keys sorted by code point, no whitespace, integers as decimal (a
+ * non-integer number throws), strings with `"` and `\` escaped, `\b \f \n
+ * \r \t`, other control characters as `\u00xx`, and every character outside
+ * U+0020–U+007E — U+007F included — as lowercase `\uXXXX` per UTF-16 code
+ * unit (a non-BMP character as its surrogate pair). `<`, `>` and `&` stay raw.
+ * Any change to these bytes is a major version of the package.
  */
 export declare function canonicalJson(value: Record<string, string | number>): string;

package/dist/receipt.js

@@ -141,9 +141,14 @@ export async function receiptSigningInput(receipt) {
     return out;
 }
 /**
- * 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).
+ * Canonical JSON as the issuer produces it — Python's
+ * `json.dumps(sort_keys=True, separators=(',', ':'), ensure_ascii=True)`:
+ * keys sorted by code point, no whitespace, integers as decimal (a
+ * non-integer number throws), strings with `"` and `\` escaped, `\b \f \n
+ * \r \t`, other control characters as `\u00xx`, and every character outside
+ * U+0020–U+007E — U+007F included — as lowercase `\uXXXX` per UTF-16 code
+ * unit (a non-BMP character as its surrogate pair). `<`, `>` and `&` stay raw.
+ * Any change to these bytes is a major version of the package.
  */
 export function canonicalJson(value) {
     const keys = Object.keys(value).sort();
@@ -161,8 +166,9 @@ function jsonScalar(v) {
 }
 function jsonString(s) {
     const escaped = JSON.stringify(s);
-    // JSON.stringify leaves non-ASCII as-is; the issuer escapes it.
-    return escaped.replace(/[\u0080-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    // JSON.stringify leaves DEL and non-ASCII as-is (lone surrogates aside); the
+    // issuer escapes every code unit from U+007F up.
+    return escaped.replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
 }
 function hexDecode(hex, length) {
     if (!/^[0-9a-f]*$/.test(hex) || hex.length !== length * 2) {

package/dist/verdict.d.ts

@@ -1,10 +1,4 @@
-/**
- * The payment rails the seller rail covers (Platform Decision 14): USDC on
- * Base (`base`, an EVM address) or on Solana (`solana`). The contract is a
- * closed enumeration — the service answers a 400 problem to any other value,
- * and other EVM chains are not declared until a seller needs one — so the
- * type is the same closed union, not a string.
- */
+import { type ClientDeclaration } from './client.js';
 export type Chain = 'base' | 'solana';
 /** The declared rails, in the order the contract lists them. */
 export declare const CHAINS: readonly Chain[];
@@ -12,12 +6,18 @@ export declare const CHAINS: readonly Chain[];
 export declare function isChain(value: unknown): value is Chain;
 /** Verdict outcomes, mirroring the public API contract vocabulary. */
 export type VerdictOutcome = 'human_backed' | 'revoked' | 'stale' | 'no_signal';
+/** The outcome vocabulary as a runtime list (closed: anything else is not a verdict). */
+export declare const VERDICT_OUTCOMES: readonly VerdictOutcome[];
 /**
  * Why a verdict is not `human_backed`: the standing read's closed vocabulary
  * (MintID's, restated — never a flag of the service's own), or `suspended`
- * when the witnessed status is suspended. Never present on `human_backed`.
+ * when the witnessed status is suspended. Never present on `human_backed`,
+ * and never required anywhere: `revoked` carries none (the status is the
+ * reason), nor does a `no_signal` withheld by the deposit gate.
  */
 export type VerdictReason = 'state_unavailable' | 'issuer_unknown' | 'issuer_not_active' | 'status_root_stale' | 'height_stale' | 'witness_unavailable' | 'witness_malformed' | 'witness_invalid' | 'witness_root_mismatch' | 'bond_insufficient' | 'suspended';
+/** The reason vocabulary as a runtime list. */
+export declare const VERDICT_REASONS: readonly VerdictReason[];
 /** The x402 endpoint a verdict speaks about: chain-qualified payTo + resource URL. */
 export type VerdictSubject = {
     chain: Chain;
@@ -50,19 +50,83 @@ export type Verdict = {
     signature?: string;
     /** Identifies the verdict-signing key (first 8 bytes of the public key's SHA-256, hex). */
     keyId?: string;
-    /** Present on every non-positive outcome, from the closed vocabulary; absent on `human_backed`. */
+    /**
+     * Why the outcome is not positive, from the closed vocabulary — optional on
+     * every outcome: absent on `human_backed`, on `revoked` and on a `no_signal`
+     * withheld by the deposit gate. A missing reason is never malformed.
+     */
     reason?: VerdictReason;
+    /**
+     * The verifying party's own statements beside the canonical verdict, keyed
+     * by its brand in lower case (`VERDICT_EXTENSION_KEY`). Outside the signed
+     * bytes; absent on most verdicts. Read with `readDepositDeclaration`.
+     */
+    extensions?: Record<string, {
+        deposit?: DepositDeclaration;
+    } | undefined>;
 };
+/** The declaration's public states — one code per label of the seller's deposit, as the service publishes them. */
+export declare const DEPOSIT_DECLARATION_STATES: readonly ["required", "awaiting_funds", "held", "below_level", "claim_pending", "released_partial", "returning", "returned"];
+export type DepositDeclarationState = (typeof DEPOSIT_DECLARATION_STATES)[number];
+/** The band of the deposit, named by the schedule tier; the amount is never carried. */
+export declare const DEPOSIT_LEVELS: readonly ["attested_vendor", "regulated_compliance"];
+export type DepositLevel = (typeof DEPOSIT_LEVELS)[number];
+/**
+ * The service's own statement about the seller's guarantee deposit under its
+ * Terms, beside the verdict: a state and a level band read from the service's
+ * record at `verifiedAt` — never an amount, a balance or a holder reference.
+ * The identity network carries no fact about this deposit; the statement is
+ * the service's and sits outside the verdict's signed bytes.
+ */
+export type DepositDeclaration = {
+    state: DepositDeclarationState;
+    level: DepositLevel;
+    verifiedAt: string;
+};
+/**
+ * The deposit declaration a verdict carries, or `null` when it carries none
+ * (the deposit rail off, no deposit owed, or a reader that was served the
+ * verdict alone). Malformed content reads as none — nothing throws.
+ */
+export declare function readDepositDeclaration(verdict: Verdict | undefined | null): DepositDeclaration | null;
+/**
+ * Structural check of a verdict as the free path serves it: an object with an
+ * `outcome` from the closed vocabulary, a `subject` of the declared rails with
+ * string `payTo` and `resourceUrl`, an integer `recheckEveryHours`, and the
+ * optional fields (`assuranceLevel`, `verifiedAt`, `signature`, `keyId`,
+ * `reason`) strings when present. `reason` is never required, and unknown keys
+ * (top level or under `extensions`) are ignored, never fatal. Anything else —
+ * `null`, an array, a scalar, a missing subject — is not a verdict: treat it
+ * exactly like no verdict ("unknown").
+ */
+export declare function isVerdict(value: unknown): value is Verdict;
+/**
+ * Whether a served subject is the one that was asked about: `chain` and
+ * `resourceUrl` compared exactly, `payTo` in canonical form (case-insensitive
+ * on `base`, where EVM addresses are kept lowercase; exact on `solana`).
+ */
+export declare function subjectMatches(requested: VerdictSubject, served: VerdictSubject): boolean;
 export declare const DEFAULT_TIMEOUT_MS = 3000;
+/**
+ * The one place the free path's requests are built (verdicts, keys, the
+ * badge): anonymous — no credentials, no cookies — and bounded by the
+ * timeout. The client-declaring User-Agent, where the runtime allows one, is
+ * added here and nowhere else.
+ */
+export declare function freePathRequest(timeoutMs?: number, client?: ClientDeclaration): RequestInit;
 /**
  * Fetches the current verdict for an endpoint from the free verification path.
  *
  * Degradation path: resolves to `undefined` — never rejects — on timeout,
- * network failure or a non-OK response. Treat `undefined` exactly like a
+ * network failure, a non-OK response, a body that is not JSON, a 2xx body
+ * that is not a structurally valid verdict (`isVerdict`), or a verdict about
+ * another subject (`subjectMatches`). Treat `undefined` exactly like a
  * `no_signal` outcome: show "unknown" and carry on.
  */
 export declare function fetchVerdict(baseUrl: string, subject: VerdictSubject, options?: {
     timeoutMs?: number;
+    /** Which of the service's clients is calling (default: this library). See client.ts. */
+    client?: ClientDeclaration;
 }): Promise<Verdict | undefined>;
 /** Freshness against the cadence promise the verdict itself carries. */
 export type Freshness = 'fresh' | 'overdue' | 'unknown';
@@ -75,21 +139,27 @@ export type Freshness = 'fresh' | 'overdue' | 'unknown';
 export declare function freshness(verdict: Verdict, now?: Date): Freshness;
 /**
  * Renders the canonical signed statement byte-for-byte as the service signs
- * it: fixed key order, RFC 3339 UTC at second precision, and Go-style JSON
- * escaping of `<`, `>` and `&`. Returns `undefined` when the verdict lacks
- * the fields a signed (positive) claim always carries.
+ * it (Go `encoding/json` of a flat struct): fixed key order `chain`, `payTo`,
+ * `resourceUrl`, `outcome`, `assuranceLevel`, `verifiedAt`,
+ * `recheckEveryHours`; no whitespace; UTF-8 with non-ASCII raw; `<`, `>`, `&`,
+ * U+2028 and U+2029 escaped as Go does; `verifiedAt` in UTC truncated to whole
+ * seconds. Returns `undefined` ("cannot build") when the verdict lacks the
+ * fields a signed (positive) claim always carries, or they are ill-typed.
+ * Any change to these bytes is a major version of the package.
  */
 export declare function canonicalVerdictPayload(verdict: Verdict): Uint8Array<ArrayBuffer> | undefined;
 /** Outcome of a local signature check. */
 export type SignatureCheck = 'valid' | 'invalid' | 'unverifiable';
 /**
  * Verifies the verdict's Ed25519 signature locally against a known public key
- * (base64, 32 raw bytes) — no round-trip involved.
+ * (base64, 32 raw bytes) — no round-trip involved. Never throws or rejects,
+ * whatever the verdict's shape.
  *
  * Degradation path: `unverifiable` (missing signature, or no Ed25519 support
  * in the runtime's WebCrypto) is not a negative finding — display the verdict
  * as usual, or fall back to "unknown" if your policy prefers only locally
- * checked claims. `invalid` means the bytes do not match the key: treat as
+ * checked claims. `invalid` means the bytes, the base64 or the key do not
+ * match (a signature whose signed bytes cannot be built included): treat as
  * "unknown".
  */
 export declare function verifyVerdictSignature(verdict: Verdict, publicKeyBase64: string): Promise<SignatureCheck>;

package/dist/verdict.js

@@ -10,12 +10,42 @@
 // or an absent verdict as "no signal". Nothing here throws on network failure
 // and nothing blocks your payment flow — your integration keeps working
 // unchanged when no verification response is available.
+/**
+ * The payment rails the seller rail covers (Platform Decision 14): USDC on
+ * Base (`base`, an EVM address) or on Solana (`solana`). The contract is a
+ * closed enumeration — the service answers a 400 problem to any other value,
+ * and other EVM chains are not declared until a seller needs one — so the
+ * type is the same closed union, not a string.
+ */
+import { VERDICT_EXTENSION_KEY } from "./brand.js";
+import { SDK_CLIENT, clientHeaders } from "./client.js";
 /** The declared rails, in the order the contract lists them. */
 export const CHAINS = ['base', 'solana'];
 /** Runtime guard for the `Chain` enumeration (input from a wire, an agent or an env var). */
 export function isChain(value) {
     return typeof value === 'string' && CHAINS.includes(value);
 }
+/** The outcome vocabulary as a runtime list (closed: anything else is not a verdict). */
+export const VERDICT_OUTCOMES = [
+    'human_backed',
+    'revoked',
+    'stale',
+    'no_signal',
+];
+/** The reason vocabulary as a runtime list. */
+export const VERDICT_REASONS = [
+    'state_unavailable',
+    'issuer_unknown',
+    'issuer_not_active',
+    'status_root_stale',
+    'height_stale',
+    'witness_unavailable',
+    'witness_malformed',
+    'witness_invalid',
+    'witness_root_mismatch',
+    'bond_insufficient',
+    'suspended',
+];
 /**
  * The address as the service stores and echoes it. An EVM address (`base`)
  * is case-insensitive — its checksum and lowercase spellings name the same
@@ -33,12 +63,100 @@ export function canonicalPayTo(chain, payTo) {
 export function canonicalSubject(subject) {
     return { ...subject, payTo: canonicalPayTo(subject.chain, subject.payTo) };
 }
+/** The declaration's public states — one code per label of the seller's deposit, as the service publishes them. */
+export const DEPOSIT_DECLARATION_STATES = [
+    'required',
+    'awaiting_funds',
+    'held',
+    'below_level',
+    'claim_pending',
+    'released_partial',
+    'returning',
+    'returned',
+];
+/** The band of the deposit, named by the schedule tier; the amount is never carried. */
+export const DEPOSIT_LEVELS = ['attested_vendor', 'regulated_compliance'];
+/**
+ * The deposit declaration a verdict carries, or `null` when it carries none
+ * (the deposit rail off, no deposit owed, or a reader that was served the
+ * verdict alone). Malformed content reads as none — nothing throws.
+ */
+export function readDepositDeclaration(verdict) {
+    const d = verdict?.extensions?.[VERDICT_EXTENSION_KEY]?.deposit;
+    if (typeof d !== 'object' || d === null)
+        return null;
+    const { state, level, verifiedAt } = d;
+    if (!DEPOSIT_DECLARATION_STATES.includes(String(state)))
+        return null;
+    if (!DEPOSIT_LEVELS.includes(String(level)))
+        return null;
+    if (typeof verifiedAt !== 'string' || Number.isNaN(Date.parse(verifiedAt)))
+        return null;
+    return { state: state, level: level, verifiedAt };
+}
+/**
+ * Structural check of a verdict as the free path serves it: an object with an
+ * `outcome` from the closed vocabulary, a `subject` of the declared rails with
+ * string `payTo` and `resourceUrl`, an integer `recheckEveryHours`, and the
+ * optional fields (`assuranceLevel`, `verifiedAt`, `signature`, `keyId`,
+ * `reason`) strings when present. `reason` is never required, and unknown keys
+ * (top level or under `extensions`) are ignored, never fatal. Anything else —
+ * `null`, an array, a scalar, a missing subject — is not a verdict: treat it
+ * exactly like no verdict ("unknown").
+ */
+export function isVerdict(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const v = value;
+    if (!VERDICT_OUTCOMES.includes(v['outcome']))
+        return false;
+    const subject = v['subject'];
+    if (typeof subject !== 'object' || subject === null || Array.isArray(subject))
+        return false;
+    const s = subject;
+    if (!isChain(s['chain']) || typeof s['payTo'] !== 'string')
+        return false;
+    if (typeof s['resourceUrl'] !== 'string')
+        return false;
+    if (!Number.isInteger(v['recheckEveryHours']))
+        return false;
+    for (const key of ['assuranceLevel', 'verifiedAt', 'signature', 'keyId', 'reason']) {
+        if (v[key] !== undefined && typeof v[key] !== 'string')
+            return false;
+    }
+    return true;
+}
+/**
+ * Whether a served subject is the one that was asked about: `chain` and
+ * `resourceUrl` compared exactly, `payTo` in canonical form (case-insensitive
+ * on `base`, where EVM addresses are kept lowercase; exact on `solana`).
+ */
+export function subjectMatches(requested, served) {
+    return (requested.chain === served.chain &&
+        requested.resourceUrl === served.resourceUrl &&
+        canonicalPayTo(requested.chain, requested.payTo) === canonicalPayTo(served.chain, served.payTo));
+}
 export const DEFAULT_TIMEOUT_MS = 3000;
+/**
+ * The one place the free path's requests are built (verdicts, keys, the
+ * badge): anonymous — no credentials, no cookies — and bounded by the
+ * timeout. The client-declaring User-Agent, where the runtime allows one, is
+ * added here and nowhere else.
+ */
+export function freePathRequest(timeoutMs = DEFAULT_TIMEOUT_MS, client = SDK_CLIENT) {
+    return {
+        credentials: 'omit',
+        headers: clientHeaders(client),
+        signal: AbortSignal.timeout(timeoutMs),
+    };
+}
 /**
  * Fetches the current verdict for an endpoint from the free verification path.
  *
  * Degradation path: resolves to `undefined` — never rejects — on timeout,
- * network failure or a non-OK response. Treat `undefined` exactly like a
+ * network failure, a non-OK response, a body that is not JSON, a 2xx body
+ * that is not a structurally valid verdict (`isVerdict`), or a verdict about
+ * another subject (`subjectMatches`). Treat `undefined` exactly like a
  * `no_signal` outcome: show "unknown" and carry on.
  */
 export async function fetchVerdict(baseUrl, subject, options) {
@@ -47,13 +165,12 @@ export async function fetchVerdict(baseUrl, subject, options) {
     url.searchParams.set('payTo', subject.payTo);
     url.searchParams.set('resourceUrl', subject.resourceUrl);
     try {
-        const res = await fetch(url, {
-            signal: AbortSignal.timeout(options?.timeoutMs ?? DEFAULT_TIMEOUT_MS),
-        });
+        const res = await fetch(url, freePathRequest(options?.timeoutMs, options?.client));
         if (!res.ok) {
             return undefined;
         }
-        return (await res.json());
+        const body = await res.json();
+        return isVerdict(body) && subjectMatches(subject, body.subject) ? body : undefined;
     }
     catch {
         // No signal is a normal state, never an error surface.
@@ -67,7 +184,7 @@ export async function fetchVerdict(baseUrl, subject, options) {
  * any further round-trip.
  */
 export function freshness(verdict, now = new Date()) {
-    if (verdict.verifiedAt === undefined) {
+    if (typeof verdict?.verifiedAt !== 'string' || !Number.isFinite(verdict.recheckEveryHours)) {
         return 'unknown';
     }
     const verified = Date.parse(verdict.verifiedAt);
@@ -79,12 +196,27 @@ export function freshness(verdict, now = new Date()) {
 }
 /**
  * Renders the canonical signed statement byte-for-byte as the service signs
- * it: fixed key order, RFC 3339 UTC at second precision, and Go-style JSON
- * escaping of `<`, `>` and `&`. Returns `undefined` when the verdict lacks
- * the fields a signed (positive) claim always carries.
+ * it (Go `encoding/json` of a flat struct): fixed key order `chain`, `payTo`,
+ * `resourceUrl`, `outcome`, `assuranceLevel`, `verifiedAt`,
+ * `recheckEveryHours`; no whitespace; UTF-8 with non-ASCII raw; `<`, `>`, `&`,
+ * U+2028 and U+2029 escaped as Go does; `verifiedAt` in UTC truncated to whole
+ * seconds. Returns `undefined` ("cannot build") when the verdict lacks the
+ * fields a signed (positive) claim always carries, or they are ill-typed.
+ * Any change to these bytes is a major version of the package.
  */
 export function canonicalVerdictPayload(verdict) {
-    if (verdict.assuranceLevel === undefined || verdict.verifiedAt === undefined) {
+    if (typeof verdict !== 'object' || verdict === null)
+        return undefined;
+    const subject = verdict.subject;
+    if (typeof subject !== 'object' ||
+        subject === null ||
+        typeof subject.chain !== 'string' ||
+        typeof subject.payTo !== 'string' ||
+        typeof subject.resourceUrl !== 'string' ||
+        typeof verdict.outcome !== 'string' ||
+        typeof verdict.assuranceLevel !== 'string' ||
+        typeof verdict.verifiedAt !== 'string' ||
+        !Number.isInteger(verdict.recheckEveryHours)) {
         return undefined;
     }
     const parsed = Date.parse(verdict.verifiedAt);
@@ -94,9 +226,9 @@ export function canonicalVerdictPayload(verdict) {
     // Second precision: the canonical form drops any fractional seconds the
     // transport representation may carry.
     const verifiedAt = new Date(Math.floor(parsed / 1000) * 1000).toISOString().replace('.000Z', 'Z');
-    const json = `{"chain":${goJson(verdict.subject.chain)}` +
-        `,"payTo":${goJson(verdict.subject.payTo)}` +
-        `,"resourceUrl":${goJson(verdict.subject.resourceUrl)}` +
+    const json = `{"chain":${goJson(subject.chain)}` +
+        `,"payTo":${goJson(subject.payTo)}` +
+        `,"resourceUrl":${goJson(subject.resourceUrl)}` +
         `,"outcome":${goJson(verdict.outcome)}` +
         `,"assuranceLevel":${goJson(verdict.assuranceLevel)}` +
         `,"verifiedAt":"${verifiedAt}"` +
@@ -113,18 +245,24 @@ function goJson(value) {
 }
 /**
  * Verifies the verdict's Ed25519 signature locally against a known public key
- * (base64, 32 raw bytes) — no round-trip involved.
+ * (base64, 32 raw bytes) — no round-trip involved. Never throws or rejects,
+ * whatever the verdict's shape.
  *
  * Degradation path: `unverifiable` (missing signature, or no Ed25519 support
  * in the runtime's WebCrypto) is not a negative finding — display the verdict
  * as usual, or fall back to "unknown" if your policy prefers only locally
- * checked claims. `invalid` means the bytes do not match the key: treat as
+ * checked claims. `invalid` means the bytes, the base64 or the key do not
+ * match (a signature whose signed bytes cannot be built included): treat as
  * "unknown".
  */
 export async function verifyVerdictSignature(verdict, publicKeyBase64) {
-    if (verdict.signature === undefined) {
+    const claimed = typeof verdict === 'object' && verdict !== null ? verdict.signature : undefined;
+    if (claimed === undefined) {
         return 'unverifiable';
     }
+    if (typeof claimed !== 'string') {
+        return 'invalid';
+    }
     const payload = canonicalVerdictPayload(verdict);
     if (payload === undefined) {
         return 'invalid';
@@ -132,12 +270,17 @@ export async function verifyVerdictSignature(verdict, publicKeyBase64) {
     let signature;
     let publicKey;
     try {
-        signature = base64Decode(verdict.signature);
+        signature = base64Decode(claimed);
         publicKey = base64Decode(publicKeyBase64);
     }
     catch {
         return 'invalid';
     }
+    // A raw Ed25519 key is 32 bytes and a signature 64: anything else cannot
+    // match, and must not be mistaken for a runtime without Ed25519 below.
+    if (publicKey.byteLength !== 32 || signature.byteLength !== 64) {
+        return 'invalid';
+    }
     try {
         const key = await crypto.subtle.importKey('raw', publicKey, { name: 'Ed25519' }, false, [
             'verify',

package/dist/webhook.d.ts

@@ -22,8 +22,10 @@ export declare function webhookKeyId(secretHex: string): Promise<string>;
  */
 export declare function verifyWebhookSignature(secretHex: string, rawBody: Uint8Array | string, headers: HeaderSource): Promise<boolean>;
 /**
- * Parses a delivery body into a `VerdictEvent`. Returns `undefined` for
- * anything that is not a well-formed `verdict.updated` event.
+ * Parses a delivery body into a `VerdictEvent`: the free path's verdict
+ * (the same structural check as `fetchVerdict`, so the signature check
+ * applies unchanged) with `"event": "verdict.updated"`. Returns `undefined`
+ * for anything else — never throws.
  */
 export declare function parseVerdictEvent(rawBody: Uint8Array | string): VerdictEvent | undefined;
 export {};

package/dist/webhook.js

@@ -6,7 +6,7 @@
 // Zero runtime dependencies (WebCrypto). Graceful degradation: a delivery
 // that does not verify is `false` — drop it and keep polling the free path;
 // nothing in your flow depends on webhooks arriving.
-import { isChain } from "./verdict.js";
+import { isVerdict } from "./verdict.js";
 /** Header names used by deliveries. */
 export const SIGNATURE_HEADER = 'X-Signature';
 export const SIGNATURE_KEY_HEADER = 'X-Signature-Key';
@@ -55,22 +55,16 @@ export async function verifyWebhookSignature(secretHex, rawBody, headers) {
     }
 }
 /**
- * Parses a delivery body into a `VerdictEvent`. Returns `undefined` for
- * anything that is not a well-formed `verdict.updated` event.
+ * Parses a delivery body into a `VerdictEvent`: the free path's verdict
+ * (the same structural check as `fetchVerdict`, so the signature check
+ * applies unchanged) with `"event": "verdict.updated"`. Returns `undefined`
+ * for anything else — never throws.
  */
 export function parseVerdictEvent(rawBody) {
     try {
         const text = typeof rawBody === 'string' ? rawBody : new TextDecoder().decode(rawBody);
         const value = JSON.parse(text);
-        const subject = value['subject'];
-        if (value['event'] !== 'verdict.updated' ||
-            typeof value['outcome'] !== 'string' ||
-            typeof value['recheckEveryHours'] !== 'number' ||
-            typeof subject !== 'object' ||
-            subject === null ||
-            !isChain(subject['chain']) ||
-            typeof subject['payTo'] !== 'string' ||
-            typeof subject['resourceUrl'] !== 'string') {
+        if (!isVerdict(value) || value['event'] !== 'verdict.updated') {
             return undefined;
         }
         return value;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zadq/x402",
-  "version": "0.1.0",
-  "description": "Client helpers for the free seller-verification path of x402 endpoints: the signed verdict and its local Ed25519 check, the HTTP 402 identity-policy extension and companion header, the issuer receipt, the explorer client, the webhook receiver and the seller holder driver. Zero runtime dependencies; every helper degrades to \"unknown\".",
+  "version": "0.3.0",
+  "description": "Client helpers for the free seller-verification path of x402 endpoints: the signed verdict and its local Ed25519 check, the HTTP 402 identity-policy extension and companion header, the issuer receipt, the badge, the explorer client, the webhook receiver and the seller holder driver. Zero runtime dependencies; every helper degrades to \"unknown\".",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
@@ -13,6 +13,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
     "./verdict": {
       "types": "./dist/verdict.d.ts",
       "import": "./dist/verdict.js"
@@ -41,6 +45,18 @@
       "types": "./dist/webhook.d.ts",
       "import": "./dist/webhook.js"
     },
+    "./badge": {
+      "types": "./dist/badge.d.ts",
+      "import": "./dist/badge.js"
+    },
+    "./payment-required": {
+      "types": "./dist/extension.d.ts",
+      "import": "./dist/extension.js"
+    },
+    "./x-payment": {
+      "types": "./dist/header.d.ts",
+      "import": "./dist/header.js"
+    },
     "./holder": {
       "types": "./dist/holder/index.d.ts",
       "import": "./dist/holder/index.js"