@nylorun/runtime 0.16.0-beta → 0.19.0-beta

package/dist/tenant/operator-keys.js

@@ -0,0 +1,87 @@
+/**
+ * The Tenant's keys by name (F9 I1), managed through the Management API (`/v1/tenant/keys`,
+ * application keys only) and `nylorun-operate keys`. A key is a principal (F9-D11): its id is the key's name
+ * (`APPLICATION_KEY_ID_PATTERN`), the key is 64 hex characters (`mintBearerToken`), and the
+ * Tenant keeps only its SHA-256. Putting a key creates the principal or rotates its key;
+ * deleting it removes the row. Either way the old key stops authenticating on its next request,
+ * since authentication reads the principal on every request (`auth.ts`).
+ *
+ * `studio` is derived from the admin key (F9-D9): it is never put or deleted here. `bootstrap` is
+ * the management key a Host registers from `NYLORUN_MANAGEMENT_KEY_FILE`: its file is its only
+ * source. A key has a role (protocol 8): `application` reaches the Runtime API, `management` the
+ * Management API; a key keeps its role when it is rotated.
+ */
+import { APPLICATION_KEY_ID_PATTERN, BOOTSTRAP_KEY_ID, } from "@nylorun/core/compatibility";
+import { hashToken, mintBearerToken } from "../core/bearer.js";
+import { PrincipalRoleConflict } from "../store/ownership.js";
+import { STUDIO_PRINCIPAL_ID } from "./principals.js";
+/**
+ * The refusal for `id`, or undefined when it may be `put` or deleted. `bootstrap` is never put
+ * here (its file is its only source) but may be deleted on the machine (AP18).
+ */
+export function refuseOperatorKeyId(id, purpose = "put") {
+    if (!APPLICATION_KEY_ID_PATTERN.test(id))
+        return {
+            reason: "invalid",
+            message: `A key id must match ${APPLICATION_KEY_ID_PATTERN.source}`,
+        };
+    if (id === STUDIO_PRINCIPAL_ID)
+        return {
+            reason: "reserved",
+            message: "The studio key is derived from the admin key: it is not put or deleted here",
+        };
+    if (id === BOOTSTRAP_KEY_ID && purpose === "put")
+        return {
+            reason: "reserved",
+            message: "The bootstrap key comes from NYLORUN_MANAGEMENT_KEY_FILE: change that file to rotate it",
+        };
+    return undefined;
+}
+export function operatorKeys(store, now = () => new Date().toISOString()) {
+    return {
+        async list() {
+            const rows = await store.tx((t) => t.listPrincipals());
+            return rows.map(({ id, role, createdAt }) => ({ id, role, createdAt }));
+        },
+        async put(id, role = "application") {
+            const refused = refuseOperatorKeyId(id);
+            if (refused)
+                return refused;
+            const key = mintBearerToken();
+            try {
+                const { row, rotated } = await store.tx(async (t) => {
+                    const existing = await t.principalById(id);
+                    return {
+                        row: await t.putPrincipal(id, hashToken(key), now(), role),
+                        rotated: existing !== undefined,
+                    };
+                });
+                return { id: row.id, role: row.role, createdAt: row.createdAt, key, rotated };
+            }
+            catch (error) {
+                if (error instanceof PrincipalRoleConflict)
+                    return {
+                        reason: "role",
+                        message: `Key ${id} is not a${role === "application" ? "n application" : " management"} key: delete it first, or choose another name`,
+                    };
+                throw error;
+            }
+        },
+        async delete(id, role) {
+            const refused = refuseOperatorKeyId(id, "delete");
+            if (refused)
+                return refused;
+            return await store.tx(async (t) => {
+                if (role !== undefined) {
+                    const existing = await t.principalById(id);
+                    if (existing && existing.role !== role)
+                        return {
+                            reason: "role",
+                            message: `Key ${id} is a ${existing.role} key: only the Tenant's machine manages it (nylorun-operate)`,
+                        };
+                }
+                return await t.deletePrincipal(id);
+            });
+        },
+    };
+}

