@webjsdev/server 0.8.9 → 0.8.11

package/src/env-schema.js

@@ -0,0 +1,250 @@
+/**
+ * Startup env-var validation with a typed schema hook (issue #236).
+ *
+ * webjs auto-loads `<appDir>/.env` into `process.env` at boot, but does no
+ * validation, so a missing or misconfigured required var (DATABASE_URL,
+ * AUTH_SECRET, ...) fails late and cryptically (a Prisma connect error
+ * mid-request, an undefined secret signing a token). This module adds an
+ * optional boot-time validation hook that fails fast with one clear message
+ * listing EVERY missing or invalid var at once, before the app serves a
+ * request.
+ *
+ * The hook is an optional `env.{js,ts}` module at the app root (sibling of
+ * `middleware.js` / `readiness.js`), default-exporting either:
+ *   1. a plain SCHEMA object, dependency-free, e.g.
+ *        export default {
+ *          DATABASE_URL: 'string',
+ *          AUTH_SECRET: { type: 'string', required: true, minLength: 16 },
+ *          PORT: { type: 'number', optional: true, default: 3000 },
+ *          NODE_ENV: { type: 'enum', values: ['development','production','test'] },
+ *        };
+ *   2. a FUNCTION `(env) => void | throw` for full custom validation (the
+ *      escape hatch), so an app can use zod or anything it likes without webjs
+ *      depending on it. A thrown Error is surfaced as the boot failure.
+ *
+ * The validator is a PURE function (`validateEnv`) so it unit-tests with an
+ * injected schema + env object, no temp app dir needed. `loadEnvSchema` reads
+ * the app's `env.{js,ts}` (returns `null` when absent, so the feature is fully
+ * opt-in), and `applyEnvValidation` is the side-effecting boot wrapper: it runs
+ * the schema/function against `process.env`, applies coerced + defaulted values
+ * back into `process.env`, and throws a clear aggregated Error on failure (so
+ * `createRequestHandler` rejects and the CLI exits non-zero, consistent with
+ * the Node-version preflight).
+ */
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { stat } from 'node:fs/promises';
+
+/** Field type names a schema may declare. */
+const KNOWN_TYPES = new Set(['string', 'number', 'boolean', 'url', 'enum']);
+
+/**
+ * Normalize a schema field to its object form. A bare string like `'string'`
+ * is shorthand for `{ type: 'string' }`.
+ * @param {string | object} rule
+ * @returns {{ type: string, required?: boolean, optional?: boolean, default?: any, values?: any[], minLength?: number, pattern?: (string|RegExp) }}
+ */
+function normalizeRule(rule) {
+  if (typeof rule === 'string') return { type: rule };
+  return rule && typeof rule === 'object' ? rule : { type: 'string' };
+}
+
+/**
+ * Is a field required? A field is required by default. It is optional when it
+ * declares `optional: true`, `required: false`, or carries a `default`.
+ * @param {object} rule normalized rule
+ */
+function isRequired(rule) {
+  if (rule.required === false) return false;
+  if (rule.optional === true) return false;
+  if ('default' in rule) return false;
+  return true;
+}
+
+/**
+ * Coerce a raw string value to the declared type, enforcing the field's
+ * constraints. Returns `{ value }` on success or `{ error }` (a human string)
+ * on failure.
+ * @param {string} name the env var name (for messages)
+ * @param {object} rule normalized rule
+ * @param {string} raw the raw string from the env
+ * @returns {{ value: any } | { error: string }}
+ */
+function coerce(name, rule, raw) {
+  const type = rule.type || 'string';
+  switch (type) {
+    case 'string': {
+      if (typeof rule.minLength === 'number' && raw.length < rule.minLength) {
+        return { error: `${name} must be at least ${rule.minLength} characters (got ${raw.length})` };
+      }
+      if (rule.pattern != null) {
+        const re = rule.pattern instanceof RegExp ? rule.pattern : new RegExp(rule.pattern);
+        if (!re.test(raw)) return { error: `${name} does not match required pattern ${re}` };
+      }
+      return { value: raw };
+    }
+    case 'number': {
+      const n = Number(raw);
+      if (raw.trim() === '' || Number.isNaN(n)) {
+        // Never echo the value: a secret given the wrong type would leak to logs.
+        return { error: `${name} must be a number` };
+      }
+      return { value: n };
+    }
+    case 'boolean': {
+      const v = raw.trim().toLowerCase();
+      if (['1', 'true', 'yes', 'on'].includes(v)) return { value: true };
+      if (['0', 'false', 'no', 'off'].includes(v)) return { value: false };
+      // Never echo the value: list the accepted spellings, not what was given.
+      return { error: `${name} must be a boolean (one of true/false/1/0/yes/no/on/off)` };
+    }
+    case 'url': {
+      try {
+        // eslint-disable-next-line no-new
+        new URL(raw);
+        return { value: raw };
+      } catch {
+        // Never echo the value: a DSN with embedded credentials must not leak.
+        return { error: `${name} must be a valid URL` };
+      }
+    }
+    case 'enum': {
+      const values = Array.isArray(rule.values) ? rule.values : [];
+      if (!values.includes(raw)) {
+        // Name the ALLOWED values (from the schema, safe), never the provided one.
+        return { error: `${name} must be one of ${values.map((v) => JSON.stringify(v)).join(', ')}` };
+      }
+      return { value: raw };
+    }
+    default:
+      return { error: `${name} has an unknown schema type ${JSON.stringify(type)}` };
+  }
+}
+
+/**
+ * Pure env validator. Validates `env` against `schema`, collecting ALL errors
+ * (never stopping at the first), and computes the coerced + defaulted values to
+ * write back. Does NOT mutate `env` or `process.env`; the caller applies
+ * `coerced` to `process.env`.
+ *
+ * When `schema` is a FUNCTION it is the custom-validator escape hatch: it is
+ * called with the env object and any thrown Error is surfaced as a single
+ * error. A function validator never coerces.
+ *
+ * @param {object | Function} schema the default export of `env.{js,ts}`
+ * @param {Record<string, string|undefined>} env the source env (e.g. process.env)
+ * @returns {{ ok: boolean, errors: string[], coerced: Record<string, string> }}
+ */
+export function validateEnv(schema, env) {
+  // Escape hatch: a function gets the env and validates however it wants.
+  if (typeof schema === 'function') {
+    try {
+      schema(env);
+      return { ok: true, errors: [], coerced: {} };
+    } catch (e) {
+      const msg = e && e.message ? String(e.message) : String(e);
+      return { ok: false, errors: [msg], coerced: {} };
+    }
+  }
+
+  if (!schema || typeof schema !== 'object') {
+    // Nothing to validate against. Treat as a no-op rather than an error so a
+    // stray default export does not brick boot.
+    return { ok: true, errors: [], coerced: {} };
+  }
+
+  const errors = [];
+  /** @type {Record<string, string>} */
+  const coerced = {};
+
+  for (const name of Object.keys(schema)) {
+    const rule = normalizeRule(schema[name]);
+    const type = rule.type || 'string';
+    if (!KNOWN_TYPES.has(type)) {
+      errors.push(`${name} declares an unknown type ${JSON.stringify(type)} (expected one of ${[...KNOWN_TYPES].join(', ')})`);
+      continue;
+    }
+    const present = env[name] != null && env[name] !== '';
+    if (!present) {
+      if (isRequired(rule)) {
+        errors.push(`${name} is required but missing`);
+      } else if ('default' in rule) {
+        // Apply the default, coercing it through the same path so a number
+        // default lands as a string in process.env (env values are strings).
+        coerced[name] = String(rule.default);
+      }
+      continue;
+    }
+    const result = coerce(name, rule, String(env[name]));
+    if ('error' in result) {
+      errors.push(result.error);
+    } else if (typeof result.value !== 'string') {
+      // Re-stringify coerced non-string values so process.env stays string-typed.
+      coerced[name] = String(result.value);
+    }
+  }
+
+  return { ok: errors.length === 0, errors, coerced };
+}
+
+/**
+ * Compose the aggregated, actionable failure message from a list of errors.
+ * @param {string[]} errors
+ * @returns {string}
+ */
+export function formatEnvErrors(errors) {
+  const lines = errors.map((e) => `  - ${e}`);
+  return (
+    `webjs env validation failed (${errors.length} ${errors.length === 1 ? 'error' : 'errors'}):\n` +
+    lines.join('\n') +
+    `\n\nFix the variables above in your .env (or the host environment) and restart. ` +
+    `The schema lives in env.{js,ts} at the app root.`
+  );
+}
+
+/**
+ * Load the optional `env.{js,ts}` schema module from the app root. Returns the
+ * default export (a schema object or a validator function), or `null` when no
+ * such file exists, so env validation is fully opt-in.
+ * @param {string} appDir
+ * @param {{ dev?: boolean }} [opts]
+ * @returns {Promise<object | Function | null>}
+ */
+export async function loadEnvSchema(appDir, opts = {}) {
+  let file = null;
+  for (const name of ['env.ts', 'env.js', 'env.mts', 'env.mjs']) {
+    const p = join(appDir, name);
+    try {
+      await stat(p);
+      file = p;
+      break;
+    } catch {
+      // not this name, try the next
+    }
+  }
+  if (!file) return null;
+  const url = pathToFileURL(file).toString();
+  const bust = opts.dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
+  const mod = await import(url + bust);
+  return mod.default ?? null;
+}
+
+/**
+ * Side-effecting boot wrapper: load the app's `env.{js,ts}` (if any), validate
+ * `process.env` against it, apply coerced + defaulted values back into
+ * `process.env`, and THROW a clear aggregated Error on failure. A no-op when
+ * `env.{js,ts}` is absent. Called by `createRequestHandler` right after the
+ * `.env` auto-load and before any server-only module is imported.
+ * @param {string} appDir
+ * @param {{ dev?: boolean, env?: Record<string, string|undefined> }} [opts]
+ * @returns {Promise<void>}
+ */
+export async function applyEnvValidation(appDir, opts = {}) {
+  const schema = await loadEnvSchema(appDir, opts);
+  if (schema == null) return; // opt-in: no env.{js,ts}, nothing to do
+  const env = opts.env ?? process.env;
+  const { ok, errors, coerced } = validateEnv(schema, env);
+  if (!ok) throw new Error(formatEnvErrors(errors));
+  // Apply coerced values + defaults back so the app reads the coerced value.
+  for (const key of Object.keys(coerced)) env[key] = coerced[key];
+}

