@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/tools/connectors.service.js

@@ -8,12 +8,14 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { ToolError, } from "@capybara-hq/plugin-sdk";
+import { connectorToolKey, ToolError, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { z } from "zod";
-import { assertItemInstallable } from "../catalog/requests.service.js";
+import { connectorTemplateState } from "../catalog/component-state.js";
+import { assertItemInstallable } from "../catalog/request-rules.js";
 import { ApiError } from "../errors.js";
+import { PluginGuides, } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
 import { assertCustomAllowed } from "../identity/settings.js";
@@ -25,7 +27,7 @@ import { OrgLock } from "../orgs/org-lock.js";
 import { CredentialMissing, Credentials, isOAuth, } from "./credentials.js";
 import { snapshot, ToolDrift, toolIssue, } from "./drift.js";
 import { endpointCredentialIssues, endpointView } from "./endpoint.js";
-import { deriveSlug, isValidSlug, SLUG_RULE, toolKey } from "./naming.js";
+import { deriveSlug, isValidSlug, SLUG_RULE } from "./naming.js";
 import { checkOAuthUrl, discoverMcp, OAuthSetupError, oauthHttpOptions, pickAuthMethod, registerClient, } from "./oauth/discovery.js";
 import { callbackUrl, publicUrlRequired } from "./oauth/flow-paths.js";
 import { OAuthGrantError, OAuthUnavailable, tokenRequest, } from "./oauth/tokens.js";
@@ -92,11 +94,14 @@ let ConnectorsService = class ConnectorsService {
     drift;
     orgLock;
     txHost;
+    guides;
     constructor(kdb, registry, 
     /** Extension manifests (a slug may not take an extension's name). */
     extensions, credentials, config, drift, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock, txHost) {
+    orgLock, txHost, 
+    /** Setup guides of connector templates (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    guides) {
         this.kdb = kdb;
         this.registry = registry;
         this.extensions = extensions;
@@ -105,6 +110,7 @@ let ConnectorsService = class ConnectorsService {
         this.drift = drift;
         this.orgLock = orgLock;
         this.txHost = txHost;
+        this.guides = guides;
     }
     /** The kernel-schema handle of the current context (its transaction, else the pool). */
     get db() {
@@ -142,6 +148,34 @@ let ConnectorsService = class ConnectorsService {
             .executeTakeFirst();
         return row !== undefined;
     }
+    /**
+     * The first free default name and slug ({@link CreateConnectorInput.slugDefault}), read in the
+     * caller's transaction under the org lock.
+     */
+    async freeName(t, orgId, d) {
+        const base = deriveSlug(d.name ?? d.display) ?? deriveSlug(d.display);
+        if (base === null) {
+            throw fail("slug", `Cannot derive a slug from the name; provide one. ${SLUG_RULE}`);
+        }
+        const taken = new Set((await t
+            .selectFrom("connectors")
+            .select("slug")
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .execute()).map((r) => r.slug));
+        for (const m of this.extensions.manifests())
+            taken.add(m.name);
+        for (let n = 1;; n++) {
+            const suffix = n === 1 ? "" : `_${n}`;
+            const slug = `${base.slice(0, 24 - suffix.length).replace(/_+$/, "")}${suffix}`;
+            if (!isValidSlug(slug) || taken.has(slug))
+                continue;
+            const nth = ` ${n}`;
+            const name = d.name ??
+                (n === 1 ? d.display : `${[...d.display].slice(0, 80 - nth.length).join("")}${nth}`);
+            return { name: [...name].slice(0, 80).join(""), slug };
+        }
+    }
     resolveSlug(input) {
         if (input.slug !== undefined) {
             if (!isValidSlug(input.slug))
@@ -181,7 +215,7 @@ let ConnectorsService = class ConnectorsService {
                 ...(auth.scopes && { scopes: auth.scopes }),
             };
             try {
-                const tokens = await tokenRequest(client, { grant_type: "client_credentials", scope: auth.scopes?.join(" ") }, http);
+                const tokens = await tokenRequest(client, { grant_type: "client_credentials", scope: auth.scopes?.join(" ") }, http, { tokenTypes: auth.tokenTypes });
                 return { client, tokens };
             }
             catch (e) {
@@ -253,7 +287,8 @@ let ConnectorsService = class ConnectorsService {
     checkCreateInput(actorAccountId, input) {
         const slug = this.resolveSlug(input);
         const endpoint = this.parseEndpoint(input.connector, input.endpoint);
-        if (this.extensions.manifests().some((m) => m.name === slug)) {
+        // a defaulted slug skips plugin names itself (`freeName`)
+        if (!input.slugDefault && this.extensions.manifests().some((m) => m.name === slug)) {
             throw fail("slug", `Slug "${slug}" is the name of an installed plugin; choose another`);
         }
         const auth = input.auth;
@@ -311,21 +346,21 @@ let ConnectorsService = class ConnectorsService {
         // 自建被禁止时先拒绝（事务里再复核一次）：不该为此触发外连
         if (!input.template)
             await assertCustomAllowed(this.db, "customConnectors");
+        await this.assertKindAvailable(orgId, input.connector);
         const { slug, endpoint, owner, secret } = this.checkCreateInput(actorAccountId, input);
         const id = randomUUID();
         const auth = input.auth;
         const publicUrl = this.config.get().http.publicUrl;
-        // 先做不需要连接的检查：冲突的 slug 不该触发一次外连
-        if (await this.slugTaken(this.db, orgId, slug)) {
+        // 先做不需要连接的检查：冲突的 slug 不该触发一次外连 (a defaulted slug is chosen under the lock)
+        if (!input.slugDefault && (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 = [];
+        let listed;
         if (auth.type !== "oauth_code") {
-            const listed = await this.drift.listTools(input.connector, endpoint, async () => {
+            listed = await this.drift.listTools(input.connector, endpoint, async () => {
                 if (auth.type === "none")
                     return { headers: {} };
                 if (oauth?.tokens) {
@@ -335,8 +370,12 @@ let ConnectorsService = class ConnectorsService {
                     throw new CredentialMissing(id, auth.ownership);
                 return this.credentials.injectionFor(id, auth, secret);
             }, { orgId, slug });
-            ({ rows, issues } = snapshot(slug, listed.specs, listed.resources));
         }
+        // the guide the wizard and 补充配置 showed: the template's current one (spec §11)
+        const tpl = input.template;
+        const guideAck = tpl?.templateId !== undefined
+            ? await this.guides.templateAck(tpl.itemId, tpl.templateId)
+            : null;
         return this.createIn(orgId, actorAccountId, input, actorTokenId, {
             id,
             slug,
@@ -344,13 +383,13 @@ let ConnectorsService = class ConnectorsService {
             owner,
             secret,
             oauth,
-            rows,
-            issues,
+            listed,
+            guideAck,
         });
     }
     /** The org-locked, re-checked insert of {@link create} (the outbound checks ran before). */
     async createIn(orgId, actorAccountId, input, actorTokenId, c) {
-        const { id, slug, endpoint, owner, secret, oauth, rows, issues } = c;
+        const { id, endpoint, owner, secret, oauth } = c;
         const auth = input.auth;
         const t = this.db;
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "connectors.manage");
@@ -359,22 +398,55 @@ let ConnectorsService = class ConnectorsService {
         }
         else
             await assertCustomAllowed(t, "customConnectors");
-        if (await this.slugTaken(t, orgId, slug)) {
+        let slug = c.slug;
+        let name = input.name;
+        if (input.slugDefault)
+            ({ slug, name } = await this.freeName(t, orgId, input.slugDefault));
+        else if (await this.slugTaken(t, orgId, slug)) {
             throw new ApiError("connector.slug_taken", "Connector slug is already taken");
         }
+        // the snapshot's keys name the final slug
+        const { rows, issues } = c.listed === undefined
+            ? { rows: [], issues: [] }
+            : snapshot(slug, c.listed.specs, c.listed.resources);
+        // A connector made from a platform connector template stays linked to it (ruling E2)
+        const tpl = input.template;
+        const platformTemplate = tpl?.templateId !== undefined
+            ? await t
+                .selectFrom("platform_connector_templates")
+                .select("id")
+                .where("catalog_item_id", "=", tpl.itemId)
+                .where("template_id", "=", tpl.templateId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst()
+            : undefined;
+        if (tpl?.mustBeOn) {
+            const state = platformTemplate === undefined
+                ? "absent"
+                : await connectorTemplateState(t, orgId, platformTemplate.id);
+            if (state === "absent") {
+                throw new ApiError("component.not_found", "The connector template does not exist or is not available in this organization");
+            }
+            if (state === "off") {
+                throw new ApiError("component.off", "This connector template is off in this organization; switch it (or its plugin) on first");
+            }
+        }
         await t
             .insertInto("connectors")
             .values({
             id,
             org_id: orgId,
             slug,
-            name: input.name,
+            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,
+            platform_template_id: platformTemplate?.id ?? null,
+            // linked to its template only through the platform component (drift is judged there)
+            guide_ack: platformTemplate !== undefined && c.guideAck !== null ? JSON.stringify(c.guideAck) : null,
             // 授权码连接器安装时没有快照：模板的默认策略留到首个快照时应用
             template_tool_policies: input.template?.defaultToolPolicies
                 ? JSON.stringify(input.template.defaultToolPolicies)
@@ -418,7 +490,7 @@ let ConnectorsService = class ConnectorsService {
         return { connector: await this.detail(t, orgId, id, actorAccountId), issues };
     }
     /**
-     * Checks a template update before anything is written (an org plugin upgrade): the endpoint
+     * Checks a template update before anything is written (the platform plugin update): 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.
@@ -534,6 +606,21 @@ let ConnectorsService = class ConnectorsService {
             },
         });
     }
+    /** Refuses a loaded kind whose extension is not enabled in the org (the same notion as {@link kinds}). */
+    async assertKindAvailable(orgId, kind) {
+        if (!this.registry.findConnector(kind))
+            return; // unknown kinds fail in parseEndpoint
+        if (!(await this.registry.connectorKindAvailable(orgId, kind))) {
+            throw new ApiError("connector.kind_unavailable", `Connector kind "${kind}" is not enabled for this organization; enable its plugin first`);
+        }
+    }
+    /**
+     * The connector kinds the org can create connectors of (the install wizard's protocol step): a
+     * kind is listed when its `connector@1` extension is loaded and enabled in the org.
+     */
+    kinds(orgId) {
+        return this.registry.connectorKindsFor(orgId);
+    }
     /**
      * 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
@@ -548,6 +635,7 @@ let ConnectorsService = class ConnectorsService {
     async preview(orgId, input) {
         // 部署禁止组织自建连接器时也不替组织去连任意端点（目录安装不走预览）
         await assertCustomAllowed(this.db, "customConnectors");
+        await this.assertKindAvailable(orgId, input.connector);
         const endpoint = this.parseEndpoint(input.connector, input.endpoint);
         const connector = this.registry.findConnector(input.connector);
         if (!connector)
@@ -619,7 +707,7 @@ let ConnectorsService = class ConnectorsService {
             issues = snap.issues;
             tools = snap.rows.map((r) => ({
                 name: r.name,
-                key: toolKey(slug, r.name),
+                key: connectorToolKey(slug, r.name),
                 description: r.spec.description,
                 inputSchema: r.spec.inputSchema,
                 annotations: r.spec.annotations ?? null,
@@ -684,6 +772,8 @@ let ConnectorsService = class ConnectorsService {
             endpoint: endpointView(r.endpoint),
             auth: r.auth,
             status: r.status,
+            platformTemplateId: r.platform_template_id ?? null,
+            catalogItemId: r.catalog_item_id ?? null,
             createdBy: r.created_by,
             createdAt: r.created_at,
             updatedAt: r.updated_at,
@@ -720,7 +810,8 @@ let ConnectorsService = class ConnectorsService {
                 const next = t.pending_spec;
                 return {
                     name: t.name,
-                    key: toolKey(r.slug, t.name),
+                    key: connectorToolKey(r.slug, t.name),
+                    title: typeof spec.title === "string" ? spec.title : null,
                     description: spec.description,
                     inputSchema: spec.inputSchema,
                     annotations: spec.annotations ?? null,
@@ -748,7 +839,85 @@ let ConnectorsService = class ConnectorsService {
             credential: { ownership: auth.type === "none" ? null : auth.ownership, status },
         };
     }
-    /** 本组织未删除的连接器（按创建时间）。 */
+    /**
+     * The setup guide fields of the org's connectors (`setupGuide`, `guideDrift`; spec
+     * 2026-11-09-setup-guides-v2-design.md §9.3, §11): resolved through each connector's platform
+     * template to its item's guide for that template; custom connectors get nulls.
+     */
+    async guideStates(org, connectorIds) {
+        if (connectorIds.length === 0)
+            return new Map();
+        const rows = await this.db
+            .selectFrom("connectors as c")
+            .leftJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+            .select(["c.id", "c.guide_ack", "t.catalog_item_id", "t.template_id"])
+            .where("c.org_id", "=", org.orgId)
+            .where("c.id", "in", [...new Set(connectorIds)])
+            .where("c.deleted_at", "is", null)
+            .execute();
+        return this.guides.connectorStates(rows.map((r) => ({
+            id: r.id,
+            itemId: r.catalog_item_id ?? null,
+            templateId: r.template_id ?? null,
+            guideAck: r.guide_ack ?? null,
+        })), org);
+    }
+    /**
+     * 「我已更新应用」 for a connector made from a template: records the template's current guide as
+     * the one it is set up with. `hash` is the admin drift hash of the guide the person was shown;
+     * when the plugin moved on since, 409 `connector.guide_changed` (show the new guide first). A
+     * connector without a template guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
+     */
+    async ackGuide(org, connectorId, hash, actorAccountId, actorTokenId) {
+        const { orgId } = org;
+        const r = await this.db
+            .selectFrom("connectors as c")
+            .leftJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+            .select(["c.id", "t.catalog_item_id", "t.template_id"])
+            .where("c.id", "=", connectorId)
+            .where("c.org_id", "=", orgId)
+            .where("c.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!r)
+            throw notFound();
+        const ack = r.catalog_item_id && r.template_id
+            ? // the guide read's visibility: an item the org's catalog does not show has no guide
+                await this.guides.templateAck(r.catalog_item_id, r.template_id, org)
+            : null;
+        if (ack === null) {
+            throw new ApiError("catalog.guide_not_found", "The connector has no template setup guide");
+        }
+        if (ack.hash !== hash) {
+            throw new ApiError("connector.guide_changed", "The connector template's setup guide changed since it was shown; review the new guide first");
+        }
+        return this.ackIn(orgId, connectorId, ack, actorAccountId, actorTokenId);
+    }
+    /** The row and audit of {@link ackGuide}, in one transaction under the org lock. */
+    async ackIn(orgId, connectorId, ack, actorAccountId, actorTokenId) {
+        const t = this.db;
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "connectors.manage");
+        const updated = await t
+            .updateTable("connectors")
+            .set({ guide_ack: JSON.stringify(ack), updated_at: sql `now()` })
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .returning("id")
+            .executeTakeFirst();
+        if (!updated)
+            throw notFound();
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "connector.guide_confirmed",
+            target: connectorId,
+            detail: { guideId: ack.guideId, version: ack.version },
+        });
+        return this.detail(t, orgId, connectorId, actorAccountId);
+    }
+    /** The org's connectors that are not deleted (by creation time). */
     async list(orgId) {
         const rows = await this.db
             .selectFrom("connectors")
@@ -882,16 +1051,75 @@ let ConnectorsService = class ConnectorsService {
         });
         return this.detail(t, orgId, connectorId, actorAccountId);
     }
+    /**
+     * The org id of a live connector of a live org (the platform paths address a connector by its
+     * global id); else `connector.not_found`.
+     */
+    async liveOrgOf(connectorId) {
+        const r = await this.db
+            .selectFrom("connectors as c")
+            .innerJoin("orgs as o", "o.id", "c.org_id")
+            .select("c.org_id")
+            .where("c.id", "=", connectorId)
+            .where("c.deleted_at", "is", null)
+            .where("o.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!r)
+            throw notFound();
+        return r.org_id;
+    }
+    /**
+     * Disables or enables a connector on the platform's behalf (a super admin who need not be a
+     * member of the org; the caller checks the super admin): org row lock, the status update, audit
+     * `connector.updated` with `via: "platform"`. `auditDetail` (a Platform tool write's
+     * `viaAgent`) is merged into the detail; `via` stays `"platform"`.
+     */
+    async setStatusAsPlatform(connectorId, status, actor, auditDetail) {
+        const t = this.db;
+        const orgId = await this.liveOrgOf(connectorId);
+        await this.orgLock.lock(orgId);
+        const app = await this.row(t, orgId, connectorId, true);
+        await t
+            .updateTable("connectors")
+            .set({ status, updated_at: sql `now()` })
+            .where("id", "=", connectorId)
+            .execute();
+        await audit(t, {
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+            orgId,
+            action: "connector.updated",
+            target: connectorId,
+            detail: { ...auditDetail, status: { from: app.status, to: status }, via: "platform" },
+        });
+    }
+    /**
+     * Deletes a connector on the platform's behalf (see {@link setStatusAsPlatform}): org row lock,
+     * then {@link removeIn} with `via: "platform"` in the audit detail (merged over `auditDetail`,
+     * a Platform tool write's `viaAgent`).
+     */
+    async removeAsPlatform(connectorId, actor, auditDetail) {
+        const orgId = await this.liveOrgOf(connectorId);
+        await this.orgLock.lock(orgId);
+        await this.removeIn(orgId, connectorId, actor.accountId, actor.tokenId, undefined, {
+            ...auditDetail,
+            via: "platform",
+        });
+    }
     /** 软删除，并删除该连接器的全部凭据（`connectors.manage`）。 */
-    async remove(orgId, connectorId, actorAccountId, actorTokenId) {
+    async remove(orgId, connectorId, actorAccountId, actorTokenId, auditDetail) {
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "connectors.manage");
-        await this.removeIn(orgId, connectorId, actorAccountId, actorTokenId);
+        await this.removeIn(orgId, connectorId, actorAccountId, actorTokenId, undefined, auditDetail);
     }
     /**
      * 在调用方事务里软删除连接器（调用方已锁组织行并按需复核角色；应用安装的回滚与卸载用）：删全部凭据与授权，
      * 审计 `connector.deleted`（`reason` 并进 detail）。已删除 / 不存在 → `connector.not_found`。
      */
-    async removeIn(orgId, connectorId, actorAccountId, actorTokenId, reason) {
+    async removeIn(orgId, connectorId, 
+    /** null: the kernel itself (the plugin scope sync uninstalling a plugin). */
+    actorAccountId, actorTokenId, reason, 
+    /** Merged into the audit detail (a write made through the Platform tool). */
+    auditDetail) {
         const t = this.db;
         const app = await this.row(t, orgId, connectorId, true);
         await t
@@ -912,7 +1140,7 @@ let ConnectorsService = class ConnectorsService {
             orgId,
             action: "connector.deleted",
             target: connectorId,
-            detail: { slug: app.slug, ...(reason !== undefined && { reason }) },
+            detail: { slug: app.slug, ...(reason !== undefined && { reason }), ...auditDetail },
         });
     }
     /**
@@ -954,7 +1182,7 @@ let ConnectorsService = class ConnectorsService {
             orgId,
             action: "connector.tools_refreshed",
             target: connectorId,
-            detail: { ...changes, ...(opts.trigger && { trigger: opts.trigger }) },
+            detail: { ...changes, ...(opts.trigger && { trigger: opts.trigger }), ...opts.auditDetail },
         });
         return {
             connector: await this.detail(t, orgId, connectorId, actorAccountId),
@@ -1107,7 +1335,7 @@ let ConnectorsService = class ConnectorsService {
         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.get()));
+                tokens = await tokenRequest(client, { grant_type: "client_credentials", scope: (auth.scopes ?? client.scopes)?.join(" ") }, oauthHttpOptions(this.config.get()), { tokenTypes: auth.tokenTypes });
             }
             catch (e) {
                 throw connectFailed(e);
@@ -1154,9 +1382,18 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], ConnectorsService.prototype, "applyTemplateIn", null);
+__decorate([
+    Transactional()
+], ConnectorsService.prototype, "ackIn", null);
 __decorate([
     Transactional()
 ], ConnectorsService.prototype, "update", null);
+__decorate([
+    Transactional()
+], ConnectorsService.prototype, "setStatusAsPlatform", null);
+__decorate([
+    Transactional()
+], ConnectorsService.prototype, "removeAsPlatform", null);
 __decorate([
     Transactional()
 ], ConnectorsService.prototype, "remove", null);
@@ -1187,6 +1424,7 @@ ConnectorsService = __decorate([
     __param(4, Inject(KernelConfigService)),
     __param(5, Inject(ToolDrift)),
     __param(6, Inject(OrgLock)),
-    __param(7, Inject(TransactionHost))
+    __param(7, Inject(TransactionHost)),
+    __param(8, Inject(PluginGuides))
 ], ConnectorsService);
 export { ConnectorsService };

package/dist/tools/credentials.d.ts

@@ -42,12 +42,15 @@ export type OAuthAuth = {
     client: "dcr" | "manual";
     /** 令牌端点的客户端认证方式（有密钥时），默认 client_secret_basic。 */
     tokenAuthMethod?: "client_secret_basic" | "client_secret_post" | undefined;
+    /** More `token_type` values accepted as bearer tokens (besides Bearer and `user`). */
+    tokenTypes?: string[] | undefined;
 } | {
     type: "oauth_client";
     ownership: "org";
     tokenUrl: string;
     scopes?: string[] | undefined;
     tokenAuthMethod?: "client_secret_basic" | "client_secret_post" | undefined;
+    tokenTypes?: string[] | undefined;
 };
 export type ConnectorAuth = StaticAuth | OAuthAuth;
 export declare const isOAuth: (auth: ConnectorAuth) => auth is OAuthAuth;
@@ -116,6 +119,26 @@ export declare class Credentials {
      * 都会更新写入时间），最多 `limit` 个。漂移检查用它挑个人凭据型连接器的凭据。
      */
     personalHolders(orgId: string, connectorId: string, limit: number): Promise<string[]>;
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a connector's credentials,
+     * the `updated_at` of its OAuth client row, its org credential row and, given `accountId`, that
+     * member's row (ISO), never a value. Reads no secret.
+     */
+    checkRevision(orgId: string, connectorId: string, accountId: string | null): Promise<string>;
+    /**
+     * For setup checks (setup guides v2 §10.8), never refreshing or writing anything: every stored
+     * credential value of a connector (decrypted: the OAuth client secret and DCR registration
+     * token, the org credential, every member's access and refresh tokens or static values) that a
+     * check result is redacted by, with the forms they are sent in (what `injectionSecrets` covers
+     * for a tool call: the Basic header value, its base64 token and decoded `user:pass`, the
+     * `encodeURIComponent` forms; for the client also the `client_secret_basic` header the token
+     * request sends and the raw `id:secret`), and the stored OAuth client id (null without a
+     * client). Never echo the values; a plugin check gets only a manual client's id.
+     */
+    checkMaterial(orgId: string, connectorId: string): Promise<{
+        secrets: string[];
+        clientId: string | null;
+    }>;
     /** 只看与 auth.ownership 对应的那一条凭据是否存在（不解密）；none 恒为 connected。 */
     status(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string): Promise<"connected" | "missing">;
     /** 返回本次请求要注入的头 / 查询参数；缺凭据抛 CredentialMissing。 */

package/dist/tools/credentials.js

@@ -17,7 +17,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { LockService } from "../infra/lock/lock.service.js";
 import { KERNEL_LOGGER, KEYRING, REDIS } from "../infra/tokens.js";
 import { oauthHttpOptions } from "./oauth/discovery.js";
-import { OAuthReconnectRequired, OAuthTokens, } from "./oauth/tokens.js";
+import { basicClientAuth, OAuthReconnectRequired, OAuthTokens, } from "./oauth/tokens.js";
 import { injectionSecrets } from "./redact.js";
 export const isOAuth = (auth) => auth.type === "oauth_code" || auth.type === "oauth_client";
 /** 缺凭据：只带连接器 id 与归属，绝不带值。 */
@@ -239,6 +239,95 @@ let Credentials = class Credentials {
       LIMIT ${limit}`.execute(this.db.db);
         return rows.rows.map((r) => r.account_id);
     }
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a connector's credentials,
+     * the `updated_at` of its OAuth client row, its org credential row and, given `accountId`, that
+     * member's row (ISO), never a value. Reads no secret.
+     */
+    async checkRevision(orgId, connectorId, accountId) {
+        const keys = [clientKey(connectorId), orgKey(connectorId)];
+        if (accountId !== null)
+            keys.push(userKey(connectorId, accountId));
+        const rows = await this.db
+            .selectFrom("secrets")
+            .select(["key", "updated_at"])
+            .where("namespace", "=", NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "in", keys)
+            .execute();
+        const at = new Map(rows.map((r) => [r.key, new Date(r.updated_at).toISOString()]));
+        return keys.map((k) => at.get(k) ?? "-").join("|");
+    }
+    /**
+     * For setup checks (setup guides v2 §10.8), never refreshing or writing anything: every stored
+     * credential value of a connector (decrypted: the OAuth client secret and DCR registration
+     * token, the org credential, every member's access and refresh tokens or static values) that a
+     * check result is redacted by, with the forms they are sent in (what `injectionSecrets` covers
+     * for a tool call: the Basic header value, its base64 token and decoded `user:pass`, the
+     * `encodeURIComponent` forms; for the client also the `client_secret_basic` header the token
+     * request sends and the raw `id:secret`), and the stored OAuth client id (null without a
+     * client). Never echo the values; a plugin check gets only a manual client's id.
+     */
+    async checkMaterial(orgId, connectorId) {
+        const prefix = orgKey(connectorId).slice(0, -"org".length);
+        const rows = await this.db
+            .selectFrom("secrets")
+            .select("key")
+            .where("namespace", "=", NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where(sql `left(key, ${prefix.length})`, "=", prefix)
+            .execute();
+        const secrets = new Set();
+        const push = (...vs) => {
+            for (const v of vs) {
+                if (typeof v !== "string" || v === "")
+                    continue;
+                // the value and the forms an injection carries it in (`Bearer`, query, percent-encoded)
+                for (const s of injectionSecrets({ headers: { a: `Bearer ${v}` }, query: { q: v } })) {
+                    secrets.add(s);
+                }
+            }
+        };
+        const pushBasic = (user, password) => {
+            const header = `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
+            for (const s of injectionSecrets({ headers: { a: header } }))
+                secrets.add(s);
+        };
+        let clientId = null;
+        for (const r of rows) {
+            const v = (await this.readJson(orgId, r.key, connectorId));
+            if (v === null || typeof v !== "object")
+                continue;
+            if (r.key === clientKey(connectorId)) {
+                // the client id is not a secret (a plugin check gets it); the secret and DCR token are
+                if (typeof v.clientId === "string")
+                    clientId = v.clientId;
+                push(v.clientSecret, v.registration?.accessToken);
+                if (typeof v.clientId === "string" && typeof v.clientSecret === "string") {
+                    // as the token request sends it (both parts form-encoded), and as typed
+                    const header = basicClientAuth(v.clientId, v.clientSecret);
+                    for (const s of injectionSecrets({ headers: { a: header } }))
+                        secrets.add(s);
+                    pushBasic(v.clientId, v.clientSecret);
+                }
+            }
+            else if (typeof v.access_token === "string") {
+                push(v.access_token, v.refresh_token);
+            }
+            else {
+                push(v.token, v.password);
+                if (typeof v.username === "string" && typeof v.password === "string") {
+                    pushBasic(v.username, v.password);
+                }
+                if (typeof v.headers === "object" && v.headers !== null) {
+                    const headers = Object.fromEntries(Object.entries(v.headers).filter((e) => typeof e[1] === "string"));
+                    for (const s of injectionSecrets({ headers }))
+                        secrets.add(s);
+                }
+            }
+        }
+        return { secrets: [...secrets], clientId };
+    }
     /** 只看与 auth.ownership 对应的那一条凭据是否存在（不解密）；none 恒为 connected。 */
     async status(orgId, connectorId, auth, accountId) {
         if (auth.type === "none")

package/dist/tools/display-names.d.ts

@@ -0,0 +1,9 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * The display names of plugins, for naming their extensions' tools (`<display name> [<tool>]`,
+ * tool naming spec §7): the live catalog item's `displayName`, else the plugin name in both
+ * languages (a bootstrap or uploaded plugin without a catalog item, or one without a display name).
+ * Display only.
+ */
+export declare function pluginDisplayNames(db: KernelSchemaDb, names: readonly string[]): Promise<Map<string, LocalizedName>>;