@nylorun/runtime 0.19.0-beta → 0.20.0-beta

package/dist/api/http/define.d.ts

@@ -27,7 +27,8 @@ export interface RouteAccess {
     /** The subject scopes that reach the route: any one of them, none (`never`), or all (`any`). */
     readonly scopes: readonly SubjectScope[] | "never" | "any";
     /**
-     * Public data: a request with no credential at all (no `Authorization`) is served too. A credential that is sent is still checked, so a wrong one stays the opaque 404.
+     * Public data: a request with no credential at all (no `Authorization`) is served too. A
+     * credential that is sent is still checked, so a wrong one is `401 credential_invalid`.
      */
     readonly anonymous?: boolean;
     /**
@@ -49,7 +50,7 @@ export declare function authenticateCaller(c: Context<TenantEnv>,
 anonymous?: boolean, 
 /** The keys the route takes; a Runtime API route's by default. */
 keys?: KeyAccess): Promise<AuthScope>;
-/** No route: authenticated first, so an unknown credential stays the opaque 404. */
+/** No route: authenticated first, so only a known credential learns there is no such route. */
 export declare function routeNotFound(c: Context<TenantEnv>): Promise<Response>;
 /** Which keys a route's credentials take. */
 export declare function keyAccess(access: RouteAccess): KeyAccess;

package/dist/api/http/define.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { PROTOCOL_VERSION } from "@nylorun/core/compatibility";
-import { authenticate, requireScopes } from "../../tenant/auth.js";
+import { authenticate, challengeMetadata, requireScopes, } from "../../tenant/auth.js";
 import { fail } from "../../tenant/http.js";
 import { ProtocolRejected, Rejected } from "../components.js";
 const SCHEMES = {
@@ -38,7 +38,7 @@ keys) {
         return { kind: "anonymous" };
     return await authenticate(tenant, incoming, keys);
 }
