@antelopejs/dms-frontend 0.9.3 → 0.10.0

package/templates/vue/frontend-runtime/state.ts

@@ -1,4 +1,3 @@
-import { ofetch } from "ofetch";
 import {
   type App,
   effectScope,
@@ -19,6 +18,7 @@ import {
 import {
   type DmsAppContext,
   type DmsRoute,
+  type DmsServerFetch,
   type DmsRuntimeConfig,
 } from "./types";
 
@@ -65,7 +65,7 @@ export function forgetBrowserRuntime(runtime: DmsFrontendRuntime): void {
 
 /** Creates mutable runtime state owned by one Vue application. */
 export function createDmsFrontendRuntime(
-  serverFetch?: typeof ofetch,
+  serverFetch?: DmsServerFetch,
   hydratedAsyncData?: Record<string, unknown>,
   isServer = false,
   requestCookies?: string,

package/templates/vue/frontend-runtime/types.ts

@@ -1,5 +1,5 @@
 import { type InertiaLinkProps } from "@inertiajs/vue3";
-import { type FetchOptions, ofetch } from "ofetch";
+import { type FetchOptions } from "ofetch";
 import {
   type App,
   type ComputedRef,
@@ -246,6 +246,12 @@ export interface UseAsyncDataOptions<T> {
    */
   refreshInterval?: MaybeRefOrGetter<number | null | undefined>;
 }
+/** What the runtime calls to read the backend: `ofetch`, or a stand-in for it. */
+export type DmsServerFetch = (
+  request: string,
+  options?: FetchOptions,
+) => Promise<unknown>;
+
 /**
  * `useDmsFetch`'s options: ofetch's request options, of which the method, the
  * query, the params and the body may be refs or getters, and the async data
@@ -271,7 +277,7 @@ export interface UseFetchOptions<T>
     context: DmsFetchTransformContext,
   ) => T | Promise<T>;
   /** Replaces the fetch function; it receives the run's signal. */
-  $fetch?: typeof ofetch;
+  $fetch?: DmsServerFetch;
 }
 export interface DmsErrorData {
   statusCode?: number;

package/templates/vue/head-order.mjs

@@ -1,6 +1,10 @@
 const SCRIPT = /<script[^>]*\stype="module"[^>]*><\/script>/;
 const STYLESHEET = /[ \t]*<link rel="stylesheet"[^>]*>\n?/;
 
+/**
+ * @param {string} html
+ * @returns {string}
+ */
 function deprioritize(html) {
   return html.replace(SCRIPT, (tag) =>
     tag.includes("fetchpriority")
@@ -24,6 +28,9 @@ function deprioritize(html) {
  * HTTP/1.1 the generated server speaks. Kept beside vite.config.ts rather than
  * inside it so the transform can be exercised on its own, the way
  * client-manifest.mjs is.
+ *
+ * @param {string} html
+ * @returns {string}
  */
 export function orderHeadForFirstPaint(html) {
   const prioritized = deprioritize(html);

package/templates/vue/icon-scan.mjs

@@ -19,6 +19,10 @@ const SOURCE_SCRIPT_GLOB = "app/**/*.ts";
  * fetched from the Iconify API at run time. Every frontend source root lives
  * under the workspace (`frontend-modules/`, enforced when the registry is
  * written), so a relative glob reaches it. Globs are POSIX on every platform.
+ *
+ * @param {string} viteRoot
+ * @param {readonly string[]} sourceRoots
+ * @returns {string[]}
  */
 export function iconScanGlobs(viteRoot, sourceRoots) {
   const sourceGlobs = sourceRoots.map((root) =>

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

@@ -1,4 +1,5 @@
 import { REDIRECT_STATUSES } from "../proxy-redirects.mjs";
+import { isString } from "../type-guards.mjs";
 import { clientCountryHeader, clientIp, clientIpHeader } from "./client-ip.mjs";
 
 /**
@@ -14,6 +15,10 @@ export const CLIENT_HEADERS = [
 ];
 
 export class UpstreamError extends Error {
+  /**
+   * @param {number} status
+   * @param {string} message
+   */
   constructor(status, message) {
     super(message);
     this.status = status;
@@ -27,9 +32,15 @@ const PUBLIC_AUTH_MESSAGE = /^error\.[a-z0-9_.-]{1,100}$/;
  */
 export const GENERIC_ERROR_MESSAGE = "error.500.description";
 
+/**
+ * @param {unknown} data A backend answer: any JSON value, or the text of one
+ *   that is not JSON
+ * @returns {string | undefined}
+ */
 export function publicBackendMessage(data) {
-  const message = typeof data === "string" ? data : data?.message;
-  return typeof message === "string" && PUBLIC_AUTH_MESSAGE.test(message)
+  /** @type {unknown} */
+  const message = isString(data) ? data : data?.message;
+  return isString(message) && PUBLIC_AUTH_MESSAGE.test(message)
     ? message
     : undefined;
 }
@@ -37,8 +48,10 @@ export function publicBackendMessage(data) {
 /**
  * The headers of a client request the server relays to the backend.
  *
- * @param request The client request
- * @param names Lowercase names of the request headers to copy when present
+ * @param {import("./client-ip.mjs").ForwardedRequest} request The client
+ *   request
+ * @param {readonly string[]} names Lowercase names of the request headers to
+ *   copy when present
  * @returns The client country header, then the copied headers
  */
 export function relayedHeaders(request, names) {
@@ -58,8 +71,22 @@ export function relayedHeaders(request, names) {
  * `options.headers` adds request headers; the client's address and the
  * relayed client headers are set after them, so no caller replaces those.
  * A redirect is not followed: it is no JSON answer, so it fails with a 502.
+ *
+ * @param {string} path
+ * @param {import("./client-ip.mjs").ForwardedRequest} request The client
+ *   request
+ * @param {{
+ *   method?: string,
+ *   body?: unknown,
+ *   token?: string,
+ *   relay?: boolean,
+ *   headers?: Record<string, string>
+ * }} [options]
+ * @returns {Promise<unknown>} The answer's JSON, `{}` for a successful one that
+ *   is not JSON
  */
 export async function backend(path, request, options = {}) {
+  /** @type {Record<string, string | string[]>} */
   const headers = Object.fromEntries(
     Object.entries(options.headers ?? {}).map(([name, value]) => [
       name.toLowerCase(),
@@ -87,6 +114,7 @@ export async function backend(path, request, options = {}) {
     throw new UpstreamError(502, GENERIC_ERROR_MESSAGE);
   }
   const text = await response.text();
+  /** @type {unknown} */
   let data;
   try {
     data = JSON.parse(text);
@@ -105,12 +133,21 @@ export async function backend(path, request, options = {}) {
 }
 
 export class RequestBodyError extends Error {
+  /**
+   * @param {number} status
+   * @param {string} message
+   */
   constructor(status, message) {
     super(message);
     this.status = status;
   }
 }
 
+/**
+ * @param {import("node:http").ServerResponse} response
+ * @param {number} status
+ * @param {unknown} value Anything `JSON.stringify` writes
+ */
 export function json(response, status, value) {
   response.writeHead(status, { "content-type": "application/json" });
   response.end(JSON.stringify(value));

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(
@@ -68,7 +72,7 @@ export function allowedEstablishEndpoints(
   return [
     ...new Set(
       [...declared, ...fromEnvironment].filter(
-        (entry) => typeof entry === "string" && BACKEND_API_PATH.test(entry),
+        (entry) => isString(entry) && BACKEND_API_PATH.test(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");
@@ -75,6 +103,11 @@ function decode(value) {
   }
 }
 
+/**
+ * @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 +119,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,11 +129,21 @@ 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");
@@ -109,16 +155,30 @@ function appendCookie(response, name, value, cookieAttributes) {
   );
 }
 
+/**
+ * @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 +188,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-hooks.mjs

@@ -12,6 +12,8 @@ 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}/**`;
@@ -22,6 +24,9 @@ function defaultExempt(signInPath) {
  * 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 +45,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 +59,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("node:http").IncomingMessage} request
+     * @param {import("node:http").ServerResponse} response
      */
     async refresh(request, response) {
       if (!refreshSession) return undefined;