@tuppence/http402 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @tuppence/http402
 
-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.
+Put a price on an API route in one line, and let people *and agents* pay for it.
+
+```ts
+import { Tuppence } from "@tuppence/node";
+import { http402 } from "@tuppence/http402";
+
+const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY!);
+
+app.get(
+  "/v1/report",
+  http402({ tuppence, price: 50, currency: "gbp", account: "acct_…" }),
+  (req, res) => res.json(buildReport()),
+);
+```
+
+## What the caller sees
+
+An unpaid request gets **`402 Payment Required`**:
+
+```json
+{
+  "error": { "type": "payment_required", "code": "payment_required", "message": "…" },
+  "price": 50,
+  "currency": "gbp",
+  "resource": "GET /v1/report",
+  "payment_id": "pay_…",
+  "accepts": [{ "type": "card_link", "url": "https://pay.tuppence.ai/pay/pay_…#…" }],
+  "receipt": {
+    "url": "https://api.tuppence.ai/public/payments/pay_…",
+    "header": "Tuppence-Client-Secret",
+    "client_secret": "…"
+  }
+}
+```
+
+with a `Link: <…>; rel="payment"` header. The caller pays at the URL, fetches `receipt.url`
+with the `Tuppence-Client-Secret` header, and retries with
+
+```
+Authorization: Tuppence-Receipt <receipt_token>
+```
+
+and gets the resource. A caller who retries before paying gets the **same** payment, not a
+new one each time.
+
+## Why it is safe
+
+- **Verified offline.** The receipt is a JWT signed by Tuppence (EdDSA); it is checked against
+  Tuppence's published keys (`/.well-known/jwks.json`, cached). No call to Tuppence on the hot
+  path.
+- **Bound to what was bought.** The receipt names its `resource` (default `METHOD /path`) and
+  amount: a 1p receipt for another route opens nothing here.
+- **Used once.** Its `jti` is remembered until it expires (fifteen minutes). The default store is
+  in memory. Running more than one process? Pass a shared `store` (`{ claim(jti, expiresAt) }`,
+  e.g. Redis `SET NX EX`).
+- **Paid to you.** Pass `account` and receipts paid to anyone else are refused.
+
+## Credits: agents paying from prepaid balance (no card per call)
+
+Give the route a meter priced the same, and your customers' agents can pay from their prepaid
+credit instead of a card:
+
+```ts
+app.get("/v1/report", http402({ tuppence, price: 50, currency: "gbp", credits: { meter: "report" } }), handler);
+```
+
+Your server mints the agent a token for its customer, capped and short-lived:
+
+```ts
+const { token } = await tuppence.request("POST", `/v1/credits/${customerId}/tokens`, {
+  body: { max_amount: 1000, expires_in: 3600 },
+});
+```
+
+and the agent sends `Authorization: Tuppence-Credits <token>` (with an `Idempotency-Key`, so a
+retried request is one use, not two). Tuppence enforces the cap and the expiry as it draws the
+credit; past either, the agent gets a `402` saying why (`credit_token_limit`,
+`credit_token_expired`, `insufficient_credits` with a `topup_url`).
+
+## Other frameworks
+
+```ts
+// Next.js route handlers, Hono, Bun, Deno, Workers
+export const GET = withPayment({ tuppence, price: 50, currency: "gbp" }, async (req, paid) =>
+  Response.json(await buildReport()),
+);
+
+// An MCP tool: an optional `receipt` argument; without it the agent is told where to pay
+server.tool(
+  "deep_research",
+  { topic: z.string(), receipt: z.string().optional() },
+  paidTool({ tuppence, price: 200, currency: "gbp", name: "deep_research" }, async ({ topic }) => ({
+    content: [{ type: "text", text: await research(topic) }],
+  })),
+);
+
+// Anything else: the framework-free core
+const decide = payWall({ tuppence, price: 50, currency: "gbp" });
+const decision = await decide({ method, path, authorization, caller });
+```

package/dist/agent-proof.d.ts

@@ -0,0 +1,56 @@
+import { type KeyObject } from "node:crypto";
+import { Jwks, type ReceiptStore } from "./verify.js";
+/**
+ * Agent identity (plan 20-06). A restricted API key says *what* may be done; it does not say
+ * *who* did it, and a key that leaks is anyone. An agent can instead hold a key pair of its own:
+ * Tuppence publishes the public half, the agent keeps the private half and signs a short-lived
+ * PROOF for each request. Anyone — us, or the developer's own server — can then check that this
+ * request was made by that agent, offline, against the published keys.
+ *
+ * The proof is a JWT the agent signs (EdDSA), shaped like DPoP (RFC 9449): it names the method
+ * and URL it is for, lives seconds, and carries a `jti` so it cannot be replayed. It proves
+ * possession of the key for THIS request — not a bearer token that works anywhere.
+ */
+export type AgentProofClaims = {
+    /** The agent: `agt_…`. */
+    iss: string;
+    /** HTTP method, upper case. */
+    htm: string;
+    /** The URL it is for, without the fragment. */
+    htu: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    /** base64url SHA-256 of the request body, when there is one. */
+    bh?: string;
+    /** Who it is for, if the caller wants it bound: a host, a merchant id, anything agreed. */
+    aud?: string;
+};
+export type AgentProofErrorCode = "malformed_proof" | "unknown_key" | "bad_signature" | "expired_proof" | "wrong_request" | "wrong_agent" | "wrong_audience" | "body_changed" | "proof_already_used";
+export declare class AgentProofError extends Error {
+    readonly code: AgentProofErrorCode;
+    constructor(code: AgentProofErrorCode, message: string);
+}
+/** Tuppence publishes each agent's public keys here. */
+export declare const agentJwksUrl: (agent: string, baseUrl?: string) => string;
+/** The keys of ONE agent, cached like any other JWKS. */
+export declare const agentKeys: (agent: string, baseUrl?: string, fetcher?: typeof fetch) => Jwks;
+/** The URL a proof is compared against: no fragment, and no trailing "?" for an empty query. */
+export declare function canonicalUrl(url: string): string;
+export declare const bodyHash: (body: string | Uint8Array) => string;
+/**
+ * Checks a proof completely: it is a real EdDSA JWT signed by a key the agent publishes, it was
+ * made for THIS method and URL, it has not expired, and — when given — the body is the one it was
+ * made for. It does NOT mark the proof used: `claim` its `jti` in a store for that, or pass one.
+ */
+export declare function verifyAgentProof(proof: string, keys: Jwks | {
+    key(kid: string): Promise<KeyObject | undefined>;
+}, expected: {
+    agent: string;
+    method: string;
+    url: string;
+    body?: string | Uint8Array;
+    audience?: string;
+    nowSeconds?: number;
+    store?: ReceiptStore;
+}): Promise<AgentProofClaims>;

