nexus-shared 3.1.0 → 3.2.0

package/dist/Services/ApiProxy.js

@@ -2,71 +2,160 @@ import { DEFAULT_API_TIMEOUT, isFrameworkError } from "../Helpers/ApiClient.js";
 import { getApiModules } from "../Helpers/ApiModules.js";
 import { joinUrl } from "../Helpers/ApiRoutes.js";
 import { buildMessage } from "../Helpers/MessageBuilder.js";
-import { serverModuleRoot } from "./ServerApi.js";
+import { BODY_HEADERS, DEFAULT_PROXY_BODY_LIMIT, DEFAULT_PROXY_REDIRECTS, ERROR_BODY_LIMIT, filterResponseHeaders, forwardRequestHeaders, harden, isCrossSiteCall, isRedirect, isUnsafeSegment, lastForwardedAddress, logSnippet, logUrl, methodAfterRedirect, nexusFailure, ownOrigin, PROXY_REFUSALS, readBody, readIpAddress, redirectInsideModule, whyHidden, } from "./ApiProxyRules.js";
+import { serverAppOrigin, serverModuleRoot } from "./ServerApi.js";
+export { DEFAULT_PROXY_BODY_LIMIT, DEFAULT_PROXY_REDIRECTS, DEFAULT_PROXY_RESPONSE_HEADERS, lastForwardedAddress, nexusFailure, PROXY_REFUSALS, readIpAddress } from "./ApiProxyRules.js";
 const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
-/** Request headers that belong to this hop, or to the app (its cookies), not to the backend. */
-const REQUEST_HEADERS_TO_SKIP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive", "upgrade", "cookie", "te", "trailer", "proxy-authorization", "proxy-connection", "accept-encoding"]);
+/** Statuses whose answer has no body. */
+const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+/** What a call does, for the plain words of a refusal: a GET loads, a DELETE deletes, the rest save. */
+function actionOf(method) {
+    if (method === "GET" || method === "HEAD")
+        return "load";
+    return method === "DELETE" ? "delete" : "save";
+}
+/** Whether an answer reaches the browser as it came, without being read first: a success, or a 304. */
+function passesUnread(status) {
+    return (status >= 200 && status < 300) || status === 304;
+}
+/** Why a `fetch` failed, from its cause ("ECONNREFUSED", "DEPTH_ZERO_SELF_SIGNED_CERT"), with what to do about a certificate. */
+function describeFetchError(error) {
+    const cause = error?.cause;
+    let text = error instanceof Error ? error.message : String(error);
+    if (typeof cause?.code === "string")
+        text = cause.code;
+    else if (typeof cause?.message === "string")
+        text = cause.message;
+    if (!/CERT|SELF_SIGNED|UNABLE_TO_VERIFY|ERR_TLS/i.test(text))
+        return text;
+    return `${text}: this server does not trust the backend's certificate. Start Node.js with NODE_USE_SYSTEM_CA=1 (or NODE_EXTRA_CA_CERTS) so it trusts the certificates this machine trusts, or give the module a root it trusts`;
+}
+/** A redirect's target for the log, without its query. */
+function logLocation(location, from) {
+    try {
+        return logUrl(new URL(location, from));
+    }
+    catch {
+        return "a Location that is not a URL";
+    }
+}
+function logProblem(problem) {
+    console.error(`[apiProxy] ${problem.call}: ${problem.messageCode}, ${problem.detail}`);
+}
 /**
- * Response headers that belong to the backend's hop. `content-encoding` and `content-length` go too: `fetch` has already
- * decompressed the body, so passing them on would make the browser decode it twice.
+ * The app's address as the backend is told it in X-Forwarded-Host and -Proto: the configured one
+ * (`configureServerApi({ origin })`, URL_CURRENT), else this request's, which Next.js builds from its own host and port
+ * (never the Host header) but with the protocol X-Forwarded-Proto names. Never where a call goes: that is `ownOrigin`.
  */
-const RESPONSE_HEADERS_TO_SKIP = new Set(["connection", "transfer-encoding", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "upgrade", "content-encoding", "content-length"]);
-/** An answer the client reads like the backend's own. */
-function failure(status, message, messageCode) {
-    return Response.json({ isSuccess: false, code: status, message, messageCode }, { status });
-}
-/** A backend redirect to its own host, pointed back through the proxy. */
-function rewriteLocation(location, root, module, proxyPath) {
-    const target = new URL(location, root);
-    if (target.host !== root.host)
-        return location;
-    const base = root.pathname.replace(/\/+$/, "");
-    const relative = target.pathname.startsWith(`${base}/`) ? target.pathname.slice(base.length + 1) : target.pathname.replace(/^\/+/, "");
-    return `${joinUrl(joinUrl(proxyPath, module), relative)}${target.search}`;
+async function appOriginOf(incoming) {
+    try {
+        const configured = await serverAppOrigin();
+        if (configured)
+            return new URL(configured);
+    }
+    catch (error) {
+        if (isFrameworkError(error))
+            throw error;
+    }
+    return incoming;
 }
 /**
  * Makes the route handlers of the proxy. Only the modules' configured roots can be reached: a path cannot climb out of
  * its module (`..` is refused), and the query goes on unchanged.
  */
 export function createApiProxy(options = {}) {
+    const maxBodySize = options.maxBodySize ?? DEFAULT_PROXY_BODY_LIMIT;
+    const maxRedirects = options.maxRedirects ?? DEFAULT_PROXY_REDIRECTS;
+    const timeout = options.timeout ?? DEFAULT_API_TIMEOUT;
+    /** A refusal of the proxy's own, in the app's envelope (Nexus's by default). */
+    function refuse(messageCode, message, status = PROXY_REFUSALS[messageCode].status) {
+        return harden((options.failure ?? nexusFailure)({ status, message, messageCode, errorCode: PROXY_REFUSALS[messageCode].errorCode }));
+    }
+    function report(problem) {
+        try {
+            (options.onProblem ?? logProblem)(problem);
+        }
+        catch {
+            // A log that fails must not change the answer.
+        }
+    }
     async function handle(request, context) {
         const method = request.method.toUpperCase();
-        if (!METHODS.has(method))
-            return failure(405, buildMessage("reason", { status: 405 }), "METHOD_NOT_ALLOWED");
         const { module: key, path = [] } = await context.params;
+        // The call as the log names it: the module and path the browser asked for, never the query. Encoded, so a line
+        // break the browser put in the path cannot start a line of its own in the log.
+        const call = `${method} ${[key, ...path].map(encodeURIComponent).join("/")}`;
+        const action = actionOf(method);
+        if (!METHODS.has(method)) {
+            const refusal = refuse("METHOD_NOT_ALLOWED", buildMessage("reason", { status: 405 }));
+            refusal.headers.set("Allow", [...METHODS].join(", "));
+            return refusal;
+        }
+        if (!options.allowCrossSite && isCrossSiteCall(request.headers, method))
+            return refuse("CROSS_SITE_REFUSED", buildMessage("reason", { action, status: 403 }));
         // Asked on every request, so the app's modules count even when they were registered after this route was made.
         const modules = getApiModules();
         const info = modules.info(key);
         if (!info || (options.allow && !options.allow.includes(info.module)))
-            return failure(404, `No API module is named "${key}".`, "MODULE_NOT_FOUND");
+            return refuse("MODULE_NOT_FOUND", `No API module is named "${key}".`);
         if (!modules.proxies(info.module))
-            return failure(404, `The ${info.label} API is not called through this app's proxy.`, "MODULE_NOT_PROXIED");
-        if (path.some(segment => segment === "." || segment === ".." || /[\\/]/.test(segment)))
-            return failure(400, "The API path is not valid.", "INVALID_PATH");
+            return refuse("MODULE_NOT_PROXIED", `The ${info.label} API is not available at this address.`);
+        if (path.some(isUnsafeSegment))
+            return refuse("INVALID_PATH", "The API path is not valid.");
+        // The app's address as the backend is told it, in X-Forwarded-Host and -Proto. The configured one comes first:
+        // Next.js takes a request URL's protocol from X-Forwarded-Proto, which anyone can send.
         const incoming = new URL(request.url);
+        const app = await appOriginOf(incoming);
+        // The module's root. One that is a path on this app is called at this server's own host and port, never at the
+        // configured origin, which an app may build from the Host header. What is wrong with a root (an environment
+        // variable's name, an address) is for the log only.
         let root;
         try {
-            root = new URL(await serverModuleRoot(info.module, incoming.origin));
+            root = new URL(await serverModuleRoot(info.module, ownOrigin(incoming)));
+            if (root.protocol !== "http:" && root.protocol !== "https:")
+                throw new Error(`The ${info.label} API's root is not an http or https address.`);
         }
         catch (error) {
             if (isFrameworkError(error))
                 throw error;
-            return failure(500, error instanceof Error ? error.message : String(error), "MODULE_NOT_CONFIGURED");
+            report({ messageCode: "MODULE_NOT_CONFIGURED", call, detail: error instanceof Error ? error.message : String(error) });
+            return refuse("MODULE_NOT_CONFIGURED", `The ${info.label} API is not set up on this server.`);
         }
         const target = new URL(joinUrl(root.toString(), path.map(encodeURIComponent).join("/")));
         target.search = incoming.search;
-        const headers = new Headers();
-        request.headers.forEach((value, name) => {
-            if (!REQUEST_HEADERS_TO_SKIP.has(name.toLowerCase()))
-                headers.set(name, value);
-        });
+        // The body, read whole so a 307 or 308 can send it again. A declared length over the limit is refused before a
+        // byte is read; an undeclared one is counted as it arrives.
+        let body;
+        if (method !== "GET" && method !== "HEAD") {
+            let read;
+            try {
+                read = Number(request.headers.get("content-length")) > maxBodySize ? null : await readBody(request.body, maxBodySize);
+            }
+            catch (error) {
+                if (isFrameworkError(error))
+                    throw error;
+                return refuse("REQUEST_UNREADABLE", buildMessage("reason", { status: 400 }));
+            }
+            if (!read)
+                return refuse("REQUEST_TOO_LARGE", buildMessage("reason", { action, status: 413 }));
+            body = read;
+        }
+        // The headers: the browser's, less this hop's, the app's cookies and everything the browser says about where it
+        // came from; then who the client is and where the app is, as the app knows them; then the app's own and the token.
+        const headers = forwardRequestHeaders(request.headers);
+        const client = readIpAddress(options.clientAddress ? await options.clientAddress(request) : lastForwardedAddress(request.headers));
+        if (client)
+            headers.set("X-Forwarded-For", client);
+        headers.set("X-Forwarded-Host", app.host);
+        headers.set("X-Forwarded-Proto", app.protocol.replace(":", ""));
         for (const [name, value] of Object.entries((await options.headers?.(request)) ?? {}))
             headers.set(name, value);
         const token = await options.token?.(request);
         if (token)
             headers.set("Authorization", /^bearer /i.test(token) ? token : `Bearer ${token}`);
+        // The token as the backend got it, to keep it out of the log and to spot an error page that repeats it.
+        const sentToken = token ? token.replace(/^bearer\s+/i, "") : undefined;
         const controller = new AbortController();
-        const timeout = options.timeout ?? DEFAULT_API_TIMEOUT;
         let timedOut = false;
         const timer = setTimeout(() => {
             timedOut = true;
@@ -75,37 +164,78 @@ export function createApiProxy(options = {}) {
         // The browser left: stop waiting for the backend.
         const leave = () => controller.abort();
         request.signal?.addEventListener("abort", leave, { once: true });
+        const send = options.fetch ?? globalThis.fetch;
+        let url = target;
+        let hopMethod = method;
+        let hopBody = body;
         let answer;
+        // An error answer, read whole (up to a limit) to see whether it may reach the browser as it came; null when larger.
+        let errorBody;
         try {
-            answer = await (options.fetch ?? globalThis.fetch)(target, {
-                method,
-                headers,
-                body: method === "GET" || method === "HEAD" ? undefined : await request.arrayBuffer(),
-                redirect: "manual",
-                cache: "no-store",
-                signal: controller.signal,
-            });
+            const ask = () => send(url, { method: hopMethod, headers, body: hopBody, redirect: "manual", cache: "no-store", signal: controller.signal });
+            answer = await ask();
+            let hops = 0;
+            while (isRedirect(answer.status)) {
+                // A redirect never reaches the browser: followed here while it stays inside the module, refused otherwise.
+                await answer.body?.cancel().catch(() => undefined);
+                const location = answer.headers.get("location");
+                const next = location ? redirectInsideModule(location, url, root) : undefined;
+                if (!next) {
+                    const where = location ? `to ${logLocation(location, url)}, outside the module's root ${logUrl(root)}` : "with no Location";
+                    report({ messageCode: "BACKEND_REDIRECT_REFUSED", call, detail: `${logUrl(url)} answered ${answer.status} ${where}` });
+                    return refuse("BACKEND_REDIRECT_REFUSED", buildMessage("reason", { status: 502 }));
+                }
+                if (hops >= maxRedirects) {
+                    report({ messageCode: "BACKEND_REDIRECT_LIMIT", call, detail: `more than ${maxRedirects} redirects; the last from ${logUrl(url)} to ${logUrl(next)}` });
+                    return refuse("BACKEND_REDIRECT_LIMIT", buildMessage("reason", { status: 502 }));
+                }
+                const nextMethod = methodAfterRedirect(answer.status, hopMethod);
+                if (nextMethod !== hopMethod) {
+                    // A 303, or a 301 or 302 after a POST: the request becomes a GET and leaves its body behind.
+                    hopBody = undefined;
+                    for (const name of BODY_HEADERS)
+                        headers.delete(name);
+                }
+                hopMethod = nextMethod;
+                url = next;
+                hops++;
+                answer = await ask();
+            }
+            if (hopMethod !== "HEAD" && !passesUnread(answer.status))
+                errorBody = await readBody(answer.body, ERROR_BODY_LIMIT);
         }
         catch (error) {
             if (isFrameworkError(error))
                 throw error;
-            if (timedOut)
-                return failure(504, buildMessage("reason", { timeout: true }), "BACKEND_TIMEOUT");
-            return failure(502, `The ${info.label} API cannot be reached. Try again in a moment.`, "BACKEND_UNREACHABLE");
+            if (timedOut) {
+                report({ messageCode: "BACKEND_TIMEOUT", call, detail: `${logUrl(url)} did not answer within ${timeout} ms` });
+                return refuse("BACKEND_TIMEOUT", buildMessage("reason", { timeout: true }));
+            }
+            // When the browser left, nobody reads the answer, and nothing failed on the backend's side.
+            if (!request.signal?.aborted)
+                report({ messageCode: "BACKEND_UNREACHABLE", call, detail: `${logUrl(url)}: ${describeFetchError(error)}` });
+            return refuse("BACKEND_UNREACHABLE", `The ${info.label} API cannot be reached. Try again in a moment.`);
         }
         finally {
-            // The timeout covers the wait for the answer to start; a long download then streams through.
+            // The timeout covers the wait for the answer to start, its redirects and the reading of an error answer included;
+            // a long download then streams through.
             clearTimeout(timer);
             request.signal?.removeEventListener("abort", leave);
         }
-        const responseHeaders = new Headers();
-        answer.headers.forEach((value, name) => {
-            const lower = name.toLowerCase();
-            if (RESPONSE_HEADERS_TO_SKIP.has(lower))
-                return;
-            responseHeaders.append(name, lower === "location" ? rewriteLocation(value, root, info.key, modules.proxyPath) : value);
-        });
-        return new Response(method === "HEAD" ? null : answer.body, { status: answer.status, statusText: answer.statusText, headers: responseHeaders });
+        const status = answer.status;
+        const responseHeaders = filterResponseHeaders(answer.headers, { extra: options.responseHeaders, passCookies: options.passCookies });
+        if (errorBody === undefined) {
+            const noBody = hopMethod === "HEAD" || NULL_BODY_STATUSES.has(status);
+            return harden(new Response(noBody ? null : answer.body, { status, headers: responseHeaders }));
+        }
+        // An error answer passes as it came when it is empty, or JSON that says nothing about the backend; anything else
+        // is replaced with the failure envelope, in plain words for the status, and the real cause is logged.
+        const text = errorBody === null ? "" : new TextDecoder().decode(errorBody);
+        const reason = errorBody === null ? `it was over ${ERROR_BODY_LIMIT} bytes` : whyHidden(answer.headers.get("content-type") ?? "", text, sentToken);
+        if (reason === undefined)
+            return harden(new Response(text === "" ? null : errorBody, { status, headers: responseHeaders }));
+        report({ messageCode: "BACKEND_ERROR_PAGE", call, detail: `${logUrl(url)} answered ${status}, and ${reason}: ${logSnippet(text, sentToken)}` });
+        return refuse("BACKEND_ERROR_PAGE", buildMessage("reason", { action, status }), status);
     }
     return { GET: handle, HEAD: handle, POST: handle, PUT: handle, PATCH: handle, DELETE: handle };
 }

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;