@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/http/app.js

@@ -1,41 +1,73 @@
-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 { AccountsService } from "../identity/accounts.js";
+import { ApiTokenService } from "../identity/api-tokens.js";
+import { authenticateOrgUploader, authorizeSuperAdmin, } from "../identity/auth.guard.js";
+import { SessionService } from "../identity/sessions.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { withLogContext } from "../log-context.js";
+import { authorizeOrgAction } from "../orgs/org.guard.js";
+import { redactPath } from "./error.filter.js";
+import { registerGatewayRoutes } from "./gateway-routes.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 platform skill version upload route (a skill package zip as the raw body). */
+export const COMPONENT_SKILL_UPLOAD_ROUTE = "/api/v1/admin/components/skill/:id/versions";
 /**
  * The upload routes that take raw bytes (`application/octet-stream`, limit `packages.maxBytes`,
- * the enterprise admin is authenticated before the body is read).
+ * the super admin is authenticated before the body is read).
  */
 export const PACKAGE_UPLOAD_ROUTES = new Set([
     EXTENSION_PACKAGE_UPLOAD_ROUTE,
     CATALOG_UPLOAD_ROUTE,
+    COMPONENT_SKILL_UPLOAD_ROUTE,
 ]);
+/** An org admin's plugin package upload (spec §14, ruling P3-7; a tgz as the raw body). */
+export const ORG_PLUGIN_UPLOAD_ROUTE = "/api/v1/orgs/:orgId/catalog/uploads/file";
 /**
- * 把 `http.trustProxy` 配置转成 Fastify 的 trustProxy。布尔与 IP / CIDR 列表原样传入；
- * 跳数转成 `(addr, hop) => hop < n`：Fastify 5.12 起对 number 一律 fail closed（不信任任何一跳），
- * 所以由这里实现跳数语义——前提是服务只能经由这 n 层代理访问（配置说明里已写明，并推荐 CIDR 列表）。
+ * The org routes that take raw package bytes (limit `packages.maxBytes`): before the body is read
+ * the caller is authenticated as a person with the org role of `catalog.upload` (ruling P3-29).
  */
