@antelopejs/dms-frontend 0.5.2 → 0.5.4

package/README.md

@@ -159,7 +159,7 @@ The generated Vue application uses `@inertiajs/vue3`, `@nuxt/ui/vite` with `{ ro
 
 Vue modules register through `dms.frontend.ts` and import the SDK from the `#dms/frontend-module` alias, which the loader resolves to the generated `frontend-module.ts`: `defineDmsPlugin`, `useDmsRouter`, the page and session types, and everything else a module needs from the host. Email templates register separately through `dms.email.ts`.
 
-An email entry exports `serverEmailTemplates` and may export a plain `appConfig` object, such as shared branding defaults. Email rendering merges these configurations in manifest-priority order and provides them to `useDmsAppConfig` per render. Public runtime options come from the module manifest; `DMS_CLIENT_BASE_URL` overrides `public.dms.clientBaseUrl`. Email entries must not import the browser frontend module.
+An email entry exports `serverEmailTemplates` and may export a plain `appConfig` object, such as shared branding defaults. Email rendering merges these configurations in manifest-priority order and provides them to `useDmsAppConfig` per render. Public runtime options come from the module manifest; `DMS_CLIENT_BASE_URL` overrides `public.dms.clientBaseUrl`. Email entries must not import the browser frontend module. The rendered HTML carries no Vue hydration comments (`<!--[-->`, `<!---->`, teleport anchors): an email is never hydrated, so the renderer strips them, and keeps every other comment, Outlook's conditional comments included.
 
 Email builds ship complete merged translation catalogs as JSON under `dist/server/locales/`, separate from executable JavaScript. Deploy the entire `dist/server` directory. Each render loads only its requested language and the English fallback; arbitrary translation keys and module overrides remain available. Unknown languages fall back to English, while missing or corrupt files for a supported language fail rendering rather than silently dropping translations. The source harness keeps the 256 KiB JavaScript ceiling and reports locale-data bytes separately.
 
@@ -426,6 +426,57 @@ pair can be turned into a login by a request from the browser. An undeclared
 endpoint is answered `403` and never called. The route is `POST`-only and
 same-origin, like every other auth action.
 
