@antelopejs/dms-frontend 0.5.5 → 0.6.0

package/templates/vue/globals.d.ts

@@ -1 +1 @@
-declare const defineAppConfig: typeof import("./frontend-module").defineAppConfig;
+declare const defineDmsAppConfig: typeof import("./frontend-module").defineDmsAppConfig;

package/templates/vue/icon-hydration.ts

@@ -7,10 +7,29 @@ import {
   type IconifyJSON,
   iconLoaded,
 } from "@iconify/vue";
-import type { App, Component, ComponentPublicInstance } from "vue";
+import {
+  type App,
+  type Component,
+  type ComponentPublicInstance,
+  cloneVNode,
+  inject,
+  type InjectionKey,
+  type VNode,
+} from "vue";
 
 /** The element a server render writes the data of the icons it drew to. */
 export const SSR_ICONS_ID = "dms-ssr-icons";
+/** The hidden `<svg>` that holds each drawn icon once, as a `<symbol>`. */
+export const ICON_SPRITE_ID = "dms-icon-sprite";
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+const SYMBOL_PREFIX = "dms-icon-";
+const HASH_OFFSET = 0x811c9dc5;
+const HASH_PRIME = 0x01000193;
+const HASH_RADIX = 36;
+
+/** The symbols of one server render, by id. */
+type IconSymbols = Map<string, string>;
+const SERVER_SYMBOLS: InjectionKey<IconSymbols> = Symbol("dms-icon-symbols");
 
 interface IconProps {
   icon?: unknown;
@@ -33,6 +52,92 @@ export function drawLoadedIconsAtOnce(): void {
     default: ({ icon }: IconProps) =>
       typeof icon !== "string" || iconLoaded(icon),
   };
+  drawIconsFromSprite();
+}
+
+/** FNV-1a: the same short digest in a server and in a browser. */
+function digest(text: string): string {
+  let hash = HASH_OFFSET;
+  for (let index = 0; index < text.length; index++) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, HASH_PRIME);
+  }
+  return (hash >>> 0).toString(HASH_RADIX);
+}
+
+function symbolMarkup(id: string, viewBox: string, body: string): string {
+  return `<symbol id="${id}" viewBox="${viewBox}">${body}</symbol>`;
+}
+
+/** Adds a symbol to the page's sprite, which it creates the first time. */
+function addSymbolToDocument(id: string, viewBox: string, body: string): void {
+  if (document.getElementById(id)) return;
+  let sprite: Element | null = document.getElementById(ICON_SPRITE_ID);
+  if (!sprite) {
+    const created = document.createElementNS(SVG_NAMESPACE, "svg");
+    created.id = ICON_SPRITE_ID;
+    created.setAttribute("aria-hidden", "true");
+    created.setAttribute("style", "display:none");
+    document.body.append(created);
+    sprite = created;
+  }
+  sprite.insertAdjacentHTML("beforeend", symbolMarkup(id, viewBox, body));
+}
+
+/**
+ * The icon drawn as a `<use>` of its symbol in the page's sprite, rather than
+ * with its whole body: an icon shown on every row of a table is sent once.
+ * The symbol is keyed by the drawn body and view box, so a flipped or rotated
+ * icon is a symbol of its own. Left inline on a server render that collects no
+ * symbols, and for an empty icon.
+ */
+function spriteIcon(vnode: VNode, symbols: IconSymbols | null): VNode {
+  const props = vnode.props as Record<string, unknown> | null;
+  const body = props?.innerHTML;
+  const viewBox = props?.viewBox;
+  if (
+    vnode.type !== "svg" ||
+    typeof body !== "string" ||
+    body === "" ||
+    typeof viewBox !== "string"
+  )
+    return vnode;
+  const id = `${SYMBOL_PREFIX}${digest(`${viewBox}\n${body}`)}`;
+  if (symbols) symbols.set(id, symbolMarkup(id, viewBox, body));
+  else if (typeof document !== "undefined")
+    addSymbolToDocument(id, viewBox, body);
+  else return vnode;
+  return cloneVNode(vnode, { innerHTML: `<use href="#${id}"></use>` });
+}
+
+let drawingFromSprite = false;
+
+/** Makes every Iconify icon draw itself from the page's sprite. */
+function drawIconsFromSprite(): void {
+  if (drawingFromSprite) return;
+  drawingFromSprite = true;
+  const component = Icon as unknown as {
+    setup: (props: unknown, context: unknown) => () => VNode;
+  };
+  const setup = component.setup;
+  component.setup = (props, context) => {
+    const symbols = inject(SERVER_SYMBOLS, null);
+    const draw = setup(props, context);
+    return () => spriteIcon(draw(), symbols);
+  };
+}
+
+/** Collects the symbols of the icons a server render draws. */
+export function collectDmsIconSymbols(app: App): IconSymbols {
+  const symbols: IconSymbols = new Map();
+  app.provide(SERVER_SYMBOLS, symbols);
+  return symbols;
+}
+
+/** The sprite of a server render, each icon it drew once. */
+export function dmsIconSprite(symbols: IconSymbols): string {
+  if (!symbols.size) return "";
+  return `<svg id="${ICON_SPRITE_ID}" aria-hidden="true" style="display:none">${[...symbols.values()].join("")}</svg>`;
 }
 
 /**

package/templates/vue/index.html

@@ -3,7 +3,6 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <link rel="icon" href="data:," />
     <title>Antelope DMS</title>
   </head>
   <body>

package/templates/vue/layer-app-config.ts

@@ -0,0 +1,92 @@
+// The DMS app config the layers' `app/app.config.ts` make, and how an edited
+// one reaches it while the page is open in development.
+//
+// Lives apart from frontend-module.ts so the merge can be exercised on its own,
+// the way ui-app-config.ts is.
+
+import { defu } from "defu";
+import { clonePlain, isPlainRecord, type PlainRecord } from "./ui-app-config";
+
+/**
+ * The layer configs, highest precedence first, merged into a new object that
+ * shares nothing with them: the modules extend what this returns, and must not
+ * write into a config module's exports, which a development server keeps from
+ * one setup of the modules to the next.
+ */
+export function mergeLayerAppConfigs(configs: readonly unknown[]): PlainRecord {
+  return defu({}, ...configs.filter(isPlainRecord).map(clonePlain));
+}
+
+function isSameValue(left: unknown, right: unknown): boolean {
+  if (Array.isArray(left) && Array.isArray(right))
+    return (
+      left.length === right.length &&
+      left.every((item, index) => isSameValue(item, right[index]))
+    );
+  if (isPlainRecord(left) && isPlainRecord(right)) {
+    const keys = Object.keys(left);
+    return (
+      keys.length === Object.keys(right).length &&
+      keys.every((key) => key in right && isSameValue(left[key], right[key]))
+    );
+  }
+  return Object.is(left, right);
+}
+
+/**
+ * What `after` holds that `before` does not: each value added or changed, down
+ * through the records both hold. An array counts as one value.
+ */
+export function appConfigChanges(
+  before: PlainRecord,
+  after: PlainRecord,
+): PlainRecord {
+  const changes: PlainRecord = {};
+  for (const [key, value] of Object.entries(after)) {
+    const previous = before[key];
+    if (isPlainRecord(previous) && isPlainRecord(value)) {
+      const nested = appConfigChanges(previous, value);
+      if (Object.keys(nested).length > 0) changes[key] = nested;
+    } else if (!isSameValue(previous, value)) {
+      changes[key] = clonePlain(value);
+    }
+  }
+  return changes;
+}
+
+/**
+ * `config` with `changes` on top: a record both hold is merged, anything else
+ * the changes hold replaces what `config` has, arrays included.
+ */
+export function withAppConfigChanges(
+  config: PlainRecord,
+  changes: PlainRecord,
+): PlainRecord {
+  const result = { ...config };
+  for (const [key, value] of Object.entries(changes)) {
+    const current = result[key];
+    result[key] =
+      isPlainRecord(current) && isPlainRecord(value)
+        ? withAppConfigChanges(current, value)
+        : clonePlain(value);
+  }
+  return result;
+}
+
+/**
+ * Make `target` hold what `source` holds, in place: a record both hold is
+ * updated rather than replaced, so whoever kept it, a component reading
+ * `useDmsAppConfig().branding` for instance, sees the new values too, and a
+ * key `source` no longer has is removed.
+ */
+export function assignInPlace(target: PlainRecord, source: PlainRecord): void {
+  for (const key of Object.keys(target)) {
+    if (!(key in source)) delete target[key];
+  }
+  for (const [key, value] of Object.entries(source)) {
+    const current = target[key];
+    if (isPlainRecord(current) && isPlainRecord(value))
+      assignInPlace(current, value);
+    else target[key] = value;
+  }
+}

