@antelopejs/dms 0.8.3 → 0.9.1

package/frontend-vue/layers/dms-layout/i18n/locales/layout-fr-FR.json

@@ -739,18 +739,85 @@
     },
     "store": {
       "title": "Store de modules",
-      "description": "Les modules AntelopeJS officiels qui ne sont pas installés sur cette plateforme.",
-      "soon": "Bientôt",
-      "banner": {
-        "title": "Bientôt disponible",
-        "description": "Parcourez et installez les modules officiels du catalogue AntelopeJS directement depuis votre tableau de bord."
+      "description": "Les modules officiels AntelopeJS : installez-les, mettez-les à jour, mettez-les en pause ou retirez-les sans toucher au code du projet.",
+      "scope": {
+        "label": "Afficher",
+        "all": "Tous · {count}",
+        "available": "Disponibles · {count}",
+        "installed": "Installés · {count}"
       },
+      "state": {
+        "available": "Disponible",
+        "busy": "En cours",
+        "active": "Actif",
+        "disabled": "En pause",
+        "error": "Échec",
+        "pending": "Non appliqué",
+        "update_available": "Mise à jour"
+      },
+      "actions": {
+        "install": "Installer",
+        "update": "Mettre à jour",
+        "enable": "Reprendre",
+        "disable": "Mettre en pause",
+        "uninstall": "Désinstaller",
+        "apply": "Appliquer",
+        "manage": "Gérer"
+      },
+      "steps": {
+        "resolve": "Trouver la dernière version",
+        "unload": "Arrêter la version en cours",
+        "load": "Télécharger et démarrer",
+        "save": "Écrire antelope.config.ts",
+        "dependencies": "Installer les modules requis"
+      },
+      "progress": {
+        "install": "Installation",
+        "update": "Mise à jour",
+        "enable": "Reprise",
+        "disable": "Mise en pause",
+        "uninstall": "Désinstallation",
+        "apply": "Application"
+      },
+      "more_actions": "Autres actions",
+      "incompatible": "Demande {'@'}antelopejs/interface-dms {range} : mettez d’abord le DMS à jour",
+      "no_release": "Le registre npm ne propose aucune version lisible depuis cette plateforme",
+      "locked": "Un autre module est en cours de modification",
+      "pending_hint": "antelope.config.ts et la plateforme ne concordent pas : Appliquer les remet d’accord.",
+      "uninstall_confirm": {
+        "title": "Désinstaller {module} ?",
+        "description": "{module} s’arrête et quitte le menu. Ses données (collections, fichiers, réglages) restent en place et reviennent si vous le réinstallez."
+      },
+      "action_failed": "{module} n’a pas pu être modifié",
+      "errors": {
+        "store_busy": "Un autre module est en cours de modification. Réessayez une fois terminé.",
+        "store_module_unknown": "Ce module n’est pas dans le catalogue.",
+        "store_disabled": "Le store est en lecture seule sur cette plateforme.",
+        "store_invalid_state": "Le module a changé entre-temps. La liste est de nouveau à jour.",
+        "unauthorized": "Seuls les propriétaires de la plateforme gèrent les modules.",
+        "store_module_required": "D’autres modules en cours d’exécution ont besoin de celui-ci. Retirez-les d’abord."
+      },
+      "frontend": {
+        "dev": {
+          "title": "Rechargement de l’interface pour {modules}",
+          "description": "Le frontend de dev prend le changement en compte et la page se recharge toute seule."
+        },
+        "production": {
+          "title": "{modules} : reconstruisez le frontend",
+          "description": "Le module tourne côté backend. Lancez {command} puis redémarrez le frontend pour afficher ses pages."
+        },
+        "unknown": {
+          "title": "{modules} : redémarrez le frontend",
+          "description": "Le module tourne côté backend, mais aucun serveur frontend n’a indiqué ce qu’il sert. Redémarrez-le ({command} en production) pour afficher les pages du module."
+        }
+      },
+      "disabled": {
+        "title": "Le store est en lecture seule ici",
+        "description": "Les modules s’installent depuis le développement, qui les écrit dans antelope.config.ts ; cette plateforme charge ce que déclare ce fichier. Passez store.enabled à true dans la configuration du DMS pour les modifier d’ici."
+      },
+      "load_error": "Le store de modules n’a pas pu être chargé",
       "search_placeholder": "Rechercher dans le store",
       "category_label": "Catégorie du store",
-      "available_soon": "Bientôt disponible",
-      "install": "Installer",
-      "install_soon": "Bientôt disponible",
-      "command_label": "Commande d’installation",
       "no_result": {
         "title": "Aucun module du store ne correspond à « {query} »",
         "title_filtered": "Aucun module du store ne correspond à ces filtres"
@@ -813,6 +880,37 @@
           "title": "SaaS",
           "description": "Offres, espaces de travail, facturation Stripe et cycle de vie client."
         }
+      },
+      "config_error": "antelope.config.ts ne peut pas être modifié d’ici",
+      "frontend_requirement": {
+        "needs": "Demande dms-frontend {range}, ce projet utilise {running}.",
+        "run": "Pour passer le projet à dms-frontend {target}, exécutez :",
+        "breaks": "dms-frontend {target} refuserait ces couches frontend installées :",
+        "supports": "accepte {range}",
+        "no_target": "Aucune version publiée de dms-frontend ne correspond à cette plage."
+      },
+      "requires": "Requiert : {interfaces}",
+      "requires_first": "Demande {interfaces}, qu’aucun module en cours d’exécution n’implémente : installez d’abord un module qui le fait.",
+      "used_by": "Utilisé par : {modules}. Retirez-les d’abord.",
+      "frontend_version": {
+        "label": "dms-frontend {version}",
+        "reported": "Indiquée par le serveur frontend en cours d’exécution",
+        "project": "Lue dans les dépendances du projet : aucun serveur frontend n’a indiqué sa version"
+      },
+      "install_dialog": {
+        "title": "Installer {module}",
+        "description": "{module} demande des interfaces qu’aucun module en cours d’exécution n’implémente. Choisissez un module pour chacune : il est installé en premier.",
+        "other": "Autre paquet npm",
+        "package_label": "Paquet npm",
+        "package_placeholder": "{'@'}scope/paquet",
+        "config_label": "Configuration (JSON)",
+        "config_hint": "Facultatif",
+        "note": "Ces modules sont ajoutés à antelope.config.ts comme entrées distinctes, où leur configuration reste modifiable par la suite.",
+        "errors": {
+          "package_required": "Saisissez un nom de paquet npm.",
+          "package_invalid": "Ce n’est pas un nom de paquet npm : les sources git et locales ne sont pas acceptées.",
+          "config_invalid": "Doit être un objet JSON."
+        }
       }
     },
     "sort": {

package/frontend-vue/layers/dms-layout/server/html-render.ts

@@ -0,0 +1,58 @@
+import type { DmsServerEvent } from "#dms/server";
+import { privateSecret } from "../../../server/private-options";
+import { validRenderToken } from "./render-token";
+
+const SERVICE_TOKEN_HEADER = "x-dms-service-token";
+
+interface RenderInput {
+  templateName?: unknown;
+  props?: unknown;
+}
+
+function failure(status: number, message: string): Response {
+  return Response.json({ message }, { status });
+}
+
+function renderSecret(event: DmsServerEvent): string | undefined {
+  return privateSecret(
+    event,
+    "htmlRender",
+    "serviceSecret",
+    "DMS_HTML_RENDER_SECRET",
+  );
+}
+
+/**
+ * `POST /api/html/render`: renders one of the application's email templates
+ * for the DMS backend (`GenerateHtml`), which authenticates with a
+ * single-use service token rather than a browser session.
+ */
+export async function renderHtml(event: DmsServerEvent): Promise<Response> {
+  if (
+    !validRenderToken(
+      event.request.headers.get(SERVICE_TOKEN_HEADER),
+      renderSecret(event),
+    )
+  )
+    return failure(401, "Invalid service token");
+  const input = await event.readJson<RenderInput>();
+  if (
+    typeof input.templateName !== "string" ||
+    input.templateName.trim() === "" ||
+    typeof input.props !== "object"
+  )
+    return failure(400, "Invalid request body");
+  try {
+    const html = await event.renderEmail(
+      input.templateName,
+      (input.props ?? {}) as Record<string, unknown>,
+      { locale: event.request.headers.get("x-content-language") ?? undefined },
+    );
+    return Response.json({ html });
+  } catch {
+    return failure(
+      404,
+      `Template "${input.templateName}" not found or render failed`,
+    );
+  }
+}

package/frontend-vue/layers/dms-layout/server/render-token.ts

@@ -0,0 +1,95 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// The service token that guards the HTML render route, minted by the DMS
+// backend (`service-jwt.ts`) for its own render requests: its signature, its
+// claims and its single use.
+
+const RENDER_TOKEN_LIFETIME_SECONDS = 5 * 60;
+const RENDER_REPLAY_LIMIT = 10_000;
+
+interface RenderTokenClaims {
+  namespace?: unknown;
+  purpose?: unknown;
+  aud?: unknown;
+  jti?: unknown;
+  iat?: unknown;
+  exp?: unknown;
+}
+
+/** jti -> exp, for tokens already spent. Pruned on every accepted token. */
+const usedRenderTokens = new Map<string, number>();
+
+/**
+ * Constant-time check of the token's HMAC. The length comparison guards
+ * timingSafeEqual, which throws on mismatched lengths; it is not itself a
+ * timing leak, since the length of a base64url HMAC is fixed.
+ */
+function signatureValid(parts: string[], secret: string): boolean {
+  const expected = createHmac("sha256", secret)
+    .update(`${parts[0]}.${parts[1]}`)
+    .digest("base64url");
+  if (expected.length !== parts[2].length) return false;
+  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts[2]));
+}
+
+/**
+ * The claims this service accepts. `exp - iat` is bounded so a token minted
+ * with a far-future expiry cannot outlive the intended window.
+ */
+function claimsValid(
+  payload: RenderTokenClaims,
+  now: number,
+): payload is RenderTokenClaims & { jti: string; exp: number } {
+  return (
+    payload.namespace === "html-render-service" &&
+    payload.purpose === "html-render" &&
+    payload.aud === "dms-frontend" &&
+    typeof payload.jti === "string" &&
+    payload.jti.length >= 16 &&
+    Number.isSafeInteger(payload.iat) &&
+    Number.isSafeInteger(payload.exp) &&
+    (payload.exp as number) > now &&
+    (payload.exp as number) - (payload.iat as number) <=
+      RENDER_TOKEN_LIFETIME_SECONDS &&
+    (payload.iat as number) <= now
+  );
+}
+
+/**
+ * Records a token as spent, dropping expired entries first and evicting the
+ * oldest if the map is at its cap, so a flood of tokens cannot grow it without
+ * bound.
+ */
+function rememberToken(jti: string, exp: number, now: number) {
+  for (const [spent, expiresAt] of usedRenderTokens)
+    if (expiresAt <= now) usedRenderTokens.delete(spent);
+  while (usedRenderTokens.size >= RENDER_REPLAY_LIMIT)
+    usedRenderTokens.delete(usedRenderTokens.keys().next().value as string);
+  usedRenderTokens.set(jti, exp);
+}
+
+/**
+ * Whether the token is well-formed, signed with `secret`, unexpired and not
+ * already spent. A token accepted here is immediately marked as spent.
+ */
+export function validRenderToken(
+  token: string | null,
+  secret: string | undefined,
+): boolean {
+  if (!token || !secret) return false;
+  const parts = token.split(".");
+  if (parts.length !== 3) return false;
+  if (!signatureValid(parts, secret)) return false;
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1], "base64url").toString("utf8"),
+    ) as RenderTokenClaims;
+    const now = Math.floor(Date.now() / 1000);
+    if (!claimsValid(payload, now)) return false;
+    if (usedRenderTokens.has(payload.jti)) return false;
+    rememberToken(payload.jti, payload.exp, now);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/frontend-vue/layers/dms-onboarding/app/composables/onboarding/useOnboarding.ts

@@ -6,34 +6,38 @@ interface OnboardingInfoResponse {
   has_onboarded: boolean;
 }
 
+/**
+ * Transferred: the global middleware reads it while a server renders the
+ * page, and the browser's run of the middleware then finds it instead of
+ * asking again. It holds nothing private.
+ */
+function useOnboardingCache() {
+  return useDmsState<OnboardingInfo | null>("dms-onboarding-info", () => null, {
+    transfer: true,
+  });
+}
+
 export const useOnboarding = async (): Promise<OnboardingInfo> => {
-  const cache = useDmsState<OnboardingInfo | null>(
-    "dms-onboarding-info",
-    () => null,
-  );
+  const cache = useOnboardingCache();
 
-  if (cache.value) return cache.value;
+  const known = cache.value;
+  if (known) return known;
 
   const { $authFetch } = useAuthFetch();
 
-  const response = await $authFetch<OnboardingInfoResponse>(
-    "/api/onboarding/informations",
-    { method: "GET" },
-  );
-
-  const info: OnboardingInfo = {
-    hasOnboarded: response.has_onboarded,
-  };
-
-  cache.value = info;
-  return info;
+  // One request per app however many callers ask before it answers: the
+  // preload started with the app and the `onboarding` middleware share it.
+  await useTrailingDeduper("onboarding").join(async () => {
+    const response = await $authFetch<OnboardingInfoResponse>(
+      "/api/onboarding/informations",
+      { method: "GET" },
+    );
+    cache.value = { hasOnboarded: response.has_onboarded };
+  });
+  return cache.value as OnboardingInfo;
 };
 
 /** Release the cached onboarding guard after the backend creates the admin. */
 export const setOnboardingComplete = () => {
-  const cache = useDmsState<OnboardingInfo | null>(
-    "dms-onboarding-info",
-    () => null,
-  );
-  cache.value = { hasOnboarded: true };
+  useOnboardingCache().value = { hasOnboarded: true };
 };

