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

package/dist/identity/cookies.js

@@ -68,3 +68,17 @@ export function refreshCookieValues(header) {
     }
     return out;
 }
+/**
+ * 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 function insecurePublicUrlWarning(cfg) {
+    const url = cfg.http.publicUrl;
+    if (!cfg.auth.cookieSecure || url === undefined || !url.startsWith("http://"))
+        return null;
+    const host = new URL(url).hostname;
+    if (host === "localhost" || host.endsWith(".localhost") || host === "127.0.0.1")
+        return null;
+    return `http.publicUrl is ${url} (plain http) while auth.cookieSecure is true: browsers drop the Secure session cookies, so sign-in will not stick. Serve the app over HTTPS, or for a short http trial set auth.cookieSecure=false (CAPYBARA_AUTH__COOKIE_SECURE=false; CAPYBARA_COOKIE_SECURE=false in the compose .env)`;
+}

package/dist/identity/identity.module.js

@@ -13,6 +13,7 @@ import { ApiTokenService } from "./api-tokens.js";
 import { IdentityBinding } from "./binding.js";
 import { ExternalIdentities } from "./external.js";
 import { ExternalIdentityLock } from "./external-identity-lock.js";
+import { InitialPasswords } from "./initial-passwords.js";
 import { SessionService } from "./sessions.js";
 import { SettingsService } from "./settings.js";
 import { SsoFlow } from "./sso.js";
@@ -40,6 +41,7 @@ IdentityModule = __decorate([
             ExternalIdentities,
             IdentityBinding,
             SsoFlow,
+            InitialPasswords,
         ],
         exports: [
             AccountsModule,
@@ -50,6 +52,7 @@ IdentityModule = __decorate([
             ExternalIdentities,
             IdentityBinding,
             SsoFlow,
+            InitialPasswords,
         ],
     })
 ], IdentityModule);

package/dist/identity/initial-passwords.controller.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { InitialPasswords } from "./initial-passwords.js";
+import { type Principal } from "./principal.js";
+declare const ApprovalParams: z.ZodObject<{
+    approvalId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The generated initial password of an account the super admin's agent created (Platform tool
+ * spec §14.5 item 2): shown once, on the web, to the person who approved the `accounts.create`
+ * call. A POST because reading consumes it.
+ */
+export declare class InitialPasswordsController {
+    private readonly passwords;
+    constructor(passwords: InitialPasswords);
+    reveal(principal: Principal, org: OrgContext, params: z.infer<typeof ApprovalParams>): Promise<{
+        accountId: string;
+        login: string | null;
+        password: string;
+    }>;
+}
+export {};

package/dist/identity/initial-passwords.controller.js

@@ -0,0 +1,49 @@
+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 { Controller, HttpCode, Inject, Post } from "@nestjs/common";
+import { z } from "zod";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZParam } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { InitialPasswords } from "./initial-passwords.js";
+import { CurrentPrincipal, requireUser, SessionOnly, SuperAdmin, } from "./principal.js";
+const ApprovalParams = z.object({ approvalId: z.string().min(1).max(100) });
+class ApprovalParamsDto extends createZodDto(ApprovalParams, "InitialPasswordParams") {
+}
+/**
+ * The generated initial password of an account the super admin's agent created (Platform tool
+ * spec §14.5 item 2): shown once, on the web, to the person who approved the `accounts.create`
+ * call. A POST because reading consumes it.
+ */
+let InitialPasswordsController = class InitialPasswordsController {
+    passwords;
+    constructor(passwords) {
+        this.passwords = passwords;
+    }
+    async reveal(principal, org, params) {
+        const p = requireUser(principal);
+        return this.passwords.reveal(org.orgId, params.approvalId, p.account.id);
+    }
+};
+__decorate([
+    Post(),
+    HttpCode(200),
+    OrgAction("org.read"),
+    SuperAdmin(),
+    SessionOnly(),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ApprovalParamsDto))
+], InitialPasswordsController.prototype, "reveal", null);
+InitialPasswordsController = __decorate([
+    Controller("api/v1/orgs/:orgId/approvals/:approvalId/initial-password"),
+    __param(0, Inject(InitialPasswords))
+], InitialPasswordsController);
+export { InitialPasswordsController };

