@antelopejs/dms-frontend 0.1.1 → 0.1.3

package/README.md

@@ -126,9 +126,105 @@ The SDK also exposes `use` for Vue plugins. Entries execute by descending manife
 
 ## Discovery, caching, and security
 
-In development, `ajs dms` discovers the backend from the nearest live `.antelope/dev.json`. It reads the local bootstrap credential from `.antelope/dms-dev.json` only when that discovered backend matches the destination URL. For production and CI, set `DMS_API_BASE_URL` and `DMS_BOOTSTRAP_SECRET` in the environment rather than passing credentials on the command line.
+In development, `ajs dms` discovers the backend from the nearest live `.antelope/dev.json`. It reads the local bootstrap credential from `.antelope/dms-dev.json` only when that discovered backend matches the destination URL. For production and CI, set `DMS_API_BASE_URL` and `DMS_BOOTSTRAP_SECRET` in the environment, or in the project's `.env`, rather than passing credentials on the command line.
 
-Each canonical backend URL gets an owner-only workspace under `~/.antelopejs/dms-frontend`. Manifest caches, private module configuration, and extracted archives retain restrictive permissions. `--offline` reuses the last successful manifest and archive; an authorization failure never falls back to privileged cached data.
+Each canonical backend URL gets an owner-only workspace under `~/.antelopejs/dms-frontend` (see [Workspaces](#workspaces) for how the key is derived). Manifest caches, private module configuration, and extracted archives retain restrictive permissions. `--offline` reuses the last successful manifest and archive; an authorization failure never falls back to privileged cached data.
+
+## Configuration
+
+Every command loads `.env.local` then `.env` from the **current working
+directory** before it parses its options, so a project can keep its
+configuration in a file instead of exporting variables by hand:
+
+```bash
+# .env
+DMS_API_BASE_URL=http://localhost:5010
+DMS_CLIENT_BASE_URL=http://localhost:3001
+DMS_BOOTSTRAP_SECRET=replace_with_a_strong_random_value
+DMS_SESSION_SECRET=replace_with_at_least_32_characters
+```
+
+Precedence is environment, then `.env.local`, then `.env`: a variable already
+present in the environment is never overwritten, so `DMS_API_BASE_URL=… ajs dms
+build` and a CI job's injected secrets always win over a file left in the
+checkout. A variable exported as an empty string counts as set. Only the
+current directory is read — never a parent directory, and never the generated
+workspace under `~/.antelopejs/dms-frontend`, which is this tool's own output
+and is handed its environment explicitly by the command that spawns it. The
+values loaded here reach the workspace build started by `build`, the dev server
+started by `dev`, and the production server started by `start`, because those
+child processes inherit the environment. A missing file is not an error; an
+unreadable one is reported and skipped.
+
+`DMS_SESSION_SECRET` is mandatory for anything that touches a session. The
+generated server encrypts its session cookie with it, and with no value — or
+one shorter than 32 characters — the login page at `/auth` fails the first
+sign-in attempt rather than starting degraded. Generate one with
+`openssl rand -hex 32`.
+
+### Opening a session from a module flow
+
+`/auth/login`, `/auth/signup` and `/auth/verify-2fa` are not the only ways a
+visitor becomes authenticated: a module can own a flow that ends in an
+authenticated user — a self-service registration completing after payment, an
+invitation being redeemed — and needs the session cookie opened at the end of
+it. `POST /auth/establish` is the generic form of those three routes.
+
+The browser names a backend endpoint and the payload to send it:
+
+```ts
+await $fetch("/auth/establish", {
+  method: "POST",
+  body: {
+    endpoint: "/api/saas/register/finalize",
+    payload: { /* whatever that backend route expects */ },
+  },
+});
+```
+
+The frontend server calls that endpoint itself over its own server-to-server
+channel to `DMS_API_BASE_URL`, exactly as it calls `/api/auth/login`, and
+writes the session from the token pair the backend answers with. The browser
+never sends a token and never receives one: it gets back the same
+`{ user, account }` body the login route returns, and the two-factor and
+tenant-assignment outcomes are handled identically.
+
+Because the route turns a backend endpoint into a login, it only calls the
+endpoints the deployment names:
+
+```bash
+# .env
+DMS_AUTH_ESTABLISH_ENDPOINTS=/api/saas/register/finalize,/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.
+
+### Workspaces
+
+Each canonical backend URL gets its own owner-only workspace under
+`~/.antelopejs/dms-frontend/<sha256>/`; `build`, `start`, `clean -b` and
+`dev -b` all key on that URL, so one backend means one workspace shared by
+every command.
+
+`dev` without `-b` is the deliberate exception. It discovers the backend from
+the enclosing antelope project's `.antelope/dev.json` and keys its workspace on
+the **project directory** instead, because a development backend can land on a
+different port between runs and re-keying on the URL would discard
+`node_modules`, the manifest cache and the client-side appId scope every time it
+does. The consequence is that `ajs dms dev` followed by `ajs dms build -b <url>`
+against the same backend creates two workspaces of their own — several hundred
+megabytes each. Pass `-b` to `dev` to share a single one. `clean --all` lists
+both and names the project a workspace is keyed on; `clean -b <url>` only
+reaches the URL-keyed one.
+
+A `DMS_API_BASE_URL` line in `.env` counts as an explicit backend, so a project
+that configures one gets the single shared workspace and gives up autodiscovery
+— including its tolerance for the backend moving to another port. Leave the
+variable out of `.env` to keep autodiscovery for `dev`.
 
 ## Rendering model
 
@@ -149,6 +245,11 @@ frontend-module registry drives server and client entries.
 | `--bootstrap-secret` | `DMS_BOOTSTRAP_SECRET` | Backend bootstrap credential |
 | | `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_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).
 
 Use pnpm for all repository and workspace operations.
 

package/dist/commands/clean.js

@@ -21,14 +21,17 @@ function cmdClean() {
             }
             for (const ws of workspaces) {
                 (0, node_fs_1.rmSync)(ws.dir, { recursive: true, force: true });
-                (0, cli_ui_1.success)(`Removed ${ws.dir} (${ws.backendUrl})`);
+                (0, cli_ui_1.success)(`Removed ${ws.dir} (${(0, common_1.describeWorkspace)(ws)})`);
             }
             console.log("");
             (0, cli_ui_1.success)(`Cleaned ${workspaces.length} workspace(s).`);
             return;
         }
         if (!options.backendUrl) {
-            (0, cli_ui_1.warning)("Specify -b <url> to clean a specific workspace, or --all to clean everything.");
+            (0, cli_ui_1.warning)("Specify -b <url> to clean a specific workspace, or --all to clean everything.\n" +
+                "  -b only reaches the workspace 'build', 'start' and 'dev -b' share for that URL;\n" +
+                "  a workspace 'dev' created without -b is keyed on the project directory and is\n" +
+                "  only removable with --all.");
             process.exit(1);
         }
         const workspaceDir = (0, common_1.getWorkspaceDir)(options.backendUrl);

