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

package/dist/setup/kernel-checks.d.ts

@@ -0,0 +1,91 @@
+import { type SetupCheckResult, type SetupCheckText } from "@capybara-hq/plugin-sdk";
+import { type OnModuleInit } from "@nestjs/common";
+import type { Redis } from "ioredis";
+import { webhookBase } from "../channels/webhook-url.js";
+import type { KernelConfig } from "../config/schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { Credentials } from "../tools/credentials.js";
+import { SetupCheckRegistry } from "./setup-check-registry.js";
+/** The fixed texts of the kernel checks (only `last_error` and a time are ever interpolated). */
+export declare const KERNEL_CHECK_TEXTS: {
+    readonly publicUrlSet: SetupCheckText;
+    readonly publicUrlMissing: SetupCheckText;
+    readonly publicUrlFix: SetupCheckText;
+    readonly webhookPublic: SetupCheckText;
+    readonly webhookBaseMissing: SetupCheckText;
+    readonly webhookBaseFix: SetupCheckText;
+    readonly webhookNone: SetupCheckText;
+    readonly connectionGone: SetupCheckText;
+    readonly connectionDisabled: SetupCheckText;
+    readonly connectionEnableFix: SetupCheckText;
+    readonly connectionFailed: SetupCheckText;
+    readonly connectionFix: SetupCheckText;
+    readonly connectionPending: SetupCheckText;
+    readonly connectionActive: SetupCheckText;
+    readonly connectorGone: SetupCheckText;
+    readonly notOAuthCode: SetupCheckText;
+    readonly dcr: SetupCheckText;
+    readonly clientStored: SetupCheckText;
+    readonly clientMissing: SetupCheckText;
+    readonly clientFix: SetupCheckText;
+    readonly noClient: SetupCheckText;
+    readonly toolsRead: SetupCheckText;
+    readonly toolsPending: SetupCheckText;
+    readonly connected: SetupCheckText;
+    readonly notConnected: SetupCheckText;
+    readonly connectFix: SetupCheckText;
+    readonly publicUrlFirst: SetupCheckText;
+};
+/** `capybara:public-url`: `http.publicUrl` is set. */
+export declare function publicUrlCheck(config: Pick<KernelConfig, "http">): SetupCheckResult;
+/**
+ * `capybara:webhook-public`: webhook callback URLs have a usable https base. The kernel builds
+ * them from `channels.webhookBaseUrl` only (`webhook-url.ts`), never from `http.publicUrl`, so
+ * that is what is checked; a loopback http base (tests only) is not public.
+ */
+export declare function webhookPublicCheck(config: Parameters<typeof webhookBase>[0]): SetupCheckResult;
+/** `capybara:webhook-received`: the marker the gateway sets on an accepted webhook, or none. */
+export declare function webhookReceivedResult(seenAt: string | null): SetupCheckResult;
+/**
+ * `capybara:connection-active`: active with a bot identity and no recorded error is ok. A recorded
+ * `last_error` (status `error`, or a failure an active connection keeps retrying) is failing with
+ * that text, redacted by every secret the result is redacted by and kept only when the result
+ * with it passes the result validation (control, bidi and lone surrogate rules, length);
+ * otherwise the reason leaves it out. The kernel pipeline validates and redacts the result again.
+ */
+export declare function connectionActiveResult(row: {
+    status: string;
+    botUserId: string | null;
+    lastError: string | null;
+} | undefined, secrets: readonly string[]): SetupCheckResult;
+/**
+ * Registers the kernel checks on module init (static code, the same on every replica). Each reads
+ * only the target the service resolved (ids of the caller's org, after authorization) and never
+ * writes; `capybara:oauth-token-endpoint` is the only one that leaves the kernel (§10.6).
+ */
+export declare class KernelChecks implements OnModuleInit {
+    private readonly registry;
+    private readonly config;
+    private readonly db;
+    private readonly redis;
+    private readonly credentials;
+    constructor(registry: SetupCheckRegistry, config: Pick<KernelConfigService, "get">, db: KernelDb, redis: Pick<Redis, "get">, credentials: Pick<Credentials, "oauthClient" | "status">);
+    onModuleInit(): void;
+    private webhookReceived;
+    private connectionActive;
+    /** The connector's auth settings (a live connector of the caller's org), or undefined. */
+    private connectorAuth;
+    private oauthClient;
+    private connectorTools;
+    /** The caller's own credential (cached per account, as every kernel check). */
+    private connectorConnected;
+    /**
+     * The token endpoint probe for a manual OAuth client (`oauth-token-probe.ts`): the stored
+     * client record is the connect flow's (its `tokenEndpoint` came from discovery or the
+     * template's `tokenUrl` at install, its auth method from `tokenAuthMethod`), the redirect URI
+     * is the connect flow's callback URL. Runs per admin (kernel checks are cached per account);
+     * each run is one token request, inside the per-account rate limit and the org's cap.
+     */
+    private tokenEndpoint;
+}

