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

package/dist/http/app.js

@@ -0,0 +1,170 @@
+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;
+};
+import "reflect-metadata";
+import fastifyCookie from "@fastify/cookie";
+import { Module } from "@nestjs/common";
+import { APP_FILTER, NestFactory } from "@nestjs/core";
+import { FastifyAdapter } from "@nestjs/platform-fastify";
+import { ApiError, errorBody } from "../errors.js";
+import { authorizeEnterpriseAdmin } from "../identity/auth.guard.js";
+import { ErrorFilter, redactPath } from "./error.filter.js";
+import { registerGatewayRoutes } from "./gateway.module.js";
+import { HealthController } from "./health.controller.js";
+import { NestLogAdapter } from "./nest-logger.js";
+import { createPluginRouter, registerPluginDispatch, staticRouteTable, } from "./plugin-dispatch.js";
+import { ACCOUNTS, API_TOKENS, HEALTH_OPTIONS, KERNEL_LOG, SESSIONS } from "./tokens.js";
+/** The extension package upload route (Fastify route template). */
+export const EXTENSION_PACKAGE_UPLOAD_ROUTE = "/api/v1/admin/extensions/packages/file";
+/** The plugin package upload route of the catalog import (Fastify route template). */
+export const CATALOG_UPLOAD_ROUTE = "/api/v1/admin/catalog/import/file";
+/**
+ * The upload routes that take raw bytes (`application/octet-stream`, limit `packages.maxBytes`,
+ * the enterprise admin is authenticated before the body is read).
+ */
+export const PACKAGE_UPLOAD_ROUTES = new Set([
+    EXTENSION_PACKAGE_UPLOAD_ROUTE,
+    CATALOG_UPLOAD_ROUTE,
+]);
+/**
+ * 把 `http.trustProxy` 配置转成 Fastify 的 trustProxy。布尔与 IP / CIDR 列表原样传入；
+ * 跳数转成 `(addr, hop) => hop < n`：Fastify 5.12 起对 number 一律 fail closed（不信任任何一跳），
+ * 所以由这里实现跳数语义——前提是服务只能经由这 n 层代理访问（配置说明里已写明，并推荐 CIDR 列表）。
+ */
+function fastifyTrustProxy(tp) {
+    return typeof tp === "number" ? (_addr, hop) => hop < tp : tp;
+}
+/** 允许较大请求体的路由（Fastify 路由模板，只读常量表）及其上限。 */
+const LARGE_BODY_ROUTES = new Set([
+    "/api/v1/orgs/:orgId/connectors",
+    "/api/v1/orgs/:orgId/connectors/preview",
+]);
+const LARGE_BODY_LIMIT = 6 * 1024 * 1024;
+/** 根模块：总是含健康检查；`serveApi` 时 import `apiModule`；全局错误过滤器。 */
+function rootModule(opts) {
+    let RootModule = class RootModule {
+    };
+    RootModule = __decorate([
+        Module({})
+    ], RootModule);
+    return {
+        module: RootModule,
+        imports: opts.serveApi && opts.apiModule ? [opts.apiModule] : [],
+        controllers: [HealthController],
+        providers: [
+            { provide: KERNEL_LOG, useValue: opts.log },
+            { provide: HEALTH_OPTIONS, useValue: opts.health },
+            { provide: APP_FILTER, useClass: ErrorFilter },
+        ],
+    };
+}
+/**
+ * 创建并初始化内核 HTTP 应用（NestJS + Fastify），不连接任何外部资源。
+ * 插件路由不经过 Nest：在 Fastify 的独立作用域里统一转发 `/plugins/*`（见 plugin-dispatch.ts）；
+ * 插件加载前 `/plugins/*` 一律 404。未匹配的内核路由同样返回 404 错误信封。
+ */
+export async function createHttpApp(opts) {
+    const app = await NestFactory.create(rootModule(opts), new FastifyAdapter({ trustProxy: fastifyTrustProxy(opts.trustProxy ?? false) }), { logger: new NestLogAdapter(opts.log), abortOnError: false });
+    // Cookie 解析（会话 Cookie）；必须在 init 之前注册
+    await app.register(fastifyCookie);
+    const fastify = app.getHttpAdapter().getInstance();
+    const replicaId = opts.replicaId;
+    if (replicaId !== undefined) {
+        // 直接设在原始响应上：hijack 后自己 writeHead 的 SSE 流也会带上（writeHead 合并已 setHeader 的头）
+        fastify.addHook("onRequest", async (_req, reply) => {
+            reply.raw.setHeader("x-capybara-replica", replicaId);
+        });
+    }
+    const routes = [];
+    fastify.addHook("onRoute", (r) => {
+        for (const method of [r.method].flat())
+            routes.push({ method, url: r.url });
+        // 安装 / 预览连接器的请求体可带最大 2 MB 的 OpenAPI 文档（JSON 转义后更大），其余路由保持默认 1 MiB
+        if (LARGE_BODY_ROUTES.has(r.url) && [r.method].flat().includes("POST")) {
+            r.bodyLimit = LARGE_BODY_LIMIT;
+        }
+        if (PACKAGE_UPLOAD_ROUTES.has(r.url) && opts.packageMaxBytes !== undefined) {
+            r.bodyLimit = opts.packageMaxBytes + 1;
+        }
+    });
+    // 读请求体之前：包上传（插件包、企业目录包）先认证（未认证 / 非企业管理员的大请求体不读进内存）；其余内核路由不收
+    // application/octet-stream（415）。插件路由 /plugins/* 在自己的作用域里收任何类型，不受影响
+    let authServices;
+    const services = () => {
+        authServices ??= {
+            accounts: app.get(ACCOUNTS, { strict: false }),
+            sessions: app.get(SESSIONS, { strict: false }),
+            tokens: app.get(API_TOKENS, { strict: false }),
+        };
+        return authServices;
+    };
+    const sendError = (reply, e, method, url) => {
+        if (e instanceof ApiError) {
+            return reply.code(e.status).send(errorBody(e.code, e.message, e.details));
+        }
+        opts.log.error("http handler failed", { method, path: redactPath(url), err: e });
+        return reply.code(500).send(errorBody("internal", "Internal error"));
+    };
+    fastify.addHook("onRequest", async (req, reply) => {
+        if (!req.url.startsWith("/api/"))
+            return;
+        if (req.method === "POST" && PACKAGE_UPLOAD_ROUTES.has(req.routeOptions.url ?? "")) {
+            try {
+                await authorizeEnterpriseAdmin(req, services());
+            }
+            catch (e) {
+                return sendError(reply, e, req.method, req.url);
+            }
+            return;
+        }
+        const type = String(req.headers["content-type"] ?? "")
+            .split(";")[0]
+            ?.trim()
+            .toLowerCase();
+        if (type === "application/octet-stream") {
+            return reply
+                .code(415)
+                .send(errorBody("unsupported_media_type", "This endpoint does not accept application/octet-stream request bodies"));
+        }
+    });
+    // 原始字节的请求体（只有包上传路由能走到这里，见上面的 onRequest）：交给处理函数一个 Buffer
+    fastify.addContentTypeParser("application/octet-stream", { parseAs: "buffer" }, (_req, body, done) => done(null, body));
+    let table;
+    let unwatch;
+    const dispatch = opts.servePlugins
+        ? await registerPluginDispatch(fastify, () => table, opts.log)
+        : undefined;
+    if (opts.gateway)
+        await registerGatewayRoutes(fastify, opts.gateway, opts.log);
+    await app.init();
+    return {
+        inject: (o) => fastify.inject(o),
+        routes: () => [...routes],
+        connections: () => new Promise((resolve, reject) => fastify.server.getConnections((err, n) => (err ? reject(err) : resolve(n)))),
+        mountPlugins(pluginRoutes) {
+            if (table)
+                throw new Error("plugin routes already mounted");
+            const t = Array.isArray(pluginRoutes) ? staticRouteTable(pluginRoutes) : pluginRoutes;
+            // 先建一次：路径不在 /plugins/ 下的立即报错
+            createPluginRouter(t.routes());
+            table = t;
+            // 插件实例撤销 / 替换：中止它进行中的请求（SSE 等长连接不留在旧实例上）
+            unwatch = t.onChange?.((plugin) => dispatch?.abortPlugin(plugin));
+        },
+        async listen(port) {
+            await app.listen(port, "0.0.0.0");
+            const addr = fastify.server.address();
+            return addr && typeof addr === "object" ? addr.port : port;
+        },
+        close: () => {
+            unwatch?.();
+            dispatch?.abortAll();
+            return app.close();
+        },
+        abortPluginRequests: () => dispatch?.abortAll(),
+        closeAllConnections: () => fastify.server.closeAllConnections(),
+    };
+}

