@nylorun/runtime 0.12.0-beta → 0.14.0-beta

package/dist/host/admin-api.js

@@ -0,0 +1,178 @@
+/**
+ * The Admin API (`/v1/admin/**`): Tenants and the Host's status, for a caller with the admin
+ * key. The Host checks the listener, the protocol and the admin key first (`app.ts`); what
+ * gets here is authorized. Routes are declared once, for serving and for the OpenAPI document.
+ */
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { z } from "zod";
+import { CreateTenantRequestSchema } from "@nylorun/core/contracts";
+import { AdminStatus as AdminStatusBody, AdminTenantList, AdminTenantStatus, CreateTenantRequest, HostShutdownResponse, ProtocolRejected, Rejected, TenantEnvelope, } from "../api/components.js";
+import { serveRoute } from "../api/route.js";
+import { TenantBusyError, TenantConflictError } from "../tenant/quarantine.js";
+import { TenantNotFoundError, } from "../tenant/types.js";
+import { jsonResponse, opaqueNotFoundResponse, readJsonBody, rejectedResponse, } from "./http.js";
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const rejected = (description) => json(Rejected, description);
+/** What every Admin route may answer before its own logic runs. */
+const gated = {
+    404: rejected("Not found: an unknown admin key, the public listener, or an unknown Tenant"),
+    426: json(ProtocolRejected, "`Nylorun-Protocol` missing or unsupported"),
+};
+const tenantId = z.object({
+    tenantId: z.string().meta({ example: "tn_0123456789abcdefghjkmnpqrs" }),
+});
+function adminRoute(route) {
+    return {
+        ...route,
+        tags: ["Admin"],
+        security: [{ adminKey: [] }],
+        responses: { ...gated, ...route.responses },
+    };
+}
+export function createAdminApi(options) {
+    const { module } = options;
+    const api = new OpenAPIHono();
+    // HEAD is not a GET here: an Admin route answers only the methods it declares.
+    api.use(async (c, next) => {
+        if (c.req.method === "HEAD")
+            return notFound();
+        await next();
+    });
+    serveRoute(api, adminRoute({
+        method: "get",
+        path: "/v1/admin/tenants",
+        summary: "List Tenants",
+        responses: { 200: json(AdminTenantList, "Every Tenant on the Host") },
+    }), async () => jsonResponse(200, await module.list()));
+    serveRoute(api, adminRoute({
+        method: "post",
+        path: "/v1/admin/tenants",
+        summary: "Create a Tenant",
+        description: "Idempotent on `idempotencyKey`: a replay answers 200 with the same Tenant.",
+        request: {
+            body: {
+                required: true,
+                content: { "application/json": { schema: CreateTenantRequest } },
+            },
+        },
+        responses: {
+            200: json(TenantEnvelope, "The Tenant, created earlier by the same request"),
+            201: json(TenantEnvelope, "The Tenant, created"),
+            400: rejected("Invalid JSON or request body (`invalid_request`)"),
+            409: rejected("Another Tenant has this id or idempotency key (`tenant_conflict`)"),
+            413: rejected("Request body over 1 MiB"),
+        },
+    }), async (c) => {
+        const body = CreateTenantRequestSchema.parse(await readJsonBody(c.req.raw));
+        try {
+            const result = await module.create({
+                tenantId: body.tenantId,
+                name: body.name,
+                principalId: body.principalId,
+                credentialHash: body.credentialHash,
+                idempotencyKey: body.idempotencyKey,
+                ...(body.studioCredentialHash
+                    ? { studioCredentialHash: body.studioCredentialHash }
+                    : {}),
+                ...(body.derivedPrincipals?.length
+                    ? { derivedPrincipals: body.derivedPrincipals }
+                    : {}),
+            });
+            return jsonResponse(result.created ? 201 : 200, result.envelope);
+        }
+        catch (error) {
+            const code = error.code;
+            if (error instanceof TenantConflictError ||
+                error.name === "TenantConflictError" ||
+                code === "conflict" ||
+                code === "tenant_conflict")
+                return rejectedResponse(409, "tenant_conflict", error instanceof Error ? error.message : "Tenant conflict");
+            throw error;
+        }
+    });
+    serveRoute(api, adminRoute({
+        method: "get",
+        path: "/v1/admin/tenants/{tenantId}",
+        summary: "Get a Tenant's status",
+        request: { params: tenantId },
+        responses: { 200: json(AdminTenantStatus, "The Tenant and its state") },
+    }), async (c) => {
+        const status = await module.status(c.req.param("tenantId"));
+        return status ? jsonResponse(200, status) : opaqueNotFoundResponse();
+    });
+    serveRoute(api, adminRoute({
+        method: "delete",
+        path: "/v1/admin/tenants/{tenantId}",
+        summary: "Delete a Tenant",
+        request: {
+            params: tenantId,
+            query: z.object({
+                activeWork: z.enum(["refuse", "drain", "cancel"]).optional().meta({
+                    description: "What to do with turns in progress: refuse to delete (default), wait for them, or cancel them",
+                }),
+            }),
+        },
+        responses: {
+            204: { description: "Deleted" },
+            400: rejected("`activeWork` is not refuse, drain or cancel (`invalid_request`)"),
+            409: rejected("The Tenant has work in progress and `activeWork` is refuse (`active_work`)"),
+        },
+    }), async (c) => {
+        const activeWork = c.req.query("activeWork") ?? "refuse";
+        if (activeWork !== "refuse" && activeWork !== "drain" && activeWork !== "cancel")
+            return rejectedResponse(400, "invalid_request", "activeWork must be refuse, drain, or cancel");
+        try {
+            await module.delete(c.req.param("tenantId"), activeWork);
+            return new Response(null, { status: 204 });
+        }
+        catch (error) {
+            if (error instanceof TenantNotFoundError)
+                return opaqueNotFoundResponse();
+            const code = error.code;
+            if (error instanceof TenantBusyError ||
+                error.name === "TenantBusyError" ||
+                code === "active_work" ||
+                code === "conflict")
+                return rejectedResponse(409, "active_work", error instanceof Error ? error.message : "Active work");
+            throw error;
+        }
+    });
+    // D12: `/v1/admin/status` and `/v1/admin/host` are one answer.
+    for (const path of ["/v1/admin/status", "/v1/admin/host"])
+        serveRoute(api, adminRoute({
+            method: "get",
+            path,
+            summary: path.endsWith("host") ? "Get the Host's status (alias)" : "Get the Host's status",
+            responses: { 200: json(AdminStatusBody, "Version, protocol, Tenants and the Host") },
+        }), async () => jsonResponse(200, await options.status()));
+    serveRoute(api, adminRoute({
+        method: "post",
+        path: "/v1/admin/host/shutdown",
+        summary: "Shut the Host down",
+        description: "Answers, then stops the Host. Served by a self-hosted Runtime only.",
+        responses: { 200: json(HostShutdownResponse, "The Host is stopping") },
+    }), (c) => {
+        c.env.outgoing.once("finish", () => options.shutdown());
+        return jsonResponse(200, { status: "shutting_down" });
+    });
+    serveRoute(api, adminRoute({
+        method: "get",
+        path: "/v1/admin/openapi.json",
+        summary: "Get this document",
+        responses: { 200: { description: "The Admin API's OpenAPI document" } },
+    }), () => options.document
+        ? jsonResponse(200, options.document(), { "cache-control": "no-cache" })
+        : notFound());
+    api.notFound(() => notFound());
+    // The Host answers what a route throws (`app.ts`), as it did before Hono.
+    api.onError((error) => {
+        throw error;
+    });
+    return api;
+}
+function notFound() {
+    return rejectedResponse(404, "not_found", "Route not found");
+}

