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

package/dist/tools/credentials.d.ts

@@ -0,0 +1,139 @@
+import type { AuthInjection } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { type Transaction } from "kysely";
+import type { KernelConfig } from "../config/schema.js";
+import { type Keyring } from "../ctx/secrets.js";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+import type { KernelLogger } from "../log.js";
+import { type OAuthClientRecord, type OAuthTokenRecord } from "./oauth/tokens.js";
+export type Ownership = "org" | "personal";
+/** 静态认证方式（连接器安装时选定）；`headers` 的值本身就是凭据。 */
+export type StaticAuth = {
+    type: "none";
+} | {
+    type: "bearer";
+    ownership: Ownership;
+} | {
+    type: "api_key";
+    ownership: Ownership;
+    in: "header" | "query";
+    name: string;
+} | {
+    type: "basic";
+    ownership: Ownership;
+} | {
+    type: "headers";
+    ownership: Ownership;
+    names: string[];
+};
+/**
+ * OAuth 认证方式。授权码流为个人凭据（每个成员自己连接），`discovery: "mcp"` 时端点经 MCP OAuth 发现得到，
+ * `client: "dcr"` 时安装时动态注册客户端（只能配合 MCP 发现）；客户端凭据流为组织凭据。
+ */
+export type OAuthAuth = {
+    type: "oauth_code";
+    ownership: "personal";
+    discovery: "mcp" | "manual";
+    authorizationUrl?: string | undefined;
+    tokenUrl?: string | undefined;
+    scopes?: string[] | undefined;
+    client: "dcr" | "manual";
+    /** 令牌端点的客户端认证方式（有密钥时），默认 client_secret_basic。 */
+    tokenAuthMethod?: "client_secret_basic" | "client_secret_post" | undefined;
+} | {
+    type: "oauth_client";
+    ownership: "org";
+    tokenUrl: string;
+    scopes?: string[] | undefined;
+    tokenAuthMethod?: "client_secret_basic" | "client_secret_post" | undefined;
+};
+export type ConnectorAuth = StaticAuth | OAuthAuth;
+export declare const isOAuth: (auth: ConnectorAuth) => auth is OAuthAuth;
+/** 静态凭据的存储形态（JSON 序列化后信封加密）。 */
+export type StaticSecret = {
+    token: string;
+} | {
+    username: string;
+    password: string;
+} | {
+    headers: Record<string, string>;
+};
+export type CredentialOwner = {
+    kind: "org";
+} | {
+    kind: "user";
+    accountId: string;
+};
+/** 缺凭据：只带连接器 id 与归属，绝不带值。 */
+export declare class CredentialMissing extends ApiError {
+    readonly connectorId: string;
+    readonly ownership: Ownership;
+    constructor(connectorId: string, ownership: Ownership);
+}
+/**
+ * 删除某账号在该组织所有连接器上的个人凭据（`credentials:app:<connectorId>:user:<accountId>`，含已删除连接器残留的），
+ * 成员离职时在其事务内调用（不解密，不需要密钥环）。返回删除条数。
+ */
+export declare function clearAccountCredentials(db: KernelDb | Transaction<KernelDatabase>, orgId: string, accountId: string): Promise<number>;
+/** OAuth 刷新所需的依赖（锁在 Redis，往返限时与本机 http 放行取自配置）。 */
+export interface CredentialsOAuthDeps {
+    redis: Redis;
+    config: () => KernelConfig;
+}
+/**
+ * 连接器凭据：信封加密存入 capybara.secrets，解密后只在构造注入头时出现。OAuth 连接器的 token 也存在这里
+ * （个人 / 组织键，同静态凭据），OAuth 客户端存组织级的 `:client` 键；刷新见 oauth/tokens.ts。
+ */
+export declare class Credentials {
+    private readonly db;
+    private readonly keyring;
+    private readonly log;
+    private readonly tokens;
+    constructor(db: KernelDb, keyring: Keyring, log: KernelLogger, oauth?: CredentialsOAuthDeps);
+    private oauth;
+    /** 读一条 JSON 凭据；不存在 / 解不开 → null（日志不带内容）。 */
+    private readJson;
+    /** OAuth 客户端与令牌里的密钥值登记日志打码（logger 只收 ≥ 12 的值）。 */
+    private registerSecrets;
+    oauthClient(orgId: string, connectorId: string): Promise<OAuthClientRecord | null>;
+    setOAuthClient(orgId: string, connectorId: string, client: OAuthClientRecord, trx?: Transaction<KernelDatabase>): Promise<void>;
+    oauthTokens(orgId: string, connectorId: string, owner: CredentialOwner): Promise<OAuthTokenRecord | null>;
+    setOAuthTokens(orgId: string, connectorId: string, owner: CredentialOwner, rec: OAuthTokenRecord, trx?: Transaction<KernelDatabase>): Promise<void>;
+    private secrets;
+    /**
+     * 按认证方式校验凭据形状与归属；错误（`validation_failed`）只含路径与英文说明，不回显值。
+     * 连接器创建时先用它校验、再拿内存中的值连接，连上之后才落库。
+     */
+    validate(auth: ConnectorAuth, owner: CredentialOwner, value: unknown): asserts value is StaticSecret;
+    setStatic(orgId: string, connectorId: string, auth: ConnectorAuth, owner: CredentialOwner, value: StaticSecret, 
+    /** 传入时在调用方事务内写入（与连接器行 / 审计同生共死）。 */
+    trx?: Transaction<KernelDatabase>): Promise<void>;
+    clear(orgId: string, connectorId: string, owner: CredentialOwner, trx?: Transaction<KernelDatabase>): Promise<void>;
+    /** 删除某连接器的全部凭据（组织凭据与所有成员的个人凭据），连接器删除时调用。 */
+    clearConnector(orgId: string, connectorId: string, trx?: Transaction<KernelDatabase>): Promise<void>;
+    /** 删除某账号在该组织所有连接器上的个人凭据，见 {@link clearAccountCredentials}。 */
+    clearAccount(orgId: string, accountId: string, trx?: Transaction<KernelDatabase>): Promise<number>;
+    /**
+     * 持有该连接器个人凭据的**现任成员**（不解密），按凭据最近写入时间倒序（保存静态凭据、OAuth 连接与刷新 token
+     * 都会更新写入时间），最多 `limit` 个。漂移检查用它挑个人凭据型连接器的凭据。
+     */
+    personalHolders(orgId: string, connectorId: string, limit: number): Promise<string[]>;
+    /** 只看与 auth.ownership 对应的那一条凭据是否存在（不解密）；none 恒为 connected。 */
+    status(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string, trx?: Transaction<KernelDatabase>): Promise<"connected" | "missing">;
+    /** 返回本次请求要注入的头 / 查询参数；缺凭据抛 CredentialMissing。 */
+    injection(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string): Promise<AuthInjection>;
+    /**
+     * 连接器收到 401 时调用（`stale` 为那次请求注入的鉴权）：OAuth 连接器在刷新锁内强制刷新，之后的 `injection()`
+     * 返回新 token；refresh 被拒 → 凭据删除并抛 CredentialMissing。静态凭据无事可做。
+     */
+    onUnauthorized(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string, stale?: AuthInjection): Promise<void>;
+    /** 「需要重新连接」→ CredentialMissing（个人凭据由管线转成 connection_required）。 */
+    private oauthCall;
+    /**
+     * 由凭据值构造注入（不读库）；值登记日志打码。连接器创建时用请求里带的、尚未落库的凭据连接。
+     * 值缺字段 → CredentialMissing。
+     */
+    injectionFor(connectorId: string, auth: ConnectorAuth, secret: StaticSecret): AuthInjection;
+    private build;
+}

