unified-keys 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# unified-keys
+
+自建通用 API key 管理 SDK。**明文存储 + 明文返回 + 完整使用记录**。服务跑在 Cloudflare Worker + D1，替代 Unkey SaaS。
+
+## 特性
+
+- ✅ **明文可重复显示**：list/get 返回完整明文（Unkey 只给前缀）
+- ✅ **完整使用记录**：每次 verify/refund/create/delete 写 usage_log（Unkey 无）
+- ✅ **verify 原子扣减**：`UPDATE ... WHERE credits>0 RETURNING`，并发安全
+- ✅ **多 app 命名空间**：appId（slug）区分项目，首次创建 key 自动注册
+- ✅ **零依赖**：纯 fetch，Worker/Node/Next.js 通用
+- ✅ **TS 强类型**
+
+## 安装
+
+```bash
+pnpm add unified-keys
+```
+
+## 快速开始
+
+```ts
+import { createClient, verifyKey } from "unified-keys";
+
+const client = createClient({
+  baseUrl: "https://keys.932324.xyz",
+  rootKey: process.env.KEYS_ROOT_KEY,
+});
+
+// 创建 key（明文返回）
+const { keys } = await client.createKey({
+  appId: "my-app",
+  credits: 5,
+  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" } }
+);
+```
+
+## API
+
+### `createClient({ baseUrl, rootKey })` → client
+管理客户端。`rootKey` 用于管理 API（verify 端点不需要）。
+
+### `client.createKey({ appId, prefix?, credits?, maxUses?, meta?, externalId?, expiresAt?, count? })`
+创建 key。返回 `{ keys: [{ key, keyId }] }`，`key` 是完整明文。`appId` 首次自动注册。
+
+### `verifyKey({ baseUrl }, { key, decrement?, context? })`
+公开验证（无需 rootKey）。`decrement: true` 扣减额度并写 verify log；`false` 只查。
+返回 `{ valid, found, keyId, remaining, maxUses, meta, externalId, appId, enabled, expiresAt, createdAt }`。
+
+### `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)`
+
+## usage_log event 类型
+
+| event | 触发 | creditsBefore/After |
+|---|---|---|
+| `verify` | verify decrement:true 扣减 | ✅ |
+| `refund` | updateCredits increment | ✅ |
+| `create` | createKey | after = 初始额度 |
+| `delete` | deleteKey | — |
+| `update` | updateKey / updateCredits(decrement/set) | — |
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: unified-keys
+description: 当项目需要管理 API key（创建、验证扣减额度、查询使用记录、管理端显示明文）时使用。自建通用 key 服务 keys.932324.xyz，明文存储 + 完整使用记录，npm 包 unified-keys。
+---
+
+# unified-keys
+
+自建通用 API key 管理 SDK（替代 Unkey）。**明文存储 + 明文返回 + 完整使用记录**。服务跑在 Cloudflare Worker（`keys.932324.xyz`），数据存 D1。
+
+## 何时用
+
+- 项目要发 API key / 邀请码 / 访问凭证给用户
+- 需要 verify key + 原子扣减额度（credits）
+- 想看每个 key 的使用历史（谁、何时、扣了几次、退了几次）
+- 想在管理端显示**完整 key 明文**（Unkey 做不到，只给前缀）
+- 多项目共用一个 key 服务（appId 命名空间隔离）
+
+## 安装
+
+```bash
+pnpm add unified-keys
+# 或 npm i unified-keys
+```
+
+## 服务端点
+
+- **公开 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 联系服务管理员获取。
+
+## 核心 API
+
+```ts
+import { createClient, verifyKey } from "unified-keys";
+
+// 管理客户端（需 rootKey）
+const client = createClient({
+  baseUrl: "https://keys.932324.xyz",
+  rootKey: process.env.KEYS_ROOT_KEY,
+});
+
+// 创建 key（明文返回；appId = 项目 slug，首次自动注册）
+const { keys } = await client.createKey({
+  appId: "my-app",
+  credits: 5,              // 初始剩余次数
+  maxUses: 5,              // 总额度（0 = 无限）
+  externalId: "user-123",  // 应用层关联业务实体（可选）
+  meta: { plan: "pro" },   // 任意元数据（可选）
+  count: 1,                // 批量创建数
+});
+// keys[0].key = 完整明文（仅创建时与 list/get 返回），keys[0].keyId
+
+// 验证 + 扣减（用户持有明文 key，服务端验证）
+const result = await verifyKey(
+  { baseUrl: "https://keys.932324.xyz" },
+  { key: userKey, decrement: true, context: { username: "alice", ip: "1.2.3.4" } }
+);
+// { 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 });
+
+// 详情（明文 + 使用记录）
+const { key, usageLogs } = await client.getKey(keyId);
+
+// 查使用记录（核心特性）
+const { logs } = await client.getKeyUsageLogs(keyId, { limit: 50 });
+// logs: [{ event: "verify"|"refund"|"create"|"delete"|"update", creditsBefore, creditsAfter, context, createdAt }]
+
+// 调整额度（refund 恢复）
+await client.updateCredits(keyId, {
+  operation: "increment",  // increment | decrement | set
+  value: 1,
+  context: { reason: "refund" },
+});
+
+// 更新元数据 / 禁用
+await client.updateKey(keyId, { meta: { plan: "enterprise" }, enabled: false });
+
+// 删除
+await client.deleteKey(keyId);
+await client.deleteKeys([keyId1, keyId2]);
+```
+
+## 特性（区别于 Unkey）
+
+| | unified-keys | Unkey |
+|---|---|---|
+| 明文显示 | ✅ 列表/详情返回完整明文 | ❌ 只给 start 前缀 |
+| 使用记录 | ✅ 每次 verify/refund/create/delete 写 usage_log | ❌ 只给当前 remaining |
+| verify 延迟 | <5ms（D1 binding 零网络跳） | 50-100ms（公网） |
+| 自托管 | ✅ 自己的 D1 | ❌ SaaS |
+| 原子扣减 | ✅ `UPDATE ... WHERE credits>0 RETURNING` | ✅ |
+
+## event 类型（usage_log）
+
+- `verify`：verify 扣减（含 creditsBefore/After + context）
+- `refund`：updateCredits increment 恢复额度
+- `create` / `delete` / `update` / `disable`
+
+## 集成示例
+
+### Next.js Route Handler（服务端 verify 用户持有 key）
+```ts
+import { verifyKey } from "unified-keys";
+export async function POST(req: Request) {
+  const { key } = await req.json();
+  const r = await verifyKey(
+    { baseUrl: "https://keys.932324.xyz" },
+    { key, decrement: true, context: { ip: req.headers.get("x-forwarded-for") } }
+  );
+  if (!r.valid) return Response.json({ error: "invalid key" }, { status: 403 });
+  // ... 授权逻辑
+}
+```
+
+### Next.js Server Component（只读查询，不扣减）
+```ts
+import { verifyKey } from "unified-keys";
+const info = await verifyKey(
+  { baseUrl: "https://keys.932324.xyz" },
+  { key: params.key, decrement: false }
+);
+if (!info.found || !info.valid) notFound();
+// info.remaining / info.meta / info.expiresAt
+```
+
+### Cloudflare Worker（管理端）
+```ts
+import { createClient } from "unified-keys";
+const client = createClient({
+  baseUrl: c.env.KEY_SERVICE_URL,
+  rootKey: c.env.KEY_SERVICE_ROOT_KEY,
+});
+await client.createKey({ appId: "my-app", credits: 1 });
+```
+
+## 实现位置（本项目内）
+
+- 服务端：`apps/key-service`（Hono Worker → keys.932324.xyz）
+- SDK：`packages/keys`（发布名 unified-keys）
+- schema：`packages/db/src/schemas/key-service.ts`（key_apps / key_records / key_usage_logs）
+- 已迁移：github-inviter / user-dashboard（shadcn-proxy / notify-me 仍用 Unkey，待后续）

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "unified-keys",
+  "version": "0.1.0",
+  "description": "自建通用 API key 管理 SDK（明文存储 + 明文返回 + 完整使用记录），调用 keys.932324.xyz 服务",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "SKILL.md"
+  ],
+  "keywords": [
+    "api-key",
+    "key-management",
+    "unkey",
+    "credits",
+    "usage-logs",
+    "cloudflare-workers",
+    "d1"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "catalog:"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit"
+  }
+}

