@webjsdev/server 0.8.8 → 0.8.10

package/src/cors.js

@@ -0,0 +1,245 @@
+/**
+ * Reusable CORS primitive for webjs.
+ *
+ * Two surfaces share one origin-resolution + header-building core:
+ *
+ * 1. `cors(options)` returns a webjs MIDDLEWARE `(req, next) => Response`,
+ *    usable in `middleware.js` (root or per-segment) or wrapped around a
+ *    `route.js` handler. This is the public app-facing API.
+ * 2. The `expose()` REST path (`actions.js`) reuses `resolveOrigin` and
+ *    `applyCorsHeaders` so a route's `cors` config and a standalone
+ *    `cors()` middleware compute identical headers.
+ *
+ * Web-standards-first: the option shape mirrors the well-trodden
+ * `cors` npm package and the Fetch CORS protocol. We reflect the
+ * request `Origin` ONLY when the policy allows it, never blanket-reflect
+ * with credentials, and always append (never clobber) `Vary: Origin`
+ * when the allowed origin is dynamic, to keep shared caches correct.
+ *
+ * The one hard CORS-spec rule we enforce: a wildcard origin (`*`) is
+ * incompatible with `credentials: true`. The browser rejects
+ * `Access-Control-Allow-Origin: *` together with
+ * `Access-Control-Allow-Credentials: true`, so when both are configured
+ * we NARROW to the reflected request origin instead of sending `*`
+ * (and append `Vary: Origin`, since the response now varies by origin).
+ *
+ * ```js
+ * // middleware.js
+ * import { cors } from '@webjsdev/server';
+ * export default cors({ origin: ['https://app.example.com'], credentials: true });
+ * ```
+ *
+ * @module cors
+ */
+
+/**
+ * @typedef {string | RegExp | ((origin: string) => boolean)} OriginRule
+ *   A single origin rule. A function receives the request `Origin` and
+ *   returns whether it is allowed.
+ */
+
+/**
+ * @typedef {Object} CorsOptions
+ * @property {'*' | true | OriginRule | OriginRule[]} [origin]
+ *   Allowed origin policy. `'*'` / `true` allows any origin. A string is
+ *   an exact match. A `RegExp` tests the origin. A function returns a
+ *   boolean. An array is an allow-list of any of the above (matches if
+ *   ANY entry matches). Defaults to `'*'`.
+ * @property {boolean} [credentials]
+ *   Send `Access-Control-Allow-Credentials: true`. Forces a wildcard
+ *   origin to narrow to the reflected request origin (spec requirement).
+ * @property {string[] | string} [methods]
+ *   Methods advertised on a preflight. Defaults to the common verb set.
+ * @property {string[] | string} [allowedHeaders]
+ *   Request headers advertised on a preflight. Defaults to reflecting
+ *   the preflight's `Access-Control-Request-Headers`.
+ * @property {string[] | string} [exposedHeaders]
+ *   Response headers exposed to client JS via
+ *   `Access-Control-Expose-Headers`.
+ * @property {number} [maxAge]
+ *   Preflight cache lifetime in seconds (`Access-Control-Max-Age`).
+ */
+
+const DEFAULT_METHODS = ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE'];
+
+/**
+ * Module-level dedupe flag for the credentials+wildcard warning. Reflecting
+ * the request origin under `credentials: true` grants credentialed access to
+ * EVERY origin, a real footgun, so we warn ONCE (not per request) to keep
+ * logs readable while still surfacing it. The request still proceeds.
+ */
+let warnedCredentialedWildcard = false;
+
+/** Emit the one-time credentials+wildcard warning (deduped across requests). */
+function warnCredentialedWildcard() {
+  if (warnedCredentialedWildcard) return;
+  warnedCredentialedWildcard = true;
+  console.warn(
+    'cors(): credentials with a wildcard origin reflects ANY origin with credentials. ' +
+      'Use an explicit origin allowlist for credentialed requests.',
+  );
+}
+
+/** Testing hook: reset the one-time warning dedupe flag. */
+export function _resetCorsWarnings() {
+  warnedCredentialedWildcard = false;
+}
+
+/** @param {string[] | string | undefined} v @returns {string | undefined} */
+function csv(v) {
+  if (v == null) return undefined;
+  return Array.isArray(v) ? v.join(', ') : String(v);
+}
+
+/**
+ * Decide whether `origin` is allowed by a single rule.
+ *
+ * @param {OriginRule | '*' | true} rule
+ * @param {string} origin
+ * @returns {boolean}
+ */
+function ruleAllows(rule, origin) {
+  if (rule === '*' || rule === true) return true;
+  if (typeof rule === 'string') return rule === origin;
+  if (rule instanceof RegExp) return rule.test(origin);
+  if (typeof rule === 'function') return rule(origin) === true;
+  return false;
+}
+
+/**
+ * Resolve a CORS origin policy against a request `Origin` header.
+ *
+ * Returns the value to send in `Access-Control-Allow-Origin`, or `null`
+ * when the origin is NOT allowed (the caller then omits the header so the
+ * browser blocks the cross-origin read). The shape:
+ *
+ * - `{ allowOrigin: '*', dynamic: false }`  any origin, no credentials.
+ * - `{ allowOrigin: '<origin>', dynamic: true }`  reflected, varies by origin.
+ * - `null`  disallowed.
+ *
+ * `credentials: true` forces a wildcard to narrow: `*` is invalid with
+ * credentials, so we reflect the concrete request origin (and mark the
+ * result dynamic so `Vary: Origin` is appended). With no `Origin` header
+ * a wildcard policy still resolves to `*` (or, under credentials, yields
+ * no reflected value), matching same-origin / server-to-server traffic.
+ *
+ * @param {'*' | true | OriginRule | OriginRule[]} policy
+ * @param {string} origin  request `Origin` header (`''` if absent)
+ * @param {boolean} credentials
+ * @returns {{ allowOrigin: string, dynamic: boolean } | null}
+ */
+export function resolveOrigin(policy, origin, credentials) {
+  const rules = Array.isArray(policy) ? policy : [policy];
+  const isWildcard = rules.some((r) => r === '*' || r === true);
+
+  if (isWildcard) {
+    // Wildcard + credentials is invalid per the CORS spec: a literal `*`
+    // ACAO can never be combined with `Allow-Credentials: true`. Narrow
+    // to the reflected origin (dynamic), or refuse if no origin is given.
+    // Reflecting under credentials effectively allows EVERY origin, so warn
+    // once (the request still proceeds) to flag the footgun.
+    if (credentials) {
+      warnCredentialedWildcard();
+      if (!origin) return null;
+      return { allowOrigin: origin, dynamic: true };
+    }
+    return { allowOrigin: '*', dynamic: false };
+  }
+
+  if (!origin) return null;
+  const allowed = rules.some((r) => ruleAllows(r, origin));
+  if (!allowed) return null;
+  return { allowOrigin: origin, dynamic: true };
+}
+
+/** @param {Headers} headers append `Vary: Origin` without clobbering existing Vary */
+function appendVaryOrigin(headers) {
+  const existing = headers.get('vary');
+  if (!existing) {
+    headers.set('vary', 'Origin');
+    return;
+  }
+  const parts = existing.split(',').map((s) => s.trim().toLowerCase());
+  if (parts.includes('*') || parts.includes('origin')) return;
+  headers.append('vary', 'Origin');
+}
+
+/**
+ * Mutate `headers` in place to carry the actual-request CORS headers for
+ * a resolved origin: `Access-Control-Allow-Origin`, optional
+ * `Allow-Credentials`, optional `Expose-Headers`, and `Vary: Origin`
+ * when the origin is dynamic.
+ *
+ * @param {Headers} headers
+ * @param {{ allowOrigin: string, dynamic: boolean }} resolved
+ * @param {{ credentials?: boolean, exposedHeaders?: string[] | string }} cfg
+ */
+export function applyCorsHeaders(headers, resolved, cfg) {
+  headers.set('access-control-allow-origin', resolved.allowOrigin);
+  if (cfg.credentials && resolved.allowOrigin !== '*') {
+    headers.set('access-control-allow-credentials', 'true');
+  }
+  const exposed = csv(cfg.exposedHeaders);
+  if (exposed) headers.set('access-control-expose-headers', exposed);
+  if (resolved.dynamic) appendVaryOrigin(headers);
+}
+
+/**
+ * Build a CORS middleware `(req, next) => Response`.
+ *
+ * Behavior:
+ * - On an OPTIONS preflight (carries `Access-Control-Request-Method`),
+ *   short-circuit with a 204 carrying Allow-Methods / Allow-Headers /
+ *   Max-Age. `next()` is NOT called.
+ * - On an actual request, call `next()` then attach the actual-request
+ *   CORS headers to the response.
+ * - A disallowed origin gets NO `Access-Control-Allow-Origin` (the
+ *   browser blocks the read). The server still serves the actual request
+ *   (CORS is browser-enforced); a disallowed PREFLIGHT returns a bare 204
+ *   with no CORS headers, so the browser blocks the follow-up.
+ *
+ * @param {CorsOptions} [options]
+ * @returns {(req: Request, next: () => Promise<Response>) => Promise<Response>}
+ */
+export function cors(options = {}) {
+  const policy = options.origin ?? '*';
+  const credentials = options.credentials === true;
+  const methods = csv(options.methods) || DEFAULT_METHODS.join(', ');
+  const allowedHeaders = csv(options.allowedHeaders);
+  const exposedHeaders = options.exposedHeaders;
+  const maxAge = options.maxAge;
+
+  return async function corsMiddleware(req, next) {
+    const origin = req.headers.get('origin') || '';
+    const resolved = resolveOrigin(policy, origin, credentials);
+    const isPreflight =
+      req.method === 'OPTIONS' && req.headers.has('access-control-request-method');
+
+    if (isPreflight) {
+      const headers = new Headers();
+      // Disallowed preflight: bare 204, no CORS headers. The browser then
+      // blocks the actual request, which is the correct CORS posture.
+      if (resolved) {
+        applyCorsHeaders(headers, resolved, { credentials, exposedHeaders });
+        headers.set('access-control-allow-methods', methods);
+        const reqHeaders =
+          allowedHeaders || req.headers.get('access-control-request-headers') || 'content-type';
+        headers.set('access-control-allow-headers', reqHeaders);
+        if (maxAge != null) headers.set('access-control-max-age', String(maxAge));
+      }
+      return new Response(null, { status: 204, headers });
+    }
+
+    const resp = await next();
+    if (!resolved) return resp;
+    // Some synthetic Responses have immutable headers; fall back to a copy.
+    try {
+      applyCorsHeaders(resp.headers, resolved, { credentials, exposedHeaders });
+      return resp;
+    } catch {
+      const headers = new Headers(resp.headers);
+      applyCorsHeaders(headers, resolved, { credentials, exposedHeaders });
+      return new Response(resp.body, { status: resp.status, statusText: resp.statusText, headers });
+    }
+  };
+}