package/dist/tenant/outbound.d.ts

@@ -36,9 +36,48 @@ export declare const MAX_RESPONSE_BYTES: number;
 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. */
+/**
+ * POSTs (or, with `method`, PUTs or PATCHes) the JSON `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;
+    method?: "POST" | "PUT" | "PATCH";
 }): Promise<OutboundResult>;
+/**
+ * A refusal of `guardedFetch`: the Host's policy forbids the URL or every address it resolves
+ * to. Not a `TypeError`, so callers that read a `TypeError` as a CORS failure (the MCP SDK's
+ * discovery) see the refusal instead of trying again.
+ */
+export declare class OutboundRefused extends Error {
+    readonly code = "ENDPOINT_ADDRESS_REFUSED";
+    constructor(message: string);
+}
+/** A request `guardedFetch` sent that failed: refused connection, reset, timeout, redirect. */
+export declare class OutboundFailed extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** The largest answer `guardedFetch` reads. OAuth metadata and tokens are small. */
+export declare const MAX_FETCH_RESPONSE_BYTES: number;
+/** How long a `guardedFetch` request may take without a signal of its own. */
+export declare const FETCH_TIMEOUT_MS = 30000;
+/**
+ * A `fetch` under the Host's address policy (F9 C2): the literal-IP and DNS checks of `post`
+ * on the address actually connected to, `localhost` rewritten for the local stack, no
+ * redirects (`redirect: "error"`; a 3xx answer rejects), a bounded answer and a 30 s timeout
+ * unless the caller passes a signal. The gateway calls OAuth discovery, registration, the code
+ * exchange and refresh with it. A refused URL or address rejects with `OutboundRefused`, any
+ * other failure with `OutboundFailed`.
+ *
+ * `stream`: the Response resolves once the headers arrive and its body streams, unbounded and
+ * with no timeout but the caller's signal: remote MCP servers, whose answers and event streams
+ * stay open (`mcp/connect.ts`).
+ */
+export declare function guardedFetch(policy: OutboundPolicy, options?: {
+    maxResponseBytes?: number;
+    timeoutMs?: number;
+    stream?: boolean;
+}): typeof fetch;

package/dist/tenant/outbound.js

@@ -1,16 +1,18 @@
 /**
- * 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 Runtime's requests to developer URLs: HTTP tools (`gates/http-tool.ts`) and, through
+ * `guardedFetch`, remote MCP servers and OAuth: one request, 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 request 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`.
+ * The result says whether anything reached the URL. A request that failed before its body was
+ * flushed (refused connection, unknown host, TLS failure, a refused address) was `not_sent`;
+ * 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";
+import { Readable } from "node:stream";
 /** The largest answer read from an endpoint. */
 export const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 const PRIVATE = new BlockList();