package/dist/agent-proof.js

@@ -0,0 +1,83 @@
+import { createHash, verify } from "node:crypto";
+import { Jwks } from "./verify.js";
+export class AgentProofError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AgentProofError";
+    }
+}
+/** Tuppence publishes each agent's public keys here. */
+export const agentJwksUrl = (agent, baseUrl = "https://api.tuppence.ai") => `${baseUrl.replace(/\/+$/, "")}/public/agents/${agent}/jwks.json`;
+/** The keys of ONE agent, cached like any other JWKS. */
+export const agentKeys = (agent, baseUrl, fetcher) => new Jwks(agentJwksUrl(agent, baseUrl), fetcher);
+/** The URL a proof is compared against: no fragment, and no trailing "?" for an empty query. */
+export function canonicalUrl(url) {
+    const parsed = new URL(url);
+    parsed.hash = "";
+    return parsed.search === "?" ? parsed.toString().replace(/\?$/, "") : parsed.toString();
+}
+export const bodyHash = (body) => createHash("sha256").update(body).digest("base64url");
+/** How far out of step the agent's clock may be, in seconds. */
+const CLOCK_SKEW_SECONDS = 30;
+/**
+ * Checks a proof completely: it is a real EdDSA JWT signed by a key the agent publishes, it was
+ * made for THIS method and URL, it has not expired, and — when given — the body is the one it was
+ * made for. It does NOT mark the proof used: `claim` its `jti` in a store for that, or pass one.
+ */
+export async function verifyAgentProof(proof, keys, expected) {
+    const parts = proof.split(".");
+    if (parts.length !== 3)
+        throw new AgentProofError("malformed_proof", "That is not a proof.");
+    const [h, p, s] = parts;
+    let header;
+    let claims;
+    try {
+        header = JSON.parse(Buffer.from(h, "base64url").toString());
+        claims = JSON.parse(Buffer.from(p, "base64url").toString());
+    }
+    catch {
+        throw new AgentProofError("malformed_proof", "That is not a proof.");
+    }
+    if (header.alg !== "EdDSA" || !header.kid) {
+        throw new AgentProofError("malformed_proof", "A proof is an EdDSA JWT with a key id.");
+    }
+    const key = await keys.key(header.kid);
+    if (!key) {
+        throw new AgentProofError("unknown_key", "That agent does not publish the key it signed with.");
+    }
+    if (!verify(null, Buffer.from(`${h}.${p}`), key, Buffer.from(s, "base64url"))) {
+        throw new AgentProofError("bad_signature", "The proof's signature does not verify.");
+    }
+    if (claims.iss !== expected.agent) {
+        throw new AgentProofError("wrong_agent", "The proof was made by a different agent.");
+    }
+    const now = expected.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (!Number.isFinite(claims.exp) || claims.exp + CLOCK_SKEW_SECONDS < now) {
+        throw new AgentProofError("expired_proof", "The proof has expired.");
+    }
+    if (!Number.isFinite(claims.iat) || claims.iat - CLOCK_SKEW_SECONDS > now) {
+        throw new AgentProofError("expired_proof", "The proof was made in the future.");
+    }
+    if (claims.htm !== expected.method.toUpperCase()) {
+        throw new AgentProofError("wrong_request", "The proof was made for another method.");
+    }
+    if (claims.htu !== canonicalUrl(expected.url)) {
+        throw new AgentProofError("wrong_request", "The proof was made for another URL.");
+    }
+    if (expected.audience !== undefined && claims.aud !== expected.audience) {
+        throw new AgentProofError("wrong_audience", "The proof was made for somebody else.");
+    }
+    if (expected.body !== undefined) {
+        if (claims.bh !== bodyHash(expected.body)) {
+            throw new AgentProofError("body_changed", "The proof was made for a different body.");
+        }
+    }
+    if (expected.store) {
+        const fresh = await expected.store.claim(claims.jti, claims.exp);
+        if (!fresh)
+            throw new AgentProofError("proof_already_used", "That proof has been used.");
+    }
+    return claims;
+}

package/dist/index.cjs

