@ashlar-blue/x402-trust 0.3.0

package/dist/badges.js

@@ -0,0 +1,213 @@
+// GENERATED from src/x402/badges.ts by scripts/sdk/sync-sdk.ts — do not edit here.
+// The canonical module is the one FlareClaw runs in production; this is a copy so
+// that what we publish and what we run cannot diverge. Edit the canonical file.
+/**
+ * badges — reading the x402 `attestations` extension registry (#3000)
+ * with ZERO dependencies.
+ *
+ * ── WHY ZERO DEPENDENCIES ──
+ * This ships as the reference client for a trust extension. A package
+ * whose job is "decide whether to trust a stranger before paying them"
+ * cannot credibly arrive with a dependency tree the reader will never
+ * audit. Everything here is one `eth_call` over `fetch` and some hex
+ * slicing, so the whole trust path is readable in one sitting.
+ *
+ * The cost of that choice is that we cannot compute keccak256 at
+ * runtime, so the function selector and the well-known `kind` hashes
+ * are compile-time constants below. `tests/x402/badges.test.ts` derives
+ * all of them with ethers and asserts equality, so a typo cannot
+ * survive — the constants are verified, not trusted.
+ */
+/** keccak256("hasActiveBadge(address,bytes32)")[0..4] */
+const HAS_ACTIVE_BADGE_SELECTOR = '0x322ad60a';
+/**
+ * keccak256(utf8(kind)) for the kinds this ecosystem has defined so far.
+ * Callers may also pass a pre-hashed 0x-prefixed bytes32 for any other
+ * kind, or supply their own keccak via `hashKind`.
+ */
+export const KNOWN_BADGE_KINDS = Object.freeze({
+    'x402-facilitator-attested': '0xdd51a17aff71777ed7ca01b179f89a5754182ef754023c65de446ce7abeb611e',
+    'bingo-verifiable-venue': '0xf886e00578ed56c02ff72c2950ac3141e4d7221e874b739ab807b8c8f7e9370b',
+    'agent-audits-before-paying': '0x7b93d3c0d725755d8d14df7aaef4fd20ed4d5b1c0c92c5a41a177787e5b72a42',
+});
+const BYTES32 = /^0x[0-9a-fA-F]{64}$/;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+/** Resolve a kind name (or pass through a pre-hashed bytes32). */
+export function resolveKind(kind, hashKind) {
+    if (BYTES32.test(kind))
+        return kind.toLowerCase();
+    const known = KNOWN_BADGE_KINDS[kind];
+    if (known)
+        return known;
+    if (hashKind) {
+        const h = hashKind(kind);
+        if (!BYTES32.test(h))
+            throw new Error(`hashKind returned a non-bytes32 value for "${kind}"`);
+        return h.toLowerCase();
+    }
+    throw new Error(`unknown badge kind "${kind}" — pass a 0x-prefixed bytes32, or supply hashKind (e.g. ethers.id)`);
+}
+/**
+ * `hasActiveBadge(subject, kind)` on a conforming registry.
+ *
+ * ⚠️ Spec rule (Security considerations, "Registry substitution"): a
+ * malicious manifest can point at a lookalike registry, so a caller MUST
+ * pin or allowlist the registries it accepts. This function deliberately
+ * takes the registry as an explicit argument rather than reading it from
+ * a manifest — so that pinning is a decision you make, not one you
+ * forget to make.
+ *
+ * Throws on RPC failure rather than returning false: "I could not check"
+ * and "I checked and it is not active" are different answers, and
+ * collapsing them is how a chain outage turns into a silent trust
+ * upgrade. Callers decide their own failure policy.
+ */
+export async function hasActiveBadge(q) {
+    if (!ADDRESS.test(q.registry))
+        throw new Error(`registry is not an address: ${q.registry}`);
+    if (!ADDRESS.test(q.subject))
+        throw new Error(`subject is not an address: ${q.subject}`);
+    const kindHash = resolveKind(q.kind, q.hashKind);
+    const data = HAS_ACTIVE_BADGE_SELECTOR
+        + q.subject.toLowerCase().replace(/^0x/, '').padStart(64, '0')
+        + kindHash.replace(/^0x/, '');
+    const doFetch = q.fetchImpl ?? fetch;
+    const res = await doFetch(q.rpcUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            jsonrpc: '2.0', id: 1, method: 'eth_call',
+            params: [{ to: q.registry, data }, 'latest'],
+        }),
+        signal: AbortSignal.timeout(q.timeoutMs ?? 10_000),
+    });
+    if (!res.ok)
+        throw new Error(`badge RPC failed: HTTP ${res.status}`);
+    const body = await res.json();
+    if (body.error)
+        throw new Error(`badge RPC error: ${body.error.message ?? 'unknown'}`);
+    if (typeof body.result !== 'string')
+        throw new Error('badge RPC returned no result');
+    // A bool is abi-encoded as a 32-byte word; anything nonzero is true.
+    // An empty result means there is no contract at that address — which
+    // is a misconfiguration, not a negative answer.
+    const word = body.result.replace(/^0x/, '');
+    if (word.length === 0)
+        throw new Error(`no contract at registry ${q.registry}`);
+    return /[1-9a-f]/i.test(word);
+}
+/**
+ * `hasActiveBadge` across N independent endpoints, requiring agreement.
+ *
+ * ── WHY THIS EXISTS ──
+ * Badge status GATES PAYMENTS, and a single `eth_call` is one endpoint's
+ * word. Failover fixes liveness, not honesty: with one source, a hostile
+ * or buggy RPC can report `active` for a revoked venue (or `inactive` to
+ * censor a competitor) and the caller cannot tell. Any read whose answer
+ * we act on without a second source needs a second source.
+ *
+ * Three outcomes, deliberately distinct — collapsing them is how a trust
+ * check quietly stops being one:
+ *   agreed      — quorum endpoints returned the same answer. Act on it.
+ *   disputed    — endpoints DISAGREED. This is not "unknown", it is
+ *                 evidence that one of them is wrong about a
+ *                 payment-gating fact. Callers should refuse, not retry.
+ *   unavailable — too few answered. "I could not check" ≠ "not active".
+ */
+export async function hasActiveBadgeQuorum(q) {
+    const urls = [...new Set(q.rpcUrls)];
+    if (urls.length === 0)
+        throw new Error('hasActiveBadgeQuorum: rpcUrls is empty');
+    // Deliberately NOT clamped to urls.length. Clamping would silently
+    // turn a requested 2-of-N into 1-of-1 whenever a caller passed too
+    // few (or duplicate) endpoints — the guarantee evaporating exactly
+    // where nobody looks. Too few sources yields `unavailable`, which is
+    // the truthful answer: this could not be checked to the requested
+    // standard.
+    const required = Math.max(1, q.quorum ?? 2);
+    const settled = await Promise.allSettled(urls.map(rpcUrl => hasActiveBadge({ ...q, rpcUrl })));
+    const answers = [];
+    const errors = [];
+    for (const r of settled) {
+        if (r.status === 'fulfilled')
+            answers.push(r.value);
+        else
+            errors.push(r.reason instanceof Error ? r.reason.message : String(r.reason));
+    }
+    const yes = answers.filter(Boolean).length;
+    const no = answers.length - yes;
+    // Disagreement is checked BEFORE quorum: 2 yes + 1 no is not a
+    // 2-of-3 pass, it is a contradiction about a fact that has exactly
+    // one true value on one chain.
+    if (yes > 0 && no > 0)
+        return { status: 'disputed', answers, errors };
+    if (answers.length >= required) {
+        return { status: 'agreed', active: yes > 0, agreed: answers.length, queried: urls.length };
+    }
+    return { status: 'unavailable', agreed: answers.length, quorum: required, errors };
+}
+/**
+ * Evaluate an operator the way the spec requires for any decision that
+ * depends on RUNTIME state (e.g. "is settlement attested right now?").
+ *
+ * ── THE MISTAKE THIS FUNCTION EXISTS TO PREVENT ──
+ * A registry record is soulbound, therefore durable. TEE attestation is
+ * transient. Pointing the first at the second produces a claim that is
+ * true when written and silently false later, with nothing in the record
+ * to reveal the drift. We shipped exactly that: our own
+ * `x402-facilitator-attested` record read `active` on-chain while our own
+ * manifest honestly reported `attestation: none` because the enclave was
+ * down. The record was not lying about what it attested — a verification
+ * really did happen — it was being READ as a liveness signal it cannot
+ * carry.
+ *
+ * So the two answers are kept separate and only combined explicitly:
+ *   verified        — "was this operator verified?"      (registry)
+ *   liveAttestation — "is it in that mode right now?"    (manifest)
+ *   attestedNow     — both, which is what you actually gate on.
+ *
+ * Fails CLOSED: any inability to establish the live state yields
+ * attestedNow === false.
+ */
+export async function checkOperatorTrust(opts) {
+    const notes = [];
+    const att = opts.manifest.attestation;
+    // Apply the extension's own "absent verification, treat as none" rule:
+    // a TEE block whose verifier is not dereferenceable cannot be checked
+    // by anyone, so it must not read as attested.
+    let liveAttestation;
+    if (!att) {
+        liveAttestation = 'absent';
+        notes.push('manifest carries no attestation block');
+    }
+    else if (att.type === 'tee' && typeof att.verifier === 'string' && att.verifier.startsWith('https://')) {
+        liveAttestation = 'tee';
+    }
+    else {
+        liveAttestation = 'none';
+        notes.push(att.type === 'tee'
+            ? 'manifest claims tee but its verifier is not a dereferenceable HTTPS URL — treated as none per spec'
+            : `manifest reports attestation: ${att.type ?? 'unknown'}`);
+    }
+    let verified = false;
+    try {
+        // Spread conditionally: under exactOptionalPropertyTypes an
+        // explicit `undefined` is not the same as an absent key.
+        verified = await hasActiveBadge({
+            rpcUrl: opts.rpcUrl, registry: opts.registry, subject: opts.subject,
+            kind: opts.kind,
+            ...(opts.hashKind ? { hashKind: opts.hashKind } : {}),
+            ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+        });
+        if (!verified)
+            notes.push('no active record for this subject+kind in the pinned registry');
+    }
+    catch (e) {
+        notes.push(`registry unreadable (${e instanceof Error ? e.message : String(e)}) — treating as unverified`);
+    }
+    if (verified && liveAttestation !== 'tee') {
+        notes.push('RECORD IS DURABLE, STATE IS NOT: the operator was verified, but is not running in the verified mode right now. Do not treat the record as a liveness signal.');
+    }
+    return { verified, liveAttestation, attestedNow: verified && liveAttestation === 'tee', notes };
+}
+//# sourceMappingURL=badges.js.map

