nexus-shared 3.1.0 → 4.0.0

package/dist/Services/ApiProxyRules.d.ts

@@ -0,0 +1,203 @@
+/** The most bytes a request body may have, unless the app says otherwise (`maxBodySize`): 100 MB. */
+export declare const DEFAULT_PROXY_BODY_LIMIT: number;
+/** How many redirects inside a module the proxy follows for one call, unless the app says otherwise (`maxRedirects`). */
+export declare const DEFAULT_PROXY_REDIRECTS = 3;
+/** The most of an error answer the proxy reads to see what it is. A bigger one is never passed on. */
+export declare const ERROR_BODY_LIMIT: number;
+/**
+ * The browser's request headers the backend may see: all of them except the ones above, and except any that the
+ * request's own `Connection` header names (those belong to this hop too).
+ */
+export declare function forwardRequestHeaders(incoming: Headers): Headers;
+/**
+ * An IP address as text, without the port some proxies add; `undefined` for anything else (a host name, "unknown", an
+ * obfuscated identifier, a zone such as `%eth0`). An IPv6 address is checked by the URL parser, which every runtime has,
+ * once its characters are known to be an address's: without that, text that closes the bracket itself and goes on
+ * (`::1]/,6.6.6.6`) parsed as an address followed by a path.
+ *
+ * @example
+ * readIpAddress(" 203.0.113.7:51000 ")   // "203.0.113.7"
+ * readIpAddress("[2001:db8::1]:443")      // "2001:db8::1"
+ * readIpAddress("unknown")                // undefined
+ * readIpAddress("::1]/,6.6.6.6")          // undefined
+ */
+export declare function readIpAddress(value: string | null | undefined): string | undefined;
+/**
+ * This server's own origin, for a module whose root is a path on the app (a pretend backend): the host and port of the
+ * request URL, over http. Next.js builds that URL from the host and port it listens on, never from the Host header, but
+ * takes its protocol from X-Forwarded-Proto, which anyone can send, so the protocol is not read from it. A server that
+ * listens on every address (`0.0.0.0`, `::`) is called on this machine's own, and the port is always the one Next.js
+ * wrote, even when the URL leaves it out as its protocol's default.
+ *
+ * Never the app's configured origin: an app may build that from a request's Host header, and then a client would choose
+ * which port on this machine the proxy calls, with the user's token.
+ *
+ * @example
+ * ownOrigin(new URL("https://localhost:20016/api/app/drive/File/List"))   // "http://localhost:20016"
+ * ownOrigin(new URL("http://0.0.0.0:3000/api/app/drive/File/List"))       // "http://127.0.0.1:3000"
+ */
+export declare function ownOrigin(requestUrl: URL): string;
+/**
+ * The client's address as the app received it: the **last** one in X-Forwarded-For, which is the one Next.js (from the
+ * connection) or the app's own reverse proxy in front of it wrote. The ones before it are what the client claims, and
+ * a client can claim anything. Behind two proxies of the app's own, or a CDN with a header of its own, the app passes
+ * `clientAddress` to the proxy instead. It reads anything with a `get`: a request's headers, or Next.js's `headers()`.
+ *
+ * @example
+ * // A browser sent "X-Forwarded-For: 6.6.6.6"; the app's nginx appended the address it really came from.
+ * lastForwardedAddress(new Headers({ "x-forwarded-for": "6.6.6.6, 203.0.113.7" }))   // "203.0.113.7"
+ */
+export declare function lastForwardedAddress(headers: {
+    get(name: string): string | null;
+}): string | undefined;
+/**
+ * Whether a browser sent this request from a page of another site, other than by following a link. Every current
+ * browser says where a request comes from in `Sec-Fetch-Site` and `Sec-Fetch-Mode`. The proxy turns the app's own
+ * session into the user's token, so a page on another site must not be able to call the backend through it (cross-site
+ * request forgery). A link followed from another site (an email, a chat) is a GET navigation and passes; a request
+ * without these headers (an older browser, a server, a tool) is no browser's cross-site call and passes too.
+ */
+export declare function isCrossSiteCall(headers: Headers, method: string): boolean;
+/** A path segment the proxy refuses: one that climbs (`.`, `..`, nothing but dots and spaces), or one holding a slash. */
+export declare function isUnsafeSegment(segment: string): boolean;
+/** Reads a body whole, up to `limit` bytes. `null` when it is longer: the rest is not read. */
+export declare function readBody(stream: ReadableStream<Uint8Array> | null, limit: number): Promise<Uint8Array<ArrayBuffer> | null>;
+/** The backend's response headers that come back to the browser, and the only ones unless an app names more. */
+export declare const DEFAULT_PROXY_RESPONSE_HEADERS: readonly string[];
+export interface ResponseHeaderRules {
+    /** Header names to pass besides the defaults (any case). Never one of those that name the backend. */
+    extra?: readonly string[];
+    /** Pass the backend's Set-Cookie headers. */
+    passCookies?: boolean;
+}
+/** The backend's response headers the browser may see: the allowlist and the app's own names, never one of the above. */
+export declare function filterResponseHeaders(answer: Headers, rules?: ResponseHeaderRules): Headers;
+export declare function isRedirect(status: number): boolean;
+/**
+ * Where a backend's redirect leads, when it stays inside the module: on the root's own origin, or on the root's own
+ * host moved from http to https (a backend's HTTPS redirection, which picks its own https port), and under the root's
+ * path, whose casing may differ ("/App/Api" and "/app/api"). Anything else - another host or port, a move from https
+ * to http, a path outside the root, a URL with a user name in it - is `undefined`, and the proxy refuses it: following
+ * it would carry the user's token somewhere the app never named.
+ *
+ * @example
+ * // The module's root is http://localhost:10040/App/Api, and the proxy asked for .../App/Api/Region/ActiveListing:
+ * redirectInsideModule("https://localhost:10041/App/Api/Region/ActiveListing", asked, root) // followed: the https upgrade
+ * redirectInsideModule("/App/Api/Region/ActiveListing/", asked, root)                       // followed: a trailing slash
+ * redirectInsideModule("https://sso.example.com/login?next=/App/Api", asked, root)          // undefined: another host
+ */
+export declare function redirectInsideModule(location: string, from: URL, root: URL): URL | undefined;
+/**
+ * The method of the request after a redirect, as the Fetch standard follows one: a 303 asks for a GET (a HEAD stays a
+ * HEAD), a 301 or 302 turns a POST into a GET, and a 307 or 308 keeps the method and the body.
+ */
+export declare function methodAfterRedirect(status: number, method: string): string;
+/** Headers that describe a request's body: they go with the body when a redirect turns the request into a GET. */
+export declare const BODY_HEADERS: readonly string[];
+/**
+ * Why an error answer cannot reach the browser as it came, or `undefined` when it can. An empty answer passes (there is
+ * nothing in it), and so does JSON - the backend's envelope, or problem details - unless it is a stack trace or repeats
+ * the user's token (a page that lists the request's headers). Anything else (an HTML page, text, XML) is the backend
+ * talking about itself.
+ */
+export declare function whyHidden(contentType: string, text: string, token?: string | null): string | undefined;
+/**
+ * A short, one-line piece of an error answer for the server's log: the user's token, styles, scripts and tags taken
+ * out, spaces collapsed.
+ */
+export declare function logSnippet(text: string, token?: string | null, length?: number): string;
+/** A URL for the server's log: its origin and path, never its query (it may hold what a user searched for, or a key). */
+export declare function logUrl(url: URL): string;
+/**
+ * The proxy's own refusals: each code is answered from one place in `ApiProxy.ts`, with its HTTP status and its kind
+ * as the Nexus backend numbers kinds (`EErrorCodes`, where a kind's category is its number divided by 20).
+ */
+export declare const PROXY_REFUSALS: {
+    /** A method other than GET, HEAD, POST, PUT, PATCH and DELETE. RequestInvalid. */
+    readonly METHOD_NOT_ALLOWED: {
+        readonly status: 405;
+        readonly errorCode: 29;
+    };
+    /** A call from a page of another site. AccessDenied. */
+    readonly CROSS_SITE_REFUSED: {
+        readonly status: 403;
+        readonly errorCode: 60;
+    };
+    /** A module the app does not have. RequestInvalid. */
+    readonly MODULE_NOT_FOUND: {
+        readonly status: 404;
+        readonly errorCode: 29;
+    };
+    /** A module the browser calls directly, not through the proxy. RequestInvalid. */
+    readonly MODULE_NOT_PROXIED: {
+        readonly status: 404;
+        readonly errorCode: 29;
+    };
+    /** A path that climbs out of its module. RequestInvalid. */
+    readonly INVALID_PATH: {
+        readonly status: 400;
+        readonly errorCode: 29;
+    };
+    /** A body over the limit. TooLong. */
+    readonly REQUEST_TOO_LARGE: {
+        readonly status: 413;
+        readonly errorCode: 22;
+    };
+    /** A body that could not be read (the client left while sending it). RequestInvalid. */
+    readonly REQUEST_UNREADABLE: {
+        readonly status: 400;
+        readonly errorCode: 29;
+    };
+    /** A module without a usable root URL on this server. SettingMissing. */
+    readonly MODULE_NOT_CONFIGURED: {
+        readonly status: 500;
+        readonly errorCode: 120;
+    };
+    /** A backend that cannot be reached: down, refused, or a certificate this server does not trust. ServiceUnavailable. */
+    readonly BACKEND_UNREACHABLE: {
+        readonly status: 502;
+        readonly errorCode: 160;
+    };
+    /** A backend that did not start answering in time. ServiceTimeout. */
+    readonly BACKEND_TIMEOUT: {
+        readonly status: 504;
+        readonly errorCode: 161;
+    };
+    /** A redirect out of the module, or one with no usable Location. ServiceAnswerInvalid. */
+    readonly BACKEND_REDIRECT_REFUSED: {
+        readonly status: 502;
+        readonly errorCode: 163;
+    };
+    /** More redirects inside the module than the limit. ServiceAnswerInvalid. */
+    readonly BACKEND_REDIRECT_LIMIT: {
+        readonly status: 502;
+        readonly errorCode: 163;
+    };
+    /** An error page that cannot be passed on, answered with the backend's own status. ServiceRefused. */
+    readonly BACKEND_ERROR_PAGE: {
+        readonly status: 502;
+        readonly errorCode: 162;
+    };
+};
+export type ApiProxyCode = keyof typeof PROXY_REFUSALS;
+/** A refusal of the proxy's own, for the app's `failure` builder. */
+export interface ApiProxyFailure {
+    /** The HTTP status. */
+    status: number;
+    /** What the user reads, in plain words: never a host, a port, a setting, or anything else about the backend. */
+    message: string;
+    /** The proxy's code for this refusal, for a developer and for a page to react to: "BACKEND_REDIRECT_REFUSED". */
+    messageCode: ApiProxyCode;
+    /** The kind, as the Nexus backend numbers kinds: 163 is an answer that cannot be passed on. */
+    errorCode: number;
+}
+/**
+ * A refusal as the Nexus backend answers one: `{ isSuccess: false, code, errorMessages: [{ message, messageCode,
+ * errorCode }] }`, with the one problem at the top level too, for readers of the older shape.
+ */
+export declare function nexusFailure(failure: ApiProxyFailure): Response;
+/**
+ * Every answer the proxy gives: never sniffed into another type, and kept out of every cache unless the backend said
+ * how to cache it - the answer was fetched with the user's token, so a shared cache must never keep it for another user.
+ */
+export declare function harden(response: Response): Response;