@@ -0,0 +1,421 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentProofError: () => AgentProofError,
+  Jwks: () => Jwks,
+  MemoryReceiptStore: () => MemoryReceiptStore,
+  ReceiptError: () => ReceiptError,
+  agentJwksUrl: () => agentJwksUrl,
+  agentKeys: () => agentKeys,
+  bodyHash: () => bodyHash,
+  canonicalUrl: () => canonicalUrl,
+  http402: () => http402,
+  paidTool: () => paidTool,
+  payWall: () => payWall,
+  verifyAgentProof: () => verifyAgentProof,
+  verifyCreditToken: () => verifyCreditToken,
+  verifyReceipt: () => verifyReceipt,
+  withPayment: () => withPayment
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_crypto3 = require("node:crypto");
+
+// src/verify.ts
+var import_node_crypto = require("node:crypto");
+var ReceiptError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ReceiptError";
+  }
+};
+var Jwks = class {
+  constructor(url, fetcher = globalThis.fetch, ttlMs = 5 * 6e4) {
+    this.url = url;
+    this.fetcher = fetcher;
+    this.ttlMs = ttlMs;
+  }
+  keys = /* @__PURE__ */ new Map();
+  fetchedAt = 0;
+  inflight;
+  async key(kid) {
+    const stale = Date.now() - this.fetchedAt > this.ttlMs;
+    if (stale || !this.keys.has(kid)) await this.refresh();
+    return this.keys.get(kid);
+  }
+  refresh() {
+    this.inflight ??= (async () => {
+      try {
+        const response = await this.fetcher(this.url, { headers: { Accept: "application/json" } });
+        if (!response.ok) throw new Error(`Could not fetch Tuppence's keys (${response.status})`);
+        const { keys } = await response.json();
+        this.keys = new Map(
+          keys.filter((k) => k.kty === "OKP" && k.crv === "Ed25519").map((k) => [k.kid, (0, import_node_crypto.createPublicKey)({ key: k, format: "jwk" })])
+        );
+        this.fetchedAt = Date.now();
+      } finally {
+        this.inflight = void 0;
+      }
+    })();
+    return this.inflight;
+  }
+};
+var MemoryReceiptStore = class {
+  used = /* @__PURE__ */ new Map();
+  claim(jti, expiresAt) {
+    const now = Date.now() / 1e3;
+    for (const [id, exp] of this.used) if (exp < now) this.used.delete(id);
+    if (this.used.has(jti)) return false;
+    this.used.set(jti, expiresAt);
+    return true;
+  }
+};
+async function verifyReceipt(token, jwks, expected) {
+  const parts = token.split(".");
+  if (parts.length !== 3)
+    throw new ReceiptError("malformed_receipt", "That is not a receipt token.");
+  const [h, p, s] = parts;
+  let header;
+  let claims;
+  try {
+    header = JSON.parse(Buffer.from(h, "base64url").toString());
+    claims = JSON.parse(Buffer.from(p, "base64url").toString());
+  } catch {
+    throw new ReceiptError("malformed_receipt", "That is not a receipt token.");
+  }
+  if (header.alg !== "EdDSA" || !header.kid) {
+    throw new ReceiptError("malformed_receipt", "Receipts are EdDSA-signed JWTs with a key id.");
+  }
+  const key = await jwks.key(header.kid);
+  if (!key) {
+    throw new ReceiptError(
+      "unknown_key",
+      "The receipt was signed by a key Tuppence does not publish."
+    );
+  }
+  if (!(0, import_node_crypto.verify)(null, Buffer.from(`${h}.${p}`), key, Buffer.from(s, "base64url"))) {
+    throw new ReceiptError("bad_signature", "The receipt's signature does not verify.");
+  }
+  const now = expected.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  if (typeof claims.exp !== "number" || now >= claims.exp) {
+    throw new ReceiptError("expired_receipt", "The receipt has expired. Pay again.");
+  }
+  if (claims.resource !== expected.resource) {
+    throw new ReceiptError(
+      "wrong_resource",
+      `The receipt is for ${claims.resource ?? "nothing in particular"}, not ${expected.resource}.`
+    );
+  }
+  if (claims.currency !== expected.currency || claims.amount < expected.price) {
+    throw new ReceiptError("wrong_amount", "The receipt is for less than the price.");
+  }
+  if (expected.account && claims.account !== expected.account) {
+    throw new ReceiptError("wrong_account", "The receipt was paid to someone else.");
+  }
+  return claims;
+}
+async function verifyCreditToken(token, jwks, expected = {}) {
+  const parts = token.split(".");
+  if (parts.length !== 3)
+    throw new ReceiptError("malformed_receipt", "That is not a credit token.");
+  const [h, p, s] = parts;
+  let header;
+  let claims;
+  try {
+    header = JSON.parse(Buffer.from(h, "base64url").toString());
+    claims = JSON.parse(Buffer.from(p, "base64url").toString());
+  } catch {
+    throw new ReceiptError("malformed_receipt", "That is not a credit token.");
+  }
+  const key = header.alg === "EdDSA" && header.kid ? await jwks.key(header.kid) : void 0;
+  if (!key) throw new ReceiptError("unknown_key", "The credit token was not signed by Tuppence.");
+  if (!(0, import_node_crypto.verify)(null, Buffer.from(`${h}.${p}`), key, Buffer.from(s, "base64url"))) {
+    throw new ReceiptError("bad_signature", "The credit token's signature does not verify.");
+  }
+  if (claims.typ !== "credit")
+    throw new ReceiptError("malformed_receipt", "That is not a credit token.");
+  const now = expected.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  if (typeof claims.exp !== "number" || now >= claims.exp) {
+    throw new ReceiptError("expired_receipt", "The credit token has expired.");
+  }
+  if (expected.account && claims.account !== expected.account) {
+    throw new ReceiptError("wrong_account", "The credit token was issued by someone else.");
+  }
+  return claims;
+}
+
+// src/agent-proof.ts
+var import_node_crypto2 = require("node:crypto");
+var AgentProofError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AgentProofError";
+  }
+};
+var agentJwksUrl = (agent, baseUrl = "https://api.tuppence.ai") => `${baseUrl.replace(/\/+$/, "")}/public/agents/${agent}/jwks.json`;
+var agentKeys = (agent, baseUrl, fetcher) => new Jwks(agentJwksUrl(agent, baseUrl), fetcher);
+function canonicalUrl(url) {
+  const parsed = new URL(url);
+  parsed.hash = "";
+  return parsed.search === "?" ? parsed.toString().replace(/\?$/, "") : parsed.toString();
+}
+var bodyHash = (body) => (0, import_node_crypto2.createHash)("sha256").update(body).digest("base64url");
+var CLOCK_SKEW_SECONDS = 30;
+async function verifyAgentProof(proof, keys, expected) {
+  const parts = proof.split(".");
+  if (parts.length !== 3) throw new AgentProofError("malformed_proof", "That is not a proof.");
+  const [h, p, s] = parts;
+  let header;
+  let claims;
+  try {
+    header = JSON.parse(Buffer.from(h, "base64url").toString());
+    claims = JSON.parse(Buffer.from(p, "base64url").toString());
+  } catch {
+    throw new AgentProofError("malformed_proof", "That is not a proof.");
+  }
+  if (header.alg !== "EdDSA" || !header.kid) {
+    throw new AgentProofError("malformed_proof", "A proof is an EdDSA JWT with a key id.");
+  }
+  const key = await keys.key(header.kid);
+  if (!key) {
+    throw new AgentProofError("unknown_key", "That agent does not publish the key it signed with.");
+  }
+  if (!(0, import_node_crypto2.verify)(null, Buffer.from(`${h}.${p}`), key, Buffer.from(s, "base64url"))) {
+    throw new AgentProofError("bad_signature", "The proof's signature does not verify.");
+  }
+  if (claims.iss !== expected.agent) {
+    throw new AgentProofError("wrong_agent", "The proof was made by a different agent.");
+  }
+  const now = expected.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  if (!Number.isFinite(claims.exp) || claims.exp + CLOCK_SKEW_SECONDS < now) {
+    throw new AgentProofError("expired_proof", "The proof has expired.");
+  }
+  if (!Number.isFinite(claims.iat) || claims.iat - CLOCK_SKEW_SECONDS > now) {
+    throw new AgentProofError("expired_proof", "The proof was made in the future.");
+  }
+  if (claims.htm !== expected.method.toUpperCase()) {
+    throw new AgentProofError("wrong_request", "The proof was made for another method.");
+  }
+  if (claims.htu !== canonicalUrl(expected.url)) {
+    throw new AgentProofError("wrong_request", "The proof was made for another URL.");
+  }
+  if (expected.audience !== void 0 && claims.aud !== expected.audience) {
+    throw new AgentProofError("wrong_audience", "The proof was made for somebody else.");
+  }
+  if (expected.body !== void 0) {
+    if (claims.bh !== bodyHash(expected.body)) {
+      throw new AgentProofError("body_changed", "The proof was made for a different body.");
+    }
+  }
+  if (expected.store) {
+    const fresh = await expected.store.claim(claims.jti, claims.exp);
+    if (!fresh) throw new AgentProofError("proof_already_used", "That proof has been used.");
+  }
+  return claims;
+}
+
+// src/index.ts
+function payWall(options) {
+  const apiBase = (options.apiBase ?? "https://api.tuppence.ai").replace(/\/+$/, "");
+  const store = options.store ?? new MemoryReceiptStore();
+  const jwks = options.jwks ?? new Jwks(`${apiBase}/.well-known/jwks.json`);
+  const offers = /* @__PURE__ */ new Map();
+  const reuseMs = (options.reuseSeconds ?? 300) * 1e3;
+  return async (request) => {
+    const resource = request.resource ?? `${request.method.toUpperCase()} ${request.path}`;
+    const presented = /^Tuppence-Receipt\s+(\S+)$/i.exec(request.authorization ?? "")?.[1];
+    const credit = /^Tuppence-Credits\s+(\S+)$/i.exec(request.authorization ?? "")?.[1];
+    let refusal;
+    if (credit && options.credits && options.tuppence.meterEvents) {
+      try {
+        const claims = await verifyCreditToken(credit, jwks, {
+          ...options.account ? { account: options.account } : {}
+        });
+        await options.tuppence.meterEvents.create({
+          customer: claims.customer,
+          meter: options.credits.meter,
+          identifier: request.idempotencyKey?.slice(0, 200) || `h402_${(0, import_node_crypto3.randomUUID)()}`,
+          credit_token: credit
+        });
+        return { paid: true, credits: claims };
+      } catch (error) {
+        const known = error;
+        if (error instanceof ReceiptError) refusal = { code: error.code, message: error.message };
+        else if (known.code && /^(insufficient_credits|credit_token_)/.test(known.code)) {
+          refusal = {
+            code: known.code,
+            message: known.message ?? "The credit could not be used.",
+            ...known.raw?.topup_url ? { topup_url: known.raw.topup_url } : {}
+          };
+        } else throw error;
+      }
+    } else if (presented) {
+      try {
+        const receipt = await verifyReceipt(presented, jwks, {
+          resource,
+          price: options.price,
+          currency: options.currency,
+          ...options.account ? { account: options.account } : {}
+        });
+        if (await store.claim(receipt.jti, receipt.exp)) return { paid: true, receipt };
+        refusal = {
+          code: "receipt_already_used",
+          message: "That receipt has been used. Pay again."
+        };
+      } catch (error) {
+        if (!(error instanceof ReceiptError)) throw error;
+        refusal = { code: error.code, message: error.message };
+      }
+    }
+    const key = `${request.caller} ${resource}`;
+    const now = Date.now();
+    let offer = offers.get(key);
+    if (!offer || now - offer.at > reuseMs || refusal?.code === "receipt_already_used") {
+      const payment = await options.tuppence.payments.create({
+        amount: options.price,
+        currency: options.currency,
+        resource,
+        ...options.description ? { description: options.description } : {}
+      });
+      const clientSecret = String(payment.approval_url).split("#")[1] ?? "";
+      offer = {
+        at: now,
+        headers: { Link: `<${payment.approval_url}>; rel="payment"` },
+        body: {
+          price: options.price,
+          currency: options.currency,
+          ...options.description ? { description: options.description } : {},
+          resource,
+          payment_id: payment.id,
+          accepts: [
+            { type: "card_link", url: payment.approval_url },
+            ...options.credits ? [{ type: "credits", scheme: "Tuppence-Credits", meter: options.credits.meter }] : []
+          ],
+          // Once paid: GET `url` with `header: client_secret`, and retry with its receipt_token.
+          receipt: {
+            url: `${apiBase}/public/payments/${payment.id}`,
+            header: "Tuppence-Client-Secret",
+            client_secret: clientSecret
+          }
+        }
+      };
+      offers.set(key, offer);
+    }
+    return {
+      paid: false,
+      status: 402,
+      headers: offer.headers,
+      body: {
+        error: {
+          type: "payment_required",
+          code: refusal?.code ?? "payment_required",
+          message: refusal?.message ?? "Payment required. Pay at the URL, then retry with the receipt.",
+          ...refusal?.topup_url ? { topup_url: refusal.topup_url } : {}
+        },
+        ...offer.body
+      }
+    };
+  };
+}
+var paidBy = (decision) => decision.receipt ? { receipt: decision.receipt } : { credits: decision.credits };
+function http402(options) {
+  const decide = payWall(options);
+  return (req, res, next) => {
+    decide({
+      method: req.method ?? "GET",
+      path: req.path ?? new URL(req.url ?? "/", "http://localhost").pathname,
+      authorization: req.headers.authorization,
+      idempotencyKey: req.headers["idempotency-key"],
+      caller: options.caller?.(req) ?? req.ip ?? req.socket.remoteAddress ?? "unknown",
+      ...options.resource ? { resource: options.resource(req) } : {}
+    }).then(
+      (decision) => {
+        if (decision.paid) {
+          if (decision.receipt) req.tuppenceReceipt = decision.receipt;
+          if (decision.credits) req.tuppenceCredits = decision.credits;
+          next();
+          return;
+        }
+        res.writeHead(decision.status, { "content-type": "application/json", ...decision.headers });
+        res.end(JSON.stringify(decision.body));
+      },
+      (error) => next(error)
+    );
+  };
+}
+function withPayment(options, handler) {
+  const decide = payWall(options);
+  return async (request) => {
+    const url = new URL(request.url);
+    const decision = await decide({
+      method: request.method,
+      path: url.pathname,
+      authorization: request.headers.get("authorization"),
+      idempotencyKey: request.headers.get("idempotency-key"),
+      caller: options.callerOf?.(request) ?? request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "unknown"
+    });
+    if (decision.paid) return handler(request, paidBy(decision));
+    return Response.json(decision.body, { status: decision.status, headers: decision.headers });
+  };
+}
+function paidTool(options, handler) {
+  const decide = payWall(options);
+  return async (args, extra) => {
+    const decision = await decide({
+      method: "TOOL",
+      path: options.name,
+      resource: `tool:${options.name}`,
+      authorization: args.credit_token ? `Tuppence-Credits ${args.credit_token}` : args.receipt ? `Tuppence-Receipt ${args.receipt}` : null,
+      caller: extra?.sessionId ?? "mcp"
+    });
+    if (decision.paid) return handler(args, paidBy(decision));
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Payment required: pay ${options.price} ${options.currency} at the URL below, fetch the receipt, then call this tool again with \`receipt\` set.
+${JSON.stringify(decision.body, null, 2)}`
+        }
+      ]
+    };
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentProofError,
+  Jwks,
+  MemoryReceiptStore,
+  ReceiptError,
+  agentJwksUrl,
+  agentKeys,
+  bodyHash,
+  canonicalUrl,
+  http402,
+  paidTool,
+  payWall,
+  verifyAgentProof,
+  verifyCreditToken,
+  verifyReceipt,
+  withPayment
+});