@@ -53,18 +55,14 @@ export function refusal(url, policy) {
         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;
+/** `localhost` means the machine that runs Docker (`OutboundPolicy.loopback`). */
+function dockerHost(url, policy) {
     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) => {
+}
+/** A DNS lookup that drops private answers when `policy` refuses them: checked on what is connected to. */
+function guardedLookup(policy) {
+    return (hostname, lookupOptions, callback) => dnsLookup(hostname, { ...lookupOptions, all: true }, (error, addresses) => {
         if (error)
             return callback(error, []);
         const allowed = policy.privateAddresses === "refuse"
@@ -76,6 +74,21 @@ export async function post(target, body, headers, options) {
             return callback(null, allowed);
         return callback(null, allowed[0].address, allowed[0].family);
     });
+}
+/**
+ * POSTs (or, with `method`, PUTs or PATCHes) the JSON `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;
+    dockerHost(url, policy);
+    const lookup = guardedLookup(policy);
     return new Promise((resolve) => {
         let sent = false;
         let settled = false;
@@ -88,10 +101,10 @@ export async function post(target, body, headers, options) {
         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,
+            message: signal.aborted ? "The request was aborted" : error.message,
         });
         const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
-            method: "POST",
+            method: options.method ?? "POST",
             headers: {
                 ...headers,
                 host: originalHost,
@@ -125,3 +138,139 @@ export async function post(target, body, headers, options) {
         request.end(body);
     });
 }
+/**
+ * A refusal of `guardedFetch`: the Host's policy forbids the URL or every address it resolves
+ * to. Not a `TypeError`, so callers that read a `TypeError` as a CORS failure (the MCP SDK's
+ * discovery) see the refusal instead of trying again.
+ */
+export class OutboundRefused extends Error {
+    code = "ENDPOINT_ADDRESS_REFUSED";
+    constructor(message) {
+        super(message);
+        this.name = "OutboundRefused";
+    }
+}
+/** A request `guardedFetch` sent that failed: refused connection, reset, timeout, redirect. */
+export class OutboundFailed extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "OutboundFailed";
+    }
+}
+/** The largest answer `guardedFetch` reads. OAuth metadata and tokens are small. */
+export const MAX_FETCH_RESPONSE_BYTES = 1024 * 1024;
+/** How long a `guardedFetch` request may take without a signal of its own. */
+export const FETCH_TIMEOUT_MS = 30_000;
+/**
+ * A `fetch` under the Host's address policy (F9 C2): the literal-IP and DNS checks of `post`
+ * on the address actually connected to, `localhost` rewritten for the local stack, no
+ * redirects (`redirect: "error"`; a 3xx answer rejects), a bounded answer and a 30 s timeout
+ * unless the caller passes a signal. The gateway calls OAuth discovery, registration, the code
+ * exchange and refresh with it. A refused URL or address rejects with `OutboundRefused`, any
+ * other failure with `OutboundFailed`.
+ *
+ * `stream`: the Response resolves once the headers arrive and its body streams, unbounded and
+ * with no timeout but the caller's signal: remote MCP servers, whose answers and event streams
+ * stay open (`mcp/connect.ts`).
+ */
+export function guardedFetch(policy, options = {}) {
+    const limit = options.maxResponseBytes ?? MAX_FETCH_RESPONSE_BYTES;
+    const timeoutMs = options.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const stream = options.stream === true;
+    const lookup = guardedLookup(policy);
+    const guarded = async (input, init = {}) => {
+        const request = input instanceof Request ? input : undefined;
+        const url = new URL(request ? request.url : String(input));
+        const refused = refusal(url, policy);
+        if (refused)
+            throw new OutboundRefused(refused);
+        const method = (init.method ?? request?.method ?? "GET").toUpperCase();
+        const headers = new Headers(request?.headers);
+        for (const [name, value] of new Headers(init.headers))
+            headers.set(name, value);
+        let body;
+        const source = init.body ?? (request && method !== "GET" && method !== "HEAD" ? await request.arrayBuffer() : undefined);
+        if (source !== undefined && source !== null) {
+            if (typeof source === "string")
+                body = Buffer.from(source, "utf8");
+            else if (source instanceof URLSearchParams) {
+                body = Buffer.from(source.toString(), "utf8");
+                if (!headers.has("content-type"))
+                    headers.set("content-type", "application/x-www-form-urlencoded;charset=UTF-8");
+            }
+            else if (source instanceof ArrayBuffer)
+                body = Buffer.from(source);
+            else if (ArrayBuffer.isView(source))
+                body = Buffer.from(source.buffer, source.byteOffset, source.byteLength);
+            else
+                throw new OutboundFailed("guardedFetch sends only string, form or byte bodies", "UNSUPPORTED_BODY");
+        }
+        const originalHost = url.host;
+        dockerHost(url, policy);
+        const signal = init.signal ?? request?.signal ?? (stream ? undefined : AbortSignal.timeout(timeoutMs));
+        const outgoing = { host: originalHost };
+        for (const [name, value] of headers)
+            outgoing[name] = value;
+        if (body)
+            outgoing["content-length"] = String(body.byteLength);
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
+            const failed = (error) => settle(() => reject(error instanceof RefusedAddress
+                ? new OutboundRefused(error.message)
+                : new OutboundFailed(signal?.aborted ? `The request to ${originalHost} was aborted or timed out` : error.message, signal?.aborted ? "ABORTED" : (error.code ?? error.name))));
+            const sent = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, { method, headers: outgoing, lookup: lookup, ...(signal ? { signal } : {}) }, (response) => {
+                const status = response.statusCode ?? 0;
+                if (status >= 300 && status < 400 && response.headers.location !== undefined) {
+                    response.resume();
+                    return settle(() => reject(new OutboundFailed(`${originalHost} answered a redirect, which this Runtime does not follow`, "REDIRECT")));
+                }
+                const noBody = status === 204 || status === 304 || method === "HEAD";
+                const answer = (body) => {
+                    const headers = new Headers();
+                    for (const [name, value] of Object.entries(response.headers)) {
+                        if (value === undefined)
+                            continue;
+                        for (const item of Array.isArray(value) ? value : [value])
+                            headers.append(name, item);
+                    }
+                    return new Response(noBody ? null : body, {
+                        status,
+                        statusText: response.statusMessage ?? "",
+                        headers,
+                    });
+                };
+                if (stream) {
+                    // A failure after this reaches the reader as the body's error.
+                    if (noBody)
+                        response.resume();
+                    return settle(() => resolve(answer(noBody ? null : Readable.toWeb(response))));
+                }
+                const chunks = [];
+                let size = 0;
+                response.on("data", (chunk) => {
+                    size += chunk.length;
+                    if (size > limit) {
+                        settle(() => reject(new OutboundFailed(`The answer from ${originalHost} is larger than ${limit} bytes`, "TOO_LARGE")));
+                        response.destroy();
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                response.on("end", () => settle(() => resolve(answer(Buffer.concat(chunks)))));
+                response.on("error", failed);
+                response.on("aborted", () => failed(Object.assign(new Error("The answer was cut off"), { code: "ECONNRESET" })));
+            });
+            sent.on("error", failed);
+            sent.end(body);
+        });
+    };
+    return guarded;
+}

