@catalystiq/test-kit 0.3.2 → 0.4.0

package/dist/setup/database.js

@@ -3,7 +3,8 @@
  *
  * 1. A database URL in the test environment whose host is on the repo's production list is refused. An entry matches the
  *    host itself, any subdomain of it, and, for a host whose first label is a compute endpoint id (`ep-…`), that
- *    endpoint with or without its `-pooler` suffix.
+ *    endpoint with or without its `-pooler` suffix. A host is read in every spelling a client resolves
+ *    (`canonicalHost`): percent-encoded, in fullwidth letters, with a soft hyphen inside.
  * 2. A database URL in the test environment that names the same database as any `.env*` file at the repo root is
  *    refused: those files hold a developer's own (perhaps production) connection, and a test must never reach it. Every
  *    `postgres://` text in the files counts, in any variable, quoted any way, or in a comment, except the lines whose key
@@ -14,10 +15,80 @@ import { join } from 'node:path';
 const LOOPBACK = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
 /** A Postgres URL anywhere in a text. */
 const POSTGRES_URL = /postgres(?:ql)?:\/\/[^\s'"`]+/gi;
+/** A value that holds a Postgres URL, or opens with a Postgres scheme however it goes on (`postgres:user:pw@host/db`). */
+const HOLDS_SCHEME = /postgres(?:ql)?:\/\/|^postgres(?:ql)?:/i;
+/** A value without the white space and control characters it opens with, which a URL parser drops there. */
+function withoutLeadingControls(value) {
+    let start = 0;
+    while (start < value.length && value.charCodeAt(start) <= 0x20)
+        start++;
+    return value.slice(start);
+}
 /** The text's own punctuation after a URL is not part of it: `(postgres://h/db)` names `db`. */
 function trimmedUrl(match) {
     return match.replace(/[)>,;.]+$/, '');
 }
