@webjsdev/server 0.8.12 → 0.8.13

package/index.js

@@ -27,6 +27,7 @@ export {
   listPinned,
   auditPinned,
   findOutdated,
+  hasVendorPin,
   updatePinned,
   readPinFile,
   serveDownloadedBundle,
@@ -46,8 +47,25 @@ 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';
+export { sitemap, sitemapIndex } from './src/sitemap.js';
 export { attachWebSocket } from './src/websocket.js';
 export { getSerializer, setSerializer, defaultSerializer } from './src/serializer.js';
 
 // Auth (NextAuth-style)
 export { createAuth, Credentials, Google, GitHub } from './src/auth.js';
+
+// Test harness helpers (issue #267): thin builders over handle()
+export {
+  testRequest,
+  toRequest,
+  getCsrf,
+  readCsrfCookie,
+  getSetCookies,
+  cookiesToHeader,
+  withCookies,
+  withSessionCookie,
+  loginAndGetCookies,
+  actionEndpoint,
+  invokeActionForTest,
+  rawActionRequest,
+} from './src/testing.js';

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
     "./check": "./src/check.js",
+    "./testing": "./src/testing.js",
     "./webjs-config.schema.json": "./webjs-config.schema.json"
   },
   "files": [

package/src/actions.js

@@ -33,6 +33,60 @@ function jsonBodyLimit() {
  */
 export const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
 
+/**
+ * Run an attached input validator against an action's input, shared by the RPC
+ * path (`invokeAction`) and the `expose()` REST path (`invokeExposedAction`) so
+ * the contract is identical across transports (#245). The framework only CALLS
+ * the validator and shapes the result; it ships no validation library.
+ *
+ * @param {(input: any) => any} validate the attached validator
+ * @param {any} input the value handed to the validator (the action's first arg
+ *   on RPC, the merged query/params/body object on REST)
+ * @returns {{ ok: true, value: any } | { ok: false, result: { success: false, fieldErrors?: Record<string,string>, error?: string, status: number }, thrown?: unknown }}
+ *   `ok: true` carries the value to pass to the action (the validated `data`,
+ *   the transformed return, or the original input). `ok: false` carries the
+ *   structured failure result the caller serializes back; on a THROWN validator
+ *   it also carries the original error on `thrown` so a caller can salvage a
+ *   schema lib's structured `issues` (the REST path does, for back-compat).
+ */
+export function runValidate(validate, input) {
+  let out;
+  try {
+    out = validate(input);
+  } catch (e) {
+    // Throw-to-reject (the classic `Schema.parse` contract). Map to a sanitized
+    // failure result; a thrown validator is a 400 (bad input), not a 500.
+    // Surface only the message; `thrown` lets the REST caller recover `issues`.
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, result: { success: false, error: msg, status: 400 }, thrown: e };
+  }
+  // Disambiguate an ActionResult envelope from a plain transformed value: a
+  // return is an envelope ONLY when it is an object carrying a boolean
+  // `success` OR a `fieldErrors`. Anything else is a transformed input.
+  if (out && typeof out === 'object' && !Array.isArray(out) &&
+      (typeof (/** @type any */ (out).success) === 'boolean' || 'fieldErrors' in out)) {
+    const env = /** @type any */ (out);
+    if (env.success === true) {
+      // `{ success: true, data? }` → valid; use `data` when present, else input.
+      return { ok: true, value: 'data' in env ? env.data : input };
+    }
+    // Failure: `{ success: false, ... }` or `{ fieldErrors }` (no literal
+    // success). Shape the structured field-error result.
+    return {
+      ok: false,
+      result: {
+        success: false,
+        ...(env.fieldErrors ? { fieldErrors: env.fieldErrors } : {}),
+        ...(env.message || env.error ? { error: env.message || env.error } : {}),
+        status: typeof env.status === 'number' ? env.status : 422,
+      },
+    };
+  }
+  // A non-envelope return transforms the input (back-compat with
+  // `validate: Schema.parse`); `undefined` means "no transform", keep input.
+  return { ok: true, value: out === undefined ? input : out };
+}
+
 /** Build a serialized Response with webjs content-type. */
 async function rpcResponse(payload, init = {}) {
   const s = getSerializer();
@@ -145,6 +199,12 @@ export async function buildActionIndex(appDir, dev) {
         if (typeof fn !== 'function') continue;
         const http = getExposed(fn);
         if (!http) continue;
+        // A `validateInput(fn, ...)` attachment writes `__webjsHttp` with a
+        // `validate` but NO `method`/`path` (it does not create a REST route),
+        // so it is not an exposed route. Only `expose()` sets a path; skip a
+        // validate-only attachment here (its validator is read at RPC call
+        // time via getExposed in invokeAction).
+        if (!http.path || !http.method) continue;
         const { pattern, paramNames } = pathToPattern(http.path);
         httpRoutes.push({
           method: http.method,
@@ -335,6 +395,30 @@ export async function invokeAction(idx, hash, fnName, req, onError) {
   const mod = await loadModule(file, idx.dev);
   const fn = fnName === 'default' ? mod.default : mod[fnName];
   if (typeof fn !== 'function') return rpcResponse({ error: `Unknown action ${fnName}` }, { status: 404 });
+  // Input validation (#245): a validator attached via `validateInput(fn, ...)`
+  // or `expose(spec, fn, { validate })` runs SERVER-SIDE before the body on
+  // this RPC path too, not just the REST path. The RPC stub sends an args
+  // array; an action conventionally takes one input object, so validate the
+  // FIRST arg (matching how the REST path validates its single merged object).
+  const attached = getExposed(fn);
+  if (attached && typeof attached.validate === 'function') {
+    const v = runValidate(attached.validate, args[0]);
+    if (!v.ok) {
+      if (v.thrown !== undefined) {
+        // A THROWN validator behaves like a thrown action: a sanitized error
+        // response (non-200, so the client stub throws), with prod stack
+        // sanitization. The onError sink sees the original error too.
+        if (typeof onError === 'function') onError(v.thrown);
+        return actionErrorResponse(v.thrown, idx.dev);
+      }
+      // A structured `{ success: false, fieldErrors }` envelope is a NORMAL
+      // result the action author renders (`result.fieldErrors`): serialized as
+      // a 200 RPC payload so the client stub returns it as a real object rather
+      // than throwing, the failure status riding inside the envelope.
+      return rpcResponse(v.result);
+    }
+    args = [v.value, ...args.slice(1)];
+  }
   try {
     const result = await fn(...args);
     return rpcResponse(result ?? null);
@@ -470,17 +554,26 @@ export async function invokeExposedAction(idx, route, params, req, onError) {
   }
   let arg = { ...query, ...params, ...body };
   if (route.validate) {
-    try {
-      arg = route.validate(arg);
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      // Many schema libs (zod, valibot) throw structured errors: pass their
-      // `issues` array through when present for easier client-side handling.
-      const issues = e && typeof e === 'object' && 'issues' in e
-        ? /** @type any */ (e).issues
-        : undefined;
-      return Response.json({ error: msg, issues }, { status: 400 });
+    // Run the validator through the SHARED contract (#245) so the REST path and
+    // the RPC path interpret a `{ success, fieldErrors }` envelope, a throw, and
+    // a transform-return identically. A structured failure becomes a 422 JSON
+    // `{ error?, fieldErrors }` (not just a thrown 400); a throw stays a 400; a
+    // transform-return keeps replacing the input (back-compat).
+    const v = runValidate(route.validate, arg);
+    if (!v.ok) {
+      if (v.thrown !== undefined) {
+        // A thrown validator (the classic `Schema.parse` style): keep the exact
+        // legacy REST shape, including a schema lib's structured `issues` array.
+        const msg = v.result.error || 'Invalid input';
+        const issues = v.thrown && typeof v.thrown === 'object' && 'issues' in v.thrown
+          ? /** @type any */ (v.thrown).issues
+          : undefined;
+        return Response.json({ error: msg, issues }, { status: 400 });
+      }
+      const { status, ...payload } = v.result;
+      return Response.json(payload, { status });
     }
+    arg = v.value;
   }
   const mod = await loadModule(route.file, idx.dev);
   const fn = mod[route.fnName];

package/src/sitemap.js

@@ -0,0 +1,161 @@
+/**
+ * Sitemap helpers (issue #276). Two pure functions that turn an array of
+ * entries into spec-valid XML, so an author of `app/sitemap.{js,ts}` does not
+ * hand-roll the `<urlset>` string (escaping URLs, formatting lastmod dates) and
+ * has a built-in path to shard a large site via a `<sitemapindex>`.
+ *
+ * Both are OPTIONAL and tiny. The dev server serves a STRING returned from a
+ * `sitemap.{js,ts}` default export as `application/xml`, so the author returns
+ * `sitemap([...])` from that function. They can still return a raw Response or a
+ * hand-built string, so this is thin XML serialization, not a sitemap framework.
+ *
+ * Reference: the sitemaps.org 0.9 protocol; Next.js `sitemap.ts` (a typed array
+ * serialized to XML) and `generateSitemaps()` (the index for sharding).
+ */
+
+/** Per-URL entry for {@link sitemap}.
+ * @typedef {object} SitemapEntry
+ * @property {string} url Absolute URL (REQUIRED). XML-escaped on emit.
+ * @property {string|Date} [lastModified] Last-modified time, formatted as W3C
+ *   datetime (ISO 8601). A Date is `toISOString()`'d; a string passes through.
+ * @property {'always'|'hourly'|'daily'|'weekly'|'monthly'|'yearly'|'never'} [changeFrequency]
+ *   How often the page changes. An invalid value is dropped (not emitted).
+ * @property {number} [priority] Priority 0.0..1.0. Out-of-range / non-numeric
+ *   is dropped.
+ */
+
+/** Child-sitemap entry for {@link sitemapIndex}.
+ * @typedef {object} SitemapIndexEntry
+ * @property {string} url Absolute URL of a child sitemap (REQUIRED).
+ * @property {string|Date} [lastModified] Last-modified time (W3C datetime).
+ */
+
+const VALID_CHANGEFREQ = new Set([
+  'always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never',
+]);
+
+const MAX_URLS = 50000;
+
+/**
+ * XML-escape text destined for an element body. This is the security-critical
+ * part: a url derived from author data or a DB can contain `&` or `<`, which
+ * would break the XML document or allow injection if emitted raw. The five
+ * predefined XML entities are replaced (`&` first, so the entities the other
+ * replacements introduce are not double-escaped).
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeXml(value) {
+  return String(value)
+    // Strip the C0 control characters XML 1.0 forbids (everything below 0x20
+    // except tab, newline, and carriage return). A stray one from a corrupt
+    // DB-derived URL would otherwise make the WHOLE sitemap document invalid
+    // and silently rejected by search engines, the exact failure this helper
+    // exists to prevent. Done before entity-escaping so it cannot interfere.
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Format a `lastModified` value as a W3C datetime (ISO 8601) string. A Date
+ * becomes its `toISOString()`; a non-empty string passes through verbatim (the
+ * spec accepts both `YYYY-MM-DD` and a full timestamp). Anything else yields
+ * null so the `<lastmod>` element is omitted rather than emitted broken.
+ * @param {string|Date|undefined} value
+ * @returns {string|null}
+ */
+function formatLastmod(value) {
+  if (value instanceof Date) {
+    const ms = value.getTime();
+    if (Number.isNaN(ms)) return null;
+    return value.toISOString();
+  }
+  if (typeof value === 'string' && value.trim() !== '') return value.trim();
+  return null;
+}
+
+/**
+ * Validate + format a `priority` to one decimal in the 0.0..1.0 range. Returns
+ * null (so the element is dropped) for a non-number or an out-of-range value.
+ * @param {number|undefined} value
+ * @returns {string|null}
+ */
+function formatPriority(value) {
+  if (typeof value !== 'number' || Number.isNaN(value)) return null;
+  if (value < 0 || value > 1) return null;
+  return value.toFixed(1);
+}
+
+/**
+ * Serialize an array of {@link SitemapEntry} into a complete `<urlset>` XML
+ * document. Element order per the protocol is loc, lastmod, changefreq,
+ * priority. A malformed entry (missing / non-string / empty `url`) is skipped so
+ * it cannot produce broken XML. Output is deterministic.
+ * @param {SitemapEntry[]} entries
+ * @returns {string} a `<?xml ?>` + `<urlset>` document
+ */
+export function sitemap(entries) {
+  const list = Array.isArray(entries) ? entries : [];
+  if (list.length > MAX_URLS) {
+    console.warn(
+      `[webjs] sitemap() received ${list.length} URLs, over the ${MAX_URLS} per-file limit. ` +
+      'Shard the site with sitemapIndex() instead. Emitting all URLs anyway.'
+    );
+  }
+  const urls = [];
+  for (const entry of list) {
+    if (!entry || typeof entry.url !== 'string' || entry.url.trim() === '') {
+      console.warn('[webjs] sitemap(): skipping an entry with a missing or invalid url');
+      continue;
+    }
+    const parts = [`    <loc>${escapeXml(entry.url.trim())}</loc>`];
+    const lastmod = formatLastmod(entry.lastModified);
+    if (lastmod !== null) parts.push(`    <lastmod>${escapeXml(lastmod)}</lastmod>`);
+    if (typeof entry.changeFrequency === 'string' && VALID_CHANGEFREQ.has(entry.changeFrequency)) {
+      parts.push(`    <changefreq>${entry.changeFrequency}</changefreq>`);
+    }
+    const priority = formatPriority(entry.priority);
+    if (priority !== null) parts.push(`    <priority>${priority}</priority>`);
+    urls.push(`  <url>\n${parts.join('\n')}\n  </url>`);
+  }
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    (urls.length ? urls.join('\n') + '\n' : '') +
+    '</urlset>\n'
+  );
+}
+
+/**
+ * Serialize an array of {@link SitemapIndexEntry} into a `<sitemapindex>` XML
+ * document, one `<sitemap>` per child sitemap URL. Same escaping + lastmod rules
+ * and same skip-malformed-entry behavior as {@link sitemap}. Use it from the
+ * root `app/sitemap.{js,ts}` to point at sharded child sitemaps served by
+ * `route.{js,ts}` handlers.
+ * @param {SitemapIndexEntry[]} sitemaps
+ * @returns {string} a `<?xml ?>` + `<sitemapindex>` document
+ */
+export function sitemapIndex(sitemaps) {
+  const list = Array.isArray(sitemaps) ? sitemaps : [];
+  const items = [];
+  for (const entry of list) {
+    if (!entry || typeof entry.url !== 'string' || entry.url.trim() === '') {
+      console.warn('[webjs] sitemapIndex(): skipping an entry with a missing or invalid url');
+      continue;
+    }
+    const parts = [`    <loc>${escapeXml(entry.url.trim())}</loc>`];
+    const lastmod = formatLastmod(entry.lastModified);
+    if (lastmod !== null) parts.push(`    <lastmod>${escapeXml(lastmod)}</lastmod>`);
+    items.push(`  <sitemap>\n${parts.join('\n')}\n  </sitemap>`);
+  }
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    (items.length ? items.join('\n') + '\n' : '') +
+    '</sitemapindex>\n'
+  );
+}

package/src/testing.js

@@ -0,0 +1,400 @@
+/**
+ * Server-side test harness helpers (issue #267).
+ *
+ * `createRequestHandler(...).handle(request)` drives the FULL webjs pipeline
+ * (middleware, routing, SSR, page actions, server-action RPC, auth + CSRF), and
+ * the framework's own suite already drives it. These helpers are THIN builders
+ * over the native `Request` / `Response` around that `handle()`, so an app test
+ * reads as a one-liner instead of hand-assembling a `Request`, minting a CSRF
+ * pair, or serializing an action payload by hand.
+ *
+ * They are intentionally not a test framework: each is a few lines, returns
+ * native objects, and reuses the REAL cookie / header names (`csrf.js`) and the
+ * REAL wire serializer (`serializer.js` -> `@webjsdev/core`), never a parallel
+ * fake. The most robust auth helper drives the REAL login through `handle()` and
+ * captures the `Set-Cookie`, so it exercises the production cookie shape.
+ *
+ * Usage (a scaffolded app test):
+ *
+ * ```js
+ * import { createRequestHandler } from '@webjsdev/server';
+ * import { testRequest, getCsrf, invokeActionForTest } from '@webjsdev/server/testing';
+ *
+ * const app = await createRequestHandler({ appDir: process.cwd(), dev: true });
+ *
+ * // 1. fire a request through the real pipeline
+ * const res = await testRequest(app.handle, '/about');
+ *
+ * // 2. round-trip an action through the real /__webjs/action/<hash>/<fn> path
+ * const out = await invokeActionForTest(app, 'modules/m/act.server.js', 'echo', [new Date()]);
+ * ```
+ *
+ * @module testing
+ */
+
+import { hashFile, RPC_CONTENT_TYPE } from './actions.js';
+import { CSRF_COOKIE, CSRF_HEADER } from './csrf.js';
+import { getSerializer } from './serializer.js';
+import { join, sep } from 'node:path';
+
+/**
+ * A `handle` is whatever `createRequestHandler(...).handle` is: a function
+ * taking a native `Request` and returning a `Promise<Response>`.
+ * @typedef {(req: Request) => Promise<Response>} Handle
+ */
+
+/** Dummy origin used to turn a bare path (`/about`) into an absolute URL. */
+const DUMMY_ORIGIN = 'http://webjs.test';
+
+/**
+ * Coerce a path-or-Request `input` into a native `Request`.
+ *
+ * A string starting with `/` is prefixed with a dummy origin (the pipeline only
+ * reads `url.pathname` + `url.search`, so the origin is irrelevant); a full URL
+ * string is used as-is; a `Request` is passed through (with `init` overrides
+ * merged when provided).
+ *
+ * @param {string | Request} input
+ * @param {RequestInit} [init]
+ * @returns {Request}
+ */
+export function toRequest(input, init) {
+  if (input instanceof Request) {
+    return init ? new Request(input, init) : input;
+  }
+  const url = input.startsWith('/') ? DUMMY_ORIGIN + input : input;
+  return new Request(url, init);
+}
+
+/**
+ * Fire a request through the real `handle()` pipeline and return the `Response`.
+ *
+ * The documented one-liner: `const res = await testRequest(app.handle, '/about')`.
+ * Accepts a bare path (prefixed with a dummy origin), a full URL string, or a
+ * pre-built `Request`. `init` is the standard `RequestInit` (method, headers,
+ * body, ...).
+ *
+ * @param {Handle} handle
+ * @param {string | Request} input
+ * @param {RequestInit} [init]
+ * @returns {Promise<Response>}
+ */
+export function testRequest(handle, input, init) {
+  return handle(toRequest(input, init));
+}
+
+/**
+ * Read the `webjs_csrf` cookie value off a response's `Set-Cookie` header(s).
+ * Returns null when the response set no CSRF cookie.
+ *
+ * @param {Response} res
+ * @returns {string | null}
+ */
+export function readCsrfCookie(res) {
+  const cookies = getSetCookies(res);
+  for (const c of cookies) {
+    const m = new RegExp(`(?:^|\\s)${CSRF_COOKIE}=([^;]+)`).exec(c);
+    if (m) {
+      try { return decodeURIComponent(m[1]); } catch { return m[1]; }
+    }
+  }
+  return null;
+}
+
+/**
+ * Collect every `Set-Cookie` value off a `Response`, preferring the
+ * structured `getSetCookie()` (which keeps multiple cookies separate) and
+ * falling back to the single combined header.
+ *
+ * @param {Response} res
+ * @returns {string[]}
+ */
+export function getSetCookies(res) {
+  const h = res.headers;
+  if (typeof h.getSetCookie === 'function') {
+    const list = h.getSetCookie();
+    if (list && list.length) return list;
+  }
+  const single = h.get('set-cookie');
+  return single ? [single] : [];
+}
+
+/**
+ * Turn a list of `Set-Cookie` header values into a single `Cookie` request
+ * header value (`name=value; name2=value2`). Strips the cookie attributes
+ * (`Path`, `Max-Age`, ...), keeping only the `name=value` pair of each.
+ *
+ * @param {string[]} setCookies
+ * @returns {string}
+ */
+export function cookiesToHeader(setCookies) {
+  return setCookies
+    .map((c) => c.split(';', 1)[0].trim())
+    .filter(Boolean)
+    .join('; ');
+}
+
+/**
+ * Do an initial GET to mint a CSRF token, returning the `{ cookie, token }`
+ * pair so a test can send a CSRF-valid action request. `cookie` is a ready-made
+ * `Cookie` request-header value; `token` is the bare value for the
+ * `x-webjs-csrf` header. Reuses the REAL cookie / header names from `csrf.js`.
+ *
+ * @param {Handle} handle
+ * @param {string} [path] the GET path used to issue the cookie (default `/`)
+ * @returns {Promise<{ cookie: string, token: string, header: string }>}
+ */
+export async function getCsrf(handle, path = '/') {
+  const res = await testRequest(handle, path);
+  const token = readCsrfCookie(res);
+  if (!token) {
+    throw new Error(
+      `getCsrf: GET ${path} issued no ${CSRF_COOKIE} cookie. The first SSR ` +
+      `response issues it; hit a real page route (or pass a path that renders).`,
+    );
+  }
+  return {
+    token,
+    header: CSRF_HEADER,
+    cookie: `${CSRF_COOKIE}=${encodeURIComponent(token)}`,
+  };
+}
+
+/**
+ * Merge an extra cookie string into a `RequestInit`'s `Cookie` header,
+ * preserving any cookie already on `init.headers`.
+ *
+ * @param {RequestInit} [init]
+ * @param {string} cookieValue a `name=value; name2=value2` string
+ * @returns {RequestInit}
+ */
+export function withCookies(init = {}, cookieValue) {
+  const headers = new Headers(init.headers || {});
+  const existing = headers.get('cookie');
+  headers.set('cookie', existing ? `${existing}; ${cookieValue}` : cookieValue);
+  return { ...init, headers };
+}
+
+/**
+ * Attach an auth/session cookie (captured from a real login `Set-Cookie`) to a
+ * `RequestInit` so a follow-up request hits a protected route as the logged-in
+ * user. A thin convenience over `withCookies`; the cookie value comes from the
+ * REAL session mechanism (see `loginAndGetCookies`), never a fabricated shape.
+ *
+ * @param {RequestInit} [init]
+ * @param {string} sessionCookie a `Cookie` header value (e.g. from `loginAndGetCookies`)
+ * @returns {RequestInit}
+ */
+export function withSessionCookie(init = {}, sessionCookie) {
+  return withCookies(init, sessionCookie);
+}
+
+/**
+ * Drive the REAL credentials login through `handle()` and return the resulting
+ * cookies as a ready-to-reuse `Cookie` request-header value, so a test can hit a
+ * protected route as a logged-in user. This exercises the production auth flow
+ * (the `app/api/auth/[...path]/route.ts` handler + `createAuth`'s
+ * `Set-Cookie`), so the captured cookie is the genuine signed session cookie,
+ * not a fabricated one.
+ *
+ * Defaults target `createAuth`'s credentials sign-in route
+ * (`POST /api/auth/signin/credentials`, the path its handler actually routes a
+ * credentials login through), posting a urlencoded `email` + `password`.
+ * Override `loginPath` / `body` / `method` for a different auth wiring.
+ *
+ * @param {Handle} handle
+ * @param {{ email: string, password: string }} credentials
+ * @param {{
+ *   loginPath?: string,
+ *   method?: string,
+ *   body?: BodyInit,
+ *   contentType?: string,
+ *   expectStatuses?: number[],
+ * }} [opts]
+ * @returns {Promise<{ cookies: string, setCookies: string[], response: Response }>}
+ *   `cookies` is the combined `Cookie` header value; `setCookies` is the raw
+ *   `Set-Cookie` list; `response` is the login response (a 302 on success).
+ */
+export async function loginAndGetCookies(handle, credentials, opts = {}) {
+  const loginPath = opts.loginPath || '/api/auth/signin/credentials';
+  const method = opts.method || 'POST';
+  const contentType = opts.contentType || 'application/x-www-form-urlencoded';
+  const body =
+    opts.body != null
+      ? opts.body
+      : new URLSearchParams({
+          email: credentials.email,
+          password: credentials.password,
+        }).toString();
+
+  const res = await testRequest(handle, loginPath, {
+    method,
+    headers: { 'content-type': contentType },
+    body,
+  });
+
+  const setCookies = getSetCookies(res);
+  const cookies = cookiesToHeader(setCookies);
+  if (!cookies) {
+    throw new Error(
+      `loginAndGetCookies: POST ${loginPath} returned no Set-Cookie (status ` +
+      `${res.status}). The credentials were likely rejected, or the login path ` +
+      `is wrong for this app's auth wiring (override opts.loginPath / opts.body).`,
+    );
+  }
+  return { cookies, setCookies, response: res };
+}
+
+/**
+ * Compute the RPC endpoint path for an action, addressing it the same way the
+ * generated client stub does: by the SHA-256 hash of the action's ABSOLUTE file
+ * path (`hashFile` in `actions.js`, the single source of truth) plus the
+ * exported function name.
+ *
+ * `serverFilePath` may be absolute, or relative to `appDir` (joined with the
+ * OS separator, matching `resolveServerModule`).
+ *
+ * @param {string} appDir the app root passed to `createRequestHandler`
+ * @param {string} serverFilePath the `.server.{js,ts}` file (absolute or appDir-relative)
+ * @param {string} fnName the exported action function name
+ * @returns {Promise<string>} the path, e.g. `/__webjs/action/<hash>/<fn>`
+ */
+export async function actionEndpoint(appDir, serverFilePath, fnName) {
+  const abs = isAbsolutePath(serverFilePath)
+    ? serverFilePath
+    : join(appDir, serverFilePath.split('/').join(sep));
+  const hash = await hashFile(abs);
+  return `/__webjs/action/${hash}/${fnName}`;
+}
+
+/** @param {string} p */
+function isAbsolutePath(p) {
+  return p.startsWith('/') || /^[A-Za-z]:[\\/]/.test(p);
+}
+
+/**
+ * Round-trip a registered server action through the REAL
+ * `/__webjs/action/<hash>/<fn>` endpoint: serialize `args` with the webjs
+ * serializer (exactly as the client stub does), POST them with a valid CSRF
+ * cookie + header, and parse the response with the serializer.
+ *
+ * Unlike a DIRECT import of the action (which calls the function in-process),
+ * this exercises the production path: CSRF validation, the wire serializer
+ * round-trip (so a `Date` / `Map` / `BigInt` arg or return is genuinely
+ * encoded + decoded), and prod error sanitization (a thrown error surfaces as a
+ * sanitized message, never the stack). That is why it catches a
+ * serializer / CSRF / error-sanitization regression a direct import would miss.
+ *
+ * The action is addressed via `actionEndpoint` (the file-path hash + fn name),
+ * the same scheme the generated stub uses.
+ *
+ * On a non-2xx response the parsed `error` is thrown as an `Error` whose
+ * `status` property carries the HTTP status, mirroring the client stub's
+ * behavior (so a CSRF 403 or a sanitized 500 surfaces as a throw a test can
+ * assert on).
+ *
+ * @param {{ handle: Handle, appDir: string } | Handle} app
+ *   the handler object (`{ handle, appDir }`, e.g. the `createRequestHandler`
+ *   return) or, when you pass `opts.appDir` and `opts.endpoint`, just the
+ *   `handle` function.
+ * @param {string} serverFilePath the `.server.{js,ts}` action file (absolute or appDir-relative)
+ * @param {string} fnName the exported action function name
+ * @param {unknown[]} [args] positional args (serialized as the stub sends an arg array)
+ * @param {{
+ *   csrf?: { cookie: string, token: string },
+ *   appDir?: string,
+ *   extraCookies?: string,
+ *   throwOnError?: boolean,
+ * }} [opts]
+ * @returns {Promise<any>} the parsed action return value
+ */
+export async function invokeActionForTest(app, serverFilePath, fnName, args = [], opts = {}) {
+  const handle = typeof app === 'function' ? app : app.handle;
+  const appDir = opts.appDir || (typeof app === 'object' ? app.appDir : undefined);
+  if (!appDir) {
+    throw new Error(
+      'invokeActionForTest: appDir unknown. Pass the createRequestHandler ' +
+      'return value (which carries appDir), or set opts.appDir.',
+    );
+  }
+  const throwOnError = opts.throwOnError !== false;
+
+  const endpoint = await actionEndpoint(appDir, serverFilePath, fnName);
+  const csrf = opts.csrf || (await getCsrf(handle));
+
+  const serializer = getSerializer();
+  const body = await serializer.serialize(args);
+
+  let cookie = csrf.cookie || `${CSRF_COOKIE}=${encodeURIComponent(csrf.token)}`;
+  if (opts.extraCookies) cookie = `${cookie}; ${opts.extraCookies}`;
+
+  const res = await testRequest(handle, endpoint, {
+    method: 'POST',
+    headers: {
+      'content-type': RPC_CONTENT_TYPE,
+      [CSRF_HEADER]: csrf.token,
+      cookie,
+    },
+    body,
+  });
+
+  const text = await res.text();
+  const ct = res.headers.get('content-type') || '';
+  let parsed;
+  if (ct.includes(RPC_CONTENT_TYPE)) parsed = serializer.deserialize(text);
+  else if (ct.includes('application/json')) parsed = text ? JSON.parse(text) : null;
+  else parsed = text;
+
+  if (!res.ok && throwOnError) {
+    const msg = (parsed && parsed.error) || `webjs action ${fnName} -> ${res.status}`;
+    const err = /** @type {Error & { status?: number, response?: Response }} */ (new Error(msg));
+    err.status = res.status;
+    err.response = res;
+    throw err;
+  }
+  return parsed;
+}
+
+/**
+ * Lower-level variant of `invokeActionForTest` that returns the raw `Response`
+ * (never throws on a non-2xx), so a test can assert on the status directly
+ * (e.g. a CSRF-missing request returns 403). Send `opts.csrf = null` /
+ * `opts.omitCsrf = true` to deliberately omit the CSRF header + cookie.
+ *
+ * @param {{ handle: Handle, appDir: string } | Handle} app
+ * @param {string} serverFilePath
+ * @param {string} fnName
+ * @param {unknown[]} [args]
+ * @param {{
+ *   csrf?: { cookie: string, token: string } | null,
+ *   omitCsrf?: boolean,
+ *   appDir?: string,
+ *   extraCookies?: string,
+ *   contentType?: string,
+ * }} [opts]
+ * @returns {Promise<Response>}
+ */
+export async function rawActionRequest(app, serverFilePath, fnName, args = [], opts = {}) {
+  const handle = typeof app === 'function' ? app : app.handle;
+  const appDir = opts.appDir || (typeof app === 'object' ? app.appDir : undefined);
+  if (!appDir) {
+    throw new Error('rawActionRequest: appDir unknown. Pass the handler object or set opts.appDir.');
+  }
+  const endpoint = await actionEndpoint(appDir, serverFilePath, fnName);
+  const serializer = getSerializer();
+  const body = await serializer.serialize(args);
+
+  /** @type {Record<string,string>} */
+  const headers = { 'content-type': opts.contentType || RPC_CONTENT_TYPE };
+  if (!opts.omitCsrf && opts.csrf !== null) {
+    const csrf = opts.csrf || (await getCsrf(handle));
+    headers[CSRF_HEADER] = csrf.token;
+    let cookie = csrf.cookie || `${CSRF_COOKIE}=${encodeURIComponent(csrf.token)}`;
+    if (opts.extraCookies) cookie = `${cookie}; ${opts.extraCookies}`;
+    headers.cookie = cookie;
+  } else if (opts.extraCookies) {
+    headers.cookie = opts.extraCookies;
+  }
+
+  return testRequest(handle, endpoint, { method: 'POST', headers, body });
+}

package/src/vendor.js

@@ -462,6 +462,7 @@ export async function vendorImportMapEntries(bareImports, appDir) {
  */
 export function clearVendorCache() {
   jspmCache.clear();
+  liveIntegrityCache.clear();
 }
 
 // ---------------------------------------------------------------------------
@@ -1299,10 +1300,12 @@ function maxSemverVersion(versions) {
  *   2. Live api.jspm.io/generate (fallback when no pin file exists)
  *
  * Returns both `imports` (the URL map) and `integrity` (SRI hashes
- * keyed by URL). Integrity is populated only from the pin file;
- * live-API mode skips it (would require per-package fetches just to
- * hash, defeating the live-mode speed advantage. Users who want SRI
- * run `webjs vendor pin`).
+ * keyed by the FINAL URL). Integrity is populated on BOTH paths (#235):
+ * the pin file supplies it directly, and the live-API path now hashes
+ * each cross-origin bundle after resolving (bounded + fail-open, see
+ * `computeLiveIntegrity`), so an unpinned app also serves SRI. A fetch
+ * failure for one URL degrades to a missing hash for that URL plus a
+ * one-time warning, never a broken resolve.
  *
  * @param {string} appDir
  * @param {() => Promise<Set<string>>} getBareImports lazy scan, invoked ONLY
@@ -1358,6 +1361,130 @@ export function prunePinToReachable(imports, integrity, reachable) {
   return { imports: keptImports, integrity: keptIntegrity };
 }
 
+/**
+ * Per-process cache of SHA-384 integrity hashes for live-resolved vendor
+ * URLs, keyed by the FINAL cross-origin URL. A vendor bundle at a given
+ * versioned URL is immutable, so once hashed it never needs re-fetching
+ * within the process: a re-resolve (e.g. after a file-watcher rebuild
+ * that did not change the dep) reuses the hash instead of re-downloading.
+ * Cleared by `clearVendorCache` alongside the jspm fragment cache so a
+ * version bump re-hashes. This is NOT a persistent cache (that is the pin
+ * file's job); it only avoids redundant fetches in one running process.
+ *
+ * @type {Map<string, string>}
+ */
+const liveIntegrityCache = new Map();
+
+const INTEGRITY_FETCH_TIMEOUT_MS = 10_000;
+// Cap concurrent bundle fetches so a large dep set does not open dozens of
+// sockets at once during warmup. Matches the bounded posture of the rest of
+// vendor.js (the jspm resolve is per-package but the network is the shared
+// constraint).
+const INTEGRITY_FETCH_CONCURRENCY = 6;
+// Total wall-clock budget for the whole live-integrity hashing phase. It runs
+// inside the readiness-gating warmup, so even a CDN that serves the importmap
+// then hangs on every bundle GET must not stall the first request for the sum
+// of per-fetch timeouts. Once the budget passes, the remaining URLs are left
+// without integrity (the same fail-open fallback as a fetch failure) instead of
+// waiting out a 10s timeout each. A healthy CDN finishes in well under this.
+const INTEGRITY_TOTAL_BUDGET_MS = 15_000;
+
+/**
+ * Fetch a single cross-origin URL with a bounded timeout and return its
+ * SHA-384 SRI hash, or null on any failure (network, timeout, non-ok).
+ * Fail-OPEN by design: a CDN hiccup must never break warmup, so a failure
+ * is a skipped hash (the URL serves without `integrity`, the pre-#235
+ * behavior for that one URL), not a thrown error.
+ *
+ * @param {string} url
+ * @returns {Promise<string | null>}
+ */
+async function fetchLiveIntegrity(url) {
+  const cached = liveIntegrityCache.get(url);
+  if (cached) return cached;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), INTEGRITY_FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) return null;
+    // Hash the raw response bytes (arrayBuffer -> Uint8Array), the same
+    // primitive the browser's SRI implementation hashes. Decoding to a
+    // string first would risk encoding round-trip drift. See the matching
+    // comment in downloadBundle / fetchIntegrity.
+    const buf = new Uint8Array(await response.arrayBuffer());
+    const sri = await sha384Integrity(buf);
+    liveIntegrityCache.set(url, sri);
+    return sri;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Compute SRI integrity for the CROSS-ORIGIN targets of a live-resolved
+ * import map. Same-origin targets (the `@webjsdev/core/*` runtime under
+ * `/__webjs/core/...` and any local `/__webjs/vendor/...` bundle) are
+ * skipped: they are served by the framework and already trusted, and SRI
+ * is a cross-origin defense.
+ *
+ * The returned map is keyed by the FINAL URL (the import-map target
+ * value), matching `vendorIntegrityFor(url)`'s lookup key so ssr.js emits
+ * the `integrity` sibling for free.
+ *
+ * Bounded and fail-open: cross-origin bundles are fetched in parallel with
+ * a small concurrency cap and a per-fetch timeout, and a failed fetch is
+ * skipped (no integrity for that one URL) rather than breaking the resolve.
+ * A single one-time `console.warn` reports the count of URLs that could not
+ * be hashed (no per-URL spam).
+ *
+ * @param {Record<string, string>} imports  specifier -> final URL
+ * @returns {Promise<Record<string, string>>}  integrity keyed by final URL
+ */
+async function computeLiveIntegrity(imports) {
+  // De-duplicate by URL: two specifiers can resolve to the same bundle URL
+  // (a bare import and one of its subpaths), so hash each URL once.
+  const urls = [...new Set(Object.values(imports))].filter((u) => /^https:\/\//.test(u));
+  /** @type {Record<string, string>} */
+  const integrity = {};
+  if (urls.length === 0) return integrity;
+
+  const failed = [];
+  let next = 0;
+  const deadline = Date.now() + INTEGRITY_TOTAL_BUDGET_MS;
+  async function worker() {
+    // Stop claiming new URLs once the total budget passes; a URL already
+    // in flight still settles under its own per-fetch timeout.
+    while (next < urls.length && Date.now() < deadline) {
+      const url = urls[next++];
+      const sri = await fetchLiveIntegrity(url);
+      if (sri) integrity[url] = sri;
+      else failed.push(url);
+    }
+  }
+  const workerCount = Math.min(INTEGRITY_FETCH_CONCURRENCY, urls.length);
+  await Promise.all(Array.from({ length: workerCount }, worker));
+  // Any URL never claimed because the budget passed also fails open (served
+  // without integrity), the same outcome as a fetch failure.
+  while (next < urls.length) failed.push(urls[next++]);
+
+  if (failed.length) {
+    // One-time, count-based warning. The app still boots and the imports
+    // still work; only these URLs lack SRI (served as before #235). Run
+    // `webjs vendor pin` to lock in integrity, or retry once the CDN is
+    // healthy. Naming one example URL aids diagnosis without per-URL spam.
+    console.warn(
+      `[webjs] could not compute SRI for ${failed.length} live-resolved ` +
+      `vendor URL(s) (e.g. ${failed[0]}); they will load WITHOUT integrity. ` +
+      `This is a fail-open fallback for a CDN fetch failure or the warmup ` +
+      `time budget; the app still works. Run \`webjs vendor pin\` to lock in ` +
+      `SRI hashes.`,
+    );
+  }
+  return integrity;
+}
+
 export async function resolveVendorImports(appDir, getBareImports) {
   const file = await readPinFile(appDir);
   // A committed pin file IS the import map. The whole-app bare-import scan is
@@ -1366,16 +1493,26 @@ export async function resolveVendorImports(appDir, getBareImports) {
   // solely here, only when there is no pin file.
   if (file) {
     // A pin file is a deterministic disk read: always "ok" (no live CDN call
-    // that could partially fail). This is the recommended prod posture.
+    // that could partially fail). This is the recommended prod posture. The
+    // pin's own integrity is used verbatim; the live-hash path below is NOT
+    // taken for a pinned app.
     return { imports: file.imports, integrity: file.integrity || {}, ok: true };
   }
   lastLiveResolveFailed = false;
   const bareImports = await getBareImports();
   const imports = await vendorImportMapEntries(bareImports, appDir);
+  // Fill the SRI gap for live-resolved (unpinned) apps (#235): hash each
+  // cross-origin bundle and key the integrity by its final URL, the same
+  // shape the pin path uses and `vendorIntegrityFor` looks up. Bounded +
+  // fail-open, so a CDN fetch failure degrades to a missing hash for that
+  // URL (a warning), never a broken resolve. This runs only AFTER a live
+  // resolve produced URLs; if the resolve itself failed there is nothing to
+  // hash.
+  const integrity = await computeLiveIntegrity(imports);
   // ok=false means at least one install could not be resolved (CDN unreachable
   // / timeout / non-ok), so `imports` is partial. The caller must not memoize
   // this as done; it should retry once the CDN recovers.
-  return { imports, integrity: {}, ok: !lastLiveResolveFailed };
+  return { imports, integrity, ok: !lastLiveResolveFailed };
 }
 
 /**