@nylorun/runtime 0.14.0-beta → 0.15.0-beta

package/dist/host/stack-config.js

@@ -3,6 +3,18 @@
  * snapshot and argv. Pure: `host/main.ts` passes the process environment and
  * arguments; nothing here reads ambient state.
  *
+ * `--service core,loop` names the Runtime services the process runs (blueprint
+ * §19, D12): one image runs every service, and a container may pack several.
+ * Without the flag a process runs core and loop. `--role api|worker|all` is
+ * the deprecated name of the same choice (core, loop, or both). `gates` (the
+ * Model Gate) never shares a process with core or loop: it holds the
+ * credentials they must not. Only a process that runs core or loop parses the
+ * API listener (`NYLORUN_LISTEN_*`); only one that runs gates parses its
+ * listener (`NYLORUN_GATES_LISTEN_*`), and only one that runs loop parses
+ * where to reach the gate (`NYLORUN_GATES_URL`). Both read
+ * `NYLORUN_GATES_TOKEN`. In a container, loop requires the gate: the loop
+ * process must never hold a model credential.
+ *
  * Two listen modes:
  * - **local** (no `NYLORUN_LISTEN_*` / `NYLORUN_ALLOWED_HOSTS`): the Host binds
  *   what `host.json` names, loopback only unless `allowNonLoopback`.
@@ -12,9 +24,41 @@
  *   probes from inside the container.
  *
  * The Postgres, Restate and S2 endpoints are parsed and validated here;
- * `infra/*` builds the clients from them.
+ * `infra/*` builds the clients from them. So is who the Host's Tenant is when its database
+ * holds none yet (`NYLORUN_TENANT_ID`, `NYLORUN_TENANT_NAME`, `NYLORUN_DERIVED_PRINCIPALS`).
+ */
+import { DERIVED_PRINCIPAL_ID_PATTERN, isTenantId } from "@nylorun/core/compatibility";
+export const RUNTIME_SERVICES = ["core", "loop", "gates", "keys"];
+/**
+ * Services that may share a process (D12): they hold the same secrets and parse the same
+ * trust class of input. keys joins gates (F4.2); egress joins them in a later release.
  */