+/** The code points IDNA mapping ignores, so a host holding one resolves without it: a soft hyphen, a zero-width space. */
+const IGNORED = /\p{Default_Ignorable_Code_Point}/gu;
+/** The ideographic full stop, which IDNA mapping reads as a dot (NFKC has already made the fullwidth and halfwidth ones a dot or this). */
+const FULL_STOPS = /\u3002/g;
+/** The tab and line breaks a URL parser drops from anywhere in a URL, before it reads anything else. */
+const URL_DROPPED = /[\t\n\r]/g;
+/** A text with each run of `%XX` escapes decoded as UTF-8, so one malformed `%` elsewhere cannot hide the rest. */
+function percentDecoded(text) {
+    return text.replace(/(?:%[0-9a-f]{2})+/gi, (run) => Buffer.from(run.replaceAll('%', ''), 'hex').toString('utf8'));
+}
+/** A text percent-decoded and IDNA-mapped, near enough: compatibility forms as ASCII (a fullwidth `ｅｐ－` is `ep-`), lowercased. */
+function mapped(text) {
+    return percentDecoded(text).normalize('NFKC').replace(IGNORED, '').replace(FULL_STOPS, '.').toLowerCase();
+}
+/**
+ * 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 function canonicalHost(text) {
+    return mapped(text.replace(URL_DROPPED, '')).replace(URL_DROPPED, '');
+}
+/** A backslash escape of a libpq keyword/value string (`host=e\p-…`, `host='ep\-…'`): the client reads the character after it. */
+const LIBPQ_ESCAPE = /\\([^\\])/g;
+/**
+ * A host as an `http:` URL reads it, or null: an IPv4 address in any numeric spelling as dotted decimal (`0x0a.0.0.5`,
+ * `167772165` and `10.5` are `10.0.0.5`), an internationalised name in its `xn--` form. Only a bare host is read.
+ */
+function urlHost(host) {
+    if (host === '' || /[\s/?#@\\:[\]%]/.test(host))
+        return null;
+    try {
+        return new URL(`http://${host}/`).hostname || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 function hostSpellings(text) {
+    const spellings = new Set();
+    let form = text;
+    for (let round = 0; round < 4; round++) {
+        spellings.add(form);
+        for (const text of new Set([form, form.replace(LIBPQ_ESCAPE, '$1')])) {
+            for (const spelling of [mapped(text), canonicalHost(text)])
+                spellings.add(spelling);
+        }
+        const next = percentDecoded(form);
+        if (next === form)
+            break;
+        form = next;
+    }
+    return [...spellings];
+}
 /** 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] ?? '';
@@ -25,6 +96,15 @@ export function endpointOf(host) {
         return null;
     return first.endsWith('-pooler') ? first.slice(0, -'-pooler'.length) : first;
 }
+/** A URL part percent-decoded, or as written when an escape in it is malformed (`app_%s`, a template). */
+function decodedOrAsWritten(part) {
+    try {
+        return decodeURIComponent(part);
+    }
+    catch {
+        return part;
+    }
+}
 /**
  * The one database a URL names, as a comparable key: `endpoint:<id>` for an endpoint host, else
  * `<host>:<port>/<database>` with every loopback name read as `localhost`. Null when the text is not a Postgres URL.
@@ -39,11 +119,11 @@ export function databasePlace(url) {
     }
     if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:')
         return null;
-    const host = parsed.hostname.toLowerCase();
+    const host = canonicalHost(parsed.hostname);
     const endpoint = endpointOf(host);
     if (endpoint)
         return `endpoint:${endpoint}`;
-    const database = decodeURIComponent(parsed.pathname.replace(/^\//, '')) || decodeURIComponent(parsed.username) || 'postgres';
+    const database = decodedOrAsWritten(parsed.pathname.replace(/^\//, '')) || decodedOrAsWritten(parsed.username) || 'postgres';
     return `${LOOPBACK.has(host) || host === '' ? 'localhost' : host}:${parsed.port || '5432'}/${database}`;
 }
 /** Every Postgres URL in a text. */
@@ -78,40 +158,159 @@ export function protectedPlaces(root, testDatabaseEnv = []) {
     }
     return [...places].sort();
 }
-/** Whether `host` is on the production list. */
-export function isProductionHost(host, productionHosts) {
-    const h = host.toLowerCase();
-    const endpoint = endpointOf(h);
-    return productionHosts.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 whose every label is a number: an IPv4 address in some form, or a version, a port, a count. */
+const NUMERIC_HOST = /^(?:0x[0-9a-f]*|\d+)(?:\.(?:0x[0-9a-f]*|\d+))*$/i;
+/**
+ * Every reading of one host: each of its {@link hostSpellings} lowercased, and as an `http:` URL reads it (before and
+ * after lowercasing: a capital sigma lowercases by its position, and a URL maps it its own way). A trailing dot is the
+ * same name, fully qualified. With `numeric` false a host of numbers alone is not read as an address.
+ */
+function hostReadings(host, numeric) {
+    const readings = new Set();
+    for (const spelling of hostSpellings(host)) {
+        const written = spelling.replace(/\.+$/, '');
+        const lower = written.toLowerCase();
+        readings.add(lower);
+        for (const form of new Set([written, lower])) {
+            if (!numeric && NUMERIC_HOST.test(form))
+                continue;
+            const read = urlHost(form);
+            if (read)
+                readings.add(read);
+        }
+    }
+    return [...readings];
+}
+/** Each list entry with the forms it is compared in: as written and as a URL reads it (a name in its `xn--` form). */
+function listedForms(productionHosts) {
+    return productionHosts
+        .map((raw) => raw.trim())
+        .filter((entry) => entry !== '')
+        .map((entry) => {
+        const lower = entry.toLowerCase();
+        return { entry, forms: [...new Set([lower, urlHost(entry) ?? lower])] };
     });
 }
-/** Throws when `url` names a production host or a database a `.env*` file names. The message never carries the URL. */
+/** The list entry one of a host's readings is: the host itself, a subdomain of it, or the same endpoint id. */
+function entryOf(readings, listed) {
+    for (const h of readings) {
+        const endpoint = endpointOf(h);
+        for (const { entry, forms } of listed) {
+            if (forms.some((form) => h === form || h.endsWith(`.${form}`) || (endpoint !== null && endpointOf(form) === endpoint)))
+                return entry;
+        }
+    }
+    return null;
+}
+/** Whether `host` is on the production list, in any spelling a client resolves to a listed host ({@link hostReadings}). */
+export function isProductionHost(host, productionHosts) {
+    return entryOf(hostReadings(host, true), listedForms(productionHosts)) !== null;
+}
+/** A host-shaped run of a value: 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 character outside ASCII. */
+export const NON_ASCII = /[\u0080-\u{10ffff}]/u;
+/**
+ * The same with any character outside ASCII in its labels: an internationalised name, which a client resolves in its
+ * `xn--` form. Any character, not letters alone: a name may hold a middle dot or a zero-width non-joiner.
+ */
+const UNICODE_HOST_TOKEN = /(?:[a-z0-9-]|[\u0080-\u{10ffff}])+(?:\.(?:[a-z0-9-]|[\u0080-\u{10ffff}])+)*/giu;
+/**
+ * Where a host stands: after a URL's `//` or `\\`, after a Postgres scheme and one slash, as a keyword/value
+ * string's `host=` or `hostaddr=`, or after another host of a list (`db.example:5432,`).
+ */
+const HOST_POSITION = /(?:[/\\]{2}|postgres(?:ql)?:[/\\]|host(?:addr)?\s*=\s*['"]?|[a-z](?::\d+)?,)$/i;
+/** Straight after a Postgres scheme: a host when a path, a port or a query follows it (`postgres:10.5/db`), else an image tag (`postgres:10.5`). */
+const SCHEME_BEFORE = /postgres(?:ql)?:$/i;
+/** The text before a URL's `@`, back to the last white space: a URL's own (`//`, a Postgres scheme), not `name@1.2.3`. */
+const URL_BEFORE_AT = /(?:[/\\]{2}|postgres(?:ql)?:)\S*@$/i;
+/** Whether the token at `index` of `text` stands where a host does. */
+function inHostPosition(text, index, length) {
+    const before = text.slice(Math.max(0, index - 512), index);
+    if (SCHEME_BEFORE.test(before))
+        return /^[/\\:?]/.test(text.slice(index + length));
+    return HOST_POSITION.test(before) || URL_BEFORE_AT.test(before);
+}
+/**
+ * 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 function productionEntryIn(value, productionHosts) {
+    const listed = listedForms(productionHosts);
+    const seen = new Set();
+    for (const text of hostSpellings(value)) {
+        const tokens = [...text.matchAll(HOST_TOKEN)];
+        // Only a token with a character outside ASCII is new here: the rest are the tokens above.
+        for (const m of text.matchAll(UNICODE_HOST_TOKEN))
+            if (NON_ASCII.test(m[0]))
+                tokens.push(m);
+        for (const m of tokens) {
+            const numeric = NUMERIC_HOST.test(m[0]) && inHostPosition(text, m.index, m[0].length);
+            const key = `${numeric ? 1 : 0}${m[0]}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const entry = entryOf(hostReadings(m[0], numeric), listed);
+            if (entry)
+                return entry;
+        }
+    }
+    return null;
+}
+/** The refusal of a production database: it carries the matched list entry, never the value or any part of it. */
+function productionRefusal(label, entry) {
+    return new Error(`test-kit: ${label} names a PRODUCTION database host (${entry}). Tests never connect to production.`);
+}
+/**
+ * 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 function assertSafeDatabaseUrl(url, rules, label = 'a database URL') {
-    const place = databasePlace(url);
-    if (place === null)
-        return;
-    const host = new URL(url).hostname;
-    if (isProductionHost(host, rules.productionHosts)) {
-        throw new Error(`test-kit: ${label} names a PRODUCTION database host (${host}). Tests never connect to production.`);
+    // The host as a postgres: URL holds it and as an http: URL reads the same string, which is how the Neon driver
+    // reads it: a backslash ends the host there (`prod\@other` is `prod`), and `postgres:///host` has one.
+    const hosts = [];
+    for (const reading of [url, url.replace(/^[a-z][a-z0-9+.-]*:/i, 'http:')]) {
+        try {
+            hosts.push(new URL(reading).hostname);
+        }
+        catch {
+            // A reading that does not parse names no host; the search below still reads the text.
+        }
     }
-    if (rules.protectedPlaces.includes(place)) {
+    const listed = listedForms(rules.productionHosts);
+    const entry = entryOf(hosts.filter((host) => host !== '').flatMap((host) => hostReadings(host, true)), listed) ?? productionEntryIn(url, rules.productionHosts);
+    if (entry)
+        throw productionRefusal(label, entry);
+    const place = databasePlace(url);
+    if (place !== null && rules.protectedPlaces.includes(place)) {
         throw new Error(`test-kit: ${label} names the same database as a .env* file at the repository root. ` +
             'A test database must be its own (a container, or a branch made for the run).');
     }
 }
-/** 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 function assertSafeDatabaseEnv(env, rules) {
     for (const [name, value] of Object.entries(env)) {
         if (!value)
             continue;
-        for (const url of postgresUrlsIn(value))
-            assertSafeDatabaseUrl(url, rules, `$${name}`);
+        for (const text of new Set([value, value.replace(URL_DROPPED, '').replace(IGNORED, '')])) {
+            for (const url of postgresUrlsIn(text))
+                assertSafeDatabaseUrl(url, rules, `$${name}`);
+        }
+        // The scan above ends a URL at a quote or a space (a password may hold one) and reads no scheme without `//`
+        // (`postgres:u:p@host/db`, which an `http:` reading still resolves): the whole of such a value is searched too.
+        if (HOLDS_SCHEME.test(withoutLeadingControls(value.replace(URL_DROPPED, '').replace(IGNORED, '')))) {
+            const entry = productionEntryIn(value, rules.productionHosts);
+            if (entry)
+                throw productionRefusal(`$${name}`, entry);
+        }
     }
 }
 /** The hosts of every Postgres URL `env` holds: what the network guard lets through once the URLs passed the check. */
@@ -125,6 +324,9 @@ export function databaseHostsIn(env) {
                 const host = new URL(url).hostname;
                 if (host)
                     hosts.add(host.toLowerCase());
+                // The same host as the clients resolve it, which is where the socket goes.
+                if (host)
+                    hosts.add(canonicalHost(host));
             }
             catch {
                 // not a URL after all

package/dist/setup/network.js

@@ -57,7 +57,7 @@ export function installNetworkGuard(allowHosts = []) {
         s.realFetch = realFetch;
         const guardedFetch = (async (input, init) => {
             const url = requestUrl(input);
-            let host = '';
+            let host;
             try {
                 const parsed = new URL(url);
                 if (parsed.protocol === 'data:' || parsed.protocol === 'blob:')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalystiq/test-kit",
-  "version": "0.3.2",
-  "description": "Shared test setup for Vitest, a fake MCP Apps host for jsdom and Playwright, the local Neon test-database run, and the local environment guard.",
+  "version": "0.4.0",
+  "description": "Shared test setup for Vitest, a fake MCP Apps host for jsdom and Playwright, the local Neon test-database run, the local environment guard, the database endpoint reader and the install hardening check.",
   "type": "module",
   "license": "MIT",
   "sideEffects": true,
@@ -42,6 +42,15 @@
       "types": "./dist/env/index.d.ts",
       "import": "./dist/env/index.js"
     },
+    "./neon-endpoint": {
+      "types": "./dist/neon-endpoint/index.d.ts",
+      "import": "./dist/neon-endpoint/index.js",
+      "default": "./dist/neon-endpoint/index.js"
+    },
+    "./install": {
+      "types": "./dist/install/index.d.ts",
+      "import": "./dist/install/index.js"
+    },
     "./neon-test-db": {
       "types": "./dist/neon-test-db/neon-test-db.d.mts",
       "import": "./dist/neon-test-db/neon-test-db.mjs"
@@ -53,6 +62,7 @@
     "tk-check-allowlist": "dist/bin/check-allowlist.js",
     "tk-dev-guard": "dist/bin/dev-guard.js",
     "tk-check-env-example": "dist/bin/check-env-example.js",
+    "tk-check-install-scripts": "dist/bin/check-install-scripts.js",
     "tk-neon-test-db": "dist/neon-test-db/neon-test-db.mjs"
   },
   "files": [
@@ -94,7 +104,7 @@
     }
   },
   "devDependencies": {
-    "@eslint/js": "9.39.5",
+    "@eslint/js": "10.0.1",
     "@modelcontextprotocol/client": "2.4.0",
     "@modelcontextprotocol/core": "2.4.0",
     "@modelcontextprotocol/ext-apps": "2.0.4",
@@ -107,7 +117,7 @@
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "esbuild": "0.28.2",
-    "eslint": "9.39.5",
+    "eslint": "10.12.0",
     "jsdom": "30.1.3",
     "react": "19.3.1",
     "react-dom": "19.3.1",