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

package/dist/http/app.js

@@ -1,52 +1,40 @@
-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 "reflect-metadata";
-import { randomUUID } from "node:crypto";
 import fastifyCookie from "@fastify/cookie";
-import { Module } from "@nestjs/common";
-import { APP_FILTER, NestFactory } from "@nestjs/core";
-import { FastifyAdapter } from "@nestjs/platform-fastify";
 import { ApiError, errorBody } from "../errors.js";
-import { authorizeEnterpriseAdmin } from "../identity/auth.guard.js";
+import { AccountsService } from "../identity/accounts.js";
+import { ApiTokenService } from "../identity/api-tokens.js";
+import { authenticateOrgUploader, authorizeSuperAdmin, } from "../identity/auth.guard.js";
+import { SessionService } from "../identity/sessions.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 import { withLogContext } from "../log-context.js";
-import { ErrorFilter, redactPath } from "./error.filter.js";
-import { registerGatewayRoutes } from "./gateway.module.js";
-import { HealthController } from "./health.controller.js";
-import { NestLogAdapter } from "./nest-logger.js";
+import { authorizeOrgAction } from "../orgs/org.guard.js";
+import { redactPath } from "./error.filter.js";
+import { registerGatewayRoutes } from "./gateway-routes.js";
 import { createPluginRouter, registerPluginDispatch, staticRouteTable, } from "./plugin-dispatch.js";
-import { ACCOUNTS, API_TOKENS, HEALTH_OPTIONS, KERNEL_LOG, SESSIONS } from "./tokens.js";
 /** The extension package upload route (Fastify route template). */
 export const EXTENSION_PACKAGE_UPLOAD_ROUTE = "/api/v1/admin/extensions/packages/file";
 /** The plugin package upload route of the catalog import (Fastify route template). */
 export const CATALOG_UPLOAD_ROUTE = "/api/v1/admin/catalog/import/file";
+/** The platform skill version upload route (a skill package zip as the raw body). */
+export const COMPONENT_SKILL_UPLOAD_ROUTE = "/api/v1/admin/components/skill/:id/versions";
 /**
  * The upload routes that take raw bytes (`application/octet-stream`, limit `packages.maxBytes`,
- * the enterprise admin is authenticated before the body is read).
+ * the super admin is authenticated before the body is read).
  */
 export const PACKAGE_UPLOAD_ROUTES = new Set([
     EXTENSION_PACKAGE_UPLOAD_ROUTE,
     CATALOG_UPLOAD_ROUTE,
+    COMPONENT_SKILL_UPLOAD_ROUTE,
 ]);
+/** An org admin's plugin package upload (spec §14, ruling P3-7; a tgz as the raw body). */
+export const ORG_PLUGIN_UPLOAD_ROUTE = "/api/v1/orgs/:orgId/catalog/uploads/file";
 /**
- * 把 `http.trustProxy` 配置转成 Fastify 的 trustProxy。布尔与 IP / CIDR 列表原样传入；
- * 跳数转成 `(addr, hop) => hop < n`：Fastify 5.12 起对 number 一律 fail closed（不信任任何一跳），
- * 所以由这里实现跳数语义——前提是服务只能经由这 n 层代理访问（配置说明里已写明，并推荐 CIDR 列表）。
+ * The org routes that take raw package bytes (limit `packages.maxBytes`): before the body is read
+ * the caller is authenticated as a person with the org role of `catalog.upload` (ruling P3-29).
  */
-function fastifyTrustProxy(tp) {
-    return typeof tp === "number" ? (_addr, hop) => hop < tp : tp;
-}
-const REQUEST_ID = /^[A-Za-z0-9._-]{1,128}$/;
+export const ORG_PACKAGE_UPLOAD_ROUTES = new Set([ORG_PLUGIN_UPLOAD_ROUTE]);
 /** Paths without an access log line (probes). */
 const QUIET_PATHS = new Set(["/healthz", "/readyz"]);
