@capybara-hq/kernel 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/extensions/state.module.js

@@ -0,0 +1,38 @@
+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 { SuperAdminLockModule } from "../identity/super-admin.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { ExtensionApprovals } from "./approvals.js";
+import { ExtensionBlobs } from "./blobs.js";
+import { EffectiveConfigs } from "./effective-config.js";
+import { ExtensionInstalls } from "./installs.js";
+import { ExtensionRegistryModule } from "./registry.js";
+/**
+ * The extension state the model domain reads below the host: the install records with their
+ * packages and approvals, and each extension's effective config per org. Apart from
+ * `ExtensionsModule` so the model provider registry (and the `ctx.models` broker the host injects)
+ * can depend on it without a module cycle (writing-kernel-api: a cycle is cut by moving the shared
+ * part into its own provider both sides inject). `ExtensionsModule` re-exports it.
+ */
+let ExtensionStateModule = class ExtensionStateModule {
+};
+ExtensionStateModule = __decorate([
+    Module({
+        imports: [ExtensionRegistryModule, SuperAdminLockModule, OrgLockModule, StorageModule],
+        providers: [ExtensionApprovals, ExtensionBlobs, ExtensionInstalls, EffectiveConfigs],
+        exports: [
+            ExtensionRegistryModule,
+            ExtensionApprovals,
+            ExtensionBlobs,
+            ExtensionInstalls,
+            EffectiveConfigs,
+        ],
+    })
+], ExtensionStateModule);
+export { ExtensionStateModule };

package/dist/extensions/unavailable.d.ts

@@ -0,0 +1,49 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type DeploymentExtensionStatus } from "./permission-view.js";
+import { ExtensionRegistry } from "./registry.js";
+/**
+ * Why an extension cannot be used right now (Platform tool spec §14.2 problem 1, §14.5 item 4):
+ * - `not_deployed`: no install record on the platform (a catalog plugin whose extension was never
+ *   installed);
+ * - `needs_deployment_config`: installed, its deployment config is missing or invalid;
+ * - `pending_approval`: its permissions wait for the super admin's approval;
+ * - `pending_migration` / `loading`: the platform is still bringing it up;
+ * - `dependency`: an extension point it requires has no loaded provider;
+ * - `failed`: it failed to load (or its package cannot be read);
+ * - `deployment_disabled`: the super admin disabled it on the platform.
+ * State only: never a config value or field name.
+ */
+export type ExtensionUnavailableReason = "not_deployed" | "needs_deployment_config" | "pending_approval" | "pending_migration" | "loading" | "dependency" | "failed" | "deployment_disabled";
+/** The deployment status of an extension that is not loaded, and the reason it shows for it. */
+export interface ExtensionUnavailability {
+    /** Null when it has no install record (`not_deployed`). */
+    status: DeploymentExtensionStatus | null;
+    reason: ExtensionUnavailableReason;
+}
+/** The reason an org or the Platform tool shows for a deployment status of a not-loaded extension. */
+export declare function unavailableReason(status: DeploymentExtensionStatus): ExtensionUnavailableReason;
+/**
+ * The state of extensions that are not loaded on this replica, derived like the admin console's
+ * status ({@link deriveExtensionStatus}) from the install record and the replicas' recent reports,
+ * without reading packages: a pending approval and a pending config come from the replicas' rows
+ * (`pending` with reason `approval` / `config`). Reads PG on every call (no in-process state).
+ *
+ * Its inputs differ slightly from the admin view's (`ExtensionAdmin`): there `pendingApproval`
+ * compares the package's permission set with the snapshot and `configValid` checks the deployment
+ * config, while here both come from what the replicas last reported. They agree once a replica
+ * has tried the current package; until then this view says `loading` where the admin view may
+ * already say `pending_approval` or `pending_config`.
+ *
+ * Which extensions count as loaded is this replica's registry: replica-local and transient. During
+ * a rollout, or right after an enable or upgrade, one replica may answer `loading` while another
+ * has it loaded; the next call (or the next reconcile) converges.
+ */
+export declare class ExtensionAvailability {
+    private readonly kdb;
+    private readonly config;
+    private readonly registry;
+    constructor(kdb: KernelDb, config: KernelConfigService, registry: ExtensionRegistry);
+    /** For each of `names` not loaded on this replica: its status and reason (loaded ones absent). */
+    unavailable(names: readonly string[]): Promise<Map<string, ExtensionUnavailability>>;
+}

