@naulon/wayfarer 0.1.1

package/dist/gateway.js

@@ -0,0 +1,187 @@
+/**
+ * Gateway buyer — the memo-LESS Circle rail (Base + every other Gateway chain). Where the
+ * memo rail (memo.ts) relays a raw USDC EIP-3009 authorization, the gateway rail signs an
+ * EIP-3009 authorization against the Circle **GatewayWallet** contract (the `extra.
+ * verifyingContract` the gate advertises) and posts the full x402 envelope `{x402Version,
+ * payload:{authorization,signature}, resource, accepted}` as `payment-signature` — the shape
+ * Circle's facilitator `verify` requires (a bare/mock shape is rejected 400
+ * `x402Version/resource/accepted/payload: Required` — the Base-settle bug this path fixes).
+ *
+ * Custody-free seam (mirrors `memoBuyer(MemoSigner)`): a cloud host injects a sign-only
+ * `GatewaySigner` (its address + a `signTypedData` that signs the GatewayWallet-domain typed
+ * data elsewhere — a grant-checked BFF holding the encrypted session key), so the private key
+ * never lives in this process. A viem `PrivateKeyAccount` satisfies the same shape, keeping
+ * the CLI/self-host path (env `BUYER_PRIVATE_KEY`) symmetric. The signing wraps the SDK's
+ * `BatchEvmScheme` so the signed shape / validity clamp can never drift from the rail (the
+ * same reason the gate's own `gatewayLegPayload` does — see tollgate/src/x402.ts).
+ *
+ * The Gateway balance is funded out-of-band (a one-time deposit into Circle's non-custodial
+ * Gateway Wallet); the pay path here is pure sign-only. On the env/CLI path `init()` still
+ * deposits via the SDK `GatewayClient` for backwards compatibility.
+ */
+import {} from "viem";
+import { activeNetwork, getConfig } from "@naulon/shared";
+import { classifyPaymentError, classifySignerRefusal, probe, } from "./buyer.js";
+import { runPaidFetch } from "./paidFetch.js";
+function envAccountKey() {
+    const cfg = getConfig();
+    if (!cfg.BUYER_PRIVATE_KEY) {
+        throw new Error(`PAYMENT_MODE=gateway on ${activeNetwork().chainName} requires an injected signer or a funded ` +
+            `BUYER_PRIVATE_KEY (a wallet whose USDC is deposited in the Circle Gateway Wallet).`);
+    }
+    return (cfg.BUYER_PRIVATE_KEY.startsWith("0x") ? cfg.BUYER_PRIVATE_KEY : `0x${cfg.BUYER_PRIVATE_KEY}`);
+}
+/** Sign one Gateway leg's EIP-3009 authorization against the GatewayWallet domain and return
+ *  the full envelope `{x402Version, payload, resource, accepted}` — exactly the gate's
+ *  `gatewayLegPayload` shape. Wraps the SDK's `BatchEvmScheme` so the domain / validity clamp
+ *  never drifts from the rail. SDK loaded lazily so the mock path never pulls it in. */
+export async function gatewayLegPayload(signer, quoted, x402Version) {
+    // Both pre-sign guards live HERE, not in the callers. They used to sit in gatewayBuyer only,
+    // while railBuyer (the mixed-fleet path) called this helper directly and got neither — the
+    // classic drifted-sibling shape. Taking the whole `quoted` instead of bare requirements makes
+    // them unbypassable: a caller cannot reach the signer without passing through both.
+    //
+    // 1. The Circle SDK's batched pay signs ONE leg. An N-leg (operator-fee) quote would be silently
+    //    underpaid — refuse loudly and point at the memo rail (N-leg-capable).
+    if (quoted.legs && quoted.legs.length > 1) {
+        throw new Error(`gateway (Circle SDK) mode cannot pay a ${quoted.legs.length}-leg toll (operator fee): ` +
+            `the SDK signs only the author leg. Use the memo (Arc) rail for multi-leg settlement.`);
+    }
+    const requirements = quoted.requirements;
+    // 2. Refuse to sign a Circle envelope for a 402 that is not actually a Gateway batching option.
+    if (requirements.extra?.name !== "GatewayWalletBatched") {
+        throw new Error("gateway mode expects a Circle Gateway batching option (extra.name 'GatewayWalletBatched'); " +
+            "the gate advertised a non-gateway 402. Check PAYMENT_MODE / the settlement network.");
+    }
+    const { BatchEvmScheme } = await import("@circle-fin/x402-batching/client");
+    const scheme = new BatchEvmScheme(signer);
+    const signed = await scheme.createPaymentPayload(x402Version, requirements);
+    return { ...signed, resource: quoted.resource, accepted: requirements };
+}
+export function gatewayBuyer(signer) {
+    const cfg = getConfig();
+    // Resolve the signer once. An injected signer NEVER reads BUYER_PRIVATE_KEY (the whole point
+    // of the cloud wallet — the key lives in the grant-checked BFF, not this process).
+    let resolved = signer ?? null;
+    const getSigner = async () => {
+        if (resolved)
+            return resolved;
+        const { privateKeyToAccount } = await import("viem/accounts");
+        return (resolved = privateKeyToAccount(envAccountKey()));
+    };
+    const fallbackAddress = signer ? signer.address : (cfg.BUYER_ADDRESS ?? "0x");
+    return {
+        get address() {
+            return resolved?.address ?? fallbackAddress;
+        },
+        async init() {
+            // Custody-free out-of-band deposit: the Gateway balance is funded separately, so the
+            // injected-signer (cloud) path is a no-op. The env/CLI path keeps the SDK deposit for
+            // backwards compatibility — it needs the raw key, which only exists on that path.
+            if (signer)
+                return;
+            // Resolve the env-key address here so `address` is honest from init onward, matching
+            // memoBuyer (which resolves eagerly at construction). Without this the env/CLI path
+            // reported the "0x" placeholder until the first pay — agent.ts logs `wallet ${address}`
+            // BEFORE init(), so an operator saw `wallet 0x` instead of the real derived address.
+            await getSigner();
+            const { GatewayClient } = await import("@circle-fin/x402-batching/client");
+            const client = new GatewayClient({ chain: activeNetwork().chainName, privateKey: envAccountKey() });
+            console.log(`  depositing ${cfg.DEPOSIT_AMOUNT_USDC} USDC into the Gateway Wallet...`);
+            const result = await client.deposit(cfg.DEPOSIT_AMOUNT_USDC);
+            console.log(`  deposit tx ${result.depositTxHash}`);
+        },
+        price(url, kind) {
+            return probe(url, kind, this.address).then((o) => (o.status === "gated" ? o.quoted : null));
+        },
+        async fetch(url, kind, guard) {
+            const address = this.address;
+            // The shared loop owns probe→moved-guard→paid-GET→classify. The gateway rail supplies only
+            // how it builds the payment (the two pre-sign guards live INSIDE the builder so a bad quote
+            // throws into onSignError, keeping a typed result) and how it classifies a sign throw
+            // (grant refusal → typed needs_topup; any other → classifyPaymentError — a gateway sign path
+            // never sees a socket error, the shared loop handles that as a rail-agnostic origin_error).
+            return runPaidFetch(url, kind, address, guard, async (quoted) => {
+                // Both pre-sign guards (N-leg refusal + GatewayWalletBatched check) now live inside
+                // gatewayLegPayload, so this rail and railBuyer enforce them identically. They still
+                // throw into onSignError below, keeping a typed Fetched.
+                const payload = await gatewayLegPayload(await getSigner(), quoted, 2);
+                return Buffer.from(JSON.stringify(payload)).toString("base64");
+            }, (error) => {
+                const refusal = classifySignerRefusal(error);
+                return refusal
+                    ? { ok: false, error, ...refusal }
+                    : { ok: false, error, ...classifyPaymentError(error) };
+            });
+        },
+    };
+}
+/**
+ * Out-of-band, custody-free deposit into the Circle Gateway Wallet — the non-custodial contract that
+ * holds the buyer's unified balance (Circle infra, buyer-controlled; naulon custodies nothing). The
+ * cloud (injected-signer) path funds the Gateway balance HERE, out of band, because `gatewayBuyer.init()`
+ * is a deposit NO-OP when a signer is injected (the key lives in the grant-checked BFF, not this process).
+ * The self-host/CLI path still deposits inside `init()`; this is the standalone entry a deposit
+ * script/operator calls. SDK loaded lazily so the mock/memo paths never pull it in.
+ */
+export async function gatewayDeposit(opts) {
+    const { GatewayClient } = await import("@circle-fin/x402-batching/client");
+    const client = new GatewayClient({ chain: opts.chain, privateKey: opts.privateKey });
+    return client.deposit(opts.amountUsdc);
+}
+/** Read the wallet + Gateway balances for a key — the preflight a deposit script shows before it moves
+ *  funds, and the check the buyer uses to see if its unified balance covers a toll. Pass `address` to
+ *  read ANOTHER account's balances (e.g. confirm the AUTHOR received a settle) — the client key only
+ *  authenticates the read, it needn't own the address. SDK loaded lazily. */
+export async function gatewayBalances(opts) {
+    const { GatewayClient } = await import("@circle-fin/x402-batching/client");
+    return new GatewayClient({ chain: opts.chain, privateKey: opts.privateKey }).getBalances(opts.address);
+}
+/**
+ * Look up a single Gateway transfer (a settlement) by its Circle id — the `settlementRef` a gateway
+ * settle stamps. On the Gateway rail that ref is a **Circle UUID, not an on-chain tx hash**; the
+ * response carries the authoritative `status` plus the eventual on-chain `txHash`. This is the
+ * correct "did the settle land?" check — pair `status` with `classifyGatewaySettlement`. SDK lazy.
+ */
+export async function gatewayTransferStatus(opts) {
+    const { GatewayClient } = await import("@circle-fin/x402-batching/client");
+    return new GatewayClient({ chain: opts.chain, privateKey: opts.privateKey }).getTransferById(opts.id);
+}
+/**
+ * Search Gateway transfers with optional filters (`to`/`from`/`status`/`network`/date range). Use to
+ * confirm a payee (author) received without holding the transfer id — e.g. `{ to: authorAddress }`.
+ * SDK loaded lazily.
+ */
+export async function gatewayTransfers(opts) {
+    const { chain, privateKey, ...params } = opts;
+    const { GatewayClient } = await import("@circle-fin/x402-batching/client");
+    return new GatewayClient({ chain, privateKey }).searchTransfers(params);
+}
+/**
+ * Classify a Circle Gateway transfer `status` into settled / pending / failed. This is the CODE form
+ * of the hard-won rule that a Gateway settle credits the payee's OFF-CHAIN Gateway balance — so
+ * `balanceOf(payee)` is the wrong check and the transfer's own `status` is the authoritative signal.
+ * `completed` ⇒ settled; the in-pipeline states ⇒ pending; `failed` ⇒ failed. An unknown/future status
+ * is treated as `pending` — never falsely report the money landed.
+ */
+export function classifyGatewaySettlement(status) {
+    switch (status) {
+        case "completed":
+            return "settled";
+        case "failed":
+            return "failed";
+        case "received":
+        case "batched":
+        case "confirmed":
+            return "pending";
+        default: {
+            // Exhaustiveness guard: if Circle adds a TransferStatus, this line fails tsc —
+            // forcing a human to classify it, NOT silently bucketing it as pending. At
+            // runtime an unknown value is treated as pending (never falsely "settled").
+            const _exhaustive = status;
+            void _exhaustive;
+            return "pending";
+        }
+    }
+}
+//# sourceMappingURL=gateway.js.map

