@antelopejs/dms-frontend 0.9.2 → 0.10.0

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;

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

@@ -1,4 +1,36 @@
 import { compilePathPattern } from "./path-patterns.mjs";
+import { isNonNullObject } 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,7 +50,12 @@ function literalPrefix(pattern) {
   return `/${literal.join("/")}`;
 }
 
-/** Why a proxy declaration is ignored, or `undefined`. */
+/**
+ * Why a proxy declaration is ignored, or `undefined`.
+ *
+ * @param {string} 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/**";
@@ -29,7 +68,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,6 +80,12 @@ export function proxyRejection(pattern, options) {
   return undefined;
 }
 
+/**
+ * @param {string} pattern A pattern `proxyRejection` accepted
+ * @param {ProxyOptions | undefined} options
+ * @param {string} owner Who declared it
+ * @returns {BackendProxy}
+ */
 function compileProxy(pattern, options, owner) {
   return {
     pattern: compilePathPattern(pattern),
@@ -60,16 +105,22 @@ 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 current = kept.get(pattern);
@@ -94,7 +145,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 +159,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));

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

@@ -0,0 +1,61 @@
+import { CLIENT_HEADERS, relayedHeaders } from "./auth/backend.mjs";
+import { forwardedHeaders } from "./auth/client-ip.mjs";
+import { readSession } from "./auth/session.mjs";
+import { backendResponseError } from "./backend-response.mjs";
+import { serverReads } from "./in-place-render.mjs";
+
+/**
+ * The headers of a backend request: the relayed client headers, the client's
+ * Origin and Referer as received, the `X-Forwarded-*` headers (set last, so no
+ * caller writes them), and the session's access token unless the request goes
+ * anonymously.
+ *
+ * @param {import("node:http").IncomingMessage} request
+ * @param {{ anonymous: boolean, headers: readonly string[] }} [access]
+ * @returns {Record<string, string>}
+ */
+export function backendHeaders(
+  request,
+  access = { anonymous: false, headers: [] },
+) {
+  /** @type {Record<string, string>} */
+  const headers = {
+    ...relayedHeaders(request, [
+      "accept",
+      "content-type",
+      "if-match",
+      "origin",
+      "referer",
+      ...CLIENT_HEADERS,
+      ...access.headers,
+    ]),
+    ...forwardedHeaders(request),
+  };
+  const session = access.anonymous ? undefined : readSession(request);
+  if (session?.accessToken)
+    headers.authorization = `Bearer ${session.accessToken}`;
+  return headers;
+}
+
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {import("./in-place-render.mjs").ServerReads}
+ */
+export function serverComponentFetch(request) {
+  return serverReads(() => backendHeaders(request));
+}
+
+/**
+ * @param {string} path
+ * @param {import("node:http").IncomingMessage} request
+ * @returns {Promise<unknown>}
+ */
+export async function backendJson(path, request) {
+  const response = await fetch(new URL(path, process.env.DMS_API_BASE_URL), {
+    headers: backendHeaders(request),
+  });
+  if (!response.ok) {
+    throw await backendResponseError(response);
+  }
+  return response.json();
+}

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

@@ -1,5 +1,6 @@
 import { GENERIC_ERROR_MESSAGE } from "./auth/backend.mjs";
 import { isFrontendVisit, redirectFrontendVisit } from "./inertia.mjs";
