@nimbus-sh/worker 0.4.0 → 0.6.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

@@ -10,13 +10,37 @@
  * `buildPreviewHost` and `parsePreviewHost` are exact inverses: every
  * `(sid, port)` has exactly ONE valid origin. Without that bijection a cookie
  * set on the canonical host is missing from an equivalent-but-different one.
+ *
+ * The middle label may be a NAME instead of a port — `<name>--<sid>` and
+ * `<cap>--<name>--<sid>` — for an application whose reservation carries a
+ * name alias. A numeric label is a port; anything else that is a DNS label
+ * is a name. The scoped name form is resolved to a port inside the session
+ * (its reservation records); the public name form through the directory.
  */
 export interface PreviewHost {
-    port: number;
+    /** The port, on the port forms. Absent on a name form — the name resolves to it. */
+    port?: number;
+    /** The name alias, on the name forms `<name>--<sid>` / `<cap>--<name>--<sid>`. */
+    name?: string;
     sid: string;
+    /**
+     * Present only on the public capability forms `<cap>--<port>--<sid>` and
+     * `<cap>--<name>--<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;
 }
+/** `<port>--<sid>` or `<name>--<sid>`: the middle label is a port number or a name alias. */
+export declare function buildPreviewHost(sid: string, target: number | string, suffix: string): string;
+/**
+ * `<capability>--<port|name>--<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, target: number | string, capability: string, suffix: string): string;
 export declare function isPreviewHostSafeSid(sid: string): boolean;
-export declare function buildPreviewHost(sid: string, port: number, suffix: string): string;
 /**
  * Read the configured preview-host suffix out of a bindings env.
  *
@@ -26,6 +50,13 @@ export declare function buildPreviewHost(sid: string, port: number, suffix: stri
  */
 export declare function readPreviewHostSuffix(env: unknown): string | null;
 export declare function parsePreviewHost(host: string, suffix: string | undefined | null): PreviewHost | null;
+/**
+ * A name label: a DNS label that is neither a port (all digits) nor a
+ * capability (24 lowercase hex), and contains no `--` host-label separator.
+ * The same rule the session applies when it stores a
+ * name on a reservation, so every name it accepts is a host it can parse.
+ */
+export declare function isPreviewHostName(label: string): boolean;
 /**
  * True when `url` addresses a port preview. Embedders MUST test this BEFORE
  * their own route table: a preview host serves untrusted user code at the

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;;;;;;;;;;;;;;;;;;GAkBG;AAkBH,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,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,CA8CpB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKxD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAEpE"}

package/dist/_shared/preview-host.js

@@ -10,18 +10,43 @@
  * `buildPreviewHost` and `parsePreviewHost` are exact inverses: every
  * `(sid, port)` has exactly ONE valid origin. Without that bijection a cookie
  * set on the canonical host is missing from an equivalent-but-different one.
+ *
+ * The middle label may be a NAME instead of a port — `<name>--<sid>` and
+ * `<cap>--<name>--<sid>` — for an application whose reservation carries a
+ * name alias. A numeric label is a port; anything else that is a DNS label
+ * is a name. The scoped name form is resolved to a port inside the session
+ * (its reservation records); the public name form through the directory.
  */
 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 scoped name form: a non-numeric DNS label in the port's place. */
+const PREVIEW_NAME_HOST_LABEL_RE = /^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)--([a-z0-9-]{1,63})$/;
+// 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})$/;
+/** The public name form: the capability names the session in the directory, the name is verified there. */
+const PREVIEW_CAPABILITY_NAME_HOST_LABEL_RE = /^([a-f0-9]{24})--([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)--([a-z0-9-]{1,63})$/;
 /** Binding that carries the deployment's preview-host suffix. */
 const PREVIEW_HOST_SUFFIX_BINDING = 'NIMBUS_PREVIEW_HOST_SUFFIX';
+/** `<port>--<sid>` or `<name>--<sid>`: the middle label is a port number or a name alias. */
+export function buildPreviewHost(sid, target, suffix) {
+    return `${target}--${sid}.${suffix}`;
+}
+/**
+ * `<capability>--<port|name>--<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, target, capability, suffix) {
+    return `${capability}--${target}--${sid}.${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}`;
-}
 /**
  * Read the configured preview-host suffix out of a bindings env.
  *
@@ -46,14 +71,54 @@ 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 capabilityNameMatch = label.match(PREVIEW_CAPABILITY_NAME_HOST_LABEL_RE);
+    if (capabilityNameMatch) {
+        const capability = capabilityNameMatch[1];
+        const name = capabilityNameMatch[2];
+        const sid = capabilityNameMatch[4];
+        if (!isPreviewHostName(name) || !isPreviewHostSafeSid(sid))
+            return null;
+        return { name, sid, capability };
+    }
     const match = label.match(PREVIEW_HOST_LABEL_RE);
-    if (!match)
+    if (match) {
+        const port = Number(match[1]);
+        const sid = match[2];
+        if (port < 1 || port > 65535 || !isPreviewHostSafeSid(sid))
+            return null;
+        return { port, sid };
+    }
+    const nameMatch = label.match(PREVIEW_NAME_HOST_LABEL_RE);
+    if (!nameMatch)
         return null;
-    const port = Number(match[1]);
-    const sid = match[2];
-    if (port < 1 || port > 65535 || !isPreviewHostSafeSid(sid))
+    const name = nameMatch[1];
+    const sid = nameMatch[3];
+    if (!isPreviewHostName(name) || !isPreviewHostSafeSid(sid))
         return null;
-    return { port, sid };
+    return { name, sid };
+}
+/**
+ * A name label: a DNS label that is neither a port (all digits) nor a
+ * capability (24 lowercase hex), and contains no `--` host-label separator.
+ * The same rule the session applies when it stores a
+ * name on a reservation, so every name it accepts is a host it can parse.
+ */
+export function isPreviewHostName(label) {
+    return /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(label)
+        && !label.includes('--')
+        && !/^\d+$/.test(label)
+        && !/^[a-f0-9]{24}$/.test(label);
 }
 /**
  * True when `url` addresses a port preview. Embedders MUST test this BEFORE

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/facets/durable-images.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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";
+/** Remove only the owner's blobs that no other retained recipe references. */
+export declare function purgeDurableWorkerImages(vfs: SqliteVFS, owned: Iterable<{
+    runner: string;
+    application: string;
+}>, retained: Iterable<{
+    runner: string;
+    application: string;
+}>): number;
+/**
+ * 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>;
+    startArgs?: unknown;
+}): 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;AAIlD,8EAA8E;AAC9E,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,EACxD,QAAQ,EAAE,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1D,MAAM,CAaR;AAOD;;;;;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;IACxC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GACA,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAclD;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA0BtC"}

package/dist/facets/durable-images.js

@@ -0,0 +1,94 @@
+/**
+ * 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}`;
+/** Remove only the owner's blobs that no other retained recipe references. */
+export function purgeDurableWorkerImages(vfs, owned, retained) {
+    const keep = new Set([...retained].flatMap((image) => [image.runner, image.application]));
+    const candidates = new Set([...owned].flatMap((image) => [image.runner, image.application]));
+    const kernel = vfs.as(CRED_KERNEL);
+    let removed = 0;
+    for (const digest of candidates) {
+        if (keep.has(digest) || !/^[a-f0-9]{64}$/.test(digest))
+            continue;
+        const path = imagePath(digest);
+        if (!kernel.exists(path))
+            continue;
+        kernel.unlink(path);
+        removed += 1;
+    }
+    return removed;
+}
+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,
+        ...(payload.startArgs !== undefined ? { startArgs: payload.startArgs } : {}),
+    });
+    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, startArgs } = JSON.parse(new TextDecoder().decode(applicationBytes));
+    return {
+        env: env ?? null,
+        globalOutbound: undefined,
+        modules: { 'worker.js': runner, ...modules },
+        ...(startArgs !== undefined ? { startArgs } : {}),
+        ...(vfsWasmModules !== null ? { vfsWasmModules } : {}),
+    };
+}