package/dist/index.d.ts

@@ -0,0 +1,142 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type CreditClaims, Jwks, type ReceiptClaims, type ReceiptStore } from "./verify.js";
+export type { AgentProofClaims, AgentProofErrorCode } from "./agent-proof.js";
+export { AgentProofError, agentJwksUrl, agentKeys, bodyHash, canonicalUrl, verifyAgentProof, } from "./agent-proof.js";
+export type { CreditClaims, ReceiptClaims, ReceiptErrorCode, ReceiptStore } from "./verify.js";
+export { Jwks, MemoryReceiptStore, ReceiptError, verifyCreditToken, verifyReceipt, } from "./verify.js";
+/**
+ * What the pay wall needs from a Tuppence client: to create a payment. `new Tuppence(key)` from
+ * `@tuppence/node` is exactly this — any object with the same method will do.
+ */
+export type PaymentsClient = {
+    payments: {
+        create(body: {
+            amount: number;
+            currency: string;
+            resource?: string;
+            description?: string;
+        }): Promise<{
+            id: string;
+            approval_url: string;
+        }>;
+    };
+    /** Needed for the credits rail (`credits` below). */
+    meterEvents?: {
+        create(body: {
+            customer: string;
+            meter: string;
+            identifier: string;
+            credit_token: string;
+        }): Promise<unknown>;
+    };
+};
+export type Http402Options = {
+    /** `new Tuppence(process.env.TUPPENCE_SECRET_KEY)` from `@tuppence/node`. */
+    tuppence: PaymentsClient;
+    /** In minor units: 50 = 50p. */
+    price: number;
+    currency: string;
+    description?: string;
+    /** What is being bought. Default `<METHOD> <path>`: a receipt for one route opens no other. */
+    resource?: (req: IncomingMessage) => string;
+    /** Your account id (`acct_…`): receipts paid to anyone else are refused. Recommended. */
+    account?: string;
+    /** Where used receipts are remembered. Default: this process's memory. */
+    store?: ReceiptStore;
+    /** Default `https://api.tuppence.ai`: where the keys (JWKS) and receipts live. */
+    apiBase?: string;
+    /** Where public keys come from. Default: `<apiBase>/.well-known/jwks.json`, cached. */
+    jwks?: Jwks;
+    /** How long an unpaid caller keeps getting the SAME payment to pay. Default 300 s. */
+    reuseSeconds?: number;
+    /** Who is asking, for that reuse. Default: the caller's address. */
+    caller?: (req: IncomingMessage) => string;
+    /**
+     * The credits rail (plan 12-06): let a customer's agent pay from their prepaid credit with a
+     * credit token (`Authorization: Tuppence-Credits <token>`) — no card, no fee per call. Each
+     * request records one use of `meter` (price it the same as `price`).
+     */
+    credits?: {
+        meter: string;
+    };
+};
+export type Decision = {
+    paid: true;
+    receipt: ReceiptClaims;
+    credits?: undefined;
+} | {
+    paid: true;
+    credits: CreditClaims;
+    receipt?: undefined;
+} | {
+    paid: false;
+    status: 402;
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+};
+/**
+ * HTTP 402 — "one line to put a price on a route" (plan 11-09). The framework-free core: given
+ * who is asking, for what, with which `Authorization`, decide. Adapters wrap it.
+ *
+ * Unpaid → `402 Payment Required` with where to pay (and a `Link` header). Once paid, the caller
+ * retries with `Authorization: Tuppence-Receipt <token>`, checked OFFLINE against Tuppence's
+ * published keys — no call to Tuppence on the hot path — and accepted once.
+ */
+export declare function payWall(options: Http402Options): (request: {
+    method: string;
+    path: string;
+    authorization?: string | null;
+    caller: string;
+    resource?: string;
+    /** The caller's `Idempotency-Key`: a retried request is then one use of credit, not two. */
+    idempotencyKey?: string | null;
+}) => Promise<Decision>;
+/** How a request was paid for: a receipt (card link) or a credit token (credits rail). */
+export type Paid = {
+    receipt?: ReceiptClaims;
+    credits?: CreditClaims;
+};
+type NodeRequest = IncomingMessage & {
+    tuppenceReceipt?: ReceiptClaims;
+    tuppenceCredits?: CreditClaims;
+    path?: string;
+    ip?: string;
+};
+/**
+ * Node `http`, Express or Connect middleware:
+ *
+ *   app.get("/v1/report", http402({ tuppence, price: 50, currency: "gbp" }), handler);
+ *
+ * On success, `req.tuppenceReceipt` holds the receipt's claims.
+ */
+export declare function http402(options: Http402Options): (req: NodeRequest, res: ServerResponse, next: (error?: unknown) => void) => void;
+/**
+ * Fetch-style handlers (Next.js route handlers, Hono, Bun, Deno, Workers):
+ *
+ *   export const GET = withPayment({ tuppence, price: 50, currency: "gbp" }, async () => Response.json(report));
+ */
+export declare function withPayment(options: Http402Options & {
+    callerOf?: (request: Request) => string;
+}, handler: (request: Request, paid: Paid) => Response | Promise<Response>): (request: Request) => Promise<Response>;
+/**
+ * A paid MCP tool (any MCP server SDK): the tool takes an optional `receipt` argument. Without
+ * a good one it answers with where to pay — as a tool error the agent can act on — and with one
+ * it runs, once.
+ *
+ *   server.tool("deep_research", schema, paidTool({ tuppence, price: 200, currency: "gbp", name: "deep_research" }, run));
+ */
+export declare function paidTool<A extends {
+    receipt?: string;
+    credit_token?: string;
+}, R>(options: Omit<Http402Options, "resource" | "caller"> & {
+    name: string;
+}, handler: (args: A, paid: Paid) => R | Promise<R>): (args: A, extra?: {
+    sessionId?: string;
+}) => Promise<R | ToolPaymentRequired>;
+export type ToolPaymentRequired = {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/index.js

@@ -0,0 +1,215 @@
+import { randomUUID } from "node:crypto";
+import { Jwks, MemoryReceiptStore, ReceiptError, verifyCreditToken, verifyReceipt, } from "./verify.js";
+export { AgentProofError, agentJwksUrl, agentKeys, bodyHash, canonicalUrl, verifyAgentProof, } from "./agent-proof.js";
+export { Jwks, MemoryReceiptStore, ReceiptError, verifyCreditToken, verifyReceipt, } from "./verify.js";
+/**
+ * HTTP 402 — "one line to put a price on a route" (plan 11-09). The framework-free core: given
+ * who is asking, for what, with which `Authorization`, decide. Adapters wrap it.
+ *
+ * Unpaid → `402 Payment Required` with where to pay (and a `Link` header). Once paid, the caller
+ * retries with `Authorization: Tuppence-Receipt <token>`, checked OFFLINE against Tuppence's
+ * published keys — no call to Tuppence on the hot path — and accepted once.
+ */
+export function payWall(options) {
+    const apiBase = (options.apiBase ?? "https://api.tuppence.ai").replace(/\/+$/, "");
+    const store = options.store ?? new MemoryReceiptStore();
+    const jwks = options.jwks ?? new Jwks(`${apiBase}/.well-known/jwks.json`);
+    const offers = new Map();
+    const reuseMs = (options.reuseSeconds ?? 300) * 1000;
+    return async (request) => {
+        const resource = request.resource ?? `${request.method.toUpperCase()} ${request.path}`;
+        const presented = /^Tuppence-Receipt\s+(\S+)$/i.exec(request.authorization ?? "")?.[1];
+        const credit = /^Tuppence-Credits\s+(\S+)$/i.exec(request.authorization ?? "")?.[1];
+        let refusal;
+        if (credit && options.credits && options.tuppence.meterEvents) {
+            try {
+                const claims = await verifyCreditToken(credit, jwks, {
+                    ...(options.account ? { account: options.account } : {}),
+                });
+                await options.tuppence.meterEvents.create({
+                    customer: claims.customer,
+                    meter: options.credits.meter,
+                    identifier: request.idempotencyKey?.slice(0, 200) || `h402_${randomUUID()}`,
+                    credit_token: credit,
+                });
+                return { paid: true, credits: claims };
+            }
+            catch (error) {
+                const known = error;
+                if (error instanceof ReceiptError)
+                    refusal = { code: error.code, message: error.message };
+                else if (known.code && /^(insufficient_credits|credit_token_)/.test(known.code)) {
+                    refusal = {
+                        code: known.code,
+                        message: known.message ?? "The credit could not be used.",
+                        ...(known.raw?.topup_url ? { topup_url: known.raw.topup_url } : {}),
+                    };
+                }
+                else
+                    throw error;
+            }
+        }
+        else if (presented) {
+            try {
+                const receipt = await verifyReceipt(presented, jwks, {
+                    resource,
+                    price: options.price,
+                    currency: options.currency,
+                    ...(options.account ? { account: options.account } : {}),
+                });
+                if (await store.claim(receipt.jti, receipt.exp))
+                    return { paid: true, receipt };
+                refusal = {
+                    code: "receipt_already_used",
+                    message: "That receipt has been used. Pay again.",
+                };
+            }
+            catch (error) {
+                if (!(error instanceof ReceiptError))
+                    throw error;
+                refusal = { code: error.code, message: error.message };
+            }
+        }
+        // Where to pay — the same payment for a few minutes, so an agent that retries does not
+        // leave a trail of unpaid payments behind it. A spent receipt needs a new payment.
+        const key = `${request.caller} ${resource}`;
+        const now = Date.now();
+        let offer = offers.get(key);
+        if (!offer || now - offer.at > reuseMs || refusal?.code === "receipt_already_used") {
+            const payment = await options.tuppence.payments.create({
+                amount: options.price,
+                currency: options.currency,
+                resource,
+                ...(options.description ? { description: options.description } : {}),
+            });
+            const clientSecret = String(payment.approval_url).split("#")[1] ?? "";
+            offer = {
+                at: now,
+                headers: { Link: `<${payment.approval_url}>; rel="payment"` },
+                body: {
+                    price: options.price,
+                    currency: options.currency,
+                    ...(options.description ? { description: options.description } : {}),
+                    resource,
+                    payment_id: payment.id,
+                    accepts: [
+                        { type: "card_link", url: payment.approval_url },
+                        ...(options.credits
+                            ? [{ type: "credits", scheme: "Tuppence-Credits", meter: options.credits.meter }]
+                            : []),
+                    ],
+                    // Once paid: GET `url` with `header: client_secret`, and retry with its receipt_token.
+                    receipt: {
+                        url: `${apiBase}/public/payments/${payment.id}`,
+                        header: "Tuppence-Client-Secret",
+                        client_secret: clientSecret,
+                    },
+                },
+            };
+            offers.set(key, offer);
+        }
+        return {
+            paid: false,
+            status: 402,
+            headers: offer.headers,
+            body: {
+                error: {
+                    type: "payment_required",
+                    code: refusal?.code ?? "payment_required",
+                    message: refusal?.message ?? "Payment required. Pay at the URL, then retry with the receipt.",
+                    ...(refusal?.topup_url ? { topup_url: refusal.topup_url } : {}),
+                },
+                ...offer.body,
+            },
+        };
+    };
+}
+const paidBy = (decision) => decision.receipt ? { receipt: decision.receipt } : { credits: decision.credits };
+/**
+ * Node `http`, Express or Connect middleware:
+ *
+ *   app.get("/v1/report", http402({ tuppence, price: 50, currency: "gbp" }), handler);
+ *
+ * On success, `req.tuppenceReceipt` holds the receipt's claims.
+ */
+export function http402(options) {
+    const decide = payWall(options);
+    return (req, res, next) => {
+        decide({
+            method: req.method ?? "GET",
+            path: req.path ?? new URL(req.url ?? "/", "http://localhost").pathname,
+            authorization: req.headers.authorization,
+            idempotencyKey: req.headers["idempotency-key"],
+            caller: options.caller?.(req) ?? req.ip ?? req.socket.remoteAddress ?? "unknown",
+            ...(options.resource ? { resource: options.resource(req) } : {}),
+        }).then((decision) => {
+            if (decision.paid) {
+                if (decision.receipt)
+                    req.tuppenceReceipt = decision.receipt;
+                if (decision.credits)
+                    req.tuppenceCredits = decision.credits;
+                next();
+                return;
+            }
+            res.writeHead(decision.status, { "content-type": "application/json", ...decision.headers });
+            res.end(JSON.stringify(decision.body));
+        }, (error) => next(error));
+    };
+}
+/**
+ * Fetch-style handlers (Next.js route handlers, Hono, Bun, Deno, Workers):
+ *
+ *   export const GET = withPayment({ tuppence, price: 50, currency: "gbp" }, async () => Response.json(report));
+ */
+export function withPayment(options, handler) {
+    const decide = payWall(options);
+    return async (request) => {
+        const url = new URL(request.url);
+        const decision = await decide({
+            method: request.method,
+            path: url.pathname,
+            authorization: request.headers.get("authorization"),
+            idempotencyKey: request.headers.get("idempotency-key"),
+            caller: options.callerOf?.(request) ??
+                request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+                "unknown",
+        });
+        if (decision.paid)
+            return handler(request, paidBy(decision));
+        return Response.json(decision.body, { status: decision.status, headers: decision.headers });
+    };
+}
+/**
+ * A paid MCP tool (any MCP server SDK): the tool takes an optional `receipt` argument. Without
+ * a good one it answers with where to pay — as a tool error the agent can act on — and with one
+ * it runs, once.
+ *
+ *   server.tool("deep_research", schema, paidTool({ tuppence, price: 200, currency: "gbp", name: "deep_research" }, run));
+ */
+export function paidTool(options, handler) {
+    const decide = payWall(options);
+    return async (args, extra) => {
+        const decision = await decide({
+            method: "TOOL",
+            path: options.name,
+            resource: `tool:${options.name}`,
+            authorization: args.credit_token
+                ? `Tuppence-Credits ${args.credit_token}`
+                : args.receipt
+                    ? `Tuppence-Receipt ${args.receipt}`
+                    : null,
+            caller: extra?.sessionId ?? "mcp",
+        });
+        if (decision.paid)
+            return handler(args, paidBy(decision));
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Payment required: pay ${options.price} ${options.currency} at the URL below, fetch the receipt, then call this tool again with \`receipt\` set.\n${JSON.stringify(decision.body, null, 2)}`,
+                },
+            ],
+        };
+    };
+}