package/dist/extensions/unavailable.js

@@ -0,0 +1,113 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { STALE_RECONCILE_PERIODS } from "./lifecycle-topics.js";
+import { deriveExtensionStatus } from "./permission-view.js";
+import { ExtensionRegistry } from "./registry.js";
+/** The reason an org or the Platform tool shows for a deployment status of a not-loaded extension. */
+export function unavailableReason(status) {
+    switch (status) {
+        case "pending_config":
+            return "needs_deployment_config";
+        case "pending_approval":
+            return "pending_approval";
+        case "pending_migration":
+            return "pending_migration";
+        case "dependency":
+            return "dependency";
+        case "failed":
+        case "legacy_format":
+            return "failed";
+        case "disabled":
+            return "deployment_disabled";
+        // loaded on another replica, or not yet on this one
+        case "converging":
+        case "enabled":
+            return "loading";
+    }
+}
+/**
+ * The state of extensions that are not loaded on this replica, derived like the admin console's
+ * status ({@link deriveExtensionStatus}) from the install record and the replicas' recent reports,
+ * without reading packages: a pending approval and a pending config come from the replicas' rows
+ * (`pending` with reason `approval` / `config`). Reads PG on every call (no in-process state).
+ *
+ * Its inputs differ slightly from the admin view's (`ExtensionAdmin`): there `pendingApproval`
+ * compares the package's permission set with the snapshot and `configValid` checks the deployment
+ * config, while here both come from what the replicas last reported. They agree once a replica
+ * has tried the current package; until then this view says `loading` where the admin view may
+ * already say `pending_approval` or `pending_config`.
+ *
+ * Which extensions count as loaded is this replica's registry: replica-local and transient. During
+ * a rollout, or right after an enable or upgrade, one replica may answer `loading` while another
+ * has it loaded; the next call (or the next reconcile) converges.
+ */
+let ExtensionAvailability = class ExtensionAvailability {
+    kdb;
+    config;
+    registry;
+    constructor(kdb, config, registry) {
+        this.kdb = kdb;
+        this.config = config;
+        this.registry = registry;
+    }
+    /** For each of `names` not loaded on this replica: its status and reason (loaded ones absent). */
+    async unavailable(names) {
+        const loaded = new Set(this.registry.manifests().map((m) => m.name));
+        const wanted = [...new Set(names)].filter((n) => !loaded.has(n));
+        const out = new Map();
+        if (wanted.length === 0)
+            return out;
+        const db = this.kdb.db;
+        const staleSeconds = STALE_RECONCILE_PERIODS * this.config.get().extensionHost.reconcileIntervalSeconds;
+        const [installs, replicas] = await Promise.all([
+            db
+                .selectFrom("extension_installs")
+                .select(["name", "sha256", "desired_state", "migrated_sha"])
+                .where("name", "in", wanted)
+                .execute(),
+            db
+                .selectFrom("extension_replica_status")
+                .select(["plugin", "state", "reason", "sha256"])
+                .where("plugin", "in", wanted)
+                .where("heartbeat_at", ">", sql `now() - make_interval(secs => ${staleSeconds})`)
+                .execute(),
+        ]);
+        for (const name of wanted) {
+            const install = installs.find((i) => i.name === name);
+            if (install === undefined) {
+                out.set(name, { status: null, reason: "not_deployed" });
+                continue;
+            }
+            const rows = replicas.filter((r) => r.plugin === name);
+            const target = rows.filter((r) => r.sha256 === install.sha256);
+            const status = deriveExtensionStatus({
+                source: "install",
+                desired: { sha256: install.sha256, state: install.desired_state },
+                pendingApproval: target.some((r) => r.state === "pending" && r.reason === "approval"),
+                configValid: !target.some((r) => r.state === "pending" && r.reason === "config"),
+                migratedSha: install.migrated_sha,
+                replicas: rows,
+            });
+            out.set(name, { status, reason: unavailableReason(status) });
+        }
+        return out;
+    }
+};
+ExtensionAvailability = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(ExtensionRegistry))
+], ExtensionAvailability);
+export { ExtensionAvailability };

