@nimbus-sh/worker 0.3.0 → 0.5.0

package/README.md

@@ -1,14 +1,18 @@
 # @nimbus-sh/worker
 
-The Cloudflare half of Nimbus: the `NimbusSession` Durable Object, router,
-static assets, facet machinery, and auth internals. The filesystem, shell,
-and WASI runtime layer live in
+Run a Linux-like sandbox on Cloudflare Workers. A session gets a filesystem,
+a shell, real processes, and ports you can reach from a browser, all inside
+one Durable Object.
+
+This package is the Cloudflare half: the `NimbusSession` Durable Object, the
+router, the static assets, the facet machinery, and the auth internals. The
+filesystem, shell, and WASI runtime layer live in
 [`@nimbus-sh/core`](https://www.npmjs.com/package/@nimbus-sh/core), which
-this package composes on — core also runs standalone in bun or node.
+this package composes on. Core also runs standalone in bun or node.
 
-Application code should import the deploy-time API through
-`@nimbus-sh/sdk/worker`. This package is still installed because it carries
-the runtime implementation and static assets used by the SDK entrypoint.
+Import the deploy-time API from `@nimbus-sh/sdk/worker`. Install this package
+as well, because it carries the runtime implementation and the static assets
+that entrypoint serves.
 
 ## Install
 
@@ -123,9 +127,9 @@ Cloudflare Dashboard once for the account, then rerun the setup command.
 single-tenant demos can set `NIMBUS_LEGACY_PUBLIC=1` and rely on URL
 possession instead.
 
-## Composable API
+## createNimbusHandler
 
-`createNimbusHandler(options)` accepts:
+The handler owns the router, auth, and the session protocol. Its options:
 
 ```ts
 {
@@ -144,8 +148,8 @@ possession instead.
 
 ### Custom routes
 
-Routes that return non-`null` short-circuit Nimbus's router. Use them
-for a token-mint endpoint, `/healthz`, SDK smoke tests, or backend
+A route that returns anything but `null` short-circuits Nimbus's router. Use
+one for a token-mint endpoint, `/healthz`, SDK smoke tests, or backend
 sandbox jobs.
 
 ```ts
@@ -209,8 +213,7 @@ Applications normally call it through `Nimbus.connect({ endpoint, token,
 config })`. The route requires a valid Nimbus JWT and `sandbox:use` scope.
 `box.destroy()` additionally requires `session:destroy` or `session:admin`.
 
-For long-running app servers, start an explicit long-running process and
-expose the virtual port:
+For an app server, start the process and expose its virtual port:
 
 ```ts
 await box.files.write('/home/user/app/server.js', serverSource);
@@ -220,19 +223,39 @@ const port = await box.ports.expose(3000);
 // box.processes.kill(proc.pid) stops it
 ```
 
+### Hooks
+
+```ts
+export default createNimbusHandler({
+  hooks: {
+    onSessionStart: ({ sessionId, tenantSegment, request }) => {
+      console.log(`[${tenantSegment}] session ${sessionId} attached from ${request.headers.get('cf-connecting-ip')}`);
+    },
+  },
+});
+```
+
+### Auth modes
+
+| Mode | Meaning |
+|---|---|
+| `'auto'` (default) | Verify token when `JWT_SECRET` is set AND `NIMBUS_LEGACY_PUBLIC` is unset. Otherwise legacy-public. |
+| `'enforce'` | Always verify token; fail closed if `JWT_SECRET` is missing. |
+| `'legacy'` | Never verify; all requests route to the single `legacy:public:_` tenant. Use only for single-tenant demos. |
+
 ## Session Agent
 
-The bundled session shell includes an Agent surface inside the editor
-workspace. The route lives inside the session Durable Object under
-`/api/agent/*`; the stable Cloudflare OAuth callback is
+The bundled session shell carries an agent surface inside the editor
+workspace. Its route lives in the session Durable Object under
+`/api/agent/*`. The stable Cloudflare OAuth callback is
 `/api/nimbus/oauth/callback`.
 
-The agent can use the same session tools as the SDK: shell exec, files,
-runtime installs, long-running processes, logs, and preview ports. Model calls
-use the AI SDK with Cloudflare Workers AI's OpenAI-compatible endpoint and an
+The agent uses the same session tools as the SDK: shell exec, files, runtime
+installs, long-running processes, logs, and preview ports. Model calls use
+the AI SDK with Cloudflare Workers AI's OpenAI-compatible endpoint and an
 optional AI Gateway name.
 
-For user-owned quota, create a Cloudflare OAuth client with response type
+For user-owned quota, create a Cloudflare OAuth client. Use response type
 `Code`, grant type `Authorization Code`, token authentication method `None`,
 and redirect URL `https://<your-nimbus-host>/api/nimbus/oauth/callback`.
 Nimbus uses PKCE and stores user OAuth tokens only in encrypted `HttpOnly`,
@@ -257,26 +280,6 @@ npx wrangler secret put NIMBUS_AGENT_COOKIE_SECRET
 npx wrangler secret put NIMBUS_CLOUDFLARE_API_TOKEN
 ```
 
-### Hooks
-
-```ts
-export default createNimbusHandler({
-  hooks: {
-    onSessionStart: ({ sessionId, tenantSegment, request }) => {
-      console.log(`[${tenantSegment}] session ${sessionId} attached from ${request.headers.get('cf-connecting-ip')}`);
-    },
-  },
-});
-```
-
-### Auth modes
-
-| Mode | Meaning |
-|---|---|
-| `'auto'` (default) | Verify token when `JWT_SECRET` is set AND `NIMBUS_LEGACY_PUBLIC` is unset. Otherwise legacy-public. |
-| `'enforce'` | Always verify token; fail closed if `JWT_SECRET` is missing. |
-| `'legacy'` | Never verify; all requests route to the single `legacy:public:_` tenant. Use only for single-tenant demos. |
-
 ## Subpath exports
 
 | Subpath | What |
@@ -288,7 +291,7 @@ export default createNimbusHandler({
 
 ## Required bindings
 
-Every binding is load-bearing — see `apps/hosted-demo/wrangler.jsonc` or
+None of these is optional. See `apps/hosted-demo/wrangler.jsonc` or
 `@nimbus-sh/config` for the canonical set:
 
 - `NIMBUS_SESSION` (Durable Object) — per-session SQLite state
@@ -299,7 +302,7 @@ Every binding is load-bearing — see `apps/hosted-demo/wrangler.jsonc` or
 
 ## Status
 
-v0.1 — first public release. SemVer not yet stable; expect breaking
-changes through v0.x. Issues + PRs welcome.
+v0.1 is the first public release. SemVer is not stable yet, so expect
+breaking changes through v0.x. Issues + PRs welcome.
 
 MIT. © Ashish Kumar Singh + contributors.

package/dist/_shared/preview-host.d.ts

@@ -14,9 +14,22 @@
 export interface PreviewHost {
     port: number;
     sid: string;
+    /**
+     * Present only on the public capability form `<cap>--<port>--<sid>`: the
+     * bearer is the capability itself, so the request skips session-attach
+     * auth entirely — the session decides by the port's stored visibility.
+     */
+    capability?: string;
 }
-export declare function isPreviewHostSafeSid(sid: string): boolean;
 export declare function buildPreviewHost(sid: string, port: number, suffix: string): string;
+/**
+ * `<capability>--<port>--<sid>.<suffix>` — the unauthenticated sibling of
+ * `buildPreviewHost`, for applications whose visibility is `public`. The
+ * capability is the bearer: 24 lowercase hex, the same shape the port
+ * registry mints.
+ */
+export declare function buildPublicPreviewHost(sid: string, port: number, capability: string, suffix: string): string;
+export declare function isPreviewHostSafeSid(sid: string): boolean;
 /**
  * Read the configured preview-host suffix out of a bindings env.
  *

package/dist/_shared/preview-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview-host.d.ts","sourceRoot":"","sources":["../../src/_shared/preview-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAChC,WAAW,GAAG,IAAI,CAqBpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAEpE"}
+{"version":3,"file":"preview-host.d.ts","sourceRoot":"","sources":["../../src/_shared/preview-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAcH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAChC,WAAW,GAAG,IAAI,CAgCpB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAEpE"}

package/dist/_shared/preview-host.js

@@ -14,14 +14,28 @@
 const PREVIEW_HOST_SAFE_SID_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 /** Canonical port form only: no leading zeros, so `03000--x` is not a host. */
 const PREVIEW_HOST_LABEL_RE = /^(0|[1-9]\d*)--(.+)$/;
+// The public capability form: the bearer is the capability itself, no
+// attach token and no embedder credential ever crosses this hostname.
+// The label carries everything a request needs — which port, which
+// session, and which token — so it works with no server-side lookup.
+const PREVIEW_CAPABILITY_HOST_LABEL_RE = /^([a-f0-9]{24})--(\d{1,5})--([a-z0-9-]{1,63})$/;
 /** Binding that carries the deployment's preview-host suffix. */
 const PREVIEW_HOST_SUFFIX_BINDING = 'NIMBUS_PREVIEW_HOST_SUFFIX';
-export function isPreviewHostSafeSid(sid) {
-    return sid.length <= 56 && PREVIEW_HOST_SAFE_SID_RE.test(sid);
-}
 export function buildPreviewHost(sid, port, suffix) {
     return `${port}--${sid}.${suffix}`;
 }
+/**
+ * `<capability>--<port>--<sid>.<suffix>` — the unauthenticated sibling of
+ * `buildPreviewHost`, for applications whose visibility is `public`. The
+ * capability is the bearer: 24 lowercase hex, the same shape the port
+ * registry mints.
+ */
+export function buildPublicPreviewHost(sid, port, capability, suffix) {
+    return `${capability}--${port}--${sid}.${suffix}`;
+}
+export function isPreviewHostSafeSid(sid) {
+    return sid.length <= 56 && PREVIEW_HOST_SAFE_SID_RE.test(sid);
+}
 /**
  * Read the configured preview-host suffix out of a bindings env.
  *
@@ -46,6 +60,17 @@ export function parsePreviewHost(host, suffix) {
     const label = normalizedHost.slice(0, -suffixWithDot.length);
     if (!label || label.includes('.'))
         return null;
+    // The capability form is checked first: its leading 24-hex run would
+    // otherwise parse as the port of the legacy form's widest match.
+    const capabilityMatch = label.match(PREVIEW_CAPABILITY_HOST_LABEL_RE);
+    if (capabilityMatch) {
+        const capability = capabilityMatch[1];
+        const port = Number(capabilityMatch[2]);
+        const sid = capabilityMatch[3];
+        if (port < 1 || port > 65535 || !isPreviewHostSafeSid(sid))
+            return null;
+        return { port, sid, capability };
+    }
     const match = label.match(PREVIEW_HOST_LABEL_RE);
     if (!match)
         return null;

package/dist/_shared/session-router.d.ts

@@ -51,6 +51,23 @@ export declare const TENANT_HEADER = "X-Nimbus-Tenant";
  * `Authorization` is preserved — the one route on which that is true.
  */
 export declare const PREVIEW_CAPABILITY_HEADER = "x-nimbus-preview-capability";
+/**
+ * Header the Worker sets when a request arrived on the public capability
+ * host form `<cap>--<port>--<sid>` — the request was never attached to a
+ * session, so the capability in `PREVIEW_CAPABILITY_HEADER` is the only
+ * credential it carries, and the session may honor it ONLY for a port whose
+ * stored visibility is `public`. Any other request answering on that mark
+ * is 404.
+ */
+export declare const PUBLIC_BEARER_HEADER = "x-nimbus-public-bearer";
+/**
+ * Header the Worker sets carrying the caller's verified token scopes, so the
+ * DO can gate routes that need more than session attach (e.g. the _diag
+ * abort). The header is deleted from the caller's own request before the
+ * verified value is set — a forged inbound copy never survives forwarding.
+ * Absent/empty in legacy mode, where no scopes were verified.
+ */
+export declare const CALLER_SCOPES_HEADER = "x-nimbus-caller-scopes";
 /**
  * DO-name segment used when tenant scoping is disabled (legacy-public).
  * Picked so it cannot collide with a verified token's
@@ -85,6 +102,17 @@ export declare function parseSessionRoute(pathname: string): ParsedSessionRoute
 export interface ForwardOptions {
     /** Verified tenant segment for DO naming. */
     tenantSegment: string;
+    /**
+     * Router-minted headers the DO must see — the preview capability, the
+     * public-bearer mark. Entries arrive only from code that vetted them.
+     */
+    extraHeaders?: Readonly<Record<string, string>>;
+    /**
+     * The caller's verified token scopes. Forwarded as
+     * {@link CALLER_SCOPES_HEADER} so scope-gated routes inside the DO can
+     * check them. Omitted in legacy mode or when the caller was not verified.
+     */
+    callerScopes?: readonly string[];
 }
 /**
  * Forward a request to the session's DO.
@@ -106,6 +134,21 @@ export interface ForwardOptions {
  * @param opts Tenant scoping. See {@link ForwardOptions}.
  */
 export declare function forwardToSession(request: Request, route: ParsedSessionRoute, env: any, opts: ForwardOptions): Promise<Response>;
+/**
+ * The card every session-facing error/status page shares: dark, centered,
+ * mono title. `metaRefreshSeconds` opts the page into self-refresh — the
+ * "starting" page re-asks on its own timer, the invalid page never does.
+ */
+export declare function renderSessionStatusPage(input: {
+    title: string;
+    heading: string;
+    body: string;
+    action?: {
+        href: string;
+        label: string;
+    };
+    metaRefreshSeconds?: number;
+}): string;
 /** HTML body for the "invalid session ID" 400 page. Tiny, inline-only. */
 export declare function renderInvalidSessionHtml(attemptedId: string): string;
 //# sourceMappingURL=session-router.d.ts.map

package/dist/_shared/session-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-router.d.ts","sourceRoot":"","sources":["../../src/_shared/session-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAEvE;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAS1D,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAa7E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,QAAQ,CAAC,CAsCnB;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA6BpE"}
+{"version":3,"file":"session-router.d.ts","sourceRoot":"","sources":["../../src/_shared/session-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAS1D,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAa7E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AACD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,QAAQ,CAAC,CA8CnB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,MAAM,CA8BT;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAapE"}

package/dist/_shared/session-router.js

@@ -52,6 +52,23 @@ export const TENANT_HEADER = 'X-Nimbus-Tenant';
  * `Authorization` is preserved — the one route on which that is true.
  */
 export const PREVIEW_CAPABILITY_HEADER = 'x-nimbus-preview-capability';
+/**
+ * Header the Worker sets when a request arrived on the public capability
+ * host form `<cap>--<port>--<sid>` — the request was never attached to a
+ * session, so the capability in `PREVIEW_CAPABILITY_HEADER` is the only
+ * credential it carries, and the session may honor it ONLY for a port whose
+ * stored visibility is `public`. Any other request answering on that mark
+ * is 404.
+ */
+export const PUBLIC_BEARER_HEADER = 'x-nimbus-public-bearer';
+/**
+ * Header the Worker sets carrying the caller's verified token scopes, so the
+ * DO can gate routes that need more than session attach (e.g. the _diag
+ * abort). The header is deleted from the caller's own request before the
+ * verified value is set — a forged inbound copy never survives forwarding.
+ * Absent/empty in legacy mode, where no scopes were verified.
+ */
+export const CALLER_SCOPES_HEADER = 'x-nimbus-caller-scopes';
 /**
  * DO-name segment used when tenant scoping is disabled (legacy-public).
  * Picked so it cannot collide with a verified token's
@@ -115,6 +132,16 @@ export function forwardToSession(request, route, env, opts) {
     const headers = new Headers(request.headers);
     headers.set(BASE_PATH_HEADER, route.basePath);
     headers.set(TENANT_HEADER, opts.tenantSegment);
+    // Verified scopes come from the router alone: a caller-supplied copy is
+    // deleted before the real value is set, never appended to.
+    headers.delete(CALLER_SCOPES_HEADER);
+    if (opts.callerScopes !== undefined) {
+        headers.set(CALLER_SCOPES_HEADER, opts.callerScopes.join(' '));
+    }
+    if (opts.extraHeaders) {
+        for (const [name, value] of Object.entries(opts.extraHeaders))
+            headers.set(name, value);
+    }
     // Load-bearing, not hygiene: the query is a first-class auth channel
     // (`extractBearerToken` reads it), so anything forwarded with the token
     // still attached would carry a live credential into inner-DO logs, the
@@ -142,18 +169,23 @@ export function forwardToSession(request, route, env, opts) {
     const stub = env.NIMBUS_SESSION.get(id);
     return stub.fetch(inner);
 }
-/** HTML body for the "invalid session ID" 400 page. Tiny, inline-only. */
-export function renderInvalidSessionHtml(attemptedId) {
-    // Escape the attempted ID for display. We don't use innerHTML anywhere,
-    // but defensive escaping keeps the HTML validator happy and avoids any
-    // future XSS footguns if someone refactors this to document.write().
-    const safe = String(attemptedId).replace(/[&<>"']/g, (c) => ({
-        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
-    }[c]));
+/**
+ * The card every session-facing error/status page shares: dark, centered,
+ * mono title. `metaRefreshSeconds` opts the page into self-refresh — the
+ * "starting" page re-asks on its own timer, the invalid page never does.
+ */
+export function renderSessionStatusPage(input) {
+    const refresh = input.metaRefreshSeconds !== undefined
+        ? `<meta http-equiv="refresh" content="${input.metaRefreshSeconds}">`
+        : '';
+    const action = input.action !== undefined
+        ? `<a class="btn" href="${input.action.href}">${input.action.label}</a>`
+        : '';
     return `<!DOCTYPE html>
 <html lang="en"><head>
 <meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1">
-<title>Invalid session — Nimbus</title>
+${refresh}
+<title>${input.title} — Nimbus</title>
 <style>
   *{margin:0;padding:0;box-sizing:border-box}
   html,body{height:100%}
@@ -168,8 +200,23 @@ export function renderInvalidSessionHtml(attemptedId) {
   a.btn:hover{filter:brightness(1.1)}
 </style></head>
 <body><div class="card">
-<h1>Invalid session</h1>
-<p>The ID <code>${safe}</code> isn&rsquo;t a valid Nimbus session URL.<br>Launch a new one to get started.</p>
-<a class="btn" href="/">&larr; Back to Nimbus</a>
+<h1>${input.heading}</h1>
+<p>${input.body}</p>
+${action}
 </div></body></html>`;
 }
+/** HTML body for the "invalid session ID" 400 page. Tiny, inline-only. */
+export function renderInvalidSessionHtml(attemptedId) {
+    // Escape the attempted ID for display. We don't use innerHTML anywhere,
+    // but defensive escaping keeps the HTML validator happy and avoids any
+    // future XSS footguns if someone refactors this to document.write().
+    const safe = String(attemptedId).replace(/[&<>"']/g, (c) => ({
+        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    }[c]));
+    return renderSessionStatusPage({
+        title: 'Invalid session',
+        heading: 'Invalid session',
+        body: `The ID <code>${safe}</code> isn&rsquo;t a valid Nimbus session URL.<br>Launch a new one to get started.`,
+        action: { href: '/', label: '&larr; Back to Nimbus' },
+    });
+}

package/dist/esbuild-wasm-bundle.generated.d.ts

@@ -2,7 +2,7 @@
  * esbuild-wasm-bundle.generated.ts — AUTO-GENERATED by scripts/bundle-esbuild-wasm.mjs
  * DO NOT EDIT.
  *
- * Bundled esbuild-wasm 0.24.2 adapter for use inside NimbusLoaderPool
+ * Bundled esbuild-wasm 0.24.2 adapter for use inside NimbusIsolatePool
  * isolates. Only the JS adapter is bundled here (~117 KiB); the wasm
  * binary itself lives in the static-assets layer at
  * public/_assets/esbuild-0.24.2.wasm and is fetched on demand by

package/dist/esbuild-wasm-bundle.generated.js

@@ -2,7 +2,7 @@
  * esbuild-wasm-bundle.generated.ts — AUTO-GENERATED by scripts/bundle-esbuild-wasm.mjs
  * DO NOT EDIT.
  *
- * Bundled esbuild-wasm 0.24.2 adapter for use inside NimbusLoaderPool
+ * Bundled esbuild-wasm 0.24.2 adapter for use inside NimbusIsolatePool
  * isolates. Only the JS adapter is bundled here (~117 KiB); the wasm
  * binary itself lives in the static-assets layer at
  * public/_assets/esbuild-0.24.2.wasm and is fetched on demand by

package/dist/facets/cirrus-real.js

@@ -57,7 +57,7 @@ import { REAL_VITE_VERSION, VITE_CLIENT_MJS, VITE_ENV_MJS, getRealViteBundle, ge
 import { CIRRUS_PLUGIN_REACT_VERSION, getCirrusPluginReactBundle, } from '../cirrus-plugin-react.generated.js';
 import { CIRRUS_NPM_CJS_VERSIONS, getCirrusNpmCjsBundles } from '../cirrus-npm-cjs.generated.js';
 import { CF_COMPAT_DATE } from '@nimbus-sh/core/constants.js';
-import { getCtxExports } from '@nimbus-sh/fabric/ctx-exports.js';
+import { getCtxExports } from '@nimbus-sh/fabric/composition.js';
 import { buildFsSnapshot, generateFsShimModuleCode, generateFsPromisesShimModuleCode, generateSyntheticModuleCode, } from './real-vite-fs-shim.js';
 import { HmrBridge, registerHmrBridge, generateWsShimModuleCode, generateChokidarShimModuleCode, } from './real-vite-hmr.js';
 import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';

package/dist/facets/durable-images.d.ts

@@ -0,0 +1,50 @@
+/**
+ * facets/durable-images.ts — the durable application's boot-image store.
+ *
+ * A durable spawn's journal row carries only digests — the launch's code,
+ * modules, and environment have to live somewhere a reset can still read
+ * them, and that is the kernel-space VFS under `.nimbus/images/<sha256>`,
+ * content-addressed so a re-drive with the same recipe reads the same bytes.
+ *
+ * The store is deliberately separate from the process boot-image sweep in
+ * `image-store.ts`: that sweep is rooted at live pids and would collect an
+ * application's image the moment its process ends — the precise condition a
+ * durable spawn exists to survive. Durable images are kept for the
+ * application's life and released only by explicit removal.
+ *
+ * Two blobs per launch: `runner` is the worker.js source text, `application`
+ * is a JSON payload of `{ modules, env, vfsWasmModules }`. The digests in the
+ * journal's `recipe.image` are sha256 hashes of those two payloads, and a
+ * self-owned spawn mints them at spawn time; an embedder-owned spawn is given
+ * them by its own bookkeeping instead.
+ */
+import type { SqliteVFS } from '@nimbus-sh/core/vfs/sqlite-vfs.js';
+import type { ResidentCodeSpec } from '@nimbus-sh/fabric/process-fabric.js';
+import type { ResolvedWorkerLaunch, WorkerRecipe } from './manager.js';
+/** The directory every durable application's image blobs live under. */
+export declare const DURABLE_IMAGE_DIR = ".nimbus/images";
+/**
+ * Persist a launch's image blobs, minting their digests, for a self-owned
+ * durable spawn. Reads and writes as CRED_KERNEL: the directory is session
+ * kernel data, not user content, and a durable application's images must not
+ * be writable — or deletable — by the user process they belong to.
+ */
+export declare function persistDurableWorkerImage(vfs: SqliteVFS, workerCode: string, payload: {
+    modules: Record<string, string | {
+        wasm: ArrayBuffer;
+    }>;
+    env?: ResidentCodeSpec['env'];
+    vfsWasmModules?: Record<string, string>;
+}): Promise<{
+    runner: string;
+    application: string;
+}>;
+/**
+ * The default resolver a self-owned durable spawn answers through: read the
+ * two blobs the spawn persisted, restore the env, and hand back the launch a
+ * re-drive can boot. Returns null only when an image row has gone missing —
+ * which a re-drive treats as 'the application is gone', exactly as an
+ * embedder-owned launch whose embedder answers null.
+ */
+export declare function resolveDurableWorkerImage(vfs: SqliteVFS, recipe: WorkerRecipe): Promise<ResolvedWorkerLaunch | null>;
+//# sourceMappingURL=durable-images.d.ts.map

package/dist/facets/durable-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-images.d.ts","sourceRoot":"","sources":["../../src/facets/durable-images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEvE,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,mBAAmB,CAAC;AASlD;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,SAAS,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE;IACP,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACxD,GAAG,CAAC,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC,GACA,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAalD;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAwBtC"}

package/dist/facets/durable-images.js

@@ -0,0 +1,75 @@
+/**
+ * facets/durable-images.ts — the durable application's boot-image store.
+ *
+ * A durable spawn's journal row carries only digests — the launch's code,
+ * modules, and environment have to live somewhere a reset can still read
+ * them, and that is the kernel-space VFS under `.nimbus/images/<sha256>`,
+ * content-addressed so a re-drive with the same recipe reads the same bytes.
+ *
+ * The store is deliberately separate from the process boot-image sweep in
+ * `image-store.ts`: that sweep is rooted at live pids and would collect an
+ * application's image the moment its process ends — the precise condition a
+ * durable spawn exists to survive. Durable images are kept for the
+ * application's life and released only by explicit removal.
+ *
+ * Two blobs per launch: `runner` is the worker.js source text, `application`
+ * is a JSON payload of `{ modules, env, vfsWasmModules }`. The digests in the
+ * journal's `recipe.image` are sha256 hashes of those two payloads, and a
+ * self-owned spawn mints them at spawn time; an embedder-owned spawn is given
+ * them by its own bookkeeping instead.
+ */
+import { CRED_KERNEL } from '@nimbus-sh/core/runtime/os-contracts.js';
+/** The directory every durable application's image blobs live under. */
+export const DURABLE_IMAGE_DIR = '.nimbus/images';
+const imagePath = (digest) => `${DURABLE_IMAGE_DIR}/${digest}`;
+async function sha256Hex(text) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Persist a launch's image blobs, minting their digests, for a self-owned
+ * durable spawn. Reads and writes as CRED_KERNEL: the directory is session
+ * kernel data, not user content, and a durable application's images must not
+ * be writable — or deletable — by the user process they belong to.
+ */
+export async function persistDurableWorkerImage(vfs, workerCode, payload) {
+    const kernel = vfs.as(CRED_KERNEL);
+    kernel.mkdir(DURABLE_IMAGE_DIR, { recursive: true });
+    const runner = await sha256Hex(workerCode);
+    kernel.writeFile(imagePath(runner), workerCode);
+    const applicationPayload = JSON.stringify({
+        modules: payload.modules,
+        env: payload.env ?? null,
+        vfsWasmModules: payload.vfsWasmModules ?? null,
+    });
+    const application = await sha256Hex(applicationPayload);
+    kernel.writeFile(imagePath(application), applicationPayload);
+    return { runner, application };
+}
+/**
+ * The default resolver a self-owned durable spawn answers through: read the
+ * two blobs the spawn persisted, restore the env, and hand back the launch a
+ * re-drive can boot. Returns null only when an image row has gone missing —
+ * which a re-drive treats as 'the application is gone', exactly as an
+ * embedder-owned launch whose embedder answers null.
+ */
+export async function resolveDurableWorkerImage(vfs, recipe) {
+    const kernel = vfs.as(CRED_KERNEL);
+    let runnerBytes;
+    let applicationBytes;
+    try {
+        runnerBytes = kernel.readFile(imagePath(recipe.image.runner));
+        applicationBytes = kernel.readFile(imagePath(recipe.image.application));
+    }
+    catch {
+        return null;
+    }
+    const runner = new TextDecoder().decode(runnerBytes);
+    const { modules = {}, env = null, vfsWasmModules = undefined } = JSON.parse(new TextDecoder().decode(applicationBytes));
+    return {
+        env: env ?? null,
+        globalOutbound: undefined,
+        modules: { 'worker.js': runner, ...modules },
+        ...(vfsWasmModules !== null ? { vfsWasmModules } : {}),
+    };
+}

package/dist/facets/durable-slots.d.ts

@@ -0,0 +1,45 @@
+/**
+ * facets/durable-slots.ts — the durable application's facet-name allocator.
+ *
+ * A durable application's storage has to answer under ONE facet name for its
+ * whole life: abort ends the process, not the store, so relaunch and eviction
+ * re-attach the same SQLite — which is only true while the name is stable.
+ * The ephemeral slot book in `workerd-facet-host.ts` cannot supply it: it is
+ * in-memory, and a fresh incarnation restarts `proc-slot-<n>` numbering from
+ * zero, so a durable name needs a store of its own — the DO storage this file
+ * keeps it in.
+ *
+ * The rows:
+ *
+ *   durable-slot:next    — the lowest never-issued slot number. Minting burns
+ *                          one facet ID forever, so a freed name goes to
+ *                          `free`, never back to `next`.
+ *   durable-slot:free    — slot numbers whose applications were removed.
+ *   durable-slot:<owner> — the owner's pinned slot. Written once, ever;
+ *                          re-read on every relaunch and re-drive.
+ *
+ * Names carry the `app-slot-` prefix, disjoint by construction from the
+ * ephemeral book's `proc-slot-` — the two namespaces share the facet-ID
+ * budget, and a collision would hand one application's retained storage to
+ * another process.
+ */
+/** The facet name a durable slot number names. */
+export declare function durableFacetName(slot: number): string;
+/**
+ * The owner's facet name, minted on first call and pinned for the
+ * application's life. The owner key, counter and free list move inside one
+ * transaction, so a concurrent spawn cannot split the claim, and a re-read
+ * after a reset — or after eviction — answers the same name.
+ *
+ * A fresh name records the mint against the lifetime facet-ID ledger so the
+ * budget a durable spawn consumes is counted the same way an ephemeral one's
+ * is.
+ */
+export declare function acquireDurableFacetSlot(ctx: DurableObjectState, owner: string): Promise<string>;
+/**
+ * Hand the owner's slot back to the free list and drop its pin — the last
+ * step of explicit removal, after the facet's SQLite is already gone. Answers
+ * the freed name, or null when the owner held nothing.
+ */
+export declare function freeDurableFacetSlot(ctx: DurableObjectState, owner: string): Promise<string | null>;
+//# sourceMappingURL=durable-slots.d.ts.map

package/dist/facets/durable-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-slots.d.ts","sourceRoot":"","sources":["../../src/facets/durable-slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CA4BjB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYxB"}