@keelcodes/x402-gate 0.1.1 → 0.1.3

package/README.md

@@ -53,7 +53,7 @@ export const GET = withX402(gateOptions, async () => Response.json({ price: 42 }
 | `paymentsUrl` | 支付引擎地址（自建或 `https://keel.codes/v1/payment`） |
 | `paymentsKey` | 支付引擎 Bearer key |
 | `payTo` | 收款地址（B 端自己的钱包；资金直达，不经平台） |
-| `amount` | 单次价格（最小单位）；也可用 `amountFor(path)` 动态定价 |
+| `amount` | 单次价格（最小单位）；也可用 `amountFor(path, req)` 动态定价（A7.9.3：`req.query` 可取 `limit` 做阶梯）。不填时从第一个带 `amount` 的 accept 取价（`0.1.1` 起；再没有就**直接报错**，不会静默免费放行） |
 | `accepts` | 多链多资产；每项二选一：`eip3009: { name, version }` 或 `permit2: true` |
 | `exempt` | 免费路径前缀（默认已含 `/health`、`/metrics`） |
 | `passthroughHeaders` | 额外视为「已有平台凭证」的头（如 `x-tenant-id`） |
@@ -100,12 +100,65 @@ const gate = createX402Gate({
 > `X-PAYMENT-RESPONSE`。`PAYMENT-REQUIRED` 头始终是 v2。
 
 ```ts
-const keel = new KeelClient({
-  x402: { address, signTypedData, signPermit2TypedData },
+import { Keel } from '@keelcodes/sdk'
+
+const keel = new Keel({
+  baseUrl: 'https://api.example', // 收费服务端（不是支付引擎）
+  x402: {
+    address: wallet.account.address, // viem WalletClient
+    signTypedData: (typed) => wallet.signTypedData(typed),
+    maxAmount: '2000', // 单笔上限（最小单位），超过直接拒付
+  },
 })
-await keel.get('https://api.example/quote') // 402 → 签名 → 重试 → 200
+await keel.request('GET', '/quote') // 402 → 签名 → 重试 → 200
+```
+
+### 可运行 demo（agent 自付，零资金）
+
+`projects/keel-sdk/examples/agent-autopay-demo.mjs` 把上面这条链路跑通，默认**全本地、离线、不上链**：
+
+```bash
+cd projects/x402-gate && npm run build
+cd ../keel-sdk && npm run build && node examples/agent-autopay-demo.mjs
+```
+
+输出依次覆盖：免费路径放行 → 未付款拿 `402`（v1 体 + v2 `PAYMENT-REQUIRED` 头 + `links`） →
+Keel 自动签名重试 `200` → 超出 `maxAmount` 时拒付。demo 内置 mock facilitator，
+只验 EIP-712 签名并回一个假 `transaction`，所以**不需要真钱包余额、也不需要 gas**。
+
+接真环境时换成真收款地址/真付款私钥/真支付引擎（此时不再起本地服务）：
+
+```bash
+PAYMENTS_URL=https://keel.codes/v1/payment \
+GATE_URL=https://your-service.example \
+PAYER_PRIVATE_KEY=0x... PAY_TO=0x... \
+node examples/agent-autopay-demo.mjs
+```
+
+demo 只演示 EIP-3009 轨（Base USDC）；BSC USDT/USDC 走 Permit2 时，同一份代码由 SDK
+自动改签 Permit2（`extra.assetTransferMethod=permit2`），首次使用需先按
+「Permit2 预算」授权一次（见下）。
+
+### Permit2 预算（授权上限）
+
+Permit2 轨下，付款人要先给 **canonical Permit2 合约**（不是 proxy）一笔 ERC-20 allowance，
+这笔额度就是链上硬上限；`approve` 是覆盖写，撤销 = `approve(Permit2, 0)`：
+
+```bash
+cd projects/payment/payments
+npx tsx scripts/permit2-budget.ts --chain bsc --budget 5        # dry-run，只打印 calldata
+npx tsx scripts/permit2-budget.ts --chain bsc --budget 5 --broadcast   # 真广播
+npx tsx scripts/permit2-budget.ts --chain bsc --revoke --broadcast     # 撤销
 ```
 
+### per-key / per-agent 预算（可选身份头）
+
+网关会把调用方的 `x-keel-key-id` / `x-keel-agent-id` 转发给支付引擎（裁剪 256 字符），
+引擎据此把消费记到 `key:<sha256 前 16 位>` 或 `agent:<小写 id>` 主体；两者都缺省时退回按付款方地址。
+运营可用 `GET/PUT /v1/payment/spend-policies[/:subject]` 为这些主体配置日限额、单次上限与收款方白名单。
+
+> 这两个头只应由**受信服务端**设置（例如你们自己的 API 网关），不要直接透传外部用户输入，否则调用方可伪造主体。
+
 ## 状态码
 
 | 场景 | 响应 |

package/dist/index.d.ts

@@ -121,8 +121,8 @@ export interface X402GateOptions {
     accepts?: X402GateAccept[];
     /** 命中这些路径前缀的请求不收费（探针/文档） */
     exempt?: string[];
-    /** 按请求覆盖价格（最小单位）；返回 null 表示不收费 */
-    amountFor?: (path: string) => string | null;
+    /** 按请求覆盖价格（最小单位）；返回 null 表示不收费。A7.9.3：第二参可读 query 做 limit 阶梯 */
+    amountFor?: (path: string, req: GateRequest) => string | null;
     /** 额外视为「已有平台凭证」的请求头（如 x-tenant-id） */
     passthroughHeaders?: string[];
     /** 资源元数据（写进 402 的 resource；B13.1 目录展示用） */
@@ -145,6 +145,8 @@ export interface GateRequest {
     path: string;
     url: string;
     header: (name: string) => string | null;
+    /** 查询串（A7.9.3：`amountFor` 按 `limit` 阶梯计价用） */
+    query?: URLSearchParams;
     /** 调用方地址（免费额度分桶用；缺省视为同一桶） */
     ip?: string;
 }

package/dist/index.js

@@ -209,9 +209,22 @@ function hasPlatformCredential(req, extra) {
         return typeof v === 'string' && v.trim().length > 0;
     });
 }
+/**
+ * B5.1：透传调用方身份头，供支付引擎按 `key:<hash>` / `agent:<id>` 做预算主体。
+ * 只转发这两个命名空间内的头，并裁剪长度。
+ */
+function identityHeaders(req) {
+    const out = {};
+    for (const name of ['x-keel-key-id', 'x-keel-agent-id']) {
+        const value = (req.header(name) ?? '').trim();
+        if (value)
+            out[name] = value.slice(0, 256);
+    }
+    return out;
+}
 /**
  * 本次调用的价格（最小单位）。
- * 优先级：`amountFor(path)` > 顶层 `amount` > 第一个带价格的 accept。
+ * 优先级：`amountFor(path, req)` > 顶层 `amount` > 第一个带价格的 accept。
  * 只配 `accepts`（多币种）而不写顶层 `amount` 是文档里的标准用法，必须从 accept 取价，
  * 否则 `amount` 为 undefined 会命中下面的「不收费」分支，等于整站免费。
  */
@@ -228,7 +241,7 @@ async function authorizeX402(opts, req) {
         return { action: 'pass' };
     if (hasPlatformCredential(req, opts.passthroughHeaders ?? []))
         return { action: 'pass' };
-    const amount = opts.amountFor ? opts.amountFor(req.path) : resolveAmount(opts);
+    const amount = opts.amountFor ? opts.amountFor(req.path, req) : resolveAmount(opts);
     // `amountFor` 返回 null = 该路径明确免费；但「压根没配价格」必须报错，
     // 不能静默放行（否则漏配一个 amount 就等于整站免费）。
     if (amount === null)
@@ -263,6 +276,7 @@ async function authorizeX402(opts, req) {
             headers: {
                 'Content-Type': 'application/json',
                 ...(opts.paymentsKey ? { Authorization: `Bearer ${opts.paymentsKey}` } : {}),
+                ...identityHeaders(req),
             },
             // 转发完整挑战：引擎按载荷在 `accepts[]` 中匹配（EIP-3009 / Permit2）。
             body: JSON.stringify({ paymentPayload: signature, paymentRequirements: challenge }),
@@ -362,6 +376,7 @@ function withX402(opts, handler) {
         const result = await authorizeX402(opts, {
             path: parsed.pathname,
             url,
+            query: parsed.searchParams,
             ip: request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || undefined,
             header: (name) => request.headers.get(name),
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keelcodes/x402-gate",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -8,7 +8,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist"