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

package/dist/channels/threads.js

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { audit } from "../identity/audit.js";
+/** 匿名访客账号的显示名。 */
+const ANONYMOUS_DISPLAY_NAME = "Anonymous guest";
+/** 匿名访客成员关系的来源标记（通讯录同步只撤销 `directory:*`，不会碰它）。 */
+const ANONYMOUS_MEMBERSHIP_SOURCE = "anonymous";
+/**
+ * 该组织唯一的匿名访客账号 id；首次使用时创建（`accounts.status = active`、没有任何登录方式、组织角色 guest）。
+ * 每次都确保成员关系存在（被移出后再次使用会补回 guest）：运行的兜底扫描会中止「发起人已不是该组织成员」的运行。
+ * 跨副本并发首次创建用事务级咨询锁串行化，只建一个账号。
+ */
+export async function ensureAnonymousGuest(db, orgId) {
+    return db.transaction().execute(async (t) => {
+        await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.anonymous:${orgId}`}))`.execute(t);
+        const existing = await t
+            .selectFrom("org_anonymous_accounts")
+            .select("account_id")
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        let accountId = existing?.account_id;
+        if (accountId === undefined) {
+            accountId = randomUUID();
+            await t
+                .insertInto("accounts")
+                .values({ id: accountId, display_name: ANONYMOUS_DISPLAY_NAME, email: null })
+                .execute();
+            await t
+                .insertInto("org_anonymous_accounts")
+                .values({ org_id: orgId, account_id: accountId })
+                .execute();
+            await audit(t, {
+                orgId,
+                action: "account.created",
+                target: accountId,
+                detail: { anonymousGuest: true },
+            });
+        }
+        await t
+            .insertInto("memberships")
+            .values({
+            org_id: orgId,
+            account_id: accountId,
+            role: "guest",
+            source: ANONYMOUS_MEMBERSHIP_SOURCE,
+        })
+            .onConflict((oc) => oc.columns(["org_id", "account_id"]).doNothing())
+            .execute();
+        return accountId;
+    });
+}
+/**
+ * 话题键：私聊 `dm:<externalId>`；群聊用平台话题 id，消息不在话题里（开启新话题）时用该消息 id——
+ * 机器人回复在以它为根的话题里，后续消息的 threadId 就是它，于是落到同一个对话。
+ */
+export function threadKeyOf(target, senderExternalId, messageId) {
+    if (target.chatType === "dm")
+        return `dm:${senderExternalId}`;
+    return target.threadId ?? messageId;
+}
+/** 未归档的话题行对应的会话；没有返回 undefined。 */
+export async function findThread(db, k) {
+    const row = await db
+        .selectFrom("channel_threads")
+        .select("conversation_id")
+        .where("connection_id", "=", k.connectionId)
+        .where("chat_id", "=", k.chatId)
+        .where("thread_key", "=", k.threadKey)
+        .where(sql `coalesce(account_id::text, '')`, "=", k.accountId ?? "")
+        .where("archived_at", "is", null)
+        .executeTakeFirst();
+    return row?.conversation_id;
+}
+/**
+ * 记下话题 → 会话；同一话题已有未归档的行（并发的另一条消息抢先建了）时不写，返回已有的会话 id。
+ * 返回实际生效的会话 id。
+ */
+export async function insertThread(db, k, conversationId) {
+    const r = await sql `
+    INSERT INTO capybara.channel_threads (id, connection_id, chat_id, thread_key, account_id, conversation_id)
+    VALUES (${randomUUID()}, ${k.connectionId}, ${k.chatId}, ${k.threadKey}, ${k.accountId}, ${conversationId})
+    ON CONFLICT (connection_id, chat_id, thread_key, coalesce(account_id::text, ''))
+      WHERE archived_at IS NULL DO NOTHING
+    RETURNING conversation_id`.execute(db);
+    if (r.rows[0])
+        return r.rows[0].conversation_id;
+    const winner = await findThread(db, k);
+    if (winner === undefined)
+        throw new Error("channel thread vanished after a conflicting insert");
+    return winner;
+}
+/** 私聊 `/new`：归档当前话题行（下一条消息新建对话）。返回是否归档了一行。 */
+export async function archiveThread(db, k) {
+    const r = await db
+        .updateTable("channel_threads")
+        .set({ archived_at: sql `now()` })
+        .where("connection_id", "=", k.connectionId)
+        .where("chat_id", "=", k.chatId)
+        .where("thread_key", "=", k.threadKey)
+        .where(sql `coalesce(account_id::text, '')`, "=", k.accountId ?? "")
+        .where("archived_at", "is", null)
+        .executeTakeFirst();
+    return r.numUpdatedRows > 0n;
+}

