@nimbus-sh/worker 0.1.0

package/dist/_shared/retry.js

@@ -0,0 +1,161 @@
+/**
+ * retry.ts — small, dependency-free retry helper for flaky HTTP GETs.
+ *
+ * The npm path (resolver packument fetches + tarball fetches) talks to
+ * registry.npmjs.org via Cloudflare's edge. Either hop can produce a
+ * transient 5xx — we've seen HTTP 503 on a single tarball out of 456
+ * kill a whole install. npm's client retries 5xx by default; we didn't,
+ * until this file. Any single transient failure across hundreds of
+ * packages = whole install dead.
+ *
+ * Scope:
+ *   - Retries on 5xx (500/502/503/504 especially) and network errors
+ *     (fetch rejection, AbortError timeout, etc.).
+ *   - Does NOT retry on 4xx (those are hard: 404 means the package or
+ *     version genuinely doesn't exist; retrying is wrong and wastes time).
+ *   - Budget: 3 retries with jittered exponential backoff (500/1500/4500 ms
+ *     ±25% jitter). Worst-case added latency per package ≈ 6.5 s in the
+ *     fully-degraded path. Tighter than npm's ~5×60s because dev iteration
+ *     speed matters more than absolute resilience here.
+ *
+ * Intentionally NOT exported to the facet isolate: the facet serializes
+ * its task function via fn.toString() and can't cross a module boundary,
+ * so `src/npm-install-facet.ts` duplicates this retry loop inline inside
+ * `fetchAndStagePackage`. Keep the two in sync if behaviour changes.
+ */
+/** Default retry count AFTER the first attempt (3 = up to 4 total attempts). */
+export const DEFAULT_RETRIES = 3;
+/** Base backoff delays in ms. Index = retry attempt (0-indexed). */
+export const BACKOFF_MS = [500, 1500, 4500];
+/** Jitter ±25% of the base delay, uniformly distributed. */
+export function jittered(baseMs) {
+    const span = baseMs * 0.25;
+    // Math.random is fine here — cryptographic randomness is not required;
+    // the goal is to break up synchronized retries across concurrent fetches
+    // after a shared upstream hiccup.
+    return Math.max(0, Math.round(baseMs + (Math.random() * 2 - 1) * span));
+}
+/** True if an HTTP status should trigger a retry. */
+export function isRetriableStatus(status) {
+    // 5xx only. 429 (Too Many Requests) is arguably retriable too, but
+    // registry.npmjs.org is fronted by Cloudflare which generally rate-
+    // limits per-IP silently rather than with 429, and if we ever DO see
+    // 429 the right handling is Retry-After header honor, which we don't
+    // implement here. Keep the surface minimal.
+    return status >= 500 && status <= 599;
+}
+/**
+ * fetch() wrapper with 5xx + network-error retry and jittered backoff.
+ *
+ * On a 4xx response, returns the Response object as-is (caller decides
+ * whether that's an error). On a 5xx or network-level failure, retries
+ * up to `retries` times with BACKOFF_MS[attempt] ± 25% jitter.
+ *
+ * When retries are exhausted, either:
+ *   - Returns the last (5xx) Response, so the caller can read .status for
+ *     error reporting, OR
+ *   - Re-throws the last network error (caller never sees a Response).
+ *
+ * Callers that previously did `if (!resp.ok) throw ...` retain that shape;
+ * the only change is that transient failures are recovered before the
+ * throw instead of killing the whole install on the first hiccup.
+ */
+export async function retryableFetch(url, init, opts) {
+    const totalRetries = Math.max(0, opts?.retries ?? DEFAULT_RETRIES);
+    const name = opts?.name ?? url;
+    const doFetch = opts?.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    let lastError;
+    let lastResp;
+    for (let attempt = 0; attempt <= totalRetries; attempt++) {
+        // Per-attempt timeout via a fresh AbortController so a single slow
+        // response can't consume the whole retry budget. We merge the caller's
+        // signal (if any) by forwarding its abort to ours.
+        let timer;
+        let attemptInit = init;
+        const perAttemptMs = opts?.perAttemptTimeoutMs;
+        let localController;
+        if (perAttemptMs && perAttemptMs > 0) {
+            localController = new AbortController();
+            timer = setTimeout(() => localController.abort(), perAttemptMs);
+            const callerSignal = init?.signal;
+            if (callerSignal) {
+                if (callerSignal.aborted)
+                    localController.abort();
+                else
+                    callerSignal.addEventListener('abort', () => localController.abort(), { once: true });
+            }
+            attemptInit = { ...(init ?? {}), signal: localController.signal };
+        }
+        try {
+            const resp = await doFetch(url, attemptInit);
+            if (timer)
+                clearTimeout(timer);
+            if (resp.ok || !isRetriableStatus(resp.status)) {
+                // Success or 4xx — don't retry. Return as-is; caller checks .ok.
+                return resp;
+            }
+            // 5xx: drain the body to release the underlying stream.
+            try {
+                await resp.body?.cancel();
+            }
+            catch { /* best-effort */ }
+            lastResp = resp;
+            lastError = undefined;
+            if (attempt === totalRetries) {
+                // Out of retries — return the 5xx Response so the caller can
+                // surface the final status. Caller (e.g. npm-resolver.ts) is
+                // responsible for disposing the stub via Symbol.dispose after
+                // reading status. (Matches the previous !resp.ok throw shape if
+                // the caller checks .ok next.)
+                return resp;
+            }
+            // We're going to retry — dispose the stub NOW so it doesn't leak.
+            //
+            // When `doFetch` is the supervisor's fetch-proxy entrypoint
+            // (src/nimbus-session.ts:1729-1747), `resp` is an RPC stub returned
+            // from `entrypoint.fetch(...)`. Workerd auto-disposes such stubs
+            // only at the end of the enclosing event-handler context — which
+            // for `npm install` means "until the whole install completes".
+            // Cancelling `resp.body` (above) releases the underlying stream
+            // but does NOT release the stub itself. Across an install with N
+            // retries fired, that's N leaked stubs accumulating alongside the
+            // resolver's own per-packument stubs (already disposed in
+            // npm-resolver.ts:307-317). Each leaked stub keeps its server-side
+            // counterpart pinned until the deferred-destruction queue runs at
+            // request end, contributing to the queueState != ACTIVE fatal
+            // documented in WORKERD-CRASH.md.
+            //
+            // Same disposer pattern as src/npm-resolver.ts:312-316.
+            try {
+                const disposerKey = Symbol.dispose;
+                const disposer = disposerKey ? resp?.[disposerKey] : undefined;
+                if (typeof disposer === 'function')
+                    disposer.call(resp);
+            }
+            catch { /* best-effort */ }
+            const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
+            opts?.onRetry?.(attempt + 1, totalRetries, delayMs, `HTTP ${resp.status}`);
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+        catch (e) {
+            if (timer)
+                clearTimeout(timer);
+            // Network-level failure (fetch rejection, timeout via AbortError,
+            // DNS, connection reset). Retry the same way as a 5xx.
+            lastError = e;
+            lastResp = undefined;
+            if (attempt === totalRetries) {
+                throw e;
+            }
+            const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
+            const reason = e?.name === 'AbortError' ? 'timeout' : (e?.message || String(e));
+            opts?.onRetry?.(attempt + 1, totalRetries, delayMs, reason);
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+    }
+    // Unreachable: the loop either returns (on success / non-retriable /
+    // final 5xx) or throws (on final network error).
+    if (lastResp)
+        return lastResp;
+    throw lastError ?? new Error(`retryableFetch: exhausted for ${name}`);
+}

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

@@ -0,0 +1,39 @@
+/**
+ * session-id.ts — Friendly human-readable session identifiers.
+ *
+ * Format: `adjective-noun-NNNN` (e.g. `nimble-otter-4271`).
+ *
+ * Why friendly IDs rather than opaque crypto strings?
+ *   - Shareable over voice/chat without character-by-character dictation.
+ *   - Memorable enough to bookmark a sandbox and return to it.
+ *   - Same UX convention as Vercel preview URLs / StackBlitz sandboxes.
+ *
+ * DO mapping: `env.NIMBUS_SESSION.idFromName(sessionId)` — deterministic.
+ * No backing store required; the session ID IS the key.
+ *
+ * Entropy budget: ~200 adjectives × ~200 nouns × 10,000 numeric suffixes
+ * ≈ 4 × 10⁸ combinations. Birthday-collision probability at 1M live
+ * sessions ≈ 0.12%. Acceptable for v1. If we ever push past that scale,
+ * widen the suffix to 6 digits (≈ 4 × 10¹⁰).
+ *
+ * Validation is strict: lowercase ASCII only, exact shape enforced.
+ * `idFromName` is case-sensitive, so accepting mixed-case would fragment
+ * sessions. Reject anything non-conforming with 400 before touching a DO.
+ */
+/**
+ * Validate a session ID before touching a DO. Returns true iff the string
+ * matches the exact `adjective-noun-NNNN` shape. Length bounds on each part
+ * are deliberately looser than our own word lists so future list growth
+ * doesn't invalidate bookmarked URLs.
+ */
+export declare function isValidSessionId(id: string | null | undefined): boolean;
+/**
+ * Generate a fresh session ID. Uses crypto.getRandomValues for uniform
+ * sampling — NOT Math.random (which on Workers is seeded at isolate start
+ * and can repeat across concurrent requests that share an isolate).
+ *
+ * Suffix is a 4-digit zero-padded decimal (0000–9999), so parseInt can
+ * round-trip it cleanly if anyone ever needs to sort/compare.
+ */
+export declare function generateSessionId(): string;
+//# sourceMappingURL=session-id.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-id.d.ts","sourceRoot":"","sources":["../../src/_shared/session-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAiFH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAIvE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C"}

package/dist/_shared/session-id.js

@@ -0,0 +1,127 @@
+/**
+ * session-id.ts — Friendly human-readable session identifiers.
+ *
+ * Format: `adjective-noun-NNNN` (e.g. `nimble-otter-4271`).
+ *
+ * Why friendly IDs rather than opaque crypto strings?
+ *   - Shareable over voice/chat without character-by-character dictation.
+ *   - Memorable enough to bookmark a sandbox and return to it.
+ *   - Same UX convention as Vercel preview URLs / StackBlitz sandboxes.
+ *
+ * DO mapping: `env.NIMBUS_SESSION.idFromName(sessionId)` — deterministic.
+ * No backing store required; the session ID IS the key.
+ *
+ * Entropy budget: ~200 adjectives × ~200 nouns × 10,000 numeric suffixes
+ * ≈ 4 × 10⁸ combinations. Birthday-collision probability at 1M live
+ * sessions ≈ 0.12%. Acceptable for v1. If we ever push past that scale,
+ * widen the suffix to 6 digits (≈ 4 × 10¹⁰).
+ *
+ * Validation is strict: lowercase ASCII only, exact shape enforced.
+ * `idFromName` is case-sensitive, so accepting mixed-case would fragment
+ * sessions. Reject anything non-conforming with 400 before touching a DO.
+ */
+// Curated single-word adjectives. Lowercase ASCII, no profanity, no numbers,
+// no compounds. Sort order doesn't matter — we index randomly.
+const ADJECTIVES = [
+    'agile', 'alert', 'amber', 'ancient', 'arctic', 'ardent', 'autumn', 'azure',
+    'balmy', 'bashful', 'bitter', 'blissful', 'bold', 'bouncy', 'brave', 'breezy',
+    'bright', 'brisk', 'bronze', 'burly', 'busy', 'calm', 'candid', 'carbon',
+    'cheerful', 'chilly', 'classic', 'clever', 'cloudy', 'coastal', 'cobalt', 'cold',
+    'cool', 'copper', 'cosmic', 'cosy', 'crimson', 'crisp', 'curious', 'daring',
+    'dashing', 'dawn', 'dazzling', 'deep', 'dewy', 'distant', 'divine', 'dotted',
+    'dreamy', 'dry', 'dusty', 'eager', 'early', 'earnest', 'eastern', 'easy',
+    'elated', 'electric', 'elegant', 'emerald', 'endless', 'epic', 'even', 'fair',
+    'fancy', 'faithful', 'faint', 'falling', 'famous', 'fancy', 'fast', 'fearless',
+    'feisty', 'fiery', 'fine', 'firm', 'flat', 'fleeting', 'fluffy', 'flying',
+    'focused', 'fond', 'foggy', 'forgiving', 'frosty', 'gentle', 'giddy', 'glad',
+    'gleaming', 'glowing', 'golden', 'good', 'graceful', 'grand', 'grateful', 'green',
+    'gusty', 'handy', 'happy', 'hardy', 'harmonic', 'hasty', 'hazy', 'healthy',
+    'helpful', 'heroic', 'honest', 'hopeful', 'humble', 'icy', 'idle', 'indigo',
+    'ironclad', 'ivory', 'jade', 'jolly', 'joyful', 'keen', 'kind', 'lively',
+    'loyal', 'lucky', 'lunar', 'merry', 'mighty', 'mild', 'misty', 'modern',
+    'modest', 'mossy', 'muted', 'mystic', 'nimble', 'noble', 'northern', 'noisy',
+    'obsidian', 'orchid', 'patient', 'peachy', 'pearly', 'peppy', 'plucky', 'plum',
+    'polar', 'polite', 'proud', 'pure', 'quick', 'quiet', 'quirky', 'radiant',
+    'rapid', 'rare', 'ready', 'regal', 'resolute', 'rich', 'ripe', 'rosy',
+    'royal', 'ruby', 'rustic', 'sage', 'salty', 'sandy', 'scarlet', 'serene',
+    'sharp', 'shiny', 'silent', 'silken', 'silver', 'simple', 'sleepy', 'sleek',
+    'slender', 'smart', 'smooth', 'snappy', 'snowy', 'solar', 'solemn', 'solid',
+    'sonic', 'spicy', 'spirited', 'spry', 'stable', 'steady', 'stellar', 'steep',
+    'stormy', 'stout', 'sturdy', 'subtle', 'summer', 'sunny', 'super', 'supple',
+    'swift', 'tame', 'tangerine', 'tart', 'tender', 'thankful', 'tidy', 'tiny',
+    'tireless', 'topaz', 'tranquil', 'trusty', 'twilight', 'twinkling', 'upbeat',
+    'valiant', 'velvet', 'vibrant', 'vigilant', 'violet', 'vivid', 'wandering',
+    'warm', 'wary', 'whimsical', 'wild', 'windy', 'winsome', 'witty', 'wise',
+    'woolly', 'youthful', 'zealous', 'zen', 'zesty',
+];
+// Curated single-word concrete nouns (mostly animals + natural features).
+// Avoid anything culturally loaded, branded, or with negative connotations.
+const NOUNS = [
+    'acorn', 'alder', 'anchor', 'aspen', 'aster', 'axis', 'badger', 'bamboo',
+    'basin', 'basil', 'beacon', 'beagle', 'bear', 'beaver', 'beetle', 'birch',
+    'bison', 'blossom', 'bobcat', 'boulder', 'branch', 'breeze', 'briar', 'brook',
+    'bubble', 'buffalo', 'butler', 'cactus', 'camel', 'canyon', 'capybara',
+    'cardinal', 'caribou', 'cascade', 'castle', 'cavern', 'cedar', 'channel',
+    'cheetah', 'cherry', 'chestnut', 'chipmunk', 'cinnamon', 'citrus', 'clam',
+    'cliff', 'clover', 'coast', 'cobra', 'comet', 'coral', 'cosmos', 'cougar',
+    'coyote', 'crane', 'creek', 'crocus', 'crystal', 'cub', 'cypress', 'dahlia',
+    'daisy', 'deer', 'delta', 'diamond', 'dolphin', 'dove', 'dragon', 'dune',
+    'eagle', 'ember', 'emu', 'falcon', 'fawn', 'fennel', 'fern', 'ferret',
+    'finch', 'firefly', 'fjord', 'flame', 'flint', 'foal', 'forest', 'fossil',
+    'fox', 'galaxy', 'garden', 'gazelle', 'gecko', 'geyser', 'gibbon', 'giraffe',
+    'glacier', 'granite', 'grove', 'gull', 'harbor', 'harp', 'harvest', 'hawk',
+    'hedge', 'heron', 'hickory', 'horizon', 'hornet', 'hummingbird', 'husky',
+    'iguana', 'iris', 'island', 'jackal', 'jasmine', 'juniper', 'kestrel',
+    'kingfisher', 'kite', 'koala', 'lagoon', 'lantern', 'lark', 'laurel',
+    'lavender', 'lemur', 'leopard', 'lichen', 'lighthouse', 'lilac', 'lily',
+    'lion', 'llama', 'lobster', 'lotus', 'lynx', 'magnolia', 'mallard', 'mango',
+    'maple', 'marble', 'marlin', 'marmot', 'marsh', 'meadow', 'medallion',
+    'meridian', 'meteor', 'mink', 'mint', 'mist', 'mockingbird', 'moose', 'moss',
+    'mouse', 'mulberry', 'mustang', 'narwhal', 'nebula', 'nectar', 'newt',
+    'nightingale', 'oak', 'oasis', 'ocean', 'ocelot', 'opal', 'orchid', 'oriole',
+    'otter', 'owl', 'oyster', 'palm', 'panda', 'pangolin', 'panther', 'parrot',
+    'peak', 'pebble', 'peony', 'petal', 'phoenix', 'pigeon', 'pine', 'piper',
+    'plateau', 'poppy', 'prairie', 'puffin', 'puma', 'quail', 'quartz', 'quokka',
+    'rabbit', 'raccoon', 'rapids', 'raven', 'reef', 'reindeer', 'ribbon', 'ridge',
+    'river', 'robin', 'rose', 'sable', 'sage', 'salmon', 'sapphire', 'savanna',
+    'seal', 'sequoia', 'shark', 'shrub', 'silo', 'skink', 'sky', 'snail',
+    'snowflake', 'sparrow', 'spider', 'spire', 'spruce', 'squirrel', 'starling',
+    'stingray', 'stone', 'stork', 'stream', 'summit', 'sunflower', 'swan',
+    'swift', 'talon', 'tamarind', 'tapir', 'teal', 'tern', 'thicket', 'thistle',
+    'thrush', 'tiger', 'toad', 'topaz', 'tortoise', 'toucan', 'tree', 'trout',
+    'tulip', 'tundra', 'turtle', 'valley', 'vine', 'violet', 'viper', 'vista',
+    'vole', 'walnut', 'warbler', 'waterfall', 'wave', 'weasel', 'whale', 'wharf',
+    'wheat', 'whippet', 'willow', 'wisp', 'wolf', 'wombat', 'woodland',
+    'woodpecker', 'yak', 'yew', 'zebra', 'zinnia',
+];
+/** Strict shape check. Rejects empty, uppercase, missing-parts, extra-parts. */
+const SESSION_ID_RE = /^[a-z]{3,14}-[a-z]{3,14}-\d{4}$/;
+/**
+ * Validate a session ID before touching a DO. Returns true iff the string
+ * matches the exact `adjective-noun-NNNN` shape. Length bounds on each part
+ * are deliberately looser than our own word lists so future list growth
+ * doesn't invalidate bookmarked URLs.
+ */
+export function isValidSessionId(id) {
+    if (typeof id !== 'string')
+        return false;
+    if (id.length < 9 || id.length > 40)
+        return false;
+    return SESSION_ID_RE.test(id);
+}
+/**
+ * Generate a fresh session ID. Uses crypto.getRandomValues for uniform
+ * sampling — NOT Math.random (which on Workers is seeded at isolate start
+ * and can repeat across concurrent requests that share an isolate).
+ *
+ * Suffix is a 4-digit zero-padded decimal (0000–9999), so parseInt can
+ * round-trip it cleanly if anyone ever needs to sort/compare.
+ */
+export function generateSessionId() {
+    const buf = new Uint32Array(3);
+    crypto.getRandomValues(buf);
+    const adj = ADJECTIVES[buf[0] % ADJECTIVES.length];
+    const noun = NOUNS[buf[1] % NOUNS.length];
+    const num = (buf[2] % 10000).toString().padStart(4, '0');
+    return `${adj}-${noun}-${num}`;
+}

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

@@ -0,0 +1,104 @@
+/**
+ * session-router.ts — Rewrite `/s/<id>/<rest>` → DO-internal `/ <rest>`.
+ *
+ * Nimbus sessions live behind friendly URLs like `/s/nimble-otter-4271/`.
+ * The Worker's fetch handler delegates to this module for anything that
+ * starts with `/s/`. The DO itself remains blissfully ignorant of its
+ * public URL: it sees `/ws`, `/api/*`, `/preview/*`, `/__nimbus/worker/*`
+ * (and the deprecated `/worker/*`), `/port/<n>/*` — the same shape it
+ * did in the single-session era.
+ *
+ * Session identity flows three places:
+ *   1. The DO ID — derived via `env.NIMBUS_SESSION.idFromName(doName)`.
+ *      `doName` is `${tenant}:${sub || '_'}:${sessionId}` when tenant
+ *      scoping is on (JWT verified upstream); falls back to
+ *      `legacy:public:_:${sessionId}` when `NIMBUS_LEGACY_PUBLIC === "1"`
+ *      or `JWT_SECRET` is unset. The fallback preserves the live-demo
+ *      single-tenant behavior while letting third-party embedders enforce
+ *      tenant isolation by default. Caller (the worker fetch handler)
+ *      passes `tenantSegment` in via {@link forwardToSession}.
+ *   2. The `X-Nimbus-Base` request header — set to the URL-prefix the DO
+ *      is mounted at (e.g. `/s/nimble-otter-4271`). ViteDevServer uses
+ *      this to emit correct `<base href>`, module URLs, `import.meta.env
+ *      .BASE_URL`, and router `basename` so the user's React app resolves
+ *      `<NavLink to="/docs">` → `/s/nimble-otter-4271/preview/docs`.
+ *   3. The `X-Nimbus-Tenant` request header — set to the verified
+ *      `${tenant}:${sub}` so downstream RPC handlers can audit cross-
+ *      session multi-tenancy invariants. Optional; never trusted as
+ *      authority (the DO name itself is the trust boundary).
+ *
+ * Why a header instead of the DO auto-detecting?
+ *   - The DO never sees the outer URL (we forward a rewritten Request).
+ *   - Explicit plumbing is easier to test; auto-detect from Referer is
+ *     unreliable (no Referer for API fetches from the xterm shell).
+ *   - Single source of truth: this module owns the `/s/<id>/` mapping.
+ */
+/** Prefix for all session-scoped routes. Centralized for future refactors. */
+export declare const SESSION_ROUTE_PREFIX = "/s";
+/** Header the Worker sets on forwarded requests. The DO reads it. */
+export declare const BASE_PATH_HEADER = "X-Nimbus-Base";
+/**
+ * Header the Worker sets to inform the DO of its tenant scope. The DO
+ * reads it for audit-logging / RPC-routing; it does NOT use it for
+ * authority — the DO instance name is the trust boundary.
+ */
+export declare const TENANT_HEADER = "X-Nimbus-Tenant";
+/**
+ * DO-name segment used when tenant scoping is disabled (legacy-public).
+ * Picked so it cannot collide with a verified token's
+ * `${tn}:${sub || '_'}` (because `legacy` is never a valid `tn` shape
+ * starting with that exact prefix-then-colon when JWT_SECRET is set).
+ */
+export declare const LEGACY_PUBLIC_DO_SEGMENT = "legacy:public:_";
+export interface ParsedSessionRoute {
+    /** Session ID portion (unverified until `isValidSessionId` check). */
+    sessionId: string;
+    /** Inner path the DO should see, starting with "/" (e.g. "/ws", "/api/stats"). */
+    innerPath: string;
+    /** Public URL prefix the DO is mounted at (e.g. "/s/nimble-otter-4271"). */
+    basePath: string;
+}
+/**
+ * Attempt to parse a URL pathname as a session route.
+ * Returns null if the pathname doesn't start with `/s/<something>`.
+ *
+ * Does NOT validate session ID shape — callers do that next so they can
+ * emit a specific 400 (bad ID) vs continuing with a 404 fall-through.
+ */
+export declare function parseSessionRoute(pathname: string): ParsedSessionRoute | null;
+/**
+ * Options for {@link forwardToSession}.
+ *
+ * `tenantSegment` is the verified `${tn}:${sub || '_'}` from JWT, or
+ * {@link LEGACY_PUBLIC_DO_SEGMENT} when running in legacy-public mode.
+ * The worker fetch handler computes this BEFORE calling this function
+ * — the router itself does not parse tokens.
+ */
+export interface ForwardOptions {
+    /** Verified tenant segment for DO naming. */
+    tenantSegment: string;
+}
+/**
+ * Forward a request to the session's DO.
+ *
+ * Contract:
+ *   - Caller has already validated the session ID (or tolerates whatever
+ *     DO spawns if they didn't — still safe, but malformed IDs should be
+ *     rejected upstream with 400).
+ *   - Caller has already verified the token (or chosen legacy-public).
+ *     We trust `opts.tenantSegment` verbatim.
+ *   - Original request's method, body, and headers are preserved.
+ *   - `X-Nimbus-Base` is injected so the DO can thread it into ViteDevServer.
+ *   - `X-Nimbus-Tenant` is injected for audit/observability (NOT authority).
+ *   - WebSocket upgrades flow naturally: `stub.fetch()` returns a Response
+ *     with a `webSocket` field and status 101, which workerd passes through.
+ *
+ * @param request The inbound Request. Method/body/headers preserved.
+ * @param route Output of {@link parseSessionRoute}.
+ * @param env Bindings env. Must carry `NIMBUS_SESSION` DO namespace.
+ * @param opts Tenant scoping. See {@link ForwardOptions}.
+ */
+export declare function forwardToSession(request: Request, route: ParsedSessionRoute, env: any, opts: ForwardOptions): Promise<Response>;
+/** 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

@@ -0,0 +1 @@
+{"version":3,"file":"session-router.d.ts","sourceRoot":"","sources":["../../src/_shared/session-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,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;;;;;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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,QAAQ,CAAC,CAoCnB;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA6BpE"}

package/dist/_shared/session-router.js

@@ -0,0 +1,165 @@
+/**
+ * session-router.ts — Rewrite `/s/<id>/<rest>` → DO-internal `/ <rest>`.
+ *
+ * Nimbus sessions live behind friendly URLs like `/s/nimble-otter-4271/`.
+ * The Worker's fetch handler delegates to this module for anything that
+ * starts with `/s/`. The DO itself remains blissfully ignorant of its
+ * public URL: it sees `/ws`, `/api/*`, `/preview/*`, `/__nimbus/worker/*`
+ * (and the deprecated `/worker/*`), `/port/<n>/*` — the same shape it
+ * did in the single-session era.
+ *
+ * Session identity flows three places:
+ *   1. The DO ID — derived via `env.NIMBUS_SESSION.idFromName(doName)`.
+ *      `doName` is `${tenant}:${sub || '_'}:${sessionId}` when tenant
+ *      scoping is on (JWT verified upstream); falls back to
+ *      `legacy:public:_:${sessionId}` when `NIMBUS_LEGACY_PUBLIC === "1"`
+ *      or `JWT_SECRET` is unset. The fallback preserves the live-demo
+ *      single-tenant behavior while letting third-party embedders enforce
+ *      tenant isolation by default. Caller (the worker fetch handler)
+ *      passes `tenantSegment` in via {@link forwardToSession}.
+ *   2. The `X-Nimbus-Base` request header — set to the URL-prefix the DO
+ *      is mounted at (e.g. `/s/nimble-otter-4271`). ViteDevServer uses
+ *      this to emit correct `<base href>`, module URLs, `import.meta.env
+ *      .BASE_URL`, and router `basename` so the user's React app resolves
+ *      `<NavLink to="/docs">` → `/s/nimble-otter-4271/preview/docs`.
+ *   3. The `X-Nimbus-Tenant` request header — set to the verified
+ *      `${tenant}:${sub}` so downstream RPC handlers can audit cross-
+ *      session multi-tenancy invariants. Optional; never trusted as
+ *      authority (the DO name itself is the trust boundary).
+ *
+ * Why a header instead of the DO auto-detecting?
+ *   - The DO never sees the outer URL (we forward a rewritten Request).
+ *   - Explicit plumbing is easier to test; auto-detect from Referer is
+ *     unreliable (no Referer for API fetches from the xterm shell).
+ *   - Single source of truth: this module owns the `/s/<id>/` mapping.
+ */
+/** Prefix for all session-scoped routes. Centralized for future refactors. */
+export const SESSION_ROUTE_PREFIX = '/s';
+/** Header the Worker sets on forwarded requests. The DO reads it. */
+export const BASE_PATH_HEADER = 'X-Nimbus-Base';
+/**
+ * Header the Worker sets to inform the DO of its tenant scope. The DO
+ * reads it for audit-logging / RPC-routing; it does NOT use it for
+ * authority — the DO instance name is the trust boundary.
+ */
+export const TENANT_HEADER = 'X-Nimbus-Tenant';
+/**
+ * DO-name segment used when tenant scoping is disabled (legacy-public).
+ * Picked so it cannot collide with a verified token's
+ * `${tn}:${sub || '_'}` (because `legacy` is never a valid `tn` shape
+ * starting with that exact prefix-then-colon when JWT_SECRET is set).
+ */
+export const LEGACY_PUBLIC_DO_SEGMENT = 'legacy:public:_';
+/**
+ * Match `/s/<id>(/<rest>)?` with `<id>` being ANY lowercase-letters-digits-
+ * dashes token. Shape validation happens in a second step so we can return
+ * a specific 400 for malformed IDs (vs falling through to the Worker's 404).
+ */
+const SESSION_PATH_RE = /^\/s\/([^\/]+)(\/.*)?$/;
+/**
+ * Attempt to parse a URL pathname as a session route.
+ * Returns null if the pathname doesn't start with `/s/<something>`.
+ *
+ * Does NOT validate session ID shape — callers do that next so they can
+ * emit a specific 400 (bad ID) vs continuing with a 404 fall-through.
+ */
+export function parseSessionRoute(pathname) {
+    const m = pathname.match(SESSION_PATH_RE);
+    if (!m)
+        return null;
+    const sessionId = m[1];
+    // Ensure inner path starts with "/" and defaults to "/" for `/s/<id>`
+    // (no trailing slash). This matches how the DO's existing handlers
+    // distinguish `/preview` from `/preview/` — both reach the same code.
+    const innerPath = m[2] && m[2].length > 0 ? m[2] : '/';
+    return {
+        sessionId,
+        innerPath,
+        basePath: `${SESSION_ROUTE_PREFIX}/${sessionId}`,
+    };
+}
+/**
+ * Forward a request to the session's DO.
+ *
+ * Contract:
+ *   - Caller has already validated the session ID (or tolerates whatever
+ *     DO spawns if they didn't — still safe, but malformed IDs should be
+ *     rejected upstream with 400).
+ *   - Caller has already verified the token (or chosen legacy-public).
+ *     We trust `opts.tenantSegment` verbatim.
+ *   - Original request's method, body, and headers are preserved.
+ *   - `X-Nimbus-Base` is injected so the DO can thread it into ViteDevServer.
+ *   - `X-Nimbus-Tenant` is injected for audit/observability (NOT authority).
+ *   - WebSocket upgrades flow naturally: `stub.fetch()` returns a Response
+ *     with a `webSocket` field and status 101, which workerd passes through.
+ *
+ * @param request The inbound Request. Method/body/headers preserved.
+ * @param route Output of {@link parseSessionRoute}.
+ * @param env Bindings env. Must carry `NIMBUS_SESSION` DO namespace.
+ * @param opts Tenant scoping. See {@link ForwardOptions}.
+ */
+export function forwardToSession(request, route, env, opts) {
+    const url = new URL(request.url);
+    // Rebuild the URL the DO will see: same origin, inner path, preserved query.
+    const innerUrl = new URL(route.innerPath + url.search + url.hash, url.origin);
+    // Clone headers and set the X-Nimbus-* metadata. We can't mutate the
+    // original Request's headers directly (they're immutable on a real Request).
+    const headers = new Headers(request.headers);
+    headers.set(BASE_PATH_HEADER, route.basePath);
+    headers.set(TENANT_HEADER, opts.tenantSegment);
+    // Defense in depth: strip any user-supplied `nimbus_token` query param
+    // BEFORE forwarding so it doesn't end up in inner-DO logs / referrers.
+    // The DO has its own header-based auth model post-router (none today,
+    // but this future-proofs the surface).
+    innerUrl.searchParams.delete('nimbus_token');
+    // Build the forwarded Request. Preserve body + method. For GETs/HEADs,
+    // body is undefined (Request constructor rejects bodies there anyway).
+    const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+    const inner = new Request(innerUrl.toString(), {
+        method: request.method,
+        headers,
+        body: hasBody ? request.body : undefined,
+        // Preserve WS upgrade. Workerd needs the Upgrade header to stay put;
+        // copying via new Headers(...) does preserve it.
+        redirect: 'manual',
+    });
+    // Tenant-scoped DO instance name. `tenantSegment` is `${tn}:${sub||'_'}`
+    // (verified token) or `legacy:public:_` (legacy mode). Either way, the
+    // sessionId is appended — different tenants get different DOs even with
+    // the same sessionId in the URL.
+    const doName = `${opts.tenantSegment}:${route.sessionId}`;
+    const id = env.NIMBUS_SESSION.idFromName(doName);
+    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]));
+    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>
+<style>
+  *{margin:0;padding:0;box-sizing:border-box}
+  html,body{height:100%}
+  body{background:#0a0a0a;color:#e6edf3;font:15px/1.6 ui-sans-serif,-apple-system,"Segoe UI",sans-serif;
+       display:flex;align-items:center;justify-content:center;padding:24px;
+       background-image:radial-gradient(700px 400px at 50% -10%,rgba(100,255,218,0.05),transparent 60%)}
+  .card{max-width:520px;text-align:center}
+  h1{font-size:28px;color:#64ffda;margin-bottom:12px;font-family:ui-monospace,Menlo,monospace}
+  p{color:#8b949e;margin-bottom:24px}
+  code{font-family:ui-monospace,Menlo,monospace;background:#111;padding:2px 8px;border-radius:4px;color:#e6edf3}
+  a.btn{display:inline-block;background:#64ffda;color:#000;font-weight:700;padding:10px 22px;border-radius:6px;text-decoration:none}
+  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>
+</div></body></html>`;
+}