@webjsdev/server 0.8.32 → 0.8.34

package/index.d.ts

@@ -457,6 +457,21 @@ export declare function findOrphanComponents(
   appDir: string,
 ): Promise<Array<{ className: string; file: string }>>;
 
+// ---------------------------------------------------------------------------
+// elision-report.js (#646)
+// ---------------------------------------------------------------------------
+
+/**
+ * App-level elision report: the page/layout route modules that SHIP WHOLE to
+ * the browser instead of being elided as carriers, each with the first
+ * client-effecting blocker that pins it (or `null` when the module's own code
+ * is the cause) plus a human reason. A reporting layer over `analyzeElision`,
+ * consumed by the `webjs doctor` carrier-hygiene advisory (#646).
+ */
+export declare function analyzeAppElision(
+  appDir: string,
+): Promise<{ analysed: boolean; shipped: Array<{ file: string; blocker: string | null; reason: string }> }>;
+
 // ---------------------------------------------------------------------------
 // context.js (per-request context helpers)
 // ---------------------------------------------------------------------------

package/index.js

@@ -42,6 +42,7 @@ 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 { 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';
@@ -68,8 +69,6 @@ export { createAuth, Credentials, Google, GitHub } from './src/auth.js';
 export {
   testRequest,
   toRequest,
-  getCsrf,
-  readCsrfCookie,
   getSetCookies,
   cookiesToHeader,
   withCookies,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.32",
+  "version": "0.8.34",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/actions.js

@@ -3,7 +3,7 @@ import { pathToFileURL } from 'node:url';
 import { readFile } from 'node:fs/promises';
 import { join, sep } from 'node:path';
 import { walk } from './fs-walk.js';
-import { verify as verifyCsrf, CSRF_COOKIE, CSRF_HEADER } from './csrf.js';
+import { verifyOrigin } from './csrf.js';
 import { getSerializer } from './serializer.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 import {
@@ -311,7 +311,6 @@ export async function serveActionStub(idx, absFile) {
  */
 function buildStubBody({ hash, method, fnNames, actionUrl }) {
   const URL_ARG = URL_ARG_VERBS.has(method);
-  const SAFE = SAFE_VERBS.has(method);
   const J = JSON.stringify;
   const lines = [];
   lines.push(`// webjs: generated server-action stub (${method})`);
@@ -334,7 +333,8 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   lines.push(`const __METHOD = ${J(method)};`);
   lines.push(`const __MAX = ${MAX_URL_ARGS};`);
   lines.push(`const __CT = ${J(RPC_CONTENT_TYPE)};`);
-  lines.push(`function __csrf() { const m = document.cookie.match(/(?:^|;\\s*)${CSRF_COOKIE}=([^;]+)/); return m ? decodeURIComponent(m[1]) : ''; }`);
+  // CSRF is enforced server-side by an Origin-header check, so the stub sends
+  // nothing extra: the browser attaches `Origin` to a same-origin POST itself.
   // Shared: parse a response, surface invalidation, register a GET's tags
   // (stamped with the clock SAMPLED BEFORE the fetch, so a mutation in flight is
   // caught on the next read).
@@ -383,8 +383,8 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   // captured SYNCHRONOUSLY at __call entry (#492): the active render signal must
   // be read before the stub's first await (stringify), or the render's
   // synchronous window has already closed and cleared it.
-  lines.push(`async function __body(fn, body, m, csrf, sig) {`);
-  lines.push(`  const headers = { 'content-type': __CT }; if (csrf) headers[${J(CSRF_HEADER)}] = __csrf();`);
+  lines.push(`async function __body(fn, body, m, sig) {`);
+  lines.push(`  const headers = { 'content-type': __CT };`);
   lines.push(`  const res = await fetch(__URL + fn, { method: m, headers, credentials: 'same-origin', body, signal: sig });`);
   lines.push(`  return __handle(res, fn, null);`);
   lines.push(`}`);
@@ -394,14 +394,14 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
     lines.push(`  const sig = __sig();`); // sync capture before any await
     lines.push(`  const key = await __s(args);`);
     lines.push(`  const seeded = __seedTake(__HASH, fn, key); if (seeded !== __MISS) return seeded;`);
-    lines.push(`  if (key.length > __MAX) return __body(fn, key, 'POST', ${SAFE ? 'false' : 'true'}, sig);`);
+    lines.push(`  if (key.length > __MAX) return __body(fn, key, 'POST', sig);`);
     if (method === 'GET') {
       lines.push(`  const bypass = __stale(key);`);
       lines.push(`  const since = __mark();`);
       lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: 'GET', credentials: 'same-origin', cache: bypass ? 'no-cache' : 'default', signal: sig });`);
       lines.push(`  return __handle(res, fn, key, since);`);
     } else {
-      lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: __METHOD, headers: { ${J(CSRF_HEADER)}: __csrf() }, credentials: 'same-origin', signal: sig });`);
+      lines.push(`  const res = await fetch(__URL + fn + '?a=' + encodeURIComponent(key), { method: __METHOD, credentials: 'same-origin', signal: sig });`);
       lines.push(`  return __handle(res, fn, null);`);
     }
     lines.push(`}`);
@@ -413,7 +413,7 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
     lines.push(`  const sig = __sig();`); // sync capture before any await
     lines.push(`  const key = await __s(args);`);
     lines.push(`  const seeded = __seedTake(__HASH, fn, key); if (seeded !== __MISS) return seeded;`);
-    lines.push(`  return __body(fn, key, __METHOD, true, sig);`);
+    lines.push(`  return __body(fn, key, __METHOD, sig);`);
     lines.push(`}`);
   }
   for (const name of fnNames) {
@@ -436,8 +436,10 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
  *   invoked when the action throws unexpectedly, BEFORE the sanitized 500 is
  *   returned, so an APM integration sees the original error. The caller wraps
  *   it so a throwing sink can never affect the response.
+ * @param {string[]} [allowedOrigins] cross-site origins the CSRF check allows
+ *   (the app's `webjs.allowedOrigins`), for reverse-proxy / multi-domain setups.
  */
-export async function invokeAction(idx, hash, fnName, req, onError) {
+export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigins = []) {
   const file = idx.hashToFile.get(hash);
   if (!file) return rpcResponse({ error: 'Unknown action' }, { status: 404 });
   const mod = await loadModule(file, idx.dev);
@@ -459,10 +461,14 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
       { status: 405, headers: { allow: [...allowed].join(', ') } },
     );
   }
-  // CSRF: required for every verb except a safe GET (a read with no state
-  // change, which is also browser-cacheable so it cannot carry a fresh token).
-  if (!SAFE_VERBS.has(method) && !verifyCsrf(req)) {
-    return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
+  // CSRF: an Origin-header check on every state-changing verb (a safe GET is a
+  // read with no state change). A browser sets `Origin` on a cross-site POST to
+  // the ATTACKER's origin, so a forged request fails the host match. No token
+  // or cookie is involved, which keeps SSR HTML free of `Set-Cookie` and so
+  // CDN-cacheable. See csrf.js.
+  if (!SAFE_VERBS.has(method)) {
+    const v = verifyOrigin(req, allowedOrigins);
+    if (!v.ok) return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
   }
 
   // Args ride the URL for a URL-arg request (GET / DELETE), else the body.

package/src/check.js

@@ -5,6 +5,7 @@ import {
   redactStringsAndTemplates,
   extractWebComponentClassBodies,
   matchClosingBrace,
+  parsePropEntries,
 } from './js-scan.js';
 import { buildModuleGraph, transitiveDeps } from './module-graph.js';
 import { scanComponents } from './component-scanner.js';
@@ -83,6 +84,11 @@ export const RULES = [
     description:
       'A reactive property declared via the `extends WebComponent({ … })` factory must NOT also have a plain class-field initializer (`count = 0` or `count: number = 0`) in the class body. Under modern class-field semantics that initializer runs Object.defineProperty *after* super(), clobbering the framework\'s reactive accessor and silently breaking re-renders. Set the default via the `default` property option (`prop(Number, { default: 0 })`) or by assigning in the constructor after super().',
   },
+  {
+    name: 'array-prop-uses-array-type',
+    description:
+      'An array-typed reactive property declared via the `extends WebComponent({ … })` factory must pass the `Array` runtime constructor, not `Object`: `count: prop<Tag[]>(Array)`, never `prop<Tag[]>(Object)`. The two share one converter (both JSON-encode the value), so the wrong one does not crash, but `Object` misstates the prop contract to the next reader and diverges from the documented built-in set (String/Number/Boolean/Object/Array). Fires only when the factory generic is itself an array type (`T[]`, `readonly T[]`, `Array<T>`, `ReadonlyArray<T>`) AND the constructor argument is `Object`; a bare `foo: Object` with no generic is never flagged. Fix: change the constructor to `Array`.',
+  },
   {
     name: 'shell-in-non-root-layout',
     description:
@@ -184,6 +190,38 @@ function isComponentFile(relPath) {
  * @param {Set<string>} props
  * @returns {string[]}
  */
+/**
+ * True when a factory prop value is an array-typed `prop<…>(…)` whose
+ * runtime constructor argument is `Object`. The generic and the
+ * constructor sit in the same call, so it is decidable from the value
+ * text alone. The match is greedy on the generic so a nested generic
+ * (`prop<Array<X>>(Object)`) closes at the outer `>` that precedes the
+ * `(Object` call. A bare constructor (`Object`, with no generic) or a
+ * non-array generic (`prop<Foo>(Object)`) returns false.
+ *
+ * @param {string} value the raw prop value text, e.g. `prop<Tag[]>(Object)`
+ * @returns {boolean}
+ */
+function arrayPropUsesObject(value) {
+  const m = /^prop\s*<([\s\S]*)>\s*\(\s*Object\s*[,)]/.exec(value.trim());
+  if (!m) return false;
+  return isArrayTypeText(m[1]);
+}
+
+/**
+ * True when a TypeScript type expression denotes an array: `T[]`,
+ * `readonly T[]`, `T[][]`, `Array<T>`, or `ReadonlyArray<T>`.
+ *
+ * @param {string} type
+ * @returns {boolean}
+ */
+function isArrayTypeText(type) {
+  const bare = type.trim().replace(/^readonly\s+/, '');
+  if (/\[\s*\]$/.test(bare)) return true;
+  if (/^(?:Readonly)?Array\s*<[\s\S]*>$/.test(bare)) return true;
+  return false;
+}
+
 function findFieldInitializers(classBody, props) {
   /** @type {string[]} */
   const out = [];
@@ -440,6 +478,37 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: array-prop-uses-array-type ---
+  // An array-typed reactive prop declared via the factory should pass the
+  // `Array` runtime constructor, not `Object`. Both share one converter
+  // (JSON encode/decode), so `Object` does not crash, but it misstates the
+  // prop contract and diverges from the documented built-in set. Fires only
+  // when the factory generic is itself an array type AND the constructor is
+  // `Object`; a bare `foo: Object` (no generic to prove array-ness) is left
+  // alone to avoid false positives. Uses the redacted `scan`, so a
+  // `prop<X[]>(Object)` shown inside an html`` example string never fires.
+  {
+    for (const { rel, scan } of files) {
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
+      for (const { factoryArg } of extractWebComponentClassBodies(scan)) {
+        const objStart = factoryArg.indexOf('{');
+        if (objStart === -1) continue;
+        const objEnd = matchClosingBrace(factoryArg, objStart + 1);
+        if (objEnd === -1) continue;
+        const objContent = factoryArg.slice(objStart + 1, objEnd);
+        for (const { key, value } of parsePropEntries(objContent)) {
+          if (!arrayPropUsesObject(value)) continue;
+          violations.push({
+            rule: 'array-prop-uses-array-type',
+            file: rel,
+            message: `Array-typed reactive prop \`${key}\` is declared with the \`Object\` constructor (\`prop<…[]>(Object)\`); use \`Array\` so the runtime converter matches the declared shape.`,
+            fix: `Change the constructor to \`Array\`: \`${key}: prop<…[]>(Array)\`. Object and Array share one converter so behaviour is unchanged, but \`Array\` states the prop's shape correctly.`,
+          });
+        }
+      }
+    }
+  }
+
   // --- Rule: no-browser-globals-in-render ---
   // The SSR pipeline runs the constructor (`new Cls()`), willUpdate, and
   // render() on the server element shim (attribute methods backed, but no real