package/src/headers.js

@@ -0,0 +1,213 @@
+/**
+ * Secure-by-default response headers plus a small declarative per-path
+ * header config (issue #232).
+ *
+ * webjs sets a baseline of standard security headers on every document
+ * and asset response, so a scaffolded app is not clickjackable or
+ * MIME-sniffable out of the box (no reverse proxy required for the
+ * baseline). The defaults are LITERAL HTTP headers, no abstraction.
+ *
+ * An app can ADD, OVERRIDE, or DISABLE any header per path via a
+ * declarative config (`package.json` -> `webjs.headers`), shaped like
+ * Next's: an array of `{ source, headers: [{ key, value }] }` where
+ * `source` is a path pattern matched with the native URLPattern API.
+ *
+ * Precedence, lowest to highest:
+ *   1. secure defaults
+ *   2. path config (webjs.headers)        overrides/adds/removes a default
+ *   3. app middleware (already on the Response when we merge)
+ *
+ * In other words middleware wins over the path config, which wins over
+ * the defaults. We only ever ADD a header the response does not already
+ * carry, so a header an app set (in middleware, a route handler, or via
+ * `expose`) is never clobbered. A path-config entry with a null/empty
+ * value REMOVES a header (e.g. drop a default on a public embed route).
+ *
+ * This is the connective tissue #233 (CSP) and #234 (CORS) plug into
+ * later: the merge seam (applySecurityHeaders) is the single place a
+ * future per-path policy layers onto a Response, so neither needs to
+ * touch the response pipeline again.
+ */
+
+/**
+ * Baseline security headers, as literal name -> value pairs. Set only
+ * when absent, so an app override always wins. HSTS is NOT here: it is
+ * conditional (production + HTTPS) and added separately.
+ *
+ * @type {ReadonlyArray<[string, string]>}
+ */
+const SECURE_DEFAULTS = [
+  ['X-Content-Type-Options', 'nosniff'],
+  ['X-Frame-Options', 'SAMEORIGIN'],
+  ['Referrer-Policy', 'strict-origin-when-cross-origin'],
+  ['Permissions-Policy', 'camera=(), microphone=(), geolocation=()'],
+];
+
+/** The standard HSTS posture: two years, include subdomains. */
+const HSTS_VALUE = 'max-age=63072000; includeSubDomains';
+
+/**
+ * Read the per-path header config from the app's package.json
+ * (`webjs.headers`). Returns a normalized array of compiled rules, each
+ * pairing a URLPattern against the configured header directives. A
+ * malformed or absent config yields an empty array (no per-path rules),
+ * never a throw: a broken config must not take the app down.
+ *
+ * Shape consumed:
+ *   "webjs": { "headers": [ { "source": "/embed/:path*",
+ *     "headers": [ { "key": "X-Frame-Options", "value": null } ] } ] }
+ *
+ * A `value` of null, undefined, or false REMOVES the header on a match
+ * (the disable-a-default escape hatch). Any other value is stringified
+ * and SET (override or add).
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @returns {Array<{ pattern: URLPattern, directives: Array<{ key: string, value: string | null }> }>}
+ */
+export function compileHeaderRules(pkg) {
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.headers;
+  if (!Array.isArray(raw)) return [];
+  /** @type {Array<{ pattern: URLPattern, directives: Array<{ key: string, value: string | null }> }>} */
+  const rules = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue;
+    const source = /** @type {any} */ (entry).source;
+    const list = /** @type {any} */ (entry).headers;
+    if (typeof source !== 'string' || !Array.isArray(list)) continue;
+    let pattern;
+    try {
+      // Match on the pathname only. A bare path string is the common
+      // Next-style usage; URLPattern treats it as the pathname component.
+      pattern = new URLPattern({ pathname: source });
+    } catch {
+      continue; // skip an invalid pattern rather than crash the request
+    }
+    /** @type {Array<{ key: string, value: string | null }>} */
+    const directives = [];
+    for (const d of list) {
+      if (!d || typeof d !== 'object') continue;
+      const key = /** @type {any} */ (d).key;
+      if (typeof key !== 'string' || !key) continue;
+      const v = /** @type {any} */ (d).value;
+      // null / undefined / false means REMOVE the header on a match.
+      const value = v === null || v === undefined || v === false ? null : String(v);
+      // Validate the key/value against the real Headers parser at COMPILE
+      // time (consistent with dropping a bad `source`). A name or value
+      // that Headers rejects (an invalid header name, or a value carrying
+      // CR/LF) would otherwise make `applySecurityHeaders` THROW on every
+      // matching request, a self-inflicted 500, which breaks this file's
+      // "a broken config must not take the app down" guarantee. Probe on a
+      // throwaway Headers and DROP the directive if it throws. For a delete
+      // (value null) only the key needs to be a valid header name, so probe
+      // it with a placeholder value.
+      try {
+        new Headers().set(key, value === null ? 'x' : value);
+      } catch {
+        // eslint-disable-next-line no-console
+        console.warn(`[webjs] dropping invalid webjs.headers directive for key "${key}"`);
+        continue;
+      }
+      directives.push({ key, value });
+    }
+    if (directives.length) rules.push({ pattern, directives });
+  }
+  return rules;
+}
+
+/**
+ * Apply the security defaults and the per-path config to a Response,
+ * returning a Response carrying the merged headers. The input Response
+ * is not mutated; a new Headers is derived from it so the body/status
+ * are preserved by reference (no body copy).
+ *
+ * Headers already on the response (set by app middleware, a route
+ * handler, or `expose`) are treated as authoritative and never
+ * overwritten by a default. The per-path config runs AFTER the defaults
+ * but BEFORE that "already present" rule is consulted for middleware:
+ * the config can override a default freely (it is the app's own
+ * declarative intent), while middleware still wins because its headers
+ * are on the response before we are even called.
+ *
+ * @param {Response} res the response produced by the app pipeline
+ * @param {{
+ *   pathname: string,
+ *   https: boolean,
+ *   prod: boolean,
+ *   rules?: Array<{ pattern: URLPattern, directives: Array<{ key: string, value: string | null }> }>,
+ * }} ctx
+ * @returns {Response}
+ */
+export function applySecurityHeaders(res, ctx) {
+  const headers = new Headers(res.headers);
+  // Snapshot the keys the app already set, so a default never clobbers
+  // them. Captured BEFORE we add anything. Lowercased for compare;
+  // Headers itself is case-insensitive.
+  const appSet = new Set();
+  headers.forEach((_v, k) => appSet.add(k.toLowerCase()));
+
+  // 1. Secure defaults: set only if the app did not already set them.
+  for (const [k, v] of SECURE_DEFAULTS) {
+    if (!appSet.has(k.toLowerCase())) headers.set(k, v);
+  }
+  // HSTS only in production AND only over HTTPS (never on a plain-HTTP
+  // hop). Same "do not clobber" rule.
+  if (ctx.prod && ctx.https && !appSet.has('strict-transport-security')) {
+    headers.set('Strict-Transport-Security', HSTS_VALUE);
+  }
+
+  // 2. Per-path config: override / add / remove. Runs over the merged
+  // set so it can replace a default this same call just added. It does
+  // NOT override a header the app set in middleware (appSet), preserving
+  // the middleware-wins precedence.
+  const rules = ctx.rules || [];
+  for (const rule of rules) {
+    if (!rule.pattern.test({ pathname: ctx.pathname })) continue;
+    for (const { key, value } of rule.directives) {
+      if (appSet.has(key.toLowerCase())) continue; // middleware wins
+      // Belt and suspenders: compileHeaderRules already validated the
+      // key/value, so this never throws in practice, but a surprise from a
+      // directive constructed elsewhere must never throw the response
+      // pipeline. Skip the bad directive instead.
+      try {
+        if (value === null) headers.delete(key);
+        else headers.set(key, value);
+      } catch {
+        /* skip a directive the Headers parser rejects */
+      }
+    }
+  }
+
+  return new Response(res.body, {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+  });
+}
+
+/**
+ * Detect whether the original client request was HTTPS, from a web
+ * `Request` (the shape `handle()` works with). Honors the same
+ * reverse-proxy trust posture as `forwarded.js`: read
+ * `X-Forwarded-Proto` only when proxy trust is on
+ * (`WEBJS_NO_TRUST_PROXY !== '1'`); otherwise fall back to the request
+ * URL's scheme. Never trusts the header blindly.
+ *
+ * @param {Request} req
+ * @returns {boolean}
+ */
+export function webRequestIsHttps(req) {
+  const trust = process.env.WEBJS_NO_TRUST_PROXY !== '1';
+  if (trust) {
+    const proto = req.headers.get('x-forwarded-proto');
+    if (proto) return proto.split(',')[0].trim().toLowerCase() === 'https';
+  }
+  try {
+    return new URL(req.url).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}