package/dist/channels/webhook-url.d.ts

@@ -0,0 +1,16 @@
+import type { KernelConfig } from "../config/schema.js";
+/** Path prefix of the channel webhook route on the gateway role (F9). */
+export declare const CHANNEL_WEBHOOK_PREFIX = "/channels/webhook/";
+type WebhookConfig = Pick<KernelConfig, "channels"> & {
+    tools: Pick<KernelConfig["tools"], "oauthAllowInsecureLoopback">;
+};
+/**
+ * Why `channels.webhookBaseUrl` is unusable, or null when it is unset or fine. It must be https;
+ * plain http is accepted only for loopback hosts with `tools.oauthAllowInsecureLoopback` (tests).
+ */
+export declare function webhookBaseUrlProblem(config: WebhookConfig): string | null;
+/** The usable webhook base without a trailing slash, or undefined when unset or unusable. */
+export declare function webhookBase(config: WebhookConfig): string | undefined;
+/** The callback URL the admin registers with the platform: `<base>/channels/webhook/<id>`. */
+export declare const webhookUrlOf: (base: string, connectionId: string) => string;
+export {};

package/dist/channels/webhook-url.js

@@ -0,0 +1,34 @@
+import { isIP } from "node:net";
+/** Path prefix of the channel webhook route on the gateway role (F9). */
+export const CHANNEL_WEBHOOK_PREFIX = "/channels/webhook/";
+const isLoopbackHost = (host) => {
+    const h = host.replace(/^\[|\]$/g, "");
+    return h === "localhost" || h === "::1" || (isIP(h) === 4 && h.startsWith("127."));
+};
+/**
+ * Why `channels.webhookBaseUrl` is unusable, or null when it is unset or fine. It must be https;
+ * plain http is accepted only for loopback hosts with `tools.oauthAllowInsecureLoopback` (tests).
+ */
+export function webhookBaseUrlProblem(config) {
+    const raw = config.channels.webhookBaseUrl;
+    if (raw === undefined)
+        return null;
+    const u = new URL(raw);
+    if (u.protocol === "https:")
+        return null;
+    if (u.protocol === "http:" &&
+        isLoopbackHost(u.hostname) &&
+        config.tools.oauthAllowInsecureLoopback) {
+        return null;
+    }
+    return "channels.webhookBaseUrl must be an https URL (plain http only for loopback hosts with tools.oauthAllowInsecureLoopback)";
+}
+/** The usable webhook base without a trailing slash, or undefined when unset or unusable. */
+export function webhookBase(config) {
+    const raw = config.channels.webhookBaseUrl;
+    if (raw === undefined || webhookBaseUrlProblem(config) !== null)
+        return undefined;
+    return raw.replace(/\/+$/, "");
+}
+/** The callback URL the admin registers with the platform: `<base>/channels/webhook/<id>`. */
+export const webhookUrlOf = (base, connectionId) => `${base}${CHANNEL_WEBHOOK_PREFIX}${connectionId}`;

package/dist/channels/webhook.controller.d.ts

@@ -0,0 +1,19 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { FastifyInstance } from "fastify";
+import { type ChannelWebhooks } from "./webhook.js";
+/** Fastify route template of the channel webhook (F9). */
+export declare const CHANNEL_WEBHOOK_ROUTE = "/channels/webhook/:connectionId";
+export interface ChannelWebhookRouteOptions {
+    webhooks: Pick<ChannelWebhooks, "handle">;
+    /** `channels.webhookMaxBodyBytes`: a larger body is answered 413 before the handler runs. */
+    maxBodyBytes: number;
+    log: Pick<Logger, "error">;
+}
+/**
+ * Registers `POST /channels/webhook/:connectionId` as a raw Fastify route in its own encapsulated
+ * scope (P-4), like `/plugins/*`: outside Nest, so neither the global `AuthGuard` nor the CSRF
+ * check applies (platforms send neither; the plugin verifies signatures). Inside this scope only,
+ * every content type is read as a raw Buffer (the global JSON parser is untouched), limited to
+ * `maxBodyBytes`. Must be called before Nest `app.init()`.
+ */
+export declare function registerChannelWebhookRoute(fastify: FastifyInstance, opts: ChannelWebhookRouteOptions): Promise<void>;

