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

package/dist/tools/oauth/discovery.d.ts

@@ -0,0 +1,65 @@
+import type { KernelConfig } from "../../config/schema.js";
+import type { OAuthClientRecord, TokenAuthMethod } from "./tokens.js";
+/**
+ * MCP OAuth 发现与动态注册（MCP 授权规范）：
+ * RFC 9728 受保护资源元数据（401 的 `WWW-Authenticate: Bearer resource_metadata=…`，或
+ * `/.well-known/oauth-protected-resource[/<path>]`）→ RFC 8414 授权服务器元数据（OpenID 发现文档作回退）
+ * → RFC 7591 动态客户端注册。
+ *
+ * 自己实现而不引库：内核只需要这几次 HTTP 往返，且要统一「不跟随重定向、限时、限响应大小、只允许 https」
+ * 与错误映射（错误只带原因码与英文说明，不带对方响应正文）。`oauth4webapi` 默认禁止 http、自带错误模型，
+ * 换来的代码量并不少；MCP SDK 的 client auth 帮助函数围绕交互式 `OAuthClientProvider`，且会把 MCP SDK
+ * 拉进与协议无关的内核。
+ */
+export interface OAuthHttpOptions {
+    /** 允许本机（127.0.0.1 / localhost / [::1]）的 http，仅开发与测试。 */
+    allowInsecureLoopback: boolean;
+    timeoutMs: number;
+}
+/** OAuth 往返的限时：工具超时与 30 秒取小。 */
+export declare function oauthHttpOptions(cfg: KernelConfig): OAuthHttpOptions;
+export type OAuthSetupReason = "insecure_url" | "discovery_failed" | "dcr_unsupported" | "dcr_failed" | "token_failed";
+/** 发现 / 注册 / 安装时取 token 失败：原因码供向导分支（如 `dcr_unsupported` 改为手填 client），说明为英文。 */
+export declare class OAuthSetupError extends Error {
+    readonly reason: OAuthSetupReason;
+    constructor(reason: OAuthSetupReason, message: string);
+}
+/** 只接受 https（放行时本机 http 也可），不允许 URL 里带用户信息。 */
+export declare function checkOAuthUrl(raw: string, http: OAuthHttpOptions): URL;
+export interface OAuthResponse {
+    status: number;
+    headers: Headers;
+    text: string;
+}
+/**
+ * OAuth 往返：校验 URL、不跟随重定向（3xx 原样返回，调用方按失败处理）、限时、正文超过 1 MiB 即中止。
+ * 网络错误 / 超时原样抛出。
+ */
+export declare function oauthFetch(url: string, init: RequestInit, http: OAuthHttpOptions): Promise<OAuthResponse>;
+/** 发现结果：授权服务器端点 + 资源标识（RFC 8707 `resource` 参数）。 */
+export interface McpAuthMetadata {
+    resource: string;
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint?: string;
+    /** 401 的 `scope` 参数，或受保护资源元数据的 `scopes_supported`。 */
+    scopes?: string[];
+    /** 授权服务器的 `token_endpoint_auth_methods_supported`。 */
+    authMethods?: string[];
+}
+/**
+ * 对 MCP 端点做 OAuth 发现：先以不带凭据的 `initialize` 探测拿 401 的 `WWW-Authenticate`，再取受保护资源元数据，
+ * 再取授权服务器元数据（RFC 8414 §3.1 的路径插入式，OpenID 发现作回退）。校验资源标识与端点匹配、
+ * 元数据 `issuer` 与授权服务器标识一致、声明了 PKCE 方法时必须含 S256。
+ */
+export declare function discoverMcp(endpointUrl: string, http: OAuthHttpOptions): Promise<McpAuthMetadata>;
+/** 按授权服务器声明的方法选客户端认证方式（未声明时 RFC 8414 默认 client_secret_basic）。 */
+export declare function pickAuthMethod(supported: string[] | undefined, hasSecret: boolean): TokenAuthMethod;
+/**
+ * 动态客户端注册（RFC 7591），每个连接器注册一次。授权服务器没有注册端点 → `dcr_unsupported`（向导据此改为手填
+ * client）。注册失败只报 HTTP 状态，不带对方正文。
+ */
+export declare function registerClient(meta: McpAuthMetadata, redirectUri: string, http: OAuthHttpOptions, 
+/** 管理员指定的客户端认证方式（`tokenAuthMethod`）；不给则按授权服务器声明选择。 */
+preferred?: TokenAuthMethod): Promise<OAuthClientRecord>;