package/dist/identity/initial-passwords.d.ts

@@ -0,0 +1,61 @@
+import type { Keyring } from "../ctx/secrets.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { type Account, AccountsService } from "./accounts.js";
+/**
+ * How long a generated password waits for its reader. The approving person reads it right after
+ * the call runs; one that is never read expires (the account can still be disabled and recreated).
+ */
+export declare const INITIAL_PASSWORD_TTL_MS: number;
+/** The tool key of the approval a generated password belongs to. */
+export declare const CREATE_ACCOUNT_TOOL_KEY = "Platform:accounts.create";
+/** A one-time initial password, cryptographically random. */
+export declare function generateInitialPassword(): string;
+/** Where a generated password is delivered: the approved tool call and the person who approved. */
+export interface InitialPasswordDelivery {
+    conversationId: string;
+    /** The run of the call: a call id is unique only within its run. */
+    runId: string;
+    callId: string;
+    /** The account that may read it: the actor who confirmed the call. */
+    recipientAccountId: string;
+}
+/**
+ * Accounts created with a kernel-generated one-time password (Platform tool spec §14.5 item 2).
+ * The password never leaves the kernel except through {@link reveal}: it is not returned to the
+ * caller, not written to the audit, the event log or the logs. It is sealed with the master keyring
+ * in the creation's transaction and read once, on the web, by the person who approved the call.
+ */
+export declare class InitialPasswords {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly keyring;
+    private readonly accounts;
+    constructor(db: KernelDb, txHost: TransactionHost, keyring: Keyring, accounts: AccountsService);
+    /**
+     * Creates a local account (never a super admin) with a generated password it must change at
+     * first sign-in, and seals the password for `to`. Returns the account only.
+     */
+    createAccount(input: {
+        login: string;
+        displayName: string;
+        email?: string;
+    }, actorAccountId: string, to: InitialPasswordDelivery, auditDetail?: Record<string, unknown>): Promise<Account>;
+    /** Stores the sealed password in the creation's transaction (the hourly job drops expired ones). */
+    private seal;
+    /**
+     * The password created by an approved `accounts.create` call, read once by the person who
+     * approved it (`approvalId` in `orgId`, decided by `accountId`), then deleted. Anything else (not
+     * that person, not approved, not run yet, read already, expired) is
+     * `account.initial_password_unavailable`, saying nothing about which. Audits the read (without
+     * the password).
+     */
+    reveal(orgId: string, approvalId: string, accountId: string): Promise<{
+        accountId: string;
+        login: string | null;
+        password: string;
+    }>;
+}
+/** Deletes the sealed passwords past `expires_at`; returns how many. */
+export declare function deleteExpiredInitialPasswords(db: KernelSchemaDb): Promise<number>;

package/dist/identity/initial-passwords.job.d.ts

@@ -0,0 +1,16 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+/** The hourly cleanup of expired sealed initial passwords (`@LockedCron`). */
+export declare const INITIAL_PASSWORD_CLEANUP_JOB = "initial-password-cleanup";
+/**
+ * Deletes generated initial passwords nobody read before they expired (Platform tool spec §14.5
+ * item 2), once per tick across replicas; the worker role's.
+ */
+export declare class InitialPasswordCleanupJob {
+    private readonly db;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(db: KernelDb, lockService: LockService, log: KernelLogger);
+    cleanup(): Promise<void>;
+}

package/dist/identity/initial-passwords.job.js

