@webjsdev/server 0.9.0 → 0.10.0

package/index.js

@@ -2,7 +2,7 @@ export { startServer, createRequestHandler } from './src/dev.js';
 export { assertNodeVersion, checkNodeVersion, requiredNodeMajor, parseMajor, parseRequiredMajor } from './src/node-version.js';
 export { validateEnv, formatEnvErrors, loadEnvSchema, applyEnvValidation } from './src/env-schema.js';
 export { setOnError, runInstrumentation } from './src/instrumentation.js';
-export { buildRouteTable, matchPage, matchApi } from './src/router.js';
+export { buildRouteTable, matchPage, matchApi, staticPageRoutes } from './src/router.js';
 export { generateRouteTypes } from './src/route-types.js';
 export { ssrPage, ssrNotFound } from './src/ssr.js';
 export { handleApi } from './src/api.js';
@@ -43,9 +43,8 @@ export {
 } from './src/vendor.js';
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
-export { analyzeAppElision } from './src/elision-report.js';
+export { analyzeRouteModules } from './src/route-report.js';
 export { regenerateOutputs, regenerateStatus } from './src/dev-regenerate.js';
-export { maskJsSet, staticPageRoutes } from './src/elision-differential.js';
 export { headers, cookies, getRequest, withRequest, cspNonce, requestId } from './src/context.js';
 export { defaultLogger } from './src/logger.js';
 export { rateLimit, parseWindow, clientIp, stampRemoteIp } from './src/rate-limit.js';
@@ -65,8 +64,13 @@ export { stream, streamResponse, acceptsStream, STREAM_MIME } from './src/stream
 export { attachWebSocket } from './src/websocket.js';
 export { getSerializer, setSerializer, defaultSerializer } from './src/serializer.js';
 
+// Next.js's navigation helpers (`next/navigation`), the same functions
+// `@webjsdev/core` exports, so a server action or route handler can import
+// them from the server package as well. (#1686)
+export { notFound, forbidden, unauthorized, redirect, permanentRedirect } from '@webjsdev/core';
+
 // Auth (NextAuth-style)
-export { createAuth, Credentials, Google, GitHub } from './src/auth.js';
+export { createAuth, Credentials, Google, GitHub, AuthError, CredentialsSignin } from './src/auth.js';
 
 // Test harness helpers (issue #267): thin builders over handle()
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "The server for WebJs, a full-stack JavaScript framework built on web components with server-side rendering and no build step. Provides the file-based router, SSR, server actions, route handlers, middleware, and live reload on Node 24+ or Bun.",
   "main": "index.js",
@@ -55,9 +55,9 @@
     "amaro": "^1.1.10"
   },
   "peerDependencies": {
-    "@webjsdev/core": "^0.8.0"
+    "@webjsdev/core": "^0.9.0"
   },
   "devDependencies": {
-    "@webjsdev/core": "^0.8.0"
+    "@webjsdev/core": "^0.9.0"
   }
 }

package/src/action-flash.js

