@nylorun/runtime 0.12.0-beta → 0.14.0-beta

package/dist/tenant/http.js

@@ -1,3 +1,9 @@
+/**
+ * The Tenant's typed rejections: what a route or the code it calls throws for the client to
+ * see (`api/http/respond.ts` answers it), and the opaque 404 for unknown credentials (D5).
+ *
+ * Later waves: stable; the streams seam (Wave 2 / Y) keeps using these helpers.
+ */
 /** D5 opaque failure for unknown/rejected credentials on Tenant routes. */
 export const OPAQUE_NOT_FOUND = {
     status: "rejected",
@@ -7,14 +13,18 @@ export const OPAQUE_NOT_FOUND = {
 export class HttpError extends Error {
     status;
     rejection;
-    constructor(status, message, rejection = {}) {
+    headers;
+    constructor(status, message, rejection = {}, 
+    /** Response headers the rejection carries, such as `retry-after` or `www-authenticate`. */
+    headers = {}) {
         super(message);
         this.status = status;
         this.rejection = rejection;
+        this.headers = headers;
     }
 }
-export const fail = (status, message, rejection) => {
-    throw new HttpError(status, message, rejection);
+export const fail = (status, message, rejection, headers) => {
+    throw new HttpError(status, message, rejection, headers);
 };
 export class OpaqueAuthError extends Error {
     status = 404;
@@ -27,27 +37,3 @@ export class OpaqueAuthError extends Error {
 export const failOpaque = () => {
     throw new OpaqueAuthError();
 };
-/** AbortSignal tied to the HTTP request being closed by the client. */
-export function requestAborted(request) {
-    const controller = new AbortController();
-    request.on("close", () => {
-        if (!request.complete)
-            controller.abort();
-    });
-    return controller.signal;
-}
-/** Read a JSON request body, capped at 1 MiB. */
-export async function readBody(request) {
-    let data = "";
-    for await (const chunk of request) {
-        data += chunk;
-        if (Buffer.byteLength(data) > 1024 * 1024)
-            fail(413, "Request too large");
-    }
-    try {
-        return JSON.parse(data);
-    }
-    catch {
-        return fail(400, "Invalid JSON");
-    }
-}

package/dist/tenant/jwt.d.ts

@@ -0,0 +1,16 @@
+export declare const MAX_TOKEN_BYTES = 4096;
+export declare const CLOCK_TOLERANCE_SECONDS = 30;
+/** True when `bearer` has the shape of a JWT; application keys never do. */
+export declare function looksLikeToken(bearer: string): boolean;
+/** The `typ` of a JWT-shaped bearer, or `undefined` when its header cannot be read. */
+export declare function tokenType(raw: string): string | undefined;
+/**
+ * Why the header of a token of type `typ` is refused before any key is read, or its key id
+ * when it is not: `malformed` (size, shape, undecodable) or `header` (algorithm, type, key id,
+ * or a header that could name another key).
+ */
+export declare function tokenKeyId(raw: string, typ: string): {
+    kid: string;
+} | {
+    refused: "malformed" | "header";
+};

package/dist/tenant/jwt.js

@@ -0,0 +1,50 @@
+/**
+ * What subject tokens and delivery tokens share: the Tenant's ES256 JWTs, recognised by shape,
+ * told apart by their `typ`, and refused before any key is read when the header is not one the
+ * Runtime issues.
+ */
+import { decodeProtectedHeader } from "jose";
+import { SIGNING_KEY_ID_PATTERN } from "@nylorun/core/compatibility";
+export const MAX_TOKEN_BYTES = 4096;
+export const CLOCK_TOLERANCE_SECONDS = 30;
+const JWT_SHAPE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const FORBIDDEN_HEADERS = ["jku", "jwk", "x5u", "x5c", "x5t", "crit"];
+/** True when `bearer` has the shape of a JWT; application keys never do. */
+export function looksLikeToken(bearer) {
+    return JWT_SHAPE.test(bearer);
+}
+/** The `typ` of a JWT-shaped bearer, or `undefined` when its header cannot be read. */
+export function tokenType(raw) {
+    if (Buffer.byteLength(raw) > MAX_TOKEN_BYTES || !JWT_SHAPE.test(raw))
+        return undefined;
+    try {
+        const typ = decodeProtectedHeader(raw).typ;
+        return typeof typ === "string" ? typ : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Why the header of a token of type `typ` is refused before any key is read, or its key id
+ * when it is not: `malformed` (size, shape, undecodable) or `header` (algorithm, type, key id,
+ * or a header that could name another key).
+ */
+export function tokenKeyId(raw, typ) {
+    if (Buffer.byteLength(raw) > MAX_TOKEN_BYTES || !JWT_SHAPE.test(raw))
+        return { refused: "malformed" };
+    let header;
+    try {
+        header = decodeProtectedHeader(raw);
+    }
+    catch {
+        return { refused: "malformed" };
+    }
+    if (header.alg !== "ES256" ||
+        header.typ !== typ ||
+        typeof header.kid !== "string" ||
+        !SIGNING_KEY_ID_PATTERN.test(header.kid) ||
+        FORBIDDEN_HEADERS.some((name) => name in header))
+        return { refused: "header" };
+    return { kid: header.kid };
+}

package/dist/tenant/module.d.ts

@@ -1,3 +1,4 @@
+import type { StreamRelayStatus } from "@nylorun/core/contracts";
 import { isQuarantineError, quarantine, TenantBusyError, TenantConflictError } from "./quarantine.js";
 import { TenantNotFoundError, TenantUnavailableError, type Logger, type OpenTenantRuntime, type TenantConfig, type TenantModule, type TenantStore } from "./types.js";
 export interface CreateTenantModuleOptions {
@@ -21,6 +22,8 @@ export interface CreateTenantModuleOptions {
      * Durable Streams basin, its armed sweep). A failure is logged; the Tenant stays deleted.
      */
     onDeleted?: (tenantId: string) => Promise<void>;
+    /** This process's stream relay, for the Host aggregate (a Host with S2 runs one). */
+    relayStatus?: () => Promise<StreamRelayStatus>;
 }
 /**
  * Deep Tenant module (§8): discovery, create, resolve, list, delete and summarize over an

package/dist/tenant/module.js

@@ -7,7 +7,7 @@ import { TenantNotFoundError, TenantUnavailableError, } from "./types.js";
 const OPEN_TIMEOUT_MS = 30_000;
 function hasLiveWork(summary) {
     return (summary.runningSessions > 0 ||
-        summary.connectedExecutors > 0 ||
+        summary.inFlightDeliveries > 0 ||
         summary.pendingActions > 0);
 }
 function toAdmin(id, entry, envelope) {
@@ -284,28 +284,22 @@ export function createTenantModule(options) {
         },
         async summarize() {
             let runningSessions = 0;
-            let connectedExecutors = 0;
+            let inFlightDeliveries = 0;
             let pendingActions = 0;
             let uncertainEffects = 0;
-            let outboxDepth;
-            let relayLagMs;
             for (const s of await Promise.all(openEntries().map((e) => e.handle.summary()))) {
                 runningSessions += s.runningSessions;
-                connectedExecutors += s.connectedExecutors;
+                inFlightDeliveries += s.inFlightDeliveries;
                 pendingActions += s.pendingActions;
                 uncertainEffects += s.uncertainEffects;
-                if (s.outboxDepth !== undefined)
-                    outboxDepth = (outboxDepth ?? 0) + s.outboxDepth;
-                if (s.relayLagMs !== undefined)
-                    relayLagMs = Math.max(relayLagMs ?? 0, s.relayLagMs);
             }
+            const relay = await options.relayStatus?.().catch(() => undefined);
             return {
                 runningSessions,
-                connectedExecutors,
+                inFlightDeliveries,
                 pendingActions,
                 uncertainEffects,
-                ...(outboxDepth !== undefined ? { outboxDepth } : {}),
-                ...(relayLagMs !== undefined ? { relayLagMs } : {}),
+                ...(relay ? { relay } : {}),
             };
         },
         async close() {

package/dist/tenant/outbound.d.ts

@@ -0,0 +1,44 @@
+import { type IncomingHttpHeaders } from "node:http";
+/** How the Host lets the Runtime call developer URLs (Host settings, `TenantConfig.delivery`). */
+export interface OutboundPolicy {
+    /** `http` URLs as well as `https`. Default true (OSS). */
+    allowHttp?: boolean;
+    /** Private, loopback and link-local addresses. Default `allow` (OSS); Cloud refuses. */
+    privateAddresses?: "allow" | "refuse";
+    /**
+     * `docker-host`: the Runtime runs in the local stack's container, so `localhost`,
+     * `127.0.0.1` and `[::1]` mean the machine that runs Docker (`host.docker.internal`).
+     */
+    loopback?: "docker-host";
+}
+export type OutboundResult = {
+    kind: "response";
+    status: number;
+    headers: IncomingHttpHeaders;
+    body: Buffer;
+}
+/** The answer was larger than `maxResponseBytes`. */
+ | {
+    kind: "too_large";
+    status: number;
+} | {
+    kind: "not_sent";
+    code: string;
+    message: string;
+} | {
+    kind: "lost";
+    code: string;
+    message: string;
+};
+/** The largest answer read from an endpoint. */
+export declare const MAX_RESPONSE_BYTES: number;
+/** True when `address` is private, loopback, link-local or unspecified (IPv4-mapped included). */
+export declare function isPrivateAddress(address: string): boolean;
+/** Why the Host refuses `url`, or `undefined` when it may be called. */
+export declare function refusal(url: URL, policy: OutboundPolicy): string | undefined;
+/** POSTs `body` to `url` under `policy`. Never throws; `signal` aborts the request. */
+export declare function post(target: string, body: string, headers: Record<string, string>, options: {
+    policy: OutboundPolicy;
+    signal: AbortSignal;
+    maxResponseBytes?: number;
+}): Promise<OutboundResult>;

package/dist/tenant/outbound.js

@@ -0,0 +1,127 @@
+/**
+ * The Runtime's requests to Action endpoints (design: Action endpoints §8.3): one POST, no
+ * redirects, a bounded answer, and the Host's address policy checked on the address actually
+ * connected to, so a DNS answer cannot steer a delivery somewhere the Host forbids.
+ *
+ * The result says whether anything reached the endpoint. A request that failed before its body
+ * was flushed (refused connection, unknown host, TLS failure, a refused address) was `not_sent`
+ * and is safe to send again, even for a tool; one that failed after (reset, timeout) is `lost`.
+ */
+import { lookup as dnsLookup } from "node:dns";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { BlockList, isIP } from "node:net";
+/** The largest answer read from an endpoint. */
+export const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const PRIVATE = new BlockList();
+for (const [network, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.168.0.0", 16],
+])
+    PRIVATE.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+    ["::", 128],
+    ["::1", 128],
+    ["fc00::", 7],
+    ["fe80::", 10],
+])
+    PRIVATE.addSubnet(network, prefix, "ipv6");
+/** True when `address` is private, loopback, link-local or unspecified (IPv4-mapped included). */
+export function isPrivateAddress(address) {
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+    if (mapped)
+        return PRIVATE.check(mapped[1], "ipv4");
+    const family = isIP(address);
+    if (family === 0)
+        return false;
+    return PRIVATE.check(address, family === 4 ? "ipv4" : "ipv6");
+}
+class RefusedAddress extends Error {
+    code = "ENDPOINT_ADDRESS_REFUSED";
+}
+/** Why the Host refuses `url`, or `undefined` when it may be called. */
+export function refusal(url, policy) {
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && policy.allowHttp !== false))
+        return `This Runtime calls only ${policy.allowHttp === false ? "https" : "http and https"} endpoints`;
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (policy.privateAddresses === "refuse" && isIP(host) && isPrivateAddress(host))
+        return "This Runtime does not call private addresses; expose the endpoint through a public URL (a tunnel, for a local app)";
+    return undefined;
+}
+/** POSTs `body` to `url` under `policy`. Never throws; `signal` aborts the request. */
+export async function post(target, body, headers, options) {
+    const { policy, signal } = options;
+    const limit = options.maxResponseBytes ?? MAX_RESPONSE_BYTES;
+    const url = new URL(target);
+    const refused = refusal(url, policy);
+    if (refused)
+        return { kind: "not_sent", code: "ENDPOINT_ADDRESS_REFUSED", message: refused };
+    const originalHost = url.host;
+    if (policy.loopback === "docker-host" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))
+        url.hostname = "host.docker.internal";
+    const lookup = (hostname, lookupOptions, callback) => dnsLookup(hostname, { ...lookupOptions, all: true }, (error, addresses) => {
+        if (error)
+            return callback(error, []);
+        const allowed = policy.privateAddresses === "refuse"
+            ? addresses.filter((a) => !isPrivateAddress(a.address))
+            : addresses;
+        if (allowed.length === 0)
+            return callback(new RefusedAddress(`${hostname} resolves only to private addresses, which this Runtime does not call`), []);
+        if (lookupOptions.all)
+            return callback(null, allowed);
+        return callback(null, allowed[0].address, allowed[0].family);
+    });
+    return new Promise((resolve) => {
+        let sent = false;
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const failed = (error) => finish({
+            kind: sent ? "lost" : "not_sent",
+            code: signal.aborted ? "ABORTED" : (error.code ?? error.name),
+            message: signal.aborted ? "The delivery was aborted" : error.message,
+        });
+        const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
+            method: "POST",
+            headers: {
+                ...headers,
+                host: originalHost,
+                "content-type": "application/json",
+                "content-length": String(Buffer.byteLength(body)),
+            },
+            lookup: lookup,
+            signal,
+        }, (response) => {
+            const status = response.statusCode ?? 0;
+            const chunks = [];
+            let size = 0;
+            response.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > limit) {
+                    // Settle first: destroying the answer reports an error of its own.
+                    finish({ kind: "too_large", status });
+                    response.destroy();
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on("end", () => finish({ kind: "response", status, headers: response.headers, body: Buffer.concat(chunks) }));
+            response.on("error", failed);
+            response.on("aborted", () => failed(Object.assign(new Error("The answer was cut off"), { code: "ECONNRESET" })));
+        });
+        request.on("finish", () => {
+            sent = true;
+        });
+        request.on("error", failed);
+        request.end(body);
+    });
+}

package/dist/tenant/pool.d.ts

@@ -1,5 +1,3 @@
-/** Run async work over items with a fixed concurrency limit. */
-export declare function mapPool<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
 export declare class TimeoutError extends Error {
     constructor(message?: string);
 }

package/dist/tenant/pool.js

@@ -1,21 +1,3 @@
-/** Run async work over items with a fixed concurrency limit. */
-export async function mapPool(items, concurrency, worker) {
-    if (items.length === 0)
-        return [];
-    const limit = Math.max(1, Math.min(concurrency, items.length));
-    const results = new Array(items.length);
-    let next = 0;
-    async function run() {
-        for (;;) {
-            const index = next++;
-            if (index >= items.length)
-                return;
-            results[index] = await worker(items[index], index);
-        }
-    }
-    await Promise.all(Array.from({ length: limit }, () => run()));
-    return results;
-}
 export class TimeoutError extends Error {
     constructor(message = "operation timed out") {
         super(message);

package/dist/tenant/reset.d.ts

@@ -1,17 +1,13 @@
 import type { ResetScope, SessionStore } from "../store/types.js";
-import type { ExecutorRegistry } from "../core/executors.js";
 import type { SandboxManager } from "../sandbox/manager.js";
 import type { TenantPaths } from "./types.js";
 export type { ResetScope } from "../store/types.js";
 export interface ResetTenantContext {
     store: SessionStore;
-    registry: ExecutorRegistry;
     sandbox: SandboxManager;
     paths: TenantPaths;
     /** Clear in-memory session observers after the store wipe. */
     clearSessionState: () => void;
-    /** Clear executor SSE streams when registrations are removed. */
-    clearExecutorStreams: () => void;
 }
 /**
  * Reset Tenant durable state for `scope` (A17).

package/dist/tenant/reset.js

@@ -42,13 +42,8 @@ export async function resetTenant(ctx, scope) {
         await ctx.sandbox.reconcile(() => false);
     }
     await ctx.store.tx((t) => t.reset(scope));
-    if (clearAll)
-        for (const row of ctx.registry.list())
-            ctx.registry.remove(row.agentId);
     if (clearSessions)
         ctx.clearSessionState();
-    if (clearAll)
-        ctx.clearExecutorStreams();
     if (clearSandboxes)
         replaceDirectory(ctx.paths.sandboxes);
     if (clearAll) {

package/dist/tenant/runtime.d.ts

@@ -1,25 +1,8 @@
-/**
- * Composition root of an open Tenant: validates the config, opens the Session Store and the
- * vault key, builds the services and the `TenantContext`, wires the seams, registers the
- * Tenant's Worker handlers and arms its sweep, and implements `TenantHandle` (handle,
- * summary, drain, close) by delegating to the Tenant modules.
- *
- * Seams wired here: `wireStreams()` connects the store's commits to Durable Streams (the
- * relay, and the history, SSE, work and control readers); `wake` goes to the
- * `DurableExecution`, whose handlers (`worker.ts`) call `advance` and `sweep`; `abortLocal`
- * aborts an advance running on this process. The sweep also drains the outbox.
- *
- * Execution: the Host passes one `TenantExecution` for every Tenant it opens
- * (`TenantOpenHooks.execution`); without one, the Tenant runs its own in-process
- * `MemoryExecution`. No lock file: several processes may open a Tenant, and ownership of each
- * session (§10.6) keeps its advances apart.
- */
-import type { ServerResponse, IncomingMessage } from "node:http";
 import type { TenantEnvelope } from "@nylorun/core/contracts";
 import { type ModelProvider } from "../core/provider.js";
 import { type AuthorizeResult } from "../vault/service.js";
 import type { DurableStreams } from "../streams/types.js";
-import type { OpenedTenant, TenantConfig, TenantHandle, TenantSummary } from "./types.js";
+import type { NodeBindings, OpenedTenant, TenantConfig, TenantHandle, TenantSummary } from "./types.js";
 import { type StreamsStatus } from "./streams.js";
 import { type TenantExecution, type TenantWorker } from "./worker.js";
 /** TENANTS-CCR: test/injection hooks until TenantConfig gains them. */
@@ -42,6 +25,13 @@ export type TenantOpenHooks = {
      * survive a restart (tests, and a Host without S2).
      */
     streams?: DurableStreams;
+    /**
+     * The Host's stream relay feeds `streams` from the record for every Tenant. Without it the
+     * Tenant relays its own commits.
+     */
+    hostRelay?: boolean;
+    /** How long a retired stream basin is kept after a reset (tests). Default 60 s. */
+    retireGraceMs?: number;
 } & OpenedTenant;
 export declare class TenantRuntime implements TenantHandle {
     private readonly ctx;
@@ -53,7 +43,7 @@ export declare class TenantRuntime implements TenantHandle {
     private readonly closeGraceMs;
     private constructor();
     static open(config: TenantConfig, hooks: TenantOpenHooks): Promise<TenantRuntime>;
-    handle(request: IncomingMessage, response: ServerResponse, url?: URL): Promise<void>;
+    fetch(request: Request, node: NodeBindings): Promise<Response>;
     authorize(sessionId: string, request: {
         url: string;
         serverName?: string;
@@ -67,7 +57,7 @@ export declare class TenantRuntime implements TenantHandle {
     abortLocal(sessionId: string): void;
     /**
      * The Durable Streams seam's status for Tenant status and readiness: S2 reachability, the
-     * basin, outbox depth and relay lag (`streamsStatus` in `tenant/streams.ts`).
+     * basin, its generation and the Tenant's relay (`streamsStatus` in `tenant/streams.ts`).
      */
     streamsStatus(): Promise<StreamsStatus>;
     /** Adds a callback to the Tenant sweep. Returns a function that removes it. */