@antelopejs/dms-frontend 0.1.6 → 0.1.8

package/README.md

@@ -190,18 +190,38 @@ never sends a token and never receives one: it gets back the same
 tenant-assignment outcomes are handled identically.
 
 Because the route turns a backend endpoint into a login, it only calls the
-endpoints the deployment names:
+endpoints that were declared for it.
+
+Backend modules declare their own. A module registering its frontend names the
+routes that finish its flow, the DMS aggregates them into the frontend manifest
+it serves with the bootstrap secret, and `dev`/`build` write them into the
+workspace as it is materialized:
+
+```ts
+// in the backend module
+await AddFrontendModule({
+  name: "@antelopejs/dms-saas-frontend-vue",
+  sourcePath: path.join(__dirname, "../frontend-vue"),
+  renderer: { name: "vue", version: "3" },
+  authEstablishEndpoints: ["/api/saas/register/finalize"],
+});
+```
+
+A standard deployment therefore needs no configuration at all. The environment
+variable stays as an override, for a backend route no module declares — or one
+declared by a DMS too old to carry the field:
 
 ```bash
 # .env
-DMS_AUTH_ESTABLISH_ENDPOINTS=/api/saas/register/finalize,/api/invites/redeem
+DMS_AUTH_ESTABLISH_ENDPOINTS=/api/invites/redeem
 ```
 
-The list is empty by default and matched verbatim against absolute `/api/…`
-paths — no prefixes, no query strings, no traversal — so no backend route that
-happens to mint a token 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.
+The effective allow-list is the union of the two. Every entry, from either
+source, is matched verbatim against absolute `/api/…` paths — no prefixes, no
+query strings, no traversal — so no backend route that happens to mint a token
+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.
 
 ### Workspaces
 
@@ -246,7 +266,7 @@ frontend-module registry drives server and client entries.
 | | `DMS_COOKIE_SECURE` | Secure cookies (`true` by default; `ajs dms dev` defaults to `false`) |
 | | `DMS_TRUSTED_PROXY_HOPS` | Number of trusted, rightmost reverse-proxy hops (default `0`) |
 | | `DMS_SESSION_SECRET` | Session cookie encryption key, 32 characters or more (required for login) |
