@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/host/app.js

@@ -0,0 +1,181 @@
+import { Hono } from "hono";
+import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
+import { checkCompatibility, HOST_PROTOCOL, PROTOCOL_HEADER, PUBLISHABLE_KEY_HEADER, TENANT_HEADER, tenantOfPublishableKey, } from "@nylorun/core/compatibility";
+import { RUNTIME_VERSION } from "../version.js";
+import { findTenantRoute } from "../api/http/app.js";
+import { tenantDocument } from "../api/openapi.js";
+import { answerPreflight } from "./cors.js";
+import { adminKeyMatches, headerValue, isJsonContentType, jsonResponse, opaqueNotFoundResponse, protocolRejectedResponse, readBearer, pathnameIsLogged, redactRoutePath, rejectedResponse, requestHasBody, } from "./http.js";
+export function createHostApp(options) {
+    const { module, logger } = options;
+    const app = new Hono();
+    app.use(async (c, next) => {
+        const started = Date.now();
+        try {
+            await next();
+        }
+        finally {
+            const { incoming } = c.env;
+            if (pathnameIsLogged(incoming.url))
+                logger.info("request", {
+                    status: statusOf(c),
+                    tenantId: c.get("tenantId"),
+                    durationMs: Date.now() - started,
+                    path: redactRoutePath(pathnameOf(incoming)),
+                    method: incoming.method,
+                });
+        }
+    });
+    app.use(async (c, next) => {
+        const { incoming, outgoing, role } = c.env;
+        if (headerValue(incoming, "origin") !== undefined) {
+            const route = pathnameOf(incoming).split("/").filter(Boolean);
+            // Only Tenant routes, and only when the operator allows browsers; the Tenant then
+            // checks the publishable key and its origins before adding any CORS header.
+            const tenantRoute = route[0] === "v1" && route[1] !== "admin";
+            // The operator listener never serves browsers.
+            if (!options.browserAccess || role === "operator" || !tenantRoute)
+                return rejectedResponse(403, "origin_rejected", "Browser Origin headers are not accepted");
+            if (incoming.method === "OPTIONS") {
+                c.set("status", answerPreflight(incoming, outgoing, route, browserRoute));
+                return RESPONSE_ALREADY_SENT;
+            }
+        }
+        await next();
+    });
+    app.use(async (c, next) => {
+        const { incoming } = c.env;
+        if (requestHasBody(incoming) && !isJsonContentType(headerValue(incoming, "content-type")))
+            return rejectedResponse(415, "unsupported_media_type", "Request bodies must use application/json");
+        await next();
+    });
+    app.all("*", async (c) => {
+        const { incoming, outgoing, role } = c.env;
+        const url = new URL(incoming.url ?? "/", "http://runtime.local");
+        const pathname = url.pathname;
+        if (pathname === "/health")
+            return jsonResponse(200, {
+                status: "ok",
+                service: "nylorun-runtime",
+                version: RUNTIME_VERSION,
+                protocol: {
+                    min: HOST_PROTOCOL.min,
+                    max: HOST_PROTOCOL.max,
+                    features: [...HOST_PROTOCOL.features],
+                },
+                coreVersion: options.coreVersion,
+                hostId: options.hostId,
+                pid: options.pid,
+            });
+        if (pathname === "/ready") {
+            const listener = options.listening();
+            const tenant = module.ready;
+            const infra = await options.readiness?.();
+            const ready = listener && tenant && !options.closing() && (infra?.ok ?? true);
+            return jsonResponse(ready ? 200 : 503, {
+                status: ready ? "ready" : "not_ready",
+                service: "nylorun-runtime",
+                checks: { listener, tenant, ...infra?.checks },
+            });
+        }
+        // This API's own description: public, as the npm package that ships it.
+        if (pathname === "/openapi.json" && incoming.method === "GET")
+            return jsonResponse(200, tenantDocument(), { "cache-control": "no-cache" });
+        const segments = pathname.split("/").filter(Boolean);
+        if (segments[0] === "v1" && segments[1] === "admin") {
+            // A public listener has no admin routes: the same 404 as a wrong admin key.
+            if (role === "public")
+                return opaqueNotFoundResponse();
+            if (!protocolAccepted(headerValue(incoming, PROTOCOL_HEADER)))
+                return protocolRejectedResponse();
+            const token = readBearer(headerValue(incoming, "authorization"));
+            if (!adminKeyMatches(token, options.adminKey))
+                return opaqueNotFoundResponse();
+            return await options.admin(c.req.raw, { incoming, outgoing });
+        }
+        // Tenant routes: key pattern → protocol → the Tenant → selection → the Tenant's routes.
+        const keyHeader = headerValue(incoming, PUBLISHABLE_KEY_HEADER);
+        const keyTenant = keyHeader === undefined ? undefined : tenantOfPublishableKey(keyHeader);
+        if (keyHeader !== undefined && keyTenant === undefined)
+            return rejectedResponse(400, "invalid_request", `${PUBLISHABLE_KEY_HEADER} header is malformed`);
+        const tenantHeader = headerValue(incoming, TENANT_HEADER);
+        const named = tenantHeader === undefined || tenantHeader.trim() === "" ? undefined : tenantHeader.trim();
+        if (!protocolAccepted(headerValue(incoming, PROTOCOL_HEADER)))
+            return protocolRejectedResponse();
+        const resolution = await module.resolve();
+        if (resolution.kind !== "open") {
+            if (resolution.cause)
+                logger.warn("tenant_unavailable", {
+                    code: resolution.cause.code,
+                    repair: resolution.cause.repair,
+                });
+            return opaqueNotFoundResponse();
+        }
+        const { handle } = resolution;
+        const tenantId = handle.envelope.id;
+        // A protocol 4 client names the Tenant; a publishable key carries one. Either naming
+        // another Tenant (or a malformed header) reached the wrong installation.
+        if ((named !== undefined && named !== tenantId) || (keyTenant !== undefined && keyTenant !== tenantId))
+            return opaqueNotFoundResponse();
+        c.set("tenantId", tenantId);
+        return await handle.fetch(c.req.raw, { incoming, outgoing });
+    });
+    app.onError((error, c) => {
+        const status = error.status;
+        let rejection;
+        if (typeof status === "number" && status >= 400 && status < 600) {
+            rejection = {
+                status,
+                code: status === 400 ? "invalid_request" : "request_rejected",
+                message: error.message,
+            };
+        }
+        else if (error.name === "ZodError") {
+            rejection = { status: 400, code: "invalid_request", message: "Invalid request body" };
+        }
+        else {
+            logger.error("request_failed", { error: error.message });
+            rejection = { status: 500, code: "internal_error", message: "Internal error" };
+        }
+        c.set("status", rejection.status);
+        const { outgoing } = c.env;
+        // Once a response has started, the rejection can only end it.
+        if (outgoing.headersSent) {
+            outgoing.end();
+            return RESPONSE_ALREADY_SENT;
+        }
+        return rejectedResponse(rejection.status, rejection.code, rejection.message);
+    });
+    return app;
+}
+/** A route a browser page may call, decided from the route alone (`api/http/define.ts`). */
+function browserRoute(method, segments) {
+    return findTenantRoute(method, segments)?.browser === true;
+}
+/** The answer's status: a Response's, or the Node response's when it was written there. */
+function statusOf(c) {
+    const logged = c.get("status");
+    if (logged !== undefined)
+        return logged;
+    if (c.res.headers.has(ALREADY_SENT))
+        return c.env.outgoing.statusCode || 200;
+    return c.res.status;
+}
+const ALREADY_SENT = "x-hono-already-sent";
+function pathnameOf(incoming) {
+    return new URL(incoming.url ?? "/", "http://runtime.local").pathname;
+}
+function parseProtocolVersion(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    return Number(trimmed);
+}
+function protocolAccepted(raw) {
+    const version = parseProtocolVersion(raw);
+    if (version === undefined)
+        return false;
+    return checkCompatibility({ version, required: [] }, HOST_PROTOCOL).ok;
+}

