@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/identity/audit.js

@@ -0,0 +1,41 @@
+/** 写一条审计事件；`action` 用点分英文小写，如 `org.member.role_changed`。 */
+export async function audit(db, e) {
+    await db
+        .insertInto("audit_events")
+        .values({
+        actor_account_id: e.actorAccountId ?? null,
+        actor_token_id: e.actorTokenId ?? null,
+        org_id: e.orgId ?? null,
+        action: e.action,
+        target: e.target ?? null,
+        detail: JSON.stringify(e.detail ?? {}),
+    })
+        .execute();
+}
+/**
+ * Connector audit actions written before the D17 rename (old rows are not rewritten, C27) -> the
+ * renamed action. Only these are listed, nothing is inferred from the `app.*` prefix: after D17
+ * "app" meant app bundles (`app.installed` etc., `plugin.org_installed` since phase 0a), which are
+ * unrelated to connectors (F-X).
+ */
+export const LEGACY_AUDIT_ACTIONS = Object.freeze({
+    "app.created": "connector.created",
+    "app.updated": "connector.updated",
+    "app.deleted": "connector.deleted",
+    "app.tools_refreshed": "connector.tools_refreshed",
+    "app.tools_drifted": "connector.tools_drifted",
+    "app.tool_reviewed": "connector.tool_reviewed",
+    "app.credential.set": "connector.credential.set",
+    "app.credential.cleared": "connector.credential.cleared",
+});
+/**
+ * 按 action 查询审计时与之同义的全部 action（含自身）：`connector.created` ↔ `app.created` 等，
+ * 只按 {@link LEGACY_AUDIT_ACTIONS} 显式映射；其余 action 只有自身。
+ */
+export function auditActionAliases(action) {
+    const current = LEGACY_AUDIT_ACTIONS[action] ?? action;
+    const legacy = Object.entries(LEGACY_AUDIT_ACTIONS)
+        .filter(([, to]) => to === current)
+        .map(([from]) => from);
+    return [current, ...legacy];
+}

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

@@ -0,0 +1,40 @@
+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<{
+    login: z.ZodString;
+    password: z.ZodString;
+}, z.core.$strip>;
+/** 会话的客户端信息（记入 sessions 表）。`req.ip` 在 `http.trustProxy` 时取自 X-Forwarded-For。 */
+export declare function clientMeta(req: FastifyRequest): {
+    userAgent?: string;
+    ip: string;
+};
+/** 本地登录、刷新与登出（`/api/v1/auth/*`，均为公开路由）。 */
+export declare class AuthController {
+    private readonly accounts;
+    private readonly sessions;
+    private readonly limiter;
+    private readonly config;
+    constructor(accounts: AccountsService, sessions: SessionService, limiter: LoginRateLimiter, config: () => KernelConfig);
+    /**
+     * 登录名不存在与密码错误返回同一错误；每次尝试先按（登录名, IP）、IP、登录名三个计数原子占用限流额度，
+     * 成功后清零登录名计数并退还 IP 额度（见 LoginRateLimiter）。
+     */
+    login(body: z.infer<typeof LoginBody>, req: FastifyRequest, reply: FastifyReply): Promise<{
+        account: Account;
+    }>;
+    /**
+     * 用 `cap_rt` 换新的一对 Cookie。失败时清 Cookie；但 `auth.refresh_race` 不清——
+     * 并发的另一个请求刚换到了新 Cookie，这里清掉会覆盖它。
+     */
+    refresh(req: FastifyRequest, reply: FastifyReply): Promise<{
+        account: Account;
+    }>;
+    /** 吊销 Cookie 对应的会话（access token 过期也接受，验签失败忽略），总是清 Cookie。 */
+    logout(req: FastifyRequest, reply: FastifyReply): Promise<void>;
+}
+export {};

package/dist/identity/auth.controller.js