package/src/client.ts

@@ -0,0 +1,147 @@
+import type {
+	BatchDeleteResult,
+	CreateAppInput,
+	CreateAppResult,
+	CreateKeyInput,
+	CreateKeyResult,
+	DeleteResult,
+	GetKeyResult,
+	GetKeyUsageLogsInput,
+	KeyServiceClient,
+	KeyServiceClientConfig,
+	ListAppsResult,
+	ListKeysInput,
+	ListKeysResult,
+	UpdateCreditsInput,
+	UpdateCreditsResult,
+	UpdateKeyInput,
+	UsageLogsResult,
+	VerifyInput,
+	VerifyResult,
+} from "./types";
+
+const KEY_FORMAT = /^[a-zA-Z0-9_-]{8,128}$/;
+
+/**
+ * key 格式校验（base62 + 下划线/连字符，8-128 位，含可选前缀）。
+ * verify 前置校验：格式不对直接判 invalid，不查 DB，省时间。
+ */
+export function isValidKeyFormat(key: string): boolean {
+	return typeof key === "string" && KEY_FORMAT.test(key);
+}
+
+export function createClient(config: KeyServiceClientConfig): KeyServiceClient {
+	const baseUrl = config.baseUrl.replace(/\/$/, "");
+	const rootKey = config.rootKey;
+
+	async function request<T>(
+		method: string,
+		path: string,
+		options?: { body?: unknown; auth?: boolean }
+	): Promise<T> {
+		const headers: Record<string, string> = {
+			"Content-Type": "application/json",
+		};
+		const needAuth = options?.auth ?? true;
+		if (needAuth) {
+			if (!rootKey) {
+				throw new Error("unified-keys: rootKey is required for management API");
+			}
+			headers.Authorization = `Bearer ${rootKey}`;
+		}
+		const res = await fetch(`${baseUrl}${path}`, {
+			method,
+			headers,
+			body: options?.body ? JSON.stringify(options.body) : undefined,
+		});
+		const text = await res.text();
+		let data: unknown;
+		try {
+			data = text ? JSON.parse(text) : {};
+		} catch {
+			throw new Error(
+				`unified-keys ${method} ${path}: ${res.status} ${text.slice(0, 200)}`
+			);
+		}
+		if (!res.ok) {
+			const msg = (data as { error?: string }).error ?? `${res.status}`;
+			throw new Error(`unified-keys ${method} ${path}: ${msg}`);
+		}
+		return data as T;
+	}
+
+	return {
+		createApp: (input: CreateAppInput) =>
+			request<CreateAppResult>("POST", "/v1/apps", { body: input }),
+		listApps: () => request<ListAppsResult>("GET", "/v1/apps"),
+		createKey: (input: CreateKeyInput) =>
+			request<CreateKeyResult>("POST", "/v1/keys", { body: input }),
+		listKeys: (input: ListKeysInput) => {
+			const params = new URLSearchParams({ appId: input.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}`);
+		},
+		getKey: (keyId: string) =>
+			request<GetKeyResult>("GET", `/v1/keys/${keyId}`),
+		deleteKey: (keyId: string) =>
+			request<DeleteResult>("DELETE", `/v1/keys/${keyId}`),
+		deleteKeys: (keyIds: string[]) =>
+			request<BatchDeleteResult>("POST", "/v1/keys/batch-delete", {
+				body: { keyIds },
+			}),
+		updateKey: (keyId: string, input: UpdateKeyInput) =>
+			request<DeleteResult>("PATCH", `/v1/keys/${keyId}`, {
+				body: input,
+			}),
+		updateCredits: (keyId: string, input: UpdateCreditsInput) =>
+			request<UpdateCreditsResult>("POST", `/v1/keys/${keyId}/credits`, {
+				body: input,
+			}),
+		getKeyUsageLogs: (keyId: string, input?: GetKeyUsageLogsInput) => {
+			const limit = input?.limit ?? 50;
+			return request<UsageLogsResult>(
+				"GET",
+				`/v1/keys/${keyId}/usage-logs?limit=${limit}`
+			);
+		},
+		verifyKey: (input: VerifyInput) => {
+			if (!isValidKeyFormat(input.key)) {
+				return Promise.resolve({ valid: false, found: false } as VerifyResult);
+			}
+			return request<VerifyResult>("POST", "/v1/keys/verify", {
+				body: input,
+				auth: false,
+			});
+		},
+	};
+}
+
+/**
+ * 公开 verify 端点，无需 rootKey。
+ * 适合「用户持有明文 key、服务端验证并扣减」的场景。
+ */
+export async function verifyKey(
+	config: { baseUrl: string },
+	input: VerifyInput
+): Promise<VerifyResult> {
+	if (!isValidKeyFormat(input.key)) return { valid: false, found: false };
+	const baseUrl = config.baseUrl.replace(/\/$/, "");
+	const res = await fetch(`${baseUrl}/v1/keys/verify`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(input),
+	});
+	const text = await res.text();
+	let data: unknown;
+	try {
+		data = text ? JSON.parse(text) : {};
+	} catch {
+		throw new Error(`unified-keys verify: ${res.status} ${text.slice(0, 200)}`);
+	}
+	if (!res.ok) {
+		const msg = (data as { error?: string }).error ?? `${res.status}`;
+		throw new Error(`unified-keys verify: ${msg}`);
+	}
+	return data as VerifyResult;
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export { createClient, isValidKeyFormat, verifyKey } from "./client";
+export type {
+	AppRecord,
+	BatchDeleteResult,
+	CreateAppInput,
+	CreateAppResult,
+	CreatedKey,
+	CreateKeyInput,
+	CreateKeyResult,
+	DeleteResult,
+	GetKeyResult,
+	GetKeyUsageLogsInput,
+	KeyRecord,
+	KeyServiceClient,
+	KeyServiceClientConfig,
+	ListAppsResult,
+	ListKeysInput,
+	ListKeysResult,
+	UpdateCreditsInput,
+	UpdateCreditsResult,
+	UpdateKeyInput,
+	UsageLog,
+	UsageLogsResult,
+	VerifyInput,
+	VerifyResult,
+} from "./types";

package/src/types.ts

@@ -0,0 +1,175 @@
+/** unified-keys SDK 类型定义 */
+
+export interface KeyServiceClientConfig {
+	/** 服务端点，如 https://keys.932324.xyz */
+	baseUrl: string;
+	/** 管理 API 需要；verify 端点不需要 */
+	rootKey?: string;
+}
+
+export interface AppRecord {
+	createdAt: string;
+	id: string;
+	slug: string;
+}
+
+export interface CreateAppInput {
+	slug: string;
+}
+
+export interface CreateAppResult {
+	app: AppRecord;
+}
+
+export interface ListAppsResult {
+	apps: AppRecord[];
+}
+
+export interface CreateKeyInput {
+	appId: string;
+	/** 批量创建数量，默认 1 */
+	count?: number;
+	/** 初始额度（剩余次数），默认 1 */
+	credits?: number;
+	/** ISO 时间字符串，过期时间 */
+	expiresAt?: string;
+	/** 应用层关联业务实体（如 github-inviter 的 configSlug） */
+	externalId?: string;
+	/** 总额度（0=无限），默认等于 credits */
+	maxUses?: number;
+	/** 应用层任意元数据 */
+	meta?: Record<string, unknown>;
+	/** 可选前缀，生成 `<prefix>_<rand>`；不传则纯 random */
+	prefix?: string;
+}
+
+export interface CreatedKey {
+	/** 完整明文 key（仅创建时与服务端 list/get 返回） */
+	key: string;
+	keyId: string;
+}
+
+export interface CreateKeyResult {
+	keys: CreatedKey[];
+}
+
+export interface KeyRecord {
+	appId: string;
+	createdAt: string;
+	creditsRemaining: number;
+	enabled: boolean;
+	expiresAt: string | null;
+	externalId: string | null;
+	keyId: string;
+	maxUses: number;
+	meta: Record<string, unknown> | null;
+	plaintext: string;
+	prefix: string | null;
+	updatedAt: string;
+}
+
+export interface ListKeysInput {
+	appId: string;
+	limit?: number;
+	offset?: number;
+}
+
+export interface ListKeysResult {
+	keys: KeyRecord[];
+	total: number;
+}
+
+export interface UpdateKeyInput {
+	enabled?: boolean;
+	expiresAt?: string | null;
+	meta?: Record<string, unknown>;
+}
+
+export interface UpdateCreditsInput {
+	/** 上下文，写入 usage_log（如 {reason:"revoke"}） */
+	context?: Record<string, unknown>;
+	operation: "increment" | "decrement" | "set";
+	value: number;
+}
+
+export interface UpdateCreditsResult {
+	remaining: number;
+}
+
+export interface UsageLog {
+	appId: string;
+	context: Record<string, unknown> | null;
+	createdAt: string;
+	creditsAfter: number | null;
+	creditsBefore: number | null;
+	/** verify(扣减) / refund(恢复) / create / delete / update / disable */
+	event: string;
+	id: string;
+	keyId: string;
+}
+
+export interface GetKeyUsageLogsInput {
+	limit?: number;
+}
+
+export interface UsageLogsResult {
+	logs: UsageLog[];
+}
+
+export interface GetKeyResult {
+	key: KeyRecord;
+	usageLogs: UsageLog[];
+}
+
+export interface VerifyInput {
+	/** 上下文，写入 usage_log（如 {username, source, ip}） */
+	context?: Record<string, unknown>;
+	/** 默认 true；false 时只查不扣（写 verify log 但不扣减） */
+	decrement?: boolean;
+	/** 完整明文 key */
+	key: string;
+}
+
+export interface VerifyResult {
+	appId?: string;
+	createdAt?: string;
+	enabled?: boolean;
+	expiresAt?: string | null;
+	externalId?: string | null;
+	/** key 是否存在（区别「不存在」与「存在但额度耗尽」） */
+	found: boolean;
+	keyId?: string;
+	maxUses?: number;
+	meta?: Record<string, unknown> | null;
+	remaining?: number;
+	valid: boolean;
+}
+
+export interface DeleteResult {
+	success: boolean;
+}
+
+export interface BatchDeleteResult {
+	deleted: string[];
+	failed: string[];
+}
+
+export interface KeyServiceClient {
+	createApp(input: CreateAppInput): Promise<CreateAppResult>;
+	createKey(input: CreateKeyInput): Promise<CreateKeyResult>;
+	deleteKey(keyId: string): Promise<DeleteResult>;
+	deleteKeys(keyIds: string[]): Promise<BatchDeleteResult>;
+	getKey(keyId: string): Promise<GetKeyResult>;
+	getKeyUsageLogs(
+		keyId: string,
+		input?: GetKeyUsageLogsInput
+	): Promise<UsageLogsResult>;
+	listApps(): Promise<ListAppsResult>;
+	listKeys(input: ListKeysInput): Promise<ListKeysResult>;
+	updateCredits(
+		keyId: string,
+		input: UpdateCreditsInput
+	): Promise<UpdateCreditsResult>;
+	updateKey(keyId: string, input: UpdateKeyInput): Promise<DeleteResult>;
+	verifyKey(input: VerifyInput): Promise<VerifyResult>;
+}