@stelstone/server 0.26.0

package/src/core/handler.mjs

@@ -0,0 +1,209 @@
+/**
+ * The CMS request handler — the single implementation of request policy.
+ *
+ * Everything that decides *whether* and *how* a request runs lives here:
+ * route matching, CORS, authentication, role checks, body parsing, and the
+ * ResponseSpec → Response translation. Runtimes (Node, Cloudflare Workers)
+ * only translate transport; they never make these decisions.
+ *
+ * This exists because the previous design had one policy implementation per
+ * runtime. They drifted, and both of the security defects found in the
+ * 2026-08 audit lived in that drift: a `verify()` that was not awaited in one
+ * shim, and an admin-role check that passed unauthenticated requests in the
+ * other. With a single chain, that class of bug cannot recur.
+ *
+ * The handler speaks the Web Fetch API:
+ *
+ *   handle(request, env) -> Response | null
+ *
+ * `null` means "no CMS route matched" so the caller can fall through to its
+ * own handling (static files in Node, the assets binding in a Worker).
+ */
+
+import { allRoutes } from "../routes.mjs";
+
+/** Turn "/api/collections/:collection/:file" into a matcher. */
+function compileRoute(route) {
+  const paramNames = [];
+  const pattern = route.path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_, name) => {
+    paramNames.push(name);
+    return "([^/]+)";
+  });
+  return { ...route, regex: new RegExp(`^${pattern}$`), paramNames };
+}
+
+function decodeParam(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/** Query string → plain object (last value wins, matching the previous shims). */
+function queryOf(url) {
+  const query = {};
+  for (const [key, value] of url.searchParams) query[key] = value;
+  return query;
+}
+
+/** ResponseSpec ({ status?, json?, text?, redirect?, headers? }) → Response. */
+function toResponse(spec, baseHeaders) {
+  if (!spec) return new Response(null, { status: 204, headers: baseHeaders });
+
+  const headers = new Headers(baseHeaders);
+  if (spec.headers) {
+    for (const [key, value] of Object.entries(spec.headers)) headers.set(key, value);
+  }
+
+  if (spec.redirect) {
+    headers.set("Location", spec.redirect);
+    return new Response(null, { status: spec.status || 302, headers });
+  }
+
+  const status = spec.status || 200;
+  if (spec.json !== undefined) {
+    headers.set("Content-Type", "application/json");
+    return new Response(JSON.stringify(spec.json), { status, headers });
+  }
+  if (spec.text !== undefined) {
+    headers.set("Content-Type", "text/plain; charset=utf-8");
+    return new Response(spec.text, { status, headers });
+  }
+  return new Response(null, { status, headers });
+}
+
+/**
+ * @param {Object} opts
+ * @param {Object} opts.config                     The site's cms.config object.
+ * @param {Object|Function} opts.adapters          Adapter bag, or (env) => bag
+ *                                                 when adapters are per-request
+ *                                                 (Cloudflare Workers).
+ * @param {"node"|"worker"} [opts.runtime="node"]  Declared by the caller —
+ *        never sniffed. With `nodejs_compat` a Worker also exposes
+ *        `process.versions.node`, so feature detection gets this wrong.
+ * @param {string|null} [opts.adminUiVersion]  Version of the admin UI this
+ *        deployment serves, when the caller resolved one. Reported by
+ *        `/api/about`; null when the SPA is served by something the CMS
+ *        cannot inspect (a Worker's assets binding).
+ * @returns {(request: Request, env?: object) => Promise<Response|null>}
+ */
+export function createRequestHandler({ config, adapters, runtime = "node", adminUiVersion = null }) {
+  const routes = allRoutes(config).map(compileRoute);
+  const resolveAdapters = typeof adapters === "function" ? adapters : () => adapters;
+
+  // Reporting an open CORS policy is config validation's job, not the
+  // handler's — see core/config-schema.mjs.
+  const corsOrigin = config.cors?.origin ?? "*";
+  const corsAllowList = Array.isArray(corsOrigin) ? corsOrigin : [corsOrigin];
+
+  function corsHeaders(request) {
+    const headers = new Headers({
+      "Access-Control-Allow-Methods": "GET,PUT,POST,DELETE,OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type,Authorization",
+    });
+    const origin = request.headers.get("origin");
+    if (corsAllowList.includes("*")) {
+      headers.set("Access-Control-Allow-Origin", "*");
+    } else if (origin && corsAllowList.includes(origin)) {
+      headers.set("Access-Control-Allow-Origin", origin);
+      headers.set("Vary", "Origin");
+    }
+    return headers;
+  }
+
+  /** Does any route own this path, regardless of method? (for 405 vs fall-through) */
+  function pathIsRouted(pathname) {
+    return routes.some((route) => route.regex.test(pathname));
+  }
+
+  return async function handle(request, env) {
+    const url = new URL(request.url);
+    const pathname = url.pathname;
+    const cors = corsHeaders(request);
+
+    // Preflight for any path this handler owns.
+    if (request.method === "OPTIONS" && pathIsRouted(pathname)) {
+      return new Response(null, { status: 204, headers: cors });
+    }
+
+    const match = routes
+      .map((route) => ({ route, m: route.method === request.method && route.regex.exec(pathname) }))
+      .find((candidate) => candidate.m);
+
+    // Not ours — let the caller serve static files / assets / next middleware.
+    if (!match) return null;
+
+    const { route, m } = match;
+    const adapterBag = resolveAdapters(env);
+
+    // ── Authentication ───────────────────────────────────────────────────
+    // One code path, always awaited. `verify` receives the Request so that
+    // adapters which authenticate from something other than the Authorization
+    // header (e.g. Cloudflare Access, which reads its own header or cookie)
+    // are first-class rather than special cases.
+    let user = null;
+    if (route.auth !== "public") {
+      if (!adapterBag.auth.configured) {
+        // No credentials configured at all — the local dev mode. Every adapter
+        // behaves the same here because the decision is made once, here,
+        // rather than inside each adapter's verify(). The server warns loudly
+        // about this at startup.
+        user = { login: "admin", name: "admin", role: "admin" };
+      } else {
+        user = await adapterBag.auth.verify(request);
+        if (!user) {
+          const body =
+            config.auth?.provider === "github-oauth"
+              ? { error: "Authentication required", loginUrl: "/admin/oauth/login" }
+              : { error: "Authentication required" };
+          return toResponse({ status: 401, json: body }, cors);
+        }
+      }
+    }
+
+    // ── Role check ───────────────────────────────────────────────────────
+    // Reached only with a resolved user: unauthenticated requests to a
+    // non-public route were already rejected above.
+    if (route.auth === "admin" && user.role !== "admin") {
+      return toResponse({ status: 403, json: { error: "Admin role required" } }, cors);
+    }
+
+    // ── Body ─────────────────────────────────────────────────────────────
+    // A route with `rawBody` reads the stream itself (the forms endpoint
+    // accepts form-encoded bodies, which a failed .json() would consume).
+    let body = null;
+    if (!route.rawBody && (request.method === "POST" || request.method === "PUT" || request.method === "PATCH")) {
+      try {
+        body = await request.json();
+      } catch {
+        body = null;
+      }
+    }
+
+    const params = {};
+    route.paramNames.forEach((name, i) => {
+      params[name] = decodeParam(m[i + 1]);
+    });
+
+    const ctx = {
+      params,
+      query: queryOf(url),
+      body,
+      user,
+      request,
+      runtime,
+      adminUiVersion,
+      header: (name) => request.headers.get(name),
+      env: (name) => (env && name in env ? env[name] : globalThis.process?.env?.[name]),
+      adapters: adapterBag,
+      config,
+    };
+
+    try {
+      return toResponse(await route.handler(ctx), cors);
+    } catch (err) {
+      return toResponse({ status: 500, json: { error: err.message } }, cors);
+    }
+  };
+}

package/src/core/node-adapter.mjs

@@ -0,0 +1,99 @@
+/**
+ * Node ↔ Fetch transport bridge.
+ *
+ * Translates Node's IncomingMessage/ServerResponse to the Web Fetch
+ * Request/Response the CMS handler speaks, and back. This layer makes no
+ * decisions — no auth, no roles, no routing. It only moves bytes, which is
+ * what a transport adapter should do.
+ */
+
+import { Readable } from "node:stream";
+
+const DEFAULT_BODY_LIMIT = 10 * 1024 * 1024; // 10 MB, matching the old express.json limit
+
+/**
+ * Buffer a request body. Bodies here are JSON documents (pages, templates,
+ * base64 media uploads), so buffering keeps the bridge simple and avoids
+ * half-duplex streaming caveats.
+ */
+async function readBody(req, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > limit) {
+      const err = new Error("Request body too large");
+      err.status = 413;
+      throw err;
+    }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+/** IncomingMessage → Request. */
+export async function nodeToRequest(req, { bodyLimit = DEFAULT_BODY_LIMIT } = {}) {
+  const proto = req.headers["x-forwarded-proto"] || "http";
+  const host = req.headers.host || "localhost";
+  const url = new URL(req.url || "/", `${proto}://${host}`);
+
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) value.forEach((v) => headers.append(key, v));
+    else headers.set(key, value);
+  }
+
+  const method = req.method || "GET";
+  let body;
+  if (method !== "GET" && method !== "HEAD") {
+    // A connect stack upstream may have parsed the body already.
+    if (req.body !== undefined) {
+      body = typeof req.body === "string" ? req.body : JSON.stringify(req.body);
+    } else {
+      const buffered = await readBody(req, bodyLimit);
+      body = buffered.length ? buffered : undefined;
+    }
+  }
+
+  return new Request(url, { method, headers, body });
+}
+
+/** Response → ServerResponse. */
+export async function writeNodeResponse(res, response) {
+  const headers = {};
+  for (const [key, value] of response.headers) headers[key] = value;
+  res.writeHead(response.status, headers);
+
+  if (!response.body) {
+    res.end();
+    return;
+  }
+  Readable.fromWeb(response.body).pipe(res);
+}
+
+/**
+ * Wrap a Fetch-style handler as connect/Vite-compatible middleware.
+ * When the handler returns null the request is passed to `next()`, so the
+ * CMS can be mounted alongside a site's own middleware stack.
+ *
+ * @param {(request: Request) => Promise<Response|null>} handle
+ */
+export function toNodeMiddleware(handle) {
+  return async function cmsMiddleware(req, res, next) {
+    try {
+      const request = await nodeToRequest(req);
+      const response = await handle(request);
+      if (!response) {
+        if (next) return next();
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        return res.end("Not found");
+      }
+      await writeNodeResponse(res, response);
+    } catch (err) {
+      const status = err.status || 500;
+      if (!res.headersSent) res.writeHead(status, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  };
+}

package/src/core/static-files.mjs

@@ -0,0 +1,115 @@
+/**
+ * Minimal static file serving for the Node runtime.
+ *
+ * Replaces express.static / res.sendFile so the server has no web-framework
+ * dependency. Like the Node bridge, this makes no policy decisions.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain; charset=utf-8",
+  ".xml": "application/xml; charset=utf-8",
+  ".pdf": "application/pdf",
+};
+
+export function contentTypeFor(filePath) {
+  return TYPES[path.extname(filePath).toLowerCase()] || "application/octet-stream";
+}
+
+/**
+ * Resolve a URL sub-path inside `root`, refusing anything that escapes it.
+ * The trailing-separator comparison matters: a bare startsWith(root) would
+ * also accept a sibling directory such as "<root>-other".
+ */
+export function resolveWithin(root, subPath) {
+  const rel = decodeURIComponent(String(subPath)).replace(/^\/+/, "");
+  const full = path.resolve(root, rel);
+  if (full !== root && !full.startsWith(root + path.sep)) return null;
+  return full;
+}
+
+/** Send one file as a Response, or null when it is missing/not a file. */
+export function fileResponse(filePath, { status = 200 } = {}) {
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile()) return null;
+
+  return new Response(Readable.toWeb(fs.createReadStream(filePath)), {
+    status,
+    headers: {
+      "Content-Type": contentTypeFor(filePath),
+      "Content-Length": String(stat.size),
+    },
+  });
+}
+
+/**
+ * Serve `root` under the URL prefix `mount`.
+ *
+ * @param {Object} opts
+ * @param {string} opts.root          Absolute directory to serve from.
+ * @param {string} opts.mount         URL prefix, e.g. "/admin" or "/src/assets".
+ * @param {boolean} [opts.spaFallback] Serve index.html for unmatched paths.
+ * @returns {(request: Request) => Response|null}
+ */
+export function createStaticHandler({ root, mount, spaFallback = false }) {
+  const prefix = mount.replace(/\/+$/, "");
+
+  return function serveStatic(request) {
+    if (request.method !== "GET" && request.method !== "HEAD") return null;
+
+    const url = new URL(request.url);
+    const { pathname } = url;
+    if (pathname !== prefix && !pathname.startsWith(`${prefix}/`)) return null;
+
+    // `/admin` → `/admin/`. The SPA's index.html references its bundle
+    // relatively (`./assets/…`), and a browser resolves that against `/admin`
+    // as `/assets/…` — which 404s, leaving a blank page with no error to go on.
+    // Serving index.html at the bare mount is what makes it look like the
+    // admin UI is broken; the slash is what makes the relative URLs resolve.
+    if (prefix && pathname === prefix) {
+      return new Response(null, {
+        status: 301,
+        headers: { Location: `${prefix}/${url.search}` },
+      });
+    }
+
+    const sub = pathname.slice(prefix.length) || "/";
+    const target = resolveWithin(root, sub === "/" ? "index.html" : sub);
+    if (!target) return null;
+
+    const direct = fileResponse(target);
+    if (direct) return direct;
+
+    // Directory → its index.html
+    const asIndex = fileResponse(path.join(target, "index.html"));
+    if (asIndex) return asIndex;
+
+    if (spaFallback) return fileResponse(path.join(root, "index.html"));
+    return null;
+  };
+}

package/src/default-public-config.mjs

@@ -0,0 +1,39 @@
+/**
+ * Derive a safe browser-facing config from the full cms.config object.
+ *
+ * Never exposes: auth credentials env var names, build tokens, git config,
+ * GitHub OAuth secrets, content adapter internals.
+ *
+ * Used automatically by createCmsServer when the consumer does not supply
+ * their own publicConfig function.
+ *
+ * @param {Object} config            Full cms.config object
+ * @param {Object} [overrides={}]    Extra fields merged in at the end (shallow)
+ * @returns {Object}                 Safe subset for the browser
+ */
+export function defaultPublicConfig(config, overrides = {}) {
+  const cfg = {
+    mountPath:         config.mountPath,
+    locales:           config.locales,
+    defaultLocale:     config.defaultLocale,
+    previewUrlPattern: config.previewUrlPattern,
+    media:             config.media,
+    collections:       config.collections,
+    blocks:            config.blocks,
+    content: {
+      provider: config.content?.provider || "fs",
+      // Whether saving and publishing are separate steps. False only on the
+      // github backend without a draft branch — the admin hides Publish there,
+      // because saving already published.
+      deferredPublish:
+        (config.content?.provider || "fs") !== "github" || !!config.content?.draftBranch,
+      list: {
+        strategy:  config.content?.list?.strategy  || "index",
+        rebuild:   config.content?.list?.rebuild   || "build",
+        indexFile: config.content?.list?.indexFile || "_index.json",
+      },
+    },
+    auth:              { provider: config.auth?.provider || "basic" },
+  };
+  return Object.assign(cfg, overrides);
+}

package/src/index.mjs

@@ -0,0 +1,22 @@
+export {
+  createCmsServer,
+  resolveAdminUi,
+  resolveAdminUiOptions,
+  startCmsServer,
+  startScheduler,
+} from "./server.mjs";
+export { createRequestHandler } from "./core/handler.mjs";
+export { toNodeMiddleware, nodeToRequest, writeNodeResponse } from "./core/node-adapter.mjs";
+export { defaultPublicConfig } from "./default-public-config.mjs";
+export {
+  createFsJsonContent,
+  createFsTemplates,
+  createGitHubContent,
+  createGitHubTemplates,
+  createLocalAssetsMedia,
+  createCdnProxyMedia,
+  createBasicAuth,
+  createGitHubOAuth,
+  createNetlifyBuild,
+  createMediaUrl,
+} from "./adapters/index.mjs";