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

package/dist/identity/api-tokens.d.ts

@@ -1,6 +1,7 @@
-import { type Transaction } from "kysely";
 import { z } from "zod";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
 export interface ApiTokenRecord {
     id: string;
     kind: "personal" | "service";
@@ -21,11 +22,13 @@ type Scope = {
 };
 /**
  * API 令牌服务：个人令牌（`cap_pat_`，代表账号本人）与服务令牌（`cap_svc_`，属于组织、带角色）。
- * 库里只存 sha256；明文只在创建时返回一次。框架无关，由调用方注入 db。
+ * 库里只存 sha256；明文只在创建时返回一次。
  */
 export declare class ApiTokenService {
     private readonly db;
-    constructor(db: KernelDb);
+    readonly txHost: TransactionHost;
+    private readonly orgLock;
+    constructor(db: KernelDb, txHost: TransactionHost, orgLock: OrgLock);
     createPersonal(accountId: string, input: {
         name: string;
         expiresAt?: Date | undefined;
@@ -63,9 +66,10 @@ export declare class ApiTokenService {
     authenticate(token: string): Promise<ApiTokenRecord | null>;
     /** 列出该 scope 下未吊销的令牌（含已过期），按创建时间升序。 */
     list(scope: Scope): Promise<ApiTokenRecord[]>;
-    /** 吊销令牌；令牌不存在、已吊销或不在该 scope 内 → `token.not_found`。 */
-    revoke(id: string, scope: Scope, trx?: Transaction<KernelDatabase>): Promise<void>;
-    revokeAllForOrg(orgId: string, trx?: Transaction<KernelDatabase>): Promise<void>;
+    /** Revokes a token (in the context's transaction when there is one); missing, revoked or out of scope → `token.not_found`. */
+    revoke(id: string, scope: Scope): Promise<void>;
+    /** Revokes the org's service tokens (in the context's transaction when there is one). */
+    revokeAllForOrg(orgId: string): Promise<void>;
     revokeAllPersonal(accountId: string): Promise<void>;
     private scoped;
     private insertToken;

package/dist/identity/api-tokens.js

@@ -1,8 +1,21 @@
+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 { randomBytes, randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
-import { lockOrgAndAuthorize } from "../orgs/org-lock.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 { OrgLock } from "../orgs/org-lock.js";
 import { roleAtLeast } from "../orgs/roles.js";
 import { audit } from "./audit.js";
 import { sha256Hex } from "./hash.js";
@@ -35,16 +48,20 @@ function validate(input) {
 }
 /**
  * API 令牌服务：个人令牌（`cap_pat_`，代表账号本人）与服务令牌（`cap_svc_`，属于组织、带角色）。
- * 库里只存 sha256；明文只在创建时返回一次。框架无关，由调用方注入 db。
+ * 库里只存 sha256；明文只在创建时返回一次。
  */
-export class ApiTokenService {
+let ApiTokenService = class ApiTokenService {
     db;
-    constructor(db) {
+    txHost;
+    orgLock;
+    constructor(db, txHost, orgLock) {
         this.db = db;
+        this.txHost = txHost;
+        this.orgLock = orgLock;
     }
     async createPersonal(accountId, input) {
         validate(input);
-        return this.insertToken(this.db, "personal", {
+        return this.insertToken("personal", {
             account_id: accountId,
             org_id: null,
             role: null,
@@ -55,7 +72,7 @@ export class ApiTokenService {
     }
     async createService(orgId, input) {
         validate(input);
-        return this.insertToken(this.db, "service", {
+        return this.insertToken("service", {
             account_id: null,
             org_id: orgId,
             role: input.role,
@@ -70,43 +87,39 @@ export class ApiTokenService {
      */
     async createServiceAs(orgId, actorAccountId, input) {
         validate(input);
-        return this.db.transaction().execute(async (t) => {
-            const { role } = await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.tokens.manage");
-            if (!roleAtLeast(role, input.role)) {
-                throw new ApiError("forbidden", "Insufficient organization role");
-            }
-            const created = await this.insertToken(t, "service", {
-                account_id: null,
-                org_id: orgId,
-                role: input.role,
-                name: input.name,
-                created_by: actorAccountId,
-                expires_at: input.expiresAt ?? null,
-            });
-            await audit(t, {
-                actorAccountId,
-                orgId,
-                action: "org.service_token.created",
-                target: created.record.id,
-                detail: { name: input.name, role: input.role },
-            });
-            return created;
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "org.tokens.manage");
+        if (!roleAtLeast(role, input.role)) {
+            throw new ApiError("forbidden", "Insufficient organization role");
+        }
+        const created = await this.insertToken("service", {
+            account_id: null,
+            org_id: orgId,
+            role: input.role,
+            name: input.name,
+            created_by: actorAccountId,
+            expires_at: input.expiresAt ?? null,
         });
+        await audit(this.db.db, {
+            actorAccountId,
+            orgId,
+            action: "org.service_token.created",
+            target: created.record.id,
+            detail: { name: input.name, role: input.role },
+        });
+        return created;
     }
     /**
      * 以账号身份吊销组织服务令牌并写审计（同一事务）：同 createServiceAs 在组织行锁内实时复核发起人角色
      * （组织不存在 / 已删除 → `org.not_found`，无 `org.tokens.manage` → `forbidden`）；不在该组织内 → `token.not_found`。
      */
     async revokeServiceAs(orgId, tokenId, actorAccountId) {
-        await this.db.transaction().execute(async (t) => {
-            await lockOrgAndAuthorize(t, orgId, actorAccountId, "org.tokens.manage");
-            await this.revoke(tokenId, { orgId }, t);
-            await audit(t, {
-                actorAccountId,
-                orgId,
-                action: "org.service_token.revoked",
-                target: tokenId,
-            });
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "org.tokens.manage");
+        await this.revoke(tokenId, { orgId });
+        await audit(this.db.db, {
+            actorAccountId,
+            orgId,
+            action: "org.service_token.revoked",
+            target: tokenId,
         });
     }
     /** 校验令牌明文；未知、已吊销、已过期或前缀不对一律返回 null。 */
@@ -153,17 +166,18 @@ export class ApiTokenService {
             .execute();
         return rows.map(toRecord);
     }
-    /** 吊销令牌；令牌不存在、已吊销或不在该 scope 内 → `token.not_found`。 */
-    async revoke(id, scope, trx) {
-        const r = await this.scoped((trx ?? this.db).updateTable("api_tokens").set({ revoked_at: sql `now()` }), scope)
+    /** Revokes a token (in the context's transaction when there is one); missing, revoked or out of scope → `token.not_found`. */
+    async revoke(id, scope) {
+        const r = await this.scoped(this.db.updateTable("api_tokens").set({ revoked_at: sql `now()` }), scope)
             .where("id", "=", id)
             .where("revoked_at", "is", null)
             .executeTakeFirst();
         if (r.numUpdatedRows === 0n)
             throw new ApiError("token.not_found", "Token not found");
     }
-    async revokeAllForOrg(orgId, trx) {
-        await (trx ?? this.db)
+    /** Revokes the org's service tokens (in the context's transaction when there is one). */
+    async revokeAllForOrg(orgId) {
+        await this.db
             .updateTable("api_tokens")
             .set({ revoked_at: sql `now()` })
             .where("kind", "=", "service")
@@ -185,13 +199,26 @@ export class ApiTokenService {
             ? q.where("kind", "=", "personal").where("account_id", "=", scope.accountId)
             : q.where("kind", "=", "service").where("org_id", "=", scope.orgId);
     }
-    async insertToken(db, kind, values) {
+    async insertToken(kind, values) {
         const token = PREFIX[kind] + randomBytes(32).toString("base64url");
-        const row = await db
+        const row = await this.db
             .insertInto("api_tokens")
             .values({ id: randomUUID(), kind, token_hash: sha256Hex(token), ...values })
             .returningAll()
             .executeTakeFirstOrThrow();
         return { token, record: toRecord(row) };
     }
-}
+};
+__decorate([
+    Transactional()
+], ApiTokenService.prototype, "createServiceAs", null);
+__decorate([
+    Transactional()
+], ApiTokenService.prototype, "revokeServiceAs", null);
+ApiTokenService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(OrgLock))
+], ApiTokenService);
+export { ApiTokenService };

package/dist/identity/audit.d.ts

@@ -1,8 +1,12 @@
-import type { Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-/** 写一条审计事件；`action` 用点分英文小写，如 `org.member.role_changed`。 */
-export declare function audit(db: KernelDb | Transaction<KernelDatabase>, e: {
-    actorAccountId?: string;
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * Writes one audit event (`action` is dotted lower-case English, e.g. `org.member.role_changed`)
+ * through `db`: a service passes `this.db.db` (`KernelDb`: the context's transaction or the pool),
+ * so the event commits or rolls back with the write it records.
+ */
+export declare function audit(db: KernelSchemaDb, e: {
+    /** 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/audit.js

@@ -1,4 +1,8 @@
-/** 写一条审计事件；`action` 用点分英文小写，如 `org.member.role_changed`。 */
+/**
+ * Writes one audit event (`action` is dotted lower-case English, e.g. `org.member.role_changed`)
+ * through `db`: a service passes `this.db.db` (`KernelDb`: the context's transaction or the pool),
+ * so the event commits or rolls back with the write it records.
+ */
 export async function audit(db, e) {
     await db
         .insertInto("audit_events")

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

@@ -1,10 +1,10 @@
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
-import type { KernelConfig } from "../config/schema.js";
-import type { Account, AccountsService } from "./accounts.js";
-import type { LoginRateLimiter } from "./rate-limit.js";
-import type { SessionService } from "./sessions.js";
-declare const LoginBody: z.ZodObject<{
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { CredentialThrottler } from "../infra/throttler/credential-throttler.js";
+import { type Account, AccountsService } from "./accounts.js";
+import { SessionService } from "./sessions.js";
+declare const LoginBodySchema: z.ZodObject<{
     login: z.ZodString;
     password: z.ZodString;
 }, z.core.$strip>;
@@ -17,14 +17,15 @@ export declare function clientMeta(req: FastifyRequest): {
 export declare class AuthController {
     private readonly accounts;
     private readonly sessions;
-    private readonly limiter;
+    private readonly throttler;
     private readonly config;
-    constructor(accounts: AccountsService, sessions: SessionService, limiter: LoginRateLimiter, config: () => KernelConfig);
+    constructor(accounts: AccountsService, sessions: SessionService, throttler: CredentialThrottler, config: KernelConfigService);
     /**
-     * 登录名不存在与密码错误返回同一错误；每次尝试先按（登录名, IP）、IP、登录名三个计数原子占用限流额度，
-     * 成功后清零登录名计数并退还 IP 额度（见 LoginRateLimiter）。
+     * An unknown login and a wrong password answer the same error. Every attempt first reserves one
+     * attempt on the (login, IP), IP and login counters atomically; success clears the login
+     * counters and gives the IP attempt back (`CredentialThrottler`).
      */
-    login(body: z.infer<typeof LoginBody>, req: FastifyRequest, reply: FastifyReply): Promise<{
+    login(body: z.infer<typeof LoginBodySchema>, req: FastifyRequest, reply: FastifyReply): Promise<{
         account: Account;
     }>;
     /**

package/dist/identity/auth.controller.js

@@ -7,14 +7,22 @@ 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, HttpCode, Inject, Post, Req, Res } from "@nestjs/common";
+import { Controller, HttpCode, Inject, Post, Req, Res } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
-import { ACCOUNTS, KERNEL_CONFIG, RATE_LIMITER, SESSIONS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
-import { ACCESS_COOKIE, clearSessionCookies, REFRESH_COOKIE, setSessionCookies, } from "./cookies.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+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, refreshCookieValues, setSessionCookies, } from "./cookies.js";
 import { Public } from "./principal.js";
-const LoginBody = z.object({ login: z.string().max(256), password: z.string() });
+import { SessionService } from "./sessions.js";
+const LoginBodySchema = z.object({ login: z.string().max(256), password: z.string() });
+class LoginBody extends createZodDto(LoginBodySchema, "LoginBody") {
+}
+/** The credential throttlers of a login attempt (R25: per (login, IP), per IP, per login). */
+const LOGIN_THROTTLERS = ["login", "login-ip", "login-account"];
 /** 会话的客户端信息（记入 sessions 表）。`req.ip` 在 `http.trustProxy` 时取自 X-Forwarded-For。 */
 export function clientMeta(req) {
     const ua = req.headers["user-agent"];
@@ -24,42 +32,40 @@ export function clientMeta(req) {
 let AuthController = class AuthController {
     accounts;
     sessions;
-    limiter;
+    throttler;
     config;
-    constructor(accounts, sessions, limiter, config) {
+    constructor(accounts, sessions, throttler, config) {
         this.accounts = accounts;
         this.sessions = sessions;
-        this.limiter = limiter;
+        this.throttler = throttler;
         this.config = config;
     }
     /**
-     * 登录名不存在与密码错误返回同一错误；每次尝试先按（登录名, IP）、IP、登录名三个计数原子占用限流额度，
-     * 成功后清零登录名计数并退还 IP 额度（见 LoginRateLimiter）。
+     * An unknown login and a wrong password answer the same error. Every attempt first reserves one
+     * attempt on the (login, IP), IP and login counters atomically; success clears the login
+     * counters and gives the IP attempt back (`CredentialThrottler`).
      */
     async login(body, req, reply) {
         const meta = clientMeta(req);
-        // 校验密码之前先原子地占用一次尝试额度：并发请求也无法绕过上限
-        const rl = await this.limiter.reserve(body.login, meta.ip);
-        if (!rl.allowed) {
-            reply.header("retry-after", String(rl.retryAfterSeconds));
-            throw new ApiError("auth.rate_limited", "Too many failed login attempts; try again later");
-        }
+        // reserve before checking the password, atomically: concurrent requests cannot pass the limit
+        await this.throttler.reserve(LOGIN_THROTTLERS, req, reply);
         let account;
         try {
             account = await this.accounts.authenticateLocal(body.login, body.password);
         }
         catch (e) {
-            // 停用账号的密码是对的（authenticateLocal 先核对密码再看状态）：不算失败尝试，退还占用的额度
+            // a disabled account's password is right (authenticateLocal checks it before the status):
+            // not a failed attempt, the reservation is given back
             if (e instanceof ApiError && e.code === "auth.account_disabled") {
-                await this.limiter.succeeded(body.login, meta.ip);
+                await this.throttler.succeeded(LOGIN_THROTTLERS, req);
             }
             throw e;
         }
         if (!account)
             throw new ApiError("auth.invalid_credentials", "Invalid login or password");
-        await this.limiter.succeeded(body.login, meta.ip);
+        await this.throttler.succeeded(LOGIN_THROTTLERS, req);
         const session = await this.sessions.create(account.id, meta);
-        setSessionCookies(reply, session, this.config());
+        setSessionCookies(reply, session, this.config.get());
         return { account };
     }
     /**
@@ -68,14 +74,18 @@ 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)
                 throw new ApiError("auth.refresh_invalid", "Refresh token is invalid");
-            setSessionCookies(reply, session, this.config());
+            setSessionCookies(reply, session, this.config.get());
             return { account };
         }
         catch (e) {
@@ -88,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);
     }
 };
@@ -102,7 +112,7 @@ __decorate([
     Post("login"),
     Public(),
     HttpCode(200),
-    __param(0, Body(new ZodPipe(LoginBody))),
+    __param(0, ZBody(LoginBody)),
     __param(1, Req()),
     __param(2, Res({ passthrough: true }))
 ], AuthController.prototype, "login", null);
@@ -122,9 +132,9 @@ __decorate([
 ], AuthController.prototype, "logout", null);
 AuthController = __decorate([
     Controller("api/v1/auth"),
-    __param(0, Inject(ACCOUNTS)),
-    __param(1, Inject(SESSIONS)),
-    __param(2, Inject(RATE_LIMITER)),
-    __param(3, Inject(KERNEL_CONFIG))
+    __param(0, Inject(AccountsService)),
+    __param(1, Inject(SessionService)),
+    __param(2, Inject(CredentialThrottler)),
+    __param(3, Inject(KernelConfigService))
 ], AuthController);
 export { AuthController };

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

@@ -1,23 +1,31 @@
 import { type CanActivate, type ExecutionContext } from "@nestjs/common";
 import { Reflector } from "@nestjs/core";
 import type { FastifyRequest } from "fastify";
-import type { AccountsService } from "./accounts.js";
-import type { ApiTokenService } from "./api-tokens.js";
-import type { SessionService } from "./sessions.js";
+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

@@ -10,9 +10,11 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable } from "@nestjs/common";
 import { Reflector } from "@nestjs/core";
 import { ApiError } from "../errors.js";
-import { ACCOUNTS, API_TOKENS, SESSIONS } from "../http/tokens.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";
 const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
@@ -60,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");
@@ -74,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`），默认拒绝：
@@ -86,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，不受此守卫约束。
  */
@@ -140,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;
     }
@@ -149,11 +175,13 @@ let AuthGuard = class AuthGuard {
 AuthGuard = __decorate([
     Injectable(),
     __param(0, Inject(Reflector)),
-    __param(1, Inject(ACCOUNTS)),
-    __param(2, Inject(SESSIONS)),
-    __param(3, Inject(API_TOKENS))
+    __param(1, Inject(AccountsService)),
+    __param(2, Inject(SessionService)),
+    __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/binding.d.ts

@@ -1,8 +1,8 @@
 import type { ExternalIdentity } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { ExternalIdentities } from "./external.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { ExternalIdentities } from "./external.js";
 /** 绑定令牌的有效期（秒）。 */
 export declare const BIND_TOKEN_TTL_SECONDS = 900;
 /** 绑定确认页（网页）路径前缀：`<http.publicUrl>/bind/<token>`。 */
@@ -19,16 +19,14 @@ export interface PendingBinding {
 /**
  * IM 里识别不出的人：内核发一个一次性绑定链接，本人登录网页后确认，把该 IM 身份绑到当前账号。
  * 令牌 `cap_bind_<32 字节>`，Redis `capk:bind:<sha256>` 15 分钟、单次有效（确认时 GETDEL）。
- * 查看与确认时都复核发出链接的渠道连接仍可用（存在、未删除、其插件仍在该组织启用），否则 `bind.invalid`。框架无关。
+ * 查看与确认时都复核发出链接的渠道连接仍可用（存在、未删除、其插件仍在该组织启用），否则 `bind.invalid`。
  */
 export declare class IdentityBinding {
-    private readonly deps;
-    constructor(deps: {
-        db: KernelDb;
-        redis: Redis;
-        config: () => KernelConfig;
-        external: ExternalIdentities;
-    });
+    private readonly db;
+    private readonly redis;
+    private readonly config;
+    private readonly external;
+    constructor(db: KernelDb, redis: Redis, config: Pick<KernelConfigService, "get">, external: ExternalIdentities);
     /** 生成绑定链接（渠道运行时在回绑定卡片时调用）；需要 `http.publicUrl`。 */
     createBindToken(args: {
         connectionId: string;