package/dist/config.js

@@ -88,7 +88,9 @@ exports.Options = {
         .default("3001")
         .env("PORT"),
     force: new commander_1.Option("-f, --force", "Force reinstall dependencies"),
-    offline: new commander_1.Option("--offline", "Skip the backend manifest fetch and reuse the last cached manifest (env: DMS_OFFLINE)").default(booleanFromEnv("DMS_OFFLINE")),
+    get offline() {
+        return new commander_1.Option("--offline", "Skip the backend manifest fetch and reuse the last cached manifest (env: DMS_OFFLINE)").default(booleanFromEnv("DMS_OFFLINE"));
+    },
     bootstrapSecret: new commander_1.Option("--bootstrap-secret <secret>", "Credential presented to the backend's layer endpoints (env: DMS_BOOTSTRAP_SECRET, preferred — " +
         "a secret passed on the command line is visible to every process on the machine). In dev it is " +
         "discovered from the antelope project's .antelope/dms-dev.json.").env("DMS_BOOTSTRAP_SECRET"),

package/dist/env-file.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENV_FILE_NAMES = void 0;
+exports.loadProjectEnv = loadProjectEnv;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+exports.ENV_FILE_NAMES = [".env.local", ".env"];
+function loadProjectEnv(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const onWarning = options.onWarning ?? ((message) => console.warn(message));
+    const loaded = [];
+    for (const name of exports.ENV_FILE_NAMES) {
+        const file = (0, node_path_1.join)(cwd, name);
+        if (!(0, node_fs_1.existsSync)(file))
+            continue;
+        let parsed;
+        try {
+            parsed = (0, node_util_1.parseEnv)((0, node_fs_1.readFileSync)(file, "utf-8"));
+        }
+        catch (err) {
+            onWarning(`⚠ Ignoring ${file}: ${err?.message ?? err}`);
+            continue;
+        }
+        for (const [key, value] of Object.entries(parsed)) {
+            if (value !== undefined && env[key] === undefined)
+                env[key] = value;
+        }
+        loaded.push(file);
+    }
+    return loaded;
+}

package/dist/index.js

@@ -12,10 +12,12 @@ const dev_1 = require("./commands/dev");
 const prepare_1 = require("./commands/prepare");
 const start_1 = require("./commands/start");
 const verify_source_1 = require("./commands/verify-source");
+const env_file_1 = require("./env-file");
 const update_check_1 = require("./update-check");
 const cli_ui_1 = require("./utils/cli-ui");
 const { version } = require("../package.json");
 const runCLI = async () => {
+    (0, env_file_1.loadProjectEnv)();
     const argv = process.argv.slice(2);
     void (0, update_check_1.checkForUpdate)({ currentVersion: version, argv });
     if (process.argv.length <= 2) {
@@ -28,7 +30,21 @@ const runCLI = async () => {
         `Materializes frontend modules from an AntelopeJS backend and starts a Vue or React Vite and Inertia application.`)
         .version(version, "-v, --version", "Display version number")
         .option("--no-update-check", "Skip the daily check for a newer DMS frontend release")
-        .helpCommand("help [command]", "Display help for a specific command");
+        .helpCommand("help [command]", "Display help for a specific command")
+        .addHelpText("after", `
+Environment:
+  Every command reads ${env_file_1.ENV_FILE_NAMES.join(" then ")} from the current directory before parsing
+  its options, so DMS_API_BASE_URL, DMS_BOOTSTRAP_SECRET, DMS_SESSION_SECRET and
+  the other variables below can live in the project's .env. A variable already
+  set in the environment always wins over a file, and .env.local wins over .env.
+  The generated workspace never loads a .env of its own.
+
+Workspaces:
+  Each canonical backend URL gets its own workspace under
+  ~/.antelopejs/dms-frontend. 'dev' without -b is the exception: it keys the
+  workspace on the antelope project directory instead, so a backend that lands
+  on a different port between runs keeps its node_modules and manifest cache.
+  Pass -b to 'dev' to share one workspace with 'build' and 'start'.`);
     program.addCommand((0, dev_1.cmdDev)());
     program.addCommand((0, build_1.cmdBuild)());
     program.addCommand((0, start_1.cmdStart)());

package/dist/workspace.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FRONTEND_MANIFEST_VERSION = void 0;
 exports.getWorkspaceDirForKey = getWorkspaceDirForKey;
 exports.projectWorkspaceKey = projectWorkspaceKey;
+exports.projectDirFromWorkspaceKey = projectDirFromWorkspaceKey;
 exports.getWorkspaceDir = getWorkspaceDir;
 exports.ensureWorkspace = ensureWorkspace;
+exports.describeWorkspace = describeWorkspace;
 exports.listWorkspaces = listWorkspaces;
 exports.writeWorkspaceMeta = writeWorkspaceMeta;
 exports.bootstrapHeaders = bootstrapHeaders;
@@ -16,8 +18,14 @@ const WORKSPACE_META_FILE = ".ajs-dms-meta.json";
 function getWorkspaceDirForKey(key) {
     return (0, node_path_1.join)(config_1.DMS_FRONTEND_HOME, (0, config_1.sha256Hex)(key));
 }
+const PROJECT_KEY_PREFIX = "project:";
 function projectWorkspaceKey(projectDir) {
-    return `project:${(0, node_path_1.resolve)(projectDir)}`;
+    return `${PROJECT_KEY_PREFIX}${(0, node_path_1.resolve)(projectDir)}`;
+}
+function projectDirFromWorkspaceKey(workspaceKey) {
+    return workspaceKey?.startsWith(PROJECT_KEY_PREFIX)
+        ? workspaceKey.slice(PROJECT_KEY_PREFIX.length)
+        : undefined;
 }
 function getWorkspaceDir(backendUrl) {
     return getWorkspaceDirForKey((0, config_1.canonicalizeBackendUrl)(backendUrl));
@@ -30,6 +38,12 @@ function ensureWorkspace(workspaceKey) {
     (0, node_fs_1.chmodSync)(dir, config_1.WORKSPACE_DIR_MODE);
     return dir;
 }
+function describeWorkspace(entry) {
+    const projectDir = projectDirFromWorkspaceKey(entry.workspaceKey);
+    return projectDir
+        ? `${entry.backendUrl}, keyed on project ${projectDir}`
+        : entry.backendUrl;
+}
 function listWorkspaces() {
     if (!(0, node_fs_1.existsSync)(config_1.DMS_FRONTEND_HOME))
         return [];
@@ -38,16 +52,20 @@ function listWorkspaces() {
         if (!entry.isDirectory())
             continue;
         const dir = (0, node_path_1.join)(config_1.DMS_FRONTEND_HOME, entry.name);
-        const backendUrl = readWorkspaceBackendUrl(dir);
-        if (backendUrl === undefined) {
+        const meta = readWorkspaceMeta(dir);
+        if (meta?.backendUrl === undefined) {
             console.warn(`⚠ Skipping ${dir}: no readable ${WORKSPACE_META_FILE}.`);
             continue;
         }
-        workspaces.push({ dir, backendUrl });
+        workspaces.push({
+            dir,
+            backendUrl: meta.backendUrl,
+            workspaceKey: meta.workspaceKey,
+        });
     }
     return workspaces;
 }
-function readWorkspaceBackendUrl(dir) {
+function readWorkspaceMeta(dir) {
     let meta;
     try {
         meta = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, WORKSPACE_META_FILE), "utf-8"));
@@ -55,8 +73,13 @@ function readWorkspaceBackendUrl(dir) {
     catch {
         return undefined;
     }
-    const backendUrl = meta?.backendUrl;
-    return typeof backendUrl === "string" ? backendUrl : undefined;
+    const record = meta;
+    return {
+        backendUrl: typeof record?.backendUrl === "string" ? record.backendUrl : undefined,
+        workspaceKey: typeof record?.workspaceKey === "string"
+            ? record.workspaceKey
+            : undefined,
+    };
 }
 function writeWorkspaceMeta(workspaceDir, backendUrl, workspaceKey) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(workspaceDir, WORKSPACE_META_FILE), JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
@@ -96,5 +96,8 @@
     "@oxc-parser/binding-linux-x64-gnu": "^0.95.0",
     "@oxc-parser/binding-win32-x64-msvc": "^0.95.0"
   },
+  "engines": {
+    "node": ">=20.12.0"
+  },
   "packageManager": "pnpm@10.6.5"
 }

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

@@ -23,6 +23,11 @@ const PASSTHROUGH = new Map([
   ["/auth/request-2fa-email", "/api/auth/request-2fa-email"],
 ]);
 
+// 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._~-]*)*$/;
+
 export function publicSession(session) {
   if (!session) return {};
   return {
@@ -64,10 +69,10 @@ function singleFlight(token, operation) {
   return promise;
 }
 
-async function establish(request, response, endpoint) {
+async function establishWith(request, response, endpoint, payload) {
   const result = await backend(endpoint, request, {
     method: "POST",
-    body: await body(request),
+    body: payload,
   });
   if (result.requires_2fa || result.requires_tenant_assignment)
     return json(response, 200, result);
@@ -76,6 +81,65 @@ async function establish(request, response, endpoint) {
   json(response, 200, { user: result.user, account });
 }
 
+async function establish(request, response, endpoint) {
+  return establishWith(request, response, endpoint, await body(request));
+}
+
+/**
+ * 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.
+ *
+ * @param declaration Comma-separated absolute backend paths
+ * @returns The declared paths that are well-formed backend API paths
+ */
+export function allowedEstablishEndpoints(
+  declaration = process.env.DMS_AUTH_ESTABLISH_ENDPOINTS,
+) {
+  return (declaration ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => BACKEND_API_PATH.test(entry));
+}
+
+/**
+ * Whether a caller-named endpoint is one of the declared ones.
+ *
+ * The grammar is checked on the caller's value too, so a declaration that was
+ * never meant to be a prefix cannot be widened by a traversal or a query
+ * string smuggled into the request.
+ *
+ * @param endpoint Endpoint the browser asked to establish a session from
+ * @param allowed Declared endpoints
+ * @returns True when the endpoint may be called
+ */
+export function isAllowedEstablishEndpoint(endpoint, allowed) {
+  return (
+    typeof endpoint === "string" &&
+    BACKEND_API_PATH.test(endpoint) &&
+    allowed.includes(endpoint)
+  );
+}
+
+/**
+ * Open a session from a backend endpoint that mints a token pair.
+ *
+ * The generic half of `/auth/login`: a module whose own flow ends in an
+ * authenticated user — a self-service registration completing, an invitation
+ * being redeemed — points this at the backend route that finishes it, and the
+ * session cookie is written from the tokens the loader fetched itself. The
+ * browser never carries a token: it names an endpoint and a payload, and gets
+ * back the same `{ user, account }` the login route answers.
+ */
+async function establishFromEndpoint(request, response) {
+  const input = await body(request);
+  if (!isAllowedEstablishEndpoint(input.endpoint, allowedEstablishEndpoints()))
+    return json(response, 403, { error: "Forbidden" });
+  return establishWith(request, response, input.endpoint, input.payload ?? {});
+}
+
 export async function refreshSession(request, response) {
   const session = readSession(request);
   if (!session?.refreshToken) return undefined;
@@ -209,6 +273,7 @@ const actions = {
     establish(request, response, "/api/auth/signup"),
   "/auth/verify-2fa": (request, response) =>
     establish(request, response, "/api/auth/verify-2fa"),
+  "/auth/establish": establishFromEndpoint,
   "/auth/switch-account": switchAccount,
   "/auth/switch-tenant": switchTenant,
   "/auth/validate-account": validateAccount,

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

@@ -17,7 +17,10 @@ const UUID =
 function key() {
   const secret = process.env.DMS_SESSION_SECRET;
   if (!secret || secret.length < 32)
-    throw new Error("DMS_SESSION_SECRET must contain at least 32 characters");
+    throw new Error(
+      "DMS_SESSION_SECRET must contain at least 32 characters; " +
+        "generate one with: openssl rand -hex 32",
+    );
   return createHash("sha256").update(secret).digest();
 }
 

package/templates/vue/server.mjs

@@ -56,7 +56,7 @@ const AUTH_SERVER_ROUTES = [
   ["DELETE", /^\/api\/_auth\/session\/?$/],
   [
     "POST",
-    /^\/auth\/(?:login|signup|verify-2fa|request-2fa-email|switch-account|switch-tenant|validate-account|remove-account)\/?$/,
+    /^\/auth\/(?:login|signup|verify-2fa|establish|request-2fa-email|switch-account|switch-tenant|validate-account|remove-account)\/?$/,
   ],
   ["POST", /^\/auth\/oauth\/handoff\/?$/],
   ["GET", /^\/auth\/oauth\/[^/]+\/(?:start|callback)\/?$/],