unified-keys 0.5.0 → 0.7.0

package/README.md

@@ -5,11 +5,13 @@
 ## 特性
 
 - ✅ **明文可重复显示**：list/get 返回完整明文（Unkey 只给前缀）
-- ✅ **完整使用记录**：每次 verify/refund/create/delete 写 usage_log（Unkey 无）
-- ✅ **verify 原子扣减**：`UPDATE ... WHERE credits>0 RETURNING`，并发安全
+- ✅ **完整使用记录**：每次 check/verify/refund/create/delete 写 usage_log
+- ✅ **check/verify 分离**：check 公开只读校验，verify 管理（带 rootKey）扣减
+- ✅ **client 绑定 appId**：createClient 时指定 appId，createKey/listKeys 自动绑定，无需每次传
+- ✅ **原子扣减**：`UPDATE ... WHERE credits>0 RETURNING`，并发安全
 - ✅ **多 app 命名空间**：appId（slug）区分项目，首次创建 key 自动注册
-- ✅ **零依赖**：纯 fetch，Worker/Node/Next.js 通用
-- ✅ **TS 强类型**
+- ✅ **零依赖**：纯 fetch，Worker/Node/Next.js 通用 + TS 强类型
+- ✅ **baseUrl 内置**：服务端点已内置，无需配置
 
 ## 安装
 
@@ -20,67 +22,72 @@ 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",
+  appId: "my-app", // 绑定应用命名空间（createKey/listKeys 自动用）
   rootKey: process.env.KEYS_ROOT_KEY,
 });
 