-/** No route: authenticated first, so an unknown credential stays the opaque 404. */
+/** No route: authenticated first, so only a known credential learns there is no such route. */
 export async function routeNotFound(c) {
     // Any known key, of either API, learns only that there is no such route.
     await authenticateCaller(c, false, { application: true, management: true });
@@ -64,8 +64,9 @@ export function declaredRoute(method, segments) {
 }
 function authenticated(access) {
     return async (c, next) => {
-        const scope = await authenticateCaller(c, access.anonymous === true, keyAccess(access));
-        requireScopes(scope, access.scopes);
+        const keys = keyAccess(access);
+        const scope = await authenticateCaller(c, access.anonymous === true, keys);
+        requireScopes(scope, access.scopes, challengeMetadata(c.env.tenant, c.env.incoming, keys));
         c.set("scope", scope);
         await next();
     };
@@ -99,15 +100,13 @@ export function tenantRoute(api, access, route, handler) {
         request: { ...route.request, headers },
         responses: {
             400: rejected("Invalid headers, path, body or cursor"),
-            ...(takes("token")
-                ? {
-                    401: rejected("The token expired (`token_expired`), or its issuer's keys cannot be fetched now (`issuer_unavailable`)"),
-                }
-                : {}),
+            401: rejected(takes("token")
+                ? "No credential (`credential_required`), one the Tenant does not accept (`credential_invalid`), a token that expired (`token_expired`), or a token whose issuer's keys cannot be fetched now (`issuer_unavailable`). `WWW-Authenticate: Bearer` names the protected resource metadata (`resource_metadata`)"
+                : "No credential (`credential_required`), or one the Tenant does not accept (`credential_invalid`), with a `WWW-Authenticate: Bearer` challenge"),
             403: rejected(takes("management")
                 ? "Not allowed for this credential, a key of the other API (`key_role_mismatch`), a key from a browser (`origin_rejected`) or a management key acting for a subject"
-                : "Not allowed for this credential or subject scope, a key of the other API (`key_role_mismatch`), or an application key from a browser (`origin_rejected`)"),
-            404: rejected("Not found, or a credential the Tenant does not know (`not_found`)"),
+                : "Not allowed for this credential or subject scope (`scope_required`; a token also gets `WWW-Authenticate: Bearer error=\"insufficient_scope\"` and the scope), a key of the other API (`key_role_mismatch`), or an application key from a browser (`origin_rejected`)"),
+            404: rejected("Not found (`not_found`)"),
             426: { description: "`Nylorun-Protocol` missing or unsupported", content: { "application/json": { schema: ProtocolRejected } } },
             503: rejected("The Tenant's storage or streams are unavailable"),
             ...route.responses,

package/dist/api/openapi.js

@@ -12,6 +12,7 @@
 import { OpenAPIRegistry, OpenApiGeneratorV32, } from "@asteasolutions/zod-to-openapi";
 import { HOST_PROTOCOL } from "@nylorun/core/compatibility";
 import { HealthResponseSchema, ReadyResponseSchema } from "@nylorun/core/contracts";
+import { z } from "zod";
 import { RUNTIME_VERSION } from "../version.js";
 import { tenantApi } from "./http/app.js";
 const PROTOCOL = {
@@ -25,7 +26,22 @@ const bearer = (description, bearerFormat) => ({
     ...(bearerFormat ? { bearerFormat } : {}),
     description,
 });
-/** `/health`, `/ready` and `/openapi.json`: what every listener answers without a key. */
+/** RFC 9728 protected resource metadata, as `tenant/resource-server.ts` builds it. */
+const ProtectedResourceMetadataSchema = z
+    .object({
+    resource: z.string().meta({ description: "The Runtime API: `NYLORUN_PUBLIC_URL`, else the origin the request reached" }),
+    authorization_servers: z
+        .array(z.string())
+        .meta({ description: "The identity file's issuers, in its order: a client usually signs in at the first" }),
+    scopes_supported: z.array(z.string()).meta({ description: "The scopes the issuers' tokens may carry, `studio` aside" }),
+    bearer_methods_supported: z.array(z.literal("header")),
+    resource_name: z.string(),
+})
+    .meta({ id: "ProtectedResourceMetadata" });
+/**
+ * `/health`, `/ready`, the documents and the OAuth metadata: what every listener answers
+ * without a key. The `/openapi.json` alias is served but left out of the documents.
+ */
 function hostRoutes() {
     const registry = new OpenAPIRegistry();
     const route = (config) => registry.registerPath(config);
@@ -58,17 +74,24 @@ function hostRoutes() {
     });
     route({
         method: "get",
-        path: "/openapi/runtime.json",
+        path: "/.well-known/oauth-protected-resource",
         tags: ["Host"],
-        summary: "Get the Runtime API's document",
-        description: "This document. `/openapi.json` is the same.",
-        responses: { 200: { description: "The Runtime API's OpenAPI document" } },
+        summary: "Get the protected resource metadata",
+        description: "OAuth 2.0 Protected Resource Metadata (RFC 9728): the identity providers whose access tokens the Runtime API accepts (the identity file's trusted issuers) and their scopes. Nylorun is never the authorization server: a client signs in at one of `authorization_servers` and presents its token as `Authorization: Bearer`. A `401` from the Runtime API names this document in `WWW-Authenticate` (`resource_metadata`). Needs no key or `Nylorun-Protocol`, and accepts an `Origin`.",
+        responses: {
+            200: {
+                description: "The metadata",
+                content: { "application/json": { schema: ProtectedResourceMetadataSchema } },
+            },
+            404: { description: "The Runtime trusts no identity provider (no identity file)" },
+        },
     });
     route({
         method: "get",
-        path: "/openapi.json",
+        path: "/openapi/runtime.json",
         tags: ["Host"],
-        summary: "Get the Runtime API's document (alias)",
+        summary: "Get the Runtime API's document",
+        description: "This document. `/openapi.json` is the same.",
         responses: { 200: { description: "The Runtime API's OpenAPI document" } },
     });
     route({
@@ -86,19 +109,6 @@ function tenantSchemes(registry) {
     registry.registerComponent("securitySchemes", "issuerToken", bearer("A JWT from a trusted issuer of the Host's identity file (Host feature `trusted-issuers`): one person, with the issuer's scopes, agents and sandbox grants, until it expires. Accepted from servers and browsers alike; CORS is the operator's proxy's.", "JWT"));
 }
 const RUNTIME_TAGS = [
-    {
-        name: "Runtime",
-        group: "Get started",
-        description: "Check a Runtime is up and speaks your protocol, ask who your credential is, and read the public keys of the tokens it signs. `/health`, `/ready`, the JWKS and the documents need no key.",
-        operations: [
-            "GET /health",
-            "GET /ready",
-            "GET /v1/me",
-            "GET /v1/access/jwks",
-            "GET /openapi/runtime.json",
-            "GET /openapi.json",
-        ],
-    },
     {
         name: "Agents",
         group: "Agents",
@@ -147,7 +157,7 @@ const RUNTIME_TAGS = [
     },
     {
         name: "Sandboxes",
-        group: "Sandboxes & artifacts",
+        group: "Sandboxes",
         description: "Isolated machines an agent works in: create or find one, watch its lifecycle, stop, reset or delete it. In `@nylorun/agents`.",
         operations: [
             "PUT /v1/sandboxes/{sandboxId}",
@@ -161,7 +171,7 @@ const RUNTIME_TAGS = [
     },
     {
         name: "Artifacts",
-        group: "Sandboxes & artifacts",
+        group: "Artifacts",
         description: "Files and folders agents and people produce, versioned, with short-lived capability links to share them. In `@nylorun/agents`.",
         operations: [
             "POST /v1/artifacts",
@@ -178,6 +188,19 @@ const RUNTIME_TAGS = [
             "DELETE /v1/artifacts/{artifactId}",
         ],
     },
+    {
+        name: "Service",
+        group: "Service",
+        description: "Check a Runtime is up and speaks your protocol, ask who your credential is, find the identity providers it takes tokens from, and read the public keys of the tokens it signs. `/health`, `/ready`, the protected resource metadata, the JWKS and the documents need no key.",
+        operations: [
+            "GET /health",
+            "GET /ready",
+            "GET /v1/me",
+            "GET /.well-known/oauth-protected-resource",
+            "GET /v1/access/jwks",
+            "GET /openapi/runtime.json",
+        ],
+    },
 ];
 const MANAGEMENT_TAGS = [
     {

package/dist/execution/types.d.ts

@@ -91,7 +91,7 @@ export interface SandboxResult {
 export interface WorkerHandlers {
     /**
      * Advances one session (§10.5). `signal` aborts when the Worker stops or the
-     * session is cancelled through the control stream. Throw only on
+     * session is cancelled through the control bus. Throw only on
      * infrastructure errors.
      */
     advance(tenantId: string, sessionId: string, signal: AbortSignal): Promise<AdvanceResult>;

package/dist/host/app.d.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import type { Logger, NodeBindings, TenantModule } from "../tenant/types.js";
+import { type ResourceServerConfig } from "../tenant/resource-server.js";
 export type HostEnv = {
     Bindings: NodeBindings;
     Variables: {
@@ -19,6 +20,8 @@ export interface HostAppOptions {
         ok: boolean;
         checks: Record<string, boolean>;
     }>;
+    /** The public URL and trusted issuers the OAuth metadata and challenges name. */
+    resourceServer?: ResourceServerConfig;
     /** The listener is listening. */
     listening(): boolean;
     closing(): boolean;

package/dist/host/app.js

@@ -3,10 +3,13 @@ import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
 import { checkCompatibility, HOST_PROTOCOL, PROTOCOL_HEADER, TENANT_HEADER, } from "@nylorun/core/compatibility";
 import { RUNTIME_VERSION } from "../version.js";
 import { findTenantRoute } from "../api/http/app.js";
+import { keyAccess } from "../api/http/define.js";
+import { bearerChallenge, PROTECTED_RESOURCE_PATH, protectedResourceMetadata, protectedResourceMetadataUrl, } from "../tenant/resource-server.js";
 import { managementDocument, runtimeDocument } from "../api/openapi.js";
 import { headerValue, isJsonContentType, jsonResponse, opaqueNotFoundResponse, protocolRejectedResponse, pathnameIsLogged, redactRoutePath, rejectedResponse, requestHasBody, } from "./http.js";
 export function createHostApp(options) {
     const { module, logger } = options;
+    const resourceServer = options.resourceServer ?? {};
     const app = new Hono();
     app.use(async (c, next) => {
         const started = Date.now();
@@ -28,9 +31,10 @@ export function createHostApp(options) {
     app.use(async (c, next) => {
         const { incoming } = c.env;
         if (headerValue(incoming, "origin") !== undefined) {
-            // Only Tenant routes; the Tenant then accepts only a trusted issuer's token from a
-            // browser.
-            if (pathnameOf(incoming).split("/").filter(Boolean)[0] !== "v1")
+            // Only Tenant routes, where the Tenant then accepts only a trusted issuer's token from a
+            // browser, and the public OAuth metadata a browser client reads before it signs in.
+            if (pathnameOf(incoming).split("/").filter(Boolean)[0] !== "v1" &&
+                !isProtectedResourcePath(pathnameOf(incoming)))
                 return rejectedResponse(403, "origin_rejected", "Browser Origin headers are not accepted");
         }
         // CORS is the operator's proxy's: an OPTIONS request gets no CORS header.
@@ -83,13 +87,35 @@ export function createHostApp(options) {
             return jsonResponse(200, runtimeDocument(), { "cache-control": "no-cache" });
         if (pathname === "/openapi/management.json" && incoming.method === "GET")
             return jsonResponse(200, managementDocument(), { "cache-control": "no-cache" });
+        // RFC 9728: where the Runtime API's tokens come from. None without trusted issuers.
+        if (isProtectedResourcePath(pathname) && incoming.method === "GET") {
+            const metadata = protectedResourceMetadata(resourceServer, incoming);
+            return metadata
+                ? jsonResponse(200, metadata, { "cache-control": "no-cache" })
+                : rejectedResponse(404, "not_found", "This Runtime trusts no identity provider");
+        }
         // Tenant routes: protocol → the Tenant → selection → the Tenant's routes.
         const tenantHeader = headerValue(incoming, TENANT_HEADER);
         const named = tenantHeader === undefined || tenantHeader.trim() === "" ? undefined : tenantHeader.trim();
         const protocol = headerValue(incoming, PROTOCOL_HEADER);
+        // A generic OAuth client sends neither header: answer it the challenge, not the 426.
+        const route = tenantRouteOf(incoming);
+        if (protocol === undefined &&
+            headerValue(incoming, "authorization") === undefined &&
+            route !== undefined &&
+            route.anonymous !== true) {
+            const metadata = keyAccess(route).application
+                ? protectedResourceMetadataUrl(resourceServer, incoming)
+                : undefined;
+            return jsonResponse(401, {
+                status: "rejected",
+                code: "credential_required",
+                message: "A bearer credential is required",
+            }, { "www-authenticate": bearerChallenge({ resourceMetadata: metadata }) });
+        }
         // A capability link is opened without the header; when one is sent, it is checked.
         if (!protocolAccepted(protocol) &&
-            !(protocol === undefined && tenantRouteOf(incoming)?.unversioned === true))
+            !(protocol === undefined && route?.unversioned === true))
             return protocolRejectedResponse();
         const resolution = await module.resolve();
         if (resolution.kind !== "open") {
@@ -138,6 +164,9 @@ export function createHostApp(options) {
 }
 /** The methods the Runtime serves, for an `OPTIONS` answer's `Allow`. */
 const ALLOWED_METHODS = "GET, POST, PUT, DELETE, OPTIONS";
+function isProtectedResourcePath(pathname) {
+    return pathname === PROTECTED_RESOURCE_PATH || pathname.startsWith(`${PROTECTED_RESOURCE_PATH}/`);
+}
 /** The Tenant route a request names, if any; a malformed path names none. */
 function tenantRouteOf(incoming) {
     const segments = [];

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

@@ -1,3 +1,4 @@
+import type { ResourceServerConfig } from "../tenant/resource-server.js";
 import type { Logger, TenantModule } from "../tenant/types.js";
 import type { HostConfigFile } from "./config.js";
 import type { ContainerListen } from "./stack-config.js";
@@ -25,6 +26,11 @@ export interface CreateHostOptions {
         ok: boolean;
         checks: Record<string, boolean>;
     }>;
+    /**
+     * The public URL and trusted issuers behind `/.well-known/oauth-protected-resource` and the
+     * challenge a request without credential or protocol gets (protocol 9). Absent: no metadata.
+     */
+    resourceServer?: ResourceServerConfig;
     /**
      * Shutdown steps around closing the Tenant. `close()` runs them whatever asked for it
      * (SIGTERM in `host/main.ts`): the listener stops, then

package/dist/host/create-host.js

@@ -20,6 +20,7 @@ export function createHost(options) {
         coreVersion,
         pid,
         ...(options.readiness ? { readiness: options.readiness } : {}),
+        ...(options.resourceServer ? { resourceServer: options.resourceServer } : {}),
         listening: () => Boolean(server?.listening),
         closing: () => closing,
     });

package/dist/host/main.js

@@ -71,9 +71,10 @@ function loadJson(path) {
 /**
  * The trusted issuers of the identity file (`NYLORUN_IDENTITY_FILE`, Host feature
  * `trusted-issuers`). A missing or malformed file stops the boot, naming the issuer and field;
- * an issuer's JWKS is fetched only when a token needs it, so one that is down does not.
+ * a key the file does not define is logged and ignored. An issuer's JWKS is fetched only when a
+ * token needs it, so one that is down does not stop the boot.
  */
-function loadIssuers(path) {
+function loadIssuers(path, logger) {
     let text;
     try {
         text = readFileSync(path, "utf8");
@@ -81,7 +82,9 @@ function loadIssuers(path) {
     catch (error) {
         throw new Error(`NYLORUN_IDENTITY_FILE names ${path}, which cannot be read: ${error instanceof Error ? error.message : String(error)}`);
     }
-    return createTrustedIssuers(parseIdentityFile(text, path));
+    return createTrustedIssuers(parseIdentityFile(text, path, {
+        warn: (message) => logger.warn("identity_file_key_ignored", { message }),
+    }));
 }
 /** The bootstrap management key: 64 hex characters, surrounding whitespace ignored. */
 function loadManagementKey(path) {
@@ -224,8 +227,8 @@ export async function main() {
     const config = loadJson(paths.config);
     const credentials = loadJson(paths.credentials);
     const identityFile = stack.tenant?.identityFile;
-    const issuers = identityFile ? loadIssuers(identityFile) : undefined;
     const logger = createHostLogger();
+    const issuers = identityFile ? loadIssuers(identityFile, logger) : undefined;
     if (issuers)
         logger.info("trusted_issuers", {
             file: identityFile,
@@ -362,6 +365,10 @@ export async function main() {
         coreVersion: coreVersion(),
         ...(stack.listen ? { listen: stack.listen } : {}),
         ...(infra.readiness ? { readiness: infra.readiness } : {}),
+        resourceServer: {
+            ...(issuers ? { issuers } : {}),
+            ...(stack.publicUrl ? { publicUrl: stack.publicUrl } : {}),
+        },
         // SIGTERM closes the Host this way: stop the Worker and the relay, close the Tenant, then end the infrastructure clients.
         shutdown: {
             beforeTenants: async () => {

package/dist/host/stack-config.js

@@ -66,7 +66,7 @@ export const DEFAULT_SERVICES = new Set([
 ]);
 /** Services of the blueprint this release doesn't have yet. */
 const LATER_SERVICES = [
-    "sandboxd",
+    "sandboxes",
 ];
 const ROLE_SERVICES = {
     api: ["core"],

package/dist/infra/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * The Host's infrastructure clients, built from the stack configuration: the
  * Postgres pool, Durable Session Execution and Durable Streams, each only when
- * its endpoints are configured, plus the readiness that covers them.
+ * its endpoints are configured, plus the readiness that covers Postgres and
+ * Restate (not S2: `readiness.ts`).
  *
  * Building a client connects to nothing: the pool connects on first query,
  * Restate and S2 on first call. Nothing here starts a Worker (see

package/dist/infra/index.js

@@ -20,7 +20,6 @@ export function createInfra(config, options = {}) {
     const probes = infraProbes({
         ...(database ? { database } : {}),
         ...(execution ? { execution } : {}),
-        ...(streams ? { streams } : {}),
     });
     const readiness = Object.keys(probes).length > 0
         ? logTransitions(createReadiness(probes), options.logger)

package/dist/infra/readiness.d.ts

@@ -1,20 +1,21 @@
 /**
  * Aggregate readiness of the Host's infrastructure (architecture §13, §14.3):
- * the Runtime's `/ready` covers Postgres, Restate and S2. s2-lite's image has
- * no health check of its own, so this is the only place its health shows.
+ * the Runtime's `/ready` covers Postgres and Restate. S2 is left out (D48): it only
+ * serves API listeners (history, SSE, AG-UI, A2A), so an outage degrades those reads
+ * and never makes the Runtime unready. Its health shows in the Tenant's status
+ * (`GET /v1/tenant`, `streams.reachable`).
  *
  * Every probe runs on each call, in parallel, bounded by one timeout. A probe
  * that throws or outlives the timeout marks its check `false`. Only check
  * names and booleans are reported; the errors stay in the report for logs.
  */
 import type { DurableExecution } from "../execution/types.js";
-import type { DurableStreams } from "../streams/types.js";
 import { type PostgresClient } from "./database.js";
 /** Resolves when the dependency answers; rejects otherwise. Must honour `signal`. */
 export type Probe = (signal: AbortSignal) => Promise<void>;
 export interface ReadinessReport {
     ok: boolean;
-    /** One entry per configured dependency, e.g. `{ postgres, restate, s2 }`. */
+    /** One entry per configured dependency, e.g. `{ postgres, restate }`. */
     checks: Record<string, boolean>;
     /** Why each failing check failed. Not for unauthenticated responses. */
     errors: Record<string, string>;
@@ -25,9 +26,8 @@ export declare const READINESS_TIMEOUT_MS = 2000;
 export declare function createReadiness(probes: Readonly<Record<string, Probe>>, options?: {
     timeoutMs?: number;
 }): Readiness;
-/** The standard checks for whichever infrastructure the Host was built with. */
+/** The standard checks for whichever infrastructure the Host was built with. Never S2 (D48). */
 export declare function infraProbes(infra: {
     database?: PostgresClient;
     execution?: DurableExecution;
-    streams?: DurableStreams;
 }): Record<string, Probe>;

package/dist/infra/readiness.js

@@ -1,6 +1,5 @@
 import { probeDatabase } from "./database.js";
 import { probeExecution } from "./execution.js";
-import { probeStreams } from "./streams.js";
 /** Default bound on one readiness pass. Compose probes `/ready` every 2 s with a 5 s timeout. */
 export const READINESS_TIMEOUT_MS = 2000;
 export function createReadiness(probes, options = {}) {
@@ -18,16 +17,14 @@ export function createReadiness(probes, options = {}) {
         return { ok: Object.values(checks).every(Boolean), checks, errors };
     };
 }
-/** The standard checks for whichever infrastructure the Host was built with. */
+/** The standard checks for whichever infrastructure the Host was built with. Never S2 (D48). */
 export function infraProbes(infra) {
     const probes = {};
-    const { database, execution, streams } = infra;
+    const { database, execution } = infra;
     if (database)
         probes.postgres = (signal) => probeDatabase(database, signal);
     if (execution)
         probes.restate = (signal) => probeExecution(execution, signal);
-    if (streams)
-        probes.s2 = (signal) => probeStreams(streams, signal);
     return probes;
 }
 /** Runs one probe under a timeout; returns its failure message, or undefined when ready. */