package/dist/host/app.d.ts

@@ -0,0 +1,34 @@
+import { Hono } from "hono";
+import type { Logger, NodeBindings, TenantModule } from "../tenant/types.js";
+import type { ListenerRole } from "./create-host.js";
+export type HostBindings = NodeBindings & {
+    readonly role: ListenerRole;
+};
+export type HostEnv = {
+    Bindings: HostBindings;
+    Variables: {
+        /** The Tenant a request named, for the request log. */
+        tenantId?: string;
+        /** The status to log when it is not the answer's (a rejection after a stream started). */
+        status?: number;
+    };
+};
+export interface HostAppOptions {
+    module: TenantModule;
+    logger: Logger;
+    hostId: string;
+    adminKey: string;
+    coreVersion: string;
+    pid: number;
+    browserAccess: boolean;
+    readiness?: () => Promise<{
+        ok: boolean;
+        checks: Record<string, boolean>;
+    }>;
+    /** Every listener is listening. */
+    listening(): boolean;
+    closing(): boolean;
+    /** The Admin API (`admin-api.ts`), for a request whose admin key checked out. */
+    admin(request: Request, node: NodeBindings): Promise<Response>;
+}
+export declare function createHostApp(options: HostAppOptions): Hono<HostEnv>;

package/dist/host/app.js

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

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

@@ -14,4 +14,6 @@ export declare function configForFactory(options: {
     mode?: TenantConfig["mode"];
     /** Override model; default vault. Fixture/scripted require ephemeral/test mode. */
     model?: TenantConfig["model"];
+    /** How Tenants may call Action endpoints (`StackConfig.delivery`). */
+    delivery?: TenantConfig["delivery"];
 }): (id: string) => TenantConfig;

package/dist/host/config-for.js

@@ -16,6 +16,7 @@ export function configForFactory(options) {
             paths: tenant,
             sandbox: { backend: sandboxBackend },
             model: options.model ?? { kind: "vault" },
+            ...(options.delivery ? { delivery: options.delivery } : {}),
             childEnv: tenantChildEnvironment(baseline, options.hostConfig, tenant),
             logger: {
                 info: (message, fields) => options.logger.info(message, { tenantId: id, ...fields }),

package/dist/host/config.d.ts

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

package/dist/host/cors.d.ts

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

package/dist/host/cors.js

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

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

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