@antelopejs/dms-frontend 0.1.7 → 0.1.9

package/README.md

@@ -10,7 +10,9 @@ Frontend-agnostic loader for AntelopeJS DMS. The backend serves a frontend
 manifest and the matching frontend-module archives; the `ajs dms` CLI
 materializes them into a generated workspace for one renderer, builds it, and
 runs its Node frontend server. The `vue` renderer — Vue 3, Vite, Inertia, and
-SSR — is the one shipped today.
+SSR — is the one shipped today. The package itself installs a single executable,
+`ajs-dms`; `ajs dms` is the core CLI delegating to it, and is the name every
+project, script and document uses.
 
 ## Renderers
 
@@ -55,15 +57,23 @@ not infer application ownership from other framework configuration.
 
 ## Install
 
-The loader is an AntelopeJS CLI plugin: install it next to `@antelopejs/core`
-and `ajs` delegates its `dms` command to the `ajs-dms` executable.
+The loader is an official AntelopeJS CLI plugin: install it next to
+`@antelopejs/core` and run it as `ajs dms <command>`. That is the only supported
+way to invoke it — in a shell, in a package script, in CI and in a container
+alike.
 
 ```bash
+# in a project (the usual case: both are already project dependencies)
+pnpm add @antelopejs/core @antelopejs/dms-frontend
+
+# or globally
 pnpm add -g @antelopejs/core @antelopejs/dms-frontend
 ```
 
 `npm install -g` works too; this repository and every generated workspace use
-pnpm.
+pnpm. Inside a package script, `ajs` resolves from `node_modules/.bin`, and the
+`dms` command it delegates to resolves the project-local plugin, so a script
+never depends on a global install.
 
 ## Commands
 
@@ -76,9 +86,6 @@ ajs dms clean -b https://dms.example.com
 ajs dms clean --all
 ```
 
-`ajs dms <command>` and `ajs-dms <command>` are the same program; the delegation
-only saves you from remembering a second executable name. Package scripts should
-call `ajs-dms` directly so they do not depend on the CLI being installed.
 `--help`, `--version` and `clean` run from any directory. `prepare` also runs
 anywhere: with no backend in reach it warns and exits 0, so a frontend module's
 `postinstall` hook never fails an install, and the generated types are refreshed
@@ -190,18 +197,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 +273,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/commands/build.js

@@ -51,7 +51,7 @@ function cmdBuild() {
             if (code === 0) {
                 console.log("");
                 (0, cli_ui_1.success)("Build completed successfully!");
-                console.log(chalk_1.default.dim("  Run 'ajs-dms start' to start the production server"));
+                console.log(chalk_1.default.dim("  Run 'ajs dms start' to start the production server"));
             }
             else {
                 (0, cli_ui_1.error)("Build failed");

package/dist/commands/start.js

@@ -26,7 +26,7 @@ function cmdStart() {
         if (!(0, node_fs_1.existsSync)(serverPath) || !(0, node_fs_1.existsSync)(clientPath)) {
             console.log("");
             (0, cli_ui_1.error)("Production build not found!");
-            console.log(chalk_1.default.dim("  Run 'ajs-dms build -b " +
+            console.log(chalk_1.default.dim("  Run 'ajs dms build -b " +
                 options.backendUrl +
                 "' first to create a production build"));
             process.exit(1);

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/index.js

@@ -25,7 +25,7 @@ const runCLI = async () => {
         console.log(chalk_1.default.dim(`  Frontend Loader for AntelopeJS DMS - v${version}\n`));
     }
     const program = new commander_1.Command()
-        .name("ajs-dms")
+        .name("ajs dms")
         .description(`Antelope DMS - Frontend Loader v${version}\n\n` +
         `Materializes frontend modules from an AntelopeJS backend and starts a Vue or React Vite and Inertia application.`)
         .version(version, "-v, --version", "Display version number")

package/dist/layers.js

@@ -23,8 +23,8 @@ function assertLayerPathsServed(modules) {
         return;
     throw new Error("The backend served a manifest without layer source paths:\n" +
         pathless.map((mod) => `  - ${mod.name}`).join("\n") +
-        "\n`ajs-dms dev` needs a development backend running on this machine (started with " +
-        "`ajs project dev`); use `ajs-dms build` against a remote or production one.\n" +
+        "\n`ajs dms dev` needs a development backend running on this machine (started with " +
+        "`ajs project dev`); use `ajs dms build` against a remote or production one.\n" +
         "If the backend is local and in development mode, it did not recognize the bootstrap " +
         "credential — see DMS_BOOTSTRAP_SECRET.");
 }
@@ -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/package.json

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

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

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { backend, body, json, UpstreamError } from "./backend.mjs";
 import { CROSS_ORIGIN_ERROR, isSameOrigin } from "./client-ip.mjs";
 import {
@@ -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),
+      ),
+    ),
+  ];
 }
 
 /**