@@ -0,0 +1,130 @@
+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 { Body, 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 { Public } from "./principal.js";
+const LoginBody = z.object({ login: z.string().max(256), password: z.string() });
+/** 会话的客户端信息（记入 sessions 表）。`req.ip` 在 `http.trustProxy` 时取自 X-Forwarded-For。 */
+export function clientMeta(req) {
+    const ua = req.headers["user-agent"];
+    return { ip: req.ip, ...(ua !== undefined && { userAgent: ua }) };
+}
+/** 本地登录、刷新与登出（`/api/v1/auth/*`，均为公开路由）。 */
+let AuthController = class AuthController {
+    accounts;
+    sessions;
+    limiter;
+    config;
+    constructor(accounts, sessions, limiter, config) {
+        this.accounts = accounts;
+        this.sessions = sessions;
+        this.limiter = limiter;
+        this.config = config;
+    }
+    /**
+     * 登录名不存在与密码错误返回同一错误；每次尝试先按（登录名, IP）、IP、登录名三个计数原子占用限流额度，
+     * 成功后清零登录名计数并退还 IP 额度（见 LoginRateLimiter）。
+     */
+    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");
+        }
+        let account;
+        try {
+            account = await this.accounts.authenticateLocal(body.login, body.password);
+        }
+        catch (e) {
+            // 停用账号的密码是对的（authenticateLocal 先核对密码再看状态）：不算失败尝试，退还占用的额度
+            if (e instanceof ApiError && e.code === "auth.account_disabled") {
+                await this.limiter.succeeded(body.login, meta.ip);
+            }
+            throw e;
+        }
+        if (!account)
+            throw new ApiError("auth.invalid_credentials", "Invalid login or password");
+        await this.limiter.succeeded(body.login, meta.ip);
+        const session = await this.sessions.create(account.id, meta);
+        setSessionCookies(reply, session, this.config());
+        return { account };
+    }
+    /**
+     * 用 `cap_rt` 换新的一对 Cookie。失败时清 Cookie；但 `auth.refresh_race` 不清——
+     * 并发的另一个请求刚换到了新 Cookie，这里清掉会覆盖它。
+     */
+    async refresh(req, reply) {
+        try {
+            const rt = req.cookies[REFRESH_COOKIE];
+            if (!rt)
+                throw new ApiError("auth.refresh_invalid", "Refresh token is missing");
+            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());
+            return { account };
+        }
+        catch (e) {
+            if (!(e instanceof ApiError && e.code === "auth.refresh_race"))
+                clearSessionCookies(reply);
+            throw e;
+        }
+    }
+    /** 吊销 Cookie 对应的会话（access token 过期也接受，验签失败忽略），总是清 Cookie。 */
+    async logout(req, reply) {
+        clearSessionCookies(reply);
+        const at = req.cookies[ACCESS_COOKIE];
+        const rt = req.cookies[REFRESH_COOKIE];
+        if (at) {
+            const sid = await this.sessions.sessionIdFromAccess(at);
+            if (sid !== undefined)
+                await this.sessions.revoke(sid);
+        }
+        if (rt)
+            await this.sessions.revokeByRefresh(rt);
+    }
+};
+__decorate([
+    Post("login"),
+    Public(),
+    HttpCode(200),
+    __param(0, Body(new ZodPipe(LoginBody))),
+    __param(1, Req()),
+    __param(2, Res({ passthrough: true }))
+], AuthController.prototype, "login", null);
+__decorate([
+    Post("refresh"),
+    Public(),
+    HttpCode(200),
+    __param(0, Req()),
+    __param(1, Res({ passthrough: true }))
+], AuthController.prototype, "refresh", null);
+__decorate([
+    Post("logout"),
+    Public(),
+    HttpCode(204),
+    __param(0, Req()),
+    __param(1, Res({ passthrough: true }))
+], 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))
+], AuthController);
+export { AuthController };

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

