@antelopejs/dms-frontend 0.9.3 → 0.10.1

package/templates/vue/server/auth/client-ip.mjs

@@ -1,5 +1,21 @@
+import { isString } from "../type-guards.mjs";
+
 const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9a-z-]+$/;
 
+/**
+ * A request, whose socket is a TLS one (`encrypted`) when the server itself
+ * terminates TLS.
+ *
+ * @typedef {import("node:http").IncomingMessage & {
+ *   socket: import("node:net").Socket & { encrypted?: boolean }
+ * }} ForwardedRequest
+ */
+
+/**
+ * @param {string | undefined} value A header name from the environment
+ * @returns {string | undefined} The lowercase name, `undefined` when it is not
+ *   a header name
+ */
 function headerName(value) {
   const name = (value ?? "").trim().toLowerCase();
   return HEADER_NAME.test(name) ? name : undefined;
@@ -17,18 +33,26 @@ function trustedHops() {
  * so its presence also vouches for the platform's `X-Forwarded-*`. On a path
  * the platform does not front (a private call from another service), it is
  * absent and the request falls back to `DMS_TRUSTED_PROXY_HOPS`.
+ *
+ * @param {ForwardedRequest} request
+ * @returns {string | undefined}
  */
 function platformClientIp(request) {
   const name = headerName(process.env.DMS_CLIENT_IP_HEADER);
   if (!name) return undefined;
   const value = request.headers?.[name];
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+  return isString(value) && value.trim() ? value.trim() : undefined;
 }
 
+/** @param {ForwardedRequest} request */
 function isProxyTrusted(request) {
   return Boolean(platformClientIp(request)) || trustedHops() > 0;
 }
 
+/**
+ * @param {ForwardedRequest} request
+ * @returns {string}
+ */
 export function requestScheme(request) {
   if (isProxyTrusted(request)) {
     const forwarded = String(request.headers["x-forwarded-proto"] ?? "")
@@ -41,6 +65,10 @@ export function requestScheme(request) {
   return request.socket?.encrypted ? "https" : "http";
 }
 
+/**
+ * @param {ForwardedRequest} request
+ * @returns {string | undefined}
+ */
 function requestHost(request) {
   if (!isProxyTrusted(request)) return request.headers.host;
   return (
@@ -62,8 +90,12 @@ function requestHost(request) {
  * proxy wrote it (`DMS_TRUSTED_PROXY_HOPS` above `0`): otherwise any caller
  * could have, and the socket's address replaces it. The scheme and the host
  * are read the same way as the CSRF origin check reads them.
+ *
+ * @param {ForwardedRequest} request
+ * @returns {Record<string, string>}
  */
 export function forwardedHeaders(request) {
+  /** @type {Record<string, string>} */
   const headers = {
     "x-forwarded-for": forwardedFor(request),
     "x-forwarded-proto": requestScheme(request),
@@ -74,6 +106,10 @@ export function forwardedHeaders(request) {
   return headers;
 }
 
+/**
+ * @param {ForwardedRequest} request
+ * @returns {string}
+ */
 function forwardedFor(request) {
   const platformIp = platformClientIp(request);
   if (platformIp) return platformIp;
@@ -92,12 +128,19 @@ function forwardedFor(request) {
  * address this server resolved, so the backend reads the same address
  * without counting hops. Always written, never relayed: a value the caller
  * sent is replaced. None when the variable is unset.
+ *
+ * @param {ForwardedRequest} request
+ * @returns {Record<string, string>}
  */
 export function clientIpHeader(request) {
   const name = headerName(process.env.DMS_CLIENT_IP_HEADER);
   return name ? { [name]: clientIp(request) } : {};
 }
 
+/**
+ * @param {ForwardedRequest} request
+ * @returns {boolean}
+ */
 export function isSameOrigin(request) {
   const origin = request.headers.origin;
   if (!origin) return false;
@@ -111,6 +154,10 @@ export function isSameOrigin(request) {
   }
 }
 
+/**
+ * @param {ForwardedRequest} request
+ * @returns {string}
+ */
 export function clientIp(request) {
   const platformIp = platformClientIp(request);
   if (platformIp) return platformIp;
@@ -136,6 +183,9 @@ const DEFAULT_COUNTRY_HEADER = "CF-IPCountry";
  * from a trusted reverse proxy (the platform's client IP header, or
  * `DMS_TRUSTED_PROXY_HOPS` above `0`): otherwise any caller could have set
  * it, so nothing is relayed.
+ *
+ * @param {ForwardedRequest} request
+ * @returns {Record<string, string>}
  */
 export function clientCountryHeader(request) {
   const name = headerName(
@@ -143,9 +193,7 @@ export function clientCountryHeader(request) {
   );
   if (!name || !isProxyTrusted(request)) return {};
   const value = request.headers?.[name];
-  return typeof value === "string" && value.trim()
-    ? { [name]: value.trim() }
-    : {};
+  return isString(value) && value.trim() ? { [name]: value.trim() } : {};
 }
 
 /**

package/templates/vue/server/auth/establish-endpoints.mjs

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { isObjectLike, isString } from "../type-guards.mjs";
 
 /**
  * Absolute backend API paths only: no scheme, no authority, no query string,
@@ -17,6 +18,7 @@ const DECLARED_ENDPOINTS_FILE = new URL(
   import.meta.url,
 );
 
+/** @type {unknown[] | undefined} */
 let declaredEndpoints;
 
 /**
@@ -28,13 +30,15 @@ let declaredEndpoints;
  * 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
+ * @param {URL | string} [file] Generated file to read
+ * @returns {unknown[]} The declared paths, unfiltered
  */
 export function readDeclaredEstablishEndpoints(file = DECLARED_ENDPOINTS_FILE) {
   try {
+    /** @type {unknown} */
     const parsed = JSON.parse(readFileSync(file, "utf8"));
-    return Array.isArray(parsed?.endpoints) ? parsed.endpoints : [];
+    const endpoints = isObjectLike(parsed) ? parsed.endpoints : undefined;
+    return Array.isArray(endpoints) ? endpoints : [];
   } catch {
     return [];
   }
@@ -54,8 +58,8 @@ export function readDeclaredEstablishEndpoints(file = DECLARED_ENDPOINTS_FILE) {
  * (`DMS_AUTH_ESTABLISH_ENDPOINTS`). The module that owns sign-in reads them as
  * `event.app.authEstablishEndpoints`.
  *
- * @param declaration Comma-separated absolute backend paths from the environment
- * @param declared Paths declared by the backend's frontend modules
+ * @param {string} [declaration] Comma-separated absolute backend paths from the environment
+ * @param {unknown[]} [declared] Paths declared by the backend's frontend modules
  * @returns The well-formed backend API paths, without duplicates
  */
 export function allowedEstablishEndpoints(
@@ -67,8 +71,8 @@ export function allowedEstablishEndpoints(
     .map((entry) => entry.trim());
   return [
     ...new Set(
-      [...declared, ...fromEnvironment].filter(
-        (entry) => typeof entry === "string" && BACKEND_API_PATH.test(entry),
+      [...declared, ...fromEnvironment].flatMap((entry) =>
+        isString(entry) && BACKEND_API_PATH.test(entry) ? [entry] : [],
       ),
     ),
   ];

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

@@ -9,6 +9,21 @@ export const SESSION_COOKIE = "dms_session";
 const REQUEST_SESSION = Symbol("dms-request-session");
 const MAX_AGE = 60 * 60 * 24 * 30;
 
+/**
+ * The session a module writes: the `DmsSession` of `#dms/server`.
+ *
+ * @typedef {import("../../server-module.ts").DmsSession} Session
+ */
+
+/**
+ * A request, and the session `setRequestSession` set on it for the rest of the
+ * request.
+ *
+ * @typedef {import("node:http").IncomingMessage & {
+ *   [REQUEST_SESSION]?: Session | undefined
+ * }} SessionRequest
+ */
+
 /**
  * A suffix that keeps this instance's cookies apart from another's on the same
  * host. Browsers scope cookies by hostname, not port: without it, two DMS
@@ -31,7 +46,11 @@ function cookieScope() {
   return createHash("sha256").update(canonical).digest("hex").slice(0, 12);
 }
 
-/** The name `name` takes in this instance's cookie jar. */
+/**
+ * The name `name` takes in this instance's cookie jar.
+ *
+ * @param {string} name
+ */
 export function scopedCookieName(name) {
   return `${name}_${cookieScope()}`;
 }
@@ -46,6 +65,10 @@ function key() {
   return createHash("sha256").update(secret).digest();
 }
 
+/**
+ * @param {unknown} value A session, or the value of a module's sealed cookie
+ * @returns {string}
+ */
 function encode(value) {
   const iv = randomBytes(12);
   const cipher = createCipheriv("aes-256-gcm", key(), iv);
@@ -58,6 +81,11 @@ function encode(value) {
   );
 }
 
+/**
+ * @param {string} value The cookie's value
+ * @returns {any} What was sealed, as the JSON it was written from, `undefined`
+ *   when it does not open
+ */
 function decode(value) {
   try {
     const payload = Buffer.from(value, "base64url");
@@ -68,13 +96,21 @@ function decode(value) {
     );
     decipher.setAuthTag(payload.subarray(12, 28));
     return JSON.parse(
-      Buffer.concat([decipher.update(payload.subarray(28)), decipher.final()]),
+      Buffer.concat([
+        decipher.update(payload.subarray(28)),
+        decipher.final(),
+      ]).toString(),
     );
   } catch {
     return undefined;
   }
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {string} name
+ * @returns {string | undefined}
+ */
 function cookieValue(request, name) {
   const scoped = scopedCookieName(name);
   const cookies = request.headers.cookie?.split(";") ?? [];
@@ -86,6 +122,9 @@ function cookieValue(request, name) {
 /**
  * Cookie attributes. Without a `maxAge` the cookie lasts as long as the
  * browser session: it is gone once the browser is closed.
+ *
+ * @param {number | undefined} maxAge
+ * @param {string} [path]
  */
 function attributes(maxAge, path = "/") {
   const secure = process.env.DMS_COOKIE_SECURE !== "false" ? "; Secure" : "";
@@ -93,32 +132,56 @@ function attributes(maxAge, path = "/") {
   return `Path=${path}; HttpOnly; SameSite=Lax${lifetime}${secure}`;
 }
 
-/** A session outlives the browser only when it is written `persistent: true`. */
+/**
+ * A session outlives the browser only when it is written `persistent: true`.
+ *
+ * @param {Session} session
+ */
 function lifetime(session) {
   return session.persistent === true ? MAX_AGE : undefined;
 }
 
+/**
+ * @param {import("node:http").ServerResponse} response
+ * @param {string} name
+ * @param {string} value
+ * @param {string} cookieAttributes
+ */
 function appendCookie(response, name, value, cookieAttributes) {
   const cookie = `${scopedCookieName(name)}=${value}; ${cookieAttributes}`;
   const current = response.getHeader("set-cookie");
   response.setHeader(
     "set-cookie",
     current
-      ? [cookie, ...(Array.isArray(current) ? current : [current])]
+      ? [cookie, ...(Array.isArray(current) ? current : [String(current)])]
       : cookie,
   );
 }
 
+/**
+ * @param {SessionRequest} request
+ * @returns {Session | undefined} The session set for the request, else the one
+ *   the cookie seals, `undefined` when there is none
+ */
 export function readSession(request) {
   if (REQUEST_SESSION in request) return request[REQUEST_SESSION];
   const value = cookieValue(request, SESSION_COOKIE);
+  // oxlint-disable-next-line typescript/no-unsafe-return -- `decode` returns the JSON this server sealed under `SESSION_COOKIE`, untyped because `JSON.parse` is; the AES-GCM tag rejects any cookie it did not write.
   return value ? decode(value) : undefined;
 }
 
+/**
+ * @param {SessionRequest} request
+ * @param {Session | undefined} session
+ */
 export function setRequestSession(request, session) {
   request[REQUEST_SESSION] = session;
 }
 
+/**
+ * @param {import("node:http").ServerResponse} response
+ * @param {Session} session
+ */
 export function writeSession(response, session) {
   appendCookie(
     response,
@@ -128,19 +191,38 @@ export function writeSession(response, session) {
   );
 }
 
+/** @param {import("node:http").ServerResponse} response */
 export function clearSession(response) {
   appendCookie(response, SESSION_COOKIE, "", attributes(0));
 }
 
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {string} name
+ * @returns {unknown} What was sealed, as the JSON it was written from,
+ *   `undefined` when there is none or it does not open
+ */
 export function readSealedCookie(request, name) {
   const value = cookieValue(request, name);
   return value ? decode(value) : undefined;
 }
 
+/**
+ * @param {import("node:http").ServerResponse} response
+ * @param {string} name
+ * @param {unknown} value
+ * @param {number | undefined} maxAge
+ * @param {string} [path]
+ */
 export function writeSealedCookie(response, name, value, maxAge, path = "/") {
   appendCookie(response, name, encode(value), attributes(maxAge, path));
 }
 
+/**
+ * @param {import("node:http").ServerResponse} response
+ * @param {string} name
+ * @param {string} [path]
+ */
 export function clearSealedCookie(response, name, path = "/") {
   appendCookie(response, name, "", attributes(0, path));
 }

package/templates/vue/server/auth-declarations.mjs

@@ -0,0 +1,46 @@
+import { authRejection } from "./auth-hooks.mjs";
+import { compilePathPattern } from "./path-patterns.mjs";
+
+/**
+ * @import { AuthProvider, DeclaredModule } from "./module-route-types.mjs"
+ */
+
+/**
+ * The auth hooks: those of the highest-priority module that registers them.
+ * A module registering them twice, or after another one, is reported.
+ *
+ * @param {DeclaredModule[]} modules
+ * @param {(message: string) => void} warn
+ */
+export function resolveAuth(modules, warn) {
+  /** @type {AuthProvider | undefined} */
+  let provider;
+  for (const module of modules) {
+    for (const auth of module.declared.auth) {
+      const reason = authRejection(auth);
+      if (reason) {
+        warn(
+          `Frontend module ${module.id} registers auth hooks, which are ignored: ${reason}.`,
+        );
+        continue;
+      }
+      if (provider) {
+        warn(
+          `Frontend module ${module.id} registers auth hooks, which are ignored: ${provider.id} (priority ${provider.priority ?? 0}) provides them.`,
+        );
+        continue;
+      }
+      provider = {
+        id: module.id,
+        priority: module.priority ?? 0,
+        signInPath: auth.signInPath,
+        signInExempt: auth.signInExempt?.flatMap(
+          (pattern) => compilePathPattern(pattern) ?? [],
+        ),
+        refreshSession: auth.refreshSession?.bind(auth),
+        publicSession: auth.publicSession?.bind(auth),
+      };
+    }
+  }
+  return provider;
+}

package/templates/vue/server/auth-hooks.mjs

@@ -1,6 +1,7 @@
 import { readSession, setRequestSession } from "./auth/session.mjs";
 import { createServerEvent } from "./module-event.mjs";
-import { compilePathPattern } from "./path-patterns.mjs";
+import { compilePathPattern, PATH_PATTERN_FORMS } from "./path-patterns.mjs";
+import { isFunction, isRecord, isString } from "./type-guards.mjs";
 
 const DEFAULT_SIGN_IN_PATH = "/auth";
 const DEFAULT_ONBOARDING_PATH = "/onboarding";
@@ -12,16 +13,58 @@ const HOOK_ROUTE = Object.freeze({ bodyLimit: 0 });
  * sign-in page and everything below it, whole segments only (`/auth` exempts
  * `/auth/callback`, never `/authors`), and the onboarding page. Derived from
  * the sign-in path in use, or a custom one would redirect to itself.
+ *
+ * @param {string} signInPath
  */
 function defaultExempt(signInPath) {
   const signIn = signInPath === "/" ? "/" : `${signInPath}/**`;
-  return [signIn, DEFAULT_ONBOARDING_PATH].map(compilePathPattern);
+  return [signIn, DEFAULT_ONBOARDING_PATH].flatMap(
+    (pattern) => compilePathPattern(pattern) ?? [],
+  );
+}
+
+const AUTH_HOOKS = ["refreshSession", "publicSession"];
+
+/**
+ * Why an auth hooks registration is ignored, or `undefined`.
+ *
+ * @param {unknown} auth
+ */
+export function authRejection(auth) {
+  if (!isRecord(auth)) return "it is not an object";
+  for (const hook of AUTH_HOOKS)
+    if (auth[hook] !== undefined && !isFunction(auth[hook]))
+      return `${hook} is not a function`;
+  if (
+    auth.signInPath !== undefined &&
+    (!isString(auth.signInPath) ||
+      !compilePathPattern(auth.signInPath) ||
+      auth.signInPath.includes("*"))
+  )
+    return "signInPath is not a page path";
+  return exemptionRejection(auth.signInExempt);
+}
+
+/** @param {unknown} signInExempt */
+function exemptionRejection(signInExempt) {
+  if (signInExempt === undefined) return undefined;
+  if (!Array.isArray(signInExempt))
+    return `signInExempt is not a list of ${PATH_PATTERN_FORMS} patterns`;
+  for (const pattern of signInExempt)
+    if (!compilePathPattern(pattern))
+      return isString(pattern)
+        ? `signInExempt holds "${pattern}", which is not ${PATH_PATTERN_FORMS}`
+        : "signInExempt holds an entry that is not a string";
+  return undefined;
 }
 
 /**
  * The page props `user` and `session` of `session`, from the provider's
  * `publicSession`. The server adds the `updatedAt` stamp it wrote itself,
  * which the browser compares to drop a page restored from its cache.
+ *
+ * @param {NonNullable<import("./module-route-types.mjs").AuthProvider["publicSession"]>} publicSession
+ * @param {import("./module-event.mjs").Session | undefined} session
  */
 function hookView(publicSession, session) {
   if (!session) return {};
@@ -40,9 +83,9 @@ function hookView(publicSession, session) {
  * `dms.server.ts`. Without one, a page carries no session and a refused session
  * is not renewed.
  *
- * @param provider The resolved auth hooks, `undefined` when no module
+ * @param {import("./module-route-types.mjs").AuthProvider | undefined} provider The resolved auth hooks, `undefined` when no module
  *   registers any
- * @param context `(id) => ({ module, app })`, a module's event context
+ * @param {(id: string) => import("./module-server.mjs").ModuleContext} context `(id) => ({ module, app })`, a module's event context
  * @returns `{ provider, signInPath, isSignInExempt, signInLocation, view,
  *   refresh }`
  */
@@ -54,16 +97,21 @@ export function serverAuth(provider, context) {
   return {
     provider: provider?.id,
     signInPath,
-    isSignInExempt: (pathname) =>
+    isSignInExempt: (/** @type {string} */ pathname) =>
       exempt.some((pattern) => pattern.test(pathname)),
-    signInLocation: (requestUrl) =>
+    signInLocation: (/** @type {string} */ requestUrl) =>
       `${signInPath}?redirect=${encodeURIComponent(requestUrl)}`,
     view: publicSession
-      ? (session) => hookView(publicSession, session)
+      ? (
+          /** @type {import("./module-event.mjs").Session | undefined} */ session,
+        ) => hookView(publicSession, session)
       : () => ({}),
     /**
      * Renews the request's session after the backend refused it. Returns the
      * new session, which the rest of the request runs with, or `undefined`.
+     *
+     * @param {import("./request-target.mjs").ServerRequest} request
+     * @param {import("node:http").ServerResponse} response
      */
     async refresh(request, response) {
       if (!refreshSession) return undefined;

package/templates/vue/server/backend-proxies.mjs

@@ -1,4 +1,36 @@
-import { compilePathPattern } from "./path-patterns.mjs";
+import { compilePathPattern, PATH_PATTERN_FORMS } from "./path-patterns.mjs";
+import { isNonNullObject, isString } from "./type-guards.mjs";
+
+/** @typedef {import("../server-module.ts").DmsBackendProxyOptions} ProxyOptions */
+/**
+ * A backend prefix the server proxies, compiled from a pattern `proxyRejection`
+ * accepted.
+ *
+ * @typedef {object} BackendProxy
+ * @property {import("./path-patterns.mjs").CompiledPathPattern} pattern
+ * @property {string} path The pattern as declared
+ * @property {string} owner Who declared it
+ * @property {NonNullable<ProxyOptions["auth"]>} auth
+ * @property {number} [maxBodyBytes]
+ */
+/**
+ * What `registerBackendProxy` declared, per call.
+ *
+ * @typedef {object} ProxyDeclaration
+ * @property {string} id The declaring frontend module
+ * @property {string} pattern
+ * @property {ProxyOptions} [options]
+ */
+/**
+ * What a backend module declared in the manifest, or an operator in
+ * `DMS_BACKEND_PROXIES`.
+ *
+ * @typedef {object} ManifestProxy
+ * @property {string} [module]
+ * @property {string} [path]
+ * @property {ProxyOptions["auth"]} [auth]
+ * @property {number} [maxBodyBytes]
+ */
 
 /** How the proxy authenticates a request to the backend. */
 export const PROXY_AUTH_MODES = Object.freeze(["session", "none"]);
@@ -6,8 +38,10 @@ const DEFAULT_AUTH = "session";
 /** The renderer's own paths, never a backend's. */
 const RENDERER_PREFIXES = ["/api/_dms", "/@", "/assets", "/node_modules"];
 
+/** @param {string} pattern */
 function literalPrefix(pattern) {
   const segments = pattern === "/" ? [] : pattern.slice(1).split("/");
+  /** @type {string[]} */
   const literal = [];
   for (const segment of segments) {
     if (segment === "*" || segment === "**") break;
@@ -16,10 +50,16 @@ function literalPrefix(pattern) {
   return `/${literal.join("/")}`;
 }
 
-/** Why a proxy declaration is ignored, or `undefined`. */
+/**
+ * Why a proxy declaration is ignored, or `undefined`.
+ *
+ * @param {string | undefined} pattern
+ * @param {ProxyOptions | undefined} options
+ */
 export function proxyRejection(pattern, options) {
   const compiled = compilePathPattern(pattern);
-  if (!compiled) return "the pattern is not /x, /x/* or /x/**";
+  if (!compiled || !isString(pattern))
+    return `the pattern is not ${PATH_PATTERN_FORMS}`;
   const prefix = literalPrefix(pattern);
   if (prefix === "/")
     return "its first segment is not literal: it would take every page";
@@ -29,7 +69,7 @@ export function proxyRejection(pattern, options) {
     )
   )
     return `${RENDERER_PREFIXES.join(", ")} are the renderer's own paths`;
-  if (options !== undefined && (typeof options !== "object" || !options))
+  if (options !== undefined && !isNonNullObject(options))
     return "its options are not an object";
   if (options?.auth !== undefined && !PROXY_AUTH_MODES.includes(options.auth))
     return `auth is not one of ${PROXY_AUTH_MODES.map((mode) => `"${mode}"`).join(", ")}`;
@@ -41,10 +81,16 @@ export function proxyRejection(pattern, options) {
   return undefined;
 }
 
-function compileProxy(pattern, options, owner) {
+/**
+ * @param {import("./path-patterns.mjs").CompiledPathPattern} compiled A pattern `proxyRejection` accepted
+ * @param {ProxyOptions | undefined} options
+ * @param {string} owner Who declared it
+ * @returns {BackendProxy}
+ */
+function compileProxy(compiled, options, owner) {
   return {
-    pattern: compilePathPattern(pattern),
-    path: pattern,
+    pattern: compiled,
+    path: compiled.pattern,
     owner,
     auth: options?.auth ?? DEFAULT_AUTH,
     maxBodyBytes: options?.maxBodyBytes,
@@ -60,26 +106,35 @@ function compileProxy(pattern, options, owner) {
  * (`backendProxies`, next to its `publicEndpoints`). A path no prefix covers is
  * never sent to the backend.
  *
- * @param declared `{ id, pattern, options }` per `registerBackendProxy` call,
+ * @param {readonly ProxyDeclaration[]} declared `{ id, pattern, options }` per `registerBackendProxy` call,
  *   from the highest-priority module down
- * @param manifest `{ module, path, auth?, maxBodyBytes? }` per backend
+ * @param {readonly (ManifestProxy | null | undefined)[]} manifest `{ module, path, auth?, maxBodyBytes? }` per backend
  *   module declaration
- * @param warn Reports a declaration problem
- * @returns The proxies, the most specific pattern first: a request reaches
+ * @param {(message: string) => void} warn Reports a declaration problem
+ * @returns {BackendProxy[]} The proxies, the most specific pattern first: a request reaches
  *   the first that matches
  */
 export function resolveBackendProxies(declared, manifest, warn) {
+  /** @type {Map<string | undefined, BackendProxy>} */
   const kept = new Map();
+  /**
+   * @param {string | undefined} pattern
+   * @param {ProxyOptions | undefined} options
+   * @param {string} owner
+   */
   const add = (pattern, options, owner) => {
-    const reason = proxyRejection(pattern, options);
+    const compiled = compilePathPattern(pattern);
     const current = kept.get(pattern);
-    if (reason || current) {
+    const reason =
+      proxyRejection(pattern, options) ??
+      (current && `${current.owner} declares it`);
+    if (!compiled || reason) {
       warn(
-        `${owner} declares the backend proxy "${pattern}", which is ignored: ${reason ?? `${current.owner} declares it`}.`,
+        `${owner} declares the backend proxy "${pattern}", which is ignored: ${reason}.`,
       );
       return;
     }
-    kept.set(pattern, compileProxy(pattern, options, owner));
+    kept.set(pattern, compileProxy(compiled, options, owner));
   };
   for (const { id, pattern, options } of declared)
     add(pattern, options, `Frontend module ${id}`);
@@ -94,7 +149,12 @@ export function resolveBackendProxies(declared, manifest, warn) {
   );
 }
 
-/** The backend proxy a path reaches, or `undefined`. */
+/**
+ * The backend proxy a path reaches, or `undefined`.
+ *
+ * @param {readonly BackendProxy[]} proxies
+ * @param {string} pathname
+ */
 export function matchBackendProxy(proxies, pathname) {
   return proxies.find((proxy) => proxy.pattern.test(pathname));
 }
@@ -103,8 +163,8 @@ export function matchBackendProxy(proxies, pathname) {
  * The lines the server prints at startup: each backend prefix, who declared
  * it and how it authenticates, then who owns the rest.
  *
- * @param proxies What `resolveBackendProxies` returned
- * @param routeCount The number of module routes
+ * @param {readonly BackendProxy[]} proxies What `resolveBackendProxies` returned
+ * @param {number} routeCount The number of module routes
  */
 export function routingReport(proxies, routeCount) {
   const width = Math.max(0, ...proxies.map((proxy) => proxy.path.length));