-export const RUNTIME_ROLES = ["api", "worker", "all"];
+const SERVICE_GROUPS = [
+    ["core", "loop"],
+    ["gates", "keys"],
+];
+/** Where the gates service listens by default. */
+export const DEFAULT_GATES_LISTEN_PORT = 4100;
+/** What a process runs without `--service`: core and loop, as `--role all` did. */
+export const DEFAULT_SERVICES = new Set([
+    "core",
+    "loop",
+]);
+/** Services of the blueprint this release doesn't have yet. */
+const LATER_SERVICES = [
+    "egress",
+    "harness",
+    "sandboxd",
+];
+const ROLE_SERVICES = {
+    api: ["core"],
+    worker: ["loop"],
+    all: ["core", "loop"],
+};
+/** `services` as the `--service` value that selects them, e.g. `core,loop`. */
+export function describeServices(services) {
+    return RUNTIME_SERVICES.filter((service) => services.has(service)).join(",");
+}
 export const DEFAULT_CONTAINER_LISTEN_HOST = "0.0.0.0";
 export const DEFAULT_CONTAINER_LISTEN_PORT = 4000;
 export class StackConfigError extends Error {
@@ -30,30 +74,69 @@ function read(env, name) {
     const trimmed = value.trim();
     return trimmed === "" ? undefined : trimmed;
 }
-export function parseRole(argv) {
+const USAGE = "Usage: main.js [--service core,loop|gates]";
+/** Parses `--service a,b` (or the deprecated `--role`); throws `StackConfigError`. */
+export function parseServices(argv) {
+    let service;
     let role;
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
+        const flag = arg.startsWith("--service")
+            ? "--service"
+            : arg.startsWith("--role")
+                ? "--role"
+                : undefined;
         let value;
-        if (arg === "--role") {
+        if (flag && arg === flag) {
             value = argv[index + 1];
             index += 1;
             if (value === undefined || value.startsWith("-"))
-                throw new StackConfigError("--role requires a value: api, worker or all");
+                throw new StackConfigError(flag === "--service"
+                    ? "--service requires a value, e.g. core,loop"
+                    : "--role requires a value: api, worker or all");
         }
-        else if (arg.startsWith("--role=")) {
-            value = arg.slice("--role=".length);
+        else if (flag && arg.startsWith(`${flag}=`)) {
+            value = arg.slice(flag.length + 1);
         }
         else {
-            throw new StackConfigError(`Unknown argument ${arg}. Usage: main.js [--role api|worker|all]`);
+            throw new StackConfigError(`Unknown argument ${arg}. ${USAGE}`);
         }
-        if (role !== undefined)
-            throw new StackConfigError("--role may only be supplied once");
-        if (!RUNTIME_ROLES.includes(value))
-            throw new StackConfigError(`Invalid --role ${value}; expected api, worker or all`);
-        role = value;
+        if ((flag === "--service" ? service : role) !== undefined)
+            throw new StackConfigError(`${flag} may only be supplied once`);
+        if (flag === "--service")
+            service = value;
+        else
+            role = value;
     }
-    return role ?? "all";
+    if (service !== undefined && role !== undefined)
+        throw new StackConfigError("--role is the deprecated name of --service; supply only --service");
+    if (role !== undefined) {
+        if (!Object.hasOwn(ROLE_SERVICES, role))
+            throw new StackConfigError(`Invalid --role ${role}; expected api, worker or all (deprecated: use --service core, loop or core,loop)`);
+        const deprecatedRole = role;
+        return { services: new Set(ROLE_SERVICES[deprecatedRole]), deprecatedRole };
+    }
+    if (service === undefined)
+        return { services: DEFAULT_SERVICES };
+    const names = service.split(",").map((name) => name.trim());
+    const services = new Set();
+    for (const name of names) {
+        if (name === "")
+            throw new StackConfigError(`--service ${service} has an empty entry. ${USAGE}`);
+        if (name === "all")
+            throw new StackConfigError("--service all is not a service; use --service core,loop");
+        if (LATER_SERVICES.includes(name))
+            throw new StackConfigError(`The ${name} service is not in this release of the Runtime`);
+        if (!RUNTIME_SERVICES.includes(name))
+            throw new StackConfigError(`Unknown service ${name}; expected ${RUNTIME_SERVICES.join(" or ")}`);
+        if (services.has(name))
+            throw new StackConfigError(`--service names ${name} twice`);
+        services.add(name);
+    }
+    const groups = SERVICE_GROUPS.filter((group) => group.some((name) => services.has(name)));
+    if (groups.length > 1)
+        throw new StackConfigError(`--service ${service}: ${groups.map((group) => group.join(" and ")).join(" may not share a process with ")}; run them as separate processes`);
+    return { services };
 }
 function parsePort(name, raw) {
     if (!/^\d+$/.test(raw))
@@ -164,11 +247,23 @@ function parseIdentityKeys(env) {
 }
 /** Parse the stack configuration; throws `StackConfigError` naming the variable. */
 export function parseStackConfig(env, argv) {
-    const role = parseRole(argv);
-    const listen = parseListen(env);
-    const operator = parseAdminListen(env);
+    const { services, deprecatedRole } = parseServices(argv);
+    // The image sets NYLORUN_LISTEN_*: only the API's processes read them.
+    const servesApi = services.has("core") || services.has("loop");
+    const listen = servesApi ? parseListen(env) : undefined;
+    const operator = servesApi ? parseAdminListen(env) : undefined;
+    const gates = services.has("gates") || services.has("keys") ? parseGates(env) : undefined;
+    // The gates service's clients: the loop's model and tool calls, and core's endpoint pings.
+    const modelGate = servesApi ? parseModelGate(env) : undefined;
+    // The keys service is the gateway's unless NYLORUN_KEYS_URL names another listener.
+    const keys = servesApi ? (parseKeysEndpoint(env) ?? modelGate) : undefined;
     if (operator && listen && operator.port === listen.port)
         throw new StackConfigError("NYLORUN_ADMIN_LISTEN_PORT must differ from NYLORUN_LISTEN_PORT");
+    if (services.has("loop") && listen && !modelGate)
+        throw new StackConfigError("NYLORUN_GATES_URL is required for the loop service in a container: model calls go through the gates service (the gateway container), so the loop never holds a model credential. Set NYLORUN_GATES_URL and NYLORUN_GATES_TOKEN (`nylorun start` sets both)");
+    const rawPacking = read(env, "NYLORUN_PACKING");
+    if (rawPacking !== undefined && rawPacking !== "combined" && rawPacking !== "split")
+        throw new StackConfigError(`NYLORUN_PACKING must be combined or split, not ${rawPacking}`);
     const http = ["http:", "https:"];
     const endpoints = {};
     const databaseUrl = parseUrl(env, "NYLORUN_DATABASE_URL", [
@@ -208,16 +303,95 @@ export function parseStackConfig(env, argv) {
     if (rawBrowser !== undefined && rawBrowser !== "on" && rawBrowser !== "off")
         throw new StackConfigError(`NYLORUN_BROWSER_ACCESS must be on or off, not ${rawBrowser}`);
     const delivery = parseDelivery(env);
+    const tenant = servesApi ? parseTenant(env) : undefined;
     return {
-        role,
+        services,
+        ...(deprecatedRole ? { deprecatedRole } : {}),
+        ...(gates ? { gates } : {}),
+        ...(modelGate ? { modelGate } : {}),
+        ...(keys ? { keys } : {}),
+        ...(rawPacking ? { packing: rawPacking } : {}),
         ...(listen ? { listen } : {}),
         endpoints,
         ...(publicUrl ? { publicUrl } : {}),
         ...(rawBrowser === undefined ? {} : { browserAccess: rawBrowser === "on" }),
         ...(operator ? { operator } : {}),
         ...(delivery ? { delivery } : {}),
+        ...(tenant ? { tenant } : {}),
+    };
+}
+function parseTenant(env) {
+    const id = read(env, "NYLORUN_TENANT_ID");
+    if (id !== undefined && !isTenantId(id))
+        throw new StackConfigError(`NYLORUN_TENANT_ID must be a Tenant id (tn_ and 26 Crockford characters), not ${id}`);
+    const raw = read(env, "NYLORUN_DERIVED_PRINCIPALS");
+    const derivedPrincipals = raw === undefined ? ["project"] : raw.split(",").map((entry) => entry.trim());
+    for (const principal of derivedPrincipals)
+        if (!DERIVED_PRINCIPAL_ID_PATTERN.test(principal) || principal === "studio")
+            throw new StackConfigError(`NYLORUN_DERIVED_PRINCIPALS has '${principal}': each entry must match ${DERIVED_PRINCIPAL_ID_PATTERN} and not be studio`);
+    return {
+        ...(id ? { id } : {}),
+        name: read(env, "NYLORUN_TENANT_NAME") ?? "default",
+        derivedPrincipals: [...new Set(derivedPrincipals)],
+    };
+}
+const GATES_TOKEN = /^[0-9a-f]{64,}$/i;
+/** `StackConfig.gates` from `NYLORUN_GATES_*`. */
+function parseGates(env) {
+    const host = read(env, "NYLORUN_GATES_LISTEN_HOST") ?? DEFAULT_CONTAINER_LISTEN_HOST;
+    if (/\s|\//.test(host))
+        throw new StackConfigError(`NYLORUN_GATES_LISTEN_HOST is not an address: ${host}`);
+    const rawPort = read(env, "NYLORUN_GATES_LISTEN_PORT");
+    const port = rawPort === undefined
+        ? DEFAULT_GATES_LISTEN_PORT
+        : parsePort("NYLORUN_GATES_LISTEN_PORT", rawPort);
+    const rawAllowed = read(env, "NYLORUN_GATES_ALLOWED_HOSTS");
+    const explicit = rawAllowed === undefined
+        ? []
+        : rawAllowed
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== "")
+            .map((entry) => normalizeAllowedHost("NYLORUN_GATES_ALLOWED_HOSTS", entry));
+    if (explicit.length === 0 && !isLoopbackAddress(host))
+        throw new StackConfigError(`NYLORUN_GATES_ALLOWED_HOSTS is required when NYLORUN_GATES_LISTEN_HOST is ${host}: list the Host headers the loop sends, e.g. gateway:${port}`);
+    const token = read(env, "NYLORUN_GATES_TOKEN");
+    if (token === undefined)
+        throw new StackConfigError("NYLORUN_GATES_TOKEN is required for --service gates: the token the loop presents (`nylorun start` sets it)");
+    if (!GATES_TOKEN.test(token))
+        throw new StackConfigError("NYLORUN_GATES_TOKEN must be at least 32 bytes as hex");
+    return {
+        listen: { host, port, allowedHosts: [...new Set([...explicit, ...loopbackForms(port)])] },
+        token,
     };
 }
+/** `StackConfig.modelGate` from `NYLORUN_GATES_URL` and `NYLORUN_GATES_TOKEN`. */
+function parseModelGate(env) {
+    const url = parseUrl(env, "NYLORUN_GATES_URL", ["http:", "https:"]);
+    const token = read(env, "NYLORUN_GATES_TOKEN");
+    if (url === undefined) {
+        if (token !== undefined)
+            throw new StackConfigError("NYLORUN_GATES_TOKEN is set without NYLORUN_GATES_URL: set the URL of the gates service, e.g. http://gateway:4100");
+        return undefined;
+    }
+    if (token === undefined)
+        throw new StackConfigError("NYLORUN_GATES_TOKEN is required with NYLORUN_GATES_URL: the gates service refuses calls without it");
+    if (!GATES_TOKEN.test(token))
+        throw new StackConfigError("NYLORUN_GATES_TOKEN must be at least 32 bytes as hex");
+    return { url: url.replace(/\/+$/, ""), token };
+}
+/** `StackConfig.keys` from `NYLORUN_KEYS_URL` and `NYLORUN_GATES_TOKEN`. */
+function parseKeysEndpoint(env) {
+    const url = parseUrl(env, "NYLORUN_KEYS_URL", ["http:", "https:"]);
+    if (url === undefined)
+        return undefined;
+    const token = read(env, "NYLORUN_GATES_TOKEN");
+    if (token === undefined)
+        throw new StackConfigError("NYLORUN_GATES_TOKEN is required with NYLORUN_KEYS_URL: the keys service refuses calls without it");
+    if (!GATES_TOKEN.test(token))
+        throw new StackConfigError("NYLORUN_GATES_TOKEN must be at least 32 bytes as hex");
+    return { url: url.replace(/\/+$/, ""), token };
+}
 /** `StackConfig.delivery` from `NYLORUN_ENDPOINT_*`, or `undefined` when none is set. */
 function parseDelivery(env) {
     const loopback = read(env, "NYLORUN_ENDPOINT_LOOPBACK");

package/dist/infra/database.d.ts

@@ -1,7 +1,7 @@
 /**
  * Builds the Host's Postgres connection pool from the stack configuration
- * (architecture §12.2, §14.5). One pool serves the Tenant catalog and every
- * Tenant schema; the Host ends it at shutdown. The driver stays behind
+ * (architecture §12.2, §14.5): the pool on the Tenant's database, for its bootstrap and its
+ * Session Store; the Host ends it at shutdown. The driver stays behind
  * `store/postgres/connect.ts`.
  */
 import type { StackConfig } from "../host/stack-config.js";

package/dist/infra/execution.d.ts

@@ -1,5 +1,5 @@
 import type { DurableExecution } from "../execution/types.js";
-import type { RuntimeRole, StackConfig } from "../host/stack-config.js";
+import { type RuntimeServices, type StackConfig } from "../host/stack-config.js";
 /** Where a Worker serves the Restate endpoint (architecture §14.3). */
 export declare const WORKER_LISTEN: {
     readonly host: "0.0.0.0";
@@ -23,14 +23,14 @@ export interface CreateExecutionOptions {
 export declare function executionKind(config: Pick<StackConfig, "endpoints">): "restate" | "memory";
 /**
  * Throws naming the missing variable when the Restate endpoints are
- * incomplete for `role`. The api role never serves the Worker endpoint, so it
- * needs no `NYLORUN_WORKER_URL`.
+ * incomplete for `services`. Without the loop service a process never serves
+ * the Worker endpoint, so it needs no `NYLORUN_WORKER_URL`.
  */
 export declare function validateExecutionConfig(config: Pick<StackConfig, "endpoints"> & {
-    role?: RuntimeRole;
+    services?: RuntimeServices;
 }): void;
 export declare function createExecution(config: Pick<StackConfig, "endpoints"> & {
-    role?: RuntimeRole;
+    services?: RuntimeServices;
 }, options?: CreateExecutionOptions): DurableExecution;
 /**
  * Readiness probe: resolves when Restate's admin API and ingress answer

package/dist/infra/execution.js

@@ -5,9 +5,9 @@
  * With `NYLORUN_RESTATE_INGRESS_URL` and `NYLORUN_RESTATE_ADMIN_URL` the Host
  * uses Restate:
  *
- * - wakes, timers and sweep arming go through the ingress, so every role can
+ * - wakes, timers and sweep arming go through the ingress, so every process can
  *   call them;
- * - a Worker (`--role worker|all`) serves the Restate endpoint on
+ * - a Worker (a process running the loop service) serves the Restate endpoint on
  *   `0.0.0.0:9080` and registers `NYLORUN_WORKER_URL` with the admin API when
  *   `infra/workers.ts` starts it;
  * - with `NYLORUN_RESTATE_IDENTITY_KEY` the endpoint accepts only requests
@@ -18,6 +18,7 @@
  */
 import { createRestateExecution } from "../adapters/execution/restate.js";
 import { MemoryExecution } from "../execution/memory.js";
+import { DEFAULT_SERVICES, describeServices, } from "../host/stack-config.js";
 /** Where a Worker serves the Restate endpoint (architecture §14.3). */
 export const WORKER_LISTEN = { host: "0.0.0.0", port: 9080 };
 /** Which implementation `createExecution` chooses for a configuration. */
@@ -27,8 +28,8 @@ export function executionKind(config) {
 }
 /**
  * Throws naming the missing variable when the Restate endpoints are
- * incomplete for `role`. The api role never serves the Worker endpoint, so it
- * needs no `NYLORUN_WORKER_URL`.
+ * incomplete for `services`. Without the loop service a process never serves
+ * the Worker endpoint, so it needs no `NYLORUN_WORKER_URL`.
  */
 export function validateExecutionConfig(config) {
     const { restateIngressUrl, restateAdminUrl, workerUrl, restateIdentityKeys } = config.endpoints;
@@ -41,8 +42,9 @@ export function validateExecutionConfig(config) {
         throw new Error("NYLORUN_RESTATE_INGRESS_URL is required with NYLORUN_RESTATE_ADMIN_URL");
     if (!restateAdminUrl)
         throw new Error("NYLORUN_RESTATE_ADMIN_URL is required with NYLORUN_RESTATE_INGRESS_URL");
-    if ((config.role ?? "all") !== "api" && !workerUrl)
-        throw new Error(`NYLORUN_WORKER_URL is required for --role ${config.role ?? "all"}: the Worker endpoint URL Restate calls`);
+    const services = config.services ?? DEFAULT_SERVICES;
+    if (services.has("loop") && !workerUrl)
+        throw new Error(`NYLORUN_WORKER_URL is required for --service ${describeServices(services)}: the Worker endpoint URL Restate calls`);
 }
 export function createExecution(config, options = {}) {
     validateExecutionConfig(config);

package/dist/infra/index.d.ts

@@ -35,7 +35,7 @@ export interface Infra {
  * Builds the configured clients. Throws naming the variable when endpoints are
  * incomplete (e.g. a Restate ingress without an admin URL).
  */
-export declare function createInfra(config: Pick<StackConfig, "role" | "endpoints">, options?: {
+export declare function createInfra(config: Pick<StackConfig, "services" | "endpoints">, options?: {
     logger?: Logger;
     execution?: CreateExecutionOptions;
     streams?: CreateStreamsOptions;

package/dist/infra/workers.d.ts

@@ -1,39 +1,39 @@
 /**
- * Worker lifecycle by role (architecture §6).
+ * Worker lifecycle by service (architecture §6, blueprint §19).
  *
- * | Role | Serves | `execution.start` |
+ * | Services | Serves | `execution.start` |
  * | --- | --- | --- |
- * | `api` | Tenant API, Admin API, SSE | **never**: wakes, timers and sweep arming go through Restate's ingress, which needs no Worker endpoint |
- * | `worker` | the Restate endpoint (`NylorunSession.advance`, `NylorunTenant.sweep`, timers) | yes |
- * | `all` | both (the local stack) | yes |
+ * | `core` | Tenant API, Admin API, SSE | **never**: wakes, timers and sweep arming go through Restate's ingress, which needs no Worker endpoint |
+ * | `loop` | the Restate endpoint (`NylorunSession.advance`, `NylorunTenant.sweep`, timers) | yes |
+ * | `core,loop` | both (the local stack's `runtime` container) | yes |
  *
- * An API node that called `start` would register its own endpoint with
+ * A core-only process that called `start` would register its own endpoint with
  * Restate, and Restate would send new invocations to it (it routes to the
  * latest registered deployment), so the rule is enforced here rather than left
- * to callers: `startWorker` with role `api` returns a handle that never
- * started anything.
+ * to callers: `startWorker` without the loop service returns a handle that
+ * never started anything.
  */
 import type { DurableExecution, WorkerHandlers } from "../execution/types.js";
-import type { RuntimeRole } from "../host/stack-config.js";
+import type { RuntimeServices } from "../host/stack-config.js";
 export interface WorkerHandle {
-    readonly role: RuntimeRole;
+    readonly services: RuntimeServices;
     /** True when this process serves the Worker endpoint. */
     readonly serving: boolean;
 }
-/** Whether a process in `role` serves the Worker endpoint. */
-export declare function servesWorker(role: RuntimeRole): boolean;
+/** Whether a process running `services` serves the Worker endpoint: when it runs loop. */
+export declare function servesWorker(services: RuntimeServices): boolean;
 /**
- * Starts delivering Restate invocations to `handlers` when `role` is `worker`
- * or `all` (serving and registering the Worker endpoint, for Restate). For
- * `api` it does nothing. Rejects if the endpoint cannot listen or register.
+ * Starts delivering Restate invocations to `handlers` when the process runs
+ * loop (serving and registering the Worker endpoint, for Restate). Without
+ * loop it does nothing. Rejects if the endpoint cannot listen or register.
  */
 export declare function startWorker(input: {
-    role: RuntimeRole;
+    services: RuntimeServices;
     execution: DurableExecution;
     handlers: WorkerHandlers;
 }): Promise<WorkerHandle>;
 /**
  * Stops a Worker started by `startWorker`: aborts running advances' signals
- * and waits for them. Idempotent; a no-op for the api role.
+ * and waits for them. Idempotent; a no-op without the loop service.
  */
 export declare function stopWorker(handle: WorkerHandle): Promise<void>;

package/dist/infra/workers.js

@@ -1,17 +1,17 @@
-/** Whether a process in `role` serves the Worker endpoint. */
-export function servesWorker(role) {
-    return role !== "api";
+/** Whether a process running `services` serves the Worker endpoint: when it runs loop. */
+export function servesWorker(services) {
+    return services.has("loop");
 }
 /** What `stopWorker` needs for a handle that serves the endpoint. */
 const started = new WeakMap();
 /**
- * Starts delivering Restate invocations to `handlers` when `role` is `worker`
- * or `all` (serving and registering the Worker endpoint, for Restate). For
- * `api` it does nothing. Rejects if the endpoint cannot listen or register.
+ * Starts delivering Restate invocations to `handlers` when the process runs
+ * loop (serving and registering the Worker endpoint, for Restate). Without
+ * loop it does nothing. Rejects if the endpoint cannot listen or register.
  */
 export async function startWorker(input) {
-    const { role, execution, handlers } = input;
-    const handle = Object.freeze({ role, serving: servesWorker(role) });
+    const { services, execution, handlers } = input;
+    const handle = Object.freeze({ services, serving: servesWorker(services) });
     if (!handle.serving)
         return handle;
     await execution.start(handlers);
@@ -20,7 +20,7 @@ export async function startWorker(input) {
 }
 /**
  * Stops a Worker started by `startWorker`: aborts running advances' signals
- * and waits for them. Idempotent; a no-op for the api role.
+ * and waits for them. Idempotent; a no-op without the loop service.
  */
 export async function stopWorker(handle) {
     const worker = started.get(handle);

package/dist/keys/client.d.ts

@@ -0,0 +1,9 @@
+import { type Keys } from "./keys.js";
+export interface HttpKeysOptions {
+    /** The gateway, e.g. `http://gateway:4100` (`NYLORUN_KEYS_URL`). */
+    readonly url: string;
+    /** `NYLORUN_GATES_TOKEN`. */
+    readonly token: string;
+    readonly timeoutMs?: number;
+}
+export declare function httpKeys(options: HttpKeysOptions): Keys;

package/dist/keys/client.js

@@ -0,0 +1,70 @@
+/**
+ * The runtime container's client of the `keys` service in the gateway (F4.2, `contract.ts`).
+ * Over `node:http` rather than `fetch`, which tests and embedders may replace. A refusal comes
+ * back as the error the operation threw in the gateway (`VaultError` or `HttpError`, same status,
+ * code and details); a hop failure is a 503, so the API route answers that the gateway is down.
+ */
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { HttpError } from "../tenant/http.js";
+import { VaultError } from "../vault/error.js";
+import { KEYS_PATH } from "./contract.js";
+import { KEYS_OPERATIONS } from "./keys.js";
+/** Signing and vault writes are short; anything slower is a gateway in trouble. */
+const KEYS_TIMEOUT_MS = 30_000;
+export function httpKeys(options) {
+    const where = new URL(options.url).origin;
+    const timeoutMs = options.timeoutMs ?? KEYS_TIMEOUT_MS;
+    function call(operation, args) {
+        const url = new URL(`${KEYS_PATH}/${operation}`, options.url);
+        const send = url.protocol === "https:" ? httpsRequest : httpRequest;
+        const payload = Buffer.from(JSON.stringify({ args }), "utf8");
+        return new Promise((resolve, reject) => {
+            const unavailable = (detail) => reject(new HttpError(503, `The keys service at ${where} is unavailable (${detail}); check the gateway container`, {
+                code: "keys_unavailable",
+            }));
+            const outgoing = send(url, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${options.token}`,
+                    "content-type": "application/json",
+                    "content-length": payload.byteLength,
+                },
+                timeout: timeoutMs,
+            }, (response) => {
+                const chunks = [];
+                response.on("data", (chunk) => chunks.push(chunk));
+                response.on("error", (error) => unavailable(error.message));
+                response.on("end", () => {
+                    let answer;
+                    try {
+                        answer = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                    }
+                    catch {
+                        answer = undefined;
+                    }
+                    if (response.statusCode !== 200 || !answer)
+                        return unavailable(response.statusCode === 401
+                            ? "it refused this Runtime's token: the runtime and gateway containers must share NYLORUN_GATES_TOKEN"
+                            : `it answered ${response.statusCode}`);
+                    if ("result" in answer)
+                        return resolve(answer.result);
+                    const error = answer.error;
+                    reject(error.kind === "vault"
+                        ? new VaultError(error.status, error.message)
+                        : new HttpError(error.status, error.message, {
+                            ...(error.code === undefined ? {} : { code: error.code }),
+                            ...(error.details === undefined ? {} : { details: error.details }),
+                        }));
+                });
+            });
+            outgoing.on("timeout", () => outgoing.destroy(new Error(`no answer in ${timeoutMs / 1000} s`)));
+            outgoing.on("error", (error) => unavailable(error.message));
+            outgoing.end(payload);
+        });
+    }
+    const keys = {};
+    for (const operation of KEYS_OPERATIONS)
+        keys[operation] = (...args) => call(operation, args);
+    return keys;
+}

package/dist/keys/contract.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `keys` service's wire format (F4.2): `POST /nylorun/v1/keys/{operation}` with
+ * `{args}`, the operation's arguments in order, on the gateway's listener with the stack's
+ * gates token. Internal: only core calls it, so it is not in the published OpenAPI documents.
+ *
+ * `200 {result}` when the operation succeeded, `200 {error}` when it refused: a vault error or
+ * a Tenant API error with its status, code and details, so the route that called it answers
+ * exactly what it answered when the operation ran in its own process.
+ */
+export declare const KEYS_PATH = "/nylorun/v1/keys";
+/** Largest request body: a credential with its secret, or a token's claims. */
+export declare const MAX_KEYS_BODY_BYTES: number;
+export interface KeysError {
+    readonly kind: "vault" | "http";
+    readonly status: number;
+    readonly message: string;
+    readonly code?: string;
+    readonly details?: unknown;
+}
+export type KeysAnswer = {
+    readonly result: unknown;
+} | {
+    readonly error: KeysError;
+};

package/dist/keys/contract.js

@@ -0,0 +1,12 @@
+/**
+ * The `keys` service's wire format (F4.2): `POST /nylorun/v1/keys/{operation}` with
+ * `{args}`, the operation's arguments in order, on the gateway's listener with the stack's
+ * gates token. Internal: only core calls it, so it is not in the published OpenAPI documents.
+ *
+ * `200 {result}` when the operation succeeded, `200 {error}` when it refused: a vault error or
+ * a Tenant API error with its status, code and details, so the route that called it answers
+ * exactly what it answered when the operation ran in its own process.
+ */
+export const KEYS_PATH = "/nylorun/v1/keys";
+/** Largest request body: a credential with its secret, or a token's claims. */
+export const MAX_KEYS_BODY_BYTES = 1024 * 1024;

package/dist/keys/keys.d.ts

@@ -0,0 +1,41 @@
+import type { CreateCredentialRequest, CredentialInfo, HostModelView, PutHostModelRequest, RotateCredentialRequest, SelectHostModelRequest, SigningKeyView } from "@nylorun/core/contracts";
+import type { SessionStore } from "../store/types.js";
+import { type SigningKeys } from "../tenant/signing-keys.js";
+import type { VaultService } from "../vault/service.js";
+/** One JWT to sign: its `typ` and every claim, `iss`, `aud`, `sub`, `iat`, `exp` and `jti` included. */
+export interface SignRequest {
+    readonly typ: string;
+    readonly claims: Readonly<Record<string, unknown>>;
+}
+export interface Signed {
+    readonly token: string;
+    /** The signing key's id, the token's `kid`. */
+    readonly keyId: string;
+}
+export interface Keys {
+    createCredential(vaultId: string, body: CreateCredentialRequest): Promise<CredentialInfo>;
+    rotateCredential(vaultId: string, id: string, body: RotateCredentialRequest): Promise<CredentialInfo>;
+    putHostModel(body: PutHostModelRequest): Promise<HostModelView>;
+    selectHostModel(body: SelectHostModelRequest): Promise<HostModelView>;
+    /** Signs with the current key, creating the Tenant's keys if it has none. */
+    sign(request: SignRequest): Promise<Signed>;
+    /** Rotates the signing keys (`SigningKeys.rotate`); 409 while the previous key may verify live tokens. */
+    rotateSigningKeys(request: {
+        maxTtlSeconds: number;
+        force: boolean;
+    }): Promise<SigningKeyView[]>;
+    /** Creates the current and standby keys when the Tenant has none. */
+    ensureSigningKeys(): Promise<void>;
+}
+/** The operations, by the name the HTTP route carries. */
+export declare const KEYS_OPERATIONS: readonly ["createCredential", "rotateCredential", "putHostModel", "selectHostModel", "sign", "rotateSigningKeys", "ensureSigningKeys"];
+export type KeysOperation = (typeof KEYS_OPERATIONS)[number];
+export interface InProcessKeysOptions {
+    readonly store: SessionStore;
+    /** Its vault key is `kek`. */
+    readonly vault: VaultService;
+    readonly signingKeys: SigningKeys;
+    /** The vault key. */
+    readonly kek: () => Buffer;
+}
+export declare function inProcessKeys(options: InProcessKeysOptions): Keys;