package/dist/gateway.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * Wayfarer CLI — an autonomous research agent that pays per citation.
+ *
+ *   npm run wayfarer -- "what does the author say about payment and passage?"
+ *
+ * It discovers essays, decides which are worth paying to cite under a budget
+ * (visible reasoning, not hardcoded), pays the naulon through the tollgate, and
+ * grounds a cited answer. Requires a running tollgate (npm run tollgate).
+ */
+import { run } from "./lib.js";
+const topic = process.argv.slice(2).join(" ").trim();
+if (!topic) {
+    console.error('usage: npm run wayfarer -- "<research topic>"');
+    process.exit(1);
+}
+const result = await run(topic, (line) => console.log(line));
+console.log("\n" + "─".repeat(60));
+console.log(result.answer);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACrD,IAAI,CAAC,KAAK,EAAE,CAAC;IACX,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAE7D,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;AACnC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC"}

package/dist/lib.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @naulon/wayfarer — public library surface.
+ *
+ * The autonomous buy-side research agent: discover → quote → appraise → decide →
+ * pay → ground, with reusable Citation Licenses (pay once, re-read free). This
+ * barrel is the side-effect-free entry the package.json `exports` map points at;
+ * the CLI (`./index.ts`) is a thin consumer of it, never the other way round.
+ *
+ * Stage-name map (buy-side spec → the genuine export):
+ *   quote → probePrice (free 402 probe, no spend)
+ *   pay   → selectBuyer + the Buyer seam (mock | memo | gateway)
+ *   read  → rereadWithLicense (free re-read of a held live license)
+ */
+export { run } from "./agent.ts";
+export type { Logger, RunOptions } from "./agent.ts";
+export { tollgateBase, articleUrl, fetchJwks, verifyAgainst } from "./agent.ts";
+export { discover } from "./discover.ts";
+export { appraise } from "./appraise.ts";
+export { probe, probePrice, probeFailure, assemblePayment, rereadWithLicense, selectBuyer, quotedTotalAtomic, tollMovedOrNull, classifyPaymentError, } from "./buyer.ts";
+export type { Buyer, Quoted, LegRequirements, Fetched, FetchErrorCode, PayGuard, ProbeOutcome } from "./buyer.ts";
+export { mockBuyer } from "./pay.ts";
+export { gatewayBuyer, gatewayDeposit, gatewayBalances, gatewayTransferStatus, gatewayTransfers, classifyGatewaySettlement, } from "./gateway.ts";
+export type { GatewaySigner, GatewayDepositOpts, GatewaySettlementState } from "./gateway.ts";
+export { memoBuyer, signMemoPayment } from "./memo.ts";
+export type { MemoSigner } from "./memo.ts";
+export { railBuyer } from "./rail.ts";
+export type { RailSigners } from "./rail.ts";
+export { decide, DEFAULT_POLICY, spendGate } from "./decide.ts";
+export type { DecisionPolicy, DecideContext, SpendVerdict } from "./decide.ts";
+export { authorizeOrigin } from "./origin-policy.ts";
+export type { OriginRequest, OriginVerdict, PayableTarget } from "./origin-policy.ts";
+export { allocateByContribution } from "./allocation.ts";
+export type { SourceAllocation } from "./allocation.ts";
+export { decodeHeld, fileHeldStore, isLive, loadHeld, memoryHeldStore, saveHeld } from "./licenseStore.ts";
+export type { HeldLicense, HeldStore } from "./licenseStore.ts";
+export { buildPopProof } from "./pop.ts";
+export { getWallet } from "./wallet.ts";
+export type { AgentWallet } from "./wallet.ts";
+export type { Candidate, PricedCandidate, AppraisedCandidate, Action, Decision, Source, RunResult, } from "./types.ts";
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACjC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAKrD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhF,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EACL,KAAK,EACL,UAAU,EACV,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAClH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAC9F,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACvD,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM/E,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC3G,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,YAAY,EACV,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,MAAM,EACN,QAAQ,EACR,MAAM,EACN,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/lib.js

