@nylorun/runtime 0.15.2-beta → 0.17.0-beta

package/dist/tenant/issuers.d.ts

@@ -0,0 +1,48 @@
+import { type JWTPayload } from "jose";
+import type { AuthScope, TenantContext } from "./context.js";
+import { type TrustedIssuerConfig } from "./identity-file.js";
+/** The byte cap of an issuer's token; Nylorun's own token families keep 4 KiB. */
+export declare const MAX_ISSUER_TOKEN_BYTES: number;
+export interface TrustedIssuersOptions {
+    /** Fetches JWKS URLs. Default: the global fetch. */
+    fetch?: typeof fetch;
+    /** The least time between two JWKS fetches of one issuer for an unknown `kid`. Default 60 s. */
+    refetchMs?: number;
+    /** How old cached JWKS keys get before a background refresh. Default 10 minutes. */
+    maxAgeMs?: number;
+    /** Milliseconds since the epoch. Default `Date.now`. */
+    now?: () => number;
+}
+/** What verifying an issuer's token found. */
+export type IssuerVerdict = {
+    readonly ok: true;
+    readonly payload: JWTPayload;
+    readonly kid?: string;
+} | {
+    readonly ok: false;
+    readonly refused: "invalid" | "expired" | "unavailable";
+    readonly reason: string;
+};
+/** One configured issuer, with its keys. */
+export interface TrustedIssuer {
+    readonly config: TrustedIssuerConfig;
+    /** Checks `raw`'s header and signature, `iss`, `aud`, `exp`, `iat` and its lifetime. */
+    verify(raw: string): Promise<IssuerVerdict>;
+}
+/** The Host's trusted issuers (`TenantConfig.issuers`), built once from the identity file. */
+export interface TrustedIssuers {
+    readonly issuers: readonly TrustedIssuer[];
+    /** The issuer a JWT-shaped bearer claims by its unverified `iss`, if it is one of these. */
+    claimed(raw: string): TrustedIssuer | undefined;
+}
+/** The trusted issuers of `configs` (`parseIdentityFile`). No key is fetched until needed. */
+export declare function createTrustedIssuers(configs: readonly TrustedIssuerConfig[], options?: TrustedIssuersOptions): TrustedIssuers;
+export type IssuerTokenScope = Extract<AuthScope, {
+    kind: "token";
+}>;
+/**
+ * Verifies a bearer that `issuer` claims (`TrustedIssuers.claimed`). Returns the request's
+ * scope; answers `401 token_expired` for an expired token, `401 issuer_unavailable` for a key
+ * the Runtime cannot fetch now, and the opaque 404 for everything else.
+ */
+export declare function verifyIssuerToken(ctx: TenantContext, issuer: TrustedIssuer, raw: string): Promise<IssuerTokenScope>;

package/dist/tenant/issuers.js

