postgres-mcp-hardened 0.1.1

package/README.md

@@ -0,0 +1,57 @@
+# postgres-mcp-hardened
+
+A maintained, read-only PostgreSQL MCP server — the drop-in replacement for
+[`@modelcontextprotocol/server-postgres`](https://www.npmjs.com/package/@modelcontextprotocol/server-postgres),
+which was deprecated by its authors and last released in December 2024.
+
+Writes are refused by walking the parsed SQL, not by matching strings. Comments, dollar-quoting and
+Unicode tricks do not survive the parse, so they cannot smuggle a statement past the check.
+
+## Replace the deprecated server
+
+```diff
+ {
+   "mcpServers": {
+     "postgres": {
+-      "command": "npx",
+-      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
++      "command": "npx",
++      "args": ["-y", "postgres-mcp-hardened", "--stdio"],
++      "env": { "DATABASE_URL": "postgres://readonly_user:PASSWORD@localhost:5432/mydb" }
+     }
+   }
+ }
+```
+
+The connection string moves from an argument to `DATABASE_URL` on purpose: arguments show up in
+`ps` output and in shell history on a shared machine, and a database password does not belong there.
+
+## What it does differently
+
+- **Read-only is enforced twice.** The validator rejects anything that is not a read, and the
+  session runs in a `READ ONLY` transaction — so a gap in the first layer is not a breach.
+- **Statement timeout and row caps** are set server-side, so a careless question cannot pin your
+  database or drag a million rows into a model's context.
+- **Every query is written to an audit log** chained by hash, which survives a restart and makes
+  a deleted or truncated tail detectable.
+- **Optional OAuth (RS256)** with audience and issuer enforced, for running it as a shared HTTP
+  endpoint rather than a local process.
+- **Signed releases** — every artefact carries a Sigstore signature and a SHA-256, and this package
+  refuses to install a binary whose checksum does not match the one recorded at publish time.
+
+## Install
+
+```bash
+npx -y postgres-mcp-hardened --stdio       # no install
+npm install -g postgres-mcp-hardened       # or keep it around
+```
+
+The package fetches a prebuilt binary for your platform from the matching GitHub release:
+Linux (x64, arm64), macOS (Intel, Apple Silicon) and Windows (x64). Alpine/musl is not among them —
+the Linux builds link against glibc; use the container image `ghcr.io/eszetael/postgres-mcp-hardened`
+or build from source with `cargo build --release` in a clone.
+
+Full documentation, configuration reference and the security model:
+**https://github.com/Eszetael/postgres-mcp-hardened**
+
+MIT licensed.

package/bin/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+
+// The launcher an MCP client actually spawns. It hands over to the native binary with execve-like
+// semantics: same stdio, same exit code, no wrapper process interpreting the protocol.
+//
+// It also downloads the binary if it is missing. That is deliberate belt-and-braces: `postinstall`
+// normally does it at install time, but plenty of environments run `npm install --ignore-scripts`
+// (corporate policy, most CI defaults), and there the postinstall never fires. Without this branch
+// those users would get "command not found" from a package that installed successfully — the kind
+// of failure people do not report, they just leave.
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const { ensureBinary, binaryPath } = require('../lib/install.js');
+
+// Every flag the server understands, top-level and inside `--print-setup-sql`. Kept here because
+// the server itself scans for the flags it knows and ignores the rest — so `--stdi` does not fail,
+// it starts an HTTP listener instead of a stdio server. For someone wiring this into an MCP client
+// that is a silent hang; on a shared machine it is an unintended open port. A test asserts this
+// list against the Rust sources, so a new flag upstream breaks the build rather than a user's day.
+const KNOWN = new Set([
+  '--stdio', '--validate', '--canon', '--fuzz', '--verify-audit', '--expect-last',
+  '--print-setup-sql', '--role', '--schemas', '--tables', '--redact', '--database', '--owner',
+]);
+
+const USAGE = `postgres-mcp-hardened — read-only PostgreSQL MCP server
+
+  postgres-mcp-hardened --stdio          speak MCP over stdin/stdout (what an MCP client spawns)
+  postgres-mcp-hardened                  serve Streamable HTTP on MCP_ADDR (default 127.0.0.1:8080)
+
+  --validate <sql>                       print the validator's verdict for one statement
+  --canon <sql>                          print the text that would actually reach the database
+  --verify-audit <path> [--expect-last <hash>]   check the audit log's hash chain
+  --print-setup-sql [--role R] [--schemas S] [--tables T] [--redact C] [--database D] [--owner O]
+                                         print the SQL that creates a least-privilege role
+  --fuzz [iterations] [seed]             deterministic validator fuzz; exits 1 on a violation
+
+  -h, --help                             this text
+  -V, --version                          package version
+
+Configuration is environment-driven; DATABASE_URL is required to serve.
+Full reference: https://github.com/Eszetael/postgres-mcp-hardened`;
+
+function guard(argv) {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    process.stdout.write(USAGE + '\n');
+    return { exit: 0 };
+  }
+  if (argv.includes('-V') || argv.includes('--version')) {
+    process.stdout.write(require('../package.json').version + '\n');
+    return { exit: 0 };
+  }
+  const unknown = argv.filter((a) => a.startsWith('--') && !KNOWN.has(a));
+  if (unknown.length) {
+    process.stderr.write(
+      `postgres-mcp-hardened: unknown option ${unknown.join(', ')}\n` +
+      `The server ignores options it does not recognise, so a typo in --stdio would have started ` +
+      `a network listener instead of a stdio server. Refusing.\n\n${USAGE}\n`);
+    return { exit: 2 };
+  }
+  return null;
+}
+
+async function main() {
+  const stop = guard(process.argv.slice(2));
+  if (stop) process.exit(stop.exit);
+
+  let bin = binaryPath();
+  if (!fs.existsSync(bin)) {
+    // stdio is the MCP transport: one stray byte on stdout and the client sees a malformed frame.
+    // Progress goes to stderr, which clients log and ignore.
+    bin = await ensureBinary();
+  }
+
+  const child = spawn(bin, process.argv.slice(2), { stdio: 'inherit' });
+
+  // Signals are forwarded rather than left to kill the launcher: an MCP client shutting a server
+  // down sends SIGTERM to the process it spawned, and if that is us, the native process would be
+  // orphaned and keep its database connections open.
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    process.on(sig, () => { try { child.kill(sig); } catch { /* already gone */ } });
+  }
+
+  child.on('error', (e) => {
+    process.stderr.write(`postgres-mcp-hardened: cannot start ${bin}\n${e.message}\n`);
+    process.exit(127);
+  });
+  // A process killed by a signal has no exit code; report it the way a shell does, so a supervisor
+  // can tell "crashed" from "exited non-zero".
+  child.on('exit', (code, signal) => process.exit(signal ? 128 + osSignalNumber(signal) : code ?? 0));
+}
+
+function osSignalNumber(sig) {
+  return { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 }[sig] ?? 0;
+}
+
+main().catch((e) => {
+  process.stderr.write(`postgres-mcp-hardened: ${e.message}\n`);
+  process.exit(1);
+});

