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

package/dist/cards.js

@@ -0,0 +1,217 @@
+import { validateInputForm } from "./tool.js";
+import { isHttpUrl } from "./url.js";
+const MAX_INLINE_SINGLE = 5;
+const MAX_INLINE_MULTI = 10;
+/**
+ * 提问能否在 IM 内直接作答：仅当表单恰有一个枚举字段（单选 ≤ 5 项 / 多选 ≤ 10 项）且不允许「其他」时为真；
+ * 否则卡片只给网页链接。
+ */
+export function questionRenderableInline(form) {
+    if (form.fields.length !== 1)
+        return false;
+    const f = form.fields[0];
+    if (!f || f.allowOther)
+        return false;
+    if (f.schema.type !== "string" || !("enum" in f.schema))
+        return false;
+    const n = f.schema.enum.length;
+    return f.multiSelect ? n <= MAX_INLINE_MULTI : n <= MAX_INLINE_SINGLE;
+}
+const KINDS = ["approval", "question", "connect", "bind"];
+const SCOPES = ["once", "session", "always"];
+const APPROVAL_STATES = ["pending", "approved", "denied", "expired", "cancelled"];
+const QUESTION_STATES = ["pending", "answered", "expired", "cancelled"];
+const ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+const list = (xs) => xs.map((x) => JSON.stringify(x)).join(", ");
+/** 校验卡片结构，返回问题列表（空 = 合法）。 */
+export function validateChannelCard(card) {
+    if (typeof card !== "object" || card === null || Array.isArray(card))
+        return ["card must be an object"];
+    const c = card;
+    const out = [];
+    const nonEmpty = (k) => {
+        if (typeof c[k] !== "string" || c[k] === "")
+            out.push(`${k} must be a non-empty string`);
+    };
+    const optNonEmpty = (k) => {
+        if (c[k] !== undefined)
+            nonEmpty(k);
+    };
+    const oneOf = (k, xs) => {
+        if (typeof c[k] !== "string" || !xs.includes(c[k]))
+            out.push(`${k} must be one of ${list(xs)}`);
+    };
+    const url = (k) => {
+        if (!isHttpUrl(c[k]))
+            out.push(`${k} must be an absolute http(s) URL of at most 2000 characters`);
+    };
+    switch (c.kind) {
+        case "approval": {
+            for (const k of ["id", "title", "toolName", "agentName"])
+                nonEmpty(k);
+            optNonEmpty("appName");
+            if (typeof c.inputPreview !== "string")
+                out.push("inputPreview must be a string");
+            const s = c.scopes;
+            if (!Array.isArray(s) ||
+                s.length === 0 ||
+                new Set(s).size !== s.length ||
+                s.some((x) => !SCOPES.includes(x)))
+                out.push(`scopes must be a non-empty array of ${list(SCOPES)} without duplicates`);
+            if (typeof c.expiresAt !== "string" ||
+                !ISO_8601.test(c.expiresAt) ||
+                Number.isNaN(Date.parse(c.expiresAt)))
+                out.push("expiresAt must be an ISO 8601 timestamp");
+            oneOf("state", APPROVAL_STATES);
+            optNonEmpty("decidedBy");
+            optNonEmpty("denyReason");
+            url("webUrl");
+            return out;
+        }
+        case "question": {
+            nonEmpty("id");
+            oneOf("state", QUESTION_STATES);
+            url("webUrl");
+            if (c.answerSummary !== undefined && typeof c.answerSummary !== "string")
+                out.push("answerSummary must be a string");
+            // 不能在 IM 内作答的表单（见 questionRenderableInline）同样合法：渠道只渲染网页链接。
+            for (const p of validateInputForm(c.form))
+                out.push(`form: ${p}`);
+            return out;
+        }
+        case "connect":
+            nonEmpty("appName");
+            url("url");
+            return out;
+        case "bind":
+            url("url");
+            nonEmpty("text");
+            return out;
+        default:
+            return [`kind must be one of ${list(KINDS)}`];
+    }
+}
+/**
+ * 把模型可控的值（审批标题、输入预览、提问标题、回答摘要）放进代码里，退回文本里它们不会变成链接、强调或 HTML：
+ * 单行用行内代码，多行用围栏代码块（以换行开头），分隔符都比值里最长的反引号串更长（CommonMark 6.1 / 4.5）。
+ * 选代码而不是给标点加反斜杠：代码是 CommonMark / GFM 里唯一保证内容按原样显示的写法（反斜杠挡不住 GFM 的裸网址
+ * 自动链接，各渠道转换器对反斜杠的处理也不一致）。
+ */
+function asCode(s) {
+    const v = s.replace(/\r\n?/g, "\n");
+    const longest = Math.max(0, ...[...v.matchAll(/`+/g)].map((m) => m[0].length));
+    if (v.includes("\n")) {
+        const fence = "`".repeat(Math.max(3, longest + 1));
+        return `\n${fence}\n${v}\n${fence}`;
+    }
+    const d = "`".repeat(longest + 1);
+    // 值以反引号开头 / 结尾、或首尾都是空格时补一个空格（渲染时去掉），否则会与分隔符粘连或被吃掉空格
+    const pad = /^`|`$/.test(v) || (v.startsWith(" ") && v.endsWith(" ")) ? " " : "";
+    return `${d}${pad}${v}${pad}${d}`;
+}
+/** 前缀 + 代码：代码是围栏块（以换行开头）时去掉前缀末尾的空格。 */
+const withCode = (prefix, code) => code.startsWith("\n") ? `${prefix.trimEnd()}${code}` : `${prefix}${code}`;
+const TEXT = {
+    en: {
+        sep: ": ",
+        approval: "[Approval] ",
+        question: "[Question] ",
+        connect: (app) => `[Connect] ${app} needs to be connected.`,
+        tool: "Tool",
+        agent: "Agent",
+        input: "Input",
+        status: "Status",
+        reason: "Reason",
+        expires: "Expires",
+        answer: "Answer",
+        approveOnWeb: "Cards are not supported here. Approve or deny on the web",
+        answerOnWeb: "Answer on the web",
+        details: "Details",
+        connectLink: "Connect",
+        approvalStates: {
+            pending: "Pending",
+            approved: "Approved",
+            denied: "Denied",
+            expired: "Expired",
+            cancelled: "Cancelled",
+        },
+        questionStates: {
+            pending: "Pending",
+            answered: "Answered",
+            expired: "Expired",
+            cancelled: "Cancelled",
+        },
+    },
+    zh: {
+        sep: "：",
+        approval: "【审批】",
+        question: "【提问】",
+        connect: (app) => `【连接】需要连接 ${app}。`,
+        tool: "工具",
+        agent: "Agent",
+        input: "输入",
+        status: "状态",
+        reason: "原因",
+        expires: "过期时间",
+        answer: "回答",
+        approveOnWeb: "此处不支持卡片，请到网页上批准或拒绝",
+        answerOnWeb: "到网页上回答",
+        details: "详情",
+        connectLink: "连接",
+        approvalStates: {
+            pending: "待审批",
+            approved: "已批准",
+            denied: "已拒绝",
+            expired: "已过期",
+            cancelled: "已取消",
+        },
+        questionStates: {
+            pending: "待回答",
+            answered: "已回答",
+            expired: "已过期",
+            cancelled: "已取消",
+        },
+    },
+};
+/**
+ * 不支持卡片的渠道的统一退回文本（含链接）；固定话术按 locale 取 zh / en。结果是 Markdown（放进
+ * `OutboundMessage.text`，由渠道插件转换）：模型可控的字段放在代码里（见 `asCode`），不会产生链接。
+ */
+export function renderCardAsText(card, locale) {
+    const t = TEXT[locale] ?? TEXT.en;
+    const line = (label, value) => withCode(`${label}${t.sep}`, value);
+    switch (card.kind) {
+        case "approval": {
+            const state = t.approvalStates[card.state];
+            const lines = [
+                withCode(t.approval, asCode(card.title)),
+                line(t.tool, card.appName ? `${card.appName} / ${card.toolName}` : card.toolName),
+                line(t.agent, card.agentName),
+                line(t.input, asCode(card.inputPreview)),
+                line(t.status, card.decidedBy ? `${state} (${card.decidedBy})` : state),
+            ];
+            if (card.state === "denied" && card.denyReason)
+                lines.push(line(t.reason, asCode(card.denyReason)));
+            if (card.state === "pending")
+                lines.push(line(t.expires, card.expiresAt), line(t.approveOnWeb, card.webUrl));
+            else
+                lines.push(line(t.details, card.webUrl));
+            return lines.join("\n");
+        }
+        case "question": {
+            const title = typeof card.form.title === "string" ? card.form.title : card.form.title[locale];
+            const lines = [
+                withCode(t.question, asCode(title)),
+                line(t.status, t.questionStates[card.state]),
+            ];
+            if (card.answerSummary)
+                lines.push(line(t.answer, asCode(card.answerSummary)));
+            lines.push(line(card.state === "pending" ? t.answerOnWeb : t.details, card.webUrl));
+            return lines.join("\n");
+        }
+        case "connect":
+            return `${t.connect(card.appName)}\n${line(t.connectLink, card.url)}`;
+        case "bind":
+            return `${card.text}\n${card.url}`;
+    }
+}

package/dist/channel.d.ts

@@ -0,0 +1,230 @@
+import type { ZodTypeAny } from "zod";
+import type { CardAction, Locale, OutboundMessage } from "./cards.js";
+/**
+ * 消息的投递目标。群聊里的 `threadId` 是话题**根消息的 `messageId`**（内核用它把同一话题归到一个会话，
+ * 回复也投到这个话题）：Slack 为插件所定义的根消息 `messageId`（如 `<频道>:<ts>`，ts 即回复的
+ * `thread_ts`）；飞书为根消息的 `message_id`（`root_id`，`om_…`），**不是** `thread_id`（`omt_…`）。私聊不带。
+ */
+export interface ChannelTarget {
+    chatId: string;
+    threadId?: string;
+    chatType: "dm" | "group";
+}
+/**
+ * 入站事件的发言人 / 点击者。`tenantId` 为发言人所属企业：Slack 为 team id（Enterprise Grid 下是 team，
+ * 不是 enterprise），飞书为 `tenant_key`；与连接的租户（`verify` 返回的 `tenantId`，同一口径）不同的人
+ * （外部联系人、共享频道里的其他企业）内核只允许绑定，不按匿名访客处理。`displayName`、`avatarUrl` 为平台上的
+ * 显示名与头像（拿得到就带）：内核把显示名用在绑定确认页（没有时回落到 externalId）。
+ */
+export interface InboundSender {
+    externalId: string;
+    tenantId: string;
+    displayName?: string;
+    avatarUrl?: string;
+}
+/**
+ * 渠道交给内核的入站事件。插件的约定：
+ * - `message.messageId` 在本连接内唯一（内核按它去重）；
+ * - M4 只处理文本：附件、图片、文件等忽略（消息只有附件时不发事件）；
+ * - 用户编辑、撤回 / 删除消息不发事件（忽略）；
+ * - `text` 里去掉 @ 机器人的部分（`mentionsBot` 另行说明是否 @ 了机器人）；
+ * - `card_action`：`messageId` 为卡片所在消息的 id（同一张卡片的多次点击相同）；`eventId` 为平台给这次点击的
+ *   唯一 id（拿得到就带，本连接内唯一：内核按它去重平台重投）；群聊里 `target.threadId` 拿得到就带，
+ *   拿不到时内核取发出该卡片时记下的话题。
+ */
+export type InboundEvent = {
+    type: "message";
+    messageId: string;
+    target: ChannelTarget;
+    sender: InboundSender;
+    text: string;
+    mentionsBot: boolean;
+} | {
+    type: "card_action";
+    target: ChannelTarget;
+    messageId: string;
+    /** 平台给这次点击的唯一 id（如飞书回调的 event_id、Slack 的 trigger / action 时间戳组合）。 */
+    eventId?: string;
+    sender: InboundSender;
+    action: CardAction;
+}
+/** 平台推送人员变动的提示，内核据此触发通讯录同步。 */
+ | {
+    type: "directory_changed";
+    tenantId: string;
+};
+export interface ChannelConnectArgs {
+    connectionId: string;
+    /** 已按 connectionSchema 校验，含密钥。 */
+    config: unknown;
+    /**
+     * 把入站事件交给内核。内核只做去重并把事件持久地排进队列（很快，不在这里处理消息），resolve 即表示内核已经
+     * 可靠地收下了这条事件：插件**在它 resolve 之后**才向平台确认（ack）；reject 时**不要**确认，让平台重投；
+     * 插件自己不必重试 `onEvent`。去重范围：`message` 按 `messageId`、带 `eventId` 的 `card_action` 按 `eventId`
+     * （各保留 24 小时）——重投只处理一次；不带 `eventId` 的 `card_action` 不去重（每次都处理，重复的审批 /
+     * 回答由内核回「已处理」）；`directory_changed` 不去重（同步任务本身按分钟合并）。
+     */
+    onEvent(e: InboundEvent): Promise<void>;
+    signal: AbortSignal;
+}
+export interface ChannelSendArgs {
+    config: unknown;
+    target: ChannelTarget;
+    /**
+     * 消息内容。`text` 超过平台单条长度上限时由插件自行拆成多条按序发送，返回**最后一条**的消息 id
+     * （内核之后编辑的是这条）。
+     */
+    message: OutboundMessage;
+    signal: AbortSignal;
+    /** 连接所属组织的界面语言：插件自己渲染的文案（卡片按钮、降级文本里的固定词）按它选择。 */
+    locale: Locale;
+    /**
+     * 幂等键（可选）：不超过 40 个 `[A-Za-z0-9_-]` 字符，同一条逻辑消息的每次重试（崩溃后其他副本续投、
+     * 可重试失败后重发）都相同——内核由「会话 + 事件 seq」或「卡片 + 状态」稳定哈希得到。平台支持幂等发送
+     * （如飞书的 `uuid`）时插件应原样透传或按平台要求映射，以免重复消息；不支持的平台忽略即可。
+     */
+    idempotencyKey?: string;
+}
+/**
+ * An inbound webhook request as the kernel received it on `POST /channels/webhook/<connectionId>`.
+ * `headers` names are lowercase (repeated headers joined with `, `; cookies are dropped); `body` is
+ * the raw request bytes, unparsed, so the plugin can verify signatures over them; `receivedAt` is the
+ * kernel's receive time in epoch milliseconds (use it for timestamp replay checks).
+ */
+export interface ChannelWebhookRequest {
+    method: "POST";
+    headers: Readonly<Record<string, string>>;
+    body: Uint8Array;
+    receivedAt: number;
+}
+/** An HTTP response the kernel writes back to the platform as is. */
+export interface ChannelWebhookResponse {
+    status: number;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/**
+ * What the plugin made of a webhook request:
+ * - `respond`: reply directly without any event (URL verification challenge and the like);
+ * - `events`: hand these events to the kernel, which dedupes and enqueues them like the long
+ *   connection's `onEvent` and replies `ack` only after every one resolved; if any rejects, the
+ *   kernel replies 503 so the platform redelivers (dedupe makes the redelivery safe);
+ *   an empty list just replies `ack` (ignored events are still acknowledged);
+ * - `reject`: the request is not genuine (bad signature, stale timestamp, malformed): reply this
+ *   status and enqueue nothing.
+ */
+export type ChannelWebhookResult = {
+    kind: "respond";
+    response: ChannelWebhookResponse;
+} | {
+    kind: "events";
+    events: InboundEvent[];
+    ack: ChannelWebhookResponse;
+} | {
+    kind: "reject";
+    status: 400 | 401 | 403;
+};
+/**
+ * Optional webhook inbound mode (`Channel.webhook`). Signature verification, decryption and
+ * timestamp replay protection all happen here: the kernel knows no platform formats, applies no
+ * auth on the route, and only calls this for connections in webhook mode. `config` is the
+ * connection config (validated against `connectionSchema`, secrets included).
+ *
+ * Timing: one request has a 10 second kernel deadline covering `handle` and handing its events to
+ * the kernel. `signal` aborts at the deadline or when the platform hangs up; past the deadline the
+ * kernel answers 503 whether or not `handle` stops (late work is not cancelled). Platforms' own ack
+ * deadlines are a few seconds, so keep it quick.
+ *
+ * Responses the kernel writes without asking the plugin:
+ * - 404 `channel.webhook_not_found`, the same body for an unknown connection, one not in webhook
+ *   mode, a disabled one, or one whose plugin is off for its org;
+ * - 503 `extension.unavailable` when the plugin is not loaded on the replica that got the request (a
+ *   rolling upgrade; the platform retries and reaches one that has it) or the stored config no
+ *   longer matches `connectionSchema`; only reachable with an existing webhook connection's id;
+ * - 413 `payload_too_large` above `channels.webhookMaxBodyBytes` (default 1 MiB), and 415 for a
+ *   malformed `Content-Type` header, both before `handle` is called (any well-formed content type,
+ *   or none, reaches the plugin as raw bytes);
+ * - after `handle`: 503 `channel.webhook_retry` when the deadline passes or any `onEvent` rejects,
+ *   500 `internal` when `handle` throws or returns something else.
+ * Every response carries `x-content-type-options: nosniff` and
+ * `content-security-policy: default-src 'none'`, which the plugin cannot override; plugin-set
+ * `set-cookie`, `content-length`, `transfer-encoding`, `connection` and `keep-alive` are dropped.
+ */
+export interface ChannelWebhook {
+    handle(args: {
+        connectionId: string;
+        config: unknown;
+        request: ChannelWebhookRequest;
+        signal: AbortSignal;
+    }): Promise<ChannelWebhookResult>;
+}
+/** 渠道实现（bot 用渠道连接配置）。 */
+export interface Channel {
+    /** 渠道连接配置的 schema；密钥字段用 secret()。 */
+    connectionSchema: ZodTypeAny;
+    /**
+     * `minEditIntervalMs`：平台允许的同一条消息两次编辑的最小间隔；内核流式草稿的更新间隔取
+     * `max(1000, minEditIntervalMs)`。
+     */
+    features: {
+        cards: boolean;
+        edit: boolean;
+        threads: boolean;
+        minEditIntervalMs?: number;
+    };
+    verify(args: {
+        config: unknown;
+        signal: AbortSignal;
+    }): Promise<{
+        botUserId: string;
+        botName: string;
+        tenantId: string;
+    }>;
+    /** 长连接循环：signal 中止时返回；断线自行重连。 */
+    connect(args: ChannelConnectArgs): Promise<void>;
+    /** 失败时抛 {@link ChannelSendError} 说明能否重试；其他异常内核按可重试处理（次数有限）。 */
+    send(args: ChannelSendArgs): Promise<{
+        messageId: string;
+    }>;
+    /**
+     * features.edit 为 false 的渠道不会被调用。失败语义同 send。新文本超过平台单条上限、无法改成一条时
+     * 抛不可重试的 {@link ChannelSendError}（`reason: "too_large"`）：内核改为把完整文本作为新消息 `send`
+     * （由插件拆分）。
+     */
+    update(args: ChannelSendArgs & {
+        messageId: string;
+    }): Promise<void>;
+    /**
+     * Optional webhook inbound (see {@link ChannelWebhook}). Only connections of plugins that
+     * implement it can be switched from the default long connection to webhook mode; a connection in
+     * webhook mode gets no `connect` call.
+     */
+    webhook?: ChannelWebhook;
+}
+/**
+ * 不可重试失败的原因（`ChannelSendError.reason`），内核据此处理：
+ * - `auth`：凭据失效 / 权限被收回 → 记连接 `last_error`，停止该会话本轮的投递；
+ * - `target_gone`：机器人被移出群、会话不存在 → 停止该会话本轮的投递，不计入毒事件；
+ * - `rejected`（内容被平台拒绝）、`too_large`（拆分后仍超限，如卡片过大）→ 按同一事件失败计数，满 3 次跳过它。
+ * 未给出原因的按 `rejected` 处理。
+ */
+export type ChannelSendFailure = "auth" | "target_gone" | "rejected" | "too_large";
+/**
+ * 渠道发送 / 更新消息失败的分类：`retryable` 为 true（限流、平台 5xx、网络）时内核退避后重试，
+ * `retryAfterMs` 为平台给出的建议等待时长；为 false 时按 `reason`（见 {@link ChannelSendFailure}）处理。
+ * 编辑流式草稿不可重试地失败（`auth` / `target_gone` 除外）时，内核改为把完整文本作为新消息发出。
+ * 消息里不要带凭据。
+ */
+export declare class ChannelSendError extends Error {
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number;
+    readonly reason?: ChannelSendFailure;
+    constructor(message: string, opts: {
+        retryable: boolean;
+        retryAfterMs?: number;
+        reason?: ChannelSendFailure;
+        cause?: unknown;
+    });
+}
+/** 鸭子类型判断（不用 instanceof），兼容插件自带另一份 plugin-sdk 副本的情况。 */
+export declare function isChannelSendError(e: unknown): e is ChannelSendError;

package/dist/channel.js

@@ -0,0 +1,26 @@
+/**
+ * 渠道发送 / 更新消息失败的分类：`retryable` 为 true（限流、平台 5xx、网络）时内核退避后重试，
+ * `retryAfterMs` 为平台给出的建议等待时长；为 false 时按 `reason`（见 {@link ChannelSendFailure}）处理。
+ * 编辑流式草稿不可重试地失败（`auth` / `target_gone` 除外）时，内核改为把完整文本作为新消息发出。
+ * 消息里不要带凭据。
+ */
+export class ChannelSendError extends Error {
+    retryable;
+    retryAfterMs;
+    reason;
+    constructor(message, opts) {
+        super(message, "cause" in opts ? { cause: opts.cause } : undefined);
+        this.name = "ChannelSendError";
+        this.retryable = opts.retryable;
+        if (opts.retryAfterMs !== undefined)
+            this.retryAfterMs = opts.retryAfterMs;
+        if (opts.reason !== undefined)
+            this.reason = opts.reason;
+    }
+}
+/** 鸭子类型判断（不用 instanceof），兼容插件自带另一份 plugin-sdk 副本的情况。 */
+export function isChannelSendError(e) {
+    return (e instanceof Error &&
+        e.name === "ChannelSendError" &&
+        typeof e.retryable === "boolean");
+}

package/dist/connector-auth.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+/** 认证方式：只有类型与非密钥字段；凭据值走内核的 `credential` / 凭据接口。 */
+export declare const ConnectorAuthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"none">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"bearer">;
+    ownership: z.ZodEnum<{
+        org: "org";
+        personal: "personal";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"api_key">;
+    ownership: z.ZodEnum<{
+        org: "org";
+        personal: "personal";
+    }>;
+    in: z.ZodEnum<{
+        header: "header";
+        query: "query";
+    }>;
+    name: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"basic">;
+    ownership: z.ZodEnum<{
+        org: "org";
+        personal: "personal";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"headers">;
+    ownership: z.ZodEnum<{
+        org: "org";
+        personal: "personal";
+    }>;
+    names: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"oauth_code">;
+    ownership: z.ZodLiteral<"personal">;
+    discovery: z.ZodEnum<{
+        manual: "manual";
+        mcp: "mcp";
+    }>;
+    authorizationUrl: z.ZodOptional<z.ZodURL>;
+    tokenUrl: z.ZodOptional<z.ZodURL>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    client: z.ZodEnum<{
+        dcr: "dcr";
+        manual: "manual";
+    }>;
+    tokenAuthMethod: z.ZodOptional<z.ZodEnum<{
+        client_secret_basic: "client_secret_basic";
+        client_secret_post: "client_secret_post";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"oauth_client">;
+    ownership: z.ZodLiteral<"org">;
+    tokenUrl: z.ZodURL;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tokenAuthMethod: z.ZodOptional<z.ZodEnum<{
+        client_secret_basic: "client_secret_basic";
+        client_secret_post: "client_secret_post";
+    }>>;
+}, z.core.$strict>], "type">;
+/** 认证预设（{@link ConnectorAuthSchema} 的输出）。 */
+export type ConnectorAuthPreset = z.infer<typeof ConnectorAuthSchema>;

package/dist/connector-auth.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+/*
+ * 连接器的认证方式（只有类型与非密钥字段，凭据值不在这里）：内核的连接器安装接口与企业目录里的连接器模板
+ * （`ConnectorTemplateSpec.auth`）共用这一个 schema。各分支都是 strict：多出的字段（如 `token`）一律拒绝，
+ * 所以合法的认证预设里不可能夹带凭据。OAuth 端点是否必须 https 由内核按部署配置再校验。
+ */
+/** HTTP 头名（RFC 9110 token）。 */
+const HeaderName = z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/, "Invalid header name");
+const Ownership = z.enum(["org", "personal"]);
+/** OAuth 端点（https 等由内核按部署配置再校验）。 */
+const OAuthUrl = z.url().max(2000);
+/** 令牌端点的客户端认证方式（有客户端密钥时）。 */
+const TokenAuthMethod = z.enum(["client_secret_basic", "client_secret_post"]);
+/** OAuth scope（RFC 6749 §3.3 scope-token）。 */
+const Scopes = z
+    .array(z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[\x21\x23-\x5B\x5D-\x7E]+$/, "Invalid scope"))
+    .max(50);
+/** 认证方式：只有类型与非密钥字段；凭据值走内核的 `credential` / 凭据接口。 */
+export const ConnectorAuthSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("none") }).strict(),
+    z.object({ type: z.literal("bearer"), ownership: Ownership }).strict(),
+    z
+        .object({
+        type: z.literal("api_key"),
+        ownership: Ownership,
+        in: z.enum(["header", "query"]),
+        name: z.string().min(1).max(100),
+    })
+        .strict()
+        .refine((a) => a.in === "query" || HeaderName.safeParse(a.name).success, {
+        path: ["name"],
+        message: "Invalid header name",
+    }),
+    z.object({ type: z.literal("basic"), ownership: Ownership }).strict(),
+    z
+        .object({
+        type: z.literal("headers"),
+        ownership: Ownership,
+        names: z.array(HeaderName).min(1).max(20),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("oauth_code"),
+        ownership: z.literal("personal"),
+        discovery: z.enum(["mcp", "manual"]),
+        authorizationUrl: OAuthUrl.optional(),
+        tokenUrl: OAuthUrl.optional(),
+        scopes: Scopes.optional(),
+        client: z.enum(["dcr", "manual"]),
+        tokenAuthMethod: TokenAuthMethod.optional(),
+    })
+        .strict()
+        .superRefine((a, ctx) => {
+        if (a.discovery === "manual") {
+            for (const k of ["authorizationUrl", "tokenUrl"]) {
+                if (a[k] === undefined)
+                    ctx.addIssue({ code: "custom", path: [k], message: "Required with discovery manual" });
+            }
+        }
+        else {
+            for (const k of ["authorizationUrl", "tokenUrl"]) {
+                if (a[k] !== undefined)
+                    ctx.addIssue({
+                        code: "custom",
+                        path: [k],
+                        message: "Endpoints are discovered with discovery mcp; omit this field",
+                    });
+            }
+        }
+        if (a.client === "dcr" && a.discovery !== "mcp") {
+            ctx.addIssue({
+                code: "custom",
+                path: ["client"],
+                message: "Dynamic client registration requires discovery mcp",
+            });
+        }
+    }),
+    z
+        .object({
+        type: z.literal("oauth_client"),
+        ownership: z.literal("org"),
+        tokenUrl: OAuthUrl,
+        scopes: Scopes.optional(),
+        tokenAuthMethod: TokenAuthMethod.optional(),
+    })
+        .strict(),
+]);