@@ -0,0 +1,44 @@
+/**
+ * @naulon/wayfarer — public library surface.
+ *
+ * The autonomous buy-side research agent: discover → quote → appraise → decide →
+ * pay → ground, with reusable Citation Licenses (pay once, re-read free). This
+ * barrel is the side-effect-free entry the package.json `exports` map points at;
+ * the CLI (`./index.ts`) is a thin consumer of it, never the other way round.
+ *
+ * Stage-name map (buy-side spec → the genuine export):
+ *   quote → probePrice (free 402 probe, no spend)
+ *   pay   → selectBuyer + the Buyer seam (mock | memo | gateway)
+ *   read  → rereadWithLicense (free re-read of a held live license)
+ */
+// ── pipeline entry ──────────────────────────────────────────────────────────
+export { run } from "./agent.js";
+// Pipeline primitives a second consumer (the MCP server) reuses to resolve an
+// article URL from a slug against the configured gate, and to verify a captured
+// license against the gate's JWKS — single-sourced here so the two can't drift.
+export { tollgateBase, articleUrl, fetchJwks, verifyAgainst } from "./agent.js";
+// ── discover ────────────────────────────────────────────────────────────────
+export { discover } from "./discover.js";
+// ── appraise ────────────────────────────────────────────────────────────────
+export { appraise } from "./appraise.js";
+// ── quote + pay (the Buyer seam) ────────────────────────────────────────────
+export { probe, probePrice, probeFailure, assemblePayment, rereadWithLicense, selectBuyer, quotedTotalAtomic, tollMovedOrNull, classifyPaymentError, } from "./buyer.js";
+export { mockBuyer } from "./pay.js";
+export { gatewayBuyer, gatewayDeposit, gatewayBalances, gatewayTransferStatus, gatewayTransfers, classifyGatewaySettlement, } from "./gateway.js";
+export { memoBuyer, signMemoPayment } from "./memo.js";
+export { railBuyer } from "./rail.js";
+// ── decide (policy) ─────────────────────────────────────────────────────────
+export { decide, DEFAULT_POLICY, spendGate } from "./decide.js";
+// ── origin policy (whose origin may money touch) ─────────────────────────────
+// The one answer to that question; `spendGate` above stays the one answer to "how
+// much". `PayableTarget` is mintable only by `authorizeOrigin`, so a pay path that
+// skips the check fails to typecheck rather than failing in production.
+export { authorizeOrigin } from "./origin-policy.js";
+// ── cross-source allocation (buyer-side citation-reward policy) ──────────────
+export { allocateByContribution } from "./allocation.js";
+// ── citation licenses (pay once, re-read free) ──────────────────────────────
+export { decodeHeld, fileHeldStore, isLive, loadHeld, memoryHeldStore, saveHeld } from "./licenseStore.js";
+export { buildPopProof } from "./pop.js";
+// ── wallet ──────────────────────────────────────────────────────────────────
+export { getWallet } from "./wallet.js";
+//# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAGjC,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAChF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhF,+EAA+E;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,+EAA+E;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,+EAA+E;AAC/E,OAAO,EACL,KAAK,EACL,UAAU,EACV,YAAY,EACZ,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,+EAA+E;AAC/E,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGhE,gFAAgF;AAChF,kFAAkF;AAClF,mFAAmF;AACnF,wEAAwE;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,gFAAgF;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,+EAA+E;AAC/E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE3G,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,+EAA+E;AAC/E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/licenseStore.d.ts