@@ -0,0 +1,311 @@
+/**
+ * Trusted issuers (Host feature `trusted-issuers`, F9 I2): JWTs from the operator's own
+ * identity provider, declared in the identity file (`identity-file.ts`), accepted as bearers.
+ * A token is one of theirs when its unverified `iss` names a configured issuer; it is then
+ * verified like this, and nothing else is tried:
+ *
+ * - at most 16 KiB (identity providers' tokens often pass Nylorun's 4 KiB), RS256, ES256 or
+ *   EdDSA, and no header that could name another key (`jku`, `jwk`, `x5u`, `x5c`, `crit`);
+ * - signed by a key of the issuer: its static `keys`, or its JWKS, fetched only from the
+ *   configured URL (`redirect: "error"`), cached by `kid`, refetched at most once a minute for
+ *   a `kid` it has not seen, and refreshed in the background once the cache is 10 minutes old.
+ *   When the JWKS cannot be fetched, cached keys keep working and a new `kid` is
+ *   `401 issuer_unavailable`;
+ * - `iss` and `aud` as configured, `exp` and `iat` present, `exp - iat` at most `maxLifetime`,
+ *   with the 30 s clock tolerance of every Runtime token;
+ * - a subject the template renders from scalar claims, valid and not reserved.
+ *
+ * The result is the `token` AuthScope (F9-D12) with `issuer`: only its expiry ends it. An
+ * expired token is `401 token_expired`; every other refusal is the opaque 404, its reason
+ * logged.
+ */
+import { createHash, createPublicKey } from "node:crypto";
+import { decodeJwt, decodeProtectedHeader, errors, jwtVerify } from "jose";
+import { isSubject } from "@nylorun/core/contracts";
+import { failOpaque, HttpError } from "./http.js";
+import { CLOCK_TOLERANCE_SECONDS, looksLikeToken } from "./jwt.js";
+import { ISSUER_ALGORITHMS, issuerKey, renderTemplate, } from "./identity-file.js";
+/** The byte cap of an issuer's token; Nylorun's own token families keep 4 KiB. */
+export const MAX_ISSUER_TOKEN_BYTES = 16 * 1024;
+/** Subjects the Runtime keeps for itself: never an issuer token's. */
+const RESERVED = new Set(["host", "installation"]);
+const FORBIDDEN_HEADERS = ["jku", "jwk", "x5u", "x5c", "crit"];
+const JWKS_TIMEOUT_MS = 5000;
+const JWKS_MAX_BYTES = 256 * 1024;
+const JWKS_MAX_KEYS = 64;
+const DEFAULT_REFETCH_MS = 60_000;
+const DEFAULT_MAX_AGE_MS = 10 * 60_000;
+/** A grant's claim value: one sandbox id segment, so a claim never widens the template. */
+const GRANT_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** The issuer's public keys: static, or its JWKS's as last fetched. */
+class IssuerKeys {
+    config;
+    options;
+    byKid = new Map();
+    unnamed = [];
+    fetchedAt = Number.NEGATIVE_INFINITY;
+    okAt = Number.NEGATIVE_INFINITY;
+    lastOk;
+    inflight;
+    constructor(config, options) {
+        this.config = config;
+        this.options = options;
+        for (const key of config.keys ?? [])
+            this.unnamed.push(key);
+    }
+    /** The keys that may have signed a token with `kid` and `alg`, or `unavailable`. */
+    async candidates(kid, alg) {
+        const usable = (key) => key.alg === alg;
+        // Static keys have no `kid`; a JWKS token with a `kid` is checked against that key alone.
+        const pick = () => {
+            if (!this.config.jwks)
+                return this.unnamed.filter(usable);
+            if (kid !== undefined) {
+                const key = this.byKid.get(kid);
+                return key && usable(key) ? [key] : [];
+            }
+            return [...this.byKid.values(), ...this.unnamed].filter(usable);
+        };
+        if (!this.config.jwks)
+            return pick();
+        const now = this.options.now();
+        let found = pick();
+        if (found.length === 0) {
+            if (this.inflight)
+                await this.inflight;
+            else if (now - this.fetchedAt >= this.options.refetchMs)
+                await this.refresh();
+            found = pick();
+            if (found.length === 0 && this.lastOk === false)
+                return "unavailable";
+        }
+        else if (now - this.okAt >= this.options.maxAgeMs && now - this.fetchedAt >= this.options.refetchMs) {
+            // Old keys keep working while the refresh runs, and when it fails.
+            void this.refresh();
+        }
+        return found;
+    }
+    /** Fetches the JWKS once, joining a fetch already running. A failure keeps the cache. */
+    refresh() {
+        this.inflight ??= this.fetchKeys().finally(() => {
+            this.inflight = undefined;
+        });
+        return this.inflight;
+    }
+    async fetchKeys() {
+        const started = this.options.now();
+        this.fetchedAt = started;
+        try {
+            const response = await this.options.fetch(this.config.jwks, {
+                redirect: "error",
+                headers: { accept: "application/jwk-set+json, application/json" },
+                signal: AbortSignal.timeout(JWKS_TIMEOUT_MS),
+            });
+            if (!response.ok)
+                throw new Error(`JWKS answered ${response.status}`);
+            const text = await response.text();
+            if (Buffer.byteLength(text) > JWKS_MAX_BYTES)
+                throw new Error("JWKS is too large");
+            const body = JSON.parse(text);
+            if (!Array.isArray(body.keys))
+                throw new Error("JWKS has no keys array");
+            const byKid = new Map();
+            const unnamed = [];
+            for (const jwk of body.keys.slice(0, JWKS_MAX_KEYS)) {
+                const key = jwkKey(jwk);
+                if (!key)
+                    continue;
+                if (key.kid !== undefined)
+                    byKid.set(key.kid, key);
+                else
+                    unnamed.push(key);
+            }
+            this.byKid = byKid;
+            this.unnamed = unnamed;
+            this.okAt = started;
+            this.lastOk = true;
+        }
+        catch {
+            this.lastOk = false;
+        }
+    }
+}
+/** A JWK an issuer signs with, or undefined for one the Runtime does not use. */
+function jwkKey(jwk) {
+    if (!jwk || typeof jwk !== "object")
+        return undefined;
+    const entry = jwk;
+    if (entry.use !== undefined && entry.use !== "sig")
+        return undefined;
+    if (entry.d !== undefined)
+        return undefined; // a private key: never trusted as published
+    if (entry.alg !== undefined && !ISSUER_ALGORITHMS.includes(entry.alg))
+        return undefined;
+    const kid = typeof entry.kid === "string" && entry.kid.length <= 256 ? entry.kid : undefined;
+    try {
+        const key = issuerKey(createPublicKey({ key: jwk, format: "jwk" }), kid);
+        return entry.alg === undefined || entry.alg === key.alg ? key : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function trustedIssuer(config, options) {
+    const keys = new IssuerKeys(config, options);
+    return {
+        config,
+        async verify(raw) {
+            const refuse = (refused, reason) => ({
+                ok: false,
+                refused,
+                reason,
+            });
+            let header;
+            try {
+                header = decodeProtectedHeader(raw);
+            }
+            catch {
+                return refuse("invalid", "issuer_token_malformed");
+            }
+            const alg = header.alg;
+            if (!ISSUER_ALGORITHMS.includes(alg) ||
+                (header.kid !== undefined && typeof header.kid !== "string") ||
+                FORBIDDEN_HEADERS.some((name) => name in header))
+                return refuse("invalid", "issuer_token_header");
+            const kid = header.kid;
+            const candidates = await keys.candidates(kid, alg);
+            if (candidates === "unavailable")
+                return refuse("unavailable", "issuer_jwks_unavailable");
+            if (candidates.length === 0)
+                return refuse("invalid", "issuer_key_unknown");
+            for (const candidate of candidates) {
+                try {
+                    const { payload } = await jwtVerify(raw, candidate.key, {
+                        algorithms: [candidate.alg],
+                        issuer: config.issuer,
+                        audience: config.audience,
+                        clockTolerance: CLOCK_TOLERANCE_SECONDS,
+                        requiredClaims: ["iat", "exp"],
+                        currentDate: new Date(options.now()),
+                    });
+                    const now = Math.floor(options.now() / 1000);
+                    if (payload.iat > now + CLOCK_TOLERANCE_SECONDS)
+                        return refuse("invalid", "issuer_token_future");
+                    if (payload.exp - payload.iat > config.maxLifetimeSeconds)
+                        return refuse("invalid", "issuer_token_lifetime");
+                    return { ok: true, payload, ...(kid !== undefined ? { kid } : {}) };
+                }
+                catch (error) {
+                    // Signature checks come first: an expiry is only reported for a token the issuer signed.
+                    if (error instanceof errors.JWSSignatureVerificationFailed)
+                        continue;
+                    if (error instanceof errors.JWTExpired)
+                        return refuse("expired", "issuer_token_expired");
+                    return refuse("invalid", "issuer_token_invalid");
+                }
+            }
+            return refuse("invalid", "issuer_token_signature");
+        },
+    };
+}
+/** The trusted issuers of `configs` (`parseIdentityFile`). No key is fetched until needed. */
+export function createTrustedIssuers(configs, options = {}) {
+    const resolved = {
+        fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init)),
+        refetchMs: options.refetchMs ?? DEFAULT_REFETCH_MS,
+        maxAgeMs: options.maxAgeMs ?? DEFAULT_MAX_AGE_MS,
+        now: options.now ?? Date.now,
+    };
+    const issuers = configs.map((config) => trustedIssuer(config, resolved));
+    const byIss = new Map(issuers.map((issuer) => [issuer.config.issuer, issuer]));
+    return {
+        issuers,
+        claimed(raw) {
+            if (byIss.size === 0 || Buffer.byteLength(raw) > MAX_ISSUER_TOKEN_BYTES || !looksLikeToken(raw))
+                return undefined;
+            try {
+                const iss = decodeJwt(raw).iss;
+                return typeof iss === "string" ? byIss.get(iss) : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}
+/** A claim's value as template text: strings and finite numbers only (scalar claims). */
+function scalarClaim(payload, claim) {
+    if (!Object.hasOwn(payload, claim))
+        return undefined;
+    const value = payload[claim];
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+function scopesOf(config, payload) {
+    let names = [];
+    if ("fixed" in config.scopes)
+        names = [...config.scopes.fixed];
+    else if (Object.hasOwn(payload, config.scopes.claim)) {
+        const value = payload[config.scopes.claim];
+        if (typeof value === "string")
+            names = value.split(" ");
+        else if (Array.isArray(value))
+            names = value;
+    }
+    return new Set(config.allowedScopes.filter((scope) => names.includes(scope)));
+}
+/**
+ * Verifies a bearer that `issuer` claims (`TrustedIssuers.claimed`). Returns the request's
+ * scope; answers `401 token_expired` for an expired token, `401 issuer_unavailable` for a key
+ * the Runtime cannot fetch now, and the opaque 404 for everything else.
+ */
+export async function verifyIssuerToken(ctx, issuer, raw) {
+    const { config } = issuer;
+    const rejected = (reason) => {
+        ctx.config.logger.warn("credential rejected", { reason, issuer: config.name });
+        return failOpaque();
+    };
+    const verdict = await issuer.verify(raw);
+    if (!verdict.ok) {
+        if (verdict.refused === "expired") {
+            ctx.config.logger.warn("issuer token refused", { reason: verdict.reason, issuer: config.name });
+            throw new HttpError(401, "The token has expired", { code: "token_expired" }, { "www-authenticate": 'Bearer error="invalid_token"' });
+        }
+        if (verdict.refused === "unavailable") {
+            ctx.config.logger.warn("issuer token refused", { reason: verdict.reason, issuer: config.name });
+            throw new HttpError(401, `The keys of issuer ${config.name} cannot be fetched now; try again later`, {
+                code: "issuer_unavailable",
+            });
+        }
+        return rejected(verdict.reason);
+    }
+    const { payload } = verdict;
+    const subject = renderTemplate(config.subject, (claim) => scalarClaim(payload, claim));
+    if (subject === undefined || !isSubject(subject) || RESERVED.has(subject))
+        return rejected("issuer_token_subject");
+    const sandboxes = config.sandboxes?.flatMap((grant) => {
+        const rendered = renderTemplate(grant, (claim) => {
+            const value = scalarClaim(payload, claim);
+            return value !== undefined && GRANT_SEGMENT.test(value) ? value : undefined;
+        });
+        // A grant whose claim is missing or not one id segment reaches nothing.
+        return rendered === undefined ? [] : [rendered];
+    });
+    const jti = typeof payload.jti === "string" && payload.jti.length > 0 && payload.jti.length <= 200
+        ? payload.jti
+        : createHash("sha256").update(raw).digest("base64url");
+    return {
+        kind: "token",
+        issuer: config.name,
+        subject,
+        scopes: scopesOf(config, payload),
+        agents: config.agents ? new Set(config.agents) : "*",
+        sandboxes: [...new Set(sandboxes ?? [])],
+        expiresAt: payload.exp * 1000,
+        tokenId: jti,
+        ...(verdict.kid !== undefined ? { keyId: verdict.kid } : {}),
+    };
+}

package/dist/tenant/jwt.js

@@ -1,7 +1,7 @@
 /**
- * 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.
+ * What the Runtime's own tokens share (delivery tokens, capability links, run and host tokens):
+ * 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";

package/dist/tenant/module.js

@@ -158,6 +158,7 @@ export function createTenantModule(options) {
                 pendingActions: summary?.pendingActions ?? 0,
                 uncertainEffects: summary?.uncertainEffects ?? 0,
                 ...(relay ? { relay } : {}),
+                ...(summary?.harness ? { harness: summary.harness } : {}),
             };
         },
         async close() {

package/dist/tenant/operator-keys.d.ts

@@ -0,0 +1,18 @@
+import type { OperatorKey, PutOperatorKeyResponse } from "@nylorun/core/contracts";
+import type { SessionStore } from "../store/types.js";
+/** Why a key id is refused: not a key name, or the reserved `studio`. */
+export type OperatorKeyRefusal = {
+    reason: "invalid" | "reserved";
+    message: string;
+};
+/** The refusal for `id`, or undefined when operator keys may use it. */
+export declare function refuseOperatorKeyId(id: string): OperatorKeyRefusal | undefined;
+export interface OperatorKeys {
+    /** Every principal of the Tenant, by id (Studio's and derived ones included). */
+    list(): Promise<OperatorKey[]>;
+    /** Creates key `id` or rotates it; the key is returned this once. */
+    put(id: string): Promise<PutOperatorKeyResponse | OperatorKeyRefusal>;
+    /** Deletes key `id`: false when there is none. */
+    delete(id: string): Promise<boolean | OperatorKeyRefusal>;
+}
+export declare function operatorKeys(store: SessionStore, now?: () => string): OperatorKeys;

package/dist/tenant/operator-keys.js

@@ -0,0 +1,55 @@
+/**
+ * Operator keys (F9 I1, Host feature `operator-keys`): the Tenant's application keys, managed
+ * by name through the Admin API. 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.
+ */
+import { APPLICATION_KEY_ID_PATTERN } from "@nylorun/core/compatibility";
+import { hashToken, mintBearerToken } from "../core/bearer.js";
+import { STUDIO_PRINCIPAL_ID } from "./principals.js";
+/** The refusal for `id`, or undefined when operator keys may use it. */
+export function refuseOperatorKeyId(id) {
+    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",
+        };
+    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) {
+            const refused = refuseOperatorKeyId(id);
+            if (refused)
+                return refused;
+            const key = mintBearerToken();
+            const { row, rotated } = await store.tx(async (t) => {
+                const existing = await t.principalById(id);
+                return {
+                    row: await t.putPrincipal(id, hashToken(key), now()),
+                    rotated: existing !== undefined,
+                };
+            });
+            return { id: row.id, role: row.role, createdAt: row.createdAt, key, rotated };
+        },
+        async delete(id) {
+            const refused = refuseOperatorKeyId(id);
+            if (refused)
+                return refused;
+            return await store.tx((t) => t.deletePrincipal(id));
+        },
+    };
+}

package/dist/tenant/outbound.d.ts

@@ -42,3 +42,33 @@ export declare function post(target: string, body: string, headers: Record<strin
     signal: AbortSignal;
     maxResponseBytes?: number;
 }): 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`.
+ */
+export declare function guardedFetch(policy: OutboundPolicy, options?: {
+    maxResponseBytes?: number;
+    timeoutMs?: number;
+}): typeof fetch;

package/dist/tenant/outbound.js

@@ -53,18 +53,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 +72,18 @@ export async function post(target, body, headers, options) {
             return callback(null, allowed);
         return callback(null, allowed[0].address, allowed[0].family);
     });
+}
+/** 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;
+    dockerHost(url, policy);
+    const lookup = guardedLookup(policy);
     return new Promise((resolve) => {
         let sent = false;
         let settled = false;
@@ -125,3 +133,127 @@ 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`.
+ */
+export function guardedFetch(policy, options = {}) {
+    const limit = options.maxResponseBytes ?? MAX_FETCH_RESPONSE_BYTES;
+    const timeoutMs = options.timeoutMs ?? FETCH_TIMEOUT_MS;
+    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 ?? 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 }, (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 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(() => {
+                    const answer = new Headers();
+                    for (const [name, value] of Object.entries(response.headers)) {
+                        if (value === undefined)
+                            continue;
+                        for (const item of Array.isArray(value) ? value : [value])
+                            answer.append(name, item);
+                    }
+                    const noBody = status === 204 || status === 304 || method === "HEAD";
+                    resolve(new Response(noBody ? null : Buffer.concat(chunks), {
+                        status,
+                        statusText: response.statusMessage ?? "",
+                        headers: answer,
+                    }));
+                }));
+                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,8 @@ 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/`, `logs/tenant.log`. The vault key is the one exception:
+ * `tmp/`, `sandboxes/`, `plugin-data/`, `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.
  */