unified-keys 0.8.0 → 0.9.0

package/README.md

@@ -55,7 +55,7 @@ const v = await client.verifyKey({ key: userKey, context: { ip: "1.2.3.4" } });
 
 创建 key（自动绑定 client.appId）。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文。`length` 默认 8；**长期付费 key 传 16**。
 
-`autoDelete`：`true` 立即软删；`"3m"`/`"2h"`/`"3d"` 延迟软删（set deleteAt，Cron 清理，保留记录供 admin 查一段时间）。
+`autoDelete`：`true` 立即软删；`"3m"`/`"2h"`/`"3d"` 延迟软删（set deleteAt，Cron 每 5min 清理，保留记录供 admin 查一段时间）。`"now"`/`"0"` 等价 `true`（0.9.0 收窄，向后兼容）。`KeyRecord.deleteAt` 返回软删时间点，前端可展示「将于 XX 软删」。
 
 ### `checkKey({ key, context? })` / `client.checkKey(...)`
 
@@ -89,6 +89,13 @@ const v = await client.verifyKey({ key: userKey, context: { ip: "1.2.3.4" } });
 - **rootKey 必传**：verify 扣减也需 rootKey（0.6.0 已加鉴权）
 - **baseUrl 内置**：不再在文档/示例暴露服务地址
 
+## 0.8.0 → 0.9.0
+
+- **autoDelete 值域收窄**：`true`(立即软删) / `"3m"`/`"2h"`/`"3d"`(延迟) / 不设(不删)；`"now"`/`"0"` 等价 `true`（向后兼容，worker 收到归一）
+- **`KeyRecord.deleteAt`**：新增返回软删时间点（延迟模式 + verify 用尽后写入），前端可展示「将于 XX 软删」
+- **Cron 10min → 5min**：延迟软删精度提升（deleteAt 与实际软删偏差 ≤5min）
+- 非 breaking（additive + 兼容归一）
+
 ## License
 
 MIT

package/SKILL.md

@@ -11,7 +11,7 @@ description: 当项目需要管理 API key（创建、只读校验、扣减验
 
 - **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」漏洞）
+- **autoDelete 在 createKey 预设**（不再由 verify 调用方传——堵「任何人拿 key 明文删别人 key」漏洞）；值域 `true`(立即软删) / `"3d"` 等时长(延迟软删) / 不设(不删)，`"now"`/`"0"` 等价 `true`（0.9.0 收窄，老值 worker 归一兼容）
 - **baseUrl 内置**：服务端点已内置到 SDK（`DEFAULT_BASE_URL`），文档/示例不暴露
 
 ## 何时用
@@ -87,7 +87,7 @@ if (!isValidKeyFormat(inputKey)) return invalid();
 | event | `check` | `verify`（无限 key 写 `check`） |
 | 场景 | 探活 / 前端校验 / 只验证不扣减 | 真正消费额度 |
 
-**`autoDelete`（createKey 预设，verify 执行）**：`true` 立即 soft delete；`"3m"`/`"2h"`/`"3d"` 延迟（set deleteAt，Cron 每 10min 清理）；不传 = 不删（无限/长期 key）。
+**`autoDelete`（用尽后软删策略，createKey 预设，verify 执行）**：`true` 立即 soft delete；`"3m"`/`"2h"`/`"3d"` 延迟（set deleteAt，Cron 每 5min 清理）；不传 = 不删（无限/长期 key）。`KeyRecord.deleteAt` 返回软删时间点（延迟模式 + 用尽后写入），前端可展示「将于 XX 软删」。
 
 **返回 `code`**（valid=false 时）：`RATE_LIMITED`(429) / `KEY_PAUSED`、`KEY_BANNED`(423) / `KEY_DISABLED` / `KEY_EXPIRED` / `KEY_EXHAUSTED`。
 
@@ -172,7 +172,7 @@ const { found, key, recentLogs } = await client.lookupKey({ plaintext: "sk_xxx"
 ## 实现位置（项目内）
 
 - 服务端：`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`）
+- SDK：`packages/keys`（npm `unified-keys@0.9.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 自动跑）
+- migrations：`packages/infra/migrations/keys/0001` ~ `0007`（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.8.0",
+  "version": "0.9.0",
   "description": "通用 API key 管理 SDK（明文存储 + 明文返回 + 完整使用记录 + per-key 限流/自动处罚）",
   "type": "module",
   "main": "./src/index.ts",

package/src/types.ts

@@ -75,8 +75,9 @@ export interface CreateKeyInput {
 	/** 自动处罚策略（存 meta.autoBan）：pause/ban 互斥，banAfter 渐进式 */
 	autoBan?: AutoBanConfig;
 	/**
-	 * autoDelete（createKey 时预设为 key 属性，verify 扣减到 0 时执行；verify 端点不再接受调用方传参）：
-	 *   true / "now" → 立即 soft delete；"3m" / "2h" / "3d" → set deleteAt，Cron 软删（保留记录供 admin 查一段时间）
+	 * autoDelete（用尽后软删策略：createKey 预设，verify 扣到 0 时执行；verify 端点不再接受调用方传参）：
+	 *   true → 立即 soft delete；"3m"/"2h"/"3d" → set deleteAt，Cron 软删（保留记录供 admin 查一段时间）；不设 = 不删
+	 *   （"now"/"0" 老值等价 true，向后兼容）
 	 */
 	autoDelete?: boolean | string;
 	/** 批量创建数量，默认 1 */
@@ -115,12 +116,14 @@ export interface CreateKeyResult {
 
 export interface KeyRecord {
 	appId: string;
-	/** autoDelete 策略（createKey 预设，verify 只读）：null=不删 | "true"=用尽立即软删 | "3m"/"2h"/"3d"=延迟软删 */
+	/** autoDelete 策略（createKey 预设，verify 只读）：null=不删 | "true"=用尽立即软删 | "Nm"/"Nh"/"Nd"=延迟软删 */
 	autoDelete: string | null;
 	banReason: string | null;
 	banStatus: "active" | "paused" | "banned";
 	createdAt: string;
 	creditsRemaining: number;
+	/** 软删时间点（ISO）：autoDelete 延迟模式 + verify 扣到 0 时写入；Cron 每 5min 扫描软删；null=未安排 */
+	deleteAt: string | null;
 	/** soft delete 标志（true=已软删，verify/list 过滤但 admin 可查）*/
 	deleted: boolean;
 	enabled: boolean;