@@ -0,0 +1,46 @@
+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 { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { deleteExpiredInitialPasswords } from "./initial-passwords.js";
+/** The hourly cleanup of expired sealed initial passwords (`@LockedCron`). */
+export const INITIAL_PASSWORD_CLEANUP_JOB = "initial-password-cleanup";
+/**
+ * Deletes generated initial passwords nobody read before they expired (Platform tool spec §14.5
+ * item 2), once per tick across replicas; the worker role's.
+ */
+let InitialPasswordCleanupJob = class InitialPasswordCleanupJob {
+    db;
+    lockService;
+    log;
+    constructor(db, lockService, log) {
+        this.db = db;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async cleanup() {
+        const n = await deleteExpiredInitialPasswords(this.db.db);
+        if (n > 0)
+            this.log.info("expired initial passwords deleted", { count: n });
+    }
+};
+__decorate([
+    LockedCron("20 * * * *", { name: INITIAL_PASSWORD_CLEANUP_JOB })
+], InitialPasswordCleanupJob.prototype, "cleanup", null);
+InitialPasswordCleanupJob = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(LockService)),
+    __param(2, Inject(KERNEL_LOGGER))
+], InitialPasswordCleanupJob);
+export { InitialPasswordCleanupJob };

package/dist/identity/initial-passwords.js