package/dist/files/previewers.controller.js

@@ -14,11 +14,10 @@ import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { PreviewerRegistry } from "./previewers.js";
+import { FilePreviewersOrderBody } from "./previewers.schemas.js";
 const Id = z.string().min(1).max(100);
 const PreviewQuery = z.object({ locale: z.enum(["zh", "en"]).default("en") });
-const OrderBody = z.object({
-    items: z.array(z.object({ plugin: Id, id: Id, disabled: z.boolean().default(false) })).max(500),
-});
+const OrderBody = FilePreviewersOrderBody;
 /** The previewer named in a preview path (the other path parameters are read as they are). */
 const PreviewParams = z.object({ plugin: Id, previewerId: Id });
 class FilePreviewQueryDto extends createZodDto(PreviewQuery, "FilePreviewQuery") {

package/dist/files/previewers.d.ts

@@ -61,7 +61,7 @@ export declare class PreviewerRegistry {
     }[], actor?: {
         accountId?: string;
         tokenId?: string;
-    }): Promise<OrgPreviewerItem[]>;
+    }, auditDetail?: Record<string, unknown>): Promise<OrgPreviewerItem[]>;
     /** Replaces the org's rows of the previewers this replica knows, in one transaction. */
     private putIn;
     /** Previewers that take this file (viewer must read the conversation), in the org's order. */

package/dist/files/previewers.js

