@catalystiq/test-kit 0.3.1 → 0.4.0

package/dist/neon-endpoint/index.js

@@ -0,0 +1,359 @@
+/**
+ * Which database a connection string addresses, read from the string alone the way the clients that will use it read
+ * it: no network, no query. The reader for an app's build and boot checks, fed with the app's own endpoint ids
+ * ({@link createEndpointGuard}). The kit's own guards (`tk-dev-guard`, the Vitest setup's production check) keep their
+ * own reading, `../setup/database.ts`, which normalises a whole value and errs further towards refusing.
+ *
+ * WHY "THE WAY THE CLIENTS READ IT". A `postgres:` URL keeps an opaque host: `new URL(url).hostname` neither
+ * percent-decodes nor IDNA-maps it. The clients do. `pg-connection-string` runs `decodeURIComponent` on the host, and
+ * the Neon serverless driver's `neon()` re-parses the whole string as `http:` + the rest, so its host is read as a
+ * WHATWG special-scheme host: percent-decoded, lowercased and IDNA-mapped. A fullwidth letter or hyphen becomes its
+ * ASCII twin, a soft hyphen disappears, an ideographic full stop becomes a dot. A guard that matches the text as
+ * written passes a production endpoint id spelled with any of those, and the app then connects to production through
+ * it. Every reading here is therefore taken over each spelling a client might resolve ({@link hostSpellings}).
+ *
+ * TWO QUESTIONS, TWO READERS.
+ *  - "Does this value name one of these databases ANYWHERE?" ({@link listedEntryIn}, {@link namesEndpoint}): a
+ *    denylist, so it reads every shape (a URL, a keyword/value string, a bare `PGHOST`, `PGOPTIONS endpoint=…`, a
+ *    `?host=` override, an `options=endpoint%3D…`) on any domain, and errs on naming.
+ *  - "Which ONE endpoint does this URL connect to?" ({@link neonEndpointId}): an allowlist's question, so it answers
+ *    only for a host under Neon's own domains whose every reading and every other route in the URL agree, and null
+ *    otherwise, which an allowlist refuses.
+ *
+ * A LEAF ON PURPOSE: no import, not even a `node:` builtin, so an app can bundle it into server code and a build script
+ * can run it with bare `node`. It spells no database host (an app's build may refuse one in a server chunk); ids are
+ * the caller's. Nothing here returns or throws a piece of the value other than an endpoint id or a list entry, which
+ * are routing names and not credentials.
+ */
+const ENDPOINT_LABEL = /^(ep-[a-z0-9]+(?:-[a-z0-9]+)*?)(?:-pooler)?$/;
+const NEON_DOMAIN = /(?:^|\.)neon\.(?:tech|build)$/;
+/** An `ep-…` label with any `-pooler` suffix stripped, or null. The one normalisation every URL reading uses. */
+export function endpointFromLabel(label) {
+    const match = ENDPOINT_LABEL.exec(String(label).toLowerCase());
+    return match ? match[1] : null;
+}
+/**
+ * The endpoint id of one bare host name, or null when it is not an endpoint host. A host holding a comma is null too:
+ * libpq reads `ep-a…,ep-b…` as a list of hosts, and a non-special scheme keeps the comma in `URL.hostname`, so reading
+ * its first label would silently drop every later member.
+ */
+function endpointFromHost(host, anyDomain) {
+    const h = String(host).trim().toLowerCase();
+    if (h.includes(','))
+        return null;
+    if (!anyDomain && !NEON_DOMAIN.test(h))
+        return null;
+    return endpointFromLabel(h.split('.')[0] ?? '');
+}
+/**
+ * A host as a WHATWG `http:`/`https:` URL reads it: percent-decoded, IDNA-mapped, lowercased. That is the host `neon()`
+ * fetches from. Null when the text does not parse as a host at all.
+ */
+export function specialSchemeHostname(host) {
+    try {
+        return new URL(`https://${host}`).hostname || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The URL's host when the whole string is re-read under a special scheme, exactly as `neon()` does, or null. */
+export function specialSchemeUrlHostname(url) {
+    try {
+        return new URL(String(url).replace(/^[a-z][a-z0-9+.-]*:/i, 'https:')).hostname || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every spelling of a host some client might resolve: as written, percent-decoded (`pg-connection-string`), and each of
+ * those as a special-scheme URL reads it (`neon()`).
+ */
+export function hostSpellings(host) {
+    const raw = String(host);
+    const out = [raw];
+    try {
+        out.push(decodeURIComponent(raw));
+    }
+    catch {
+        // A malformed escape is read as written.
+    }
+    for (const h of [...out]) {
+        const special = specialSchemeHostname(h);
+        if (special)
+            out.push(special);
+    }
+    return [...new Set(out)];
+}
+/**
+ * The endpoint ids of a host as SOME client might read it, for the "names it anywhere" list only: every spelling, each
+ * split on commas (a libpq host list, each member spelled again) and with trailing dots stripped (a fully qualified
+ * name resolves to the same compute).
+ */
+function endpointsFromHostLenient(host, anyDomain) {
+    const ids = [];
+    for (const spelling of hostSpellings(host)) {
+        for (const member of spelling.split(',')) {
+            for (const m of hostSpellings(member.trim()))
+                ids.push(endpointFromHost(m.trim().replace(/\.+$/, ''), anyDomain));
+        }
+    }
+    return ids;
+}
+function parseUrl(url) {
+    if (typeof url !== 'string')
+        return null;
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+/** Every query parameter named `name`, in any letter case: reading every spelling only ever names more endpoints. */
+function paramValues(parsed, name) {
+    const out = [];
+    for (const [key, value] of parsed.searchParams)
+        if (key.toLowerCase() === name)
+            out.push(value);
+    return out;
+}
+/**
+ * The host overrides node-postgres honours: a non-empty `?host=` REPLACES the URL host for `pg` (each entry of a
+ * comma-separated list), while `neon()` ignores it and fetches from the URL host. `hostaddr` is an IP address nothing
+ * here can attribute to an endpoint.
+ */
+function hostOverrides(parsed) {
+    const hosts = paramValues(parsed, 'host')
+        .flatMap((v) => v.split(','))
+        .map((h) => h.trim())
+        .filter(Boolean);
+    return { hosts, hostaddr: paramValues(parsed, 'hostaddr').length > 0 };
+}
+/** The endpoint the URL host names, read BOTH ways a client reads it; both must be an endpoint host for one endpoint. */
+function urlHostEndpointId(parsed, url, anyDomain) {
+    const opaque = endpointFromHost(parsed.hostname, anyDomain);
+    if (opaque === null)
+        return null;
+    const special = specialSchemeUrlHostname(url);
+    return special !== null && endpointFromHost(special, anyDomain) === opaque ? opaque : null;
+}
+/** {@link neonEndpointId} before the cross-check against every other route the URL carries. */
+function connectEndpointId(url, anyDomain) {
+    const parsed = parseUrl(url);
+    if (!parsed)
+        return null;
+    const { hosts, hostaddr } = hostOverrides(parsed);
+    if (hostaddr)
+        return null;
+    const fromUrlHost = urlHostEndpointId(parsed, url, anyDomain);
+    if (hosts.length === 0 || fromUrlHost === null)
+        return fromUrlHost;
+    // `pg` connects to the override, `neon()` to the URL host, so the URL host must itself be an endpoint host (above)
+    // and every override must name the same endpoint.
+    return hosts.every((h) => endpointFromHost(h, anyDomain) === fromUrlHost) ? fromUrlHost : null;
+}
+/**
+ * True when the URL carries a host override (`hostaddr`, or a non-empty `host` parameter) and cannot be pinned to one
+ * endpoint with it. An allowlist cannot show such a URL is not production's, so it must refuse it.
+ */
+export function hasUnattributableHostOverride(url, options = {}) {
+    const parsed = parseUrl(url);
+    if (!parsed)
+        return false;
+    const { hosts, hostaddr } = hostOverrides(parsed);
+    if (!hostaddr && hosts.length === 0)
+        return false;
+    return connectEndpointId(url, options.anyDomain === true) === null;
+}
+/**
+ * The ONE endpoint id the URL connects to, or null: the host is not an endpoint host under Neon's domains (a
+ * percent-encoded, IDNA-mapped, trailing-dot or comma-separated host included, since the opaque and the special-scheme
+ * reading must agree), the value is not a URL, or the URL cannot be pinned to one endpoint (a `hostaddr`, a `host`
+ * entry elsewhere, or an `options` or password route naming another endpoint than the host).
+ */
+export function neonEndpointId(url, options = {}) {
+    const id = connectEndpointId(url, options.anyDomain === true);
+    if (id === null)
+        return null;
+    return neonEndpointIds(url, options).every((other) => other === id) ? id : null;
+}
+/** A value as written and percent-decoded, up to `rounds` times over (a client may decode what another already did). */
+export function decodedForms(value, rounds = 3) {
+    const forms = [value];
+    let text = value;
+    for (let i = 0; i < rounds; i += 1) {
+        const next = decodedOnce(text);
+        if (next === text)
+            break;
+        forms.push(next);
+        text = next;
+    }
+    return forms;
+}
+/**
+ * Each run of `%XX` escapes decoded as UTF-8 on its own, so one malformed `%` elsewhere cannot hide the rest, and an
+ * escaped non-ASCII letter (`%EF%BD%85`) becomes the letter a client would then map.
+ */
+function decodedOnce(value) {
+    return value.replace(/(?:%[0-9a-f]{2})+/gi, (run) => utf8(run));
+}
+function utf8(run) {
+    const bytes = new Uint8Array(run.length / 3);
+    for (let i = 0; i < bytes.length; i += 1)
+        bytes[i] = Number.parseInt(run.slice(i * 3 + 1, i * 3 + 3), 16);
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * Every endpoint id the URL names, wherever it names one: the URL host (each member of a comma-separated list, each
+ * spelling), each `host` query parameter entry, an `endpoint=<id>` (or the older `project=<id>`, the id quoted or not)
+ * in an `options` parameter, the same in the password field and in a `password` parameter (which node-postgres uses
+ * INSTEAD of the URL's password). Ids are normalised as the host's are (`-pooler` stripped).
+ */
+export function neonEndpointIds(url, options = {}) {
+    const parsed = parseUrl(url);
+    if (!parsed)
+        return [];
+    const anyDomain = options.anyDomain === true;
+    const ids = [];
+    const add = (id) => {
+        if (id && !ids.includes(id))
+            ids.push(id);
+    };
+    for (const id of endpointsFromHostLenient(parsed.hostname, anyDomain))
+        add(id);
+    // The whole string re-read under a special scheme, as `neon()` reads it (backslashes, IDNA).
+    const special = specialSchemeUrlHostname(url);
+    if (special)
+        for (const id of endpointsFromHostLenient(special, anyDomain))
+            add(id);
+    for (const h of hostOverrides(parsed).hosts)
+        for (const id of endpointsFromHostLenient(h, anyDomain))
+            add(id);
+    const named = /(?:^|[^a-z0-9_])(?:endpoint|project)\s*[=:]\s*["']?(ep-[a-z0-9-]+)["']?/gi;
+    const routes = [...paramValues(parsed, 'options'), parsed.password, ...paramValues(parsed, 'password')];
+    for (const route of routes) {
+        for (const form of decodedForms(route)) {
+            for (const m of form.matchAll(named))
+                add(endpointFromLabel(m[1]));
+        }
+    }
+    return ids;
+}
+/** True when ANY endpoint the URL names ({@link neonEndpointIds}) is one of `ids`. */
+export function namesEndpoint(url, ids, options = {}) {
+    const wanted = ids.map((id) => endpointFromLabel(id.trim()) ?? id.trim().toLowerCase());
+    return neonEndpointIds(url, options).some((id) => wanted.includes(id));
+}
+/** The endpoint id of a host whose first label is one (`ep-quiet-sun-123-pooler.region.example` → `ep-quiet-sun-123`). */
+export function endpointOf(host) {
+    const first = host.toLowerCase().split('.')[0] ?? '';
+    if (!first.startsWith('ep-'))
+        return null;
+    return first.endsWith('-pooler') ? first.slice(0, -'-pooler'.length) : first;
+}
+/**
+ * Whether `host` is on a list of hosts and endpoint ids: an entry matches the host itself, any subdomain of it, and,
+ * for a host whose first label is an endpoint id, that endpoint with or without `-pooler`, on any domain.
+ */
+export function isListedHost(host, entries) {
+    const h = host.toLowerCase();
+    const endpoint = endpointOf(h);
+    return entries.some((raw) => {
+        const entry = raw.trim().toLowerCase();
+        if (entry === '')
+            return false;
+        if (h === entry || h.endsWith(`.${entry}`))
+            return true;
+        return endpoint !== null && endpointOf(entry) === endpoint;
+    });
+}
+/** A host-shaped run of a text: labels of letters, digits and `-`, joined by dots (`ep-…-pooler.c-1.example`, `ep-…`). */
+const HOST_TOKEN = /[a-z0-9-]+(?:\.[a-z0-9-]+)*/gi;
+/**
+ * A run of a text between the ASCII characters that end a host in a URL, a keyword/value string or a shell line. ASCII
+ * only: what a character outside ASCII does inside a host is the URL parser's to say, never a guess made here (U+FEFF
+ * is white space to a regular expression and nothing at all to a host).
+ */
+// eslint-disable-next-line no-control-regex -- the range is the point: every ASCII control character and the space
+const WORD = /[^\u0000-\u0020/?#@:=&,;'"`\\<>()[\]{}|^$!*+~]+/gu;
+/** A word that a special-scheme host reading would change: it holds an escape, or a character outside ASCII. */
+const MAPPABLE = /%|[^!-~]/u;
+/**
+ * Every text a client might resolve a host from: the value as written and percent-decoded, each also without the tabs
+ * and line breaks a URL parser drops from inside a host, and each of its words as a special-scheme host reads one (the
+ * IDNA mapping).
+ */
+function resolvableTexts(value) {
+    const texts = new Set();
+    for (const form of decodedForms(value).flatMap((f) => [f, f.replace(/[\t\n\r]/g, '')])) {
+        texts.add(form);
+        for (const word of form.matchAll(WORD)) {
+            if (!MAPPABLE.test(word[0]))
+                continue;
+            const mapped = specialSchemeHostname(word[0]);
+            if (mapped)
+                texts.add(mapped);
+            // A word no host reading takes whole (white space outside ASCII between two hosts) is read piece by piece.
+            if (!mapped)
+                for (const piece of word[0].split(/\s+/u))
+                    texts.add(specialSchemeHostname(piece) ?? piece);
+        }
+    }
+    return texts;
+}
+/**
+ * The entry of a list of hosts and endpoint ids that a value names, or null. One pass over every host-shaped token of
+ * every text a client might resolve from the value, so every connection-string shape counts: a URL (one host or
+ * several), a keyword/value string (`host=… dbname=…`), `PGHOST` (with a port), `PGOPTIONS endpoint=…`, a URL's
+ * `options=endpoint%3D…` or `?host=`, each as written, percent-encoded, or spelled with characters a URL host maps back
+ * to ASCII (fullwidth letters and hyphens, a soft hyphen, an ideographic full stop).
+ */
+export function listedEntryIn(value, entries) {
+    for (const text of resolvableTexts(value)) {
+        for (const token of text.matchAll(HOST_TOKEN)) {
+            const entry = entries.find((e) => isListedHost(token[0], [e]));
+            if (entry)
+                return entry.trim();
+        }
+    }
+    return null;
+}
+/**
+ * An app's guard, from its own ids: `const db = createEndpointGuard({ production: ['ep-…'], allowed: ['ep-…'] })`,
+ * then `db.namesProduction(url)` wherever production must be refused and `db.isAllowed(url)` where only the allowed
+ * endpoints may be used. An id that is not a bare `ep-…` id throws here, at load: a mistyped list guards nothing.
+ */
+export function createEndpointGuard(config) {
+    const bare = (id, list) => {
+        const read = typeof id === 'string' ? endpointFromLabel(id) : null;
+        if (read === null || read !== id)
+            throw new Error(`createEndpointGuard: an entry of ${list} is not a bare ep-… endpoint id`);
+        return read;
+    };
+    const production = Object.freeze(config.production.map((id) => bare(id, 'production')));
+    const allowed = Object.freeze((config.allowed ?? []).map((id) => bare(id, 'allowed')));
+    if (production.length === 0)
+        throw new Error('createEndpointGuard: production names no endpoint id');
+    if (allowed.some((id) => production.includes(id)))
+        throw new Error('createEndpointGuard: an allowed endpoint id is also a production one');
+    const options = { anyDomain: config.anyDomain === true };
+    const productionIn = (value) => {
+        if (typeof value !== 'string')
+            return null;
+        return listedEntryIn(value, production);
+    };
+    const endpointId = (url) => neonEndpointId(url, options);
+    return Object.freeze({
+        production,
+        allowed,
+        endpointId,
+        productionIn,
+        namesProduction: (value) => productionIn(value) !== null,
+        isAllowed: (url) => {
+            const id = endpointId(url);
+            return id !== null && allowed.includes(id) && productionIn(url) === null;
+        },
+    });
+}

package/dist/setup/README.md

@@ -29,7 +29,7 @@ A file that needs a DOM says so on its first line: `// @vitest-environment jsdom
 | Defaults | `environment: 'node'`, 30 s test and hook timeouts, `retry: 0` (a retry is refused), `server-only` resolves to an empty module, `*.pw.ts` is excluded, the kit's setup file runs first. A repo's own `include` replaces the kit's catch-all glob rather than joining it; every other list is merged. The config helper loads from a CommonJS `vitest.config.ts` too (a package without `"type": "module"`). |
 | Credentials | Every variable whose name holds `KEY`, `TOKEN`, `SECRET`, `DSN`, `PASSWORD`, `PASSWD`, `CREDENTIAL`, `PRIVATE`, `WEBHOOK`, `COOKIE`, `SESSION` or `AUTH`, and every variable whose value is a URL with a password, is deleted. `keepEnv` keeps names; `stripEnv` deletes more. Set the placeholders your code needs in your own setup file. |
 | Network | `fetch` and every TCP socket (`http`, `https`, `tls`, undici, database drivers) are refused unless the host is loopback, on `allowHosts` (`*.example.test` matches subdomains), or the host of a database URL that passed the check below (`allowDatabaseHosts`, default true). Only a URL the credential strip kept counts, so name the test database in `keepEnv` or set it in your own setup file. Neon's serverless HTTP driver sends a query to the region's gateway (`api.<region>.neon.tech`, the database named in a header), not to the database's host: a repo that runs it against a Neon branch lists that gateway in `allowHosts` itself, knowing it serves every database in the region (the credential strip is what keeps another database's password out). A refused request fails the test even when the code swallowed the error. `allowNetworkHosts(host)` adds one for the rest of a file. |
-| Production databases | A Postgres URL in the environment whose host is on your production list (a host, a subdomain of it, or a compute endpoint id `ep-…` with or without `-pooler`) is refused before any test runs, and again before the tests (your own setup file may set the URL). |
+| Production databases | A Postgres URL in the environment whose host is on your production list (a host, a subdomain of it, or a compute endpoint id `ep-…` with or without `-pooler`; in any spelling a client still resolves to it, such as percent-encoded, fullwidth `ｅｐ-…` or with a soft hyphen inside) is refused before any test runs, and again before the tests (your own setup file may set the URL). So is a URL that names an entry anywhere else in it (`?host=`, `options=endpoint%3D…`), and any value that holds a Postgres URL or opens with a Postgres scheme (`postgres:user:pw@host/db`) and names one anywhere in it, so a URL the parser rejects or a password with a quote or a space hides nothing. A keyword/value string (`host=… dbname=…`) is not read here: `tk-dev-guard` reads those. The refusal names the list entry, never the URL. |
 | `.env*` files | A Postgres URL in the environment that names the same database as any `.env*` file at the root is refused: those hold a developer's own connections. Every `postgres://` text counts, comments included, except lines keyed by `testDatabaseEnv`. |
 | React warnings | A React or Radix warning (`console.error` / `console.warn`) fails the test, also when the test muted the console (`vi.spyOn(console, 'error').mockImplementation(() => {})`, `console.error = vi.fn()`, `console.error = () => {}`). |
 | DOM files | Under jsdom: a `matchMedia` stub, `localStorage` / `sessionStorage` re-bound on Node 26, Testing Library's `cleanup` after each test (imported by the setup; with `domCleanup: 'deferred'`, after the first test instead, so a file can put React's devtools hook in place before react-dom loads), and jest-dom's matchers when installed. |

package/dist/setup/database.d.ts

@@ -1,3 +1,17 @@
+/**
+ * A host as a client resolves it, in ASCII where it has an ASCII reading: without the tab and line breaks a URL
+ * parser drops (dropped first, as it does, so one inside a `%XX` escape does not break the escape), then {@link mapped}. A `postgres:` URL keeps its host as written, but the Neon driver re-reads the string as an
+ * `http:` URL and node-postgres percent-decodes it, so `ｅｐ-…`, `e%70-…` and `ep-pr<soft hyphen>od-…` all connect to
+ * `ep-prod-…`. It drops more than a URL parser does (a guard errs on refusing).
+ */
+export declare function canonicalHost(text: string): string;
+/**
+ * Every reading of a text a host is looked for in: as written, mapped, and as {@link canonicalHost} reads it (a
+ * dropped character joins what stood on either side of it, which can hide a host as well as show one), and the last
+ * two without libpq's backslash escapes. Then the same of the text percent-decoded, up to three times: a route encoded
+ * twice (`options=endpoint%253D…`) is decoded by the client that reads the parameter.
+ */
+export declare function hostSpellings(text: string): string[];
 /** The endpoint id of a host whose first label is one (`ep-quiet-sun-123-pooler.region.example` → `ep-quiet-sun-123`). */
 export declare function endpointOf(host: string): string | null;
 /**
@@ -14,15 +28,33 @@ export declare function envFilesAt(root: string): string[];
  * `export KEY=…`, with or without spaces).
  */
 export declare function protectedPlaces(root: string, testDatabaseEnv?: readonly string[]): string[];
-/** Whether `host` is on the production list. */
+/** Whether `host` is on the production list, in any spelling a client resolves to a listed host ({@link hostReadings}). */
 export declare function isProductionHost(host: string, productionHosts: readonly string[]): boolean;
+/** A character outside ASCII. */
+export declare const NON_ASCII: RegExp;
+/**
+ * The production list entry a value names anywhere in it, or null. One pass over every host-shaped token of the value,
+ * in each of its {@link hostSpellings} (the characters a URL parser drops are dropped before the tokens are cut), so
+ * every connection-string shape counts: a URL (one host or several), its `?host=` and `options=endpoint%3D…`, a
+ * keyword/value string (`host=… dbname=…`), `PGHOST` (with a port), `PGOPTIONS endpoint=…`. A token of numbers alone is
+ * read as an address only where a host stands ({@link inHostPosition}): elsewhere it is a version or a count
+ * (`npm/10.8.2` is not `10.8.0.2`, `web@10.0.5` is not `10.0.0.5`).
+ */
+export declare function productionEntryIn(value: string, productionHosts: readonly string[]): string | null;
 export interface DatabaseRules {
     productionHosts: readonly string[];
     protectedPlaces: readonly string[];
 }
-/** Throws when `url` names a production host or a database a `.env*` file names. The message never carries the URL. */
+/**
+ * Throws when `url` names a production list entry (as its host, or anywhere else in it: `?host=`, `options=endpoint…`;
+ * also when it does not parse as a URL at all) or a database a `.env*` file names. The message carries the matched list entry, never the URL or any part of it.
+ */
 export declare function assertSafeDatabaseUrl(url: string, rules: DatabaseRules, label?: string): void;
-/** Runs {@link assertSafeDatabaseUrl} over every Postgres URL any variable of `env` holds. */
+/**
+ * Runs {@link assertSafeDatabaseUrl} over every Postgres URL any variable of `env` holds: in the value as written, and
+ * without the characters a URL parser drops (a tab, a line break, a zero-width no-break space), which would otherwise
+ * end the URL where one stands.
+ */
 export declare function assertSafeDatabaseEnv(env: NodeJS.ProcessEnv, rules: DatabaseRules): void;
 /** The hosts of every Postgres URL `env` holds: what the network guard lets through once the URLs passed the check. */
 export declare function databaseHostsIn(env: NodeJS.ProcessEnv): string[];