package/templates/vue/main.ts

@@ -3,7 +3,12 @@ import { addAPIProvider } from "@iconify/vue";
 import { createInertiaApp } from "@inertiajs/vue3";
 import { createHead } from "@unhead/vue/client";
 import { createApp, createSSRApp, h } from "vue";
-import { configureDmsApp, resolveDmsInertiaPage } from "./app-runtime";
+import { appConfigs, syncAppConfigs } from "./app-configs.generated";
+import {
+  applyLayerAppConfigs,
+  configureDmsApp,
+  resolveDmsInertiaPage,
+} from "./app-runtime";
 import { setupFrontendModules } from "./frontend-module";
 import { frontendModules } from "./frontend-modules.generated";
 import { sameOriginIconProvider } from "./icon-api.mjs";
@@ -52,7 +57,10 @@ if (import.meta.env.DEV) adoptViteDevStyles();
 // the generated server answers those queries from the installed collections.
 addAPIProvider("", sameOriginIconProvider(location.origin));
 
-await setupFrontendModules(frontendModules);
+await setupFrontendModules(frontendModules, appConfigs);
+// A layer's app config edited during development reaches the page without a
+// reload. A server render imports the new configs instead.
+syncAppConfigs(applyLayerAppConfigs);
 
 createInertiaApp({
   resolve: resolveDmsInertiaPage,

package/templates/vue/package.json

@@ -4,11 +4,13 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build && node compress-assets.mjs && vite build --ssr ssr-renderer.ts --outDir dist/ssr && vite build --config vite.email.config.ts",
+    "build": "vite build && node compress-assets.mjs && vite build --ssr ssr-renderer.ts --outDir dist/ssr && vite build --config vite.email.config.ts && vite build --config vite.server.config.ts",
     "build:client": "vite build",
     "build:compress": "node compress-assets.mjs",
     "build:ssr": "vite build --ssr ssr-renderer.ts --outDir dist/ssr",
     "build:email": "vite build --config vite.email.config.ts",
+    "build:server": "vite build --config vite.server.config.ts",
+    "build:types": "node prepare-types.mjs",
     "typecheck": "node --import ./typecheck-loader.mjs ./node_modules/vue-tsc/bin/vue-tsc.js --noEmit",
     "start": "node server.mjs"
   },
@@ -25,6 +27,7 @@
     "@vue/server-renderer": "^3.5.0",
     "@vueuse/core": "^14.3.0",
     "defu": "^6.1.4",
+    "devalue": "^5.9.4",
     "ofetch": "^1.4.1",
     "reka-ui": "^2.6.0",
     "tailwindcss": "^4.0.0",
@@ -36,6 +39,7 @@
     "vue-i18n": "^11.1.12"
   },
   "devDependencies": {
+    "@types/node": "^24.0.0",
     "typescript": "^5.8.2",
     "vue-tsc": "3.1.1"
   },