package/checksums.json

@@ -0,0 +1,7 @@
+{
+  "postgres-mcp-hardened-aarch64-apple-darwin.tar.gz": "7d1dedc7f46a34f3863a8b3ab7dd34d6eba75e086f567e0874e2dae657d925e8",
+  "postgres-mcp-hardened-aarch64-unknown-linux-gnu.tar.gz": "1ce5543a4feaaedd13536a75895f29cf9fa9b498704e1c1a5b157f0b85ce570c",
+  "postgres-mcp-hardened-x86_64-apple-darwin.tar.gz": "5747fa27c728f35de77467bd9cd91c3f7f8598983bc3dfd8365bd222fd20d823",
+  "postgres-mcp-hardened-x86_64-unknown-linux-gnu.tar.gz": "5853be99322d5bdcbcc35d7a5cd6f5a4f687f336c1db68daea27a4eb638fcf2e",
+  "postgres-mcp-hardened-x86_64-pc-windows-msvc.zip": "f8ccaf6d08a6e16b4bdefb2b6fd81d1255b3fac1cdb5587921d593eca93ed6ee"
+}

package/lib/install.js

@@ -0,0 +1,136 @@
+'use strict';
+
+// Fetches the prebuilt binary for this platform from the GitHub Release that matches this package
+// version, verifies it against a checksum baked in at publish time, and unpacks it next to this file.
+//
+// Why the checksum is IN the package rather than fetched alongside the download: a checksum served
+// from the same place as the artefact proves the transfer was not corrupted and nothing else. The
+// list in `checksums.json` is written by the release workflow from the artefacts it just built, so
+// it travels with npm's own integrity guarantee. If the two disagree, the download is wrong — and
+// for a tool whose whole selling point is refusing unsafe input, "run it anyway" is not an option.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const REPO = 'Eszetael/postgres-mcp-hardened';
+const BIN = 'postgres-mcp-hardened';
+
+// npm's platform names on the left, Rust target triples on the right. Kept explicit rather than
+// assembled from parts: a wrong triple would download an archive that unpacks fine and then dies
+// with "Exec format error", which is a far worse message than "unsupported platform".
+const TARGETS = {
+  'linux-x64': 'x86_64-unknown-linux-gnu',
+  'linux-arm64': 'aarch64-unknown-linux-gnu',
+  'darwin-x64': 'x86_64-apple-darwin',
+  'darwin-arm64': 'aarch64-apple-darwin',
+  'win32-x64': 'x86_64-pc-windows-msvc',
+};
+
+const key = () => `${process.platform}-${process.arch}`;
+
+function binaryPath() {
+  const exe = process.platform === 'win32' ? `${BIN}.exe` : BIN;
+  return path.join(__dirname, '..', 'vendor', exe);
+}
+
+function targetOrExplain() {
+  const t = TARGETS[key()];
+  if (t) return t;
+  const supported = Object.keys(TARGETS).join(', ');
+  throw new Error(
+    `No prebuilt binary for ${key()}. Supported: ${supported}.\n` +
+    `Build from source instead: cargo install --git https://github.com/${REPO}\n` +
+    `(Alpine/musl is not in that list either — the Linux builds are glibc. Use the container image: ` +
+    `ghcr.io/${REPO.toLowerCase()})`
+  );
+}
+
+function expectedChecksum(archive) {
+  let sums;
+  try {
+    sums = require('../checksums.json');
+  } catch {
+    sums = null;
+  }
+  const sum = sums && sums[archive];
+  if (!sum) {
+    // Fail closed. An empty checksum list means the package was published without the release
+    // workflow filling it in — that is a broken publish, and silently trusting the download would
+    // turn one mistake into a supply-chain hole that nobody would ever notice.
+    throw new Error(
+      `No checksum recorded for ${archive}. This package was published incorrectly; ` +
+      `refusing to install an unverified binary. Please open an issue at https://github.com/${REPO}/issues`
+    );
+  }
+  return sum;
+}
+
+async function download(url) {
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) {
+    throw new Error(`Download failed: ${res.status} ${res.statusText}\n  ${url}`);
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+function unpack(archivePath, into) {
+  fs.mkdirSync(into, { recursive: true });
+  try {
+    // bsdtar ships with macOS, every Linux, and Windows 10+ — and it reads .zip as well as .tar.gz,
+    // so one command covers all five targets.
+    execFileSync('tar', ['-xf', archivePath, '-C', into], { stdio: 'ignore' });
+  } catch (e) {
+    if (process.platform !== 'win32') throw e;
+    execFileSync('powershell', ['-NoProfile', '-Command',
+      `Expand-Archive -LiteralPath '${archivePath}' -DestinationPath '${into}' -Force`],
+      { stdio: 'ignore' });
+  }
+}
+
+async function ensureBinary({ quiet = false } = {}) {
+  const dest = binaryPath();
+  if (fs.existsSync(dest)) return dest;
+
+  const target = targetOrExplain();
+  const ext = process.platform === 'win32' ? 'zip' : 'tar.gz';
+  const archive = `${BIN}-${target}.${ext}`;
+  const version = require('../package.json').version;
+  const url = `https://github.com/${REPO}/releases/download/v${version}/${archive}`;
+
+  // Ask for the checksum BEFORE spending the bandwidth. If the list is missing an entry we are
+  // going to refuse anyway, and refusing after a 10 MB download only makes the failure slower.
+  const want = expectedChecksum(archive);
+
+  if (!quiet) process.stderr.write(`postgres-mcp-hardened: fetching ${archive} (v${version})\n`);
+  const buf = await download(url);
+
+  const got = crypto.createHash('sha256').update(buf).digest('hex');
+  if (got !== want) {
+    throw new Error(
+      `Checksum mismatch for ${archive}\n  expected ${want}\n  got      ${got}\n` +
+      `Refusing to install. Report this at https://github.com/${REPO}/issues`
+    );
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pmh-'));
+  const archivePath = path.join(tmp, archive);
+  fs.writeFileSync(archivePath, buf);
+  unpack(archivePath, path.dirname(dest));
+  fs.rmSync(tmp, { recursive: true, force: true });
+
+  if (!fs.existsSync(dest)) {
+    throw new Error(`Archive ${archive} did not contain ${path.basename(dest)}`);
+  }
+  if (process.platform !== 'win32') fs.chmodSync(dest, 0o755);
+  return dest;
+}
+
+module.exports = {
+  ensureBinary, binaryPath, TARGETS, REPO, BIN,
+  // Exported for the tests: both are refusal paths, and a refusal that is never exercised is a
+  // refusal nobody knows still works.
+  targetOrExplain, expectedChecksum, key,
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "postgres-mcp-hardened",
+  "version": "0.1.1",
+  "description": "Secure read-only PostgreSQL MCP server in Rust — a maintained alternative to the deprecated @modelcontextprotocol/server-postgres. Blocks writes at the AST, not with regexes.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "postgres",
+    "postgresql",
+    "mcp-server",
+    "read-only",
+    "sql",
+    "ai",
+    "llm",
+    "claude",
+    "cursor",
+    "rust"
+  ],
+  "homepage": "https://github.com/Eszetael/postgres-mcp-hardened#readme",
+  "bugs": "https://github.com/Eszetael/postgres-mcp-hardened/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Eszetael/postgres-mcp-hardened.git",
+    "directory": "npm"
+  },
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "postgres-mcp-hardened": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "checksums.json",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node scripts/run-tests.js"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,18 @@
+'use strict';
+
+// Fetches the binary at install time so the first `npx` run is instant — an MCP client spawns the
+// server and waits for a handshake, and a 10 MB download inside that window looks like a hang.
+//
+// It must never fail the install. Offline machines, proxies and `--ignore-scripts` all exist, and
+// the launcher downloads on demand anyway; turning a recoverable situation into a failed
+// `npm install` would be worse than the delay it avoids. So: explain, and exit 0.
+
+const { ensureBinary } = require('../lib/install.js');
+
+ensureBinary().catch((e) => {
+  process.stderr.write(
+    `postgres-mcp-hardened: could not fetch the binary now (${e.message.split('\n')[0]}).\n` +
+    `It will be fetched on first run instead.\n`
+  );
+  process.exit(0);
+});

package/scripts/run-tests.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+'use strict';
+
+// Uruchamia testy opakowania i ODMAWIA, gdy nie ma czego uruchomić.
+//
+// Dwa błędy naraz, oba znalezione 7.08 i oba tego samego rodzaju — ścieżka, której nikt nie wykonał.
+//
+// 1. `npm test` było ustawione na `node --test test/`. Na Node 22 ta forma nie uruchamia katalogu,
+//    tylko próbuje wczytać go jako moduł i pada z MODULE_NOT_FOUND. Czyli udokumentowana komenda
+//    projektu nie działała, podczas gdy same testy przechodziły 9/9 uruchomione na pliku. CI
+//    wywoływało dokładnie tę zepsutą formę i nigdy się o tym nie dowiedziało, bo zadanie `npm`
+//    zależy od `build`, a `build` padał od 28.07 na uprawnieniach.
+//
+// 2. Oczywista poprawka — samo `node --test` — ma gorszą wadę: w katalogu BEZ testów kończy się
+//    kodem 0. Zero testów wygląda wtedy identycznie jak komplet zdanych. Sprawdzone wprost.
+//
+// Stąd ten plik: wyszukaj pliki testów, odmów przy zerze, a dopiero potem uruchom. Wyszukiwanie
+// jest rekurencyjne, więc nowy podkatalog nie wypadnie po cichu z pakietu.
+
+const { readdirSync, statSync } = require('node:fs');
+const { join, relative } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const ROOT = join(__dirname, '..');
+const TEST_DIR = join(ROOT, 'test');
+
+function collect(dir) {
+  let out = [];
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (statSync(p).isDirectory()) out = out.concat(collect(p));
+    else if (/\.test\.(c|m)?js$/.test(name)) out.push(p);
+  }
+  return out;
+}
+
+let files = [];
+try {
+  files = collect(TEST_DIR);
+} catch (err) {
+  console.error(`ODMOWA: nie da się odczytać ${relative(ROOT, TEST_DIR)} — ${err.message}`);
+  process.exit(3);
+}
+
+if (files.length === 0) {
+  console.error('ODMOWA: nie znaleziono ani jednego pliku *.test.js.');
+  console.error('Zero testów nie jest sukcesem, a `node --test` w pustym katalogu kończy się zerem.');
+  process.exit(3);
+}
+
+console.log(`uruchamiam ${files.length} plik(ów) testów:`);
+for (const f of files) console.log(`  ${relative(ROOT, f)}`);
+
+const r = spawnSync(process.execPath, ['--test', ...files], { stdio: 'inherit', cwd: ROOT });
+process.exit(r.status === null ? 1 : r.status);