@nylorun/runtime 0.13.0-beta → 0.14.0-beta

package/dist/tenant/effects.js

@@ -3,34 +3,49 @@ import { countActiveFlowWork, deriveAgentEffectSessionId, isFlowEffect, isFlowTo
 import { mayDispatchMore } from "../core/limits.js";
 import { canonical } from "../store/canonical.js";
 import { isOwnershipLost } from "../store/ownership.js";
-import { newStreamIncarnation } from "../streams/types.js";
 import { piModel } from "../model/pi-model.js";
 import { scrub } from "../redact.js";
 import { serversOf } from "../mcp/pool.js";
 import { sandboxCapabilityOf } from "../sandbox/manager.js";
-import { owningSandboxSessionId, sandboxSpecOf } from "../sandbox/share.js";
+import { owningSandboxSessionId, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
+import { withSandboxCapability } from "../sandbox/session-sandbox.js";
 import { loadSession, ownedSession, sandboxLookup, sessionOf, } from "./context.js";
 import { fail } from "./http.js";
 import { actionTarget, linkedAgentOutput, manifestFor, mcpToolOf, pinnedTool, turnManifestOf, } from "./session.js";
 import { command } from "./commands.js";
-import { assistantMessage, toolCompleted, toolIds } from "./transcript.js";
+import { offerAction } from "./delivery.js";
+import { assistantMessage, contextCompacted, modelFailed, toolCompleted, toolIds, } from "./transcript.js";
+import { classifyThrown } from "../model/classify.js";
 import { abortKind } from "./worker.js";
-export function invokeModel(ctx, request, signal, model) {
-    if (model)
-        return model(request, signal);
-    if (!ctx.useVaultModel)
-        return ctx.modelProvider(request, signal);
-    const adapter = piModel({
-        root: ctx.config.paths.home,
-        readHostModel: () => ctx.vault.readHostModel(),
-        writeHostCredential: (credential) => ctx.vault.updateHostCredential(credential),
-    });
-    return adapter(request.input, {
-        request: request.context.request,
-        invocationId: String(request.context.invocationId),
-        signal,
-        reportPreparedCall() { },
-    });
+/**
+ * Call the model for one effect. A provider failure comes back as a failure outcome
+ * (Model Calls §6), whichever provider serves the call; only an abort throws, and the
+ * advance decides what the abort means.
+ */
+export async function invokeModel(ctx, request, signal, model) {
+    try {
+        if (model)
+            return await model(request, signal);
+        if (!ctx.useVaultModel)
+            return await ctx.modelProvider(request, signal);
+        const adapter = piModel({
+            root: ctx.config.paths.home,
+            readHostModel: () => ctx.vault.readHostModel(),
+            writeHostCredential: (credential) => ctx.vault.updateHostCredential(credential),
+            ...(ctx.config.modelCall ? { settings: ctx.config.modelCall } : {}),
+        });
+        return await adapter(request.input, {
+            request: request.context.request,
+            invocationId: String(request.context.invocationId),
+            signal,
+            reportPreparedCall() { },
+        });
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        return classifyThrown(error);
+    }
 }
 /**
  * The outcome of a flow `agent` effect once the linked turn it started ended, or undefined
@@ -159,8 +174,6 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             context: request.context,
             status: "pending",
             generation: 0,
-            claimId: null,
-            leaseExpiresAt: null,
             ...(request.agent ? { agent: request.agent } : {}),
         };
         const action = request.kind === "hook"
@@ -189,7 +202,7 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             ...(action.kind === "tool" ? toolIds(request.context) : {}),
             input: action.input,
         });
-        t.signalWork();
+        await offerAction(t, ctx, action);
         return resolved({ status: "pending" });
     });
     if (journaled.kind === "resolved")
@@ -219,11 +232,23 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             effect.status = "completed";
             effect.outcome = { value };
             await t.put("effects", request.effectId, effect);
-            const transcript = invoke === "model"
-                ? assistantMessage(request, value)
-                : toolCompleted(request, value);
-            if (transcript)
-                await t.event(s.id, request.turnId, invoke === "model" ? "message.assistant" : "tool.completed", transcript);
+            const failed = invoke === "model" ? modelFailed(request, value) : undefined;
+            // A summary call is never an assistant message; the last one publishes context.compacted.
+            const summarizing = invoke === "model" && Boolean(request.context.compaction);
+            const compacted = summarizing && !failed ? contextCompacted(request, value) : undefined;
+            const transcript = failed || summarizing
+                ? undefined
+                : invoke === "model"
+                    ? assistantMessage(request, value)
+                    : toolCompleted(request, value);
+            if (failed)
+                await t.event(s.id, request.turnId, "model.failed", failed);
+            if (compacted)
+                await t.event(s.id, request.turnId, "context.compacted", compacted);
+            if (transcript && invoke === "model")
+                await t.event(s.id, request.turnId, "message.assistant", transcript);
+            else if (transcript)
+                await t.event(s.id, request.turnId, "tool.completed", transcript);
             return { status: "completed", outcome: effect.outcome };
         });
     }
@@ -312,8 +337,6 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                     context: request.context,
                     status: "pending",
                     generation: 0,
-                    claimId: null,
-                    leaseExpiresAt: null,
                     kind: request.kind,
                     path: request.path,
                     key: request.key,
@@ -329,8 +352,6 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                     context: request.context,
                     status: "pending",
                     generation: 0,
-                    claimId: null,
-                    leaseExpiresAt: null,
                     kind: "tool",
                     path: request.path,
                     key: request.key,
@@ -353,7 +374,7 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                 key: action.key,
                 input: action.input,
             });
-            t.signalWork();
+            await offerAction(t, ctx, action);
             return resolved({ status: "pending" });
         }
         return { kind: "agent", workflow };
@@ -388,15 +409,18 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
         if (exists)
             return;
         const definition = await leafDefinition(t, workflow, body, request);
-        const sandboxOwnerId = sandboxSpecOf(workflow.manifest) || workflow.sandboxOwnerId
-            ? owningSandboxSessionId(workflow, await sandboxLookup(t, workflow.sandboxOwnerId))
+        const lookup = await sandboxLookup(t, workflow.sandboxOwnerId);
+        const sandboxOwnerId = sessionSandboxSpec(workflow) || workflow.sandboxOwnerId
+            ? owningSandboxSessionId(workflow, lookup)
             : undefined;
+        // A sandbox chosen when the tree was opened reaches every agent in it, with its tools.
+        const inherited = inheritedSandbox(sandboxOwnerId === undefined ? undefined : lookup(sandboxOwnerId) ?? workflow, definition);
         const created = {
             id: agentSessionId,
             agentId: body.agentId,
             ownerUserId: workflow.ownerUserId,
-            manifest: definition.manifest,
-            manifestHash: definition.manifestHash,
+            manifest: inherited?.manifest ?? definition.manifest,
+            manifestHash: inherited?.manifestHash ?? definition.manifestHash,
             implementationVersion: definition.implementationVersion,
             status: "idle",
             activeTurnId: null,
@@ -410,7 +434,9 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
             credentialSelections: workflow.credentialSelections,
             pluginRoots: definition.pluginRoots ?? {},
             ...(sandboxOwnerId ? { sandboxOwnerId } : {}),
-            streamIncarnation: newStreamIncarnation(),
+            ...(inherited
+                ? { sandbox: inherited.spec, sandboxSource: "shared" }
+                : {}),
         };
         await t.put("sessions", agentSessionId, created);
     });
@@ -534,6 +560,21 @@ async function callMcpTool(ctx, request) {
         pluginRoots: s.pluginRoots ?? {},
     });
 }
+/**
+ * The sandbox a linked session inherits from its tree's owner when that sandbox was chosen at
+ * open (pinned on the owner). A definition that declares its own sandbox keeps it, as before.
+ */
+function inheritedSandbox(owner, definition) {
+    const spec = owner?.sandbox;
+    if (!spec || sandboxSpecOf(definition.manifest))
+        return undefined;
+    if (isWorkflowManifest(definition.manifest))
+        return { spec };
+    const sandboxed = withSandboxCapability(definition.manifest, spec);
+    if (!sandboxed.ok)
+        throw new Error(sandboxed.message);
+    return { spec, manifest: sandboxed.manifest, manifestHash: sandboxed.manifestHash };
+}
 async function callSandboxTool(ctx, request, signal) {
     const { s, ownerId } = await ctx.store.tx(async (t) => {
         const s = await sessionOf(t, request.sessionId);

package/dist/tenant/endpoints.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Action endpoints (design: Action endpoints §4.2): where the Runtime delivers each agent's
+ * Actions, registered with the application key.
+ */
+import { type Endpoint, type PutEndpointsRequest } from "@nylorun/core/contracts";
+import type { EndpointRow } from "../store/types.js";
+import type { TenantContext } from "./context.js";
+/** An endpoint as the Tenant API answers it. */
+export declare function endpointView(row: EndpointRow): Endpoint;
+/** `GET /v1/endpoints`. */
+export declare function listEndpoints(ctx: TenantContext): Promise<{
+    endpoints: {
+        agentId: string;
+        url: string;
+        implementationVersion: string;
+        manifestHash?: string | undefined;
+        timeoutMs: number;
+        maxConcurrent: number;
+        health: {
+            lastDeliveryAt?: string | undefined;
+            lastSuccessAt?: string | undefined;
+            lastError?: {
+                code: string;
+                message: string;
+            } | undefined;
+            consecutiveFailures: number;
+            served?: {
+                implementationVersion: string;
+                manifestHash?: string | undefined;
+            } | undefined;
+        };
+        updatedAt: string;
+    }[];
+}>;
+/**
+ * `PUT /v1/endpoints`: upsert the batch in one transaction, then send the Actions already
+ * waiting for these agents. Answers every registered endpoint of the batch.
+ */
+export declare function putEndpoints(ctx: TenantContext, principalId: string, body: PutEndpointsRequest): Promise<{
+    endpoints: {
+        agentId: string;
+        url: string;
+        implementationVersion: string;
+        manifestHash?: string | undefined;
+        timeoutMs: number;
+        maxConcurrent: number;
+        health: {
+            lastDeliveryAt?: string | undefined;
+            lastSuccessAt?: string | undefined;
+            lastError?: {
+                code: string;
+                message: string;
+            } | undefined;
+            consecutiveFailures: number;
+            served?: {
+                implementationVersion: string;
+                manifestHash?: string | undefined;
+            } | undefined;
+        };
+        updatedAt: string;
+    }[];
+}>;
+/** `DELETE /v1/endpoints/:agentId`. The agent's pending Actions wait for a new endpoint. */
+export declare function deleteEndpoint(ctx: TenantContext, agentId: string): Promise<{
+    agentId: string;
+    deleted: true;
+}>;

package/dist/tenant/endpoints.js

@@ -0,0 +1,90 @@
+/**
+ * Action endpoints (design: Action endpoints §4.2): where the Runtime delivers each agent's
+ * Actions, registered with the application key.
+ */
+import { ENDPOINT_MAX_CONCURRENT_DEFAULT, ENDPOINT_TIMEOUT_DEFAULT_MS, } from "@nylorun/core/contracts";
+import { fail } from "./http.js";
+/** An endpoint as the Tenant API answers it. */
+export function endpointView(row) {
+    const served = row.servedImplementationVersion === undefined
+        ? undefined
+        : {
+            implementationVersion: row.servedImplementationVersion,
+            ...(row.servedManifestHash === undefined
+                ? {}
+                : { manifestHash: row.servedManifestHash }),
+        };
+    return {
+        agentId: row.agentId,
+        url: row.url,
+        implementationVersion: row.implementationVersion,
+        ...(row.manifestHash === undefined ? {} : { manifestHash: row.manifestHash }),
+        timeoutMs: row.timeoutMs,
+        maxConcurrent: row.maxConcurrent,
+        health: {
+            ...(row.lastDeliveryAt === undefined ? {} : { lastDeliveryAt: row.lastDeliveryAt }),
+            ...(row.lastSuccessAt === undefined ? {} : { lastSuccessAt: row.lastSuccessAt }),
+            ...(row.lastErrorCode === undefined
+                ? {}
+                : {
+                    lastError: {
+                        code: row.lastErrorCode,
+                        message: row.lastErrorMessage ?? "",
+                    },
+                }),
+            consecutiveFailures: row.consecutiveFailures,
+            ...(served ? { served } : {}),
+        },
+        updatedAt: row.updatedAt,
+    };
+}
+/** `GET /v1/endpoints`. */
+export async function listEndpoints(ctx) {
+    const rows = await ctx.store.tx((t) => t.listEndpoints());
+    return { endpoints: rows.map(endpointView) };
+}
+/**
+ * `PUT /v1/endpoints`: upsert the batch in one transaction, then send the Actions already
+ * waiting for these agents. Answers every registered endpoint of the batch.
+ */
+export async function putEndpoints(ctx, principalId, body) {
+    const updatedAt = new Date().toISOString();
+    const rows = await ctx.store.tx(async (t) => {
+        const saved = [];
+        for (const endpoint of body.endpoints) {
+            await t.putEndpoint({
+                agentId: endpoint.agentId,
+                url: endpoint.url,
+                implementationVersion: endpoint.implementationVersion,
+                ...(endpoint.manifestHash === undefined
+                    ? {}
+                    : { manifestHash: endpoint.manifestHash }),
+                timeoutMs: endpoint.timeoutMs ?? ENDPOINT_TIMEOUT_DEFAULT_MS,
+                maxConcurrent: endpoint.maxConcurrent ?? ENDPOINT_MAX_CONCURRENT_DEFAULT,
+                principalId,
+                updatedAt,
+            });
+            saved.push((await t.getEndpoint(endpoint.agentId)));
+        }
+        return saved;
+    });
+    // Actions already waiting for these agents go to their endpoint now.
+    const waiting = await ctx.store.tx(async (t) => {
+        const actions = [];
+        for (const endpoint of body.endpoints)
+            actions.push(...(await t.pendingActions(endpoint.agentId)));
+        return actions;
+    });
+    for (const action of waiting)
+        await ctx.deliver(action.actionId);
+    return { endpoints: rows.map(endpointView) };
+}
+/** `DELETE /v1/endpoints/:agentId`. The agent's pending Actions wait for a new endpoint. */
+export async function deleteEndpoint(ctx, agentId) {
+    await ctx.store.tx(async (t) => {
+        if (!(await t.getEndpoint(agentId)))
+            fail(404, "Endpoint not found");
+        await t.deleteEndpoint(agentId);
+    });
+    return { agentId, deleted: true };
+}

package/dist/tenant/ephemeral.d.ts

@@ -19,6 +19,10 @@ export interface StartEphemeralRuntimeOptions {
     sandboxBackend?: "auto" | "virtual";
     /** When true, close() leaves hostRoot on disk. */
     retainRoot?: boolean;
+    /** Allow browser requests (an `Origin` with a publishable key). Default off. */
+    browserAccess?: boolean;
+    /** Serve the Admin API on its own loopback listener (`adminUrl`). Default off. */
+    operatorListener?: boolean;
     logger?: Logger;
     /**
      * A Postgres pool: Tenants become schemas in it (`store-pg.ts`) instead of living in memory.
@@ -28,6 +32,8 @@ export interface StartEphemeralRuntimeOptions {
 }
 export interface EphemeralRuntime {
     url: string;
+    /** Where the Admin API answers: `url`, or the operator listener when requested. */
+    adminUrl: string;
     tenantId: string;
     applicationKey: string;
     adminKey: string;

package/dist/tenant/ephemeral.js

@@ -13,7 +13,7 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { createRequire } from "node:module";
 import { newTenantId } from "@nylorun/core/compatibility";
-import { hashToken, mintBearerToken } from "../core/executors.js";
+import { hashToken, mintBearerToken } from "../core/bearer.js";
 import { createHost } from "../host/create-host.js";
 import { createKekFile } from "../vault/kek.js";
 import { MemorySessionStore } from "../store/memory.js";
@@ -95,6 +95,7 @@ function kept(store) {
         tenantId: store.tenantId,
         tx: (fn) => store.tx(fn),
         onCommit: (listener) => store.onCommit(listener),
+        record: () => store.record(),
         health: () => store.health(),
         close: async () => { },
     };
@@ -173,37 +174,65 @@ export async function startEphemeralRuntime(options) {
         logger,
         onDeleted: (tenantId) => streams.deleteTenant(tenantId),
     });
-    await module.start();
-    const tenantId = options.tenantId ?? newTenantId();
-    const applicationKey = options.applicationKey ?? mintBearerToken();
-    const principalId = options.principalId ?? `principal_${randomBytes(8).toString("hex")}`;
-    const credentialHash = hashToken(applicationKey);
-    await module.create({
-        tenantId,
-        name: options.name ?? "ephemeral",
-        principalId,
-        credentialHash,
-        idempotencyKey: `ephemeral-${tenantId}`,
-        ...(options.studioCredentialHash
-            ? { studioCredentialHash: options.studioCredentialHash }
-            : {}),
-    });
-    // KEK for first vault write; openTenantRuntime also creates when hooks allow.
-    const kekPath = tenantPaths(hostRoot, tenantId).kek;
-    if (!existsSync(kekPath))
-        createKekFile(kekPath);
-    const host = createHost({
-        hostRoot,
-        module,
-        config: hostConfig,
-        credentials,
-        logger,
-        coreVersion: coreVersion(),
-    });
-    await host.listen();
+    let host;
+    /** Closes what was opened, in reverse order; `close()` and a failed start share it. */
+    const release = async () => {
+        await host?.close();
+        await module.close();
+        await memory?.close();
+        await streams.close();
+        if (!options.retainRoot)
+            rmSync(hostRoot, { recursive: true, force: true });
+    };
+    let tenantId;
+    let applicationKey;
+    let principalId;
+    try {
+        await module.start();
+        tenantId = options.tenantId ?? newTenantId();
+        applicationKey = options.applicationKey ?? mintBearerToken();
+        principalId =
+            options.principalId ?? `principal_${randomBytes(8).toString("hex")}`;
+        const credentialHash = hashToken(applicationKey);
+        await module.create({
+            tenantId,
+            name: options.name ?? "ephemeral",
+            principalId,
+            credentialHash,
+            idempotencyKey: `ephemeral-${tenantId}`,
+            ...(options.studioCredentialHash
+                ? { studioCredentialHash: options.studioCredentialHash }
+                : {}),
+        });
+        // KEK for first vault write; openTenantRuntime also creates when hooks allow.
+        const kekPath = tenantPaths(hostRoot, tenantId).kek;
+        if (!existsSync(kekPath))
+            createKekFile(kekPath);
+        host = createHost({
+            hostRoot,
+            module,
+            config: hostConfig,
+            credentials,
+            logger,
+            coreVersion: coreVersion(),
+            browserAccess: options.browserAccess === true,
+            ...(options.operatorListener
+                ? { operator: { host: "127.0.0.1", port: 0 } }
+                : {}),
+        });
+        await host.listen();
+    }
+    catch (error) {
+        await release().catch((cleanup) => logger.warn("ephemeral runtime cleanup failed", {
+            message: cleanup instanceof Error ? cleanup.message : String(cleanup),
+        }));
+        throw error;
+    }
+    const started = host;
     let closed = false;
     return {
-        url: host.url,
+        url: started.url,
+        adminUrl: started.adminUrl,
         tenantId,
         applicationKey,
         adminKey,
@@ -213,12 +242,7 @@ export async function startEphemeralRuntime(options) {
             if (closed)
                 return;
             closed = true;
-            await host.close();
-            await module.close();
-            await memory?.close();
-            await streams.close();
-            if (!options.retainRoot)
-                rmSync(hostRoot, { recursive: true, force: true });
+            await release();
         },
     };
 }

package/dist/tenant/http.d.ts

@@ -1,10 +1,9 @@
 /**
- * HTTP plumbing shared by the Tenant route modules: typed rejections, the opaque 404 for
- * unknown credentials (D5), request-body parsing and the client-abort signal.
+ * 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).
  *
  * Later waves: stable; the streams seam (Wave 2 / Y) keeps using these helpers.
  */
-import type { IncomingMessage } from "node:http";
 /** D5 opaque failure for unknown/rejected credentials on Tenant routes. */
 export declare const OPAQUE_NOT_FOUND: {
     status: "rejected";
@@ -19,9 +18,13 @@ export interface Rejection {
 export declare class HttpError extends Error {
     readonly status: number;
     readonly rejection: Rejection;
-    constructor(status: number, message: string, rejection?: Rejection);
+    /** Response headers the rejection carries, such as `retry-after` or `www-authenticate`. */
+    readonly headers: Readonly<Record<string, string>>;
+    constructor(status: number, message: string, rejection?: Rejection, 
+    /** Response headers the rejection carries, such as `retry-after` or `www-authenticate`. */
+    headers?: Readonly<Record<string, string>>);
 }
-export declare const fail: (status: number, message: string, rejection?: Rejection) => never;
+export declare const fail: (status: number, message: string, rejection?: Rejection, headers?: Readonly<Record<string, string>>) => never;
 export declare class OpaqueAuthError extends Error {
     readonly status = 404;
     readonly body: {
@@ -32,7 +35,3 @@ export declare class OpaqueAuthError extends Error {
     constructor();
 }
 export declare const failOpaque: () => never;
-/** AbortSignal tied to the HTTP request being closed by the client. */
-export declare function requestAborted(request: IncomingMessage): AbortSignal;
-/** Read a JSON request body, capped at 1 MiB. */
-export declare function readBody(request: IncomingMessage): Promise<unknown>;

package/dist/tenant/http.js

@@ -1,3 +1,9 @@
+/**
+ * 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).
+ *
+ * Later waves: stable; the streams seam (Wave 2 / Y) keeps using these helpers.
+ */
 /** D5 opaque failure for unknown/rejected credentials on Tenant routes. */
 export const OPAQUE_NOT_FOUND = {
     status: "rejected",
@@ -7,14 +13,18 @@ export const OPAQUE_NOT_FOUND = {
 export class HttpError extends Error {
     status;
     rejection;
-    constructor(status, message, rejection = {}) {
+    headers;
+    constructor(status, message, rejection = {}, 
+    /** Response headers the rejection carries, such as `retry-after` or `www-authenticate`. */
+    headers = {}) {
         super(message);
         this.status = status;
         this.rejection = rejection;
+        this.headers = headers;
     }
 }
-export const fail = (status, message, rejection) => {
-    throw new HttpError(status, message, rejection);
+export const fail = (status, message, rejection, headers) => {
+    throw new HttpError(status, message, rejection, headers);
 };
 export class OpaqueAuthError extends Error {
     status = 404;
@@ -27,27 +37,3 @@ export class OpaqueAuthError extends Error {
 export const failOpaque = () => {
     throw new OpaqueAuthError();
 };
-/** AbortSignal tied to the HTTP request being closed by the client. */
-export function requestAborted(request) {
-    const controller = new AbortController();
-    request.on("close", () => {
-        if (!request.complete)
-            controller.abort();
-    });
-    return controller.signal;
-}
-/** Read a JSON request body, capped at 1 MiB. */
-export async function readBody(request) {
-    let data = "";
-    for await (const chunk of request) {
-        data += chunk;
-        if (Buffer.byteLength(data) > 1024 * 1024)
-            fail(413, "Request too large");
-    }
-    try {
-        return JSON.parse(data);
-    }
-    catch {
-        return fail(400, "Invalid JSON");
-    }
-}

package/dist/tenant/jwt.d.ts

@@ -0,0 +1,16 @@
+export declare const MAX_TOKEN_BYTES = 4096;
+export declare const CLOCK_TOLERANCE_SECONDS = 30;
+/** True when `bearer` has the shape of a JWT; application keys never do. */
+export declare function looksLikeToken(bearer: string): boolean;
+/** The `typ` of a JWT-shaped bearer, or `undefined` when its header cannot be read. */
+export declare function tokenType(raw: string): string | undefined;
+/**
+ * Why the header of a token of type `typ` is refused before any key is read, or its key id
+ * when it is not: `malformed` (size, shape, undecodable) or `header` (algorithm, type, key id,
+ * or a header that could name another key).
+ */
+export declare function tokenKeyId(raw: string, typ: string): {
+    kid: string;
+} | {
+    refused: "malformed" | "header";
+};

package/dist/tenant/jwt.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+import { decodeProtectedHeader } from "jose";
+import { SIGNING_KEY_ID_PATTERN } from "@nylorun/core/compatibility";
+export const MAX_TOKEN_BYTES = 4096;
+export const CLOCK_TOLERANCE_SECONDS = 30;
+const JWT_SHAPE = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const FORBIDDEN_HEADERS = ["jku", "jwk", "x5u", "x5c", "x5t", "crit"];
+/** True when `bearer` has the shape of a JWT; application keys never do. */
+export function looksLikeToken(bearer) {
+    return JWT_SHAPE.test(bearer);
+}
+/** The `typ` of a JWT-shaped bearer, or `undefined` when its header cannot be read. */
+export function tokenType(raw) {
+    if (Buffer.byteLength(raw) > MAX_TOKEN_BYTES || !JWT_SHAPE.test(raw))
+        return undefined;
+    try {
+        const typ = decodeProtectedHeader(raw).typ;
+        return typeof typ === "string" ? typ : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Why the header of a token of type `typ` is refused before any key is read, or its key id
+ * when it is not: `malformed` (size, shape, undecodable) or `header` (algorithm, type, key id,
+ * or a header that could name another key).
+ */
+export function tokenKeyId(raw, typ) {
+    if (Buffer.byteLength(raw) > MAX_TOKEN_BYTES || !JWT_SHAPE.test(raw))
+        return { refused: "malformed" };
+    let header;
+    try {
+        header = decodeProtectedHeader(raw);
+    }
+    catch {
+        return { refused: "malformed" };
+    }
+    if (header.alg !== "ES256" ||
+        header.typ !== typ ||
+        typeof header.kid !== "string" ||
+        !SIGNING_KEY_ID_PATTERN.test(header.kid) ||
+        FORBIDDEN_HEADERS.some((name) => name in header))
+        return { refused: "header" };
+    return { kid: header.kid };
+}