@catalystiq/test-kit 0.3.1 → 0.4.0

package/dist/install/index.js

@@ -0,0 +1,460 @@
+/**
+ * The install hardening every getcatalystiq app keeps, checked from the app's own files (`tk-check-install-scripts`,
+ * or {@link checkInstallHardening} from a test):
+ *
+ *  - package.json's `allowScripts` names exactly the locked packages that have an install script, each `true` (run) or
+ *    `false` (skipped), and the ones that run are the ones the app says run;
+ *  - `.npmrc` sets `min-release-age` and `strict-allow-scripts=true` (and no `legacy-peer-deps`), the npm on PATH knows
+ *    both keys and takes them from the project's file, and it refuses an install whose tree has a script the list does
+ *    not name, before running it;
+ *  - the lockfile pins every package it fetches by registry URL and sha512;
+ *  - the app's npm floor script (run before `npm ci` where no CI job watches the install) admits the floor and refuses
+ *    anything older, a prerelease and a string that is no version, and the host's install command runs it first;
+ *  - npm is the package manager: one lockfile, version 3, tracked; `packageManager` names an npm the floor admits, and
+ *    under `.nvmrc`'s own Node exactly the npm in use.
+ *
+ * It reports what is wrong, one line each, and what it could not check (`skipped`): a check that did not run is never
+ * reported as passed. It reads files and runs `npm`, `node` and `git`; it imports no test runner.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, dirname, join, resolve } from 'node:path';
+/** The names of the locked packages that run an install script. */
+export function withInstallScripts(lock) {
+    const names = new Set();
+    for (const [path, entry] of Object.entries(lock.packages ?? {})) {
+        if (path === '' || entry.link || !entry.hasInstallScript)
+            continue;
+        // A path with no node_modules/ segment (a workspace folder) has no name to cut from it.
+        const at = path.lastIndexOf('node_modules/');
+        names.add(entry.name ?? (at === -1 ? path : path.slice(at + 'node_modules/'.length)));
+    }
+    return [...names].sort();
+}
+/** What is wrong between a lockfile and an `allowScripts`, one line each. */
+export function scriptProblems(lock, allow) {
+    const problems = [];
+    const needed = withInstallScripts(lock);
+    for (const name of needed) {
+        if (!Object.hasOwn(allow, name))
+            problems.push(`unreviewed install script: ${name} (name it in package.json allowScripts, true or false)`);
+    }
+    for (const [key, value] of Object.entries(allow)) {
+        if (typeof value !== 'boolean')
+            problems.push(`allowScripts.${key} is not true or false`);
+        if (!needed.includes(key))
+            problems.push(`stale allowScripts entry: ${key} (no locked package of that name has an install script)`);
+    }
+    return problems;
+}
+/** The lockfile paths npm would fetch that are not pinned to `registry` and a sha512. */
+export function unpinnedPackages(lock, registry = 'https://registry.npmjs.org/') {
+    const loose = [];
+    for (const [path, entry] of Object.entries(lock.packages ?? {})) {
+        // The root, workspace links and a tarball's own bundled packages are never fetched on their own.
+        if (path === '' || entry.link || entry.inBundle)
+            continue;
+        if (!entry.resolved?.startsWith(registry) || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(entry.integrity ?? ''))
+            loose.push(path);
+    }
+    return loose;
+}
+/** `X.Y.Z` as numbers, or null: a prerelease (`11.19.1-rc.0`) is below its release, and anything else is no version. */
+export function releaseVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+/** Whether `version` is a release at or above `floor`. */
+export function atLeast(version, floor) {
+    const have = releaseVersion(version);
+    const want = releaseVersion(floor);
+    if (!have || !want)
+        return false;
+    for (let i = 0; i < 3; i += 1) {
+        if (have[i] !== want[i])
+            return have[i] > want[i];
+    }
+    return true;
+}
+/** The versions a floor script must admit and refuse, from the floor itself. */
+export function floorCases(floor, prereleases = true) {
+    const parts = releaseVersion(floor);
+    if (!parts)
+        throw new Error(`the npm floor ${JSON.stringify(floor)} is not an X.Y.Z version`);
+    const [major, minor, patch] = parts;
+    const admitted = [floor, `${major}.${minor + 1}.0`, `${major + 1}.0.0`];
+    const refused = ['not-a-version'];
+    if (patch > 0)
+        refused.push(`${major}.${minor}.${patch - 1}`);
+    if (minor > 0)
+        refused.push(`${major}.${minor - 1}.99`);
+    if (major > 0)
+        refused.push(`${major - 1}.99.0`);
+    if (prereleases)
+        refused.push(`${floor}-rc.0`, `${major + 1}.0.0-pre`);
+    return { admitted, refused };
+}
+/** The settings of an `.npmrc` text, by key, as written (comments and blank lines left out; the last one wins). */
+export function npmrcSettings(text) {
+    const settings = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*([^#;=\s][^=]*?)\s*=\s*(.*?)\s*$/.exec(line);
+        if (match)
+            settings[match[1].toLowerCase()] = match[2];
+    }
+    return settings;
+}
+/** The environment without npm's own `npm_config_*` variables, which npm exports to the scripts it runs. */
+function withoutNpmConfig(env) {
+    return Object.fromEntries(Object.entries(env).filter(([key]) => !/^npm_config_/i.test(key)));
+}
+function readJson(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+function withTempDir(prefix, run) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    try {
+        return run(dir);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** The floor script's verdict under an `npm` that answers `version`: admitted, refused (its own refusal), or a crash. */
+function floorVerdict(script, version, env) {
+    return withTempDir('tk-npm-floor-', (dir) => {
+        // The version reaches the stub as data (an environment variable), never as shell text.
+        writeFileSync(join(dir, 'npm'), '#!/bin/sh\nprintf \'%s\\n\' "$TK_FAKE_NPM_VERSION"\n');
+        chmodSync(join(dir, 'npm'), 0o755);
+        const run = spawnSync(process.execPath, [script], {
+            env: { ...env, TK_FAKE_NPM_VERSION: version, PATH: `${dir}${delimiter}${env.PATH ?? ''}` },
+            encoding: 'utf8',
+        });
+        if (run.status === 0)
+            return 'admitted';
+        // A crash exits 1 too: only the script's own refusal counts as one.
+        if (run.status === 1 && /is older than/.test(run.stderr))
+            return 'refused';
+        return `it failed (${run.status ?? run.error?.message ?? 'no status'}): ${run.stderr.trim().split('\n').at(-1) ?? ''}`;
+    });
+}
+/** Every check, over the app at `root`. See the module header and {@link InstallCheckOptions}. */
+export function checkInstallHardening(root, options = {}) {
+    const problems = [];
+    const skipped = [];
+    const env = withoutNpmConfig(options.env ?? process.env);
+    const floor = options.npmFloor ?? '11.19.1';
+    const floorScript = options.floorScript === undefined ? 'scripts/check-npm-version.mjs' : options.floorScript;
+    const minReleaseAge = String(options.minReleaseAge ?? 1);
+    let manifest;
+    let lock;
+    try {
+        manifest = readJson(join(root, 'package.json'));
+        lock = readJson(join(root, 'package-lock.json'));
+    }
+    catch (error) {
+        return { problems: [`package.json or package-lock.json could not be read: ${error.message}`], skipped, scripts: [] };
+    }
+    // 1. allowScripts against the lockfile.
+    const scripts = withInstallScripts(lock);
+    const allow = manifest.allowScripts;
+    const allowed = allow !== null && typeof allow === 'object' && !Array.isArray(allow) ? allow : {};
+    if (allow !== undefined && allowed !== allow)
+        problems.push('package.json allowScripts is not an object of package names');
+    const minScripts = options.minScripts ?? 1;
+    if (scripts.length < minScripts) {
+        problems.push(`the lockfile has ${scripts.length} packages with an install script, fewer than the ${minScripts} expected: it proves nothing about allowScripts`);
+    }
+    problems.push(...scriptProblems(lock, allowed));
+    if (options.run !== undefined) {
+        const runs = Object.entries(allowed)
+            .filter(([, value]) => value === true)
+            .map(([name]) => name)
+            .sort();
+        const expected = [...options.run].sort();
+        if (JSON.stringify(runs) !== JSON.stringify(expected)) {
+            problems.push(`allowScripts runs [${runs.join(', ')}], not the reviewed [${expected.join(', ')}]: every other install script is skipped (false)`);
+        }
+    }
+    // 2. The pinned npx lines and local tools.
+    const devDependencies = (manifest.devDependencies ?? {});
+    for (const name of options.requireDevDependencies ?? []) {
+        if (!Object.hasOwn(devDependencies, name))
+            problems.push(`${name} is not a devDependency (an npx of a package the lockfile does not hold meets the install-script refusal)`);
+    }
+    const manifestScripts = (manifest.scripts ?? {});
+    for (const [name, text] of Object.entries(options.requireScripts ?? {})) {
+        if (manifestScripts[name] !== text)
+            problems.push(`package.json scripts.${name} is not ${JSON.stringify(text)}`);
+    }
+    // 3. .npmrc, as written.
+    let npmrc = null;
+    try {
+        npmrc = readFileSync(join(root, '.npmrc'), 'utf8');
+    }
+    catch {
+        problems.push('.npmrc could not be read: min-release-age and strict-allow-scripts are unset');
+    }
+    if (npmrc !== null) {
+        const settings = npmrcSettings(npmrc);
+        if (settings['min-release-age'] !== minReleaseAge)
+            problems.push(`.npmrc does not set min-release-age=${minReleaseAge}`);
+        if (settings['strict-allow-scripts'] !== 'true')
+            problems.push('.npmrc does not set strict-allow-scripts=true');
+        if (!options.allowLegacyPeerDeps && Object.hasOwn(settings, 'legacy-peer-deps')) {
+            problems.push('.npmrc sets legacy-peer-deps: a peer conflict is fixed by the versions, never by ignoring peers');
+        }
+    }
+    // 4. The lockfile's pins.
+    if (options.lockfilePins ?? true) {
+        const loose = unpinnedPackages(lock, options.registry);
+        if (loose.length > 0)
+            problems.push(`the lockfile does not pin by registry URL and sha512: ${loose.slice(0, 5).join(', ')}${loose.length > 5 ? ` and ${loose.length - 5} more` : ''}`);
+    }
+    // 5. npm is the package manager.
+    if (lock.lockfileVersion !== 3)
+        problems.push(`package-lock.json is lockfileVersion ${String(lock.lockfileVersion)}, not 3`);
+    if (manifest.pnpm !== undefined)
+        problems.push('package.json still has a pnpm key');
+    const git = spawnSync('git', ['ls-files'], { cwd: root, env, encoding: 'utf8' });
+    if (git.status !== 0) {
+        problems.push('git ls-files failed, so the tracked lockfiles are unknown');
+    }
+    else {
+        const tracked = git.stdout.split('\n').filter(Boolean);
+        const others = tracked.filter((file) => /(?:^|\/)(?:pnpm-lock\.yaml|pnpm-workspace\.yaml|yarn\.lock|bun\.lockb?|npm-shrinkwrap\.json)$/.test(file));
+        if (others.length > 0)
+            problems.push(`another package manager's file is tracked: ${others.join(', ')}`);
+        if (!tracked.includes('package-lock.json'))
+            problems.push('package-lock.json is not tracked');
+    }
+    // 6. The floor script, and the install command that runs it.
+    if (floorScript === null) {
+        skipped.push('the npm floor script: the app has none (floorScript: null)');
+    }
+    else if (!existsSync(join(root, floorScript))) {
+        problems.push(`${floorScript} does not exist: nothing refuses an npm too old to read allowScripts`);
+    }
+    else {
+        const cases = floorCases(floor, options.prereleaseBelowRelease ?? true);
+        for (const [versions, want] of [[cases.admitted, 'admitted'], [cases.refused, 'refused']]) {
+            for (const version of versions) {
+                const verdict = floorVerdict(join(root, floorScript), version, env);
+                if (verdict !== want) {
+                    problems.push(`${floorScript} under npm ${version}: ${verdict === 'admitted' || verdict === 'refused' ? `${verdict}, not ${want}` : verdict}`);
+                }
+            }
+        }
+    }
+    const installCommand = options.installCommand === undefined ? (floorScript === null ? null : `node ${floorScript} && npm ci`) : options.installCommand;
+    if (installCommand !== null) {
+        let found;
+        try {
+            found = readJson(join(root, 'vercel.json')).installCommand;
+        }
+        catch {
+            found = undefined;
+        }
+        if (found !== installCommand)
+            problems.push(`vercel.json installCommand is not ${JSON.stringify(installCommand)}`);
+    }
+    // 7. packageManager.
+    const declared = /^npm@(\d+\.\d+\.\d+)(?:\+sha\d+\.[0-9a-f]+)?$/.exec(typeof manifest.packageManager === 'string' ? manifest.packageManager : '');
+    if (!declared) {
+        problems.push('package.json packageManager is not npm@X.Y.Z');
+    }
+    else if (!atLeast(declared[1], floor)) {
+        problems.push(`package.json packageManager names npm ${declared[1]}, below the floor ${floor}`);
+    }
+    const npmOnPath = spawnSync('npm', ['--version'], { cwd: root, env, encoding: 'utf8' });
+    const npmVersion = npmOnPath.status === 0 ? npmOnPath.stdout.trim() : null;
+    const mode = options.packageManager ?? 'path';
+    if (declared && mode !== 'declared') {
+        let nvmrc = null;
+        try {
+            nvmrc = readFileSync(join(root, '.nvmrc'), 'utf8').trim().replace(/^v/, '');
+        }
+        catch {
+            problems.push('.nvmrc could not be read, so packageManager cannot be held to its Node\'s npm');
+        }
+        const bundled = join(dirname(process.execPath), '..', 'lib', 'node_modules', 'npm', 'package.json');
+        if (nvmrc !== null && process.version !== `v${nvmrc}`) {
+            skipped.push(`packageManager against the npm in use: this is Node ${process.version}, not .nvmrc's ${nvmrc}`);
+        }
+        else if (nvmrc !== null && mode === 'bundled' && !existsSync(bundled)) {
+            skipped.push('packageManager against the bundled npm: this Node ships none beside its binary');
+        }
+        else if (nvmrc !== null) {
+            const inUse = mode === 'bundled' ? readJson(bundled).version : npmVersion;
+            if (inUse !== declared[1]) {
+                problems.push(`package.json packageManager names npm ${declared[1]}, but ${mode === 'bundled' ? `Node ${nvmrc} ships` : 'the npm on PATH is'} ${inUse ?? 'unreadable'}`);
+            }
+        }
+    }
+    // 8. npm itself: it knows the two keys, takes them from the project, and refuses an unnamed script.
+    const probes = options.npmProbes ?? 'required';
+    if (probes === 'off') {
+        skipped.push('the npm checks (config keys, the strict-allow-scripts refusal): npmProbes is off');
+    }
+    else if (npmVersion === null || !atLeast(npmVersion, floor)) {
+        const why = `the npm on PATH is ${npmVersion ?? 'not runnable'}, below ${floor}, which ignores allowScripts and strict-allow-scripts`;
+        if (probes === 'required')
+            problems.push(`the npm checks did not run: ${why}`);
+        else
+            skipped.push(`the npm checks (config keys, the strict-allow-scripts refusal): ${why}`);
+    }
+    else if (npmrc !== null) {
+        problems.push(...npmProbeProblems(root, npmrc, env, minReleaseAge, options.allowLegacyPeerDeps === true));
+    }
+    return { problems, skipped, scripts };
+}
+/** What npm itself says about the project's `.npmrc`: asked with an empty user and global config, so only it answers. */
+function npmProbeProblems(root, npmrc, env, minReleaseAge, allowLegacyPeerDeps) {
+    return withTempDir('tk-npm-config-', (dir) => {
+        const problems = [];
+        writeFileSync(join(dir, 'user'), '');
+        writeFileSync(join(dir, 'global'), '');
+        const projectOnly = { ...env, NPM_CONFIG_USERCONFIG: join(dir, 'user'), NPM_CONFIG_GLOBALCONFIG: join(dir, 'global') };
+        // `npm config get` echoes a key npm does not know (with only a warning), so the value is not read back: npm's own
+        // list prints each known key's default, commented out where a config file overrides it, and then the file's value.
+        let list = '';
+        try {
+            list = execFileSync('npm', ['config', 'ls', '-l'], { cwd: root, env: projectOnly, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch (error) {
+            problems.push(`npm config ls -l failed: ${error.message.split('\n')[0]}`);
+        }
+        for (const [key, value] of [['min-release-age', minReleaseAge], ['strict-allow-scripts', 'true']]) {
+            const overridden = new RegExp(`^; ${key} = .* ; overridden by project$`, 'm');
+            const set = new RegExp(`^${key} = ${value}$`, 'm');
+            if (!overridden.test(list) || !set.test(list))
+                problems.push(`npm does not read ${key}=${value} from the project's .npmrc (an unknown key, or another config file's value)`);
+        }
+        if (!allowLegacyPeerDeps) {
+            const legacy = spawnSync('npm', ['config', 'get', 'legacy-peer-deps'], { cwd: root, env: projectOnly, encoding: 'utf8' });
+            if (legacy.stdout.trim() !== 'false')
+                problems.push('npm reads legacy-peer-deps as on for this project');
+        }
+        // The policy itself: a tree with a script allowScripts does not name is refused before anything runs.
+        const probe = join(dir, 'probe');
+        mkdirSync(join(probe, 'dep'), { recursive: true });
+        writeFileSync(join(probe, '.npmrc'), npmrc);
+        writeFileSync(join(probe, 'dep', 'package.json'), JSON.stringify({ name: 'dep', version: '1.0.0', scripts: { postinstall: "node -e \"require('fs').writeFileSync('../ran', '')\"" } }));
+        writeFileSync(join(probe, 'package.json'), JSON.stringify({ name: 'probe', version: '1.0.0', dependencies: { dep: 'file:./dep' } }));
+        const install = spawnSync('npm', ['install', '--offline', '--no-audit', '--no-fund'], { cwd: probe, env: projectOnly, encoding: 'utf8' });
+        if (install.status === 0 || !/ESTRICTALLOWSCRIPTS/.test(install.stderr)) {
+            problems.push("npm did not refuse (ESTRICTALLOWSCRIPTS) an install whose tree has a script allowScripts does not name, under the project's .npmrc");
+        }
+        if (existsSync(join(probe, 'ran')))
+            problems.push("npm ran an install script allowScripts does not name, under the project's .npmrc");
+        return problems;
+    });
+}
+export const INSTALL_CHECK_USAGE = 'usage: tk-check-install-scripts [--root <dir>] [--run <package>]... [--run-none] [--min-scripts <n>] [--min-release-age <days>]\n' +
+    '  [--npm-floor <X.Y.Z>] [--floor-script <path> | --no-floor-script] [--install-command <text> | --no-install-command]\n' +
+    '  [--package-manager path|bundled|declared] [--npm-probes required|when-supported|off] [--require-dev <package>]...\n' +
+    '  [--require-script <name>=<text>]... [--registry <url>] [--allow-legacy-peer-deps] [--no-lockfile-pins] [--no-prerelease-cases]';
+const VALUE_FLAGS = [
+    '--root',
+    '--run',
+    '--min-scripts',
+    '--min-release-age',
+    '--npm-floor',
+    '--floor-script',
+    '--install-command',
+    '--package-manager',
+    '--npm-probes',
+    '--require-dev',
+    '--require-script',
+    '--registry',
+];
+const SWITCHES = ['--run-none', '--no-floor-script', '--no-install-command', '--allow-legacy-peer-deps', '--no-lockfile-pins', '--no-prerelease-cases'];
+/** The bin's arguments as a root and options. Throws, with the usage, on an unknown flag or a value that is not one. */
+export function parseInstallCheckArgs(args, cwd) {
+    const values = new Map();
+    const switches = new Set();
+    const fail = (message) => {
+        throw new Error(`${message}\n${INSTALL_CHECK_USAGE}`);
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (SWITCHES.includes(arg)) {
+            switches.add(arg);
+        }
+        else if (VALUE_FLAGS.includes(arg)) {
+            const value = args[i + 1];
+            if (value === undefined)
+                fail(`${arg} needs a value`);
+            values.set(arg, [...(values.get(arg) ?? []), value]);
+            i += 1;
+        }
+        else {
+            fail(`unknown argument ${arg}`);
+        }
+    }
+    const last = (flag) => values.get(flag)?.at(-1);
+    const count = (flag) => {
+        const text = last(flag);
+        if (text === undefined)
+            return undefined;
+        if (!/^\d+$/.test(text))
+            fail(`${flag} takes a whole number`);
+        return Number(text);
+    };
+    const oneOf = (flag, choices) => {
+        const text = last(flag);
+        if (text !== undefined && !choices.includes(text))
+            fail(`${flag} takes one of ${choices.join(', ')}`);
+        return text;
+    };
+    if (switches.has('--run-none') && values.has('--run'))
+        fail('--run-none and --run contradict each other');
+    if (switches.has('--no-floor-script') && values.has('--floor-script'))
+        fail('--no-floor-script and --floor-script contradict each other');
+    if (switches.has('--no-install-command') && values.has('--install-command'))
+        fail('--no-install-command and --install-command contradict each other');
+    const requireScripts = {};
+    for (const pair of values.get('--require-script') ?? []) {
+        const at = pair.indexOf('=');
+        if (at < 1)
+            fail('--require-script takes <name>=<text>');
+        requireScripts[pair.slice(0, at)] = pair.slice(at + 1);
+    }
+    const floor = last('--npm-floor');
+    if (floor !== undefined && !releaseVersion(floor))
+        fail('--npm-floor takes an X.Y.Z version');
+    const options = {
+        ...(switches.has('--run-none') ? { run: [] } : values.has('--run') ? { run: values.get('--run') } : {}),
+        ...(count('--min-scripts') !== undefined ? { minScripts: count('--min-scripts') } : {}),
+        ...(count('--min-release-age') !== undefined ? { minReleaseAge: count('--min-release-age') } : {}),
+        ...(floor !== undefined ? { npmFloor: floor } : {}),
+        ...(switches.has('--no-floor-script') ? { floorScript: null } : last('--floor-script') !== undefined ? { floorScript: last('--floor-script') } : {}),
+        ...(switches.has('--no-install-command') ? { installCommand: null } : last('--install-command') !== undefined ? { installCommand: last('--install-command') } : {}),
+        ...(oneOf('--package-manager', ['path', 'bundled', 'declared']) !== undefined ? { packageManager: oneOf('--package-manager', ['path', 'bundled', 'declared']) } : {}),
+        ...(oneOf('--npm-probes', ['required', 'when-supported', 'off']) !== undefined ? { npmProbes: oneOf('--npm-probes', ['required', 'when-supported', 'off']) } : {}),
+        ...(values.has('--require-dev') ? { requireDevDependencies: values.get('--require-dev') } : {}),
+        ...(values.has('--require-script') ? { requireScripts } : {}),
+        ...(last('--registry') !== undefined ? { registry: last('--registry') } : {}),
+        ...(switches.has('--allow-legacy-peer-deps') ? { allowLegacyPeerDeps: true } : {}),
+        ...(switches.has('--no-lockfile-pins') ? { lockfilePins: false } : {}),
+        ...(switches.has('--no-prerelease-cases') ? { prereleaseBelowRelease: false } : {}),
+    };
+    const root = last('--root');
+    return { root: root === undefined ? cwd : resolve(cwd, root), options };
+}
+/** The whole bin, as a function. */
+export function runInstallCheck(args, cwd, env = process.env) {
+    try {
+        const { root, options } = parseInstallCheckArgs(args, cwd);
+        const result = checkInstallHardening(root, { ...options, env });
+        const skipped = result.skipped.map((line) => `  not checked: ${line}`);
+        if (result.problems.length > 0) {
+            return { code: 1, lines: ['tk-check-install-scripts: the install hardening does not hold:', ...result.problems.map((p) => `  ${p}`), ...skipped] };
+        }
+        return { code: 0, lines: [`ok   install hardening: ${result.scripts.length} install scripts reviewed in allowScripts, .npmrc, the lockfile and the npm floor hold`, ...skipped] };
+    }
+    catch (error) {
+        return { code: 1, lines: [`tk-check-install-scripts: ${error.message}`] };
+    }
+}

package/dist/neon-endpoint/README.md

@@ -0,0 +1,57 @@
+# `@catalystiq/test-kit/neon-endpoint`
+
+Which database a connection string addresses, read the way the clients that will use it read it. One dependency-free
+module (no import, not even a `node:` builtin; it spells no database host), so an app can import it in a build script
+run with bare `node` and bundle it into server code at boot. `tk-dev-guard` and the Vitest setup's production check
+do not read through it: they keep their own host reading (`src/setup/database.ts`), which normalises a whole value
+and refuses more; `test/env.test.ts` holds both to the same list of production spellings.
+
+An app that imports it outside its tests lists `@catalystiq/test-kit` under `dependencies`, not `devDependencies`.
+
+## Why
+
+A `postgres:` URL keeps an opaque host: `new URL(url).hostname` neither percent-decodes nor IDNA-maps it. The clients
+do. `pg-connection-string` decodes the host, and the Neon serverless driver's `neon()` re-parses the string as `http:` +
+the rest, so its host is a WHATWG special-scheme host: 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 that way, and the app connects to production through it.
+
+## An app's guard
+
+```ts
+import { createEndpointGuard } from '@catalystiq/test-kit/neon-endpoint';
+
+export const db = createEndpointGuard({
+  production: ['ep-…'], // bare ids: no -pooler, no domain
+  allowed: ['ep-…'], // what a preview deployment may connect to
+});
+
+db.namesProduction(value); // the denylist: every non-production context
+db.productionIn(value); // the production id it names, or null: for a message
+db.isAllowed(url); // the allowlist: exactly one allowed endpoint, production nowhere
+db.endpointId(url); // the one endpoint a URL connects to, or null
+```
+
+An id that is not a bare `ep-…` id, an empty production list, or an id on both lists throws at load.
+
+| Question | Reads | Errs toward |
+|---|---|---|
+| `namesProduction`, `productionIn`, `listedEntryIn(value, entries)` | Every shape, on any domain: a URL (one host or a comma-separated list), a keyword/value string, a bare `PGHOST`, `PGOPTIONS endpoint=…`, a `?host=`, an `options=endpoint%3D…`, each as written, percent-encoded (up to three times over) or spelled with characters a URL host maps to ASCII. An entry is an endpoint id or a host (its subdomains match). | Naming: a value that might reach production is production. |
+| `isAllowed`, `endpointId`, `neonEndpointId(url)` | A URL whose host is under Neon's own domains, read both as `pg` and as `neon()` read it, with every other route it carries (`?host=`, `options=endpoint=` / `project=`, the password field, `?password=`). | Null: a percent-encoded, mapped, trailing-dot or comma-separated host, a `hostaddr`, a `?host=` elsewhere, or a second endpoint anywhere in it is no single endpoint, which an allowlist refuses. |
+
+Also exported: `neonEndpointIds(url)` (every endpoint a URL names), `namesEndpoint(url, ids)`,
+`hasUnattributableHostOverride(url)`, `hostSpellings(host)`, `isListedHost(host, entries)`, `endpointOf(host)`. The URL
+readers take `{ anyDomain: true }` to read an `ep-…` label on any domain (a test corpus, a proxy domain). Nothing
+returns or throws a piece of the value other than an endpoint id or a list entry.
+
+## Replacing each app's own matcher
+
+Each app keeps its ids, its rule for which context is production or a preview, and its messages. What its matcher
+becomes, and what its copy does that this one does not:
+
+| App | Its matcher | Becomes | Not here |
+|---|---|---|---|
+| divorce-virtual | `lib/db/neon-endpoint.mjs`: `namesProductionEndpoint`, `isPreviewEndpoint`, `neonEndpointId`, `neonEndpointIds`, `hasUnattributableHostOverride` | `db.namesProduction`, `db.isAllowed`, and the same three by name | Nothing is lost; one answer changes. `namesProductionEndpoint` reads a host only under Neon's domains; `db.namesProduction` also names the id on any other domain and in a value that is not a URL (`namesEndpoint(url, [id])` is the old reading). `isPreviewDeployment`, `PG_ROUTING_ENV_VARS` and the id constants stay in the app. |
+| easy-carnet | `src/lib/db/preview-database-guard.ts`: `neonEndpointIdOf`, `namesProductionAnywhere`, `endpointOptionsOf` | `db.endpointId`, `db.namesProduction`, and `db.isAllowed` for the endpoint and its options together | `neonEndpointIdOf` answers for a percent-encoded host, a host with a final dot and a host on any domain; `db.endpointId` answers null for each (a preview is then refused, and `productionEndpointPinDrift` would not name a drift on such a string). It refuses every location key in the query (`port`, `dbname`, `database`); this one refuses only `hostaddr` and a `?host=` that names another place. Its production match is a substring; this one matches a whole id. `onVercel`, the `VERCEL_ENV` rules, the pin-drift line and `withExplicitVerifyFullSslMode` stay in the app. |
+| easy-plans | `lib/db/production-endpoint.ts`: `endpointOf`, `routedEndpoint` | `neonEndpointId` (null whenever a route in the URL names another endpoint) | `endpointOf` reads any domain (`{ anyDomain: true }`). `routedEndpoint` refuses more than a disagreement: any `options` endpoint, any `host` or `password` parameter, a second `options`, a URL with no password (pg then reads `PGPASSWORD` or a pgpass file) and an endpoint in `PGOPTIONS`. Nothing here reads the environment or a pgpass file: an app that keeps that rule keeps `routedEndpoint`. `withVerifiedSsl` stays in the app. |
+| easy-passport | `scripts/assert-not-prod.mjs`, `lib/db/assert-not-prod.ts`: `url.includes(host)` | `listedEntryIn(url, hosts)` over the same `db/production-endpoints.json` list | A substring match also takes part of an id as an entry; this one needs the whole id or a host. The `ALLOW_PROD_DB`, `VERCEL_ENV` and `NODE_ENV` exemptions, the strict form and the messages stay in the app. |

package/dist/neon-endpoint/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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.
+ */
+export interface EndpointReadOptions {
+    /**
+     * Read an `ep-…` first label as an endpoint on any domain, not only under Neon's own. For a test corpus or a proxy
+     * domain; an allowlist on real strings leaves it off, since `ep-<allowed>.elsewhere.example` is not that endpoint.
+     */
+    anyDomain?: boolean;
+}
+/** An `ep-…` label with any `-pooler` suffix stripped, or null. The one normalisation every URL reading uses. */
+export declare function endpointFromLabel(label: string): string | null;
+/**
+ * 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 declare function specialSchemeHostname(host: string): string | null;
+/** The URL's host when the whole string is re-read under a special scheme, exactly as `neon()` does, or null. */
+export declare function specialSchemeUrlHostname(url: string): string | 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 declare function hostSpellings(host: string): string[];
+/**
+ * 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 declare function hasUnattributableHostOverride(url: unknown, options?: EndpointReadOptions): boolean;
+/**
+ * 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 declare function neonEndpointId(url: unknown, options?: EndpointReadOptions): string | null;
+/** A value as written and percent-decoded, up to `rounds` times over (a client may decode what another already did). */
+export declare function decodedForms(value: string, rounds?: number): string[];
+/**
+ * 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 declare function neonEndpointIds(url: unknown, options?: EndpointReadOptions): string[];
+/** True when ANY endpoint the URL names ({@link neonEndpointIds}) is one of `ids`. */
+export declare function namesEndpoint(url: unknown, ids: readonly string[], options?: EndpointReadOptions): boolean;
+/** 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;
+/**
+ * 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 declare function isListedHost(host: string, entries: readonly string[]): boolean;
+/**
+ * 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 declare function listedEntryIn(value: string, entries: readonly string[]): string | null;
+export interface EndpointGuardConfig {
+    /** Production's compute endpoint ids (`ep-…`, bare: no `-pooler`, no domain). At least one. */
+    production: readonly string[];
+    /** The endpoint ids an allowlisted context (a preview deployment) may connect to. */
+    allowed?: readonly string[];
+    /** See {@link EndpointReadOptions.anyDomain}; applies to {@link EndpointGuard.endpointId} and `isAllowed`. */
+    anyDomain?: boolean;
+}
+export interface EndpointGuard {
+    readonly production: readonly string[];
+    readonly allowed: readonly string[];
+    /** The ONE endpoint a URL connects to, or null ({@link neonEndpointId}). */
+    endpointId(url: unknown): string | null;
+    /** The production id a value names anywhere, in any shape and on any domain, or null. Never part of the value. */
+    productionIn(value: unknown): string | null;
+    /** True when the value names a production endpoint anywhere: the denylist every non-production context applies. */
+    namesProduction(value: unknown): boolean;
+    /** True when the URL pins exactly one allowed endpoint and names production nowhere: the allowlist. */
+    isAllowed(url: unknown): boolean;
+}
+/**
+ * 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 declare function createEndpointGuard(config: EndpointGuardConfig): EndpointGuard;