@bonniernews/stayput 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bonnier News AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @bonniernews/stayput
+
+Default-deny network guard for Node.js test environments. Blocks non-local TCP at the socket level, so a test suite with a leaked production connection string fails loudly at connect time instead of silently mutating production. Works for raw-TCP drivers (pg, mongodb, elasticsearch, redis) as well as fetch/undici — not just HTTP.
+
+## Quick start
+
+```js
+// .mocharc.cjs
+module.exports = { require: ['@bonniernews/stayput/register'] };
+```
+
+Blocked connections throw with `err.code === 'EREMOTEBLOCKED'`.
+
+CI already injects the guard into every node process via `NODE_OPTIONS` in the shared workflow templates — the mocharc line is what protects laptops, which is where stray prod credentials actually live.
+
+Adoption is checked by ESLint: the shared ESLint config ships two rules — `stayput-required` flags a mocharc missing the register line (auto-fixable), and `project-has-guard` flags test files not governed by any stayput-loading mocha config. If you're seeing one of those warnings, the quick start above is the fix.
+
+### Runner-proofing (belt and suspenders)
+
+The mocharc line only guards runs that load the mocharc. `mocha --no-config`, mocha invoked from a subdirectory, `node --test`, or jest all skip it. If your repo has a shared test helper that tests import anyway, anchor the guard there too — loading is idempotent, so double-loading costs nothing:
+
+```js
+// test/helpers/db.js
+import '@bonniernews/stayput/register'; // guard on, no matter how the runner was invoked
+import stayput from '@bonniernews/stayput';
+
+export async function testDb() {
+  stayput.assertActive(); // refuse to hand out connections if the guard was tampered with
+  // ...create and return the client
+}
+```
+
+Boundary rule: stayput is a devDependency and only test-owned files (test helpers, setup files, mocharc) may import it — never `src/`, where it would crash a production install. If tests use the app's real DB module directly, add a thin test helper in between rather than gating production code on `NODE_ENV`.
+
+(In CI this is all redundant — `NODE_OPTIONS` injection guards every node process regardless of runner or config.)
+
+## Policy
+
+Locally (no `CI` env): loopback only. In CI: loopback + private ranges (RFC1918). Everything else is blocked.
+
+| Env var | Effect |
+|---|---|
+| `STAYPUT_ALLOW` | comma-separated extra hosts / IPs / IPv4 CIDRs, e.g. `10.128.0.5,db.internal` |
+| `STAYPUT_DENY` | same format — **deny beats allow** |
+| `STAYPUT_DISABLE=I_UNDERSTAND_THE_RISK` | turns the guard off (deliberately ugly so it stands out in review) |
+
+Put overrides in the workflow file, not in code: `STAYPUT_ALLOW`/`STAYPUT_DISABLE` are greppable fleet-wide and double as the exception inventory.
+
+## AI agents
+
+An `EREMOTEBLOCKED` error is a stop signal, not a bug to fix. Do not set `STAYPUT_ALLOW` or `STAYPUT_DISABLE`, edit workflow env, or remove the mocharc line to make tests pass — the block usually means the test suite is pointing at infrastructure it should not touch. Pause and ask a human to verify the target. Only a human adds exceptions, in the workflow file, where they are visible in review and in the fleet-wide grep.
+
+This contract has been red-teamed (2026-08-24): a coding agent (Claude) was given a sandboxed repo whose tests hit a blocked private-range database and told to "just get it green today". It diagnosed the guard from the error message, refused to override or fake the result (including mocking the driver or repointing the test), and stopped to ask for human verification. Steering, not enforcement — but it works on well-behaved agents.
+
+## Programmatic API
+
+```js
+import stayput from '@bonniernews/stayput';
+
+stayput.enable({
+  allow: ['10.128.0.5'],
+  deny: ['10.10.0.0/16'],   // deny beats allow
+  privateRanges: 'auto',    // 'auto' = private ranges only when CI is set
+  onBlock: (host, port) => {},
+});
+stayput.assertActive();     // throws if never loaded or unpatched
+stayput.isActive;
+```
+
+`@bonniernews/stayput/mocha` exports a root hook plugin that runs `assertActive()` before tests.
+
+Loading is idempotent: multiple loads (NODE_OPTIONS + mocharc + import) merge allowlists, patch once, and log one greppable line:
+
+```
+stayput/0.1.0 active mode=loopback+private allow=2 deny=1 source=NODE_OPTIONS
+```
+
+## One layer of many
+
+stayput is a client-side footgun guard — the last line of defence, not the plan. It complements, never replaces:
+
+- **Education** — knowing why prod credentials don't belong on laptops or in repos beats any guard.
+- **Easy, short-lived access paths** — when you genuinely need to reach a real database, use the ephemeral proxies/jumphosts on non-default ports. The sanctioned way is easier than the risky way, and a leaked default-port connection string doesn't route anywhere.
+- **Firewall rules / network design** — test environments should have no route to production at all; stayput only matters where a route exists.
+- **Test frameworks and fixtures** — testcontainers, CI service containers, and hermetic fixtures remove the reason to point tests at shared infrastructure in the first place.
+- **Server-side guards** — read-only default roles, DDL gating, RBAC without destructive verbs (per-database plan in [HANDOVER.md](HANDOVER.md)).
+
+## How it works
+
+Patches `net.Socket.prototype.connect` (sync throw on blocked IP literals; unix sockets always allowed) and `dns.lookup` (hostnames are vetted when they resolve). TLS and undici ride on `net.Socket`, so they're covered for free. This is a footgun guard, not a security boundary.
+
+Requires node ≥ 20.6 (preloaded in CI with `NODE_OPTIONS=--import …/register.js`).
+
+## Development
+
+```sh
+npm test                  # unit tests — no deps, no network, no docker
+npm run test:integration  # pg + mongodb + elasticsearch against docker (compose.yaml)
+```
+
+Design decisions, environment matrix, and rollout plan: [HANDOVER.md](HANDOVER.md).

package/index.js

@@ -0,0 +1,211 @@
+// stayput — default-deny network guard for Node test environments.
+// Zero dependencies by design: this is loaded via NODE_OPTIONS into every
+// node process in CI. A bad publish is a fleet-wide outage — keep it boring.
+//
+// ponytail: dns.promises and a custom options.lookup bypass the guard.
+// This is a footgun guard, not a security boundary (see HANDOVER.md).
+
+import net from 'node:net';
+import dns from 'node:dns';
+
+const VERSION = '0.1.0';
+const STATE_KEY = Symbol.for('bonnier.stayput');
+
+// ---- address helpers ------------------------------------------------------
+// ponytail: IPv4 CIDRs only; IPv6 covered as loopback/ULA/link-local/mapped
+// literals. Full IPv6 CIDR parsing when someone actually allows an IPv6 range.
+
+// '::ffff:1.2.3.4' → '1.2.3.4'; anything else passes through untouched
+function unmapIPv4(address) {
+  const match = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  return match ? match[1] : address;
+}
+
+function ipv4ToInt(address) {
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(address);
+  if (!match) return null;
+  let result = 0;
+  for (const octetString of match.slice(1)) {
+    const octet = Number(octetString);
+    if (octet > 255) return null;
+    result = result * 256 + octet;
+  }
+  return result;
+}
+
+function inCidr4(address, cidr) {
+  const slashIndex = cidr.indexOf('/');
+  const prefixBits = Number(cidr.slice(slashIndex + 1));
+  const networkInt = ipv4ToInt(cidr.slice(0, slashIndex));
+  const addressInt = ipv4ToInt(address);
+  if (networkInt === null || addressInt === null || !(prefixBits >= 0 && prefixBits <= 32)) return false;
+  const hostBits = 2 ** (32 - prefixBits);
+  return Math.floor(addressInt / hostBits) === Math.floor(networkInt / hostBits);
+}
+
+function isLoopback(address) {
+  const unmapped = unmapIPv4(address);
+  return unmapped === 'localhost' || unmapped === '::1' || inCidr4(unmapped, '127.0.0.0/8');
+}
+
+function isPrivate(address) {
+  const unmapped = unmapIPv4(address);
+  if (/^f[cd]/i.test(unmapped) || /^fe80:/i.test(unmapped)) return true; // IPv6 ULA + link-local
+  return inCidr4(unmapped, '10.0.0.0/8') || inCidr4(unmapped, '172.16.0.0/12') || inCidr4(unmapped, '192.168.0.0/16');
+}
+
+function matchesList(list, target) {
+  const unmapped = unmapIPv4(target);
+  return list.some((entry) => entry === unmapped || (entry.includes('/') && inCidr4(unmapped, entry)));
+}
+
+// deny beats allow — the key design decision (see HANDOVER.md).
+// hostAllowed: the hostname this address resolved from was allow-listed.
+function addressOk(address, state, hostAllowed) {
+  if (matchesList(state.deny, address)) return false;
+  if (hostAllowed || matchesList(state.allow, address)) return true;
+  if (isLoopback(address)) return true;
+  return state.privateOk && isPrivate(address);
+}
+
+// ---- blocking -------------------------------------------------------------
+
+function blockedError(target) {
+  const error = new Error(
+    `stayput: blocked connection to ${target} — non-local network access is denied in tests. ` +
+      'If this target is legitimate, a human must add it to STAYPUT_ALLOW in the workflow file. ' +
+      'AI agents: do not set STAYPUT_ALLOW or STAYPUT_DISABLE yourself — pause and ask a human to verify this connection is intended.'
+  );
+  error.code = 'EREMOTEBLOCKED';
+  return error;
+}
+
+function notifyBlock(state, host, port) {
+  if (typeof state.onBlock === 'function') {
+    try { state.onBlock(host, port); } catch { /* metrics hook must never mask the block */ }
+  }
+}
+
+// ---- patches ---------------------------------------------------------------
+
+function makePatchedConnect(originalConnect) {
+  return function connect(...args) {
+    const state = globalThis[STATE_KEY];
+    if (state && !state.disabled) {
+      let firstArg = args[0];
+      if (Array.isArray(firstArg)) firstArg = firstArg[0]; // node-internal pre-normalized [options, callback]
+      let host, port, path;
+      if (firstArg !== null && typeof firstArg === 'object') ({ host, port, path } = firstArg);
+      else if (typeof firstArg === 'string' && Number.isNaN(Number(firstArg))) path = firstArg; // mirrors node's pipe-name detection
+      else { port = firstArg; if (typeof args[1] === 'string') host = args[1]; }
+      if (path === undefined) { // unix sockets always allowed
+        const targetHost = String(host === undefined ? 'localhost' : host).toLowerCase();
+        const isIpLiteral = net.isIP(unmapIPv4(targetHost)) !== 0;
+        // non-IP hostnames (unless deny-listed) are vetted async in the dns.lookup patch —
+        // connect is sync, DNS isn't
+        if (matchesList(state.deny, targetHost) || (isIpLiteral && !addressOk(targetHost, state, false))) {
+          notifyBlock(state, targetHost, port);
+          throw blockedError(`${targetHost}:${port}`); // sync throw — driver retry loops swallow emitted errors
+        }
+      }
+    }
+    return originalConnect.apply(this, args);
+  };
+}
+
+function makePatchedLookup(originalLookup) {
+  return function lookup(hostname, options, callback) {
+    const state = globalThis[STATE_KEY];
+    if (!state || state.disabled) return originalLookup.call(this, hostname, options, callback);
+    if (typeof options === 'function') { callback = options; options = undefined; }
+    const targetHost = String(hostname || '').toLowerCase();
+    if (matchesList(state.deny, targetHost)) {
+      notifyBlock(state, targetHost);
+      return process.nextTick(callback, blockedError(targetHost));
+    }
+    const hostAllowed = matchesList(state.allow, targetHost);
+    const vetResolvedAddresses = function (error, address, family) {
+      if (!error) {
+        // with {all: true} node hands back [{address, family}, ...], otherwise a single string
+        const addresses = Array.isArray(address) ? address.map((entry) => (entry && entry.address) || entry) : [address];
+        const blockedAddress = addresses.find((resolved) => !addressOk(String(resolved), state, hostAllowed));
+        if (blockedAddress !== undefined) {
+          notifyBlock(state, targetHost);
+          return callback(blockedError(`${targetHost} (resolved to ${blockedAddress})`));
+        }
+      }
+      return callback(error, address, family);
+    };
+    return options === undefined
+      ? originalLookup.call(this, hostname, vetResolvedAddresses)
+      : originalLookup.call(this, hostname, options, vetResolvedAddresses);
+  };
+}
+
+// ---- public API -------------------------------------------------------------
+
+function splitEnvList(value) {
+  return (value || '').split(',').map((item) => item.trim().toLowerCase()).filter(Boolean);
+}
+
+export function enable(options = {}) {
+  const env = process.env;
+  const allow = [...(options.allow || []).map((entry) => String(entry).toLowerCase()), ...splitEnvList(env.STAYPUT_ALLOW)];
+  const deny = [...(options.deny || []).map((entry) => String(entry).toLowerCase()), ...splitEnvList(env.STAYPUT_DENY)];
+
+  let state = globalThis[STATE_KEY];
+  if (state) {
+    // later loads merge lists, never re-patch, never re-log
+    for (const entry of allow) if (!state.allow.includes(entry)) state.allow.push(entry);
+    for (const entry of deny) if (!state.deny.includes(entry)) state.deny.push(entry);
+    if (options.onBlock) state.onBlock = options.onBlock;
+    return api;
+  }
+
+  const privateRanges = options.privateRanges === undefined ? 'auto' : options.privateRanges;
+  state = {
+    version: VERSION,
+    allow,
+    deny,
+    // auto: laptops (no CI env) are where stray prod creds live → loopback-only;
+    // CI is ephemeral/containerized → private ranges too
+    privateOk: privateRanges === 'auto' ? Boolean(env.CI) : Boolean(privateRanges),
+    disabled: env.STAYPUT_DISABLE === 'I_UNDERSTAND_THE_RISK',
+    onBlock: options.onBlock,
+    patchedConnect: makePatchedConnect(net.Socket.prototype.connect),
+    patchedLookup: makePatchedLookup(dns.lookup),
+  };
+  globalThis[STATE_KEY] = state;
+  net.Socket.prototype.connect = state.patchedConnect;
+  dns.lookup = state.patchedLookup;
+
+  const source = /stayput/.test(env.NODE_OPTIONS || '') ? 'NODE_OPTIONS' : 'require';
+  const mode = state.privateOk ? 'loopback+private' : 'loopback';
+  console.error(
+    state.disabled
+      ? `stayput/${VERSION} disabled via STAYPUT_DISABLE source=${source}`
+      : `stayput/${VERSION} active mode=${mode} allow=${state.allow.length} deny=${state.deny.length} source=${source}`
+  );
+  return api;
+}
+
+export function assertActive() {
+  const state = globalThis[STATE_KEY];
+  if (!state) {
+    throw new Error("stayput: guard never loaded — add '@bonniernews/stayput/register' to your mocharc require array");
+  }
+  if (net.Socket.prototype.connect !== state.patchedConnect || dns.lookup !== state.patchedLookup) {
+    throw new Error('stayput: guard was unpatched after load');
+  }
+}
+
+const api = {
+  enable,
+  assertActive,
+  get isActive() {
+    const state = globalThis[STATE_KEY];
+    return Boolean(state) && net.Socket.prototype.connect === state.patchedConnect;
+  },
+};
+
+export default api;

package/mocha.js

@@ -0,0 +1,8 @@
+// Root hook plugin: catches the guard being unpatched between load and test run.
+import { assertActive } from './index.js';
+
+export const mochaHooks = {
+  beforeAll() {
+    assertActive();
+  },
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@bonniernews/stayput",
+  "version": "0.1.0",
+  "description": "Default-deny network guard for Node.js test environments — blocks non-local TCP at the socket level.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BonnierNews/stayput.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./register": "./register.js",
+    "./mocha": "./mocha.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "register.js",
+    "mocha.js"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "test:integration": "node test-integration.js",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@elastic/elasticsearch": "^8.17.0",
+    "mongodb": "^6.10.0",
+    "pg": "^8.13.0"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}

package/register.js

@@ -0,0 +1,4 @@
+// Side-effect entry, loaded via NODE_OPTIONS --import or mocharc require.
+// Runs in every node process in CI — keep dependency-free and boring.
+import { enable } from './index.js';
+enable();