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

package/dist/identity/identity.module.js

@@ -0,0 +1,56 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { SetupLockModule } from "../admin/setup-lock.js";
+import { ExtensionRegistryModule } from "../extensions/registry.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { AccountsModule } from "./accounts.js";
+import { ApiTokenService } from "./api-tokens.js";
+import { IdentityBinding } from "./binding.js";
+import { EnterpriseAdminLockModule } from "./enterprise-admin.js";
+import { ExternalIdentities } from "./external.js";
+import { ExternalIdentityLock } from "./external-identity-lock.js";
+import { SessionService } from "./sessions.js";
+import { SettingsService } from "./settings.js";
+import { SsoFlow } from "./sso.js";
+/**
+ * Identity: accounts, sessions, API tokens, deployment settings and the enterprise admin lock,
+ * external identities with IM binding and third-party sign-in.
+ */
+let IdentityModule = class IdentityModule {
+};
+IdentityModule = __decorate([
+    Module({
+        imports: [
+            AccountsModule,
+            OrgLockModule,
+            SetupLockModule,
+            EnterpriseAdminLockModule,
+            ExtensionRegistryModule,
+        ],
+        providers: [
+            SessionService,
+            ApiTokenService,
+            SettingsService,
+            ExternalIdentityLock,
+            ExternalIdentities,
+            IdentityBinding,
+            SsoFlow,
+        ],
+        exports: [
+            AccountsModule,
+            SessionService,
+            ApiTokenService,
+            SettingsService,
+            EnterpriseAdminLockModule,
+            ExternalIdentities,
+            IdentityBinding,
+            SsoFlow,
+        ],
+    })
+], IdentityModule);
+export { IdentityModule };

package/dist/identity/me.controller.d.ts

@@ -1,22 +1,22 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
-import type { OrgsService } from "../orgs/orgs.service.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { OrgsService } from "../orgs/orgs.service.js";
 import type { OrgRole } from "../orgs/roles.js";
-import type { Account, AccountsService } from "./accounts.js";
-import { type ApiTokenRecord, type ApiTokenService } from "./api-tokens.js";
+import { type Account, AccountsService } from "./accounts.js";
+import { type ApiTokenRecord, ApiTokenService } from "./api-tokens.js";
 import { type Principal } from "./principal.js";