package/dist/channels/webhook.controller.js

@@ -0,0 +1,72 @@
+import { errorBody } from "../errors.js";
+import { codeForStatus, redactPath } from "../http/error.filter.js";
+import { WEBHOOK_SECURITY_HEADERS } from "./webhook.js";
+import { CHANNEL_WEBHOOK_PREFIX } from "./webhook-url.js";
+/** Fastify route template of the channel webhook (F9). */
+export const CHANNEL_WEBHOOK_ROUTE = `${CHANNEL_WEBHOOK_PREFIX}:connectionId`;
+/** Request headers as the plugin sees them: lowercase names, repeats joined, no cookies. */
+function headersOf(req) {
+    const out = {};
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined || name === "cookie")
+            continue;
+        out[name.toLowerCase()] = Array.isArray(value) ? value.join(", ") : value;
+    }
+    return out;
+}
+/**
+ * Registers `POST /channels/webhook/:connectionId` as a raw Fastify route in its own encapsulated
+ * scope (P-4), like `/plugins/*`: outside Nest, so neither the global `AuthGuard` nor the CSRF
+ * check applies (platforms send neither; the plugin verifies signatures). Inside this scope only,
+ * every content type is read as a raw Buffer (the global JSON parser is untouched), limited to
+ * `maxBodyBytes`. Must be called before Nest `app.init()`.
+ */
+export async function registerChannelWebhookRoute(fastify, opts) {
+    const handler = async (req, reply) => {
+        const { connectionId } = req.params;
+        // Aborts only when the platform hangs up before the response is written
+        const ac = new AbortController();
+        reply.raw.once("close", () => {
+            if (!reply.raw.writableFinished)
+                ac.abort();
+        });
+        const body = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0);
+        let res;
+        try {
+            res = await opts.webhooks.handle(connectionId, {
+                method: "POST",
+                headers: headersOf(req),
+                body: new Uint8Array(body.buffer, body.byteOffset, body.byteLength),
+                receivedAt: Date.now(),
+            }, ac.signal);
+        }
+        catch (err) {
+            opts.log.error("channel webhook failed", { path: redactPath(req.url), err });
+            return reply.code(500).send(errorBody("internal", "Internal error"));
+        }
+        reply.code(res.status);
+        for (const [name, value] of Object.entries(res.headers ?? {}))
+            reply.header(name, value);
+        return reply.send(res.body ?? "");
+    };
+    await fastify.register(async (scope) => {
+        // Every response of the route, including Fastify's own 413 / 415 / 500
+        scope.addHook("onSend", async (_req, reply, payload) => {
+            for (const [name, value] of Object.entries(WEBHOOK_SECURITY_HEADERS)) {
+                reply.header(name, value);
+            }
+            return payload;
+        });
+        scope.removeAllContentTypeParsers();
+        scope.addContentTypeParser("*", { parseAs: "buffer" }, (_req, body, done) => done(null, body));
+        scope.setErrorHandler((err, req, reply) => {
+            const status = typeof err.statusCode === "number" ? err.statusCode : 500;
+            if (status >= 400 && status < 500) {
+                return reply.code(status).send(errorBody(codeForStatus(status), err.message));
+            }
+            opts.log.error("channel webhook request failed", { path: redactPath(req.url), err });
+            return reply.code(500).send(errorBody("internal", "Internal error"));
+        });
+        scope.post(CHANNEL_WEBHOOK_ROUTE, { bodyLimit: opts.maxBodyBytes }, handler);
+    });
+}

package/dist/channels/webhook.d.ts

