@antelopejs/dms-frontend 0.5.0 → 0.5.2

package/README.md

@@ -252,7 +252,7 @@ It stays `false` on the server and during hydration, which render the page resol
 
 ### Interface language
 
-The interface language follows the session (`useUserSession().user.language`), not the props of the page on screen: the first render takes it from the session the page arrived with, and it changes when the session's language does, after `useUserSession().fetch()` or a visit with a newer session. A page Inertia restores from history or serves from its prefetch cache carries the session it was fetched with: the frontend server stamps every session it writes (`session.updatedAt`), and a page carrying an older stamp of the same account updates neither the session nor the language. A session without a language, such as a signed-out one, keeps the language on screen; `$i18n.setLocale()` still switches it at any time.
+The interface language follows the session (`useUserSession().user.language`), not the props of the page on screen: the first render takes it from the session the page arrived with, and it changes when the session's language does, after `useUserSession().fetch()` or a visit with a newer session. A page Inertia restores from history or serves from its prefetch cache carries the session it was fetched with: the frontend server stamps every session it writes (`session.updatedAt`), and a page carrying an older stamp of the same account updates neither the session nor the language. A session without a language, such as a signed-out one, keeps the language on screen; `$i18n.setLocale()` still switches it at any time. It also remembers a language the application offers in the `dms_locale` cookie (one year, `SameSite=Lax`), and a page without a signed-in user's language, such as a public sign-in page, first renders in that one: a visitor's choice survives a reload, while a signed-in user's own language still comes first.
 
 ### Declaring the loader releases a module supports
 

package/package.json

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

package/templates/vue/app-runtime.ts