package/frontend-vue/layers/dms-onboarding/app/middleware/onboarding.global.ts

@@ -5,7 +5,7 @@ const LOGIN_PATH = "/auth";
 // login page for anyone else rather than a homepage whose 401 would bounce
 // them there anyway.
 function completedOnboardingDestination(): string {
-  const { loggedIn } = useUserSession();
+  const { loggedIn } = useDmsUserSession();
   return loggedIn.value ? useHomepage() : LOGIN_PATH;
 }
 

package/frontend-vue/layers/dms-onboarding/app/plugins/onboarding-preload.ts

@@ -0,0 +1,9 @@
+/**
+ * Asks for the onboarding status as the app starts rather than when the
+ * `onboarding` middleware does, once the plugins and the page have set up:
+ * the request runs alongside the others the render makes, and the middleware
+ * joins it. A failure stays the middleware's to handle.
+ */
+export default defineDmsPlugin(() => {
+  useOnboarding().catch(() => undefined);
+});

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/registerDefaults.ts

@@ -742,7 +742,9 @@ interface TextOptions {
 /**
  * `string`: the value as written, in the tone the row gives (`toneField`) when
  * it gives one; a row without one keeps the bare value, as a string column
- * always drew it.
+ * always drew it. An empty one is `null`: a cell rendering `""` as its root
+ * leaves no node in the server's HTML, which the browser hydrates as a
+ * mismatch, where `null` renders a placeholder both sides agree on.
  */
 function renderText(
   value: unknown,
@@ -750,6 +752,7 @@ function renderText(
   options?: unknown,
   row?: Row,
 ): unknown {
+  if (value === "") return null;
   const tone = readRowTone(
     row,
     (options as TextOptions | undefined)?.toneField,

package/frontend-vue/layers/dms-ui/app/build/composables/files/useFileMetadata.ts

@@ -0,0 +1,162 @@
+import {
+  effectScope,
+  getCurrentInstance,
+  inject,
+  onScopeDispose,
+  shallowReactive,
+  watch,
+} from "vue";
+import { FORM_CONTENT_LANGUAGE_KEY } from "../../../composables/form/types/content-language";
+import {
+  isDefinitiveMetadataFailure,
+  resolveMetadataRetryDelay,
+} from "../../../utils/metadataRetry";
+
+/** What `/api/files/metadata` answers for a stored file. */
+export interface FileMetadata {
+  resourceKey: string;
+  filename: string;
+  size: number;
+  mimetype: string;
+  url: string;
+  /** When `url` stops working, in milliseconds since the epoch. */
+  expiresAt?: number;
+}
+
+const METADATA_URL = "/api/files/metadata";
+// A read URL is read again this long before it expires.
+const URL_REFRESH_LEAD_MS = 5000;
+
+const isExpired = (metadata: FileMetadata): boolean =>
+  metadata.expiresAt !== undefined && metadata.expiresAt <= Date.now();
+
+/**
+ * The metadata of stored files (name, size, type, read URL), one read per
+ * file key, shared by every component showing that file.
+ *
+ * A key resolved during a component's setup (directly, or from an immediate
+ * watcher) is read with the page: a server render waits for it and hands it
+ * to the browser, which does not ask again. A key resolved later (a new
+ * value, an upload) is read in the browser. While a component shows a file,
+ * its URL is read again before it expires, and a failed read that may heal
+ * (network, 5xx, rate limiting) is retried with a growing delay; a refused or
+ * missing file (another 4xx) is not.
+ *
+ * @param storage The storage the keys live in (the field's `storage`)
+ */
+export function useFileMetadata(storage?: string) {
+  const contentLanguage = inject(FORM_CONTENT_LANGUAGE_KEY, undefined);
+  // Reads resolved past the setup run with the application's context.
+  const app = getCurrentInstance()?.appContext.app;
+  const scope = effectScope();
+  const reads = shallowReactive(new Map<string, ApiDataResult<FileMetadata>>());
+  const timers = new Map<string, ReturnType<typeof setTimeout>>();
+  const failures = new Map<string, number>();
+
+  function schedule(key: string, delay: number, read: () => Promise<void>) {
+    clearTimeout(timers.get(key));
+    timers.set(
+      key,
+      setTimeout(() => {
+        timers.delete(key);
+        void read();
+      }, delay),
+    );
+  }
+
+  /** The next read of `key` its last answer calls for, in the browser. */
+  function follow(key: string, result: ApiDataResult<FileMetadata>): void {
+    const refresh = () => result.refresh({ dedupe: "defer" });
+    watch(
+      [result.data, result.error, result.status],
+      ([metadata, error, status]) => {
+        if (status === "pending" || status === "idle") return;
+        clearTimeout(timers.get(key));
+        if (error) {
+          const attempts = (failures.get(key) ?? 0) + 1;
+          failures.set(key, attempts);
+          const delay = resolveMetadataRetryDelay(error, attempts);
+          if (delay !== null) schedule(key, delay, refresh);
+          return;
+        }
+        failures.delete(key);
+        if (metadata?.expiresAt === undefined) return;
+        const remaining = Math.max(metadata.expiresAt - Date.now(), 0);
+        const lead = Math.min(URL_REFRESH_LEAD_MS, remaining / 2);
+        schedule(key, remaining - lead, refresh);
+      },
+      { immediate: true },
+    );
+  }
+
+  function readOf(key: string): ApiDataResult<FileMetadata> {
+    const known = reads.get(key);
+    if (known) return known;
+    const read = () =>
+      useApiData<FileMetadata>(
+        `dms-file-metadata:${storage ?? ""}:${contentLanguage ?? ""}:${key}`,
+        ({ $authFetch, signal }) =>
+          $authFetch<FileMetadata>(METADATA_URL, {
+            query: { resourceKey: key, storage },
+            headers: contentLanguage
+              ? { [CONTENT_LANGUAGE_HEADER]: contentLanguage }
+              : undefined,
+            signal,
+          }),
+      );
+    const result = scope.run(() => {
+      const started =
+        getCurrentInstance() || !app ? read() : app.runWithContext(read);
+      if (!import.meta.env.SSR) follow(key, started);
+      return started;
+    })!;
+    reads.set(key, result);
+    return result;
+  }
+
+  /**
+   * Reads `key`'s metadata unless it is known; `force` reads it again (to
+   * open a file with a fresh URL).
+   */
+  async function resolve(key: string, force = false): Promise<void> {
+    const result = readOf(key);
+    if (force) await result.refresh({ dedupe: "defer" });
+    else await result;
+  }
+
+  /** The last metadata read for `key`, its URL possibly expired. */
+  const lastRead = (key: string): FileMetadata | undefined =>
+    reads.get(key)?.data.value ?? undefined;
+
+  /**
+   * Whether `key` cannot be shown: its last read failed and the server
+   * refused it for good, or nothing usable is left (never read, or expired).
+   */
+  function isUnavailable(key: string): boolean {
+    const result = reads.get(key);
+    // A failure stays until the next answer: a retry keeps the file marked.
+    if (!result?.error.value) return false;
+    const known = result.data.value;
+    return (
+      !known ||
+      isExpired(known) ||
+      isDefinitiveMetadataFailure(result.error.value)
+    );
+  }
+
+  /** The metadata to show for `key`: read, not expired, still available. */
+  function metadata(key: string): FileMetadata | undefined {
+    const known = lastRead(key);
+    return known && !isExpired(known) && !isUnavailable(key)
+      ? known
+      : undefined;
+  }
+
+  onScopeDispose(() => {
+    scope.stop();
+    timers.forEach(clearTimeout);
+    timers.clear();
+  });
+
+  return { resolve, metadata, lastRead, isUnavailable };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/form/formRecordLoad.ts

@@ -1,4 +1,4 @@
-import { type Ref, ref } from "vue";
+import { type Ref, ref, watch } from "vue";
 import { apiErrorStatus } from "#dms-core/app/composables/useFieldErrors";
 import { HTTP_FORBIDDEN } from "#dms-core/app/utils/http-status";
 
@@ -27,9 +27,7 @@ export function missingRecordFailure(
   address: FormRecordAddress,
 ): FormLoadFailure | null {
   const isMissing =
-    !!address.requiresRecord &&
-    !!address.fetchUrl &&
-    !address.resolvedFetchUrl;
+    !!address.requiresRecord && !!address.fetchUrl && !address.resolvedFetchUrl;
   return isMissing ? "missing" : null;
 }
 
@@ -56,15 +54,31 @@ export function formLoadFailure(error: unknown): FormLoadFailure | null {
   return apiErrorStatus(error) === HTTP_FORBIDDEN ? "forbidden" : "error";
 }
 
+/** How a form takes the answers of its record's later reads. */
+export interface FormRecordLoadOptions {
+  /**
+   * Whether the user holds edits a later read must not replace: the read is
+   * then left for the next opening (a save reads the record again).
+   */
+  isEditing?: () => boolean;
+  /** Called once a later read was applied: its values are the saved ones. */
+  onReloaded?: () => void;
+}
+
 /**
  * Follow a form's record load: `apply` receives the record once it loaded,
  * and only then. A failed load is never applied, not even the values a
  * previous opening left in the cache: a form showing them, or its defaults,
  * would read as the record and save over it.
+ *
+ * The record is read again in the background each time the form mounts on a
+ * cached one, and when the page refreshes its data: the form opens on the
+ * cached values, then takes the new ones, unless the user started editing.
  */
 export function trackFormRecordLoad<T>(
   load: FormLoadSource<T>,
   apply: (payload: T) => void,
+  options: FormRecordLoadOptions = {},
 ): FormRecordLoad {
   const failure = ref<FormLoadFailure | null>(null);
   const retrying = ref(false);
@@ -74,6 +88,11 @@ export function trackFormRecordLoad<T>(
     if (!failure.value && payload) apply(payload);
   };
   settle();
+  watch([load.data, load.error], () => {
+    if (options.isEditing?.()) return;
+    settle();
+    if (!failure.value) options.onReloaded?.();
+  });
   return {
     failure,
     retrying,