@@ -0,0 +1,56 @@
+export interface HeldLicense {
+    slug: string;
+    title: string;
+    jti: string;
+    /** exp (epoch seconds) decoded from the token, for the liveness check. */
+    exp: number;
+    /** The token's audience (= gate identity); the value a PoP proof must bind to. */
+    aud: string;
+    /** Holder-of-key: true when the license carries a `cnf` claim — a re-read needs
+     * a wallet proof-of-possession, not just the token. */
+    pop: boolean;
+    /** The compact-JWS token to present on a re-read. */
+    jws: string;
+    /** The canonical URL this source was actually PAID at — captured at pay time so a
+     * later `read_held` re-fetches the exact link (`/articles/<slug>`, a custom domain,
+     * whatever the publisher serves) instead of reconstructing a `/essays/<slug>`
+     * template that 404s off-shape. Optional: a license held from before this field
+     * existed has none, and the re-read falls back to the template. NOT part of the
+     * decoded token — it's the buyer's own bookkeeping, so `decodeHeld` never sets it. */
+    url?: string;
+}
+/**
+ * Decode a token's `jti`, `exp`, and `naulon.slug/title` WITHOUT verifying — this
+ * is the agent reading its own captured receipt for bookkeeping, not trusting a
+ * third party. (The agent separately verifies the signature against the gate's
+ * JWKS when it captures the license; see agent.ts.) Returns null if unparseable.
+ */
+export declare function decodeHeld(jws: string): Omit<HeldLicense, "jws"> | null;
+/** Is this held license still valid at `nowSec` (epoch seconds)? */
+export declare function isLive(held: HeldLicense, nowSec: number): boolean;
+export declare function loadHeld(): Promise<Map<string, HeldLicense>>;
+export declare function saveHeld(held: Map<string, HeldLicense>): Promise<void>;
+/**
+ * The held-license backend as a seam. The stdio funnel uses the process-global
+ * file (`fileHeldStore`); the hosted path (many buyer sessions in one process)
+ * MUST inject a store scoped to the caller — else session B could re-read the
+ * license session A paid for, since the file store is keyed by slug alone and
+ * shared across every session in the process (a cross-buyer isolation leak).
+ * The interface is deliberately the shape `loadHeld`/`saveHeld` already have, so
+ * the file default and an injected store are interchangeable at every call site.
+ */
+export interface HeldStore {
+    load(): Promise<Map<string, HeldLicense>>;
+    save(held: Map<string, HeldLicense>): Promise<void>;
+}
+/** The OSS default: the process-global JSON file at `WAYFARER_LICENSE_PATH`. */
+export declare const fileHeldStore: HeldStore;
+/**
+ * An in-process, isolated held store — the hosted-path default. Each instance
+ * owns a private Map; two instances never share state, so building one per MCP
+ * session gives per-session isolation for free (session B's `load()` cannot see
+ * what session A `save()`d). Ephemeral by design: a held license lives with the
+ * session, not across process restarts — the right trade for a capped hot session.
+ */
+export declare function memoryHeldStore(seed?: Iterable<readonly [string, HeldLicense]>): HeldStore;
+//# sourceMappingURL=licenseStore.d.ts.map