package/dist/tools/credentials.js

@@ -0,0 +1,351 @@
+import { sql } from "kysely";
+import { z } from "zod";
+import { createSecrets } from "../ctx/secrets.js";
+import { ApiError } from "../errors.js";
+import { oauthHttpOptions } from "./oauth/discovery.js";
+import { OAuthReconnectRequired, OAuthTokens, } from "./oauth/tokens.js";
+import { injectionSecrets } from "./redact.js";
+export const isOAuth = (auth) => auth.type === "oauth_code" || auth.type === "oauth_client";
+/** 缺凭据：只带连接器 id 与归属，绝不带值。 */
+export class CredentialMissing extends ApiError {
+    connectorId;
+    ownership;
+    constructor(connectorId, ownership) {
+        super("credential.missing", `No credential configured for connector ${connectorId} (${ownership})`);
+        this.connectorId = connectorId;
+        this.ownership = ownership;
+        this.name = "CredentialMissing";
+    }
+}
+/**
+ * 内核自己的 secrets 命名空间：plugin-sdk 把 `kernel` 列为保留插件名，而 `credentials` 是合法插件名，
+ * 会与某个同名插件的 ctx.secrets 相撞，所以凭据用 `kernel` 命名空间加 `credentials:` 键前缀。
+ */
+const NAMESPACE = "kernel";
+/* secrets 键沿用改名前的 `credentials:app:<connectorId>:…`（D17 / C27：已存数据不迁移）。 */
+const NO_COLON = (label, v) => {
+    if (v.length === 0 || v.includes(":"))
+        throw new Error(`credentials: invalid ${label}`);
+};
+const orgKey = (connectorId) => {
+    NO_COLON("connectorId", connectorId);
+    return `credentials:app:${connectorId}:org`;
+};
+const userKey = (connectorId, accountId) => {
+    NO_COLON("connectorId", connectorId);
+    NO_COLON("accountId", accountId);
+    return `credentials:app:${connectorId}:user:${accountId}`;
+};
+const keyOf = (connectorId, owner) => owner.kind === "org" ? orgKey(connectorId) : userKey(connectorId, owner.accountId);
+/** OAuth 客户端（组织级，按连接器一条）。 */
+const clientKey = (connectorId) => {
+    NO_COLON("connectorId", connectorId);
+    return `credentials:app:${connectorId}:client`;
+};
+const ownerOf = (auth, accountId) => auth.type !== "none" && auth.ownership === "personal"
+    ? { kind: "user", accountId }
+    : { kind: "org" };
+const nonEmpty = z.string().min(1);
+const secretSchemas = {
+    token: z.strictObject({ token: nonEmpty }),
+    basic: z.strictObject({ username: nonEmpty, password: nonEmpty }),
+};
+/**
+ * 删除某账号在该组织所有连接器上的个人凭据（`credentials:app:<connectorId>:user:<accountId>`，含已删除连接器残留的），
+ * 成员离职时在其事务内调用（不解密，不需要密钥环）。返回删除条数。
+ */
+export async function clearAccountCredentials(db, orgId, accountId) {
+    NO_COLON("accountId", accountId);
+    const prefix = "credentials:app:";
+    const suffix = `:user:${accountId}`;
+    const r = await db
+        .deleteFrom("secrets")
+        .where("namespace", "=", NAMESPACE)
+        .where("org_id", "=", orgId)
+        .where(sql `left(key, ${prefix.length})`, "=", prefix)
+        .where(sql `right(key, ${suffix.length})`, "=", suffix)
+        .executeTakeFirst();
+    return Number(r.numDeletedRows);
+}
+/**
+ * 连接器凭据：信封加密存入 capybara.secrets，解密后只在构造注入头时出现。OAuth 连接器的 token 也存在这里
+ * （个人 / 组织键，同静态凭据），OAuth 客户端存组织级的 `:client` 键；刷新见 oauth/tokens.ts。
+ */
+export class Credentials {
+    db;
+    keyring;
+    log;
+    tokens;
+    constructor(db, keyring, log, oauth) {
+        this.db = db;
+        this.keyring = keyring;
+        this.log = log;
+        if (oauth) {
+            const store = {
+                readClient: (orgId, connectorId) => this.oauthClient(orgId, connectorId),
+                readTokens: (orgId, connectorId, owner) => this.oauthTokens(orgId, connectorId, owner),
+                writeTokens: (orgId, connectorId, owner, rec) => this.setOAuthTokens(orgId, connectorId, owner, rec),
+                deleteTokens: (orgId, connectorId, owner) => this.clear(orgId, connectorId, owner),
+            };
+            this.tokens = new OAuthTokens(store, oauth.redis, () => oauthHttpOptions(oauth.config()), log);
+        }
+    }
+    oauth() {
+        if (!this.tokens)
+            throw new Error("credentials: OAuth is not configured");
+        return this.tokens;
+    }
+    /** 读一条 JSON 凭据；不存在 / 解不开 → null（日志不带内容）。 */
+    async readJson(orgId, key, connectorId) {
+        const raw = await this.secrets().get(orgId, key);
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            this.log.warn("credential payload is corrupted", { connectorId });
+            return null;
+        }
+    }
+    /** OAuth 客户端与令牌里的密钥值登记日志打码（logger 只收 ≥ 12 的值）。 */
+    registerSecrets(values) {
+        this.log.addOrgSecrets(values.filter((v) => typeof v === "string" && v !== ""));
+    }
+    async oauthClient(orgId, connectorId) {
+        const v = (await this.readJson(orgId, clientKey(connectorId), connectorId));
+        if (v === null || typeof v !== "object" || typeof v.clientId !== "string")
+            return null;
+        this.registerSecrets([v.clientSecret, v.registration?.accessToken]);
+        return v;
+    }
+    async setOAuthClient(orgId, connectorId, client, trx) {
+        this.registerSecrets([client.clientSecret, client.registration?.accessToken]);
+        await this.secrets(trx).set(orgId, clientKey(connectorId), JSON.stringify(client));
+    }
+    async oauthTokens(orgId, connectorId, owner) {
+        const v = (await this.readJson(orgId, keyOf(connectorId, owner), connectorId));
+        if (v === null || typeof v !== "object" || typeof v.access_token !== "string")
+            return null;
+        this.registerSecrets([v.access_token, v.refresh_token]);
+        return v;
+    }
+    async setOAuthTokens(orgId, connectorId, owner, rec, trx) {
+        this.registerSecrets([rec.access_token, rec.refresh_token]);
+        await this.secrets(trx).set(orgId, keyOf(connectorId, owner), JSON.stringify(rec));
+    }
+    secrets(db = this.db) {
+        return createSecrets(db, this.keyring, NAMESPACE);
+    }
+    /**
+     * 按认证方式校验凭据形状与归属；错误（`validation_failed`）只含路径与英文说明，不回显值。
+     * 连接器创建时先用它校验、再拿内存中的值连接，连上之后才落库。
+     */
+    validate(auth, owner, value) {
+        const fail = (issues) => new ApiError("validation_failed", "Invalid credential", issues);
+        if (auth.type === "none")
+            throw fail([{ path: "", message: "Auth type none takes no credential" }]);
+        if (isOAuth(auth)) {
+            throw fail([
+                {
+                    path: "",
+                    message: "OAuth connectors get their tokens through the connect flow; credentials cannot be set directly",
+                },
+            ]);
+        }
+        const want = auth.ownership === "org" ? "org" : "user";
+        if (owner.kind !== want) {
+            throw fail([
+                {
+                    path: "owner",
+                    message: `Credential owner must be ${want} for ${auth.ownership} ownership`,
+                },
+            ]);
+        }
+        let schema;
+        if (auth.type === "bearer" || auth.type === "api_key")
+            schema = secretSchemas.token;
+        else if (auth.type === "basic")
+            schema = secretSchemas.basic;
+        else {
+            const names = auth.names;
+            schema = z.strictObject({ headers: z.record(z.string(), nonEmpty) }).superRefine((v, ctx) => {
+                for (const n of names) {
+                    if (!(n in v.headers))
+                        ctx.addIssue({
+                            code: "custom",
+                            path: ["headers", n],
+                            message: "Required header is missing",
+                        });
+                }
+                for (const n of Object.keys(v.headers)) {
+                    if (!names.includes(n))
+                        ctx.addIssue({ code: "custom", path: ["headers", n], message: "Unexpected header" });
+                }
+            });
+        }
+        const r = schema.safeParse(value);
+        if (!r.success) {
+            throw fail(r.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })));
+        }
+    }
+    async setStatic(orgId, connectorId, auth, owner, value, 
+    /** 传入时在调用方事务内写入（与连接器行 / 审计同生共死）。 */
+    trx) {
+        this.validate(auth, owner, value);
+        await this.secrets(trx).set(orgId, keyOf(connectorId, owner), JSON.stringify(value));
+    }
+    async clear(orgId, connectorId, owner, trx) {
+        await this.secrets(trx).delete(orgId, keyOf(connectorId, owner));
+    }
+    /** 删除某连接器的全部凭据（组织凭据与所有成员的个人凭据），连接器删除时调用。 */
+    async clearConnector(orgId, connectorId, trx) {
+        const prefix = orgKey(connectorId).slice(0, -"org".length);
+        await (trx ?? this.db)
+            .deleteFrom("secrets")
+            .where("namespace", "=", NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "like", `${prefix}%`)
+            .execute();
+    }
+    /** 删除某账号在该组织所有连接器上的个人凭据，见 {@link clearAccountCredentials}。 */
+    async clearAccount(orgId, accountId, trx) {
+        return clearAccountCredentials(trx ?? this.db, orgId, accountId);
+    }
+    /**
+     * 持有该连接器个人凭据的**现任成员**（不解密），按凭据最近写入时间倒序（保存静态凭据、OAuth 连接与刷新 token
+     * 都会更新写入时间），最多 `limit` 个。漂移检查用它挑个人凭据型连接器的凭据。
+     */
+    async personalHolders(orgId, connectorId, limit) {
+        const prefix = userKey(connectorId, "x").slice(0, -1);
+        const rows = await sql `
+      SELECT m.account_id FROM capybara.secrets s
+      JOIN capybara.memberships m
+        ON m.org_id = s.org_id AND m.account_id = substr(s.key, ${prefix.length + 1})
+      WHERE s.namespace = ${NAMESPACE} AND s.org_id = ${orgId}
+        AND left(s.key, ${prefix.length}) = ${prefix}
+      ORDER BY s.updated_at DESC, m.account_id
+      LIMIT ${limit}`.execute(this.db);
+        return rows.rows.map((r) => r.account_id);
+    }
+    /** 只看与 auth.ownership 对应的那一条凭据是否存在（不解密）；none 恒为 connected。 */
+    async status(orgId, connectorId, auth, accountId, trx) {
+        if (auth.type === "none")
+            return "connected";
+        // 客户端凭据流：有客户端即可按需取 token
+        const key = auth.type === "oauth_client"
+            ? clientKey(connectorId)
+            : auth.ownership === "personal"
+                ? userKey(connectorId, accountId)
+                : orgKey(connectorId);
+        const row = await (trx ?? this.db)
+            .selectFrom("secrets")
+            .select("key")
+            .where("namespace", "=", NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "=", key)
+            .executeTakeFirst();
+        return row ? "connected" : "missing";
+    }
+    /** 返回本次请求要注入的头 / 查询参数；缺凭据抛 CredentialMissing。 */
+    async injection(orgId, connectorId, auth, accountId) {
+        if (auth.type === "none")
+            return { headers: {} };
+        const owner = ownerOf(auth, accountId);
+        if (isOAuth(auth)) {
+            const token = await this.oauthCall(connectorId, auth, () => this.oauth().accessToken(orgId, connectorId, auth, owner));
+            return this.injectionFor(connectorId, auth, { token });
+        }
+        const missing = () => new CredentialMissing(connectorId, auth.ownership);
+        const raw = await this.secrets().get(orgId, keyOf(connectorId, owner));
+        if (raw === null)
+            throw missing();
+        let value;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            // 密文解开后不是合法 JSON：按缺失处理，日志不带内容
+            this.log.warn("credential payload is corrupted", { connectorId });
+            throw missing();
+        }
+        return this.injectionFor(connectorId, auth, value);
+    }
+    /**
+     * 连接器收到 401 时调用（`stale` 为那次请求注入的鉴权）：OAuth 连接器在刷新锁内强制刷新，之后的 `injection()`
+     * 返回新 token；refresh 被拒 → 凭据删除并抛 CredentialMissing。静态凭据无事可做。
+     */
+    async onUnauthorized(orgId, connectorId, auth, accountId, stale) {
+        if (!isOAuth(auth))
+            return;
+        const header = stale?.headers.Authorization;
+        const token = header?.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined;
+        await this.oauthCall(connectorId, auth, () => this.oauth().forceRefresh(orgId, connectorId, auth, ownerOf(auth, accountId), token));
+    }
+    /** 「需要重新连接」→ CredentialMissing（个人凭据由管线转成 connection_required）。 */
+    async oauthCall(connectorId, auth, work) {
+        try {
+            return await work();
+        }
+        catch (e) {
+            if (e instanceof OAuthReconnectRequired) {
+                throw new CredentialMissing(connectorId, e.owner.kind === "user" ? "personal" : auth.ownership);
+            }
+            throw e;
+        }
+    }
+    /**
+     * 由凭据值构造注入（不读库）；值登记日志打码。连接器创建时用请求里带的、尚未落库的凭据连接。
+     * 值缺字段 → CredentialMissing。
+     */
+    injectionFor(connectorId, auth, secret) {
+        const inj = this.build(connectorId, auth, secret);
+        // 与工具结果打码同一套展开（含 scheme 后的 token、Basic 解码串、百分号编码形式）；logger 只收 ≥ 12 的值
+        this.log.addOrgSecrets(injectionSecrets(inj));
+        return inj;
+    }
+    build(connectorId, auth, secret) {
+        if (auth.type === "none")
+            return { headers: {} };
+        if (isOAuth(auth)) {
+            const token = secret.token;
+            if (typeof token !== "string" || token === "")
+                throw new CredentialMissing(connectorId, auth.ownership);
+            return { headers: { Authorization: `Bearer ${token}` } };
+        }
+        const missing = () => new CredentialMissing(connectorId, auth.ownership);
+        if (typeof secret !== "object" || secret === null)
+            throw missing();
+        const value = secret;
+        switch (auth.type) {
+            case "bearer": {
+                if (!value.token)
+                    throw missing();
+                return { headers: { Authorization: `Bearer ${value.token}` } };
+            }
+            case "api_key": {
+                if (!value.token)
+                    throw missing();
+                return auth.in === "header"
+                    ? { headers: { [auth.name]: value.token } }
+                    : { headers: {}, query: { [auth.name]: value.token } };
+            }
+            case "basic": {
+                if (value.username === undefined || value.password === undefined)
+                    throw missing();
+                const encoded = Buffer.from(`${value.username}:${value.password}`).toString("base64");
+                return { headers: { Authorization: `Basic ${encoded}` } };
+            }
+            case "headers": {
+                const headers = {};
+                for (const name of auth.names) {
+                    const v = value.headers?.[name];
+                    if (v === undefined)
+                        throw missing();
+                    headers[name] = v;
+                }
+                return { headers };
+            }
+        }
+    }
+}