-// 创建 key（明文返回）
+// 创建 key（明文返回；autoDelete 预设为 key 属性）
 const { keys } = await client.createKey({
-  appId: "my-app",
   credits: 5,
+  maxUses: 5,
+  autoDelete: "3d", // 用尽后延迟软删
   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" } });
+
+// 扣减（client 带 rootKey）
+const v = await client.verifyKey({ key: userKey, context: { ip: "1.2.3.4" } });
 ```
 
 ## API
 
-### `createClient({ baseUrl, rootKey })` → client
-管理客户端。`rootKey` 用于管理 API（verify 端点不需要）。
+### `createClient({ appId, rootKey, baseUrl? })` → client
+
+管理客户端。`appId` 绑定应用命名空间（createKey/listKeys 自动用，无需每次传）；`rootKey` 用于管理 API + verify 扣减（必传）；`baseUrl` 内置默认，仅在指向自建/测试实例时传。
+
+### `client.createKey({ prefix?, length?, credits?, maxUses?, meta?, externalId?, expiresAt?, count?, autoDelete?, rateLimit?, autoBan? })`
+
+创建 key（自动绑定 client.appId）。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文。`length` 默认 8；**长期付费 key 传 16**。
 
-### `client.createKey({ appId, prefix?, length?, credits?, maxUses?, meta?, externalId?, expiresAt?, count? })`
-创建 key。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文（`<prefix>_<base62 length>`）。`appId` 首次自动注册。`length` 默认 8（短期邀请码等）；**长期付费 key 传 16**（≈95 bit 防爆破）。
+`autoDelete`：`true` 立即软删；`"3m"`/`"2h"`/`"3d"` 延迟软删（set deleteAt，Cron 清理，保留记录供 admin 查一段时间）。
 
-### `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 }`。
+### `checkKey({ key, context? })` / `client.checkKey(...)`
 
-### `client.listKeys({ appId, limit?, offset? })`
-列表，含完整明文。返回 `{ keys: KeyRecord[], total }`。
+公开只读校验（无需 rootKey，不扣减不删）。SDK 前置 `isValidKeyFormat` 校验。
 
-### `client.getKey(keyId)`
-详情（明文 + 最近 50 条 usage_logs）。
+### `client.verifyKey({ key, context? })`
 
-### `client.getKeyUsageLogs(keyId, { limit? })`
-使用记录。返回 `{ logs: UsageLog[] }`。
+管理扣减（需 rootKey）。原子扣减 1；扣到 0 时按 key 的 `autoDelete` 属性删除。`code`（valid=false 时）：`RATE_LIMITED`(429) / `KEY_PAUSED`、`KEY_BANNED`(423) / `KEY_DISABLED` / `KEY_EXPIRED` / `KEY_EXHAUSTED`。
 
-### `client.updateCredits(keyId, { operation, value, context? })`
-调整额度。`operation: "increment" | "decrement" | "set"`。increment 写 `refund` 事件。
+### `client.listKeys({ limit?, offset? })`
 
-### `client.updateKey(keyId, { meta?, enabled?, expiresAt? })`
-更新元数据/禁用。
+列表（自动绑定 client.appId），含完整明文。
 
-### `client.deleteKey(keyId)` / `client.deleteKeys(keyIds)`
+### 其他管理方法
+
+`client.getKey(keyId)` / `client.getKeyUsageLogs(keyId, { limit? })` / `client.updateCredits(...)` / `client.updateKey(...)` / `client.deleteKey(...)` / `client.deleteKeys(...)` / `client.lookupKey(...)` / `client.pauseKey(...)` / `client.banKey(...)` 等——详见类型定义。
 
 ## usage_log event 类型
 
-| event | 触发 | creditsBefore/After |
-|---|---|---|
-| `verify` | verify decrement:true 扣减 | ✅ |
-| `refund` | updateCredits increment | ✅ |
-| `create` | createKey | after = 初始额度 |
-| `delete` | deleteKey | — |
-| `update` | updateKey / updateCredits(decrement/set) | — |
+| event | 触发 |
+|---|---|
+| `check` | check 端点 / verify 遇无限 key |
+| `verify` | verify 扣减 |
+| `refund` | updateCredits increment |
+| `create` / `soft_delete` | createKey / deleteKey·autoDelete |
+| `rate_limited` / `auto_pause` / `auto_ban` / `pause` / `unpause` / `ban` / `unban` / `update` | 对应操作 |
+
+## 0.6.0 → 0.7.0 破坏性变更
+
+- **appId 移到 createClient**：`createClient({ appId, rootKey })` 必传 appId；`createKey`/`listKeys` 不再接受 appId（自动用 client.appId）
+- **rootKey 必传**：verify 扣减也需 rootKey（0.6.0 已加鉴权）
+- **baseUrl 内置**：不再在文档/示例暴露服务地址
 
 ## License
 

package/SKILL.md

@@ -1,160 +1,171 @@
 ---
 name: unified-keys
-description: 当项目需要管理 API key（创建、验证扣减额度、查询使用记录、管理端显示明文、用尽自动删除）时使用。自建通用 key 服务 keys.932324.xyz，明文存储 + 完整使用记录，npm 包 unified-keys。
+description: 当项目需要管理 API key（创建、只读校验、扣减验证、查询使用记录、管理端显示明文、用尽自动软删、DO 限流、自动暂停/封禁、明文反查）时使用。自建通用 key 服务，明文存储 + 完整使用记录 + 永久痕迹，npm 包 unified-keys。check 公开只读 / verify 管理扣减分离，createClient 绑定 appId。
 ---
 
 # unified-keys
 
-自建通用 API key 管理 SDK（替代 Unkey）。**明文存储 + 明文返回 + 完整使用记录 + 用尽自动删除**。服务跑在 Cloudflare Worker（`keys.932324.xyz`），数据存 D1。
+自建通用 API key 管理 SDK（替代 Unkey）。**明文存储 + 明文返回 + 完整使用记录 + soft delete 永久痕迹 + DO 滑动窗口限流 + 渐进式/直接自动封禁 + 反查**。服务跑在 Cloudflare Worker + D1。
+
+## 0.7.0 设计要点
+
+- **appId 是 client 的责任**：`createClient({ appId, rootKey })` 必传 appId，createKey/listKeys 自动绑定，不再每次传
+- **check/verify 端点拆分**（0.6.0 安全修复）：`POST /v1/keys/check` 公开只读（不扣不删）；`POST /v1/keys/verify` 需 `rootKeyAuth`（扣减是写操作）
+- **autoDelete 在 createKey 预设**（不再由 verify 调用方传——堵「任何人拿 key 明文删别人 key」漏洞）
+- **baseUrl 内置**：服务端点已内置到 SDK（`DEFAULT_BASE_URL`），文档/示例不暴露
 
 ## 何时用
 
 - 项目要发 API key / 邀请码 / 访问凭证给用户
 - 需要 verify key + 原子扣减额度（credits）
-- 想看每个 key 的使用历史（谁、何时、扣了几次、退了几次）
-- 想在管理端显示**完整 key 明文**（Unkey 做不到，只给前缀）
-- 一次性 key 用完自动删（避免 DB 堆积无用 key）
-- 多项目共用一个 key 服务（appId 命名空间隔离）
+- 需要「只读校验 key 有效性」不扣减（前端探活、whoami）
+- 想看每个 key 的使用历史 + 管理端显示完整明文
+- 限流 / 自动封禁 / 永久痕迹（soft delete 反查） / 多项目命名空间
 
 ## 安装
 
 ```bash
 pnpm add unified-keys
-# 或 npm i unified-keys
 ```
 
 ## 核心 API
 
-**baseUrl 内置默认**（`https://keys.932324.xyz`），无需传。
-
 ```ts
-import { createClient, isValidKeyFormat, verifyKey } from "unified-keys";
+import { createClient, checkKey, isValidKeyFormat } from "unified-keys";
 
-// 管理客户端（需 rootKey；baseUrl 内置）
-const client = createClient({ rootKey: process.env.KEYS_ROOT_KEY });
-
-// 创建 key（明文返回；appId = 项目 slug，首次自动注册）
-const { keys } = await client.createKey({
+// 管理客户端（appId 绑定应用；rootKey 必传）
+const client = createClient({
   appId: "my-app",
-  credits: 5,              // 初始剩余次数
-  maxUses: 5,              // 总额度（0 = 无限）
-  length: 8,               // body 位数（默认 8；长期付费 key 用 16 防爆破）
-  externalId: "user-123",  // 应用层关联业务实体（可选）
-  meta: { plan: "pro" },   // 任意元数据（可选）
-  count: 1,                // 批量创建数
+  rootKey: process.env.KEYS_ROOT_KEY,
 });
-// 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
+
+// 创建 key（自动用 client.appId；autoDelete 预设为 key 属性）
+const { keys } = await client.createKey({
+  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，不扣减不删）
+const c = await checkKey({ key: userKey, context: { ip: "1.2.3.4" } });
 
-// 详情（明文 + 使用记录）
-const { key, usageLogs } = await client.getKey(keyId);
+// 扣减（client 带 rootKey）
+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" },
-});
+// 列表（自动用 client.appId，含明文）
+const { keys: all, total } = await client.listKeys({ limit: 200 });
 
-// 更新元数据 / 禁用
+// 调整额度（refund 恢复）/ 更新元数据 / 删除（soft delete）
+await client.updateCredits(keyId, { operation: "increment", value: 1 });
 await client.updateKey(keyId, { meta: { plan: "enterprise" }, enabled: false });
-
-// 删除
 await client.deleteKey(keyId);
-await client.deleteKeys([keyId1, keyId2]);
 
-// 手输校验（isValidKeyFormat 库内置，与 verify 前置校验同源）
+// 手输校验
 if (!isValidKeyFormat(inputKey)) return invalid();
 ```
 
-## 特性（区别于 Unkey）
+## check vs verify
 
-| | unified-keys | Unkey |
+| | `checkKey` | `client.verifyKey` |
 |---|---|---|
-| 明文显示 | ✅ 列表/详情返回完整明文 | ❌ 只给前缀 |
-| 使用记录 | ✅ 每次 verify/refund/create/delete 写 usage_log | ❌ 只给当前 remaining |
-| verify 延迟 | <5ms（D1 binding 零网络跳） | 50-100ms（公网） |
-| 用尽自动删 | ✅ verify `autoDelete` 选项 | ❌ |
-| 前置格式校验 | ✅ SDK `isValidKeyFormat`，格式不对不查 DB | ❌ |
-| 自托管 | ✅ 自己的 D1 | ❌ SaaS |
-| 原子扣减 | ✅ `UPDATE ... WHERE credits>0 RETURNING` | ✅ |
+| 鉴权 | 公开（无需 rootKey） | 管理（需 rootKey） |
+| 扣减 | ❌ 不扣 | ✅ 原子扣减 1 |
+| autoDelete | ❌ 不删 | ✅ 扣到 0 按 key.autoDelete 删 |
+| event | `check` | `verify`（无限 key 写 `check`） |
+| 场景 | 探活 / 前端校验 / 只验证不扣减 | 真正消费额度 |
 
-## verify 选项
+**`autoDelete`（createKey 预设，verify 执行）**：`true` 立即 soft delete；`"3m"`/`"2h"`/`"3d"` 延迟（set deleteAt，Cron 每 10min 清理）；不传 = 不删（无限/长期 key）。
 
-| 选项 | 默认 | 说明 |
-|---|---|---|
-| `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, ...}） |
+**返回 `code`**（valid=false 时）：`RATE_LIMITED`(429) / `KEY_PAUSED`、`KEY_BANNED`(423) / `KEY_DISABLED` / `KEY_EXPIRED` / `KEY_EXHAUSTED`。
 
-**SDK 前置校验**：verify 前先 `isValidKeyFormat(key)`，格式不对直接返回 `{valid:false, found:false}`，不查 DB（省时间）。应用也可单独用 `isValidKeyFormat` 做手输校验。
+**SDK 对 429/423 不 throw**，返回 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 |
+|---|---|---|
+| 明文显示 | ✅ 列表/详情/反查返回完整明文 | ❌ 只给前缀 |
+| 使用记录 | ✅ 每次 check/verify/refund/create/soft_delete/... 写 log | ❌ 只给 remaining |
+| check/verify 拆分 | ✅ 公开只读 vs 管理扣减 | ❌ 单端点 |
+| 用尽自动删 | ✅ autoDelete（createKey 预设） | ❌ |
+| 永久痕迹 | ✅ soft delete 反查 | ❌ 真删丢痕迹 |
+| 限流 / 自动封禁 | ✅ DO 滑动窗口 / 渐进式·直接 | ❌ |
+| 前置格式校验 | ✅ SDK isValidKeyFormat | ❌ |
+
+## 自动封禁（autoBan）
+
+**渐进式**（默认）：违规累计达 maxViolations 永久 ban，前 N-1 次 pause。
+```jsonc
+{ "threshold": 10, "windowSec": 600, "maxViolations": 3, "durationSec": 3600 }
+```
+**直接**（`mode: "direct"`）：单次达阈值即 action。
+```jsonc
+{ "mode": "direct", "action": "ban", "threshold": 10, "windowSec": 600 }
+```
+`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（扣减，client 带 rootKey）
 ```ts
-import { verifyKey } from "unified-keys";
+import { createClient } from "unified-keys";
+const client = createClient({ appId: "my-app", 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`
+## 注意事项
 
-ROOT_KEY 联系服务管理员获取。
+- **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。
+- **soft delete 不丢痕迹**：deleteKey/autoDelete 只 set `_delete=true`，明文 + meta + usage_logs 永久保留，lookup 可反查。
+- **D1 datetime 拼接**：服务端 `datetime('now', '+N seconds')` 必须用 `sql.raw(String(N))`，不能 `${N}` 参数化。
 
-## 实现位置（本项目内）
+## 实现位置（项目内）
 
-- 服务端：`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；D1 binding `KEY_SERVICE_DB` + Durable Object `RATE_LIMITER`）
+- SDK：`packages/keys`（npm `unified-keys@0.7.0`，monorepo workspace 直接用 src；服务端点 `DEFAULT_BASE_URL` 在 `src/client.ts`）
+- schema：`packages/db/src/schemas/key-service.ts`（`key_apps` / `key_records`（含 `auto_delete` 列）/ `key_usage_logs`）
+- migrations：`packages/infra/migrations/keys/0001` ~ `0005`（alchemy deploy 自动跑）
+- rootKey：`packages/infra/.env` 的 `KEYS_ROOT_KEY`（admin-api + 4 应用共用，alchemy `secret("KEYS_ROOT_KEY")` 同步）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unified-keys",
-  "version": "0.5.0",
+  "version": "0.7.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,
@@ -33,8 +40,10 @@ export function isValidKeyFormat(key: string): boolean {
 }
 
 export function createClient(config: KeyServiceClientConfig): KeyServiceClient {
+	const { appId, rootKey } = config;
 	const baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
-	const rootKey = config.rootKey;
+	if (!appId) throw new Error("unified-keys: appId is required");
+	if (!rootKey) throw new Error("unified-keys: rootKey is required");
 
 	async function request<T>(
 		method: string,
@@ -65,7 +74,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}`);
 		}
