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

package/dist/http/gateway-routes.js

@@ -1,8 +1,10 @@
 import { registerChannelWebhookRoute } from "../channels/webhook.controller.js";
+import { registerDeviceConnectRoute, } from "../local-devices/device-routes.js";
 /**
- * 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 async function registerGatewayRoutes(fastify, routes, log) {
     await registerChannelWebhookRoute(fastify, {
@@ -10,4 +12,5 @@ export async function registerGatewayRoutes(fastify, routes, log) {
         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

@@ -3,31 +3,48 @@ 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";
+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;
 }
-/** 企业管理员可改的账号字段。 */
+/** 超级管理员可改的账号字段。 */
 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>;
 }
 /**
  * Accounts: local account creation, authentication and administration. Every write is
@@ -39,7 +56,7 @@ export declare class AccountsService {
     readonly txHost: TransactionHost;
     private readonly adminLock;
     private readonly setupLock;
-    constructor(db: KernelDb, txHost: TransactionHost, adminLock: EnterpriseAdminLock, setupLock: 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>;
     /**
@@ -49,32 +66,59 @@ export declare class AccountsService {
      */
     createLocal(input: LocalAccountInput, passwordHash?: string): Promise<Account>;
     /**
-     * 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
+     * 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): Promise<Account>;
+    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.
+     */
+    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;
     /**
-     * CLI: creates an enterprise admin without checking whether the deployment is set up; a taken
+     * CLI: creates a super admin without checking whether the deployment is set up; a taken
      * login → `account.login_taken`.
      */
-    createEnterpriseAdmin(input: EnterpriseAdminInput): Promise<Account>;
+    createSuperAdmin(input: SuperAdminInput): Promise<Account>;
     /**
-     * CLI `admin create --if-none`: creates an enterprise admin only when no active one exists. The
+     * 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 enterprise admin already exists; a taken login still throws
+     * when an active super admin already exists; a taken login still throws
      * `account.login_taken`.
      */
-    createEnterpriseAdminIfNone(input: EnterpriseAdminInput): Promise<Account | undefined>;
-    private createEnterpriseAdminIfNoneIn;
-    private insertEnterpriseAdmin;
+    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: `timeZone` is their time zone setting (IANA), null = follow the browser
+     * (run context spec §3.4); `theme` their theme (a `platform_themes` id), null = follow the org
+     * (themes spec §7). Missing account -> nulls.
+     */
+    preferences(accountId: string): Promise<{
+        timeZone: string | null;
+        theme: string | null;
+    }>;
+    /**
+     * Updates the preferences given (a field left out keeps its value; the caller validated the time
+     * zone). A theme must be on in at least one of the person's orgs, else 400 `theme.not_available`.
+     */
+    setPreferences(accountId: string, prefs: {
+        timeZone?: string | null | undefined;
+        theme?: string | null | undefined;
+    }): Promise<{
+        timeZone: string | null;
+        theme: string | null;
+    }>;
     /** 按 id 升序分页，`after` 为上一页最后一个 id。 */
     list(opts: {
         limit: number;
@@ -92,45 +136,47 @@ export declare class AccountsService {
     private changePasswordIn;
     update(id: string, patch: AccountPatch, actorAccountId: string, actorTokenId?: string): Promise<Account>;
     /**
-     * An enterprise admin changes an account. Disabling (`status: "disabled"`) revokes the
+     * 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[];
     }>;
     /**
-     * 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`),
+     * 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 setEnterpriseAdminIn;
+    private setSuperAdminIn;
     /** 全部账号数（含停用的；后台概览）。 */
     count(): Promise<number>;
-    /** Active (status = active) enterprise admins, in the context's transaction when there is one. */
-    countEnterpriseAdmins(): 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;
     /**
-     * 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
+     * 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;
 }
-/** Input of the CLI enterprise admin creation. */
-export interface EnterpriseAdminInput {
+/** Input of the CLI super admin creation. */
+export interface SuperAdminInput {
     login: string;
     password: string;
     displayName: string;