@@ -0,0 +1,159 @@
+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 { randomInt } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KEYRING } from "../infra/tokens.js";
+import { AccountsService } from "./accounts.js";
+import { audit } from "./audit.js";
+/** Letters and digits without the look-alikes (0 O 1 l I): read off a screen and typed by hand. */
+const ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789";
+/** 20 characters of 56: about 116 bits. */
+const LENGTH = 20;
+/**
+ * How long a generated password waits for its reader. The approving person reads it right after
+ * the call runs; one that is never read expires (the account can still be disabled and recreated).
+ */
+export const INITIAL_PASSWORD_TTL_MS = 24 * 60 * 60 * 1000;
+/** The tool key of the approval a generated password belongs to. */
+export const CREATE_ACCOUNT_TOOL_KEY = "Platform:accounts.create";
+/** A one-time initial password, cryptographically random. */
+export function generateInitialPassword() {
+    let out = "";
+    for (let i = 0; i < LENGTH; i++)
+        out += ALPHABET[randomInt(ALPHABET.length)];
+    return out;
+}
+/** The AAD binding a sealed password to its account (a row moved to another account fails). */
+const aadOf = (accountId) => `capybara:initial-password:${accountId}`;
+/**
+ * Accounts created with a kernel-generated one-time password (Platform tool spec §14.5 item 2).
+ * The password never leaves the kernel except through {@link reveal}: it is not returned to the
+ * caller, not written to the audit, the event log or the logs. It is sealed with the master keyring
+ * in the creation's transaction and read once, on the web, by the person who approved the call.
+ */
+let InitialPasswords = class InitialPasswords {
+    db;
+    txHost;
+    keyring;
+    accounts;
+    constructor(db, txHost, keyring, accounts) {
+        this.db = db;
+        this.txHost = txHost;
+        this.keyring = keyring;
+        this.accounts = accounts;
+    }
+    /**
+     * Creates a local account (never a super admin) with a generated password it must change at
+     * first sign-in, and seals the password for `to`. Returns the account only.
+     */
+    async createAccount(input, actorAccountId, to, auditDetail) {
+        const password = generateInitialPassword();
+        return this.accounts.createByAdmin({ ...input, password, superAdmin: false, mustChangePassword: true }, actorAccountId, undefined, {
+            ...(auditDetail !== undefined && { auditDetail }),
+            inTransaction: (account) => this.seal(account.id, password, to),
+        });
+    }
+    /** Stores the sealed password in the creation's transaction (the hourly job drops expired ones). */
+    async seal(accountId, password, to) {
+        const { data, masterKeyId } = this.keyring.wrap(Buffer.from(password, "utf8"), aadOf(accountId));
+        await this.db
+            .insertInto("account_initial_passwords")
+            .values({
+            account_id: accountId,
+            recipient_account_id: to.recipientAccountId,
+            conversation_id: to.conversationId,
+            run_id: to.runId,
+            call_id: to.callId,
+            master_key_id: masterKeyId,
+            ciphertext: data,
+            expires_at: new Date(Date.now() + INITIAL_PASSWORD_TTL_MS),
+        })
+            .execute();
+    }
+    /**
+     * The password created by an approved `accounts.create` call, read once by the person who
+     * approved it (`approvalId` in `orgId`, decided by `accountId`), then deleted. Anything else (not
+     * that person, not approved, not run yet, read already, expired) is
+     * `account.initial_password_unavailable`, saying nothing about which. Audits the read (without
+     * the password).
+     */
+    async reveal(orgId, approvalId, accountId) {
+        const unavailable = () => new ApiError("account.initial_password_unavailable", "No initial password to show: it was shown already, has expired, or the account was not created by a call you approved");
+        const approval = await this.db
+            .selectFrom("approvals")
+            .select(["conversation_id", "run_id", "call_id", "tool_key", "status", "decided_by"])
+            .where("id", "=", approvalId)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (approval === undefined ||
+            approval.tool_key !== CREATE_ACCOUNT_TOOL_KEY ||
+            approval.status !== "approved" ||
+            approval.decided_by !== accountId) {
+            throw unavailable();
+        }
+        // exactly the row of this approval's call: locked, then deleted by its key
+        const found = await this.db
+            .selectFrom("account_initial_passwords")
+            .select("account_id")
+            .where("conversation_id", "=", approval.conversation_id)
+            .where("run_id", "=", approval.run_id)
+            .where("call_id", "=", approval.call_id)
+            .where("recipient_account_id", "=", accountId)
+            .where("expires_at", ">", sql `now()`)
+            .limit(1)
+            .forUpdate()
+            .executeTakeFirst();
+        if (found === undefined)
+            throw unavailable();
+        const row = await this.db
+            .deleteFrom("account_initial_passwords")
+            .where("account_id", "=", found.account_id)
+            .returning(["account_id", "master_key_id", "ciphertext"])
+            .executeTakeFirst();
+        if (row === undefined)
+            throw unavailable();
+        const password = this.keyring
+            .unwrap(row.master_key_id, row.ciphertext, aadOf(row.account_id))
+            .toString("utf8");
+        const login = (await this.accounts.localLogins([row.account_id])).get(row.account_id) ?? null;
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            orgId,
+            action: "account.initial_password_shown",
+            target: row.account_id,
+            detail: { approvalId },
+        });
+        return { accountId: row.account_id, login, password };
+    }
+};
+__decorate([
+    Transactional()
+], InitialPasswords.prototype, "reveal", null);
+InitialPasswords = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(KEYRING)),
+    __param(3, Inject(AccountsService))
+], InitialPasswords);
+export { InitialPasswords };
+/** Deletes the sealed passwords past `expires_at`; returns how many. */
+export async function deleteExpiredInitialPasswords(db) {
+    const r = await db
+        .deleteFrom("account_initial_passwords")
+        .where("expires_at", "<=", sql `now()`)
+        .executeTakeFirst();
+    return Number(r.numDeletedRows);
+}

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

@@ -17,6 +17,9 @@ declare const TokenSchema: z.ZodObject<{
     name: z.ZodString;
     expiresAt: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
 }, z.core.$strip>;
