@nylorun/runtime 0.15.1-beta → 0.16.0-beta

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 subject 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 { subjectTokenIssuer } 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: subjectTokenIssuer(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: subjectTokenIssuer(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: subjectTokenIssuer(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/module.js

@@ -158,6 +158,7 @@ export function createTenantModule(options) {
                 pendingActions: summary?.pendingActions ?? 0,
                 uncertainEffects: summary?.uncertainEffects ?? 0,
                 ...(relay ? { relay } : {}),
+                ...(summary?.harness ? { harness: summary.harness } : {}),
             };
         },
         async close() {

package/dist/tenant/paths.d.ts

@@ -16,7 +16,8 @@ export declare function hostPaths(hostRoot: string): HostPaths;
  * root after realpath.
  *
  * The directory holds what stays on the Host (the Tenant's data is its database): `home/`,
- * `tmp/`, `sandboxes/`, `plugin-data/`, `logs/tenant.log`. The vault key is the one exception:
+ * `tmp/`, `sandboxes/`, `plugin-data/`, `blobs/` (the `fs` BlobStore, when the Host has no
+ * Object store), `logs/tenant.log`. The vault key is the one exception:
  * it lives beside the Tenant directory, in `<hostRoot>/keys/vault-kek`, which the local stack
  * mounts only into the gateway (F4.2), never into the runtime container.
  */

package/dist/tenant/paths.js

@@ -24,7 +24,8 @@ export function hostPaths(hostRoot) {
  * root after realpath.
  *
  * The directory holds what stays on the Host (the Tenant's data is its database): `home/`,
- * `tmp/`, `sandboxes/`, `plugin-data/`, `logs/tenant.log`. The vault key is the one exception:
+ * `tmp/`, `sandboxes/`, `plugin-data/`, `blobs/` (the `fs` BlobStore, when the Host has no
+ * Object store), `logs/tenant.log`. The vault key is the one exception:
  * it lives beside the Tenant directory, in `<hostRoot>/keys/vault-kek`, which the local stack
  * mounts only into the gateway (F4.2), never into the runtime container.
  */
@@ -41,6 +42,7 @@ export function tenantPaths(hostRoot) {
         tmp: join(root, "tmp"),
         sandboxes: join(root, "sandboxes"),
         pluginData: join(root, "plugin-data"),
+        blobs: join(root, "blobs"),
         logs: join(root, "logs"),
         log: join(root, "logs", "tenant.log"),
     };

package/dist/tenant/reset.d.ts

@@ -1,11 +1,14 @@
 import type { ResetScope, SessionStore } from "../store/types.js";
-import type { SandboxManager } from "../sandbox/manager.js";
+import type { WorkspacePort } from "../harness-api/workspace.js";
 import type { TenantPaths } from "./types.js";
+import type { BlobStore } from "../blob/index.js";
 export type { ResetScope } from "../store/types.js";
 export interface ResetTenantContext {
     store: SessionStore;
-    sandbox: SandboxManager;
+    sandbox: WorkspacePort;
     paths: TenantPaths;
+    /** Where the deleted artifacts' bytes are; they are removed after the store wipe. */
+    blobs?: BlobStore;
     /** Clear in-memory session observers after the store wipe. */
     clearSessionState: () => void;
 }

package/dist/tenant/reset.js

@@ -1,5 +1,7 @@
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
+import { detachAllSessions } from "./sandboxes.js";
+import { contentKey } from "../artifacts/folders.js";
 /**
  * Rename `dir` to a sibling, delete the sibling, recreate an empty `dir`.
  * Failure before rename leaves the original intact; after rename the empty
@@ -39,11 +41,29 @@ export async function resetTenant(ctx, scope) {
     const clearSandboxes = scope === "sandboxes" || scope === "all";
     const clearAll = scope === "all";
     if (clearSandboxes) {
-        await ctx.sandbox.reconcile(() => false);
+        await ctx.sandbox.removeAll();
     }
-    await ctx.store.tx((t) => t.reset(scope));
+    // The artifacts the reset deletes: their rows go in its transaction, their bytes after it.
+    const blobKeys = await ctx.store.tx(async (t) => {
+        // Sandbox resources outlive their sessions: a sessions reset only detaches them.
+        if (clearSessions && !clearSandboxes)
+            await detachAllSessions(t);
+        const scoped = clearAll ? "all" : "sessions";
+        const keys = clearSessions ? await t.artifactBlobKeys(scoped) : [];
+        // Folders' content-addressed files: those no remaining folder names (F8.2).
+        const content = clearSessions ? await t.artifactContentShas(scoped) : [];
+        await t.reset(scope);
+        const kept = await t.referencedArtifactContent(content);
+        for (const sha of content)
+            if (!kept.has(sha))
+                keys.push(contentKey(sha));
+        return keys;
+    });
     if (clearSessions)
         ctx.clearSessionState();
+    if (ctx.blobs)
+        for (const key of blobKeys)
+            await ctx.blobs.delete(key).catch(() => undefined);
     if (clearSandboxes)
         replaceDirectory(ctx.paths.sandboxes);
     if (clearAll) {

package/dist/tenant/run-grants.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Run grants (F5, gate trust): the run token each advance of this process holds while it owns
+ * a session (`run-token.ts`). The advance mints one when it takes the lease (`grantRun`), the
+ * lease heartbeat re-mints it before it expires (`renewRunGrant`), and it goes when the
+ * advance ends or loses the lease (`dropRunGrant`). The HTTP gate clients read the session's
+ * token on every request (`RunTokens`), so a re-mint applies to the next call.
+ *
+ * Only a Runtime whose gates are a service has grants (`TenantContext.runGrants`). With the
+ * gates in this process nothing is minted (G6): the trust boundary is the gate's HTTP route.
+ */
+import type { Lease, TenantContext } from "./context.js";
+import { type RunGrant } from "./run-token.js";
+/** What a gate client reads: the current run token of a session, if an advance holds one. */
+export interface RunTokens {
+    token(sessionId: string): string | undefined;
+}
+/** The run grants of this process's advances, by session id. */
+export interface RunGrants extends RunTokens {
+    get(sessionId: string): RunGrant | undefined;
+    set(grant: RunGrant): void;
+    /** Forgets the grant of `sessionId` if it is the one of `epoch`: a newer advance's stays. */
+    drop(sessionId: string, epoch: number): void;
+}
+export declare function createRunGrants(): RunGrants;
+type GrantContext = Pick<TenantContext, "keys" | "config" | "runGrants">;
+/** What a run token names of the session: its root agent and the turn the advance runs. */
+export interface RunOf {
+    readonly agentId: string;
+    readonly activeTurnId: string | null;
+}
+/**
+ * Mints and registers the run token of the advance that just took `lease`. Nothing when the
+ * gates run in this process, or the session has no active turn (it makes no gate call).
+ *
+ * Never throws: an advance may make no gate call at all (a model the Tenant serves itself, a
+ * workflow step), so a keys service that does not answer must not stop it. Without a grant
+ * the session's model calls fail as when the gateway is down, its MCP requests use core's
+ * credential, and the heartbeat tries again (`renewRunGrant`).
+ */
+export declare function grantRun(ctx: GrantContext, lease: Lease, run: RunOf): Promise<void>;
+/**
+ * Re-mints the grant of `lease` when less than `RUN_TOKEN_RENEW_SECONDS` remain, or mints it
+ * when the first mint failed. `active` is false once the advance ended: a token minted after
+ * that is not registered.
+ */
+export declare function renewRunGrant(ctx: GrantContext, lease: Lease, run: RunOf, active?: () => boolean): Promise<void>;
+/** Forgets the grant of `lease` (the advance ended, or lost the lease). */
+export declare function dropRunGrant(ctx: Pick<TenantContext, "runGrants">, lease: Lease): void;
+export {};

package/dist/tenant/run-grants.js

@@ -0,0 +1,62 @@
+import { mintRunToken, RUN_TOKEN_RENEW_SECONDS } from "./run-token.js";
+export function createRunGrants() {
+    const grants = new Map();
+    return {
+        token: (sessionId) => grants.get(sessionId)?.token,
+        get: (sessionId) => grants.get(sessionId),
+        set(grant) {
+            const held = grants.get(grant.claims.sessionId);
+            // An older advance of the same session (a lease lost while it still ran) never replaces it.
+            if (held && held.claims.epoch > grant.claims.epoch)
+                return;
+            grants.set(grant.claims.sessionId, grant);
+        },
+        drop(sessionId, epoch) {
+            if (grants.get(sessionId)?.claims.epoch === epoch)
+                grants.delete(sessionId);
+        },
+    };
+}
+/**
+ * Mints and registers the run token of the advance that just took `lease`. Nothing when the
+ * gates run in this process, or the session has no active turn (it makes no gate call).
+ *
+ * Never throws: an advance may make no gate call at all (a model the Tenant serves itself, a
+ * workflow step), so a keys service that does not answer must not stop it. Without a grant
+ * the session's model calls fail as when the gateway is down, its MCP requests use core's
+ * credential, and the heartbeat tries again (`renewRunGrant`).
+ */
+export async function grantRun(ctx, lease, run) {
+    if (!ctx.runGrants || !run.activeTurnId)
+        return;
+    try {
+        ctx.runGrants.set(await mintRunToken(ctx, lease, run));
+    }
+    catch (error) {
+        ctx.config.logger.warn("advance could not mint its run token", {
+            sessionId: lease.sessionId,
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Re-mints the grant of `lease` when less than `RUN_TOKEN_RENEW_SECONDS` remain, or mints it
+ * when the first mint failed. `active` is false once the advance ended: a token minted after
+ * that is not registered.
+ */
+export async function renewRunGrant(ctx, lease, run, active = () => true) {
+    if (!ctx.runGrants || !run.activeTurnId)
+        return;
+    const held = ctx.runGrants.get(lease.sessionId);
+    if (held && held.claims.epoch !== lease.epoch)
+        return;
+    if (held && held.claims.expiresAt - Date.now() > RUN_TOKEN_RENEW_SECONDS * 1000)
+        return;
+    const grant = await mintRunToken(ctx, lease, held ? { agentId: held.claims.agentId, activeTurnId: held.claims.turnId } : run);
+    if (active())
+        ctx.runGrants.set(grant);
+}
+/** Forgets the grant of `lease` (the advance ended, or lost the lease). */
+export function dropRunGrant(ctx, lease) {
+    ctx.runGrants?.drop(lease.sessionId, lease.epoch);
+}

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

@@ -0,0 +1,70 @@
+import { importJWK } from "jose";
+import type { Keys } from "../keys/keys.js";
+import type { SessionStore } from "../store/types.js";
+import type { Lease } from "./context.js";
+export declare const RUN_TOKEN_TYP = "nylorun-run+jwt";
+export declare const RUN_TOKEN_AUD = "nylorun-gates";
+/** How long a run token lives. */
+export declare const RUN_TOKEN_TTL_SECONDS: number;
+/** The lease heartbeat re-mints a token with less than this left. */
+export declare const RUN_TOKEN_RENEW_SECONDS: number;
+/** What a verified run token says: one lease of one session's turn. */
+export interface RunClaims {
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+    /** The session's root agent: the ledger's and the agent budget's scope. */
+    readonly agentId: string;
+    /** The lease epoch: the fence. */
+    readonly epoch: number;
+    /** Milliseconds since the epoch. */
+    readonly expiresAt: number;
+}
+/** A minted run token and what it says. */
+export interface RunGrant {
+    readonly token: string;
+    readonly claims: RunClaims;
+}
+/** Who mints: the Tenant's keys and id (a `TenantContext` is one). */
+export interface RunTokenSigner {
+    readonly keys: Keys;
+    readonly config: {
+        readonly tenantId: string;
+    };
+}
+/**
+ * Mints the run token of `lease` over `session`'s active turn. Throws when the session has
+ * no active turn: there is no run to name.
+ */
+export declare function mintRunToken(signer: RunTokenSigner, lease: Lease, session: {
+    readonly agentId: string;
+    readonly activeTurnId: string | null;
+}): Promise<RunGrant>;
+/** A verified token's claims, or why it was refused (logged, never answered). */
+export type RunTokenVerdict = {
+    readonly ok: true;
+    readonly claims: RunClaims;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+type PublicKey = Awaited<ReturnType<typeof importJWK>>;
+/**
+ * Public keys imported by key id. The key row is read on every verification, so a new key
+ * (a rotation) and a revoked one apply at once; only the imported key object is kept.
+ */
+export type RunTokenKeyCache = Map<string, PublicKey>;
+/**
+ * Verifies a run token of Tenant `tenantId` against the public keys in `store`: everything a
+ * forger controls (size, shape, header) is checked before any key is read, then the
+ * signature, `iss`, `aud`, `typ`, lifetime and claims. A revoked key refuses even a token it
+ * signed while it was live.
+ */
+export declare function verifyRunToken(store: SessionStore, tenantId: string, raw: string, cache?: RunTokenKeyCache): Promise<RunTokenVerdict>;
+/**
+ * Why calls under `claims` are stale, or undefined while its lease is still the session's
+ * (G4): the session's epoch is the token's, its active turn is the token's, and it is not
+ * cancelled. One indexed read of the session row.
+ */
+export declare function staleRun(store: SessionStore, claims: RunClaims): Promise<string | undefined>;
+export {};