@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.2

package/dist/identity/accounts.js

@@ -1,8 +1,22 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { randomUUID } from "node:crypto";
+import { Inject, Injectable, Module } from "@nestjs/common";
 import { sql } from "kysely";
+import { SetupLock, SetupLockModule } from "../admin/setup-lock.js";
 import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
 import { audit } from "./audit.js";
-import { lockEnterpriseAdmins, lockEnterpriseAdminsAndAuthorize } from "./enterprise-admin.js";
+import { EnterpriseAdminLock, EnterpriseAdminLockModule } 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 使用）。 */
@@ -38,97 +52,93 @@ async function prepareLocal(input, passwordHash) {
     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 {
+/**
+ * Accounts: local account creation, authentication and administration. Every write is
+ * `@Transactional` (joining the caller's transaction when there is one); scrypt runs before any
+ * transaction opens.
+ */
+let AccountsService = class AccountsService {
     db;
-    constructor(db) {
+    txHost;
+    adminLock;
+    setupLock;
+    constructor(db, txHost, adminLock, setupLock) {
         this.db = db;
+        this.txHost = txHost;
+        this.adminLock = adminLock;
+        this.setupLock = setupLock;
     }
-    /** 校验密码长度并算出哈希（scrypt，较慢）：供需要在事务之外先算好哈希的调用方使用。 */
+    /** Checks the password length and hashes it (scrypt, slow): for callers that hash before their transaction opens. */
     async hashNewPassword(password) {
         validatePassword(password);
         return hashPassword(password);
     }
     /**
-     * 建本地账号。传 `trx` 时在调用方的事务内插入；在事务内调用时应先在事务**之外**用 `hashNewPassword`
-     * 算好 `passwordHash` 传进来，避免 scrypt 期间连接处于 idle in transaction。
+     * Creates a local account, in the caller's transaction when there is one. A caller inside a
+     * transaction hashes first with {@link hashNewPassword} and passes `passwordHash`, so the
+     * connection is never idle in transaction during scrypt.
      */
-    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);
+    async createLocal(input, passwordHash) {
+        return this.insertLocal(await prepareLocal(input, passwordHash));
     }
     /**
-     * 企业管理员建本地账号（可同时设为企业管理员）：事务内取企业管理员锁并复核发起人仍是活跃企业管理员
-     * （否则 `forbidden`），建号并写审计 `account.created`。密码哈希在取锁之前算好，不在锁内跑 scrypt。
+     * An enterprise admin creates a local account (optionally an enterprise admin): under the
+     * enterprise admin lock, re-checks that the actor is still an active enterprise admin (else
+     * `forbidden`), creates the account and audits `account.created`. The hash is computed before
+     * the lock.
      */
     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;
+        return this.createByAdminIn(await prepareLocal(input), actorAccountId, actorTokenId);
+    }
+    async createByAdminIn(prepared, actorAccountId, actorTokenId) {
+        await this.adminLock.lockAndAuthorize(actorAccountId);
+        const a = await this.insertLocal(prepared);
+        await audit(this.db.db, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            action: "account.created",
+            target: a.id,
+            detail: { enterpriseAdmin: a.isEnterpriseAdmin },
         });
+        return a;
+    }
+    /**
+     * CLI: creates an enterprise admin without checking whether the deployment is set up; a taken
+     * login → `account.login_taken`.
+     */
+    async createEnterpriseAdmin(input) {
+        return this.insertEnterpriseAdmin(input, await this.hashNewPassword(input.password));
+    }
+    /**
+     * CLI `admin create --if-none`: creates an enterprise admin only when no active one exists. The
+     * check and the insert run in one transaction under {@link SetupLock}, the lock the web setup
+     * takes, so concurrent runs (and a concurrent web setup) create exactly one. Returns undefined
+     * when an active enterprise admin already exists; a taken login still throws
+     * `account.login_taken`.
+     */
+    async createEnterpriseAdminIfNone(input) {
+        return this.createEnterpriseAdminIfNoneIn(input, await this.hashNewPassword(input.password));
+    }
+    async createEnterpriseAdminIfNoneIn(input, passwordHash) {
+        await this.setupLock.lock();
+        if ((await this.countEnterpriseAdmins()) > 0)
+            return undefined;
+        return this.insertEnterpriseAdmin(input, passwordHash);
+    }
+    async insertEnterpriseAdmin(input, passwordHash) {
+        const account = await this.createLocal({
+            login: input.login,
+            password: input.password,
+            displayName: input.displayName,
+            enterpriseAdmin: true,
+            ...(input.email !== undefined && { email: input.email }),
+        }, passwordHash);
+        await audit(this.db.db, {
+            action: "account.created",
+            target: account.id,
+            detail: { enterpriseAdmin: true, via: "cli" },
+        });
+        return account;
     }
     async authenticateLocal(login, password) {
         // 超长密码不可能正确（validatePassword 上限 256），不跑 scrypt 也不查库，免得被超长输入拖慢；
@@ -200,70 +210,71 @@ export class AccountsService {
     }
     async setPassword(accountId, password) {
         validatePassword(password);
-        const passwordHash = await hashPassword(password);
-        await this.db.transaction().execute((trx) => writePassword(trx, accountId, passwordHash));
+        await this.writePassword(accountId, await hashPassword(password));
     }
     /**
-     * 用户改密码（R24）：同一个 PG 事务里写新密码、吊销该账号除 `exceptSessionId` 外的全部会话
-     * （`sessions.revoked_at`）与全部个人访问令牌，要么全部生效要么都不生效。scrypt 在 BEGIN 之前算好。
-     * 返回被吊销的会话 id，调用方随后写 Redis 吊销标记（快速路径；鉴权以 PG `revoked_at` 为准，
-     * 标记写失败也不会让这些会话继续可用）。
+     * A person changes their password (R24): one PG transaction writes the new password and revokes
+     * the account's sessions except `exceptSessionId` (`sessions.revoked_at`) and all its personal
+     * access tokens; all or nothing. scrypt runs before BEGIN. Returns the revoked session ids; the
+     * caller then writes the Redis revocation markers (the fast path: auth reads PG `revoked_at`,
+     * so a failed marker never keeps a session usable).
      */
     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);
-        });
+        return this.changePasswordIn(accountId, await this.hashNewPassword(password), exceptSessionId);
+    }
+    async changePasswordIn(accountId, passwordHash, exceptSessionId) {
+        await this.writePassword(accountId, passwordHash);
+        const sessions = await this.db
+            .updateTable("sessions")
+            .set({ revoked_at: sql `now()` })
+            .where("account_id", "=", accountId)
+            .where("revoked_at", "is", null)
+            .where("id", "!=", exceptSessionId)
+            .returning("id")
+            .execute();
+        await this.db
+            .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 为准）。
+     * An enterprise admin changes an account. Disabling (`status: "disabled"`) revokes the
+     * account's sessions (`sessions.revoked_at`) and personal tokens in **the same PG transaction**,
+     * all or nothing; returns the revoked session ids, whose Redis markers the caller writes after
+     * the commit (the fast path; a failure is only a warning: auth reads 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,
-            });
+        // Every enterprise admin write is serialized by one lock and re-checks the actor under it: two
+        // admins revoking each other concurrently cannot leave none, and a just-revoked admin's
+        // request in flight fails
+        await this.adminLock.lockAndAuthorize(actorAccountId);
+        const before = await this.db
+            .selectFrom("accounts")
+            .selectAll()
+            .where("id", "=", id)
+            .executeTakeFirst();
+        if (!before)
+            throw new ApiError("account.not_found", "Account not found");
+        return this.applyUpdate(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`。
+     * The CLI's `capybara admin grant|revoke <login>` (no actor account): changes the enterprise
+     * admin flag by local login under the enterprise admin lock; revoking keeps the
+     * {@link updateAccount} "last active enterprise admin" check (`account.last_enterprise_admin`),
+     * decided under the lock, so it cannot race a web revoke into none. Audit `account.updated`
+     * without an actor, `detail.via = "cli"`. Already in the target state → no change and no audit
+     * (`changed: false`). Unknown login → `account.not_found`.
      */
     async setEnterpriseAdminByLogin(login, isEnterpriseAdmin) {
         let external;
@@ -273,32 +284,107 @@ export class AccountsService {
         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 };
+        return this.setEnterpriseAdminIn(external, isEnterpriseAdmin);
+    }
+    async setEnterpriseAdminIn(external, isEnterpriseAdmin) {
+        await this.adminLock.lock();
+        const before = await this.db
+            .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(before, patch, {
+            detail: { ...patch, via: "cli" },
         });
+        return { account, changed: true };
+    }
+    /** 全部账号数（含停用的；后台概览）。 */
+    async count() {
+        const r = await this.db
+            .selectFrom("accounts")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** Active (status = active) enterprise admins, in the context's transaction when there is one. */
+    async countEnterpriseAdmins() {
+        const r = await this.db
+            .selectFrom("accounts")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("is_enterprise_admin", "=", true)
+            .where("status", "=", "active")
+            .executeTakeFirstOrThrow();
+        return Number(r.n);
+    }
+    /** Inserts the account, its local identity and password; a taken login → `account.login_taken`. */
+    async insertLocal(p) {
+        const { input, login, passwordHash } = p;
+        const id = randomUUID();
+        const row = await this.db
+            .insertInto("accounts")
+            .values({
+            id,
+            display_name: input.displayName,
+            email: input.email ?? null,
+            is_enterprise_admin: input.enterpriseAdmin ?? false,
+        })
+            .returningAll()
+            .executeTakeFirstOrThrow();
+        try {
+            await this.db
+                .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 this.db
+            .insertInto("local_passwords")
+            .values({ account_id: id, password_hash: passwordHash })
+            .execute();
+        return toAccount(row);
+    }
+    /** Writes (or replaces) the local password hash; a missing account → `account.not_found`. */
+    async writePassword(accountId, passwordHash) {
+        const exists = await this.db
+            .selectFrom("accounts")
+            .select("id")
+            .where("id", "=", accountId)
+            .executeTakeFirst();
+        if (!exists)
+            throw new ApiError("account.not_found", "Account not found");
+        await this.db
+            .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();
     }
     /**
-     * 已持企业管理员锁的事务内改账号：改行、复核「最后一个活跃企业管理员」、写审计 `account.updated`；
-     * 停用时吊销该账号的全部会话与个人令牌。
+     * Changes the account under the enterprise admin lock the caller holds: updates the row,
+     * re-checks "the last active enterprise admin", audits `account.updated`; disabling revokes the
+     * account's sessions and personal tokens.
      */
-    async applyUpdate(trx, before, patch, auditAs) {
+    async applyUpdate(before, patch, auditAs) {
         const id = before.id;
         const values = { updated_at: new Date() };
         if (patch.displayName !== undefined)
@@ -307,7 +393,7 @@ export class AccountsService {
             values.status = patch.status;
         if (patch.isEnterpriseAdmin !== undefined)
             values.is_enterprise_admin = patch.isEnterpriseAdmin;
-        const row = await trx
+        const row = await this.db
             .updateTable("accounts")
             .set(values)
             .where("id", "=", id)
@@ -315,10 +401,10 @@ export class AccountsService {
             .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) {
+        if (wasActiveAdmin && !isActiveAdmin && (await this.countEnterpriseAdmins()) === 0) {
             throw new ApiError("account.last_enterprise_admin", "Cannot remove the last active enterprise admin");
         }
-        await audit(trx, {
+        await audit(this.db.db, {
             ...(auditAs.actorAccountId !== undefined && { actorAccountId: auditAs.actorAccountId }),
             ...(auditAs.actorTokenId !== undefined && { actorTokenId: auditAs.actorTokenId }),
             action: "account.updated",
@@ -327,15 +413,16 @@ export class AccountsService {
         });
         let revokedSessionIds = [];
         if (patch.status === "disabled") {
-            // 鉴权每次请求实时读账号状态，停用已立即生效；这里再吊销凭据，重新启用后旧凭据也不复活
-            const sessions = await trx
+            // Auth reads the account status on every request, so disabling is effective at once; the
+            // credentials are revoked too, so re-enabling does not bring old ones back
+            const sessions = await this.db
                 .updateTable("sessions")
                 .set({ revoked_at: sql `now()` })
                 .where("account_id", "=", id)
                 .where("revoked_at", "is", null)
                 .returning("id")
                 .execute();
-            await trx
+            await this.db
                 .updateTable("api_tokens")
                 .set({ revoked_at: sql `now()` })
                 .where("kind", "=", "personal")
@@ -346,22 +433,54 @@ export class AccountsService {
         }
         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);
-    }
-}
+};
+__decorate([
+    Transactional()
+], AccountsService.prototype, "createByAdminIn", null);
+__decorate([
+    Transactional()
+], AccountsService.prototype, "createEnterpriseAdminIfNoneIn", null);
+__decorate([
+    Transactional()
+], AccountsService.prototype, "insertEnterpriseAdmin", null);
+__decorate([
+    Transactional()
+], AccountsService.prototype, "changePasswordIn", null);
+__decorate([
+    Transactional()
+], AccountsService.prototype, "updateAccount", null);
+__decorate([
+    Transactional()
+], AccountsService.prototype, "setEnterpriseAdminIn", null);
+__decorate([
+    Transactional()
+], AccountsService.prototype, "insertLocal", null);
+__decorate([
+    Transactional()
+], AccountsService.prototype, "writePassword", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AccountsService.prototype, "applyUpdate", null);
+AccountsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(EnterpriseAdminLock)),
+    __param(3, Inject(SetupLock))
+], AccountsService);
+export { AccountsService };
+/**
+ * {@link AccountsService} with the locks it takes; needs only the database. Part of
+ * `IdentityModule`; the CLI's `admin create` / `admin grant` contexts and `@capybara-hq/testing`'s
+ * `createLocalAccount` import it alone.
+ */
+let AccountsModule = class AccountsModule {
+};
+AccountsModule = __decorate([
+    Module({
+        imports: [SetupLockModule, EnterpriseAdminLockModule],
+        providers: [AccountsService],
+        exports: [AccountsService],
+    })
+], AccountsModule);
+export { AccountsModule };

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

@@ -1,6 +1,7 @@
-import { type Transaction } from "kysely";
 import { z } from "zod";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
 export interface ApiTokenRecord {
     id: string;
     kind: "personal" | "service";
@@ -21,11 +22,13 @@ type Scope = {
 };
 /**
  * API 令牌服务：个人令牌（`cap_pat_`，代表账号本人）与服务令牌（`cap_svc_`，属于组织、带角色）。
- * 库里只存 sha256；明文只在创建时返回一次。框架无关，由调用方注入 db。
+ * 库里只存 sha256；明文只在创建时返回一次。
  */
 export declare class ApiTokenService {
     private readonly db;
-    constructor(db: KernelDb);
+    readonly txHost: TransactionHost;
+    private readonly orgLock;
+    constructor(db: KernelDb, txHost: TransactionHost, orgLock: OrgLock);
     createPersonal(accountId: string, input: {
         name: string;
         expiresAt?: Date | undefined;
@@ -63,9 +66,10 @@ export declare class ApiTokenService {
     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>;
+    /** Revokes a token (in the context's transaction when there is one); missing, revoked or out of scope → `token.not_found`. */
+    revoke(id: string, scope: Scope): Promise<void>;
+    /** Revokes the org's service tokens (in the context's transaction when there is one). */
+    revokeAllForOrg(orgId: string): Promise<void>;
     revokeAllPersonal(accountId: string): Promise<void>;
     private scoped;
     private insertToken;