@@ -35,6 +35,7 @@ import {
   installDmsPlugins,
   preloadDmsPage,
   provideDmsFrontendRuntime,
+  readDmsLocaleCookie,
   resolveDmsAsyncComponents,
   resolveDmsComponent,
   serializeDmsAsyncData,
@@ -260,7 +261,12 @@ export async function configureDmsApp(
       options.serverFetch as typeof import("ofetch").ofetch,
       readServerRendered<Record<string, unknown>>(SSR_ASYNC_DATA_ID, {}),
     );
-  const locale = userLocale(options.initialPageProps.user) ?? DEFAULT_LOCALE;
+  // The signed-in user's language, else the one this browser picked, which is
+  // how a visitor's choice on a public page survives a reload.
+  const locale =
+    userLocale(options.initialPageProps.user) ??
+    readDmsLocaleCookie(runtime, supportedLocales) ??
+    DEFAULT_LOCALE;
   const messages = await loadLocaleMessages(locale);
   const i18n = createI18n({
     legacy: false,

package/templates/vue/frontend-module.ts

@@ -537,11 +537,54 @@ function parseRoute(runtime: DmsFrontendRuntime, url: string): DmsRoute {
   };
 }
 
+function hasSameEntries(
+  left: Record<string, string>,
+  right: Record<string, string>,
+): boolean {
+  const keys = Object.keys(left);
+  return (
+    keys.length === Object.keys(right).length &&
+    keys.every((key) => right[key] === left[key])
+  );
+}
+
+// Every parse builds a new query, params and matched: assigning them as they
+// come would re-run each watcher of the route on every call of useDmsRoute,
+// though the URL did not change. They are only replaced when their content did.
 function updateRoute(runtime: DmsFrontendRuntime, url: string): void {
   // The meta is the page's, not the URL's: a page declares it, then reads its
   // route, and the middleware the meta selected must still find it.
-  const { meta: _pageMeta, ...location } = parseRoute(runtime, url);
-  Object.assign(runtime.route, location);
+  const {
+    meta: _pageMeta,
+    query,
+    params,
+    matched,
+    ...location
+  } = parseRoute(runtime, url);
+  const route = runtime.route;
+  if (!hasSameEntries(query, route.query)) route.query = query;
+  if (!hasSameEntries(params, route.params)) route.params = params;
+  if (matched.length !== route.matched.length) route.matched = matched;
+  Object.assign(route, location);
+}
+
+const URL_BASE = "http://frontend.local";
+
+// The URL the browser shows: it may be ahead of the route, which follows
+// Inertia's page, when a component wrote it in place (history.replaceState).
+function currentUrl(runtime: DmsFrontendRuntime): string {
+  if (runtime.isServer || typeof window === "undefined")
+    return new URL(runtime.route.fullPath, URL_BASE).href;
+  return window.location.href;
+}
+
+// One spelling per URL: `a b`, `a+b` and `a%20b` are the same query, as are
+// `:` and `%3A`. The origin is kept, so a URL of another site never matches
+// the current one, whatever its path.
+function normalizeUrl(url: string, base: string): string {
+  const parsed = new URL(url, base);
+  const search = parsed.searchParams.toString();
+  return `${parsed.origin}${parsed.pathname}${search ? `?${search}` : ""}${parsed.hash}`;
 }
 
 function locationToUrl(
@@ -645,10 +688,13 @@ export function useDmsRoute(pattern?: string): DmsRoute {
 
 export function useDmsRouter(): DmsRouter {
   const runtime = useDmsRuntime();
-  const navigate = (to: RouteLocationRaw, options?: DmsNavigationOptions) =>
-    locationToUrl(runtime, to) === runtime.route.fullPath
+  const navigate = (to: RouteLocationRaw, options?: DmsNavigationOptions) => {
+    const current = currentUrl(runtime);
+    return normalizeUrl(locationToUrl(runtime, to), current) ===
+      normalizeUrl(current, current)
       ? Promise.resolve()
       : visit(runtime, to, options);
+  };
   return {
     currentRoute: computed(() => runtime.route),
     push: navigate,
@@ -1143,6 +1189,35 @@ function createCookieRef<T>(
   });
 }
 
+// The language a visitor picks, kept by the browser so that a reload renders
+// in it. A signed-in user's own language still comes first.
+const LOCALE_COOKIE = "dms_locale";
+const LOCALE_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+/**
+ * The language this browser picked: read from `document.cookie`, or in a
+ * server render from the request. Only one of `supportedLocales` counts.
+ */
+export function readDmsLocaleCookie(
+  runtime: DmsFrontendRuntime,
+  supportedLocales: string[],
+): string | undefined {
+  const source =
+    typeof document === "undefined" ? runtime.requestCookies : document.cookie;
+  try {
+    const locale = parseCookieValue<unknown>(
+      readCookie(source, LOCALE_COOKIE),
+      {},
+    );
+    return typeof locale === "string" && supportedLocales.includes(locale)
+      ? locale
+      : undefined;
+  } catch {
+    // A value that is not URI-encoded: as if the browser had picked none.
+    return undefined;
+  }
+}
+
 /**
  * A cookie as a ref, shared by every caller of the same name — so a plugin and
  * a page reading one preference see each other's writes — and read on the
@@ -1707,6 +1782,12 @@ export async function installDmsPlugins(
     const messages = await loadLocaleMessages(locale);
     i18n.setLocaleMessage(locale, messages);
     i18n.locale.value = locale;
+    if (typeof document !== "undefined" && supportedLocales.includes(locale))
+      writeCookie(LOCALE_COOKIE, locale, {
+        maxAge: LOCALE_COOKIE_MAX_AGE,
+        sameSite: "lax",
+        secure: globalThis.location?.protocol === "https:",
+      });
   };
   dmsI18n.locales = computed(() =>
     supportedLocales.map((code) => ({

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

@@ -197,7 +197,13 @@ export function oauthHandoff(request, response) {
   json(response, 200, handoff);
 }
 
-export function sessionFrom(result) {
+/**
+ * The session a token pair opens.
+ *
+ * @param result Backend answer carrying the tokens and the user
+ * @param persistent Whether the session outlives the browser
+ */
+export function sessionFrom(result, persistent = true) {
   const payload = JSON.parse(
     Buffer.from(
       result.access_token.split(".")[1] ?? "",
@@ -209,5 +215,6 @@ export function sessionFrom(result) {
     accessToken: result.access_token,
     refreshToken: result.refresh_token,
     activeTenantId: payload.tenantId ?? "default",
+    persistent,
   };
 }

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

@@ -9,17 +9,28 @@ import {
   sessionFrom,
 } from "./oauth.mjs";
 import {
+  clearSealedCookie,
   clearSession,
+  isPersistent,
   persistAccountSession,
   readAccount,
+  readSealedCookie,
   readSession,
   removeAccount,
   setRequestSession,
+  storeAccount,
+  writeSealedCookie,
 } from "./session.mjs";
 
 const REFRESH_TTL_MS = 15_000;
 const refreshes = new Map();
 
+// Carries the "keep me signed in" choice of a login across its 2FA step, whose
+// request names only the challenge. Lives as long as the challenge token.
+const PENDING_LOGIN = "dms_pending_login";
+const PENDING_LOGIN_PATH = "/auth/verify-2fa";
+const PENDING_LOGIN_LIFETIME_S = 300;
+
 const PASSTHROUGH = new Map([
   ["/auth/request-2fa-email", "/api/auth/request-2fa-email"],
 ]);
@@ -101,14 +112,30 @@ function singleFlight(token, operation) {
   return promise;
 }
 
-async function establishWith(request, response, endpoint, payload) {
+async function establishWith(
+  request,
+  response,
+  endpoint,
+  payload,
+  persistent = true,
+) {
   const result = await backend(endpoint, request, {
     method: "POST",
     body: payload,
   });
+  if (result.requires_2fa && typeof result.two_factor_token === "string")
+    writeSealedCookie(
+      response,
+      PENDING_LOGIN,
+      { token: result.two_factor_token, persistent },
+      PENDING_LOGIN_LIFETIME_S,
+      PENDING_LOGIN_PATH,
+    );
   if (result.requires_2fa || result.requires_tenant_assignment)
     return json(response, 200, result);
-  const session = sessionFrom(result);
+  if (readSealedCookie(request, PENDING_LOGIN))
+    clearSealedCookie(response, PENDING_LOGIN, PENDING_LOGIN_PATH);
+  const session = sessionFrom(result, persistent);
   const account = persistAccountSession(request, response, session);
   json(response, 200, { user: result.user, account });
 }
@@ -117,6 +144,42 @@ async function establish(request, response, endpoint) {
   return establishWith(request, response, endpoint, await body(request));
 }
 
+/**
+ * Sign in with a password. Only a login that asked to be kept signed in
+ * outlives the browser; any other ends when the browser closes.
+ */
+async function login(request, response) {
+  const input = await body(request);
+  return establishWith(
+    request,
+    response,
+    "/api/auth/login",
+    input,
+    input.keep_login === true,
+  );
+}
+
+/**
+ * Finish a login on its 2FA step, with the lifetime the login chose. A
+ * challenge that no login of this browser left a choice for, such as the one
+ * an OAuth sign-in hands over, keeps the default.
+ */
+async function verifyTwoFactor(request, response) {
+  const input = await body(request);
+  const pending = readSealedCookie(request, PENDING_LOGIN);
+  const persistent =
+    typeof input.token === "string" && pending?.token === input.token
+      ? isPersistent(pending)
+      : true;
+  return establishWith(
+    request,
+    response,
+    "/api/auth/verify-2fa",
+    input,
+    persistent,
+  );
+}
+
 /**
  * Backend endpoints this deployment lets a module open a session from.
  *
@@ -196,7 +259,7 @@ export async function refreshSession(request, response) {
     const user = await backend("/api/auth/me", request, {
       token: tokens.access_token,
     });
-    const refreshed = sessionFrom({ ...tokens, user });
+    const refreshed = sessionFrom({ ...tokens, user }, isPersistent(session));
     persistAccountSession(request, response, refreshed, session.accountId);
     setRequestSession(request, refreshed);
     return refreshed;
@@ -246,7 +309,7 @@ async function switchTenant(request, response) {
   const user = await backend("/api/auth/me", request, {
     token: tokens.access_token,
   });
-  const switched = sessionFrom({ ...tokens, user });
+  const switched = sessionFrom({ ...tokens, user }, isPersistent(session));
   persistAccountSession(request, response, switched, session.accountId);
   json(response, 200, { success: true, user });
 }
@@ -263,7 +326,7 @@ async function switchAccount(request, response) {
     const user = await backend("/api/auth/me", request, {
       token: tokens.access_token,
     });
-    const session = sessionFrom({ ...tokens, user });
+    const session = sessionFrom({ ...tokens, user }, isPersistent(account));
     const descriptor = persistAccountSession(
       request,
       response,
@@ -281,6 +344,36 @@ async function switchAccount(request, response) {
   }
 }
 
+/**
+ * Keep the tokens a validation refreshed, without changing which account is
+ * signed in. Another account only has its own cookie updated. The current one
+ * also has the session updated, since a refresh may have rotated the token the
+ * session holds; it keeps its user as the backend gave it.
+ */
+function storeValidatedAccount(request, response, account, accountId, tokens) {
+  const current = readSession(request);
+  if (current?.accountId === accountId) {
+    persistAccountSession(
+      request,
+      response,
+      sessionFrom({ ...tokens, user: current.user }, isPersistent(current)),
+      accountId,
+    );
+    return;
+  }
+  const user = {
+    _id: account.userId,
+    email: account.email,
+    name: account.name,
+  };
+  storeAccount(
+    request,
+    response,
+    sessionFrom({ ...tokens, user }, isPersistent(account)),
+    accountId,
+  );
+}
+
 async function validateAccount(request, response) {
   const input = await body(request);
   const account = readAccount(request, input.accountId);
@@ -290,15 +383,7 @@ async function validateAccount(request, response) {
       method: "POST",
       body: { token: account.refreshToken },
     });
-    persistAccountSession(
-      request,
-      response,
-      sessionFrom({
-        ...tokens,
-        user: { id: account.userId, email: account.email, name: account.name },
-      }),
-      input.accountId,
-    );
+    storeValidatedAccount(request, response, account, input.accountId, tokens);
     json(response, 200, { valid: true });
   } catch (error) {
     const rejected =
@@ -309,12 +394,10 @@ async function validateAccount(request, response) {
 }
 
 const actions = {
-  "/auth/login": (request, response) =>
-    establish(request, response, "/api/auth/login"),
+  "/auth/login": login,
   "/auth/signup": (request, response) =>
     establish(request, response, "/api/auth/signup"),
-  "/auth/verify-2fa": (request, response) =>
-    establish(request, response, "/api/auth/verify-2fa"),
+  "/auth/verify-2fa": verifyTwoFactor,
   "/auth/establish": establishFromEndpoint,
   "/auth/switch-account": switchAccount,
   "/auth/switch-tenant": switchTenant,

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

@@ -60,9 +60,27 @@ function cookieValue(request, name) {
     .find(([key]) => key === name)?.[1];
 }
 
+/**
+ * Cookie attributes. Without a `maxAge` the cookie lasts as long as the
+ * browser session: it is gone once the browser is closed.
+ */
 function attributes(maxAge, path = "/") {
   const secure = process.env.DMS_COOKIE_SECURE !== "false" ? "; Secure" : "";
-  return `Path=${path}; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${secure}`;
+  const lifetime = maxAge === undefined ? "" : `; Max-Age=${maxAge}`;
+  return `Path=${path}; HttpOnly; SameSite=Lax${lifetime}${secure}`;
+}
+
+/**
+ * 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.
+ */
+export function isPersistent(session) {
+  return session?.persistent !== false;
+}
+
+function lifetime(persistent) {
+  return persistent ? MAX_AGE : undefined;
 }
 
 function appendCookie(response, cookie) {
@@ -87,6 +105,7 @@ function descriptor(session, accountId) {
     email: session.user?.email,
     name: session.user?.name,
     activeTenantId: session.activeTenantId,
+    persistent: isPersistent(session),
   };
 }
 
@@ -103,7 +122,7 @@ export function setRequestSession(request, session) {
 export function writeSession(response, session) {
   appendCookie(
     response,
-    `${SESSION_COOKIE}=${encode(session)}; ${attributes(MAX_AGE)}`,
+    `${SESSION_COOKIE}=${encode(session)}; ${attributes(lifetime(isPersistent(session)))}`,
   );
 }
 
@@ -117,9 +136,10 @@ export function readAccounts(request) {
 }
 
 function writeAccountIndex(response, accounts) {
+  const persistent = Object.values(accounts).some(isPersistent);
   appendCookie(
     response,
-    `${ACCOUNT_INDEX_COOKIE}=${encode(accounts)}; ${attributes(MAX_AGE)}`,
+    `${ACCOUNT_INDEX_COOKIE}=${encode(accounts)}; ${attributes(lifetime(persistent))}`,
   );
 }
 
@@ -136,7 +156,7 @@ export function storeAccount(request, response, session, accountId) {
   writeAccountIndex(response, accounts);
   appendCookie(
     response,
-    `${accountCookieName(id)}=${encode({ refreshToken: session.refreshToken, ...accountDescriptor })}; ${attributes(MAX_AGE)}`,
+    `${accountCookieName(id)}=${encode({ refreshToken: session.refreshToken, ...accountDescriptor })}; ${attributes(lifetime(accountDescriptor.persistent))}`,
   );
   return accountDescriptor;
 }
@@ -177,13 +197,19 @@ export function readSealedCookie(request, name) {
   return value ? decode(value) : undefined;
 }
 
-export function writeSealedCookie(response, name, value, maxAge) {
+export function writeSealedCookie(
+  response,
+  name,
+  value,
+  maxAge,
+  path = "/auth/oauth",
+) {
   appendCookie(
     response,
-    `${name}=${encode(value)}; ${attributes(maxAge, "/auth/oauth")}`,
+    `${name}=${encode(value)}; ${attributes(maxAge, path)}`,
   );
 }
 
-export function clearSealedCookie(response, name) {
-  appendCookie(response, `${name}=; ${attributes(0, "/auth/oauth")}`);
+export function clearSealedCookie(response, name, path = "/auth/oauth") {
+  appendCookie(response, `${name}=; ${attributes(0, path)}`);
 }