package/dist/setup/kernel-checks.js

@@ -0,0 +1,295 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+// The kernel's own setup checks, `capybara:*` (spec 2026-11-09-setup-guides-v2-design.md §10.6):
+// answered from the kernel's state with no plugin code, usable by any guide of their place. They go
+// through the same `SetupChecksService` pipeline as plugin checks (authorization, the rendered
+// guide, cache, single flight, the org's concurrency cap, the time limit, validate / redact /
+// validate), and are cached per account like every kernel check.
+import { validateSetupCheckResult, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { webhookSeenKey } from "../channels/webhook.js";
+import { webhookBase } from "../channels/webhook-url.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { REDIS } from "../infra/tokens.js";
+import { Credentials } from "../tools/credentials.js";
+import { callbackUrl } from "../tools/oauth/flow-paths.js";
+import { probeNetPolicy, probeTokenEndpoint } from "./oauth-token-probe.js";
+import { checkRedactor } from "./redact-check.js";
+import { SetupCheckRegistry } from "./setup-check-registry.js";
+const text = (en, zh) => ({ en, zh });
+/** The fixed texts of the kernel checks (only `last_error` and a time are ever interpolated). */
+export const KERNEL_CHECK_TEXTS = {
+    publicUrlSet: text("The public URL (http.publicUrl) is set.", "公开地址（http.publicUrl）已设置。"),
+    publicUrlMissing: text("The public URL (http.publicUrl) is not set.", "公开地址（http.publicUrl）没有设置。"),
+    publicUrlFix: text("Ask your super admin to set http.publicUrl.", "请超级管理员设置 http.publicUrl。"),
+    webhookPublic: text("Webhook callbacks have a public https address (channels.webhookBaseUrl).", "Webhook 回调有公开的 https 地址（channels.webhookBaseUrl）。"),
+    webhookBaseMissing: text("No public https address is set for webhook callbacks (channels.webhookBaseUrl).", "没有为 Webhook 回调设置公开的 https 地址（channels.webhookBaseUrl）。"),
+    webhookBaseFix: text("Ask your super admin to set channels.webhookBaseUrl to an https address that reaches the gateway.", "请超级管理员把 channels.webhookBaseUrl 设置为能到达网关的 https 地址。"),
+    webhookNone: text("No verified webhook request has arrived in the last 7 days.", "最近 7 天没有收到通过校验的 Webhook 请求。"),
+    connectionGone: text("The connection was not found.", "找不到这个连接。"),
+    connectionDisabled: text("The connection is disabled.", "这个连接已停用。"),
+    connectionEnableFix: text("Enable the connection.", "启用这个连接。"),
+    connectionFailed: text("The connection reported an error.", "这个连接报告了错误。"),
+    connectionFix: text("Check the credentials on this page and save them again.", "检查本页的凭据并重新保存。"),
+    connectionPending: text("The connection has not reported its bot identity yet; retry in a moment.", "这个连接还没有报告机器人身份，请稍后重试。"),
+    connectionActive: text("The connection is active.", "这个连接正常运行。"),
+    connectorGone: text("The connector was not found.", "找不到这个连接器。"),
+    notOAuthCode: text("This connector does not use an OAuth client.", "这个连接器不使用 OAuth 客户端。"),
+    dcr: text("Registered automatically; nothing to check.", "客户端是自动注册的，无需检查。"),
+    clientStored: text("The OAuth client id and secret are stored.", "OAuth 客户端 ID 和密钥已保存。"),
+    clientMissing: text("The OAuth client id or secret is not stored.", "OAuth 客户端 ID 或密钥没有保存。"),
+    clientFix: text("Enter the Client ID and Client Secret on the connector's page.", "在连接器页面填写 Client ID 和 Client Secret。"),
+    noClient: text("No OAuth client is stored yet.", "还没有保存 OAuth 客户端。"),
+    toolsRead: text("The connector's tool list has been read.", "已读取这个连接器的工具清单。"),
+    toolsPending: text("The tool list is read when the first member connects.", "第一位成员连接后会读取工具清单。"),
+    connected: text("You are connected.", "你已连接。"),
+    notConnected: text("You have not connected your account yet.", "你还没有连接自己的账号。"),
+    connectFix: text("Select Connect and sign in.", "选择「连接」并登录。"),
+    publicUrlFirst: text("The callback URL needs http.publicUrl; ask your super admin to set it.", "回调地址需要 http.publicUrl，请超级管理员设置。"),
+};
+/** `capybara:public-url`: `http.publicUrl` is set. */
+export function publicUrlCheck(config) {
+    return config.http.publicUrl
+        ? { status: "ok", reason: KERNEL_CHECK_TEXTS.publicUrlSet }
+        : {
+            status: "failing",
+            reason: KERNEL_CHECK_TEXTS.publicUrlMissing,
+            fix: KERNEL_CHECK_TEXTS.publicUrlFix,
+        };
+}
+/**
+ * `capybara:webhook-public`: webhook callback URLs have a usable https base. The kernel builds
+ * them from `channels.webhookBaseUrl` only (`webhook-url.ts`), never from `http.publicUrl`, so
+ * that is what is checked; a loopback http base (tests only) is not public.
+ */
+export function webhookPublicCheck(config) {
+    const base = webhookBase(config);
+    return base?.startsWith("https://")
+        ? { status: "ok", reason: KERNEL_CHECK_TEXTS.webhookPublic }
+        : {
+            status: "failing",
+            reason: KERNEL_CHECK_TEXTS.webhookBaseMissing,
+            fix: KERNEL_CHECK_TEXTS.webhookBaseFix,
+        };
+}
+/** `capybara:webhook-received`: the marker the gateway sets on an accepted webhook, or none. */
+export function webhookReceivedResult(seenAt) {
+    const at = seenAt === null ? Number.NaN : Date.parse(seenAt);
+    if (Number.isNaN(at))
+        return { status: "unknown", reason: KERNEL_CHECK_TEXTS.webhookNone };
+    const iso = new Date(at).toISOString();
+    return {
+        status: "ok",
+        reason: text(`A verified webhook request arrived at ${iso}.`, `${iso} 收到过通过校验的 Webhook 请求。`),
+    };
+}
+/** The most of `last_error` a reason carries (after redaction). */
+const LAST_ERROR_CHARS = 200;
+/**
+ * `last_error` fit for a reason: redacted over the whole text first by every secret the result is
+ * redacted by (the connection's and the plugin's config secrets: a cut never leaves part of a
+ * secret behind), then cut to {@link LAST_ERROR_CHARS} code points.
+ */
+function lastErrorText(lastError, secrets) {
+    const redacted = checkRedactor(secrets)(lastError);
+    const points = [...redacted];
+    return points.length > LAST_ERROR_CHARS
+        ? `${points.slice(0, LAST_ERROR_CHARS).join("")}…`
+        : redacted;
+}
+/**
+ * `capybara:connection-active`: active with a bot identity and no recorded error is ok. A recorded
+ * `last_error` (status `error`, or a failure an active connection keeps retrying) is failing with
+ * that text, redacted by every secret the result is redacted by and kept only when the result
+ * with it passes the result validation (control, bidi and lone surrogate rules, length);
+ * otherwise the reason leaves it out. The kernel pipeline validates and redacts the result again.
+ */
+export function connectionActiveResult(row, secrets) {
+    if (!row)
+        return { status: "unknown", reason: KERNEL_CHECK_TEXTS.connectionGone };
+    if (row.status === "disabled") {
+        return {
+            status: "failing",
+            reason: KERNEL_CHECK_TEXTS.connectionDisabled,
+            fix: KERNEL_CHECK_TEXTS.connectionEnableFix,
+        };
+    }
+    if (row.status === "error" || (row.lastError !== null && row.lastError !== "")) {
+        const generic = {
+            status: "failing",
+            reason: KERNEL_CHECK_TEXTS.connectionFailed,
+            fix: KERNEL_CHECK_TEXTS.connectionFix,
+        };
+        if (row.lastError === null || row.lastError === "")
+            return generic;
+        const detail = lastErrorText(row.lastError, secrets);
+        const withError = validateSetupCheckResult({
+            ...generic,
+            reason: text(`The connection reported an error: ${detail}`, `这个连接报告了错误：${detail}`),
+        });
+        return "problem" in withError ? generic : withError;
+    }
+    if (row.botUserId === null || row.botUserId === "") {
+        return { status: "unknown", reason: KERNEL_CHECK_TEXTS.connectionPending };
+    }
+    return { status: "ok", reason: KERNEL_CHECK_TEXTS.connectionActive };
+}
+/**
+ * Registers the kernel checks on module init (static code, the same on every replica). Each reads
+ * only the target the service resolved (ids of the caller's org, after authorization) and never
+ * writes; `capybara:oauth-token-endpoint` is the only one that leaves the kernel (§10.6).
+ */
+let KernelChecks = class KernelChecks {
+    registry;
+    config;
+    db;
+    redis;
+    credentials;
+    constructor(registry, config, db, redis, credentials) {
+        this.registry = registry;
+        this.config = config;
+        this.db = db;
+        this.redis = redis;
+        this.credentials = credentials;
+    }
+    onModuleInit() {
+        const r = this.registry;
+        r.registerKernel("capybara:public-url", "any", async () => publicUrlCheck(this.config.get()));
+        r.registerKernel("capybara:webhook-public", "channel-connection", async () => webhookPublicCheck(this.config.get()));
+        r.registerKernel("capybara:webhook-received", "channel-connection", (a) => this.webhookReceived(a));
+        r.registerKernel("capybara:connection-active", "channel-connection", (a) => this.connectionActive(a));
+        r.registerKernel("capybara:oauth-client", "connector-template", (a) => this.oauthClient(a));
+        r.registerKernel("capybara:connector-tools", "connector-template", (a) => this.connectorTools(a));
+        r.registerKernel("capybara:connector-connected", "connector-template", (a) => this.connectorConnected(a));
+        r.registerKernel("capybara:oauth-token-endpoint", "connector-template", (a) => this.tokenEndpoint(a));
+    }
+    async webhookReceived(a) {
+        if (a.target.kind !== "channel-connection")
+            return notApplicable();
+        return webhookReceivedResult(await this.redis.get(webhookSeenKey(a.target.connectionId)));
+    }
+    async connectionActive(a) {
+        if (a.target.kind !== "channel-connection")
+            return notApplicable();
+        const row = await this.db
+            .selectFrom("channel_connections")
+            .select(["status", "bot_user_id", "last_error"])
+            .where("id", "=", a.target.connectionId)
+            .where("org_id", "=", a.orgId)
+            .where("plugin", "=", a.target.plugin)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return connectionActiveResult(row && { status: row.status, botUserId: row.bot_user_id, lastError: row.last_error }, a.secrets);
+    }
+    /** The connector's auth settings (a live connector of the caller's org), or undefined. */
+    async connectorAuth(a) {
+        if (a.target.kind !== "connector")
+            return undefined;
+        const row = await this.db
+            .selectFrom("connectors")
+            .select("auth")
+            .where("id", "=", a.target.connectorId)
+            .where("org_id", "=", a.orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return row ? row.auth : undefined;
+    }
+    async oauthClient(a) {
+        const auth = await this.connectorAuth(a);
+        if (!auth || a.target.kind !== "connector")
+            return connectorGone();
+        if (auth.type !== "oauth_code")
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.notOAuthCode };
+        if (auth.client === "dcr")
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.dcr };
+        const client = await this.credentials.oauthClient(a.orgId, a.target.connectorId);
+        return client && client.clientId !== "" && client.clientSecret
+            ? { status: "ok", reason: KERNEL_CHECK_TEXTS.clientStored }
+            : {
+                status: "failing",
+                reason: KERNEL_CHECK_TEXTS.clientMissing,
+                fix: KERNEL_CHECK_TEXTS.clientFix,
+            };
+    }
+    async connectorTools(a) {
+        if (a.target.kind !== "connector" || !(await this.connectorAuth(a)))
+            return connectorGone();
+        const tool = await this.db
+            .selectFrom("connector_tools")
+            .select("name")
+            .where("connector_id", "=", a.target.connectorId)
+            .limit(1)
+            .executeTakeFirst();
+        return tool
+            ? { status: "ok", reason: KERNEL_CHECK_TEXTS.toolsRead }
+            : { status: "unknown", reason: KERNEL_CHECK_TEXTS.toolsPending };
+    }
+    /** The caller's own credential (cached per account, as every kernel check). */
+    async connectorConnected(a) {
+        const auth = await this.connectorAuth(a);
+        if (!auth || a.target.kind !== "connector")
+            return connectorGone();
+        const s = await this.credentials.status(a.orgId, a.target.connectorId, auth, a.accountId);
+        return s === "connected"
+            ? { status: "ok", reason: KERNEL_CHECK_TEXTS.connected }
+            : {
+                status: "failing",
+                reason: KERNEL_CHECK_TEXTS.notConnected,
+                fix: KERNEL_CHECK_TEXTS.connectFix,
+            };
+    }
+    /**
+     * The token endpoint probe for a manual OAuth client (`oauth-token-probe.ts`): the stored
+     * client record is the connect flow's (its `tokenEndpoint` came from discovery or the
+     * template's `tokenUrl` at install, its auth method from `tokenAuthMethod`), the redirect URI
+     * is the connect flow's callback URL. Runs per admin (kernel checks are cached per account);
+     * each run is one token request, inside the per-account rate limit and the org's cap.
+     */
+    async tokenEndpoint(a) {
+        const auth = await this.connectorAuth(a);
+        if (!auth || a.target.kind !== "connector")
+            return connectorGone();
+        if (auth.type !== "oauth_code")
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.notOAuthCode };
+        if (auth.client === "dcr")
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.dcr };
+        const config = this.config.get();
+        const publicUrl = config.http.publicUrl;
+        if (!publicUrl)
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.publicUrlFirst };
+        const client = await this.credentials.oauthClient(a.orgId, a.target.connectorId);
+        if (!client)
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.noClient };
+        return probeTokenEndpoint({
+            client,
+            redirectUri: callbackUrl(publicUrl),
+            net: probeNetPolicy(config),
+            signal: a.signal,
+        });
+    }
+};
+KernelChecks = __decorate([
+    Injectable(),
+    __param(0, Inject(SetupCheckRegistry)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(KernelDb)),
+    __param(3, Inject(REDIS)),
+    __param(4, Inject(Credentials))
+], KernelChecks);
+export { KernelChecks };
+const notApplicable = () => ({
+    status: "unknown",
+    reason: text("This check does not apply on this page.", "这项检查不适用于本页面。"),
+});
+const connectorGone = () => ({
+    status: "unknown",
+    reason: KERNEL_CHECK_TEXTS.connectorGone,
+});

