@antelopejs/dms-frontend 0.5.6 → 0.6.1

package/templates/vue/server/backend-proxies.mjs

@@ -0,0 +1,110 @@
+// The backend prefixes the frontend server proxies. The renderer hardcodes
+// none: a frontend module declares them in its `dms.server.ts`
+// (`registerBackendProxy`), and a backend module in the frontend manifest
+// (`backendProxies`, next to its `publicEndpoints`). A path no prefix covers
+// is never sent to the backend.
+
+import { compilePathPattern } from "./path-patterns.mjs";
+
+/** How the proxy authenticates a request to the backend. */
+export const PROXY_AUTH_MODES = Object.freeze(["session", "none"]);
+const DEFAULT_AUTH = "session";
+/** The renderer's own paths, never a backend's. */
+const RENDERER_PREFIXES = ["/api/_dms", "/@", "/assets", "/node_modules"];
+
+function literalPrefix(pattern) {
+  const segments = pattern === "/" ? [] : pattern.slice(1).split("/");
+  const literal = [];
+  for (const segment of segments) {
+    if (segment === "*" || segment === "**") break;
+    literal.push(segment);
+  }
+  return `/${literal.join("/")}`;
+}
+
+/** Why a proxy declaration is ignored, or `undefined`. */
+export function proxyRejection(pattern, options) {
+  const compiled = compilePathPattern(pattern);
+  if (!compiled) return "the pattern is not /x, /x/* or /x/**";
+  const prefix = literalPrefix(pattern);
+  if (prefix === "/")
+    return "its first segment is not literal: it would take every page";
+  if (
+    RENDERER_PREFIXES.some(
+      (reserved) => prefix === reserved || prefix.startsWith(`${reserved}/`),
+    )
+  )
+    return `${RENDERER_PREFIXES.join(", ")} are the renderer's own paths`;
+  if (options !== undefined && (typeof options !== "object" || !options))
+    return "its options are not an object";
+  if (options?.auth !== undefined && !PROXY_AUTH_MODES.includes(options.auth))
+    return `auth is not one of ${PROXY_AUTH_MODES.map((mode) => `"${mode}"`).join(", ")}`;
+  return undefined;
+}
+
+function compileProxy(pattern, options, owner) {
+  return {
+    pattern: compilePathPattern(pattern),
+    path: pattern,
+    owner,
+    auth: options?.auth ?? DEFAULT_AUTH,
+  };
+}
+
+/**
+ * The deployment's backend proxies, one per pattern.
+ *
+ * @param declared `{ id, pattern, options }` per `registerBackendProxy` call,
+ *   from the highest-priority module down
+ * @param manifest `{ module, path, auth? }` per backend module declaration
+ * @param warn Reports a declaration problem
+ * @returns The proxies, the most specific pattern first: a request reaches
+ *   the first that matches
+ */
+export function resolveBackendProxies(declared, manifest, warn) {
+  const kept = new Map();
+  const add = (pattern, options, owner) => {
+    const reason = proxyRejection(pattern, options);
+    const current = kept.get(pattern);
+    if (reason || current) {
+      warn(
+        `${owner} declares the backend proxy "${pattern}", which is ignored: ${reason ?? `${current.owner} declares it`}.`,
+      );
+      return;
+    }
+    kept.set(pattern, compileProxy(pattern, options, owner));
+  };
+  for (const { id, pattern, options } of declared)
+    add(pattern, options, `Frontend module ${id}`);
+  for (const entry of manifest)
+    add(entry?.path, { auth: entry?.auth }, `Backend module ${entry?.module}`);
+  return [...kept.values()].sort(
+    (left, right) => right.pattern.specificity - left.pattern.specificity,
+  );
+}
+
+/** The backend proxy a path reaches, or `undefined`. */
+export function matchBackendProxy(proxies, pathname) {
+  return proxies.find((proxy) => proxy.pattern.test(pathname));
+}
+
+/**
+ * The lines the server prints at startup: each backend prefix, who declared
+ * it and how it authenticates, then who owns the rest.
+ *
+ * @param proxies What `resolveBackendProxies` returned
+ * @param routeCount The number of module routes
+ */
+export function routingReport(proxies, routeCount) {
+  const width = Math.max(0, ...proxies.map((proxy) => proxy.path.length));
+  const lines = proxies.map(
+    (proxy) =>
+      `  ${proxy.path.padEnd(width)}  -> backend (${proxy.auth}), declared by ${proxy.owner.replace(/^\w+ module /, "")}`,
+  );
+  return [
+    `Routing: renderer files, then ${routeCount} module route${routeCount === 1 ? "" : "s"}, then the backend proxies below, then the pages`,
+    ...(lines.length
+      ? lines
+      : ["  (no backend proxy declared: no request reaches the backend)"]),
+  ];
+}

