@zadq/x402 0.0.0-stage → 0.1.0

package/dist/holder/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// The kill switch as a command the seller runs on its middleware host —
+// where the custody file and the payment key live, never at the
+// verification service. It loads the credential from custody, revokes it
+// through the privacy relay, confirms on the chain, prints one value-free
+// JSON report, and optionally tells the seller's dashboard record that the
+// credential was revoked (state only; the dashboard learns nothing else).
+//
+//   MINTID_HOLDER_BIN=/usr/local/bin/mintid-holder \
+//   CREDENTIAL_CUSTODY_FILE=/var/lib/seller/credential.custody \
+//   CREDENTIAL_CUSTODY_KEY=<64 hex> \
+//   MINTID_RELAY_URL=https://relay.example MINTID_CHAIN_RPC=https://rpc.example \
+//     node --experimental-strip-types src/holder/cli.ts --yes
+//
+// Flags: --yes (required: the revocation is irreversible), --no-jitter or
+// --jitter-ms <n> (the random delay before the submission, up to a minute
+// by default), --report (tell the dashboard, with VERIFICATION_BASE_URL,
+// VERIFICATION_SELLER_ID and VERIFICATION_SESSION — the dashboard's short-lived session
+// credential — set). Nothing here logs; stdout carries the report only.
+import { pathToFileURL } from 'node:url';
+import { custodyKeyFromHex, fileCustodyStore, sealedCustodyStore, } from "./custody.js";
+import { HolderError } from "./errors.js";
+import { SellerHolder } from "./holder.js";
+import { CHAIN_ID_ENV, CHAIN_RPC_ENV, RELAY_URL_ENV, RelayRefusedError, revokeCredential, } from "./killswitch.js";
+import { HOLDER_BINARY_ENV, HolderProcess } from "./process.js";
+export const CUSTODY_FILE_ENV = 'CREDENTIAL_CUSTODY_FILE';
+export const CUSTODY_KEY_ENV = 'CREDENTIAL_CUSTODY_KEY';
+export const DASHBOARD_URL_ENV = 'VERIFICATION_BASE_URL';
+export const DASHBOARD_SELLER_ENV = 'VERIFICATION_SELLER_ID';
+export const DASHBOARD_SESSION_ENV = 'VERIFICATION_SESSION';
+/** The credential state the seller's record takes at the dashboard service. */
+export const DASHBOARD_REVOKED_STATE = 'self_revoked';
+const NEXT_STEP = 'Open the dashboard and press "Revoke my credential" → "My middleware revoked it" ' +
+    'so your record shows it; then re-verify when you want a fresh credential.';
+function flag(argv, name) {
+    return argv.includes(name);
+}
+function value(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+/**
+ * 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 async function runKillSwitch(argv, env, io, deps = {}) {
+    if (!flag(argv, '--yes')) {
+        io.err('This revokes your credential for good: from the next status root on it presents nowhere, ' +
+            'and only a new verification gives you a fresh one. Run again with --yes.');
+        return 1;
+    }
+    const relayUrl = env[RELAY_URL_ENV];
+    if (!relayUrl) {
+        io.err(`${RELAY_URL_ENV} is not set: the revocation travels through the privacy relay only.`);
+        return 1;
+    }
+    const custodyFile = env[CUSTODY_FILE_ENV];
+    if (!custodyFile && !deps.custody) {
+        io.err(`${CUSTODY_FILE_ENV} is not set: where the custody encoding lives.`);
+        return 1;
+    }
+    let custody = deps.custody ?? fileCustodyStore(custodyFile ?? '');
+    const keyHex = env[CUSTODY_KEY_ENV];
+    if (keyHex) {
+        try {
+            custody = sealedCustodyStore(custody, custodyKeyFromHex(keyHex));
+        }
+        catch {
+            io.err(`${CUSTODY_KEY_ENV} must be 32 bytes as hex.`);
+            return 1;
+        }
+    }
+    const options = { relayUrl };
+    const chainRpc = env[CHAIN_RPC_ENV];
+    if (chainRpc)
+        options.chainRpc = chainRpc;
+    const chainId = env[CHAIN_ID_ENV];
+    if (chainId)
+        options.chainId = chainId;
+    if (flag(argv, '--no-jitter'))
+        options.jitterMs = 0;
+    const jitter = value(argv, '--jitter-ms');
+    if (jitter !== undefined) {
+        const ms = Number(jitter);
+        if (!Number.isFinite(ms) || ms < 0) {
+            io.err('--jitter-ms takes a non-negative number of milliseconds.');
+            return 1;
+        }
+        options.jitterMs = ms;
+    }
+    const rpc = deps.rpc ?? HolderProcess.start(env[HOLDER_BINARY_ENV]);
+    const fetchImpl = deps.fetch ?? fetch;
+    let report;
+    try {
+        const holder = await SellerHolder.load(rpc, { custody, fetch: fetchImpl });
+        try {
+            report = await (deps.revoke ?? revokeCredential)(holder, options);
+        }
+        finally {
+            await holder.close().catch(() => undefined);
+        }
+    }
+    catch (err) {
+        if (err instanceof RelayRefusedError) {
+            io.err(`relay refused at stage ${err.stage}: ${err.code}` +
+                (err.retryable ? ' — worth a retry, here or at another relay' : '') +
+                '. The holder refuses to present from now on regardless.');
+            return 2;
+        }
+        if (err instanceof HolderError) {
+            io.err(`${err.name}: ${err.message}`);
+            return 1;
+        }
+        throw err;
+    }
+    finally {
+        if (!deps.rpc)
+            await rpc.close();
+    }
+    const out = { ...report, dashboard: 'not_reported' };
+    if (flag(argv, '--report')) {
+        const base = env[DASHBOARD_URL_ENV];
+        const sellerId = env[DASHBOARD_SELLER_ENV];
+        const session = env[DASHBOARD_SESSION_ENV];
+        if (!base || !sellerId || !session) {
+            io.err(`--report needs ${DASHBOARD_URL_ENV}, ${DASHBOARD_SELLER_ENV} and ${DASHBOARD_SESSION_ENV}.`);
+            out.next = NEXT_STEP;
+        }
+        else {
+            out.dashboard = (await reportToDashboard(fetchImpl, base, sellerId, session))
+                ? 'reported'
+                : 'report_failed';
+            if (out.dashboard === 'report_failed')
+                out.next = NEXT_STEP;
+        }
+    }
+    else {
+        out.next = NEXT_STEP;
+    }
+    io.out(JSON.stringify(out));
+    return out.state === 'unconfirmed' ? 2 : 0;
+}
+/**
+ * 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 async function reportToDashboard(fetchImpl, baseUrl, sellerId, session) {
+    try {
+        const response = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/v0/sellers/${encodeURIComponent(sellerId)}/credential`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${session}` },
+            body: JSON.stringify({ state: DASHBOARD_REVOKED_STATE }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    runKillSwitch(process.argv.slice(2), process.env, {
+        out: (line) => process.stdout.write(line + '\n'),
+        err: (line) => process.stderr.write(line + '\n'),
+    }).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`${err instanceof Error ? err.name : 'error'}\n`);
+        process.exit(1);
+    });
+}

package/dist/holder/custody.d.ts

@@ -0,0 +1,20 @@
+/** Where the custody encoding lives. `load` resolves `undefined` when nothing is stored. */
+export interface CustodyStore {
+    load(): Promise<string | undefined>;
+    save(encoding: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** In-process only: for tests and for a seller that keeps the encoding elsewhere itself. */
+export declare function memoryCustodyStore(initial?: string): CustodyStore;
+/** One file, owner-readable only (0600), created with its directory. */
+export declare function fileCustodyStore(path: string): CustodyStore;
+/** The seller's key: 32 raw bytes, given directly or fetched when needed (KMS/HSM). */
+export type CustodyKey = Uint8Array | (() => Promise<Uint8Array>);
+/**
+ * Wraps another store so that what it holds is AES-256-GCM ciphertext under
+ * the seller's key (`v1.<nonce>.<ciphertext>`, base64url). A wrong key or a
+ * tampered record opens to nothing: `load` rejects, it never returns garbage.
+ */
+export declare function sealedCustodyStore(inner: CustodyStore, key: CustodyKey): CustodyStore;
+/** A 32-byte key from its hex form (64 hex characters), e.g. read from an environment secret. */
+export declare function custodyKeyFromHex(hex: string): Uint8Array;

package/dist/holder/custody.js

@@ -0,0 +1,112 @@
+// Custody of the credential's storage encoding — the one serialization the
+// holder library produces. It holds the link secret, so it is the seller's
+// to keep: in the seller's own infrastructure, encrypted under a key the
+// seller controls, next to the payment key it already protects. Nothing here
+// ever leaves the seller's side; the verification service holds no copy.
+//
+// This module invents no cryptography: the sealed store wraps the platform's
+// WebCrypto AES-256-GCM under a key the seller supplies (from an environment
+// secret, a cloud KMS data key or an HSM-wrapped key — the key never travels
+// through the holder module beyond the seal/open calls).
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** In-process only: for tests and for a seller that keeps the encoding elsewhere itself. */
+export function memoryCustodyStore(initial) {
+    let value = initial;
+    return {
+        load: async () => value,
+        save: async (encoding) => {
+            value = encoding;
+        },
+        clear: async () => {
+            value = undefined;
+        },
+    };
+}
+/** One file, owner-readable only (0600), created with its directory. */
+export function fileCustodyStore(path) {
+    return {
+        load: async () => {
+            try {
+                return (await readFile(path, 'utf8')).trim() || undefined;
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    return undefined;
+                throw err;
+            }
+        },
+        save: async (encoding) => {
+            await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+            await writeFile(path, encoding + '\n', { mode: 0o600 });
+        },
+        clear: async () => {
+            await rm(path, { force: true });
+        },
+    };
+}
+// WebCrypto takes views over a plain ArrayBuffer; copy so a shared or
+// pooled buffer never reaches it.
+function plain(bytes) {
+    const out = new Uint8Array(new ArrayBuffer(bytes.byteLength));
+    out.set(bytes);
+    return out;
+}
+const SEAL_VERSION = 'v1';
+/**
+ * Wraps another store so that what it holds is AES-256-GCM ciphertext under
+ * the seller's key (`v1.<nonce>.<ciphertext>`, base64url). A wrong key or a
+ * tampered record opens to nothing: `load` rejects, it never returns garbage.
+ */
+export function sealedCustodyStore(inner, key) {
+    const subtle = globalThis.crypto.subtle;
+    const cryptoKey = async () => {
+        const raw = typeof key === 'function' ? await key() : key;
+        if (raw.byteLength !== 32)
+            throw new Error('custody key must be 32 bytes');
+        return subtle.importKey('raw', plain(raw), { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+    };
+    return {
+        load: async () => {
+            const sealed = await inner.load();
+            if (sealed === undefined)
+                return undefined;
+            const [version, nonce, ciphertext] = sealed.split('.');
+            if (version !== SEAL_VERSION || !nonce || !ciphertext) {
+                throw new Error('custody record is not a sealed encoding');
+            }
+            const opened = await subtle.decrypt({ name: 'AES-GCM', iv: fromBase64Url(nonce) }, await cryptoKey(), fromBase64Url(ciphertext));
+            return new TextDecoder().decode(opened);
+        },
+        save: async (encoding) => {
+            const nonce = globalThis.crypto.getRandomValues(new Uint8Array(12));
+            const ciphertext = await subtle.encrypt({ name: 'AES-GCM', iv: nonce }, await cryptoKey(), new TextEncoder().encode(encoding));
+            await inner.save(`${SEAL_VERSION}.${toBase64Url(nonce)}.${toBase64Url(new Uint8Array(ciphertext))}`);
+        },
+        clear: () => inner.clear(),
+    };
+}
+/** A 32-byte key from its hex form (64 hex characters), e.g. read from an environment secret. */
+export function custodyKeyFromHex(hex) {
+    const clean = hex.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(clean))
+        throw new Error('custody key hex must be 64 hex characters');
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++)
+        out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+function toBase64Url(bytes) {
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64);
+    const out = new Uint8Array(new ArrayBuffer(binary.length));
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}

package/dist/holder/errors.d.ts

@@ -0,0 +1,22 @@
+export declare class HolderError extends Error {
+    constructor(message: string);
+}
+/** The hand-off is not a redeemable MintID identity offer (wrong class, shape or past its expiry). */
+export declare class OfferError extends HolderError {
+}
+/** A refusal of the holder library process; `text` names no claim value. */
+export declare class HolderLibraryError extends HolderError {
+    readonly op: string;
+    readonly text: string;
+    constructor(op: string, text: string);
+}
+/** A refused HTTP step against the issuer (metadata, grant, credential, witness). */
+export declare class HolderStepError extends HolderError {
+    readonly step: string;
+    readonly status: number;
+    readonly body: unknown;
+    constructor(step: string, status: number, body: unknown);
+}
+/** The issuer no longer serves a witness for this credential: revoked, or expired with its verification. */
+export declare class CredentialRevokedError extends HolderError {
+}

package/dist/holder/errors.js

@@ -0,0 +1,38 @@
+// What the seller-side holder module throws. Every refusal is value-free: a
+// step name, an HTTP status, a reason code or the holder library's own
+// refusal text (which names an output key at most) — never a secret, never
+// a custody encoding, never an attribute of the accountable party.
+export class HolderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** The hand-off is not a redeemable MintID identity offer (wrong class, shape or past its expiry). */
+export class OfferError extends HolderError {
+}
+/** A refusal of the holder library process; `text` names no claim value. */
+export class HolderLibraryError extends HolderError {
+    op;
+    text;
+    constructor(op, text) {
+        super(`${op}: ${text}`);
+        this.op = op;
+        this.text = text;
+    }
+}
+/** A refused HTTP step against the issuer (metadata, grant, credential, witness). */
+export class HolderStepError extends HolderError {
+    step;
+    status;
+    body;
+    constructor(step, status, body) {
+        super(`${step}: HTTP ${status}`);
+        this.step = step;
+        this.status = status;
+        this.body = body;
+    }
+}
+/** The issuer no longer serves a witness for this credential: revoked, or expired with its verification. */
+export class CredentialRevokedError extends HolderError {
+}

package/dist/holder/holder.d.ts

@@ -0,0 +1,115 @@
+import type { HolderRpc } from './process.js';
+import type { CustodyStore } from './custody.js';
+import type { ChallengeAnswer, HolderInfo, IssuedChallenge, PresentationEnvelope, PresentationRequest, SelfRevocation, SelfRevokeContext, SelfRevokeMaterial, WitnessState } from './types.js';
+/** The identity credential's configuration id at the issuer's metadata. */
+export declare const IDENTITY_CONFIGURATION_ID = "mintid_identity_v1";
+export declare const CREDENTIAL_FORMAT = "mintid/anoncreds-v2";
+export declare const PROOF_TYPE = "mintid_blind_request";
+export declare const PRE_AUTHORIZED_GRANT = "urn:ietf:params:oauth:grant-type:pre-authorized_code";
+export declare const METADATA_PATH = "/.well-known/openid-credential-issuer";
+/** The issuer's public build information: names the chain it anchors on. */
+export declare const BUILD_INFO_PATH = "/v0/build-info";
+/** A presentation lives ten seconds from the challenge; the holder answers well inside it. */
+export declare const PRESENTATION_WINDOW_MS = 10000;
+export type Fetch = typeof fetch;
+export type HolderOptions = {
+    fetch?: Fetch;
+    /** Where the custody encoding is kept; `persist()` writes to it, `issue`/`selfRevoke` do so too. */
+    custody?: CustodyStore;
+};
+/** The parsed operator hand-out: the offer object and, when the hand-off says, its expiry. */
+export type CredentialOffer = {
+    offer: Record<string, unknown>;
+    expiresAt?: Date;
+};
+/**
+ * Reads the operator's hand-out in any of its forms — the dashboard's
+ * `{offer, expiresAt, credential}`, the issuer's `{credential_offer,
+ * expires_at}`, or the bare offer — and refuses anything that is not a
+ * pre-authorized MintID identity offer, or one already past its expiry.
+ */
+export declare function readCredentialOffer(input: unknown, now?: Date): CredentialOffer;
+export declare class SellerHolder {
+    readonly rpc: HolderRpc;
+    readonly handle: number;
+    private readonly fetchImpl;
+    private readonly custody;
+    private material;
+    private constructor();
+    /**
+     * Redeem the operator's offer, once: issuer metadata → the one-shot
+     * grant (with its nonce) → the library's blinded request → the
+     * credential → the library completes and holds it. The custody encoding
+     * is saved when a store is given. `OfferError` on a hand-out of another
+     * class, `HolderStepError` on a terminal issuer refusal (an offer past
+     * its verification's expiry answers 409 `session_reuse_expired`; the way
+     * back is a new verification, never a retry).
+     */
+    static issue(handout: unknown, rpc: HolderRpc, options?: HolderOptions): Promise<SellerHolder>;
+    /** Resume from the custody store (or a custody encoding given directly). */
+    static load(rpc: HolderRpc, options?: HolderOptions & {
+        encoding?: string;
+    }): Promise<SellerHolder>;
+    /** Custody encoding — it contains the link secret; keep it sealed, never log it. */
+    storage(): Promise<string>;
+    /** Writes the current custody encoding to the store, when one is configured. */
+    persist(): Promise<void>;
+    info(): Promise<HolderInfo>;
+    /**
+     * Fresh witness material from the issuer, adopted once a finalized root
+     * anchors it. Run it on your cadence — sized to how often roots are
+     * published — and right before presenting: a stale witness fails closed.
+     * `CredentialRevokedError` once the issuer serves none (revoked, or
+     * expired with its verification).
+     */
+    refreshWitness(): Promise<WitnessState>;
+    /**
+     * One bound, ten-second envelope for a verifier's challenge — the
+     * `createChallenge` answer as received (`{request, signature_hex}`) or
+     * its `request` object. The library refuses (naming an output key at
+     * most) when the credential cannot satisfy the policy: nothing is sent.
+     */
+    present(challenge: IssuedChallenge | PresentationRequest): Promise<PresentationEnvelope>;
+    /**
+     * The presentation endpoint's whole answer to the verification service's
+     * challenge (`POST` of the issued challenge, byte for byte): the witness
+     * is refreshed first, then one envelope is built. A witness endpoint that
+     * cannot be reached is not a refusal — the holder presents against the
+     * root it holds and the verifier decides. Refusals are value-free reason
+     * codes: `challenge_malformed` (400), `challenge_expired`,
+     * `credential_revoked`, `holder_refused` (409). Nothing of the exchange
+     * is logged here, and nothing is retried: the next cadence brings the
+     * next challenge.
+     */
+    answerChallenge(body: unknown, now?: Date): Promise<ChallengeAnswer>;
+    /** The library's own consistency check under a caller nonce (hex); rejects otherwise. */
+    selfCheck(nonce?: string): Promise<void>;
+    /** The self-revocation material cached by the last witness refresh, if any. */
+    selfRevokeContext(): SelfRevokeMaterial | undefined;
+    /**
+     * The chain the issuer anchors on, from its public build information
+     * (the issuer is where the witness endpoint lives). `HolderStepError`
+     * when it cannot be read.
+     */
+    chainId(): Promise<string>;
+    /**
+     * Builds the credential's self-revocation against the issuer's published
+     * anchoring of a finalized root — the material cached by the last witness
+     * refresh unless the caller passes its own. From this call on the holder
+     * refuses to present, also after a reload from custody (the store is
+     * updated). The message revokes nothing until a privacy relay submits it
+     * and the chain records it: `revokeCredential` (killswitch.ts) is the
+     * product kill switch that does both and reports; this method is the
+     * primitive under it.
+     */
+    selfRevoke(context: SelfRevokeContext): Promise<SelfRevocation>;
+    /** Forget the credential inside the process (its secret with it). The custody store is untouched. */
+    close(): Promise<void>;
+}
+/**
+ * Reads the verification service's `POST` body as an issued challenge:
+ * `{request, signature_hex}`, or the bare request. Returns `undefined` for
+ * anything that is not a presentation request (no nonce, no audience, no
+ * expiry, no policy) — the endpoint answers 400 and moves on.
+ */
+export declare function readIssuedChallenge(body: unknown): IssuedChallenge | undefined;