package/dist/tools/oauth/discovery.js

@@ -0,0 +1,307 @@
+/** OAuth 往返的限时：工具超时与 30 秒取小。 */
+export function oauthHttpOptions(cfg) {
+    return {
+        allowInsecureLoopback: cfg.tools.oauthAllowInsecureLoopback,
+        timeoutMs: Math.min(cfg.tools.timeoutMs, 30_000),
+    };
+}
+/** 发现 / 注册 / 安装时取 token 失败：原因码供向导分支（如 `dcr_unsupported` 改为手填 client），说明为英文。 */
+export class OAuthSetupError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "OAuthSetupError";
+    }
+}
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+/** 元数据 / 令牌响应的大小上限。 */
+const MAX_BODY_BYTES = 1024 * 1024;
+/** 只接受 https（放行时本机 http 也可），不允许 URL 里带用户信息。 */
+export function checkOAuthUrl(raw, http) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new OAuthSetupError("discovery_failed", "An OAuth URL is not a valid absolute URL");
+    }
+    const ok = u.protocol === "https:" ||
+        (u.protocol === "http:" && http.allowInsecureLoopback && LOOPBACK.has(u.hostname));
+    if (!ok) {
+        throw new OAuthSetupError("insecure_url", `OAuth URLs must use https (got ${u.protocol}//${u.host})`);
+    }
+    if (u.username !== "" || u.password !== "") {
+        throw new OAuthSetupError("insecure_url", "OAuth URLs must not contain user information");
+    }
+    return u;
+}
+/**
+ * OAuth 往返：校验 URL、不跟随重定向（3xx 原样返回，调用方按失败处理）、限时、正文超过 1 MiB 即中止。
+ * 网络错误 / 超时原样抛出。
+ */
+export async function oauthFetch(url, init, http) {
+    checkOAuthUrl(url, http);
+    const res = await fetch(url, {
+        ...init,
+        redirect: "manual",
+        signal: AbortSignal.timeout(http.timeoutMs),
+    });
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        await res.body?.cancel();
+        throw new Error("OAuth response is too large");
+    }
+    const chunks = [];
+    let size = 0;
+    if (res.body) {
+        const reader = res.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_BODY_BYTES) {
+                await reader.cancel().catch(() => { });
+                throw new Error("OAuth response is too large");
+            }
+            chunks.push(value);
+        }
+    }
+    return { status: res.status, headers: res.headers, text: Buffer.concat(chunks).toString("utf8") };
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const parseJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string") ? v : undefined;
+/** `WWW-Authenticate: Bearer k="v", …` 中某个参数（带引号或不带）。 */
+function challengeParam(header, name) {
+    if (!header)
+        return undefined;
+    const m = new RegExp(`(?:^|[\\s,])${name}\\s*=\\s*(?:"([^"]*)"|([^\\s,]+))`, "i").exec(header);
+    return m ? (m[1] ?? m[2]) : undefined;
+}
+const failed = (message) => new OAuthSetupError("discovery_failed", message);
+/** 依次 GET 候选地址，返回第一个 200 且为 JSON 对象的正文；网络错误按「这个位置没有」处理。 */
+async function firstJson(urls, http) {
+    for (const url of urls) {
+        let res;
+        try {
+            res = await oauthFetch(url, { headers: { accept: "application/json" } }, http);
+        }
+        catch (e) {
+            if (e instanceof OAuthSetupError)
+                throw e;
+            continue;
+        }
+        if (res.status !== 200)
+            continue;
+        const body = parseJson(res.text);
+        if (isObj(body))
+            return body;
+    }
+    return undefined;
+}
+/** 资源标识与端点：同源，且端点路径以资源路径为前缀（MCP 规范的资源匹配）。 */
+function resourceMatches(resource, endpoint) {
+    let r;
+    try {
+        r = new URL(resource);
+    }
+    catch {
+        return false;
+    }
+    if (r.origin !== endpoint.origin)
+        return false;
+    const rp = r.pathname.endsWith("/") ? r.pathname : `${r.pathname}/`;
+    const ep = endpoint.pathname.endsWith("/") ? endpoint.pathname : `${endpoint.pathname}/`;
+    return ep.startsWith(rp);
+}
+const trimSlash = (s) => s.replace(/\/+$/, "");
+/**
+ * 对 MCP 端点做 OAuth 发现：先以不带凭据的 `initialize` 探测拿 401 的 `WWW-Authenticate`，再取受保护资源元数据，
+ * 再取授权服务器元数据（RFC 8414 §3.1 的路径插入式，OpenID 发现作回退）。校验资源标识与端点匹配、
+ * 元数据 `issuer` 与授权服务器标识一致、声明了 PKCE 方法时必须含 S256。
+ */
+export async function discoverMcp(endpointUrl, http) {
+    const endpoint = checkOAuthUrl(endpointUrl, http);
+    let challenge = null;
+    try {
+        const probe = await oauthFetch(endpoint.toString(), {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json, text/event-stream",
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "initialize",
+                params: {
+                    protocolVersion: "2025-06-18",
+                    capabilities: {},
+                    clientInfo: { name: "capybara", version: "0.1.0" },
+                },
+            }),
+        }, http);
+        if (probe.status === 401)
+            challenge = probe.headers.get("www-authenticate");
+    }
+    catch (e) {
+        if (e instanceof OAuthSetupError)
+            throw e;
+        throw failed("Could not reach the connector's server for OAuth discovery");
+    }
+    const metadataUrl = challengeParam(challenge, "resource_metadata");
+    const prmCandidates = [];
+    if (metadataUrl !== undefined) {
+        prmCandidates.push(checkOAuthUrl(metadataUrl, http).toString());
+    }
+    else {
+        const path = trimSlash(endpoint.pathname);
+        if (path !== "")
+            prmCandidates.push(`${endpoint.origin}/.well-known/oauth-protected-resource${path}`);
+        prmCandidates.push(`${endpoint.origin}/.well-known/oauth-protected-resource`);
+    }
+    const prm = await firstJson(prmCandidates, http);
+    if (!prm) {
+        throw failed("The connector's server did not publish OAuth protected resource metadata (RFC 9728)");
+    }
+    const resource = prm.resource;
+    const servers = strings(prm.authorization_servers);
+    if (typeof resource !== "string" || !servers || servers.length === 0) {
+        throw failed("The protected resource metadata lacks resource or authorization_servers");
+    }
+    if (!resourceMatches(resource, endpoint)) {
+        throw failed("The protected resource metadata names a different resource than the connector's URL");
+    }
+    const issuer = servers[0];
+    const as = checkOAuthUrl(issuer, http);
+    const asPath = trimSlash(as.pathname);
+    const asCandidates = asPath === ""
+        ? [
+            `${as.origin}/.well-known/oauth-authorization-server`,
+            `${as.origin}/.well-known/openid-configuration`,
+        ]
+        : [
+            `${as.origin}/.well-known/oauth-authorization-server${asPath}`,
+            `${as.origin}/.well-known/openid-configuration${asPath}`,
+            `${as.origin}${asPath}/.well-known/openid-configuration`,
+        ];
+    const meta = await firstJson(asCandidates, http);
+    if (!meta)
+        throw failed("The authorization server did not publish its metadata (RFC 8414)");
+    // RFC 8414 §3.3：元数据的 issuer 必须与授权服务器标识完全相同
+    if (meta.issuer !== issuer) {
+        throw failed("The authorization server metadata issuer does not match the server");
+    }
+    const authz = meta.authorization_endpoint;
+    const token = meta.token_endpoint;
+    if (typeof authz !== "string" || typeof token !== "string") {
+        throw failed("The authorization server metadata lacks authorization or token endpoints");
+    }
+    checkOAuthUrl(authz, http);
+    checkOAuthUrl(token, http);
+    const pkce = strings(meta.code_challenge_methods_supported);
+    // MCP 授权规范：授权服务器必须声明支持 S256，未声明即拒绝
+    if (!pkce?.includes("S256")) {
+        throw failed("The authorization server does not advertise PKCE S256 support (code_challenge_methods_supported)");
+    }
+    const reg = meta.registration_endpoint;
+    if (reg !== undefined && typeof reg !== "string") {
+        throw failed("The authorization server metadata has an invalid registration_endpoint");
+    }
+    const scopeParam = challengeParam(challenge, "scope");
+    const scopes = scopeParam !== undefined
+        ? scopeParam.split(/\s+/).filter(Boolean)
+        : strings(prm.scopes_supported);
+    const authMethods = strings(meta.token_endpoint_auth_methods_supported);
+    return {
+        resource,
+        issuer,
+        authorizationEndpoint: authz,
+        tokenEndpoint: token,
+        ...(reg !== undefined && { registrationEndpoint: reg }),
+        ...(scopes !== undefined && scopes.length > 0 && { scopes }),
+        ...(authMethods !== undefined && { authMethods }),
+    };
+}
+/** 按授权服务器声明的方法选客户端认证方式（未声明时 RFC 8414 默认 client_secret_basic）。 */
+export function pickAuthMethod(supported, hasSecret) {
+    if (!hasSecret)
+        return "none";
+    if (!supported || supported.includes("client_secret_basic"))
+        return "client_secret_basic";
+    if (supported.includes("client_secret_post"))
+        return "client_secret_post";
+    return supported.includes("none") ? "none" : "client_secret_basic";
+}
+/**
+ * 动态客户端注册（RFC 7591），每个连接器注册一次。授权服务器没有注册端点 → `dcr_unsupported`（向导据此改为手填
+ * client）。注册失败只报 HTTP 状态，不带对方正文。
+ */
+export async function registerClient(meta, redirectUri, http, 
+/** 管理员指定的客户端认证方式（`tokenAuthMethod`）；不给则按授权服务器声明选择。 */
+preferred) {
+    if (!meta.registrationEndpoint) {
+        throw new OAuthSetupError("dcr_unsupported", "The authorization server does not support dynamic client registration; provide a client ID (and secret) registered with it");
+    }
+    // 优先机密客户端（client_secret_basic / post）；授权服务器两者都不支持时注册为公开客户端（只靠 PKCE）
+    const wanted = preferred ?? pickAuthMethod(meta.authMethods, true);
+    let res;
+    try {
+        res = await oauthFetch(meta.registrationEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({
+                client_name: "Capybara",
+                redirect_uris: [redirectUri],
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: wanted,
+                ...(meta.scopes && { scope: meta.scopes.join(" ") }),
+            }),
+        }, http);
+    }
+    catch (e) {
+        if (e instanceof OAuthSetupError)
+            throw e;
+        throw new OAuthSetupError("dcr_failed", "Could not reach the client registration endpoint");
+    }
+    const body = parseJson(res.text);
+    if ((res.status !== 201 && res.status !== 200) ||
+        !isObj(body) ||
+        typeof body.client_id !== "string") {
+        throw new OAuthSetupError("dcr_failed", `Dynamic client registration failed (HTTP ${res.status})`);
+    }
+    const secret = typeof body.client_secret === "string" && body.client_secret !== ""
+        ? body.client_secret
+        : undefined;
+    const method = body.token_endpoint_auth_method;
+    const authMethod = method === "client_secret_basic" || method === "client_secret_post" || method === "none"
+        ? method
+        : pickAuthMethod(meta.authMethods, secret !== undefined);
+    const regToken = body.registration_access_token;
+    const regUri = body.registration_client_uri;
+    return {
+        clientId: body.client_id,
+        ...(secret !== undefined && { clientSecret: secret }),
+        authMethod,
+        authorizationEndpoint: meta.authorizationEndpoint,
+        tokenEndpoint: meta.tokenEndpoint,
+        resource: meta.resource,
+        issuer: meta.issuer,
+        ...(meta.scopes && { scopes: meta.scopes }),
+        registration: {
+            ...(typeof regToken === "string" && { accessToken: regToken }),
+            ...(typeof regUri === "string" && { clientUri: regUri }),
+            ...(typeof body.client_id_issued_at === "number" && { issuedAt: body.client_id_issued_at }),
+        },
+    };
+}