package/dist/verify.d.ts

@@ -0,0 +1,78 @@
+import { type KeyObject } from "node:crypto";
+/** The claims inside a Tuppence receipt token (plan 11-08). */
+export type ReceiptClaims = {
+    iss: string;
+    payment_id: string;
+    account: string;
+    livemode: boolean;
+    amount: number;
+    currency: string;
+    resource: string | null;
+    iat: number;
+    exp: number;
+    jti: string;
+};
+export type ReceiptErrorCode = "malformed_receipt" | "unknown_key" | "bad_signature" | "expired_receipt" | "wrong_resource" | "wrong_amount" | "wrong_account" | "receipt_already_used";
+export declare class ReceiptError extends Error {
+    readonly code: ReceiptErrorCode;
+    constructor(code: ReceiptErrorCode, message: string);
+}
+/**
+ * Tuppence's public keys, fetched from its JWKS and kept for five minutes — and fetched again
+ * at once if a token names a key we have not seen (a rotation). Nothing else calls Tuppence:
+ * verifying a receipt is offline.
+ */
+export declare class Jwks {
+    private readonly url;
+    private readonly fetcher;
+    private readonly ttlMs;
+    private keys;
+    private fetchedAt;
+    private inflight;
+    constructor(url: string, fetcher?: typeof fetch, ttlMs?: number);
+    key(kid: string): Promise<KeyObject | undefined>;
+    private refresh;
+}
+/** Where a receipt's `jti` is remembered until it expires, so each receipt is used once. */
+export interface ReceiptStore {
+    /** True if `jti` was new (and is now taken); false if it had been used. */
+    claim(jti: string, expiresAt: number): Promise<boolean> | boolean;
+}
+/** The default store: this process's memory. Run more than one process? Share a store. */
+export declare class MemoryReceiptStore implements ReceiptStore {
+    private readonly used;
+    claim(jti: string, expiresAt: number): boolean;
+}
+/**
+ * Checks a receipt token completely: signature (against the JWKS), expiry, the resource it was
+ * bought for, amount and currency, and — if you say — the account it was paid to. It does NOT
+ * mark the receipt used: `claim` its `jti` in a store for that.
+ */
+export declare function verifyReceipt(token: string, jwks: Jwks, expected: {
+    resource: string;
+    price: number;
+    currency: string;
+    account?: string;
+    nowSeconds?: number;
+}): Promise<ReceiptClaims>;
+/** The claims inside a Tuppence credit token (plan 12-06): an agent's permission to spend. */
+export type CreditClaims = {
+    typ: "credit";
+    iss: string;
+    account: string;
+    livemode: boolean;
+    customer: string;
+    max_amount: number;
+    currency: string;
+    iat: number;
+    exp: number;
+    jti: string;
+};
+/**
+ * A credit token, checked offline before anything is spent: signature, kind, expiry and — if
+ * you say — the account. The cap is enforced by Tuppence when the usage is recorded.
+ */
+export declare function verifyCreditToken(token: string, jwks: Jwks, expected?: {
+    account?: string;
+    nowSeconds?: number;
+}): Promise<CreditClaims>;