package/templates/vue/server/dev-private-files.mjs

@@ -0,0 +1,99 @@
+// The files of the workspace the development server never hands to a browser.
+//
+// Vite's root is the workspace root, where the generated server options (the
+// modules' private options: the backend's secrets) and the cached manifest are
+// written, and the modules' server code is materialized under it. Vite serves
+// any file under its root, as is, `?raw`, `?import` or `?url`. Its
+// `server.fs.deny` list covers most of these, but not every query combination
+// (`?import&raw` gets through in Vite 7.2), so a middleware ahead of Vite's own
+// answers 403 by path, whatever the query, and a load guard refuses them to
+// any client request that reaches the transform pipeline another way.
+// `ssrLoadModule`, which loads the server modules, is left alone.
+
+import { relative, resolve, sep } from "node:path";
+
+const PRIVATE_FILE_NAMES = new Set([
+  "generated-server-options.json",
+  ".manifest-cache.json",
+]);
+const SERVER_ENTRY = /^dms\.server\./;
+const MODULES_DIRECTORY = "frontend-modules";
+const FORBIDDEN_STATUS = 403;
+
+/**
+ * Vite's `server.fs.deny` for the development server: Vite's own defaults,
+ * which a `deny` list replaces, and the private files.
+ */
+export const DEV_FS_DENY = [
+  ".env",
+  ".env.*",
+  "*.{crt,pem}",
+  "**/.git/**",
+  ...PRIVATE_FILE_NAMES,
+  "dms.server.*",
+  `**/${MODULES_DIRECTORY}/**/server/**`,
+];
+
+/**
+ * Whether `file`, an absolute path, is private: a generated secret-bearing
+ * file, a module's server entry, or a file under a `server/` directory of a
+ * module materialized under `root`. Compared without case, as a
+ * case-insensitive file system would serve them.
+ */
+export function isPrivateFile(file, root) {
+  const name = (resolve(file).split(/[\\/]/).at(-1) ?? "").toLowerCase();
+  if (PRIVATE_FILE_NAMES.has(name) || SERVER_ENTRY.test(name)) return true;
+  const segments = relative(root, file).toLowerCase().split(/[\\/]/);
+  return (
+    segments[0] === MODULES_DIRECTORY &&
+    segments.slice(1, -1).includes("server")
+  );
+}
+
+function stripQuery(id) {
+  const query = id.search(/[?#]/);
+  return query === -1 ? id : id.slice(0, query);
+}
+
+/** The file a request URL names under `root`, `undefined` when it names none. */
+function requestedFile(url, root) {
+  let pathname;
+  try {
+    pathname = decodeURIComponent(stripQuery(url ?? ""));
+  } catch {
+    return undefined;
+  }
+  if (pathname.startsWith("/@fs/")) return resolve(pathname.slice(4));
+  if (pathname.startsWith("/@id/")) pathname = pathname.slice(4);
+  return resolve(root, `.${sep}${pathname.replace(/^[\\/]+/, "")}`);
+}
+
+/** Answers 403 to private files, and fails a client load of one. */
+export function denyPrivateFiles() {
+  let root = process.cwd();
+  return {
+    name: "dms-deny-private-files",
+    apply: "serve",
+    enforce: "pre",
+    configResolved(config) {
+      root = config.root;
+    },
+    configureServer(server) {
+      // Registered directly, not returned: it runs before Vite's middlewares.
+      server.middlewares.use((request, response, next) => {
+        const file = requestedFile(request.url, root);
+        if (!file || !isPrivateFile(file, root)) return next();
+        response.statusCode = FORBIDDEN_STATUS;
+        response.setHeader("content-type", "text/plain; charset=utf-8");
+        response.end("Forbidden");
+      });
+    },
+    load(id, options) {
+      if (options?.ssr || id.startsWith("\0")) return null;
+      if (!isPrivateFile(stripQuery(id), root)) return null;
+      this.error(
+        `${stripQuery(id)} is private to the server and never served to the browser.`,
+      );
+    },
+  };
+}

package/templates/vue/server/email.mjs

@@ -1,10 +1,7 @@
 import { fork } from "node:child_process";
 import { constants, setPriority } from "node:os";
 import { fileURLToPath } from "node:url";
-import { body } from "./auth/backend.mjs";
-import { validRenderToken } from "./render-token.mjs";
 
-const JSON_TYPE = "application/json";
 const EMAIL_RENDERER_URL = new URL(
   "../dist/server/email-renderer.js",
   import.meta.url,
@@ -78,34 +75,15 @@ async function loadEmailRenderer() {
   return import(url.href);
 }
 
-/** Renders an email template for an authenticated backend request. */
-export async function handleEmailRender(request, response) {
-  if (!validRenderToken(request.headers["x-dms-service-token"])) {
-    response.writeHead(401, { "content-type": JSON_TYPE });
-    return response.end(JSON.stringify({ message: "Invalid service token" }));
-  }
-  const input = await body(request);
-  if (
-    typeof input.templateName !== "string" ||
-    input.templateName.trim() === "" ||
-    typeof input.props !== "object"
-  ) {
-    response.writeHead(400, { "content-type": JSON_TYPE });
-    return response.end(JSON.stringify({ message: "Invalid request body" }));
-  }
-  try {
-    const { renderEmail } = await loadEmailRenderer();
-    const html = await renderEmail(input.templateName, input.props ?? {}, {
-      locale: request.headers["x-content-language"],
-    });
-    response.writeHead(200, { "content-type": JSON_TYPE });
-    response.end(JSON.stringify({ html }));
-  } catch {
-    response.writeHead(404, { "content-type": JSON_TYPE });
-    response.end(
-      JSON.stringify({
-        message: `Template "${input.templateName}" not found or render failed`,
-      }),
-    );
-  }
+/**
+ * Renders an email template of the application's email bundle, waiting for a
+ * development build in progress.
+ *
+ * @param template The template's name
+ * @param props The template's props
+ * @param options `locale`, the language to render in
+ */
+export async function renderEmailTemplate(template, props, options = {}) {
+  const { renderEmail } = await loadEmailRenderer();
+  return renderEmail(template, props, options);
 }

package/templates/vue/server/favicon.mjs

@@ -0,0 +1,20 @@
+// The favicon placeholder of a page whose render declares no icon.
+//
+// A document without any `<link rel="icon">` makes the browser ask for
+// `/favicon.ico`, a request the frontend server would pass on to the backend
+// on every page load. An empty data URL stops it. The template used to carry
+// that placeholder itself, but a module declaring real icons through `useHead`
+// (light and dark, one per `prefers-color-scheme`) then competed with it, and
+// the browser could keep the empty one: it only goes in when the rendered head
+// has no icon of its own.
+
+const FAVICON_PLACEHOLDER = '<link rel="icon" href="data:," />';
+/** A `<link>` whose `rel` holds the `icon` token, `shortcut icon` included. */
+const ICON_LINK = /<link\b[^>]*\srel=(["'])(?:[^"']*\s)?icon(?:\s[^"']*)?\1/i;
+
+/** The rendered head tags, behind the placeholder when they hold no icon. */
+export function withFaviconPlaceholder(headTags) {
+  return ICON_LINK.test(headTags)
+    ? headTags
+    : `${FAVICON_PLACEHOLDER}${headTags}`;
+}

package/templates/vue/server/inertia.mjs

@@ -32,13 +32,58 @@ export function inertiaAppHtml(page) {
   return `<script data-page="app" type="application/json">${serialized}</script><div id="app"></div>`;
 }
 
-export function createInertiaPage(url, props, version = assetVersion()) {
-  return {
-    component: "DmsDynamicPage",
+/** The one Inertia component every DMS page renders through. */
+export const DMS_PAGE_COMPONENT = "DmsDynamicPage";
+
+export function createInertiaPage(
+  url,
+  props,
+  version = assetVersion(),
+  onceProps,
+) {
+  const page = {
+    component: DMS_PAGE_COMPONENT,
     props: { ...props, errors: props?.errors ?? {} },
     url,
     version,
   };
+  if (onceProps) page.onceProps = onceProps;
+  return page;
+}
+
+function headerList(request, name) {
+  return String(request.headers[name] ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Which top-level props a request asks for. A full visit asks for all of them.
+ * A partial reload (`router.reload({ only, except })`) of the page on screen
+ * names them: a nested path selects its top-level prop, which is sent whole,
+ * and only a top-level name excludes one.
+ */
+export function requestedProps(request) {
+  const partial =
+    Boolean(request.headers["x-inertia"]) &&
+    request.headers["x-inertia-partial-component"] === DMS_PAGE_COMPONENT;
+  if (!partial) return { partial, wants: () => true };
+  const only = new Set(
+    headerList(request, "x-inertia-partial-data").map(
+      (path) => path.split(".")[0],
+    ),
+  );
+  const except = new Set(headerList(request, "x-inertia-partial-except"));
+  return {
+    partial,
+    wants: (prop) => (only.size === 0 || only.has(prop)) && !except.has(prop),
+  };
+}
+
+/** The once props the browser already holds, unexpired, by key. */
+export function heldOnceProps(request) {
+  return new Set(headerList(request, "x-inertia-except-once-props"));
 }
 
 export function inertiaHeaders(version = assetVersion()) {

package/templates/vue/server/listen-host.mjs

@@ -0,0 +1,19 @@
+// The address the frontend server listens on.
+
+const LOOPBACK = "127.0.0.1";
+const EVERY_INTERFACE = "0.0.0.0";
+
+/**
+ * `HOST` when set. Otherwise the development server (`ajs dms dev`) listens
+ * on the loopback address only: it serves the sources, the modules' server
+ * code and its own error overlays, which nobody else on the network should
+ * reach. `HOST=0.0.0.0` opens it to them. A production server listens on
+ * every interface, as a container expects.
+ *
+ * @param env The server's environment
+ */
+export function listenHost(env = process.env) {
+  const host = env.HOST?.trim();
+  if (host) return host;
+  return env.DMS_DEV === "true" ? LOOPBACK : EVERY_INTERFACE;
+}

package/templates/vue/server/module-event.mjs

@@ -0,0 +1,265 @@
+// What a module route handler receives and how its answer is written: the
+// Web-standard request, the session, the module's sealed cookies, the backend,
+// and the defaults every route gets once (same-origin on unsafe methods, a body
+// limit, `no-store`). See `server-module.ts` for the types a module reads.
+
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { backend, json, RequestBodyError } from "./auth/backend.mjs";
+import {
+  clientIp,
+  CROSS_ORIGIN_ERROR,
+  isSameOrigin,
+  requestScheme,
+} from "./auth/client-ip.mjs";
+import {
+  clearSealedCookie,
+  clearSession,
+  readSealedCookie,
+  readSession,
+  SESSION_COOKIE,
+  setRequestSession,
+  writeSealedCookie,
+  writeSession,
+} from "./auth/session.mjs";
+import { renderEmailTemplate } from "./email.mjs";
+import { backendUrl } from "./request-target.mjs";
+
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+const COOKIE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/** The sealed cookies of the module that owns sign-in: session, accounts, flows. */
+const RESERVED_COOKIE_PREFIX = "dms_";
+const BODY_TOO_LARGE = "Request body too large";
+
+function requestOrigin(request) {
+  const host = request.headers.host;
+  try {
+    return new URL(`${requestScheme(request)}://${host}`).origin;
+  } catch {
+    return "http://frontend.local";
+  }
+}
+
+function requestHeaders(request) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (name.startsWith(":") || value === undefined) continue;
+    for (const entry of [value].flat()) headers.append(name, entry);
+  }
+  return headers;
+}
+
+/** The request body as a Web stream that errors past `limit` bytes. */
+function limitedBody(request, limit) {
+  let size = 0;
+  return Readable.toWeb(request).pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        size += chunk.byteLength;
+        if (size > limit)
+          controller.error(new RequestBodyError(413, BODY_TOO_LARGE));
+        else controller.enqueue(chunk);
+      },
+    }),
+  );
+}
+
+function webRequest(request, route) {
+  const url = new URL(request.url, requestOrigin(request));
+  const hasBody = !["GET", "HEAD"].includes(request.method);
+  const declaredLength = Number(request.headers["content-length"] ?? 0);
+  if (hasBody && declaredLength > route.bodyLimit)
+    throw new RequestBodyError(413, BODY_TOO_LARGE);
+  return new Request(url, {
+    method: request.method,
+    headers: requestHeaders(request),
+    body: hasBody ? limitedBody(request, route.bodyLimit) : undefined,
+    duplex: "half",
+  });
+}
+
+async function readJson(webRequestValue) {
+  if (!webRequestValue.body) return {};
+  const chunks = [];
+  const reader = webRequestValue.body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+  }
+  if (!chunks.length) return {};
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new RequestBodyError(400, "Invalid request body");
+  }
+}
+
+function checkedCookieName(name) {
+  if (typeof name !== "string" || !COOKIE_NAME.test(name))
+    throw new Error(`Invalid cookie name: ${String(name)}`);
+  if (name === SESSION_COOKIE)
+    throw new Error(
+      `The ${SESSION_COOKIE} cookie is the session's: use event.session`,
+    );
+  return name;
+}
+
+function sessionAccess(request, response, view) {
+  return {
+    read: () => readSession(request),
+    view: () => view?.(readSession(request)) ?? {},
+    write(session) {
+      session.updatedAt = Date.now();
+      writeSession(response, session);
+    },
+    clear: () => clearSession(response),
+    useForRequest: (session) => setRequestSession(request, session),
+  };
+}
+
+/**
+ * The name a module's sealed cookie takes in the jar. The module that owns
+ * sign-in (`registerAuth`) names its own, the `dms_*` ones included; any other
+ * module's are prefixed with its id and a dot, which no name of the owner's
+ * holds, so no module reads or overwrites another's, nor the owner's session
+ * and account cookies.
+ */
+function moduleCookieName(name, moduleId, authOwner) {
+  const checked = checkedCookieName(name);
+  if (moduleId === authOwner) return checked;
+  if (checked.startsWith(RESERVED_COOKIE_PREFIX))
+    throw new Error(
+      `The ${RESERVED_COOKIE_PREFIX}* cookies belong to the module that owns sign-in` +
+        `${authOwner ? ` (${authOwner})` : ""}: choose another name than ${name}`,
+    );
+  return `${String(moduleId).replaceAll(/[^A-Za-z0-9_-]/g, "-")}.${checked}`;
+}
+
+function cookieAccess(request, response, moduleId, authOwner) {
+  const named = (name) => moduleCookieName(name, moduleId, authOwner);
+  return {
+    readSealed: (name) => readSealedCookie(request, named(name)),
+    writeSealed: (name, value, options = {}) =>
+      writeSealedCookie(
+        response,
+        named(name),
+        value,
+        options.maxAge,
+        options.path ?? "/",
+      ),
+    clear: (name, options = {}) =>
+      clearSealedCookie(response, named(name), options.path ?? "/"),
+  };
+}
+
+function frozenCopy(value) {
+  return Object.freeze(structuredClone(value ?? {}));
+}
+
+/**
+ * The event a handler receives.
+ *
+ * @param context `{ request, response, route, params, module, app, view,
+ *   authOwner }`, where `module` is `{ id, options, privateOptions }`, `app`
+ *   the deployment's read-only data, `view` what a session shows a page and
+ *   `authOwner` the id of the module that owns sign-in
+ */
+export function createServerEvent(context) {
+  const { request, response, route, params } = context;
+  const event = {
+    request: webRequest(request, route),
+    params: Object.freeze({ ...params }),
+    session: sessionAccess(request, response, context.view),
+    cookies: cookieAccess(
+      request,
+      response,
+      context.module.id,
+      context.authOwner,
+    ),
+    backend: (path, init = {}) => backend(path, request, init),
+    backendUrl: (path) => backendUrl(path),
+    clientIp: () => clientIp(request),
+    module: Object.freeze({
+      id: context.module.id,
+      options: frozenCopy(context.module.options),
+      privateOptions: frozenCopy(context.module.privateOptions),
+    }),
+    renderEmail: (template, props, options = {}) =>
+      renderEmailTemplate(template, props, options),
+    app: Object.freeze({
+      authEstablishEndpoints: Object.freeze([
+        ...(context.app?.authEstablishEndpoints ?? []),
+      ]),
+    }),
+  };
+  event.url = new URL(event.request.url);
+  event.readJson = () => readJson(event.request);
+  return event;
+}
+
+function isResponse(value) {
+  return (
+    value instanceof Response ||
+    (typeof value === "object" &&
+      value !== null &&
+      typeof value.status === "number" &&
+      typeof value.headers?.get === "function" &&
+      "body" in value)
+  );
+}
+
+function asResponse(result) {
+  if (isResponse(result)) return result;
+  if (result === undefined || result === null)
+    return new Response(null, { status: 204 });
+  return Response.json(result);
+}
+
+/**
+ * Writes a handler's answer. The cookies the event wrote are already on the
+ * Node response; those of a returned `Response` are added to them.
+ */
+async function writeServerResponse(request, response, result) {
+  const answer = asResponse(result);
+  const cookies = [response.getHeader("set-cookie") ?? []]
+    .flat()
+    .concat(answer.headers.getSetCookie());
+  answer.headers.forEach((value, name) => {
+    if (name !== "set-cookie") response.setHeader(name, value);
+  });
+  if (cookies.length) response.setHeader("set-cookie", cookies);
+  if (!answer.headers.has("cache-control"))
+    response.setHeader("cache-control", "no-store");
+  response.writeHead(answer.status, answer.statusText || undefined);
+  if (!answer.body || request.method === "HEAD") {
+    await answer.body?.cancel();
+    response.end();
+    return;
+  }
+  await pipeline(Readable.fromWeb(answer.body), response);
+}
+
+/**
+ * Answers a request with the module route it reached. The route's defaults
+ * apply first: a request with a state-changing method needs the frontend's
+ * own `Origin` unless the route says otherwise. An error the handler lets
+ * through reaches the server's error handling with the cookies written so
+ * far.
+ *
+ * @param context See `createServerEvent`
+ */
+export async function answerModuleRoute(context) {
+  const { request, response, route } = context;
+  if (
+    route.sameOrigin &&
+    !SAFE_METHODS.has(request.method) &&
+    !isSameOrigin(request)
+  ) {
+    json(response, 403, CROSS_ORIGIN_ERROR);
+    return;
+  }
+  const event = createServerEvent(context);
+  const result = await route.handler(event);
+  await writeServerResponse(request, response, result);
+}