@@ -0,0 +1,73 @@
+import type { ChannelWebhookRequest, ChannelWebhookResponse, Logger } from "@capybara-hq/plugin-sdk";
+import type { ChannelConnections } from "./connections.service.js";
+import type { ChannelInbound } from "./inbound.js";
+/**
+ * Deadline of one webhook request: connection lookups, the plugin's `webhook.handle` and handing
+ * its events to `onEvent` (platform ack deadlines are a few seconds). Past it the kernel answers 503.
+ */
+export declare const WEBHOOK_HANDLE_TIMEOUT_MS = 10000;
+/** How long a connection's decrypted runtime (plugin + config) is reused across requests. */
+export declare const WEBHOOK_RUNTIME_CACHE_MS = 5000;
+/** Most connections whose runtime is cached in one process. */
+export declare const WEBHOOK_RUNTIME_CACHE_MAX = 1000;
+/**
+ * Headers every webhook response carries; a plugin cannot override them (the body is never meant to
+ * be rendered or sniffed by a browser).
+ */
+export declare const WEBHOOK_SECURITY_HEADERS: Readonly<Record<string, string>>;
+export interface ChannelWebhooksDeps {
+    connections: Pick<ChannelConnections, "row" | "runtime">;
+    inbound: Pick<ChannelInbound, "onEvent">;
+    log: Pick<Logger, "warn">;
+    /** Defaults to {@link WEBHOOK_HANDLE_TIMEOUT_MS}. */
+    handleTimeoutMs?: number;
+    /** Defaults to {@link WEBHOOK_RUNTIME_CACHE_MS}; 0 disables the cache. */
+    runtimeCacheMs?: number;
+}
+/**
+ * Channel webhook inbound (F8 / F9), framework free. The gateway route
+ * `POST /channels/webhook/:connectionId` hands every request here; the kernel applies no auth, so
+ * everything a request can do goes through the plugin's `webhook.handle`, which verifies the
+ * signature, decrypts and checks timestamps:
+ * - unknown connection, not in webhook mode, not active or plugin off for the org → uniform 404
+ *   `channel.webhook_not_found` (the connection row is read on every request);
+ * - plugin not loaded on this replica, being disabled / upgraded, or stored config no longer valid →
+ *   503 `extension.unavailable`.
+ *   Deliberate tradeoff: during a rolling upgrade the platform retries and reaches a replica that
+ *   has the plugin. It is only reachable with the UUID of an existing webhook-mode connection
+ *   (the URL the platform already has), so it reveals nothing to a guesser;
+ * - `respond` → written back (minus framing / cookie headers);
+ * - `events` → each goes through the same `onEvent` as the long connection (dedupe by `messageId` /
+ *   `eventId`, durable enqueue); the plugin's `ack` is written only after every one resolved, and
+ *   any rejection answers 503 `channel.webhook_retry` so the platform redelivers;
+ * - `reject` → that status (400 / 401 / 403), nothing enqueued;
+ * - plugin throws or returns something else → 500 `internal`;
+ * - the whole request (connection lookups, handle, onEvent) has one deadline ({@link WEBHOOK_HANDLE_TIMEOUT_MS}): a
+ *   plugin that ignores its `signal` or an enqueue stuck on Redis answers 503 `channel.webhook_retry`
+ *   when it passes (late work is not cancelled; dedupe makes the redelivery safe).
+ * - `webhook.handle` counts toward the plugin instance's in-flight calls: a disable or upgrade waits
+ *   for it (`extensionHost.drainSeconds`) before `dispose`; past that the call is aborted → 503
+ *   `channel.webhook_retry`.
+ * Every response carries {@link WEBHOOK_SECURITY_HEADERS}.
+ *
+ * The decrypted runtime (plugin implementation + config) is cached per connection for a few seconds
+ * (bounded, process local), so unauthenticated requests stay cheap before the signature check. It is
+ * a read-through cache only: the kernel calls {@link invalidate} on `channel.changed` (config rotation,
+ * mode switch, deletion…) and {@link invalidateAll} when a plugin instance changes; a generation
+ * counter keeps a fetch that started before `invalidateAll` from storing the old plugin instance.
+ */
+export declare class ChannelWebhooks {
+    private readonly deps;
+    private readonly runtimes;
+    /** Bumped by {@link invalidateAll}: a fetch started before the bump is not stored. */
+    private generation;
+    constructor(deps: ChannelWebhooksDeps);
+    /** Drops the cached runtime of one connection (on `channel.changed`). */
+    invalidate(connectionId: string): void;
+    /** Drops every cached runtime (a plugin was replaced, revoked or reloaded). */
+    invalidateAll(): void;
+    handle(connectionId: string, request: ChannelWebhookRequest, signal: AbortSignal): Promise<ChannelWebhookResponse>;
+    private runtime;
+    private respond;
+    private respondBefore;
+}