+declare const PreferencesSchema: z.ZodObject<{
+    timeZone: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
 declare const CurrentOrgSchema: z.ZodObject<{
     orgId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
@@ -44,6 +47,17 @@ export declare class MeController {
         /** Whether `POST /api/v1/orgs` would accept this account (the `orgCreation` setting). */
         canCreateOrg: boolean;
     }>;
+    /**
+     * The person's preferences (run context spec §3.4): `timeZone` null = follow the browser's time
+     * zone sent with each message; a set zone overrides it for the messages sent afterwards.
+     */
+    preferences(principal: Principal): Promise<{
+        timeZone: string | null;
+    }>;
+    /** Replaces the person's preferences; an unknown time zone → 400 `validation_failed`. */
+    setPreferences(principal: Principal, body: z.infer<typeof PreferencesSchema>): Promise<{
+        timeZone: string | null;
+    }>;
     /** 切换当前组织（仅 Web 会话）；`null` 清空。非成员或已软删除的组织 → `org.not_found`。 */
     setCurrentOrg(principal: Principal, body: z.infer<typeof CurrentOrgSchema>): Promise<void>;
     /**

package/dist/identity/me.controller.js

@@ -15,10 +15,11 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { OrgsService } from "../orgs/orgs.service.js";
+import { IanaTimeZone } from "../time-zone.js";
 import { AccountsService } from "./accounts.js";
 import { ApiTokenService, FutureIsoDate } from "./api-tokens.js";
 import { MAX_PASSWORD_LENGTH } from "./login.js";
-import { CurrentPrincipal, requireUser, SessionOnly } from "./principal.js";
+import { AllowPendingPasswordChange, CurrentPrincipal, requireUser, SessionOnly, } from "./principal.js";
 import { SessionService } from "./sessions.js";
 import { SettingsService } from "./settings.js";
 /** The credential throttlers of a password change (per account, per client IP). */
@@ -35,6 +36,14 @@ const TokenSchema = z.object({
 });
 class PersonalTokenBody extends createZodDto(TokenSchema, "PersonalTokenBody") {
 }
+const PreferencesSchema = z
+    .object({
+    /** The person's time zone (IANA); null = follow the browser (run context spec §3.4). */
+    timeZone: IanaTimeZone.nullable(),
+})
+    .strict();
+class PreferencesBody extends createZodDto(PreferencesSchema, "PreferencesBody") {
+}
 const CurrentOrgSchema = z.object({ orgId: z.string().min(1).nullable() });
 class CurrentOrgBody extends createZodDto(CurrentOrgSchema, "CurrentOrgBody") {
 }
@@ -72,6 +81,19 @@ let MeController = class MeController {
         const canCreateOrg = orgCreation === "anyone" || p.account.isSuperAdmin;
         return { account: p.account, via: p.via, currentOrgId: current, memberships, canCreateOrg };
     }
+    /**
+     * The person's preferences (run context spec §3.4): `timeZone` null = follow the browser's time
+     * zone sent with each message; a set zone overrides it for the messages sent afterwards.
+     */
+    async preferences(principal) {
+        return this.accounts.preferences(requireUser(principal).account.id);
+    }
+    /** Replaces the person's preferences; an unknown time zone → 400 `validation_failed`. */
+    async setPreferences(principal, body) {
+        return this.accounts.setPreferences(requireUser(principal).account.id, {
+            timeZone: body.timeZone,
+        });
+    }
     /** 切换当前组织（仅 Web 会话）；`null` 清空。非成员或已软删除的组织 → `org.not_found`。 */
     async setCurrentOrg(principal, body) {
         const p = requireUser(principal);
@@ -97,6 +119,11 @@ let MeController = class MeController {
             throw new ApiError("auth.invalid_credentials", "Current password is incorrect");
         }
         await this.throttler.succeeded(CHANGE_PASSWORD_THROTTLERS, req);
+        if (p.account.mustChangePassword && body.newPassword === body.currentPassword) {
+            throw new ApiError("validation_failed", "Choose a password other than the initial one", [
+                { path: "newPassword", message: "must differ from the initial password" },
+            ]);
+        }
         // 新密码、吊销其他会话（PG revoked_at）与个人令牌在同一个 PG 事务里完成
         const revoked = await this.accounts.changePassword(p.account.id, body.newPassword, p.sessionId);
         try {
@@ -125,8 +152,18 @@ let MeController = class MeController {
 };
 __decorate([
     Get(),
+    AllowPendingPasswordChange(),
     __param(0, CurrentPrincipal())
 ], MeController.prototype, "me", null);
+__decorate([
+    Get("preferences"),
+    __param(0, CurrentPrincipal())
+], MeController.prototype, "preferences", null);
+__decorate([
+    Put("preferences"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZBody(PreferencesBody))
+], MeController.prototype, "setPreferences", null);
 __decorate([
     Put("current-org"),
     SessionOnly(),
@@ -137,6 +174,7 @@ __decorate([
 __decorate([
     Put("password"),
     SessionOnly(),
+    AllowPendingPasswordChange(),
     HttpCode(204),
     __param(0, CurrentPrincipal()),
     __param(1, ZBody(ChangePasswordBody)),

package/dist/identity/principal.d.ts

@@ -30,6 +30,7 @@ export declare const PUBLIC_KEY = "capybara:auth:public";
 export declare const SESSION_ONLY_KEY = "capybara:auth:session-only";
 export declare const SUPER_ADMIN_KEY = "capybara:auth:super-admin";
 export declare const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
+export declare const PASSWORD_CHANGE_KEY = "capybara:auth:password-change";
 /**
  * 不要求凭据：无凭据时放行（principal 为 undefined）；带了有效凭据仍解析，无效凭据按无凭据处理。
  * 非安全方法照样要求 `X-Capybara-Csrf: 1`（防登录 CSRF）。新增公开路由必须同时更新 public-routes 元测试的清单。
@@ -39,6 +40,13 @@ export declare const Public: () => MethodDecorator & ClassDecorator;
 export declare const SessionOnly: () => MethodDecorator;
 /** 仅超级管理员（user principal 且 `isSuperAdmin`）；否则 `forbidden`。 */
 export declare const SuperAdmin: () => MethodDecorator & ClassDecorator;
+/**
+ * Reachable by an account that must change its generated initial password first
+ * (`Account.mustChangePassword`): the guard refuses every other route with
+ * `auth.password_change_required`. Only `GET /me` and `PUT /me/password` carry it (public routes
+ * such as logout are reachable anyway).
+ */
+export declare const AllowPendingPasswordChange: () => MethodDecorator;
 /**
  * 允许服务令牌（service principal）访问。默认拒绝：未标注的路由只接受 user principal，service → `forbidden`。
  * 组织级路由由 OrgGuard 再核对令牌所属组织与角色。

package/dist/identity/principal.js

@@ -4,6 +4,7 @@ export const PUBLIC_KEY = "capybara:auth:public";
 export const SESSION_ONLY_KEY = "capybara:auth:session-only";
 export const SUPER_ADMIN_KEY = "capybara:auth:super-admin";
 export const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
+export const PASSWORD_CHANGE_KEY = "capybara:auth:password-change";
 /**
  * 不要求凭据：无凭据时放行（principal 为 undefined）；带了有效凭据仍解析，无效凭据按无凭据处理。
  * 非安全方法照样要求 `X-Capybara-Csrf: 1`（防登录 CSRF）。新增公开路由必须同时更新 public-routes 元测试的清单。
@@ -13,6 +14,13 @@ export const Public = () => SetMetadata(PUBLIC_KEY, true);
 export const SessionOnly = () => SetMetadata(SESSION_ONLY_KEY, true);
 /** 仅超级管理员（user principal 且 `isSuperAdmin`）；否则 `forbidden`。 */
 export const SuperAdmin = () => SetMetadata(SUPER_ADMIN_KEY, true);
+/**
+ * Reachable by an account that must change its generated initial password first
+ * (`Account.mustChangePassword`): the guard refuses every other route with
+ * `auth.password_change_required`. Only `GET /me` and `PUT /me/password` carry it (public routes
+ * such as logout are reachable anyway).
+ */
+export const AllowPendingPasswordChange = () => SetMetadata(PASSWORD_CHANGE_KEY, true);
 /**
  * 允许服务令牌（service principal）访问。默认拒绝：未标注的路由只接受 user principal，service → `forbidden`。
  * 组织级路由由 OrgGuard 再核对令牌所属组织与角色。

package/dist/identity/settings.d.ts

@@ -133,6 +133,8 @@ export declare class SettingsService {
      */
     get(): Promise<DeploymentSettings>;
     /** Updates settings under the super admin lock, re-checking the actor (else `forbidden`). */
-    update(patch: DeploymentSettingsPatch, actorAccountId: string, actorTokenId?: string): Promise<DeploymentSettings>;
+    update(patch: DeploymentSettingsPatch, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<DeploymentSettings>;
     private write;
 }

package/dist/identity/settings.js

@@ -241,15 +241,17 @@ let SettingsService = class SettingsService {
         return out;
     }
     /** Updates settings under the super admin lock, re-checking the actor (else `forbidden`). */
-    async update(patch, actorAccountId, actorTokenId) {
+    async update(patch, actorAccountId, actorTokenId, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail) {
         const check = DEPLOYMENT_SETTINGS_PATCH.safeParse(patch);
         if (!check.success) {
             throw new ApiError("validation_failed", "Invalid deployment settings", check.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })));
         }
-        await this.write(check.data, actorAccountId, actorTokenId);
+        await this.write(check.data, actorAccountId, actorTokenId, auditDetail);
         return this.get();
     }
-    async write(patch, actorAccountId, actorTokenId) {
+    async write(patch, actorAccountId, actorTokenId, auditDetail) {
         await this.adminLock.lockAndAuthorize(actorAccountId);
         // The super admin lock serializes every settings write: the current overrides are read
         // and merged under it, so no concurrent change is lost
@@ -294,7 +296,7 @@ let SettingsService = class SettingsService {
             actorAccountId,
             ...(actorTokenId !== undefined && { actorTokenId }),
             action: "deployment.settings.updated",
-            detail: patch,
+            detail: { ...patch, ...auditDetail },
         });
     }
 };

package/dist/inbox/inbox.schemas.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `:id` of a notice dismissal (the org's and the platform's inbox). */
+export declare const InboxNoticeParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/** The inbox routes (the org's and the super admin's) the Platform inbox operations mirror. */
+export declare const INBOX_ROUTES: readonly RouteSchemas[];

package/dist/inbox/inbox.schemas.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/** `:id` of a notice dismissal (the org's and the platform's inbox). */
+export const InboxNoticeParams = z.object({ id: z.string().min(1).max(100) });
+/** The inbox routes (the org's and the super admin's) the Platform inbox operations mirror. */
+export const INBOX_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/inbox" },
+    { route: "POST /api/v1/orgs/:orgId/inbox/notices/:id/dismiss", params: InboxNoticeParams },
+    { route: "GET /api/v1/admin/inbox" },
+    { route: "GET /api/v1/admin/inbox/count" },
+    { route: "POST /api/v1/admin/inbox/notices/:id/dismiss", params: InboxNoticeParams },
+];

package/dist/inbox/platform-inbox.controller.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import type { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { PlatformInboxService, type PlatformInboxView } from "./platform-inbox.service.js";
 declare const NoticeParamsSchema: z.ZodObject<{

package/dist/inbox/platform-inbox.controller.js

@@ -8,12 +8,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, HttpCode, Inject, Post } from "@nestjs/common";
-import { z } from "zod";
 import { CurrentPrincipal, requireUser, SuperAdmin, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZParam } from "../infra/validation/zod-params.js";
+import { InboxNoticeParams } from "./inbox.schemas.js";
 import { PlatformInboxService } from "./platform-inbox.service.js";
-const NoticeParamsSchema = z.object({ id: z.string().min(1).max(100) });
+const NoticeParamsSchema = InboxNoticeParams;
 class NoticeParams extends createZodDto(NoticeParamsSchema, "PlatformInboxNoticeParams") {
 }
 /**