@stelstone/server 0.26.0

package/src/core/adapter-options.mjs

@@ -0,0 +1,167 @@
+/**
+ * Pure config → adapter-options builders.
+ *
+ * The Node server and the Worker construct different adapter sets — only Node
+ * has a filesystem and a git binary — but they were deriving the *same* option
+ * values independently: which env var holds which secret, what `STAGING_BRANCH`
+ * overrides, what the fallbacks are. That is the duplication that produced the
+ * drift between the two runtimes everywhere else, so it lives here once.
+ *
+ * These functions import nothing and touch no environment: secrets arrive
+ * through the injected `secrets(name)` lookup. That keeps them testable, and it
+ * keeps Node-only adapter modules out of the Worker bundle — each runtime still
+ * imports only the factories it can actually run.
+ */
+
+/** @typedef {(name: string) => string|undefined} SecretLookup */
+
+/**
+ * Options for `createGitHubContent`.
+ * @param {Object} config
+ * @param {SecretLookup} secrets
+ */
+export function githubContentOptions(config, secrets) {
+  // GITHUB_REPO ("owner/repo") overrides the config — set where the secrets
+  // already live, so a deploy-button user never edits a file. Lenient about
+  // pasted URLs: the last two path segments are the coordinates.
+  const repoEnv = String(secrets("GITHUB_REPO") ?? "")
+    .replace(/\.git$/, "")
+    .split(/[/:]/)
+    .filter(Boolean)
+    .slice(-2);
+  const [envOwner, envRepo] = repoEnv.length === 2 ? repoEnv : [];
+  return {
+    token: secrets(config.content.githubTokenEnv || "GITHUB_TOKEN"),
+    owner: envOwner || config.content.owner,
+    repo: envRepo || config.content.repo,
+    branch: secrets("STAGING_BRANCH") || config.content.branch || "main",
+    draftBranch: config.content.draftBranch,
+    pagesDir: config.content.pagesDir,
+    commitMessage: config.content.commitMessage,
+    list: config.content.list,
+    collections: config.collections,
+  };
+}
+
+/**
+ * Options for `createFsJsonContent`. Node only.
+ * @param {Object} config
+ * @param {SecretLookup} secrets
+ * @param {string} rootDir
+ */
+export function fsContentOptions(config, secrets, rootDir) {
+  return {
+    rootDir,
+    pagesDir: config.content.pagesDir,
+    publishBranch: secrets("STAGING_BRANCH") || config.content.publishBranch,
+    publishPaths: config.content.publishPaths,
+    commitMessage: config.content.commitMessage,
+    collections: config.collections,
+  };
+}
+
+/** Options for `createGitHubTemplates`. */
+export function githubTemplatesOptions(config, secrets) {
+  return {
+    token: secrets(config.content.githubTokenEnv || "GITHUB_TOKEN"),
+    owner: config.content.owner,
+    repo: config.content.repo,
+    branch: secrets("STAGING_BRANCH") || config.content.branch || "main",
+    templatesDir: config.content.templatesDir,
+    commitMessage: config.content.commitMessage,
+  };
+}
+
+/**
+ * Which auth factory to use, and the options for it.
+ *
+ * Secrets — including every `users[].passEnv` — are resolved here rather than
+ * inside the adapter. An adapter that reads `process.env` itself cannot work in
+ * a Worker, which is exactly why the Worker used to re-resolve the user list by
+ * hand before handing it over.
+ *
+ * @param {Object} config
+ * @param {SecretLookup} secrets
+ * @returns {{ provider: "basic"|"github-oauth"|"cloudflare-access", options: Object }}
+ */
+export function authOptions(config, secrets) {
+  const auth = config.auth ?? {};
+  const provider = auth.provider ?? "basic";
+
+  if (provider === "github-oauth") {
+    return {
+      provider,
+      options: {
+        clientId: secrets(auth.githubClientIdEnv || "GITHUB_CLIENT_ID"),
+        clientSecret: secrets(auth.githubClientSecretEnv || "GITHUB_CLIENT_SECRET"),
+        allowedLogins: auth.allowedLogins || [],
+        roles: auth.roles || {},
+        defaultRole: auth.defaultRole,
+        jwtSecret: secrets(auth.jwtSecretEnv),
+        jwtTtl: auth.jwtTtl,
+      },
+    };
+  }
+
+  if (provider === "cloudflare-access") {
+    return {
+      provider,
+      options: {
+        teamDomain: auth.teamDomain,
+        audience: auth.audience,
+        roles: auth.roles || {},
+        defaultRole: auth.defaultRole || "editor",
+      },
+    };
+  }
+
+  return {
+    provider: "basic",
+    options: {
+      user: secrets(auth.userEnv) || "admin",
+      pass: secrets(auth.passEnv),
+      users: auth.users?.map((entry) => ({
+        ...entry,
+        pass: entry.passEnv ? secrets(entry.passEnv) : entry.pass,
+      })),
+      jwtSecret: secrets(auth.jwtSecretEnv),
+      jwtTtl: auth.jwtTtl,
+    },
+  };
+}
+
+/** Options for `createNetlifyBuild`. */
+export function netlifyBuildOptions(config, secrets) {
+  return {
+    token: secrets(config.build?.netlifyTokenEnv || "NETLIFY_AUTH_TOKEN"),
+    siteId: secrets(config.build?.netlifySiteIdEnv || "NETLIFY_SITE_ID"),
+    defaultBranch:
+      secrets("STAGING_BRANCH") || config.content?.publishBranch || config.content?.branch,
+  };
+}
+
+/**
+ * Options for `createCdnProxyMedia`.
+ * @param {Object} config
+ * @param {Object} auth  The constructed auth adapter (for media tokens).
+ */
+export function cdnMediaOptions(config, auth) {
+  return {
+    baseUrl: config.media.cdnBase,
+    getToken: () => auth.issueMediaToken(config.media.tenantId),
+  };
+}
+
+/**
+ * Options for `createResendMail` — the forms module's delivery. Missing
+ * config.mail means "forms deliver nowhere": the adapter reports
+ * `configured: false` and the route answers 503 instead of pretending.
+ * @param {Object} config
+ * @param {SecretLookup} secrets
+ */
+export function mailOptions(config, secrets) {
+  return {
+    apiKey: secrets(config.mail?.keyEnv || "RESEND_API_KEY"),
+    from: config.mail?.from,
+  };
+}