package/dist/badges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"badges.js","sourceRoot":"","sources":["../src/badges.ts"],"names":[],"mappings":"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"}

package/dist/catalog-mcp.d.ts

@@ -0,0 +1,145 @@
+import type { ReconcileQuery, ReconcileVerdict } from './reconcile.js';
+export declare const MCP_PROTOCOL_STATELESS = "2026-07-28";
+/** Newest first; `initialize` negotiation answers with the first of these. */
+export declare const MCP_PROTOCOL_LEGACY: readonly ["2025-11-25", "2025-06-18", "2025-03-26"];
+export declare const MCP_SUPPORTED_VERSIONS: string[];
+export declare const CATALOG_MCP_SERVER_INFO: {
+    readonly name: "flareclaw-open-catalog";
+    readonly title: "The x402 Open Catalog";
+    readonly version: "0.1.0";
+};
+export interface CatalogAnchorInfo {
+    tx: string;
+    digest: string;
+    at: string;
+}
+export interface HostResolution {
+    via: 'dns-txt' | 'well-known';
+    kind: string;
+    attestationUsable: boolean;
+    kindsMatchLive?: boolean;
+    baseUrl?: string;
+}
+export interface CatalogMcpDeps {
+    statePath: string;
+    /** Live anchor state from the serving process; null before first anchor. */
+    anchor?: () => CatalogAnchorInfo | null;
+    /** How often the serving process refreshes the snapshot (ttl honesty). */
+    refreshIntervalMs?: number;
+    /** Live discovery resolution for verify_host; absent → tool reports unavailable. */
+    resolveHost?: (domain: string) => Promise<HostResolution>;
+    /** Rail-side settlement reconciliation (src/x402/reconcile.ts);
+     *  absent → the reconcile tool reports unavailable. */
+    reconcile?: (q: ReconcileQuery) => Promise<ReconcileVerdict>;
+    explorerBase?: string;
+    now?: () => number;
+}
+export interface CatalogMcpHeaders {
+    /** MCP-Protocol-Version */
+    protocolVersion?: string;
+    /** Mcp-Method (SEP-2243) — when present it MUST match the body method. */
+    mcpMethod?: string;
+}
+export interface McpHttpAnswer {
+    status: number;
+    body: unknown | null;
+}
+/** Alphabetical and stays that way: deterministic tools/list order is a
+ *  spec requirement (prompt-cache friendliness), enforced by a test. */
+export declare const CATALOG_MCP_TOOLS: readonly [{
+    readonly name: "catalog_get";
+    readonly description: "Look up Open Catalog entries for one resource URL or domain, across both provenance lanes (bazaar-mirror + discovery). Returns every matching row with its source and re-derivation recipe.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly resource: {
+                readonly type: "string";
+                readonly description: "Resource URL (exact or prefix) or a bare domain name";
+            };
+        };
+        readonly required: readonly ["resource"];
+    };
+}, {
+    readonly name: "catalog_search";
+    readonly description: "Query the Open Catalog: filter by source (bazaar-mirror | discovery), network, or independently-verifiable attestation; paginated. Every row is provenance-tagged — how to re-derive it without trusting this server.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly source: {
+                readonly type: "string";
+                readonly enum: readonly ["bazaar-mirror", "discovery"];
+            };
+            readonly network: {
+                readonly type: "string";
+                readonly description: "e.g. \"coston2\", \"base\", \"eip155:114\"";
+            };
+            readonly attested: {
+                readonly type: "boolean";
+                readonly description: "true → only entries whose attestation claim is independently checkable";
+            };
+            readonly limit: {
+                readonly type: "number";
+                readonly description: "1–500, default 50";
+            };
+            readonly offset: {
+                readonly type: "number";
+            };
+        };
+    };
+}, {
+    readonly name: "catalog_stats";
+    readonly description: "Headline numbers: mirrored vs discovered vs attested counts, networks the Bazaar structurally excludes, the served snapshot's sha256 digest and its on-chain anchor.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {};
+    };
+}, {
+    readonly name: "reconcile";
+    readonly description: "Determinate verdict for one EIP-3009 payment authorization on the Coston2 rail: settled (with the settlement tx + transfers), refused-not-charged (window closed, nonce unconsumed — can never settle), or indeterminate with a machine-readable reason. Every verdict re-derivable from public RPC: authorizationState + AuthorizationUsed logs.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly asset: {
+                readonly type: "string";
+                readonly description: "EIP-3009 asset contract address (0x…)";
+            };
+            readonly payer: {
+                readonly type: "string";
+                readonly description: "The authorizer — the `from` of the authorization (0x…)";
+            };
+            readonly nonce: {
+                readonly type: "string";
+                readonly description: "The 32-byte authorization nonce (0x + 64 hex)";
+            };
+            readonly validBefore: {
+                readonly type: "number";
+                readonly description: "The authorization's validBefore (unix seconds). Required to prove refused-not-charged: an unconsumed nonce inside its window could still settle.";
+            };
+        };
+        readonly required: readonly ["asset", "payer", "nonce"];
+    };
+}, {
+    readonly name: "verify_host";
+    readonly description: "Two-observation verdict for a hostname: a LIVE x402 discovery resolution (DNS TXT → /.well-known/x402 → live capability cross-check) compared against this catalog's last anchored crawl observation. Discovery is not endorsement; this reports checkability, not trustworthiness.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly domain: {
+                readonly type: "string";
+                readonly description: "Bare hostname, e.g. \"api.flareclaw.app\"";
+            };
+        };
+        readonly required: readonly ["domain"];
+    };
+}];
+/** Map a body-parse failure (transport layer) to the spec's JSON-RPC shape. */
+export declare function catalogMcpParseError(message?: string): McpHttpAnswer;
+export declare function handleCatalogMcp(body: unknown, headers: CatalogMcpHeaders, deps: CatalogMcpDeps): Promise<McpHttpAnswer>;
+/**
+ * Same shape family as /.well-known/x402: one host, two well-knowns, one
+ * signed identity — the facilitator serves this next to the x402 manifest
+ * and signs it with the same per-serve Ed25519 lane, so the DNS-published
+ * key vouches for the MCP surface too.
+ */
+export declare function buildMcpServerCard(base: string, deps: CatalogMcpDeps): Record<string, unknown>;
+//# sourceMappingURL=catalog-mcp.d.ts.map

package/dist/catalog-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-mcp.d.ts","sourceRoot":"","sources":["../src/catalog-mcp.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvE,eAAO,MAAM,sBAAsB,eAAe,CAAC;AACnD,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,qDAAsD,CAAC;AACvF,eAAO,MAAM,sBAAsB,UAAmD,CAAC;AAavF,eAAO,MAAM,uBAAuB;;;;CAI1B,CAAC;AAUX,MAAM,WAAW,iBAAiB;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AAE7E,MAAM,WAAW,cAAc;IAC3B,GAAG,EAAE,SAAS,GAAG,YAAY,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,iBAAiB,GAAG,IAAI,CAAC;IACxC,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1D;2DACuD;IACvD,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAC9B,2BAA2B;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE;AA0EvE;wEACwE;AACxE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwDpB,CAAC;AAyJX,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,OAAO,SAA2B,GAAG,aAAa,CAEtF;AAED,wBAAsB,gBAAgB,CAClC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,GAChE,OAAO,CAAC,aAAa,CAAC,CA6FxB;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAe9F"}