@webjsdev/server 0.8.9 → 0.8.11

package/index.js

@@ -1,4 +1,6 @@
 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 { buildRouteTable, matchPage, matchApi } from './src/router.js';
 export { ssrPage, ssrNotFound } from './src/ssr.js';
 export { handleApi } from './src/api.js';
@@ -32,11 +34,14 @@ export {
 } from './src/vendor.js';
 export { buildModuleGraph, transitiveDeps } from './src/module-graph.js';
 export { scanComponents, primeComponentRegistry, extractComponents, findOrphanComponents } from './src/component-scanner.js';
-export { headers, cookies, getRequest, withRequest, cspNonce } from './src/context.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';
+export { cors, resolveOrigin, applyCorsHeaders } from './src/cors.js';
 export { memoryStore, redisStore, getStore, setStore } from './src/cache.js';
 export { cache } from './src/cache-fn.js';
+export { revalidateTag, revalidateTags } from './src/cache-tags.js';
+export { revalidatePath, revalidateAll } from './src/html-cache.js';
 export { Session, session, cookieSessionStorage, storeSessionStorage, cookieSession, storeSession, getSession } from './src/session.js';
 export { broadcast } from './src/broadcast.js';
 export { json, readBody } from './src/json.js';

package/package.json

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

package/src/actions.js

@@ -6,6 +6,20 @@ import { getExposed } from '@webjsdev/core';
 import { walk } from './fs-walk.js';
 import { verify as verifyCsrf, CSRF_COOKIE, CSRF_HEADER } from './csrf.js';
 import { getSerializer } from './serializer.js';
+import { resolveOrigin } from './cors.js';
+import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
+import { getBodyLimits } from './context.js';
+
+/**
+ * The JSON / RPC body cap in effect for the current request: the per-request
+ * limit the handler stamped, or the secure default outside a request scope (a
+ * direct unit-test invocation). `0` disables the cap.
+ * @returns {number}
+ */
+function jsonBodyLimit() {
+  const limits = getBodyLimits();
+  return limits ? limits.json : DEFAULT_MAX_BODY_BYTES;
+}
 
 /**
  * Internal RPC wire-format content type. Distinguishes webjs action
@@ -287,16 +301,24 @@ export async function serveActionStub(idx, absFile) {
  * @param {string} hash
  * @param {string} fnName
  * @param {Request} req
+ * @param {(error: unknown) => void} [onError] best-effort sink (issue #239)
+ *   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.
  */