-function fastifyTrustProxy(tp) {
-    return typeof tp === "number" ? (_addr, hop) => hop < tp : tp;
+export const ORG_PACKAGE_UPLOAD_ROUTES = new Set([ORG_PLUGIN_UPLOAD_ROUTE]);
+/** Paths without an access log line (probes). */
+const QUIET_PATHS = new Set(["/healthz", "/readyz"]);
+/**
+ * Request ids and the access log. Every request runs in a log context with its `reqId` (records
+ * logged while handling it carry it) and answers with `x-request-id` (set on the raw response, so
+ * hijacked SSE streams carry it too). One access line per request when the response is done:
+ * `info`, except event streams (`debug`, when they close) and the probes (none).
+ */
+function registerRequestLog(fastify, log) {
+    fastify.addHook("onRequest", (req, reply, done) => {
+        reply.raw.setHeader("x-request-id", req.id);
+        const started = performance.now();
+        const path = req.url.split("?")[0] ?? "";
+        let logged = false;
+        const accessLine = () => {
+            if (logged || QUIET_PATHS.has(path))
+                return;
+            logged = true;
+            const type = String(reply.raw.getHeader("content-type") ?? "");
+            const fields = {
+                method: req.method,
+                url: redactPath(req.url),
+                status: reply.raw.statusCode,
+                ms: Math.round(performance.now() - started),
+                reqId: req.id,
+            };
+            if (type.startsWith("text/event-stream"))
+                log.debug?.("request", fields);
+            else
+                log.info("request", fields);
+        };
+        reply.raw.once("finish", accessLine);
+        reply.raw.once("close", accessLine);
+        withLogContext({ reqId: req.id }, done);
+    });
 }
 /** 允许较大请求体的路由（Fastify 路由模板，只读常量表）及其上限。 */
 const LARGE_BODY_ROUTES = new Set([
@@ -43,34 +75,20 @@ const LARGE_BODY_ROUTES = new Set([
     "/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 错误信封。
+ * Sets up the Fastify side of the kernel's Nest application (built by `buildKernelApp` from
+ * `KernelModule`, which provides the health endpoints and the API) without connecting to anything,
+ * and returns it uninitialized: `init()` is the caller's (it runs the start sequence), `close()`
+ * closes only the HTTP server (the rest of the application is closed by the caller's shutdown).
+ * Extension routes do not go through Nest: `/plugins/*` is dispatched in its own Fastify scope
+ * (see plugin-dispatch.ts) and answers 404 until extensions are loaded. Unmatched kernel routes
+ * answer the 404 error envelope as well.
  */
-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 });
+export async function createHttpApp(opts, app) {
     // Cookie 解析（会话 Cookie）；必须在 init 之前注册
     await app.register(fastifyCookie);
     const fastify = app.getHttpAdapter().getInstance();
+    registerRequestLog(fastify, opts.log);
     const replicaId = opts.replicaId;
     if (replicaId !== undefined) {
         // 直接设在原始响应上：hijack 后自己 writeHead 的 SSE 流也会带上（writeHead 合并已 setHeader 的头）
@@ -86,18 +104,19 @@ export async function createHttpApp(opts) {
         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) {
+        const upload = PACKAGE_UPLOAD_ROUTES.has(r.url) || ORG_PACKAGE_UPLOAD_ROUTES.has(r.url);
+        if (upload && 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 }),
+            accounts: app.get(AccountsService, { strict: false }),
+            sessions: app.get(SessionService, { strict: false }),
+            tokens: app.get(ApiTokenService, { strict: false }),
         };
         return authServices;
     };
@@ -113,7 +132,20 @@ export async function createHttpApp(opts) {
             return;
         if (req.method === "POST" && PACKAGE_UPLOAD_ROUTES.has(req.routeOptions.url ?? "")) {
             try {
-                await authorizeEnterpriseAdmin(req, services());
+                await authorizeSuperAdmin(req, services());
+            }
+            catch (e) {
+                return sendError(reply, e, req.method, req.url);
+            }
+            return;
+        }
+        if (req.method === "POST" && ORG_PACKAGE_UPLOAD_ROUTES.has(req.routeOptions.url ?? "")) {
+            try {
+                // the org admin role before the body (ruling P3-29): no one else makes the kernel buffer
+                // a package-sized body
+                const principal = await authenticateOrgUploader(req, services());
+                const orgId = req.params.orgId ?? "";
+                await authorizeOrgAction(app.get(KernelDb, { strict: false }).db, principal, orgId, "catalog.upload");
             }
             catch (e) {
                 return sendError(reply, e, req.method, req.url);
@@ -139,7 +171,6 @@ export async function createHttpApp(opts) {
         : undefined;
     if (opts.gateway)
         await registerGatewayRoutes(fastify, opts.gateway, opts.log);
-    await app.init();
     return {
         inject: (o) => fastify.inject(o),
         routes: () => [...routes],
@@ -162,7 +193,7 @@ export async function createHttpApp(opts) {
         close: () => {
             unwatch?.();
             dispatch?.abortAll();
-            return app.close();
+            return fastify.close();
         },
         abortPluginRequests: () => dispatch?.abortAll(),
         closeAllConnections: () => fastify.server.closeAllConnections(),

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

@@ -0,0 +1,5 @@
+/**
+ * The global error filter (`APP_FILTER`: the error envelope for every route).
+ */
+export declare class ErrorFilterModule {
+}

package/dist/http/error-filter.module.js

@@ -0,0 +1,18 @@
+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 { Module } from "@nestjs/common";
+import { APP_FILTER } from "@nestjs/core";
+import { ErrorFilter } from "./error.filter.js";
+/**
+ * The global error filter (`APP_FILTER`: the error envelope for every route).
+ */
+let ErrorFilterModule = class ErrorFilterModule {
+};
+ErrorFilterModule = __decorate([
+    Module({ providers: [{ provide: APP_FILTER, useClass: ErrorFilter }] })
+], ErrorFilterModule);
+export { ErrorFilterModule };

package/dist/http/error.filter.js

@@ -9,7 +9,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Catch, HttpException, Inject, } from "@nestjs/common";
 import { ApiError, errorBody } from "../errors.js";
-import { KERNEL_LOG } from "./tokens.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
 /**
  * Nest `HttpException`（框架自身抛出，如路由不存在、请求体解析失败）的状态码 → 通用错误码。
  * 显式列出而不是反查 `ERROR_CODES`：同一状态码下有多个业务码，反查会误取到业务码。
@@ -80,6 +80,6 @@ let ErrorFilter = class ErrorFilter {
 };
 ErrorFilter = __decorate([
     Catch(),
-    __param(0, Inject(KERNEL_LOG))
+    __param(0, Inject(KERNEL_LOGGER))
 ], ErrorFilter);
 export { ErrorFilter };

package/dist/http/{gateway.module.d.ts → gateway-routes.d.ts}

@@ -1,15 +1,19 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { FastifyInstance } from "fastify";
 import type { ChannelWebhooks } from "../channels/webhook.js";
+import { type DeviceRoutesOptions } from "../devices/device-routes.js";
 /** What the gateway role serves over HTTP besides health and plugin routes. */
 export interface GatewayRoutes {
     webhooks: Pick<ChannelWebhooks, "handle">;
     /** `channels.webhookMaxBodyBytes`. */
     webhookMaxBodyBytes: number;
+    /** The device connection route (`GET /device/connect`, environments spec §13.4). */
+    devices: DeviceRoutesOptions;
 }
 /**
- * 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.
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): the
+ * channel webhook and the device connection WebSocket. 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
+ * verification (the channel plugin's signature check, the machine credential).
  */
 export declare function registerGatewayRoutes(fastify: FastifyInstance, routes: GatewayRoutes, log: Pick<Logger, "error">): Promise<void>;

package/dist/http/gateway-routes.js

@@ -0,0 +1,16 @@
+import { registerChannelWebhookRoute } from "../channels/webhook.controller.js";
+import { registerDeviceConnectRoute } from "../devices/device-routes.js";
+/**
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): the
+ * channel webhook and the device connection WebSocket. 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
+ * verification (the channel plugin's signature check, the machine credential).
+ */
+export async function registerGatewayRoutes(fastify, routes, log) {
+    await registerChannelWebhookRoute(fastify, {
+        webhooks: routes.webhooks,
+        maxBodyBytes: routes.webhookMaxBodyBytes,
+        log,
+    });
+    await registerDeviceConnectRoute(fastify, routes.devices);
+}

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

@@ -1,12 +1,13 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { LoggerService } from "@nestjs/common";
-/** 可选带 debug 的 logger（内核 logger 有 debug；插件契约的 Logger 没有）。 */
+/** A logger with an optional debug (the kernel logger has one; the SDK Logger does not). */
 type MaybeDebugLogger = Logger & {
     debug?: (msg: string, fields?: Record<string, unknown>) => void;
 };
 /**
- * 把 Nest 自身的日志转给内核 logger：`log`（启动时的模块加载、路由映射等，每次启动几十行）降为 debug，
- * `warn` / `error` 原级别转发，`debug` / `verbose` 丢弃。logger 没有 debug 时 `log` 也丢弃。
+ * Forwards Nest's own log lines to the kernel logger, as octok does: `log` (module loading,
+ * the `Mapped {/api/v1/…, GET} route` lines at startup) at info, `warn` / `error` as they are,
+ * `debug` / `verbose` at debug. Nest's context name becomes the record's `context`.
  */
 export declare class NestLogAdapter implements LoggerService {
     private readonly logger;
@@ -14,7 +15,7 @@ export declare class NestLogAdapter implements LoggerService {
     log(message: unknown, ...params: unknown[]): void;
     warn(message: unknown, ...params: unknown[]): void;
     error(message: unknown, ...params: unknown[]): void;
-    debug(): void;
-    verbose(): void;
+    debug(message: unknown, ...params: unknown[]): void;
+    verbose(message: unknown, ...params: unknown[]): void;
 }
 export {};

package/dist/http/nest-logger.js

@@ -1,6 +1,7 @@
 /**
- * 把 Nest 自身的日志转给内核 logger：`log`（启动时的模块加载、路由映射等，每次启动几十行）降为 debug，
- * `warn` / `error` 原级别转发，`debug` / `verbose` 丢弃。logger 没有 debug 时 `log` 也丢弃。
+ * Forwards Nest's own log lines to the kernel logger, as octok does: `log` (module loading,
+ * the `Mapped {/api/v1/…, GET} route` lines at startup) at info, `warn` / `error` as they are,
+ * `debug` / `verbose` at debug. Nest's context name becomes the record's `context`.
  */
 export class NestLogAdapter {
     logger;
@@ -8,7 +9,7 @@ export class NestLogAdapter {
         this.logger = logger;
     }
     log(message, ...params) {
-        this.logger.debug?.(String(message), fields(params));
+        this.logger.info(String(message), fields(params));
     }
     warn(message, ...params) {
         this.logger.warn(String(message), fields(params));
@@ -16,13 +17,26 @@ export class NestLogAdapter {
     error(message, ...params) {
         this.logger.error(String(message), fields(params));
     }
-    debug() { }
-    verbose() { }
+    debug(message, ...params) {
+        this.logger.debug?.(String(message), fields(params));
+    }
+    verbose(message, ...params) {
+        this.logger.debug?.(String(message), fields(params));
+    }
 }
-/** Nest 把上下文名（如 `RoutesResolver`）、错误堆栈作为额外参数传入。 */
+/**
+ * Nest passes its context name (e.g. `RoutesResolver`) last and, for errors, the stack before it. The
+ * name becomes `context` (the pretty `[context=…]`), anything else `nest`.
+ */
 function fields(params) {
-    const ctx = params.filter((p) => p !== undefined);
-    if (ctx.length === 0)
-        return undefined;
-    return { nest: ctx.length === 1 ? ctx[0] : ctx };
+    const rest = params.filter((p) => p !== undefined);
+    const last = rest.at(-1);
+    const out = {};
+    if (typeof last === "string" && /^[A-Za-z][\w.-]*$/.test(last)) {
+        out.context = last;
+        rest.pop();
+    }
+    if (rest.length > 0)
+        out.nest = rest.length === 1 ? rest[0] : rest;
+    return Object.keys(out).length > 0 ? out : undefined;
 }

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

@@ -45,7 +45,10 @@ export declare function createPluginRouter(routes: Route[]): PluginRouter;
  * - `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).
+ *   error message is not echoed), except a `model.hook_denied` `ApiError` that escaped from
+ *   `ctx.models.embed` (an organization policy hook denied the call, spec B §5.4): a deliberate
+ *   outcome, not a failure, so it answers 403 `model.hook_denied` with a generic message (the
+ *   routes are unauthenticated: the policy extension's name and reason are 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`.

package/dist/http/plugin-dispatch.js

@@ -1,6 +1,6 @@
 import { Readable } from "node:stream";
 import FindMyWay from "find-my-way";
-import { errorBody } from "../errors.js";
+import { ApiError, ERROR_CODES, errorBody } from "../errors.js";
 import { ACCESS_COOKIE, REFRESH_COOKIE } from "../identity/cookies.js";
 import { codeForStatus, redactPath } from "./error.filter.js";
 /** 插件路由都在此前缀下（ctx.http.route 已加 `/plugins/<name>` 前缀）。 */
@@ -47,7 +47,10 @@ export function createPluginRouter(routes) {
  * - `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).
+ *   error message is not echoed), except a `model.hook_denied` `ApiError` that escaped from
+ *   `ctx.models.embed` (an organization policy hook denied the call, spec B §5.4): a deliberate
+ *   outcome, not a failure, so it answers 403 `model.hook_denied` with a generic message (the
+ *   routes are unauthenticated: the policy extension's name and reason are 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`.
@@ -108,6 +111,15 @@ export async function registerPluginDispatch(fastify, getTable, log) {
             res = await pluginHandler(webReq);
         }
         catch (err) {
+            if (err instanceof ApiError && err.code === "model.hook_denied") {
+                log.warn("plugin handler refused: a policy hook denied its model call", {
+                    method: req.method,
+                    path: redactPath(path),
+                });
+                return reply
+                    .code(ERROR_CODES["model.hook_denied"])
+                    .send(errorBody(err.code, "An organization policy denied this model call"));
+            }
             log.error("plugin handler failed", { method: req.method, path: redactPath(path), err });
             return reply.code(500).send(errorBody("internal", "Internal error"));
         }