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

package/dist/identity/accounts.js

@@ -15,17 +15,19 @@ 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 { assertThemeOnForAccount } from "../themes/theme-state.js";
 import { audit } from "./audit.js";
-import { EnterpriseAdminLock, EnterpriseAdminLockModule } from "./enterprise-admin.js";
 import { MAX_PASSWORD_LENGTH, normalizeLogin, validatePassword } from "./login.js";
 import { DUMMY_PASSWORD_HASH, hashPassword, verifyPassword } from "./passwords.js";
+import { SuperAdminLock, SuperAdminLockModule } from "./super-admin.js";
 /** 构造 `Account` 所需的 accounts 列（供跨表查询 select 使用）。 */
 export const ACCOUNT_COLUMNS = [
     "accounts.id",
     "accounts.display_name",
     "accounts.email",
     "accounts.status",
-    "accounts.is_enterprise_admin",
+    "accounts.is_super_admin",
+    "accounts.must_change_password",
     "accounts.created_at",
 ];
 export function toAccount(r) {
@@ -34,7 +36,8 @@ export function toAccount(r) {
         displayName: r.display_name,
         email: r.email,
         status: r.status,
-        isEnterpriseAdmin: r.is_enterprise_admin,
+        isSuperAdmin: r.is_super_admin,
+        mustChangePassword: r.must_change_password,
         createdAt: r.created_at,
     };
 }
@@ -82,15 +85,42 @@ let AccountsService = class AccountsService {
         return this.insertLocal(await prepareLocal(input, passwordHash));
     }
     /**
-     * An enterprise admin creates a local account (optionally an enterprise admin): under the
-     * enterprise admin lock, re-checks that the actor is still an active enterprise admin (else
+     * A super admin creates a local account (optionally a super admin): under the
+     * super admin lock, re-checks that the actor is still an active super admin (else
      * `forbidden`), creates the account and audits `account.created`. The hash is computed before
      * the lock.
      */
-    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,45 +128,50 @@ let AccountsService = class AccountsService {
             ...(actorTokenId !== undefined && { actorTokenId }),
             action: "account.created",
             target: a.id,
-            detail: { enterpriseAdmin: a.isEnterpriseAdmin },
+            detail: {
+                superAdmin: a.isSuperAdmin,
+                ...(a.mustChangePassword && { mustChangePassword: true }),
+                ...opts.auditDetail,
+            },
         });
+        await opts.inTransaction?.(a);
         return a;
     }
     /**
-     * CLI: creates an enterprise admin without checking whether the deployment is set up; a taken
+     * CLI: creates a super admin without checking whether the deployment is set up; a taken
      * login → `account.login_taken`.
      */