@@ -0,0 +1,41 @@
+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";
+/** CSRF 头：Cookie 认证的非安全请求（及所有公开路由的非安全请求）必须带 `X-Capybara-Csrf: 1`。 */
+export declare const CSRF_HEADER = "x-capybara-csrf";
+/** 解析凭据要用的服务（{@link AuthGuard} 与 {@link authorizeEnterpriseAdmin} 共用）。 */
+export interface AuthServices {
+    accounts: AccountsService;
+    sessions: SessionService;
+    tokens: ApiTokenService;
+}
+/**
+ * 在读请求体之前（Fastify `onRequest`）按 `@EnterpriseAdmin` 路由的规则认证：无凭据 / 凭据无效 → `auth.required`
+ * 等，Cookie 认证的非安全请求要求 CSRF 头，服务令牌与非企业管理员 → `forbidden`。插件包上传用它：
+ * 未认证的大请求体不被读入内存。之后 {@link AuthGuard} 照常再判一次。
+ */
+export declare function authorizeEnterpriseAdmin(req: FastifyRequest, s: AuthServices): Promise<void>;
+/**
+ * 全局守卫（`APP_GUARD`），默认拒绝：
+ * 1. `Authorization: Bearer cap_pat_…|cap_svc_…` → API 令牌；个人令牌再实时读账号状态。不做 CSRF 检查。
+ * 2. 否则 Cookie `cap_at` → 会话 access token（Redis 吊销标记作快速路径，再以 PG `sessions.revoked_at` 为准，
+ *    与账号读取合并为一条查询）→ 实时判断账号状态；非安全方法要求 CSRF 头。
+ * 3. 都没有：`@Public` 放行，否则 `auth.required`。`@Public` 路由上凭据无效（`ApiError`）按无凭据处理
+ *    （便于登出 / 刷新）；PG / Redis 故障等其他异常照常抛出。
+ * 4. 路由约束：service principal 只能访问 `@AllowService` 路由（否则 `forbidden`）；
+ *    `@SessionOnly` 要求 Web 会话：个人令牌 → `auth.session_required`，服务令牌（即使路由经 `@OrgAction`
+ *    隐含 `@AllowService`）→ `forbidden`；`@EnterpriseAdmin` 要求企业管理员（`forbidden`）。
+ * 5. `@Public` 路由的非安全方法无论是否带 Cookie 都要求 CSRF 头。
+ * 账号状态每个请求都从 PG 实时读取，不在进程内缓存。插件路由 `/plugins/*` 不经过 Nest，不受此守卫约束。
+ */
+export declare class AuthGuard implements CanActivate {
+    private readonly reflector;
+    readonly accounts: AccountsService;
+    readonly sessions: SessionService;
+    readonly tokens: ApiTokenService;
+    constructor(reflector: Reflector, accounts: AccountsService, sessions: SessionService, tokens: ApiTokenService);
+    canActivate(ctx: ExecutionContext): Promise<boolean>;
+}

package/dist/identity/auth.guard.js

