@ashlar-blue/x402-trust 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Walter D. Hawkins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @ashlar-blue/x402-trust
+
+**Find an x402 facilitator, and decide whether to trust it before you pay.**
+
+Reference implementation of two proposed x402 extensions:
+
+- **`discovery`** ([x402-foundation/x402 #2979](https://github.com/x402-foundation/x402/pull/2979)) — find a facilitator from a domain name via DNS `TXT` + `/.well-known/x402`. No central directory, no list, no gatekeeper.
+- **`attestations`** ([#3000](https://github.com/x402-foundation/x402/pull/3000)) — verify what a service claims about itself *before* paying it: TEE attestation blocks and soulbound, revocable, evidence-linked reputation records.
+
+Discovery finds a service. Attestations tell you whether to trust it.
+
+## Three verbs
+
+An agent that spends money has to do three things. This library does each in a
+handful of lines, with **zero dependencies** and — for the two verification
+verbs — **zero network and zero trust in us**.
+
+```ts
+import { checkService, Transcript, verifyReceipt } from '@ashlar-blue/x402-trust';
+
+// 1. BEFORE YOU PAY — resolve a service and get a plain decision + reasons.
+const t = await checkService('facilitator.example');
+if (!t.safeToPay) throw new Error(t.reasons.join('; '));   // e.g. off-domain resource, stale manifest
+
+// 2. WHAT YOU PRODUCE — commit the work your agent did to a Merkle transcript.
+const work = new Transcript()
+  .add('inv-002', 'GET /price?asset=XRP', '{"price":"2.99"}');
+const root    = work.root();      // sign or anchor this ONE value
+const receipt = work.prove(0);    // hand a counterparty a proof of just their line
+
+// 3. WHAT YOU'RE HANDED — verify a receipt offline, trusting no one.
+verifyReceipt(receipt);           // true iff the work was in the committed set
+```
+
+`checkService` composes the hardened resolver (same-origin enforcement,
+SSRF/DoS guards, HTTPS-only redirects, live `/supported` cross-check) into one
+call, so you do not re-implement the adversarial edge cases. The verification
+functions are pure [RFC 6962](https://www.rfc-editor.org/rfc/rfc6962) Merkle
+math: if a proof verifies, the claim is true no matter who produced it — an
+enterprise does not have to trust FlareClaw to use FlareClaw's proofs.
+
+Three more offline verifiers cover the artifacts the catalog and reconciler
+emit — `verifyDirectoryEntry` (one host in a census), `verifyReconcileRow` (one
+row of a two-observer reconciliation), and the signed-manifest / evidence
+grammar below.
+
+**Runnable tour:** [`examples/demo.mjs`](./examples/demo.mjs) — `npm run build && node examples/demo.mjs`. Produces work, verifies it, catches a tamper, and refuses a spoofed facilitator, all offline.
+
+The rest of this document is the building blocks `checkService` sits on, for
+callers who want the lower-level surface.
+
+## The Open Catalog, self-hostable (staged for 0.2.0)
+
+Two further modules ship the catalog itself as a reference implementation —
+the "anyone can rebuild this from public data" claim, made executable:
+
+- **`open-catalog`** — the catalog engine: mirror the CDP Bazaar via its own
+  public API (with attribution), crawl `discovery` records breadth-first with
+  per-operator frontier-diversity bounds, and serve a provenance-tagged,
+  sha256-digested snapshot. Run it yourself and you are an independent
+  observer, not a mirror of ours.
+- **`catalog-mcp`** — a transport-free MCP server core for that catalog:
+  stateless protocol revision 2026-07-28 primary, sessionless legacy
+  `initialize` shim, four read tools, a signable Server Card, and evidence
+  (snapshot digest + on-chain anchor) carried in BOTH `_meta` and readable
+  content. Wire it to any HTTP framework in ~20 lines; every dependency is
+  injected.
+
+## Zero dependencies
+
+`npm ls` returns nothing. That is deliberate: a library whose job is *"decide whether to trust a stranger before sending them money"* cannot credibly arrive with a dependency tree you will never read. The entire trust path — DNS record parsing, manifest validation, redirect handling, the `eth_call`, the digest grammar — is auditable in one sitting.
+
+The one consequence: we cannot compute `keccak256` at runtime, so the badge function selector and well-known `kind` hashes are compile-time constants. They are [asserted against `ethers` in the test suite](https://gitlab.com/flareclaw-saving-demo-group/flareclaw-verifier), so they are verified, not trusted. You can pass your own hasher for any other kind.
+
+## Install
+
+```bash
+npm install @ashlar-blue/x402-trust
+```
+
+## Find a facilitator from a domain name
+
+```ts
+import { resolveX402 } from '@ashlar-blue/x402-trust';
+
+const r = await resolveX402('flareclaw.app');
+
+r.via;              // 'dns-txt' — found via _x402.flareclaw.app
+r.manifest.facilitator.baseUrl;
+r.liveKinds;        // fetched from /supported — authoritative over the manifest
+r.kindsMatchLive;   // false = the operator's manifest is stale
+r.attestationUsable // false = treat any TEE claim as absent
+```
+
+Runs in Node out of the box. In a browser or a worker, inject a DNS resolver (DoH) and it works unchanged:
+
+```ts
+await resolveX402('flareclaw.app', { resolveTxt: myDohResolver, fetchImpl: fetch });
+```
+
+### What it refuses to do
+
+These are the extension's security rules, enforced rather than documented:
+
+| Situation | Behaviour |
+|---|---|
+| `wk` in the TXT record points off-domain | hard error (spoofing signal) |
+| Manifest redirects off-domain | hard error — the in-domain rule is re-applied to **every hop**, so the check runs on where the bytes came from, not where you asked |
+| `facilitator.baseUrl` is off-domain | hard error — otherwise any domain could claim someone else's facilitator, and point every crawler at them |
+| TEE block whose `verifier` is not a dereferenceable HTTPS URL | `attestationUsable: false` — an unverifiable claim must not read as a verified one |
+
+## Decide whether to trust it
+
+The important part, and the part most callers get wrong:
+
+```ts
+import { checkOperatorTrust } from '@ashlar-blue/x402-trust';
+
+const trust = await checkOperatorTrust({
+  manifest: r.manifest,
+  rpcUrl:   'https://coston2-api.flare.network/ext/C/rpc',
+  registry: '0xb02f83e994830C4954c89C10482665A3963229c5',  // PIN THIS
+  subject:  r.manifest.badges.subject,
+  kind:     'x402-facilitator-attested',
+});
+
+trust.verified;         // was this operator ever verified?      (registry)
+trust.liveAttestation;  // is it in that mode right now?          (manifest)
+trust.attestedNow;      // both — this is what you gate on
+```
+
+### Why these are three values and not one
+
+A registry record is soulbound, therefore **durable**. TEE attestation is **transient**. Point the first at the second and you get a claim that is true when written and silently false later, with nothing in the record to reveal the drift.
+
+We shipped exactly that bug. 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, and its evidence still hashes — it was being *read* as a liveness signal it cannot carry.
+
+So:
+
+| Question | Source of truth |
+|---|---|
+| *Was this operator verified, by whom, against what evidence?* | the registry record (durable, revocable) |
+| *Is it operating that way right now?* | the operator's live manifest (self-degrading) |
+
+`checkOperatorTrust` keeps them apart and only combines them explicitly. It **fails closed**: anything it cannot establish yields `attestedNow: false`.
+
+`hasActiveBadge` likewise **throws rather than returning `false`** when it cannot reach the chain. "I could not check" and "I checked and it is not active" are different answers, and collapsing them is how an RPC outage becomes a silent trust upgrade.
+
+## Drop into the official SDK (`@x402/core`, Stripe Machine Payments)
+
+Every integration built from the [Stripe Machine Payments sample](https://docs.stripe.com/payments/machine/x402) (and most others built on `@x402/core`) hardcodes its facilitator:
+
+```ts
+import { facilitator } from "@coinbase/x402";           // ← a constant
+const client = new HTTPFacilitatorClient(facilitator);
+```
+
+`discoverFacilitator()` turns that constant into a resolved, verified choice — one line changes:
+
+```ts
+import { HTTPFacilitatorClient } from "@x402/core/server";
+import { discoverFacilitator } from "@ashlar-blue/x402-trust";
+
+const { config, resolution } = await discoverFacilitator("facilitator.example.com", {
+  scheme: "exact",
+  network: "eip155:8453",     // require support, judged against the LIVE /supported
+});
+const client = new HTTPFacilitatorClient(config);        // drop-in
+
+resolution.attestationUsable; // and you know whether its TEE claim is checkable
+```
+
+No dependency on `@x402/core` is taken — the returned `config` is a plain `{ url, timeoutMs? }` matching core's `FacilitatorConfig` shape, so your SDK version is the only SDK version involved.
+
+One honest constraint: `HTTPFacilitatorClient` calls the fixed paths `/verify`, `/settle`, `/supported`. A discovered manifest declaring different endpoint paths cannot be expressed as a `FacilitatorConfig`, so `discoverFacilitator()` **fails at resolve time** (`reason: "endpoints"`) instead of handing you a config that 404s at pay time.
+
+## Evidence references
+
+Records point at the evidence that justified them. A bare URI has the trust model of brand reputation — it can be edited or taken down after the fact — so records carry a digest:
+
+```ts
+import { encodeEvidenceRef, parseEvidenceRef, sameEvidence, canonicalJson } from '@ashlar-blue/x402-trust';
+
+const ref = encodeEvidenceRef({
+  alg: 'sha256',
+  hex: '...',
+  ref: 'https://api.flareclaw.app/evidence/<digest>.json',
+});
+// "x402ev/1; digest=sha256:...; ref=https://..."
+```
+
+Verify one by fetching the artifact, canonicalizing it ([RFC 8785 JCS](https://www.rfc-editor.org/rfc/rfc8785)), hashing, and comparing to the digest. A fetched artifact that **mismatches** its digest is evidence-invalid and must be a hard negative; an artifact that is merely **unreachable** should down-weight the record, not revoke it. Link rot and tampering are different failures.
+
+## Status
+
+`0.2.0`. Both extensions are open pull requests, not ratified standards — the wire formats may change in response to review, and this package tracks them. It is published because a specification with an installable implementation is a proposal with users attached, and one without is a PDF. Requires Node ≥20 (the manifest signer validates UTF-16 well-formedness via `String.prototype.isWellFormed`).
+
+MIT.

package/dist/attested-directory.d.ts

@@ -0,0 +1,78 @@
+export declare const DIRECTORY_SCHEMA = "x402-attested-directory/1";
+/**
+ * What a census can say about a host. Ordered strongest to weakest claim, and
+ * deliberately parallel to the fc-liveness vocabulary: `unreachable` is a
+ * statement about OUR vantage on this date, never about the host.
+ */
+export type DirectoryVerdict = 'discoverable-verified' | 'discoverable' | 'one-edit-away' | 'not-discoverable' | 'unreachable';
+export interface DirectoryEntry {
+    domain: string;
+    verdict: DirectoryVerdict;
+    /** One line a reader can check against the columns, never an accusation. */
+    detail: string;
+    /** The record as observed, verbatim, when there was one. */
+    record?: string;
+}
+export interface Census {
+    schema: typeof DIRECTORY_SCHEMA;
+    observedAt: string;
+    observer: string;
+    /** sha256 of the program that produced this. "Re-run it" needs a referent. */
+    methodDigest: string;
+    /** How the target set was chosen — a census over a hand-picked set is not a census. */
+    targetSource: string;
+    size: number;
+    inputRoot: string;
+    outputRoot: string;
+    tally: Record<DirectoryVerdict, number>;
+    /** Present ONLY when the run was genuinely attested. Absent means not. */
+    attestation?: {
+        type: string;
+        imageDigest?: string;
+        tokenDigest?: string;
+    };
+}
+export declare function buildCensus(entries: DirectoryEntry[], meta: {
+    observer: string;
+    methodDigest: string;
+    targetSource: string;
+    observedAt: string;
+    attestation?: Census['attestation'];
+}): Census;
+/** The digest a census is anchored under. */
+export declare function censusDigest(c: Census): string;
+/** Prove ONE host's verdict without disclosing the rest of the census. */
+export declare function proveEntry(entries: DirectoryEntry[], index: number): {
+    entry: DirectoryEntry;
+    index: number;
+    size: number;
+    proof: string[];
+};
+/**
+ * Check one host's verdict against a published outputRoot, holding nothing
+ * else. This is what makes the census checkable retail rather than wholesale.
+ */
+export declare function verifyEntry(entry: DirectoryEntry, index: number, size: number, proof: string[], outputRoot: string): boolean;
+/**
+ * Re-derive both roots from a full target list and result set. A second
+ * observer runs this against their OWN sweep: matching roots mean identical
+ * observations, and differing roots localise the disagreement rather than
+ * hiding it. Disagreement is the signal.
+ */
+export declare function recomputeRoots(entries: DirectoryEntry[]): {
+    inputRoot: string;
+    outputRoot: string;
+};
+/**
+ * Compare two censuses over the same targets. Returns the domains whose
+ * verdicts differ — the two-observer diff that makes a directory falsifiable.
+ */
+export declare function diffCensus(a: DirectoryEntry[], b: DirectoryEntry[]): {
+    sameTargets: boolean;
+    disagreements: {
+        domain: string;
+        a: DirectoryVerdict;
+        b: DirectoryVerdict;
+    }[];
+};
+//# sourceMappingURL=attested-directory.d.ts.map

package/dist/attested-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attested-directory.d.ts","sourceRoot":"","sources":["../src/attested-directory.ts"],"names":[],"mappings":"AA6CA,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACtB,uBAAuB,GACvB,cAAc,GACd,eAAe,GACf,kBAAkB,GAClB,aAAa,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gBAAgB,CAAC;IAC1B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,MAAM;IACnB,MAAM,EAAE,OAAO,gBAAgB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACxC,0EAA0E;IAC1E,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9E;AA2DD,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,IAAI,EAAE;IACzD,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;CACvC,GAAG,MAAM,CAgBT;AAED,6CAA6C;AAC7C,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG;IAClE,KAAK,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;CACvE,CAIA;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACvB,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GACxF,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAKnG;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,CAAC,EAAE,cAAc,EAAE,GAAG;IAClE,WAAW,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,gBAAgB,CAAC;QAAC,CAAC,EAAE,gBAAgB,CAAA;KAAE,EAAE,CAAC;CACvG,CAWA"}

package/dist/attested-directory.js

@@ -0,0 +1,163 @@
+// GENERATED from src/x402/attested-directory.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.
+/**
+ * attested-directory — a census of x402 discovery records that a stranger can
+ * check without trusting the party who produced it.
+ *
+ * THE PROBLEM THIS EXISTS FOR. Every directory in this ecosystem asks you to
+ * trust an index. The measured consequence (our own sweep, 2026-08-18) is a
+ * catalogue where 78% of listings have exactly one payer ever, five listings
+ * carry 45% of all traffic, and listings age out for being unpopular. An index
+ * that deletes you for having no customers is not infrastructure, and "trust
+ * our index" is not a claim anyone should accept — including about ours.
+ *
+ * WHAT REPLACES THE TRUST. A census here commits to three things at once:
+ *
+ *   methodDigest  WHICH PROGRAM ran. Content-addressed, so "re-run it" is a
+ *                 well-defined instruction rather than an invitation to write
+ *                 your own and hope it matches.
+ *   inputRoot     WHICH TARGETS it ran over. Without this a publisher can
+ *                 quietly drop hosts whose verdicts it dislikes and no reader
+ *                 can tell — the omission problem, applied to directories.
+ *   outputRoot    WHAT IT FOUND, as an RFC 6962 tree rather than a flat hash.
+ *
+ * The tree is the part that makes it usable. A flat digest over 1,564 verdicts
+ * forces anyone checking ONE host to download all 1,564 and recompute. With a
+ * Merkle root, "host X had verdict Y in census C" is eleven hashes, and the
+ * reader never sees the other 1,563 — which matters because a directory that
+ * can only be checked wholesale will not be checked at all.
+ *
+ * WHAT THIS DOES NOT CLAIM. Being signed inside an enclave would prove the
+ * program was not tampered with between build and run. That is a stronger
+ * claim than a census signed anywhere else, and it is deliberately NOT made
+ * here: this module produces the artifact, and `attestation` is populated only
+ * when a caller supplies a real one. A census with no attestation says so.
+ *
+ * Discovery is not endorsement. A verdict describes what a program observed
+ * from one vantage at one time. It says nothing about whether the operator is
+ * honest, and the vocabulary below is chosen so it cannot be read that way.
+ */
+import { createHash } from 'node:crypto';
+import { jcsCanonical, assertJcsSafe } from './manifest-sig.js';
+import { transcriptRoot, inclusionProof, verifyInclusion } from './merkle-transcript.js';
+export const DIRECTORY_SCHEMA = 'x402-attested-directory/1';
+/** Targets as tree leaves: the question asked, independent of the answer. */
+const inputLeaf = (domain) => ({ drawId: domain, nonce: 'x402-directory-target', seed: '0x00' });
+/**
+ * Verdict leaves. The domain is inside the leaf, so a proof cannot be moved
+ * from one host to another — without it, a verdict for a host that passed
+ * could be replayed as a verdict for one that did not.
+ */
+const outputLeaf = (e) => {
+    // Commit the OBSERVED RECORD, not just the verdict and prose. Without it a
+    // proof bundle's `record` could be swapped for arbitrary content and still
+    // verify — a "verified" census entry carrying a fabricated record — and
+    // two sweeps differing only in the observed record would recompute
+    // identical roots, so recomputeRoots would miss a real observation
+    // difference. `record ?? null` keeps the leaf defined when a host has no
+    // record. (Crypto review D2, 2026-08-19.)
+    const core = { domain: e.domain, verdict: e.verdict, detail: e.detail, record: e.record ?? null };
+    assertJcsSafe(core);
+    return {
+        drawId: e.domain,
+        nonce: e.verdict,
+        seed: '0x' + createHash('sha256').update(jcsCanonical(core), 'utf8').digest('hex'),
+    };
+};
+/**
+ * Reject duplicate domains. A census with the same domain twice — one verdict
+ * at index i, a different one at index j — lets a publisher anchor ONE digest
+ * and then serve each retail verifier a valid inclusion proof for whichever
+ * verdict suits, both verifying against the same outputRoot. That is exactly
+ * the equivocation CT log operators are audited against, and it makes the
+ * retail claim "host X had verdict Y in census C" ill-defined. (Review D1.)
+ */
+function assertCanonicalOrder(entries) {
+    // Unique AND ascending by domain, asserted rather than imposed. buildCensus
+    // must NOT silently re-sort: proveEntry/verifyEntry operate on the SAME
+    // array a caller holds, so if buildCensus reordered internally, a caller's
+    // index-based proof would not verify against the census's own outputRoot.
+    // classifySweep already yields this order; anything else is a caller bug.
+    const seen = new Set();
+    let prev = '';
+    for (const e of entries) {
+        if (seen.has(e.domain))
+            throw new Error(`[x402-directory] duplicate domain in census: ${e.domain}`);
+        if (prev && e.domain < prev) {
+            throw new Error(`[x402-directory] entries must be sorted by domain (${e.domain} after ${prev}) — use classifySweep`);
+        }
+        seen.add(e.domain);
+        prev = e.domain;
+    }
+}
+const EMPTY_TALLY = () => ({
+    'discoverable-verified': 0, discoverable: 0, 'one-edit-away': 0,
+    'not-discoverable': 0, unreachable: 0,
+});
+export function buildCensus(entries, meta) {
+    assertCanonicalOrder(entries);
+    const tally = EMPTY_TALLY();
+    for (const e of entries)
+        tally[e.verdict]++;
+    return {
+        schema: DIRECTORY_SCHEMA,
+        observedAt: meta.observedAt,
+        observer: meta.observer,
+        methodDigest: meta.methodDigest,
+        targetSource: meta.targetSource,
+        size: entries.length,
+        inputRoot: transcriptRoot(entries.map((e) => inputLeaf(e.domain))),
+        outputRoot: transcriptRoot(entries.map(outputLeaf)),
+        tally,
+        ...(meta.attestation ? { attestation: meta.attestation } : {}),
+    };
+}
+/** The digest a census is anchored under. */
+export function censusDigest(c) {
+    assertJcsSafe(c);
+    return 'sha256:' + createHash('sha256').update(jcsCanonical(c), 'utf8').digest('hex');
+}
+/** Prove ONE host's verdict without disclosing the rest of the census. */
+export function proveEntry(entries, index) {
+    const entry = entries[index];
+    if (!entry)
+        throw new Error(`index ${index} outside census of ${entries.length}`);
+    return { entry, index, size: entries.length, proof: inclusionProof(entries.map(outputLeaf), index) };
+}
+/**
+ * Check one host's verdict against a published outputRoot, holding nothing
+ * else. This is what makes the census checkable retail rather than wholesale.
+ */
+export function verifyEntry(entry, index, size, proof, outputRoot) {
+    return verifyInclusion(outputLeaf(entry), index, size, proof, outputRoot);
+}
+/**
+ * Re-derive both roots from a full target list and result set. A second
+ * observer runs this against their OWN sweep: matching roots mean identical
+ * observations, and differing roots localise the disagreement rather than
+ * hiding it. Disagreement is the signal.
+ */
+export function recomputeRoots(entries) {
+    return {
+        inputRoot: transcriptRoot(entries.map((e) => inputLeaf(e.domain))),
+        outputRoot: transcriptRoot(entries.map(outputLeaf)),
+    };
+}
+/**
+ * Compare two censuses over the same targets. Returns the domains whose
+ * verdicts differ — the two-observer diff that makes a directory falsifiable.
+ */
+export function diffCensus(a, b) {
+    const byDomainB = new Map(b.map((e) => [e.domain, e]));
+    const sameTargets = a.length === b.length && a.every((e) => byDomainB.has(e.domain));
+    const disagreements = [];
+    for (const e of a) {
+        const other = byDomainB.get(e.domain);
+        if (other && other.verdict !== e.verdict) {
+            disagreements.push({ domain: e.domain, a: e.verdict, b: other.verdict });
+        }
+    }
+    return { sameTargets, disagreements };
+}
+//# sourceMappingURL=attested-directory.js.map

package/dist/attested-directory.js.map

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

package/dist/badges.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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 declare const KNOWN_BADGE_KINDS: Readonly<Record<string, string>>;
+/** Resolve a kind name (or pass through a pre-hashed bytes32). */
+export declare function resolveKind(kind: string, hashKind?: (s: string) => string): string;
+export interface BadgeQuery {
+    /** JSON-RPC endpoint for the chain the registry lives on. */
+    rpcUrl: string;
+    /** Registry contract address. PIN THIS — see the note in hasActiveBadge. */
+    registry: string;
+    /** Address the record is about (facilitator settlement address, etc.). */
+    subject: string;
+    /** Kind name from KNOWN_BADGE_KINDS, or a pre-hashed bytes32. */
+    kind: string;
+    hashKind?: (s: string) => string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * `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 declare function hasActiveBadge(q: BadgeQuery): Promise<boolean>;
+export interface BadgeQuorumQuery extends Omit<BadgeQuery, 'rpcUrl'> {
+    /** Independent RPC endpoints. Two must AGREE for an answer. */
+    rpcUrls: string[];
+    /** How many agreeing answers are required. Default 2 (or all, if fewer). */
+    quorum?: number;
+}
+export type BadgeQuorumResult = {
+    status: 'agreed';
+    active: boolean;
+    agreed: number;
+    queried: number;
+}
+/** Endpoints returned CONFLICTING answers — someone is lying or broken. */
+ | {
+    status: 'disputed';
+    answers: boolean[];
+    errors: string[];
+}
+/** Too few endpoints answered to reach quorum. Not a negative answer. */
+ | {
+    status: 'unavailable';
+    agreed: number;
+    quorum: number;
+    errors: string[];
+};
+/**
+ * `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 declare function hasActiveBadgeQuorum(q: BadgeQuorumQuery): Promise<BadgeQuorumResult>;
+export interface OperatorTrust {
+    /** The durable claim: a verification happened and has not been revoked. */
+    readonly verified: boolean;
+    /** The live claim, read from the operator's own manifest right now. */
+    readonly liveAttestation: 'tee' | 'none' | 'absent';
+    /**
+     * True only when the durable record AND the live state agree. This is
+     * the value to gate a state-dependent decision on.
+     */
+    readonly attestedNow: boolean;
+    readonly notes: readonly string[];
+}
+/**
+ * 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 declare function checkOperatorTrust(opts: {
+    manifest: {
+        attestation?: {
+            type?: string;
+            verifier?: string;
+        };
+    };
+    rpcUrl: string;
+    registry: string;
+    subject: string;
+    kind: string;
+    hashKind?: (s: string) => string;
+    fetchImpl?: typeof fetch;
+}): Promise<OperatorTrust>;
+//# sourceMappingURL=badges.d.ts.map

package/dist/badges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badges.d.ts","sourceRoot":"","sources":["../src/badges.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI7D,CAAC;AAKH,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAYlF;AAED,MAAM,WAAW,UAAU;IACvB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CA6BpE;AAID,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC;IAChE,+DAA+D;IAC/D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GACvB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACxE,2EAA2E;GACzE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE;AAC9D,yEAAyE;GACvE;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+B1F;AAID,MAAM,WAAW,aAAa;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,eAAe,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IACpD;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC3C,QAAQ,EAAE;QAAE,WAAW,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IACjC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC5B,GAAG,OAAO,CAAC,aAAa,CAAC,CAwCzB"}