package/src/csp.js

@@ -0,0 +1,218 @@
+/**
+ * Content-Security-Policy: mint a per-request nonce and emit the matching
+ * header (issue #233).
+ *
+ * webjs's CSP support used to be consume-only: `ssr.js` read a nonce out
+ * of the INBOUND request's `Content-Security-Policy` header and applied it
+ * to its inline boot script, the importmap, and modulepreload hints. That
+ * only did anything if some upstream proxy already minted a nonce and set
+ * the header, so the advertised "CSP via nonce" protection was off by
+ * default and effectively dead.
+ *
+ * This module wires the GENERATING half. When CSP is enabled (opt-in, via
+ * `package.json` -> `webjs.csp`), the request handler:
+ *   1. mints a fresh CSPRNG nonce per request (`mintNonce`),
+ *   2. makes it the value `cspNonce()` returns for that request (so the
+ *      same nonce lands on every inline `<script>` / meta / modulepreload
+ *      the SSR pipeline emits), and
+ *   3. sets a literal `Content-Security-Policy` response header carrying
+ *      that EXACT nonce (`buildCspHeader`).
+ *
+ * The header value and the nonce on the inline scripts are the same
+ * minted string, so there is no drift: a single value flows
+ * mint -> request store -> SSR (`cspNonce()`) -> header.
+ *
+ * The default policy when enabled is a strict-dynamic + nonce posture
+ * that works with webjs's own inline boot script and importmap. CSP is
+ * OFF by default: an unconfigured app is byte-for-byte unchanged (no
+ * nonce minted, `cspNonce()` stays '', no CSP header).
+ */
+
+/**
+ * @typedef {{
+ *   enabled: boolean,
+ *   directives: Record<string, string>,
+ *   reportOnly: boolean,
+ * }} CspConfig
+ */
+
+/**
+ * Any C0/C1 control character, including CR and LF. A directive name or
+ * value carrying one of these would make `Headers.set` throw, so such a
+ * directive is dropped from the policy at config-read time (fail closed).
+ */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\x00-\x1f\x7f-\x9f]/;
+
+/**
+ * The strict-by-default directive set used when `webjs.csp` is `true`
+ * (or an object that does not override a given directive). Tuned to work
+ * with webjs's own output, which is: nonce-signed inline `<script>` tags
+ * (the boot script, the public-env shim, the importmap), nonce-signed
+ * `<link rel="modulepreload">`, ES modules fetched same-origin and from
+ * the configured vendor CDN, and Tailwind's runtime which injects a
+ * `<style>` element (so inline styles must be allowed).
+ *
+ * `script-src` uses `'strict-dynamic'` so a nonce-loaded module can pull
+ * in its own dependencies (the importmap-driven per-file ESM graph)
+ * without each fetched URL needing to be allow-listed. `'self'` and
+ * `https:` are kept as a fallback for browsers that do not honor
+ * `'strict-dynamic'` (they are ignored where it IS honored).
+ *
+ * The `__NONCE__` placeholder is substituted per request in
+ * `buildCspHeader`.
+ *
+ * @type {Record<string, string>}
+ */
+const DEFAULT_DIRECTIVES = {
+  'default-src': "'self'",
+  'script-src': "'nonce-__NONCE__' 'strict-dynamic' 'self' https:",
+  // Tailwind's browser runtime injects a <style> element, and webjs
+  // emits an inline <style> for adopted component styles, so inline
+  // styles must be permitted. Style elements are not a script-injection
+  // vector, so this does not weaken the script protection.
+  'style-src': "'self' 'unsafe-inline'",
+  'img-src': "'self' data: https:",
+  'font-src': "'self' data: https:",
+  'connect-src': "'self'",
+  'base-uri': "'self'",
+  'form-action': "'self'",
+  'frame-ancestors': "'self'",
+  'object-src': "'none'",
+};
+
+/**
+ * Read and normalize the CSP config from the app's package.json
+ * (`webjs.csp`). Never throws: a malformed config disables CSP rather
+ * than taking the app down (a broken security knob must fail closed and
+ * visible, not crash every request).
+ *
+ * Accepted shapes:
+ *   "csp": false | undefined    -> disabled (the default)
+ *   "csp": true                 -> enabled, default strict policy
+ *   "csp": { ...overrides }     -> enabled, custom directives
+ *
+ * Object shape:
+ *   {
+ *     "directives": { "connect-src": "'self' https://api.example.com" },
+ *     "reportOnly": true
+ *   }
+ * `directives` is merged OVER the strict defaults (per-directive
+ * override), so an app customizes one directive without restating the
+ * rest. A directive whose value is null/false/'' is DROPPED from the
+ * emitted policy (the escape hatch to remove a default directive).
+ * `reportOnly: true` emits `Content-Security-Policy-Report-Only` instead
+ * of the enforcing header (the standard staged-rollout path).
+ *
+ * A bare object with no `directives` key is also accepted and treated as
+ * the directive map directly, so `{ "connect-src": "..." }` works as a
+ * terse form. `reportOnly` is always recognized at the top level, so the
+ * terse form never mistakes it for a directive.
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @returns {CspConfig}
+ */
+export function readCspConfig(pkg) {
+  const off = { enabled: false, directives: {}, reportOnly: false };
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.csp;
+  if (raw === undefined || raw === null || raw === false) return off;
+  if (raw === true) {
+    return { enabled: true, directives: { ...DEFAULT_DIRECTIVES }, reportOnly: false };
+  }
+  if (typeof raw !== 'object') return off; // a string/number is malformed: fail closed
+
+  // `reportOnly` is a reserved top-level key in BOTH shapes, so the terse
+  // bare-directive-map form never treats it as a directive. The wrapped
+  // shape ({ directives, reportOnly }) is distinguished by a `directives`
+  // key; otherwise the object IS the directive map (minus reportOnly).
+  const obj = /** @type {any} */ (raw);
+  const reportOnly = Boolean(obj.reportOnly);
+  let overrides;
+  if (Object.prototype.hasOwnProperty.call(obj, 'directives')) {
+    overrides = obj.directives;
+  } else {
+    overrides = { ...obj };
+    delete overrides.reportOnly;
+  }
+
+  const directives = { ...DEFAULT_DIRECTIVES };
+  if (overrides && typeof overrides === 'object') {
+    for (const [k, v] of Object.entries(overrides)) {
+      if (typeof k !== 'string' || !k) continue;
+      // null / false / '' removes a default directive.
+      if (v === null || v === false || v === '') {
+        delete directives[k];
+        continue;
+      }
+      const value = String(v);
+      // Reject a directive NAME or VALUE carrying CR/LF or other control
+      // chars. Author-controlled config (no injection vector, the only
+      // request-derived input is the safe base64 nonce), but a CRLF in a
+      // value would make `Headers.set` THROW in `buildCspHeader`'s caller,
+      // a self-inflicted 500 on every request that breaks this file's
+      // "never a throw, fail closed" promise. Drop the bad directive with a
+      // one-line warning, consistent with how headers.js drops a bad
+      // header directive. `__NONCE__` is substituted later with a base64
+      // nonce, so the post-substitution value stays control-char-free.
+      if (CONTROL_CHARS.test(k) || CONTROL_CHARS.test(value)) {
+        // eslint-disable-next-line no-console
+        console.warn(`[webjs] dropping invalid webjs.csp directive "${k}" (control character in name or value)`);
+        delete directives[k];
+        continue;
+      }
+      directives[k] = value;
+    }
+  }
+  return { enabled: true, directives, reportOnly };
+}
+
+/**
+ * Mint a fresh per-request nonce with native crypto (CSPRNG). 16 random
+ * bytes, base64-encoded, which clears the CSP spec's 128-bit-entropy
+ * recommendation and is in the nonce charset (`[A-Za-z0-9+/=]`). Changes
+ * every call, so every request gets a distinct value.
+ *
+ * @returns {string}
+ */
+export function mintNonce() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  // Buffer is available in every webjs server runtime (Node 24+). Avoids a
+  // hand-rolled base64 of a binary string.
+  return Buffer.from(bytes).toString('base64');
+}
+
+/**
+ * Build the literal `Content-Security-Policy` header VALUE from a config
+ * and a minted nonce, substituting the `__NONCE__` placeholder so the
+ * header carries the exact nonce the SSR pipeline put on the inline
+ * scripts. Returns the policy string (directives joined by `; `).
+ *
+ * @param {CspConfig} config
+ * @param {string} nonce
+ * @returns {string}
+ */
+export function buildCspHeader(config, nonce) {
+  const parts = [];
+  for (const [name, value] of Object.entries(config.directives)) {
+    const v = String(value).replaceAll('__NONCE__', nonce);
+    parts.push(v ? `${name} ${v}` : name);
+  }
+  return parts.join('; ');
+}
+
+/**
+ * The header NAME to emit for a config (enforcing vs report-only).
+ *
+ * @param {CspConfig} config
+ * @returns {string}
+ */
+export function cspHeaderName(config) {
+  return config.reportOnly
+    ? 'Content-Security-Policy-Report-Only'
+    : 'Content-Security-Policy';
+}