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

package/dist/http/app.js

@@ -1,24 +1,14 @@
-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 { AccountsService } from "../identity/accounts.js";
+import { ApiTokenService } from "../identity/api-tokens.js";
 import { authorizeEnterpriseAdmin } from "../identity/auth.guard.js";
+import { SessionService } from "../identity/sessions.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 { 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). */
@@ -31,22 +21,8 @@ export const PACKAGE_UPLOAD_ROUTES = new Set([
     EXTENSION_PACKAGE_UPLOAD_ROUTE,
     CATALOG_UPLOAD_ROUTE,
 ]);
-/**
- * 把 `http.trustProxy` 配置转成 Fastify 的 trustProxy。布尔与 IP / CIDR 列表原样传入；
- * 跳数转成 `(addr, hop) => hop < n`：Fastify 5.12 起对 number 一律 fail closed（不信任任何一跳），
- * 所以由这里实现跳数语义——前提是服务只能经由这 n 层代理访问（配置说明里已写明，并推荐 CIDR 列表）。
- */
-function fastifyTrustProxy(tp) {
-    return typeof tp === "number" ? (_addr, hop) => hop < tp : tp;
-}
-const REQUEST_ID = /^[A-Za-z0-9._-]{1,128}$/;
 /** 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 +63,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();
@@ -145,9 +101,9 @@ export async function createHttpApp(opts) {
     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;
     };
@@ -189,7 +145,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 +167,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/identity/accounts.d.ts

@@ -1,5 +1,9 @@
-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 { EnterpriseAdminLock } from "./enterprise-admin.js";
 export interface Account {
     id: string;
     displayName: string;
@@ -8,7 +12,6 @@ export interface Account {
     isEnterpriseAdmin: boolean;
     createdAt: Date;
 }
-type Trx = Transaction<KernelDatabase>;
 /** 企业管理员可改的账号字段。 */
 export type AccountPatch = {
     displayName?: string;
@@ -26,22 +29,48 @@ export interface LocalAccountInput {
     email?: string;
     enterpriseAdmin?: boolean;
 }
-/** 账号服务：本地账号的创建、认证与管理。框架无关，由调用方注入 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: EnterpriseAdminLock, 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, trx?: Trx, passwordHash?: string): Promise<Account>;
+    createLocal(input: LocalAccountInput, passwordHash?: string): Promise<Account>;
     /**
-     * 企业管理员建本地账号（可同时设为企业管理员）：事务内取企业管理员锁并复核发起人仍是活跃企业管理员
-     * （否则 `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.
      */
     createByAdmin(input: LocalAccountInput, actorAccountId: string, actorTokenId?: string): Promise<Account>;
+    private createByAdminIn;
+    /**
+     * CLI: creates an enterprise admin without checking whether the deployment is set up; a taken
+     * login → `account.login_taken`.
+     */
+    createEnterpriseAdmin(input: EnterpriseAdminInput): Promise<Account>;
+    /**
+     * 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`.
+     */
+    createEnterpriseAdminIfNone(input: EnterpriseAdminInput): Promise<Account | undefined>;
+    private createEnterpriseAdminIfNoneIn;
+    private insertEnterpriseAdmin;
     authenticateLocal(login: string, password: string): Promise<Account | null>;
     /** 按账号 id 校验本地密码（改密码时核对旧密码）；没有本地密码、超长或不符 → false。 */
     verifyPassword(accountId: string, password: string): Promise<boolean>;
@@ -53,41 +82,65 @@ 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 为准）。
+     * 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).
      */
     updateAccount(id: string, patch: AccountPatch, actorAccountId: string, actorTokenId?: string): 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 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`.
      */
     setEnterpriseAdminByLogin(login: string, isEnterpriseAdmin: boolean): Promise<{
         account: Account;
         changed: boolean;
     }>;
+    private setEnterpriseAdminIn;
+    /** 全部账号数（含停用的；后台概览）。 */
+    count(): Promise<number>;
+    /** Active (status = active) enterprise admins, in the context's transaction when there is one. */
+    countEnterpriseAdmins(): 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 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.
      */
     private applyUpdate;
-    /** 全部账号数（含停用的；后台概览）。 */
-    count(): Promise<number>;
-    /** 活跃（status = active）的企业管理员数量。 */
-    countEnterpriseAdmins(trx?: Trx): Promise<number>;
+}
+/** Input of the CLI enterprise admin creation. */
+export interface EnterpriseAdminInput {
+    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 {};