@@ -0,0 +1,162 @@
+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 { Reflector } from "@nestjs/core";
+import { ApiError } from "../errors.js";
+import { ACCOUNTS, API_TOKENS, SESSIONS } from "../http/tokens.js";
+import { ACCESS_COOKIE } from "./cookies.js";
+import { ALLOW_SERVICE_KEY, ENTERPRISE_ADMIN_KEY, PUBLIC_KEY, SESSION_ONLY_KEY, } from "./principal.js";
+/** CSRF 头：Cookie 认证的非安全请求（及所有公开路由的非安全请求）必须带 `X-Capybara-Csrf: 1`。 */
+export const CSRF_HEADER = "x-capybara-csrf";
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const BEARER_RE = /^Bearer\s+(\S+)$/i;
+function requireCsrf(req) {
+    if (req.headers[CSRF_HEADER] !== "1") {
+        throw new ApiError("auth.csrf", `Missing ${CSRF_HEADER} header`);
+    }
+}
+/** 解析凭据；无凭据返回 undefined，凭据无效抛对应的 ApiError。 */
+async function resolvePrincipal(req, s) {
+    const bearer = BEARER_RE.exec(req.headers.authorization ?? "")?.[1];
+    if (bearer !== undefined) {
+        const rec = await s.tokens.authenticate(bearer);
+        if (!rec)
+            throw new ApiError("auth.required", "Authentication required");
+        if (rec.kind === "service") {
+            return {
+                principal: {
+                    kind: "service",
+                    tokenId: rec.id,
+                    orgId: rec.orgId,
+                    role: rec.role,
+                },
+                cookie: false,
+            };
+        }
+        const account = await s.accounts.get(rec.accountId);
+        if (!account)
+            throw new ApiError("auth.required", "Authentication required");
+        return {
+            principal: { kind: "user", account: requireActive(account), via: "pat", tokenId: rec.id },
+            cookie: false,
+        };
+    }
+    const at = req.cookies[ACCESS_COOKIE];
+    if (at) {
+        // 一条查询同时完成吊销检查与账号读取
+        const { account, sessionId } = await s.sessions.verifyAccess(at);
+        return {
+            principal: { kind: "user", account: requireActive(account), via: "session", sessionId },
+            cookie: true,
+        };
+    }
+    return undefined;
+}
+/**
+ * 在读请求体之前（Fastify `onRequest`）按 `@EnterpriseAdmin` 路由的规则认证：无凭据 / 凭据无效 → `auth.required`
+ * 等，Cookie 认证的非安全请求要求 CSRF 头，服务令牌与非企业管理员 → `forbidden`。插件包上传用它：
+ * 未认证的大请求体不被读入内存。之后 {@link AuthGuard} 照常再判一次。
+ */
+export async function authorizeEnterpriseAdmin(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);
+    const p = resolved.principal;
+    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");
+}
+/**
+ * 全局守卫（`APP_GUARD`），默认拒绝：
+ * 1. `Authorization: Bearer cap_pat_…|cap_svc_…` → API 令牌；个人令牌再实时读账号状态。不做 CSRF 检查。
+ * 2. 否则 Cookie `cap_at` → 会话 access token（Redis 吊销标记作快速路径，再以 PG `sessions.revoked_at` 为准，
+ *    与账号读取合并为一条查询）→ 实时判断账号状态；非安全方法要求 CSRF 头。
+ * 3. 都没有：`@Public` 放行，否则 `auth.required`。`@Public` 路由上凭据无效（`ApiError`）按无凭据处理
+ *    （便于登出 / 刷新）；PG / Redis 故障等其他异常照常抛出。
+ * 4. 路由约束：service principal 只能访问 `@AllowService` 路由（否则 `forbidden`）；
+ *    `@SessionOnly` 要求 Web 会话：个人令牌 → `auth.session_required`，服务令牌（即使路由经 `@OrgAction`
+ *    隐含 `@AllowService`）→ `forbidden`；`@EnterpriseAdmin` 要求企业管理员（`forbidden`）。
+ * 5. `@Public` 路由的非安全方法无论是否带 Cookie 都要求 CSRF 头。
+ * 账号状态每个请求都从 PG 实时读取，不在进程内缓存。插件路由 `/plugins/*` 不经过 Nest，不受此守卫约束。
+ */
+let AuthGuard = class AuthGuard {
+    reflector;
+    accounts;
+    sessions;
+    tokens;
+    constructor(reflector, accounts, sessions, tokens) {
+        this.reflector = reflector;
+        this.accounts = accounts;
+        this.sessions = sessions;
+        this.tokens = tokens;
+    }
+    async canActivate(ctx) {
+        const req = ctx.switchToHttp().getRequest();
+        const targets = [ctx.getHandler(), ctx.getClass()];
+        const flag = (key) => this.reflector.getAllAndOverride(key, targets) === true;
+        const isPublic = flag(PUBLIC_KEY);
+        const unsafe = !SAFE_METHODS.has(req.method.toUpperCase());
+        if (isPublic && unsafe)
+            requireCsrf(req);
+        let resolved;
+        try {
+            resolved = await resolvePrincipal(req, this);
+        }
+        catch (e) {
+            // 公开路由上只把「凭据无效」（ApiError）视同未携带；PG / Redis 故障等照常抛出（500），
+            // 否则故障期间带着有效 Cookie 的请求会被当作匿名放行
+            if (!isPublic || !(e instanceof ApiError))
+                throw e;
+            resolved = undefined;
+        }
+        if (!resolved) {
+            if (isPublic)
+                return true;
+            throw new ApiError("auth.required", "Authentication required");
+        }
+        if (resolved.cookie && unsafe)
+            requireCsrf(req);
+        const p = resolved.principal;
+        req.principal = p;
+        if (isPublic)
+            return true;
+        if (p.kind === "service" && !flag(ALLOW_SERVICE_KEY)) {
+            throw new ApiError("forbidden", "Service tokens cannot access this endpoint");
+        }
+        if (flag(SESSION_ONLY_KEY) && p.kind === "service") {
+            throw new ApiError("forbidden", "Service tokens cannot access this endpoint");
+        }
+        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");
+        }
+        return true;
+    }
+};
+AuthGuard = __decorate([
+    Injectable(),
+    __param(0, Inject(Reflector)),
+    __param(1, Inject(ACCOUNTS)),
+    __param(2, Inject(SESSIONS)),
+    __param(3, Inject(API_TOKENS))
+], AuthGuard);
+export { AuthGuard };
+function requireActive(account) {
+    if (account.status !== "active") {
+        throw new ApiError("auth.account_disabled", "Account is disabled");
+    }
+    return account;
+}