package/dist/channels/webhook.js

@@ -0,0 +1,274 @@
+import { ApiError, errorBody } from "../errors.js";
+import { ExtensionUnloadedError } from "../extensions/inflight.js";
+/**
+ * Deadline of one webhook request: connection lookups, the plugin's `webhook.handle` and handing
+ * its events to `onEvent` (platform ack deadlines are a few seconds). Past it the kernel answers 503.
+ */
+export const WEBHOOK_HANDLE_TIMEOUT_MS = 10_000;
+/** How long a connection's decrypted runtime (plugin + config) is reused across requests. */
+export const WEBHOOK_RUNTIME_CACHE_MS = 5_000;
+/** Most connections whose runtime is cached in one process. */
+export const WEBHOOK_RUNTIME_CACHE_MAX = 1_000;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Headers every webhook response carries; a plugin cannot override them (the body is never meant to
+ * be rendered or sniffed by a browser).
+ */
+export const WEBHOOK_SECURITY_HEADERS = {
+    "x-content-type-options": "nosniff",
+    "content-security-policy": "default-src 'none'",
+};
+/** Response headers a plugin may not set (the HTTP server owns framing, cookies and the above). */
+const DROPPED_HEADERS = new Set([
+    "connection",
+    "content-length",
+    "keep-alive",
+    "set-cookie",
+    "transfer-encoding",
+    ...Object.keys(WEBHOOK_SECURITY_HEADERS),
+]);
+const jsonError = (status, code, message) => ({
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+    body: JSON.stringify(errorBody(code, message)),
+});
+/**
+ * The one answer for an unknown connection, a connection not in webhook mode, a disabled one, or
+ * one whose plugin is off for its org: the response never reveals whether the connection exists.
+ */
+const notFound = () => jsonError(404, "channel.webhook_not_found", "No webhook is registered at this address");
+const retryLater = () => jsonError(503, "channel.webhook_retry", "The event could not be accepted; retry later");
+/** Thrown by {@link raceAbort} when the request's deadline (or the platform hanging up) wins. */
+class WebhookDeadline extends Error {
+}
+/** Settles with `p`, or rejects with {@link WebhookDeadline} once `signal` aborts (whatever `p` does). */
+function raceAbort(p, signal) {
+    if (signal.aborted) {
+        p.catch(() => { });
+        return Promise.reject(new WebhookDeadline());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new WebhookDeadline());
+        signal.addEventListener("abort", onAbort, { once: true });
+        p.then((v) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(v);
+        }, (e) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(e);
+        });
+    });
+}
+/**
+ * Channel webhook inbound (F8 / F9), framework free. The gateway route
+ * `POST /channels/webhook/:connectionId` hands every request here; the kernel applies no auth, so
+ * everything a request can do goes through the plugin's `webhook.handle`, which verifies the
+ * signature, decrypts and checks timestamps:
+ * - unknown connection, not in webhook mode, not active or plugin off for the org → uniform 404
+ *   `channel.webhook_not_found` (the connection row is read on every request);
+ * - plugin not loaded on this replica, being disabled / upgraded, or stored config no longer valid →
+ *   503 `extension.unavailable`.
+ *   Deliberate tradeoff: during a rolling upgrade the platform retries and reaches a replica that
+ *   has the plugin. It is only reachable with the UUID of an existing webhook-mode connection
+ *   (the URL the platform already has), so it reveals nothing to a guesser;
+ * - `respond` → written back (minus framing / cookie headers);
+ * - `events` → each goes through the same `onEvent` as the long connection (dedupe by `messageId` /
+ *   `eventId`, durable enqueue); the plugin's `ack` is written only after every one resolved, and
+ *   any rejection answers 503 `channel.webhook_retry` so the platform redelivers;
+ * - `reject` → that status (400 / 401 / 403), nothing enqueued;
+ * - plugin throws or returns something else → 500 `internal`;
+ * - the whole request (connection lookups, handle, onEvent) has one deadline ({@link WEBHOOK_HANDLE_TIMEOUT_MS}): a
+ *   plugin that ignores its `signal` or an enqueue stuck on Redis answers 503 `channel.webhook_retry`
+ *   when it passes (late work is not cancelled; dedupe makes the redelivery safe).
+ * - `webhook.handle` counts toward the plugin instance's in-flight calls: a disable or upgrade waits
+ *   for it (`extensionHost.drainSeconds`) before `dispose`; past that the call is aborted → 503
+ *   `channel.webhook_retry`.
+ * Every response carries {@link WEBHOOK_SECURITY_HEADERS}.
+ *
+ * The decrypted runtime (plugin implementation + config) is cached per connection for a few seconds
+ * (bounded, process local), so unauthenticated requests stay cheap before the signature check. It is
+ * a read-through cache only: the kernel calls {@link invalidate} on `channel.changed` (config rotation,
+ * mode switch, deletion…) and {@link invalidateAll} when a plugin instance changes; a generation
+ * counter keeps a fetch that started before `invalidateAll` from storing the old plugin instance.
+ */
+export class ChannelWebhooks {
+    deps;
+    runtimes = new Map();
+    /** Bumped by {@link invalidateAll}: a fetch started before the bump is not stored. */
+    generation = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Drops the cached runtime of one connection (on `channel.changed`). */
+    invalidate(connectionId) {
+        this.runtimes.delete(connectionId);
+    }
+    /** Drops every cached runtime (a plugin was replaced, revoked or reloaded). */
+    invalidateAll() {
+        this.generation++;
+        this.runtimes.clear();
+    }
+    async handle(connectionId, request, signal) {
+        return secure(await this.respond(connectionId, request, signal));
+    }
+    async runtime(connectionId, deadline) {
+        const ttl = this.deps.runtimeCacheMs ?? WEBHOOK_RUNTIME_CACHE_MS;
+        const now = Date.now();
+        const hit = this.runtimes.get(connectionId);
+        if (hit && hit.expiresAt > now)
+            return hit.value;
+        const generation = this.generation;
+        const value = await raceAbort(this.deps.connections.runtime(connectionId), deadline);
+        // A plugin instance changed while fetching: use the value once, keep no stale instance
+        if (ttl > 0 && generation === this.generation) {
+            this.runtimes.delete(connectionId);
+            while (this.runtimes.size >= WEBHOOK_RUNTIME_CACHE_MAX) {
+                const oldest = this.runtimes.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.runtimes.delete(oldest);
+            }
+            this.runtimes.set(connectionId, { value, expiresAt: now + ttl });
+        }
+        return value;
+    }
+    async respond(connectionId, request, signal) {
+        if (!UUID_RE.test(connectionId))
+            return notFound();
+        // One deadline for the whole request (DB lookups, handle, onEvent); also aborts when the
+        // platform hangs up
+        const deadline = AbortSignal.any([
+            signal,
+            AbortSignal.timeout(this.deps.handleTimeoutMs ?? WEBHOOK_HANDLE_TIMEOUT_MS),
+        ]);
+        try {
+            return await this.respondBefore(connectionId, request, deadline);
+        }
+        catch (err) {
+            if (!(err instanceof WebhookDeadline))
+                throw err;
+            this.deps.log.warn("channel webhook timed out; the platform will retry", { connectionId });
+            return retryLater();
+        }
+    }
+    async respondBefore(connectionId, request, deadline) {
+        const row = await raceAbort(this.deps.connections.row(connectionId), deadline);
+        if (row === undefined ||
+            row.inboundMode !== "webhook" ||
+            row.status !== "active" ||
+            !row.pluginEnabled) {
+            this.invalidate(connectionId);
+            return notFound();
+        }
+        let runtime;
+        try {
+            runtime = await this.runtime(connectionId, deadline);
+        }
+        catch (err) {
+            if (err instanceof WebhookDeadline)
+                throw err;
+            if (err instanceof ApiError &&
+                (err.code === "channel.not_found" || err.code === "extension.not_enabled")) {
+                return notFound();
+            }
+            this.deps.log.warn("channel webhook cannot load its connection", {
+                connectionId,
+                code: err instanceof ApiError ? err.code : undefined,
+            });
+            return jsonError(503, "extension.unavailable", "The channel is not available right now");
+        }
+        const webhook = runtime.channel.webhook;
+        if (webhook === undefined)
+            return notFound();
+        // The call counts toward the plugin instance's in-flight work, so disabling or upgrading the
+        // plugin drains it before `dispose` (and aborts it past extensionHost.drainSeconds).
+        let inflight;
+        try {
+            inflight = runtime.inflight?.enter(deadline);
+        }
+        catch (err) {
+            if (!(err instanceof ExtensionUnloadedError))
+                throw err;
+            // The cached runtime belongs to a revoked instance: the next request loads the new one
+            this.invalidate(connectionId);
+            return jsonError(503, "extension.unavailable", "The channel is not available right now");
+        }
+        const callSignal = inflight?.signal ?? deadline;
+        let result;
+        try {
+            result = await raceAbort(Promise.resolve().then(() => webhook.handle({ connectionId, config: runtime.config, request, signal: callSignal })), callSignal);
+        }
+        catch (err) {
+            if (err instanceof WebhookDeadline) {
+                this.deps.log.warn("channel webhook handler timed out; the platform will retry", {
+                    connectionId,
+                });
+                return retryLater();
+            }
+            // The kernel log redacts the connection's secrets (runtime() registered them)
+            this.deps.log.warn("channel webhook handler failed", { connectionId, err });
+            return jsonError(500, "internal", "Internal error");
+        }
+        finally {
+            inflight?.leave();
+        }
+        switch (result?.kind) {
+            case "respond":
+                return sanitize(result.response);
+            case "reject":
+                return rejected(result.status);
+            case "events": {
+                const events = result.events;
+                if (!Array.isArray(events))
+                    break;
+                for (const e of events) {
+                    try {
+                        await raceAbort(this.deps.inbound.onEvent(connectionId, e), deadline);
+                    }
+                    catch (err) {
+                        this.deps.log.warn("channel webhook event not accepted; the platform will retry", {
+                            connectionId,
+                            ...(err instanceof WebhookDeadline ? { timedOut: true } : { err }),
+                        });
+                        return retryLater();
+                    }
+                }
+                return sanitize(result.ack);
+            }
+        }
+        this.deps.log.warn("channel webhook handler returned an invalid result", { connectionId });
+        return jsonError(500, "internal", "Internal error");
+    }
+}
+/** Generic codes for the statuses a plugin may reject with (same as the HTTP error filter's). */
+const REJECT_CODES = { 400: "validation_failed", 401: "auth.required", 403: "forbidden" };
+function rejected(status) {
+    const s = status === 401 || status === 403 ? status : 400;
+    return jsonError(s, REJECT_CODES[s], "Webhook request rejected");
+}
+/** The plugin's response with a valid status and only string headers it may set. */
+function sanitize(r) {
+    const status = r !== undefined && Number.isInteger(r.status) && r.status >= 200 && r.status <= 599
+        ? r.status
+        : 500;
+    const headers = {};
+    for (const [name, value] of Object.entries(r?.headers ?? {})) {
+        if (typeof value === "string" && !DROPPED_HEADERS.has(name.toLowerCase())) {
+            headers[name] = value;
+        }
+    }
+    return {
+        status,
+        headers,
+        ...(typeof r?.body === "string" && { body: r.body }),
+    };
+}
+/** Adds {@link WEBHOOK_SECURITY_HEADERS}, replacing any same-named header whatever its case. */
+function secure(r) {
+    const headers = {};
+    for (const [name, value] of Object.entries(r.headers ?? {})) {
+        if (!(name.toLowerCase() in WEBHOOK_SECURITY_HEADERS))
+            headers[name] = value;
+    }
+    return { ...r, headers: { ...headers, ...WEBHOOK_SECURITY_HEADERS } };
+}

package/dist/config/docs.d.ts

@@ -0,0 +1,9 @@
+import type { core } from "zod";
+/** `db.poolMax` -> `CAPYBARA_DB__POOL_MAX` (the inverse of the envOverrides mapping)。 */
+export declare function envName(path: string): string;
+/**
+ * Renders the config schema as a deterministic Markdown table: dotted path, env var, type, default,
+ * hot-reloadable, secret, description. The default of a secret field is always printed as "—" and
+ * never reaches the document.
+ */
+export declare function renderConfigDocs(schema: core.$ZodType): string;