package/dist/http/error.filter.d.ts

@@ -0,0 +1,21 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type ArgumentsHost, type ExceptionFilter } from "@nestjs/common";
+import { type ErrorCode } from "../errors.js";
+/** 框架错误的状态码 → 通用错误码（插件分发作用域的 Fastify 错误处理同样使用）。 */
+export declare function codeForStatus(status: number): ErrorCode;
+/**
+ * 记日志用的请求路径：去掉查询串，公开邀请路由 `/api/v1/invitations/<token>` 的令牌段换成 `:token`，
+ * 其他任何以 `cap_` 开头的路径段（内核各类令牌的前缀）换成 `:redacted`，令牌不落日志。
+ */
+export declare function redactPath(url: string): string;
+/**
+ * 全局错误过滤器：一切异常都转成错误信封 `{ error: { code, message, details? } }`。
+ * `ApiError` 原样给出；Nest `HttpException`（含路由不存在的 404）按状态码映射；
+ * 其他异常一律 500 `internal` 并记日志，不回显错误信息。
+ */
+export declare class ErrorFilter implements ExceptionFilter {
+    private readonly log;
+    constructor(log: Logger);
+    catch(exception: unknown, host: ArgumentsHost): void;
+    private logFailure;
+}

package/dist/http/error.filter.js

@@ -0,0 +1,85 @@
+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); }
+};
+import { Catch, HttpException, Inject, } from "@nestjs/common";
+import { ApiError, errorBody } from "../errors.js";
+import { KERNEL_LOG } from "./tokens.js";
+/**
+ * Nest `HttpException`（框架自身抛出，如路由不存在、请求体解析失败）的状态码 → 通用错误码。
+ * 显式列出而不是反查 `ERROR_CODES`：同一状态码下有多个业务码，反查会误取到业务码。
+ * 表外的状态一律 `internal`（状态码本身保留）。
+ */
+const GENERIC_CODE_BY_STATUS = new Map([
+    [400, "validation_failed"],
+    [401, "auth.required"],
+    [403, "forbidden"],
+    [404, "not_found"],
+    [409, "conflict"],
+    [413, "payload_too_large"],
+    [415, "unsupported_media_type"],
+    [429, "rate_limited"],
+]);
+/** 框架错误的状态码 → 通用错误码（插件分发作用域的 Fastify 错误处理同样使用）。 */
+export function codeForStatus(status) {
+    return GENERIC_CODE_BY_STATUS.get(status) ?? "internal";
+}
+/**
+ * 记日志用的请求路径：去掉查询串，公开邀请路由 `/api/v1/invitations/<token>` 的令牌段换成 `:token`，
+ * 其他任何以 `cap_` 开头的路径段（内核各类令牌的前缀）换成 `:redacted`，令牌不落日志。
+ */
+export function redactPath(url) {
+    const path = url.split("?")[0] ?? "";
+    return path
+        .replace(/^\/api\/v1\/invitations\/[^/]+/, "/api/v1/invitations/:token")
+        .replace(/\/cap_[^/]*/g, "/:redacted");
+}
+/**
+ * 全局错误过滤器：一切异常都转成错误信封 `{ error: { code, message, details? } }`。
+ * `ApiError` 原样给出；Nest `HttpException`（含路由不存在的 404）按状态码映射；
+ * 其他异常一律 500 `internal` 并记日志，不回显错误信息。
+ */
+let ErrorFilter = class ErrorFilter {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    catch(exception, host) {
+        const http = host.switchToHttp();
+        const reply = http.getResponse();
+        const req = http.getRequest();
+        if (exception instanceof ApiError) {
+            if (exception.status >= 500)
+                this.logFailure(req, exception);
+            reply
+                .code(exception.status)
+                .send(errorBody(exception.code, exception.message, exception.details));
+            return;
+        }
+        if (exception instanceof HttpException) {
+            const status = exception.getStatus();
+            if (status < 500) {
+                reply.code(status).send(errorBody(codeForStatus(status), exception.message));
+                return;
+            }
+            this.logFailure(req, exception);
+            reply.code(status).send(errorBody(codeForStatus(status), "Internal error"));
+            return;
+        }
+        this.logFailure(req, exception);
+        reply.code(500).send(errorBody("internal", "Internal error"));
+    }
+    logFailure(req, err) {
+        this.log.error("http handler failed", { method: req.method, path: redactPath(req.url), err });
+    }
+};
+ErrorFilter = __decorate([
+    Catch(),
+    __param(0, Inject(KERNEL_LOG))
+], ErrorFilter);
+export { ErrorFilter };

package/dist/http/gateway.module.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { FastifyInstance } from "fastify";
+import type { ChannelWebhooks } from "../channels/webhook.js";
+/** What the gateway role serves over HTTP besides health and plugin routes. */
+export interface GatewayRoutes {
+    webhooks: Pick<ChannelWebhooks, "handle">;
+    /** `channels.webhookMaxBodyBytes`. */
+    webhookMaxBodyBytes: number;
+}
+/**
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): today the
+ * channel webhook. These are raw Fastify routes, not a Nest module, so the API's global guard and
+ * CSRF check do not apply (P-4); each route does its own (plugin-side) verification.
+ */
+export declare function registerGatewayRoutes(fastify: FastifyInstance, routes: GatewayRoutes, log: Pick<Logger, "error">): Promise<void>;

package/dist/http/gateway.module.js

@@ -0,0 +1,13 @@
+import { registerChannelWebhookRoute } from "../channels/webhook.controller.js";
+/**
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): today the
+ * channel webhook. These are raw Fastify routes, not a Nest module, so the API's global guard and
+ * CSRF check do not apply (P-4); each route does its own (plugin-side) verification.
+ */
+export async function registerGatewayRoutes(fastify, routes, log) {
+    await registerChannelWebhookRoute(fastify, {
+        webhooks: routes.webhooks,
+        maxBodyBytes: routes.webhookMaxBodyBytes,
+        log,
+    });
+}

package/dist/http/health.controller.d.ts

@@ -0,0 +1,26 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { FastifyReply } from "fastify";
+/** 一项就绪检查：成功 resolve，失败 reject。 */
+export type ReadinessCheck = () => Promise<void>;
+/** 健康检查参数。 */
+export interface HealthOptions {
+    checks: Record<string, ReadinessCheck>;
+    isStopping: () => boolean;
+    log: Logger;
+    /** 单项检查超时，默认 2s。 */
+    timeoutMs?: number;
+}
+/**
+ * `GET /healthz`（进程存活，恒 200）与 `GET /readyz`（依赖就绪）。
+ * readyz 的 body 只给出每项检查的 `"ok"` / `"error"`，失败原因只进日志（已打码），不进响应——
+ * 驱动的错误信息可能带连接串。停机开始后 readyz 立即 503，不再执行检查。
+ * 标为 `@Public()`：挂载内核 API 时全局 AuthGuard 也作用于这里。
+ */
+export declare class HealthController {
+    private readonly opts;
+    constructor(opts: HealthOptions);
+    healthz(): {
+        ok: true;
+    };
+    readyz(reply: FastifyReply): Promise<Record<string, unknown>>;
+}

package/dist/http/health.controller.js