package/dist/tools/oauth/flow.d.ts

@@ -0,0 +1,63 @@
+import type { Logger } 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 { ApiError } from "../../errors.js";
+import type { Credentials } from "../credentials.js";
+/** 授权回调的路径（`http.publicUrl` + 它 = 注册给授权服务器的 redirect_uri）。 */
+export declare const OAUTH_CALLBACK_PATH = "/api/v1/oauth/callback";
+/** state 的有效期（秒）。 */
+export declare const OAUTH_STATE_TTL_SECONDS = 600;
+/** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
+export declare const OAUTH_BINDING_COOKIE = "cap_oauth";
+/** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
+export declare const DEFAULT_RETURN_PATH = "/settings/connections";
+/** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
+export declare const publicUrlRequired: () => ApiError;
+export declare function callbackUrl(publicUrl: string): string;
+/**
+ * 回跳页面只接受站内相对路径（防开放重定向）：以单个 `/` 开头，不含 `\` 与控制字符，解析后仍在同一个源。
+ */
+export declare function isSafeReturnPath(p: string): boolean;
+/** 一个有效的浏览器绑定值（复用请求里已有的，否则新生成）。 */
+export declare function browserBinding(existing: string | undefined): string;
+/** 回调失败的原因码（放进回跳 URL 的 `oauth_error`；不回显授权服务器的任何文本）。 */
+export type OAuthCallbackError = "state_invalid" | "session_mismatch" | "access_denied" | "provider_error" | "token_exchange_failed" | "issuer_mismatch" | "connector_unavailable";
+/** 首次连接后刷新工具清单最多等这么久再 302（超时则在后台继续，结果照常写入）。 */
+export declare const FIRST_CONNECT_REFRESH_WAIT_MS = 15000;
+export interface OAuthFlowDeps {
+    db: KernelDb;
+    redis: Redis;
+    credentials: Credentials;
+    config: () => KernelConfig;
+    log: Logger;
+    /** 某成员首次成功连接、而连接器还没有工具快照时调用（A16：用该成员的 token 刷新工具清单）。 */
+    onFirstConnect: (orgId: string, connectorId: string, accountId: string) => Promise<void>;
+}
+/**
+ * 授权码 + PKCE（S256）连接流程。state 是 32 字节随机串，存 Redis `capk:oauth-state:<state>` 10 分钟、单次有效
+ * （GETDEL），内含组织、连接器、发起人、PKCE verifier、redirect_uri、回跳页面与浏览器绑定值的哈希。
+ */
+export declare class OAuthFlow {
+    private readonly deps;
+    constructor(deps: OAuthFlowDeps);
+    private app;
+    /** 生成授权 URL。`binding` 为本浏览器的绑定值（由 controller 写入 Cookie）。 */
+    start(orgId: string, connectorId: string, accountId: string, returnTo: string | undefined, binding: string): Promise<{
+        authorizationUrl: string;
+    }>;
+    /** 回跳地址：`http.publicUrl` + 站内路径 + 结果参数（未配置 publicUrl 时为相对地址）。 */
+    private redirect;
+    private fail;
+    /**
+     * 处理授权服务器的回跳，返回 302 的目标。state 先取后删（无论后续成败都不能再用）；浏览器绑定不符 →
+     * `session_mismatch`（把回跳链接转给别人不能把对方的授权连到发起人账号上）；授权服务器报错只映射为原因码。
+     * 成功则在组织行锁内复核发起人仍是成员（`connectors.use`），写个人凭据与审计；连接器还没有工具快照时用这个 token 刷新。
+     */
+    callback(query: {
+        code?: string | undefined;
+        state?: string | undefined;
+        error?: string | undefined;
+        iss?: string | undefined;
+    }, binding: string | undefined): Promise<string>;
+}