package/dist/Services/ApiProxyRules.js

@@ -0,0 +1,426 @@
+/*
+ * The rules the API proxy keeps so that the browser never learns where the backend is or what it runs: which request
+ * headers go on, which response headers come back, which redirects the proxy follows itself, and which error answers it
+ * replaces. Plain functions over the standard Headers, URL and streams, so they run in Node, the Edge runtime and the
+ * unit tests alike. `ApiProxy.ts` puts them together.
+ */
+/** The most bytes a request body may have, unless the app says otherwise (`maxBodySize`): 100 MB. */
+export const DEFAULT_PROXY_BODY_LIMIT = 100 * 1024 * 1024;
+/** How many redirects inside a module the proxy follows for one call, unless the app says otherwise (`maxRedirects`). */
+export const DEFAULT_PROXY_REDIRECTS = 3;
+/** The most of an error answer the proxy reads to see what it is. A bigger one is never passed on. */
+export const ERROR_BODY_LIMIT = 1024 * 1024;
+// ---------------------------------------------------------------------------------------------------------------------
+// Request headers
+/** Request headers that never reach the backend. */
+const REQUEST_HEADERS_DROPPED = new Set([
+    // This hop's own, and what `fetch` sets by itself. `expect` would make Node's fetch throw.
+    "host",
+    "connection",
+    "keep-alive",
+    "proxy-connection",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+    "expect",
+    "content-length",
+    "accept-encoding",
+    "proxy-authorization",
+    // The app's session stays with the app; the user's token goes instead.
+    "cookie",
+    // Where the request came from, as the browser tells it: anyone can send these, so the proxy writes its own.
+    "forwarded",
+    "via",
+    "x-real-ip",
+    "x-client-ip",
+    "true-client-ip",
+    "cf-connecting-ip",
+    "fastly-client-ip",
+    "x-cluster-client-ip",
+    "x-original-forwarded-for",
+    // Headers some servers obey to change the method or the path after the proxy has checked both.
+    "x-http-method-override",
+    "x-http-method",
+    "x-method-override",
+    "x-original-url",
+    "x-rewrite-url",
+    // Next.js's own.
+    "rsc",
+]);
+/** Prefixes of request headers that never reach the backend: every X-Forwarded-* (the proxy writes its own), and Next.js's. */
+const REQUEST_PREFIXES_DROPPED = ["x-forwarded-", "x-middleware-", "x-invoke-", "x-nextjs-", "next-"];
+/**
+ * The browser's request headers the backend may see: all of them except the ones above, and except any that the
+ * request's own `Connection` header names (those belong to this hop too).
+ */
+export function forwardRequestHeaders(incoming) {
+    const named = (incoming.get("connection") ?? "")
+        .split(",")
+        .map(name => name.trim().toLowerCase())
+        .filter(name => name !== "");
+    const headers = new Headers();
+    incoming.forEach((value, name) => {
+        const lower = name.toLowerCase();
+        if (REQUEST_HEADERS_DROPPED.has(lower) || named.includes(lower))
+            return;
+        if (REQUEST_PREFIXES_DROPPED.some(prefix => lower.startsWith(prefix)))
+            return;
+        headers.set(name, value);
+    });
+    return headers;
+}
+const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+/** The only characters an IPv6 address is written with: hex digits, colons, and the dots of an IPv4 address at its end. */
+const IPV6_CHARACTERS = /^[0-9a-f:.]+$/i;
+/**
+ * An IP address as text, without the port some proxies add; `undefined` for anything else (a host name, "unknown", an
+ * obfuscated identifier, a zone such as `%eth0`). An IPv6 address is checked by the URL parser, which every runtime has,
+ * once its characters are known to be an address's: without that, text that closes the bracket itself and goes on
+ * (`::1]/,6.6.6.6`) parsed as an address followed by a path.
+ *
+ * @example
+ * readIpAddress(" 203.0.113.7:51000 ")   // "203.0.113.7"
+ * readIpAddress("[2001:db8::1]:443")      // "2001:db8::1"
+ * readIpAddress("unknown")                // undefined
+ * readIpAddress("::1]/,6.6.6.6")          // undefined
+ */
+export function readIpAddress(value) {
+    let text = value?.trim();
+    if (!text)
+        return undefined;
+    const bracketed = /^\[([^\]]+)\](:\d+)?$/.exec(text);
+    if (bracketed)
+        text = bracketed[1];
+    else if (/^[\d.]+:\d+$/.test(text))
+        text = text.slice(0, text.lastIndexOf(":"));
+    if (IPV4.test(text))
+        return text;
+    if (!text.includes(":") || !IPV6_CHARACTERS.test(text))
+        return undefined;
+    try {
+        new URL(`http://[${text}]/`);
+        return text;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * This server's own origin, for a module whose root is a path on the app (a pretend backend): the host and port of the
+ * request URL, over http. Next.js builds that URL from the host and port it listens on, never from the Host header, but
+ * takes its protocol from X-Forwarded-Proto, which anyone can send, so the protocol is not read from it. A server that
+ * listens on every address (`0.0.0.0`, `::`) is called on this machine's own, and the port is always the one Next.js
+ * wrote, even when the URL leaves it out as its protocol's default.
+ *
+ * Never the app's configured origin: an app may build that from a request's Host header, and then a client would choose
+ * which port on this machine the proxy calls, with the user's token.
+ *
+ * @example
+ * ownOrigin(new URL("https://localhost:20016/api/app/drive/File/List"))   // "http://localhost:20016"
+ * ownOrigin(new URL("http://0.0.0.0:3000/api/app/drive/File/List"))       // "http://127.0.0.1:3000"
+ */
+export function ownOrigin(requestUrl) {
+    let host = requestUrl.hostname;
+    if (host === "0.0.0.0")
+        host = "127.0.0.1";
+    else if (host === "[::]")
+        host = "[::1]";
+    let port = requestUrl.port;
+    if (port === "")
+        port = requestUrl.protocol === "https:" ? "443" : "80";
+    return `http://${host}:${port}`;
+}
+/**
+ * The client's address as the app received it: the **last** one in X-Forwarded-For, which is the one Next.js (from the
+ * connection) or the app's own reverse proxy in front of it wrote. The ones before it are what the client claims, and
+ * a client can claim anything. Behind two proxies of the app's own, or a CDN with a header of its own, the app passes
+ * `clientAddress` to the proxy instead. It reads anything with a `get`: a request's headers, or Next.js's `headers()`.
+ *
+ * @example
+ * // A browser sent "X-Forwarded-For: 6.6.6.6"; the app's nginx appended the address it really came from.
+ * lastForwardedAddress(new Headers({ "x-forwarded-for": "6.6.6.6, 203.0.113.7" }))   // "203.0.113.7"
+ */
+export function lastForwardedAddress(headers) {
+    const list = headers.get("x-forwarded-for");
+    if (!list)
+        return undefined;
+    const parts = list.split(",");
+    return readIpAddress(parts[parts.length - 1]);
+}
+/**
+ * Whether a browser sent this request from a page of another site, other than by following a link. Every current
+ * browser says where a request comes from in `Sec-Fetch-Site` and `Sec-Fetch-Mode`. The proxy turns the app's own
+ * session into the user's token, so a page on another site must not be able to call the backend through it (cross-site
+ * request forgery). A link followed from another site (an email, a chat) is a GET navigation and passes; a request
+ * without these headers (an older browser, a server, a tool) is no browser's cross-site call and passes too.
+ */
+export function isCrossSiteCall(headers, method) {
+    if (headers.get("sec-fetch-site") !== "cross-site")
+        return false;
+    const followedLink = headers.get("sec-fetch-mode") === "navigate" && (method === "GET" || method === "HEAD");
+    return !followedLink;
+}
+/** A path segment the proxy refuses: one that climbs (`.`, `..`, nothing but dots and spaces), or one holding a slash. */
+export function isUnsafeSegment(segment) {
+    return /^[\s.]*$/.test(segment) || /[\\/]/.test(segment);
+}
+/** Reads a body whole, up to `limit` bytes. `null` when it is longer: the rest is not read. */
+export async function readBody(stream, limit) {
+    if (!stream)
+        return new Uint8Array(0);
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > limit) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    const whole = new Uint8Array(size);
+    let at = 0;
+    for (const chunk of chunks) {
+        whole.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return whole;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// Response headers
+/** The backend's response headers that come back to the browser, and the only ones unless an app names more. */
+export const DEFAULT_PROXY_RESPONSE_HEADERS = [
+    "content-type",
+    "content-disposition",
+    "content-language",
+    "content-range",
+    "accept-ranges",
+    "cache-control",
+    "expires",
+    "etag",
+    "last-modified",
+    "vary",
+    "retry-after",
+];
+/** Prefixes that come back too: the Nexus backend's own headers for the client, such as a download's X-Nexus-Export-Rows. */
+const RESPONSE_PREFIXES_KEPT = ["x-nexus-"];
+/**
+ * Response headers that never come back, even when an app names them. They name the backend or its software, point at
+ * it (Location, Link, Refresh), carry its own policies for its own origin, or belong to this hop. CORS headers are here
+ * because on the app's origin they would let another site read a user's data through the proxy, with the user's token.
+ */
+const RESPONSE_HEADERS_NEVER = new Set([
+    "server",
+    "x-sourcefiles",
+    "via",
+    "alt-svc",
+    "strict-transport-security",
+    "report-to",
+    "reporting-endpoints",
+    "nel",
+    "expect-ct",
+    "public-key-pins",
+    "public-key-pins-report-only",
+    "location",
+    "content-location",
+    "link",
+    "refresh",
+    "www-authenticate",
+    "timing-allow-origin",
+    "connection",
+    "keep-alive",
+    "transfer-encoding",
+    "te",
+    "trailer",
+    "upgrade",
+    // `fetch` has already decoded the body, so its encoding and length no longer describe what the browser gets.
+    "content-encoding",
+    "content-length",
+    // Only with `passCookies`, and then read on its own (see below).
+    "set-cookie",
+]);
+/** Prefixes of response headers that never come back: X-AspNet-Version, X-AspNetMvc-Version, X-Powered-By*, CORS, Proxy-*. */
+const RESPONSE_PREFIXES_NEVER = ["x-aspnet", "x-powered-by", "access-control-", "proxy-"];
+/** Whether a response header (its lower-case name) may reach the browser. */
+function mayPass(name, allowed) {
+    if (RESPONSE_HEADERS_NEVER.has(name))
+        return false;
+    if (RESPONSE_PREFIXES_NEVER.some(prefix => name.startsWith(prefix)))
+        return false;
+    return allowed.has(name) || RESPONSE_PREFIXES_KEPT.some(prefix => name.startsWith(prefix));
+}
+/** The backend's response headers the browser may see: the allowlist and the app's own names, never one of the above. */
+export function filterResponseHeaders(answer, rules = {}) {
+    const allowed = new Set([...DEFAULT_PROXY_RESPONSE_HEADERS, ...(rules.extra ?? [])].map(name => name.toLowerCase()));
+    const headers = new Headers();
+    answer.forEach((value, name) => {
+        const lower = name.toLowerCase();
+        if (mayPass(lower, allowed))
+            headers.append(lower, value);
+    });
+    // Several cookies cannot be joined into one line, so they are read one by one.
+    if (rules.passCookies)
+        for (const cookie of answer.getSetCookie())
+            headers.append("set-cookie", cookie);
+    return headers;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// Redirects
+/** The statuses `fetch` follows as redirects. The proxy follows each one itself or refuses it; none reaches the browser. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+export function isRedirect(status) {
+    return REDIRECT_STATUSES.has(status);
+}
+/**
+ * Where a backend's redirect leads, when it stays inside the module: on the root's own origin, or on the root's own
+ * host moved from http to https (a backend's HTTPS redirection, which picks its own https port), and under the root's
+ * path, whose casing may differ ("/App/Api" and "/app/api"). Anything else - another host or port, a move from https
+ * to http, a path outside the root, a URL with a user name in it - is `undefined`, and the proxy refuses it: following
+ * it would carry the user's token somewhere the app never named.
+ *
+ * @example
+ * // The module's root is http://localhost:10040/App/Api, and the proxy asked for .../App/Api/Region/ActiveListing:
+ * redirectInsideModule("https://localhost:10041/App/Api/Region/ActiveListing", asked, root) // followed: the https upgrade
+ * redirectInsideModule("/App/Api/Region/ActiveListing/", asked, root)                       // followed: a trailing slash
+ * redirectInsideModule("https://sso.example.com/login?next=/App/Api", asked, root)          // undefined: another host
+ */
+export function redirectInsideModule(location, from, root) {
+    let target;
+    try {
+        target = new URL(location, from);
+    }
+    catch {
+        return undefined;
+    }
+    if (target.username !== "" || target.password !== "")
+        return undefined;
+    const sameOrigin = target.origin === root.origin;
+    const upgraded = root.protocol === "http:" && target.protocol === "https:" && target.hostname === root.hostname;
+    if (!sameOrigin && !upgraded)
+        return undefined;
+    const base = root.pathname.replace(/\/+$/, "").toLowerCase();
+    const path = target.pathname.toLowerCase();
+    if (base !== "" && path !== base && !path.startsWith(`${base}/`))
+        return undefined;
+    target.hash = "";
+    return target;
+}
+/**
+ * The method of the request after a redirect, as the Fetch standard follows one: a 303 asks for a GET (a HEAD stays a
+ * HEAD), a 301 or 302 turns a POST into a GET, and a 307 or 308 keeps the method and the body.
+ */
+export function methodAfterRedirect(status, method) {
+    if (status === 303 && method !== "GET" && method !== "HEAD")
+        return "GET";
+    if ((status === 301 || status === 302) && method === "POST")
+        return "GET";
+    return method;
+}
+/** Headers that describe a request's body: they go with the body when a redirect turns the request into a GET. */
+export const BODY_HEADERS = ["content-type", "content-language", "content-encoding", "content-location"];
+// ---------------------------------------------------------------------------------------------------------------------
+// Error answers
+/** Top-level keys of a JSON answer that is a stack trace: ASP.NET Core's developer exception page, a serialized exception. */
+const TRACE_KEYS = new Set(["exception", "innerexception", "stacktrace", "stacktracestring", "stack"]);
+/**
+ * Why an error answer cannot reach the browser as it came, or `undefined` when it can. An empty answer passes (there is
+ * nothing in it), and so does JSON - the backend's envelope, or problem details - unless it is a stack trace or repeats
+ * the user's token (a page that lists the request's headers). Anything else (an HTML page, text, XML) is the backend
+ * talking about itself.
+ */
+export function whyHidden(contentType, text, token) {
+    if (text.trim() === "")
+        return undefined;
+    if (token && text.includes(token))
+        return "it repeated the user's token";
+    if (!contentType.toLowerCase().includes("json"))
+        return `it was ${contentType.split(";")[0].trim() || "a body with no type"}, not JSON`;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return "it said it was JSON and was not";
+    }
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        if (Object.keys(parsed).some(key => TRACE_KEYS.has(key.toLowerCase())))
+            return "it was a stack trace";
+    }
+    return undefined;
+}
+/**
+ * A short, one-line piece of an error answer for the server's log: the user's token, styles, scripts and tags taken
+ * out, spaces collapsed.
+ */
+export function logSnippet(text, token, length = 300) {
+    let plain = token ? text.split(token).join("[token]") : text;
+    plain = plain
+        .replace(/<(style|script)\b[\s\S]*?<\/\1>/gi, " ")
+        .replace(/<[^>]*>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return plain.length > length ? `${plain.slice(0, length)}...` : plain;
+}
+/** A URL for the server's log: its origin and path, never its query (it may hold what a user searched for, or a key). */
+export function logUrl(url) {
+    return `${url.origin}${url.pathname}`;
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// The proxy's own answers
+/**
+ * The proxy's own refusals: each code is answered from one place in `ApiProxy.ts`, with its HTTP status and its kind
+ * as the Nexus backend numbers kinds (`EErrorCodes`, where a kind's category is its number divided by 20).
+ */
+export const PROXY_REFUSALS = {
+    /** A method other than GET, HEAD, POST, PUT, PATCH and DELETE. RequestInvalid. */
+    METHOD_NOT_ALLOWED: { status: 405, errorCode: 29 },
+    /** A call from a page of another site. AccessDenied. */
+    CROSS_SITE_REFUSED: { status: 403, errorCode: 60 },
+    /** A module the app does not have. RequestInvalid. */
+    MODULE_NOT_FOUND: { status: 404, errorCode: 29 },
+    /** A module the browser calls directly, not through the proxy. RequestInvalid. */
+    MODULE_NOT_PROXIED: { status: 404, errorCode: 29 },
+    /** A path that climbs out of its module. RequestInvalid. */
+    INVALID_PATH: { status: 400, errorCode: 29 },
+    /** A body over the limit. TooLong. */
+    REQUEST_TOO_LARGE: { status: 413, errorCode: 22 },
+    /** A body that could not be read (the client left while sending it). RequestInvalid. */
+    REQUEST_UNREADABLE: { status: 400, errorCode: 29 },
+    /** A module without a usable root URL on this server. SettingMissing. */
+    MODULE_NOT_CONFIGURED: { status: 500, errorCode: 120 },
+    /** A backend that cannot be reached: down, refused, or a certificate this server does not trust. ServiceUnavailable. */
+    BACKEND_UNREACHABLE: { status: 502, errorCode: 160 },
+    /** A backend that did not start answering in time. ServiceTimeout. */
+    BACKEND_TIMEOUT: { status: 504, errorCode: 161 },
+    /** A redirect out of the module, or one with no usable Location. ServiceAnswerInvalid. */
+    BACKEND_REDIRECT_REFUSED: { status: 502, errorCode: 163 },
+    /** More redirects inside the module than the limit. ServiceAnswerInvalid. */
+    BACKEND_REDIRECT_LIMIT: { status: 502, errorCode: 163 },
+    /** An error page that cannot be passed on, answered with the backend's own status. ServiceRefused. */
+    BACKEND_ERROR_PAGE: { status: 502, errorCode: 162 },
+};
+/**
+ * A refusal as the Nexus backend answers one: `{ isSuccess: false, code, errorMessages: [{ message, messageCode,
+ * errorCode }] }`, with the one problem at the top level too, for readers of the older shape.
+ */
+export function nexusFailure(failure) {
+    const { status, message, messageCode, errorCode } = failure;
+    const problem = { message, messageCode, errorCode };
+    return Response.json({ isSuccess: false, code: status, ...problem, errorMessages: [problem] }, { status });
+}
+/**
+ * Every answer the proxy gives: never sniffed into another type, and kept out of every cache unless the backend said
+ * how to cache it - the answer was fetched with the user's token, so a shared cache must never keep it for another user.
+ */
+export function harden(response) {
+    const headers = new Headers(response.headers);
+    headers.set("X-Content-Type-Options", "nosniff");
+    if (!headers.has("cache-control"))
+        headers.set("Cache-Control", "private, no-store");
+    return new Response(response.body, { status: response.status, headers });
+}

package/dist/Services/ExcelApi.js

@@ -39,6 +39,9 @@ export function clearExcelSettings() {
 /** The template to fill in, as the backend built it, under the name the answer gives it. */
 export async function downloadExcelTemplate(endpoints, options = {}) {
     const limits = await excelSettings(endpoints, { signal: options.signal, params: options.params, toast: options.toast });
+    // A refused or failed settings call has said why, once: the file would only fail the same way, in a second toast.
+    if (!limits.ok)
+        return { ...limits, result: undefined };
     const name = limits.result?.templateFileName ?? "template.xlsx";
     const answer = await download(endpoints.template, options, name);
     if (answer.ok && answer.result)
@@ -57,6 +60,8 @@ export async function exportExcel(endpoints, options = {}) {
     if (!endpoint)
         throw new Error("This model has no export endpoint: `excelEndpoints` was given `exportable: false`, or the app's own endpoints left `export` out.");
     const limits = await excelSettings(endpoints, { signal: options.signal, params: options.params, toast: options.toast });
+    if (!limits.ok)
+        return { ...limits, result: undefined };
     const subject = options.subject ?? limits.result?.subject ?? "row";
     const limit = limits.result?.maxExportRows;
     if (options.confirm !== false && limit !== undefined && options.rows !== undefined && options.rows > limit) {

package/dist/Services/FileApi.d.ts

@@ -0,0 +1,13 @@
+import { PrimaryPictures } from "../Helpers/FilePrimaries.ts";
+import type { FileAdapter } from "../Helpers/FileAdapter.ts";
+/**
+ * Registers the app's file backend, once, beside its API modules. Without it, the Nexus Drive.
+ *
+ * @example
+ * defineFileAdapter(new NexusDriveAdapter({ client: api, drive: HrModule.Files }));
+ */
+export declare function defineFileAdapter<T extends FileAdapter>(adapter: T): T;
+/** The registered file backend, or the Nexus Drive. */
+export declare function getFileAdapter(): FileAdapter;
+/** Each owner's picture for the page's rows, read in one call per page and kept until a change on the page. */
+export declare const primaryPictures: PrimaryPictures;