package/dist/setup/oauth-token-probe.d.ts

@@ -0,0 +1,47 @@
+import type { SetupCheckResult, SetupCheckText } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { NetPolicy } from "../net/public-address.js";
+import { safeFetch } from "../net/safe-fetch.js";
+import { type OAuthClientRecord } from "../tools/oauth/tokens.js";
+/** The authorization code the probe sends: never a code any server issued. */
+export declare const PROBE_CODE = "capybara-setup-probe";
+/** The probe's fixed texts: nothing a token endpoint sends ever reaches a result. */
+export declare const PROBE_TEXTS: {
+    readonly accepted: SetupCheckText;
+    readonly clientRefused: SetupCheckText;
+    readonly clientFix: SetupCheckText;
+    readonly redirectRefused: SetupCheckText;
+    readonly unknown: SetupCheckText;
+    readonly netDenied: SetupCheckText;
+};
+/**
+ * The fix of a redirect refusal: the kernel-built callback URL (never anything the endpoint
+ * said): `http.publicUrl` + the fixed callback path. (A public URL so long that the fix passes
+ * its limit makes the result invalid, which the kernel answers as unknown.)
+ */
+export declare const redirectFix: (callbackUrl: string) => SetupCheckText;
+/**
+ * The network rules of the probe: the deployment's egress proxy (`net.httpsProxy` /
+ * `net.noProxy`), its private host exemptions (`marketplaces.allowPrivateHosts`, the one list of
+ * internal hosts the kernel may reach) and loopback http only under
+ * `tools.oauthAllowInsecureLoopback` (tests), as for every other OAuth URL.
+ */
+export declare function probeNetPolicy(config: KernelConfig): NetPolicy;
+export interface TokenProbeInput {
+    /** The stored client: its `tokenEndpoint` is the one the connect flow posts codes to. */
+    client: OAuthClientRecord;
+    /** The connect flow's redirect URI (`http.publicUrl` + the callback path). */
+    redirectUri: string;
+    net: NetPolicy;
+    /** The run's signal (the kernel's time limit). */
+    signal: AbortSignal;
+    /** Tests only: the network calls (defaults to {@link safeFetch}). */
+    fetch?: typeof safeFetch;
+}
+/**
+ * Probes the token endpoint (spec §10.6 table): `invalid_grant` / Slack `invalid_code` → ok; a
+ * refused client (or any other 401) → failing with the copy-again fix; a refused redirect URI →
+ * failing with the callback URL; anything else (429, 5xx, a network error, a redirect, a 2xx) →
+ * unknown. Never throws, never logs; the answer is read only for its refusal code and dropped.
+ */
+export declare function probeTokenEndpoint(input: TokenProbeInput): Promise<SetupCheckResult>;