package/templates/vue/prepare-types.mjs

@@ -0,0 +1,34 @@
+// Writes the files Vite generates and the type check reads (auto-imports.d.ts
+// and the Nuxt UI templates) without building anything: it resolves
+// vite.config.ts and runs its build hooks over an empty entry, in seconds
+// where a client build takes a minute. `ajs dms verify-source` runs it first
+// (`pnpm run build:types`), so the type check no longer waits for the client
+// bundle.
+
+import { build } from "vite";
+
+const ENTRY = "dms-prepare-types-entry";
+const RESOLVED_ENTRY = `\0${ENTRY}`;
+
+await build({
+  configFile: "vite.config.ts",
+  plugins: [
+    {
+      name: "dms-prepare-types-entry",
+      enforce: "pre",
+      resolveId: (id) => (id === ENTRY ? RESOLVED_ENTRY : null),
+      load: (id) => (id === RESOLVED_ENTRY ? "export {};" : null),
+    },
+  ],
+  build: {
+    write: false,
+    emptyOutDir: false,
+    rollupOptions: {
+      input: ENTRY,
+      // The entry is empty on purpose.
+      onwarn: (warning, warn) => {
+        if (warning.code !== "EMPTY_BUNDLE") warn(warning);
+      },
+    },
+  },
+});

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