package/dist/verify.js

@@ -0,0 +1,144 @@
+import { createPublicKey, verify } from "node:crypto";
+export class ReceiptError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ReceiptError";
+    }
+}
+/**
+ * Tuppence's public keys, fetched from its JWKS and kept for five minutes — and fetched again
+ * at once if a token names a key we have not seen (a rotation). Nothing else calls Tuppence:
+ * verifying a receipt is offline.
+ */
+export class Jwks {
+    url;
+    fetcher;
+    ttlMs;
+    keys = new Map();
+    fetchedAt = 0;
+    inflight;
+    constructor(url, fetcher = globalThis.fetch, ttlMs = 5 * 60_000) {
+        this.url = url;
+        this.fetcher = fetcher;
+        this.ttlMs = ttlMs;
+    }
+    async key(kid) {
+        const stale = Date.now() - this.fetchedAt > this.ttlMs;
+        if (stale || !this.keys.has(kid))
+            await this.refresh();
+        return this.keys.get(kid);
+    }
+    refresh() {
+        this.inflight ??= (async () => {
+            try {
+                const response = await this.fetcher(this.url, { headers: { Accept: "application/json" } });
+                if (!response.ok)
+                    throw new Error(`Could not fetch Tuppence's keys (${response.status})`);
+                const { keys } = (await response.json());
+                this.keys = new Map(keys
+                    .filter((k) => k.kty === "OKP" && k.crv === "Ed25519")
+                    .map((k) => [k.kid, createPublicKey({ key: k, format: "jwk" })]));
+                this.fetchedAt = Date.now();
+            }
+            finally {
+                this.inflight = undefined;
+            }
+        })();
+        return this.inflight;
+    }
+}
+/** The default store: this process's memory. Run more than one process? Share a store. */
+export class MemoryReceiptStore {
+    used = new Map();
+    claim(jti, expiresAt) {
+        const now = Date.now() / 1000;
+        for (const [id, exp] of this.used)
+            if (exp < now)
+                this.used.delete(id);
+        if (this.used.has(jti))
+            return false;
+        this.used.set(jti, expiresAt);
+        return true;
+    }
+}
+/**
+ * Checks a receipt token completely: signature (against the JWKS), expiry, the resource it was
+ * bought for, amount and currency, and — if you say — the account it was paid to. It does NOT
+ * mark the receipt used: `claim` its `jti` in a store for that.
+ */
+export async function verifyReceipt(token, jwks, expected) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new ReceiptError("malformed_receipt", "That is not a receipt token.");
+    const [h, p, s] = parts;
+    let header;
+    let claims;
+    try {
+        header = JSON.parse(Buffer.from(h, "base64url").toString());
+        claims = JSON.parse(Buffer.from(p, "base64url").toString());
+    }
+    catch {
+        throw new ReceiptError("malformed_receipt", "That is not a receipt token.");
+    }
+    if (header.alg !== "EdDSA" || !header.kid) {
+        throw new ReceiptError("malformed_receipt", "Receipts are EdDSA-signed JWTs with a key id.");
+    }
+    const key = await jwks.key(header.kid);
+    if (!key) {
+        throw new ReceiptError("unknown_key", "The receipt was signed by a key Tuppence does not publish.");
+    }
+    if (!verify(null, Buffer.from(`${h}.${p}`), key, Buffer.from(s, "base64url"))) {
+        throw new ReceiptError("bad_signature", "The receipt's signature does not verify.");
+    }
+    const now = expected.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (typeof claims.exp !== "number" || now >= claims.exp) {
+        throw new ReceiptError("expired_receipt", "The receipt has expired. Pay again.");
+    }
+    if (claims.resource !== expected.resource) {
+        throw new ReceiptError("wrong_resource", `The receipt is for ${claims.resource ?? "nothing in particular"}, not ${expected.resource}.`);
+    }
+    if (claims.currency !== expected.currency || claims.amount < expected.price) {
+        throw new ReceiptError("wrong_amount", "The receipt is for less than the price.");
+    }
+    if (expected.account && claims.account !== expected.account) {
+        throw new ReceiptError("wrong_account", "The receipt was paid to someone else.");
+    }
+    return claims;
+}
+/**
+ * A credit token, checked offline before anything is spent: signature, kind, expiry and — if
+ * you say — the account. The cap is enforced by Tuppence when the usage is recorded.
+ */
+export async function verifyCreditToken(token, jwks, expected = {}) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new ReceiptError("malformed_receipt", "That is not a credit token.");
+    const [h, p, s] = parts;
+    let header;
+    let claims;
+    try {
+        header = JSON.parse(Buffer.from(h, "base64url").toString());
+        claims = JSON.parse(Buffer.from(p, "base64url").toString());
+    }
+    catch {
+        throw new ReceiptError("malformed_receipt", "That is not a credit token.");
+    }
+    const key = header.alg === "EdDSA" && header.kid ? await jwks.key(header.kid) : undefined;
+    if (!key)
+        throw new ReceiptError("unknown_key", "The credit token was not signed by Tuppence.");
+    if (!verify(null, Buffer.from(`${h}.${p}`), key, Buffer.from(s, "base64url"))) {
+        throw new ReceiptError("bad_signature", "The credit token's signature does not verify.");
+    }
+    if (claims.typ !== "credit")
+        throw new ReceiptError("malformed_receipt", "That is not a credit token.");
+    const now = expected.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (typeof claims.exp !== "number" || now >= claims.exp) {
+        throw new ReceiptError("expired_receipt", "The credit token has expired.");
+    }
+    if (expected.account && claims.account !== expected.account) {
+        throw new ReceiptError("wrong_account", "The credit token was issued by someone else.");
+    }
+    return claims;
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@tuppence/http402",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Put a price on an API route or an MCP tool: HTTP 402 with Tuppence receipts, verified offline.",
+  "license": "MIT",
+  "homepage": "https://docs.tuppence.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZenningAI/tuppence.git",
+    "directory": "packages/http402"
+  },
+  "bugs": "https://github.com/ZenningAI/tuppence/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --outfile=dist/index.cjs --log-level=warning",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }