unified-keys 0.4.0 → 0.6.0

package/README.md

@@ -5,12 +5,22 @@
 ## 特性
 
 - ✅ **明文可重复显示**：list/get 返回完整明文（Unkey 只给前缀）
-- ✅ **完整使用记录**：每次 verify/refund/create/delete 写 usage_log（Unkey 无）
-- ✅ **verify 原子扣减**：`UPDATE ... WHERE credits>0 RETURNING`，并发安全
+- ✅ **完整使用记录**：每次 check/verify/refund/create/delete 写 usage_log（Unkey 无）
+- ✅ **check / verify 分离**：check 公开只读校验，verify 管理（带 rootKey）扣减
+- ✅ **原子扣减**：`UPDATE ... WHERE credits>0 RETURNING`，并发安全
 - ✅ **多 app 命名空间**：appId（slug）区分项目，首次创建 key 自动注册
 - ✅ **零依赖**：纯 fetch，Worker/Node/Next.js 通用
 - ✅ **TS 强类型**
 
+## 0.6.0 破坏性变更（安全修复）
+
+`autoDelete` 和 `decrement` 不再由 verify 调用方传参——以前公开 verify 接受这两个参数，任何拿到 key 明文的人都能删别人的 key 或白嫖额度。现在：
+
+- **`autoDelete`** 移到 `createKey`（预设为 key 属性），verify 扣减到 0 时按 key 自身策略删
+- **`POST /v1/keys/check`**（公开，无鉴权）：纯只读校验，不扣减、不删。探活 / 前端校验用这个
+- **`POST /v1/keys/verify`**（管理，需 `Bearer KEYS_ROOT_KEY`）：扣减 + autoDelete 读 key 属性
+- 顶层 `verifyKey()` 保留但 `@deprecated`，内部改调 check（只读）；扣减请用 `client.verifyKey()`
+
 ## 安装
 
 ```bash
@@ -20,67 +30,84 @@ pnpm add unified-keys
 ## 快速开始
 
 ```ts
-import { createClient, verifyKey } from "unified-keys";
+import { createClient, checkKey } from "unified-keys";
 
 const client = createClient({
   baseUrl: "https://keys.932324.xyz",
   rootKey: process.env.KEYS_ROOT_KEY,
 });
 
-// 创建 key（明文返回）
+// 创建 key（明文返回；autoDelete 预设为 key 属性）
 const { keys } = await client.createKey({
   appId: "my-app",
   credits: 5,
+  maxUses: 5,
+  autoDelete: "3d", // 用尽后 3 天软删（true 立即软删）
   externalId: "user-123",
   meta: { plan: "pro" },
 });
-console.log(keys[0].key); // 完整明文
 
-// 验证 + 扣减（用户持有 key）
-const result = await verifyKey(
-  { baseUrl: "https://keys.932324.xyz" },
-  { key: userKey, decrement: true, context: { username: "alice" } }
-);
+// 公开只读校验（无需 rootKey，不扣减）
+const r = await checkKey({ key: userKey, context: { ip: "1.2.3.4" } });
+
+// 扣减（需 rootKey，走 client）
+const v = await client.verifyKey({ key: userKey, context: { ip: "1.2.3.4" } });
 ```
 
 ## API
 
 ### `createClient({ baseUrl, rootKey })` → client
-管理客户端。`rootKey` 用于管理 API（verify 端点不需要）。
 
-### `client.createKey({ appId, prefix?, credits?, maxUses?, meta?, externalId?, expiresAt?, count? })`
-创建 key。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文。`appId` 首次自动注册。
+管理客户端。`rootKey` 用于管理 API（含 verify 扣减；check 公开不需要）。
+
+### `client.createKey({ appId, prefix?, length?, credits?, maxUses?, meta?, externalId?, expiresAt?, count?, autoDelete?, rateLimit?, autoBan? })`
+
+创建 key。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文。`appId` 首次自动注册。`length` 默认 8；**长期付费 key 传 16**。
+
+`autoDelete`（预设为 key 属性，verify 用尽时执行，不再由 verify 传参）：`true` 立即软删；`"3m"`/`"2h"`/`"3d"` 延迟软删（set deleteAt，Cron 每 10min 清理过期 key，保留记录供 admin 查）。
+
+### `checkKey({ key, context? })` / `client.checkKey(...)`
 
-### `verifyKey({ key, decrement?, autoDelete?, context? })`
-公开验证（无需 rootKey，baseUrl 内置默认）。`decrement: true` 扣减 + 写 verify log；`false` 只查。`autoDelete`：扣减后额度用尽（remaining=0）自动删——`true` 立即删；`"3m"`/`"2h"`/`"3d"` 延迟删（set deleteAt，Cron 每 10min 清理过期 key，保留记录供 admin 查看一段时间）。SDK 前置 `isValidKeyFormat` 校验，格式不对直接返回不查 DB。
-返回 `{ valid, found, keyId, remaining, maxUses, meta, externalId, appId, enabled, expiresAt, createdAt }`。
+公开只读校验（无需 rootKey，baseUrl 内置默认）。**不扣减、不删**，写 check log。返回 `{ valid, found, keyId, remaining, maxUses, meta, externalId, appId, ... }`。SDK 前置 `isValidKeyFormat` 校验。
+
+### `client.verifyKey({ key, context? })`
+
+管理扣减（需 rootKey）。原子扣减 1，写 verify log；扣到 0 时按 key 的 `autoDelete` 属性删除。返回同 check。`code`（valid=false 时）：`RATE_LIMITED`(429) / `KEY_PAUSED`、`KEY_BANNED`(423) / `KEY_DISABLED` / `KEY_EXPIRED` / `KEY_EXHAUSTED`。
 
 ### `client.listKeys({ appId, limit?, offset? })`
+
 列表，含完整明文。返回 `{ keys: KeyRecord[], total }`。
 
 ### `client.getKey(keyId)`
+
 详情（明文 + 最近 50 条 usage_logs）。
 
 ### `client.getKeyUsageLogs(keyId, { limit? })`
+
 使用记录。返回 `{ logs: UsageLog[] }`。
 
 ### `client.updateCredits(keyId, { operation, value, context? })`
+
 调整额度。`operation: "increment" | "decrement" | "set"`。increment 写 `refund` 事件。
 
 ### `client.updateKey(keyId, { meta?, enabled?, expiresAt? })`
+
 更新元数据/禁用。
 
 ### `client.deleteKey(keyId)` / `client.deleteKeys(keyIds)`
 
+soft delete（`_delete=true`，明文 + meta 永久保留可反查）。
+
 ## usage_log event 类型
 
 | event | 触发 | creditsBefore/After |
 |---|---|---|
-| `verify` | verify decrement:true 扣减 | ✅ |
+| `check` | check 端点 / verify 遇无限 key | — |
+| `verify` | verify 扣减 | ✅ |
 | `refund` | updateCredits increment | ✅ |
 | `create` | createKey | after = 初始额度 |
-| `delete` | deleteKey | — |
-| `update` | updateKey / updateCredits(decrement/set) | — |
+| `soft_delete` | deleteKey / autoDelete 用尽 | — |
+| `rate_limited` / `auto_pause` / `auto_ban` / `pause` / `unpause` / `ban` / `unban` / `update` | 对应操作 | — |
 
 ## License
 

package/SKILL.md

@@ -1,159 +1,201 @@
 ---
 name: unified-keys
-description: 当项目需要管理 API key（创建、验证扣减额度、查询使用记录、管理端显示明文、用尽自动删除）时使用。自建通用 key 服务 keys.932324.xyz，明文存储 + 完整使用记录，npm 包 unified-keys。
+description: 当项目需要管理 API key（创建、只读校验、扣减验证、查询使用记录、管理端显示明文、用尽自动软删、DO 限流、自动暂停/封禁、明文反查）时使用。自建通用 key 服务 keys.932324.xyz，明文存储 + 完整使用记录 + 永久痕迹，npm 包 unified-keys。check 公开只读 / verify 管理扣减分离。
 ---
 
 # unified-keys
 
-自建通用 API key 管理 SDK（替代 Unkey）。**明文存储 + 明文返回 + 完整使用记录 + 用尽自动删除**。服务跑在 Cloudflare Worker（`keys.932324.xyz`），数据存 D1。
+自建通用 API key 管理 SDK（替代 Unkey）。**明文存储 + 明文返回 + 完整使用记录 + soft delete 永久痕迹 + DO 滑动窗口限流 + 渐进式/直接自动封禁 + 反查**。服务跑在 Cloudflare Worker（`keys.932324.xyz`），数据存 D1。
+
+## 0.6.0 安全修复（check/verify 拆分）
+
+`autoDelete` 和 `decrement` 不再由 verify 调用方传——以前公开 verify 接受这俩参数，任何拿到 key 明文的人都能删别人的 key（`{key, decrement:true, autoDelete:true}`）或白嫖额度（`decrement:false`）。现在：
+
+- **`POST /v1/keys/check`**（公开，无鉴权）：纯只读校验，**不扣减、不删**。写 `check` event。探活 / 前端校验 / 只验证不扣减场景（如 shadcn-proxy）。
+- **`POST /v1/keys/verify`**（管理，需 `Bearer KEYS_ROOT_KEY`）：扣减 + autoDelete 读 key 属性。写 `verify` event。
+- **`autoDelete`** 在 createKey 时预设为 key 属性（`auto_delete` 列），verify 扣到 0 时执行；调用方不再传。
+- 顶层 `verifyKey()` 保留但 `@deprecated`，内部改调 check（只读）；扣减用 `client.verifyKey()`（带 rootKey）。
 
 ## 何时用
 
 - 项目要发 API key / 邀请码 / 访问凭证给用户
 - 需要 verify key + 原子扣减额度（credits）
-- 想看每个 key 的使用历史（谁、何时、扣了几次、退了几次）
+- 需要「只读校验 key 有效性」不扣减（前端探活、whoami）
+- 想看每个 key 的使用历史（谁、何时、扣了几次、退了几次、何时被软删/暂停/封禁）
 - 想在管理端显示**完整 key 明文**（Unkey 做不到，只给前缀）
-- 一次性 key 用完自动删（避免 DB 堆积无用 key）
-- 多项目共用一个 key 服务（appId 命名空间隔离）
+- **限流** / **自动封禁** / **永久痕迹（soft delete 反查）** / 多项目命名空间
 
 ## 安装
 
 ```bash
 pnpm add unified-keys
-# 或 npm i unified-keys
 ```
 
 ## 核心 API
 
-**baseUrl 内置默认**（`https://keys.932324.xyz`），无需传。
+baseUrl 内置默认（`https://keys.932324.xyz`），无需传。
 
 ```ts
-import { createClient, isValidKeyFormat, verifyKey } from "unified-keys";
+import { createClient, checkKey, isValidKeyFormat } from "unified-keys";
 
-// 管理客户端（需 rootKey；baseUrl 内置）
+// 管理客户端（需 rootKey，verify 扣减 + 管理 API 都要）
 const client = createClient({ rootKey: process.env.KEYS_ROOT_KEY });
 
-// 创建 key（明文返回；appId = 项目 slug，首次自动注册）
+// 创建 key（明文返回；appId 首次自动注册；autoDelete 预设为 key 属性）
 const { keys } = await client.createKey({
   appId: "my-app",
-  credits: 5,              // 初始剩余次数
-  maxUses: 5,              // 总额度（0 = 无限）
-  externalId: "user-123",  // 应用层关联业务实体（可选）
-  meta: { plan: "pro" },   // 任意元数据（可选）
-  count: 1,                // 批量创建数
-});
-// keys[0].key = 完整明文 `<prefix>_<8位base62>`
-
-// 验证 + 扣减（用户持有明文 key，服务端验证）
-const result = await verifyKey({
-  key: userKey,
-  decrement: true,         // 扣减（默认 true）
-  autoDelete: true,        // 扣减后用尽（remaining=0）自动删 key（一次性 key 用）
-  context: { username: "alice", ip: "1.2.3.4" },  // 写 usage_log
+  credits: 5,                 // 初始剩余次数
+  maxUses: 5,                 // 总额度（0 = 无限）
+  autoDelete: "3d",           // 用尽后延迟软删（true 立即软删；"3m"/"2h"/"3d" 延迟；不传=不删）
+  length: 8,                  // body 位数（默认 8；长期付费 key 用 16 防爆破）
+  prefix: "sk",               // 可选前缀，生成 `<prefix>_<body>`
+  externalId: "user-123",     // 应用层关联业务实体（可选）
+  meta: { plan: "pro" },      // 任意元数据（可选）
+  rateLimit: { max: 60, windowSec: 60 },  // 限流（max 不传 = 不限速）
+  autoBan: { threshold: 10, windowSec: 600, maxViolations: 3, durationSec: 3600 },
 });
-// { valid, found, keyId, remaining, maxUses, meta, externalId, appId, enabled, expiresAt, createdAt }
-// found=false: key 不存在；valid=false found=true: 存在但禁用/过期/额度耗尽
 
-// 列表（含完整明文 ★ 区别于 Unkey）
-const { keys: all, total } = await client.listKeys({ appId: "my-app", limit: 200 });
+// 公开只读校验（无需 rootKey，不扣减不删）—— 探活 / 前端校验 / shadcn-proxy
+const c = await checkKey({ key: userKey, context: { ip: "1.2.3.4" } });
+// 或 client.checkKey({...})（client 不需要 rootKey 也能 check，但通常已有 client）
 
-// 详情（明文 + 使用记录）
-const { key, usageLogs } = await client.getKey(keyId);
+// 扣减（需 rootKey，走 client）—— 真正消费额度
+const r = await client.verifyKey({ key: userKey, context: { ip: "1.2.3.4" } });
+// 返回: { valid, found, keyId, remaining, maxUses, meta, appId, banStatus,
+//        ratelimited?, code?, resetIn? }
+// code（valid=false 时）: RATE_LIMITED(429) / KEY_PAUSED(423) / KEY_BANNED(423)
+//                         / KEY_DISABLED / KEY_EXPIRED / KEY_EXHAUSTED
 
-// 查使用记录（核心特性）
-const { logs } = await client.getKeyUsageLogs(keyId, { limit: 50 });
-// logs: [{ event: "verify"|"refund"|"create"|"delete"|"update"|"disable", creditsBefore, creditsAfter, context, createdAt }]
+// 反查明文 key → keyId + 历史（★ 含已软删的 key，排查注册用户用）
+const { found, key, recentLogs } = await client.lookupKey({ plaintext: "sk_xxx" });
 
-// 调整额度（refund 恢复）
-await client.updateCredits(keyId, {
-  operation: "increment",  // increment | decrement | set
-  value: 1,
-  context: { reason: "refund" },
-});
+// 列表（含明文）/ 详情 / 使用记录
+const { keys: all, total } = await client.listKeys({ appId: "my-app", limit: 200 });
+const { key, usageLogs } = await client.getKey(keyId);
 
-// 更新元数据 / 禁用
+// 调整额度（refund 恢复）/ 更新元数据
+await client.updateCredits(keyId, { operation: "increment", value: 1 });
 await client.updateKey(keyId, { meta: { plan: "enterprise" }, enabled: false });
 
-// 删除
+// 删除（soft delete：_delete=true，明文 + meta 永久保留可反查）
 await client.deleteKey(keyId);
-await client.deleteKeys([keyId1, keyId2]);
 
-// 手输校验（isValidKeyFormat 库内置，与 verify 前置校验同源）
+// 手动管控
+await client.pauseKey(keyId, { durationSec: 3600, reason: "manual" });
+await client.banKey(keyId, { reason: "abuse" });
+
+// 手输校验
 if (!isValidKeyFormat(inputKey)) return invalid();
 ```
 
+## check vs verify（0.6.0 起拆分）
+
+| | `checkKey` | `client.verifyKey` |
+|---|---|---|
+| 鉴权 | 公开（无需 rootKey） | 管理（需 rootKey） |
+| 扣减 | ❌ 不扣 | ✅ 原子扣减 1 |
+| autoDelete | ❌ 不删 | ✅ 扣到 0 按 key.autoDelete 删 |
+| event | `check` | `verify`（无限 key 也写 `check`） |
+| 场景 | 探活 / 前端校验 / shadcn-proxy | 真正消费额度（notify-me/github-inviter/user-dashboard 兑换） |
+
+**`autoDelete`（createKey 预设，verify 执行）**：`true` 立即 soft delete；`"3m"`/`"2h"`/`"3d"` 延迟（set deleteAt，Cron 每 10min 清理）；不传 = 不删（无限 key / 长期 key）。
+
+**返回 `code`**（valid=false 时）：`RATE_LIMITED`(429) / `KEY_PAUSED`、`KEY_BANNED`(423) / `KEY_DISABLED` / `KEY_EXPIRED` / `KEY_EXHAUSTED`。
+
+**SDK 对 429/423 不 throw**（业务码，body 含 valid/code/ratelimited），返回 body 让调用方读：
+```ts
+const r = await client.verifyKey({ key });
+if (r.ratelimited || r.code === "RATE_LIMITED") return res.status(429).json({ error: "请求过于频繁" });
+if (r.code === "KEY_PAUSED" || r.code === "KEY_BANNED") return res.status(423).json({ error: "Key 已暂停/封禁" });
+if (!r.valid) return res.status(403).json({ error: "Key 无效" });
+```
+
 ## 特性（区别于 Unkey）
 
 | | unified-keys | Unkey |
 |---|---|---|
-| 明文显示 | ✅ 列表/详情返回完整明文 | ❌ 只给前缀 |
-| 使用记录 | ✅ 每次 verify/refund/create/delete 写 usage_log | ❌ 只给当前 remaining |
+| 明文显示 | ✅ 列表/详情/反查返回完整明文 | ❌ 只给前缀 |
+| 使用记录 | ✅ 每次 check/verify/refund/create/soft_delete/rate_limited/pause/ban 写 log | ❌ 只给 remaining |
 | verify 延迟 | <5ms（D1 binding 零网络跳） | 50-100ms（公网） |
-| 用尽自动删 | ✅ verify `autoDelete` 选项 | ❌ |
-| 前置格式校验 | ✅ SDK `isValidKeyFormat`，格式不对不查 DB | ❌ |
-| 自托管 | ✅ 自己的 D1 | ❌ SaaS |
-| 原子扣减 | ✅ `UPDATE ... WHERE credits>0 RETURNING` | ✅ |
+| check/verify 拆分 | ✅ 公开只读 vs 管理扣减（避免滥用） | ❌ 单端点 |
+| 用尽自动删 | ✅ autoDelete（createKey 预设，立即 / 延迟软删） | ❌ |
+| **永久痕迹** | ✅ soft delete（`_delete=true`），明文 + meta 永久可反查 | ❌ 真删丢痕迹 |
+| **限流** | ✅ Durable Object 滑动窗口 | ❌ |
+| **自动封禁** | ✅ 渐进式 / 直接 | ❌ |
+| **反查** | ✅ 明文 → keyId + 历史（含已软删） | ❌ |
+| 前置格式校验 | ✅ SDK isValidKeyFormat | ❌ |
 
-## verify 选项
+## 自动封禁（autoBan）
 
-| 选项 | 默认 | 说明 |
-|---|---|---|
-| `decrement` | true | true 扣减 + 写 verify log；false 只查 |
-| `autoDelete` | false | 扣减后 remaining=0 自动删：`true` 立即删；`"3m"`/`"2h"`/`"3d"` 延迟删（set deleteAt，Cron 每 10min 清理过期 key，保留记录供 admin 查看一段时间） |
-| `context` | - | 写入 usage_log（{username, ip, source, ...}） |
+两种模式，按 `mode` 选择：
+
+**渐进式**（默认，`mode: "progressive"`）：违规累计，达 maxViolations 永久 ban，前 N-1 次 pause。
+```jsonc
+{ "threshold": 10, "windowSec": 600, "maxViolations": 3, "durationSec": 3600 }
+```
 
-**SDK 前置校验**：verify 前先 `isValidKeyFormat(key)`，格式不对直接返回 `{valid:false, found:false}`，不查 DB（省时间）。应用也可单独用 `isValidKeyFormat` 做手输校验。
+**直接**（`mode: "direct"`）：单次达阈值即 action（不累计违规计数）。
+```jsonc
+{ "mode": "direct", "action": "ban", "threshold": 10, "windowSec": 600 }       // 一次违规永久 ban
+{ "mode": "direct", "action": "pause", "threshold": 10, "durationSec": 3600 }  // 一次违规 pause
+```
+
+`unban` 重置违规计数；`unpause` 不重置。
 
 ## event 类型（usage_log）
 
-- `verify`：verify 扣减（含 creditsBefore/After + context）
-- `refund`：updateCredits increment 恢复额度
-- `create` / `delete`（含 autoDelete 触发的 exhausted_autodelete）/ `update` / `disable`
+`check`（只读探活 / verify 遇无限 key）/ `verify`（扣减）/ `refund`（恢复额度）/ `create` / `soft_delete`（含 autoDelete 触发的）/ `rate_limited` / `auto_pause` / `auto_ban` / `pause` / `unpause` / `ban` / `unban` / `update`。
 
 ## 集成示例
 
-### Next.js Route Handler（服务端 verify + 一次性 key 用尽自动删）
+### Next.js Route Handler（扣减，带 rootKey 走 client）
 ```ts
-import { verifyKey } from "unified-keys";
+import { createClient } from "unified-keys";
+const client = createClient({ rootKey: process.env.KEYS_ROOT_KEY });
 export async function POST(req: Request) {
   const { key } = await req.json();
-  const r = await verifyKey({
-    key,
-    decrement: true,
-    autoDelete: true,   // 用完自动删
-    context: { ip: req.headers.get("x-forwarded-for") },
-  });
-  if (!r.valid) return Response.json({ error: "invalid key" }, { status: 403 });
+  const r = await client.verifyKey({ key, context: { ip: req.headers.get("x-forwarded-for") } });
+  if (r.ratelimited || r.code === "RATE_LIMITED") return Response.json({ error: "请求过于频繁" }, { status: 429 });
+  if (r.code === "KEY_PAUSED" || r.code === "KEY_BANNED") return Response.json({ error: "Key 已暂停/封禁" }, { status: 423 });
+  if (!r.valid) return Response.json({ error: "Key 无效或已使用" }, { status: 403 });
   // ... 授权逻辑
 }
 ```
 
-### Next.js Server Component（只读查询，不扣减）
+### 公开只读校验（探活 / whoami，无需 rootKey）
 ```ts
-import { verifyKey } from "unified-keys";
-const info = await verifyKey({ key: params.key, decrement: false });
-if (!info.found || !info.valid) notFound();
-// info.remaining / info.meta / info.expiresAt
+import { checkKey } from "unified-keys";
+const r = await checkKey({ key });  // 不扣减，前端可直调
 ```
 
-### Cloudflare Worker（管理端）
+### admin 反查（明文 key → 注册用户）
 ```ts
-import { createClient } from "unified-keys";
-const client = createClient({ rootKey: c.env.KEY_SERVICE_ROOT_KEY });
-await client.createKey({ appId: "my-app", credits: 1 });
+const { found, key, recentLogs } = await client.lookupKey({ plaintext: "sk_xxx" });
 ```
 
 ## 服务端点
 
-- **公开 verify**：`POST https://keys.932324.xyz/v1/keys/verify`（无需鉴权，任何持有 key 的人可调）
-- **管理 API**：`https://keys.932324.xyz/v1/*`（需 `Authorization: Bearer <ROOT_KEY>`）
-- 健康检查：`GET https://keys.932324.xyz/v1/health`
+- **公开 check**：`POST https://keys.932324.xyz/v1/keys/check`（无鉴权，只读校验，不扣不删）
+- **管理 verify**：`POST /v1/keys/verify`（需 `Bearer KEYS_ROOT_KEY`，扣减 + autoDelete 读 key 属性）
+- **管理 API**：`/v1/*`（createKey/list/get/credits/update/delete/lookup/pause/ban 等，需 rootKey）
+- **反查**：`POST /v1/keys/lookup` `{plaintext}`
+- 健康检查：`GET /v1/health`
 
-ROOT_KEY 联系服务管理员获取。
+ROOT_KEY 联系服务管理员获取（本项目在 `packages/infra/.env` 的 `KEYS_ROOT_KEY`；4 应用共用）。
 
 ## 实现位置（本项目内）
 
-- 服务端：`apps/key-service`（Hono Worker → keys.932324.xyz）
-- SDK：`packages/keys`（npm `unified-keys`）
-- schema：`packages/db/src/schemas/key-service.ts`（key_apps / key_records / key_usage_logs）
-- 4 应用全迁移：github-inviter / user-dashboard / notify-me 完整迁移；shadcn-proxy 新用新服务 + Unkey 格式路由 fallback（旧 key 保持可用）
+- 服务端：`apps/key-service`（Hono Worker → keys.932324.xyz；D1 binding `KEY_SERVICE_DB` + Durable Object `RATE_LIMITER`）
+- SDK：`packages/keys`（npm `unified-keys@0.6.0`，monorepo workspace 直接用 src）
+- schema：`packages/db/src/schemas/key-service.ts`
+  - `key_records`：含 `auto_delete`(用尽策略) / `_delete`(soft delete) / `rate_limit_*` / `ban_*`+`paused_until`+`auto_ban_count` / `delete_at`(延迟软删触发时间)
+  - `key_usage_logs`：完整事件流（含 keyId 外键，soft delete 不级联删）
+- migrations：`packages/infra/migrations/keys/0001` ~ `0005`（0005 加 auto_delete 列 + 按 appId 回填；alchemy deploy 自动跑）
+
+## 注意事项
+
+- **SDK 429/423 不 throw**：check/verify 限流/封禁时返回 429/423 + JSON body，SDK 不抛异常，调用方读 result.code/result.ratelimited。
+- **check/verify 必须分清**：探活用 check（公开，不扣），消费额度用 verify（管理，扣）。verify 需 rootKey，公开侧（浏览器/无 rootKey 的服务）只能 check。
+- **autoDelete 是 key 属性**：createKey 时预设，verify 扣到 0 自动执行；调用方无法通过 verify 传参删别人的 key（0.6.0 安全修复）。
+- **soft delete 不丢痕迹**：deleteKey/autoDelete 只 set `_delete=true`，明文 + meta + usage_logs 永久保留，lookup 可反查。
+- **D1 datetime 拼接**：服务端 `datetime('now', '+N seconds')` 必须用 `sql.raw(String(N))`，不能 `${N}` 参数化。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unified-keys",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "自建通用 API key 管理 SDK（明文存储 + 明文返回 + 完整使用记录），调用 keys.932324.xyz 服务",
   "type": "module",
   "main": "./src/index.ts",

package/src/client.ts

@@ -1,5 +1,8 @@
 import type {
+	BanInput,
 	BatchDeleteResult,
+	CheckInput,
+	CheckResult,
 	CreateAppInput,
 	CreateAppResult,
 	CreateKeyInput,
@@ -12,6 +15,10 @@ import type {
 	ListAppsResult,
 	ListKeysInput,
 	ListKeysResult,
+	LookupInput,
+	LookupResult,
+	PauseInput,
+	PauseResult,
 	UpdateCreditsInput,
 	UpdateCreditsResult,
 	UpdateKeyInput,
@@ -65,7 +72,8 @@ export function createClient(config: KeyServiceClientConfig): KeyServiceClient {
 				`unified-keys ${method} ${path}: ${res.status} ${text.slice(0, 200)}`
 			);
 		}
-		if (!res.ok) {
+		// 429/423 是 verify 端点的业务码（限流/封禁，body 含 valid/code），返回 body 让调用方读，不 throw
+		if (!res.ok && res.status !== 429 && res.status !== 423) {
 			const msg = (data as { error?: string }).error ?? `${res.status}`;
 			throw new Error(`unified-keys ${method} ${path}: ${msg}`);
 		}
@@ -107,26 +115,50 @@ export function createClient(config: KeyServiceClientConfig): KeyServiceClient {
 				`/v1/keys/${keyId}/usage-logs?limit=${limit}`
 			);
 		},
+		checkKey: (input: CheckInput) => {
+			if (!isValidKeyFormat(input.key)) {
+				return Promise.resolve({ valid: false, found: false } as CheckResult);
+			}
+			return request<CheckResult>("POST", "/v1/keys/check", {
+				body: input,
+				auth: false,
+			});
+		},
 		verifyKey: (input: VerifyInput) => {
 			if (!isValidKeyFormat(input.key)) {
 				return Promise.resolve({ valid: false, found: false } as VerifyResult);
 			}
+			// verify 改为管理端点（需 rootKey，扣减 + autoDelete 读 key 属性）
 			return request<VerifyResult>("POST", "/v1/keys/verify", {
 				body: input,
-				auth: false,
+				auth: true,
 			});
 		},
+		lookupKey: (input: LookupInput) =>
+			request<LookupResult>("POST", "/v1/keys/lookup", { body: input }),
+		pauseKey: (keyId: string, input?: PauseInput) =>
+			request<PauseResult>("POST", `/v1/keys/${keyId}/pause`, {
+				body: input ?? {},
+			}),
+		unpauseKey: (keyId: string) =>
+			request<DeleteResult>("POST", `/v1/keys/${keyId}/unpause`, { body: {} }),
+		banKey: (keyId: string, input?: BanInput) =>
+			request<DeleteResult>("POST", `/v1/keys/${keyId}/ban`, {
+				body: input ?? {},
+			}),
+		unbanKey: (keyId: string) =>
+			request<DeleteResult>("POST", `/v1/keys/${keyId}/unban`, { body: {} }),
 	};
 }
 
 /**
- * 公开 verify 端点，无需 rootKey，baseUrl 内置默认。
- * 适合「用户持有明文 key、服务端验证并扣减」的场景。
+ * 公开 check 端点（只读校验），无需 rootKey，baseUrl 内置默认。
+ * 不扣减、不删；适合「探活 / 前端校验 key 有效性 / 只验证不扣减」场景。
  */
-export async function verifyKey(input: VerifyInput): Promise<VerifyResult> {
+export async function checkKey(input: CheckInput): Promise<CheckResult> {
 	if (!isValidKeyFormat(input.key)) return { valid: false, found: false };
 	const baseUrl = DEFAULT_BASE_URL;
-	const res = await fetch(`${baseUrl}/v1/keys/verify`, {
+	const res = await fetch(`${baseUrl}/v1/keys/check`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify(input),
@@ -136,11 +168,20 @@ export async function verifyKey(input: VerifyInput): Promise<VerifyResult> {
 	try {
 		data = text ? JSON.parse(text) : {};
 	} catch {
-		throw new Error(`unified-keys verify: ${res.status} ${text.slice(0, 200)}`);
+		throw new Error(`unified-keys check: ${res.status} ${text.slice(0, 200)}`);
 	}
-	if (!res.ok) {
+	if (!res.ok && res.status !== 429 && res.status !== 423) {
 		const msg = (data as { error?: string }).error ?? `${res.status}`;
-		throw new Error(`unified-keys verify: ${msg}`);
+		throw new Error(`unified-keys check: ${msg}`);
 	}
-	return data as VerifyResult;
+	return data as CheckResult;
+}
+
+/**
+ * @deprecated 0.6.0 起 verify 改为管理端点（需 rootKey），公开场景请用 `checkKey`（只读）。
+ * 此函数保留向后兼容，内部改为调公开 check 端点（行为：只读校验，不扣减）。
+ * 扣减请用 `client.verifyKey`（`createClient({ rootKey })`）。
+ */
+export async function verifyKey(input: VerifyInput): Promise<VerifyResult> {
+	return checkKey(input);
 }

package/src/index.ts

@@ -1,7 +1,11 @@
-export { createClient, isValidKeyFormat, verifyKey } from "./client";
+export { checkKey, createClient, isValidKeyFormat, verifyKey } from "./client";
 export type {
 	AppRecord,
+	AutoBanConfig,
+	BanInput,
 	BatchDeleteResult,
+	CheckInput,
+	CheckResult,
 	CreateAppInput,
 	CreateAppResult,
 	CreatedKey,
@@ -16,11 +20,17 @@ export type {
 	ListAppsResult,
 	ListKeysInput,
 	ListKeysResult,
+	LookupInput,
+	LookupResult,
+	PauseInput,
+	PauseResult,
+	RateLimitConfig,
 	UpdateCreditsInput,
 	UpdateCreditsResult,
 	UpdateKeyInput,
 	UsageLog,
 	UsageLogsResult,
+	VerifyErrorCode,
 	VerifyInput,
 	VerifyResult,
 } from "./types";

package/src/types.ts

@@ -27,8 +27,39 @@ export interface ListAppsResult {
 	apps: AppRecord[];
 }
 
+/** 限流配置（max 配置后启用 RateLimiterDO 滑动窗口限流）*/
+export interface RateLimitConfig {
+	/** 窗口内最大请求数 */
+	max: number;
+	/** 窗口秒数，默认 60 */
+	windowSec?: number;
+}
+
+/** 自动封禁配置（meta.autoBan）*/
+export interface AutoBanConfig {
+	/** direct: 单次触发动作（pause/ban，默认 pause）*/
+	action?: "pause" | "ban";
+	/** pause 持续秒数，默认 3600（1h）*/
+	durationSec?: number;
+	/** progressive: 违规达此数 → 永久 ban（默认 3）；前 N-1 次 pause */
+	maxViolations?: number;
+	/** 模式：progressive（渐进式，默认）/ direct（直接，单次达阈值即 action）*/
+	mode?: "progressive" | "direct";
+	/** 触发阈值（窗口内 rate_limited 次数 = 一次违规）*/
+	threshold: number;
+	/** 统计窗口秒数，默认 600（10min）*/
+	windowSec?: number;
+}
+
 export interface CreateKeyInput {
 	appId: string;
+	/** 自动封禁配置（存 meta.autoBan）*/
+	autoBan?: AutoBanConfig;
+	/**
+	 * autoDelete（createKey 时预设为 key 属性，verify 扣减到 0 时执行；verify 端点不再接受调用方传参）：
+	 *   true / "now" → 立即 soft delete；"3m" / "2h" / "3d" → set deleteAt，Cron 软删（保留记录供 admin 查一段时间）
+	 */
+	autoDelete?: boolean | string;
 	/** 批量创建数量，默认 1 */
 	count?: number;
 	/** 初始额度（剩余次数），默认 1 */
@@ -37,12 +68,20 @@ export interface CreateKeyInput {
 	expiresAt?: string;
 	/** 应用层关联业务实体（如 github-inviter 的 configSlug） */
 	externalId?: string;
+	/** key body 长度（base62 位数），默认 8；长期付费 key 建议 16（防爆破） */
+	length?: number;
 	/** 总额度（0=无限），默认等于 credits */
 	maxUses?: number;
-	/** 应用层任意元数据 */
+	/** 应用层任意元数据（count 个 key 共享） */
 	meta?: Record<string, unknown>;
+	/**
+	 * 批量创建时每个 key 的独立 meta（长度须 = count）；不传则 count 个 key 共享 `meta`。
+	 */
+	metas?: Record<string, unknown>[];
 	/** 可选前缀，生成 `<prefix>_<rand>`；不传则纯 random */
 	prefix?: string;
+	/** 限流配置（max 配置后启用滑动窗口限流）*/
+	rateLimit?: RateLimitConfig;
 }
 
 export interface CreatedKey {
@@ -57,16 +96,25 @@ export interface CreateKeyResult {
 
 export interface KeyRecord {
 	appId: string;
+	/** autoDelete 策略（createKey 预设，verify 只读）：null=不删 | "true"=用尽立即软删 | "3m"/"2h"/"3d"=延迟软删 */
+	autoDelete: string | null;
+	banReason: string | null;
+	banStatus: "active" | "paused" | "banned";
 	createdAt: string;
 	creditsRemaining: number;
+	/** soft delete 标志（true=已软删，verify/list 过滤但 admin 可查）*/
+	deleted: boolean;
 	enabled: boolean;
 	expiresAt: string | null;
 	externalId: string | null;
 	keyId: string;
 	maxUses: number;
 	meta: Record<string, unknown> | null;
+	pausedUntil: string | null;
 	plaintext: string;
 	prefix: string | null;
+	rateLimitMax: number | null;
+	rateLimitWindowSec: number | null;
 	updatedAt: string;
 }
 
@@ -104,7 +152,7 @@ export interface UsageLog {
 	createdAt: string;
 	creditsAfter: number | null;
 	creditsBefore: number | null;
-	/** verify(扣减) / refund(恢复) / create / delete / update / disable */
+	/** check(只读) / verify(扣减) / refund / create / soft_delete / rate_limited / auto_pause / auto_ban / pause / unpause / ban / unban / update */
 	event: string;
 	id: string;
 	keyId: string;
@@ -124,31 +172,52 @@ export interface GetKeyResult {
 }
 
 export interface VerifyInput {
-	/**
-	 * 扣减后额度用尽（remaining=0）自动删除：true 立即删；
-	 * "3m"/"2h"/"3d" 等延迟删（set deleteAt，Cron 定期清理，保留记录一段时间）
-	 */
-	autoDelete?: boolean | string;
 	/** 上下文，写入 usage_log（如 {username, source, ip}） */
 	context?: Record<string, unknown>;
-	/** 默认 true；false 时只查不扣（写 verify log 但不扣减） */
-	decrement?: boolean;
 	/** 完整明文 key */
 	key: string;
 }
 
+/** 公开 check（只读校验）入参。check 不扣减、不删，无需 rootKey。 */
+export interface CheckInput {
+	/** 上下文，写入 usage_log */
+	context?: Record<string, unknown>;
+	/** 完整明文 key */
+	key: string;
+}
+
+/** check 结果（结构与 VerifyResult 相同）。 */
+export type CheckResult = VerifyResult;
+
+/** verify 失败码 */
+export type VerifyErrorCode =
+	| "RATE_LIMITED"
+	| "KEY_PAUSED"
+	| "KEY_BANNED"
+	| "KEY_DISABLED"
+	| "KEY_EXPIRED"
+	| "KEY_EXHAUSTED";
+
 export interface VerifyResult {
 	appId?: string;
+	banStatus?: "active" | "paused" | "banned";
+	/** 失败码（valid=false 时）*/
+	code?: VerifyErrorCode;
 	createdAt?: string;
 	enabled?: boolean;
+	error?: string;
 	expiresAt?: string | null;
 	externalId?: string | null;
-	/** key 是否存在（区别「不存在」与「存在但额度耗尽」） */
+	/** key 是否存在（区别「不存在」与「存在但额度耗尽/封禁」）*/
 	found: boolean;
 	keyId?: string;
 	maxUses?: number;
 	meta?: Record<string, unknown> | null;
+	/** 是否触发限流（429）*/
+	ratelimited?: boolean;
 	remaining?: number;
+	/** 限流/暂停重置剩余秒数 */
+	resetIn?: number;
 	valid: boolean;
 }
 
@@ -161,7 +230,37 @@ export interface BatchDeleteResult {
 	failed: string[];
 }
 
+// ===== lookup / pause / ban =====
+
+export interface LookupInput {
+	plaintext: string;
+}
+
+export interface LookupResult {
+	found: boolean;
+	key?: KeyRecord;
+	recentLogs?: UsageLog[];
+}
+
+export interface PauseInput {
+	/** 暂停秒数，默认 3600（1h）*/
+	durationSec?: number;
+	reason?: string;
+}
+
+export interface PauseResult {
+	pausedUntil: string | null;
+	success: boolean;
+}
+
+export interface BanInput {
+	reason?: string;
+}
+
 export interface KeyServiceClient {
+	banKey(keyId: string, input?: BanInput): Promise<DeleteResult>;
+	/** 公开 check（只读校验，不扣减不删，无需 rootKey）。 */
+	checkKey(input: CheckInput): Promise<CheckResult>;
 	createApp(input: CreateAppInput): Promise<CreateAppResult>;
 	createKey(input: CreateKeyInput): Promise<CreateKeyResult>;
 	deleteKey(keyId: string): Promise<DeleteResult>;
@@ -173,6 +272,10 @@ export interface KeyServiceClient {
 	): Promise<UsageLogsResult>;
 	listApps(): Promise<ListAppsResult>;
 	listKeys(input: ListKeysInput): Promise<ListKeysResult>;
+	lookupKey(input: LookupInput): Promise<LookupResult>;
+	pauseKey(keyId: string, input?: PauseInput): Promise<PauseResult>;
+	unbanKey(keyId: string): Promise<DeleteResult>;
+	unpauseKey(keyId: string): Promise<DeleteResult>;
 	updateCredits(
 		keyId: string,
 		input: UpdateCreditsInput