@webjsdev/server 0.7.2

package/src/component-scanner.js

@@ -0,0 +1,164 @@
+/**
+ * Server-side scanner that walks the app tree and records the
+ * browser-visible URL for every webjs component module.
+ *
+ * Called once at server boot. Results are used to prime the core
+ * registry (`primeModuleUrl`) BEFORE any SSR render: so when a page
+ * renders a component tag, `lookupModuleUrl(tag)` already has the URL
+ * ready for `<link rel="modulepreload">` hints.
+ *
+ * The convention webjs uses is the web-standard one:
+ *
+ *     class Counter extends WebComponent { … }
+ *     customElements.define('my-counter', Counter);
+ *
+ * The scanner looks for `customElements.define('<tag>', <ClassName>)`
+ * calls: static text patterns that are cheap to regex-match without
+ * a full TS parse. A full parse would be ~50× slower for no payoff;
+ * we only need `{ tag, className, moduleUrl }` tuples.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { sep } from 'node:path';
+import { walk } from './fs-walk.js';
+import { primeModuleUrl } from '@webjsdev/core';
+
+/**
+ * Recognise either registration pattern:
+ *
+ *     Counter.register('my-counter')           // idiomatic webjs
+ *     customElements.define('my-counter', Counter)  // native DOM API
+ *
+ * Both single and double quotes; whitespace is flexible.
+ *
+ * @param {string} src
+ * @returns {Array<{ className: string, tag: string }>}
+ */
+export function extractComponents(src) {
+  /** @type {Array<{ className: string, tag: string }>} */
+  const results = [];
+  // Pattern A: Class.register('tag')
+  const registerRe = /\b([A-Z][A-Za-z0-9_$]*)\.register\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g;
+  let m;
+  while ((m = registerRe.exec(src)) !== null) {
+    const className = m[1];
+    const tag = m[2];
+    if (tag.includes('-')) {
+      results.push({ className, tag });
+    }
+  }
+  // Pattern B: customElements.define('tag', Class)
+  const defineRe = /\bcustomElements\.define\s*\(\s*['"]([^'"\n]+)['"]\s*,\s*([A-Z][A-Za-z0-9_$]*)\b/g;
+  while ((m = defineRe.exec(src)) !== null) {
+    const tag = m[1];
+    const className = m[2];
+    if (tag.includes('-')) {
+      results.push({ className, tag });
+    }
+  }
+  return results;
+}
+
+/**
+ * Walk an app directory, return every discovered component with its
+ * browser-visible URL (rooted at `/`, matching how the dev server
+ * serves module files).
+ *
+ * @param {string} appDir
+ * @returns {Promise<Array<{ tag: string, className: string, moduleUrl: string, file: string }>>}
+ */
+export async function scanComponents(appDir) {
+  /** @type {Array<{ tag: string, className: string, moduleUrl: string, file: string }>} */
+  const components = [];
+  const filter = (p) =>
+    /\.m?[jt]sx?$/.test(p) &&
+    !/\.(test|spec)\.m?[jt]sx?$/.test(p) &&
+    !/\.server\.m?[jt]s$/.test(p);
+
+  for await (const file of walk(appDir, filter)) {
+    let src;
+    try { src = await readFile(file, 'utf8'); } catch { continue; }
+    const comps = extractComponents(src);
+    if (!comps.length) continue;
+    const moduleUrl = toUrlPath(file, appDir);
+    for (const c of comps) {
+      components.push({ ...c, moduleUrl, file });
+    }
+  }
+  return components;
+}
+
+/**
+ * Scan the app tree and push every component's (tag, moduleUrl) pair
+ * into the core registry via `primeModuleUrl`. Idempotent: if called
+ * again (e.g. on dev-server rebuild after a file add), new discoveries
+ * are added and existing tags are updated.
+ *
+ * @param {string} appDir
+ * @returns {Promise<{ count: number }>}
+ */
+export async function primeComponentRegistry(appDir) {
+  const components = await scanComponents(appDir);
+  for (const { tag, moduleUrl } of components) {
+    primeModuleUrl(tag, moduleUrl);
+  }
+  return { count: components.length };
+}
+
+/**
+ * Find `class X extends WebComponent` (or its subclasses) declarations
+ * that are NOT accompanied by a `customElements.define(tag, X)` call in
+ * the same file. Lets the dev server warn authors early when they
+ * forget the registration step.
+ *
+ * @param {string} appDir
+ * @returns {Promise<Array<{ className: string, file: string }>>}
+ */
+export async function findOrphanComponents(appDir) {
+  /** @type {Array<{ className: string, file: string }>} */
+  const orphans = [];
+  const filter = (p) =>
+    /\.m?[jt]sx?$/.test(p) &&
+    !/\.(test|spec)\.m?[jt]sx?$/.test(p) &&
+    !/\.server\.m?[jt]s$/.test(p);
+
+  for await (const file of walk(appDir, filter)) {
+    let src;
+    try { src = await readFile(file, 'utf8'); } catch { continue; }
+    // Find every class that extends WebComponent (exact name: we trust
+    // the framework convention).
+    const classRe = /\b(?:export\s+)?(?:default\s+)?class\s+([A-Z][A-Za-z0-9_$]*)\s+extends\s+WebComponent\b/g;
+    // A class counts as "registered" if either Class.register('tag') or
+    // customElements.define('tag', Class) appears in the file.
+    const registerRe = /\b([A-Z][A-Za-z0-9_$]*)\.register\s*\(\s*['"][^'"]+['"]\s*\)/g;
+    const defineRe = /\bcustomElements\.define\s*\(\s*['"][^'"]+['"]\s*,\s*([A-Z][A-Za-z0-9_$]*)\b/g;
+
+    const declared = new Set();
+    let m;
+    while ((m = classRe.exec(src)) !== null) declared.add(m[1]);
+    if (declared.size === 0) continue;
+
+    const registered = new Set();
+    while ((m = registerRe.exec(src)) !== null) registered.add(m[1]);
+    while ((m = defineRe.exec(src)) !== null) registered.add(m[1]);
+
+    for (const cls of declared) {
+      if (!registered.has(cls)) {
+        orphans.push({ className: cls, file });
+      }
+    }
+  }
+  return orphans;
+}
+
+/**
+ * @param {string} abs
+ * @param {string} appDir
+ * @returns {string}
+ */
+function toUrlPath(abs, appDir) {
+  let rel = abs.startsWith(appDir) ? abs.slice(appDir.length) : abs;
+  rel = rel.split(sep).join('/');
+  if (!rel.startsWith('/')) rel = '/' + rel;
+  return rel;
+}

package/src/context.js

@@ -0,0 +1,62 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { parseCookies } from './csrf.js';
+
+/**
+ * Per-request context backed by AsyncLocalStorage. Lets server-side code
+ * (pages, layouts, server actions, exposed actions) read the current
+ * Request's headers and cookies without explicit threading: the same
+ * ergonomics as NextJs's `headers()` / `cookies()` from `next/headers`.
+ *
+ * Strictly server-side: importing this module on the client is a bug.
+ *
+ * @typedef {{ req: Request }} Store
+ */
+
+/** @type {AsyncLocalStorage<Store>} */
+const als = new AsyncLocalStorage();
+
+/**
+ * Run `fn` with the given request bound as the current context.
+ * @template T
+ * @param {Request} req
+ * @param {() => T} fn
+ * @returns {T}
+ */
+export function withRequest(req, fn) {
+  return als.run({ req }, fn);
+}
+
+/** @returns {Request | null} */
+export function getRequest() {
+  return als.getStore()?.req ?? null;
+}
+
+/**
+ * Read-only headers for the in-flight request. Throws outside a request
+ * (e.g. at module top-level).
+ * @returns {Headers}
+ */
+export function headers() {
+  const req = getRequest();
+  if (!req) throw new Error('headers(): called outside a request scope');
+  return req.headers;
+}
+
+/**
+ * Read-only cookie jar for the in-flight request. Returns an object with
+ * `.get(name)`, `.has(name)`, `.entries()`. To SET a cookie, return a
+ * `Response` whose headers include `Set-Cookie` (route handlers and
+ * exposed actions can do this directly).
+ *
+ * @returns {{ get: (name: string) => string | undefined, has: (name: string) => boolean, entries: () => [string, string][] }}
+ */
+export function cookies() {
+  const req = getRequest();
+  if (!req) throw new Error('cookies(): called outside a request scope');
+  const map = parseCookies(req);
+  return {
+    get: (name) => map[name],
+    has: (name) => Object.prototype.hasOwnProperty.call(map, name),
+    entries: () => Object.entries(map),
+  };
+}

package/src/csrf.js

@@ -0,0 +1,95 @@
+// Use Web Crypto (globalThis.crypto) for random + hash: works on Node >=20,
+// Deno, Bun, Cloudflare Workers. Avoids the node:crypto import and keeps
+// CSRF portable across runtimes.
+const webCrypto = /** @type {Crypto} */ (globalThis.crypto);
+
+/**
+ * Double-submit cookie CSRF protection for `/__webjs/action/*` RPC endpoints.
+ *
+ * Flow:
+ *   1. Every SSR response that lacks the cookie issues a fresh `webjs_csrf`
+ *      cookie with `SameSite=Lax; Path=/` (and `Secure` when over HTTPS).
+ *      The cookie is readable by JS (not HttpOnly) so the auto-generated
+ *      action stub can echo it.
+ *   2. The action-stub `fetch` sends the token back in `x-webjs-csrf`.
+ *   3. `invokeAction` compares the header to the cookie with constant-time
+ *      equality; mismatch → 403.
+ *
+ * This protects against classic CSRF (a malicious site triggering a POST
+ * from a victim browser): cross-origin requests cannot read the cookie, so
+ * they cannot set the header to the matching value.
+ *
+ * Notes on scope:
+ *   - Applies to internal RPC only. `expose()`d REST endpoints are *not*
+ *     CSRF-protected by default because they're intended for external
+ *     consumers; those endpoints should carry their own auth (bearer token,
+ *     signed request, API key) which the app provides via middleware.
+ */
+
+export const CSRF_COOKIE = 'webjs_csrf';
+export const CSRF_HEADER = 'x-webjs-csrf';
+const COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 7; // 7 days
+
+/** @returns {string} a 128-bit hex token */
+export function newToken() {
+  const bytes = new Uint8Array(16);
+  webCrypto.getRandomValues(bytes);
+  let s = '';
+  for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s;
+}
+
+/**
+ * Parse cookies off a standard Request.
+ * @param {Request} req
+ * @returns {Record<string,string>}
+ */
+export function parseCookies(req) {
+  const header = req.headers.get('cookie') || '';
+  /** @type {Record<string,string>} */
+  const out = {};
+  for (const part of header.split(/;\s*/)) {
+    if (!part) continue;
+    const eq = part.indexOf('=');
+    if (eq <= 0) continue;
+    const k = part.slice(0, eq).trim();
+    const v = part.slice(eq + 1).trim();
+    try { out[k] = decodeURIComponent(v); } catch { out[k] = v; }
+  }
+  return out;
+}
+
+/** @param {Request} req */
+export function readToken(req) {
+  return parseCookies(req)[CSRF_COOKIE] || null;
+}
+
+/**
+ * Serialise a Set-Cookie value for the CSRF token.
+ * @param {string} token
+ * @param {{ secure?: boolean }} [opts]
+ */
+export function cookieHeader(token, opts = {}) {
+  const parts = [
+    `${CSRF_COOKIE}=${encodeURIComponent(token)}`,
+    'Path=/',
+    'SameSite=Lax',
+    `Max-Age=${COOKIE_MAX_AGE_SECONDS}`,
+  ];
+  if (opts.secure) parts.push('Secure');
+  return parts.join('; ');
+}
+
+/**
+ * Constant-time verification of the double-submit.
+ * @param {Request} req
+ */
+export function verify(req) {
+  const cookie = readToken(req);
+  const header = req.headers.get(CSRF_HEADER);
+  if (!cookie || !header) return false;
+  if (cookie.length !== header.length) return false;
+  let diff = 0;
+  for (let i = 0; i < cookie.length; i++) diff |= cookie.charCodeAt(i) ^ header.charCodeAt(i);
+  return diff === 0;
+}