@paidfor/x402-safe-fetch 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarmad Siddiki
+
+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

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @paidfor/x402-safe-fetch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A drop-in wrapper around the official [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) client (2.28.x)
+that protects the buyer before and after paying. It refuses overpriced quotes and sellers rated "avoid", never
+pays twice for the same intent, and checks what it bought.
+
+This is the client-side half of the x402 seller index at [paidfor.dev](https://paidfor.dev).
+
+```bash
+npm install @paidfor/x402-safe-fetch
+```
+
+```ts
+import { safeFetch } from "@paidfor/x402-safe-fetch";
+
+const fetchWithPay = safeFetch(walletClient, {
+  maxPerCallUsd: 0.50,
+  maxOverListedRatio: 1.1,     // refuse quotes more than 10% above the listed/known price
+  refuseVerdicts: ["avoid"],   // consult the index; "caution" is allowed but logged
+  indexUrl: "https://paidfor.dev/v1",
+  validators: ["http_status", "non_empty", "content_type", "not_truncated"],
+  telemetry: "anonymous",      // or "off" (the default)
+  receiptsDir: "./.x402-receipts",
+});
+
+const res = await fetchWithPay(url, init, { intentId: "topup:acct_42:2026-10" });
+console.log(res.status, res.receipt.outcome, res.receipt.tx_hash);
+```
+
+`walletClient` is a viem account (`privateKeyToAccount(...)`) or a viem `WalletClient` with an account attached.
+Payments are exact-scheme USDC on Base mainnet by default (`network: "eip155:84532"` for Base Sepolia).
+
+## What happens on every call
+
+1. **Before paying.** The unpaid request gets the 402 quote. The client asks the index
+   (`GET {indexUrl}/check?url=`, query string stripped) for the seller verdict and the resource's listed price,
+   with a 2-second timeout. It compares the quote to the listed price, or, when the index has none, to the last
+   price this client paid for the same resource. It refuses with a `PaymentRefusedError` when the seller verdict
+   is in `refuseVerdicts`, the quote exceeds `maxOverListedRatio` times the reference, or the amount exceeds
+   `maxPerCallUsd`. The error says why and links the seller page. The index is advisory: if it is down, slow or
+   answers `unknown`, the call proceeds on the local checks and the receipt says `index: "unavailable"`.
+2. **Idempotency.** Every call has an `intentId`, yours or a generated one. The request hash is written to the
+   receipts directory before signing, and the signed nonce is written before the payment is sent. A retry with
+   the same `intentId` and request returns the stored response and never signs again. A retry with the same
+   `intentId` and a different request throws `IntentConflictError`. If a payment was signed but no response was
+   stored, a retry throws `IntentIndeterminateError` instead of paying again.
+3. **After the response.** The configured validators run on the paid response. `res.receipt` carries the intent
+   id, quote, amount, reference price and its source, seller verdict, validator results, the settlement header,
+   and the on-chain tx hash when the header carries it. The same receipt is written to the receipts directory as
+   one JSON file per call.
+4. **Telemetry, when enabled.** One outcome-only POST, fire-and-forget. See below.
+
+## What it blocks and what it does not
+
+| Blocks | Does not block |
+| --- | --- |
+| Paying a seller the index rates `avoid` (or any verdict you list) | A bad seller the index has not rated yet, or any seller while the index is unreachable |
+| A quote more than `maxOverListedRatio` above the index listed price | An overpriced first purchase from a resource with no listed price and no local history |
+| A quote more than `maxOverListedRatio` above the last price this client paid | Slow price creep, if you keep accepting each step |
+| Any single payment above `maxPerCallUsd` | Total spend across many calls: there is no daily or per-seller budget |
+| Paying twice for the same `intentId`, across restarts and concurrent processes | Duplicates when each retry uses a new `intentId` (pass a stable one) |
+| Re-signing after a timeout or crash once a payment was signed | Recovering that money: the call fails with the nonce so you can check the chain |
+| Non-USDC assets, other networks, non-`exact` schemes, and redirects of the paid request | A seller that settles and then serves wrong or stale content that still passes the four validators |
+| Silent non-delivery: a paid 4xx/5xx, empty, wrong content type or truncated body is flagged in the receipt | Getting the money back: validators report failures, they do not refund or dispute |
+
+## Receipts directory
+
+```
+.x402-receipts/
+  2026-10-28T12-00-00-000Z-a1b2c3.json   one receipt per call
+  intents/<sha256(intentId)>.json        idempotency state and the stored response
+  prices.json                            last price paid per resource (method + origin + path)
+  debug.log                              telemetry failures, local only
+```
+
+Keep this directory if you want the idempotency guarantee to survive restarts.
+
+## Telemetry
+
+Off by default. With `telemetry: "anonymous"`, each call that got a 402 posts exactly this to
+`{indexUrl}/telemetry`, with a 1-second timeout, never awaited, every failure swallowed:
+
+```json
+{ "v": 1, "host": "api.example.com", "path_hash": "<sha256 hex of the path>", "outcome": "ok",
+  "amount_usdc": "0.010000", "latency_ms": 412, "validator_failures": [], "client": "x402-safe-fetch/0.1.0" }
+```
+
+No bodies, no wallet address, no request parameters, no intent id. The field list and the privacy promise are in
+[docs/telemetry.md](docs/telemetry.md).
+
+## Errors
+
+| Error | `code` | Paid? |
+| --- | --- | --- |
+| `PaymentRefusedError` | `refused_verdict`, `refused_ratio`, `refused_max_per_call` | No |
+| `IntentConflictError` | `intent_conflict` | No |
+| `IntentIndeterminateError` | `intent_indeterminate` | Maybe, earlier; never again |
+| `SafeFetchError` | `paid_no_response` | Signed and possibly settled; `receipt.nonce` identifies it |
+| `SafeFetchError` | `no_acceptable_quote`, `intent_in_flight`, `network`, `sdk` | No |
+
+## Example
+
+[examples/conway-topup.ts](examples/conway-topup.ts) reproduces an auto-top-up that was paid, got a 500, and
+retried every 60 seconds, and shows the idempotency guard and the `http_status` validator stopping it.
+
+## Provenance
+
+The 402 parsing, settlement decoding, pre-sign and post-sign checks, price ratio arithmetic and the four
+validators are ported from the x402-audit measurement harness behind paidfor.dev, with their unit tests.
+
+## License
+
+MIT

package/dist/body.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Like x402-audit readBodyCapped (src/x402/http.ts), but the caller still gets the whole body: the first
+ * `maxBytes` are buffered for the validators and the replay store, and anything past that is streamed
+ * through untouched.
+ */
+import type { BodyReadResult } from "./x402/http.js";
+export interface TeeResult extends BodyReadResult {
+    /** What to hand back to the caller: the bytes, or a stream of buffered prefix + rest. */
+    callerBody: Uint8Array | ReadableStream<Uint8Array> | null;
+}
+export declare function readBodyTee(res: Response, maxBytes: number): Promise<TeeResult>;

package/dist/body.js

@@ -0,0 +1,84 @@
+export async function readBodyTee(res, maxBytes) {
+    const cl = res.headers.get("content-length");
+    const declared = cl !== null && /^\d+$/.test(cl.trim()) ? Number(cl.trim()) : undefined;
+    const encoding = (res.headers.get("content-encoding") ?? "identity").trim().toLowerCase();
+    const chunks = [];
+    let total = 0;
+    let truncatedByUs = false;
+    let incomplete = false;
+    let streamError;
+    let overflow;
+    let reader;
+    if (res.body) {
+        reader = res.body.getReader();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (!value || value.byteLength === 0)
+                    continue;
+                if (total + value.byteLength > maxBytes) {
+                    const keep = maxBytes - total;
+                    if (keep > 0)
+                        chunks.push(value.subarray(0, keep));
+                    overflow = value.subarray(Math.max(keep, 0));
+                    total += Math.max(keep, 0);
+                    truncatedByUs = true;
+                    break;
+                }
+                chunks.push(value);
+                total += value.byteLength;
+            }
+        }
+        catch (e) {
+            incomplete = true;
+            streamError = e;
+        }
+    }
+    if (!truncatedByUs && !incomplete && declared !== undefined && (encoding === "identity" || encoding === "") && total < declared) {
+        incomplete = true;
+    }
+    const body = new Uint8Array(total);
+    let off = 0;
+    for (const c of chunks) {
+        body.set(c, off);
+        off += c.byteLength;
+    }
+    let callerBody = res.body ? body : null;
+    if (truncatedByUs && reader) {
+        const r = reader;
+        const head = [body, overflow ?? new Uint8Array(0)];
+        callerBody = new ReadableStream({
+            start(c) {
+                for (const h of head)
+                    if (h.byteLength)
+                        c.enqueue(h);
+            },
+            async pull(c) {
+                try {
+                    const { done, value } = await r.read();
+                    if (done)
+                        c.close();
+                    else
+                        c.enqueue(value);
+                }
+                catch (e) {
+                    c.error(e);
+                }
+            },
+            cancel(reason) {
+                return r.cancel(reason);
+            },
+        });
+    }
+    else if (reader && !incomplete) {
+        reader.releaseLock();
+    }
+    const out = { body, truncatedByUs, incomplete, callerBody };
+    if (declared !== undefined)
+        out.declaredLength = declared;
+    if (streamError !== undefined)
+        out.streamError = streamError;
+    return out;
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+import type { Receipt } from "./receipt.js";
+export type SafeFetchErrorCode = "refused_verdict" | "refused_ratio" | "refused_max_per_call" | "no_acceptable_quote" | "intent_conflict" | "intent_indeterminate" | "intent_in_flight" | "paid_no_response" | "network" | "sdk";
+/** Every error this package throws. `receipt` is set whenever a call got far enough to write one. */
+export declare class SafeFetchError extends Error {
+    readonly code: SafeFetchErrorCode;
+    readonly receipt?: Receipt | undefined;
+    name: string;
+    constructor(code: SafeFetchErrorCode, message: string, receipt?: Receipt | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** Refused before any signature: seller verdict, price ratio, or per-call cap. Nothing was paid. */
+export declare class PaymentRefusedError extends SafeFetchError {
+    readonly sellerUrl: string | null;
+    name: string;
+    constructor(code: "refused_verdict" | "refused_ratio" | "refused_max_per_call", message: string, sellerUrl: string | null, receipt?: Receipt);
+}
+/** Same intentId, different request. Nothing was sent. */
+export declare class IntentConflictError extends SafeFetchError {
+    name: string;
+}
+/** A payment for this intent was signed (and may have been sent) but no result was stored. Never re-signed. */
+export declare class IntentIndeterminateError extends SafeFetchError {
+    name: string;
+}

package/dist/errors.js

@@ -0,0 +1,28 @@
+/** Every error this package throws. `receipt` is set whenever a call got far enough to write one. */
+export class SafeFetchError extends Error {
+    code;
+    receipt;
+    name = "SafeFetchError";
+    constructor(code, message, receipt, options) {
+        super(message, options);
+        this.code = code;
+        this.receipt = receipt;
+    }
+}
+/** Refused before any signature: seller verdict, price ratio, or per-call cap. Nothing was paid. */
+export class PaymentRefusedError extends SafeFetchError {
+    sellerUrl;
+    name = "PaymentRefusedError";
+    constructor(code, message, sellerUrl, receipt) {
+        super(code, message, receipt);
+        this.sellerUrl = sellerUrl;
+    }
+}
+/** Same intentId, different request. Nothing was sent. */
+export class IntentConflictError extends SafeFetchError {
+    name = "IntentConflictError";
+}
+/** A payment for this intent was signed (and may have been sent) but no result was stored. Never re-signed. */
+export class IntentIndeterminateError extends SafeFetchError {
+    name = "IntentIndeterminateError";
+}

package/dist/fsutil.d.ts

@@ -0,0 +1,2 @@
+/** Write JSON via temp file + fsync + rename, so a crash leaves either the old or the new file. */
+export declare function writeJsonDurable(file: string, value: unknown): Promise<void>;

package/dist/fsutil.js

@@ -0,0 +1,17 @@
+import { randomBytes } from "node:crypto";
+import { mkdir, open, rename } from "node:fs/promises";
+import { dirname } from "node:path";
+/** Write JSON via temp file + fsync + rename, so a crash leaves either the old or the new file. */
+export async function writeJsonDurable(file, value) {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.${randomBytes(4).toString("hex")}.tmp`;
+    const fh = await open(tmp, "w");
+    try {
+        await fh.writeFile(JSON.stringify(value, null, 2) + "\n", "utf8");
+        await fh.sync();
+    }
+    finally {
+        await fh.close();
+    }
+    await rename(tmp, file);
+}

package/dist/index-client.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The only file that knows the shape of GET {indexUrl}/check?url=. Contract (paidfor-index lib/check.ts):
+ *   { input, host, verdict: "avoid"|"caution"|"ok"|"unknown", verdict_text, seller: {..., verdict, url} | null,
+ *     resource: { url, listed_price_usdc: "0.002000" | null, modal_quote_usdc, ... } | null,
+ *     probe, seller_url, evidence_url, methodology_url, generated_at }
+ * Every field is optional here. Advisory only: this never throws, and anything other than a parseable answer
+ * with a known verdict inside the timeout comes back as { available: false }.
+ */
+export type Verdict = "avoid" | "caution" | "ok" | "unknown";
+export interface IndexCheck {
+    available: boolean;
+    /** Why the index could not be used (timeout, http 503, unknown verdict, ...). */
+    note?: string;
+    host: string | null;
+    verdict: Verdict;
+    verdict_text: string | null;
+    seller_url: string | null;
+    evidence_url: string | null;
+    /** Listed price for this exact resource, USDC decimal string, when the index has one. */
+    listed_price_usdc: string | null;
+}
+/** Seller page on the site that hosts the index: https://paidfor.dev/v1 -> https://paidfor.dev/seller/<host>. */
+export declare function sellerPageUrl(indexUrl: string, host: string): string;
+/** Strip query and fragment: the index matches on host + path and never needs request parameters. */
+export declare function lookupUrl(resourceUrl: string): string;
+export declare function parseCheck(body: unknown, indexUrl: string, resourceUrl: string): IndexCheck;
+export interface CheckOptions {
+    timeoutMs?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}
+export declare function checkIndex(indexUrl: string, resourceUrl: string, o?: CheckOptions): Promise<IndexCheck>;

package/dist/index-client.js

@@ -0,0 +1,70 @@
+const VERDICTS = ["avoid", "caution", "ok", "unknown"];
+const str = (v) => (typeof v === "string" && v.trim() !== "" ? v : null);
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : null);
+/** Seller page on the site that hosts the index: https://paidfor.dev/v1 -> https://paidfor.dev/seller/<host>. */
+export function sellerPageUrl(indexUrl, host) {
+    return `${new URL(indexUrl).origin}/seller/${encodeURIComponent(host)}`;
+}
+/** Strip query and fragment: the index matches on host + path and never needs request parameters. */
+export function lookupUrl(resourceUrl) {
+    const u = new URL(resourceUrl);
+    return `${u.origin}${u.pathname}`;
+}
+export function parseCheck(body, indexUrl, resourceUrl) {
+    const b = obj(body) ?? {};
+    const seller = obj(b.seller);
+    const resource = obj(b.resource);
+    let host = str(b.host) ?? str(seller?.domain);
+    if (!host) {
+        try {
+            host = new URL(resourceUrl).hostname.toLowerCase();
+        }
+        catch {
+            host = null;
+        }
+    }
+    const rawVerdict = str(b.verdict) ?? str(seller?.verdict);
+    const verdict = rawVerdict && VERDICTS.includes(rawVerdict) ? rawVerdict : "unknown";
+    const out = {
+        available: verdict !== "unknown",
+        host,
+        verdict,
+        verdict_text: str(b.verdict_text),
+        seller_url: str(b.seller_url) ?? str(seller?.url) ?? (host ? sellerPageUrl(indexUrl, host) : null),
+        evidence_url: str(b.evidence_url) ?? str(seller?.evidence_url),
+        listed_price_usdc: str(resource?.listed_price_usdc),
+    };
+    if (verdict === "unknown")
+        out.note = rawVerdict ? "verdict unknown" : "no verdict in response";
+    return out;
+}
+export async function checkIndex(indexUrl, resourceUrl, o = {}) {
+    const fetchImpl = o.fetchImpl ?? globalThis.fetch;
+    const unavailable = (note) => {
+        let host = null;
+        try {
+            host = new URL(resourceUrl).hostname.toLowerCase();
+        }
+        catch {
+            /* ignore */
+        }
+        return { available: false, note, host, verdict: "unknown", verdict_text: null, seller_url: host ? sellerPageUrl(indexUrl, host) : null, evidence_url: null, listed_price_usdc: null };
+    };
+    const timeoutMs = o.timeoutMs ?? 2000;
+    try {
+        const url = `${indexUrl.replace(/\/$/, "")}/check?url=${encodeURIComponent(lookupUrl(resourceUrl))}`;
+        const signal = AbortSignal.timeout(timeoutMs);
+        const res = await fetchImpl(url, { headers: { accept: "application/json" }, signal });
+        if (!res.ok) {
+            res.body?.cancel().catch(() => undefined);
+            return unavailable(`http ${res.status}`);
+        }
+        // The timeout signal also bounds the body read.
+        const body = await res.json();
+        return parseCheck(body, indexUrl, resourceUrl);
+    }
+    catch (e) {
+        const name = e?.name;
+        return unavailable(name === "TimeoutError" || name === "AbortError" ? `timeout after ${timeoutMs}ms` : `error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { safeFetch, hashRequest, type SafeFetch, type SafeFetchOptions, type SafeResponse, type CallOptions, type WalletLike, type SafeNetwork } from "./safe-fetch.js";
+export { SafeFetchError, PaymentRefusedError, IntentConflictError, IntentIndeterminateError, type SafeFetchErrorCode } from "./errors.js";
+export type { Receipt, Outcome } from "./receipt.js";
+export type { Verdict, IndexCheck } from "./index-client.js";
+export type { ValidatorName } from "./taxonomy.js";
+export type { ValidatorResult } from "./validators/types.js";
+export type { TelemetryPayload } from "./telemetry.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { safeFetch, hashRequest } from "./safe-fetch.js";
+export { SafeFetchError, PaymentRefusedError, IntentConflictError, IntentIndeterminateError } from "./errors.js";

package/dist/intents.d.ts

@@ -0,0 +1,46 @@
+export type IntentPhase = "reserved" | "signing" | "signed" | "completed" | "unpaid" | "refused" | "failed_unpaid";
+export interface StoredResponse {
+    url: string;
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+    body_base64: string;
+    /** True when the body was larger than the stored cap; a replay then returns only the stored prefix. */
+    body_truncated: boolean;
+}
+export interface IntentRecord {
+    v: 1;
+    intent_id: string;
+    request_hash: string;
+    phase: IntentPhase;
+    attempts: number;
+    created_at: string;
+    updated_at: string;
+    nonce?: string;
+    amount_atomic?: string;
+    pay_to?: string;
+    receipt_file?: string;
+    response?: StoredResponse;
+}
+export interface IntentLease {
+    record: IntentRecord;
+    /** Set when the intent already completed: return this, do not contact the seller. */
+    replay: boolean;
+    update(patch: Partial<IntentRecord>): Promise<IntentRecord>;
+    release(): Promise<void>;
+}
+export declare class IntentStore {
+    private readonly dir;
+    private readonly held;
+    constructor(receiptsDir: string);
+    private paths;
+    private lock;
+    /** Cross-process lock. A lock file left by a dead process, or by this pid (only possible after a crash), is stale. */
+    private lockFile;
+    read(intentId: string): Promise<IntentRecord | undefined>;
+    /**
+     * Lock the intent and decide what this call may do. Writes the request hash durably before returning,
+     * so it is on disk before any signature. Throws on conflict, indeterminate, or in-flight.
+     */
+    acquire(intentId: string, requestHash: string, now?: () => Date): Promise<IntentLease>;
+}

package/dist/intents.js

@@ -0,0 +1,146 @@
+/**
+ * Idempotency. Follows the ledger rule of x402-audit src/pipeline/paidCall.ts ("ledger row BEFORE signing; if we
+ * crash after this, the row says money may have moved"), with the SQLite attempts table replaced by one JSON file
+ * per intent under <receiptsDir>/intents/.
+ *
+ * Phases, in order:
+ *   reserved   request hash stored; nothing signed           -> a retry may proceed
+ *   signing    all checks passed; signature about to be made -> a retry may proceed (nothing left the process:
+ *              `signed` is written before the paid request is sent, and a failed write aborts the send)
+ *   signed     authorization signed; paid request about to go -> a retry throws IntentIndeterminateError, never re-signs
+ *   completed  paid response stored                           -> a retry returns the stored response, never re-signs
+ *   unpaid / refused / failed_unpaid                          -> a retry may proceed (nothing was signed)
+ */
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { IntentConflictError, IntentIndeterminateError, SafeFetchError } from "./errors.js";
+import { writeJsonDurable } from "./fsutil.js";
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+export class IntentStore {
+    dir;
+    held = new Set();
+    constructor(receiptsDir) {
+        this.dir = join(receiptsDir, "intents");
+    }
+    paths(intentId) {
+        const base = join(this.dir, sha256(intentId).slice(0, 40));
+        return { file: `${base}.json`, lock: `${base}.lock` };
+    }
+    async lock(intentId, lockFile) {
+        // Claim in-process synchronously, before any await, so two concurrent calls here cannot both get past this line.
+        if (this.held.has(intentId))
+            throw new SafeFetchError("intent_in_flight", `intent ${intentId} is already in flight in this process`);
+        this.held.add(intentId);
+        try {
+            await this.lockFile(intentId, lockFile);
+        }
+        catch (e) {
+            this.held.delete(intentId);
+            throw e;
+        }
+    }
+    /** Cross-process lock. A lock file left by a dead process, or by this pid (only possible after a crash), is stale. */
+    async lockFile(intentId, lockFile) {
+        await mkdir(this.dir, { recursive: true });
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                const fh = await open(lockFile, "wx");
+                await fh.writeFile(JSON.stringify({ pid: process.pid, at: Date.now() }));
+                await fh.close();
+                return;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+                let owner;
+                try {
+                    owner = JSON.parse(await readFile(lockFile, "utf8")).pid;
+                }
+                catch {
+                    /* half-written lock: treat as stale */
+                }
+                if (owner !== undefined && owner !== process.pid && pidAlive(owner)) {
+                    throw new SafeFetchError("intent_in_flight", `intent ${intentId} is in flight in process ${owner}`);
+                }
+                await unlink(lockFile).catch(() => undefined); // stale lock from a dead process (or ourselves after a crash)
+            }
+        }
+        throw new SafeFetchError("intent_in_flight", `could not lock intent ${intentId}`);
+    }
+    async read(intentId) {
+        try {
+            return JSON.parse(await readFile(this.paths(intentId).file, "utf8"));
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return undefined;
+            throw e;
+        }
+    }
+    /**
+     * Lock the intent and decide what this call may do. Writes the request hash durably before returning,
+     * so it is on disk before any signature. Throws on conflict, indeterminate, or in-flight.
+     */
+    async acquire(intentId, requestHash, now = () => new Date()) {
+        if (typeof intentId !== "string" || intentId.length === 0 || intentId.length > 256) {
+            throw new TypeError("intentId must be a non-empty string of at most 256 characters");
+        }
+        const { file, lock } = this.paths(intentId);
+        await this.lock(intentId, lock);
+        const release = async () => {
+            this.held.delete(intentId);
+            await unlink(lock).catch(() => undefined);
+        };
+        try {
+            const prior = await this.read(intentId);
+            if (prior && prior.request_hash !== requestHash) {
+                throw new IntentConflictError("intent_conflict", `intent ${intentId} was already used for a different request (stored hash ${prior.request_hash.slice(0, 12)}, this request ${requestHash.slice(0, 12)}); use a new intentId`);
+            }
+            if (prior?.phase === "signed") {
+                throw new IntentIndeterminateError("intent_indeterminate", `intent ${intentId}: a payment was signed${prior.nonce ? ` (nonce ${prior.nonce})` : ""} but no response was stored, so it may have settled. Not signing again; check the chain or the seller before using a new intentId.`);
+            }
+            let record;
+            if (prior?.phase === "completed") {
+                record = prior;
+            }
+            else {
+                const ts = now().toISOString();
+                record = {
+                    v: 1,
+                    intent_id: intentId,
+                    request_hash: requestHash,
+                    phase: "reserved",
+                    attempts: (prior?.attempts ?? 0) + 1,
+                    created_at: prior?.created_at ?? ts,
+                    updated_at: ts,
+                };
+                await writeJsonDurable(file, record);
+            }
+            let current = record;
+            return {
+                record,
+                replay: record.phase === "completed",
+                async update(patch) {
+                    current = { ...current, ...patch, updated_at: now().toISOString() };
+                    await writeJsonDurable(file, current);
+                    return current;
+                },
+                release,
+            };
+        }
+        catch (e) {
+            await release();
+            throw e;
+        }
+    }
+}

package/dist/price.d.ts

@@ -0,0 +1,23 @@
+export declare const USDC_DECIMALS = 6;
+/** USDC contract per CAIP-2 network. Amounts are converted to USD only for these assets. */
+export declare const USDC_BY_NETWORK: Readonly<Record<string, string>>;
+/** Dollars (as configured by the caller) to USDC atomic units, rounding down so a cap is never loosened. */
+export declare function usdToAtomic(usd: number): bigint;
+/** "0.002000" (index format) to atomic units; undefined when unparseable or finer than 6 decimals. */
+export declare function usdcStringToAtomic(s: unknown): bigint | undefined;
+export declare function atomicToUsdc(a: bigint | string): string;
+export declare function quoteRatio(quote: bigint, ref: bigint): number;
+/** Exact comparison: quote > ref * maxRatio, with maxRatio taken to 6 decimal places. */
+export declare function exceedsRatio(quote: bigint, ref: bigint, maxRatio: number): boolean;
+/** Resource identity for the local price book: method + origin + path, query string dropped. */
+export declare function resourceKey(method: string, url: string): string;
+export type ReferenceSource = "index_listed" | "local_last_paid";
+/** Last price this client paid (and got a 2xx for) per resource, in <receiptsDir>/prices.json. */
+export declare class PriceBook {
+    private readonly file;
+    private cache;
+    constructor(dir: string);
+    private load;
+    get(key: string): Promise<bigint | undefined>;
+    set(key: string, amount: bigint, now?: Date): Promise<void>;
+}