@@ -0,0 +1,185 @@
+/**
+ * The form-action flash: what a form-bound server action returned, carried
+ * across the 303 that answers a successful submission, so the page it lands
+ * on still sees the result (`actionData`), and the NEXT submission of the same
+ * action receives it as `prevState` (Next.js's `useActionState(action,
+ * initial)` contract, `(prevState, formData) => newState`).
+ *
+ * The carrier is one cookie, `__webjs_flash`: HttpOnly, SameSite=Lax, 60
+ * seconds, HMAC-signed (so a visitor cannot forge a `prevState`), capped at
+ * 2 KB (a larger result is simply not carried; the action's own redirect
+ * still happens). The payload is the rich-serialized result (minus its
+ * `redirect`), the action's `<hash>/<fn>` identity, and whether a page has
+ * already displayed it: a result is shown ONCE as `actionData`, then kept
+ * only as the next `prevState`.
+ *
+ * Key: `WEBJS_SECRET`, else `AUTH_SECRET`, else `SESSION_SECRET`, else (in
+ * development and tests) the persisted dev secret, else a random per-process key (so a
+ * flash still works on one instance; a multi-instance deploy sets a secret).
+ *
+ * @module action-flash
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { stringify, parse } from '@webjsdev/core';
+import { shared } from './process-shared.js';
+import { devSecret, devSecretApplies } from './dev-secret.js';
+import { stripBasePath } from './base-path.js';
+
+export const FLASH_COOKIE = '__webjs_flash';
+const MAX_BYTES = 2048;
+const MAX_AGE_SECONDS = 60;
+
+const _key = shared('action-flash-key', () => ({ random: randomBytes(32).toString('hex'), warned: false, dev: /** @type {string | undefined | null} */ (null) }));
+
+function key() {
+  // Any secret the app already set signs it, and in development and tests the
+  // persisted dev secret does, so a flash survives a dev server restart too.
+  const set = process.env.WEBJS_SECRET || process.env.AUTH_SECRET || process.env.SESSION_SECRET;
+  if (set) return set;
+  // Whether the dev secret applies is decided on every call, as devSecret
+  // decides it, so a flash signed before NODE_ENV was set does not pin the
+  // random key for the rest of the process. Only a secret it RETURNS is kept:
+  // it is a file, and a sign and its verify must use one key even when .webjs
+  // cannot be written (devSecret then makes a new one per call).
+  if (devSecretApplies()) {
+    if (!_key.dev) _key.dev = devSecret('WEBJS_SECRET') || null;
+    if (_key.dev) return _key.dev;
+  }
+  // A per-process key verifies only on the instance that signed it, so behind
+  // a load balancer a flash whose 303 lands elsewhere is silently dropped. Say
+  // so once in production rather than let it look like a missing feature.
+  if (process.env.NODE_ENV === 'production' && !_key.warned) {
+    _key.warned = true;
+    console.warn('[webjs] none of WEBJS_SECRET, AUTH_SECRET or SESSION_SECRET is set, so form action results (actionData after a redirect, prevState) are signed with a per-process key and are lost when the redirect lands on another instance. Set any one of them.');
+  }
+  return _key.random;
+}
+
+/**
+ * HMAC of a flash body. The input is prefixed so the signature is unrelated by
+ * construction to any other HMAC made with the same secret (`AUTH_SECRET` also
+ * signs the session), whatever either format becomes.
+ * @param {string} s
+ */
+function sign(s) {
+  return createHmac('sha256', key()).update(`webjs-flash:${s}`).digest('base64url');
+}
+
+/**
+ * `path` is the page the success redirect lands on: only that page shows it.
+ * @typedef {{ id: string, result: unknown, shown: boolean, path?: string }} Flash
+ */
+
+/**
+ * Encode a flash as a cookie value, or null when it does not fit the cap.
+ * @param {Flash} flash
+ * @returns {Promise<string | null>}
+ */
+export async function encodeFlash(flash) {
+  let result = flash.result;
+  if (result && typeof result === 'object' && !Array.isArray(result) && 'redirect' in result) {
+    const { redirect: _drop, ...rest } = /** @type {Record<string, unknown>} */ (result);
+    result = rest;
+  }
+  let body;
+  try {
+    body = Buffer.from(JSON.stringify({ a: flash.id, s: flash.shown ? 1 : 0, ...(flash.path ? { p: flash.path } : {}), r: await stringify(result ?? null) })).toString('base64url');
+  } catch {
+    return null; // unserializable result: nothing to carry
+  }
+  const value = `${body}.${sign(body)}`;
+  return value.length > MAX_BYTES ? null : value;
+}
+
+/**
+ * Decode and verify a flash cookie value; null when absent, forged, or broken.
+ * @param {string | undefined | null} value
+ * @returns {Promise<Flash | null>}
+ */
+export async function decodeFlash(value) {
+  if (!value || typeof value !== 'string') return null;
+  const dot = value.lastIndexOf('.');
+  if (dot <= 0) return null;
+  const body = value.slice(0, dot);
+  const mac = Buffer.from(value.slice(dot + 1));
+  const want = Buffer.from(sign(body));
+  if (mac.length !== want.length || !timingSafeEqual(mac, want)) return null;
+  try {
+    const o = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+    if (!o || typeof o.a !== 'string' || typeof o.r !== 'string') return null;
+    return { id: o.a, shown: o.s === 1, ...(typeof o.p === 'string' ? { path: o.p } : {}), result: parse(o.r) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `Set-Cookie` value that stores a flash (or clears it with null).
+ * @param {string | null} value
+ */
+export function flashSetCookie(value) {
+  return value
+    ? `${FLASH_COOKIE}=${value}; Path=/; Max-Age=${MAX_AGE_SECONDS}; HttpOnly; SameSite=Lax`
+    : `${FLASH_COOKIE}=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax`;
+}
+
+/**
+ * Read the flash cookie off a request.
+ * @param {Request | undefined | null} req
+ * @returns {Promise<Flash | null>}
+ */
+export async function readFlash(req) {
+  const header = req && req.headers.get('cookie');
+  if (!header || !header.includes(FLASH_COOKIE)) return null;
+  const m = new RegExp(`(?:^|;\\s*)${FLASH_COOKIE}=([^;]*)`).exec(header);
+  return m ? decodeFlash(m[1]) : null;
+}
+
+/** A path without its trailing slash (the root stays "/"). @param {string} p */
+const trimSlash = (p) => (p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p);
+
+/**
+ * The app-root-relative form of a path: the `webjs.basePath` mount prefix
+ * removed when the path is under it (a redirect target may be written with or
+ * without it), else the path as is.
+ * @param {string} pathname
+ * @param {string} mount
+ */
+export function appRelativePath(pathname, mount) {
+  return (mount && stripBasePath(pathname, mount)) || pathname;
+}
+
+/**
+ * Retire an unshown flash when the page it is bound to answers a redirect
+ * instead of rendering (#1686). The result belongs to the page the success
+ * redirect named; when that page sends the visitor on to ANOTHER page (a
+ * sign-in check, a redirects rule, middleware), nothing shows it, as a
+ * redirect after an action
+ * discards its state in Next.js. Following the redirect instead would put the
+ * result on whatever page the chain ends on, a sign-in page included. The
+ * flash is marked shown, so it stays the next submission's `prevState` (as a
+ * 422's does) and is never displayed later. A redirect to the same page (the
+ * trailing-slash policy answering /done/ with /done) is not one away, so it
+ * leaves the flash for the page; a speculative prefetch leaves it too.
+ * Mutates `res.headers`; a no-op for anything else.
+ * @param {Request} req
+ * @param {Response} res
+ * @param {string} mount the app's `webjs.basePath` ('' when none)
+ */
+export async function retireFlashOnRedirect(req, res, mount) {
+  if (res.status < 300 || res.status >= 400) return;
+  if (req.headers.get('x-webjs-prefetch') === '1') return;
+  const flash = await readFlash(req);
+  if (!flash || flash.shown || !flash.path) return;
+  const from = new URL(req.url);
+  const bound = trimSlash(flash.path);
+  if (trimSlash(appRelativePath(from.pathname, mount)) !== bound) return;
+  const location = res.headers.get('location');
+  if (location) {
+    let to = null;
+    try { to = new URL(location, from); } catch { /* unparsable: treated as away */ }
+    if (to && to.origin === from.origin && trimSlash(appRelativePath(to.pathname, mount)) === bound) return;
+  }
+  const value = await encodeFlash({ ...flash, shown: true });
+  if (value) res.headers.append('set-cookie', flashSetCookie(value));
+}

package/src/action-params.js

@@ -0,0 +1,156 @@
+/**
+ * How many parameters a server action DECLARES (#1686), which is how a form
+ * submission tells a `(prevState, formData)` action from a `(formData)` one.
+ *
+ * `fn.length` cannot answer it: it stops counting at the first parameter with
+ * a default, so `async function save(prevState = initial, formData)` reports 0
+ * and never received its previous result. That default is exactly how an
+ * action supplies the first submission's state, the role `useActionState`'s
+ * second argument plays in Next.js, so the count comes from the function's
+ * source instead. A rest parameter is not counted, and anything that is not
+ * plain source (a native or bound function) falls back to `fn.length`.
+ *
+ * @param {Function} fn
+ * @returns {number}
+ */
+export function declaredParamCount(fn) {
+  let src;
+  try {
+    src = Function.prototype.toString.call(fn);
+  } catch {
+    return fn.length;
+  }
+  if (/\{\s*\[native code\]\s*\}\s*$/.test(src)) return fn.length;
+  // A single bare parameter arrow: `x => ...` or `async x => ...`.
+  if (/^\s*(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(src)) return 1;
+  const open = src.indexOf('(');
+  if (open < 0) return fn.length;
+  const list = paramListAt(src, open);
+  if (list === null) return fn.length;
+  return Math.max(fn.length, countParams(list));
+}
+
+/**
+ * The text between the `(` at `open` and its matching `)`, skipping strings,
+ * template literals, comments and nested brackets, or null if unbalanced.
+ * @param {string} src
+ * @param {number} open
+ * @returns {string | null}
+ */
+function paramListAt(src, open) {
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    const c = src[i];
+    if (c === '"' || c === "'" || c === '`') {
+      i = skipQuoted(src, i);
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '/') { const nl = src.indexOf('\n', i); i = nl < 0 ? src.length : nl; continue; }
+    if (c === '/' && src[i + 1] === '*') { const end = src.indexOf('*/', i + 2); i = end < 0 ? src.length : end + 1; continue; }
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') {
+      depth--;
+      if (depth === 0) return src.slice(open + 1, i);
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} src
+ * @param {number} start index of the opening quote
+ * @returns {number} index of the closing quote
+ */
+function skipQuoted(src, start) {
+  const q = src[start];
+  for (let i = start + 1; i < src.length; i++) {
+    if (src[i] === '\\') { i++; continue; }
+    if (q === '`' && src[i] === '$' && src[i + 1] === '{') {
+      const inner = paramListAt(src, i + 1);
+      i += 2 + (inner === null ? 0 : inner.length);
+      continue;
+    }
+    if (src[i] === q) return i;
+  }
+  return src.length;
+}
+
+/**
+ * Whether the function's declared parameters each carry a default, in order
+ * (rest parameter excluded), or null when the source cannot be read (a native
+ * or bound function). `(input, opts = {})` is `[false, true]`.
+ * @param {Function} fn
+ * @returns {boolean[] | null}
+ */
+export function declaredParamDefaults(fn) {
+  let src;
+  try {
+    src = Function.prototype.toString.call(fn);
+  } catch {
+    return null;
+  }
+  if (/\{\s*\[native code\]\s*\}\s*$/.test(src)) return null;
+  if (/^\s*(?:async\s+)?[A-Za-z_$][\w$]*\s*=>/.test(src)) return [false];
+  const open = src.indexOf('(');
+  if (open < 0) return null;
+  const list = paramListAt(src, open);
+  if (list === null) return null;
+  return splitParams(list).map(hasTopLevelDefault);
+}
+
+/**
+ * Whether a parameter's source has a default: an `=` at depth 0 that is not
+ * part of `==`, `=>`, `<=`, `>=` or `!=` (a destructuring pattern's own
+ * defaults sit inside its brackets).
+ * @param {string} param
+ */
+function hasTopLevelDefault(param) {
+  let depth = 0;
+  for (let i = 0; i < param.length; i++) {
+    const c = param[i];
+    if (c === '"' || c === "'" || c === '`') { i = skipQuoted(param, i); continue; }
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') depth--;
+    else if (c === '=' && depth === 0 && param[i + 1] !== '=' && param[i + 1] !== '>' && !'=!<>'.includes(param[i - 1] || '')) return true;
+  }
+  return false;
+}
+
+/**
+ * Top-level parameters in a parameter list, a rest parameter not counted.
+ * @param {string} list
+ * @returns {number}
+ */
+function countParams(list) {
+  return splitParams(list).length;
+}
+
+/**
+ * The declared parameters' source texts, top-level commas only, the rest
+ * parameter dropped.
+ * @param {string} list
+ * @returns {string[]}
+ */
+function splitParams(list) {
+  /** @type {string[]} */
+  const parts = [];
+  let depth = 0;
+  let cur = '';
+  for (let i = 0; i < list.length; i++) {
+    const c = list[i];
+    if (c === '"' || c === "'" || c === '`') {
+      const end = skipQuoted(list, i);
+      cur += list.slice(i, end + 1);
+      i = end;
+      continue;
+    }
+    if (c === '/' && list[i + 1] === '/') { const nl = list.indexOf('\n', i); i = nl < 0 ? list.length : nl; continue; }
+    if (c === '/' && list[i + 1] === '*') { const end = list.indexOf('*/', i + 2); i = end < 0 ? list.length : end + 1; continue; }
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') depth--;
+    if (c === ',' && depth === 0) { parts.push(cur); cur = ''; continue; }
+    cur += c;
+  }
+  parts.push(cur);
+  return parts.map((p) => p.trim()).filter((p) => p && !p.startsWith('...'));
+}

package/src/action-route.js

@@ -155,19 +155,18 @@ export function route(actionOrModule, opts = {}) {
       // Run the validator through the SHARED contract (#245) so the REST adapter
       // and the RPC path interpret a `{ success, fieldErrors }` envelope, a
       // throw, and a transform-return identically. A structured failure becomes
-      // a 422 JSON; a throw stays a 400 (keeping a schema lib's `issues`); a
+      // a 422 JSON, and so does a schema library's throw (its issues mapped to
+      // fieldErrors, the raw `issues` kept); any other throw is a 400; a
       // transform-return replaces the input.
-      const v = runValidate(validate, arg);
+      const v = await runValidate(validate, arg);
       if (!v.ok) {
-        if (v.thrown !== undefined) {
-          const msg = v.result.error || 'Invalid input';
-          const issues = v.thrown && typeof v.thrown === 'object' && 'issues' in v.thrown
-            ? /** @type any */ (v.thrown).issues
-            : undefined;
-          return Response.json({ error: msg, issues }, { status: 400 });
+        if (v.thrown !== undefined && !v.invalid) {
+          return Response.json({ error: v.result.error || 'Invalid input' }, { status: 400 });
         }
+        // A structured envelope, or a schema library's throw mapped to one
+        // (which also keeps its raw `issues` for a REST client).
         const { status, ...payload } = v.result;
-        return Response.json(payload, { status });
+        return Response.json(v.invalid ? { ...payload, issues: /** @type any */ (v.thrown).issues } : payload, { status });
       }
       arg = v.value;
     }

package/src/action-seed.js

@@ -64,7 +64,7 @@ import * as nodeModule from 'node:module';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { stringify } from '@webjsdev/core';
+import { stringify, installActionBind } from '@webjsdev/core';
 import { hashFile } from './actions.js';
 import { isStreamable } from './action-stream.js';
 import { serverRuntime } from './listener-core.js';
@@ -107,6 +107,28 @@ const _flags = shared('action-seed-flags', () => ({ seedEnabled: false, devMode:
  * @type {WeakMap<Function, { file: string, fnName: string }[]>}
  */
 const _identity = shared('action-identity', () => new WeakMap());
+/** The function each seed Proxy wraps, so its source can still be read
+ * (`Function.prototype.toString` on a Proxy is native code). */
+const _originals = shared('action-originals', () => new WeakMap());
+
+/** The property a facade's exported wrapper reads its real action through. */
+const ORIGINAL = Symbol.for('webjs.action.original');
+
+/**
+ * The action function itself, behind a facade's exported wrapper or a seed
+ * Proxy, or `fn` when it is neither. Used to read the action's own source,
+ * which neither wrapper carries (#1686).
+ * @param {Function} fn
+ * @returns {Function}
+ */
+export function originalAction(fn) {
+  /** @type {any} */
+  const f = fn;
+  let inner;
+  try { inner = f[ORIGINAL]; } catch { inner = undefined; }
+  if (typeof inner === 'function') return inner;
+  return _originals.get(fn) ?? fn;
+}
 
 /** Memoized `absPath -> hash` so a hot action call does not re-hash per call. */
 const _hashCache = shared('action-hash-cache', () => new Map());
@@ -267,6 +289,10 @@ async function assertDeterministic(prev, next, hash, fnName) {
  */
 export function __actionWrap(file, fnName, orig) {
   if (typeof orig !== 'function') return orig;
+  // `action.bind(null, id)` keeps the identity, so the bound function can be
+  // bound to a form (Next.js's way to pass an extra argument). Installed on the
+  // target, so the seed Proxy below forwards it too.
+  installActionBind(orig);
   // APPEND, defining module first. A barrel is faceted too and its body runs
   // AFTER the module it re-exports from, so the first registration is the
   // defining one: the module that also carries `validate` / `middleware` /
@@ -281,6 +307,7 @@ export function __actionWrap(file, fnName, orig) {
   _identity.set(orig, list);
   if (!_flags.seedEnabled) return orig;
   const wrapped = seedProxy(file, fnName, orig);
+  _originals.set(wrapped, orig);
   // The wrapper is a fresh object every time, so it shares the TARGET's list
   // rather than starting one of its own.
   _identity.set(wrapped, list);
@@ -552,6 +579,17 @@ function buildFacade(origUrl, absPath, exports) {
     out += `  const fn = ${v} || (${v} = __w(${file}, ${k}, __orig[${k}]));\n`;
     out += `  return typeof fn === 'function' ? fn.apply(this, args) : fn;\n`;
     out += `}\n`;
+    // Keep the action's declared arity: a form-bound action declaring
+    // `(prevState, formData)` is told apart by `fn.length` (Next's
+    // useActionState contract), and the rest-args wrapper reports 0. It is a
+    // GETTER, read when the dispatcher asks: a circular import can run this
+    // facade before the real module, while a `const` action is still in TDZ,
+    // and a value captured then would freeze the arity at 0.
+    out += `try { Object.defineProperty(${n}, 'length', { configurable: true, get() { try { return (__orig[${k}] && __orig[${k}].length) || 0; } catch { return 0; } } }); } catch {}\n`;
+    // The real function, for reading its source (`originalAction`): the
+    // dispatcher counts DECLARED parameters, which `length` undercounts at a
+    // default (#1686). A getter for the same TDZ reason as `length`.
+    out += `try { Object.defineProperty(${n}, Symbol.for('webjs.action.original'), { configurable: true, get() { try { return __orig[${k}]; } catch { return undefined; } } }); } catch {}\n`;
     out += `__w(${file}, ${k}, ${n});\n`;
   }
   for (const n of exports.valNames) {
@@ -663,10 +701,11 @@ export async function registerActionHooks(opts = {}) {
     g[installed] = true;
     // Bun has no module.registerHooks; install the same facade via Bun.plugin.
     const { installBunSeedPlugin } = await import('./action-seed-bun.js');
-    // Dev rewrites the app's `#` imports to absolute paths (#1575); the
-    // rewrite reads the app roots dev registered, so it is a no-op in prod.
-    const { rewriteAppAliases } = await import('./dev/bun-app-source.js');
-    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE, rewriteAliases: rewriteAppAliases });
+    // Dev rewrites the app's `#` imports to absolute paths (#1575) and stamps
+    // the module versions (#1689); both read the app roots dev registered, so
+    // the rewrite is a no-op in prod.
+    const { rewriteAppSource } = await import('./dev/bun-app-source.js');
+    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE, rewriteAliases: rewriteAppSource });
     _flags.hookInstalled = true;
     return;
   }