package/dist/setup/oauth-token-probe.js

@@ -0,0 +1,108 @@
+import { NetDeniedError } from "../net/public-address.js";
+import { safeFetch } from "../net/safe-fetch.js";
+import { parseTokenRefusal, tokenRequestInit, } from "../tools/oauth/tokens.js";
+/** The authorization code the probe sends: never a code any server issued. */
+export const PROBE_CODE = "capybara-setup-probe";
+/** A fixed PKCE verifier (43 characters, RFC 7636), so a server that demands one reads the code. */
+const PROBE_VERIFIER = "capybara-setup-probe-verifier-0000000000000";
+/** The most of a token endpoint answer the probe reads (an error body is a few hundred bytes). */
+const PROBE_MAX_BYTES = 64 * 1024;
+/** Codes that say the client authenticated and only the code was bad, as intended. */
+const ACCEPTED = new Set(["invalid_grant", "invalid_code"]);
+/** Codes that say the client id or secret is wrong (RFC 6749 and Slack's). */
+const CLIENT_REFUSED = new Set([
+    "invalid_client",
+    "unauthorized_client",
+    "invalid_client_id",
+    "bad_client_secret",
+]);
+/** Codes that say the redirect URI is not registered (RFC 6749 servers and Slack's). */
+const REDIRECT_REFUSED = new Set(["redirect_uri_mismatch", "bad_redirect_uri"]);
+const text = (en, zh) => ({ en, zh });
+/** The probe's fixed texts: nothing a token endpoint sends ever reaches a result. */
+export const PROBE_TEXTS = {
+    accepted: text("The token endpoint accepted the client.", "令牌端点接受了这个客户端。"),
+    clientRefused: text("The token endpoint refused the client id or secret.", "令牌端点拒绝了客户端 ID 或密钥。"),
+    clientFix: text("Copy the Client ID and Client Secret again from the app's Basic Information page.", "从应用的 Basic Information 页面重新复制 Client ID 和 Client Secret。"),
+    redirectRefused: text("The app does not list the callback URL.", "应用的重定向地址里没有这个回调地址。"),
+    unknown: text("Could not verify the client; retry later.", "无法验证这个客户端，请稍后重试。"),
+    netDenied: text("The token endpoint's address is refused by this deployment's network rules; ask your super admin.", "这个部署的网络规则拒绝访问令牌端点的地址，请联系超级管理员。"),
+};
+/**
+ * The fix of a redirect refusal: the kernel-built callback URL (never anything the endpoint
+ * said): `http.publicUrl` + the fixed callback path. (A public URL so long that the fix passes
+ * its limit makes the result invalid, which the kernel answers as unknown.)
+ */
+export const redirectFix = (callbackUrl) => text(`Add ${callbackUrl} to the app's redirect URLs.`, `把 ${callbackUrl} 加到应用的重定向地址（Redirect URLs）里。`);
+/**
+ * The network rules of the probe: the deployment's egress proxy (`net.httpsProxy` /
+ * `net.noProxy`), its private host exemptions (`marketplaces.allowPrivateHosts`, the one list of
+ * internal hosts the kernel may reach) and loopback http only under
+ * `tools.oauthAllowInsecureLoopback` (tests), as for every other OAuth URL.
+ */
+export function probeNetPolicy(config) {
+    return {
+        allowInsecureLoopback: config.tools.oauthAllowInsecureLoopback,
+        allowPrivateHosts: config.marketplaces.allowPrivateHosts,
+        trustedOrigins: [],
+        ...(config.net.httpsProxy !== undefined && {
+            proxy: { url: config.net.httpsProxy, noProxy: config.net.noProxy },
+        }),
+    };
+}
+/**
+ * Probes the token endpoint (spec §10.6 table): `invalid_grant` / Slack `invalid_code` → ok; a
+ * refused client (or any other 401) → failing with the copy-again fix; a refused redirect URI →
+ * failing with the callback URL; anything else (429, 5xx, a network error, a redirect, a 2xx) →
+ * unknown. Never throws, never logs; the answer is read only for its refusal code and dropped.
+ */
+export async function probeTokenEndpoint(input) {
+    const { client } = input;
+    const { headers, body } = tokenRequestInit(client, {
+        grant_type: "authorization_code",
+        code: PROBE_CODE,
+        redirect_uri: input.redirectUri,
+        code_verifier: PROBE_VERIFIER,
+        resource: client.resource,
+    });
+    let status;
+    let parsed;
+    try {
+        const res = await (input.fetch ?? safeFetch)(client.tokenEndpoint, { method: "POST", headers, body: body.toString(), signal: input.signal }, input.net, { maxBytes: PROBE_MAX_BYTES });
+        status = res.status;
+        // only an answer that can carry a refusal is read (400 / 401, or a 200 error body of
+        // dialects like Slack's); other bodies are dropped unread
+        if (status === 200 || status === 400 || status === 401) {
+            try {
+                parsed = JSON.parse(await res.text());
+            }
+            catch {
+                parsed = undefined;
+            }
+        }
+        else {
+            await res.body?.cancel().catch(() => { });
+        }
+    }
+    catch (e) {
+        if (e instanceof NetDeniedError && e.code !== "net.redirect" && e.code !== "net.dns_failed") {
+            return { status: "unknown", reason: PROBE_TEXTS.netDenied };
+        }
+        return { status: "unknown", reason: PROBE_TEXTS.unknown };
+    }
+    // only the refusal code is taken from the answer; a 2xx token is never looked at or kept
+    const code = parseTokenRefusal(status, parsed);
+    if (code !== null && ACCEPTED.has(code))
+        return { status: "ok", reason: PROBE_TEXTS.accepted };
+    if (code !== null && REDIRECT_REFUSED.has(code)) {
+        return {
+            status: "failing",
+            reason: PROBE_TEXTS.redirectRefused,
+            fix: redirectFix(input.redirectUri),
+        };
+    }
+    if ((code !== null && CLIENT_REFUSED.has(code)) || status === 401) {
+        return { status: "failing", reason: PROBE_TEXTS.clientRefused, fix: PROBE_TEXTS.clientFix };
+    }
+    return { status: "unknown", reason: PROBE_TEXTS.unknown };
+}