@@ -77,9 +87,11 @@ export function createClient(config: KeyServiceClientConfig): KeyServiceClient {
 			request<CreateAppResult>("POST", "/v1/apps", { body: input }),
 		listApps: () => request<ListAppsResult>("GET", "/v1/apps"),
 		createKey: (input: CreateKeyInput) =>
-			request<CreateKeyResult>("POST", "/v1/keys", { body: input }),
+			request<CreateKeyResult>("POST", "/v1/keys", {
+				body: { ...input, appId },
+			}),
 		listKeys: (input: ListKeysInput) => {
-			const params = new URLSearchParams({ appId: input.appId });
+			const params = new URLSearchParams({ appId });
 			if (input.limit != null) params.set("limit", String(input.limit));
 			if (input.offset != null) params.set("offset", String(input.offset));
 			return request<ListKeysResult>("GET", `/v1/keys?${params}`);
@@ -107,26 +119,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 +172,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

@@ -1,12 +1,12 @@
 /** unified-keys SDK 类型定义 */
 
 export interface KeyServiceClientConfig {
-	/**
-	 * 服务端点，默认 https://keys.932324.xyz（自建服务固定，通常无需传）
-	 */
+	/** 应用命名空间 slug（createKey/listKeys 自动绑定，无需每次传） */
+	appId: string;
+	/** 服务端点（内置默认，仅在指向自建/测试实例时传） */
 	baseUrl?: string;
-	/** 管理 API 需要；verify 端点不需要 */
-	rootKey?: string;
+	/** 管理 API + verify 扣减都需要（Bearer token） */
+	rootKey: string;
 }
 
 export interface AppRecord {
@@ -27,8 +27,38 @@ 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 */
@@ -41,10 +71,16 @@ export interface CreateKeyInput {
 	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 {
@@ -59,21 +95,29 @@ 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;
 }
 
 export interface ListKeysInput {
-	appId: string;
 	limit?: number;
 	offset?: number;
 }
@@ -106,7 +150,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;
@@ -126,31 +170,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;
 }
 
@@ -163,7 +228,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>;
@@ -175,6 +270,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