@@ -0,0 +1,79 @@
+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); }
+};
+import { Controller, Get, Inject, Res } from "@nestjs/common";
+import { Public } from "../identity/principal.js";
+import { HEALTH_OPTIONS } from "./tokens.js";
+/** 单项检查的超时：依赖挂起（如 Redis 正在重连、命令进了离线队列）时也要尽快给出 503。 */
+const CHECK_TIMEOUT_MS = 2_000;
+function withTimeout(p, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+        timer.unref();
+    });
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * `GET /healthz`（进程存活，恒 200）与 `GET /readyz`（依赖就绪）。
+ * readyz 的 body 只给出每项检查的 `"ok"` / `"error"`，失败原因只进日志（已打码），不进响应——
+ * 驱动的错误信息可能带连接串。停机开始后 readyz 立即 503，不再执行检查。
+ * 标为 `@Public()`：挂载内核 API 时全局 AuthGuard 也作用于这里。
+ */
+let HealthController = class HealthController {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    healthz() {
+        return { ok: true };
+    }
+    async readyz(reply) {
+        const { opts } = this;
+        const stopping = () => {
+            reply.code(503);
+            return { ok: false, stopping: true };
+        };
+        if (opts.isStopping())
+            return stopping();
+        const timeoutMs = opts.timeoutMs ?? CHECK_TIMEOUT_MS;
+        const names = Object.keys(opts.checks);
+        const results = await Promise.allSettled(names.map((n) => withTimeout(opts.checks[n](), timeoutMs)));
+        const body = {};
+        let ok = true;
+        results.forEach((r, i) => {
+            const name = names[i];
+            if (r.status === "fulfilled") {
+                body[name] = "ok";
+            }
+            else {
+                ok = false;
+                body[name] = "error";
+                opts.log.warn("readiness check failed", { check: name, err: r.reason });
+            }
+        });
+        if (opts.isStopping())
+            return stopping();
+        reply.code(ok ? 200 : 503);
+        return { ok, ...body };
+    }
+};
+__decorate([
+    Get("healthz")
+], HealthController.prototype, "healthz", null);
+__decorate([
+    Get("readyz"),
+    __param(0, Res({ passthrough: true }))
+], HealthController.prototype, "readyz", null);
+HealthController = __decorate([
+    Controller(),
+    Public(),
+    __param(0, Inject(HEALTH_OPTIONS))
+], HealthController);
+export { HealthController };

package/dist/http/nest-logger.d.ts

@@ -0,0 +1,20 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { LoggerService } from "@nestjs/common";
+/** 可选带 debug 的 logger（内核 logger 有 debug；插件契约的 Logger 没有）。 */
+type MaybeDebugLogger = Logger & {
+    debug?: (msg: string, fields?: Record<string, unknown>) => void;
+};
+/**
+ * 把 Nest 自身的日志转给内核 logger：`log`（启动时的模块加载、路由映射等，每次启动几十行）降为 debug，
+ * `warn` / `error` 原级别转发，`debug` / `verbose` 丢弃。logger 没有 debug 时 `log` 也丢弃。
+ */
+export declare class NestLogAdapter implements LoggerService {
+    private readonly logger;
+    constructor(logger: MaybeDebugLogger);
+    log(message: unknown, ...params: unknown[]): void;
+    warn(message: unknown, ...params: unknown[]): void;
+    error(message: unknown, ...params: unknown[]): void;
+    debug(): void;
+    verbose(): void;
+}
+export {};

package/dist/http/nest-logger.js

@@ -0,0 +1,28 @@
+/**
+ * 把 Nest 自身的日志转给内核 logger：`log`（启动时的模块加载、路由映射等，每次启动几十行）降为 debug，
+ * `warn` / `error` 原级别转发，`debug` / `verbose` 丢弃。logger 没有 debug 时 `log` 也丢弃。
+ */
+export class NestLogAdapter {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    log(message, ...params) {
+        this.logger.debug?.(String(message), fields(params));
+    }
+    warn(message, ...params) {
+        this.logger.warn(String(message), fields(params));
+    }
+    error(message, ...params) {
+        this.logger.error(String(message), fields(params));
+    }
+    debug() { }
+    verbose() { }
+}
+/** Nest 把上下文名（如 `RoutesResolver`）、错误堆栈作为额外参数传入。 */
+function fields(params) {
+    const ctx = params.filter((p) => p !== undefined);
+    if (ctx.length === 0)
+        return undefined;
+    return { nest: ctx.length === 1 ? ctx[0] : ctx };
+}

package/dist/http/plugin-dispatch.d.ts

