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

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

@@ -1,22 +1,24 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
-import type { OrgsService } from "../orgs/orgs.service.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { OrgsService } from "../orgs/orgs.service.js";
 import type { OrgRole } from "../orgs/roles.js";
-import type { Account, AccountsService } from "./accounts.js";
-import { type ApiTokenRecord, type ApiTokenService } from "./api-tokens.js";
+import { type Account, AccountsService } from "./accounts.js";
+import { type ApiTokenRecord, ApiTokenService } from "./api-tokens.js";
+import { type PreferencesSchema } from "./me.schemas.js";
 import { type Principal } from "./principal.js";
-import type { LoginRateLimiter } from "./rate-limit.js";
-import type { SessionService } from "./sessions.js";
-declare const ChangePasswordBody: z.ZodObject<{
+import { SessionService } from "./sessions.js";
+import { SettingsService } from "./settings.js";
+declare const ChangePasswordSchema: z.ZodObject<{
     currentPassword: z.ZodString;
     newPassword: z.ZodString;
 }, z.core.$strip>;
-declare const TokenBody: z.ZodObject<{
+declare const TokenSchema: z.ZodObject<{
     name: z.ZodString;
     expiresAt: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
 }, z.core.$strip>;
-declare const CurrentOrgBody: z.ZodObject<{
+declare const CurrentOrgSchema: z.ZodObject<{
     orgId: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 type MembershipView = {
@@ -31,25 +33,40 @@ export declare class MeController {
     private readonly sessions;
     private readonly orgs;
     private readonly tokens;
-    private readonly limiter;
+    private readonly throttler;
     private readonly log;
-    constructor(accounts: AccountsService, sessions: SessionService, orgs: OrgsService, tokens: ApiTokenService, limiter: LoginRateLimiter, log: Logger);
+    private readonly settings;
+    constructor(accounts: AccountsService, sessions: SessionService, orgs: OrgsService, tokens: ApiTokenService, throttler: CredentialThrottler, log: Logger, settings: SettingsService);
     me(principal: Principal): Promise<{
         account: Account;
         via: "session" | "pat";
         currentOrgId: string | null;
         memberships: MembershipView[];
+        /** 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 CurrentOrgBody>): Promise<void>;
+    setCurrentOrg(principal: Principal, body: z.infer<typeof CurrentOrgSchema>): Promise<void>;
     /**
      * 改密码：核对旧密码；成功后吊销该账号除当前会话外的所有会话，并吊销其全部个人访问令牌（R24）——
      * 三者在同一个 PG 事务里生效，之后再尽力写 Redis 吊销标记。
-     * 核对前先占用限流额度（scope `acct`：按账号 id 10 次、按客户端 IP 50 次，与登录的 IP 额度分开），
-     * 防止拿到会话的人无限次猜旧密码；超限 → 429 `auth.rate_limited`，核对成功后清零账号计数。
+     * Before the check one attempt is reserved (per account id 10, per client IP 50, apart from the
+     * login IP budget), so a stolen session cannot guess the old password forever; over the limit →
+     * 429 `auth.rate_limited`; a successful check clears the account counter.
      */
-    changePassword(principal: Principal, body: z.infer<typeof ChangePasswordBody>, req: FastifyRequest, reply: FastifyReply): Promise<void>;
-    createToken(principal: Principal, body: z.infer<typeof TokenBody>): Promise<{
+    changePassword(principal: Principal, body: z.infer<typeof ChangePasswordSchema>, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    createToken(principal: Principal, body: z.infer<typeof TokenSchema>): Promise<{
         token: string;
         record: ApiTokenRecord;
     }>;

package/dist/identity/me.controller.js

@@ -7,41 +7,55 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, Res, } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, Res, } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
-import { ACCOUNTS, API_TOKENS, KERNEL_LOG, ORGS, RATE_LIMITER, SESSIONS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
-import { FutureIsoDate } from "./api-tokens.js";
-import { clientMeta } from "./auth.controller.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+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 { 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";
-/** 改密码时同一账号在窗口内允许核对旧密码的次数。 */
-const CHANGE_PASSWORD_LIMIT_PER_ACCOUNT = 10;
-const ChangePasswordBody = z.object({
+import { PreferencesBody } from "./me.schemas.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). */
+const CHANGE_PASSWORD_THROTTLERS = ["change-password", "change-password-ip"];
+const ChangePasswordSchema = z.object({
     currentPassword: z.string().min(1),
     newPassword: z.string().min(12).max(MAX_PASSWORD_LENGTH),
 });
-const TokenBody = z.object({
+class ChangePasswordBody extends createZodDto(ChangePasswordSchema, "ChangePasswordBody") {
+}
+const TokenSchema = z.object({
     name: z.string().min(1).max(100),
     expiresAt: FutureIsoDate.optional(),
 });
-const CurrentOrgBody = z.object({ orgId: z.string().min(1).nullable() });
+class PersonalTokenBody extends createZodDto(TokenSchema, "PersonalTokenBody") {
+}
+const CurrentOrgSchema = z.object({ orgId: z.string().min(1).nullable() });
+class CurrentOrgBody extends createZodDto(CurrentOrgSchema, "CurrentOrgBody") {
+}
 /** 当前用户（`/api/v1/me`）。 */
 let MeController = class MeController {
     accounts;
     sessions;
     orgs;
     tokens;
-    limiter;
+    throttler;
     log;
-    constructor(accounts, sessions, orgs, tokens, limiter, log) {
+    settings;
+    constructor(accounts, sessions, orgs, tokens, throttler, log, settings) {
         this.accounts = accounts;
         this.sessions = sessions;
         this.orgs = orgs;
         this.tokens = tokens;
-        this.limiter = limiter;
+        this.throttler = throttler;
         this.log = log;
+        this.settings = settings;
     }
     async me(principal) {
         const p = requireUser(principal);
@@ -52,7 +66,25 @@ let MeController = class MeController {
             name: o.name,
             role: o.role,
         }));
-        return { account: p.account, via: p.via, currentOrgId, memberships };
+        // a session's org the account has since left reads as none (removal clears it, but a session
+        // created at that moment may still name it)
+        const current = memberships.some((m) => m.orgId === currentOrgId) ? currentOrgId : null;
+        const { orgCreation } = await this.settings.get();
+        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) {
@@ -65,24 +97,25 @@ let MeController = class MeController {
     /**
      * 改密码：核对旧密码；成功后吊销该账号除当前会话外的所有会话，并吊销其全部个人访问令牌（R24）——
      * 三者在同一个 PG 事务里生效，之后再尽力写 Redis 吊销标记。
-     * 核对前先占用限流额度（scope `acct`：按账号 id 10 次、按客户端 IP 50 次，与登录的 IP 额度分开），
-     * 防止拿到会话的人无限次猜旧密码；超限 → 429 `auth.rate_limited`，核对成功后清零账号计数。
+     * Before the check one attempt is reserved (per account id 10, per client IP 50, apart from the
+     * login IP budget), so a stolen session cannot guess the old password forever; over the limit →
+     * 429 `auth.rate_limited`; a successful check clears the account counter.
      */
     async changePassword(principal, body, req, reply) {
         const p = requireUser(principal);
         if (p.via !== "session") {
             throw new ApiError("auth.session_required", "This endpoint requires a web session");
         }
-        const { ip } = clientMeta(req);
-        const rl = await this.limiter.reserveScoped("acct", p.account.id, ip, CHANGE_PASSWORD_LIMIT_PER_ACCOUNT);
-        if (!rl.allowed) {
-            reply.header("retry-after", String(rl.retryAfterSeconds));
-            throw new ApiError("auth.rate_limited", "Too many failed password attempts; try again later");
-        }
+        await this.throttler.reserve(CHANGE_PASSWORD_THROTTLERS, req, reply);
         if (!(await this.accounts.verifyPassword(p.account.id, body.currentPassword))) {
             throw new ApiError("auth.invalid_credentials", "Current password is incorrect");
         }
-        await this.limiter.succeededScoped("acct", p.account.id, ip);
+        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 {
@@ -111,21 +144,32 @@ 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(),
     HttpCode(204),
     __param(0, CurrentPrincipal()),
-    __param(1, Body(new ZodPipe(CurrentOrgBody)))
+    __param(1, ZBody(CurrentOrgBody))
 ], MeController.prototype, "setCurrentOrg", null);
 __decorate([
     Put("password"),
     SessionOnly(),
+    AllowPendingPasswordChange(),
     HttpCode(204),
     __param(0, CurrentPrincipal()),
-    __param(1, Body(new ZodPipe(ChangePasswordBody))),
+    __param(1, ZBody(ChangePasswordBody)),
     __param(2, Req()),
     __param(3, Res({ passthrough: true }))
 ], MeController.prototype, "changePassword", null);
@@ -133,7 +177,7 @@ __decorate([
     Post("tokens"),
     SessionOnly(),
     __param(0, CurrentPrincipal()),
-    __param(1, Body(new ZodPipe(TokenBody)))
+    __param(1, ZBody(PersonalTokenBody))
 ], MeController.prototype, "createToken", null);
 __decorate([
     Get("tokens"),
@@ -149,11 +193,12 @@ __decorate([
 ], MeController.prototype, "revokeToken", null);
 MeController = __decorate([
     Controller("api/v1/me"),
-    __param(0, Inject(ACCOUNTS)),
-    __param(1, Inject(SESSIONS)),
-    __param(2, Inject(ORGS)),
-    __param(3, Inject(API_TOKENS)),
-    __param(4, Inject(RATE_LIMITER)),
-    __param(5, Inject(KERNEL_LOG))
+    __param(0, Inject(AccountsService)),
+    __param(1, Inject(SessionService)),
+    __param(2, Inject(OrgsService)),
+    __param(3, Inject(ApiTokenService)),
+    __param(4, Inject(CredentialThrottler)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(SettingsService))
 ], MeController);
 export { MeController };

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

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `PUT /me/preferences`: the person's preferences (run context spec §3.4). */
+export declare const PreferencesSchema: z.ZodObject<{
+    timeZone: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+declare const PreferencesBody_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    timeZone: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>>;
+export declare class PreferencesBody extends PreferencesBody_base {
+}
+/** The `/me` routes the Platform operations mirror (`check:platform-ops` keys). */
+export declare const ME_ROUTES: readonly RouteSchemas[];
+export {};

package/dist/identity/me.schemas.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { IanaTimeZone } from "../time-zone.js";
+/** `PUT /me/preferences`: the person's preferences (run context spec §3.4). */
+export const PreferencesSchema = z
+    .object({
+    /** The person's time zone (IANA); null = follow the browser (run context spec §3.4). */
+    timeZone: IanaTimeZone.nullable(),
+})
+    .strict();
+export class PreferencesBody extends createZodDto(PreferencesSchema, "PreferencesBody") {
+}
+/** The `/me` routes the Platform operations mirror (`check:platform-ops` keys). */
+export const ME_ROUTES = [
+    { route: "GET /api/v1/me/preferences" },
+    { route: "PUT /api/v1/me/preferences", body: PreferencesSchema },
+];

package/dist/identity/principal.d.ts

@@ -28,8 +28,9 @@ declare module "fastify" {
 }
 export declare const PUBLIC_KEY = "capybara:auth:public";
 export declare const SESSION_ONLY_KEY = "capybara:auth:session-only";
-export declare const ENTERPRISE_ADMIN_KEY = "capybara:auth:enterprise-admin";
+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 元测试的清单。
@@ -37,8 +38,15 @@ export declare const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
 export declare const Public: () => MethodDecorator & ClassDecorator;
 /** 仅接受 Web 会话（`via: "session"`）；个人令牌 → `auth.session_required`。 */
 export declare const SessionOnly: () => MethodDecorator;
-/** 仅企业管理员（user principal 且 `isEnterpriseAdmin`）；否则 `forbidden`。 */
-export declare const EnterpriseAdmin: () => MethodDecorator & ClassDecorator;
+/** 仅超级管理员（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

@@ -2,8 +2,9 @@ import { createParamDecorator, SetMetadata } from "@nestjs/common";
 import { ApiError } from "../errors.js";
 export const PUBLIC_KEY = "capybara:auth:public";
 export const SESSION_ONLY_KEY = "capybara:auth:session-only";
-export const ENTERPRISE_ADMIN_KEY = "capybara:auth:enterprise-admin";
+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 元测试的清单。
@@ -11,8 +12,15 @@ export const ALLOW_SERVICE_KEY = "capybara:auth:allow-service";
 export const Public = () => SetMetadata(PUBLIC_KEY, true);
 /** 仅接受 Web 会话（`via: "session"`）；个人令牌 → `auth.session_required`。 */
 export const SessionOnly = () => SetMetadata(SESSION_ONLY_KEY, true);
-/** 仅企业管理员（user principal 且 `isEnterpriseAdmin`）；否则 `forbidden`。 */
-export const EnterpriseAdmin = () => SetMetadata(ENTERPRISE_ADMIN_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/sessions.d.ts

@@ -1,6 +1,8 @@
 import type { Redis } from "ioredis";
 import type { Keyring } from "../ctx/secrets.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
 import { type Account } from "./accounts.js";
 export interface IssuedSession {
     sessionId: string;
@@ -16,25 +18,36 @@ export declare const REFRESH_RACE_GRACE_MS = 30000;
  * Web 会话服务：短期 access token（HS256 JWT，密钥由主密钥环派生）+ PG 中可吊销、一次一换的 refresh token。
  * 吊销会在 Redis 写 `capk:revoked-sid:<sid>`（TTL 覆盖任何配置下 access token 的最长剩余寿命），使所有副本立即拒绝该会话的 access token；
  * 验证 access token 时还会读 PG 的 `sessions.revoked_at`，Redis 丢数据也不会让已吊销的会话复活。
- * 框架无关，由调用方注入依赖。
+ * Token lifetimes are `auth.accessTokenTtlSeconds` / `auth.refreshTokenTtlDays`, read per session.
  */
 export declare class SessionService {
     private readonly db;
+    readonly txHost: TransactionHost;
     private readonly redis;
-    private readonly opts;
+    private readonly config;
     private readonly keys;
-    constructor(db: KernelDb, redis: Redis, keyring: Keyring, opts: {
-        accessTtlSeconds: number;
-        refreshTtlDays: number;
-    });
+    constructor(db: KernelDb, txHost: TransactionHost, redis: Redis, keyring: Keyring, config: Pick<KernelConfigService, "get">);
     /**
-     * 新建会话。传入 `trx` 时会话行在调用方的事务里写入（如初始化、凭邀请注册：与账号同一事务，
-     * 失败整体回滚）；Cookie 由调用方在提交之后再设置。
+     * Creates a session, in the context's transaction when there is one (setup and invitation
+     * signup write it with the account, rolled back together); the caller sets the cookies after the
+     * commit.
      */
     create(accountId: string, meta: {
         userAgent?: string;
         ip?: string;
-    }, trx?: KernelDb): Promise<IssuedSession>;
+    }): Promise<IssuedSession>;
+    /**
+     * The org a new session starts in: the account's last chosen one while it is still a member of it
+     * (and the org is not deleted), else its only org when it has exactly one, else none (the web
+     * app then asks to choose or create one).
+     */
+    private startingOrg;
+    /**
+     * Read-only: of several refresh tokens (a cookie header carrying the legacy and the `Path=/`
+     * cookie), the first that is the current token of a live session, if any. Choosing before
+     * rotating keeps a stale token from tripping replay detection on a still valid session.
+     */
+    pickCurrentRefresh(candidates: readonly string[]): Promise<string | undefined>;
     refresh(refreshToken: string, meta: {
         userAgent?: string;
         ip?: string;
@@ -73,6 +86,7 @@ export declare class SessionService {
      * 不会留下指向已移出组织的 `current_org_id`。非成员或组织已软删除 → `org.not_found`；`null` 清空，不查成员关系。
      */
     switchCurrentOrg(sessionId: string, accountId: string, orgId: string | null): Promise<void>;
+    private switchIn;
     /** 有效（未吊销且未过期）的会话；否则返回 undefined。 */
     get(sessionId: string): Promise<{
         id: string;