package/dist/identity/binding.d.ts

@@ -0,0 +1,47 @@
+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";
+/** 绑定令牌的有效期（秒）。 */
+export declare const BIND_TOKEN_TTL_SECONDS = 900;
+/** 绑定确认页（网页）路径前缀：`<http.publicUrl>/bind/<token>`。 */
+export declare const BIND_PAGE_PATH = "/bind/";
+/** 绑定确认页展示的待绑定身份。 */
+export interface PendingBinding {
+    connectionId: string;
+    source: string;
+    externalId: string;
+    displayName: string;
+    email?: string;
+    avatarUrl?: string;
+}
+/**
+ * IM 里识别不出的人：内核发一个一次性绑定链接，本人登录网页后确认，把该 IM 身份绑到当前账号。
+ * 令牌 `cap_bind_<32 字节>`，Redis `capk:bind:<sha256>` 15 分钟、单次有效（确认时 GETDEL）。
+ * 查看与确认时都复核发出链接的渠道连接仍可用（存在、未删除、其插件仍在该组织启用），否则 `bind.invalid`。框架无关。
+ */
+export declare class IdentityBinding {
+    private readonly deps;
+    constructor(deps: {
+        db: KernelDb;
+        redis: Redis;
+        config: () => KernelConfig;
+        external: ExternalIdentities;
+    });
+    /** 生成绑定链接（渠道运行时在回绑定卡片时调用）；需要 `http.publicUrl`。 */
+    createBindToken(args: {
+        connectionId: string;
+        identity: ExternalIdentity;
+    }): Promise<string>;
+    /** 查看待绑定的身份（不消耗令牌）；无效 / 过期 / 已用 → `bind.invalid`。 */
+    peek(token: string): Promise<PendingBinding>;
+    /**
+     * 把令牌里的身份绑到 `accountId`：先 GETDEL 消耗令牌（并发确认只有一个拿到），复核渠道连接仍可用
+     * （否则 `bind.invalid`：连接删除或插件停用后，旧链接不能再绑定），再绑定；
+     * 已绑定他人 → `identity.taken`（令牌同样作废，需在 IM 里重新获取）。
+     */
+    bind(token: string, accountId: string): Promise<PendingBinding>;
+    /** 渠道连接存在、未软删除，且其插件在连接所属组织启用。 */
+    private connectionUsable;
+}

package/dist/identity/binding.js