@@ -5,7 +5,6 @@ const FORWARDED_HEADERS = [
   "x-content-language",
   "x-realtime-session",
 ];
-const BODY_LIMIT = 64 * 1024;
 
 export class UpstreamError extends Error {
   constructor(status, message) {
@@ -44,8 +43,20 @@ export function relayedHeaders(request, names) {
   };
 }
 
+/**
+ * Calls the backend for a server route, JSON in and out.
+ *
+ * `options.headers` adds request headers; the client's address and the
+ * relayed client headers are set after them, so no caller replaces those.
+ */
 export async function backend(path, request, options = {}) {
-  const headers = relayedHeaders(request, FORWARDED_HEADERS);
+  const headers = Object.fromEntries(
+    Object.entries(options.headers ?? {}).map(([name, value]) => [
+      name.toLowerCase(),
+      String(value),
+    ]),
+  );
+  Object.assign(headers, relayedHeaders(request, FORWARDED_HEADERS));
   headers["x-forwarded-for"] = clientIp(request);
   if (options.token) headers.authorization = `Bearer ${options.token}`;
   if (options.relay)
@@ -74,23 +85,6 @@ export async function backend(path, request, options = {}) {
   return data;
 }
 
-export async function body(request) {
-  const chunks = [];
-  let size = 0;
-  for await (const chunk of request) {
-    size += chunk.length;
-    if (size > BODY_LIMIT)
-      throw new RequestBodyError(413, "Request body too large");
-    chunks.push(chunk);
-  }
-  if (!chunks.length) return {};
-  try {
-    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
-  } catch {
-    throw new RequestBodyError(400, "Invalid request body");
-  }
-}
-
 export class RequestBodyError extends Error {
   constructor(status, message) {
     super(message);

package/templates/vue/server/auth/client-ip.mjs

@@ -26,6 +26,33 @@ function requestHost(request) {
   );
 }
 
+/**
+ * The `X-Forwarded-*` headers of a backend request, which tell the backend
+ * the client a request comes from: its address, to limit each client, and
+ * the scheme and host it asked, to check an Origin against.
+ *
+ * The client's own `X-Forwarded-For` is extended only when a trusted reverse
+ * proxy wrote it (`DMS_TRUSTED_PROXY_HOPS` above `0`): otherwise any caller
+ * could have, and the socket's address replaces it. The scheme and the host
+ * are read the same way as the CSRF origin check reads them.
+ */
+export function forwardedHeaders(request) {
+  const socketIp = request.socket?.remoteAddress || "unknown";
+  const incoming = trustedHops()
+    ? String(request.headers["x-forwarded-for"] ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean)
+    : [];
+  const headers = {
+    "x-forwarded-for": [...incoming, socketIp].join(", "),
+    "x-forwarded-proto": requestScheme(request),
+  };
+  const host = requestHost(request);
+  if (host) headers["x-forwarded-host"] = host;
+  return headers;
+}
+
 export function isSameOrigin(request) {
   const origin = request.headers.origin;
   if (!origin) return false;

package/templates/vue/server/auth/establish-endpoints.mjs

@@ -0,0 +1,70 @@
+// The backend endpoints a module may open a session from: what the backend's
+// modules declared in the frontend manifest, and what the environment adds
+// (`DMS_AUTH_ESTABLISH_ENDPOINTS`). The module that owns sign-in reads them as
+// `event.app.authEstablishEndpoints`.
+
+import { readFileSync } from "node:fs";
+
+// Absolute backend API paths only: no scheme, no authority, no query string,
+// and no segment that could climb out of `/api/`.
+const BACKEND_API_PATH =
+  /^\/api\/[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/[A-Za-z0-9][A-Za-z0-9._~-]*)*$/;
+
+// Written at the workspace root by the loader, from the endpoints each backend
+// module declared in the frontend manifest. This file sits two directories up.
+const DECLARED_ENDPOINTS_FILE = new URL(
+  "../../generated-auth-establish.json",
+  import.meta.url,
+);
+
+let declaredEndpoints;
+
+/**
+ * Backend endpoints the modules of this deployment declared as session-opening.
+ *
+ * Read from the workspace rather than from the backend: the file is generated
+ * when the workspace is materialized, so the server needs no backend round trip
+ * — and no operator — to know which module flows may end on a login. A
+ * workspace built from a DMS that predates the declaration simply has no file,
+ * and the list falls back to whatever the environment names.
+ *
+ * @param file Generated file to read
+ * @returns The declared paths, unfiltered
+ */
+export function readDeclaredEstablishEndpoints(file = DECLARED_ENDPOINTS_FILE) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    return Array.isArray(parsed?.endpoints) ? parsed.endpoints : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Backend endpoints this deployment lets a module open a session from.
+ *
+ * The union of what the backend's modules declared — the standard case, which
+ * needs no configuration — and what the environment adds on top, which is how
+ * an operator extends the list for a route no module owns. Everything else
+ * stays refused, so no backend endpoint that happens to mint a token pair can
+ * be turned into a login by a request from the browser.
+ *
+ * @param declaration Comma-separated absolute backend paths from the environment
+ * @param declared Paths declared by the backend's frontend modules
+ * @returns The well-formed backend API paths, without duplicates
+ */
+export function allowedEstablishEndpoints(
+  declaration = process.env.DMS_AUTH_ESTABLISH_ENDPOINTS,
+  declared = (declaredEndpoints ??= readDeclaredEstablishEndpoints()),
+) {
+  const fromEnvironment = (declaration ?? "")
+    .split(",")
+    .map((entry) => entry.trim());
+  return [
+    ...new Set(
+      [...declared, ...fromEnvironment].filter(
+        (entry) => typeof entry === "string" && BACKEND_API_PATH.test(entry),
+      ),
+    ),
+  ];
+}

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

@@ -3,16 +3,11 @@ import {
   createDecipheriv,
   createHash,
   randomBytes,
-  randomUUID,
 } from "node:crypto";
 
-const SESSION_COOKIE = "dms_session";
-const ACCOUNT_INDEX_COOKIE = "dms_account_index";
-const ACCOUNT_COOKIE_PREFIX = "dms_account_";
+export const SESSION_COOKIE = "dms_session";
 const REQUEST_SESSION = Symbol("dms-request-session");
 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
@@ -98,11 +93,10 @@ function attributes(maxAge, path = "/") {
 }
 
 /**
- * Whether a session, or a stored account, outlives the browser. Only a login
- * that left "keep me signed in" unchecked says no; a cookie written before
- * the flag existed carries none, and keeps the lifetime it was given then.
+ * Whether a session outlives the browser. Only a session written with
+ * `persistent: false` says no.
  */
-export function isPersistent(session) {
+function isPersistent(session) {
   return session?.persistent !== false;
 }
 
@@ -121,22 +115,6 @@ function appendCookie(response, name, value, cookieAttributes) {
   );
 }
 
-function accountCookieName(accountId) {
-  if (!UUID.test(accountId)) throw new Error("Invalid account id");
-  return `${ACCOUNT_COOKIE_PREFIX}${accountId.replaceAll("-", "")}`;
-}
-
-function descriptor(session, accountId) {
-  return {
-    accountId,
-    userId: session.user?._id ?? session.user?.id,
-    email: session.user?.email,
-    name: session.user?.name,
-    activeTenantId: session.activeTenantId,
-    persistent: isPersistent(session),
-  };
-}
-
 export function readSession(request) {
   if (REQUEST_SESSION in request) return request[REQUEST_SESSION];
   const value = cookieValue(request, SESSION_COOKIE);
@@ -160,84 +138,15 @@ export function clearSession(response) {
   appendCookie(response, SESSION_COOKIE, "", attributes(0));
 }
 
-export function readAccounts(request) {
-  const value = cookieValue(request, ACCOUNT_INDEX_COOKIE);
-  return value ? (decode(value) ?? {}) : {};
-}
-
-function writeAccountIndex(response, accounts) {
-  const persistent = Object.values(accounts).some(isPersistent);
-  appendCookie(
-    response,
-    ACCOUNT_INDEX_COOKIE,
-    encode(accounts),
-    attributes(lifetime(persistent)),
-  );
-}
-
-export function readAccount(request, accountId) {
-  if (!UUID.test(accountId ?? "")) return undefined;
-  const value = cookieValue(request, accountCookieName(accountId));
-  return value ? decode(value) : undefined;
-}
-
-export function storeAccount(request, response, session, accountId) {
-  const id = accountId ?? randomUUID();
-  const accountDescriptor = descriptor(session, id);
-  const accounts = { ...readAccounts(request), [id]: accountDescriptor };
-  writeAccountIndex(response, accounts);
-  appendCookie(
-    response,
-    accountCookieName(id),
-    encode({ refreshToken: session.refreshToken, ...accountDescriptor }),
-    attributes(lifetime(accountDescriptor.persistent)),
-  );
-  return accountDescriptor;
-}
-
-export function assertAccountInvariant(session, accountId) {
-  if (!accountId || session.accountId !== accountId)
-    throw new Error("Account session invariant violated");
-}
-
-/**
- * Write `session` as the current one, and as one of the stored accounts.
- * Stamps it with `updatedAt`, which lets the browser tell a page fetched
- * before this write, and restored from its cache, from a current one.
- */
-export function persistAccountSession(request, response, session, accountId) {
-  const id = accountId ?? session.accountId ?? randomUUID();
-  session.accountId = id;
-  session.updatedAt = Date.now();
-  const account = storeAccount(request, response, session, id);
-  assertAccountInvariant(session, account.accountId);
-  writeSession(response, session);
-  return account;
-}
-
-export function removeAccount(request, response, accountId) {
-  const accounts = { ...readAccounts(request) };
-  delete accounts[accountId];
-  writeAccountIndex(response, accounts);
-  if (UUID.test(accountId ?? ""))
-    appendCookie(response, accountCookieName(accountId), "", attributes(0));
-}
-
 export function readSealedCookie(request, name) {
   const value = cookieValue(request, name);
   return value ? decode(value) : undefined;
 }
 
-export function writeSealedCookie(
-  response,
-  name,
-  value,
-  maxAge,
-  path = "/auth/oauth",
-) {
+export function writeSealedCookie(response, name, value, maxAge, path = "/") {
   appendCookie(response, name, encode(value), attributes(maxAge, path));
 }
 
-export function clearSealedCookie(response, name, path = "/auth/oauth") {
+export function clearSealedCookie(response, name, path = "/") {
   appendCookie(response, name, "", attributes(0, path));
 }