-| | `DMS_AUTH_ESTABLISH_ENDPOINTS` | Backend endpoints `/auth/establish` may open a session from (comma-separated, empty by default) |
+| | `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_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.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.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = 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.TAILWIND_SOURCE_GLOB = exports.PNPM_LIFECYCLE_SCRIPTS = exports.layerCopyIgnore = exports.LAYER_COPY_BLOCKLIST = exports.AUTH_ESTABLISH_FILE = 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.normalizeBootstrapSecret = normalizeBootstrapSecret;
 exports.resolveBootstrapSecret = resolveBootstrapSecret;
@@ -52,6 +52,7 @@ exports.TEMPLATE_FILES = [
 ];
 exports.LAYERS_SUBDIR = "frontend-modules";
 exports.FRONTEND_MODULE_ENTRY = "dms.frontend.ts";
+exports.AUTH_ESTABLISH_FILE = "generated-auth-establish.json";
 exports.LAYER_COPY_BLOCKLIST = [
     "node_modules",
     "dist",

package/dist/layers.js

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

package/dist/materialize.js

@@ -5,6 +5,7 @@ exports.copyStaticTemplates = copyStaticTemplates;
 exports.writeWorkspacePackageJson = writeWorkspacePackageJson;
 exports.materializeLayers = materializeLayers;
 exports.createFrontendModuleRegistry = createFrontendModuleRegistry;
+exports.collectAuthEstablishEndpoints = collectAuthEstablishEndpoints;
 exports.writeFrontendModuleRegistry = writeFrontendModuleRegistry;
 exports.writeDmsMainCss = writeDmsMainCss;
 const node_fs_1 = require("node:fs");
@@ -107,9 +108,30 @@ function createFrontendModuleRegistry(workspaceDir, layers) {
     validateFrontendModuleRegistry(registry, workspaceDir);
     return registry;
 }
+const BACKEND_API_PATH = /^\/api\/[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/[A-Za-z0-9][A-Za-z0-9._~-]*)*$/;
+function collectAuthEstablishEndpoints(layers) {
+    const endpoints = new Set();
+    for (const layer of layers) {
+        for (const endpoint of layer.authEstablishEndpoints ?? []) {
+            if (typeof endpoint === "string" && BACKEND_API_PATH.test(endpoint)) {
+                endpoints.add(endpoint);
+                continue;
+            }
+            console.warn(`⚠ Ignoring malformed authEstablishEndpoints entry ${JSON.stringify(endpoint)} ` +
+                `declared by ${layer.packageName ?? layer.path}: expected an absolute ` +
+                "backend API path under /api/ with no query string.");
+        }
+    }
+    return [...endpoints];
+}
+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 writeFrontendModuleRegistry(workspaceDir, layers) {
     const registry = createFrontendModuleRegistry(workspaceDir, layers);
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, "generated-frontend-modules.json"), `${JSON.stringify(registry, null, 2)}\n`);
+    writeAuthEstablishEndpoints(workspaceDir, layers);
     writeFrontendTypePaths(workspaceDir, registry);
     writeFrontendModuleLoader(workspaceDir, registry);
     writeLocaleMessages(workspaceDir, registry);

package/dist/workspace-setup.js

@@ -9,6 +9,7 @@ exports.setupWorkspace = setupWorkspace;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const layers_1 = require("./layers");
 const manifest_1 = require("./manifest");
@@ -50,15 +51,77 @@ function installDeps(workspaceDir) {
         stdio: "inherit",
     });
 }
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const CHILD_SHUTDOWN_TIMEOUT_MS = 5000;
+function exitCodeForSignal(signal) {
+    const number = node_os_1.constants.signals[signal];
+    return 128 + (typeof number === "number" ? number : 15);
+}
 function runCommand(command, args, options) {
+    const isWindows = process.platform === "win32";
     return new Promise((resolve, reject) => {
         const child = (0, node_child_process_1.spawn)(command, args, {
             stdio: "inherit",
-            shell: true,
+            shell: isWindows,
             ...options,
         });
-        child.on("error", (error) => reject(error));
-        child.on("exit", (code) => resolve(code || 0));
+        let escalation;
+        let forwarded;
+        const alive = () => child.exitCode === null && child.signalCode === null;
+        const stopChild = (signal) => {
+            if (!alive())
+                return;
+            try {
+                child.kill(isWindows ? "SIGTERM" : signal);
+            }
+            catch {
+            }
+            if (escalation || isWindows)
+                return;
+            escalation = setTimeout(() => {
+                if (alive()) {
+                    try {
+                        child.kill("SIGKILL");
+                    }
+                    catch {
+                    }
+                }
+            }, CHILD_SHUTDOWN_TIMEOUT_MS);
+            escalation.unref();
+        };
+        const onSignal = (signal) => {
+            forwarded = signal;
+            stopChild(signal);
+        };
+        const onParentExit = () => {
+            if (alive()) {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch {
+                }
+            }
+        };
+        for (const signal of FORWARDED_SIGNALS)
+            process.on(signal, onSignal);
+        process.on("exit", onParentExit);
+        const cleanup = () => {
+            if (escalation)
+                clearTimeout(escalation);
+            for (const signal of FORWARDED_SIGNALS)
+                process.off(signal, onSignal);
+            process.off("exit", onParentExit);
+        };
+        child.on("error", (error) => {
+            cleanup();
+            reject(error);
+        });
+        child.on("exit", (code, signal) => {
+            cleanup();
+            if (code !== null)
+                return resolve(code);
+            resolve(exitCodeForSignal(signal ?? forwarded ?? "SIGTERM"));
+        });
     });
 }
 async function setupWorkspace(opts) {

package/package.json

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

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

@@ -50,3 +50,17 @@ export function clientIp(request) {
   const chain = [...forwarded, socketIp];
   return chain[Math.max(0, chain.length - hops - 1)] ?? socketIp;
 }
+
+/**
+ * Body answered with the 403 of the CSRF origin check.
+ *
+ * The check itself is unchanged: a state-changing request must carry an
+ * `Origin` matching the frontend's own. The `reason` only makes the refusal
+ * diagnosable, since a bare `{"error":"Forbidden"}` on `POST /auth/login`
+ * looks exactly like bad credentials to an API client that simply forgot
+ * the header (curl, a server-side integration, a test harness).
+ */
+export const CROSS_ORIGIN_ERROR = Object.freeze({
+  error: "Forbidden",
+  reason: "missing or untrusted Origin header",
+});

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { backend, body, json, UpstreamError } from "./backend.mjs";
-import { isSameOrigin } from "./client-ip.mjs";
+import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./client-ip.mjs";
 import {
   oauthCallback,
   oauthHandoff,
@@ -28,6 +29,36 @@ const PASSTHROUGH = new Map([
 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 [];
+  }
+}
+
 export function publicSession(session) {
   if (!session) return {};
   return {
@@ -88,20 +119,30 @@ async function establish(request, response, endpoint) {
 /**
  * Backend endpoints this deployment lets a module open a session from.
  *
- * Empty by default: a module route only becomes a session-opening route once
- * the operator names it, so no backend endpoint that happens to mint a token
- * pair can be turned into a login by a request from the browser.
+ * 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
- * @returns The declared paths that are well-formed backend API paths
+ * @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()),
 ) {
-  return (declaration ?? "")
+  const fromEnvironment = (declaration ?? "")
     .split(",")
-    .map((entry) => entry.trim())
-    .filter((entry) => BACKEND_API_PATH.test(entry));
+    .map((entry) => entry.trim());
+  return [
+    ...new Set(
+      [...declared, ...fromEnvironment].filter(
+        (entry) => typeof entry === "string" && BACKEND_API_PATH.test(entry),
+      ),
+    ),
+  ];
 }
 
 /**
@@ -288,8 +329,7 @@ export async function handleAuth(request, response, url) {
       response.setHeader("allow", "GET, POST, DELETE");
       return json(response, 405, { error: "Method Not Allowed" });
     }
-    if (!isSameOrigin(request))
-      return json(response, 403, { error: "Forbidden" });
+    if (!isSameOrigin(request)) return json(response, 403, CROSS_ORIGIN_ERROR);
     return request.method === "DELETE"
       ? logout(request, response)
       : refresh(request, response);
@@ -301,8 +341,9 @@ export async function handleAuth(request, response, url) {
     return match[2] === "start"
       ? oauthStart(request, response, match[1], url)
       : oauthCallback(request, response, match[1], url);
-  if (request.method !== "POST" || !isSameOrigin(request))
-    return json(response, 403, { error: "Forbidden" });
+  if (request.method !== "POST")
+    return json(response, 403, { error: "Forbidden", reason: "POST required" });
+  if (!isSameOrigin(request)) return json(response, 403, CROSS_ORIGIN_ERROR);
   if (url.pathname === "/auth/oauth/handoff")
     return oauthHandoff(request, response);
   const endpoint = PASSTHROUGH.get(url.pathname);

package/templates/vue/server/tester.mjs

@@ -1,5 +1,5 @@
 import { body, json, RequestBodyError } from "./auth/backend.mjs";
-import { isSameOrigin } from "./auth/client-ip.mjs";
+import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./auth/client-ip.mjs";
 import { readSession } from "./auth/session.mjs";
 
 const RESPONSE_LIMIT = 64 * 1024;
@@ -206,8 +206,7 @@ export async function handleTester(request, response) {
     response.setHeader("allow", "POST");
     return json(response, 405, { error: "Method Not Allowed" });
   }
-  if (!isSameOrigin(request))
-    return json(response, 403, { error: "Forbidden" });
+  if (!isSameOrigin(request)) return json(response, 403, CROSS_ORIGIN_ERROR);
   try {
     const session = readSession(request);
     if (!session?.accessToken)

package/templates/vue/server.mjs

@@ -11,7 +11,7 @@ import {
 } from "node:zlib";
 import { ofetch } from "ofetch";
 import { RequestBodyError, UpstreamError } from "./server/auth/backend.mjs";
-import { isSameOrigin } from "./server/auth/client-ip.mjs";
+import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./server/auth/client-ip.mjs";
 import {
   handleAuth,
   publicSession,
@@ -242,7 +242,7 @@ 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({ error: "Forbidden" }));
+    response.end(JSON.stringify(CROSS_ORIGIN_ERROR));
     return true;
   }
   const target = new URL(request.url, process.env.DMS_API_BASE_URL);