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

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

@@ -0,0 +1,59 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { KernelConfig } from "../config/schema.js";
+import type { AccountsService } from "./accounts.js";
+import type { IdentityBinding, PendingBinding } from "./binding.js";
+import type { ExternalIdentities, LinkedIdentity } from "./external.js";
+import { type Principal } from "./principal.js";
+import type { SessionService } from "./sessions.js";
+import { type SsoFlow } from "./sso.js";
+/**
+ * 第三方登录（`/api/v1/auth/sources`、`/api/v1/auth/sso/:plugin/*`，均为公开路由）。浏览器整页跳转，
+ * 发起与回调都以 302 结束；失败回登录页并带原因码（`/login?error=<code>`），不回显身份源文本。
+ */
+export declare class SsoController {
+    private readonly flow;
+    private readonly sessions;
+    private readonly accounts;
+    private readonly config;
+    constructor(flow: SsoFlow, sessions: SessionService, accounts: AccountsService, config: () => KernelConfig);
+    sources(): {
+        sources: {
+            plugin: string;
+            label: {
+                zh: string;
+                en: string;
+            };
+        }[];
+    };
+    /**
+     * 发起登录：302 到身份源的授权地址，并写浏览器绑定 Cookie `cap_sso`（HttpOnly、SameSite=Lax——身份源回跳是
+     * 跨站顶级 GET 导航，Lax 会带上；Path 只到 `/api/v1/auth/sso`）。已登录的用户同样可以发起（见 callback）。
+     */
+    start(plugin: string, returnTo: unknown, principal: Principal | undefined, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    /**
+     * 身份源回跳：核对 state 与绑定 Cookie → 插件换取外部身份 → 解析到账号 → 建会话、写会话 Cookie → 302 回网页
+     * （`http.publicUrl` + returnTo）。账号已停用 → 登录页 `auth.account_disabled`，不建会话。
+     * 请求已带着 Web 会话时（已登录的用户发起，「登录状态下绑定」），把会话的账号交给 `SsoFlow.callback`：
+     * 与发起时记下的会话账号相同，经 IM 绑定建立的同一账号的身份才由此升级为可登录（Ruling A18）。
+     */
+    callback(plugin: string, q: Record<string, unknown>, principal: Principal | undefined, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+}
+export declare class BindController {
+    private readonly binding;
+    constructor(binding: IdentityBinding);
+    peek(principal: Principal, token: string): Promise<{
+        binding: PendingBinding;
+    }>;
+    bind(principal: Principal, token: string): Promise<{
+        binding: PendingBinding;
+    }>;
+}
+/** 本人绑定的外部身份（`/api/v1/me/identities`）：列出、解除。 */
+export declare class MeIdentitiesController {
+    private readonly external;
+    constructor(external: ExternalIdentities);
+    list(principal: Principal): Promise<{
+        identities: LinkedIdentity[];
+    }>;
+    unlink(principal: Principal, source: string, externalId: string): Promise<void>;
+}

package/dist/identity/sso.controller.js

@@ -0,0 +1,192 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Query, Req, Res, } from "@nestjs/common";
+import { ACCOUNTS, EXTERNAL_IDENTITIES, IDENTITY_BINDING, KERNEL_CONFIG, SESSIONS, SSO_FLOW, } from "../http/tokens.js";
+import { clientMeta } from "./auth.controller.js";
+import { setSessionCookies } from "./cookies.js";
+import { CurrentPrincipal, Public, requireUser, SessionOnly } from "./principal.js";
+import { SSO_BINDING_COOKIE, SSO_COOKIE_PATH, SSO_STATE_TTL_SECONDS, ssoBrowserBinding, } from "./sso.js";
+const MAX_QUERY_KEYS = 50;
+const MAX_QUERY_VALUE = 4096;
+/** 查询参数只取单值字符串（重复参数 / 数组 / 超长值丢弃）。 */
+function stringQuery(q) {
+    const out = {};
+    for (const [k, v] of Object.entries(q).slice(0, MAX_QUERY_KEYS)) {
+        if (typeof v === "string" && v.length <= MAX_QUERY_VALUE)
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * 第三方登录（`/api/v1/auth/sources`、`/api/v1/auth/sso/:plugin/*`，均为公开路由）。浏览器整页跳转，
+ * 发起与回调都以 302 结束；失败回登录页并带原因码（`/login?error=<code>`），不回显身份源文本。
+ */
+let SsoController = class SsoController {
+    flow;
+    sessions;
+    accounts;
+    config;
+    constructor(flow, sessions, accounts, config) {
+        this.flow = flow;
+        this.sessions = sessions;
+        this.accounts = accounts;
+        this.config = config;
+    }
+    sources() {
+        return { sources: this.flow.sources() };
+    }
+    /**
+     * 发起登录：302 到身份源的授权地址，并写浏览器绑定 Cookie `cap_sso`（HttpOnly、SameSite=Lax——身份源回跳是
+     * 跨站顶级 GET 导航，Lax 会带上；Path 只到 `/api/v1/auth/sso`）。已登录的用户同样可以发起（见 callback）。
+     */
+    async start(plugin, returnTo, principal, req, reply) {
+        const binding = ssoBrowserBinding(req.cookies[SSO_BINDING_COOKIE]);
+        // 发起时的会话账号记进 state：回调时同一账号才升级经 IM 绑定的身份（见 callback）
+        const location = await this.flow.start(plugin, typeof returnTo === "string" ? returnTo : undefined, binding, sessionAccount(principal));
+        reply.setCookie(SSO_BINDING_COOKIE, binding, {
+            path: SSO_COOKIE_PATH,
+            httpOnly: true,
+            sameSite: "lax",
+            secure: this.flow.cookieSecure(),
+            maxAge: SSO_STATE_TTL_SECONDS,
+        });
+        await reply.header("cache-control", "no-store").redirect(location, 302);
+    }
+    /**
+     * 身份源回跳：核对 state 与绑定 Cookie → 插件换取外部身份 → 解析到账号 → 建会话、写会话 Cookie → 302 回网页
+     * （`http.publicUrl` + returnTo）。账号已停用 → 登录页 `auth.account_disabled`，不建会话。
+     * 请求已带着 Web 会话时（已登录的用户发起，「登录状态下绑定」），把会话的账号交给 `SsoFlow.callback`：
+     * 与发起时记下的会话账号相同，经 IM 绑定建立的同一账号的身份才由此升级为可登录（Ruling A18）。
+     */
+    async callback(plugin, q, principal, req, reply) {
+        const r = await this.flow.callback(plugin, stringQuery(q), req.cookies[SSO_BINDING_COOKIE], sessionAccount(principal));
+        let location;
+        if (!r.ok) {
+            location = this.flow.loginError(r.error);
+        }
+        else {
+            const account = await this.accounts.get(r.accountId);
+            if (account?.status !== "active") {
+                location = this.flow.loginError("auth.account_disabled");
+            }
+            else {
+                const session = await this.sessions.create(account.id, clientMeta(req));
+                setSessionCookies(reply, session, this.config());
+                location = this.flow.webUrl(r.returnTo);
+            }
+        }
+        reply.clearCookie(SSO_BINDING_COOKIE, { path: SSO_COOKIE_PATH });
+        await reply.header("cache-control", "no-store").redirect(location, 302);
+    }
+};
+__decorate([
+    Get("sources"),
+    Public()
+], SsoController.prototype, "sources", null);
+__decorate([
+    Get("sso/:plugin/start"),
+    Public(),
+    __param(0, Param("plugin")),
+    __param(1, Query("returnTo")),
+    __param(2, CurrentPrincipal()),
+    __param(3, Req()),
+    __param(4, Res())
+], SsoController.prototype, "start", null);
+__decorate([
+    Get("sso/:plugin/callback"),
+    Public(),
+    __param(0, Param("plugin")),
+    __param(1, Query()),
+    __param(2, CurrentPrincipal()),
+    __param(3, Req()),
+    __param(4, Res())
+], SsoController.prototype, "callback", null);
+SsoController = __decorate([
+    Controller("api/v1/auth"),
+    __param(0, Inject(SSO_FLOW)),
+    __param(1, Inject(SESSIONS)),
+    __param(2, Inject(ACCOUNTS)),
+    __param(3, Inject(KERNEL_CONFIG))
+], SsoController);
+export { SsoController };
+/**
+ * IM 身份绑定确认（`/api/v1/bind/:token`，需 Web 会话）：GET 查看待绑定的身份，POST 绑到当前账号。
+ * 令牌单次有效；身份已绑定他人 → 409 `identity.taken`。
+ */
+/** 请求带着的 Web 会话的账号（PAT / 未登录时 undefined）。 */
+function sessionAccount(principal) {
+    return principal?.kind === "user" && principal.via === "session"
+        ? principal.account.id
+        : undefined;
+}
+let BindController = class BindController {
+    binding;
+    constructor(binding) {
+        this.binding = binding;
+    }
+    async peek(principal, token) {
+        requireUser(principal);
+        return { binding: await this.binding.peek(token) };
+    }
+    async bind(principal, token) {
+        const p = requireUser(principal);
+        return { binding: await this.binding.bind(token, p.account.id) };
+    }
+};
+__decorate([
+    Get(":token"),
+    SessionOnly(),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("token"))
+], BindController.prototype, "peek", null);
+__decorate([
+    Post(":token"),
+    SessionOnly(),
+    HttpCode(200),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("token"))
+], BindController.prototype, "bind", null);
+BindController = __decorate([
+    Controller("api/v1/bind"),
+    __param(0, Inject(IDENTITY_BINDING))
+], BindController);
+export { BindController };
+/** 本人绑定的外部身份（`/api/v1/me/identities`）：列出、解除。 */
+let MeIdentitiesController = class MeIdentitiesController {
+    external;
+    constructor(external) {
+        this.external = external;
+    }
+    async list(principal) {
+        const p = requireUser(principal);
+        return { identities: await this.external.listForAccount(p.account.id) };
+    }
+    async unlink(principal, source, externalId) {
+        const p = requireUser(principal);
+        await this.external.unlink(p.account.id, source, externalId);
+    }
+};
+__decorate([
+    Get(),
+    __param(0, CurrentPrincipal())
+], MeIdentitiesController.prototype, "list", null);
+__decorate([
+    Delete(":source/:externalId"),
+    SessionOnly(),
+    HttpCode(204),
+    __param(0, CurrentPrincipal()),
+    __param(1, Param("source")),
+    __param(2, Param("externalId"))
+], MeIdentitiesController.prototype, "unlink", null);
+MeIdentitiesController = __decorate([
+    Controller("api/v1/me/identities"),
+    __param(0, Inject(EXTERNAL_IDENTITIES))
+], MeIdentitiesController);
+export { MeIdentitiesController };

package/dist/identity/sso.d.ts

@@ -0,0 +1,83 @@
+import { type Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import type { KernelConfig } from "../config/schema.js";
+import type { ExtensionHost } from "../extensions/host.js";
+import { type ExternalIdentities } from "./external.js";
+/** state 的有效期（秒）。 */
+export declare const SSO_STATE_TTL_SECONDS = 600;
+/** 浏览器绑定 Cookie：回调必须来自发起登录的同一个浏览器（防登录 CSRF / 把回跳链接转给别人）。 */
+export declare const SSO_BINDING_COOKIE = "cap_sso";
+/** 绑定 Cookie 的 Path：覆盖所有插件的回调。 */
+export declare const SSO_COOKIE_PATH = "/api/v1/auth/sso";
+/** 登录失败回到的网页（next-intl 会补语言前缀）。 */
+export declare const LOGIN_PATH = "/login";
+/** 插件 `callback` 的最长等待。 */
+export declare const SSO_CALLBACK_TIMEOUT_MS = 15000;
+/**
+ * 登录失败的原因码（放进回跳 URL `/login?error=<code>`，界面按码走 i18n；不回显身份源的任何文本）。
+ * `auth.account_disabled` 与 API 错误码同名。
+ */
+export type SsoLoginError = "sso.unavailable" | "sso.state_invalid" | "sso.session_mismatch" | "sso.access_denied" | "sso.provider_error" | "sso.identity_not_verified" | "auth.account_disabled";
+/** 一个有效的浏览器绑定值（复用请求里已有的，否则新生成）。 */
+export declare function ssoBrowserBinding(existing: string | undefined): string;
+/** 回跳页面：站内相对路径（以单个 `/` 开头，非 `//`），否则 `/`（防开放重定向）。 */
+export declare function safeReturnTo(p: string | undefined): string;
+export interface SsoFlowDeps {
+    redis: Redis;
+    config: () => KernelConfig;
+    host: Pick<ExtensionHost, "list" | "deploymentConfig">;
+    external: ExternalIdentities;
+    log: Pick<Logger, "warn">;
+}
+/** 回调结果：成功给账号与回跳页面，失败给原因码。 */
+export type SsoCallbackResult = {
+    ok: true;
+    accountId: string;
+    returnTo: string;
+} | {
+    ok: false;
+    error: SsoLoginError;
+};
+/**
+ * 第三方登录（`identity-source@1`）：发起时生成 state（32 字节随机串，Redis `capk:sso-state:<state>` 10 分钟、
+ * 单次有效，内含插件名、nonce、PKCE verifier、redirect_uri、回跳页面与浏览器绑定值的哈希），授权地址带 PKCE
+ * challenge（S256）；回调时先取后删 state、核对绑定 Cookie，再交给插件（连同 verifier）换取外部身份并解析到账号。
+ * 会话由 controller 在成功后创建。状态全部在 Redis，没有进程内状态。
+ *
+ * 已登录的用户也可以发起（「登录状态下绑定」）：回调请求带着同一账号的 Web 会话时，经 IM 绑定链接建立的身份
+ * 由此证明本人控制该外部身份，升级为可登录（Ruling A18，见 `ExternalIdentities.resolve`）。
+ */
+export declare class SsoFlow {
+    private readonly deps;
+    constructor(deps: SsoFlowDeps);
+    /** 已启用的登录方式：`auth.loginSources` 中（按其顺序）且已加载、提供 `identity-source@1` 的插件。 */
+    sources(): {
+        plugin: string;
+        label: {
+            zh: string;
+            en: string;
+        };
+    }[];
+    private provider;
+    private redirectUri;
+    /** 绑定 Cookie 是否加 Secure：`auth.cookieSecure`，或 `http.publicUrl` 是 https（浏览器经 https 访问）。 */
+    cookieSecure(): boolean;
+    /** 网页地址：`http.publicUrl` + 站内路径（未配置 publicUrl 时为相对地址）。 */
+    webUrl(path: string): string;
+    /** 登录页并带原因码。 */
+    loginError(code: SsoLoginError): string;
+    /**
+     * 发起登录，返回 302 目标：插件的授权地址；插件未启用、未配置 `http.publicUrl` 或插件出错 → 登录页 `sso.unavailable`。
+     * `binding` 为本浏览器的绑定值（由 controller 写入 Cookie）；`sessionAccountId` 为发起请求带着的 Web 会话账号。
+     */
+    start(plugin: string, returnTo: string | undefined, binding: string, sessionAccountId?: string): Promise<string>;
+    /**
+     * 处理身份源的回跳。state 先取后删（无论成败都不能再用）；state 属于别的插件 → `sso.state_invalid`；
+     * 绑定 Cookie 不符 → `sso.session_mismatch`；身份源报错只映射为原因码；插件交回的身份源键必须由内核推导得出
+     * （`${插件名}:${identity.tenantId}`，Ruling A19），否则按 `sso.provider_error` 拒绝。
+     * 身份行经 IM 绑定建立、且发起与回调时不是同一个已登录的本人账号 → `sso.identity_not_verified`
+     * （Ruling A18）。成功则解析到账号（不判断账号状态，由调用方处理）。
+     * `sessionAccountId`：回调请求已带着的 Web 会话的账号（未登录时省略）。
+     */
+    callback(plugin: string, query: Record<string, string>, binding: string | undefined, sessionAccountId?: string): Promise<SsoCallbackResult>;
+}

package/dist/identity/sso.js

@@ -0,0 +1,202 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { IDENTITY_SOURCE_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { isSafeReturnPath } from "../tools/oauth/flow.js";
+import { IdentityNotVerified } from "./external.js";
+/** state 的有效期（秒）。 */
+export const SSO_STATE_TTL_SECONDS = 600;
+/** 浏览器绑定 Cookie：回调必须来自发起登录的同一个浏览器（防登录 CSRF / 把回跳链接转给别人）。 */
+export const SSO_BINDING_COOKIE = "cap_sso";
+/** 绑定 Cookie 的 Path：覆盖所有插件的回调。 */
+export const SSO_COOKIE_PATH = "/api/v1/auth/sso";
+/** 登录失败回到的网页（next-intl 会补语言前缀）。 */
+export const LOGIN_PATH = "/login";
+/** 插件 `callback` 的最长等待。 */
+export const SSO_CALLBACK_TIMEOUT_MS = 15_000;
+const stateKey = (state) => `capk:sso-state:${state}`;
+const STATE_RE = /^[A-Za-z0-9_-]{43}$/;
+const BINDING_RE = /^[A-Za-z0-9_-]{43}$/;
+const b64url = (n = 32) => randomBytes(n).toString("base64url");
+const sha256 = (s) => createHash("sha256").update(s).digest("base64url");
+/** 常量时间比较两个 base64url 哈希（长度不同直接不等）。 */
+function sameHash(a, b) {
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+/** 一个有效的浏览器绑定值（复用请求里已有的，否则新生成）。 */
+export function ssoBrowserBinding(existing) {
+    return existing !== undefined && BINDING_RE.test(existing) ? existing : b64url();
+}
+/** 回跳页面：站内相对路径（以单个 `/` 开头，非 `//`），否则 `/`（防开放重定向）。 */
+export function safeReturnTo(p) {
+    return p !== undefined && isSafeReturnPath(p) ? p : "/";
+}
+/**
+ * 第三方登录（`identity-source@1`）：发起时生成 state（32 字节随机串，Redis `capk:sso-state:<state>` 10 分钟、
+ * 单次有效，内含插件名、nonce、PKCE verifier、redirect_uri、回跳页面与浏览器绑定值的哈希），授权地址带 PKCE
+ * challenge（S256）；回调时先取后删 state、核对绑定 Cookie，再交给插件（连同 verifier）换取外部身份并解析到账号。
+ * 会话由 controller 在成功后创建。状态全部在 Redis，没有进程内状态。
+ *
+ * 已登录的用户也可以发起（「登录状态下绑定」）：回调请求带着同一账号的 Web 会话时，经 IM 绑定链接建立的身份
+ * 由此证明本人控制该外部身份，升级为可登录（Ruling A18，见 `ExternalIdentities.resolve`）。
+ */
+export class SsoFlow {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 已启用的登录方式：`auth.loginSources` 中（按其顺序）且已加载、提供 `identity-source@1` 的插件。 */
+    sources() {
+        return this.deps.config().auth.loginSources.flatMap((plugin) => {
+            const src = this.provider(plugin);
+            return src ? [{ plugin, label: { zh: src.label.zh, en: src.label.en } }] : [];
+        });
+    }
+    provider(plugin) {
+        if (!this.deps.config().auth.loginSources.includes(plugin))
+            return undefined;
+        const entry = this.deps.host
+            .list("identity-source")
+            .find((e) => e.plugin === plugin && e.capability === IDENTITY_SOURCE_EXTENSION_POINT);
+        return entry?.impl;
+    }
+    redirectUri(plugin) {
+        const base = (this.deps.config().http.publicUrl ?? "").replace(/\/+$/, "");
+        return `${base}/api/v1/auth/sso/${encodeURIComponent(plugin)}/callback`;
+    }
+    /** 绑定 Cookie 是否加 Secure：`auth.cookieSecure`，或 `http.publicUrl` 是 https（浏览器经 https 访问）。 */
+    cookieSecure() {
+        const cfg = this.deps.config();
+        return cfg.auth.cookieSecure || (cfg.http.publicUrl ?? "").startsWith("https:");
+    }
+    /** 网页地址：`http.publicUrl` + 站内路径（未配置 publicUrl 时为相对地址）。 */
+    webUrl(path) {
+        const base = (this.deps.config().http.publicUrl ?? "").replace(/\/+$/, "");
+        return `${base}${path}`;
+    }
+    /** 登录页并带原因码。 */
+    loginError(code) {
+        return this.webUrl(`${LOGIN_PATH}?error=${encodeURIComponent(code)}`);
+    }
+    /**
+     * 发起登录，返回 302 目标：插件的授权地址；插件未启用、未配置 `http.publicUrl` 或插件出错 → 登录页 `sso.unavailable`。
+     * `binding` 为本浏览器的绑定值（由 controller 写入 Cookie）；`sessionAccountId` 为发起请求带着的 Web 会话账号。
+     */
+    async start(plugin, returnTo, binding, sessionAccountId) {
+        const src = this.provider(plugin);
+        if (!src || !this.deps.config().http.publicUrl)
+            return this.loginError("sso.unavailable");
+        const state = b64url();
+        const nonce = b64url();
+        const codeVerifier = b64url();
+        const redirectUri = this.redirectUri(plugin);
+        let url;
+        try {
+            url = src.authorizeUrl({
+                config: this.deps.host.deploymentConfig(plugin),
+                redirectUri,
+                state,
+                nonce,
+                codeChallenge: sha256(codeVerifier),
+                codeChallengeMethod: "S256",
+            });
+            const proto = new URL(url).protocol;
+            if (proto !== "https:" && proto !== "http:")
+                throw new Error("authorize URL must be http(s)");
+        }
+        catch (err) {
+            this.deps.log.warn("identity source authorizeUrl failed", { plugin, err });
+            return this.loginError("sso.unavailable");
+        }
+        const rec = {
+            plugin,
+            nonce,
+            redirectUri,
+            returnTo: safeReturnTo(returnTo),
+            binding: sha256(binding),
+            codeVerifier,
+            ...(sessionAccountId !== undefined && { sessionAccountId }),
+        };
+        await this.deps.redis.set(stateKey(state), JSON.stringify(rec), "EX", SSO_STATE_TTL_SECONDS);
+        return url;
+    }
+    /**
+     * 处理身份源的回跳。state 先取后删（无论成败都不能再用）；state 属于别的插件 → `sso.state_invalid`；
+     * 绑定 Cookie 不符 → `sso.session_mismatch`；身份源报错只映射为原因码；插件交回的身份源键必须由内核推导得出
+     * （`${插件名}:${identity.tenantId}`，Ruling A19），否则按 `sso.provider_error` 拒绝。
+     * 身份行经 IM 绑定建立、且发起与回调时不是同一个已登录的本人账号 → `sso.identity_not_verified`
+     * （Ruling A18）。成功则解析到账号（不判断账号状态，由调用方处理）。
+     * `sessionAccountId`：回调请求已带着的 Web 会话的账号（未登录时省略）。
+     */
+    async callback(plugin, query, binding, sessionAccountId) {
+        const state = query.state;
+        if (state === undefined || !STATE_RE.test(state))
+            return { ok: false, error: "sso.state_invalid" };
+        const raw = await this.deps.redis.getdel(stateKey(state));
+        if (raw === null)
+            return { ok: false, error: "sso.state_invalid" };
+        const rec = JSON.parse(raw);
+        if (rec.plugin !== plugin)
+            return { ok: false, error: "sso.state_invalid" };
+        if (binding === undefined || !sameHash(sha256(binding), rec.binding)) {
+            return { ok: false, error: "sso.session_mismatch" };
+        }
+        if (query.error !== undefined) {
+            return {
+                ok: false,
+                error: query.error === "access_denied" ? "sso.access_denied" : "sso.provider_error",
+            };
+        }
+        const src = this.provider(plugin);
+        if (!src)
+            return { ok: false, error: "sso.unavailable" };
+        let identity;
+        try {
+            identity = await src.callback({
+                config: this.deps.host.deploymentConfig(plugin),
+                redirectUri: rec.redirectUri,
+                query,
+                nonce: rec.nonce,
+                signal: AbortSignal.timeout(SSO_CALLBACK_TIMEOUT_MS),
+                codeVerifier: rec.codeVerifier,
+            });
+        }
+        catch (err) {
+            this.deps.log.warn("identity source callback failed", { plugin, err });
+            return { ok: false, error: "sso.provider_error" };
+        }
+        // 身份源键由内核推导（Ruling A19）：插件只能为自己、为它报出的租户声明身份
+        if (typeof identity?.tenantId !== "string" ||
+            identity.source !== `${plugin}:${identity.tenantId}`) {
+            this.deps.log.warn("identity source returned a source key that does not match its tenant", {
+                plugin,
+            });
+            return { ok: false, error: "sso.provider_error" };
+        }
+        // 升级 bind 身份：发起与回调时是同一个已登录账号才算本人在登录状态下证明了对该身份的控制
+        const provedBy = rec.sessionAccountId !== undefined && rec.sessionAccountId === sessionAccountId
+            ? sessionAccountId
+            : undefined;
+        let accountId;
+        try {
+            // 只有登录路径允许按已验证邮箱合并（Ruling A9）
+            accountId = (await this.deps.external.resolve(identity, undefined, {
+                allowMerge: true,
+                linkedVia: "sso",
+                login: provedBy === undefined ? {} : { sessionAccountId: provedBy },
+            })).accountId;
+        }
+        catch (err) {
+            if (err instanceof IdentityNotVerified) {
+                this.deps.log.warn("sign-in with an unverified linked identity refused", { plugin });
+                return { ok: false, error: "sso.identity_not_verified" };
+            }
+            if (!(err instanceof ApiError))
+                throw err;
+            this.deps.log.warn("external identity rejected", { plugin, err });
+            return { ok: false, error: "sso.provider_error" };
+        }
+        return { ok: true, accountId, returnTo: rec.returnTo };
+    }
+}

package/dist/inbox/inbox.service.d.ts

@@ -0,0 +1,43 @@
+import { type CatalogRequestsService, type CatalogRequestView } from "../catalog/requests.service.js";
+import { type SkillChangesService, type SkillChangeView } from "../skills/changes.service.js";
+import { type ApprovalsService, type ApprovalView } from "../tools/approvals.service.js";
+/** 收件箱一次最多返回的事项数。 */
+export declare const INBOX_MAX_ITEMS = 100;
+/**
+ * 收件箱里的一项（按 `type` 区分，形状稳定）：
+ * - `tool_approval`：当前用户能处理的待处理工具调用审批（与 `GET /approvals?status=pending` 同一视图）；
+ * - `skill_change`：当前用户作为 agent 负责人能决定的待处理技能变更（M5 T15，R4）；
+ * - `catalog_request`: pending catalog requests from members, when the current user is an org
+ *   admin (M6 T26, C22).
+ */
+export type InboxItem = {
+    type: "tool_approval";
+    id: string;
+    createdAt: string;
+    approval: ApprovalView;
+} | {
+    type: "skill_change";
+    id: string;
+    createdAt: string;
+    skillChange: SkillChangeView;
+} | {
+    type: "catalog_request";
+    id: string;
+    createdAt: string;
+    request: CatalogRequestView;
+};
+/** `GET /inbox` 的结果：新的在前，最多 {@link INBOX_MAX_ITEMS} 项；`truncated` 为 true 表示还有更多。 */
+export interface InboxView {
+    items: InboxItem[];
+    truncated: boolean;
+}
+/** 收件箱（计划取舍 C6）：按类型汇总各来源的待处理事项。无状态，每次实时读 PG。 */
+export declare class InboxService {
+    private readonly d;
+    constructor(d: {
+        approvals: Pick<ApprovalsService, "list">;
+        skillChanges: Pick<SkillChangesService, "listPending">;
+        catalogRequests?: Pick<CatalogRequestsService, "listForOrgAdmin">;
+    });
+    list(orgId: string, accountId: string): Promise<InboxView>;
+}

package/dist/inbox/inbox.service.js

@@ -0,0 +1,57 @@
+import { CATALOG_REQUESTS_LIST_MAX, } from "../catalog/requests.service.js";
+import { SKILL_CHANGES_LIST_MAX, } from "../skills/changes.service.js";
+import { APPROVALS_LIST_MAX, } from "../tools/approvals.service.js";
+/** 收件箱一次最多返回的事项数。 */
+export const INBOX_MAX_ITEMS = 100;
+/** 收件箱（计划取舍 C6）：按类型汇总各来源的待处理事项。无状态，每次实时读 PG。 */
+export class InboxService {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    async list(orgId, accountId) {
+        const [approvals, changes, requests] = await Promise.all([
+            this.d.approvals.list(orgId, accountId, "pending"),
+            this.d.skillChanges.listPending(orgId, accountId),
+            this.d.catalogRequests?.listForOrgAdmin(orgId, accountId) ?? [],
+        ]);
+        const all = [
+            ...approvals.map((a) => ({
+                type: "tool_approval",
+                id: a.id,
+                createdAt: a.createdAt,
+                approval: a,
+            })),
+            ...changes.map((c) => ({
+                type: "skill_change",
+                id: c.id,
+                createdAt: c.createdAt,
+                skillChange: c,
+            })),
+            ...requests.map((r) => ({
+                type: "catalog_request",
+                id: r.id,
+                createdAt: r.createdAt,
+                request: r,
+            })),
+        ];
+        // 新的在前；同一时刻按 id 定序（结果稳定）
+        all.sort((a, b) => a.createdAt !== b.createdAt
+            ? a.createdAt < b.createdAt
+                ? 1
+                : -1
+            : a.id < b.id
+                ? -1
+                : a.id > b.id
+                    ? 1
+                    : 0);
+        // 各来源自己也有上限：某个来源取满了也算还有更多
+        const full = approvals.length >= APPROVALS_LIST_MAX ||
+            changes.length >= SKILL_CHANGES_LIST_MAX ||
+            requests.length >= CATALOG_REQUESTS_LIST_MAX;
+        return {
+            items: all.slice(0, INBOX_MAX_ITEMS),
+            truncated: full || all.length > INBOX_MAX_ITEMS,
+        };
+    }
+}