-    async createEnterpriseAdmin(input) {
-        return this.insertEnterpriseAdmin(input, await this.hashNewPassword(input.password));
+    async createSuperAdmin(input) {
+        return this.insertSuperAdmin(input, await this.hashNewPassword(input.password));
     }
     /**
-     * CLI `admin create --if-none`: creates an enterprise admin only when no active one exists. The
+     * CLI `admin create --if-none`: creates a super admin only when no active one exists. The
      * check and the insert run in one transaction under {@link SetupLock}, the lock the web setup
      * takes, so concurrent runs (and a concurrent web setup) create exactly one. Returns undefined
-     * when an active enterprise admin already exists; a taken login still throws
+     * when an active super admin already exists; a taken login still throws
      * `account.login_taken`.
      */
-    async createEnterpriseAdminIfNone(input) {
-        return this.createEnterpriseAdminIfNoneIn(input, await this.hashNewPassword(input.password));
+    async createSuperAdminIfNone(input) {
+        return this.createSuperAdminIfNoneIn(input, await this.hashNewPassword(input.password));
     }
-    async createEnterpriseAdminIfNoneIn(input, passwordHash) {
+    async createSuperAdminIfNoneIn(input, passwordHash) {
         await this.setupLock.lock();
-        if ((await this.countEnterpriseAdmins()) > 0)
+        if ((await this.countSuperAdmins()) > 0)
             return undefined;
-        return this.insertEnterpriseAdmin(input, passwordHash);
+        return this.insertSuperAdmin(input, passwordHash);
     }
-    async insertEnterpriseAdmin(input, passwordHash) {
+    async insertSuperAdmin(input, passwordHash) {
         const account = await this.createLocal({
             login: input.login,
             password: input.password,
             displayName: input.displayName,
-            enterpriseAdmin: true,
+            superAdmin: true,
             ...(input.email !== undefined && { email: input.email }),
         }, passwordHash);
         await audit(this.db.db, {
             action: "account.created",
             target: account.id,
-            detail: { enterpriseAdmin: true, via: "cli" },
+            detail: { superAdmin: true, via: "cli" },
         });
         return account;
     }
@@ -163,7 +198,8 @@ let AccountsService = class AccountsService {
             "accounts.email",
             "accounts.email_verified",
             "accounts.status",
-            "accounts.is_enterprise_admin",
+            "accounts.is_super_admin",
+            "accounts.must_change_password",
             "accounts.created_at",
             "accounts.updated_at",
             "local_passwords.password_hash",
@@ -201,6 +237,39 @@ let AccountsService = class AccountsService {
             .executeTakeFirst();
         return row && toAccount(row);
     }
+    /**
+     * A person's preferences: `timeZone` is their time zone setting (IANA), null = follow the browser
+     * (run context spec §3.4); `theme` their theme (a `platform_themes` id), null = follow the org
+     * (themes spec §7). Missing account -> nulls.
+     */
+    async preferences(accountId) {
+        const row = await this.db
+            .selectFrom("accounts")
+            .select(["time_zone", "theme"])
+            .where("id", "=", accountId)
+            .executeTakeFirst();
+        return { timeZone: row?.time_zone ?? null, theme: row?.theme ?? null };
+    }
+    /**
+     * Updates the preferences given (a field left out keeps its value; the caller validated the time
+     * zone). A theme must be on in at least one of the person's orgs, else 400 `theme.not_available`.
+     */
+    async setPreferences(accountId, prefs) {
+        if (prefs.theme != null)
+            await assertThemeOnForAccount(this.db.db, accountId, prefs.theme);
+        const set = {
+            ...(prefs.timeZone !== undefined && { time_zone: prefs.timeZone }),
+            ...(prefs.theme !== undefined && { theme: prefs.theme }),
+        };
+        if (Object.keys(set).length > 0) {
+            await this.db
+                .updateTable("accounts")
+                .set({ ...set, 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 +293,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()` })
@@ -245,13 +325,13 @@ let AccountsService = class AccountsService {
         return (await this.updateAccount(id, patch, actorAccountId, actorTokenId)).account;
     }
     /**
-     * An enterprise admin changes an account. Disabling (`status: "disabled"`) revokes the
+     * A super admin changes an account. Disabling (`status: "disabled"`) revokes the
      * account's sessions (`sessions.revoked_at`) and personal tokens in **the same PG transaction**,
      * all or nothing; returns the revoked session ids, whose Redis markers the caller writes after
      * the commit (the fast path; a failure is only a warning: auth reads PG).
      */
-    async updateAccount(id, patch, actorAccountId, actorTokenId) {
-        // Every enterprise admin write is serialized by one lock and re-checks the actor under it: two
+    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
         await this.adminLock.lockAndAuthorize(actorAccountId);
@@ -265,18 +345,18 @@ let AccountsService = class AccountsService {
         return this.applyUpdate(before, patch, {
             actorAccountId,
             ...(actorTokenId !== undefined && { actorTokenId }),
-            detail: patch,
+            detail: { ...patch, ...opts.auditDetail },
         });
     }
     /**
-     * The CLI's `capybara admin grant|revoke <login>` (no actor account): changes the enterprise
-     * admin flag by local login under the enterprise admin lock; revoking keeps the
-     * {@link updateAccount} "last active enterprise admin" check (`account.last_enterprise_admin`),
+     * The CLI's `capybara admin grant|revoke <login>` (no actor account): changes the super
+     * admin flag by local login under the super admin lock; revoking keeps the
+     * {@link updateAccount} "last active super admin" check (`account.last_super_admin`),
      * decided under the lock, so it cannot race a web revoke into none. Audit `account.updated`
      * without an actor, `detail.via = "cli"`. Already in the target state → no change and no audit
      * (`changed: false`). Unknown login → `account.not_found`.
      */
-    async setEnterpriseAdminByLogin(login, isEnterpriseAdmin) {
+    async setSuperAdminByLogin(login, isSuperAdmin) {
         let external;
         try {
             external = normalizeLogin(login);
@@ -284,9 +364,9 @@ let AccountsService = class AccountsService {
         catch {
             throw new ApiError("account.not_found", "Account not found");
         }
-        return this.setEnterpriseAdminIn(external, isEnterpriseAdmin);
+        return this.setSuperAdminIn(external, isSuperAdmin);
     }
-    async setEnterpriseAdminIn(external, isEnterpriseAdmin) {
+    async setSuperAdminIn(external, isSuperAdmin) {
         await this.adminLock.lock();
         const before = await this.db
             .selectFrom("identities")
@@ -297,10 +377,10 @@ let AccountsService = class AccountsService {
             .executeTakeFirst();
         if (!before)
             throw new ApiError("account.not_found", "Account not found");
-        if (before.is_enterprise_admin === isEnterpriseAdmin) {
+        if (before.is_super_admin === isSuperAdmin) {
             return { account: toAccount(before), changed: false };
         }
-        const patch = { isEnterpriseAdmin };
+        const patch = { isSuperAdmin };
         const { account } = await this.applyUpdate(before, patch, {
             detail: { ...patch, via: "cli" },
         });
@@ -314,12 +394,12 @@ let AccountsService = class AccountsService {
             .executeTakeFirstOrThrow();
         return Number(r.n);
     }
-    /** Active (status = active) enterprise admins, in the context's transaction when there is one. */
-    async countEnterpriseAdmins() {
+    /** Active (status = active) super admins, in the context's transaction when there is one. */
+    async countSuperAdmins() {
         const r = await this.db
             .selectFrom("accounts")
             .select((eb) => eb.fn.countAll().as("n"))
-            .where("is_enterprise_admin", "=", true)
+            .where("is_super_admin", "=", true)
             .where("status", "=", "active")
             .executeTakeFirstOrThrow();
         return Number(r.n);
@@ -334,7 +414,8 @@ let AccountsService = class AccountsService {
             id,
             display_name: input.displayName,
             email: input.email ?? null,
-            is_enterprise_admin: input.enterpriseAdmin ?? false,
+            is_super_admin: input.superAdmin ?? false,
+            must_change_password: input.mustChangePassword ?? false,
         })
             .returningAll()
             .executeTakeFirstOrThrow();
@@ -380,8 +461,8 @@ let AccountsService = class AccountsService {
             .execute();
     }
     /**
-     * Changes the account under the enterprise admin lock the caller holds: updates the row,
-     * re-checks "the last active enterprise admin", audits `account.updated`; disabling revokes the
+     * Changes the account under the super admin lock the caller holds: updates the row,
+     * re-checks "the last active super admin", audits `account.updated`; disabling revokes the
      * account's sessions and personal tokens.
      */
     async applyUpdate(before, patch, auditAs) {
@@ -391,18 +472,18 @@ let AccountsService = class AccountsService {
             values.display_name = patch.displayName;
         if (patch.status !== undefined)
             values.status = patch.status;
-        if (patch.isEnterpriseAdmin !== undefined)
-            values.is_enterprise_admin = patch.isEnterpriseAdmin;
+        if (patch.isSuperAdmin !== undefined)
+            values.is_super_admin = patch.isSuperAdmin;
         const row = await this.db
             .updateTable("accounts")
             .set(values)
             .where("id", "=", id)
             .returningAll()
             .executeTakeFirstOrThrow();
-        const wasActiveAdmin = before.is_enterprise_admin && before.status === "active";
-        const isActiveAdmin = row.is_enterprise_admin && row.status === "active";
-        if (wasActiveAdmin && !isActiveAdmin && (await this.countEnterpriseAdmins()) === 0) {
-            throw new ApiError("account.last_enterprise_admin", "Cannot remove the last active enterprise admin");
+        const wasActiveAdmin = before.is_super_admin && before.status === "active";
+        const isActiveAdmin = row.is_super_admin && row.status === "active";
+        if (wasActiveAdmin && !isActiveAdmin && (await this.countSuperAdmins()) === 0) {
+            throw new ApiError("account.last_super_admin", "Cannot remove the last active super admin");
         }
         await audit(this.db.db, {
             ...(auditAs.actorAccountId !== undefined && { actorAccountId: auditAs.actorAccountId }),
@@ -439,10 +520,10 @@ __decorate([
 ], AccountsService.prototype, "createByAdminIn", null);
 __decorate([
     Transactional()
-], AccountsService.prototype, "createEnterpriseAdminIfNoneIn", null);
+], AccountsService.prototype, "createSuperAdminIfNoneIn", null);
 __decorate([
     Transactional()
-], AccountsService.prototype, "insertEnterpriseAdmin", null);
+], AccountsService.prototype, "insertSuperAdmin", null);
 __decorate([
     Transactional()
 ], AccountsService.prototype, "changePasswordIn", null);
@@ -451,7 +532,7 @@ __decorate([
 ], AccountsService.prototype, "updateAccount", null);
 __decorate([
     Transactional()
-], AccountsService.prototype, "setEnterpriseAdminIn", null);
+], AccountsService.prototype, "setSuperAdminIn", null);
 __decorate([
     Transactional()
 ], AccountsService.prototype, "insertLocal", null);
@@ -465,7 +546,7 @@ AccountsService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
-    __param(2, Inject(EnterpriseAdminLock)),
+    __param(2, Inject(SuperAdminLock)),
     __param(3, Inject(SetupLock))
 ], AccountsService);
 export { AccountsService };
@@ -478,7 +559,7 @@ let AccountsModule = class AccountsModule {
 };
 AccountsModule = __decorate([
     Module({
-        imports: [SetupLockModule, EnterpriseAdminLockModule],
+        imports: [SetupLockModule, SuperAdminLockModule],
         providers: [AccountsService],
         exports: [AccountsService],
     })

package/dist/identity/audit.d.ts

@@ -5,7 +5,8 @@ import type { KernelSchemaDb } from "../db/kernel-schema.js";
  * so the event commits or rolls back with the write it records.
  */
 export declare function audit(db: KernelSchemaDb, e: {
-    actorAccountId?: string;
+    /** The acting account; absent or null for the kernel itself (a job such as the scope sync). */
+    actorAccountId?: string | null;
     actorTokenId?: string;
     orgId?: string;
     action: string;

package/dist/identity/auth.controller.js

@@ -15,7 +15,7 @@ import { CredentialThrottler } from "../infra/throttler/credential-throttler.js"
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { AccountsService } from "./accounts.js";
-import { ACCESS_COOKIE, clearSessionCookies, REFRESH_COOKIE, setSessionCookies, } from "./cookies.js";
+import { ACCESS_COOKIE, clearSessionCookies, refreshCookieValues, setSessionCookies, } from "./cookies.js";
 import { Public } from "./principal.js";
 import { SessionService } from "./sessions.js";
 const LoginBodySchema = z.object({ login: z.string().max(256), password: z.string() });
@@ -74,9 +74,13 @@ let AuthController = class AuthController {
      */
     async refresh(req, reply) {
         try {
-            const rt = req.cookies[REFRESH_COOKIE];
-            if (!rt)
+            // the header may carry several cap_rt (legacy Path and Path=/): the current one of a live session wins
+            const candidates = refreshCookieValues(req.headers.cookie);
+            if (candidates.length === 0) {
                 throw new ApiError("auth.refresh_invalid", "Refresh token is missing");
+            }
+            // none is current: the last one (the Path=/ cookie) goes through the usual replay handling
+            const rt = (await this.sessions.pickCurrentRefresh(candidates)) ?? candidates.at(-1);
             const session = await this.sessions.refresh(rt, clientMeta(req));
             const account = await this.accounts.get(session.accountId);
             if (!account)
@@ -94,13 +98,13 @@ let AuthController = class AuthController {
     async logout(req, reply) {
         clearSessionCookies(reply);
         const at = req.cookies[ACCESS_COOKIE];
-        const rt = req.cookies[REFRESH_COOKIE];
+        const rts = refreshCookieValues(req.headers.cookie);
         if (at) {
             const sid = await this.sessions.sessionIdFromAccess(at);
             if (sid !== undefined)
                 await this.sessions.revoke(sid);
         }
-        if (rt)
+        for (const rt of rts)
             await this.sessions.revokeByRefresh(rt);
     }
 };

package/dist/identity/auth.guard.d.ts

@@ -3,21 +3,29 @@ import { Reflector } from "@nestjs/core";
 import type { FastifyRequest } from "fastify";
 import { AccountsService } from "./accounts.js";
 import { ApiTokenService } from "./api-tokens.js";
+import { type Principal } from "./principal.js";
 import { SessionService } from "./sessions.js";
 /** CSRF 头：Cookie 认证的非安全请求（及所有公开路由的非安全请求）必须带 `X-Capybara-Csrf: 1`。 */
 export declare const CSRF_HEADER = "x-capybara-csrf";
-/** 解析凭据要用的服务（{@link AuthGuard} 与 {@link authorizeEnterpriseAdmin} 共用）。 */
+/** 解析凭据要用的服务（{@link AuthGuard} 与 {@link authorizeSuperAdmin} 共用）。 */
 export interface AuthServices {
     accounts: AccountsService;
     sessions: SessionService;
     tokens: ApiTokenService;
 }
 /**
- * 在读请求体之前（Fastify `onRequest`）按 `@EnterpriseAdmin` 路由的规则认证：无凭据 / 凭据无效 → `auth.required`
- * 等，Cookie 认证的非安全请求要求 CSRF 头，服务令牌与非企业管理员 → `forbidden`。插件包上传用它：
+ * 在读请求体之前（Fastify `onRequest`）按 `@SuperAdmin` 路由的规则认证：无凭据 / 凭据无效 → `auth.required`
+ * 等，Cookie 认证的非安全请求要求 CSRF 头，服务令牌与非超级管理员 → `forbidden`。插件包上传用它：
  * 未认证的大请求体不被读入内存。之后 {@link AuthGuard} 照常再判一次。
  */
-export declare function authorizeEnterpriseAdmin(req: FastifyRequest, s: AuthServices): Promise<void>;
+export declare function authorizeSuperAdmin(req: FastifyRequest, s: AuthServices): Promise<void>;
+/**
+ * Before the body is read (Fastify `onRequest`), for an org's package upload (an `@OrgAction`
+ * route of a human-only action): authenticated like {@link authorizeSuperAdmin}, a person (service
+ * tokens -> `forbidden`), CSRF for cookies. Returns the principal for the org role check that also
+ * runs before the body (ruling P3-29); `OrgGuard` and the service's lock re-check it afterwards.
+ */
+export declare function authenticateOrgUploader(req: FastifyRequest, s: AuthServices): Promise<Principal>;
 /**
  * 全局守卫（`APP_GUARD`），默认拒绝：
  * 1. `Authorization: Bearer cap_pat_…|cap_svc_…` → API 令牌；个人令牌再实时读账号状态。不做 CSRF 检查。
@@ -27,7 +35,7 @@ export declare function authorizeEnterpriseAdmin(req: FastifyRequest, s: AuthSer
  *    （便于登出 / 刷新）；PG / Redis 故障等其他异常照常抛出。
  * 4. 路由约束：service principal 只能访问 `@AllowService` 路由（否则 `forbidden`）；
  *    `@SessionOnly` 要求 Web 会话：个人令牌 → `auth.session_required`，服务令牌（即使路由经 `@OrgAction`
- *    隐含 `@AllowService`）→ `forbidden`；`@EnterpriseAdmin` 要求企业管理员（`forbidden`）。
+ *    隐含 `@AllowService`）→ `forbidden`；`@SuperAdmin` 要求超级管理员（`forbidden`）。
  * 5. `@Public` 路由的非安全方法无论是否带 Cookie 都要求 CSRF 头。
  * 账号状态每个请求都从 PG 实时读取，不在进程内缓存。插件路由 `/plugins/*` 不经过 Nest，不受此守卫约束。
  */

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, ENTERPRISE_ADMIN_KEY, PUBLIC_KEY, SESSION_ONLY_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";
@@ -62,11 +62,11 @@ async function resolvePrincipal(req, s) {
     return undefined;
 }
 /**
- * 在读请求体之前（Fastify `onRequest`）按 `@EnterpriseAdmin` 路由的规则认证：无凭据 / 凭据无效 → `auth.required`
- * 等，Cookie 认证的非安全请求要求 CSRF 头，服务令牌与非企业管理员 → `forbidden`。插件包上传用它：
+ * 在读请求体之前（Fastify `onRequest`）按 `@SuperAdmin` 路由的规则认证：无凭据 / 凭据无效 → `auth.required`
+ * 等，Cookie 认证的非安全请求要求 CSRF 头，服务令牌与非超级管理员 → `forbidden`。插件包上传用它：
  * 未认证的大请求体不被读入内存。之后 {@link AuthGuard} 照常再判一次。
  */
-export async function authorizeEnterpriseAdmin(req, s) {
+export async function authorizeSuperAdmin(req, s) {
     const resolved = await resolvePrincipal(req, s);
     if (!resolved)
         throw new ApiError("auth.required", "Authentication required");
@@ -76,8 +76,29 @@ export async function authorizeEnterpriseAdmin(req, s) {
     if (p.kind === "service") {
         throw new ApiError("forbidden", "Service tokens cannot access this endpoint");
     }
-    if (!p.account.isEnterpriseAdmin)
-        throw new ApiError("forbidden", "Enterprise admin required");
+    if (p.account.mustChangePassword)
+        throw passwordChangeRequired();
+    if (!p.account.isSuperAdmin)
+        throw new ApiError("forbidden", "Super admin required");
+}
+/**
+ * Before the body is read (Fastify `onRequest`), for an org's package upload (an `@OrgAction`
+ * route of a human-only action): authenticated like {@link authorizeSuperAdmin}, a person (service
+ * tokens -> `forbidden`), CSRF for cookies. Returns the principal for the org role check that also
+ * runs before the body (ruling P3-29); `OrgGuard` and the service's lock re-check it afterwards.
+ */
+export async function authenticateOrgUploader(req, s) {
+    const resolved = await resolvePrincipal(req, s);
+    if (!resolved)
+        throw new ApiError("auth.required", "Authentication required");
+    if (resolved.cookie && !SAFE_METHODS.has(req.method.toUpperCase()))
+        requireCsrf(req);
+    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;
 }
 /**
  * 全局守卫（`APP_GUARD`），默认拒绝：
@@ -88,7 +109,7 @@ export async function authorizeEnterpriseAdmin(req, s) {
  *    （便于登出 / 刷新）；PG / Redis 故障等其他异常照常抛出。
  * 4. 路由约束：service principal 只能访问 `@AllowService` 路由（否则 `forbidden`）；
  *    `@SessionOnly` 要求 Web 会话：个人令牌 → `auth.session_required`，服务令牌（即使路由经 `@OrgAction`
- *    隐含 `@AllowService`）→ `forbidden`；`@EnterpriseAdmin` 要求企业管理员（`forbidden`）。
+ *    隐含 `@AllowService`）→ `forbidden`；`@SuperAdmin` 要求超级管理员（`forbidden`）。
  * 5. `@Public` 路由的非安全方法无论是否带 Cookie 都要求 CSRF 头。
  * 账号状态每个请求都从 PG 实时读取，不在进程内缓存。插件路由 `/plugins/*` 不经过 Nest，不受此守卫约束。
  */
@@ -142,8 +163,11 @@ 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 (flag(ENTERPRISE_ADMIN_KEY) && !(p.kind === "user" && p.account.isEnterpriseAdmin)) {
-            throw new ApiError("forbidden", "Enterprise admin required");
+        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");
         }
         return true;
     }
@@ -156,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

@@ -3,14 +3,35 @@ import type { KernelConfig } from "../config/schema.js";
 import type { IssuedSession } from "./sessions.js";
 /** access token Cookie：随所有请求发送。 */
 export declare const ACCESS_COOKIE = "cap_at";
-/** refresh token Cookie：只发往认证端点。 */
+/**
+ * The refresh-token cookie: SameSite=Lax so a top-level navigation from another site (an IM card
+ * link, an email, an OAuth return) carries it and the web tier can renew the session. The refresh
+ * endpoint is POST-only and requires `X-Capybara-Csrf`, and Lax cookies are not sent on cross-site
+ * POSTs, so this does not widen CSRF exposure.
+ */
 export declare const REFRESH_COOKIE = "cap_rt";
-/** refresh Cookie 的 Path。 */
-export declare const REFRESH_COOKIE_PATH = "/api/v1/auth";
 /**
- * 写会话 Cookie。两个 Cookie 都 HttpOnly、都**不设 Domain**（只属于当前主机）；
- * `cap_at` 为 SameSite=Lax、Path=/；`cap_rt` 为 SameSite=Strict、只发往 `/api/v1/auth`。
+ * Path of the refresh Cookie: `/`, so the web tier sees it on page requests and can renew the
+ * session while rendering on the server.
+ */
+export declare const REFRESH_COOKIE_PATH = "/";
+/** The Path earlier releases set `cap_rt` on; browsers may still hold it, so it is cleared too. */
+export declare const LEGACY_REFRESH_COOKIE_PATH = "/api/v1/auth";
+/**
+ * Writes the session cookies. Both are HttpOnly, host-only (no Domain), SameSite=Lax and Path=/;
+ * the `cap_rt` on the legacy Path is cleared at the same time.
  */
 export declare function setSessionCookies(reply: FastifyReply, s: IssuedSession, cfg: KernelConfig): void;
 /** 清除会话 Cookie（Path 必须与设置时一致才能覆盖）。 */
 export declare function clearSessionCookies(reply: FastifyReply): void;
+/**
+ * Every `cap_rt` value of a raw `cookie` header, in header order. A browser holding the legacy
+ * 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;