-export async function invokeAction(idx, hash, fnName, req) {
+export async function invokeAction(idx, hash, fnName, req, onError) {
   if (!verifyCsrf(req)) {
     return rpcResponse({ error: 'CSRF validation failed' }, { status: 403 });
   }
   const file = idx.hashToFile.get(hash);
   if (!file) return rpcResponse({ error: 'Unknown action' }, { status: 404 });
+  // Bounded read (issue #237): reject an over-limit RPC body with 413 without
+  // buffering it whole (Content-Length fast-reject, plus a streaming cap for a
+  // chunked body with no declared length).
+  const { tooLarge, text: body } = await readTextBounded(req, jsonBodyLimit());
+  if (tooLarge) return payloadTooLarge();
   let args = [];
   try {
-    const body = await req.text();
     args = body ? getSerializer().deserialize(body) : [];
     if (!Array.isArray(args)) args = [args];
   } catch {
@@ -309,6 +331,7 @@ export async function invokeAction(idx, hash, fnName, req) {
     const result = await fn(...args);
     return rpcResponse(result ?? null);
   } catch (e) {
+    if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }
 }
@@ -388,11 +411,23 @@ export function withCors(resp, route, req) {
   return new Response(resp.body, { status: resp.status, statusText: resp.statusText, headers: newHeaders });
 }
 
-/** @param {string|string[]} configured @param {string} origin */
+/**
+ * Match a route's configured origin policy against the request origin,
+ * preserving the expose() path's historical contract: `*` returns `true`
+ * (literal wildcard), an allowed concrete origin echoes back, and a
+ * mismatch returns `null`. Delegates the per-rule decision to the shared
+ * cors.js resolver (so RegExp + function policies work here too) but keeps
+ * the wildcard-as-`true` and echo-vs-null shape this caller expects.
+ *
+ * @param {string|string[]|RegExp|((origin: string) => boolean)} configured
+ * @param {string} origin
+ * @returns {true | string | null}
+ */
 function matchOrigin(configured, origin) {
   if (configured === '*') return true;
-  if (Array.isArray(configured)) return configured.includes(origin) ? origin : null;
-  return configured === origin ? origin : null;
+  const resolved = resolveOrigin(configured, origin, false);
+  if (!resolved) return null;
+  return resolved.allowOrigin === '*' ? true : resolved.allowOrigin;
 }
 
 /**
@@ -402,13 +437,19 @@ function matchOrigin(configured, origin) {
  * @param {ExposedRoute} route
  * @param {Record<string,string>} params
  * @param {Request} req
+ * @param {(error: unknown) => void} [onError] best-effort sink (issue #239)
+ *   invoked when the exposed REST handler 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.
  */
-export async function invokeExposedAction(idx, route, params, req) {
+export async function invokeExposedAction(idx, route, params, req, onError) {
   const url = new URL(req.url);
   const query = Object.fromEntries(url.searchParams.entries());
   let body = {};
   if (req.method !== 'GET' && req.method !== 'HEAD') {
-    const text = await req.text();
+    // Bounded read (issue #237): an over-limit body is a 413 before any parse.
+    const { tooLarge, text } = await readTextBounded(req, jsonBodyLimit());
+    if (tooLarge) return payloadTooLarge();
     if (text) {
       try {
         const parsed = JSON.parse(text);
@@ -441,6 +482,7 @@ export async function invokeExposedAction(idx, route, params, req) {
     if (result instanceof Response) return result;
     return Response.json(result ?? null);
   } catch (e) {
+    if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }
 }

package/src/api.js

@@ -25,7 +25,22 @@ export async function handleApi(route, params, webRequest, dev) {
     });
   }
   /** @type any */ (webRequest).params = params;
-  const result = await handler(webRequest, { params });
+  let result;
+  try {
+    result = await handler(webRequest, { params });
+  } catch (e) {
+    // A route handler that read its body via `readBody` (json.js) over the
+    // size limit (issue #237) throws a BodyLimitError; surface it as 413 rather
+    // than a generic 500. Detected via a marker so a cross-module-copy
+    // instanceof miss never downgrades it.
+    if (e && /** @type any */ (e).webjsBodyLimit) {
+      return new Response('Payload Too Large', {
+        status: 413,
+        headers: { 'content-type': 'text/plain; charset=utf-8' },
+      });
+    }
+    throw e;
+  }
   if (result instanceof Response) return result;
   // Convenience: allow returning plain objects as JSON.
   return Response.json(result);

package/src/auth.js

@@ -8,7 +8,8 @@
  */
 
 import { getStore } from './cache.js';
-import { getRequest } from './context.js';
+import { getRequest, getBodyLimits, markDynamicAccess } from './context.js';
+import { readTextBounded, readFormDataBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 
 const enc = new TextEncoder();
 const dec = new TextDecoder();
@@ -219,6 +220,13 @@ export function createAuth(config) {
   // -- Session read/write ---------------------------------------------------
 
   async function readSession(req) {
+    // Reading the auth session is per-user (the body branches on the logged-in
+    // user), so mark the request dynamic so the server HTML cache excludes the
+    // page even when it wrongly set `revalidate`, mirroring getSession() /
+    // cookies() / headers(). This closes the auth-path leak (#241): `auth()`
+    // reaches here, reads the auth cookie raw, and would otherwise leave the
+    // page cacheable so a logged-in body could be served to the next visitor.
+    markDynamicAccess();
     const cookies = parseCookies(req.headers.get('cookie') || '');
     const raw = cookies[AUTH_COOKIE];
     if (!raw) return null;
@@ -409,10 +417,24 @@ export function createAuth(config) {
       const provider = providers.get(seg[1]);
       if (!provider) return new Response('Unknown provider', { status: 404 });
       if (provider.type === 'credentials') {
+        // Bounded body read (issue #237): the credentials sign-in endpoint is
+        // public and unauthenticated, so cap its body to defend against
+        // memory exhaustion. Credentials are small fixed-shape JSON / form
+        // data, so the JSON / RPC limit applies. An over-limit body is a 413
+        // before any parse, and is never buffered whole (see body-limit.js).
+        const limits = getBodyLimits();
+        const limit = limits ? limits.json : DEFAULT_MAX_BODY_BYTES;
         let body = {};
         const ct = req.headers.get('content-type') || '';
-        if (ct.includes('json')) body = await req.json();
-        else if (ct.includes('form')) { const fd = await req.formData(); for (const [k, v] of fd.entries()) body[k] = v; }
+        if (ct.includes('json')) {
+          const { tooLarge, text } = await readTextBounded(req, limit);
+          if (tooLarge) return payloadTooLarge();
+          body = text ? JSON.parse(text) : {};
+        } else if (ct.includes('form')) {
+          const { tooLarge, formData } = await readFormDataBounded(req, limit);
+          if (tooLarge) return payloadTooLarge();
+          for (const [k, v] of formData.entries()) body[k] = v;
+        }
         return signInFn('credentials', body, { req });
       }
       if (provider.type === 'oauth') return oauthRedirect(provider, { req });

package/src/body-limit.js

@@ -0,0 +1,291 @@
+/**
+ * Request body-size limits (413) and node:http server timeouts (issue #237).
+ *
+ * webjs's prod server reads request bodies on three paths: the server-action
+ * RPC endpoint (actions.js), `route.{js,ts}` handlers via `readBody` (json.js),
+ * and the no-JS page-action form path (page-action.js). Without a cap, an
+ * uncapped body is a memory-exhaustion vector. This module is the SINGLE place
+ * that decides the limit and performs a bounded read, so every body-read site
+ * enforces it uniformly.
+ *
+ * Two ideas, both web-standard / node:http-native, no library:
+ *
+ *   1. A bounded read. `readTextBounded` / `readFormDataBounded` reject a body
+ *      over the configured limit with a 413 WITHOUT buffering the whole thing:
+ *      a `Content-Length` over the limit is a fast reject (the body is never
+ *      read), and a chunked/streamed body without `Content-Length` is counted
+ *      while it streams and abandoned the moment it crosses the limit (so the
+ *      process never holds more than roughly one chunk past the limit).
+ *
+ *   2. Server timeouts. `computeServerTimeouts` derives the `requestTimeout`,
+ *      `headersTimeout`, and `keepAliveTimeout` values applied to the node:http
+ *      server in `startServer`, with secure production defaults and config / env
+ *      overrides. node semantics: `headersTimeout` MUST be < `requestTimeout`
+ *      (node measures the header-receipt deadline from the start of the request,
+ *      so a headers deadline at or above the whole-request deadline can never
+ *      fire), so the helper clamps it below `requestTimeout` when a config sets
+ *      them inconsistently.
+ */
+
+/** Default JSON / RPC body cap: 1 MiB. Generous for an action payload. */
+export const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+
+/**
+ * Default form / multipart body cap: 10 MiB. A form submission (the page-action
+ * path) may legitimately carry more than a JSON RPC call (a textarea, a small
+ * upload), so it gets a separate, higher, still-bounded limit. Large file
+ * uploads are a distinct concern (#247) with their own streaming story.
+ */
+export const DEFAULT_MAX_MULTIPART_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Thrown by `readBody` (json.js) when a route handler's body exceeds the limit.
+ * The RPC and page-action paths return a 413 Response inline, but `readBody`
+ * runs INSIDE a user route handler and returns parsed data, so it signals the
+ * over-limit case by throwing. The API dispatcher (`handleApi`) catches this and
+ * maps it to a 413, so a handler that just does `await readBody(req)` gets the
+ * correct status with no extra code.
+ */
+export class BodyLimitError extends Error {
+  constructor() {
+    super('Payload Too Large');
+    this.name = 'BodyLimitError';
+    /** Marker so `handleApi` can detect it without an instanceof across module copies. */
+    this.webjsBodyLimit = true;
+  }
+}
+
+/** requestTimeout: time to receive the ENTIRE request (headers + body). 30s. */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+
+/**
+ * headersTimeout: time to receive the request headers. Must be < requestTimeout
+ * (node measures both from the same request start, so an equal-or-greater value
+ * never fires). 20s is comfortably under the 30s whole-request deadline.
+ */
+export const DEFAULT_HEADERS_TIMEOUT_MS = 20_000;
+
+/** keepAliveTimeout: idle time before closing a kept-alive socket. 5s. */
+export const DEFAULT_KEEP_ALIVE_TIMEOUT_MS = 5_000;
+
+/**
+ * Read a non-negative integer from an env var, or undefined when unset / blank /
+ * not a finite non-negative integer. A value of `0` is honored (it disables the
+ * limit / timeout), so the check is on parseability, not truthiness.
+ *
+ * @param {string | undefined} raw
+ * @returns {number | undefined}
+ */
+function envInt(raw) {
+  if (raw == null || raw === '') return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) return undefined;
+  return n;
+}
+
+/**
+ * Read a non-negative integer from a package.json `webjs.<key>` value, or
+ * undefined when absent / not a finite non-negative integer.
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @param {string} key the `webjs.<key>` field name
+ * @returns {number | undefined}
+ */
+function pkgInt(pkg, key) {
+  const v =
+    pkg && typeof pkg === 'object' && /** @type {any} */ (pkg).webjs
+      ? /** @type {any} */ (pkg).webjs[key]
+      : undefined;
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || !Number.isInteger(v)) {
+    return undefined;
+  }
+  return v;
+}
+
+/**
+ * Resolve the body-size limits. Precedence: env override wins, then the
+ * package.json `webjs.maxBodyBytes` / `webjs.maxMultipartBytes` config, then the
+ * secure defaults. A value of `0` (from env or config) disables that limit, the
+ * deliberate opt-out (e.g. an app fronted by an edge that already caps bodies).
+ *
+ *   WEBJS_MAX_BODY_BYTES        -> json / rpc cap
+ *   WEBJS_MAX_MULTIPART_BYTES   -> form / multipart cap
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts] injectable env (tests)
+ * @returns {{ json: number, multipart: number }} resolved byte limits (0 = off)
+ */
+export function readBodyLimits(pkg, opts = {}) {
+  const env = opts.env || process.env;
+  const json =
+    envInt(env.WEBJS_MAX_BODY_BYTES) ??
+    pkgInt(pkg, 'maxBodyBytes') ??
+    DEFAULT_MAX_BODY_BYTES;
+  const multipart =
+    envInt(env.WEBJS_MAX_MULTIPART_BYTES) ??
+    pkgInt(pkg, 'maxMultipartBytes') ??
+    DEFAULT_MAX_MULTIPART_BYTES;
+  return { json, multipart };
+}
+
+/**
+ * Resolve the node:http server timeouts. Precedence mirrors `readBodyLimits`:
+ * env override, then package.json `webjs.requestTimeoutMs` /
+ * `webjs.headersTimeoutMs` / `webjs.keepAliveTimeoutMs`, then the defaults. A
+ * value of `0` disables that timeout (node's own "no limit" sentinel).
+ *
+ *   WEBJS_REQUEST_TIMEOUT_MS
+ *   WEBJS_HEADERS_TIMEOUT_MS
+ *   WEBJS_KEEP_ALIVE_TIMEOUT_MS
+ *
+ * node semantics enforced here: `headersTimeout` MUST be strictly less than
+ * `requestTimeout` to fire (both deadlines run from the same request start). So
+ * when a non-zero `headersTimeout` is >= a non-zero `requestTimeout`, clamp it
+ * to just under `requestTimeout` rather than silently shipping a dead timeout.
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts] injectable env (tests)
+ * @returns {{ requestTimeout: number, headersTimeout: number, keepAliveTimeout: number }}
+ */
+export function computeServerTimeouts(pkg, opts = {}) {
+  const env = opts.env || process.env;
+  const requestTimeout =
+    envInt(env.WEBJS_REQUEST_TIMEOUT_MS) ??
+    pkgInt(pkg, 'requestTimeoutMs') ??
+    DEFAULT_REQUEST_TIMEOUT_MS;
+  let headersTimeout =
+    envInt(env.WEBJS_HEADERS_TIMEOUT_MS) ??
+    pkgInt(pkg, 'headersTimeoutMs') ??
+    DEFAULT_HEADERS_TIMEOUT_MS;
+  const keepAliveTimeout =
+    envInt(env.WEBJS_KEEP_ALIVE_TIMEOUT_MS) ??
+    pkgInt(pkg, 'keepAliveTimeoutMs') ??
+    DEFAULT_KEEP_ALIVE_TIMEOUT_MS;
+  // Keep headersTimeout strictly under requestTimeout so it can actually fire.
+  // Both are measured from the same request start; a headers deadline at or
+  // above the whole-request deadline is dead. Skip when either is 0 (disabled).
+  if (requestTimeout > 0 && headersTimeout >= requestTimeout) {
+    headersTimeout = Math.max(1, requestTimeout - 1000);
+  }
+  return { requestTimeout, headersTimeout, keepAliveTimeout };
+}
+
+/**
+ * A 413 Payload Too Large response, returned by every body-read site when the
+ * bounded read trips the limit. Tiny plain-text body so it stays content-type
+ * agnostic; the caller never needs to vary it.
+ *
+ * @returns {Response}
+ */
+export function payloadTooLarge() {
+  return new Response('Payload Too Large', {
+    status: 413,
+    headers: { 'content-type': 'text/plain; charset=utf-8' },
+  });
+}
+
+/**
+ * Read a request body as bytes, bounded by `limit`. The single funnel both text
+ * and FormData readers go through.
+ *
+ *   - `limit <= 0` disables the cap (read the whole body).
+ *   - A `Content-Length` header over the limit is a FAST REJECT: the body is
+ *     never touched, so an attacker-declared huge upload costs nothing.
+ *   - Otherwise the body stream is read chunk by chunk and the running total is
+ *     checked AFTER each chunk. The moment it crosses the limit the read is
+ *     abandoned (the stream reader is cancelled) and `tooLarge` is returned, so
+ *     a chunked body with no `Content-Length` can never buffer more than the
+ *     bytes already read (roughly limit + one chunk), not the full payload.
+ *
+ * @param {Request} req
+ * @param {number} limit max bytes (0 / negative = unlimited)
+ * @returns {Promise<{ tooLarge: boolean, bytes: Uint8Array | null }>}
+ */
+export async function readBytesBounded(req, limit) {
+  // Fast reject on a declared Content-Length over the limit: never read a byte.
+  if (limit > 0) {
+    const cl = req.headers.get('content-length');
+    if (cl != null) {
+      const declared = Number(cl);
+      if (Number.isFinite(declared) && declared > limit) {
+        return { tooLarge: true, bytes: null };
+      }
+    }
+  }
+
+  const body = req.body;
+  if (!body) return { tooLarge: false, bytes: new Uint8Array(0) };
+
+  const reader = body.getReader();
+  /** @type {Uint8Array[]} */
+  const chunks = [];
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      // Enforce WHILE reading so a no-Content-Length stream can't buffer past
+      // the limit: bail the instant the running total crosses it.
+      if (limit > 0 && total > limit) {
+        // Stop pulling more bytes; release the upstream so the socket can close.
+        try { await reader.cancel(); } catch { /* already closed */ }
+        return { tooLarge: true, bytes: null };
+      }
+      chunks.push(value);
+    }
+  } finally {
+    try { reader.releaseLock(); } catch { /* reader already released */ }
+  }
+
+  // Concatenate the collected chunks into one buffer.
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return { tooLarge: false, bytes: out };
+}
+
+/**
+ * Read a request body as text, bounded by `limit`. Used by the RPC endpoint,
+ * `readBody`, and the exposed-action REST path, all of which then parse the
+ * text (webjs wire or JSON).
+ *
+ * @param {Request} req
+ * @param {number} limit max bytes (0 / negative = unlimited)
+ * @returns {Promise<{ tooLarge: boolean, text: string }>}
+ */
+export async function readTextBounded(req, limit) {
+  const { tooLarge, bytes } = await readBytesBounded(req, limit);
+  if (tooLarge) return { tooLarge: true, text: '' };
+  const text = bytes && bytes.byteLength ? new TextDecoder().decode(bytes) : '';
+  return { tooLarge: false, text };
+}
+
+/**
+ * Read a request body as `FormData`, bounded by `limit`. Used by the page-action
+ * form path. Reconstructs a bounded Request from the already-read bytes and
+ * defers to the platform `formData()` parser, so multipart and
+ * urlencoded bodies are decoded exactly as before, just size-checked first.
+ *
+ * @param {Request} req
+ * @param {number} limit max bytes (0 / negative = unlimited)
+ * @returns {Promise<{ tooLarge: boolean, formData: FormData | null }>}
+ */
+export async function readFormDataBounded(req, limit) {
+  const { tooLarge, bytes } = await readBytesBounded(req, limit);
+  if (tooLarge) return { tooLarge: true, formData: null };
+  const ct = req.headers.get('content-type') || '';
+  // Hand the bounded bytes back to a fresh Request so its standard formData()
+  // parser (multipart boundary handling, urlencoded decoding) runs unchanged.
+  const bounded = new Request(req.url, {
+    method: 'POST',
+    headers: ct ? { 'content-type': ct } : undefined,
+    body: bytes && bytes.byteLength ? bytes : undefined,
+  });
+  const formData = await bounded.formData();
+  return { tooLarge: false, formData };
+}

package/src/build-info.js

@@ -0,0 +1,59 @@
+import { createRequire } from 'node:module';
+import { publishedBuildId } from './importmap.js';
+
+/**
+ * Build-info / version probe (issue #239).
+ *
+ * `GET /__webjs/version` returns a small JSON object a deploy can curl to
+ * verify which build is live, alongside the existing `/__webjs/health` and
+ * `/__webjs/ready` probes. It carries NO secrets: only the framework version,
+ * the published importmap build id (the same value the client router reads
+ * from `data-webjs-build` to detect a deploy), the running node version, and
+ * process uptime. Served before `ensureReady()` like the other probes, so it
+ * answers on a cold instance without blocking on the whole-app analysis.
+ *
+ * The framework version is read once from this package's own `package.json`,
+ * the same single-source pattern `requiredNodeMajor()` uses, so it never drifts
+ * from the published version.
+ */
+
+/** @type {string} */
+let _frameworkVersion = '';
+function frameworkVersion() {
+  if (_frameworkVersion) return _frameworkVersion;
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+    _frameworkVersion = String(pkg?.version || '');
+  } catch {
+    _frameworkVersion = '';
+  }
+  return _frameworkVersion;
+}
+
+/**
+ * Compose the build-info payload. Pure (takes the moment as an argument) so a
+ * test can assert the shape without mocking the clock; the handler calls it
+ * with `process.uptime()`.
+ *
+ * @param {{ uptime?: number }} [opts]
+ * @returns {{ version: string, build: string, node: string, uptime: number }}
+ */
+export function buildInfo(opts = {}) {
+  return {
+    version: frameworkVersion(),
+    build: publishedBuildId(),
+    node: process.version,
+    uptime: typeof opts.uptime === 'number' ? opts.uptime : process.uptime(),
+  };
+}
+
+/**
+ * Build the `GET /__webjs/version` response. `no-store` so a proxy / browser
+ * never caches a stale build fingerprint.
+ *
+ * @returns {Response}
+ */
+export function buildInfoResponse() {
+  return Response.json(buildInfo(), { headers: { 'cache-control': 'no-store' } });
+}

package/src/cache-fn.js

@@ -24,6 +24,7 @@
  */
 
 import { getStore } from './cache.js';
+import { addKeyToTags } from './cache-tags.js';
 
 /**
  * Wrap an async function with server-side caching.
@@ -33,9 +34,18 @@ import { getStore } from './cache.js';
  * @param {{
  *   key: string,
  *   ttl?: number,
+ *   tags?: string[] | ((...args: Parameters<T>) => string[]),
  * }} opts
  *   - `key`: cache key prefix. Combined with serialized args to form the full key.
  *   - `ttl`: time-to-live in seconds. Default: 60.
+ *   - `tags`: optional tags this cached result belongs to, for cross-module
+ *     invalidation via `revalidateTag(tag)`. Either a static `string[]`
+ *     (every cached entry of this function shares them) or a function
+ *     `(...args) => string[]` so a per-arg read tags with the entity id
+ *     (e.g. `tags: (id) => ['post:' + id]`). The result is also recorded
+ *     under each tag's thin key index so `revalidateTag` can find and
+ *     evict it later, including arg-specific entries that the no-args
+ *     `invalidate()` cannot reach.
  * @returns {T & { invalidate: () => Promise<void> }}
  *   The cached function with the same signature, plus an `invalidate()`
  *   method to manually clear the cache.
@@ -43,6 +53,19 @@ import { getStore } from './cache.js';
 export function cache(fn, opts) {
   const prefix = opts.key;
   const ttlMs = (opts.ttl ?? 60) * 1000;
+  const tagsOpt = opts.tags;
+
+  /**
+   * Resolve the tag list for one call. A function form receives the call
+   * args (so a per-entity read can tag with the id); a static array is
+   * returned as-is. Anything else yields no tags.
+   * @param {any[]} args
+   * @returns {string[]}
+   */
+  function tagsFor(args) {
+    const raw = typeof tagsOpt === 'function' ? tagsOpt(...args) : tagsOpt;
+    return Array.isArray(raw) ? raw.filter((t) => typeof t === 'string' && t) : [];
+  }
 
   const wrapped = /** @type {T & { invalidate: () => Promise<void> }} */ (
     async function (...args) {
@@ -58,6 +81,23 @@ export function cache(fn, opts) {
 
       const result = await fn(...args);
       await store.set(cacheKey, JSON.stringify(result), ttlMs);
+      // Record tag -> cacheKey in the thin tag index so a later
+      // revalidateTag can find and evict this entry (including
+      // arg-specific keys the no-args invalidate() cannot reach).
+      // Best-effort: the value is already stored, so taggability must
+      // never break the cached call. A user tags() function that throws
+      // (e.g. reading post.id off a null arg), or an index write that
+      // fails, leaves the value cached (just untagged) and returns
+      // normally. tagsFor() is INSIDE the try because it runs the
+      // user-supplied function.
+      try {
+        await addKeyToTags(tagsFor(args), cacheKey, ttlMs);
+      } catch (err) {
+        console.warn(
+          `[webjs] cache(${prefix}): tag indexing failed, value is cached ` +
+          `but untagged (revalidateTag will not reach it): ${err && err.message ? err.message : err}`
+        );
+      }
       return result;
     }
   );