package/src/core/config-schema.mjs

@@ -0,0 +1,408 @@
+/**
+ * cms.config validation and startup preflight.
+ *
+ * The config was previously read ad hoc, field by field, wherever a value was
+ * needed. Mistakes therefore surfaced as behaviour rather than errors: a typo
+ * in a `passEnv` name produced a user whose password resolved to `undefined`,
+ * which for months meant an account that could be logged into with an empty
+ * password. Nothing announced it.
+ *
+ * So: validate the whole shape up front, refuse to start on an error, and
+ * print what was actually resolved. A wrong config should be loud and
+ * immediate, never quietly wrong.
+ *
+ * No schema library — the CMS ships zero runtime dependencies and this runs in
+ * a Worker, where every kilobyte is in the request path.
+ */
+
+const CONTENT_PROVIDERS = ["fs", "github"];
+const AUTH_PROVIDERS = ["basic", "github-oauth", "cloudflare-access"];
+
+class Report {
+  constructor() {
+    this.errors = [];
+    this.warnings = [];
+  }
+  error(path, message) {
+    this.errors.push({ path, message });
+  }
+  warn(path, message) {
+    this.warnings.push({ path, message });
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function checkContent(config, report, { runtime }) {
+  const content = config.content;
+  if (!isPlainObject(content)) {
+    report.error("content", "is required and must be an object");
+    return;
+  }
+
+  const provider = content.provider ?? "fs";
+  if (!CONTENT_PROVIDERS.includes(provider)) {
+    report.error("content.provider", `must be one of ${CONTENT_PROVIDERS.join(", ")} (got "${provider}")`);
+  }
+  if (!content.pagesDir) {
+    report.error("content.pagesDir", "is required — the directory holding page JSON files");
+  }
+
+  // A Worker has no filesystem and no git binary, so it always talks to GitHub
+  // whatever the config says. Missing repo coordinates are fatal there.
+  const needsRepo = provider === "github" || runtime === "worker";
+  if (needsRepo) {
+    if (!content.owner) report.error("content.owner", 'is required for the github content backend (or set the GITHUB_REPO variable, "owner/repo")');
+    if (!content.repo) report.error("content.repo", 'is required for the github content backend (or set the GITHUB_REPO variable, "owner/repo")');
+    if (!content.branch) report.warn("content.branch", 'not set — defaulting to "main"');
+
+    const draft = content.draftBranch;
+    if (draft !== undefined && (typeof draft !== "string" || !draft)) {
+      report.error("content.draftBranch", "must be a non-empty branch name");
+    } else if (draft && draft === (content.branch || "main")) {
+      report.error("content.draftBranch", "must differ from content.branch — same branch means saving publishes");
+    } else if (!draft) {
+      report.warn(
+        "content.draftBranch",
+        "not set — on this backend saving commits straight to the deploy branch (saving IS publishing)",
+      );
+    }
+  }
+
+  if (provider === "fs" && runtime !== "worker") {
+    if (!content.publishBranch) report.warn("content.publishBranch", "not set — Publish will fail");
+    if (!Array.isArray(content.publishPaths) || content.publishPaths.length === 0) {
+      report.warn("content.publishPaths", "not set — Publish has nothing to stage");
+    }
+  }
+
+  if (content.list && !isPlainObject(content.list)) {
+    report.error("content.list", "must be an object");
+  }
+  if (content.commitMessage !== undefined && typeof content.commitMessage !== "function") {
+    report.error("content.commitMessage", "must be a function (timestamp) => string");
+  }
+}
+
+function checkAuth(config, report, { getSecret }) {
+  const auth = config.auth;
+  if (!isPlainObject(auth)) {
+    report.error("auth", "is required and must be an object");
+    return;
+  }
+
+  const provider = auth.provider ?? "basic";
+  if (!AUTH_PROVIDERS.includes(provider)) {
+    report.error("auth.provider", `must be one of ${AUTH_PROVIDERS.join(", ")} (got "${provider}")`);
+    return;
+  }
+
+  if (provider === "basic") {
+    const users = auth.users;
+    if (users !== undefined && !Array.isArray(users)) {
+      report.error("auth.users", "must be an array");
+      return;
+    }
+    if (Array.isArray(users)) {
+      users.forEach((entry, i) => {
+        const at = `auth.users[${i}]`;
+        if (!isPlainObject(entry)) return report.error(at, "must be an object");
+        if (!entry.user) report.error(`${at}.user`, "is required");
+        if (!entry.pass && !entry.passEnv) {
+          report.error(`${at}`, `user "${entry.user}" needs either pass or passEnv`);
+        }
+        if (entry.role && !["admin", "editor"].includes(entry.role)) {
+          report.warn(`${at}.role`, `unknown role "${entry.role}" — only "admin" grants admin routes`);
+        }
+        // The failure this whole module exists for.
+        if (entry.passEnv && !getSecret(entry.passEnv)) {
+          report.warn(
+            `${at}.passEnv`,
+            `${entry.passEnv} is not set — user "${entry.user}" is DISABLED (check for a typo in the variable name)`,
+          );
+        }
+      });
+    } else if (!auth.passEnv && !auth.userEnv) {
+      report.warn("auth.users", "no users configured — the CMS will run without authentication");
+    }
+  }
+
+  if (provider === "github-oauth") {
+    if (!auth.jwtSecretEnv) report.error("auth.jwtSecretEnv", "is required for github-oauth");
+    else if (!getSecret(auth.jwtSecretEnv)) report.error("auth.jwtSecretEnv", `${auth.jwtSecretEnv} is not set`);
+    if (!Array.isArray(auth.allowedLogins) || auth.allowedLogins.length === 0) {
+      report.warn("auth.allowedLogins", "empty — any GitHub account can sign in");
+    }
+    if (!auth.roles && !auth.defaultRole) {
+      report.warn("auth.defaultRole", 'not set — allowed logins get "editor"');
+    }
+  }
+
+  if (provider === "cloudflare-access") {
+    if (!auth.teamDomain) report.error("auth.teamDomain", "is required for cloudflare-access");
+    if (!auth.audience) report.error("auth.audience", "is required for cloudflare-access");
+  }
+
+  if (auth.jwtSecretEnv && !getSecret(auth.jwtSecretEnv)) {
+    report.warn("auth.jwtSecretEnv", `${auth.jwtSecretEnv} is not set — media tokens cannot be issued`);
+  }
+}
+
+function checkCollections(config, report) {
+  const collections = config.collections;
+  if (!isPlainObject(collections)) {
+    report.error("collections", "is required and must be an object");
+    return;
+  }
+  if (Object.keys(collections).length === 0) {
+    report.warn("collections", "is empty — the admin UI will have nothing to edit");
+  }
+
+  for (const [name, col] of Object.entries(collections)) {
+    const at = `collections.${name}`;
+    if (!isPlainObject(col)) {
+      report.error(at, "must be an object");
+      continue;
+    }
+    if (!col.label) report.warn(`${at}.label`, "not set — the admin UI will show the raw name");
+
+    for (const key of ["listFields", "filters", "metaFields"]) {
+      if (col[key] === undefined) continue;
+      if (!Array.isArray(col[key])) {
+        report.error(`${at}.${key}`, "must be an array");
+        continue;
+      }
+      col[key].forEach((field, i) => {
+        if (!isPlainObject(field) || !field.key) {
+          report.error(`${at}.${key}[${i}]`, "must be an object with a `key`");
+        }
+      });
+    }
+
+    // `sort` is a spec — `{ field, direction }`. An array shape also exists in
+    // older configs; the index builder tolerates it, but the API only sorts by
+    // the object form, so an array silently does nothing. Say so.
+    if (col.sort !== undefined) {
+      if (Array.isArray(col.sort)) {
+        report.warn(
+          `${at}.sort`,
+          "is an array — the list API only applies { field, direction }, so this sort is never used",
+        );
+      } else if (!isPlainObject(col.sort)) {
+        report.error(`${at}.sort`, "must be an object like { field, direction }");
+      } else if (typeof col.sort.field !== "string" || !col.sort.field) {
+        report.error(`${at}.sort.field`, "is required and must be a string");
+      } else if (col.sort.direction && !["asc", "desc"].includes(col.sort.direction)) {
+        report.error(`${at}.sort.direction`, 'must be "asc" or "desc"');
+      }
+    }
+
+    // A relation field points at one or more other collections; a typo there
+    // silently stops names from resolving in list views. `collection` may name
+    // a single target or a list of them — an array reported as one name is how
+    // this check first failed a valid multi-target field.
+    for (const field of col.metaFields || []) {
+      if (!field?.collection) continue;
+      const targets = Array.isArray(field.collection) ? field.collection : [field.collection];
+      if (Array.isArray(field.collection) && targets.length === 0) {
+        report.error(`${at}.metaFields (${field.key})`, "collection list is empty");
+        continue;
+      }
+      for (const target of targets) {
+        if (typeof target !== "string" || !target) {
+          report.error(
+            `${at}.metaFields (${field.key})`,
+            `collection targets must be non-empty strings, got ${JSON.stringify(target)}`,
+          );
+        } else if (!collections[target]) {
+          report.error(
+            `${at}.metaFields (${field.key})`,
+            `references unknown collection "${target}"`,
+          );
+        }
+      }
+    }
+  }
+}
+
+function checkForms(config, report, { getSecret }) {
+  const { forms, mail } = config;
+
+  if (mail !== undefined) {
+    if (!isPlainObject(mail)) {
+      report.error("mail", "must be an object like { from, keyEnv? }");
+    } else {
+      if (!mail.from) report.error("mail.from", 'is required — e.g. "Site <forms@site.com>" (domain must be verified at the provider)');
+      const keyEnv = mail.keyEnv || "RESEND_API_KEY";
+      if (!getSecret(keyEnv)) {
+        report.warn("mail.keyEnv", `${keyEnv} is not set — form delivery will answer 503`);
+      }
+    }
+  }
+
+  if (forms === undefined) return;
+  if (!isPlainObject(forms)) {
+    report.error("forms", "must be an object of formName → definition");
+    return;
+  }
+  if (Object.keys(forms).length && !mail) {
+    report.warn("forms", "defined without config.mail — submissions will answer 503 until mail is configured");
+  }
+  for (const [name, def] of Object.entries(forms)) {
+    const at = `forms.${name}`;
+    if (!isPlainObject(def)) {
+      report.error(at, "must be an object");
+      continue;
+    }
+    if (!def.to || typeof def.to !== "string" || !def.to.includes("@")) {
+      report.error(`${at}.to`, "is required and must be an email address");
+    }
+    if (def.subject !== undefined && typeof def.subject !== "string" && typeof def.subject !== "function") {
+      report.error(`${at}.subject`, "must be a string or a (fields) => string function");
+    }
+    if (def.redirect !== undefined && (typeof def.redirect !== "string" || !def.redirect.startsWith("/"))) {
+      report.error(`${at}.redirect`, 'must be a site-relative path like "/tesekkurler/"');
+    }
+    if (def.turnstile) {
+      const secretEnv = def.turnstileSecretEnv || "TURNSTILE_SECRET";
+      if (!getSecret(secretEnv)) {
+        report.warn(`${at}.turnstile`, `${secretEnv} is not set — verification will answer 503`);
+      }
+    }
+  }
+}
+
+function checkMisc(config, report) {
+  const { locales, defaultLocale } = config;
+  if (locales !== undefined && !Array.isArray(locales)) {
+    report.error("locales", "must be an array");
+  } else if (Array.isArray(locales) && defaultLocale && !locales.includes(defaultLocale)) {
+    report.error("defaultLocale", `"${defaultLocale}" is not in locales [${locales.join(", ")}]`);
+  }
+
+  if (config.media !== undefined) {
+    if (!isPlainObject(config.media)) report.error("media", "must be an object");
+    else if (!config.media.cdnBase) report.error("media.cdnBase", "is required when media is configured");
+  }
+
+  if (config.previewUrl !== undefined && typeof config.previewUrl !== "function") {
+    report.error("previewUrl", "must be a function ({ collection, data }) => string");
+  }
+
+  const corsOrigin = config.cors?.origin ?? "*";
+  const list = Array.isArray(corsOrigin) ? corsOrigin : [corsOrigin];
+  if (list.includes("*") && config.auth?.provider) {
+    report.warn(
+      "cors.origin",
+      "is '*' — any site can call this API in a logged-in user's browser",
+    );
+  }
+}
+
+/**
+ * Validate a cms.config object.
+ *
+ * @param {Object} config
+ * @param {Object} [opts]
+ * @param {"node"|"worker"} [opts.runtime="node"]
+ * @param {(name: string) => string|undefined} [opts.getSecret] Secret lookup;
+ *        defaults to process.env so env-dependent checks work on Node.
+ * @returns {{ errors: {path: string, message: string}[],
+ *             warnings: {path: string, message: string}[] }}
+ */
+export function validateConfig(config, { runtime = "node", getSecret } = {}) {
+  const report = new Report();
+  const lookup = getSecret ?? ((name) => globalThis.process?.env?.[name]);
+
+  if (!isPlainObject(config)) {
+    report.error("config", "must be an object — did cms.config.mjs export a default?");
+    return report;
+  }
+
+  checkContent(config, report, { runtime });
+  checkAuth(config, report, { getSecret: lookup });
+  checkCollections(config, report);
+  checkForms(config, report, { getSecret: lookup });
+  checkMisc(config, report);
+
+  return { errors: report.errors, warnings: report.warnings };
+}
+
+function format(entries) {
+  return entries.map(({ path, message }) => `  ${path} ${message}`).join("\n");
+}
+
+/**
+ * Validate and refuse to continue on error. Warnings are printed, not fatal.
+ *
+ * @throws {Error} with every problem listed, not just the first.
+ */
+export function assertValidConfig(config, opts = {}) {
+  const { errors, warnings } = validateConfig(config, opts);
+  if (warnings.length) {
+    console.warn(`cms.config warnings:\n${format(warnings)}`);
+  }
+  if (errors.length) {
+    throw new Error(`Invalid cms.config (${errors.length} problem${errors.length > 1 ? "s" : ""}):\n${format(errors)}`);
+  }
+  return { warnings };
+}
+
+/**
+ * Human-readable summary of what the config actually resolved to.
+ *
+ * Printed at startup so a misconfiguration is visible in the first lines of
+ * the log instead of being discovered later as odd behaviour.
+ *
+ * @param {Object} config
+ * @param {Object} [opts]
+ * @param {Object} [opts.adapters]  Resolved adapters, for `configured` flags.
+ * @param {(name: string) => string|undefined} [opts.getSecret]
+ * @param {"node"|"worker"} [opts.runtime]
+ * @returns {string[]} lines
+ */
+export function describeConfig(config, { adapters, getSecret, runtime = "node" } = {}) {
+  const lookup = getSecret ?? ((name) => globalThis.process?.env?.[name]);
+  const lines = [];
+
+  const authProvider = config.auth?.provider ?? "basic";
+  if (authProvider === "basic" && Array.isArray(config.auth?.users)) {
+    const active = [];
+    const disabled = [];
+    for (const entry of config.auth.users) {
+      const pass = entry.passEnv ? lookup(entry.passEnv) : entry.pass;
+      (pass ? active : disabled).push(entry);
+    }
+    let line = `auth     basic — ${active.length}/${config.auth.users.length} users active`;
+    if (active.length) line += ` (${active.map((u) => `${u.user}:${u.role || "editor"}`).join(", ")})`;
+    lines.push(line);
+    if (disabled.length) {
+      lines.push(
+        `         DISABLED: ${disabled.map((u) => `${u.user} (${u.passEnv || "no password"})`).join(", ")}`,
+      );
+    }
+  } else {
+    lines.push(`auth     ${authProvider}${adapters?.auth?.configured === false ? " — NOT CONFIGURED (open access)" : ""}`);
+  }
+
+  const provider = runtime === "worker" ? "github" : (config.content?.provider ?? "fs");
+  const target =
+    provider === "github"
+      ? `${config.content?.owner}/${config.content?.repo}@${config.content?.branch || "main"}`
+      : `publish → ${config.content?.publishBranch || "(unset)"}`;
+  lines.push(`content  ${provider} — ${config.content?.pagesDir} (${target})`);
+
+  if (config.media?.cdnBase) {
+    lines.push(`media    ${config.media.cdnBase}${config.media.tenantId ? ` (tenant: ${config.media.tenantId})` : ""}`);
+  }
+  if (adapters?.build) {
+    lines.push(`build    netlify — ${adapters.build.configured ? "configured" : "not configured"}`);
+  }
+
+  const collections = Object.keys(config.collections || {});
+  lines.push(`content model  ${collections.length} collections: ${collections.join(", ")}`);
+
+  return lines;
+}

package/src/core/forms.mjs

@@ -0,0 +1,99 @@
+/**
+ * Form submission helpers — parsing, abuse damping, message assembly.
+ *
+ * The route in routes.mjs is the policy; these are the mechanics. Kept apart
+ * so the Worker runtime can reuse the exact same pieces with its own rate
+ * limiter, and so every rule here is unit-testable without a Request cycle.
+ */
+
+// Hard ceilings, not configuration: a contact form that legitimately needs
+// more than this is a different feature. Oversize is a 400, not a truncation.
+export const FORM_LIMITS = { maxFields: 30, maxFieldLength: 5000, maxTotalLength: 20_000 };
+
+/**
+ * Read submitted fields from a Request: JSON or form-encoded (urlencoded and
+ * multipart both arrive via formData()). File parts are dropped — this module
+ * delivers text messages, not attachments.
+ *
+ * @returns {Promise<Record<string, string> | null>} null on an unreadable body.
+ */
+export async function readFormFields(request) {
+  const type = (request.headers.get("content-type") ?? "").toLowerCase();
+  try {
+    if (type.includes("application/json")) {
+      const data = await request.json();
+      if (typeof data !== "object" || data === null || Array.isArray(data)) return null;
+      const fields = {};
+      for (const [key, value] of Object.entries(data)) {
+        if (typeof value === "string" || typeof value === "number") fields[key] = String(value);
+      }
+      return fields;
+    }
+    const data = await request.formData();
+    const fields = {};
+    for (const [key, value] of data.entries()) {
+      if (typeof value === "string") fields[key] = value;
+    }
+    return fields;
+  } catch {
+    return null;
+  }
+}
+
+/** First violated limit as a message, or null when the submission fits. */
+export function fieldsError(fields) {
+  const entries = Object.entries(fields);
+  if (entries.length > FORM_LIMITS.maxFields) return `Too many fields (max ${FORM_LIMITS.maxFields})`;
+  let total = 0;
+  for (const [key, value] of entries) {
+    if (value.length > FORM_LIMITS.maxFieldLength) {
+      return `Field "${key}" is too long (max ${FORM_LIMITS.maxFieldLength} characters)`;
+    }
+    total += key.length + value.length;
+  }
+  if (total > FORM_LIMITS.maxTotalLength) return `Submission too large (max ${FORM_LIMITS.maxTotalLength} characters)`;
+  return null;
+}
+
+/** Plain-text message body: one `key: value` line per real field. */
+export function formatMessage(fields, { skip = [] } = {}) {
+  const hidden = new Set([...skip, "form-name", "cf-turnstile-response"]);
+  return Object.entries(fields)
+    .filter(([key]) => !hidden.has(key))
+    .map(([key, value]) => `${key}: ${value}`)
+    .join("\n");
+}
+
+/**
+ * Fixed-window in-memory rate limiter for the Node runtime. Per-process by
+ * design — the Node server is a single process, and forms are a trickle.
+ * The Worker runtime uses the KV-backed limiter in @stelstone/worker.
+ */
+export function createMemoryRateLimiter({ limit = 5, windowMs = 60_000 } = {}) {
+  const windows = new Map(); // key → { count, resetAt }
+  return {
+    async allow(key) {
+      const now = Date.now();
+      const entry = windows.get(key);
+      if (!entry || entry.resetAt <= now) {
+        windows.set(key, { count: 1, resetAt: now + windowMs });
+        // Opportunistic cleanup so the map does not grow with dead keys.
+        if (windows.size > 1000) {
+          for (const [k, v] of windows) if (v.resetAt <= now) windows.delete(k);
+        }
+        return true;
+      }
+      entry.count += 1;
+      return entry.count <= limit;
+    },
+  };
+}
+
+/** Client IP for rate-limit keys: Cloudflare's header, then the proxy's. */
+export function clientIp(request) {
+  return (
+    request.headers.get("cf-connecting-ip") ??
+    (request.headers.get("x-forwarded-for") ?? "").split(",")[0].trim() ??
+    "unknown"
+  ) || "unknown";
+}