@webjsdev/server 0.7.2 → 0.8.0

package/src/module-graph.js

@@ -12,11 +12,33 @@
  */
 
 import { readFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { join, resolve, dirname, extname } from 'node:path';
 
 /** @type {RegExp} match static `import … from '…'` and `import '…'` */
 const IMPORT_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?['"]([^'"]+)['"]/g;
 
+/**
+ * @type {RegExp} match `export … from '…'` re-exports.
+ * Examples:
+ *   export * from './bar';
+ *   export { x } from './bar';
+ *   export { x as y } from './bar';
+ *   export type { T } from './bar';
+ *   export {
+ *     a,
+ *     b,
+ *   } from './bar';     <-- multi-line, very common in real barrel files
+ *
+ * Barrel files are common (`lib/index.ts` re-exports its siblings),
+ * and the graph must follow these edges or downstream consumers of
+ * the barrel see authorisation 404s on the underlying files. The
+ * gap class excludes quotes and `;` (so the lazy match cannot cross
+ * a statement boundary) but DOES allow newlines, so multi-line
+ * brace lists are caught.
+ */
+const EXPORT_FROM_RE = /\bexport\b[^'";]+?\sfrom\s+['"]([^'"]+)['"]/g;
+
 /**
  * @typedef {Map<string, Set<string>>} ModuleGraph
  * A map of absolute file path → Set of absolute file paths it imports.
@@ -40,12 +62,18 @@ export async function buildModuleGraph(appDir) {
  * Entry files themselves are NOT included (they're already preloaded by the
  * boot script).
  *
+ * `skip` files are neither included nor traversed into: used to prune
+ * display-only components (and the subtree reachable only through them)
+ * from preload hints, since their imports are stripped from the served
+ * source and the browser never fetches them.
+ *
  * @param {ModuleGraph} graph
  * @param {string[]} entryFiles  absolute paths
  * @param {string} appDir
+ * @param {Set<string>} [skip]  absolute paths to exclude and not traverse
  * @returns {string[]}  absolute paths of transitive deps
  */
-export function transitiveDeps(graph, entryFiles, appDir) {
+export function transitiveDeps(graph, entryFiles, appDir, skip) {
   /** @type {Set<string>} */
   const visited = new Set(entryFiles);
   /** @type {string[]} */
@@ -59,6 +87,7 @@ export function transitiveDeps(graph, entryFiles, appDir) {
     if (!deps) continue;
     for (const dep of deps) {
       if (visited.has(dep)) continue;
+      if (skip && skip.has(dep)) continue;
       visited.add(dep);
       // Only include files within the app dir (skip node_modules, core, etc.)
       if (dep.startsWith(appDir)) {
@@ -70,6 +99,74 @@ export function transitiveDeps(graph, entryFiles, appDir) {
   return result;
 }
 
+/** @type {RegExp} files the dev server NEVER serves as source: it
+ * returns a stub instead. We stop graph traversal at these boundaries
+ * because the browser never sees their transitive imports anyway. */
+const SERVER_FILE_RE = /\.server\.m?[jt]s$/;
+
+/**
+ * Compute the set of files reachable from a set of browser-entry files.
+ *
+ * Same idea as Next.js's bundler-produced manifest: the static import
+ * graph from each page / layout / error / loading / not-found / component
+ * entry is the authoritative set of "files the browser may legitimately
+ * fetch as ES modules". Anything outside this set is server-only or
+ * unrelated and must not be served over HTTP.
+ *
+ * Result includes the entries themselves PLUS all transitive deps, all
+ * restricted to absolute paths under `appDir`. Files outside `appDir`
+ * (node_modules, @webjsdev/core, vendor URLs) are excluded; those have
+ * their own routing layers (`/__webjs/core/*`, `/__webjs/vendor/*`).
+ *
+ * Traversal stops at `.server.{js,ts,mjs,mts}` files. They ARE in the
+ * result (so a client import like `import { fn } from './x.server.ts'`
+ * resolves to the RPC stub and the gate lets the request through), but
+ * we do not walk INTO them. The browser only ever sees the RPC stub or
+ * the throw-at-load stub for those files, so a non-server file imported
+ * ONLY by a server file is never legitimately requested by the
+ * browser and should stay out of the authorisation set. Matches
+ * Next.js's behaviour, where the bundler emits server-component and
+ * server-action code into separate chunks that the client bundle
+ * never references.
+ *
+ * The dev server uses this as a runtime authorization gate before
+ * serving any `.{js,mjs,ts,mts,css,svg,…}` URL: in-set → served (still
+ * subject to the `.server.{js,ts}` stub guardrail), out-of-set → 404.
+ *
+ * @param {ModuleGraph} graph
+ * @param {string[]} entryFiles absolute paths of browser-bound entries
+ * @param {string} appDir
+ * @returns {Set<string>}
+ */
+export function reachableFromEntries(graph, entryFiles, appDir) {
+  /** @type {Set<string>} */
+  const visited = new Set();
+  /** @type {string[]} */
+  const queue = [];
+  for (const entry of entryFiles) {
+    if (!entry || !entry.startsWith(appDir)) continue;
+    visited.add(entry);
+    queue.push(entry);
+  }
+  while (queue.length) {
+    const file = /** @type {string} */ (queue.shift());
+    // Stop at server-file boundaries. The file itself stays in the
+    // visited set so its URL is servable (yields a stub at request
+    // time), but we don't add its imports because the browser never
+    // sees them.
+    if (SERVER_FILE_RE.test(file)) continue;
+    const deps = graph.get(file);
+    if (!deps) continue;
+    for (const dep of deps) {
+      if (visited.has(dep)) continue;
+      if (!dep.startsWith(appDir)) continue;
+      visited.add(dep);
+      queue.push(dep);
+    }
+  }
+  return visited;
+}
+
 /**
  * Recursively walk a directory, parse imports, and populate the graph.
  * @param {string} dir
@@ -81,7 +178,17 @@ async function walk(dir, appDir, graph) {
   try { entries = await readdir(dir, { withFileTypes: true }); }
   catch { return; }
   for (const e of entries) {
-    if (e.name === 'node_modules' || e.name === '.webjs' || e.name === 'public' || e.name.startsWith('_')) continue;
+    // Skip filesystem locations the browser-bound graph never
+    // touches: node_modules (huge, npm deps reach the browser via
+    // the importmap, not direct fs paths), .webjs (framework cache),
+    // public/ (served by a separate route with its own containment
+    // check). Do NOT skip `_*` dirs: the `_private` / `_components`
+    // / `_lib` convention is a ROUTER-ignore mechanism (router.js
+    // line 100), but files inside are still importable by pages and
+    // layouts, so the graph walker must enter them or the gate
+    // 404s legitimate imports.
+    if (e.name === 'node_modules' || e.name === '.webjs' || e.name === 'public') continue;
+    if (e.name.startsWith('.')) continue;
     const full = join(dir, e.name);
     if (e.isDirectory()) {
       await walk(full, appDir, graph);
@@ -105,12 +212,14 @@ async function parseFile(file, appDir, graph) {
   catch { return; }
 
   const deps = new Set();
-  for (const m of src.matchAll(IMPORT_RE)) {
-    const spec = m[1];
-    // Only resolve relative imports within the project
-    if (!spec.startsWith('.') && !spec.startsWith('/')) continue;
-    const resolved = resolveImport(spec, file, appDir);
-    if (resolved) deps.add(resolved);
+  for (const re of [IMPORT_RE, EXPORT_FROM_RE]) {
+    for (const m of src.matchAll(re)) {
+      const spec = m[1];
+      // Only resolve relative imports within the project.
+      if (!spec.startsWith('.') && !spec.startsWith('/')) continue;
+      const resolved = resolveImport(spec, file, appDir);
+      if (resolved) deps.add(resolved);
+    }
   }
   if (deps.size) graph.set(file, deps);
 }
@@ -124,7 +233,7 @@ async function parseFile(file, appDir, graph) {
  * @param {string} appDir
  * @returns {string | null}
  */
-function resolveImport(spec, fromFile, appDir) {
+export function resolveImport(spec, fromFile, appDir) {
   const base = dirname(fromFile);
   let target;
   if (spec.startsWith('/')) {
@@ -133,9 +242,37 @@ function resolveImport(spec, fromFile, appDir) {
   } else {
     target = resolve(base, spec);
   }
-  // Exact match check: we can't use async `stat` in a sync resolver, so we
-  // store the resolved path optimistically. The graph is advisory (for preload
-  // hints), not load-bearing, so a wrong entry is harmless: the browser will
-  // just get a redundant preload that 404s and is ignored.
+  // Sync exact-then-fallback resolution. The graph is advisory (it
+  // drives preload hints, not module loading), so a wrong entry is
+  // harmless: the browser just gets a redundant preload that 404s.
+  // But emitting a working modulepreload when the user wrote
+  // `import x from './foo'` (no extension) is much better than
+  // leaving the resolver waterfall to discover it lazily, so probe
+  // existsSync for the common fallbacks the JSDoc above promises.
+  if (existsSync(target)) return target;
+  if (!extname(target)) {
+    for (const ext of ['.ts', '.js', '.mts', '.mjs']) {
+      if (existsSync(target + ext)) return target + ext;
+    }
+    for (const ext of ['.ts', '.js']) {
+      const indexed = join(target, 'index' + ext);
+      if (existsSync(indexed)) return indexed;
+    }
+  }
+  // `.js` import maps to a `.ts` sibling: TypeScript's "rewrite to
+  // .js at runtime" convention. The browser asks for the `.js`
+  // path; the dev server's source branch falls through to the
+  // sibling. Mirror that here so the resolved path matches the
+  // file actually on disk (and the authorization gate sees the
+  // same path the request handler resolves to).
+  if (/\.js$/.test(target)) {
+    const tsAbs = target.replace(/\.js$/, '.ts');
+    if (existsSync(tsAbs)) return tsAbs;
+    const mtsAbs = target.replace(/\.js$/, '.mts');
+    if (existsSync(mtsAbs)) return mtsAbs;
+  }
+  // Optimistic fallback: return the original resolution so the graph
+  // still has an entry, even though the path may 404 on the browser.
+  // Matches prior behavior.
   return target;
 }

package/src/rate-limit.js

@@ -31,22 +31,24 @@ import { getStore } from './cache.js';
  *   key?: string | ((req: Request) => string | Promise<string>),
  *   message?: string,
  *   store?: import('./cache.js').CacheStore,
+ *   trustProxy?: boolean,
  * }} opts
  * @returns {(req: Request, next: () => Promise<Response>) => Promise<Response>}
  */
 export function rateLimit(opts = {}) {
   const windowMs = parseWindow(opts.window ?? '1m');
   const max = opts.max ?? 60;
-  const keyFn = typeof opts.key === 'function' ? opts.key : defaultKey;
+  const keyFn = typeof opts.key === 'function' ? opts.key : null;
   const keyPrefix = typeof opts.key === 'string' ? opts.key : '';
   const message = opts.message ?? 'Too Many Requests';
-  // Use the provided store, or fall back to the global cache store -
-  // whatever was set via `setStore()` at app startup (in-memory by default).
+  const trustProxy = opts.trustProxy === true;
+  // Use the provided store, or fall back to the global cache store.
+  // Whatever was set via `setStore()` at app startup (in-memory by default).
   const store = opts.store || null;
 
   return async function rateLimitMiddleware(req, next) {
     const s = store || getStore();
-    const raw = typeof opts.key === 'function' ? await keyFn(req) : defaultKey(req);
+    const raw = keyFn ? await keyFn(req) : clientIp(req, { trustProxy });
     const key = `rl:${keyPrefix}${raw}`;
 
     const count = await s.increment(key, windowMs);
@@ -77,14 +79,100 @@ export function rateLimit(opts = {}) {
   };
 }
 
-/** @param {Request} req */
-function defaultKey(req) {
-  return (
-    req.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
-    req.headers.get('cf-connecting-ip') ||
-    req.headers.get('x-real-ip') ||
-    '_anon_'
-  );
+/**
+ * Header name the framework stamps onto every incoming request with
+ * the TCP socket's remote address. Surfaces the socket IP through the
+ * Web `Request` boundary (which has no `.socket` property of its own).
+ *
+ * `dev.js`'s `toWebRequest` strips any inbound copy of this header
+ * BEFORE adding its own, so clients cannot spoof it from the wire.
+ */
+const REMOTE_IP_HEADER = 'x-webjs-remote-ip';
+
+/**
+ * Resolve the client IP for rate-limit bucket keying.
+ *
+ * `trustProxy: false` (default, safe everywhere): read ONLY the
+ * framework-stamped `x-webjs-remote-ip` header. Under `startServer`
+ * the framework derives it from the actual TCP socket and strips
+ * any inbound copy via `toWebRequest`, so clients cannot spoof it.
+ * Under `createRequestHandler` (embedded use) the host adapter MUST
+ * call `stampRemoteIp(req, remoteAddress)` first, otherwise the
+ * adapter may pass forged inbound headers straight through and the
+ * "cannot spoof" guarantee no longer holds. Forwarded-IP headers
+ * (`x-forwarded-for`, `cf-connecting-ip`, `x-real-ip`) are IGNORED
+ * regardless. Fallback `_anon_` covers requests that arrive without
+ * a stamped IP.
+ *
+ * `trustProxy: true`: honour forwarded-IP headers, preferring the
+ * leftmost entry of `X-Forwarded-For`, then `CF-Connecting-IP`,
+ * then `X-Real-IP`, then the framework-stamped remote IP, then
+ * `_anon_`. Production deploys MUST run behind a reverse proxy that
+ * STRIPS inbound `X-Forwarded-For` before adding its own, otherwise
+ * trust-proxy reintroduces the spoofability this option exists to
+ * defend against.
+ *
+ * @param {Request} req
+ * @param {{ trustProxy?: boolean }} [opts]
+ * @returns {string}
+ */
+export function clientIp(req, opts = {}) {
+  if (opts.trustProxy === true) {
+    return (
+      req.headers.get('x-forwarded-for')?.split(',')[0].trim() ||
+      req.headers.get('cf-connecting-ip') ||
+      req.headers.get('x-real-ip') ||
+      req.headers.get(REMOTE_IP_HEADER) ||
+      '_anon_'
+    );
+  }
+  return req.headers.get(REMOTE_IP_HEADER) || '_anon_';
+}
+
+/**
+ * Return a Request equivalent to `req` but with `x-webjs-remote-ip`
+ * stripped from inbound headers and re-set to `remoteAddress`.
+ *
+ * `startServer`'s built-in HTTP path does this internally via
+ * `toWebRequest`. Embedded adapters (`createRequestHandler` running
+ * under Express / Bun / Deno / edge runtimes) MUST call this helper
+ * before invoking `app.handle(req)`, otherwise a malicious client
+ * can include `x-webjs-remote-ip: <fake>` on the wire and webjs's
+ * rate-limit `clientIp(req)` will trust it.
+ *
+ * Body and method are preserved verbatim. The new Request consumes
+ * the original's body stream, so do not reuse the original afterwards.
+ *
+ * ```js
+ * // express adapter
+ * app.use(async (req, res) => {
+ *   const webReq = new Request(..., { headers: req.headers, ... });
+ *   const safe = stampRemoteIp(webReq, req.socket.remoteAddress);
+ *   const webRes = await handler.handle(safe);
+ *   // write webRes back to res
+ * });
+ * ```
+ *
+ * @param {Request} req
+ * @param {string | null | undefined} remoteAddress  trusted socket IP
+ * @returns {Request}
+ */
+export function stampRemoteIp(req, remoteAddress) {
+  const headers = new Headers(req.headers);
+  headers.delete(REMOTE_IP_HEADER);
+  if (remoteAddress) headers.set(REMOTE_IP_HEADER, remoteAddress);
+  /** @type {RequestInit & { duplex?: string }} */
+  const init = { method: req.method, headers };
+  // Preserve AbortSignal so host-side cancellation propagates
+  // (e.g. client disconnects mid-request). The framework's body
+  // stream has its own teardown, but downstream consumers may
+  // listen on the signal directly.
+  if (req.signal) init.signal = req.signal;
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    init.body = req.body;
+    init.duplex = 'half';
+  }
+  return new Request(req.url, init);
 }
 
 /** @param {number | string} w @returns {number} milliseconds */

package/src/script-tag-json.js

@@ -0,0 +1,63 @@
+/**
+ * JSON serialization safe for interpolation inside an HTML `<script>`
+ * tag body.
+ *
+ * Four escape concerns when JSON ends up inside `<script>...<` + `/script>`:
+ *
+ * 1. The substring `<` + `/` is treated by the HTML parser as a
+ *    script-element close even mid-string. A JSON string value
+ *    containing `<` + `/script>` would close the host tag and let
+ *    arbitrary content after it become regular HTML (or another
+ *    inline script). Escape it to `<\/` (valid in JS strings,
+ *    ignored by HTML parser).
+ *
+ * 2. The HTML5 tokenizer transitions into the "script-data-escaped"
+ *    state when it sees `<!--` inside a script body. From that state
+ *    a subsequent `<script>` (any casing) enters "script-data-double-
+ *    escaped", where `</script>` no longer terminates the host
+ *    element until a matching `-->` is seen. A vendor URL or import
+ *    key containing the right `<!--...<script>...</script>` shape
+ *    could survive escape (1) and still break out of the importmap.
+ *    Escape both `<!--` and `-->` to `<\!--` / `--\>`, which JS
+ *    parses as the same string literals but the HTML tokenizer no
+ *    longer matches as comment-state transitions.
+ *
+ * 3. The Unicode line / paragraph separator code points (U+2028 and
+ *    U+2029) are valid in JSON strings but legacy JavaScript treated
+ *    them as line terminators inside source. Modern JS (ES2019+)
+ *    accepts them, but encoding defensively keeps output compatible
+ *    with older parsers and is what every major framework does.
+ *
+ * Use this anywhere a `JSON.stringify` output is interpolated inside
+ * a `<script>...<` + `/script>` body (importmap content, env shim,
+ * lazy registry, boot module imports).
+ *
+ * Built with String.fromCharCode and constructed RegExp to keep the
+ * source file pure ASCII (no literal U+2028 / U+2029 / script-close).
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+const SCRIPT_CLOSE = '<' + '/';
+const COMMENT_OPEN = '<!--';
+const COMMENT_CLOSE = '-->';
+const LS = String.fromCharCode(0x2028);
+const PS = String.fromCharCode(0x2029);
+const ESCAPE_RE = new RegExp(
+  '<' + '\\/' +
+  '|<!--' +
+  '|-->' +
+  '|[\\u2028\\u2029]',
+  'g',
+);
+
+export function jsonForScriptTag(value) {
+  return JSON.stringify(value).replace(ESCAPE_RE, (ch) => {
+    if (ch === SCRIPT_CLOSE) return '<' + '\\/';
+    if (ch === COMMENT_OPEN) return '<\\!--';
+    if (ch === COMMENT_CLOSE) return '--\\>';
+    if (ch === LS) return '\\u2028';
+    if (ch === PS) return '\\u2029';
+    return ch;
+  });
+}

package/src/session.js

@@ -21,7 +21,44 @@
  */
 
 import { getStore } from './cache.js';
-import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+// -- Web Crypto helpers ------------------------------------------------------
+// Same shape as auth.js. We duplicate here rather than share a module
+// because the helpers are small and the two consumers want different
+// import surfaces.
+
+const enc = new TextEncoder();
+
+/** @param {string} secret @returns {Promise<CryptoKey>} */
+async function hmacKey(secret) {
+  return crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
+}
+
+/** @param {ArrayBuffer | ArrayBufferView} buf @returns {string} */
+function b64url(buf) {
+  let bytes;
+  if (buf instanceof Uint8Array) bytes = buf;
+  else if (buf instanceof ArrayBuffer) bytes = new Uint8Array(buf);
+  else bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** @param {string} str @returns {Uint8Array} */
+function unb64url(str) {
+  const bin = atob(str.replace(/-/g, '+').replace(/_/g, '/'));
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/** Generate a fresh base64url-encoded random 24-byte ID. Sync via Web Crypto. */
+function randomId() {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  return b64url(bytes);
+}
 
 // ---------------------------------------------------------------------------
 // Session class
@@ -46,7 +83,7 @@ export class Session {
    * @param {{ data?: Record<string, unknown>, flash?: Record<string, unknown> }} [initial]
    */
   constructor(id, initial) {
-    this.#id = id || randomBytes(24).toString('base64url');
+    this.#id = id || randomId();
     this.#data = new Map(Object.entries(initial?.data || {}));
     this.#flash = new Map(Object.entries(initial?.flash || {}));
     if (this.#flash.size > 0) this.#dirty = true;
@@ -117,7 +154,7 @@ export class Session {
   regenerateId(deleteOld = false) {
     if (this.#destroyed) throw new Error('Session has been destroyed');
     if (deleteOld) this.#deleteId = this.#id;
-    this.#id = randomBytes(24).toString('base64url');
+    this.#id = randomId();
     this.#dirty = true;
   }
 }
@@ -204,20 +241,29 @@ export const storeSession = storeSessionStorage;
 // Cookie helpers
 // ---------------------------------------------------------------------------
 
-function sign(value, secret) {
-  return `${value}.${createHmac('sha256', secret).update(value).digest('base64url')}`;
+async function sign(value, secret) {
+  const sig = await crypto.subtle.sign('HMAC', await hmacKey(secret), enc.encode(value));
+  return `${value}.${b64url(sig)}`;
 }
 
-function unsign(input, secret) {
+async function unsign(input, secret) {
   const idx = input.lastIndexOf('.');
   if (idx < 1) return null;
   const value = input.slice(0, idx);
-  const expected = createHmac('sha256', secret).update(value).digest('base64url');
-  const sigBuf = Buffer.from(input.slice(idx + 1));
-  const expBuf = Buffer.from(expected);
-  if (sigBuf.length !== expBuf.length) return null;
-  if (!timingSafeEqual(sigBuf, expBuf)) return null;
-  return value;
+  // crypto.subtle.verify is constant-time; replaces node:crypto's
+  // explicit timingSafeEqual. Wrap in try/catch because malformed
+  // base64 throws inside unb64url.
+  try {
+    const ok = await crypto.subtle.verify(
+      'HMAC',
+      await hmacKey(secret),
+      unb64url(input.slice(idx + 1)),
+      enc.encode(value),
+    );
+    return ok ? value : null;
+  } catch {
+    return null;
+  }
 }
 
 function parseCookies(header) {
@@ -284,7 +330,7 @@ export function session(opts = {}) {
   return async function sessionMiddleware(req, next) {
     const cookies = parseCookies(req.headers.get('cookie') || '');
     const rawCookie = cookies[cookieName] || '';
-    const unsigned = rawCookie ? unsign(rawCookie, secret) : null;
+    const unsigned = rawCookie ? await unsign(rawCookie, secret) : null;
 
     // Storage creates the Session
     const s = await storage.read(unsigned);
@@ -303,7 +349,7 @@ export function session(opts = {}) {
     } else if (cookieValue !== null) {
       // Changed: sign and set
       try {
-        resp.headers.append('set-cookie', serializeCookie(cookieName, sign(cookieValue, secret), cookieOpts));
+        resp.headers.append('set-cookie', serializeCookie(cookieName, await sign(cookieValue, secret), cookieOpts));
       } catch {}
     }
     // null = no change