package/dist/tools/oauth/flow.js

@@ -0,0 +1,237 @@
+import { createHash, randomBytes } from "node:crypto";
+import { ApiError } from "../../errors.js";
+import { audit } from "../../identity/audit.js";
+import { lockOrgAndAuthorize } from "../../orgs/org-lock.js";
+import { oauthHttpOptions } from "./discovery.js";
+import { tokenRequest } from "./tokens.js";
+/** 授权回调的路径（`http.publicUrl` + 它 = 注册给授权服务器的 redirect_uri）。 */
+export const OAUTH_CALLBACK_PATH = "/api/v1/oauth/callback";
+/** state 的有效期（秒）。 */
+export const OAUTH_STATE_TTL_SECONDS = 600;
+/** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
+export const OAUTH_BINDING_COOKIE = "cap_oauth";
+/** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
+export const DEFAULT_RETURN_PATH = "/settings/connections";
+const stateKey = (state) => `capk:oauth-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");
+/** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
+export const publicUrlRequired = () => new ApiError("validation_failed", "Request validation failed", [
+    {
+        path: "auth",
+        message: "OAuth connectors require http.publicUrl to be configured (it is used to build the OAuth callback URL)",
+    },
+]);
+export function callbackUrl(publicUrl) {
+    return `${publicUrl.replace(/\/+$/, "")}${OAUTH_CALLBACK_PATH}`;
+}
+/**
+ * 回跳页面只接受站内相对路径（防开放重定向）：以单个 `/` 开头，不含 `\` 与控制字符，解析后仍在同一个源。
+ */
+export function isSafeReturnPath(p) {
+    if (p.length > 500 || !p.startsWith("/") || p.startsWith("//"))
+        return false;
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要拒绝控制字符
+    if (/[\\\u0000-\u001f\u007f]/.test(p))
+        return false;
+    const base = "https://return.invalid";
+    try {
+        return new URL(p, base).origin === base;
+    }
+    catch {
+        return false;
+    }
+}
+/** 一个有效的浏览器绑定值（复用请求里已有的，否则新生成）。 */
+export function browserBinding(existing) {
+    return existing !== undefined && BINDING_RE.test(existing) ? existing : b64url();
+}
+/** 首次连接后刷新工具清单最多等这么久再 302（超时则在后台继续，结果照常写入）。 */
+export const FIRST_CONNECT_REFRESH_WAIT_MS = 15_000;
+/**
+ * 授权码 + PKCE（S256）连接流程。state 是 32 字节随机串，存 Redis `capk:oauth-state:<state>` 10 分钟、单次有效
+ * （GETDEL），内含组织、连接器、发起人、PKCE verifier、redirect_uri、回跳页面与浏览器绑定值的哈希。
+ */
+export class OAuthFlow {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async app(orgId, connectorId) {
+        return this.deps.db
+            .selectFrom("connectors")
+            .select(["id", "auth", "status"])
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+    }
+    /** 生成授权 URL。`binding` 为本浏览器的绑定值（由 controller 写入 Cookie）。 */
+    async start(orgId, connectorId, accountId, returnTo, binding) {
+        const publicUrl = this.deps.config().http.publicUrl;
+        if (!publicUrl)
+            throw publicUrlRequired();
+        const app = await this.app(orgId, connectorId);
+        if (!app)
+            throw new ApiError("connector.not_found", "Connector not found");
+        if (app.auth.type !== "oauth_code") {
+            throw new ApiError("validation_failed", "Request validation failed", [
+                {
+                    path: "auth",
+                    message: "Only OAuth authorization-code connectors are connected this way",
+                },
+            ]);
+        }
+        if (app.status !== "active") {
+            throw new ApiError("validation_failed", "Request validation failed", [
+                { path: "status", message: "The connector is disabled; ask an administrator to enable it" },
+            ]);
+        }
+        const client = await this.deps.credentials.oauthClient(orgId, connectorId);
+        if (!client?.authorizationEndpoint) {
+            throw new ApiError("connector.connect_failed", "The connector has no registered OAuth client; ask an administrator to reinstall it");
+        }
+        const state = b64url();
+        const verifier = b64url();
+        const redirectUri = callbackUrl(publicUrl);
+        const rec = {
+            orgId,
+            connectorId,
+            accountId,
+            verifier,
+            redirectUri,
+            returnTo: returnTo ?? DEFAULT_RETURN_PATH,
+            binding: sha256(binding),
+            ...(client.issuer !== undefined && { issuer: client.issuer }),
+        };
+        await this.deps.redis.set(stateKey(state), JSON.stringify(rec), "EX", OAUTH_STATE_TTL_SECONDS);
+        const url = new URL(client.authorizationEndpoint);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("client_id", client.clientId);
+        url.searchParams.set("redirect_uri", redirectUri);
+        url.searchParams.set("state", state);
+        url.searchParams.set("code_challenge", sha256(verifier));
+        url.searchParams.set("code_challenge_method", "S256");
+        if (client.scopes && client.scopes.length > 0)
+            url.searchParams.set("scope", client.scopes.join(" "));
+        if (client.resource)
+            url.searchParams.set("resource", client.resource);
+        return { authorizationUrl: url.toString() };
+    }
+    /** 回跳地址：`http.publicUrl` + 站内路径 + 结果参数（未配置 publicUrl 时为相对地址）。 */
+    redirect(path, param) {
+        const base = (this.deps.config().http.publicUrl ?? "").replace(/\/+$/, "");
+        const u = new URL(path, "https://return.invalid");
+        u.searchParams.set(param[0], param[1]);
+        return `${base}${u.pathname}${u.search}${u.hash}`;
+    }
+    fail(code, path = DEFAULT_RETURN_PATH) {
+        return this.redirect(path, ["oauth_error", code]);
+    }
+    /**
+     * 处理授权服务器的回跳，返回 302 的目标。state 先取后删（无论后续成败都不能再用）；浏览器绑定不符 →
+     * `session_mismatch`（把回跳链接转给别人不能把对方的授权连到发起人账号上）；授权服务器报错只映射为原因码。
+     * 成功则在组织行锁内复核发起人仍是成员（`connectors.use`），写个人凭据与审计；连接器还没有工具快照时用这个 token 刷新。
+     */
+    async callback(query, binding) {
+        const state = query.state;
+        if (state === undefined || !STATE_RE.test(state))
+            return this.fail("state_invalid");
+        const raw = await this.deps.redis.getdel(stateKey(state));
+        if (raw === null)
+            return this.fail("state_invalid");
+        const rec = JSON.parse(raw);
+        const back = rec.returnTo;
+        if (binding === undefined || sha256(binding) !== rec.binding) {
+            return this.fail("session_mismatch", back);
+        }
+        // RFC 9207：回跳带 iss 时必须是发起时的授权服务器（防混淆攻击）
+        if (query.iss !== undefined && rec.issuer !== undefined && query.iss !== rec.issuer) {
+            return this.fail("issuer_mismatch", back);
+        }
+        if (query.error !== undefined) {
+            return this.fail(query.error === "access_denied" ? "access_denied" : "provider_error", back);
+        }
+        if (!query.code)
+            return this.fail("provider_error", back);
+        const { orgId, connectorId, accountId } = rec;
+        const app = await this.app(orgId, connectorId);
+        const client = app ? await this.deps.credentials.oauthClient(orgId, connectorId) : null;
+        if (!app || !client || app.auth.type !== "oauth_code") {
+            return this.fail("connector_unavailable", back);
+        }
+        let tokens;
+        try {
+            tokens = await tokenRequest(client, {
+                grant_type: "authorization_code",
+                code: query.code,
+                redirect_uri: rec.redirectUri,
+                code_verifier: rec.verifier,
+                resource: client.resource,
+            }, oauthHttpOptions(this.deps.config()));
+        }
+        catch (e) {
+            this.deps.log.warn("oauth code exchange failed", { orgId, connectorId, err: e });
+            return this.fail("token_exchange_failed", back);
+        }
+        let first;
+        try {
+            first = await this.deps.db.transaction().execute(async (t) => {
+                await lockOrgAndAuthorize(t, orgId, accountId, "connectors.use");
+                const still = await t
+                    .selectFrom("connectors")
+                    .select("id")
+                    .where("id", "=", connectorId)
+                    .where("deleted_at", "is", null)
+                    .forUpdate()
+                    .executeTakeFirst();
+                if (!still)
+                    throw new ApiError("connector.not_found", "Connector not found");
+                await this.deps.credentials.setOAuthTokens(orgId, connectorId, { kind: "user", accountId }, tokens, t);
+                await audit(t, {
+                    actorAccountId: accountId,
+                    orgId,
+                    action: "connector.credential.set",
+                    target: connectorId,
+                    detail: { type: "oauth_code", ownership: "personal" },
+                });
+                const tool = await t
+                    .selectFrom("connector_tools")
+                    .select("name")
+                    .where("connector_id", "=", connectorId)
+                    .limit(1)
+                    .executeTakeFirst();
+                return tool === undefined;
+            });
+        }
+        catch (e) {
+            if (e instanceof ApiError)
+                return this.fail("connector_unavailable", back);
+            throw e;
+        }
+        if (first) {
+            // 首次连接（A16）：刷新失败不影响连接本身，凭据已存好；管理员之后可手动刷新
+            // 最多等 FIRST_CONNECT_REFRESH_WAIT_MS 再回跳（本请求自己的计时器，结束即清除）；超时的刷新在后台继续
+            const refresh = this.deps
+                .onFirstConnect(orgId, connectorId, accountId)
+                .catch((err) => {
+                this.deps.log.warn("oauth first-connect tool refresh failed", {
+                    orgId,
+                    connectorId,
+                    err,
+                });
+            });
+            let timer;
+            await Promise.race([
+                refresh,
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, FIRST_CONNECT_REFRESH_WAIT_MS);
+                }),
+            ]);
+            clearTimeout(timer);
+        }
+        return this.redirect(back, ["connected", connectorId]);
+    }
+}