@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/identity/accounts.js

@@ -0,0 +1,367 @@
+import { randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "./audit.js";
+import { lockEnterpriseAdmins, lockEnterpriseAdminsAndAuthorize } from "./enterprise-admin.js";
+import { MAX_PASSWORD_LENGTH, normalizeLogin, validatePassword } from "./login.js";
+import { DUMMY_PASSWORD_HASH, hashPassword, verifyPassword } from "./passwords.js";
+/** 构造 `Account` 所需的 accounts 列（供跨表查询 select 使用）。 */
+export const ACCOUNT_COLUMNS = [
+    "accounts.id",
+    "accounts.display_name",
+    "accounts.email",
+    "accounts.status",
+    "accounts.is_enterprise_admin",
+    "accounts.created_at",
+];
+export function toAccount(r) {
+    return {
+        id: r.id,
+        displayName: r.display_name,
+        email: r.email,
+        status: r.status,
+        isEnterpriseAdmin: r.is_enterprise_admin,
+        createdAt: r.created_at,
+    };
+}
+/** 仅当违反 identities 主键约束（登录名已被占用）时为 true；其他唯一约束冲突照常抛出。 */
+function isLoginTaken(e) {
+    const err = e;
+    return err.code === "23505" && err.constraint === "identities_pkey";
+}
+/**
+ * 规范化登录名、校验并哈希密码（不碰数据库，可在事务 / 锁之外先做）。
+ * 给了 `passwordHash`（调用方已在事务外算好）时不再跑 scrypt。
+ */
+async function prepareLocal(input, passwordHash) {
+    const login = normalizeLogin(input.login);
+    validatePassword(input.password);
+    return { input, login, passwordHash: passwordHash ?? (await hashPassword(input.password)) };
+}
+/** 在事务内插入账号、本地身份与密码；登录名已占用 → `account.login_taken`。 */
+async function insertLocal(t, p) {
+    const { input, login, passwordHash } = p;
+    const id = randomUUID();
+    const row = await t
+        .insertInto("accounts")
+        .values({
+        id,
+        display_name: input.displayName,
+        email: input.email ?? null,
+        is_enterprise_admin: input.enterpriseAdmin ?? false,
+    })
+        .returningAll()
+        .executeTakeFirstOrThrow();
+    try {
+        await t
+            .insertInto("identities")
+            .values({
+            source: "local",
+            external_id: login,
+            account_id: id,
+            email: input.email ?? null,
+            linked_via: "local",
+        })
+            .execute();
+    }
+    catch (e) {
+        if (isLoginTaken(e)) {
+            throw new ApiError("account.login_taken", "Login is already taken");
+        }
+        throw e;
+    }
+    await t
+        .insertInto("local_passwords")
+        .values({ account_id: id, password_hash: passwordHash })
+        .execute();
+    return toAccount(row);
+}
+/** 在事务内写入（或覆盖）本地密码哈希；账号不存在 → `account.not_found`。 */
+async function writePassword(t, accountId, passwordHash) {
+    const exists = await t
+        .selectFrom("accounts")
+        .select("id")
+        .where("id", "=", accountId)
+        .executeTakeFirst();
+    if (!exists)
+        throw new ApiError("account.not_found", "Account not found");
+    await t
+        .insertInto("local_passwords")
+        .values({ account_id: accountId, password_hash: passwordHash })
+        .onConflict((oc) => oc.column("account_id").doUpdateSet({ password_hash: passwordHash, updated_at: new Date() }))
+        .execute();
+}
+/** 账号服务：本地账号的创建、认证与管理。框架无关，由调用方注入 db。 */
+export class AccountsService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** 校验密码长度并算出哈希（scrypt，较慢）：供需要在事务之外先算好哈希的调用方使用。 */
+    async hashNewPassword(password) {
+        validatePassword(password);
+        return hashPassword(password);
+    }
+    /**
+     * 建本地账号。传 `trx` 时在调用方的事务内插入；在事务内调用时应先在事务**之外**用 `hashNewPassword`
+     * 算好 `passwordHash` 传进来，避免 scrypt 期间连接处于 idle in transaction。
+     */
+    async createLocal(input, trx, passwordHash) {
+        const prepared = await prepareLocal(input, passwordHash);
+        const run = (t) => insertLocal(t, prepared);
+        return trx ? run(trx) : this.db.transaction().execute(run);
+    }
+    /**
+     * 企业管理员建本地账号（可同时设为企业管理员）：事务内取企业管理员锁并复核发起人仍是活跃企业管理员
+     * （否则 `forbidden`），建号并写审计 `account.created`。密码哈希在取锁之前算好，不在锁内跑 scrypt。
+     */
+    async createByAdmin(input, actorAccountId, actorTokenId) {
+        const prepared = await prepareLocal(input);
+        return this.db.transaction().execute(async (trx) => {
+            await lockEnterpriseAdminsAndAuthorize(trx, actorAccountId);
+            const a = await insertLocal(trx, prepared);
+            await audit(trx, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                action: "account.created",
+                target: a.id,
+                detail: { enterpriseAdmin: a.isEnterpriseAdmin },
+            });
+            return a;
+        });
+    }
+    async authenticateLocal(login, password) {
+        // 超长密码不可能正确（validatePassword 上限 256），不跑 scrypt 也不查库，免得被超长输入拖慢；
+        // 只暴露「密码超长」这一事实，正常长度密码下未知登录名与错密码的耗时仍相当
+        if (password.length > MAX_PASSWORD_LENGTH)
+            return null;
+        let external;
+        try {
+            external = normalizeLogin(login);
+        }
+        catch {
+            await verifyPassword(DUMMY_PASSWORD_HASH, password);
+            return null;
+        }
+        const row = await this.db
+            .selectFrom("identities")
+            .innerJoin("accounts", "accounts.id", "identities.account_id")
+            .innerJoin("local_passwords", "local_passwords.account_id", "accounts.id")
+            .select([
+            "accounts.id",
+            "accounts.display_name",
+            "accounts.email",
+            "accounts.email_verified",
+            "accounts.status",
+            "accounts.is_enterprise_admin",
+            "accounts.created_at",
+            "accounts.updated_at",
+            "local_passwords.password_hash",
+        ])
+            .where("identities.source", "=", "local")
+            .where("identities.external_id", "=", external)
+            .executeTakeFirst();
+        if (!row) {
+            await verifyPassword(DUMMY_PASSWORD_HASH, password);
+            return null;
+        }
+        if (!(await verifyPassword(row.password_hash, password)))
+            return null;
+        if (row.status === "disabled") {
+            throw new ApiError("auth.account_disabled", "Account is disabled");
+        }
+        return toAccount(row);
+    }
+    /** 按账号 id 校验本地密码（改密码时核对旧密码）；没有本地密码、超长或不符 → false。 */
+    async verifyPassword(accountId, password) {
+        if (password.length > MAX_PASSWORD_LENGTH)
+            return false;
+        const row = await this.db
+            .selectFrom("local_passwords")
+            .select("password_hash")
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        return verifyPassword(row?.password_hash ?? DUMMY_PASSWORD_HASH, password);
+    }
+    async get(id) {
+        const row = await this.db
+            .selectFrom("accounts")
+            .selectAll()
+            .where("id", "=", id)
+            .executeTakeFirst();
+        return row && toAccount(row);
+    }
+    /** 按 id 升序分页，`after` 为上一页最后一个 id。 */
+    async list(opts) {
+        let q = this.db.selectFrom("accounts").selectAll().orderBy("id").limit(opts.limit);
+        if (opts.after !== undefined)
+            q = q.where("id", ">", opts.after);
+        return (await q.execute()).map(toAccount);
+    }
+    async setPassword(accountId, password) {
+        validatePassword(password);
+        const passwordHash = await hashPassword(password);
+        await this.db.transaction().execute((trx) => writePassword(trx, accountId, passwordHash));
+    }
+    /**
+     * 用户改密码（R24）：同一个 PG 事务里写新密码、吊销该账号除 `exceptSessionId` 外的全部会话
+     * （`sessions.revoked_at`）与全部个人访问令牌，要么全部生效要么都不生效。scrypt 在 BEGIN 之前算好。
+     * 返回被吊销的会话 id，调用方随后写 Redis 吊销标记（快速路径；鉴权以 PG `revoked_at` 为准，
+     * 标记写失败也不会让这些会话继续可用）。
+     */
+    async changePassword(accountId, password, exceptSessionId) {
+        const passwordHash = await this.hashNewPassword(password);
+        return this.db.transaction().execute(async (trx) => {
+            await writePassword(trx, accountId, passwordHash);
+            const sessions = await trx
+                .updateTable("sessions")
+                .set({ revoked_at: sql `now()` })
+                .where("account_id", "=", accountId)
+                .where("revoked_at", "is", null)
+                .where("id", "!=", exceptSessionId)
+                .returning("id")
+                .execute();
+            await trx
+                .updateTable("api_tokens")
+                .set({ revoked_at: sql `now()` })
+                .where("kind", "=", "personal")
+                .where("account_id", "=", accountId)
+                .where("revoked_at", "is", null)
+                .execute();
+            return sessions.map((r) => r.id);
+        });
+    }
+    async update(id, patch, actorAccountId, actorTokenId) {
+        return (await this.updateAccount(id, patch, actorAccountId, actorTokenId)).account;
+    }
+    /**
+     * 企业管理员改账号。停用（`status: "disabled"`）时在**同一个 PG 事务**里吊销该账号的全部会话
+     * （`sessions.revoked_at`）与个人访问令牌，要么都生效要么都不生效；返回被吊销的会话 id，
+     * 调用方在提交后写 Redis 吊销标记（快速路径，失败只记 warn：鉴权以 PG 为准）。
+     */
+    async updateAccount(id, patch, actorAccountId, actorTokenId) {
+        return this.db.transaction().execute(async (trx) => {
+            // 所有企业管理员写操作在同一把锁下串行，并在锁内复核发起人仍是活跃企业管理员：
+            // 既避免两个管理员并发互相撤销后一个都不剩，也让刚被撤销的管理员的在途请求失效
+            await lockEnterpriseAdminsAndAuthorize(trx, actorAccountId);
+            const before = await trx
+                .selectFrom("accounts")
+                .selectAll()
+                .where("id", "=", id)
+                .executeTakeFirst();
+            if (!before)
+                throw new ApiError("account.not_found", "Account not found");
+            return this.applyUpdate(trx, before, patch, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                detail: patch,
+            });
+        });
+    }
+    /**
+     * CLI 的 `capybara admin grant|revoke <login>`（没有发起账号）：按本地登录名在 {@link lockEnterpriseAdmins}
+     * 的事务里改企业管理员标记；撤销沿用 {@link updateAccount} 的「最后一个活跃企业管理员」复核
+     * （`account.last_enterprise_admin`），在锁内判定，与网页撤销并发也不会一个都不剩。审计 `account.updated`
+     * 不带发起账号，`detail.via = "cli"`。已是目标状态时不改、不写审计（`changed: false`）。
+     * 登录名不存在 → `account.not_found`。
+     */
+    async setEnterpriseAdminByLogin(login, isEnterpriseAdmin) {
+        let external;
+        try {
+            external = normalizeLogin(login);
+        }
+        catch {
+            throw new ApiError("account.not_found", "Account not found");
+        }
+        return this.db.transaction().execute(async (trx) => {
+            await lockEnterpriseAdmins(trx);
+            const before = await trx
+                .selectFrom("identities")
+                .innerJoin("accounts", "accounts.id", "identities.account_id")
+                .selectAll("accounts")
+                .where("identities.source", "=", "local")
+                .where("identities.external_id", "=", external)
+                .executeTakeFirst();
+            if (!before)
+                throw new ApiError("account.not_found", "Account not found");
+            if (before.is_enterprise_admin === isEnterpriseAdmin) {
+                return { account: toAccount(before), changed: false };
+            }
+            const patch = { isEnterpriseAdmin };
+            const { account } = await this.applyUpdate(trx, before, patch, {
+                detail: { ...patch, via: "cli" },
+            });
+            return { account, changed: true };
+        });
+    }
+    /**
+     * 已持企业管理员锁的事务内改账号：改行、复核「最后一个活跃企业管理员」、写审计 `account.updated`；
+     * 停用时吊销该账号的全部会话与个人令牌。
+     */
+    async applyUpdate(trx, before, patch, auditAs) {
+        const id = before.id;
+        const values = { updated_at: new Date() };
+        if (patch.displayName !== undefined)
+            values.display_name = patch.displayName;
+        if (patch.status !== undefined)
+            values.status = patch.status;
+        if (patch.isEnterpriseAdmin !== undefined)
+            values.is_enterprise_admin = patch.isEnterpriseAdmin;
+        const row = await trx
+            .updateTable("accounts")
+            .set(values)
+            .where("id", "=", id)
+            .returningAll()
+            .executeTakeFirstOrThrow();
+        const wasActiveAdmin = before.is_enterprise_admin && before.status === "active";
+        const isActiveAdmin = row.is_enterprise_admin && row.status === "active";
+        if (wasActiveAdmin && !isActiveAdmin && (await this.countEnterpriseAdmins(trx)) === 0) {
+            throw new ApiError("account.last_enterprise_admin", "Cannot remove the last active enterprise admin");
+        }
+        await audit(trx, {
+            ...(auditAs.actorAccountId !== undefined && { actorAccountId: auditAs.actorAccountId }),
+            ...(auditAs.actorTokenId !== undefined && { actorTokenId: auditAs.actorTokenId }),
+            action: "account.updated",
+            target: id,
+            detail: auditAs.detail,
+        });
+        let revokedSessionIds = [];
+        if (patch.status === "disabled") {
+            // 鉴权每次请求实时读账号状态，停用已立即生效；这里再吊销凭据，重新启用后旧凭据也不复活
+            const sessions = await trx
+                .updateTable("sessions")
+                .set({ revoked_at: sql `now()` })
+                .where("account_id", "=", id)
+                .where("revoked_at", "is", null)
+                .returning("id")
+                .execute();
+            await trx
+                .updateTable("api_tokens")
+                .set({ revoked_at: sql `now()` })
+                .where("kind", "=", "personal")
+                .where("account_id", "=", id)
+                .where("revoked_at", "is", null)
+                .execute();
+            revokedSessionIds = sessions.map((r) => r.id);
+        }
+        return { account: toAccount(row), revokedSessionIds };
+    }
+    /** 全部账号数（含停用的；后台概览）。 */
+    async count() {
+        const r = await this.db
+            .selectFrom("accounts")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** 活跃（status = active）的企业管理员数量。 */
+    async countEnterpriseAdmins(trx) {
+        const r = await (trx ?? this.db)
+            .selectFrom("accounts")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("is_enterprise_admin", "=", true)
+            .where("status", "=", "active")
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+}

package/dist/identity/api-tokens.d.ts

@@ -0,0 +1,73 @@
+import { type Transaction } from "kysely";
+import { z } from "zod";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+export interface ApiTokenRecord {
+    id: string;
+    kind: "personal" | "service";
+    accountId: string | null;
+    orgId: string | null;
+    role: "admin" | "member" | "guest" | null;
+    name: string;
+    createdAt: Date;
+    lastUsedAt: Date | null;
+    expiresAt: Date | null;
+}
+/** 令牌过期时间：完整 ISO 8601 datetime 字符串（`2099-01-01T00:00:00Z`），必须晚于当前时间；解析为 `Date`。 */
+export declare const FutureIsoDate: z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>;
+type Scope = {
+    accountId: string;
+} | {
+    orgId: string;
+};
+/**
+ * API 令牌服务：个人令牌（`cap_pat_`，代表账号本人）与服务令牌（`cap_svc_`，属于组织、带角色）。
+ * 库里只存 sha256；明文只在创建时返回一次。框架无关，由调用方注入 db。
+ */
+export declare class ApiTokenService {
+    private readonly db;
+    constructor(db: KernelDb);
+    createPersonal(accountId: string, input: {
+        name: string;
+        expiresAt?: Date | undefined;
+    }): Promise<{
+        token: string;
+        record: ApiTokenRecord;
+    }>;
+    createService(orgId: string, input: {
+        name: string;
+        role: "admin" | "member" | "guest";
+        createdBy: string;
+        expiresAt?: Date | undefined;
+    }): Promise<{
+        token: string;
+        record: ApiTokenRecord;
+    }>;
+    /**
+     * 以账号身份创建服务令牌：在组织行锁内实时重读发起人角色（spec 3.6 R5），
+     * 须具备 `org.tokens.manage` 且令牌角色不高于发起人角色，否则 `forbidden`；同一事务写审计（不含令牌明文）。
+     */
+    createServiceAs(orgId: string, actorAccountId: string, input: {
+        name: string;
+        role: "admin" | "member" | "guest";
+        expiresAt?: Date | undefined;
+    }): Promise<{
+        token: string;
+        record: ApiTokenRecord;
+    }>;
+    /**
+     * 以账号身份吊销组织服务令牌并写审计（同一事务）：同 createServiceAs 在组织行锁内实时复核发起人角色
+     * （组织不存在 / 已删除 → `org.not_found`，无 `org.tokens.manage` → `forbidden`）；不在该组织内 → `token.not_found`。
+     */
+    revokeServiceAs(orgId: string, tokenId: string, actorAccountId: string): Promise<void>;
+    /** 校验令牌明文；未知、已吊销、已过期或前缀不对一律返回 null。 */
+    authenticate(token: string): Promise<ApiTokenRecord | null>;
+    /** 列出该 scope 下未吊销的令牌（含已过期），按创建时间升序。 */
+    list(scope: Scope): Promise<ApiTokenRecord[]>;
+    /** 吊销令牌；令牌不存在、已吊销或不在该 scope 内 → `token.not_found`。 */
+    revoke(id: string, scope: Scope, trx?: Transaction<KernelDatabase>): Promise<void>;
+    revokeAllForOrg(orgId: string, trx?: Transaction<KernelDatabase>): Promise<void>;
+    revokeAllPersonal(accountId: string): Promise<void>;
+    private scoped;
+    private insertToken;
+}
+export {};

package/dist/identity/api-tokens.js

@@ -0,0 +1,197 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
+import { roleAtLeast } from "../orgs/roles.js";
+import { audit } from "./audit.js";
+import { sha256Hex } from "./hash.js";
+/** 令牌过期时间：完整 ISO 8601 datetime 字符串（`2099-01-01T00:00:00Z`），必须晚于当前时间；解析为 `Date`。 */
+export const FutureIsoDate = z.iso
+    .datetime()
+    .refine((s) => new Date(s).getTime() > Date.now(), "must be in the future")
+    .transform((s) => new Date(s));
+const PREFIX = { personal: "cap_pat_", service: "cap_svc_" };
+function toRecord(r) {
+    return {
+        id: r.id,
+        kind: r.kind,
+        accountId: r.account_id,
+        orgId: r.org_id,
+        role: r.role,
+        name: r.name,
+        createdAt: r.created_at,
+        lastUsedAt: r.last_used_at,
+        expiresAt: r.expires_at,
+    };
+}
+function validate(input) {
+    if (input.name.length < 1 || input.name.length > 100) {
+        throw new ApiError("validation_failed", "Token name must be 1-100 characters");
+    }
+    if (input.expiresAt !== undefined && !(input.expiresAt.getTime() > Date.now())) {
+        throw new ApiError("validation_failed", "Token expiry must be in the future");
+    }
+}
+/**
+ * API 令牌服务：个人令牌（`cap_pat_`，代表账号本人）与服务令牌（`cap_svc_`，属于组织、带角色）。
+ * 库里只存 sha256；明文只在创建时返回一次。框架无关，由调用方注入 db。
+ */
+export class ApiTokenService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async createPersonal(accountId, input) {
+        validate(input);
+        return this.insertToken(this.db, "personal", {
+            account_id: accountId,
+            org_id: null,
+            role: null,
+            name: input.name,
+            created_by: accountId,
+            expires_at: input.expiresAt ?? null,
+        });
+    }
+    async createService(orgId, input) {
+        validate(input);
+        return this.insertToken(this.db, "service", {
+            account_id: null,
+            org_id: orgId,
+            role: input.role,
+            name: input.name,
+            created_by: input.createdBy,
+            expires_at: input.expiresAt ?? null,
+        });
+    }
+    /**
+     * 以账号身份创建服务令牌：在组织行锁内实时重读发起人角色（spec 3.6 R5），
+     * 须具备 `org.tokens.manage` 且令牌角色不高于发起人角色，否则 `forbidden`；同一事务写审计（不含令牌明文）。
+     */
+    async createServiceAs(orgId, actorAccountId, input) {
+        validate(input);
+        return this.db.transaction().execute(async (t) => {
+            const { role } = await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.tokens.manage");
+            if (!roleAtLeast(role, input.role)) {
+                throw new ApiError("forbidden", "Insufficient organization role");
+            }
+            const created = await this.insertToken(t, "service", {
+                account_id: null,
+                org_id: orgId,
+                role: input.role,
+                name: input.name,
+                created_by: actorAccountId,
+                expires_at: input.expiresAt ?? null,
+            });
+            await audit(t, {
+                actorAccountId,
+                orgId,
+                action: "org.service_token.created",
+                target: created.record.id,
+                detail: { name: input.name, role: input.role },
+            });
+            return created;
+        });
+    }
+    /**
+     * 以账号身份吊销组织服务令牌并写审计（同一事务）：同 createServiceAs 在组织行锁内实时复核发起人角色
+     * （组织不存在 / 已删除 → `org.not_found`，无 `org.tokens.manage` → `forbidden`）；不在该组织内 → `token.not_found`。
+     */
+    async revokeServiceAs(orgId, tokenId, actorAccountId) {
+        await this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.tokens.manage");
+            await this.revoke(tokenId, { orgId }, t);
+            await audit(t, {
+                actorAccountId,
+                orgId,
+                action: "org.service_token.revoked",
+                target: tokenId,
+            });
+        });
+    }
+    /** 校验令牌明文；未知、已吊销、已过期或前缀不对一律返回 null。 */
+    async authenticate(token) {
+        const kind = token.startsWith(PREFIX.personal)
+            ? "personal"
+            : token.startsWith(PREFIX.service)
+                ? "service"
+                : undefined;
+        if (!kind)
+            return null;
+        const row = await this.db
+            .selectFrom("api_tokens")
+            .selectAll()
+            .where("token_hash", "=", sha256Hex(token))
+            .where("kind", "=", kind)
+            .where("revoked_at", "is", null)
+            .where((eb) => eb.or([eb("expires_at", "is", null), eb("expires_at", ">", sql `now()`)]))
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        // 节流：同一令牌 5 分钟内最多写一次 last_used_at
+        const touched = await this.db
+            .updateTable("api_tokens")
+            .set({ last_used_at: sql `now()` })
+            .where("id", "=", row.id)
+            .where((eb) => eb.or([
+            eb("last_used_at", "is", null),
+            eb("last_used_at", "<", sql `now() - interval '5 minutes'`),
+        ]))
+            .returning("last_used_at")
+            .executeTakeFirst();
+        const record = toRecord(row);
+        if (touched)
+            record.lastUsedAt = touched.last_used_at;
+        return record;
+    }
+    /** 列出该 scope 下未吊销的令牌（含已过期），按创建时间升序。 */
+    async list(scope) {
+        const rows = await this.scoped(this.db.selectFrom("api_tokens").selectAll(), scope)
+            .where("revoked_at", "is", null)
+            .orderBy("created_at")
+            .orderBy("id")
+            .execute();
+        return rows.map(toRecord);
+    }
+    /** 吊销令牌；令牌不存在、已吊销或不在该 scope 内 → `token.not_found`。 */
+    async revoke(id, scope, trx) {
+        const r = await this.scoped((trx ?? this.db).updateTable("api_tokens").set({ revoked_at: sql `now()` }), scope)
+            .where("id", "=", id)
+            .where("revoked_at", "is", null)
+            .executeTakeFirst();
+        if (r.numUpdatedRows === 0n)
+            throw new ApiError("token.not_found", "Token not found");
+    }
+    async revokeAllForOrg(orgId, trx) {
+        await (trx ?? this.db)
+            .updateTable("api_tokens")
+            .set({ revoked_at: sql `now()` })
+            .where("kind", "=", "service")
+            .where("org_id", "=", orgId)
+            .where("revoked_at", "is", null)
+            .execute();
+    }
+    async revokeAllPersonal(accountId) {
+        await this.db
+            .updateTable("api_tokens")
+            .set({ revoked_at: sql `now()` })
+            .where("kind", "=", "personal")
+            .where("account_id", "=", accountId)
+            .where("revoked_at", "is", null)
+            .execute();
+    }
+    scoped(q, scope) {
+        return "accountId" in scope
+            ? q.where("kind", "=", "personal").where("account_id", "=", scope.accountId)
+            : q.where("kind", "=", "service").where("org_id", "=", scope.orgId);
+    }
+    async insertToken(db, kind, values) {
+        const token = PREFIX[kind] + randomBytes(32).toString("base64url");
+        const row = await db
+            .insertInto("api_tokens")
+            .values({ id: randomUUID(), kind, token_hash: sha256Hex(token), ...values })
+            .returningAll()
+            .executeTakeFirstOrThrow();
+        return { token, record: toRecord(row) };
+    }
+}

package/dist/identity/audit.d.ts

@@ -0,0 +1,23 @@
+import type { Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+/** 写一条审计事件；`action` 用点分英文小写，如 `org.member.role_changed`。 */
+export declare function audit(db: KernelDb | Transaction<KernelDatabase>, e: {
+    actorAccountId?: string;
+    actorTokenId?: string;
+    orgId?: string;
+    action: string;
+    target?: string;
+    detail?: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * Connector audit actions written before the D17 rename (old rows are not rewritten, C27) -> the
+ * renamed action. Only these are listed, nothing is inferred from the `app.*` prefix: after D17
+ * "app" meant app bundles (`app.installed` etc., `plugin.org_installed` since phase 0a), which are
+ * unrelated to connectors (F-X).
+ */
+export declare const LEGACY_AUDIT_ACTIONS: Readonly<Record<string, string>>;
+/**
+ * 按 action 查询审计时与之同义的全部 action（含自身）：`connector.created` ↔ `app.created` 等，
+ * 只按 {@link LEGACY_AUDIT_ACTIONS} 显式映射；其余 action 只有自身。
+ */
+export declare function auditActionAliases(action: string): string[];