-/** The request id: a valid incoming `x-request-id`, else a random one. */
-function requestId(req) {
-    const h = req.headers["x-request-id"];
-    return typeof h === "string" && REQUEST_ID.test(h) ? h : randomUUID();
-}
 /**
  * Request ids and the access log. Every request runs in a log context with its `reqId` (records
  * logged while handling it carry it) and answers with `x-request-id` (set on the raw response, so
@@ -87,36 +75,16 @@ const LARGE_BODY_ROUTES = new Set([
     "/api/v1/orgs/:orgId/connectors/preview",
 ]);
 const LARGE_BODY_LIMIT = 6 * 1024 * 1024;
-/** 根模块：总是含健康检查；`serveApi` 时 import `apiModule`；全局错误过滤器。 */
-function rootModule(opts) {
-    let RootModule = class RootModule {
-    };
-    RootModule = __decorate([
-        Module({})
-    ], RootModule);
-    return {
-        module: RootModule,
-        imports: opts.serveApi && opts.apiModule ? [opts.apiModule] : [],
-        controllers: [HealthController],
-        providers: [
-            { provide: KERNEL_LOG, useValue: opts.log },
-            { provide: HEALTH_OPTIONS, useValue: opts.health },
-            { provide: APP_FILTER, useClass: ErrorFilter },
-        ],
-    };
-}
 /**
- * 创建并初始化内核 HTTP 应用（NestJS + Fastify），不连接任何外部资源。
- * 插件路由不经过 Nest：在 Fastify 的独立作用域里统一转发 `/plugins/*`（见 plugin-dispatch.ts）；
- * 插件加载前 `/plugins/*` 一律 404。未匹配的内核路由同样返回 404 错误信封。
+ * Sets up the Fastify side of the kernel's Nest application (built by `buildKernelApp` from
+ * `KernelModule`, which provides the health endpoints and the API) without connecting to anything,
+ * and returns it uninitialized: `init()` is the caller's (it runs the start sequence), `close()`
+ * closes only the HTTP server (the rest of the application is closed by the caller's shutdown).
+ * Extension routes do not go through Nest: `/plugins/*` is dispatched in its own Fastify scope
+ * (see plugin-dispatch.ts) and answers 404 until extensions are loaded. Unmatched kernel routes
+ * answer the 404 error envelope as well.
  */