-import type { LoginRateLimiter } from "./rate-limit.js";
-import type { SessionService } from "./sessions.js";
-declare const ChangePasswordBody: z.ZodObject<{
+import { SessionService } from "./sessions.js";
+declare const ChangePasswordSchema: z.ZodObject<{
     currentPassword: z.ZodString;
     newPassword: z.ZodString;
 }, z.core.$strip>;
-declare const TokenBody: z.ZodObject<{
+declare const TokenSchema: z.ZodObject<{
     name: z.ZodString;
     expiresAt: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
 }, z.core.$strip>;
-declare const CurrentOrgBody: z.ZodObject<{
+declare const CurrentOrgSchema: z.ZodObject<{
     orgId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 type MembershipView = {
@@ -31,9 +31,9 @@ export declare class MeController {
     private readonly sessions;
     private readonly orgs;
     private readonly tokens;
-    private readonly limiter;
+    private readonly throttler;
     private readonly log;
-    constructor(accounts: AccountsService, sessions: SessionService, orgs: OrgsService, tokens: ApiTokenService, limiter: LoginRateLimiter, log: Logger);
+    constructor(accounts: AccountsService, sessions: SessionService, orgs: OrgsService, tokens: ApiTokenService, throttler: CredentialThrottler, log: Logger);
     me(principal: Principal): Promise<{
         account: Account;
         via: "session" | "pat";
@@ -41,15 +41,16 @@ export declare class MeController {
         memberships: MembershipView[];
     }>;
     /** 切换当前组织（仅 Web 会话）；`null` 清空。非成员或已软删除的组织 → `org.not_found`。 */
-    setCurrentOrg(principal: Principal, body: z.infer<typeof CurrentOrgBody>): Promise<void>;
+    setCurrentOrg(principal: Principal, body: z.infer<typeof CurrentOrgSchema>): Promise<void>;
     /**
      * 改密码：核对旧密码；成功后吊销该账号除当前会话外的所有会话，并吊销其全部个人访问令牌（R24）——
      * 三者在同一个 PG 事务里生效，之后再尽力写 Redis 吊销标记。
-     * 核对前先占用限流额度（scope `acct`：按账号 id 10 次、按客户端 IP 50 次，与登录的 IP 额度分开），
-     * 防止拿到会话的人无限次猜旧密码；超限 → 429 `auth.rate_limited`，核对成功后清零账号计数。
+     * Before the check one attempt is reserved (per account id 10, per client IP 50, apart from the
+     * login IP budget), so a stolen session cannot guess the old password forever; over the limit →
+     * 429 `auth.rate_limited`; a successful check clears the account counter.
      */
-    changePassword(principal: Principal, body: z.infer<typeof ChangePasswordBody>, req: FastifyRequest, reply: FastifyReply): Promise<void>;
-    createToken(principal: Principal, body: z.infer<typeof TokenBody>): Promise<{
+    changePassword(principal: Principal, body: z.infer<typeof ChangePasswordSchema>, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    createToken(principal: Principal, body: z.infer<typeof TokenSchema>): Promise<{
         token: string;
         record: ApiTokenRecord;
     }>;

package/dist/identity/me.controller.js

@@ -7,40 +7,50 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, Res, } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, Res, } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
-import { ACCOUNTS, API_TOKENS, KERNEL_LOG, ORGS, RATE_LIMITER, SESSIONS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
-import { FutureIsoDate } from "./api-tokens.js";
-import { clientMeta } from "./auth.controller.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
+import { OrgsService } from "../orgs/orgs.service.js";
+import { AccountsService } from "./accounts.js";
+import { ApiTokenService, FutureIsoDate } from "./api-tokens.js";
 import { MAX_PASSWORD_LENGTH } from "./login.js";
 import { CurrentPrincipal, requireUser, SessionOnly } from "./principal.js";
-/** 改密码时同一账号在窗口内允许核对旧密码的次数。 */
-const CHANGE_PASSWORD_LIMIT_PER_ACCOUNT = 10;
-const ChangePasswordBody = z.object({
+import { SessionService } from "./sessions.js";
+/** The credential throttlers of a password change (per account, per client IP). */
+const CHANGE_PASSWORD_THROTTLERS = ["change-password", "change-password-ip"];
+const ChangePasswordSchema = z.object({
     currentPassword: z.string().min(1),
     newPassword: z.string().min(12).max(MAX_PASSWORD_LENGTH),
 });
-const TokenBody = z.object({
+class ChangePasswordBody extends createZodDto(ChangePasswordSchema, "ChangePasswordBody") {
+}
+const TokenSchema = z.object({
     name: z.string().min(1).max(100),
     expiresAt: FutureIsoDate.optional(),
 });
-const CurrentOrgBody = z.object({ orgId: z.string().min(1).nullable() });
+class PersonalTokenBody extends createZodDto(TokenSchema, "PersonalTokenBody") {
+}
+const CurrentOrgSchema = z.object({ orgId: z.string().min(1).nullable() });
+class CurrentOrgBody extends createZodDto(CurrentOrgSchema, "CurrentOrgBody") {
+}
 /** 当前用户（`/api/v1/me`）。 */
 let MeController = class MeController {
     accounts;
     sessions;
     orgs;
     tokens;
-    limiter;
+    throttler;
     log;
-    constructor(accounts, sessions, orgs, tokens, limiter, log) {
+    constructor(accounts, sessions, orgs, tokens, throttler, log) {
         this.accounts = accounts;
         this.sessions = sessions;
         this.orgs = orgs;
         this.tokens = tokens;
-        this.limiter = limiter;
+        this.throttler = throttler;
         this.log = log;
     }
     async me(principal) {
@@ -65,24 +75,20 @@ let MeController = class MeController {
     /**
      * 改密码：核对旧密码；成功后吊销该账号除当前会话外的所有会话，并吊销其全部个人访问令牌（R24）——
      * 三者在同一个 PG 事务里生效，之后再尽力写 Redis 吊销标记。
-     * 核对前先占用限流额度（scope `acct`：按账号 id 10 次、按客户端 IP 50 次，与登录的 IP 额度分开），
-     * 防止拿到会话的人无限次猜旧密码；超限 → 429 `auth.rate_limited`，核对成功后清零账号计数。
+     * Before the check one attempt is reserved (per account id 10, per client IP 50, apart from the
+     * login IP budget), so a stolen session cannot guess the old password forever; over the limit →
+     * 429 `auth.rate_limited`; a successful check clears the account counter.
      */
     async changePassword(principal, body, req, reply) {
         const p = requireUser(principal);
         if (p.via !== "session") {
             throw new ApiError("auth.session_required", "This endpoint requires a web session");
         }
-        const { ip } = clientMeta(req);
-        const rl = await this.limiter.reserveScoped("acct", p.account.id, ip, CHANGE_PASSWORD_LIMIT_PER_ACCOUNT);
-        if (!rl.allowed) {
-            reply.header("retry-after", String(rl.retryAfterSeconds));
-            throw new ApiError("auth.rate_limited", "Too many failed password attempts; try again later");
-        }
+        await this.throttler.reserve(CHANGE_PASSWORD_THROTTLERS, req, reply);
         if (!(await this.accounts.verifyPassword(p.account.id, body.currentPassword))) {
             throw new ApiError("auth.invalid_credentials", "Current password is incorrect");
         }
-        await this.limiter.succeededScoped("acct", p.account.id, ip);
+        await this.throttler.succeeded(CHANGE_PASSWORD_THROTTLERS, req);
         // 新密码、吊销其他会话（PG revoked_at）与个人令牌在同一个 PG 事务里完成
         const revoked = await this.accounts.changePassword(p.account.id, body.newPassword, p.sessionId);
         try {
@@ -118,14 +124,14 @@ __decorate([
     SessionOnly(),
     HttpCode(204),
     __param(0, CurrentPrincipal()),
-    __param(1, Body(new ZodPipe(CurrentOrgBody)))
+    __param(1, ZBody(CurrentOrgBody))
 ], MeController.prototype, "setCurrentOrg", null);
 __decorate([
     Put("password"),
     SessionOnly(),
     HttpCode(204),
     __param(0, CurrentPrincipal()),
-    __param(1, Body(new ZodPipe(ChangePasswordBody))),
+    __param(1, ZBody(ChangePasswordBody)),
     __param(2, Req()),
     __param(3, Res({ passthrough: true }))
 ], MeController.prototype, "changePassword", null);
@@ -133,7 +139,7 @@ __decorate([
     Post("tokens"),
     SessionOnly(),
     __param(0, CurrentPrincipal()),
-    __param(1, Body(new ZodPipe(TokenBody)))
+    __param(1, ZBody(PersonalTokenBody))
 ], MeController.prototype, "createToken", null);
 __decorate([
     Get("tokens"),
@@ -149,11 +155,11 @@ __decorate([
 ], MeController.prototype, "revokeToken", null);
 MeController = __decorate([
     Controller("api/v1/me"),
-    __param(0, Inject(ACCOUNTS)),
-    __param(1, Inject(SESSIONS)),
-    __param(2, Inject(ORGS)),
-    __param(3, Inject(API_TOKENS)),
-    __param(4, Inject(RATE_LIMITER)),
-    __param(5, Inject(KERNEL_LOG))
+    __param(0, Inject(AccountsService)),
+    __param(1, Inject(SessionService)),
+    __param(2, Inject(OrgsService)),
+    __param(3, Inject(ApiTokenService)),
+    __param(4, Inject(CredentialThrottler)),
+    __param(5, Inject(KERNEL_LOGGER))
 ], MeController);
 export { MeController };

package/dist/identity/sessions.d.ts

@@ -1,6 +1,8 @@
 import type { Redis } from "ioredis";
 import type { Keyring } from "../ctx/secrets.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 import { type Account } from "./accounts.js";
 export interface IssuedSession {
     sessionId: string;
@@ -16,25 +18,24 @@ export declare const REFRESH_RACE_GRACE_MS = 30000;
  * Web 会话服务：短期 access token（HS256 JWT，密钥由主密钥环派生）+ PG 中可吊销、一次一换的 refresh token。
  * 吊销会在 Redis 写 `capk:revoked-sid:<sid>`（TTL 覆盖任何配置下 access token 的最长剩余寿命），使所有副本立即拒绝该会话的 access token；
  * 验证 access token 时还会读 PG 的 `sessions.revoked_at`，Redis 丢数据也不会让已吊销的会话复活。
- * 框架无关，由调用方注入依赖。
+ * Token lifetimes are `auth.accessTokenTtlSeconds` / `auth.refreshTokenTtlDays`, read per session.
  */
 export declare class SessionService {
     private readonly db;
+    readonly txHost: TransactionHost;
     private readonly redis;
-    private readonly opts;
+    private readonly config;
     private readonly keys;
-    constructor(db: KernelDb, redis: Redis, keyring: Keyring, opts: {
-        accessTtlSeconds: number;
-        refreshTtlDays: number;
-    });
+    constructor(db: KernelDb, txHost: TransactionHost, redis: Redis, keyring: Keyring, config: Pick<KernelConfigService, "get">);
     /**
-     * 新建会话。传入 `trx` 时会话行在调用方的事务里写入（如初始化、凭邀请注册：与账号同一事务，
-     * 失败整体回滚）；Cookie 由调用方在提交之后再设置。
+     * Creates a session, in the context's transaction when there is one (setup and invitation
+     * signup write it with the account, rolled back together); the caller sets the cookies after the
+     * commit.
      */
     create(accountId: string, meta: {
         userAgent?: string;
         ip?: string;
-    }, trx?: KernelDb): Promise<IssuedSession>;
+    }): Promise<IssuedSession>;
     refresh(refreshToken: string, meta: {
         userAgent?: string;
         ip?: string;
@@ -73,6 +74,7 @@ export declare class SessionService {
      * 不会留下指向已移出组织的 `current_org_id`。非成员或组织已软删除 → `org.not_found`；`null` 清空，不查成员关系。
      */
     switchCurrentOrg(sessionId: string, accountId: string, orgId: string | null): Promise<void>;
+    private switchIn;
     /** 有效（未吊销且未过期）的会话；否则返回 undefined。 */
     get(sessionId: string): Promise<{
         id: string;

package/dist/identity/sessions.js

@@ -1,8 +1,23 @@
+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 { randomBytes, randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
 import { errors as joseErrors, jwtVerify, SignJWT } from "jose";
 import { sql } from "kysely";
 import { ACCESS_TOKEN_TTL_MAX_SECONDS } from "../config/schema.js";
 import { ApiError } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.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 { KEYRING, REDIS } from "../infra/tokens.js";
 import { ACCOUNT_COLUMNS, toAccount } from "./accounts.js";
 import { sha256Hex } from "./hash.js";
 /** 旧 refresh token 在被轮换后多久内重放视为并发刷新（不吊销会话）。 */
@@ -24,27 +39,31 @@ class UnknownKidError extends Error {
  * Web 会话服务：短期 access token（HS256 JWT，密钥由主密钥环派生）+ PG 中可吊销、一次一换的 refresh token。
  * 吊销会在 Redis 写 `capk:revoked-sid:<sid>`（TTL 覆盖任何配置下 access token 的最长剩余寿命），使所有副本立即拒绝该会话的 access token；
  * 验证 access token 时还会读 PG 的 `sessions.revoked_at`，Redis 丢数据也不会让已吊销的会话复活。
- * 框架无关，由调用方注入依赖。
+ * Token lifetimes are `auth.accessTokenTtlSeconds` / `auth.refreshTokenTtlDays`, read per session.
  */
-export class SessionService {
+let SessionService = class SessionService {
     db;
+    txHost;
     redis;
-    opts;
+    config;
     keys;
-    constructor(db, redis, keyring, opts) {
+    constructor(db, txHost, redis, keyring, config) {
         this.db = db;
+        this.txHost = txHost;
         this.redis = redis;
-        this.opts = opts;
+        this.config = config;
         this.keys = keyring.deriveKey(ACCESS_KEY_INFO);
     }
     /**
-     * 新建会话。传入 `trx` 时会话行在调用方的事务里写入（如初始化、凭邀请注册：与账号同一事务，
-     * 失败整体回滚）；Cookie 由调用方在提交之后再设置。
+     * Creates a session, in the context's transaction when there is one (setup and invitation
+     * signup write it with the account, rolled back together); the caller sets the cookies after the
+     * commit.
      */
-    async create(accountId, meta, trx) {
+    async create(accountId, meta) {
         const id = randomUUID();
         const refreshToken = newRefreshToken();
-        const row = await (trx ?? this.db)
+        const refreshTtlDays = this.config.get().auth.refreshTokenTtlDays;
+        const row = await this.db
             .insertInto("sessions")
             .values({
             id,
@@ -52,7 +71,7 @@ export class SessionService {
             refresh_hash: sha256Hex(refreshToken),
             user_agent: meta.userAgent ?? null,
             ip: meta.ip ?? null,
-            expires_at: sql `now() + make_interval(days => ${this.opts.refreshTtlDays})`,
+            expires_at: sql `now() + make_interval(days => ${refreshTtlDays})`,
         })
             .returning(["expires_at"])
             .executeTakeFirstOrThrow();
@@ -236,37 +255,38 @@ export class SessionService {
     async switchCurrentOrg(sessionId, accountId, orgId) {
         if (orgId === null)
             return this.setCurrentOrg(sessionId, null);
-        await this.db.transaction().execute(async (t) => {
-            // 加锁顺序与移出成员一致：先组织行、再成员关系行（sessions.current_org_id 的外键检查也会锁组织行，
-            // 若先锁成员关系，会与持有组织行锁的移出成员互相等待而死锁）
-            const org = await t
-                .selectFrom("orgs")
-                .select("id")
-                .where("id", "=", orgId)
-                .where("deleted_at", "is", null)
+        await this.switchIn(sessionId, accountId, orgId);
+    }
+    async switchIn(sessionId, accountId, orgId) {
+        // 加锁顺序与移出成员一致：先组织行、再成员关系行（sessions.current_org_id 的外键检查也会锁组织行，
+        // 若先锁成员关系，会与持有组织行锁的移出成员互相等待而死锁）
+        const org = await this.db
+            .selectFrom("orgs")
+            .select("id")
+            .where("id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .forShare()
+            .executeTakeFirst();
+        const m = org &&
+            (await this.db
+                .selectFrom("memberships")
+                .select("role")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", accountId)
                 .forShare()
-                .executeTakeFirst();
-            const m = org &&
-                (await t
-                    .selectFrom("memberships")
-                    .select("role")
-                    .where("org_id", "=", orgId)
-                    .where("account_id", "=", accountId)
-                    .forShare()
-                    .executeTakeFirst());
-            if (!m)
-                throw new ApiError("org.not_found", "Organization not found");
-            const r = await t
-                .updateTable("sessions")
-                .set({ current_org_id: orgId })
-                .where("id", "=", sessionId)
-                .where("revoked_at", "is", null)
-                .where("expires_at", ">", sql `now()`)
-                .executeTakeFirst();
-            if (r.numUpdatedRows === 0n) {
-                throw new ApiError("auth.session_revoked", "Session has been revoked");
-            }
-        });
+                .executeTakeFirst());
+        if (!m)
+            throw new ApiError("org.not_found", "Organization not found");
+        const r = await this.db
+            .updateTable("sessions")
+            .set({ current_org_id: orgId })
+            .where("id", "=", sessionId)
+            .where("revoked_at", "is", null)
+            .where("expires_at", ">", sql `now()`)
+            .executeTakeFirst();
+        if (r.numUpdatedRows === 0n) {
+            throw new ApiError("auth.session_revoked", "Session has been revoked");
+        }
     }
     /** 有效（未吊销且未过期）的会话；否则返回 undefined。 */
     async get(sessionId) {
@@ -287,7 +307,7 @@ export class SessionService {
     };
     async issue(sessionId, accountId, refreshToken, refreshExpiresAt) {
         const iat = Math.floor(Date.now() / 1000);
-        const exp = iat + this.opts.accessTtlSeconds;
+        const exp = iat + this.config.get().auth.accessTokenTtlSeconds;
         const accessToken = await new SignJWT({ sid: sessionId })
             .setProtectedHeader({ alg: "HS256", kid: this.keys.currentId })
             .setSubject(accountId)
@@ -303,4 +323,16 @@ export class SessionService {
             refreshExpiresAt,
         };
     }
-}
+};
+__decorate([
+    Transactional()
+], SessionService.prototype, "switchIn", null);
+SessionService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(REDIS)),
+    __param(3, Inject(KEYRING)),
+    __param(4, Inject(KernelConfigService))
+], SessionService);
+export { SessionService };

package/dist/identity/settings.d.ts

@@ -1,7 +1,9 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import type { Transaction } from "kysely";
 import { z } from "zod";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { EnterpriseAdminLock } from "./enterprise-admin.js";
 /** 沙箱 cpu（核）与内存（MB）覆盖的范围（C19）。 */
 export declare const SANDBOX_CPU_RANGE: {
     readonly min: 0.25;
@@ -91,31 +93,35 @@ export type DeploymentSettingsPatch = z.infer<typeof DEPLOYMENT_SETTINGS_PATCH>;
  * 读某个组织的沙箱限额覆盖（创建沙箱、组织设置页用）；每次实时读 PG，多副本下改动立即生效。
  * 只解析这个组织的那一条：没有设置、组织不在其中、或这一条存量值非法 → undefined；别的组织的条目非法不影响它。
  */
-export declare function readSandboxLimitOverride(db: KernelDb, orgId: string): Promise<SandboxLimitOverride | undefined>;
+export declare function readSandboxLimitOverride(db: KernelSchemaDb, orgId: string): Promise<SandboxLimitOverride | undefined>;
 /**
  * One organization's sub-agent limit override, read live from PG (so a change applies on every
  * replica at once); in the caller's transaction when one is given. Only this organization's entry
  * is parsed: no setting, no entry, or an invalid stored entry → undefined.
  */
-export declare function readSubagentLimitOverride(db: KernelDb | Transaction<KernelDatabase>, orgId: string): Promise<SubagentLimitOverride | undefined>;
+export declare function readSubagentLimitOverride(db: KernelSchemaDb, orgId: string): Promise<SubagentLimitOverride | undefined>;
 /**
  * When orgs may not create their own connectors / skills (deployment setting `customConnectors` /
  * `customSkills` is `deny`, C22) throws `catalog.custom_disabled`: install from the enterprise
  * catalog only. Reads PG live every time (can read in the caller's transaction); an invalid stored
  * value counts as allow.
  */
-export declare function assertCustomAllowed(db: KernelDb | Transaction<KernelDatabase>, key: "customConnectors" | "customSkills"): Promise<void>;
-/** 部署级设置：每个键一行，读时缺省用默认值。 */
+export declare function assertCustomAllowed(db: KernelSchemaDb, key: "customConnectors" | "customSkills"): Promise<void>;
+/** Deployment settings: one row per key, defaults for missing keys. */
 export declare class SettingsService {
     private readonly db;
-    private readonly log?;
-    constructor(db: KernelDb, log?: Pick<Logger, "warn"> | undefined);
+    readonly txHost: TransactionHost;
+    private readonly adminLock;
+    private readonly log;
+    constructor(db: KernelDb, txHost: TransactionHost, adminLock: EnterpriseAdminLock, log: Pick<KernelLogger, "warn">);
     /**
-     * 读全部设置；传 `trx` 时在该事务内读（调用方已持有事务连接时不再占用池里的第二个连接）。
-     * 逐个键校验：库里某个键的值非法时该键用默认值并 warn 点名，其余合法的键照常生效；
-     * 不认识的键（如新版本写入的）忽略。
+     * Reads every setting, in the context's transaction when there is one (a caller holding a
+     * transaction connection does not take a second one from the pool). Each key is validated on
+     * its own: an invalid stored value falls back to the default with a warning naming the key, the
+     * valid keys apply; unknown keys (written by a newer version) are ignored.
      */
-    get(trx?: Transaction<KernelDatabase>): Promise<DeploymentSettings>;
-    /** 更新设置：事务内取企业管理员锁并复核发起人仍是活跃企业管理员（否则 `forbidden`）。 */
+    get(): Promise<DeploymentSettings>;
+    /** Updates settings under the enterprise admin lock, re-checking the actor (else `forbidden`). */
     update(patch: DeploymentSettingsPatch, actorAccountId: string, actorTokenId?: string): Promise<DeploymentSettings>;
+    private write;
 }