+import { isString } from "./type-guards.mjs";
 
 /**
  * What a JSON caller gets when the backend fails: the generic i18n key of
@@ -18,6 +19,10 @@ const FORBIDDEN = 403;
 const FRONTEND_ORIGIN = "http://frontend.local";
 
 export class BackendResponseError extends Error {
+  /**
+   * @param {number} status
+   * @param {string | undefined} code The typed refusal code of the answer
+   */
   constructor(status, code) {
     super(`DMS backend returned ${status}`);
     this.status = status;
@@ -28,21 +33,28 @@ export class BackendResponseError extends Error {
 /**
  * The refusal code in a backend answer: the string or the `message` of its
  * JSON body, or the body itself when it is not JSON (a bare code).
+ *
+ * @param {Response} response
+ * @returns {Promise<string | undefined>}
  */
 async function refusalCode(response) {
   const text = (await response.text().catch(() => "")).trim();
   if (text.length > REFUSAL_CODE_MAX_LENGTH) return undefined;
+  /** @type {unknown} */
   let value = text;
   try {
+    /** @type {unknown} */
     const data = JSON.parse(text);
-    value = typeof data === "string" ? data : data?.message;
+    value = isString(data) ? data : data?.message;
   } catch {}
-  return typeof value === "string" && REFUSAL_CODE.test(value)
-    ? value
-    : undefined;
+  return isString(value) && REFUSAL_CODE.test(value) ? value : undefined;
 }
 
-/** The error for a failed backend response, with its typed code if any. */
+/**
+ * The error for a failed backend response, with its typed code if any.
+ *
+ * @param {Response} response
+ */
 export async function backendResponseError(response) {
   return new BackendResponseError(response.status, await refusalCode(response));
 }
@@ -54,7 +66,11 @@ export async function backendResponseError(response) {
  * `loadRenderer` resolves. Only a same-origin path other than the refused one
  * qualifies: a refused destination sent to itself again would loop.
  *
- * @returns Whether the visit was redirected
+ * @param {unknown} error What the request failed with
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {() => Promise<typeof import("../ssr-renderer.ts")>} loadRenderer
+ * @returns {Promise<boolean>} Whether the visit was redirected
  */
 export async function redirectAccessRefusal(
   error,
@@ -69,6 +85,7 @@ export async function redirectAccessRefusal(
     !error.code
   )
     return false;
+  /** @type {string | undefined} */
   let location;
   try {
     location = (await loadRenderer()).accessRedirect?.(error.code);

package/templates/vue/server/built-files.mjs

@@ -14,6 +14,9 @@ const PUBLIC_DOT_DIRECTORY = ".well-known";
  * source path of every module file), and a module's `public/` may hold dot
  * files too. `/.well-known/`, which RFC 8615 reserves for files meant to be
  * public, stays served.
+ *
+ * @param {string} relativePath
+ * @returns {boolean}
  */
 export function isPublicBuildPath(relativePath) {
   return relativePath
@@ -33,6 +36,10 @@ export function isPublicBuildPath(relativePath) {
  *
  * The prefix uses the native separator: `resolve` answers with backslashes on
  * Windows.
+ *
+ * @param {string} root
+ * @param {string} pathname
+ * @returns {string | undefined}
  */
 export function publicBuildFile(root, pathname) {
   let decoded;

package/templates/vue/server/cli-report.mjs

@@ -1,9 +1,16 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { stripVTControlCharacters } from "node:util";
+import { isNumber, isObjectLike, isRecord, isString } from "./type-guards.mjs";
 
 const WILDCARD_ADDRESSES = ["0.0.0.0", "::"];
 
+/**
+ * @param {import("node:child_process").Serializable} message
+ * @param {string} line
+ * @param {(line: string) => void} write
+ * @returns {Promise<void>}
+ */
 async function report(message, line, write) {
   if (!process.send) return write(line);
   await new Promise((sent) => process.send(message, () => sent()));
@@ -15,6 +22,10 @@ async function report(message, line, write) {
  * What the server tells whoever started it. Started by `ajs dms dev` or `ajs
  * dms start`, it reports over IPC and the CLI words what the user reads.
  * Started on its own, it prints the line itself.
+ *
+ * @param {string} address
+ * @param {number} port
+ * @returns {Promise<void>}
  */
 export async function reportReady(address, port) {
   const host = WILDCARD_ADDRESSES.includes(address)
@@ -33,6 +44,11 @@ export async function reportReady(address, port) {
  * The server cannot listen: a port taken by another process, an address this
  * host does not have. Reported instead of Node's unhandled-error dump, then
  * the server exits.
+ *
+ * @param {NodeJS.ErrnoException} error
+ * @param {string} host
+ * @param {number} port
+ * @returns {Promise<void>}
  */
 export async function reportListenError(error, host, port) {
   await report(
@@ -52,31 +68,46 @@ export async function reportListenError(error, host, port) {
 /** The `[PARSE_ERROR] ` Rolldown puts in front of what it says. */
 const RULE_PREFIX = /^\[[A-Z_]+\]\s*/;
 
-/** The first problem Rolldown reports when it cannot bundle a config. */
+/**
+ * The first problem Rolldown reports when it cannot bundle a config.
+ *
+ * @param {unknown} error What the startup threw
+ */
 function bundlerError(error) {
-  const first = error?.errors?.[0];
-  return first && typeof first === "object" ? first : undefined;
+  const errors = isObjectLike(error) ? error.errors : undefined;
+  const first = isObjectLike(errors) ? errors[0] : undefined;
+  return isRecord(first) ? first : undefined;
 }
 
 /**
  * Where a startup error points, when it says: Rolldown's location for a config
  * it could not bundle (the line is read back from the file, which Rolldown
  * only draws in a colored frame), Rollup's for a plugin that failed on a file.
+ *
+ * @param {unknown} error What the startup threw
  */
 function errorLocation(error) {
-  const source = bundlerError(error) ?? error;
-  const file = source?.loc?.file ?? source?.id;
-  if (typeof file !== "string") return undefined;
-  const { line, column } = source.loc ?? {};
+  const source =
+    bundlerError(error) ?? (isObjectLike(error) ? error : undefined);
+  const loc = isObjectLike(source?.loc) ? source.loc : undefined;
+  const file = loc?.file ?? source?.id;
+  if (!isString(file)) return undefined;
+  const line = isNumber(loc?.line) ? loc.line : undefined;
   return {
     file: resolve(file),
     line,
-    column,
+    column: isNumber(loc?.column) ? loc.column : undefined,
     lineText: line === undefined ? undefined : readLine(file, line),
   };
 }
 
-/** Line `line` (1-based) of `file`, `undefined` when it cannot be read. */
+/**
+ * Line `line` (1-based) of `file`, `undefined` when it cannot be read.
+ *
+ * @param {string} file
+ * @param {number} line
+ * @returns {string | undefined}
+ */
 function readLine(file, line) {
   try {
     return readFileSync(file, "utf8").split(/\r?\n/)[line - 1];
@@ -85,7 +116,11 @@ function readLine(file, line) {
   }
 }
 
-/** The first line of what went wrong, without Rolldown's rule and frame. */
+/**
+ * The first line of what went wrong, without Rolldown's rule and frame.
+ *
+ * @param {unknown} error What the startup threw
+ */
 function errorText(error) {
   const reported = bundlerError(error);
   const message = reported
@@ -101,6 +136,8 @@ function errorText(error) {
 /**
  * Vite could not start, so no page can be served: the error and where it
  * points instead of a stack trace, then the server exits.
+ *
+ * @param {unknown} error What the startup threw
  */
 export async function reportStartError(error) {
   const message = errorText(error);
@@ -109,7 +146,12 @@ export async function reportStartError(error) {
     ? `${location.file}${location.line ? `:${location.line}:${location.column ?? 0}` : ""}: `
     : "";
   await report(
-    { type: "dms:start-error", message, code: error?.code, location },
+    {
+      type: "dms:start-error",
+      message,
+      code: isObjectLike(error) ? error.code : undefined,
+      location,
+    },
     `DMS development server failed to start: ${where}${message}`,
     console.error,
   );