package/dist/licenseStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"licenseStore.d.ts","sourceRoot":"","sources":["../src/licenseStore.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ;2DACuD;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;0FAKsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,GAAG,IAAI,CAuBvE;AAED,oEAAoE;AACpE,wBAAgB,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAsB,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CASlE;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5E;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,gFAAgF;AAChF,eAAO,MAAM,aAAa,EAAE,SAA8C,CAAC;AAE3E;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,GAAG,SAAS,CAS1F"}

package/dist/licenseStore.js

@@ -0,0 +1,79 @@
+/**
+ * The agent's wallet of Citation Licenses. When the gate hands back a license on
+ * a paid read, the agent keeps it; a live (unexpired) one lets it re-read that
+ * essay free on a later run instead of paying again — the buyer-side half of the
+ * "toll becomes an asset" thesis. Persisted to a small JSON file (WAYFARER_LICENSE_PATH).
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { getConfig } from "@naulon/shared";
+const file = () => getConfig().WAYFARER_LICENSE_PATH;
+/**
+ * Decode a token's `jti`, `exp`, and `naulon.slug/title` WITHOUT verifying — this
+ * is the agent reading its own captured receipt for bookkeeping, not trusting a
+ * third party. (The agent separately verifies the signature against the gate's
+ * JWKS when it captures the license; see agent.ts.) Returns null if unparseable.
+ */
+export function decodeHeld(jws) {
+    try {
+        const seg = jws.split(".")[1];
+        if (!seg)
+            return null;
+        const claims = JSON.parse(Buffer.from(seg, "base64url").toString("utf8"));
+        if (!claims.jti || !claims.exp || !claims.aud || !claims.naulon?.slug)
+            return null;
+        return {
+            slug: claims.naulon.slug,
+            title: claims.naulon.title ?? claims.naulon.slug,
+            jti: claims.jti,
+            exp: claims.exp,
+            aud: claims.aud,
+            pop: typeof claims.cnf?.["naulon:addr"] === "string",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Is this held license still valid at `nowSec` (epoch seconds)? */
+export function isLive(held, nowSec) {
+    return held.exp > nowSec;
+}
+export async function loadHeld() {
+    try {
+        const raw = await readFile(file(), "utf8");
+        const arr = JSON.parse(raw);
+        return new Map(arr.map((h) => [h.slug, h]));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return new Map();
+        throw err;
+    }
+}
+export async function saveHeld(held) {
+    const path = file();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify([...held.values()], null, 2), "utf8");
+}
+/** The OSS default: the process-global JSON file at `WAYFARER_LICENSE_PATH`. */
+export const fileHeldStore = { load: loadHeld, save: saveHeld };
+/**
+ * An in-process, isolated held store — the hosted-path default. Each instance
+ * owns a private Map; two instances never share state, so building one per MCP
+ * session gives per-session isolation for free (session B's `load()` cannot see
+ * what session A `save()`d). Ephemeral by design: a held license lives with the
+ * session, not across process restarts — the right trade for a capped hot session.
+ */
+export function memoryHeldStore(seed) {
+    const store = new Map(seed);
+    return {
+        load: async () => new Map(store),
+        save: async (held) => {
+            store.clear();
+            for (const [k, v] of held)
+                store.set(k, v);
+        },
+    };
+}
+//# sourceMappingURL=licenseStore.js.map

package/dist/licenseStore.js.map

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

package/dist/memo.d.ts

@@ -0,0 +1,43 @@
+import { type TypedDataDomain } from "viem";
+import { TRANSFER_WITH_AUTHORIZATION_TYPES, type MemoAuthorization } from "@naulon/shared";
+import { type Buyer, type LegRequirements, type Quoted } from "./buyer.ts";
+/**
+ * The signer seam (BUY-2). By default the memo buyer signs each EIP-3009 leg with the local
+ * `BUYER_PRIVATE_KEY` (the OSS self-host path). A cloud host instead injects a `MemoSigner` — an
+ * object that signs the SAME typed data elsewhere (a grant-checked BFF holding an encrypted session
+ * key), so the private key never lives in the MCP process. A `PrivateKeyAccount` from viem satisfies
+ * this shape too, which keeps the two paths symmetric. The env key is only ever read on the default
+ * path — when a signer is injected, `BUYER_PRIVATE_KEY` is never touched.
+ */
+export interface MemoSigner {
+    address: `0x${string}`;
+    signTypedData(args: {
+        domain: TypedDataDomain;
+        types: typeof TRANSFER_WITH_AUTHORIZATION_TYPES;
+        primaryType: "TransferWithAuthorization";
+        message: {
+            from: `0x${string}`;
+            to: `0x${string}`;
+            value: bigint;
+            validAfter: bigint;
+            validBefore: bigint;
+            nonce: `0x${string}`;
+        };
+    }): Promise<`0x${string}`>;
+}
+/** Sign a raw USDC EIP-3009 `TransferWithAuthorization` against the active network's USDC
+ *  EIP-712 domain and return the base64 `{authorization, signature}` payload the gate's
+ *  memo settle path parses. The memo id is NOT signed (the gate attaches it at relay), so
+ *  the buyer needs nothing extra. Exported for unit testing against the gate's pre-verify. */
+export declare function signMemoPayment(requirements: Quoted["requirements"], nowMs: number): Promise<string>;
+/** The raw `{ authorization, signature }` for ONE leg — signs the leg's payTo + amount
+ *  against the active network's USDC domain, with its own fresh EIP-3009 nonce. The
+ *  per-leg primitive `assemblePayment` calls once per advertised leg (mirrors the gate's
+ *  `memoLegPayload` → `buildMemoSignatures`). The memo id is NOT signed (the relayer
+ *  attaches it at submit), so each leg needs nothing beyond its own authorization. */
+export declare function memoLegPayload(requirements: LegRequirements, nowMs: number, signer?: MemoSigner, net?: import("@naulon/shared").SettlementNetwork): Promise<{
+    authorization: MemoAuthorization;
+    signature: `0x${string}`;
+}>;
+export declare function memoBuyer(signer?: MemoSigner): Buyer;
+//# sourceMappingURL=memo.d.ts.map

package/dist/memo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memo.d.ts","sourceRoot":"","sources":["../src/memo.ts"],"names":[],"mappings":"AAeA,OAAO,EAAS,KAAK,eAAe,EAAE,MAAM,MAAM,CAAC;AACnD,OAAO,EAIL,iCAAiC,EACjC,KAAK,iBAAiB,EACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAIL,KAAK,KAAK,EAEV,KAAK,eAAe,EAEpB,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,aAAa,CAAC,IAAI,EAAE;QAClB,MAAM,EAAE,eAAe,CAAC;QACxB,KAAK,EAAE,OAAO,iCAAiC,CAAC;QAChD,WAAW,EAAE,2BAA2B,CAAC;QACzC,OAAO,EAAE;YACP,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;YACpB,EAAE,EAAE,KAAK,MAAM,EAAE,CAAC;YAClB,KAAK,EAAE,MAAM,CAAC;YACd,UAAU,EAAE,MAAM,CAAC;YACnB,WAAW,EAAE,MAAM,CAAC;YACpB,KAAK,EAAE,KAAK,MAAM,EAAE,CAAC;SACtB,CAAC;KACH,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC;CAC5B;AAaD;;;8FAG8F;AAC9F,wBAAsB,eAAe,CACnC,YAAY,EAAE,MAAM,CAAC,cAAc,CAAC,EACpC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;sFAIsF;AACtF,wBAAsB,cAAc,CAClC,YAAY,EAAE,eAAe,EAC7B,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,UAAU,EACnB,GAAG,6CAAkB,GACpB,OAAO,CAAC;IAAE,aAAa,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,KAAK,MAAM,EAAE,CAAA;CAAE,CAAC,CAoCzE;AAED,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,KAAK,CA+BpD"}

package/dist/memo.js

@@ -0,0 +1,102 @@
+/**
+ * Memo buyer — the client side of the Arc self-relay rail. On a memo-capable network the
+ * gate settles by RELAYING a raw USDC EIP-3009 authorization through the Arc Memo
+ * predeploy (not Circle Gateway), so the buyer signs the authorization against the USDC
+ * EIP-712 domain — the shared descriptor — and posts `{authorization, signature}` as the
+ * `payment-signature`. There is NO Gateway deposit: the transfer moves straight from the
+ * buyer's USDC balance and the gate's relayer only pays gas (custody-free).
+ *
+ * Counterpart to gateway.ts (Circle SDK, GatewayWallet domain) and pay.ts (mock offline).
+ * The signing here is wayfarer's own viem call over shared's `TRANSFER_WITH_AUTHORIZATION`
+ * descriptor + `usdcDomain` — the same "each consumer signs against the one shared
+ * descriptor" split the gate's own `buildMemoSignature` uses (the gate then verifies
+ * against that identical descriptor). `selectBuyer` routes here when `supportsMemo`.
+ */
+import { privateKeyToAccount } from "viem/accounts";
+import { toHex } from "viem";
+import { activeNetwork, getConfig, usdcDomain, TRANSFER_WITH_AUTHORIZATION_TYPES, } from "@naulon/shared";
+import { assemblePayment, classifySignerRefusal, probePrice, } from "./buyer.js";
+import { runPaidFetch } from "./paidFetch.js";
+function buyerKey() {
+    const cfg = getConfig();
+    if (!cfg.BUYER_PRIVATE_KEY) {
+        throw new Error(`PAYMENT_MODE=gateway on ${activeNetwork().chainName} (memo rail) requires BUYER_PRIVATE_KEY ` +
+            `— a wallet holding USDC on that network (the EIP-3009 transfer moves straight from it).`);
+    }
+    return (cfg.BUYER_PRIVATE_KEY.startsWith("0x") ? cfg.BUYER_PRIVATE_KEY : `0x${cfg.BUYER_PRIVATE_KEY}`);
+}
+/** Sign a raw USDC EIP-3009 `TransferWithAuthorization` against the active network's USDC
+ *  EIP-712 domain and return the base64 `{authorization, signature}` payload the gate's
+ *  memo settle path parses. The memo id is NOT signed (the gate attaches it at relay), so
+ *  the buyer needs nothing extra. Exported for unit testing against the gate's pre-verify. */
+export async function signMemoPayment(requirements, nowMs) {
+    return Buffer.from(JSON.stringify(await memoLegPayload(requirements, nowMs))).toString("base64");
+}
+/** The raw `{ authorization, signature }` for ONE leg — signs the leg's payTo + amount
+ *  against the active network's USDC domain, with its own fresh EIP-3009 nonce. The
+ *  per-leg primitive `assemblePayment` calls once per advertised leg (mirrors the gate's
+ *  `memoLegPayload` → `buildMemoSignatures`). The memo id is NOT signed (the relayer
+ *  attaches it at submit), so each leg needs nothing beyond its own authorization. */
+export async function memoLegPayload(requirements, nowMs, signer, net = activeNetwork()) {
+    const cfg = getConfig();
+    // Default path resolves the local key; an injected signer NEVER reads BUYER_PRIVATE_KEY (the whole
+    // point of the cloud wallet — the key lives in the grant-checked BFF, not this process).
+    const envAccount = signer ? undefined : privateKeyToAccount(buyerKey());
+    const from = (signer?.address ?? envAccount.address);
+    // Stamp validity at PAY time (nowMs is `Date.now()` from fetch, not quote time) with a
+    // MARGIN: floor the window to WAYFARER_MIN_VALIDITY_SECONDS so a gate advertising a
+    // too-short maxTimeoutSeconds can't make the authorization expire before the relay
+    // submits it (the facilitator's `authorization_validity_too_short` — the Keryx ~1-day
+    // lesson; see memory `x402-validity-window-floor`). The window only widens, never
+    // shrinks — a long gate window is honored as-is.
+    const window = Math.max(requirements.maxTimeoutSeconds, cfg.WAYFARER_MIN_VALIDITY_SECONDS);
+    const authorization = {
+        from,
+        to: requirements.payTo,
+        value: requirements.amount,
+        validAfter: "0",
+        validBefore: String(Math.floor(nowMs / 1000) + window),
+        nonce: toHex(crypto.getRandomValues(new Uint8Array(32))),
+    };
+    const typedData = {
+        domain: usdcDomain(net, cfg.USDC_EIP712_NAME),
+        types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+        primaryType: "TransferWithAuthorization",
+        message: {
+            from: authorization.from,
+            to: authorization.to,
+            value: BigInt(authorization.value),
+            validAfter: BigInt(authorization.validAfter),
+            validBefore: BigInt(authorization.validBefore),
+            nonce: authorization.nonce,
+        },
+    };
+    const signature = signer ? await signer.signTypedData(typedData) : await envAccount.signTypedData(typedData);
+    return { authorization, signature };
+}
+export function memoBuyer(signer) {
+    const address = signer ? signer.address : privateKeyToAccount(buyerKey()).address;
+    return {
+        address,
+        async init() {
+            // No Gateway deposit — the EIP-3009 transfer pays straight from the buyer's USDC
+            // balance, and the relayer (gate-side) covers gas. `make arc-preflight` checks funding.
+        },
+        price(url, kind) {
+            return probePrice(url, kind, address);
+        },
+        async fetch(url, kind, guard) {
+            // One raw EIP-3009 authorization per advertised leg (operator fee → 2-leg array); a stock
+            // single-author quote stays the bare object, byte-identical to before. The shared loop owns
+            // probe→moved-guard→paid-GET→classify; the memo rail supplies only how it signs and how it
+            // types a sign refusal (grant exhausted/expired/no session → typed; else a transient origin throw).
+            return runPaidFetch(url, kind, address, guard, (quoted, nowMs) => assemblePayment(quoted, (req) => memoLegPayload(req, nowMs, signer)), (error) => {
+                const refusal = classifySignerRefusal(error);
+                return refusal
+                    ? { ok: false, error, ...refusal }
+                    : { ok: false, error, errorCode: "origin_error", retryable: true };
+            });
+        },
+    };
+}
+//# sourceMappingURL=memo.js.map