@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/http/trust.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Who may talk to this server: the Host, Origin and proxy-identity checks
+ * every transport runs before it reads a request. Moved out of index.ts
+ * whole; the tenant servers import from here rather than from the entry.
+ */
+import type { IncomingMessage } from 'node:http';
+import { type ClientAddressPolicy } from '../../adapters/serverSettings.js';
+/** Split an `…_ALLOWED_HOSTS` value (`TABLEWALK_` or `MISTRI_`, product.ts). Commas or spaces, either way. */
+export declare function parseHostList(value: string | undefined): string[];
+/** What a listener knows about itself, read on every request. */
+export interface Bound {
+    host: string;
+    port: number;
+    allowedHosts?: readonly string[];
+    /** See `--auth-proxy-header`. */
+    identityHeader?: string;
+    /** See `--trust-proxy`: proxies the public form rate limit may believe about who they forwarded for. Never identity. */
+    trustedProxies?: readonly ProxyRange[];
+    /**
+     * See `--auth-proxy-from`: the peers, beside loopback, whose `identityHeader` value `identityFor` believes. A list of
+     * its own, because `--trust-proxy` is usually a wide range (a pod network, Docker's gateway) that is right for
+     * "which client is this" and wrong for "who is signed in".
+     */
+    identityProxies?: readonly ProxyRange[];
+    /**
+     * A mounting host's `embed.origins` (embed/handler.ts): browser origins
+     * other than this one that may call it (CORS) and frame its pages
+     * (`?embed=frame`), beside the origins the config file's hosts list
+     * (embed/crossOrigin.ts `embedDoorFor`). Never a way past the Origin check
+     * below: a write from one passes only on the bearer that origin was given.
+     */
+    embedOrigins?: readonly string[];
+}
+/**
+ * An address as eight 16-bit groups, or undefined. A zone (`%eth0`) is
+ * dropped; a trailing dotted quad is the last two groups. Shared with the
+ * limiter, which keys an IPv6 client by its first four.
+ */
+export declare function ipv6Groups(address: string): number[] | undefined;
+/** One `--trust-proxy` or `--auth-proxy-from` entry: an address or CIDR range, as written and as groups and a prefix. */
+export interface ProxyRange {
+    readonly text: string;
+    readonly groups: readonly number[];
+    readonly prefix: number;
+}
+/**
+ * Read `--trust-proxy` and `--auth-proxy-from` values: each an IPv4 or IPv6 address or CIDR range,
+ * several to a value when separated by commas or spaces. What is not one is
+ * returned by name, for startup to refuse — a list that silently dropped an
+ * entry would collapse that proxy's clients into one budget with no word.
+ * A zero-length prefix is refused too: it trusts every address, which makes
+ * the header anyone's to write.
+ */
+export declare function parseTrustedProxies(values: readonly string[]): {
+    ranges: ProxyRange[];
+    invalid: string[];
+};
+/**
+ * A peer on this machine (`loopbackPeer`, always), or inside a range in the list given. With the `--trust-proxy` list
+ * it is a peer whose `X-Forwarded-For` the limiter may read; with the `--auth-proxy-from` list (`Bound.identityProxies`)
+ * it is a peer whose `--auth-proxy-header` value `identityFor` believes. The two lists are never swapped: one
+ * grants a client address, the other a person.
+ */
+export declare function trustedProxyPeer(address: string | undefined, trusted?: readonly ProxyRange[]): boolean;
+/** Whether a public address (MISTRI_PUBLIC_URL) is an https one: what `ServerSettings.httpsFront` is set from. */
+export declare function httpsAddress(url: string | undefined): boolean;
+/**
+ * Whether a request reached this server over https: its socket is TLS; the
+ * server is published at an https address (`ServerSettings.httpsFront`), so
+ * a TLS front end stood before it; or a proxy it trusts (`trustedProxyPeer`)
+ * says in `X-Forwarded-Proto` that it forwarded https. The one rule for a
+ * Secure cookie, `Strict-Transport-Security` and the origin a page writes
+ * into a sitemap or a link preview (requestOrigin.ts, baselineHeaders.ts,
+ * forms/savedForms.ts `secureRequest`).
+ */
+export declare function arrivedOverHttps(req: Pick<IncomingMessage, 'headers' | 'socket'>, trusted?: readonly ProxyRange[]): boolean;
+/**
+ * Read `--trust-proxy-hops` and `--trust-proxy-cloudflare`. A hop count that
+ * is not a whole number from 1 to 32 comes back as an error for startup to
+ * print: a mistyped count would collapse every visitor into one budget, or
+ * believe a header the client wrote, with no word.
+ */
+export declare function parseClientAddressPolicy(input: {
+    hops?: string;
+    cloudflare?: boolean;
+}): {
+    policy: ClientAddressPolicy;
+} | {
+    error: string;
+};
+/**
+ * Which client a request is from, for keying a limit — never for authority.
+ *
+ * With `--trust-proxy-cloudflare`, the `CF-Connecting-IP` header, when it is
+ * one address: Cloudflare sets it and replaces any the client sent. Without
+ * the flag it is never read, because anyone can write it.
+ *
+ * With `--trust-proxy-hops N`, the address N places from the right of
+ * [socket peer, ...X-Forwarded-For read right to left]: the peer is the first
+ * proxy, and each appends the address it saw, so what is left of the Nth is
+ * the client's own claim and is dropped. Fewer entries than hops, the
+ * furthest. This does not look at who the peer is — that is the point, on a
+ * front end with no stable address — so it is for a server reachable only
+ * through those hops.
+ *
+ * Otherwise the socket peer, unless that peer is a trusted proxy (`trustedProxyPeer`:
+ * loopback, or an address `--trust-proxy` named): then the client is the
+ * nearest `X-Forwarded-For` hop that is not a trusted proxy too. Read from
+ * the right, because a proxy appends the address it saw and everything to
+ * its left is whatever the client chose to send; each trusted hop passed
+ * vouches for the one before it. When every hop is trusted, the furthest is
+ * the client. From any other peer the header is not read at all — anyone can
+ * write one — and a malformed header is ignored whole rather than
+ * half-believed. A proxy on another host that nobody listed is its own
+ * address, so its clients share one budget.
+ */
+export declare function forwardedClient(req: {
+    headers?: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+}, trusted?: readonly ProxyRange[]): string;
+/**
+ * Who is asking, when the operator has said which header carries it.
+ *
+ * `--auth-proxy-header X-Forwarded-User` means a proxy in front signs
+ * people in and writes the result into that header on the way through.
+ * A request without it did not come through the proxy — or came through
+ * one that is misconfigured — and is refused with the header named. So is
+ * a request that carries it from a peer that is not the proxy: the header
+ * is only a name anyone can type, so a value from an address neither on
+ * loopback nor in `--auth-proxy-from` is a forgery, not a sign-in. Loopback is
+ * exempt: the container's own health check, a curl on the box, the
+ * operator's terminal. Nothing here is authentication; it is the proxy's
+ * decision, carried to the journal.
+ */
+export declare function identityFor(req: {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+}, bound: Bound): {
+    who?: string;
+    refusal?: string;
+};
+/**
+ * Whether the browser on this listener is the operator.
+ *
+ * On loopback with no extra hosts, whoever reaches the port started the
+ * process, and the connection form may do what the config file may: reference
+ * `${PROD_PASSWORD}`, look a password up in the keychain by name, open a
+ * SQLite file by path, choose where the config is saved. Bound wider — or
+ * answering to a proxy's name — the browser is anyone on the network, and each
+ * of those is a way out: an env reference sends this process's secrets to a
+ * host the caller names, a keychain lookup attaches a stored password to the
+ * caller's URL, a file path reads any database the server user can, and a
+ * save path writes JSON wherever it points. The routes that take a target
+ * from the client ask this first and refuse those forms when it says no.
+ *
+ * Nothing here is authentication. It is the line between "your own machine"
+ * and "the network" that the README already draws, applied to the one API
+ * that takes a database *address* rather than a query.
+ */
+export declare function clientTrusted(bound: {
+    host: string;
+    allowedHosts?: readonly string[];
+}): boolean;
+/**
+ * Why a connection target from an untrusted client is refused, or null when
+ * it is a plain network URL that resolves nothing on this machine. A URL that
+ * passes is still dialled sealed, to public addresses only
+ * (adapters/net/untrustedDatabase.ts).
+ */
+export declare function untrustedTargetRefusal(target: string): string | null;
+/**
+ * The `Host` half, on its own, because it has to run on reads too.
+ *
+ * This was inside `crossOriginRefusal`, which only ever ran for methods that
+ * change something. The reasoning was that a read is harmless — and it is
+ * wrong, because the attack this check exists to stop is DNS rebinding, and
+ * rebinding's whole trick is to make the request *same-origin* so the
+ * response can be read. A page on a name the attacker controls, pointed at
+ * 127.0.0.1, could `fetch('/api/schema')` and read the answer: every table,
+ * every column, every foreign key. `/api/ddl` handed over `CREATE TABLE`.
+ * `/api/connections` named the hosts, users and databases. `/api/queries`
+ * gave up the saved SQL. All of it, from any page, on any machine where
+ * tablewalk happened to be running.
+ *
+ * Row data was never reachable — reads that take arguments are POSTs, and
+ * those were checked. The schema is not nothing.
+ *
+ * It runs on the static files too, so a rebinding attempt fails at the page
+ * rather than one request later. Reaching tablewalk by any name other than
+ * loopback has always needed `--allowed-host` for writes to work; this makes
+ * that one rule instead of two.
+ *
+ * It is the first part of `doorRefusal`, which is what a surface calls.
+ */
+export declare function hostRefusal(req: IncomingMessage, bound: Bound): string | null;
+/** Validate a serialized browser Origin, independently of JSON body policy.
+ * Missing Origin remains available to non-browser clients. This compares hosts,
+ * not the serving socket's scheme: TLS proxies may terminate HTTPS upstream.
+ * Full scheme equality needs explicitly trusted external-origin metadata.
+ * A part of `doorRefusal`, which is what a surface calls; `ownOrigin` asks it as a question. */
+export declare function originRefusal(req: IncomingMessage): string | null;
+/** Mark a request whose Origin the embed door admitted on its bearer. */
+export declare function vouchForOrigin(req: IncomingMessage): void;
+/** A write's door, as one sentence or null: `doorRefusal` with `{ writing: true }`. Kept for its unit tests; surfaces call `doorRefusal`. */
+export declare function crossOriginRefusal(req: IncomingMessage, bound: Bound): string | null;
+/** Whether a request can change something: anything but a GET or a HEAD. */
+export declare function writes(req: IncomingMessage): boolean;
+/** Whether the request's Origin, if it sent one, is this page's (`originRefusal`): a question, not a door. */
+export declare function ownOrigin(req: IncomingMessage): boolean;
+/**
+ * What a surface asks of the door (`doorRefusal`). Every check it leaves out
+ * is left out here, by name, with the reason beside the call — never by not
+ * calling one.
+ */
+export interface DoorRule {
+    /**
+     * The request can change something, so its Origin must be this page's and
+     * its body JSON (see `crossOriginRefusal`). False for a read, and where a
+     * dispatcher further in holds the write's line — the call says which.
+     */
+    readonly writing: boolean;
+    /**
+     * When the Origin is checked:
+     *
+     *   - `'writes'` (the default): on a write, where an Origin the embed door
+     *     admitted on its bearer (`vouchForOrigin`) passes;
+     *   - `'always'`: on reads as well, and a vouch never passes — for a surface
+     *     whose reads are an account's own (a flag's history, an administrator's
+     *     list), which no host's bearer stands for;
+     *   - `'none'`: never — the surface proves its caller another way (a
+     *     provider's signature, a signed link, a token), said beside the call.
+     */
+    readonly origin?: 'writes' | 'always' | 'none';
+    /**
+     * Also refuse `Sec-Fetch-Site: cross-site` wherever the Origin is checked:
+     * for a surface a browser may reach without an Origin a page chose — a
+     * beacon, a form, a credential's ceremony.
+     */
+    readonly sameSite?: boolean;
+    /** Whether a write's body must be JSON; the default is `writing`. False only beside a reason. */
+    readonly json?: boolean;
+}
+/** Which check refused, for a surface that answers them differently, and the sentence it refused with. */
+interface DoorRefusal {
+    readonly check: 'host' | 'site' | 'origin' | 'json';
+    readonly error: string;
+}
+/**
+ * The one door every HTTP surface holds a request to, before it reads
+ * anything else of it: the Host (`hostRefusal`, on reads too), then, where
+ * `rule` says, the browser's fetch site and the Origin, then a write's JSON
+ * body. The gate (gate.ts) asks it twice, either side of the proxy identity
+ * and the embed door, because that door decides whether an Origin is vouched
+ * for; every other surface asks once.
+ */
+export declare function doorRefusal(req: IncomingMessage, bound: Bound, rule: DoorRule): DoorRefusal | null;
+export {};