@capybara-hq/kernel 0.1.0-rc.12 → 0.1.0-rc.14

package/dist/tools/connectors.controller.d.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
+import type { ConnectionGuideState } from "../extensions/plugin-guides.js";
 import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { ConnectorAccountPolicies, type MemberToolPolicyView } from "./connector-account-policies.js";
-import { CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
+import { ConnectorGuideAckSchema, CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
 import { type ConnectorDetail, type ConnectorPreview, type ConnectorSummary, ConnectorsService, type ToolIssue } from "./connectors.service.js";
 declare const CreateBody: z.ZodObject<{
     name: z.ZodString;
@@ -169,6 +170,14 @@ declare const UpdateBody: z.ZodObject<{
     }, z.core.$strict>>>;
     allowUnannotated: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+/**
+ * A connector as the org's pages show it: with its plugin's icon (`icon`, see `withIcons`), its
+ * template's setup guide and the drift since it was set up (`setupGuide`, `guideDrift`; spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3, §11).
+ */
+export type ConnectorPage<T extends ConnectorSummary = ConnectorDetail> = T & ConnectionGuideState & {
+    icon: string | null;
+};
 /**
  * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
  * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
@@ -185,10 +194,11 @@ export declare class ConnectorsController {
      */
     private withIcons;
     list(org: OrgContext): Promise<{
-        connectors: (ConnectorSummary & {
-            icon: string | null;
-        })[];
+        connectors: ConnectorPage<ConnectorSummary>[];
     }>;
+    /** Adds the icon and the setup guide fields to connector views (one lookup each for all). */
+    private withGuides;
+    private withGuide;
     /**
      * The connector kinds the org can create connectors of, each with the plugin providing it (the
      * install wizard offers only these; an empty list means no connector extension is enabled).
@@ -200,7 +210,7 @@ export declare class ConnectorsController {
         }[];
     }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
         issues: ToolIssue[];
     }>;
     /**
@@ -209,16 +219,14 @@ export declare class ConnectorsController {
      */
     preview(principal: Principal, org: OrgContext, body: z.infer<typeof PreviewBody>): Promise<ConnectorPreview>;
     get(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail & {
-            icon: string | null;
-        };
+        connector: ConnectorPage;
     }>;
     update(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof UpdateBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
     }>;
     remove(principal: Principal, org: OrgContext, connectorId: string): Promise<void>;
     refresh(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
         issues: ToolIssue[];
         changes: {
             added: string[];
@@ -228,7 +236,16 @@ export declare class ConnectorsController {
     }>;
     /** 复核待复核的工具（漂移检测，spec 7.3）：approve 采用新定义并启用，reject 停用并保留旧定义。 */
     review(principal: Principal, org: OrgContext, connectorId: string, name: string, body: z.infer<typeof ReviewBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
+    }>;
+    /**
+     * 「我已更新应用」: the org admin updated the third-party app to the connector template's current
+     * setup guide (`{ hash }` of the guide shown) -> 200 `{ connector }`; 409
+     * `connector.guide_changed` when the guide moved on since, 404 `catalog.guide_not_found` for a
+     * connector without a template guide.
+     */
+    ackGuide(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof ConnectorGuideAckSchema>): Promise<{
+        connector: ConnectorPage;
     }>;
     setOrgCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;
     setMyCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;

package/dist/tools/connectors.controller.js

@@ -17,7 +17,7 @@ import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { can } from "../orgs/roles.js";
 import { ConnectorAccountPolicies, } from "./connector-account-policies.js";
-import { CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
+import { ConnectorGuideAckSchema, CredentialValue, MemberToolPoliciesBody, } from "./connectors.schemas.js";
 import { ConnectorsService, } from "./connectors.service.js";
 import { publicEndpoint } from "./endpoint.js";
 /**
@@ -88,6 +88,8 @@ class ConnectorCredentialBody extends createZodDto(CredentialValue, "ConnectorCr
 }
 class MemberToolPoliciesDto extends createZodDto(MemberToolPoliciesBody, "MemberToolPoliciesBody") {
 }
+class ConnectorGuideAckBody extends createZodDto(ConnectorGuideAckSchema, "ConnectorGuideAckBody") {
+}
 /**
  * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
  * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
@@ -115,8 +117,22 @@ let ConnectorsController = class ConnectorsController {
         }));
     }
     async list(org) {
-        const rows = (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a));
-        return { connectors: await this.withIcons(org, rows) };
+        const list = (await this.connectors.list(org.orgId)).map((a) => forViewer(org, a));
+        return { connectors: await this.withGuides(org, list) };
+    }
+    /** Adds the icon and the setup guide fields to connector views (one lookup each for all). */
+    async withGuides(org, views) {
+        const [withIcons, states] = await Promise.all([
+            this.withIcons(org, views),
+            this.connectors.guideStates(org, views.map((v) => v.id)),
+        ]);
+        return withIcons.map((v) => ({
+            ...v,
+            ...(states.get(v.id) ?? { setupGuide: null, guideDrift: null }),
+        }));
+    }
+    async withGuide(org, view) {
+        return (await this.withGuides(org, [view]))[0];
     }
     /**
      * The connector kinds the org can create connectors of, each with the plugin providing it (the
@@ -127,7 +143,8 @@ let ConnectorsController = class ConnectorsController {
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
-        return this.connectors.create(org.orgId, p.account.id, body, patTokenId(p));
+        const r = await this.connectors.create(org.orgId, p.account.id, body, patTokenId(p));
+        return { ...r, connector: await this.withGuide(org, r.connector) };
     }
     /**
      * 预览（安装向导）：读端点描述（认证提示、操作清单）并在能认证时列出工具，什么都不写。
@@ -139,15 +156,13 @@ let ConnectorsController = class ConnectorsController {
     }
     async get(principal, org, connectorId) {
         const p = requireUser(principal);
-        const c = forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id));
-        const [connector] = await this.withIcons(org, [c]);
-        return { connector: connector };
+        const view = forViewer(org, await this.connectors.get(org.orgId, connectorId, p.account.id));
+        return { connector: await this.withGuide(org, view) };
     }
     async update(principal, org, connectorId, body) {
         const p = requireUser(principal);
-        return {
-            connector: await this.connectors.update(org.orgId, connectorId, p.account.id, body, patTokenId(p)),
-        };
+        const view = await this.connectors.update(org.orgId, connectorId, p.account.id, body, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
     }
     async remove(principal, org, connectorId) {
         const p = requireUser(principal);
@@ -155,14 +170,25 @@ let ConnectorsController = class ConnectorsController {
     }
     async refresh(principal, org, connectorId) {
         const p = requireUser(principal);
-        return this.connectors.refresh(org.orgId, connectorId, p.account.id, patTokenId(p));
+        const r = await this.connectors.refresh(org.orgId, connectorId, p.account.id, patTokenId(p));
+        return { ...r, connector: await this.withGuide(org, r.connector) };
     }
     /** 复核待复核的工具（漂移检测，spec 7.3）：approve 采用新定义并启用，reject 停用并保留旧定义。 */
     async review(principal, org, connectorId, name, body) {
         const p = requireUser(principal);
-        return {
-            connector: await this.connectors.reviewTool(org.orgId, connectorId, name, body.action, p.account.id, patTokenId(p)),
-        };
+        const view = await this.connectors.reviewTool(org.orgId, connectorId, name, body.action, p.account.id, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
+    }
+    /**
+     * 「我已更新应用」: the org admin updated the third-party app to the connector template's current
+     * setup guide (`{ hash }` of the guide shown) -> 200 `{ connector }`; 409
+     * `connector.guide_changed` when the guide moved on since, 404 `catalog.guide_not_found` for a
+     * connector without a template guide.
+     */
+    async ackGuide(principal, org, connectorId, body) {
+        const p = requireUser(principal);
+        const view = await this.connectors.ackGuide({ orgId: org.orgId, role: org.role }, connectorId, body.hash, p.account.id, patTokenId(p));
+        return { connector: await this.withGuide(org, view) };
     }
     async setOrgCredential(principal, org, connectorId, body) {
         const p = requireUser(principal);
@@ -263,6 +289,15 @@ __decorate([
     __param(3, Param("name")),
     __param(4, ZBody(ConnectorToolReviewBody))
 ], ConnectorsController.prototype, "review", null);
+__decorate([
+    Post(":connectorId/guide-ack"),
+    HttpCode(200),
+    OrgAction("connectors.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, ZBody(ConnectorGuideAckBody))
+], ConnectorsController.prototype, "ackGuide", null);
 __decorate([
     Put(":connectorId/credentials/org"),
     HttpCode(204),

package/dist/tools/connectors.schemas.d.ts

@@ -5,6 +5,10 @@ import type { RouteSchemas } from "../platform/route-schemas.js";
  * echoed); this only bounds its size.
  */
 export declare const CredentialValue: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+/** 「我已更新应用」: the admin drift hash of the connector template guide the person was shown. */
+export declare const ConnectorGuideAckSchema: z.ZodObject<{
+    hash: z.ZodString;
+}, z.core.$strict>;
 /** `:connectorId` as the routes take it (`@Param`). */
 export declare const ConnectorPathParams: z.ZodObject<{
     connectorId: z.ZodString;

package/dist/tools/connectors.schemas.js

@@ -6,6 +6,10 @@ import { z } from "zod";
 export const CredentialValue = z
     .record(z.string().max(100), z.unknown())
     .refine((v) => JSON.stringify(v).length <= 16_384, { message: "Credential is too large" });
+/** 「我已更新应用」: the admin drift hash of the connector template guide the person was shown. */
+export const ConnectorGuideAckSchema = z
+    .object({ hash: z.string().regex(/^[0-9a-f]{64}$/) })
+    .strict();
 /** `:connectorId` as the routes take it (`@Param`). */
 export const ConnectorPathParams = z.object({ connectorId: z.string().min(1) });
 export const CONNECTOR_ROUTES = [

package/dist/tools/connectors.service.d.ts

@@ -1,9 +1,11 @@
 import { type AuthHint, type ConnectorOperation, type ToolAnnotations } from "@capybara-hq/plugin-sdk";
+import { type ConnectionGuideState, PluginGuides } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { OrgLock } from "../orgs/org-lock.js";
+import type { OrgRole } from "../orgs/roles.js";
 import { type ConnectorAuth, type CredentialOwner, Credentials, type StaticSecret } from "./credentials.js";
 import { type DriftChanges, ToolDrift, type ToolIssue } from "./drift.js";
 import { type OAuthClientRecord, type OAuthTokenRecord } from "./oauth/tokens.js";
@@ -212,11 +214,15 @@ export declare class ConnectorsService {
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     private readonly orgLock;
     readonly txHost: TransactionHost;
+    /** Setup guides of connector templates (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    private readonly guides;
     constructor(kdb: KernelDb, registry: ToolRegistry, 
     /** Extension manifests (a slug may not take an extension's name). */
     extensions: Pick<ExtensionRegistry, "manifests">, credentials: Credentials, config: Pick<KernelConfigService, "get">, drift: ToolDrift, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
-    orgLock: Pick<OrgLock, "lockAndAuthorize">, txHost: TransactionHost);
+    orgLock: Pick<OrgLock, "lockAndAuthorize">, txHost: TransactionHost, 
+    /** Setup guides of connector templates (spec 2026-11-09-setup-guides-v2-design.md §11). */
+    guides: Pick<PluginGuides, "templateAck" | "connectorStates">);
     /** The kernel-schema handle of the current context (its transaction, else the pool). */
     private get db();
     /**
@@ -305,7 +311,29 @@ export declare class ConnectorsService {
     private row;
     private summary;
     private detail;
-    /** 本组织未删除的连接器（按创建时间）。 */
+    /**
+     * 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.
+     */
+    guideStates(org: {
+        orgId: string;
+        role: OrgRole;
+    }, connectorIds: string[]): Promise<Map<string, ConnectionGuideState>>;
+    /**
+     * 「我已更新应用」 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`.
+     */
+    ackGuide(org: {
+        orgId: string;
+        role: OrgRole;
+    }, connectorId: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ConnectorDetail>;
+    /** The row and audit of {@link ackGuide}, in one transaction under the org lock. */
+    private ackIn;
+    /** The org's connectors that are not deleted (by creation time). */
     list(orgId: string): Promise<ConnectorSummary[]>;
     get(orgId: string, connectorId: string, viewerAccountId: string): Promise<ConnectorDetail>;
     /** 改名、启停连接器、工具启停与默认策略、批量把无注解工具改为 allow（`connectors.manage`）。 */

package/dist/tools/connectors.service.js

@@ -15,6 +15,7 @@ import { z } from "zod";
 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";
@@ -93,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;
@@ -106,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() {
@@ -366,6 +371,11 @@ let ConnectorsService = class ConnectorsService {
                 return this.credentials.injectionFor(id, auth, secret);
             }, { orgId, slug });
         }
+        // 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,
@@ -374,6 +384,7 @@ let ConnectorsService = class ConnectorsService {
             secret,
             oauth,
             listed,
+            guideAck,
         });
     }
     /** The org-locked, re-checked insert of {@link create} (the outbound checks ran before). */
@@ -434,6 +445,8 @@ let ConnectorsService = class ConnectorsService {
             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)
@@ -826,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")
@@ -1236,6 +1327,9 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], ConnectorsService.prototype, "applyTemplateIn", null);
+__decorate([
+    Transactional()
+], ConnectorsService.prototype, "ackIn", null);
 __decorate([
     Transactional()
 ], ConnectorsService.prototype, "update", null);
@@ -1269,6 +1363,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

@@ -119,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/oauth/tokens.d.ts

@@ -75,6 +75,26 @@ export interface TokenRequestOptions {
     /** More `token_type` values to accept as bearer tokens (`auth.tokenTypes`, case-insensitive). */
     tokenTypes?: readonly string[] | undefined;
 }
+/**
+ * The headers and form of a token request (RFC 6749 §3.2): client_id / secret per the client's
+ * auth method (Basic form-encodes them first, §2.3.1; otherwise `client_id`, plus
+ * `client_secret` for `client_secret_post`). Empty parameters are left out.
+ */
+export declare function tokenRequestInit(client: OAuthClientRecord, params: Record<string, string | undefined>): {
+    headers: Record<string, string>;
+    body: URLSearchParams;
+};
+/** The form encoding of a Basic client credential part (RFC 6749 §2.3.1). */
+export declare const formEncode: (s: string) => string;
+/** The `Authorization` value of `client_secret_basic` (both parts form-encoded first). */
+export declare const basicClientAuth: (clientId: string, clientSecret: string) => string;
+/**
+ * The refusal code of a token endpoint answer, or null when it is not a refusal (the one parser of
+ * token refusals): a 400 / 401 whose JSON body has an RFC 6749-shaped `error`, or a 200 whose body
+ * carries `ok: false` (Slack) or an `error` and no `access_token`, with a code that is not
+ * transient. Only codes matching the RFC 6749 shape are returned, never other text of the body.
+ */
+export declare function parseTokenRefusal(status: number, body: unknown): string | null;
 /**
  * Calls the token endpoint (RFC 6749 §3.2), sending client_id / secret per the client's auth method
  * (Basic form-encodes them first, §2.3.1).