@@ -0,0 +1,68 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { FastifyInstance } from "fastify";
+import type { Route } from "../ctx/create-ctx.js";
+/** 插件路由都在此前缀下（ctx.http.route 已加 `/plugins/<name>` 前缀）。 */
+export declare const PLUGIN_PREFIX = "/plugins/";
+/** 插件路由表：按方法与路径（不含查询串）找到插件 handler；HEAD 没有专门路由时按 GET 匹配。 */
+export interface PluginRouter {
+    find(method: string, path: string): Route["handler"] | undefined;
+}
+/**
+ * The live source of extension routes (C17): routes change as extension instances are revoked /
+ * replaced, and the route table is rebuilt when `revision()` changes.
+ * `unavailable(plugin)`: the extension belongs to this deployment but is not in the registry right
+ * now (revoked / pending approval / failed to load), and its `/plugins/<plugin>/*` all answer 503
+ * `extension.unavailable` (the routes stay mounted and only gate).
+ */
+export interface PluginRouteTable {
+    routes(): Route[];
+    revision(): number;
+    unavailable(plugin: string): boolean | Promise<boolean>;
+    /**
+     * 插件实例变化（撤销 / 替换）的通知：转发层据此中止该插件进行中请求的 `req.signal`
+     * （SSE 等长连接随之收尾，不留在旧实例上）。返回取消订阅函数。
+     */
+    onChange?(listener: (plugin: string) => void): () => void;
+}
+/** 固定的路由列表（测试与只挂一次的调用方）：版本不变、没有不可用的插件。 */
+export declare function staticRouteTable(routes: Route[]): PluginRouteTable;
+/** 路径里的插件名（`/plugins/<name>/...` 的 `<name>`）；不在插件前缀下返回 undefined。 */
+export declare function pluginOfPath(path: string): string | undefined;
+/** 用 find-my-way 建立插件路由表，路径语法与 Fastify 相同；路径不在 `/plugins/` 下时抛错。 */
+export declare function createPluginRouter(routes: Route[]): PluginRouter;
+/**
+ * Registers `/plugins/*` in its own encapsulated scope and hands each request to the extension handler
+ * as a Web `Request`: the scope removes the default parsers and takes every content type as a raw
+ * Buffer, so the body the extension gets is the bytes the client sent.
+ * - The extension belongs to this deployment but is not in the registry (revoked and so on) -> 503
+ *   `extension.unavailable`; when an extension instance is revoked or replaced, the `req.signal` of
+ *   that extension's in-progress requests is aborted (`abortPlugin`, triggered by the route source's
+ *   `onChange`);
+ * - not mounted or no match -> 404 `not_found`; HEAD without its own route is handled as GET, with no
+ *   body in the response.
+ * - A `Request` that cannot be built (e.g. a malformed Host) -> 400 `validation_failed`, not logged as
+ *   an error.
+ * - `req.signal` aborts only when the client disconnects before the response is written (not on
+ *   normal completion); long-lived handlers use it to unsubscribe;
+ * - a throwing handler is logged (path redacted with `redactPath`) and returns 500 `internal` (the
+ *   error message is not echoed).
+ * - Fastify's own errors (a body over 1 MiB and so on) are mapped to the error envelope by the
+ *   scope's error handler: 4xx by the common error code table (413 `payload_too_large`, 415
+ *   `unsupported_media_type` and so on), 5xx are logged and return `internal`.
+ * - Shutdown: the returned `abortAll()` aborts the `req.signal` of every in-progress request (the
+ *   extension's SSE and other long connections wind down by it without using the http shutdown
+ *   budget); requests arriving afterwards start with an aborted `req.signal`. In-progress
+ *   AbortControllers are held only for the request's lifetime.
+ *   So extension handlers either finish quickly or tolerate the abort (see
+ *   .agents/skills/writing-extensions "Extension route matching semantics").
+ * Must be called before Nest `app.init()`.
+ */
+export declare function registerPluginDispatch(fastify: FastifyInstance, getTable: () => PluginRouteTable | undefined, log: Logger): Promise<{
+    abortAll(): void;
+    abortPlugin(plugin: string): void;
+}>;
+/**
+ * 从 Cookie 头里去掉内核会话 Cookie（`cap_at` / `cap_rt`）：插件 handler 不经内核鉴权，
+ * 拿到这两个 Cookie 就能冒充用户调内核 API。全部去掉后返回 undefined（不传 Cookie 头）。
+ */
+export declare function stripKernelCookies(cookie: string): string | undefined;