@nylorun/runtime 0.16.0-beta → 0.19.0-beta

package/dist/tenant/identity-file.js

@@ -0,0 +1,202 @@
+/**
+ * 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.
+ *
+ * ```yaml
+ * issuers:
+ *   - name: keycloak
+ *     issuer: https://sso.acme.dev/realms/eng
+ *     audience: nylorun
+ *     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
+ * ```
+ */
+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";
+/** 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;
+/** At most this many static `keys` per issuer. */
+const MAX_STATIC_KEYS = 16;
+const ISSUER_NAME = /^[a-z][a-z0-9-]{0,31}$/;
+/** A claim reference in a template: `{claim}`, a top-level claim name without braces. */
+const CLAIM_REFERENCE = /\{([^{}]+)\}/g;
+/** A malformed identity file: the message names the issuer and the field. */
+export class IdentityFileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "IdentityFileError";
+    }
+}
+/** The claim names a template references. */
+export function claimReferences(template) {
+    return [...template.matchAll(CLAIM_REFERENCE)].map((match) => match[1]);
+}
+/** `template` with every reference replaced by `value(claim)`; undefined when one has none. */
+export function renderTemplate(template, value) {
+    let missing = false;
+    const rendered = template.replace(CLAIM_REFERENCE, (_, claim) => {
+        const found = value(claim);
+        if (found === undefined)
+            missing = true;
+        return found ?? "";
+    });
+    return missing ? undefined : rendered;
+}
+/** True when every brace in `template` belongs to a `{claim}` reference. */
+function bracesBalanced(template) {
+    return !/[{}]/.test(template.replace(CLAIM_REFERENCE, ""));
+}
+/** A PEM public key an issuer may sign with, and its algorithm; throws a message otherwise. */
+export function issuerKey(key, kid) {
+    const details = key.asymmetricKeyDetails ?? {};
+    switch (key.asymmetricKeyType) {
+        case "rsa":
+            if ((details.modulusLength ?? 0) < 2048)
+                throw new Error("an RSA key must be at least 2048 bits");
+            return { key, alg: "RS256", ...(kid ? { kid } : {}) };
+        case "ec":
+            if (details.namedCurve !== "prime256v1")
+                throw new Error("an EC key must be on P-256 (ES256)");
+            return { key, alg: "ES256", ...(kid ? { kid } : {}) };
+        case "ed25519":
+            return { key, alg: "EdDSA", ...(kid ? { kid } : {}) };
+        default:
+            throw new Error(`a ${key.asymmetricKeyType ?? "secret"} key is not accepted: use RSA (RS256), P-256 (ES256) or Ed25519 (EdDSA)`);
+    }
+}
+const template = (what) => z
+    .string()
+    .min(1)
+    .max(200)
+    .refine(bracesBalanced, `${what} may use braces only around a claim name, as {sub}`);
+const IssuerScopeSchema = z.enum(ISSUER_SCOPES, {
+    error: (issue) => `${String(issue.input)} is not a scope an issuer may grant (one of ${ISSUER_SCOPES.join(", ")})`,
+});
+const IssuerEntrySchema = z
+    .object({
+    name: z.string().regex(ISSUER_NAME, "must match ^[a-z][a-z0-9-]{0,31}$"),
+    issuer: z
+        .string()
+        .min(1)
+        .refine((value) => !value.startsWith("urn:nylorun:"), "urn:nylorun: issuers are the Runtime's own"),
+    audience: z.string().min(1),
+    jwks: z
+        .string()
+        .refine((value) => {
+        try {
+            const url = new URL(value);
+            return (url.protocol === "https:" || url.protocol === "http:") && !url.username && !url.password;
+        }
+        catch {
+            return false;
+        }
+    }, "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([
+        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),
+    agents: z.array(z.string().min(1)).optional(),
+    sandboxes: z
+        .array(template("a sandbox grant").refine(
+    // A rendered grant must be a grant: checked here with a sample value per claim.
+    (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();
+function issueText(issues) {
+    return issues
+        .map((issue) => {
+        const path = issue.path.map((part) => (typeof part === "number" ? `[${part}]` : `.${String(part)}`)).join("").replace(/^\./, "");
+        return `${path || "(entry)"}: ${issue.message}`;
+    })
+        .join("; ");
+}
+/**
+ * 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") {
+    const fail = (message) => {
+        throw new IdentityFileError(`${source}: ${message}`);
+    };
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (error) {
+        return fail(`not YAML: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const file = IdentityFileSchema.safeParse(raw ?? {});
+    if (!file.success)
+        return fail(issueText(file.error.issues));
+    const issuers = [];
+    file.data.issuers.forEach((entry, index) => {
+        const named = entry && typeof entry === "object" && typeof entry.name === "string"
+            ? entry.name
+            : `#${index + 1}`;
+        const where = `issuer ${named}`;
+        const parsed = IssuerEntrySchema.safeParse(entry);
+        if (!parsed.success)
+            return fail(`${where}: ${issueText(parsed.error.issues)}`);
+        const value = parsed.data;
+        if ((value.jwks === undefined) === (value.keys === undefined))
+            return fail(`${where}: jwks or keys: give exactly one of them`);
+        if ("fixed" in value.scopes) {
+            const outside = value.scopes.fixed.filter((scope) => !value.allowedScopes.includes(scope));
+            if (outside.length > 0)
+                return fail(`${where}: scopes.fixed: ${outside.join(", ")} not in allowedScopes`);
+        }
+        const keys = value.keys?.map((pem, keyIndex) => {
+            try {
+                return issuerKey(createPublicKey(pem));
+            }
+            catch (error) {
+                return fail(`${where}: keys[${keyIndex}]: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+        if (issuers.some((other) => other.name === value.name))
+            return fail(`${where}: name: another issuer has this name`);
+        if (issuers.some((other) => other.issuer === value.issuer))
+            return fail(`${where}: issuer: another issuer has ${value.issuer}`);
+        issuers.push({
+            name: value.name,
+            issuer: value.issuer,
+            audience: value.audience,
+            ...(value.jwks ? { jwks: value.jwks } : {}),
+            ...(keys ? { keys } : {}),
+            subject: value.subject,
+            scopes: value.scopes,
+            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

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

package/dist/tenant/issuers.js

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

package/dist/tenant/jwt.js

@@ -1,7 +1,7 @@
 /**
- * What subject tokens and delivery tokens share: the Tenant's ES256 JWTs, recognised by shape,
- * told apart by their `typ`, and refused before any key is read when the header is not one the
- * Runtime issues.
+ * What the Runtime's own tokens share (capability links, run and host tokens):
+ * the Tenant's ES256 JWTs, recognised by shape, told apart by their `typ`, and refused before
+ * any key is read when the header is not one the Runtime issues.
  */
 import { decodeProtectedHeader } from "jose";
 import { SIGNING_KEY_ID_PATTERN } from "@nylorun/core/compatibility";

package/dist/tenant/module.d.ts

@@ -1,4 +1,3 @@
-import type { StreamRelayStatus } from "@nylorun/core/contracts";
 import { TenantUnavailableError, type Logger, type TenantHandle, type TenantModule, type TenantOpener } from "./types.js";
 export interface CreateTenantModuleOptions {
     /** Opens the Host's Tenant (`store-pg.ts`). */
@@ -11,15 +10,13 @@ export interface CreateTenantModuleOptions {
      * Tenant's id (its stream relay). A failure is logged; the Tenant stays open.
      */
     onOpen?: (handle: TenantHandle) => void | Promise<void>;
-    /** This process's stream relay, for the Host aggregate (a Host with S2 runs one). */
-    relayStatus?: () => Promise<StreamRelayStatus>;
 }
 /**
  * Deep Tenant module (§8): the Host's one Tenant over an injected opener (tenancy.md §5).
  *
  * `start` opens it once, even when requests or Worker calls ask at the same time. An open that
  * fails for a reason in the Tenant (a `TenantOpenError`, or a timeout) is kept as the Tenant's
- * cause: the Host is not ready, `/v1/admin/status` names it, requests get the opaque 404.
+ * cause: the Host is not ready, `nylorun-operate status` names it, requests get the opaque 404.
  * One that fails outside the Tenant (`TenantUnavailableError`) is retried in the background
  * with backoff, and by the next request, which gets 503 meanwhile.
  */

package/dist/tenant/module.js

@@ -10,7 +10,7 @@ const RETRY_MAX_MS = 30_000;
  *
  * `start` opens it once, even when requests or Worker calls ask at the same time. An open that
  * fails for a reason in the Tenant (a `TenantOpenError`, or a timeout) is kept as the Tenant's
- * cause: the Host is not ready, `/v1/admin/status` names it, requests get the opaque 404.
+ * cause: the Host is not ready, `nylorun-operate status` names it, requests get the opaque 404.
  * One that fails outside the Tenant (`TenantUnavailableError`) is retried in the background
  * with backoff, and by the next request, which gets 503 meanwhile.
  */
@@ -148,18 +148,9 @@ export function createTenantModule(options) {
                     return { id: null, name: null, state: "unavailable", envelope: null };
             }
         },
-        async summarize() {
+        harnessStatus() {
             const now = current();
-            const summary = now.kind === "open" ? await now.handle.summary() : undefined;
-            const relay = await options.relayStatus?.().catch(() => undefined);
-            return {
-                runningSessions: summary?.runningSessions ?? 0,
-                inFlightDeliveries: summary?.inFlightDeliveries ?? 0,
-                pendingActions: summary?.pendingActions ?? 0,
-                uncertainEffects: summary?.uncertainEffects ?? 0,
-                ...(relay ? { relay } : {}),
-                ...(summary?.harness ? { harness: summary.harness } : {}),
-            };
+            return now.kind === "open" ? now.handle.harnessStatus?.() : undefined;
         },
         async close() {
             const previous = current();

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

@@ -0,0 +1,44 @@
+/**
+ * The Tenant's keys by name (F9 I1), managed through the Management API (`/v1/tenant/keys`,
+ * application keys only) and `nylorun-operate keys`. A key is a principal (F9-D11): its id is the key's name
+ * (`APPLICATION_KEY_ID_PATTERN`), the key is 64 hex characters (`mintBearerToken`), and the
+ * Tenant keeps only its SHA-256. Putting a key creates the principal or rotates its key;
+ * deleting it removes the row. Either way the old key stops authenticating on its next request,
+ * since authentication reads the principal on every request (`auth.ts`).
+ *
+ * `studio` is derived from the admin key (F9-D9): it is never put or deleted here. `bootstrap` is
+ * the management key a Host registers from `NYLORUN_MANAGEMENT_KEY_FILE`: its file is its only
+ * source. A key has a role (protocol 8): `application` reaches the Runtime API, `management` the
+ * Management API; a key keeps its role when it is rotated.
+ */
+import { type KeyRole } from "@nylorun/core/compatibility";
+import type { OperatorKey, PutOperatorKeyResponse } from "@nylorun/core/contracts";
+import type { SessionStore } from "../store/types.js";
+/**
+ * Why a key is refused: not a key name, a reserved id (`studio`, `bootstrap`), or an id that
+ * holds the other role (`role`).
+ */
+export type OperatorKeyRefusal = {
+    reason: "invalid" | "reserved" | "role";
+    message: string;
+};
+/**
+ * The refusal for `id`, or undefined when it may be `put` or deleted. `bootstrap` is never put
+ * here (its file is its only source) but may be deleted on the machine (AP18).
+ */
+export declare function refuseOperatorKeyId(id: string, purpose?: "put" | "delete"): OperatorKeyRefusal | undefined;
+export interface OperatorKeys {
+    /** Every principal of the Tenant, by id (Studio's and derived ones included). */
+    list(): Promise<OperatorKey[]>;
+    /**
+     * Creates key `id` with `role` (default `application`) or rotates it; the key is returned
+     * this once. An id that holds the other role is refused.
+     */
+    put(id: string, role?: Exclude<KeyRole, "studio">): Promise<PutOperatorKeyResponse | OperatorKeyRefusal>;
+    /**
+     * Deletes key `id`: false when there is none. With `role`, a key of another role is refused
+     * (the Management API deletes application keys only).
+     */
+    delete(id: string, role?: Exclude<KeyRole, "studio">): Promise<boolean | OperatorKeyRefusal>;
+}
+export declare function operatorKeys(store: SessionStore, now?: () => string): OperatorKeys;