@zadq/x402 0.0.0-stage → 0.2.0

package/dist/extension.js

@@ -0,0 +1,182 @@
+// x402 `PaymentRequired` identity-policy extension helpers, following the
+// bIP-0002 x402 transport profile (draft MintID MINT-190, cited by name): the
+// identity policy rides a `PaymentRequired` extension; the identity proof
+// rides a companion header alongside `X-PAYMENT` (see header.ts).
+//
+// Graceful degradation, by design: the extension is strictly additive.
+// Counterparties that do not understand it see a normal 402 response and pay
+// exactly as before; counterparties that do understand it can check the
+// endpoint's verification signal — from the inline signed verdict, locally
+// 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.
+/** 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.
+ */
+export function withIdentityPolicy(body, policy) {
+    const canonical = {
+        claim: policy.claim,
+        assuranceAtLeast: policy.assuranceAtLeast,
+        verifyUrl: policy.verifyUrl,
+    };
+    if (policy.verdict !== undefined)
+        canonical.verdict = policy.verdict;
+    return {
+        ...body,
+        extensions: { ...body.extensions, [IDENTITY_POLICY_EXTENSION]: canonical },
+    };
+}
+/**
+ * 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.
+ */
+export function readIdentityPolicy(body) {
+    const raw = body.extensions?.[IDENTITY_POLICY_EXTENSION];
+    if (typeof raw !== 'object' || raw === null) {
+        return undefined;
+    }
+    const policy = raw;
+    if (policy['claim'] !== 'seller-endpoint-accountability' ||
+        typeof policy['assuranceAtLeast'] !== 'string' ||
+        typeof policy['verifyUrl'] !== 'string') {
+        return undefined;
+    }
+    const read = {
+        claim: 'seller-endpoint-accountability',
+        assuranceAtLeast: policy['assuranceAtLeast'],
+        verifyUrl: policy['verifyUrl'],
+    };
+    const verdict = policy['verdict'];
+    if (typeof verdict === 'object' && verdict !== null) {
+        read.verdict = verdict;
+    }
+    return read;
+}
+/**
+ * Vendor side: returns a copy of the 402 body with the trust-perimeter
+ * invitation attached under its own key. `identityPolicy` is untouched.
+ */
+export function withPerimeterInvitation(body, invitation) {
+    const canonical = {
+        attestation: invitation.attestation,
+        attestUrl: invitation.attestUrl,
+    };
+    return {
+        ...body,
+        extensions: { ...body.extensions, [PERIMETER_EXTENSION]: canonical },
+    };
+}
+/**
+ * Agent side: reads the vendor's invitation, if present and well-formed.
+ * Anything else — absent, malformed, or a value this line does not offer
+ * (such as "required") — reads as `undefined`, and the payment proceeds
+ * exactly as before.
+ */
+export function readPerimeterInvitation(body) {
+    const raw = body.extensions?.[PERIMETER_EXTENSION];
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const v = raw;
+    const attestation = v['attestation'];
+    const attestUrl = v['attestUrl'];
+    if ((attestation !== 'welcome' && attestation !== 'preferred') ||
+        typeof attestUrl !== 'string' ||
+        !attestUrl.startsWith('https://')) {
+        return undefined;
+    }
+    return { attestation, attestUrl };
+}
+/** Extension key defined by the bIP-0002 profile for the complete v1 object. */
+export const MINTID_IDENTITY_EXTENSION = 'mintid_identity';
+/**
+ * Returns a copy of the 402 body with the canonical v1 object attached under
+ * `extensions.mintid_identity`. Only the canonical fields are emitted (each
+ * claim entry reduced to `{claim, operator?, value}`), so the object always
+ * validates against the closed v1 schema whatever else the caller's value
+ * carried. `identityPolicy` and every other key are untouched.
+ */
+export function withMintidIdentity(body, policy) {
+    return {
+        ...body,
+        extensions: { ...body.extensions, [MINTID_IDENTITY_EXTENSION]: canonicalV1(policy) },
+    };
+}
+/**
+ * Counterparty side: reads the v1 object from a 402 body, if present and
+ * well-formed for this profile. Anything else — absent, another profile,
+ * a non-https challenge endpoint, an empty policy — reads as `undefined`,
+ * and the payment proceeds exactly as before.
+ */
+export function readMintidIdentity(body) {
+    const raw = body.extensions?.[MINTID_IDENTITY_EXTENSION];
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const v = raw;
+    const entries = v['claim_policy'];
+    if (v['profile'] !== 'bip-0002/1' ||
+        typeof v['challenge_endpoint'] !== 'string' ||
+        !v['challenge_endpoint'].startsWith('https://') ||
+        v['session_mode'] !== 'token_exchange' ||
+        !Array.isArray(entries) ||
+        entries.length === 0 ||
+        !entries.every(isClaimEntry)) {
+        return undefined;
+    }
+    return canonicalV1(v);
+}
+/**
+ * Seller side: one call for the coexistence window. Returns a copy of the
+ * 402 body with `identityPolicy` attached and, when the credential is held
+ * and a v1 policy is declared, `mintid_identity` beside it. Neither object
+ * ever absorbs a field of the other; both stay canonical and closed.
+ */
+export function withSellerIdentity(body, identity) {
+    const withV0 = withIdentityPolicy(body, identity.policy);
+    if (identity.credential === 'held' && identity.v1 !== undefined) {
+        return withMintidIdentity(withV0, identity.v1);
+    }
+    return withV0;
+}
+function isClaimEntry(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return false;
+    const e = entry;
+    const value = e['value'];
+    return (typeof e['claim'] === 'string' &&
+        (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') &&
+        (e['operator'] === undefined || e['operator'] === '>='));
+}
+function canonicalV1(policy) {
+    const canonical = {
+        profile: 'bip-0002/1',
+        challenge_endpoint: policy.challenge_endpoint,
+        claim_policy: policy.claim_policy.map((e) => {
+            const entry = { claim: e.claim, value: e.value };
+            if (e.operator !== undefined)
+                entry.operator = e.operator;
+            return entry;
+        }),
+        session_mode: 'token_exchange',
+    };
+    if (policy.issuer_policy !== undefined) {
+        const ip = {};
+        if (policy.issuer_policy.accepted_issuer_ids !== undefined) {
+            ip.accepted_issuer_ids = [...policy.issuer_policy.accepted_issuer_ids];
+        }
+        if (policy.issuer_policy.issuer_state_minimum !== undefined) {
+            ip.issuer_state_minimum = policy.issuer_policy.issuer_state_minimum;
+        }
+        canonical.issuer_policy = ip;
+    }
+    return canonical;
+}

package/dist/header.d.ts

@@ -0,0 +1,30 @@
+/** The standard x402 payment header (payload untouched by this snippet). */
+export declare const X_PAYMENT_HEADER = "X-PAYMENT";
+/** Companion header defined by the bIP-0002 profile for the identity proof. */
+export declare const X_PAYMENT_IDENTITY_HEADER = "X-PAYMENT-IDENTITY";
+/**
+ * Envelope carried by the companion header (base64url-encoded JSON). The
+ * payload stays opaque to the transport: the v0 seller rail carries
+ * issuer-signed attestation references; v1 presentations ride the same
+ * envelope under their own format identifier.
+ */
+export type IdentityProof = {
+    version: 1;
+    /** Proof format identifier, e.g. "attestation-ref/v0". */
+    format: string;
+    /** Opaque proof payload, base64url. Never identity data itself. */
+    payload: string;
+};
+type HeaderRecord = Record<string, string>;
+/**
+ * Sender side: attaches the identity proof next to `X-PAYMENT`. 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.
+ */
+export declare function readIdentityProof(headers: Headers | HeaderRecord): IdentityProof | undefined;
+export {};

package/dist/header.js

@@ -0,0 +1,84 @@
+// X-PAYMENT companion header helpers — proof transport of the bIP-0002 profile
+// (draft MintID MINT-190, cited by name): the identity proof travels in a
+// companion header next to `X-PAYMENT`, so the paying request stays a single
+// HTTP round-trip and the x402 payment payload itself is never modified.
+//
+// Zero runtime dependencies; works with both `Headers`
+// objects and plain header records.
+//
+// Graceful degradation, by design: the proof header is optional in both
+// directions. A request without it is a normal x402 request and the sale
+// completes as usual; a receiver that does not understand the header ignores
+// it. Whether and how a receiver weighs an absent proof is its own published
+// policy, applied out of band — never a hard gate wired into this snippet.
+/** The standard x402 payment header (payload untouched by this snippet). */
+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.
+ */
+export function attachIdentityProof(headers, proof) {
+    const value = base64UrlEncode(JSON.stringify(proof));
+    if (headers instanceof Headers) {
+        headers.set(X_PAYMENT_IDENTITY_HEADER, value);
+    }
+    else {
+        headers[X_PAYMENT_IDENTITY_HEADER] = value;
+    }
+    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.
+ */
+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 parsed = JSON.parse(base64UrlDecode(value));
+        if (parsed['version'] !== 1 ||
+            typeof parsed['format'] !== 'string' ||
+            typeof parsed['payload'] !== 'string') {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Plain records may carry any header-name casing; HTTP header names are
+// case-insensitive.
+function findHeader(headers, name) {
+    const lower = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === lower) {
+            return headers[key];
+        }
+    }
+    return undefined;
+}
+function base64UrlEncode(value) {
+    const bytes = new TextEncoder().encode(value);
+    let binary = '';
+    for (const b of bytes) {
+        binary += String.fromCharCode(b);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlDecode(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return new TextDecoder().decode(bytes);
+}

package/dist/holder/chain.d.ts

@@ -0,0 +1,28 @@
+/** The chain query path of the issuer-scoped read. */
+export declare const RECORDED_NULLIFIERS_QUERY = "/identity.v1.selfrevoke.Query/RecordedNullifiers";
+/** A recorded self-revocation's state on the chain, by revocation value (hex). */
+export type RecordedState = 'pending' | 'folded';
+export type ChainReadOptions = {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
+/** Protobuf length-delimited field (wire type 2). */
+export declare function bytesField(field: number, value: Uint8Array): Uint8Array;
+/** Protobuf varint field (wire type 0). */
+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. */
+export declare function encodeIssuerQuery(issuerIdHex: string): Uint8Array;
+/**
+ * `QueryRecordedNullifiersResponse{repeated RecordedNullifier records = 1}`
+ * with `RecordedNullifier{version = 1, nullifier = 2, folded_in_epoch = 3}`
+ * → `{<value hex>: 'pending' | 'folded'}`. Other fields are skipped.
+ */
+export declare function decodeRecordedNullifiers(raw: Uint8Array): Map<string, RecordedState>;
+/**
+ * Reads the issuer's recorded self-revocations from a node (`rpcUrl` is
+ * the node's JSON-RPC endpoint). `HolderStepError('chain', …)` when the node
+ * does not answer or refuses the query — never a partial answer.
+ */
+export declare function readRecordedNullifiers(rpcUrl: string, issuerIdHex: string, options?: ChainReadOptions): Promise<Map<string, RecordedState>>;

package/dist/holder/chain.js

@@ -0,0 +1,167 @@
+// The holder's one chain read: the issuer-scoped set of recorded
+// self-revocations, read through a node's JSON-RPC `abci_query`, restated
+// from the chain's self-revocation query contract (cited by name). The
+// request names the issuer only; the holder finds its own revocation value
+// in the answer locally, so the node — and any edge in front of it — never
+// learns which one the caller holds. What it can pair with the caller's
+// address is "someone holds a credential of this issuer", nothing more.
+//
+// A relay's answer is never the receipt: before a self-revocation is
+// reported recorded, this read must show it. Zero runtime dependencies; the
+// two protobuf shapes involved are small enough to encode and decode by
+// hand (varints and length-delimited fields only).
+//
+// CONTRACT POINT: the query path and the field numbers below
+// (request: issuer id = field 1; each record: version = 1, value = 2,
+// folded-in epoch = 3) are restated from MintID's chain query contract and
+// are to be confirmed against MintID's self-contained attachment on the
+// card that tracks this integration, before the first live run; they are
+// the only place to change.
+import { HolderStepError } from "./errors.js";
+/** The chain query path of the issuer-scoped read. */
+export const RECORDED_NULLIFIERS_QUERY = '/identity.v1.selfrevoke.Query/RecordedNullifiers';
+function varint(value) {
+    const out = [];
+    let v = value;
+    while (v >= 0x80) {
+        out.push((v & 0x7f) | 0x80);
+        v = Math.floor(v / 128);
+    }
+    out.push(v);
+    return out;
+}
+/** Protobuf length-delimited field (wire type 2). */
+export function bytesField(field, value) {
+    return Uint8Array.from([...varint((field << 3) | 2), ...varint(value.length), ...value]);
+}
+/** Protobuf varint field (wire type 0). */
+export function varintField(field, value) {
+    return Uint8Array.from([...varint(field << 3), ...varint(value)]);
+}
+export function hexToBytes(hex) {
+    if (!/^([0-9a-f]{2})*$/.test(hex))
+        throw new HolderStepError('chain', 0, { error: 'not hex' });
+    return Uint8Array.from(hex.match(/../g) ?? [], (b) => parseInt(b, 16));
+}
+export function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** `QueryRecordedNullifiersRequest{issuer_id = 1}` — names no revocation value. */
+export function encodeIssuerQuery(issuerIdHex) {
+    return bytesField(1, hexToBytes(issuerIdHex));
+}
+function readVarint(data, pos) {
+    let result = 0;
+    let shift = 1;
+    let p = pos;
+    for (;;) {
+        const byte = data[p];
+        if (byte === undefined)
+            throw new HolderStepError('chain', 0, { error: 'truncated varint' });
+        p += 1;
+        result += (byte & 0x7f) * shift;
+        if ((byte & 0x80) === 0)
+            return [result, p];
+        shift *= 128;
+    }
+}
+function* fields(data) {
+    let pos = 0;
+    while (pos < data.length) {
+        const [tag, next] = readVarint(data, pos);
+        const field = Math.floor(tag / 8);
+        const wire = tag % 8;
+        if (wire === 0) {
+            const [value, after] = readVarint(data, next);
+            pos = after;
+            yield { field, varint: value };
+        }
+        else if (wire === 2) {
+            const [length, start] = readVarint(data, next);
+            const end = start + length;
+            if (end > data.length)
+                throw new HolderStepError('chain', 0, { error: 'truncated field' });
+            pos = end;
+            yield { field, bytes: data.subarray(start, end) };
+        }
+        else {
+            throw new HolderStepError('chain', 0, { error: `unsupported wire type ${wire}` });
+        }
+    }
+}
+/**
+ * `QueryRecordedNullifiersResponse{repeated RecordedNullifier records = 1}`
+ * with `RecordedNullifier{version = 1, nullifier = 2, folded_in_epoch = 3}`
+ * → `{<value hex>: 'pending' | 'folded'}`. Other fields are skipped.
+ */
+export function decodeRecordedNullifiers(raw) {
+    const out = new Map();
+    for (const f of fields(raw)) {
+        if (f.field !== 1 || !f.bytes)
+            continue;
+        let value = '';
+        let folded = 0;
+        for (const inner of fields(f.bytes)) {
+            if (inner.field === 2 && inner.bytes)
+                value = bytesToHex(inner.bytes);
+            else if (inner.field === 3 && inner.varint !== undefined)
+                folded = inner.varint;
+        }
+        if (value)
+            out.set(value, folded ? 'folded' : 'pending');
+    }
+    return out;
+}
+/**
+ * Reads the issuer's recorded self-revocations from a node (`rpcUrl` is
+ * the node's JSON-RPC endpoint). `HolderStepError('chain', …)` when the node
+ * does not answer or refuses the query — never a partial answer.
+ */
+export async function readRecordedNullifiers(rpcUrl, issuerIdHex, options = {}) {
+    const fetchImpl = options.fetch ?? fetch;
+    const request = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'abci_query',
+        params: {
+            path: RECORDED_NULLIFIERS_QUERY,
+            data: bytesToHex(encodeIssuerQuery(issuerIdHex)),
+            prove: false,
+        },
+    };
+    let response;
+    try {
+        response = await fetchImpl(rpcUrl, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(request),
+            signal: AbortSignal.timeout(options.timeoutMs ?? 5_000),
+        });
+    }
+    catch (cause) {
+        throw new HolderStepError('chain', 0, { error: String(cause) });
+    }
+    let answer;
+    try {
+        answer = (await response.json());
+    }
+    catch {
+        throw new HolderStepError('chain', response.status, { error: 'non_json_response' });
+    }
+    if (response.status !== 200 ||
+        typeof answer !== 'object' ||
+        answer === null ||
+        'error' in answer) {
+        throw new HolderStepError('chain', response.status, { error: 'node refused the query' });
+    }
+    const result = (answer['result'] ?? {});
+    const inner = (result['response'] ?? {});
+    if (Number(inner['code'] ?? 0) !== 0) {
+        throw new HolderStepError('chain', response.status, {
+            error: 'recorded revocations query refused',
+        });
+    }
+    const value = inner['value'];
+    const raw = typeof value === 'string' && value !== '' ? Buffer.from(value, 'base64') : Buffer.alloc(0);
+    return decodeRecordedNullifiers(new Uint8Array(raw));
+}

package/dist/holder/cli.d.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { type CustodyStore } from './custody.js';
+import { SellerHolder } from './holder.js';
+import { type KillSwitchOptions, type KillSwitchReport } from './killswitch.js';
+import { type HolderRpc } from './process.js';
+export declare const CUSTODY_FILE_ENV = "CREDENTIAL_CUSTODY_FILE";
+export declare const CUSTODY_KEY_ENV = "CREDENTIAL_CUSTODY_KEY";
+export declare const DASHBOARD_URL_ENV = "VERIFICATION_BASE_URL";
+export declare const DASHBOARD_SELLER_ENV = "VERIFICATION_SELLER_ID";
+export declare const DASHBOARD_SESSION_ENV = "VERIFICATION_SESSION";
+/** The credential state the seller's record takes at the dashboard service. */
+export declare const DASHBOARD_REVOKED_STATE = "self_revoked";
+export type KillSwitchEnv = Record<string, string | undefined>;
+export type KillSwitchIO = {
+    out: (line: string) => void;
+    err: (line: string) => void;
+};
+/** Seams for tests: the holder process, the transports, the operation itself. */
+export type KillSwitchDeps = {
+    rpc?: HolderRpc;
+    custody?: CustodyStore;
+    fetch?: typeof fetch;
+    revoke?: (holder: SellerHolder, options: KillSwitchOptions) => Promise<KillSwitchReport>;
+};
+export type CliReport = KillSwitchReport & {
+    dashboard: 'reported' | 'not_reported' | 'report_failed';
+    next?: string;
+};
+/**
+ * Runs the kill switch; resolves to the process exit code. `0`: the
+ * credential is reported `revoked` or `pending`; `2`: `unconfirmed` (the
+ * holder refuses to present already; check again or resubmit — both are
+ * safe); `1`: refused before anything was submitted, or misuse.
+ */
+export declare function runKillSwitch(argv: string[], env: KillSwitchEnv, io: KillSwitchIO, deps?: KillSwitchDeps): Promise<number>;
+/**
+ * Tells the seller's own record at the dashboard service that the
+ * credential was revoked — the state and nothing else: no value, no
+ * transaction, no time of the seller's choosing. The service keeps the
+ * state change and writes nothing next to it.
+ */
+export declare function reportToDashboard(fetchImpl: typeof fetch, baseUrl: string, sellerId: string, session: string): Promise<boolean>;