@keelcodes/x402-gate 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# @keelcodes/x402-gate
 
-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.
+给任意 HTTP 接口加一道 x402 v2 收费门：**不持私钥、不接触链**，只把客户端的
+`PAYMENT-SIGNATURE` 转给支付引擎验签/结算。
+
+- 标准轨：`exact` over **EIP-3009**（Base USDC）或 **Permit2**（BSC USDT/USDC、任意 ERC-20、智能账户）
+- Keel 轨：客户端先转账、载荷里带 `txHash`，网关自动改用 `/x402/verify`
+- 运行时无关：Express / Fetch / Next.js App Router（含 edge）/ Workers
+
+## 安装
+
+```bash
+npm i @keelcodes/x402-gate
+```
+
+## Express
+
+```ts
+import express from 'express'
+import { createX402Gate } from '@keelcodes/x402-gate'
+
+const app = express()
+app.use(express.json())
+
+const gate = createX402Gate({
+  paymentsUrl: 'https://keel.codes/v1/payment',
+  paymentsKey: process.env.PAYMENTS_KEY,
+  payTo: '0xYourReceivingAddress',
+  amount: '2000', // 最小单位
+  accepts: [
+    { network: 'eip155:8453', asset: '0x8335…2913', eip3009: { name: 'USD Coin', version: '2' } },
+    { network: 'eip155:56', asset: '0x55d3…7955', permit2: true },
+  ],
+})
+
+app.get('/quote', gate, (_req, res) => res.json({ price: 42 }))
+```
+
+## Next.js App Router
+
+```ts
+import { withX402 } from '@keelcodes/x402-gate'
+
+const gateOptions = { /* 同上 */ }
+
+export const GET = withX402(gateOptions, async () => Response.json({ price: 42 }))
+```
+
+## 配置
+
+| 字段 | 说明 |
+|---|---|
+| `paymentsUrl` | 支付引擎地址（自建或 `https://keel.codes/v1/payment`） |
+| `paymentsKey` | 支付引擎 Bearer key |
+| `payTo` | 收款地址（B 端自己的钱包；资金直达，不经平台） |
+| `amount` | 单次价格（最小单位）；也可用 `amountFor(path)` 动态定价 |
+| `accepts` | 多链多资产；每项二选一：`eip3009: { name, version }` 或 `permit2: true` |
+| `exempt` | 免费路径前缀（默认已含 `/health`、`/metrics`） |
+| `passthroughHeaders` | 额外视为「已有平台凭证」的头（如 `x-tenant-id`） |
+| `resource` | 写进 402 `resource` 的服务元数据：`description` / `mimeType` / `serviceName` / `tags` / `iconUrl`（目录与 agent 读取） |
+| `bazaar` | Bazaar 扩展 `{ info, schema? }`；facilitator 据此索引本资源 |
+| `freeQuota` | 免费额度：`{ calls, period: 'day'\|'month', windowMs?, key?, now? }`；窗口内前 N 次直接放行（响应带 `X-Free-Quota-Remaining`），用完后转 402 |
+
+已有平台凭证（`Authorization` / `X-API-Key` / `X-Service-Key`）的请求直接放行，
+不影响原来的「人」的调用。
+
+## 被发现 + 免费额度
+
+```ts
+const gate = createX402Gate({
+  paymentsUrl: 'https://keel.codes/v1/payment',
+  payTo: '0xYourReceivingAddress',
+  network: 'eip155:8453',
+  asset: '0x8335…2913',
+  amount: '2000',
+  domain: { name: 'USD Coin', version: '2' },
+  // 目录/agent 从 402 里读到这些信息
+  resource: {
+    serviceName: 'My Tick API',
+    description: 'Per-request price feed',
+    mimeType: 'application/json',
+    tags: ['market-data'],
+  },
+  bazaar: { info: { input: { type: 'http', method: 'GET' }, output: { type: 'json' } } },
+  // 每 IP 每天前 100 次免费（沙箱体验），之后 402
+  freeQuota: { calls: 100, period: 'day' },
+})
+```
+
+- 免费额度按 `serviceName|payTo` + 调用方（缺省 `req.ip`，用 `key` 可换成 X-Forwarded-For / 租户）分桶，窗口滚动。
+- `calls: 0` 表示关闭免费额度。
+
+## 客户端怎么付
+
+任何标准 x402 客户端都行：先发请求拿 `402 + PAYMENT-REQUIRED`，选一个 `accepts`
+签名，再带 `PAYMENT-SIGNATURE` 重试。用 Keel SDK 时这一套是自动的：
+
+> v1 客户端（`X-PAYMENT`）也兼容：网关同时读 `X-PAYMENT`，402 响应体降级为 v1 结构
+> （`x402Version: 1` + `maxAmountRequired` + 短网络名 `base`），成功后额外回
+> `X-PAYMENT-RESPONSE`。`PAYMENT-REQUIRED` 头始终是 v2。
+
+```ts
+const keel = new KeelClient({
+  x402: { address, signTypedData, signPermit2TypedData },
+})
+await keel.get('https://api.example/quote') // 402 → 签名 → 重试 → 200
+```
+
+## 状态码
+
+| 场景 | 响应 |
+|---|---|
+| 未付款 | `402` + `PAYMENT-REQUIRED`（含 `accepts[]` 与 `error`） |
+| 结算成功 | 原接口响应 + `PAYMENT-RESPONSE`（`transaction` / `payer` / `amount`） |
+| 结算失败 | `402` + `PAYMENT-REQUIRED`（`error` 带引擎给的原因） |
+| 引擎不可达 | `402`（不返回 500，客户端可重试） |
+| 需要先授权 Permit2 | 引擎在 `PAYMENT-RESPONSE` 前返回 `412 PERMIT2_ALLOWANCE_REQUIRED` |
+
+## 上架登记（市场）
+
+B 端要让外部用户/agent 发现你的服务，需要登记 `payTo` 并证明所有权：
+
+```bash
+# 1. 取待签名内容
+curl -sX POST https://keel.codes/v1/payment/market/listings/challenge \
+  -H 'Content-Type: application/json' \
+  -d '{"payTo":"0xB端收款地址","network":"eip155:56","asset":"0x55d3…7955","amount":"2000","method":"permit2"}'
+
+# 2. 用 payTo 的私钥对返回的 typedData 做 EIP-712 签名，提交
+curl -sX POST https://keel.codes/v1/payment/market/listings \
+  -H 'Content-Type: application/json' \
+  -d '{"payTo":"0x…","network":"eip155:56","asset":"0x55d3…","amount":"2000","method":"permit2","nonce":"0x…","signature":"0x…"}'
+```
+
+- 签名者必须等于 `payTo`，否则 `403 OWNERSHIP_PROOF_FAILED`（冒名无法登记）
+- 默认自动通过；`review: 'manual'` 时进入 `pending`，由管理员 `POST /listings/:id/review` 放行
+- 审核通过后用 `store.approvedPayTos()` 接进支付引擎：
+
+```ts
+facilitator: { allowedPayTo: () => marketplaceStore.approvedPayTos() }
+```
+
+## 安全边界
+
+- 网关只做转发，不持私钥、不读链；被攻破也无法转走资金
+- 收款地址由 B 端自己控制（或第三方白名单），平台不代收
+- 结算凭证（txHash）由支付引擎返回，网关原样透传

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+/**
+ * x402 v2 资源网关（标准 exact：EIP-3009 / Permit2）
+ *
+ * 让任意对外接口在没有平台 API Key 时也接受 agent 的 x402 付款。
+ * 鉴权优先级（命中即停）：
+ *   1. 已有平台凭证（Authorization / X-API-Key / X-Service-Key）→ 放行
+ *   2. 无付款凭证 → 402；响应体降级为 v1 结构供老客户端读取，`PAYMENT-REQUIRED` 头为 v2
+ *   3. 有 `PAYMENT-SIGNATURE`（或 v1 的 `X-PAYMENT`）→ 调支付引擎 `/x402/settle`
+ *      （Keel 轨走 `/x402/verify`）→ 200 + `PAYMENT-RESPONSE`（同时回 v1 的 `X-PAYMENT-RESPONSE`）
+ *
+ * 本包不持私钥、不接触链，只依赖全局 fetch 与 Web 标准 API，因此可以跑在
+ * Node / Next.js App Router（含 edge runtime）/ Cloudflare Workers。
+ *
+ * 多 accept：同时给出 EIP-3009 与 Permit2，客户端按自身能力选择；服务端把完整
+ * 挑战（`accepts[]`）转发给支付引擎，由引擎按载荷匹配。
+ */
+/** canonical Permit2（各链同址） */
+export declare const PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+/** canonical x402 exact over Permit2 代理（spender，资金只流向 witness.to） */
+export declare const X402_EXACT_PERMIT2_PROXY = "0x402085c248EeA27D92E8b30b2C58ed07f9E20001";
+export interface X402Accept {
+    scheme: 'exact';
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+export interface X402PaymentRequired {
+    x402Version: 2;
+    error?: string;
+    resource: {
+        url: string;
+        description?: string;
+        mimeType?: string;
+        serviceName?: string;
+        tags?: string[];
+        iconUrl?: string;
+    };
+    accepts: X402Accept[];
+    /** Bazaar 扩展（x402 v2 §extensions/bazaar）：让 facilitator 能索引本资源 */
+    extensions?: {
+        bazaar: {
+            info: Record<string, unknown>;
+            schema?: Record<string, unknown>;
+        };
+    };
+    /**
+     * 非标准扩展：给「按次太贵，买包更便宜」的引导链接。
+     * 标准客户端会忽略未知字段，不影响验签与结算。
+     */
+    links?: X402Link[];
+}
+export interface X402Link {
+    /** 目前只用 `purchase`：引导到额度包购买页 */
+    rel: 'purchase';
+    href: string;
+    title?: string;
+}
+/** 资源元数据（写进 402 的 resource，供目录/agent 读取） */
+export interface X402ResourceMeta {
+    description?: string;
+    mimeType?: string;
+    serviceName?: string;
+    tags?: string[];
+    iconUrl?: string;
+}
+/** Bazaar 扩展内容：input/output 由服务方声明，缺 schema 时 facilitator 按 info 索引 */
+export interface X402BazaarExtension {
+    info: Record<string, unknown>;
+    schema?: Record<string, unknown>;
+}
+/** 免费额度（B13.3）：每个调用方在一个窗口内前 N 次直接放行，之后转 402 */
+export interface X402FreeQuota {
+    calls: number;
+    /** 窗口长度；缺省按 period 推（day=24h / month=30d） */
+    windowMs?: number;
+    period?: 'day' | 'month';
+    /** 调用方标识（缺省用 req.ip；同一 key 共享额度） */
+    key?: (req: GateRequest) => string;
+    now?: () => number;
+}
+/** 单个可收款资产：EIP-3009 或 Permit2，二选一。 */
+export interface X402GateAccept {
+    /** CAIP-2，如 eip155:8453 */
+    network: string;
+    /** ERC-20 合约 */
+    asset: string;
+    /** 覆盖单次价格（缺省用 amount / amountFor） */
+    amount?: string;
+    /** 覆盖收款地址（缺省用顶层 payTo） */
+    payTo?: string;
+    maxTimeoutSeconds?: number;
+    /** EIP-3009 域；有 `domainName` 的代币（如 Base USDC）走这条 */
+    eip3009?: {
+        name: string;
+        version: string;
+    };
+    /** 启用 Permit2（任意 ERC-20，含 BSC USDT/USDC 与智能账户） */
+    permit2?: boolean | {
+        address?: string;
+        proxy?: string;
+    };
+}
+export interface X402GateOptions {
+    /** 支付引擎基础地址，如 https://keel.codes/v1/payment */
+    paymentsUrl: string;
+    /** 支付引擎鉴权（Bearer） */
+    paymentsKey?: string;
+    /** 单 accept 简写 */
+    payTo?: string;
+    network?: string;
+    asset?: string;
+    amount?: string;
+    domain?: {
+        name: string;
+        version: string;
+    };
+    /** 多 accept（优先于上面的简写） */
+    accepts?: X402GateAccept[];
+    /** 命中这些路径前缀的请求不收费（探针/文档） */
+    exempt?: string[];
+    /** 按请求覆盖价格（最小单位）；返回 null 表示不收费 */
+    amountFor?: (path: string) => string | null;
+    /** 额外视为「已有平台凭证」的请求头（如 x-tenant-id） */
+    passthroughHeaders?: string[];
+    /** 资源元数据（写进 402 的 resource；B13.1 目录展示用） */
+    resource?: X402ResourceMeta;
+    /** Bazaar 扩展（写进 402；B13.2 让 facilitator 自动索引） */
+    bazaar?: X402BazaarExtension;
+    /** 免费额度（B13.3）：窗口内前 N 次不收费 */
+    freeQuota?: X402FreeQuota;
+    /**
+     * 购买引导链接（写进 402 的 `links`，A7.1）：按次单价通常高于包内均价，
+     * 用这个字段告诉 agent/用户「买额度包更便宜」。返回 null 表示该路径不给链接。
+     */
+    purchaseUrl?: string | ((path: string) => string | null);
+    /** 结算超时（毫秒，默认 15s） */
+    timeoutMs?: number;
+    log?: (msg: string) => void;
+}
+/** 框架无关的请求视图 */
+export interface GateRequest {
+    path: string;
+    url: string;
+    header: (name: string) => string | null;
+    /** 调用方地址（免费额度分桶用；缺省视为同一桶） */
+    ip?: string;
+}
+export type GateResult = {
+    action: 'pass';
+    headers?: Record<string, string>;
+} | {
+    action: 'challenge';
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+};
+export declare function encodeBase64Json(obj: unknown): string;
+export declare function decodeBase64Json(input: string): unknown;
+/**
+ * 把「单 accept 简写」与「多 accept」统一展开。
+ * 有 `eip3009` 用 EIP-3009 extra；有 `permit2` 用 Permit2 extra；都没给则按 EIP-3009
+ * 无域输出（兼容老服务：只靠 `amount` 覆盖价格的场景）。
+ */
+export declare function buildAccepts(opts: X402GateOptions, amount: string): X402Accept[];
+/** 402 挑战（标准 v2）——`resource` 带上服务元数据，`extensions.bazaar` 供 facilitator 索引。 */
+export declare function buildChallenge(opts: X402GateOptions, url: string, amount: string, path?: string): X402PaymentRequired;
+/** CAIP-2 → v1 短网络名；未知网络原样返回（v1 客户端自然不支持）。 */
+export declare function toV1Network(network: string): string;
+/**
+ * v2 挑战 → v1 `PaymentRequirementsResponse`（v1 把 resource/description/mimeType
+ * 放在每个 accept 内，金额字段叫 `maxAmountRequired`）。
+ */
+export declare function toV1Challenge(challenge: X402PaymentRequired): Record<string, unknown>;
+/** 仅用于测试/运维：清空内存额度。 */
+export declare function resetFreeQuota(): void;
+/**
+ * Keel 轨（legacy verifyOnly）：客户端先广播转账，载荷里带 `txHash`。
+ * 这类请求走 `/x402/verify`（验链上凭证），而不是 `/x402/settle`（代广播）。
+ */
+export declare function legacyTxHash(header: string): string | null;
+/**
+ * 网关核心：返回「放行」或「402 挑战」，与框架无关。
+ * 结算失败一律 402（携带原因），避免把上游错误变成 500。
+ */
+export declare function authorizeX402(opts: X402GateOptions, req: GateRequest): Promise<GateResult>;
+/** Express / Connect 适配器 */
+export declare function createX402Gate(opts: X402GateOptions): (req: any, res: any, next: any) => Promise<void>;
+/** Fetch 处理器（Next.js App Router / Workers 同形） */
+export type FetchHandler = (request: Request) => Promise<Response> | Response;
+/**
+ * 包装一个 Fetch 处理器：未付款 → 402；已付款/有平台凭证 → 原处理器。
+ *
+ * ```ts
+ * // app/api/quote/route.ts
+ * export const GET = withX402(opts, async () => Response.json({ price: 42 }))
+ * ```
+ */
+export declare function withX402(opts: X402GateOptions, handler: FetchHandler): FetchHandler;

package/dist/index.js

@@ -0,0 +1,379 @@
+"use strict";
+/**
+ * x402 v2 资源网关（标准 exact：EIP-3009 / Permit2）
+ *
+ * 让任意对外接口在没有平台 API Key 时也接受 agent 的 x402 付款。
+ * 鉴权优先级（命中即停）：
+ *   1. 已有平台凭证（Authorization / X-API-Key / X-Service-Key）→ 放行
+ *   2. 无付款凭证 → 402；响应体降级为 v1 结构供老客户端读取，`PAYMENT-REQUIRED` 头为 v2
+ *   3. 有 `PAYMENT-SIGNATURE`（或 v1 的 `X-PAYMENT`）→ 调支付引擎 `/x402/settle`
+ *      （Keel 轨走 `/x402/verify`）→ 200 + `PAYMENT-RESPONSE`（同时回 v1 的 `X-PAYMENT-RESPONSE`）
+ *
+ * 本包不持私钥、不接触链，只依赖全局 fetch 与 Web 标准 API，因此可以跑在
+ * Node / Next.js App Router（含 edge runtime）/ Cloudflare Workers。
+ *
+ * 多 accept：同时给出 EIP-3009 与 Permit2，客户端按自身能力选择；服务端把完整
+ * 挑战（`accepts[]`）转发给支付引擎，由引擎按载荷匹配。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X402_EXACT_PERMIT2_PROXY = exports.PERMIT2_ADDRESS = void 0;
+exports.encodeBase64Json = encodeBase64Json;
+exports.decodeBase64Json = decodeBase64Json;
+exports.buildAccepts = buildAccepts;
+exports.buildChallenge = buildChallenge;
+exports.toV1Network = toV1Network;
+exports.toV1Challenge = toV1Challenge;
+exports.resetFreeQuota = resetFreeQuota;
+exports.legacyTxHash = legacyTxHash;
+exports.authorizeX402 = authorizeX402;
+exports.createX402Gate = createX402Gate;
+exports.withX402 = withX402;
+/** canonical Permit2（各链同址） */
+exports.PERMIT2_ADDRESS = '0x000000000022D473030F116dDEE9F6B43aC78BA3';
+/** canonical x402 exact over Permit2 代理（spender，资金只流向 witness.to） */
+exports.X402_EXACT_PERMIT2_PROXY = '0x402085c248EeA27D92E8b30b2C58ed07f9E20001';
+const KEY_HEADERS = ['authorization', 'x-api-key', 'x-service-key'];
+const DEFAULT_EXEMPT = ['/health', '/metrics'];
+// ── base64（Node 与 edge runtime 通用，不依赖 Buffer）───────────────────────
+function encodeBase64Json(obj) {
+    const json = JSON.stringify(obj);
+    const bytes = new TextEncoder().encode(json);
+    let binary = '';
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary);
+}
+function decodeBase64Json(input) {
+    const binary = atob(input);
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+/**
+ * 把「单 accept 简写」与「多 accept」统一展开。
+ * 有 `eip3009` 用 EIP-3009 extra；有 `permit2` 用 Permit2 extra；都没给则按 EIP-3009
+ * 无域输出（兼容老服务：只靠 `amount` 覆盖价格的场景）。
+ */
+function buildAccepts(opts, amount) {
+    if (opts.accepts?.length) {
+        return opts.accepts.map((a) => {
+            const target = a.payTo ?? opts.payTo;
+            if (!target)
+                throw new Error('x402 gate: payTo is required (top-level or per accept)');
+            const priced = a.amount ?? amount;
+            if (!priced)
+                throw new Error('x402 gate: every accept needs an `amount` (or a top-level amount)');
+            const base = {
+                scheme: 'exact',
+                network: a.network,
+                amount: priced,
+                asset: a.asset,
+                payTo: target,
+                maxTimeoutSeconds: a.maxTimeoutSeconds ?? 300,
+            };
+            if (a.permit2) {
+                const cfg = typeof a.permit2 === 'object' ? a.permit2 : {};
+                return {
+                    ...base,
+                    extra: {
+                        assetTransferMethod: 'permit2',
+                        permit2Address: cfg.address ?? exports.PERMIT2_ADDRESS,
+                        permit2Proxy: cfg.proxy ?? exports.X402_EXACT_PERMIT2_PROXY,
+                    },
+                };
+            }
+            const domain = a.eip3009 ?? opts.domain;
+            return domain ? { ...base, extra: { name: domain.name, version: domain.version } } : base;
+        });
+    }
+    if (!opts.payTo || !opts.network || !opts.asset) {
+        throw new Error('x402 gate: payTo / network / asset are required when `accepts` is not set');
+    }
+    return [
+        {
+            scheme: 'exact',
+            network: opts.network,
+            amount,
+            asset: opts.asset,
+            payTo: opts.payTo,
+            maxTimeoutSeconds: 300,
+            ...(opts.domain ? { extra: { name: opts.domain.name, version: opts.domain.version } } : {}),
+        },
+    ];
+}
+/** 402 挑战（标准 v2）——`resource` 带上服务元数据，`extensions.bazaar` 供 facilitator 索引。 */
+function buildChallenge(opts, url, amount, path) {
+    const challenge = {
+        x402Version: 2,
+        resource: { url, ...(opts.resource ?? {}) },
+        accepts: buildAccepts(opts, amount),
+    };
+    if (opts.bazaar)
+        challenge.extensions = { bazaar: opts.bazaar };
+    const purchase = typeof opts.purchaseUrl === 'function'
+        ? (path ? opts.purchaseUrl(path) : null)
+        : opts.purchaseUrl;
+    if (purchase) {
+        challenge.links = [{ rel: 'purchase', href: purchase, title: 'Buy a credit pack (cheaper per call)' }];
+    }
+    return challenge;
+}
+// ── x402 v1 兼容（B15.3）────────────────────────────────────────────────────
+// v1 客户端不会读 `PAYMENT-REQUIRED` 头，只看 402 响应体；并按短网络名匹配
+// （`base` 而非 `eip155:8453`）。因此响应体降级成 v1 结构，请求侧再接受 `X-PAYMENT`。
+const V1_NETWORK_NAMES = {
+    'eip155:1': 'ethereum',
+    'eip155:11155111': 'sepolia',
+    'eip155:8453': 'base',
+    'eip155:84532': 'base-sepolia',
+    'eip155:56': 'bsc',
+    'eip155:97': 'bsc-testnet',
+    'eip155:137': 'polygon',
+    'eip155:43114': 'avalanche',
+    'eip155:10': 'optimism',
+    'eip155:42161': 'arbitrum',
+};
+/** CAIP-2 → v1 短网络名；未知网络原样返回（v1 客户端自然不支持）。 */
+function toV1Network(network) {
+    return V1_NETWORK_NAMES[network] ?? network;
+}
+/**
+ * v2 挑战 → v1 `PaymentRequirementsResponse`（v1 把 resource/description/mimeType
+ * 放在每个 accept 内，金额字段叫 `maxAmountRequired`）。
+ */
+function toV1Challenge(challenge) {
+    const resource = challenge.resource;
+    return {
+        x402Version: 1,
+        ...(challenge.error ? { error: challenge.error } : {}),
+        accepts: challenge.accepts.map((a) => ({
+            scheme: a.scheme,
+            network: toV1Network(a.network),
+            maxAmountRequired: a.amount,
+            resource: resource.url,
+            ...(resource.description ? { description: resource.description } : {}),
+            mimeType: resource.mimeType ?? 'application/json',
+            payTo: a.payTo,
+            maxTimeoutSeconds: a.maxTimeoutSeconds,
+            asset: a.asset,
+            ...(a.extra ? { extra: a.extra } : {}),
+        })),
+    };
+}
+/** 读付款凭证：v2 的 `PAYMENT-SIGNATURE` 优先，回退 v1 的 `X-PAYMENT`。 */
+function paymentSignature(req) {
+    return (req.header('payment-signature') ?? req.header('x-payment'))?.trim() || undefined;
+}
+const quotaBuckets = new Map();
+/** 仅用于测试/运维：清空内存额度。 */
+function resetFreeQuota() {
+    quotaBuckets.clear();
+}
+function quotaWindowMs(q) {
+    if (q.windowMs && q.windowMs > 0)
+        return q.windowMs;
+    return q.period === 'month' ? 30 * 24 * 3_600_000 : 24 * 3_600_000;
+}
+function consumeFreeQuota(opts, req, now) {
+    const q = opts.freeQuota;
+    const ns = opts.resource?.serviceName ?? opts.payTo ?? opts.accepts?.[0]?.payTo ?? 'x402';
+    const caller = q.key ? q.key(req) : req.ip ?? 'anonymous';
+    const key = `${ns}\u0000${caller}`;
+    const win = quotaWindowMs(q);
+    const bucket = quotaBuckets.get(key);
+    if (!bucket || now - bucket.windowStart >= win) {
+        quotaBuckets.set(key, { count: 1, windowStart: now });
+        return { allowed: q.calls > 0, remaining: Math.max(0, q.calls - 1) };
+    }
+    if (bucket.count >= q.calls)
+        return { allowed: false, remaining: 0 };
+    bucket.count += 1;
+    return { allowed: true, remaining: Math.max(0, q.calls - bucket.count) };
+}
+/**
+ * Keel 轨（legacy verifyOnly）：客户端先广播转账，载荷里带 `txHash`。
+ * 这类请求走 `/x402/verify`（验链上凭证），而不是 `/x402/settle`（代广播）。
+ */
+function legacyTxHash(header) {
+    try {
+        const body = decodeBase64Json(header);
+        const txHash = body?.payload?.txHash;
+        return typeof txHash === 'string' && /^0x[0-9a-fA-F]{64}$/.test(txHash) ? txHash : null;
+    }
+    catch {
+        return null;
+    }
+}
+function hasPlatformCredential(req, extra) {
+    return [...KEY_HEADERS, ...extra].some((h) => {
+        const v = req.header(h);
+        return typeof v === 'string' && v.trim().length > 0;
+    });
+}
+/**
+ * 本次调用的价格（最小单位）。
+ * 优先级：`amountFor(path)` > 顶层 `amount` > 第一个带价格的 accept。
+ * 只配 `accepts`（多币种）而不写顶层 `amount` 是文档里的标准用法，必须从 accept 取价，
+ * 否则 `amount` 为 undefined 会命中下面的「不收费」分支，等于整站免费。
+ */
+function resolveAmount(opts) {
+    return opts.amount ?? opts.accepts?.find((a) => a.amount)?.amount;
+}
+/**
+ * 网关核心：返回「放行」或「402 挑战」，与框架无关。
+ * 结算失败一律 402（携带原因），避免把上游错误变成 500。
+ */
+async function authorizeX402(opts, req) {
+    const exempt = [...DEFAULT_EXEMPT, ...(opts.exempt ?? [])];
+    if (exempt.some((e) => req.path === e || req.path.startsWith(e)))
+        return { action: 'pass' };
+    if (hasPlatformCredential(req, opts.passthroughHeaders ?? []))
+        return { action: 'pass' };
+    const amount = opts.amountFor ? opts.amountFor(req.path) : resolveAmount(opts);
+    // `amountFor` 返回 null = 该路径明确免费；但「压根没配价格」必须报错，
+    // 不能静默放行（否则漏配一个 amount 就等于整站免费）。
+    if (amount === null)
+        return { action: 'pass' };
+    if (!amount)
+        throw new Error('x402 gate: no price configured (set `amount` or a priced accept)');
+    const signature = paymentSignature(req);
+    // 免费额度：只对「本来要收费、且没带付款凭证」的请求计数；已付款的正常走结算。
+    if (opts.freeQuota && !signature) {
+        const now = opts.freeQuota.now?.() ?? Date.now();
+        const quota = consumeFreeQuota(opts, req, now);
+        if (quota.allowed) {
+            return { action: 'pass', headers: { 'X-Free-Quota-Remaining': String(quota.remaining) } };
+        }
+    }
+    const challenge = buildChallenge(opts, req.url, amount, req.path);
+    const required = () => ({
+        'Content-Type': 'application/json',
+        'PAYMENT-REQUIRED': encodeBase64Json(challenge),
+    });
+    if (!signature) {
+        challenge.error = opts.freeQuota
+            ? 'free quota exhausted; payment signature is required (X-PAYMENT or PAYMENT-SIGNATURE)'
+            : 'payment signature is required (X-PAYMENT or PAYMENT-SIGNATURE)';
+        return { action: 'challenge', status: 402, headers: required(), body: toV1Challenge(challenge) };
+    }
+    const base = opts.paymentsUrl.replace(/\/+$/, '');
+    const txHash = legacyTxHash(signature);
+    try {
+        const resp = await fetch(`${base}${txHash ? '/x402/verify' : '/x402/settle'}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(opts.paymentsKey ? { Authorization: `Bearer ${opts.paymentsKey}` } : {}),
+            },
+            // 转发完整挑战：引擎按载荷在 `accepts[]` 中匹配（EIP-3009 / Permit2）。
+            body: JSON.stringify({ paymentPayload: signature, paymentRequirements: challenge }),
+            signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout
+                ? AbortSignal.timeout(opts.timeoutMs ?? 15_000)
+                : undefined,
+        });
+        const result = (await resp.json().catch(() => ({})));
+        // Keel 轨：交易已由客户端广播，验通过即放行；回执带客户端给的 txHash。
+        if (txHash) {
+            if (!resp.ok || result.isValid !== true) {
+                challenge.error = result.invalidReason || result.errorReason || result.message || `verification failed (${resp.status})`;
+                opts.log?.(`x402 gate: verify rejected ${req.path} → ${challenge.error}`);
+                return { action: 'challenge', status: 402, headers: required(), body: toV1Challenge(challenge) };
+            }
+            const receipt = {
+                success: true,
+                transaction: txHash,
+                network: result.network ?? challenge.accepts[0]?.network,
+                payer: result.payer,
+                amount,
+            };
+            return {
+                action: 'pass',
+                headers: {
+                    'PAYMENT-RESPONSE': encodeBase64Json(receipt),
+                    // v1 回执头：老客户端只读这个，network 用短名
+                    'X-PAYMENT-RESPONSE': encodeBase64Json({ ...receipt, network: toV1Network(receipt.network ?? '') }),
+                },
+            };
+        }
+        if (!resp.ok || !result.success) {
+            challenge.error = result.errorReason || result.invalidReason || result.message || `settlement failed (${resp.status})`;
+            opts.log?.(`x402 gate: settle rejected ${req.path} → ${challenge.error}`);
+            return { action: 'challenge', status: 402, headers: required(), body: toV1Challenge(challenge) };
+        }
+        const receipt = {
+            success: true,
+            transaction: result.transaction,
+            network: result.network,
+            payer: result.payer,
+            amount: result.amount ?? amount,
+        };
+        return {
+            action: 'pass',
+            headers: {
+                'PAYMENT-RESPONSE': encodeBase64Json(receipt),
+                // v1 回执头：老客户端只读这个，network 用短名
+                'X-PAYMENT-RESPONSE': encodeBase64Json({ ...receipt, network: toV1Network(receipt.network ?? '') }),
+            },
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'settlement unavailable';
+        opts.log?.(`x402 gate: settle error ${req.path} → ${message}`);
+        challenge.error = 'payment settlement unavailable, retry shortly';
+        return { action: 'challenge', status: 402, headers: required(), body: toV1Challenge(challenge) };
+    }
+}
+/** Express / Connect 适配器 */
+function createX402Gate(opts) {
+    return async function x402Gate(req, res, next) {
+        const path = req.path || '/';
+        const url = `${req.protocol || 'https'}://${req.get?.('host') || 'localhost'}${req.originalUrl || path}`;
+        const result = await authorizeX402(opts, {
+            path,
+            url,
+            ip: typeof req.ip === 'string' ? req.ip : undefined,
+            header: (name) => {
+                const v = req.headers?.[name];
+                return Array.isArray(v) ? v[0] ?? null : v ?? null;
+            },
+        });
+        if (result.action === 'pass') {
+            for (const [k, v] of Object.entries(result.headers ?? {}))
+                res.set(k, v);
+            next();
+            return;
+        }
+        for (const [k, v] of Object.entries(result.headers))
+            res.set(k, v);
+        res.status(result.status).json(result.body);
+    };
+}
+/**
+ * 包装一个 Fetch 处理器：未付款 → 402；已付款/有平台凭证 → 原处理器。
+ *
+ * ```ts
+ * // app/api/quote/route.ts
+ * export const GET = withX402(opts, async () => Response.json({ price: 42 }))
+ * ```
+ */
+function withX402(opts, handler) {
+    return async (request) => {
+        const url = request.url;
+        const parsed = new URL(url);
+        const result = await authorizeX402(opts, {
+            path: parsed.pathname,
+            url,
+            ip: request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || undefined,
+            header: (name) => request.headers.get(name),
+        });
+        if (result.action === 'pass') {
+            const response = await handler(request);
+            for (const [k, v] of Object.entries(result.headers ?? {}))
+                response.headers.set(k, v);
+            return response;
+        }
+        return new Response(JSON.stringify(result.body), {
+            status: result.status,
+            headers: result.headers,
+        });
+    };
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@keelcodes/x402-gate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Keel x402 v2 resource gate — Express / Fetch / Next.js adapters (no keys, no chain access)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "x402",
+    "payment",
+    "express",
+    "nextjs",
+    "fetch",
+    "agent"
+  ],
+  "license": "MIT",
+  "author": "Keel",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}