@@ -0,0 +1,84 @@
+import { createHash, randomBytes } from "node:crypto";
+import { ApiError } from "../errors.js";
+import { enabledExtensionsByOrg } from "../extensions/enabled.js";
+/** 绑定令牌的有效期（秒）。 */
+export const BIND_TOKEN_TTL_SECONDS = 900;
+/** 绑定确认页（网页）路径前缀：`<http.publicUrl>/bind/<token>`。 */
+export const BIND_PAGE_PATH = "/bind/";
+/** 令牌前缀：日志里的路径段按 `cap_` 前缀自动打码。 */
+const TOKEN_PREFIX = "cap_bind_";
+const TOKEN_RE = /^cap_bind_[A-Za-z0-9_-]{43}$/;
+/** Redis 里只存令牌的哈希，拿到 Redis 内容也换不出可用的绑定链接。 */
+const tokenKey = (token) => `capk:bind:${createHash("sha256").update(token).digest("base64url")}`;
+const invalid = () => new ApiError("bind.invalid", "Binding link is invalid or has expired");
+const view = (r) => ({
+    connectionId: r.connectionId,
+    source: r.identity.source,
+    externalId: r.identity.externalId,
+    displayName: r.identity.displayName,
+    ...(r.identity.email !== undefined && { email: r.identity.email }),
+    ...(r.identity.avatarUrl !== undefined && { avatarUrl: r.identity.avatarUrl }),
+});
+/**
+ * IM 里识别不出的人：内核发一个一次性绑定链接，本人登录网页后确认，把该 IM 身份绑到当前账号。
+ * 令牌 `cap_bind_<32 字节>`，Redis `capk:bind:<sha256>` 15 分钟、单次有效（确认时 GETDEL）。
+ * 查看与确认时都复核发出链接的渠道连接仍可用（存在、未删除、其插件仍在该组织启用），否则 `bind.invalid`。框架无关。
+ */
+export class IdentityBinding {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 生成绑定链接（渠道运行时在回绑定卡片时调用）；需要 `http.publicUrl`。 */
+    async createBindToken(args) {
+        const publicUrl = this.deps.config().http.publicUrl;
+        if (!publicUrl)
+            throw new Error("binding links require http.publicUrl to be configured");
+        const token = TOKEN_PREFIX + randomBytes(32).toString("base64url");
+        const rec = { connectionId: args.connectionId, identity: args.identity };
+        await this.deps.redis.set(tokenKey(token), JSON.stringify(rec), "EX", BIND_TOKEN_TTL_SECONDS);
+        return `${publicUrl.replace(/\/+$/, "")}${BIND_PAGE_PATH}${token}`;
+    }
+    /** 查看待绑定的身份（不消耗令牌）；无效 / 过期 / 已用 → `bind.invalid`。 */
+    async peek(token) {
+        if (!TOKEN_RE.test(token))
+            throw invalid();
+        const raw = await this.deps.redis.get(tokenKey(token));
+        if (raw === null)
+            throw invalid();
+        const rec = JSON.parse(raw);
+        if (!(await this.connectionUsable(rec.connectionId)))
+            throw invalid();
+        return view(rec);
+    }
+    /**
+     * 把令牌里的身份绑到 `accountId`：先 GETDEL 消耗令牌（并发确认只有一个拿到），复核渠道连接仍可用
+     * （否则 `bind.invalid`：连接删除或插件停用后，旧链接不能再绑定），再绑定；
+     * 已绑定他人 → `identity.taken`（令牌同样作废，需在 IM 里重新获取）。
+     */
+    async bind(token, accountId) {
+        if (!TOKEN_RE.test(token))
+            throw invalid();
+        const raw = await this.deps.redis.getdel(tokenKey(token));
+        if (raw === null)
+            throw invalid();
+        const rec = JSON.parse(raw);
+        if (!(await this.connectionUsable(rec.connectionId)))
+            throw invalid();
+        await this.deps.external.link(accountId, rec.identity);
+        return view(rec);
+    }
+    /** 渠道连接存在、未软删除，且其插件在连接所属组织启用。 */
+    async connectionUsable(connectionId) {
+        const row = await this.deps.db
+            .selectFrom("channel_connections")
+            .innerJoin(enabledExtensionsByOrg(this.deps.db).as("en"), (j) => j
+            .onRef("en.org_id", "=", "channel_connections.org_id")
+            .onRef("en.plugin", "=", "channel_connections.plugin"))
+            .select("channel_connections.id")
+            .where("channel_connections.id", "=", connectionId)
+            .where("channel_connections.deleted_at", "is", null)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+}

package/dist/identity/cookies.d.ts

@@ -0,0 +1,16 @@
+import type { FastifyReply } from "fastify";
+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：只发往认证端点。 */
+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`。
+ */
+export declare function setSessionCookies(reply: FastifyReply, s: IssuedSession, cfg: KernelConfig): void;
+/** 清除会话 Cookie（Path 必须与设置时一致才能覆盖）。 */
+export declare function clearSessionCookies(reply: FastifyReply): void;

package/dist/identity/cookies.js

@@ -0,0 +1,32 @@
+/** access token Cookie：随所有请求发送。 */
+export const ACCESS_COOKIE = "cap_at";
+/** refresh token Cookie：只发往认证端点。 */
+export const REFRESH_COOKIE = "cap_rt";
+/** refresh Cookie 的 Path。 */
+export const REFRESH_COOKIE_PATH = "/api/v1/auth";
+/**
+ * 写会话 Cookie。两个 Cookie 都 HttpOnly、都**不设 Domain**（只属于当前主机）；
+ * `cap_at` 为 SameSite=Lax、Path=/；`cap_rt` 为 SameSite=Strict、只发往 `/api/v1/auth`。
+ */
+export function setSessionCookies(reply, s, cfg) {
+    const secure = cfg.auth.cookieSecure;
+    reply.setCookie(ACCESS_COOKIE, s.accessToken, {
+        path: "/",
+        httpOnly: true,
+        sameSite: "lax",
+        secure,
+        maxAge: cfg.auth.accessTokenTtlSeconds,
+    });
+    reply.setCookie(REFRESH_COOKIE, s.refreshToken, {
+        path: REFRESH_COOKIE_PATH,
+        httpOnly: true,
+        sameSite: "strict",
+        secure,
+        maxAge: cfg.auth.refreshTokenTtlDays * 86400,
+    });
+}
+/** 清除会话 Cookie（Path 必须与设置时一致才能覆盖）。 */
+export function clearSessionCookies(reply) {
+    reply.clearCookie(ACCESS_COOKIE, { path: "/" });
+    reply.clearCookie(REFRESH_COOKIE, { path: REFRESH_COOKIE_PATH });
+}

package/dist/identity/credential-check.d.ts

@@ -0,0 +1,17 @@
+import type { ErrorCode } from "../errors.js";
+import type { ApiTokenService } from "./api-tokens.js";
+import type { UserPrincipal } from "./principal.js";
+import type { SessionService } from "./sessions.js";
+/** 复核凭据：仍然有效返回 null，否则返回应告知客户端的错误码。 */
+export type CredentialCheck = () => Promise<ErrorCode | null>;
+/**
+ * 长连接（SSE）用的凭据复核：重新校验建立连接时使用的凭据，登出 / 吊销后连接不能继续收数据（R35）。
+ * - Web 会话：按 sessionId 查会话行（未吊销、未过期、仍属该账号）；**不**重验 access token 的 exp，
+ *   access token 到期但会话仍有效时连接照常保持（客户端靠刷新续期，已建立的流不受影响）。
+ * - 个人令牌：用建立连接时的令牌明文重新 `authenticate`（吊销 / 过期 → 失效）。
+ * 账号停用由调用方的可见性判定（账号须为 active）覆盖。
+ */
+export declare function credentialCheck(p: UserPrincipal, bearer: string | undefined, deps: {
+    sessions: Pick<SessionService, "get">;
+    tokens: Pick<ApiTokenService, "authenticate">;
+}): CredentialCheck;

package/dist/identity/credential-check.js

@@ -0,0 +1,24 @@
+/**
+ * 长连接（SSE）用的凭据复核：重新校验建立连接时使用的凭据，登出 / 吊销后连接不能继续收数据（R35）。
+ * - Web 会话：按 sessionId 查会话行（未吊销、未过期、仍属该账号）；**不**重验 access token 的 exp，
+ *   access token 到期但会话仍有效时连接照常保持（客户端靠刷新续期，已建立的流不受影响）。
+ * - 个人令牌：用建立连接时的令牌明文重新 `authenticate`（吊销 / 过期 → 失效）。
+ * 账号停用由调用方的可见性判定（账号须为 active）覆盖。
+ */
+export function credentialCheck(p, bearer, deps) {
+    if (p.via === "session") {
+        const { sessionId } = p;
+        const accountId = p.account.id;
+        return async () => {
+            const s = await deps.sessions.get(sessionId);
+            return s && s.accountId === accountId ? null : "auth.session_revoked";
+        };
+    }
+    const { tokenId } = p;
+    return async () => {
+        if (bearer === undefined)
+            return "auth.required";
+        const rec = await deps.tokens.authenticate(bearer);
+        return rec && rec.id === tokenId ? null : "auth.required";
+    };
+}

package/dist/identity/enterprise-admin.d.ts

@@ -0,0 +1,14 @@
+import { type Transaction } from "kysely";
+import type { KernelDatabase } from "../db/kernel-schema.js";
+/**
+ * 在调用方事务内取 `capybara.enterprise_admins` 咨询锁（事务结束释放），串行化所有企业管理员写操作
+ * （撤销 / 停用 / 新建管理员 / 改部署设置 / CLI 的 `capybara admin grant|revoke`）。只加锁、不鉴权：
+ * 没有发起账号的调用方（CLI）用它；有发起账号的用 {@link lockEnterpriseAdminsAndAuthorize}。
+ */
+export declare function lockEnterpriseAdmins(trx: Transaction<KernelDatabase>): Promise<void>;
+/**
+ * 企业管理员写操作的执行期复核（spec 3.6 R5）：{@link lockEnterpriseAdmins} 后在锁内实时确认发起人仍是
+ * 活跃企业管理员，否则 `forbidden`。鉴权守卫在请求开头读到的身份可能已过期（另一个管理员刚撤销了他），
+ * 必须在锁内重读。
+ */
+export declare function lockEnterpriseAdminsAndAuthorize(trx: Transaction<KernelDatabase>, actorAccountId: string): Promise<void>;