package/dist/setup/redact-check.d.ts

@@ -0,0 +1,18 @@
+import type { SetupCheckResult } from "@capybara-hq/plugin-sdk";
+/** The shortest secret value redacted from a check result (shorter values would hit plain words). */
+export declare const CHECK_SECRET_MIN_CHARS = 8;
+/** A redactor over the given secret values (only strings of at least 8 characters count). */
+export declare function checkRedactor(secrets: readonly unknown[]): (s: string) => string;
+/**
+ * A fresh plain object of a validated result with its texts redacted (validate it again: the
+ * redacted copy may be too long now). Only `status`, `reason` and `fix` are carried over.
+ */
+export declare function redactCheckResult(result: SetupCheckResult, redact: (s: string) => string): SetupCheckResult;
+/**
+ * What a log line may say about an error a check threw: its name and its redacted, shortened
+ * message, never the error object (a stack or a `cause` can carry what the message does not).
+ */
+export declare function describeCheckError(err: unknown, redact: (s: string) => string): {
+    name: string;
+    message: string;
+};

package/dist/setup/redact-check.js

@@ -0,0 +1,46 @@
+import { createRedactor } from "../log.js";
+/** The shortest secret value redacted from a check result (shorter values would hit plain words). */
+export const CHECK_SECRET_MIN_CHARS = 8;
+/** A redactor over the given secret values (only strings of at least 8 characters count). */
+export function checkRedactor(secrets) {
+    return createRedactor(secrets.filter((v) => typeof v === "string"), CHECK_SECRET_MIN_CHARS);
+}
+const redactText = (t, redact) => ({
+    en: redact(t.en),
+    ...(t.zh !== undefined && { zh: redact(t.zh) }),
+});
+/**
+ * A fresh plain object of a validated result with its texts redacted (validate it again: the
+ * redacted copy may be too long now). Only `status`, `reason` and `fix` are carried over.
+ */
+export function redactCheckResult(result, redact) {
+    return {
+        status: result.status,
+        ...(result.reason !== undefined && { reason: redactText(result.reason, redact) }),
+        ...(result.fix !== undefined && { fix: redactText(result.fix, redact) }),
+    };
+}
+/** The most of an extension's error message that reaches a log line (after redaction). */
+const ERROR_LOG_CHARS = 500;
+/**
+ * What a log line may say about an error a check threw: its name and its redacted, shortened
+ * message, never the error object (a stack or a `cause` can carry what the message does not).
+ */
+export function describeCheckError(err, redact) {
+    let name = "Error";
+    let message = "";
+    try {
+        if (err instanceof Error) {
+            name = typeof err.name === "string" ? err.name.slice(0, 64) : "Error";
+            message = typeof err.message === "string" ? err.message : "";
+        }
+        else {
+            name = typeof err;
+            message = typeof err === "string" ? err : "";
+        }
+    }
+    catch {
+        // a hostile error object (a throwing getter): nothing more to say about it
+    }
+    return { name: redact(name), message: redact(message).slice(0, ERROR_LOG_CHARS) };
+}