package/dist/host/config-for.d.ts

@@ -1,7 +1,7 @@
 import type { HostConfigFile } from "./config.js";
 import type { Logger, TenantConfig } from "../tenant/types.js";
 /**
- * Builds a TenantConfig for `openTenantRuntime`.
+ * Builds the TenantConfig of the Host's Tenant for `openTenantRuntime`.
  * The sandbox backend here is the Host default; a Tenant's seeded `sandbox.backend`
  * setting overrides it when the Tenant opens (I1, A18).
  */
@@ -14,4 +14,6 @@ export declare function configForFactory(options: {
     mode?: TenantConfig["mode"];
     /** Override model; default vault. Fixture/scripted require ephemeral/test mode. */
     model?: TenantConfig["model"];
+    /** How Tenants may call Action endpoints (`StackConfig.delivery`). */
+    delivery?: TenantConfig["delivery"];
 }): (id: string) => TenantConfig;

package/dist/host/config-for.js

@@ -1,14 +1,14 @@
 import { tenantPaths } from "../tenant/paths.js";
 import { tenantChildEnvironment } from "./environment.js";
 /**
- * Builds a TenantConfig for `openTenantRuntime`.
+ * Builds the TenantConfig of the Host's Tenant for `openTenantRuntime`.
  * The sandbox backend here is the Host default; a Tenant's seeded `sandbox.backend`
  * setting overrides it when the Tenant opens (I1, A18).
  */
 export function configForFactory(options) {
     const { baseline } = options;
     return (id) => {
-        const tenant = tenantPaths(options.hostRoot, id);
+        const tenant = tenantPaths(options.hostRoot);
         const sandboxBackend = "auto";
         return {
             tenantId: id,
@@ -16,6 +16,7 @@ export function configForFactory(options) {
             paths: tenant,
             sandbox: { backend: sandboxBackend },
             model: options.model ?? { kind: "vault" },
+            ...(options.delivery ? { delivery: options.delivery } : {}),
             childEnv: tenantChildEnvironment(baseline, options.hostConfig, tenant),
             logger: {
                 info: (message, fields) => options.logger.info(message, { tenantId: id, ...fields }),

package/dist/host/config.d.ts

@@ -4,6 +4,17 @@ export interface HostConfigFile {
     host: string;
     port: number;
     allowNonLoopback?: boolean;
+    /**
+     * Whether browser requests (an `Origin` with a publishable key) may reach Tenant routes.
+     * Default off for a Host started from host.json; container mode reads
+     * `NYLORUN_BROWSER_ACCESS` instead.
+     */
+    browserAccess?: boolean;
+    /**
+     * The operator listener's port: the Admin API moves there (on `host`, loopback only), and
+     * `port` serves the Tenant API alone. Absent: one port serves both.
+     */
+    adminPort?: number;
     proxy?: {
         httpsProxy?: string;
         noProxy?: string;

package/dist/host/cors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser access at the Host (Host feature `browser-access`). A preflight carries no
+ * credentials and no header values, so it cannot name a Tenant: the Host answers it from the
+ * route alone, permissively for browser routes, and the Tenant enforces the publishable key's
+ * origin allowlist on the actual request (`tenant/browser.ts`). A cached preflight therefore
+ * never widens access, and it grants no credentials.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** Request headers a browser may send to the Runtime. */
+export declare const BROWSER_REQUEST_HEADERS: readonly ["authorization", "content-type", "nylorun-key", "nylorun-tenant", "nylorun-protocol", "last-event-id"];
+/**
+ * Tenant routes a browser may call: agents (list), sessions (not the sandbox tool route),
+ * vaults, AG-UI and the JWKS. Tokens, access management, endpoints, actions and Tenant
+ * settings never are.
+ */
+/** The `Origin` header if it is a serialized origin (not `null`, not a path). */
+export declare function browserOrigin(request: IncomingMessage): string | undefined;
+/**
+ * Answers a CORS preflight: `204` with the allowed methods and headers for a browser route,
+ * `403` without any CORS header otherwise.
+ */
+export declare function answerPreflight(request: IncomingMessage, response: ServerResponse, segments: readonly string[], isBrowserRoute: (method: string, segments: readonly string[]) => boolean): number;
+/**
+ * CORS headers for an actual request from an allowed origin; set once with `setHeader`, so
+ * every response that follows (JSON, errors, SSE) carries them.
+ */
+export declare function setCorsHeaders(response: ServerResponse, origin: string): void;

package/dist/host/cors.js

@@ -0,0 +1,64 @@
+import { isSerializedOrigin } from "@nylorun/core/contracts";
+/** Request headers a browser may send to the Runtime. */
+export const BROWSER_REQUEST_HEADERS = [
+    "authorization",
+    "content-type",
+    "nylorun-key",
+    "nylorun-tenant",
+    "nylorun-protocol",
+    "last-event-id",
+];
+const BROWSER_METHODS = ["GET", "POST", "PUT", "DELETE"];
+const PREFLIGHT_MAX_AGE_SECONDS = 600;
+/**
+ * Tenant routes a browser may call: agents (list), sessions (not the sandbox tool route),
+ * vaults, AG-UI and the JWKS. Tokens, access management, endpoints, actions and Tenant
+ * settings never are.
+ */
+/** The `Origin` header if it is a serialized origin (not `null`, not a path). */
+export function browserOrigin(request) {
+    const raw = request.headers.origin;
+    const origin = Array.isArray(raw) ? raw[0] : raw;
+    return origin !== undefined && isSerializedOrigin(origin) ? origin : undefined;
+}
+/**
+ * Answers a CORS preflight: `204` with the allowed methods and headers for a browser route,
+ * `403` without any CORS header otherwise.
+ */
+export function answerPreflight(request, response, segments, isBrowserRoute) {
+    const origin = browserOrigin(request);
+    const method = String(request.headers["access-control-request-method"] ?? "").toUpperCase();
+    const requested = String(request.headers["access-control-request-headers"] ?? "")
+        .split(",")
+        .map((name) => name.trim().toLowerCase())
+        .filter(Boolean);
+    const allowed = origin !== undefined &&
+        BROWSER_METHODS.includes(method) &&
+        isBrowserRoute(method, segments) &&
+        requested.every((name) => BROWSER_REQUEST_HEADERS.includes(name));
+    if (!allowed) {
+        response.writeHead(403, { "content-length": "0" });
+        response.end();
+        return 403;
+    }
+    response.writeHead(204, {
+        "access-control-allow-origin": origin,
+        "access-control-allow-methods": BROWSER_METHODS.join(", "),
+        "access-control-allow-headers": requested.join(", "),
+        "access-control-max-age": String(PREFLIGHT_MAX_AGE_SECONDS),
+        vary: "Origin, Access-Control-Request-Method, Access-Control-Request-Headers",
+        "content-length": "0",
+    });
+    response.end();
+    return 204;
+}
+/**
+ * CORS headers for an actual request from an allowed origin; set once with `setHeader`, so
+ * every response that follows (JSON, errors, SSE) carries them.
+ */
+export function setCorsHeaders(response, origin) {
+    response.setHeader("access-control-allow-origin", origin);
+    response.setHeader("vary", "Origin");
+    response.setHeader("access-control-expose-headers", "retry-after, www-authenticate");
+    response.setHeader("cache-control", "no-store");
+}

package/dist/host/create-host.d.ts

@@ -1,4 +1,4 @@
-import { type Logger, type TenantModule } from "../tenant/types.js";
+import type { Logger, TenantModule } from "../tenant/types.js";
 import type { HostConfigFile, HostCredentialsFile } from "./config.js";
 import type { ContainerListen } from "./stack-config.js";
 export interface CreateHostOptions {
@@ -23,20 +23,34 @@ export interface CreateHostOptions {
      * mode is `http://0.0.0.0:4000`.
      */
     publicUrl?: string;
+    /**
+     * Browser access (Host feature `browser-access`): requests with an `Origin` may reach Tenant
+     * routes, where the publishable key's origin allowlist decides. Off by default: every
+     * `Origin` is `403 origin_rejected`, as before. Admin routes, `/health` and `/ready` refuse
+     * `Origin` either way.
+     */
+    browserAccess?: boolean;
+    /**
+     * The operator listener: the Admin API (and the Tenant API, never with browser access) on
+     * its own address, kept off the network that reaches the Tenant API. When set, the main
+     * listener is public and answers admin routes with the opaque 404. Absent: one listener
+     * serves everything, as before.
+     */
+    operator?: OperatorListen;
     /**
      * Infrastructure readiness (`infra/readiness.ts`). `/ready` adds its checks
-     * and answers 503 while it reports not ok. Default: listener and discovery
-     * only.
+     * and answers 503 while it reports not ok. Default: the listener and the
+     * Tenant only.
      */
     readiness?: () => Promise<{
         ok: boolean;
         checks: Record<string, boolean>;
     }>;
     /**
-     * Shutdown steps around closing the Tenants. `close()` runs them whatever asked for it
+     * Shutdown steps around closing the Tenant. `close()` runs them whatever asked for it
      * (SIGTERM in `host/main.ts`, `POST /v1/admin/host/shutdown`): the listener stops, then
-     * `beforeTenants` (stop the Worker so no advance starts on a closing Tenant), the Tenants
-     * close, then `afterTenants` (end the infrastructure clients). A failing step is logged
+     * `beforeTenants` (stop the Worker so no advance starts on the closing Tenant), the Tenant
+     * closes, then `afterTenants` (end the infrastructure clients). A failing step is logged
      * and shutdown goes on.
      */
     shutdown?: {
@@ -44,13 +58,27 @@ export interface CreateHostOptions {
         afterTenants?(): Promise<void>;
     };
 }
+/** Where the operator listener binds, and the `Host` values it accepts. */
+export interface OperatorListen {
+    host: string;
+    port: number;
+    /** Exact `Host` values (lowercase `name:port`); absent means the loopback forms of the port. */
+    allowedHosts?: readonly string[];
+}
+/**
+ * What a listener serves. `combined`: everything (one port). `public`: the Tenant API, with
+ * browser access when enabled; admin routes are the opaque 404. `operator`: the Admin API and
+ * the Tenant API, never to browsers.
+ */
+export type ListenerRole = "combined" | "public" | "operator";
 export interface HostServer {
     listen(): Promise<void>;
     close(): Promise<void>;
     /** Settles once `close()` has finished, whatever called it. */
     readonly closed: Promise<void>;
     readonly url: string;
+    /** Where the Admin API answers: the operator listener, or `url` when there is one listener. */
+    readonly adminUrl: string;
 }
-/** Constant-time comparison of SHA-256 digests of the presented and stored admin keys. */
-export declare function adminKeyMatches(presented: string | undefined, adminKey: string): boolean;
+export { adminKeyMatches } from "./http.js";
 export declare function createHost(options: CreateHostOptions): HostServer;