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

package/dist/tools/connectors.service.js

@@ -0,0 +1,1102 @@
+import { randomUUID } from "node:crypto";
+import { ToolError, } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+import { z } from "zod";
+import { assertItemInstallable } from "../catalog/requests.service.js";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { assertCustomAllowed } from "../identity/settings.js";
+import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
+import { CredentialMissing, isOAuth, } from "./credentials.js";
+import { snapshot, toolIssue, } from "./drift.js";
+import { endpointCredentialIssues, endpointView } from "./endpoint.js";
+import { deriveSlug, isValidSlug, SLUG_RULE, toolKey } from "./naming.js";
+import { checkOAuthUrl, discoverMcp, OAuthSetupError, oauthHttpOptions, pickAuthMethod, registerClient, } from "./oauth/discovery.js";
+import { callbackUrl, publicUrlRequired } from "./oauth/flow.js";
+import { OAuthGrantError, OAuthUnavailable, tokenRequest, } from "./oauth/tokens.js";
+import { policyFromAnnotations } from "./registry.js";
+import { recordToolSpecs } from "./specs.js";
+/** 预览时没给 slug、也推导不出时，拼 key 用的占位 slug。 */
+const PREVIEW_SLUG = "app";
+/** 预览里 inspect 失败的说明里带上的 ToolError 消息最多字符数。 */
+const MAX_INSPECT_DETAIL = 500;
+const notFound = () => new ApiError("connector.not_found", "Connector not found");
+const fail = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** OAuth 连接器在安装时可带的客户端（手填 client / 客户端凭据流）。 */
+const OAuthClientCredential = z.strictObject({
+    clientId: z.string().min(1).max(500),
+    clientSecret: z.string().min(1).max(4000).optional(),
+});
+/** 发现 / 注册 / 取 token 的失败 → 502 `connector.connect_failed`，details 带原因码（向导据 `dcr_unsupported` 改为手填 client）。 */
+function connectFailed(e) {
+    if (e instanceof OAuthSetupError) {
+        return new ApiError("connector.connect_failed", e.message, [
+            { reason: e.reason, message: e.message },
+        ]);
+    }
+    if (e instanceof OAuthGrantError) {
+        const message = `The authorization server rejected the client credentials (${e.error})`;
+        return new ApiError("connector.connect_failed", message, [{ reason: "token_failed", message }]);
+    }
+    const message = e instanceof OAuthUnavailable ? e.message : "Could not complete OAuth setup with the connector";
+    return new ApiError("connector.connect_failed", message, [{ reason: "token_failed", message }]);
+}
+/**
+ * 解析请求里的 OAuth 客户端 `{ clientId, clientSecret? }`（安装时的 `credential`、轮换时的组织凭据）；
+ * 错误只带路径与英文说明，不回显值。
+ */
+function parseOAuthClient(credential, requireSecret, prefix = "credential") {
+    if (credential === undefined || credential === null) {
+        throw fail(prefix, "Provide the OAuth client registered with the authorization server ({ clientId, clientSecret })");
+    }
+    const r = OAuthClientCredential.safeParse(credential);
+    if (!r.success) {
+        throw new ApiError("validation_failed", "Invalid credential", r.error.issues.map((i) => ({
+            path: [prefix, ...i.path.map(String)].filter(Boolean).join("."),
+            message: i.message,
+        })));
+    }
+    if (requireSecret && r.data.clientSecret === undefined) {
+        throw fail(prefix ? `${prefix}.clientSecret` : "clientSecret", "A client secret is required for the client credentials flow");
+    }
+    return r.data;
+}
+/** 无注解 = 既没有 readOnlyHint 也没有 destructiveHint。 */
+const unannotated = (a) => a?.readOnlyHint === undefined && a?.destructiveHint === undefined;
+/**
+ * 连接器（远端服务实例）与其工具快照、凭据。写操作都在组织行锁内复核发起人权限并写审计
+ * （detail 只有凭据类型与归属，没有值）。连接器会话按操作打开、用完即关，不在进程内缓存。
+ */
+export class ConnectorsService {
+    db;
+    registry;
+    host;
+    credentials;
+    config;
+    drift;
+    constructor(db, registry, host, credentials, config, drift) {
+        this.db = db;
+        this.registry = registry;
+        this.host = host;
+        this.credentials = credentials;
+        this.config = config;
+        this.drift = drift;
+    }
+    /**
+     * 校验连接器存在、端点按其 schema 合法、不含凭据样式的头 / query 参数 / URL 用户信息（端点对成员可见，
+     * 凭据须走认证设置）；返回解析后的端点。
+     */
+    parseEndpoint(connector, endpoint) {
+        const c = this.registry.findConnector(connector);
+        if (!c) {
+            const kinds = this.registry.connectorKinds();
+            throw fail("connector", `Unknown connector "${connector}"; installed connectors: ${kinds.length > 0 ? kinds.join(", ") : "none"}`);
+        }
+        const r = c.endpointSchema.safeParse(endpoint);
+        if (!r.success) {
+            throw new ApiError("validation_failed", "Request validation failed", r.error.issues.map((i) => ({
+                path: ["endpoint", ...i.path.map(String)].join("."),
+                message: i.message,
+            })));
+        }
+        const leaks = endpointCredentialIssues(r.data);
+        if (leaks.length > 0)
+            throw new ApiError("validation_failed", "Request validation failed", leaks);
+        return r.data;
+    }
+    async slugTaken(db, orgId, slug) {
+        const row = await db
+            .selectFrom("connectors")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("slug", "=", slug)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+    resolveSlug(input) {
+        if (input.slug !== undefined) {
+            if (!isValidSlug(input.slug))
+                throw fail("slug", SLUG_RULE);
+            return input.slug;
+        }
+        const derived = deriveSlug(input.name);
+        if (!derived) {
+            throw fail("slug", `Cannot derive a slug from the name; provide one. ${SLUG_RULE}`);
+        }
+        return derived;
+    }
+    /**
+     * OAuth 连接器安装前的准备（A16）：授权码流按 `discovery` 取端点（MCP 发现或手填）、按 `client` 动态注册或用请求里
+     * 手填的 client（不做首次 listTools）；客户端凭据流用请求里的 client 取一次组织 token。
+     * 外连失败一律 502 `connector.connect_failed`（details 带原因码），什么都不写。
+     */
+    async prepareOAuth(auth, endpoint, credential, publicUrl) {
+        const http = oauthHttpOptions(this.config());
+        const parseClient = (requireSecret) => parseOAuthClient(credential, requireSecret);
+        const checked = (path, url) => {
+            try {
+                checkOAuthUrl(url, http);
+            }
+            catch (e) {
+                throw fail(path, e instanceof Error ? e.message : "Invalid URL");
+            }
+            return url;
+        };
+        if (auth.type === "oauth_client") {
+            const manual = parseClient(true);
+            const client = {
+                clientId: manual.clientId,
+                ...(manual.clientSecret !== undefined && { clientSecret: manual.clientSecret }),
+                authMethod: auth.tokenAuthMethod ?? "client_secret_basic",
+                tokenEndpoint: checked("auth.tokenUrl", auth.tokenUrl),
+                ...(auth.scopes && { scopes: auth.scopes }),
+            };
+            try {
+                const tokens = await tokenRequest(client, { grant_type: "client_credentials", scope: auth.scopes?.join(" ") }, http);
+                return { client, tokens };
+            }
+            catch (e) {
+                throw connectFailed(e);
+            }
+        }
+        const manual = auth.client === "manual" ? parseClient(false) : undefined;
+        if (!manual && credential !== undefined && credential !== null) {
+            throw fail("credential", "With client dcr the client is registered automatically; omit credential or use client manual");
+        }
+        let meta;
+        let endpoints;
+        if (auth.discovery === "mcp") {
+            const url = isObj(endpoint) && typeof endpoint.url === "string" ? endpoint.url : undefined;
+            if (url === undefined)
+                throw fail("endpoint.url", "MCP OAuth discovery needs an endpoint URL");
+            try {
+                meta = await discoverMcp(url, http);
+            }
+            catch (e) {
+                throw connectFailed(e);
+            }
+            endpoints = {
+                authorizationEndpoint: meta.authorizationEndpoint,
+                tokenEndpoint: meta.tokenEndpoint,
+                resource: meta.resource,
+                ...(meta.scopes && { scopes: meta.scopes }),
+            };
+        }
+        else {
+            endpoints = {
+                authorizationEndpoint: checked("auth.authorizationUrl", auth.authorizationUrl ?? ""),
+                tokenEndpoint: checked("auth.tokenUrl", auth.tokenUrl ?? ""),
+            };
+        }
+        const scopes = auth.scopes ?? endpoints.scopes;
+        if (manual) {
+            return {
+                client: {
+                    clientId: manual.clientId,
+                    ...(manual.clientSecret !== undefined && { clientSecret: manual.clientSecret }),
+                    authMethod: manual.clientSecret === undefined
+                        ? "none"
+                        : (auth.tokenAuthMethod ?? pickAuthMethod(meta?.authMethods, true)),
+                    authorizationEndpoint: endpoints.authorizationEndpoint,
+                    tokenEndpoint: endpoints.tokenEndpoint,
+                    ...(endpoints.resource !== undefined && { resource: endpoints.resource }),
+                    ...(meta && { issuer: meta.issuer }),
+                    ...(scopes && { scopes }),
+                },
+            };
+        }
+        if (!meta)
+            throw fail("auth.client", "Dynamic client registration requires discovery mcp");
+        try {
+            const client = await registerClient({ ...meta, ...(scopes && { scopes }) }, callbackUrl(publicUrl), http, auth.tokenAuthMethod);
+            return { client };
+        }
+        catch (e) {
+            throw connectFailed(e);
+        }
+    }
+    /**
+     * The checks of {@link create} that need neither a connection nor the database: the slug, the
+     * endpoint against the connector's schema, the credential shape, the OAuth client and the OAuth
+     * URL policy. `create` runs them first; a plugin install runs them for every template before it
+     * creates anything, so bad input is a 400 rather than a failed install. Returns what they parsed.
+     */
+    checkCreateInput(actorAccountId, input) {
+        const slug = this.resolveSlug(input);
+        const endpoint = this.parseEndpoint(input.connector, input.endpoint);
+        if (this.host.manifests().some((m) => m.name === slug)) {
+            throw fail("slug", `Slug "${slug}" is the name of an installed plugin; choose another`);
+        }
+        const auth = input.auth;
+        const credential = input.credential ?? undefined;
+        if (!isOAuth(auth)) {
+            if (credential === undefined)
+                return { slug, endpoint };
+            if (auth.type === "none")
+                throw fail("credential", "Auth type none takes no credential");
+            const owner = auth.ownership === "org" ? { kind: "org" } : { kind: "user", accountId: actorAccountId };
+            this.credentials.validate(auth, owner, credential);
+            return { slug, endpoint, owner, secret: credential };
+        }
+        if (!this.config().http.publicUrl)
+            throw publicUrlRequired();
+        const http = oauthHttpOptions(this.config());
+        const checked = (path, url) => {
+            try {
+                checkOAuthUrl(url, http);
+            }
+            catch (e) {
+                throw fail(path, e instanceof Error ? e.message : "Invalid URL");
+            }
+        };
+        if (auth.type === "oauth_client") {
+            parseOAuthClient(credential, true);
+            checked("auth.tokenUrl", auth.tokenUrl);
+            return { slug, endpoint };
+        }
+        if (auth.client === "manual")
+            parseOAuthClient(credential, false);
+        else if (credential !== undefined) {
+            throw fail("credential", "With client dcr the client is registered automatically; omit credential or use client manual");
+        }
+        if (auth.discovery === "mcp") {
+            if (!isObj(endpoint) || typeof endpoint.url !== "string") {
+                throw fail("endpoint.url", "MCP OAuth discovery needs an endpoint URL");
+            }
+            return { slug, endpoint };
+        }
+        checked("auth.authorizationUrl", auth.authorizationUrl ?? "");
+        checked("auth.tokenUrl", auth.tokenUrl ?? "");
+        if (auth.client !== "manual") {
+            throw fail("auth.client", "Dynamic client registration requires discovery mcp");
+        }
+        return { slug, endpoint };
+    }
+    /**
+     * 安装连接器（A4）：校验 → 用请求里的凭据（尚未落库）连接并 listTools → 一个事务内写连接器、工具快照、
+     * 凭据与审计。连接失败时什么都不写。组织凭据型连接器的 `credential` 是组织凭据，个人型是创建者自己的。
+     * OAuth（A16，要求 `http.publicUrl`）：授权码连接器不做首次 listTools（首个成员连接后刷新），只存客户端；
+     * 客户端凭据连接器用安装时取到的组织 token listTools，存客户端与 token。
+     */
+    async create(orgId, actorAccountId, input, actorTokenId) {
+        // 自建被禁止时先拒绝（事务里再复核一次）：不该为此触发外连
+        if (!input.template)
+            await assertCustomAllowed(this.db, "customConnectors");
+        const { slug, endpoint, owner, secret } = this.checkCreateInput(actorAccountId, input);
+        const id = randomUUID();
+        const auth = input.auth;
+        const publicUrl = this.config().http.publicUrl;
+        // 先做不需要连接的检查：冲突的 slug 不该触发一次外连
+        if (await this.slugTaken(this.db, orgId, slug)) {
+            throw new ApiError("connector.slug_taken", "Connector slug is already taken");
+        }
+        const oauth = isOAuth(auth)
+            ? await this.prepareOAuth(auth, endpoint, input.credential, publicUrl)
+            : undefined;
+        let rows = [];
+        let issues = [];
+        if (auth.type !== "oauth_code") {
+            const listed = await this.drift.listTools(input.connector, endpoint, async () => {
+                if (auth.type === "none")
+                    return { headers: {} };
+                if (oauth?.tokens) {
+                    return this.credentials.injectionFor(id, auth, { token: oauth.tokens.access_token });
+                }
+                if (!secret)
+                    throw new CredentialMissing(id, auth.ownership);
+                return this.credentials.injectionFor(id, auth, secret);
+            }, { orgId, slug });
+            ({ rows, issues } = snapshot(slug, listed.specs, listed.resources));
+        }
+        return this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "connectors.manage");
+            if (input.template) {
+                await assertItemInstallable(t, orgId, input.template.itemId, input.template.approvedBy ?? input.template.itemId);
+            }
+            else
+                await assertCustomAllowed(t, "customConnectors");
+            if (await this.slugTaken(t, orgId, slug)) {
+                throw new ApiError("connector.slug_taken", "Connector slug is already taken");
+            }
+            await t
+                .insertInto("connectors")
+                .values({
+                id,
+                org_id: orgId,
+                slug,
+                name: input.name,
+                connector: input.connector,
+                endpoint: JSON.stringify(endpoint),
+                auth: JSON.stringify(auth),
+                created_by: actorAccountId,
+                catalog_item_id: input.template?.itemId ?? null,
+                catalog_version: input.template?.version ?? null,
+                // 授权码连接器安装时没有快照：模板的默认策略留到首个快照时应用
+                template_tool_policies: input.template?.defaultToolPolicies
+                    ? JSON.stringify(input.template.defaultToolPolicies)
+                    : null,
+                // 授权码连接器安装时不拍快照（A16）：留空，首个快照按安装处理
+                ...(auth.type !== "oauth_code" && { tools_synced_at: sql `now()` }),
+            })
+                .execute();
+            await this.insertTools(t, id, rows, input.template?.defaultToolPolicies);
+            if (secret && owner)
+                await this.credentials.setStatic(orgId, id, auth, owner, secret, t);
+            if (oauth) {
+                await this.credentials.setOAuthClient(orgId, id, oauth.client, t);
+                if (oauth.tokens) {
+                    await this.credentials.setOAuthTokens(orgId, id, { kind: "org" }, oauth.tokens, t);
+                }
+            }
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "connector.created",
+                target: id,
+                detail: {
+                    slug,
+                    connector: input.connector,
+                    auth: { type: auth.type, ...(auth.type !== "none" && { ownership: auth.ownership }) },
+                    tools: rows.length,
+                    credentialProvided: secret !== undefined || oauth !== undefined,
+                    ...(input.template && {
+                        catalog: {
+                            itemId: input.template.itemId,
+                            version: input.template.version,
+                            ...(input.template.templateId !== undefined && {
+                                templateId: input.template.templateId,
+                            }),
+                        },
+                    }),
+                },
+            });
+            return { connector: await this.detail(t, orgId, id, actorAccountId), issues };
+        });
+    }
+    /**
+     * Checks a template update before anything is written (an org plugin upgrade): the endpoint
+     * against the connector's schema, and with `resetCredentials` the new credential's shape, or for
+     * OAuth the client setup (discovery, dynamic registration or the client credentials token; an
+     * outbound failure -> 502 `connector.connect_failed`). Writes nothing.
+     */
+    async prepareTemplateUpdate(actorAccountId, connector, input) {
+        const endpoint = this.parseEndpoint(connector, input.endpoint);
+        const out = { input, endpoint };
+        if (!input.resetCredentials)
+            return out;
+        const auth = input.auth;
+        const credential = input.credential ?? undefined;
+        if (!isOAuth(auth)) {
+            if (credential === undefined)
+                return out;
+            if (auth.type === "none")
+                throw fail("credential", "Auth type none takes no credential");
+            const owner = auth.ownership === "org" ? { kind: "org" } : { kind: "user", accountId: actorAccountId };
+            this.credentials.validate(auth, owner, credential);
+            return { ...out, owner, secret: credential };
+        }
+        const publicUrl = this.config().http.publicUrl;
+        if (!publicUrl)
+            throw publicUrlRequired();
+        return { ...out, oauth: await this.prepareOAuth(auth, endpoint, credential, publicUrl) };
+    }
+    /**
+     * Applies a prepared template update in the caller's transaction (the caller holds the org row
+     * lock and checked the actor): the endpoint, auth and template version of the connector, the
+     * template's default policies (`template_tool_policies`) and the policies the org did not set
+     * (`policy_source` `template` or `derived`): a tool the new template names takes its policy
+     * (`template`), an unnamed `template` tool returns to the policy derived from its annotations,
+     * unnamed `derived` tools and the org's own (`admin`) stay (spec §10). Tool definitions are untouched (the next refresh takes the new endpoint through drift review). With `resetCredentials` the credentials are replaced.
+     * Audits `connector.template_applied`. Deleted / missing -> `connector.not_found`.
+     */
+    async applyTemplateIn(t, orgId, connectorId, actorAccountId, p, actorTokenId) {
+        await this.row(t, orgId, connectorId, true);
+        const { input } = p;
+        const policies = input.template.defaultToolPolicies;
+        await t
+            .updateTable("connectors")
+            .set({
+            endpoint: JSON.stringify(p.endpoint),
+            auth: JSON.stringify(input.auth),
+            catalog_item_id: input.template.itemId,
+            catalog_version: input.template.version,
+            template_tool_policies: policies ? JSON.stringify(policies) : null,
+            updated_at: sql `now()`,
+        })
+            .where("id", "=", connectorId)
+            .execute();
+        // Tools at a default the org did not set (template or derived): a tool the new template names
+        // takes its policy (`template`); an unnamed `template` one returns to the derived policy;
+        // unnamed derived ones and the org's own (`admin`) stay
+        const atDefault = await t
+            .selectFrom("connector_tools")
+            .select(["name", "spec", "default_policy", "policy_source"])
+            .where("connector_id", "=", connectorId)
+            .where("policy_source", "in", ["template", "derived"])
+            .forUpdate()
+            .execute();
+        const policyChanges = {};
+        for (const tool of atDefault) {
+            const named = policies !== undefined && Object.hasOwn(policies, tool.name);
+            if (!named && tool.policy_source === "derived")
+                continue;
+            const next = named
+                ? policies[tool.name]
+                : policyFromAnnotations(tool.spec.annotations);
+            await t
+                .updateTable("connector_tools")
+                .set({ default_policy: next, policy_source: named ? "template" : "derived" })
+                .where("connector_id", "=", connectorId)
+                .where("name", "=", tool.name)
+                .execute();
+            if (next !== tool.default_policy) {
+                policyChanges[tool.name] = { from: tool.default_policy, to: next };
+            }
+        }
+        if (input.resetCredentials) {
+            await this.credentials.clearConnector(orgId, connectorId, t);
+            if (p.secret && p.owner) {
+                await this.credentials.setStatic(orgId, connectorId, input.auth, p.owner, p.secret, t);
+            }
+            if (p.oauth) {
+                await this.credentials.setOAuthClient(orgId, connectorId, p.oauth.client, t);
+                if (p.oauth.tokens) {
+                    await this.credentials.setOAuthTokens(orgId, connectorId, { kind: "org" }, p.oauth.tokens, t);
+                }
+            }
+        }
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "connector.template_applied",
+            target: connectorId,
+            detail: {
+                catalog: {
+                    itemId: input.template.itemId,
+                    version: input.template.version,
+                    ...(input.template.templateId !== undefined && {
+                        templateId: input.template.templateId,
+                    }),
+                },
+                auth: {
+                    type: input.auth.type,
+                    ...(input.auth.type !== "none" && { ownership: input.auth.ownership }),
+                },
+                credentialsReset: input.resetCredentials,
+                credentialProvided: p.secret !== undefined || p.oauth !== undefined,
+                policies: policyChanges,
+            },
+        });
+    }
+    /**
+     * Previews a connector (Ruling A20, for the install wizard): after checking the connector, the
+     * endpoint (credential pattern check included) and the credential shape, reads the endpoint
+     * description with `connector.inspect` (auth hints, operations), and when it can authenticate
+     * (static credentials / a token from the client credentials flow) or auth is none, also lists the
+     * tools, builds keys from the slug and derives default policies and issues. Writes nothing (no
+     * rows, no audit); the OAuth authorization code flow lists no tools (no dynamic registration).
+     * Any outbound failure is 502 `connector.connect_failed`, the message holding only the
+     * connector's English explanation (redacted by the injected credentials) or the error class name.
+     * `customConnectors: deny` -> `catalog.custom_disabled`.
+     */
+    async preview(orgId, input) {
+        // 部署禁止组织自建连接器时也不替组织去连任意端点（目录安装不走预览）
+        await assertCustomAllowed(this.db, "customConnectors");
+        const endpoint = this.parseEndpoint(input.connector, input.endpoint);
+        const connector = this.registry.findConnector(input.connector);
+        if (!connector)
+            throw fail("connector", `Unknown connector "${input.connector}"`);
+        let slug = PREVIEW_SLUG;
+        if (input.slug !== undefined) {
+            if (!isValidSlug(input.slug))
+                throw fail("slug", SLUG_RULE);
+            slug = input.slug;
+        }
+        else if (input.name !== undefined) {
+            slug = deriveSlug(input.name) ?? PREVIEW_SLUG;
+        }
+        // 先校验凭据形状，再做任何外连
+        const auth = input.auth;
+        const credential = input.credential ?? undefined;
+        let inject;
+        let oauthClient = false;
+        if (auth === undefined) {
+            if (credential !== undefined && credential !== null) {
+                throw fail("credential", "Provide auth together with credential");
+            }
+        }
+        else if (auth.type === "none") {
+            if (credential !== undefined && credential !== null) {
+                throw fail("credential", "Auth type none takes no credential");
+            }
+            inject = async () => ({ headers: {} });
+        }
+        else if (!isOAuth(auth)) {
+            if (credential !== undefined && credential !== null) {
+                // 预览按「安装者自己的凭据」校验归属：组织型是组织凭据，个人型是自己的
+                const owner = auth.ownership === "org" ? { kind: "org" } : { kind: "user", accountId: "preview" };
+                this.credentials.validate(auth, owner, credential);
+                const secret = credential;
+                inject = async () => this.credentials.injectionFor("preview", auth, secret);
+            }
+        }
+        else if (auth.type === "oauth_client" && credential !== undefined && credential !== null) {
+            oauthClient = true;
+        }
+        const timeoutMs = this.config().tools.timeoutMs;
+        let inspection;
+        if (connector.inspect) {
+            try {
+                inspection = await connector.inspect({ endpoint, signal: AbortSignal.timeout(timeoutMs) });
+            }
+            catch (e) {
+                const message = e instanceof ToolError
+                    ? `Could not read the connector description: ${e.message.slice(0, MAX_INSPECT_DETAIL)}`
+                    : `Could not read the connector description (${e instanceof Error ? e.name : "Error"})`;
+                throw new ApiError("connector.connect_failed", message);
+            }
+        }
+        if (oauthClient && auth?.type === "oauth_client") {
+            const oauth = await this.prepareOAuth(auth, endpoint, credential, this.config().http.publicUrl ?? "");
+            const token = oauth.tokens?.access_token;
+            if (token)
+                inject = async () => this.credentials.injectionFor("preview", auth, { token });
+        }
+        let tools = null;
+        let issues = [];
+        if (inject) {
+            const listed = await this.drift.listTools(input.connector, endpoint, inject, {
+                orgId,
+                preview: true,
+            });
+            const snap = snapshot(slug, listed.specs, listed.resources);
+            issues = snap.issues;
+            tools = snap.rows.map((r) => ({
+                name: r.name,
+                key: toolKey(slug, r.name),
+                description: r.spec.description,
+                inputSchema: r.spec.inputSchema,
+                annotations: r.spec.annotations ?? null,
+                defaultPolicy: policyFromAnnotations(r.spec.annotations),
+                issue: r.issue,
+                source: r.source,
+            }));
+        }
+        return {
+            tools,
+            issues,
+            authHints: inspection?.authHints ?? [],
+            ...(inspection?.operations !== undefined && { operations: inspection.operations }),
+        };
+    }
+    async insertTools(t, connectorId, rows, templatePolicies) {
+        if (rows.length === 0)
+            return;
+        await recordToolSpecs(t, rows);
+        const fromTemplate = (name) => templatePolicies && Object.hasOwn(templatePolicies, name)
+            ? templatePolicies[name]
+            : undefined;
+        await t
+            .insertInto("connector_tools")
+            .values(rows.map((r) => ({
+            connector_id: connectorId,
+            name: r.name,
+            spec: JSON.stringify(r.spec),
+            spec_hash: r.specHash,
+            status: r.issue ? "disabled" : "enabled",
+            default_policy: fromTemplate(r.name) ?? policyFromAnnotations(r.spec.annotations),
+            ...(fromTemplate(r.name) !== undefined && { policy_source: "template" }),
+            source: r.source,
+            // 安装即复核
+            ...(!r.issue && { reviewed_at: sql `now()` }),
+        })))
+            .execute();
+    }
+    /** 读本组织未删除的连接器行；不存在 → `connector.not_found`。`lock` 时 FOR UPDATE。 */
+    async row(db, orgId, connectorId, lock = false) {
+        let q = db
+            .selectFrom("connectors")
+            .selectAll()
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null);
+        if (lock)
+            q = q.forUpdate();
+        const r = await q.executeTakeFirst();
+        if (!r)
+            throw notFound();
+        return r;
+    }
+    summary(r) {
+        return {
+            id: r.id,
+            slug: r.slug,
+            name: r.name,
+            connector: r.connector,
+            // 大段文本（如 OpenAPI 文档）不回显全文，见 endpoint.ts
+            endpoint: endpointView(r.endpoint),
+            auth: r.auth,
+            status: r.status,
+            createdBy: r.created_by,
+            createdAt: r.created_at,
+            updatedAt: r.updated_at,
+        };
+    }
+    async detail(db, orgId, connectorId, viewerAccountId) {
+        const r = await this.row(db, orgId, connectorId);
+        const tools = await db
+            .selectFrom("connector_tools")
+            .select([
+            "name",
+            "spec",
+            "spec_hash",
+            "status",
+            "default_policy",
+            "source",
+            "policy_source",
+            "missing_since",
+            "reviewed_at",
+            "pending_spec",
+            "pending_spec_hash",
+            "pending_source",
+        ])
+            .where("connector_id", "=", connectorId)
+            .orderBy("name")
+            .execute();
+        const s = this.summary(r);
+        const auth = s.auth;
+        const status = await this.credentials.status(orgId, connectorId, auth, viewerAccountId, db === this.db ? undefined : db);
+        return {
+            ...s,
+            tools: tools.map((t) => {
+                const spec = t.spec;
+                const next = t.pending_spec;
+                return {
+                    name: t.name,
+                    key: toolKey(r.slug, t.name),
+                    description: spec.description,
+                    inputSchema: spec.inputSchema,
+                    annotations: spec.annotations ?? null,
+                    connectorData: spec.connectorData ?? null,
+                    status: t.status,
+                    defaultPolicy: t.default_policy,
+                    specHash: t.spec_hash,
+                    issue: toolIssue(r.slug, next ?? spec),
+                    source: t.source,
+                    policySource: t.policy_source,
+                    missing: t.missing_since !== null,
+                    reviewedAt: t.reviewed_at,
+                    pending: next && t.pending_spec_hash !== null
+                        ? {
+                            description: next.description,
+                            inputSchema: next.inputSchema,
+                            annotations: next.annotations ?? null,
+                            connectorData: next.connectorData ?? null,
+                            specHash: t.pending_spec_hash,
+                            source: t.pending_source ?? t.source,
+                        }
+                        : null,
+                };
+            }),
+            credential: { ownership: auth.type === "none" ? null : auth.ownership, status },
+        };
+    }
+    /** 本组织未删除的连接器（按创建时间）。 */
+    async list(orgId) {
+        const rows = await this.db
+            .selectFrom("connectors")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .orderBy("created_at")
+            .orderBy("id")
+            .execute();
+        return rows.map((r) => this.summary(r));
+    }
+    async get(orgId, connectorId, viewerAccountId) {
+        return this.detail(this.db, orgId, connectorId, viewerAccountId);
+    }
+    /** 改名、启停连接器、工具启停与默认策略、批量把无注解工具改为 allow（`connectors.manage`）。 */
+    async update(orgId, connectorId, actorAccountId, patch, actorTokenId) {
+        return this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "connectors.manage");
+            const app = await this.row(t, orgId, connectorId, true);
+            const current = await t
+                .selectFrom("connector_tools")
+                .select([
+                "name",
+                "spec",
+                "status",
+                "default_policy",
+                "missing_since",
+                "pending_spec_hash",
+                "reviewed_at",
+            ])
+                .where("connector_id", "=", connectorId)
+                .forUpdate()
+                .execute();
+            const byName = new Map(current.map((c) => [c.name, c]));
+            const toolChanges = Object.entries(patch.tools ?? {});
+            const problems = [];
+            for (const [name, change] of toolChanges) {
+                const c = byName.get(name);
+                if (!c) {
+                    problems.push({ path: `tools.${name}`, message: "No such tool in this connector" });
+                    continue;
+                }
+                if (change.status === "enabled") {
+                    const path = `tools.${name}.status`;
+                    // 待复核（新增或定义变了）的工具只能经复核接口启用：这里启用会绕过复核、或把旧定义暴露给模型
+                    if (c.status === "pending_review" || c.pending_spec_hash !== null) {
+                        problems.push({
+                            path,
+                            message: `Tool is pending review; approve it with POST /connectors/${connectorId}/tools/${name}/review`,
+                        });
+                        continue;
+                    }
+                    if (c.missing_since !== null) {
+                        problems.push({ path, message: "The connector no longer provides this tool" });
+                        continue;
+                    }
+                    // 从未复核过的工具（如被拒绝的新工具）：启用等于跳过复核，只能经复核接口批准
+                    if (c.reviewed_at === null) {
+                        problems.push({
+                            path,
+                            message: `Tool has never been reviewed; approve it with POST /connectors/${connectorId}/tools/${name}/review`,
+                        });
+                        continue;
+                    }
+                    const issue = toolIssue(app.slug, c.spec);
+                    if (issue)
+                        problems.push({ path, message: issue });
+                }
+            }
+            if (problems.length > 0) {
+                throw new ApiError("validation_failed", "Request validation failed", problems);
+            }
+            if (patch.name !== undefined || patch.status !== undefined) {
+                await t
+                    .updateTable("connectors")
+                    .set({
+                    ...(patch.name !== undefined && { name: patch.name }),
+                    ...(patch.status !== undefined && { status: patch.status }),
+                    updated_at: sql `now()`,
+                })
+                    .where("id", "=", connectorId)
+                    .execute();
+            }
+            const allowed = [];
+            if (patch.allowUnannotated) {
+                for (const c of current) {
+                    const explicit = patch.tools?.[c.name]?.defaultPolicy !== undefined;
+                    if (!explicit &&
+                        c.default_policy === "ask" &&
+                        unannotated(c.spec.annotations)) {
+                        allowed.push(c.name);
+                    }
+                }
+                if (allowed.length > 0) {
+                    await t
+                        .updateTable("connector_tools")
+                        .set({ default_policy: "allow", policy_source: "admin" })
+                        .where("connector_id", "=", connectorId)
+                        .where("name", "in", allowed)
+                        .execute();
+                }
+            }
+            for (const [name, change] of toolChanges) {
+                if (change.status === undefined && change.defaultPolicy === undefined)
+                    continue;
+                await t
+                    .updateTable("connector_tools")
+                    .set({
+                    ...(change.status !== undefined && { status: change.status }),
+                    ...(change.defaultPolicy !== undefined && {
+                        default_policy: change.defaultPolicy,
+                        policy_source: "admin",
+                    }),
+                })
+                    .where("connector_id", "=", connectorId)
+                    .where("name", "=", name)
+                    .execute();
+            }
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "connector.updated",
+                target: connectorId,
+                detail: {
+                    ...(patch.name !== undefined && { name: { from: app.name, to: patch.name } }),
+                    ...(patch.status !== undefined && { status: { from: app.status, to: patch.status } }),
+                    ...(toolChanges.length > 0 && { tools: Object.fromEntries(toolChanges) }),
+                    ...(allowed.length > 0 && { allowedUnannotated: allowed }),
+                },
+            });
+            return this.detail(t, orgId, connectorId, actorAccountId);
+        });
+    }
+    /** 软删除，并删除该连接器的全部凭据（`connectors.manage`）。 */
+    async remove(orgId, connectorId, actorAccountId, actorTokenId) {
+        await this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "connectors.manage");
+            await this.removeIn(t, orgId, connectorId, actorAccountId, actorTokenId);
+        });
+    }
+    /**
+     * 在调用方事务里软删除连接器（调用方已锁组织行并按需复核角色；应用安装的回滚与卸载用）：删全部凭据与授权，
+     * 审计 `connector.deleted`（`reason` 并进 detail）。已删除 / 不存在 → `connector.not_found`。
+     */
+    async removeIn(t, orgId, connectorId, actorAccountId, actorTokenId, reason) {
+        const app = await this.row(t, orgId, connectorId, true);
+        await t
+            .updateTable("connectors")
+            .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
+            .where("id", "=", connectorId)
+            .execute();
+        await this.credentials.clearConnector(orgId, connectorId, t);
+        // 授权绑定连接器 id（软删除不触发外键级联）：一并删掉，不留给任何后来的连接器
+        await t.deleteFrom("tool_grants").where("connector_id", "=", connectorId).execute();
+        await t
+            .deleteFrom("conversation_tool_grants")
+            .where("connector_id", "=", connectorId)
+            .execute();
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "connector.deleted",
+            target: connectorId,
+            detail: { slug: app.slug, ...(reason !== undefined && { reason }) },
+        });
+    }
+    /**
+     * 重新 listTools 并按漂移检测的规则比对写入（见 drift.ts）：新增 / 定义变化的工具待复核（旧定义保留供对比），
+     * 消失的工具停用；连接器从未拍过快照时首个快照直接启用。
+     * 组织凭据型连接器用组织凭据，个人型用发起人自己的凭据（缺 → `credential.missing`）。OAuth 连接器收到 401 时
+     * 在刷新锁内刷新 token 后重试一次。`trigger: "first_connect"`：OAuth 授权码连接器首个成员连接后由连接流程调用
+     * （A16），只要求 `connectors.use`。审计 `connector.tools_refreshed`（变化的工具名，不含定义）。
+     */
+    async refresh(orgId, connectorId, actorAccountId, actorTokenId, opts = {}) {
+        const app = await this.row(this.db, orgId, connectorId);
+        const auth = app.auth;
+        const { specs, resources } = await this.drift.listTools(app.connector, app.endpoint, () => this.credentials.injection(orgId, connectorId, auth, actorAccountId), { orgId, connectorId }, (last) => this.credentials.onUnauthorized(orgId, connectorId, auth, actorAccountId, last));
+        const { rows, issues } = snapshot(app.slug, specs, resources);
+        return this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, opts.trigger === "first_connect" ? "connectors.use" : "connectors.manage");
+            const locked = await this.row(t, orgId, connectorId, true);
+            const changes = await this.drift.apply(t, locked, rows);
+            // 首个快照（授权码连接器首个成员连接后）：按目录模板的 defaultToolPolicies 设默认策略（policy_source 'template'）
+            const templatePolicies = locked.template_tool_policies;
+            if (locked.tools_synced_at === null && templatePolicies) {
+                for (const [name, policy] of Object.entries(templatePolicies)) {
+                    await t
+                        .updateTable("connector_tools")
+                        .set({ default_policy: policy, policy_source: "template" })
+                        .where("connector_id", "=", connectorId)
+                        .where("name", "=", name)
+                        .where("policy_source", "=", "derived")
+                        .execute();
+                }
+            }
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "connector.tools_refreshed",
+                target: connectorId,
+                detail: { ...changes, ...(opts.trigger && { trigger: opts.trigger }) },
+            });
+            return {
+                connector: await this.detail(t, orgId, connectorId, actorAccountId),
+                issues,
+                changes,
+            };
+        });
+    }
+    /**
+     * 复核一个待复核的工具（`connectors.manage`，spec 7.3）。`approve`：采用待复核的新定义（若有）并启用，
+     * `reviewed_at` 记为现在；默认策略按新定义的注解重新推导，除非管理员设过（`policy_source = admin`）且来源没变。
+     * `reject`：停用，丢弃待复核的新定义、保留旧定义；从未复核过的工具被拒后 `reviewed_at` 仍为空（仍可再批准）。
+     * 工具不存在 → 404 `connector.tool_not_found`；不可复核（已复核且无待复核定义，或已消失）→ 409 `connector.tool_not_pending`；新定义不合规（如 key 不合法）不能通过 → `validation_failed`。
+     * 采用新定义即换了指纹：旧的「以后都允许」/「本会话都允许」授权按指纹比对自然失效（D8）。审计 `connector.tool_reviewed`。
+     */
+    async reviewTool(orgId, connectorId, name, action, actorAccountId, actorTokenId) {
+        return this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "connectors.manage");
+            const app = await this.row(t, orgId, connectorId, true);
+            const tool = await t
+                .selectFrom("connector_tools")
+                .select([
+                "status",
+                "source",
+                "spec",
+                "policy_source",
+                "pending_spec",
+                "pending_spec_hash",
+                "pending_source",
+                "reviewed_at",
+                "missing_since",
+            ])
+                .where("connector_id", "=", connectorId)
+                .where("name", "=", name)
+                .forUpdate()
+                .executeTakeFirst();
+            if (!tool)
+                throw new ApiError("connector.tool_not_found", "Tool not found in this connector");
+            // 可复核：待复核、有待复核的新定义，或从未复核过（如被拒绝的新工具，仍可再批准）；已消失的不可复核
+            const reviewable = tool.status === "pending_review" ||
+                tool.pending_spec_hash !== null ||
+                tool.reviewed_at === null;
+            if (!reviewable || tool.missing_since !== null) {
+                throw new ApiError("connector.tool_not_pending", "Tool is not pending review");
+            }
+            const next = (tool.pending_spec ?? tool.spec);
+            const nextSource = tool.pending_source ?? tool.source;
+            if (action === "approve") {
+                const issue = toolIssue(app.slug, next);
+                if (issue)
+                    throw fail("action", issue);
+            }
+            const rederive = tool.policy_source === "derived" || nextSource !== tool.source;
+            await t
+                .updateTable("connector_tools")
+                .set({
+                ...(action === "approve"
+                    ? {
+                        status: "enabled",
+                        ...(tool.pending_spec_hash !== null && {
+                            spec: JSON.stringify(next),
+                            spec_hash: tool.pending_spec_hash,
+                            source: nextSource,
+                        }),
+                        ...(rederive && {
+                            default_policy: policyFromAnnotations(next.annotations),
+                            policy_source: "derived",
+                        }),
+                    }
+                    : { status: "disabled" }),
+                pending_spec: null,
+                pending_spec_hash: null,
+                pending_source: null,
+                // 拒绝从未复核过的工具不算「复核通过过」：reviewed_at 保持为空（之后不能经 PATCH 启用）
+                ...((action === "approve" || tool.reviewed_at !== null) && {
+                    reviewed_at: sql `now()`,
+                }),
+            })
+                .where("connector_id", "=", connectorId)
+                .where("name", "=", name)
+                .execute();
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "connector.tool_reviewed",
+                target: connectorId,
+                detail: { tool: name, action },
+            });
+            return this.detail(t, orgId, connectorId, actorAccountId);
+        });
+    }
+    /**
+     * 写凭据（组织凭据：`connectors.manage`；个人凭据：`connectors.use`，只写发起人自己的那一条）。
+     * 形状与归属不符 → `validation_failed`。审计只记类型与归属。
+     */
+    async setCredential(orgId, connectorId, actorAccountId, ownership, value, actorTokenId) {
+        if (ownership === "org") {
+            const app = await this.row(this.db, orgId, connectorId);
+            const auth = app.auth;
+            if (isOAuth(auth)) {
+                await this.rotateOAuthClient(orgId, connectorId, actorAccountId, auth, value, actorTokenId);
+                return;
+            }
+        }
+        await this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, ownership === "org" ? "connectors.manage" : "connectors.use");
+            const app = await this.row(t, orgId, connectorId);
+            const auth = app.auth;
+            const owner = ownership === "org" ? { kind: "org" } : { kind: "user", accountId: actorAccountId };
+            this.credentials.validate(auth, owner, value);
+            await this.credentials.setStatic(orgId, connectorId, auth, owner, value, t);
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "connector.credential.set",
+                target: connectorId,
+                detail: { type: auth.type, ownership },
+            });
+        });
+    }
+    /**
+     * 轮换 OAuth 客户端（Ruling A18，组织凭据接口，`connectors.manage`）：值为 `{ clientId, clientSecret }`。
+     * 客户端凭据连接器先用新客户端取一次 token 验证（失败 → 502 `connector.connect_failed`，什么都不改），再替换客户端并以
+     * 新 token 替换缓存的组织 token；授权码连接器只限手填 client，只替换客户端（成员的 token 保留，之后刷新若得到
+     * invalid_client 会作废）。审计只记类型与归属。
+     */
+    async rotateOAuthClient(orgId, connectorId, actorAccountId, auth, value, actorTokenId) {
+        if (auth.type === "oauth_code" && auth.client !== "manual") {
+            throw fail("auth.client", "The OAuth client of this connector was registered automatically and cannot be replaced");
+        }
+        const next = parseOAuthClient(value, auth.type === "oauth_client", "");
+        const current = await this.credentials.oauthClient(orgId, connectorId);
+        if (!current) {
+            throw new ApiError("connector.connect_failed", "The connector has no registered OAuth client; reinstall it");
+        }
+        const client = { ...current, clientId: next.clientId };
+        delete client.clientSecret;
+        if (next.clientSecret !== undefined) {
+            client.clientSecret = next.clientSecret;
+            client.authMethod =
+                auth.tokenAuthMethod ??
+                    (current.authMethod === "none" ? "client_secret_basic" : current.authMethod);
+        }
+        else {
+            client.authMethod = "none";
+        }
+        let tokens;
+        if (auth.type === "oauth_client") {
+            try {
+                tokens = await tokenRequest(client, { grant_type: "client_credentials", scope: (auth.scopes ?? client.scopes)?.join(" ") }, oauthHttpOptions(this.config()));
+            }
+            catch (e) {
+                throw connectFailed(e);
+            }
+        }
+        await this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "connectors.manage");
+            await this.row(t, orgId, connectorId, true);
+            await this.credentials.setOAuthClient(orgId, connectorId, client, t);
+            if (tokens)
+                await this.credentials.setOAuthTokens(orgId, connectorId, { kind: "org" }, tokens, t);
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "connector.credential.set",
+                target: connectorId,
+                detail: { type: auth.type, ownership: "org" },
+            });
+        });
+    }
+    /** 删除发起人自己的个人凭据（`connectors.use`）；本来就没有也成功。 */
+    async clearMyCredential(orgId, connectorId, actorAccountId, actorTokenId) {
+        await this.db.transaction().execute(async (t) => {
+            await lockOrgAndAuthorize(t, orgId, actorAccountId, "connectors.use");
+            const app = await this.row(t, orgId, connectorId);
+            await this.credentials.clear(orgId, connectorId, { kind: "user", accountId: actorAccountId }, t);
+            await audit(t, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "connector.credential.cleared",
+                target: connectorId,
+                detail: { type: app.auth.type, ownership: "personal" },
+            });
+        });
+    }
+}