@nylorun/runtime 0.19.1-beta → 0.20.0-beta

package/dist/tenant/auth.js

@@ -1,9 +1,10 @@
 import { SCOPES_HEADER, SUBJECT_HEADER, } from "@nylorun/core/compatibility";
-import { parseSubjectHeaders } from "@nylorun/core/contracts";
+import { parseSubjectHeaders, TOKEN_SCOPES } from "@nylorun/core/contracts";
 import { hashToken } from "../core/bearer.js";
-import { fail, failOpaque } from "./http.js";
+import { fail } from "./http.js";
 import { verifyIssuerToken } from "./issuers.js";
 import { looksLikeToken } from "./jwt.js";
+import { bearerChallenge, failCredential, protectedResourceMetadataUrl } from "./resource-server.js";
 const SUBJECT_INVALID = { code: "subject_invalid" };
 /** One header's value, or `undefined`; a header sent twice is refused. */
 function singleHeader(request, name) {
@@ -18,20 +19,30 @@ function singleHeader(request, name) {
 }
 /** Every route that does not say otherwise is a Runtime API route. */
 export const RUNTIME_KEYS = { application: true, management: false };
+/** The bearer of an `Authorization` header: the scheme is case-insensitive (RFC 9110 §11.1). */
+const BEARER = /^bearer +(\S+) *$/i;
+/**
+ * The `resource_metadata` a route's challenges point at: a Runtime API route's, when the Runtime
+ * trusts issuers. The Management API is no OAuth resource.
+ */
+export function challengeMetadata(ctx, request, keys) {
+    return keys.application ? protectedResourceMetadataUrl(ctx.config, request) : undefined;
+}
 export async function authenticate(ctx, request, keys = RUNTIME_KEYS) {
-    const header = request.headers.authorization;
-    const token = header?.startsWith("Bearer ") ? header.slice(7) : "";
-    if (!token || !header?.startsWith("Bearer ")) {
+    const metadata = challengeMetadata(ctx, request, keys);
+    const token = BEARER.exec(request.headers.authorization ?? "")?.[1];
+    // No credential, or another scheme: the client may not know it needs one (no error code).
+    if (!token) {
         ctx.config.logger.warn("credential rejected", {
             reason: "missing_bearer",
         });
-        return failOpaque();
+        return failCredential("required", metadata);
     }
     // A trusted issuer's token (Host feature `trusted-issuers`), from a server or a browser: its
     // unverified `iss` names an issuer of the identity file, and only that issuer verifies it.
     const issuer = ctx.config.issuers?.claimed(token);
     if (issuer) {
-        const scope = await verifyIssuerToken(ctx, issuer, token);
+        const scope = await verifyIssuerToken(ctx, issuer, token, metadata);
         if (singleHeader(request, SUBJECT_HEADER) !== undefined ||
             singleHeader(request, SCOPES_HEADER) !== undefined)
             fail(403, "An issuer token cannot act for another subject");
@@ -40,7 +51,7 @@ export async function authenticate(ctx, request, keys = RUNTIME_KEYS) {
     // Any other JWT: no issuer of this Host signed it (subject tokens are gone, protocol 7).
     if (looksLikeToken(token)) {
         ctx.config.logger.warn("credential rejected", { reason: "token_unknown_issuer" });
-        return failOpaque();
+        return failCredential("invalid", metadata);
     }
     // Application keys never come from a browser or a shipped app: refused before they are even
     // looked up.
@@ -54,9 +65,9 @@ export async function authenticate(ctx, request, keys = RUNTIME_KEYS) {
         ctx.config.logger.warn("credential rejected", {
             reason: "unknown_token",
         });
-        return failOpaque();
+        return failCredential("invalid", metadata);
     }
-    // Read only after authentication, so an unknown caller sees the opaque 404 either way.
+    // Read only after authentication, so an unknown caller learns nothing of them.
     const subject = singleHeader(request, SUBJECT_HEADER);
     const scopes = singleHeader(request, SCOPES_HEADER);
     // A management key acts as itself on the Management API; Studio's key does too on a route
@@ -92,9 +103,13 @@ export async function authenticate(ctx, request, keys = RUNTIME_KEYS) {
 }
 /**
  * A subject or a token caller reaches a route only with one of the scopes it declares:
- * `403 scope_required`, decided from the route alone before anything is read.
+ * `403 scope_required`, decided from the route alone before anything is read. A token caller
+ * also gets the OAuth challenge (`error="insufficient_scope"` and the scopes that would do), so
+ * its client can ask its identity provider for them; a route no scope reaches has none.
  */
-export function requireScopes(scope, access) {
+export function requireScopes(scope, access, 
+/** The route's `resource_metadata` (`challengeMetadata`), for a token caller's challenge. */
+resourceMetadata) {
     if (scope.kind !== "subject" && scope.kind !== "token")
         return;
     if (access === "any")
@@ -105,11 +120,20 @@ export function requireScopes(scope, access) {
             details: { scopes: [] },
         });
     const held = scope.scopes;
-    if (!access.some((name) => held.has(name)))
-        fail(403, `Scope ${access.join(" or ")} required`, {
-            code: "scope_required",
-            details: { scopes: access },
-        });
+    if (!access.some((name) => held.has(name))) {
+        // Any one of the route's scopes reaches it, but OAuth's list is of scopes held together:
+        // the challenge names the first a token can carry, or none when no token reaches the route.
+        const askable = access.find((name) => TOKEN_SCOPES.includes(name));
+        fail(403, `Scope ${access.join(" or ")} required`, { code: "scope_required", details: { scopes: access } }, scope.kind === "token" && askable
+            ? {
+                "www-authenticate": bearerChallenge({
+                    error: "insufficient_scope",
+                    scope: askable,
+                    resourceMetadata,
+                }),
+            }
+            : {});
+    }
 }
 export function accessOf(scope) {
     switch (scope.kind) {

package/dist/tenant/commands.js

@@ -10,9 +10,10 @@
  * (every accepted one writes a new checkpoint segment), except that a workflow's `approve` and
  * `respond` name `<type>:<turnId>:<interactionId>`: a flow resumes in the same segment.
  *
- * Cancel commits `cancelled` first; the engine host sees it before its next effect and before
- * settlement on any Worker. It then aborts an advance running on this process
- * (`ctx.abortLocal`); reaching an advance on another process is the control stream's job.
+ * Cancel commits `cancelled` first, with a `session.cancel` signal on the control bus in the
+ * same transaction; the engine host sees it before its next effect and before settlement on
+ * any Worker. It then aborts an advance running on this process (`ctx.abortLocal`); every
+ * other process aborts its own on the signal (`control.ts`).
  */
 import { randomUUID } from "node:crypto";
 import { createDurableCheckpoint, createFlowCheckpoint, resumeFlowCheckpoint, } from "@nylorun/harness/run";
@@ -24,7 +25,6 @@ import { fail } from "./http.js";
 import { accessOf } from "./auth.js";
 import { checkSandboxTurn } from "./sandboxes.js";
 import { rebaseSessionState, turnManifestOf, variantStore } from "./session.js";
-import { signalSessionCancel } from "./streams.js";
 import { slimModelEffects } from "./slim.js";
 import { resolveMessageParts } from "../artifacts/parts.js";
 /** A command's identity for idempotency: everything but the request id. */
@@ -83,8 +83,12 @@ export async function command(ctx, id, input, scope) {
                 reason: command.reason,
             });
             await slimModelEffects(t, id, cancelledTurnId);
-            // The process running the advance aborts it on `session.cancel` (tenant/control).
-            t.afterCommit(() => signalSessionCancel(ctx, id, cancelledTurnId));
+            // The process running the advance aborts it on this signal (control.ts), sent at commit.
+            await t.signal({
+                type: "session.cancel",
+                sessionId: id,
+                ...(cancelledTurnId !== null ? { turnId: cancelledTurnId } : {}),
+            });
             s.activeTurnId = null;
             if (cancelledTurnId !== null)
                 s.lastTurnId = cancelledTurnId;

package/dist/tenant/context.d.ts

@@ -201,6 +201,10 @@ export interface TenantContext {
     readonly work: WorkState;
     /** Live delivery over Durable Streams: one `SessionStream` per observed session, and the streams wiring. */
     readonly sessionStreams: SessionStreams;
+    /** This process's follower of the control bus (`control.ts`), once wired. */
+    control?: {
+        close(): Promise<void>;
+    };
     /** The Tenant's signing keys: capability links, run and host tokens. */
     readonly signingKeys: SigningKeys;
     /** The Worker id this process writes as session `owner` (§10.6). */

package/dist/tenant/control.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The control bus of an open Tenant (blueprint D21, D48): the signals one process sends the
+ * others with the Tenant open, on Postgres (`Tx.signal`, `SessionStore.followSignals`). They
+ * never go through S2, which only serves API listeners.
+ *
+ * - `session.cancel` is written by the cancel's own transaction (`commands.ts`): every process
+ *   aborts the cancelled turn's advance if it runs there (`ctx.abortLocal`).
+ * - `sessions.reset` is written by the reset's transaction (`reset.ts`): every process moves
+ *   its session streams to the new basin generation and ends those of deleted sessions
+ *   (`checkSessionStreams`).
+ *
+ * A lost signal costs latency, never correctness: the advance checks the Session Store before
+ * every effect, and the session streams are checked periodically (`streams.ts`).
+ */
+import type { TenantContext } from "./context.js";
+export interface WireControlOptions {
+    /** How often the follower reads recent signals back (`FollowSignalsOptions.pollMs`). */
+    pollMs?: number;
+}
+/**
+ * Follows the control bus for this process and keeps the follower on `ctx.control`. Call it
+ * once, after `ctx` is built; signals committed from its return on reach this process.
+ */
+export declare function wireControl(ctx: TenantContext, options?: WireControlOptions): Promise<void>;
+/** Close: stops following the control bus. */
+export declare function closeControl(ctx: TenantContext): Promise<void>;

package/dist/tenant/control.js

@@ -0,0 +1,35 @@
+import { checkSessionStreams } from "./session-streams.js";
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Follows the control bus for this process and keeps the follower on `ctx.control`. Call it
+ * once, after `ctx` is built; signals committed from its return on reach this process.
+ */
+export async function wireControl(ctx, options = {}) {
+    if (ctx.control)
+        throw new Error("The control bus is already wired");
+    let closed = false;
+    // Nothing is reported once closed: the Tenant (and its log directory) may be gone.
+    const report = (what) => (error) => {
+        if (!closed)
+            ctx.config.logger.warn(what, { message: messageOf(error) });
+    };
+    const follower = await ctx.store.followSignals((signal) => {
+        if (signal.type === "session.cancel")
+            ctx.abortLocal(signal.sessionId, signal.turnId);
+        else
+            void checkSessionStreams(ctx).catch(report("session stream check failed"));
+    }, {
+        ...(options.pollMs !== undefined ? { pollMs: options.pollMs } : {}),
+        onError: report("control bus unavailable; retrying"),
+    });
+    ctx.control = {
+        async close() {
+            closed = true;
+            await follower.close();
+        },
+    };
+}
+/** Close: stops following the control bus. */
+export async function closeControl(ctx) {
+    await ctx.control?.close();
+}

package/dist/tenant/ephemeral.js

@@ -145,6 +145,7 @@ export async function startEphemeralRuntime(options) {
             config: hostConfig,
             logger,
             coreVersion: coreVersion(),
+            ...(issuers ? { resourceServer: { issuers } } : {}),
         });
         // Opens the Tenant: creates it in the database first when it holds none.
         await host.listen();

package/dist/tenant/http.d.ts

@@ -1,10 +1,12 @@
 /**
  * The Tenant's typed rejections: what a route or the code it calls throws for the client to
- * see (`api/http/respond.ts` answers it), and the opaque 404 for unknown credentials (D5).
+ * see (`api/http/respond.ts` answers it), and the opaque 404 (D5) for what must not be told
+ * apart from nothing: a capability link the Runtime did not sign, a Tenant that is not this
+ * Host's. Credentials are `401` with a challenge since protocol 9 (`resource-server.ts`).
  *
  * Later waves: stable; the streams seam (Wave 2 / Y) keeps using these helpers.
  */
-/** D5 opaque failure for unknown/rejected credentials on Tenant routes. */
+/** D5's opaque failure: a 404 that says nothing of why. */
 export declare const OPAQUE_NOT_FOUND: {
     status: "rejected";
     code: "not_found";

package/dist/tenant/http.js

@@ -1,10 +1,12 @@
 /**
  * The Tenant's typed rejections: what a route or the code it calls throws for the client to
- * see (`api/http/respond.ts` answers it), and the opaque 404 for unknown credentials (D5).
+ * see (`api/http/respond.ts` answers it), and the opaque 404 (D5) for what must not be told
+ * apart from nothing: a capability link the Runtime did not sign, a Tenant that is not this
+ * Host's. Credentials are `401` with a challenge since protocol 9 (`resource-server.ts`).
  *
  * Later waves: stable; the streams seam (Wave 2 / Y) keeps using these helpers.
  */
-/** D5 opaque failure for unknown/rejected credentials on Tenant routes. */
+/** D5's opaque failure: a 404 that says nothing of why. */
 export const OPAQUE_NOT_FOUND = {
     status: "rejected",
     code: "not_found",

package/dist/tenant/identity-file.d.ts

@@ -2,20 +2,22 @@
  * The identity file (Host feature `trusted-issuers`, F9 I2): the YAML file
  * `NYLORUN_IDENTITY_FILE` names, listing the issuers whose JWTs the Tenant API accepts as
  * bearers. Read once at boot (`host/main.ts`); a change takes a restart. A malformed file stops
- * the boot with a message naming the issuer and the field.
+ * the boot with a message naming the issuer and the field. A key the file does not define is
+ * ignored with a warning (`maxLifetime`, gone in protocol 9, among them), so an older file
+ * still boots.
  *
  * ```yaml
  * issuers:
  *   - name: keycloak
  *     issuer: https://sso.acme.dev/realms/eng
- *     audience: nylorun
+ *     audience: https://agents.acme.dev
  *     jwks: https://sso.acme.dev/realms/eng/protocol/openid-connect/certs  # or keys: [<PEM>]
- *     subject: "u:{sub}"                         # scalar claims only
- *     scopes: { claim: nylorun_scopes }          # or { fixed: [sessions:own, agents:read] }
- *     allowedScopes: [agents:read, sessions:own, sandboxes:write, studio]
- *     agents: [support]                          # optional allowlist; absent means all
- *     sandboxes: ["{org_id}/*"]                  # optional grants; absent reaches none
- *     maxLifetime: 15m
+ *     # Optional, with their defaults:
+ *     subject: "{sub}"                           # scalar claims only
+ *     scopes: { claim: scope }                   # or { fixed: [sessions:own, agents:read] }
+ *     allowedScopes: [agents:read, sessions:own, sandboxes:write]   # add studio to grant it
+ *     agents: [support]                          # absent reaches every agent
+ *     sandboxes: ["{org_id}/*"]                  # absent reaches no sandbox
  * ```
  */
 import { type KeyObject } from "node:crypto";
@@ -41,7 +43,7 @@ export interface TrustedIssuerConfig {
     readonly jwks?: string;
     /** Its public keys, given in the file (PEM); or `jwks`. */
     readonly keys?: readonly IssuerKey[];
-    /** The subject template, such as `u:{sub}`: at least one claim reference. */
+    /** The subject template, such as `{sub}` (the default): at least one claim reference. */
     readonly subject: string;
     /** Where its tokens' scopes come from: a claim, or a fixed list. */
     readonly scopes: {
@@ -55,8 +57,6 @@ export interface TrustedIssuerConfig {
     readonly agents?: readonly string[];
     /** Sandbox grant templates, such as `{org_id}/*`; absent reaches no sandbox. */
     readonly sandboxes?: readonly string[];
-    /** The longest `exp - iat` it may sign, in seconds. */
-    readonly maxLifetimeSeconds: number;
 }
 /** A malformed identity file: the message names the issuer and the field. */
 export declare class IdentityFileError extends Error {
@@ -68,8 +68,12 @@ export declare function claimReferences(template: string): string[];
 export declare function renderTemplate(template: string, value: (claim: string) => string | undefined): string | undefined;
 /** A PEM public key an issuer may sign with, and its algorithm; throws a message otherwise. */
 export declare function issuerKey(key: KeyObject, kid?: string): IssuerKey;
+export interface ParseIdentityFileOptions {
+    /** Told of every key the file has but does not define, which is ignored. */
+    readonly warn?: (message: string) => void;
+}
 /**
  * The issuers of an identity file's text. Throws `IdentityFileError` naming the file, the issuer
  * and the field when the file is malformed.
  */
-export declare function parseIdentityFile(text: string, source?: string): TrustedIssuerConfig[];
+export declare function parseIdentityFile(text: string, source?: string, options?: ParseIdentityFileOptions): TrustedIssuerConfig[];

package/dist/tenant/identity-file.js

@@ -2,31 +2,34 @@
  * The identity file (Host feature `trusted-issuers`, F9 I2): the YAML file
  * `NYLORUN_IDENTITY_FILE` names, listing the issuers whose JWTs the Tenant API accepts as
  * bearers. Read once at boot (`host/main.ts`); a change takes a restart. A malformed file stops
- * the boot with a message naming the issuer and the field.
+ * the boot with a message naming the issuer and the field. A key the file does not define is
+ * ignored with a warning (`maxLifetime`, gone in protocol 9, among them), so an older file
+ * still boots.
  *
  * ```yaml
  * issuers:
  *   - name: keycloak
  *     issuer: https://sso.acme.dev/realms/eng
- *     audience: nylorun
+ *     audience: https://agents.acme.dev
  *     jwks: https://sso.acme.dev/realms/eng/protocol/openid-connect/certs  # or keys: [<PEM>]
- *     subject: "u:{sub}"                         # scalar claims only
- *     scopes: { claim: nylorun_scopes }          # or { fixed: [sessions:own, agents:read] }
- *     allowedScopes: [agents:read, sessions:own, sandboxes:write, studio]
- *     agents: [support]                          # optional allowlist; absent means all
- *     sandboxes: ["{org_id}/*"]                  # optional grants; absent reaches none
- *     maxLifetime: 15m
+ *     # Optional, with their defaults:
+ *     subject: "{sub}"                           # scalar claims only
+ *     scopes: { claim: scope }                   # or { fixed: [sessions:own, agents:read] }
+ *     allowedScopes: [agents:read, sessions:own, sandboxes:write]   # add studio to grant it
+ *     agents: [support]                          # absent reaches every agent
+ *     sandboxes: ["{org_id}/*"]                  # absent reaches no sandbox
  * ```
  */
 import { createPublicKey } from "node:crypto";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
-import { ISSUER_SCOPES, isSandboxGrant, TOKEN_SANDBOX_GRANTS_MAX, } from "@nylorun/core/contracts";
-import { parseSandboxDuration } from "@nylorun/core/define";
+import { ISSUER_SCOPES, isSandboxGrant, TOKEN_SANDBOX_GRANTS_MAX, TOKEN_SCOPES, } from "@nylorun/core/contracts";
 /** The JWT algorithms an issuer may sign with. */
 export const ISSUER_ALGORITHMS = ["RS256", "ES256", "EdDSA"];
-/** The longest `maxLifetime` an issuer may set. */
-const MAX_LIFETIME_SECONDS = 24 * 60 * 60;
+/** An entry's defaults: the `sub` claim, the RFC 9068 `scope` claim, every token scope but `studio`. */
+const DEFAULT_SUBJECT = "{sub}";
+const DEFAULT_SCOPES = { claim: "scope" };
+const DEFAULT_ALLOWED_SCOPES = TOKEN_SCOPES;
 /** At most this many static `keys` per issuer. */
 const MAX_STATIC_KEYS = 16;
 const ISSUER_NAME = /^[a-z][a-z0-9-]{0,31}$/;
@@ -105,12 +108,16 @@ const IssuerEntrySchema = z
     }, "must be an http(s) URL without credentials")
         .optional(),
     keys: z.array(z.string().min(1)).min(1).max(MAX_STATIC_KEYS).optional(),
-    subject: template("subject").refine((value) => claimReferences(value).length > 0, "must reference a claim, as u:{sub}: without one every token is the same person"),
-    scopes: z.union([
+    subject: template("subject")
+        .refine((value) => claimReferences(value).length > 0, "must reference a claim, as {sub}: without one every token is the same person")
+        .default(DEFAULT_SUBJECT),
+    scopes: z
+        .union([
         z.object({ claim: z.string().min(1) }).strict(),
         z.object({ fixed: z.array(IssuerScopeSchema) }).strict(),
-    ], { error: "must be { claim: <name> } or { fixed: [<scope>, ...] }" }),
-    allowedScopes: z.array(IssuerScopeSchema).min(1),
+    ], { error: "must be { claim: <name> } or { fixed: [<scope>, ...] }" })
+        .default(DEFAULT_SCOPES),
+    allowedScopes: z.array(IssuerScopeSchema).min(1).default([...DEFAULT_ALLOWED_SCOPES]),
     agents: z.array(z.string().min(1)).optional(),
     sandboxes: z
         .array(template("a sandbox grant").refine(
@@ -118,17 +125,17 @@ const IssuerEntrySchema = z
     (value) => isSandboxGrant(renderTemplate(value, () => "x")), "must render to a sandbox id or a prefix ending in /*, as {org_id}/*"))
         .max(TOKEN_SANDBOX_GRANTS_MAX)
         .optional(),
-    maxLifetime: z
-        .string()
-        .refine((value) => {
-        const ms = parseSandboxDuration(value);
-        return ms !== undefined && ms >= 1000 && ms <= MAX_LIFETIME_SECONDS * 1000;
-    }, "must be a duration from 1s to 24h, as 15m"),
-})
-    .strict();
-const IdentityFileSchema = z
-    .object({ issuers: z.array(z.unknown()) })
-    .strict();
+});
+const IdentityFileSchema = z.object({ issuers: z.array(z.unknown()) });
+/** The keys an entry and the file define; any other is ignored with a warning. */
+const ENTRY_KEYS = new Set(Object.keys(IssuerEntrySchema.shape));
+const FILE_KEYS = new Set(Object.keys(IdentityFileSchema.shape));
+/** The keys of `value`, an object, that `known` does not define. */
+function unknownKeys(value, known) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? Object.keys(value).filter((key) => !known.has(key))
+        : [];
+}
 function issueText(issues) {
     return issues
         .map((issue) => {
@@ -141,7 +148,11 @@ function issueText(issues) {
  * The issuers of an identity file's text. Throws `IdentityFileError` naming the file, the issuer
  * and the field when the file is malformed.
  */
-export function parseIdentityFile(text, source = "identity file") {
+export function parseIdentityFile(text, source = "identity file", options = {}) {
+    const ignored = (where, keys) => {
+        if (keys.length > 0)
+            options.warn?.(`${source}: ${where}: ignored ${keys.map((key) => `\`${key}\``).join(", ")}, which the identity file does not define`);
+    };
     const fail = (message) => {
         throw new IdentityFileError(`${source}: ${message}`);
     };
@@ -155,6 +166,7 @@ export function parseIdentityFile(text, source = "identity file") {
     const file = IdentityFileSchema.safeParse(raw ?? {});
     if (!file.success)
         return fail(issueText(file.error.issues));
+    ignored("the file", unknownKeys(raw, FILE_KEYS));
     const issuers = [];
     file.data.issuers.forEach((entry, index) => {
         const named = entry && typeof entry === "object" && typeof entry.name === "string"
@@ -164,6 +176,7 @@ export function parseIdentityFile(text, source = "identity file") {
         const parsed = IssuerEntrySchema.safeParse(entry);
         if (!parsed.success)
             return fail(`${where}: ${issueText(parsed.error.issues)}`);
+        ignored(where, unknownKeys(entry, ENTRY_KEYS));
         const value = parsed.data;
         if ((value.jwks === undefined) === (value.keys === undefined))
             return fail(`${where}: jwks or keys: give exactly one of them`);
@@ -195,7 +208,6 @@ export function parseIdentityFile(text, source = "identity file") {
             allowedScopes: [...new Set(value.allowedScopes)],
             ...(value.agents ? { agents: [...new Set(value.agents)] } : {}),
             ...(value.sandboxes ? { sandboxes: value.sandboxes } : {}),
-            maxLifetimeSeconds: Math.floor(parseSandboxDuration(value.maxLifetime) / 1000),
         });
     });
     return issuers;

package/dist/tenant/issuers.d.ts

@@ -26,7 +26,7 @@ export type IssuerVerdict = {
 /** 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. */
+    /** Checks `raw`'s header and signature, `iss`, `aud`, `exp` and `iat`. */
     verify(raw: string): Promise<IssuerVerdict>;
 }
 /** The Host's trusted issuers (`TenantConfig.issuers`), built once from the identity file. */
@@ -43,6 +43,7 @@ export type IssuerTokenScope = Extract<AuthScope, {
 /**
  * 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.
+ * the Runtime cannot fetch now, and `401 credential_invalid` for everything else. Each carries
+ * a `Bearer` challenge naming `resourceMetadata`, the route's protected resource metadata.
  */
-export declare function verifyIssuerToken(ctx: TenantContext, issuer: TrustedIssuer, raw: string): Promise<IssuerTokenScope>;
+export declare function verifyIssuerToken(ctx: TenantContext, issuer: TrustedIssuer, raw: string, resourceMetadata?: string): Promise<IssuerTokenScope>;

package/dist/tenant/issuers.js

@@ -11,19 +11,21 @@
  *   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;
+ * - `iss` and `aud` as configured, and `exp` present, with the 30 s clock tolerance of every
+ *   Runtime token. How long a token lives is the issuer's to decide (protocol 9 dropped
+ *   `maxLifetime`); an `iat` in the future is still refused;
  * - 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.
+ * expired token is `401 token_expired`; every other refusal is `401 credential_invalid`
+ * (`resource-server.ts`), 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 { HttpError } from "./http.js";
 import { CLOCK_TOLERANCE_SECONDS, looksLikeToken } from "./jwt.js";
+import { bearerChallenge, failCredential } from "./resource-server.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;
@@ -185,14 +187,12 @@ function trustedIssuer(config, options) {
                         issuer: config.issuer,
                         audience: config.audience,
                         clockTolerance: CLOCK_TOLERANCE_SECONDS,
-                        requiredClaims: ["iat", "exp"],
+                        requiredClaims: ["exp"],
                         currentDate: new Date(options.now()),
                     });
                     const now = Math.floor(options.now() / 1000);
-                    if (payload.iat > now + CLOCK_TOLERANCE_SECONDS)
+                    if (payload.iat !== undefined && 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) {
@@ -260,25 +260,31 @@ function scopesOf(config, payload) {
 /**
  * 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.
+ * the Runtime cannot fetch now, and `401 credential_invalid` for everything else. Each carries
+ * a `Bearer` challenge naming `resourceMetadata`, the route's protected resource metadata.
  */
-export async function verifyIssuerToken(ctx, issuer, raw) {
+export async function verifyIssuerToken(ctx, issuer, raw, resourceMetadata) {
     const { config } = issuer;
     const rejected = (reason) => {
         ctx.config.logger.warn("credential rejected", { reason, issuer: config.name });
-        return failOpaque();
+        return failCredential("invalid", resourceMetadata);
     };
     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"' });
+            throw new HttpError(401, "The token has expired", { code: "token_expired" }, {
+                "www-authenticate": bearerChallenge({
+                    error: "invalid_token",
+                    description: "The access token expired",
+                    resourceMetadata,
+                }),
+            });
         }
         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",
-            });
+            // The token may be fine: no error code, so a client retries rather than signs in again.
+            throw new HttpError(401, `The keys of issuer ${config.name} cannot be fetched now; try again later`, { code: "issuer_unavailable" }, { "www-authenticate": bearerChallenge({ resourceMetadata }) });
         }
         return rejected(verdict.reason);
     }

package/dist/tenant/reset.d.ts

@@ -15,7 +15,7 @@ export interface ResetTenantContext {
 /**
  * Reset Tenant durable state for `scope` (A17).
  * Caller must have already drained (`activeWork`). Deletes store state in one
- * transaction (`Tx.reset`), then does the filesystem rename+delete for sandboxes /
- * log as needed. The host vault (model credentials), principals and settings stay.
+ * transaction (`Tx.reset`), which also signals a sessions reset to every process on the
+ * control bus, then does the filesystem rename+delete for sandboxes / log as needed. The host vault (model credentials), principals and settings stay.
  */
 export declare function resetTenant(ctx: ResetTenantContext, scope: ResetScope): Promise<void>;

package/dist/tenant/reset.js

@@ -33,8 +33,8 @@ function replaceDirectory(dir) {
 /**
  * Reset Tenant durable state for `scope` (A17).
  * Caller must have already drained (`activeWork`). Deletes store state in one
- * transaction (`Tx.reset`), then does the filesystem rename+delete for sandboxes /
- * log as needed. The host vault (model credentials), principals and settings stay.
+ * transaction (`Tx.reset`), which also signals a sessions reset to every process on the
+ * control bus, then does the filesystem rename+delete for sandboxes / log as needed. The host vault (model credentials), principals and settings stay.
  */
 export async function resetTenant(ctx, scope) {
     const clearSessions = scope === "sessions" || scope === "all";
@@ -53,6 +53,12 @@ export async function resetTenant(ctx, scope) {
         // Folders' content-addressed files: those no remaining folder names (F8.2).
         const content = clearSessions ? await t.artifactContentShas(scoped) : [];
         await t.reset(scope);
+        // Every process moves its session streams to the new basin generation (control.ts).
+        if (clearSessions)
+            await t.signal({
+                type: "sessions.reset",
+                generation: (await t.basinGenerations()).current,
+            });
         const kept = await t.referencedArtifactContent(content);
         for (const sha of content)
             if (!kept.has(sha))