@antelopejs/dms-frontend 0.1.2 → 0.1.4

package/README.md

@@ -162,6 +162,47 @@ 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
@@ -205,6 +246,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_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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-frontend",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Frontend-agnostic loader for AntelopeJS DMS, shipping the Vue 3 renderer (Vite, Inertia, SSR)",
   "keywords": [
     "antelope",
@@ -50,36 +50,36 @@
     "chalk": "^4.1.2",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
-    "figlet": "^1.8.0",
+    "figlet": "^1.9.4",
     "ignore": "^7.0.5",
-    "semver": "^7.7.0",
+    "semver": "^7.7.4",
     "unzipper": "^0.12.3"
   },
   "devDependencies": {
-    "@antelopejs/tooling-configs": "^0.0.4",
-    "@inertiajs/vue3": "^3.7.0",
+    "@antelopejs/tooling-configs": ">=0.0.6 <1.0.0",
+    "@inertiajs/vue3": "^3.7.1",
     "@types/figlet": "^1.7.0",
-    "@types/node": "^24.0.0",
-    "@types/semver": "^7.7.0",
+    "@types/node": "^24.8.1",
+    "@types/semver": "^7.7.1",
     "@types/unzipper": "^0.10.11",
-    "@unhead/vue": "^2.0.14",
-    "@vitejs/plugin-vue": "^6.0.0",
-    "@vue/server-renderer": "^3.5.0",
+    "@unhead/vue": "^2.1.4",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "@vue/server-renderer": "^3.5.25",
     "defu": "^6.1.4",
     "knip": "^6.34.0",
-    "ofetch": "^1.4.1",
+    "ofetch": "^1.5.1",
     "oxfmt": "^0.66.0",
     "oxlint": "1.81.0",
     "oxlint-tsgolint": "^7.0.2001",
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
-    "rimraf": "^6.0.1",
+    "rimraf": "^6.1.2",
     "tsx": "^4.20.6",
-    "typescript": "^5.8.2",
+    "typescript": "^5.9.3",
     "unplugin-auto-import": "^20.2.0",
-    "vite": "^7.0.0",
-    "vue": "^3.5.0",
-    "vue-i18n": "^11.1.12"
+    "vite": "^7.2.4",
+    "vue": "^3.5.25",
+    "vue-i18n": "^11.2.7"
   },
   "peerDependencies": {
     "@antelopejs/core": ">=1.6.0 <2"

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.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)\/?$/],