@nylorun/runtime 0.15.2-beta → 0.17.0-beta

package/dist/tenant/history.js

@@ -1,5 +1,5 @@
-/** An edit's entries are split so each event stays well under S2's 1 MiB record limit. */
-export const CHUNK_BYTES = 256 * 1024;
+import { applyUpdate, transcriptOf } from "@nylorun/core/harness-api";
+export { CHUNK_BYTES, TranscriptFoldError, applyUpdate, applyUpdates, transcriptOf, transcriptUpdates, withTranscript, } from "@nylorun/core/harness-api";
 let shadow = false;
 /** Shadow mode: keep the transcript on the session row and check the fold against it. */
 export function transcriptShadow() {
@@ -11,12 +11,6 @@ export function setTranscriptShadow(on) {
     shadow = on;
     return previous;
 }
-export class TranscriptFoldError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "TranscriptFoldError";
-    }
-}
 /** The fold and the transcript on the row differ (shadow mode only). */
 export class TranscriptParityError extends Error {
     constructor(sessionId, at, folded, stored) {
@@ -26,59 +20,21 @@ export class TranscriptParityError extends Error {
     }
 }
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
-/** The engine state's transcript, or none. */
-export function transcriptOf(state) {
-    const transcript = state?.transcript;
-    return Array.isArray(transcript) ? transcript : [];
-}
-/**
- * The edits from `before` to `after`, split into chunks of at most `CHUNK_BYTES` of entries.
- * Empty when nothing changed.
- */
-export function transcriptUpdates(before, after, chunkBytes = CHUNK_BYTES) {
-    let keep = 0;
-    while (keep < before.length && keep < after.length && same(before[keep], after[keep]))
-        keep += 1;
-    if (keep === before.length && keep === after.length)
-        return [];
-    const added = after.slice(keep);
-    if (added.length === 0)
-        return [{ keep, entries: [], length: keep }];
-    const updates = [];
-    let chunk = [];
-    let bytes = 0;
-    let base = keep;
-    const flush = () => {
-        updates.push({ keep: base, entries: chunk, length: base + chunk.length });
-        base += chunk.length;
-        chunk = [];
-        bytes = 0;
-    };
-    for (const entry of added) {
-        const size = JSON.stringify(entry).length;
-        if (chunk.length > 0 && bytes + size > chunkBytes)
-            flush();
-        chunk.push(entry);
-        bytes += size;
-    }
-    flush();
-    return updates;
-}
-/** Applies one edit. Throws `TranscriptFoldError` when it does not fit the transcript. */
-export function applyUpdate(transcript, update) {
-    if (update.keep > transcript.length)
-        throw new TranscriptFoldError(`transcript.updated keeps ${update.keep} entries of ${transcript.length}`);
-    const next = [...transcript.slice(0, update.keep), ...update.entries];
-    if (next.length !== update.length)
-        throw new TranscriptFoldError(`transcript.updated should give ${update.length} entries, not ${next.length}`);
-    return next;
-}
 /**
  * Folds a session's events, from the start of its record or from a snapshot, into the
  * transcript the engine resumes from.
  */
 export function foldTranscript(events) {
+    return foldTranscriptWithCursor(events).transcript;
+}
+/**
+ * `foldTranscript`, and the cursor of the fold: the `seq` of the last event that changed it
+ * (`transcript.updated`, `turn.cancelled`, `turn.failed`), or -1. A harness that holds the
+ * transcript at the same cursor holds this one.
+ */
+export function foldTranscriptWithCursor(events) {
     let transcript = [];
+    let cursor = -1;
     // The transcript before the current turn's first edit: what a cancel or failure restores.
     let turn;
     for (const event of events) {
@@ -86,16 +42,18 @@ export function foldTranscript(events) {
             if (!turn || turn.id !== event.turnId)
                 turn = { id: event.turnId, before: transcript };
             transcript = applyUpdate(transcript, event.payload);
+            cursor = event.seq ?? cursor;
         }
         else if (event.type === "turn.cancelled" || event.type === "turn.failed") {
             if (turn && turn.id === event.turnId)
                 transcript = turn.before;
             turn = undefined;
+            cursor = event.seq ?? cursor;
         }
         else if (event.type === "turn.completed")
             turn = undefined;
     }
-    return transcript;
+    return { transcript, cursor };
 }
 /** `state` with an empty transcript (what the session row stores outside shadow mode). */
 export function leanState(state) {
@@ -103,12 +61,6 @@ export function leanState(state) {
         return state;
     return { ...state, transcript: [] };
 }
-/** `state` with `transcript` (what the engine runs on). */
-export function withTranscript(state, transcript) {
-    if (!state)
-        return state;
-    return { ...state, transcript: [...transcript] };
-}
 /** In shadow mode, checks the fold against the transcript the row kept. */
 export function checkParity(sessionId, folded, stored) {
     if (!shadow)

package/dist/tenant/host-token.d.ts

@@ -0,0 +1,92 @@
+import { importJWK } from "jose";
+import type { Keys } from "../keys/keys.js";
+import type { SessionStore } from "../store/types.js";
+export declare const HOST_TOKEN_TYP = "nylorun-host+jwt";
+export declare const HOST_TOKEN_AUD = "nylorun-harness-api";
+export declare const EGRESS_TOKEN_TYP = "nylorun-egress+jwt";
+export declare const EGRESS_TOKEN_AUD = "nylorun-egress";
+/** How long a host or egress token lives. The engine renews them before. */
+export declare const HOST_TOKEN_TTL_SECONDS: number;
+/** What a verified host or egress token says. */
+export interface HostClaims {
+    readonly tenantId: string;
+    readonly sandboxId: string;
+    /** The host epoch: the fence. */
+    readonly epoch: number;
+    /** The UID of the pod the token was minted for. */
+    readonly podUid: string;
+    /** Milliseconds since the epoch. */
+    readonly expiresAt: number;
+}
+/** A host token and the egress token minted with it. */
+export interface HostGrant {
+    readonly hostToken: string;
+    readonly egressToken: string;
+    readonly claims: HostClaims;
+}
+export interface HostTokenSigner {
+    readonly keys: Keys;
+    readonly config: {
+        readonly tenantId: string;
+    };
+}
+/** One egress token to mint: one pod of one sandbox at one host epoch. */
+export interface EgressTokenRequest {
+    readonly tenantId: string;
+    readonly sandboxId: string;
+    /** The host epoch the join set. */
+    readonly epoch: number;
+    readonly podUid: string;
+    /** Seconds. Default and maximum `HOST_TOKEN_TTL_SECONDS`. */
+    readonly ttl?: number;
+}
+/**
+ * Mints an egress token (the only path that does): the proxy credential egress-gate accepts,
+ * with egress-gate's claims (no `sub`). `mintHostTokens` mints one with every host token.
+ */
+export declare function mintEgressToken(signer: {
+    readonly keys: Keys;
+}, request: EgressTokenRequest): Promise<{
+    readonly token: string;
+    readonly claims: HostClaims;
+}>;
+/** Mints the host and egress tokens of `sandboxId`'s pod `podUid` at host epoch `epoch`. */
+export declare function mintHostTokens(signer: HostTokenSigner, host: {
+    readonly sandboxId: string;
+    readonly epoch: number;
+    readonly podUid: string;
+}): Promise<HostGrant>;
+/** A verified token's claims, or why it was refused (logged, never answered). */
+export type HostTokenVerdict = {
+    readonly ok: true;
+    readonly claims: HostClaims;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+type PublicKey = Awaited<ReturnType<typeof importJWK>>;
+/** Public keys imported by key id; the key row is still read on every verification. */
+export type HostTokenKeyCache = Map<string, PublicKey>;
+declare const KINDS: {
+    readonly host: {
+        readonly typ: "nylorun-host+jwt";
+        readonly aud: "nylorun-harness-api";
+    };
+    readonly egress: {
+        readonly typ: "nylorun-egress+jwt";
+        readonly aud: "nylorun-egress";
+    };
+};
+/**
+ * Verifies a host (`kind: "host"`) or egress (`kind: "egress"`) token of Tenant `tenantId`:
+ * shape and header before any key is read, then the signature, `iss`, `aud`, `typ`, lifetime
+ * and claims. It does not read the sandbox: `currentHost` does.
+ */
+export declare function verifyHostToken(store: SessionStore, tenantId: string, raw: string, kind: keyof typeof KINDS, cache?: HostTokenKeyCache): Promise<HostTokenVerdict>;
+/**
+ * Why a host's claims are stale, or undefined while they are its sandbox's current host: the
+ * sandbox exists as a pod sandbox, is not deleted, lost or expired, and its epoch and pod are
+ * the token's. One indexed read of the sandbox's row.
+ */
+export declare function staleHost(store: SessionStore, claims: HostClaims): Promise<string | undefined>;
+export {};

package/dist/tenant/host-token.js

@@ -0,0 +1,179 @@
+/**
+ * Host and egress tokens (F7.2, D42): the ES256 JWTs a pod sandbox's engine holds once its
+ * join token is exchanged (`sandbox/join.ts`). Both name one sandbox and one host epoch; a
+ * join, a relaunch, a loss, an expiry, a stop or a reset moves the epoch, and a token of an
+ * older one is refused. Signed by the keys service with the Tenant's current signing key,
+ * like run tokens, and told apart from them and from each other by `typ` and `aud`:
+ *
+ * ```text
+ * host    { alg: ES256, typ: nylorun-host+jwt, kid }
+ *         { iss: urn:nylorun:tenant:<id>, aud: nylorun-harness-api, sub: <sandboxId>,
+ *           sbx: <sandboxId>, epc: <host epoch>, pod: <pod UID>, iat, exp, jti }
+ * egress  { alg: ES256, typ: nylorun-egress+jwt, kid }
+ *         { iss: urn:nylorun:tenant:<id>, aud: nylorun-egress,
+ *           sbx: <sandboxId>, epc: <host epoch>, pod: <pod UID>, iat, exp, jti }
+ * ```
+ *
+ * The host token is accepted only by the Harness API listener (a connection serving that one
+ * sandbox, and `host.renew`); the egress token only by egress-gate, as the proxy credential
+ * (`Proxy-Authorization`). Neither is a bearer anywhere else: the Tenant API's bearer check
+ * accepts trusted issuers' and delivery tokens only, and the gates run tokens only.
+ *
+ * Verification reads the key row on every call (a revoked key refuses at once) and, with
+ * `currentHost`, the sandbox's row (one indexed read): the epoch must be the sandbox's, the
+ * pod its pod, and the sandbox neither lost, expired nor deleted.
+ */
+import { randomUUID } from "node:crypto";
+import { errors, importJWK, jwtVerify } from "jose";
+import { tenantTokenIssuer } from "@nylorun/core/contracts";
+import { CLOCK_TOLERANCE_SECONDS, tokenKeyId } from "./jwt.js";
+export const HOST_TOKEN_TYP = "nylorun-host+jwt";
+export const HOST_TOKEN_AUD = "nylorun-harness-api";
+export const EGRESS_TOKEN_TYP = "nylorun-egress+jwt";
+export const EGRESS_TOKEN_AUD = "nylorun-egress";
+/** How long a host or egress token lives. The engine renews them before. */
+export const HOST_TOKEN_TTL_SECONDS = 15 * 60;
+const LIFETIME_SLACK_SECONDS = 60;
+/**
+ * Mints an egress token (the only path that does): the proxy credential egress-gate accepts,
+ * with egress-gate's claims (no `sub`). `mintHostTokens` mints one with every host token.
+ */
+export async function mintEgressToken(signer, request) {
+    const { tenantId, sandboxId, epoch, podUid } = request;
+    const ttl = request.ttl ?? HOST_TOKEN_TTL_SECONDS;
+    if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > HOST_TOKEN_TTL_SECONDS)
+        throw new Error(`An egress token lives 1 to ${HOST_TOKEN_TTL_SECONDS} s, not ${ttl}`);
+    if (!Number.isSafeInteger(epoch) || epoch < 1)
+        throw new Error(`Host epoch ${epoch} is not a positive integer`);
+    if (sandboxId === "" || podUid === "")
+        throw new Error("An egress token names a sandbox and a pod");
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = iat + ttl;
+    const { token } = await signer.keys.sign({
+        typ: EGRESS_TOKEN_TYP,
+        claims: {
+            iss: tenantTokenIssuer(tenantId),
+            aud: EGRESS_TOKEN_AUD,
+            sbx: sandboxId,
+            epc: epoch,
+            pod: podUid,
+            iat,
+            exp,
+            jti: randomUUID(),
+        },
+    });
+    return { token, claims: { tenantId, sandboxId, epoch, podUid, expiresAt: exp * 1000 } };
+}
+/** Mints the host and egress tokens of `sandboxId`'s pod `podUid` at host epoch `epoch`. */
+export async function mintHostTokens(signer, host) {
+    const tenantId = signer.config.tenantId;
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = iat + HOST_TOKEN_TTL_SECONDS;
+    const [hostToken, egress] = await Promise.all([
+        signer.keys.sign({
+            typ: HOST_TOKEN_TYP,
+            claims: {
+                iss: tenantTokenIssuer(tenantId),
+                aud: HOST_TOKEN_AUD,
+                sub: host.sandboxId,
+                sbx: host.sandboxId,
+                epc: host.epoch,
+                pod: host.podUid,
+                iat,
+                exp,
+                jti: randomUUID(),
+            },
+        }),
+        mintEgressToken(signer, { tenantId, ...host }),
+    ]);
+    return {
+        hostToken: hostToken.token,
+        egressToken: egress.token,
+        claims: {
+            tenantId,
+            sandboxId: host.sandboxId,
+            epoch: host.epoch,
+            podUid: host.podUid,
+            expiresAt: exp * 1000,
+        },
+    };
+}
+const KINDS = {
+    host: { typ: HOST_TOKEN_TYP, aud: HOST_TOKEN_AUD },
+    egress: { typ: EGRESS_TOKEN_TYP, aud: EGRESS_TOKEN_AUD },
+};
+/**
+ * Verifies a host (`kind: "host"`) or egress (`kind: "egress"`) token of Tenant `tenantId`:
+ * shape and header before any key is read, then the signature, `iss`, `aud`, `typ`, lifetime
+ * and claims. It does not read the sandbox: `currentHost` does.
+ */
+export async function verifyHostToken(store, tenantId, raw, kind, cache = new Map()) {
+    const refused = (reason) => ({ ok: false, reason: `${kind}_token_${reason}` });
+    const { typ, aud } = KINDS[kind];
+    const checked = tokenKeyId(raw, typ);
+    if ("refused" in checked)
+        return refused(checked.refused);
+    const { kid } = checked;
+    const row = await store.tx((t) => t.signingKey(kid));
+    if (!row)
+        return refused("key_unknown");
+    let key = cache.get(kid);
+    if (!key) {
+        key = await importJWK({ ...JSON.parse(row.publicJwk), alg: "ES256" }, "ES256");
+        cache.set(kid, key);
+    }
+    let payload;
+    try {
+        const verified = await jwtVerify(raw, key, {
+            algorithms: ["ES256"],
+            issuer: tenantTokenIssuer(tenantId),
+            audience: aud,
+            typ,
+            clockTolerance: CLOCK_TOLERANCE_SECONDS,
+            requiredClaims: ["iat", "exp", "jti"],
+        });
+        payload = verified.payload;
+    }
+    catch (error) {
+        return refused(error instanceof errors.JWTExpired ? "expired" : "invalid");
+    }
+    if (row.state === "revoked")
+        return refused("key_revoked");
+    const { sub, sbx, epc, pod, iat, exp } = payload;
+    if (typeof sbx !== "string" ||
+        sbx === "" ||
+        (kind === "host" && sub !== sbx) ||
+        typeof pod !== "string" ||
+        pod === "" ||
+        typeof epc !== "number" ||
+        !Number.isSafeInteger(epc) ||
+        epc < 1 ||
+        exp - iat > HOST_TOKEN_TTL_SECONDS + LIFETIME_SLACK_SECONDS)
+        return refused("claims");
+    return {
+        ok: true,
+        claims: { tenantId, sandboxId: sbx, epoch: epc, podUid: pod, expiresAt: exp * 1000 },
+    };
+}
+/**
+ * Why a host's claims are stale, or undefined while they are its sandbox's current host: the
+ * sandbox exists as a pod sandbox, is not deleted, lost or expired, and its epoch and pod are
+ * the token's. One indexed read of the sandbox's row.
+ */
+export async function staleHost(store, claims) {
+    const row = await store.tx((t) => t.sandboxResource(claims.sandboxId));
+    const pod = row?.pod;
+    if (!row || row.kind !== "pod" || !pod)
+        return "the sandbox is gone";
+    if (pod.desired === "deleted")
+        return "the sandbox was deleted";
+    if (pod.observed === "lost")
+        return "the sandbox was lost";
+    if (pod.observed === "expired")
+        return "the sandbox expired";
+    if (pod.hostEpoch !== claims.epoch)
+        return "another host holds the sandbox now";
+    if (pod.podUid !== claims.podUid)
+        return "the token is another pod's";
+    return undefined;
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 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 { type KeyObject } from "node:crypto";
+import { type IssuerScope } from "@nylorun/core/contracts";
+/** The JWT algorithms an issuer may sign with. */
+export declare const ISSUER_ALGORITHMS: readonly ["RS256", "ES256", "EdDSA"];
+export type IssuerAlgorithm = (typeof ISSUER_ALGORITHMS)[number];
+/** A public key an issuer signs with, and the one algorithm it verifies. */
+export interface IssuerKey {
+    readonly key: KeyObject;
+    readonly alg: IssuerAlgorithm;
+    readonly kid?: string;
+}
+/** One trusted issuer, as the identity file declares it. */
+export interface TrustedIssuerConfig {
+    /** Its name: `issuer:<name>` in `GET /v1/me` and the token's role. */
+    readonly name: string;
+    /** The `iss` its tokens carry, exactly. */
+    readonly issuer: string;
+    /** The `aud` its tokens must carry. */
+    readonly audience: string;
+    /** Where its public keys are fetched (a JWKS URL); or `keys`. */
+    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. */
+    readonly subject: string;
+    /** Where its tokens' scopes come from: a claim, or a fixed list. */
+    readonly scopes: {
+        readonly claim: string;
+    } | {
+        readonly fixed: readonly IssuerScope[];
+    };
+    /** The scopes its tokens may carry; others are dropped. */
+    readonly allowedScopes: readonly IssuerScope[];
+    /** The agents its tokens reach; absent reaches all. */
+    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 {
+    constructor(message: string);
+}
+/** The claim names a template references. */
+export declare function claimReferences(template: string): string[];
+/** `template` with every reference replaced by `value(claim)`; undefined when one has none. */
+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;
+/**
+ * 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[];

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;
+}