-export async function createHttpApp(opts) {
-    const app = await NestFactory.create(rootModule(opts), new FastifyAdapter({
-        trustProxy: fastifyTrustProxy(opts.trustProxy ?? false),
-        // x-request-id is read by requestId() (validated), never trusted as is
-        requestIdHeader: false,
-        genReqId: requestId,
-    }), { logger: new NestLogAdapter(opts.log), abortOnError: false });
+export async function createHttpApp(opts, app) {
     // Cookie 解析（会话 Cookie）；必须在 init 之前注册
     await app.register(fastifyCookie);
     const fastify = app.getHttpAdapter().getInstance();
@@ -136,18 +104,19 @@ export async function createHttpApp(opts) {
         if (LARGE_BODY_ROUTES.has(r.url) && [r.method].flat().includes("POST")) {
             r.bodyLimit = LARGE_BODY_LIMIT;
         }
-        if (PACKAGE_UPLOAD_ROUTES.has(r.url) && opts.packageMaxBytes !== undefined) {
+        const upload = PACKAGE_UPLOAD_ROUTES.has(r.url) || ORG_PACKAGE_UPLOAD_ROUTES.has(r.url);
+        if (upload && opts.packageMaxBytes !== undefined) {
             r.bodyLimit = opts.packageMaxBytes + 1;
         }
     });
-    // 读请求体之前：包上传（插件包、企业目录包）先认证（未认证 / 非企业管理员的大请求体不读进内存）；其余内核路由不收
+    // 读请求体之前：包上传（插件包、平台目录包）先认证（未认证 / 非超级管理员的大请求体不读进内存）；其余内核路由不收
     // application/octet-stream（415）。插件路由 /plugins/* 在自己的作用域里收任何类型，不受影响
     let authServices;
     const services = () => {
         authServices ??= {
-            accounts: app.get(ACCOUNTS, { strict: false }),
-            sessions: app.get(SESSIONS, { strict: false }),
-            tokens: app.get(API_TOKENS, { strict: false }),
+            accounts: app.get(AccountsService, { strict: false }),
+            sessions: app.get(SessionService, { strict: false }),
+            tokens: app.get(ApiTokenService, { strict: false }),
         };
         return authServices;
     };
@@ -163,7 +132,20 @@ export async function createHttpApp(opts) {
             return;
         if (req.method === "POST" && PACKAGE_UPLOAD_ROUTES.has(req.routeOptions.url ?? "")) {
             try {
-                await authorizeEnterpriseAdmin(req, services());
+                await authorizeSuperAdmin(req, services());
+            }
+            catch (e) {
+                return sendError(reply, e, req.method, req.url);
+            }
+            return;
+        }
+        if (req.method === "POST" && ORG_PACKAGE_UPLOAD_ROUTES.has(req.routeOptions.url ?? "")) {
+            try {
+                // the org admin role before the body (ruling P3-29): no one else makes the kernel buffer
+                // a package-sized body
+                const principal = await authenticateOrgUploader(req, services());
+                const orgId = req.params.orgId ?? "";
+                await authorizeOrgAction(app.get(KernelDb, { strict: false }).db, principal, orgId, "catalog.upload");
             }
             catch (e) {
                 return sendError(reply, e, req.method, req.url);
@@ -189,7 +171,6 @@ export async function createHttpApp(opts) {
         : undefined;
     if (opts.gateway)
         await registerGatewayRoutes(fastify, opts.gateway, opts.log);
-    await app.init();
     return {
         inject: (o) => fastify.inject(o),
         routes: () => [...routes],
@@ -212,7 +193,7 @@ export async function createHttpApp(opts) {
         close: () => {
             unwatch?.();
             dispatch?.abortAll();
-            return app.close();
+            return fastify.close();
         },
         abortPluginRequests: () => dispatch?.abortAll(),
         closeAllConnections: () => fastify.server.closeAllConnections(),

package/dist/http/error-filter.module.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The global error filter (`APP_FILTER`: the error envelope for every route).
+ */
+export declare class ErrorFilterModule {
+}

package/dist/http/error-filter.module.js

@@ -0,0 +1,18 @@
+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 { APP_FILTER } from "@nestjs/core";
+import { ErrorFilter } from "./error.filter.js";
+/**
+ * The global error filter (`APP_FILTER`: the error envelope for every route).
+ */
+let ErrorFilterModule = class ErrorFilterModule {
+};
+ErrorFilterModule = __decorate([
+    Module({ providers: [{ provide: APP_FILTER, useClass: ErrorFilter }] })
+], ErrorFilterModule);
+export { ErrorFilterModule };

package/dist/http/error.filter.js

@@ -9,7 +9,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Catch, HttpException, Inject, } from "@nestjs/common";
 import { ApiError, errorBody } from "../errors.js";
-import { KERNEL_LOG } from "./tokens.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
 /**
  * Nest `HttpException`（框架自身抛出，如路由不存在、请求体解析失败）的状态码 → 通用错误码。
  * 显式列出而不是反查 `ERROR_CODES`：同一状态码下有多个业务码，反查会误取到业务码。
@@ -80,6 +80,6 @@ let ErrorFilter = class ErrorFilter {
 };
 ErrorFilter = __decorate([
     Catch(),
-    __param(0, Inject(KERNEL_LOG))
+    __param(0, Inject(KERNEL_LOGGER))
 ], ErrorFilter);
 export { ErrorFilter };

package/dist/http/{gateway.module.d.ts → gateway-routes.d.ts}

@@ -1,15 +1,19 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { FastifyInstance } from "fastify";
 import type { ChannelWebhooks } from "../channels/webhook.js";
+import { type DeviceRoutesOptions } from "../devices/device-routes.js";
 /** What the gateway role serves over HTTP besides health and plugin routes. */
 export interface GatewayRoutes {
     webhooks: Pick<ChannelWebhooks, "handle">;
     /** `channels.webhookMaxBodyBytes`. */
     webhookMaxBodyBytes: number;
+    /** The device connection route (`GET /device/connect`, environments spec §13.4). */
+    devices: DeviceRoutesOptions;
 }
 /**
- * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): today the
- * channel webhook. These are raw Fastify routes, not a Nest module, so the API's global guard and
- * CSRF check do not apply (P-4); each route does its own (plugin-side) verification.
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): the
+ * channel webhook and the device connection WebSocket. These are raw Fastify routes, not a Nest
+ * module, so the API's global guard and CSRF check do not apply (P-4); each route does its own
+ * verification (the channel plugin's signature check, the machine credential).
  */
 export declare function registerGatewayRoutes(fastify: FastifyInstance, routes: GatewayRoutes, log: Pick<Logger, "error">): Promise<void>;

package/dist/http/gateway-routes.js

@@ -0,0 +1,16 @@
+import { registerChannelWebhookRoute } from "../channels/webhook.controller.js";
+import { registerDeviceConnectRoute } from "../devices/device-routes.js";
+/**
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): the
+ * channel webhook and the device connection WebSocket. These are raw Fastify routes, not a Nest
+ * module, so the API's global guard and CSRF check do not apply (P-4); each route does its own
+ * verification (the channel plugin's signature check, the machine credential).
+ */
+export async function registerGatewayRoutes(fastify, routes, log) {
+    await registerChannelWebhookRoute(fastify, {
+        webhooks: routes.webhooks,
+        maxBodyBytes: routes.webhookMaxBodyBytes,
+        log,
+    });
+    await registerDeviceConnectRoute(fastify, routes.devices);
+}

package/dist/http/nest-logger.d.ts

@@ -1,12 +1,13 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { LoggerService } from "@nestjs/common";
-/** 可选带 debug 的 logger（内核 logger 有 debug；插件契约的 Logger 没有）。 */
+/** A logger with an optional debug (the kernel logger has one; the SDK Logger does not). */
 type MaybeDebugLogger = Logger & {
     debug?: (msg: string, fields?: Record<string, unknown>) => void;
 };
 /**
- * 把 Nest 自身的日志转给内核 logger：`log`（启动时的模块加载、路由映射等，每次启动几十行）降为 debug，
- * `warn` / `error` 原级别转发，`debug` / `verbose` 丢弃。logger 没有 debug 时 `log` 也丢弃。
+ * Forwards Nest's own log lines to the kernel logger, as octok does: `log` (module loading,
+ * the `Mapped {/api/v1/…, GET} route` lines at startup) at info, `warn` / `error` as they are,
+ * `debug` / `verbose` at debug. Nest's context name becomes the record's `context`.
  */
 export declare class NestLogAdapter implements LoggerService {
     private readonly logger;
@@ -14,7 +15,7 @@ export declare class NestLogAdapter implements LoggerService {
     log(message: unknown, ...params: unknown[]): void;
     warn(message: unknown, ...params: unknown[]): void;
     error(message: unknown, ...params: unknown[]): void;
-    debug(): void;
-    verbose(): void;
+    debug(message: unknown, ...params: unknown[]): void;
+    verbose(message: unknown, ...params: unknown[]): void;
 }
 export {};

package/dist/http/nest-logger.js

@@ -1,6 +1,7 @@
 /**
- * 把 Nest 自身的日志转给内核 logger：`log`（启动时的模块加载、路由映射等，每次启动几十行）降为 debug，
- * `warn` / `error` 原级别转发，`debug` / `verbose` 丢弃。logger 没有 debug 时 `log` 也丢弃。
+ * Forwards Nest's own log lines to the kernel logger, as octok does: `log` (module loading,
+ * the `Mapped {/api/v1/…, GET} route` lines at startup) at info, `warn` / `error` as they are,
+ * `debug` / `verbose` at debug. Nest's context name becomes the record's `context`.
  */
 export class NestLogAdapter {
     logger;
@@ -8,7 +9,7 @@ export class NestLogAdapter {
         this.logger = logger;
     }
     log(message, ...params) {
-        this.logger.debug?.(String(message), fields(params));
+        this.logger.info(String(message), fields(params));
     }
     warn(message, ...params) {
         this.logger.warn(String(message), fields(params));
@@ -16,13 +17,26 @@ export class NestLogAdapter {
     error(message, ...params) {
         this.logger.error(String(message), fields(params));
     }
-    debug() { }
-    verbose() { }
+    debug(message, ...params) {
+        this.logger.debug?.(String(message), fields(params));
+    }
+    verbose(message, ...params) {
+        this.logger.debug?.(String(message), fields(params));
+    }
 }
-/** Nest 把上下文名（如 `RoutesResolver`）、错误堆栈作为额外参数传入。 */
+/**
+ * Nest passes its context name (e.g. `RoutesResolver`) last and, for errors, the stack before it. The
+ * name becomes `context` (the pretty `[context=…]`), anything else `nest`.
+ */
 function fields(params) {
-    const ctx = params.filter((p) => p !== undefined);
-    if (ctx.length === 0)
-        return undefined;
-    return { nest: ctx.length === 1 ? ctx[0] : ctx };
+    const rest = params.filter((p) => p !== undefined);
+    const last = rest.at(-1);
+    const out = {};
+    if (typeof last === "string" && /^[A-Za-z][\w.-]*$/.test(last)) {
+        out.context = last;
+        rest.pop();
+    }
+    if (rest.length > 0)
+        out.nest = rest.length === 1 ? rest[0] : rest;
+    return Object.keys(out).length > 0 ? out : undefined;
 }

package/dist/http/plugin-dispatch.d.ts

@@ -45,7 +45,10 @@ export declare function createPluginRouter(routes: Route[]): PluginRouter;
  * - `req.signal` aborts only when the client disconnects before the response is written (not on
  *   normal completion); long-lived handlers use it to unsubscribe;
  * - a throwing handler is logged (path redacted with `redactPath`) and returns 500 `internal` (the
- *   error message is not echoed).
+ *   error message is not echoed), except a `model.hook_denied` `ApiError` that escaped from
+ *   `ctx.models.embed` (an organization policy hook denied the call, spec B §5.4): a deliberate
+ *   outcome, not a failure, so it answers 403 `model.hook_denied` with a generic message (the
+ *   routes are unauthenticated: the policy extension's name and reason are not echoed).
  * - Fastify's own errors (a body over 1 MiB and so on) are mapped to the error envelope by the
  *   scope's error handler: 4xx by the common error code table (413 `payload_too_large`, 415
  *   `unsupported_media_type` and so on), 5xx are logged and return `internal`.

package/dist/http/plugin-dispatch.js

@@ -1,6 +1,6 @@
 import { Readable } from "node:stream";
 import FindMyWay from "find-my-way";
-import { errorBody } from "../errors.js";
+import { ApiError, ERROR_CODES, errorBody } from "../errors.js";
 import { ACCESS_COOKIE, REFRESH_COOKIE } from "../identity/cookies.js";
 import { codeForStatus, redactPath } from "./error.filter.js";
 /** 插件路由都在此前缀下（ctx.http.route 已加 `/plugins/<name>` 前缀）。 */
@@ -47,7 +47,10 @@ export function createPluginRouter(routes) {
  * - `req.signal` aborts only when the client disconnects before the response is written (not on
  *   normal completion); long-lived handlers use it to unsubscribe;
  * - a throwing handler is logged (path redacted with `redactPath`) and returns 500 `internal` (the
- *   error message is not echoed).
+ *   error message is not echoed), except a `model.hook_denied` `ApiError` that escaped from
+ *   `ctx.models.embed` (an organization policy hook denied the call, spec B §5.4): a deliberate
+ *   outcome, not a failure, so it answers 403 `model.hook_denied` with a generic message (the
+ *   routes are unauthenticated: the policy extension's name and reason are not echoed).
  * - Fastify's own errors (a body over 1 MiB and so on) are mapped to the error envelope by the
  *   scope's error handler: 4xx by the common error code table (413 `payload_too_large`, 415
  *   `unsupported_media_type` and so on), 5xx are logged and return `internal`.
@@ -108,6 +111,15 @@ export async function registerPluginDispatch(fastify, getTable, log) {
             res = await pluginHandler(webReq);
         }
         catch (err) {
+            if (err instanceof ApiError && err.code === "model.hook_denied") {
+                log.warn("plugin handler refused: a policy hook denied its model call", {
+                    method: req.method,
+                    path: redactPath(path),
+                });
+                return reply
+                    .code(ERROR_CODES["model.hook_denied"])
+                    .send(errorBody(err.code, "An organization policy denied this model call"));
+            }
             log.error("plugin handler failed", { method: req.method, path: redactPath(path), err });
             return reply.code(500).send(errorBody("internal", "Internal error"));
         }

package/dist/identity/accounts.d.ts

@@ -1,51 +1,117 @@
-import { type Selectable, type Transaction } from "kysely";
-import type { AccountsTable, KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { type Selectable } from "kysely";
+import { SetupLock } from "../admin/setup-lock.js";
+import type { AccountsTable } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { SuperAdminLock } from "./super-admin.js";
 export interface Account {
     id: string;
     displayName: string;
     email: string | null;
     status: "active" | "disabled";
-    isEnterpriseAdmin: boolean;
+    isSuperAdmin: boolean;
+    /**
+     * The account signed in with a generated initial password and must set its own before anything
+     * else (Platform tool spec §14.5 item 2): the auth guard refuses every other route until then.
+     */
+    mustChangePassword: boolean;
     createdAt: Date;
 }
-type Trx = Transaction<KernelDatabase>;
-/** 企业管理员可改的账号字段。 */
+/** 超级管理员可改的账号字段。 */
 export type AccountPatch = {
     displayName?: string;
     status?: "active" | "disabled";
-    isEnterpriseAdmin?: boolean;
+    isSuperAdmin?: boolean;
 };
 /** 构造 `Account` 所需的 accounts 列（供跨表查询 select 使用）。 */
-export declare const ACCOUNT_COLUMNS: readonly ["accounts.id", "accounts.display_name", "accounts.email", "accounts.status", "accounts.is_enterprise_admin", "accounts.created_at"];
-type AccountRow = Pick<Selectable<AccountsTable>, "id" | "display_name" | "email" | "status" | "is_enterprise_admin" | "created_at">;
+export declare const ACCOUNT_COLUMNS: readonly ["accounts.id", "accounts.display_name", "accounts.email", "accounts.status", "accounts.is_super_admin", "accounts.must_change_password", "accounts.created_at"];
+type AccountRow = Pick<Selectable<AccountsTable>, "id" | "display_name" | "email" | "status" | "is_super_admin" | "must_change_password" | "created_at">;
 export declare function toAccount(r: AccountRow): Account;
 export interface LocalAccountInput {
     login: string;
     password: string;
     displayName: string;
     email?: string;
-    enterpriseAdmin?: boolean;
+    superAdmin?: boolean;
+    /** The account must set its own password at first sign-in (a generated initial password). */
+    mustChangePassword?: boolean;
+}
+/** Options of {@link AccountsService.createByAdmin}. */
+export interface AdminCreateOptions {
+    /** Merged into the `account.created` audit detail (e.g. the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>;
+    /**
+     * Runs in the creation's transaction right after the insert (the generated password is sealed
+     * there), so the account and what goes with it commit or roll back together.
+     */
+    inTransaction?: (account: Account) => Promise<void>;
 }
-/** 账号服务：本地账号的创建、认证与管理。框架无关，由调用方注入 db。 */
+/**
+ * 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.
+ */
 export declare class AccountsService {
     private readonly db;
-    constructor(db: KernelDb);
-    /** 校验密码长度并算出哈希（scrypt，较慢）：供需要在事务之外先算好哈希的调用方使用。 */
+    readonly txHost: TransactionHost;
+    private readonly adminLock;
+    private readonly setupLock;
+    constructor(db: KernelDb, txHost: TransactionHost, adminLock: SuperAdminLock, setupLock: SetupLock);
+    /** Checks the password length and hashes it (scrypt, slow): for callers that hash before their transaction opens. */
     hashNewPassword(password: string): Promise<string>;
     /**
-     * 建本地账号。传 `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.
+     */
+    createLocal(input: LocalAccountInput, passwordHash?: string): Promise<Account>;
+    /**
+     * A super admin creates a local account (optionally a super admin): under the
+     * super admin lock, re-checks that the actor is still an active super admin (else
+     * `forbidden`), creates the account and audits `account.created`. The hash is computed before
+     * the lock.
+     */
+    createByAdmin(input: LocalAccountInput, actorAccountId: string, actorTokenId?: string, opts?: AdminCreateOptions): Promise<Account>;
+    /**
+     * Whether `login` is free for a new local account (`account.login_taken` otherwise) and well
+     * formed (`validation_failed`): the read a caller checks before asking a person to confirm.
      */
-    createLocal(input: LocalAccountInput, trx?: Trx, passwordHash?: string): Promise<Account>;
+    assertLoginFree(login: string): Promise<void>;
+    /** The local login of each account that has one (accounts without are left out). */
+    localLogins(accountIds: readonly string[]): Promise<Map<string, string>>;
+    private createByAdminIn;
     /**
-     * 企业管理员建本地账号（可同时设为企业管理员）：事务内取企业管理员锁并复核发起人仍是活跃企业管理员
-     * （否则 `forbidden`），建号并写审计 `account.created`。密码哈希在取锁之前算好，不在锁内跑 scrypt。
+     * CLI: creates a super admin without checking whether the deployment is set up; a taken
+     * login → `account.login_taken`.
      */
-    createByAdmin(input: LocalAccountInput, actorAccountId: string, actorTokenId?: string): Promise<Account>;
+    createSuperAdmin(input: SuperAdminInput): Promise<Account>;
+    /**
+     * CLI `admin create --if-none`: creates a super 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 super admin already exists; a taken login still throws
+     * `account.login_taken`.
+     */
+    createSuperAdminIfNone(input: SuperAdminInput): Promise<Account | undefined>;
+    private createSuperAdminIfNoneIn;
+    private insertSuperAdmin;
     authenticateLocal(login: string, password: string): Promise<Account | null>;
     /** 按账号 id 校验本地密码（改密码时核对旧密码）；没有本地密码、超长或不符 → false。 */
     verifyPassword(accountId: string, password: string): Promise<boolean>;
     get(id: string): Promise<Account | undefined>;
+    /**
+     * A person's preferences (run context spec §3.4): `timeZone` is their time zone setting (IANA),
+     * null = follow the browser. Missing account → null.
+     */
+    preferences(accountId: string): Promise<{
+        timeZone: string | null;
+    }>;
+    /** Sets a person's preferences (the caller validated the time zone). */
+    setPreferences(accountId: string, prefs: {
+        timeZone: string | null;
+    }): Promise<{
+        timeZone: string | null;
+    }>;
     /** 按 id 升序分页，`after` 为上一页最后一个 id。 */
     list(opts: {
         limit: number;
@@ -53,41 +119,67 @@ export declare class AccountsService {
     }): Promise<Account[]>;
     setPassword(accountId: string, password: string): Promise<void>;
     /**
-     * 用户改密码（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).
      */
     changePassword(accountId: string, password: string, exceptSessionId: string): Promise<string[]>;
+    private changePasswordIn;
     update(id: string, patch: AccountPatch, actorAccountId: string, actorTokenId?: string): Promise<Account>;
     /**
-     * 企业管理员改账号。停用（`status: "disabled"`）时在**同一个 PG 事务**里吊销该账号的全部会话
-     * （`sessions.revoked_at`）与个人访问令牌，要么都生效要么都不生效；返回被吊销的会话 id，
-     * 调用方在提交后写 Redis 吊销标记（快速路径，失败只记 warn：鉴权以 PG 为准）。
+     * A super 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).
      */
-    updateAccount(id: string, patch: AccountPatch, actorAccountId: string, actorTokenId?: string): Promise<{
+    updateAccount(id: string, patch: AccountPatch, actorAccountId: string, actorTokenId?: string, opts?: {
+        auditDetail?: Record<string, unknown>;
+    }): Promise<{
         account: Account;
         revokedSessionIds: string[];
     }>;
     /**
-     * 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 super
+     * admin flag by local login under the super admin lock; revoking keeps the
+     * {@link updateAccount} "last active super admin" check (`account.last_super_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`.
      */
-    setEnterpriseAdminByLogin(login: string, isEnterpriseAdmin: boolean): Promise<{
+    setSuperAdminByLogin(login: string, isSuperAdmin: boolean): Promise<{
         account: Account;
         changed: boolean;
     }>;
+    private setSuperAdminIn;
+    /** 全部账号数（含停用的；后台概览）。 */
+    count(): Promise<number>;
+    /** Active (status = active) super admins, in the context's transaction when there is one. */
+    countSuperAdmins(): Promise<number>;
+    /** Inserts the account, its local identity and password; a taken login → `account.login_taken`. */
+    private insertLocal;
+    /** Writes (or replaces) the local password hash; a missing account → `account.not_found`. */
+    private writePassword;
     /**
-     * 已持企业管理员锁的事务内改账号：改行、复核「最后一个活跃企业管理员」、写审计 `account.updated`；
-     * 停用时吊销该账号的全部会话与个人令牌。
+     * Changes the account under the super admin lock the caller holds: updates the row,
+     * re-checks "the last active super admin", audits `account.updated`; disabling revokes the
+     * account's sessions and personal tokens.
      */
     private applyUpdate;
-    /** 全部账号数（含停用的；后台概览）。 */
-    count(): Promise<number>;
-    /** 活跃（status = active）的企业管理员数量。 */
-    countEnterpriseAdmins(trx?: Trx): Promise<number>;
+}
+/** Input of the CLI super admin creation. */
+export interface SuperAdminInput {
+    login: string;
+    password: string;
+    displayName: string;
+    email?: string | undefined;
+}
+/**
+ * {@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.
+ */
+export declare class AccountsModule {
 }
 export {};