@@ -141,7 +141,7 @@ let PreviewerRegistry = class PreviewerRegistry {
      * extension that is disabled now (or not loaded here yet) keep their order and `disabled`.
      * Audited as `org.file_previewers.updated`.
      */
-    async put(orgId, items, actor = {}) {
+    async put(orgId, items, actor = {}, auditDetail) {
         const known = new Set((await this.ordered(orgId)).map((l) => `${l.plugin}/${l.previewer.id}`));
         const seen = new Set();
         for (const i of items) {
@@ -151,11 +151,11 @@ let PreviewerRegistry = class PreviewerRegistry {
             }
             seen.add(k);
         }
-        await this.putIn(orgId, items, known, actor);
+        await this.putIn(orgId, items, known, actor, auditDetail);
         return this.list(orgId);
     }
     /** Replaces the org's rows of the previewers this replica knows, in one transaction. */
-    async putIn(orgId, items, known, actor) {
+    async putIn(orgId, items, known, actor, auditDetail) {
         if (known.size > 0) {
             await this.d.db
                 .deleteFrom("file_previewers")
@@ -180,7 +180,7 @@ let PreviewerRegistry = class PreviewerRegistry {
             ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
             orgId,
             action: "org.file_previewers.updated",
-            detail: { items },
+            detail: { items, ...auditDetail },
         });
     }
     /** Previewers that take this file (viewer must read the conversation), in the org's order. */

package/dist/files/previewers.schemas.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const FilePreviewersOrderBody: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        plugin: z.ZodString;
+        id: z.ZodString;
+        disabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const FILE_PREVIEWER_ROUTES: readonly RouteSchemas[];

package/dist/files/previewers.schemas.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+const Id = z.string().min(1).max(100);
+export const FilePreviewersOrderBody = z.object({
+    items: z.array(z.object({ plugin: Id, id: Id, disabled: z.boolean().default(false) })).max(500),
+});
+export const FILE_PREVIEWER_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/file-previewers" },
+    { route: "PUT /api/v1/orgs/:orgId/file-previewers", body: FilePreviewersOrderBody },
+];

package/dist/http/api.module.js

@@ -43,10 +43,12 @@ import { FilePreviewersController } from "../files/previewers.controller.js";
 import { AuthController } from "../identity/auth.controller.js";
 import { AuthGuard } from "../identity/auth.guard.js";
 import { IdentityModule } from "../identity/identity.module.js";
+import { InitialPasswordsController } from "../identity/initial-passwords.controller.js";
 import { MeController } from "../identity/me.controller.js";
 import { BindController, MeIdentitiesController, SsoController, } from "../identity/sso.controller.js";
 import { InboxModule } from "../inbox/inbox.module.js";
 import { PlatformInboxController } from "../inbox/platform-inbox.controller.js";
+import { ModelEnablementController } from "../models/enablement.controller.js";
 import { ModelsModule } from "../models/models.module.js";
 import { ModelPurposesController } from "../models/purposes.controller.js";
 import { DirectorySyncController } from "../orgs/directory-sync.controller.js";
@@ -74,6 +76,7 @@ import { UiController } from "../ui/views.controller.js";
 const CONTROLLERS = [
     AuthController,
     MeController,
+    InitialPasswordsController,
     OrgsController,
     OrgSettingsController,
     InvitationsController,
@@ -92,6 +95,7 @@ const CONTROLLERS = [
     AgentSaveAsTemplateController,
     PendingConnectorsController,
     ModelsController,
+    ModelEnablementController,
     ReadinessController,
     ConversationsController,
     BackgroundController,

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

@@ -10,6 +10,11 @@ export interface Account {
     email: string | null;
     status: "active" | "disabled";
     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;
 }
 /** 超级管理员可改的账号字段。 */
@@ -19,8 +24,8 @@ export type AccountPatch = {
     isSuperAdmin?: boolean;
 };
 /** 构造 `Account` 所需的 accounts 列（供跨表查询 select 使用）。 */
-export declare const ACCOUNT_COLUMNS: readonly ["accounts.id", "accounts.display_name", "accounts.email", "accounts.status", "accounts.is_super_admin", "accounts.created_at"];
-type AccountRow = Pick<Selectable<AccountsTable>, "id" | "display_name" | "email" | "status" | "is_super_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;
@@ -28,6 +33,18 @@ export interface LocalAccountInput {
     displayName: string;
     email?: string;
     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
@@ -54,7 +71,14 @@ export declare class AccountsService {
      * `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 a super admin without checking whether the deployment is set up; a taken
@@ -75,6 +99,19 @@ export declare class AccountsService {
     /** 按账号 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;
@@ -97,7 +134,9 @@ export declare class AccountsService {
      * 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[];
     }>;

package/dist/identity/accounts.js

@@ -26,6 +26,7 @@ export const ACCOUNT_COLUMNS = [
     "accounts.email",
     "accounts.status",
     "accounts.is_super_admin",
+    "accounts.must_change_password",
     "accounts.created_at",
 ];
 export function toAccount(r) {
@@ -35,6 +36,7 @@ export function toAccount(r) {
         email: r.email,
         status: r.status,
         isSuperAdmin: r.is_super_admin,
+        mustChangePassword: r.must_change_password,
         createdAt: r.created_at,
     };
 }
@@ -87,10 +89,37 @@ let AccountsService = class AccountsService {
      * `forbidden`), creates the account and audits `account.created`. The hash is computed before
      * the lock.
      */
-    async createByAdmin(input, actorAccountId, actorTokenId) {
-        return this.createByAdminIn(await prepareLocal(input), actorAccountId, actorTokenId);
+    async createByAdmin(input, actorAccountId, actorTokenId, opts = {}) {
+        return this.createByAdminIn(await prepareLocal(input), actorAccountId, actorTokenId, opts);
     }
-    async createByAdminIn(prepared, actorAccountId, actorTokenId) {
+    /**
+     * 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.
+     */
+    async assertLoginFree(login) {
+        const external = normalizeLogin(login);
+        const taken = await this.db
+            .selectFrom("identities")
+            .select("account_id")
+            .where("source", "=", "local")
+            .where("external_id", "=", external)
+            .executeTakeFirst();
+        if (taken)
+            throw new ApiError("account.login_taken", "Login is already taken");
+    }
+    /** The local login of each account that has one (accounts without are left out). */
+    async localLogins(accountIds) {
+        if (accountIds.length === 0)
+            return new Map();
+        const rows = await this.db
+            .selectFrom("identities")
+            .select(["account_id", "external_id"])
+            .where("source", "=", "local")
+            .where("account_id", "in", accountIds)
+            .execute();
+        return new Map(rows.map((r) => [r.account_id, r.external_id]));
+    }
+    async createByAdminIn(prepared, actorAccountId, actorTokenId, opts) {
         await this.adminLock.lockAndAuthorize(actorAccountId);
         const a = await this.insertLocal(prepared);
         await audit(this.db.db, {
@@ -98,8 +127,13 @@ let AccountsService = class AccountsService {
             ...(actorTokenId !== undefined && { actorTokenId }),
             action: "account.created",
             target: a.id,
-            detail: { superAdmin: a.isSuperAdmin },
+            detail: {
+                superAdmin: a.isSuperAdmin,
+                ...(a.mustChangePassword && { mustChangePassword: true }),
+                ...opts.auditDetail,
+            },
         });
+        await opts.inTransaction?.(a);
         return a;
     }
     /**
@@ -164,6 +198,7 @@ let AccountsService = class AccountsService {
             "accounts.email_verified",
             "accounts.status",
             "accounts.is_super_admin",
+            "accounts.must_change_password",
             "accounts.created_at",
             "accounts.updated_at",
             "local_passwords.password_hash",
@@ -201,6 +236,27 @@ let AccountsService = class AccountsService {
             .executeTakeFirst();
         return row && toAccount(row);
     }
+    /**
+     * A person's preferences (run context spec §3.4): `timeZone` is their time zone setting (IANA),
+     * null = follow the browser. Missing account → null.
+     */
+    async preferences(accountId) {
+        const row = await this.db
+            .selectFrom("accounts")
+            .select("time_zone")
+            .where("id", "=", accountId)
+            .executeTakeFirst();
+        return { timeZone: row?.time_zone ?? null };
+    }
+    /** Sets a person's preferences (the caller validated the time zone). */
+    async setPreferences(accountId, prefs) {
+        await this.db
+            .updateTable("accounts")
+            .set({ time_zone: prefs.timeZone, updated_at: new Date() })
+            .where("id", "=", accountId)
+            .execute();
+        return this.preferences(accountId);
+    }
     /** 按 id 升序分页，`after` 为上一页最后一个 id。 */
     async list(opts) {
         let q = this.db.selectFrom("accounts").selectAll().orderBy("id").limit(opts.limit);
@@ -224,6 +280,17 @@ let AccountsService = class AccountsService {
     }
     async changePasswordIn(accountId, passwordHash, exceptSessionId) {
         await this.writePassword(accountId, passwordHash);
+        // the person set their own password: the generated one is no longer theirs to be shown
+        await this.db
+            .updateTable("accounts")
+            .set({ must_change_password: false })
+            .where("id", "=", accountId)
+            .where("must_change_password", "=", true)
+            .execute();
+        await this.db
+            .deleteFrom("account_initial_passwords")
+            .where("account_id", "=", accountId)
+            .execute();
         const sessions = await this.db
             .updateTable("sessions")
             .set({ revoked_at: sql `now()` })
@@ -250,7 +317,7 @@ let AccountsService = class AccountsService {
      * all or nothing; returns the revoked session ids, whose Redis markers the caller writes after
      * the commit (the fast path; a failure is only a warning: auth reads PG).
      */
-    async updateAccount(id, patch, actorAccountId, actorTokenId) {
+    async updateAccount(id, patch, actorAccountId, actorTokenId, opts = {}) {
         // Every super admin write is serialized by one lock and re-checks the actor under it: two
         // admins revoking each other concurrently cannot leave none, and a just-revoked admin's
         // request in flight fails
@@ -265,7 +332,7 @@ let AccountsService = class AccountsService {
         return this.applyUpdate(before, patch, {
             actorAccountId,
             ...(actorTokenId !== undefined && { actorTokenId }),
-            detail: patch,
+            detail: { ...patch, ...opts.auditDetail },
         });
     }
     /**
@@ -335,6 +402,7 @@ let AccountsService = class AccountsService {
             display_name: input.displayName,
             email: input.email ?? null,
             is_super_admin: input.superAdmin ?? false,
+            must_change_password: input.mustChangePassword ?? false,
         })
             .returningAll()
             .executeTakeFirstOrThrow();

package/dist/identity/auth.guard.js

@@ -13,7 +13,7 @@ import { ApiError } from "../errors.js";
 import { AccountsService } from "./accounts.js";
 import { ApiTokenService } from "./api-tokens.js";
 import { ACCESS_COOKIE } from "./cookies.js";
-import { ALLOW_SERVICE_KEY, PUBLIC_KEY, SESSION_ONLY_KEY, SUPER_ADMIN_KEY, } from "./principal.js";
+import { ALLOW_SERVICE_KEY, PASSWORD_CHANGE_KEY, PUBLIC_KEY, SESSION_ONLY_KEY, SUPER_ADMIN_KEY, } from "./principal.js";
 import { SessionService } from "./sessions.js";
 /** CSRF 头：Cookie 认证的非安全请求（及所有公开路由的非安全请求）必须带 `X-Capybara-Csrf: 1`。 */
 export const CSRF_HEADER = "x-capybara-csrf";
@@ -76,6 +76,8 @@ export async function authorizeSuperAdmin(req, s) {
     if (p.kind === "service") {
         throw new ApiError("forbidden", "Service tokens cannot access this endpoint");
     }
+    if (p.account.mustChangePassword)
+        throw passwordChangeRequired();
     if (!p.account.isSuperAdmin)
         throw new ApiError("forbidden", "Super admin required");
 }
@@ -94,6 +96,8 @@ export async function authenticateOrgUploader(req, s) {
     if (resolved.principal.kind === "service") {
         throw new ApiError("forbidden", "Service tokens cannot access this endpoint");
     }
+    if (resolved.principal.account.mustChangePassword)
+        throw passwordChangeRequired();
     return resolved.principal;
 }
 /**
@@ -159,6 +163,9 @@ let AuthGuard = class AuthGuard {
         if (flag(SESSION_ONLY_KEY) && !(p.kind === "user" && p.via === "session")) {
             throw new ApiError("auth.session_required", "This endpoint requires a web session");
         }
+        if (p.kind === "user" && p.account.mustChangePassword && !flag(PASSWORD_CHANGE_KEY)) {
+            throw passwordChangeRequired();
+        }
         if (flag(SUPER_ADMIN_KEY) && !(p.kind === "user" && p.account.isSuperAdmin)) {
             throw new ApiError("forbidden", "Super admin required");
         }
@@ -173,6 +180,8 @@ AuthGuard = __decorate([
     __param(3, Inject(ApiTokenService))
 ], AuthGuard);
 export { AuthGuard };
+/** An account signed in with a generated initial password reaches nothing until it changes it. */
+const passwordChangeRequired = () => new ApiError("auth.password_change_required", "Set a new password first: this account signed in with a generated initial password");
 function requireActive(account) {
     if (account.status !== "active") {
         throw new ApiError("auth.account_disabled", "Account is disabled");

package/dist/identity/cookies.d.ts

@@ -29,3 +29,9 @@ export declare function clearSessionCookies(reply: FastifyReply): void;
  * Path cookie and the new one sends both, the more specific Path first.
  */
 export declare function refreshCookieValues(header: string | undefined): string[];
+/**
+ * The startup warning for an http trial that cannot sign in: session cookies are Secure but the
+ * configured public URL is plain http, so browsers drop them. Null when cookies are not Secure,
+ * or the public URL is https or unset (an unset URL says nothing about how people reach the app).
+ */
+export declare function insecurePublicUrlWarning(cfg: KernelConfig): string | null;