+### Public endpoints
+
+Every state-changing request the server proxies to `/api/` must carry an
+`Origin` matching the frontend's own, and goes out with the signed-in user's
+session. A route meant for callers outside the dashboard — a mail provider's
+delivery webhook, a payment provider's callback — fails both ways: the caller
+sends no `Origin`, and its secret header is not among the few the proxy
+relays.
+
+A backend module declares such a route public when it registers its
+frontend:
+
+```ts
+await AddFrontendModule({
+  name: "@antelopejs/dms-mailing-frontend-vue",
+  sourcePath: path.join(__dirname, "../frontend-vue"),
+  renderer: { name: "vue", version: "3" },
+  publicEndpoints: [
+    {
+      path: "/api/mailing/events/*/*",
+      methods: ["POST"],
+      headers: ["x-mailing-webhook-secret"],
+    },
+  ],
+});
+```
+
+A request to a public endpoint:
+
+- needs no `Origin`;
+- is never sent the session, even from a signed-in browser, so a cross-site
+  form posting to it acts as nobody: the route authenticates its caller
+  itself (a shared secret, a signature);
+- carries the module's declared headers on top of the usual ones.
+
+`path` is an absolute `/api/` path whose first segment is literal (the
+module's own prefix, never `*`) and whose later `*` segments match exactly one
+segment; nothing else matches (no prefix, no query string, no `.` or `..`
+segment). The proxy matches the request's normalized path, the one it sends
+the backend, so `..`, `%2e%2e` or `\` cannot reach another route through a
+public one. `methods` defaults
+to `["POST"]`. `headers` names the module's own `x-` headers; the ones a proxy
+or the DMS gives a meaning to (`x-forwarded-*`, `x-real-ip`, `x-dms-*`,
+`x-inertia*`, method overrides) are refused, as are `authorization` and
+`cookie`. A malformed declaration is dropped whole, with a warning, never
+widened. `DMS_PUBLIC_ENDPOINTS` adds entries of the same shape, as a JSON
+array, for a route no module declares.
+
+Every proxied request also relays `If-Match`, so a backend route can refuse a
+write made from a stale copy (`412` or `409`).
+
 ### Workspaces
 
 Each canonical backend URL gets its own owner-only workspace under
@@ -529,6 +580,7 @@ browser as before.
 | | `DMS_HTML_RENDER_SECRET` | Secret that verifies the backend's signed HTML/email render requests; without it, e-mail renders are refused. Defaults to the `htmlRender.serviceSecret` the backend publishes in the frontend manifest |
 | | `DMS_OAUTH_RELAY_SECRET` | Secret the server presents to the backend's OAuth endpoints; without it, the backend refuses OAuth sign-in. Defaults to the `oauth.relaySecret` the backend publishes in the frontend manifest |
 | | `DMS_AUTH_ESTABLISH_ENDPOINTS` | Extra backend endpoints `/auth/establish` may open a session from, on top of those the backend's modules declare (comma-separated, empty by default) |
+| | `DMS_PUBLIC_ENDPOINTS` | Extra backend routes the proxy serves to anyone, on top of those the backend's modules declare: a JSON array of `{ path, methods?, headers? }` (see [Public endpoints](#public-endpoints)) |
 | | `DMS_CLIENT_BASE_URL` | Public frontend URL used in generated links and emails |
 
 All of these can be set in the project's `.env` instead of the environment; see [Configuration](#configuration).

package/dist/config.d.ts

@@ -11,6 +11,7 @@ export declare const LAYERS_SUBDIR = "frontend-modules";
 export declare const FRONTEND_MODULE_ENTRY = "dms.frontend.ts";
 export declare const FRONTEND_BUILD_ENTRY = "dms.frontend.build.ts";
 export declare const AUTH_ESTABLISH_FILE = "generated-auth-establish.json";
+export declare const PUBLIC_ENDPOINTS_FILE = "generated-public-endpoints.json";
 export declare const LAYER_COPY_BLOCKLIST: readonly string[];
 export declare const layerCopyIgnore: ignore.Ignore;
 export declare const PNPM_LIFECYCLE_SCRIPTS: readonly string[];

package/dist/config.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Options = exports.UsageError = exports.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.AUTH_ESTABLISH_FILE = exports.FRONTEND_BUILD_ENTRY = exports.FRONTEND_MODULE_ENTRY = exports.LAYERS_SUBDIR = exports.TEMPLATE_FILES = exports.WORKSPACE_DIR_MODE = exports.DEPS_HASH_FILE = exports.DMS_FRONTEND_HOME = void 0;
+exports.Options = exports.UsageError = exports.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.PUBLIC_ENDPOINTS_FILE = exports.AUTH_ESTABLISH_FILE = exports.FRONTEND_BUILD_ENTRY = exports.FRONTEND_MODULE_ENTRY = exports.LAYERS_SUBDIR = exports.TEMPLATE_FILES = exports.WORKSPACE_DIR_MODE = exports.DEPS_HASH_FILE = exports.DMS_FRONTEND_HOME = void 0;
 exports.writeSecretBearingFile = writeSecretBearingFile;
 exports.parseBackendUrl = parseBackendUrl;
 exports.requireBackendUrl = requireBackendUrl;
@@ -56,6 +56,7 @@ exports.TEMPLATE_FILES = [
     ["email-renderer.ts", "email-renderer.ts"],
     ["email-runtime.ts", "email-runtime.ts"],
     ["email-locales.ts", "email-locales.ts"],
+    ["email-markup.ts", "email-markup.ts"],
     ["tsconfig.json", "tsconfig.json"],
     ["typecheck-loader.mjs", "typecheck-loader.mjs"],
     ["app-config-stub.mjs", "app-config-stub.mjs"],
@@ -71,6 +72,7 @@ exports.LAYERS_SUBDIR = "frontend-modules";
 exports.FRONTEND_MODULE_ENTRY = "dms.frontend.ts";
 exports.FRONTEND_BUILD_ENTRY = "dms.frontend.build.ts";
 exports.AUTH_ESTABLISH_FILE = "generated-auth-establish.json";
+exports.PUBLIC_ENDPOINTS_FILE = "generated-public-endpoints.json";
 exports.LAYER_COPY_BLOCKLIST = [
     "node_modules",
     "dist",

package/dist/help.js

@@ -41,6 +41,10 @@ exports.ENVIRONMENT_VARIABLES = [
         "DMS_AUTH_ESTABLISH_ENDPOINTS",
         "More backend endpoints /auth/establish may open a session from, comma-separated",
     ],
+    [
+        "DMS_PUBLIC_ENDPOINTS",
+        "More backend routes the proxy serves to anyone, as a JSON array",
+    ],
     ["DMS_CLIENT_BASE_URL", "Public frontend URL used in links and e-mails"],
     ["NO_COLOR", "Same as --no-color"],
     ["ANTELOPEJS_VERBOSE", "Same as --verbose"],

package/dist/layers.js

@@ -126,6 +126,7 @@ function resolveLayer(layerPath, mod) {
         configKey: mod.configKey,
         options: mod.options,
         authEstablishEndpoints: mod.authEstablishEndpoints,
+        publicEndpoints: mod.publicEndpoints,
     };
 }
 function buildLayersFromPaths(modules) {

package/dist/materialize.js

@@ -95,9 +95,16 @@ function writeAuthEstablishEndpoints(workspaceDir, layers) {
     const endpoints = collectAuthEstablishEndpoints(layers);
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, config_1.AUTH_ESTABLISH_FILE), `${JSON.stringify({ endpoints }, null, 2)}\n`);
 }
+function collectPublicEndpoints(layers) {
+    return layers.flatMap((layer) => (Array.isArray(layer.publicEndpoints) ? layer.publicEndpoints : []).filter((endpoint) => typeof endpoint === "object" && endpoint !== null));
+}
+function writePublicEndpoints(workspaceDir, layers) {
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, config_1.PUBLIC_ENDPOINTS_FILE), `${JSON.stringify({ endpoints: collectPublicEndpoints(layers) }, null, 2)}\n`);
+}
 function writeFrontendModuleRegistry(workspaceDir, layers) {
     const registry = (0, derived_outputs_1.createFrontendModuleRegistry)(workspaceDir, layers);
     writeAuthEstablishEndpoints(workspaceDir, layers);
+    writePublicEndpoints(workspaceDir, layers);
     for (const output of derived_outputs_1.DERIVED_OUTPUTS)
         output.write(workspaceDir, registry);
 }

package/dist/workspace.d.ts

@@ -15,6 +15,12 @@ export interface ManifestModule {
     privateOptions?: FrontendModuleOptions;
     configKey?: string;
     authEstablishEndpoints?: string[];
+    publicEndpoints?: PublicEndpointDeclaration[];
+}
+export interface PublicEndpointDeclaration {
+    path: string;
+    methods?: string[];
+    headers?: string[];
 }
 export interface Manifest {
     pack: string;
@@ -34,6 +40,7 @@ export interface ResolvedLayer {
     configKey?: string;
     options?: FrontendModuleOptions;
     authEstablishEndpoints?: string[];
+    publicEndpoints?: PublicEndpointDeclaration[];
 }
 export declare function getWorkspaceDirForKey(key: string): string;
 export declare function projectWorkspaceKey(projectDir: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",

package/templates/vue/email-markup.ts

@@ -0,0 +1,14 @@
+/**
+ * The comments Vue's server renderer leaves for hydration: fragment brackets
+ * (`<!--[-->`, `<!--]-->`), an empty `v-if` branch (`<!---->`, `<!--v-if-->`)
+ * and teleport anchors. An email is never hydrated, so they only weigh on the
+ * message and show in its source. Any other comment, such as Outlook's
+ * conditional comments (`<!--[if mso]>`), is kept.
+ */
+const SSR_MARKERS =
+  /<!--(?:\[|\]|v-if|teleport(?: start| end)?(?: anchor)?|)-->/g;
+
+/** Removes Vue's hydration markers from server-rendered email markup. */
+export function stripSsrMarkers(html: string): string {
+  return html.replace(SSR_MARKERS, "");
+}

package/templates/vue/email-renderer.ts

@@ -4,6 +4,7 @@ import { type Component, createSSRApp, h } from "vue";
 import { createI18n } from "vue-i18n";
 import moduleRegistry from "./generated-frontend-modules.json";
 import { loadEmailLocaleMessages } from "./email-locales";
+import { stripSsrMarkers } from "./email-markup";
 
 interface EmailModule {
   default: Component;
@@ -155,5 +156,5 @@ export async function renderEmail(
     ),
   });
   registerEmailElements(app);
-  return `<!doctype html>${await renderToString(app)}`;
+  return `<!doctype html>${stripSsrMarkers(await renderToString(app))}`;
 }

package/templates/vue/server/auth/oauth.mjs

@@ -1,5 +1,5 @@
 import { timingSafeEqual } from "node:crypto";
-import { backend, json } from "./backend.mjs";
+import { backend, json, UpstreamError } from "./backend.mjs";
 import { clientIp } from "./client-ip.mjs";
 import {
   clearSealedCookie,
@@ -11,6 +11,8 @@ import {
 const FLOW = "dms_oauth_flow";
 const HANDOFF = "dms_oauth_handoff";
 const COMPLETE = "/auth/oauth/complete";
+const OAUTH_ERROR = "error.oauth.";
+const FAILED = "error.oauth.failed";
 const FLOW_LIFETIME_MS = 10 * 60 * 1000;
 const RATE_WINDOW_MS = 60 * 1000;
 const RATE_LIMIT = 10;
@@ -78,13 +80,24 @@ function errorRedirect(response, key) {
   redirect(response, `/auth?oauth_error=${encodeURIComponent(key)}`);
 }
 
+// The backend's own OAuth key says why a provider sign-in failed; any other
+// failure keeps the generic one.
+function failureRedirect(response, error) {
+  errorRedirect(
+    response,
+    error instanceof UpstreamError && error.message.startsWith(OAUTH_ERROR)
+      ? error.message
+      : FAILED,
+  );
+}
+
 export async function oauthStart(request, response, provider, url) {
   if (
     !isValidOAuthProvider(provider) ||
     request.headers["sec-fetch-site"] === "cross-site" ||
     rateLimited(request, "start")
   )
-    return errorRedirect(response, "error.oauth.failed");
+    return errorRedirect(response, FAILED);
   try {
     const result = await backend(
       `/api/auth/oauth/${provider}/authorize-url`,
@@ -104,8 +117,8 @@ export async function oauthStart(request, response, provider, url) {
       FLOW_LIFETIME_MS / 1000,
     );
     redirect(response, result.authorizeUrl);
-  } catch {
-    errorRedirect(response, "error.oauth.failed");
+  } catch (error) {
+    failureRedirect(response, error);
   }
 }
 
@@ -174,14 +187,14 @@ async function completeOAuth(request, response, provider, url, flow) {
         ? `${COMPLETE}?redirect=${encodeURIComponent(flow.redirect)}`
         : COMPLETE,
     );
-  } catch {
-    errorRedirect(response, "error.oauth.failed");
+  } catch (error) {
+    failureRedirect(response, error);
   }
 }
 
 export async function oauthCallback(request, response, provider, url) {
   if (!isValidOAuthProvider(provider) || rateLimited(request, "callback"))
-    return errorRedirect(response, "error.oauth.failed");
+    return errorRedirect(response, FAILED);
   const flow = readSealedCookie(request, FLOW);
   clearSealedCookie(response, FLOW);
   if (url.searchParams.has("error"))

package/templates/vue/server/auth/session.mjs

@@ -14,6 +14,32 @@ const MAX_AGE = 60 * 60 * 24 * 30;
 const UUID =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
+/**
+ * A suffix that keeps this instance's cookies apart from another's on the same
+ * host. Browsers scope cookies by hostname, not port: without it, two DMS
+ * frontends on localhost:3000 and localhost:3001 would overwrite each other's
+ * session, each failing to decrypt the other's and signing the user out. The
+ * suffix follows the backend, so a restart keeps the cookies it wrote.
+ */
+function cookieScope() {
+  const backendUrl = (process.env.DMS_API_BASE_URL ?? "").trim();
+  let canonical = backendUrl;
+  try {
+    const url = new URL(backendUrl);
+    if (url.hostname === "localhost" || url.hostname === "[::1]")
+      url.hostname = "127.0.0.1";
+    canonical = url.toString().replace(/\/$/, "");
+  } catch {
+    // Not a URL: the raw string still tells two backends apart.
+  }
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 12);
+}
+
+/** The name `name` takes in this instance's cookie jar. */
+export function scopedCookieName(name) {
+  return `${name}_${cookieScope()}`;
+}
+
 function key() {
   const secret = process.env.DMS_SESSION_SECRET;
   if (!secret || secret.length < 32)
@@ -54,10 +80,11 @@ function decode(value) {
 }
 
 function cookieValue(request, name) {
+  const scoped = scopedCookieName(name);
   const cookies = request.headers.cookie?.split(";") ?? [];
   return cookies
     .map((part) => part.trim().split("="))
-    .find(([key]) => key === name)?.[1];
+    .find(([key]) => key === scoped)?.[1];
 }
 
 /**
@@ -83,7 +110,8 @@ function lifetime(persistent) {
   return persistent ? MAX_AGE : undefined;
 }
 
-function appendCookie(response, cookie) {
+function appendCookie(response, name, value, cookieAttributes) {
+  const cookie = `${scopedCookieName(name)}=${value}; ${cookieAttributes}`;
   const current = response.getHeader("set-cookie");
   response.setHeader(
     "set-cookie",
@@ -122,12 +150,14 @@ export function setRequestSession(request, session) {
 export function writeSession(response, session) {
   appendCookie(
     response,
-    `${SESSION_COOKIE}=${encode(session)}; ${attributes(lifetime(isPersistent(session)))}`,
+    SESSION_COOKIE,
+    encode(session),
+    attributes(lifetime(isPersistent(session))),
   );
 }
 
 export function clearSession(response) {
-  appendCookie(response, `${SESSION_COOKIE}=; ${attributes(0)}`);
+  appendCookie(response, SESSION_COOKIE, "", attributes(0));
 }
 
 export function readAccounts(request) {
@@ -139,7 +169,9 @@ function writeAccountIndex(response, accounts) {
   const persistent = Object.values(accounts).some(isPersistent);
   appendCookie(
     response,
-    `${ACCOUNT_INDEX_COOKIE}=${encode(accounts)}; ${attributes(lifetime(persistent))}`,
+    ACCOUNT_INDEX_COOKIE,
+    encode(accounts),
+    attributes(lifetime(persistent)),
   );
 }
 
@@ -156,7 +188,9 @@ export function storeAccount(request, response, session, accountId) {
   writeAccountIndex(response, accounts);
   appendCookie(
     response,
-    `${accountCookieName(id)}=${encode({ refreshToken: session.refreshToken, ...accountDescriptor })}; ${attributes(lifetime(accountDescriptor.persistent))}`,
+    accountCookieName(id),
+    encode({ refreshToken: session.refreshToken, ...accountDescriptor }),
+    attributes(lifetime(accountDescriptor.persistent)),
   );
   return accountDescriptor;
 }
@@ -186,10 +220,7 @@ export function removeAccount(request, response, accountId) {
   delete accounts[accountId];
   writeAccountIndex(response, accounts);
   if (UUID.test(accountId ?? ""))
-    appendCookie(
-      response,
-      `${accountCookieName(accountId)}=; ${attributes(0)}`,
-    );
+    appendCookie(response, accountCookieName(accountId), "", attributes(0));
 }
 
 export function readSealedCookie(request, name) {
@@ -204,12 +235,9 @@ export function writeSealedCookie(
   maxAge,
   path = "/auth/oauth",
 ) {
-  appendCookie(
-    response,
-    `${name}=${encode(value)}; ${attributes(maxAge, path)}`,
-  );
+  appendCookie(response, name, encode(value), attributes(maxAge, path));
 }
 
 export function clearSealedCookie(response, name, path = "/auth/oauth") {
-  appendCookie(response, `${name}=; ${attributes(0, path)}`);
+  appendCookie(response, name, "", attributes(0, path));
 }

package/templates/vue/server/public-endpoints.mjs

@@ -0,0 +1,192 @@
+import { readFileSync } from "node:fs";
+import { json } from "./auth/backend.mjs";
+import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./auth/client-ip.mjs";
+
+// Written at the workspace root by the loader, from the endpoints each backend
+// module declared in the frontend manifest. This file sits one directory up.
+const DECLARED_ENDPOINTS_FILE = new URL(
+  "../generated-public-endpoints.json",
+  import.meta.url,
+);
+
+// An absolute backend API path whose first segment is literal (a `*` there
+// would open a route of every module) and whose next ones are literal or `*`
+// (exactly one segment): no prefix match, no query string, no segment that
+// climbs out. Kept in step with `PUBLIC_PATH` in the DMS
+// (`frontend-public-endpoints.ts`), which validates the modules' declarations.
+const PUBLIC_PATH =
+  /^\/api\/[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/(?:\*|[A-Za-z0-9][A-Za-z0-9._~-]*))*$/;
+const SEGMENT_WILDCARD = "*";
+const SEGMENT_PATTERN = "[^/]+";
+const ALLOWED_METHODS = new Set([
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+]);
+const DEFAULT_METHODS = ["POST"];
+// A declared header is a module's own `x-` header. Those the proxy, a reverse
+// proxy or the backend give a meaning to are never taken from the caller.
+// Kept in step with the DMS's `RESERVED_HEADER`.
+const HEADER_NAME = /^x-[a-z0-9-]+$/;
+const RESERVED_HEADER =
+  /^x-(?:forwarded-|real-ip$|dms-|inertia|http-method|method-override|original-|rewrite-)/;
+
+let declaredEndpoints;
+
+/**
+ * The public endpoints the modules of this deployment declared, unchecked.
+ *
+ * @param file Generated file to read
+ * @returns The declared entries, or none when the file is absent or broken
+ */
+export function readDeclaredPublicEndpoints(file = DECLARED_ENDPOINTS_FILE) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    return Array.isArray(parsed?.endpoints) ? parsed.endpoints : [];
+  } catch {
+    return [];
+  }
+}
+
+function environmentEndpoints(declaration) {
+  if (!declaration?.trim()) return [];
+  try {
+    const parsed = JSON.parse(declaration);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    console.warn("Ignoring DMS_PUBLIC_ENDPOINTS: not a JSON array");
+    return [];
+  }
+}
+
+function normalizedMethods(methods) {
+  if (methods === undefined) return DEFAULT_METHODS;
+  if (!Array.isArray(methods) || methods.length === 0) return undefined;
+  const upper = methods.map((method) => String(method).toUpperCase());
+  return upper.every((method) => ALLOWED_METHODS.has(method))
+    ? upper
+    : undefined;
+}
+
+function normalizedHeaders(headers) {
+  if (headers === undefined) return [];
+  if (!Array.isArray(headers)) return undefined;
+  const lower = headers.map((name) => String(name).toLowerCase());
+  return lower.every(
+    (name) => HEADER_NAME.test(name) && !RESERVED_HEADER.test(name),
+  )
+    ? lower
+    : undefined;
+}
+
+function pathMatcher(path) {
+  const pattern = path
+    .split("/")
+    .map((segment) =>
+      segment === SEGMENT_WILDCARD
+        ? SEGMENT_PATTERN
+        : segment.replaceAll(".", "\\."),
+    )
+    .join("/");
+  return new RegExp(`^${pattern}/?$`);
+}
+
+/**
+ * A declaration made usable, or `undefined` when any part of it is malformed:
+ * a bad entry is dropped whole, never widened to what it might have meant.
+ */
+export function compilePublicEndpoint(entry) {
+  if (typeof entry !== "object" || entry === null) return undefined;
+  if (typeof entry.path !== "string" || !PUBLIC_PATH.test(entry.path))
+    return undefined;
+  const methods = normalizedMethods(entry.methods);
+  const headers = normalizedHeaders(entry.headers);
+  if (!methods || !headers) return undefined;
+  return {
+    path: entry.path,
+    methods,
+    headers,
+    matcher: pathMatcher(entry.path),
+  };
+}
+
+/**
+ * The backend endpoints this deployment serves to anyone: what the backend's
+ * modules declared, plus what `DMS_PUBLIC_ENDPOINTS` adds (a JSON array of the
+ * same `{ path, methods?, headers? }` entries).
+ */
+export function allowedPublicEndpoints(
+  declaration = process.env.DMS_PUBLIC_ENDPOINTS,
+  declared = (declaredEndpoints ??= readDeclaredPublicEndpoints()),
+) {
+  return [...declared, ...environmentEndpoints(declaration)].flatMap(
+    (entry) => {
+      const endpoint = compilePublicEndpoint(entry);
+      if (!endpoint)
+        console.warn(
+          `Ignoring malformed public endpoint ${JSON.stringify(entry)}: expected ` +
+            '{ path: "/api/<prefix>/…" (segments or *), methods?: ["POST"], headers?: ["x-…"] }',
+        );
+      return endpoint ? [endpoint] : [];
+    },
+  );
+}
+
+// Compiled once per value of the environment variable, so a malformed entry
+// is reported once rather than on every request.
+let compiled;
+
+function currentPublicEndpoints() {
+  const declaration = process.env.DMS_PUBLIC_ENDPOINTS;
+  if (!compiled || compiled.declaration !== declaration)
+    compiled = { declaration, endpoints: allowedPublicEndpoints(declaration) };
+  return compiled.endpoints;
+}
+
+/**
+ * The public endpoint a request reaches, if any.
+ *
+ * @param method The request's method
+ * @param pathname The request's normalized path, without its query string
+ * @param endpoints The endpoints to match, this deployment's by default
+ */
+export function matchPublicEndpoint(
+  method,
+  pathname,
+  endpoints = currentPublicEndpoints(),
+) {
+  return endpoints.find(
+    (endpoint) =>
+      endpoint.methods.includes(method) && endpoint.matcher.test(pathname),
+  );
+}
+
+/**
+ * How the proxy treats a request: the public endpoint it reaches, if any, and
+ * whether it is refused for lacking a same-site Origin. A state-changing
+ * request needs one, unless it reaches a public endpoint, which is why the
+ * proxy never sends a public endpoint the session: a cross-site form posting
+ * to it acts as nobody.
+ *
+ * @param request The incoming request
+ * @param safeMethods Methods that change nothing and need no Origin
+ */
+export function proxyAccess(request, safeMethods) {
+  const publicEndpoint = matchPublicEndpoint(
+    request.method,
+    new URL(request.url, "http://frontend.local").pathname,
+  );
+  const isRefused =
+    !publicEndpoint &&
+    !safeMethods.has(request.method) &&
+    !isSameOrigin(request);
+  return { publicEndpoint, isRefused };
+}
+
+/** Answers the 403 of a request `proxyAccess` refused. */
+export function refuseCrossOrigin(response) {
+  json(response, 403, CROSS_ORIGIN_ERROR);
+}

package/templates/vue/server.mjs

@@ -10,7 +10,7 @@ import {
   RequestBodyError,
   UpstreamError,
 } from "./server/auth/backend.mjs";
-import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./server/auth/client-ip.mjs";
+import { proxyAccess, refuseCrossOrigin } from "./server/public-endpoints.mjs";
 import {
   handleAuth,
   publicSession,
@@ -120,15 +120,17 @@ async function developmentServer() {
   return vitePromise;
 }
 
-function backendHeaders(request) {
+function backendHeaders(request, publicEndpoint) {
   const headers = relayedHeaders(request, [
     "accept",
     "content-type",
+    "if-match",
     "user-agent",
     "x-content-language",
     "x-realtime-session",
+    ...(publicEndpoint?.headers ?? []),
   ]);
-  const session = readSession(request);
+  const session = publicEndpoint ? undefined : readSession(request);
   if (session?.accessToken)
     headers.authorization = `Bearer ${session.accessToken}`;
   return headers;
@@ -232,9 +234,9 @@ export function requestOwnership(method, pathname) {
 }
 
 async function proxy(request, response, fallbackOnNotFound = false) {
-  if (!SAFE_METHODS.has(request.method) && !isSameOrigin(request)) {
-    response.writeHead(403, { "content-type": JSON_TYPE });
-    response.end(JSON.stringify(CROSS_ORIGIN_ERROR));
+  const { publicEndpoint, isRefused } = proxyAccess(request, SAFE_METHODS);
+  if (isRefused) {
+    refuseCrossOrigin(response);
     return true;
   }
   const target = new URL(request.url, process.env.DMS_API_BASE_URL);
@@ -245,7 +247,7 @@ async function proxy(request, response, fallbackOnNotFound = false) {
   const upstream = await fetch(target, {
     signal: abandoned.signal,
     method: request.method,
-    headers: backendHeaders(request),
+    headers: backendHeaders(request, publicEndpoint),
     body: ["GET", "HEAD"].includes(request.method) ? undefined : request,
     duplex: "half",
   });