package/dist/tools/drift.d.ts

@@ -0,0 +1,141 @@
+import { type AuthInjection, type Logger, type ToolSpec } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { Maintenance } from "../runtime/maintenance.js";
+import { type Credentials } from "./credentials.js";
+import { type ToolRegistry } from "./registry.js";
+/**
+ * 工具定义漂移检测（spec 7.3：新增 / 变化的工具在组织管理员复核前不可用，防 rug-pull / 工具投毒）。
+ *
+ * 与上次快照比对：新增 → 插入 `pending_review`；定义（spec_hash 或来源）变化 → `pending_review`，新定义存
+ * `pending_spec`，旧定义留在 `spec` 供对比，复核通过才采用；消失 → `disabled` 并记 `missing_since`（行保留，
+ * 又出现时按新增处理）。定义不合规（key 不合法等）的工具只能停用：新增时直接停用；复核过的工具变成不合规
+ * 定义时新定义同样只进 `pending_spec`（停用，approve 被拒），`spec` 始终是上次复核通过的定义。
+ * 从未复核过的工具（`reviewed_at` 为空）没有可比的旧定义：定义再变时直接替换 `spec`（仍待复核），不产生 pending。
+ * 连接器从未拍过快照（`tools_synced_at` 为空且没有工具行，即 OAuth 授权码连接器安装时不 listTools，A16）时，
+ * 首个快照按安装处理（直接启用）。
+ *
+ * 触发：维护队列的周期扫描（`tools.driftIntervalHours`）、连接器在会话中报告工具清单变了（MCP
+ * `notifications/tools/list_changed`）、管理员手动刷新（`ConnectorsService.refresh`，走同一套比对）。
+ * 授权（`tool_grants` / `conversation_tool_grants`）按 spec_hash 比对（D8），复核通过采用新指纹后旧授权自然失效。
+ */
+/** 周期扫描：任务名与 job scheduler id（不含 `:`）。 */
+export declare const DRIFT_SCAN_JOB = "drift-scan";
+export declare const DRIFT_SCHEDULER_ID = "drift-scan-interval";
+/** 单个连接器的漂移检查任务名。 */
+export declare const DRIFT_CONNECTOR_JOB = "drift-connector";
+/**
+ * list_changed 触发的检查：jobId 按连接器与分钟桶去重（同一分钟内多次通知只检查一次；connectorId 为 UUID，不含 `:`）。
+ */
+export declare const listChangedJobId: (connectorId: string, now?: number) => string;
+/** 周期扫描投递的检查：jobId 按连接器与扫描周期桶去重（同一周期内重复扫描只检查一次）。 */
+export declare const driftScanJobId: (connectorId: string, bucket: number) => string;
+/** 个人凭据型连接器：最多依次尝试几个成员的凭据。 */
+export declare const PERSONAL_CANDIDATES = 3;
+export type DriftTrigger = "schedule" | "list_changed";
+export interface DriftChanges {
+    added: string[];
+    changed: string[];
+    removed: string[];
+}
+export type DriftCheckResult = {
+    status: "checked";
+    changes: DriftChanges;
+} | {
+    status: "skipped";
+    reason: "not_found" | "inactive" | "no_connector" | "no_credential" | "connect_failed";
+};
+type Trx = Transaction<KernelDatabase>;
+type ToolSource = "connector" | "resources";
+/** 快照中被停用 / 跳过的工具及英文原因。 */
+export interface ToolIssue {
+    name: string;
+    reason: string;
+}
+export interface SnapshotRow {
+    name: string;
+    spec: ToolSpec;
+    specHash: string;
+    /** key 不合法 / 定义不合规时为原因，此时工具只能停用。 */
+    issue: string | null;
+    source: ToolSource;
+}
+/**
+ * 连接 / 列工具失败的说明：ToolError 的消息是连接器写给人看的英文说明（如「Swagger 2.0 不支持」），
+ * 按本次注入的凭据打码、截断后带上；其他错误只给错误类名（详情进日志）。
+ */
+export declare function connectFailedMessage(e: unknown, redact: (s: string) => string): string;
+/**
+ * 把连接器返回的工具清单整理成快照：只保留 `name / description / inputSchema / annotations / connectorData`
+ * 以及仅供显示的 `title / keyArgs`（不合规的这两项直接丢掉，不计入指纹；连接器工具不得自带 `defaultPolicy`），
+ * 同名的后者丢弃；key 超长 / 含非法字符或定义不合规的工具
+ * 照样入库但只能停用，并给出原因——一个坏工具不挡住整个连接器。名字不是非空字符串的无法入库，只报原因。
+ */
+export declare function snapshot(slug: string, specs: unknown, resources: boolean): {
+    rows: SnapshotRow[];
+    issues: ToolIssue[];
+};
+/**
+ * Cleans a remote display title (UI refresh B, fix I2): removes format characters (Unicode Cf: bidi
+ * overrides and isolates, zero-width and other invisible ones), turns control characters (Cc,
+ * newlines included) into spaces, collapses whitespace runs to one space, trims and cuts to
+ * {@link TOOL_TITLE_MAX} code points. Undefined when nothing is left or the title is not a string.
+ * The title sits next to the reviewed tool key on the approval block, so it must not be able to
+ * reorder, hide or break that line.
+ */
+export declare function sanitizeToolTitle(raw: unknown): string | undefined;
+/** 工具当前不能启用的原因（视图、启用与复核校验共用）。 */
+export declare function toolIssue(slug: string, spec: ToolSpec): string | null;
+export interface ToolDriftDeps {
+    db: KernelDb;
+    registry: Pick<ToolRegistry, "findConnector">;
+    credentials: Pick<Credentials, "injection" | "onUnauthorized" | "personalHolders">;
+    config: () => KernelConfig;
+    log: Logger;
+    /** 维护队列（登记周期扫描与检查任务的处理函数；不给时只能同步调用 `check`）。 */
+    maintenance?: Pick<Maintenance, "add" | "handle" | "schedule">;
+}
+export declare class ToolDrift {
+    private readonly d;
+    constructor(d: ToolDriftDeps);
+    private intervalMs;
+    /**
+     * 打开一次会话拉工具清单，无论成败都关闭会话；会话带 `listResources` 即视为支持 resources。
+     * 清单里回显的凭据按本次注入的值打码（见 redact.ts）。凭据缺失原样抛 `credential.missing`；
+     * 其余失败一律 502 `connector.connect_failed`，消息只带上游错误的类名（不带消息，消息里可能回显凭据）。
+     */
+    listTools(connector: string, endpoint: unknown, auth: () => Promise<AuthInjection>, logCtx: Record<string, unknown>, 
+    /** 收到 401：OAuth 连接器在刷新锁内刷新（参数为最后一次注入的鉴权）。 */
+    onUnauthorized?: (last: AuthInjection | undefined) => Promise<void>): Promise<{
+        specs: unknown;
+        resources: boolean;
+    }>;
+    /**
+     * 把新快照与当前工具行比对并写入（调用方已在事务内锁住连接器行）；返回按名排序的变化。
+     * 规则见文件头。待复核的新定义也写进 `tool_specs`（内容寻址，只增不改）。
+     */
+    apply(t: Trx, app: {
+        id: string;
+        tools_synced_at: Date | null;
+    }, rows: SnapshotRow[]): Promise<DriftChanges>;
+    /**
+     * 后台检查一个连接器（维护队列的 worker 上执行，没有发起人）：拉工具清单 → 比对写入 → 有变化记审计
+     * `connector.tools_drifted`（detail 只有新增 / 变化 / 消失的个数与触发方式，不含定义与凭据）。
+     * 凭据：无需凭据 / 组织凭据型（含客户端凭据流）用组织凭据；个人凭据型（静态或 OAuth 授权码）依次尝试
+     * 至多 {@link PERSONAL_CANDIDATES} 个**现任成员**的个人凭据，按凭据最近写入时间倒序（连接 / 刷新 token
+     * 都会更新写入时间，即「最近连接成功的成员」优先），用第一个成功的；没有任何成员凭据 → 跳过并记日志。
+     * 连不上 / 都失败 → 跳过（不改快照，下个周期或下次通知再查）。
+     */
+    check(orgId: string, connectorId: string, trigger: DriftTrigger): Promise<DriftCheckResult>;
+    /**
+     * 连接器在会话中报告工具清单变了：投递一次该连接器的检查（jobId 按分钟桶去重）。投递失败只记日志。
+     */
+    onToolsChanged(orgId: string, connectorId: string): Promise<void>;
+    /**
+     * 周期扫描：给本周期内还没检查过的活动连接器（`tools_synced_at` 为空或早于半个周期）各投递一次检查，
+     * jobId 按周期桶去重——即使扫描在多个副本上重复执行，每个连接器每周期也只检查一次。返回投递数。
+     */
+    scan(): Promise<number>;
+}
+export {};