package/dist/tenant/paths.d.ts

@@ -16,7 +16,7 @@ export declare function hostPaths(hostRoot: string): HostPaths;
  * root after realpath.
  *
  * The directory holds what stays on the Host (the Tenant's data is its database): `home/`,
- * `tmp/`, `sandboxes/`, `plugin-data/`, `blobs/` (the `fs` BlobStore, when the Host has no
+ * `sandboxes/`, `blobs/` (the `fs` BlobStore, when the Host has no
  * Object store), `logs/tenant.log`. The vault key is the one exception:
  * it lives beside the Tenant directory, in `<hostRoot>/keys/vault-kek`, which the local stack
  * mounts only into the gateway (F4.2), never into the runtime container.

package/dist/tenant/paths.js

@@ -24,7 +24,7 @@ export function hostPaths(hostRoot) {
  * root after realpath.
  *
  * The directory holds what stays on the Host (the Tenant's data is its database): `home/`,
- * `tmp/`, `sandboxes/`, `plugin-data/`, `blobs/` (the `fs` BlobStore, when the Host has no
+ * `sandboxes/`, `blobs/` (the `fs` BlobStore, when the Host has no
  * Object store), `logs/tenant.log`. The vault key is the one exception:
  * it lives beside the Tenant directory, in `<hostRoot>/keys/vault-kek`, which the local stack
  * mounts only into the gateway (F4.2), never into the runtime container.
@@ -39,9 +39,7 @@ export function tenantPaths(hostRoot) {
         root,
         kek: join(host, "keys", "vault-kek"),
         home: join(root, "home"),
-        tmp: join(root, "tmp"),
         sandboxes: join(root, "sandboxes"),
-        pluginData: join(root, "plugin-data"),
         blobs: join(root, "blobs"),
         logs: join(root, "logs"),
         log: join(root, "logs", "tenant.log"),

package/dist/tenant/principals.d.ts

@@ -2,27 +2,27 @@ import type { InitialPrincipal } from "../store/postgres/tenant.js";
 export type { PrincipalRow } from "../store/types.js";
 /** Principal id of the Studio key derived from the admin key. */
 export declare const STUDIO_PRINCIPAL_ID = "studio";
-/** The derived principal Projects use (`PROJECT_PRINCIPAL_ID` in `@nylorun/admin`). */
-export declare const PROJECT_PRINCIPAL_ID = "project";
-/** The derived principals a Host registers when not told otherwise. */
-export declare const DEFAULT_DERIVED_PRINCIPALS: readonly string[];
-/** The Studio key of `tenantId`: HMAC-SHA256 of the admin key. */
-export declare function deriveStudioKey(adminKey: string, tenantId: string): string;
-/** The key of derived principal `principalId` on `tenantId`: HMAC-SHA256 of the admin key. */
-export declare function deriveTenantKey(adminKey: string, tenantId: string, principalId: string): string;
-/** Whether `id` may name a derived principal: the client's name, never `studio`. */
-export declare function isDerivedPrincipalId(id: string): boolean;
 /**
- * The principals a Host's Tenant is created with: `studio`, each derived principal, and an
- * application principal when a key is given (the ephemeral Runtime). Keys are hashed here.
+ * The Studio key: HMAC-SHA256 of the admin key over `nylorun/studio/v2`. It names no Tenant
+ * (protocol 8): Studio derives it before it can learn the Tenant's id, and the admin key is
+ * already one per installation.
+ */
+export declare function deriveStudioKey(adminKey: string): string;
+/**
+ * The principals a Host's Tenant is created with: `studio`, and an application principal when
+ * a key is given (the ephemeral Runtime). Keys are hashed here.
  */
 export declare function hostPrincipals(options: {
     adminKey: string;
-    derived?: readonly string[];
     application?: {
         principalId: string;
         key: string;
     };
     /** Registers `studio` with this hash instead of the admin key's derivation. */
     studioCredentialHash?: string;
+    /**
+     * The management key of `NYLORUN_MANAGEMENT_KEY_FILE`: registered as `bootstrap`, and
+     * replaced at the next start when the file changed.
+     */
+    bootstrapKey?: string;
 }): (tenantId: string) => InitialPrincipal[];

package/dist/tenant/principals.js

@@ -1,44 +1,43 @@
 /**
- * The principals the Host gives its Tenant when it creates it (tenancy.md §4, plan P9): the
- * Studio principal and the derived principals, whose keys the admin key derives, so the
- * clients holding the admin key (Studio, `nylorun start`, Babai) store none. The Tenant keeps
- * only their hashes.
+ * The principals the Host gives its Tenant when it creates it (tenancy.md §4): the Studio
+ * principal, whose key the admin key derives, so Studio (and an app embedding it) stores none,
+ * and, for the ephemeral Runtime, one application principal with a key of its own. The Tenant
+ * keeps only their hashes. Every other key is put by name (`PUT /v1/tenant/keys/{keyId}`,
+ * `nylorun-operate keys`, `operator-keys.ts`); no other key is derived.
  *
- * The derivations are the ones `@nylorun/admin` computes on the client side
- * (`admin/src/derived-credentials.ts`: `deriveStudioToken`, `deriveTenantKey`); both sides
- * must stay byte for byte the same.
+ * The derivation is the one `@nylorun/admin` computes on the client side
+ * (`admin/src/derived-credentials.ts`: `deriveStudioToken`); both sides must stay byte for byte
+ * the same.
  */
 import { createHmac } from "node:crypto";
-import { DERIVED_PRINCIPAL_ID_PATTERN } from "@nylorun/core/compatibility";
+import { BOOTSTRAP_KEY_ID } from "@nylorun/core/compatibility";
 import { hashToken } from "../core/bearer.js";
 /** Principal id of the Studio key derived from the admin key. */
 export const STUDIO_PRINCIPAL_ID = "studio";
-/** The derived principal Projects use (`PROJECT_PRINCIPAL_ID` in `@nylorun/admin`). */
-export const PROJECT_PRINCIPAL_ID = "project";
-/** The derived principals a Host registers when not told otherwise. */
-export const DEFAULT_DERIVED_PRINCIPALS = [PROJECT_PRINCIPAL_ID];
-/** The Studio key of `tenantId`: HMAC-SHA256 of the admin key. */
-export function deriveStudioKey(adminKey, tenantId) {
-    return hmac(adminKey, ["nylorun/studio/v1", tenantId]);
-}
-/** The key of derived principal `principalId` on `tenantId`: HMAC-SHA256 of the admin key. */
-export function deriveTenantKey(adminKey, tenantId, principalId) {
-    return hmac(adminKey, ["nylorun/principal/v1", principalId, tenantId]);
-}
-/** Whether `id` may name a derived principal: the client's name, never `studio`. */
-export function isDerivedPrincipalId(id) {
-    return DERIVED_PRINCIPAL_ID_PATTERN.test(id) && id !== STUDIO_PRINCIPAL_ID;
+/**
+ * The Studio key: HMAC-SHA256 of the admin key over `nylorun/studio/v2`. It names no Tenant
+ * (protocol 8): Studio derives it before it can learn the Tenant's id, and the admin key is
+ * already one per installation.
+ */
+export function deriveStudioKey(adminKey) {
+    return hmac(adminKey, ["nylorun/studio/v2"]);
 }
 /**
- * The principals a Host's Tenant is created with: `studio`, each derived principal, and an
- * application principal when a key is given (the ephemeral Runtime). Keys are hashed here.
+ * The principals a Host's Tenant is created with: `studio`, and an application principal when
+ * a key is given (the ephemeral Runtime). Keys are hashed here.
  */
 export function hostPrincipals(options) {
-    const derived = options.derived ?? DEFAULT_DERIVED_PRINCIPALS;
-    for (const id of derived)
-        if (!isDerivedPrincipalId(id))
-            throw new Error(`Derived principal id '${id}' must match ${DERIVED_PRINCIPAL_ID_PATTERN} and not be '${STUDIO_PRINCIPAL_ID}'`);
-    return (tenantId) => [
+    return () => [
+        ...(options.bootstrapKey
+            ? [
+                {
+                    id: BOOTSTRAP_KEY_ID,
+                    role: "management",
+                    credentialHash: hashToken(options.bootstrapKey),
+                    replace: true,
+                },
+            ]
+            : []),
         ...(options.application
             ? [
                 {
@@ -49,13 +48,13 @@ export function hostPrincipals(options) {
             : []),
         {
             id: STUDIO_PRINCIPAL_ID,
-            credentialHash: options.studioCredentialHash ??
-                hashToken(deriveStudioKey(options.adminKey, tenantId)),
+            // Studio runs sessions and edits the Tenant's settings: both APIs (protocol 8).
+            role: "studio",
+            credentialHash: options.studioCredentialHash ?? hashToken(deriveStudioKey(options.adminKey)),
+            // Its key derives from the admin key: a database holding an older derivation (v1, with
+            // the Tenant id) takes this one at the next start.
+            replace: true,
         },
-        ...[...new Set(derived)].map((id) => ({
-            id,
-            credentialHash: hashToken(deriveTenantKey(options.adminKey, tenantId, id)),
-        })),
     ];
 }
 /** HMAC-SHA256 (hex) of `parts` joined by NUL bytes, keyed with the admin key. */

package/dist/tenant/run-token.js

@@ -4,9 +4,9 @@
  * remote MCP calls. The gates take session, turn and agent from it, never from the body, and
  * check on every call that the lease it names is still the session's (`staleRun`).
  *
- * Signed by the keys service with the Tenant's current signing key, like subject and delivery
- * tokens, and told apart from them by `typ` and `aud`. Internal: not in `openapi.json`. A token
- * lives `RUN_TOKEN_TTL_SECONDS`, no longer than a delivery token, so a key rotation never
+ * Signed by the keys service with the Tenant's current signing key, like capability links,
+ * and told apart from them by `typ` and `aud`. Internal: not in `openapi.json`. A token lives
+ * `RUN_TOKEN_TTL_SECONDS`, no longer than `TOKEN_TTL_MAX_SECONDS`, so a key rotation never
  * revokes a live one (`signing-keys.ts`).
  *
  * ```text
@@ -17,7 +17,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { errors, importJWK, jwtVerify } from "jose";
-import { subjectTokenIssuer } from "@nylorun/core/contracts";
+import { tenantTokenIssuer } from "@nylorun/core/contracts";
 import { CLOCK_TOLERANCE_SECONDS, tokenKeyId } from "./jwt.js";
 export const RUN_TOKEN_TYP = "nylorun-run+jwt";
 export const RUN_TOKEN_AUD = "nylorun-gates";
@@ -42,7 +42,7 @@ export async function mintRunToken(signer, lease, session) {
     const { token } = await signer.keys.sign({
         typ: RUN_TOKEN_TYP,
         claims: {
-            iss: subjectTokenIssuer(tenantId),
+            iss: tenantTokenIssuer(tenantId),
             aud: RUN_TOKEN_AUD,
             sub: lease.sessionId,
             trn: turnId,
@@ -89,7 +89,7 @@ export async function verifyRunToken(store, tenantId, raw, cache = new Map()) {
     try {
         const verified = await jwtVerify(raw, key, {
             algorithms: ["ES256"],
-            issuer: subjectTokenIssuer(tenantId),
+            issuer: tenantTokenIssuer(tenantId),
             audience: RUN_TOKEN_AUD,
             typ: RUN_TOKEN_TYP,
             clockTolerance: CLOCK_TOLERANCE_SECONDS,

package/dist/tenant/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { TenantEnvelope } from "@nylorun/core/contracts";
+import type { HarnessStatus, TenantEnvelope } from "@nylorun/core/contracts";
 import { type ModelProvider } from "../core/provider.js";
 import type { ModelGate } from "../gates/model-gate.js";
 import { type AuthorizeResult } from "../vault/service.js";
@@ -23,8 +23,8 @@ export type TenantOpenHooks = {
      */
     modelGate?: ModelGate;
     /**
-     * Serves the Tenant's remote MCP servers and Action deliveries (the gates service's client).
-     * Without one, the Tenant opens them and POSTs deliveries in this process.
+     * Serves the Tenant's remote MCP servers and HTTP tools (the gates service's client).
+     * Without one, the Tenant opens and calls them in this process.
      */
     toolGate?: ToolGate;
     /**
@@ -102,6 +102,7 @@ export declare class TenantRuntime implements TenantHandle {
     authorize(sessionId: string, request: {
         url: string;
         serverName?: string;
+        agentId?: string;
     }): Promise<AuthorizeResult>;
     summary(): Promise<TenantSummary>;
     drain(activeWork: "drain" | "cancel", timeoutMs?: number): Promise<void>;
@@ -118,6 +119,7 @@ export declare class TenantRuntime implements TenantHandle {
     /** Adds a callback to the Tenant sweep. Returns a function that removes it. */
     onSweep(hook: () => Promise<void>): () => void;
     attachHarness(channel: HarnessChannel, peer: HarnessPeer): () => void;
+    harnessStatus(): HarnessStatus;
     close(): Promise<void>;
 }
 /**