pgserve 2.5.0 → 2.6.1

package/src/provision/db-naming.js

@@ -0,0 +1,130 @@
+/**
+ * Database + role naming for `pgserve provision`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3.
+ *
+ * Postgres identifiers max out at NAMEDATALEN-1 = 63 chars (default
+ * build). Our naming has to:
+ *   1. Be deterministic: same fingerprint → same name forever, so a
+ *      re-run of `pgserve provision` is idempotent and `pgserve gc`
+ *      can correlate `pg_database` rows back to `pgserve_meta` rows.
+ *   2. Be readable: include enough of the publisher slug that an
+ *      operator looking at `\l` in psql can figure out which consumer
+ *      a database belongs to.
+ *   3. Stay under 63 chars even when the publisher is long.
+ *   4. Avoid postgres reserved keywords and quoting requirements
+ *      (lowercase + [a-z0-9_] only).
+ *
+ * Layout (≤63 chars):
+ *
+ *   pgserve_<publisher-slug>_<fingerprint-hex-12>
+ *
+ *   - prefix:           "pgserve_" (8 chars) — fixed, used by gc to
+ *                       find candidate orphans without scanning every
+ *                       postgres DB.
+ *   - publisher-slug:   sanitized + truncated package.json name /
+ *                       pgserve.publisher. Effective max ≈ 37 chars
+ *                       (computed from min(dbSlugBudget, roleSlugBudget)
+ *                       so DB and role always share the same slug for
+ *                       operator UX in `\l` / `\du`).
+ *   - fingerprint hex:  first 12 hex chars of the fingerprint. Plenty
+ *                       of entropy to avoid collisions across consumers
+ *                       on the same host.
+ *
+ * Role name uses the same identifier with `_role` suffix. Because the
+ * publisher slug is already truncated to fit the database name, we
+ * recompute the role-side budget so the role also stays ≤63 chars.
+ *
+ * Pure function: no fs / network / pg.
+ */
+
+const POSTGRES_MAX_IDENTIFIER = 63;
+const PREFIX = 'pgserve_';
+const FINGERPRINT_HEX_LEN = 12;
+const ROLE_SUFFIX = '_role';
+
+/**
+ * Lowercase + replace any char that's not [a-z0-9] with '_'. Collapses
+ * runs of '_' to a single '_' and trims leading / trailing '_'.
+ */
+export function sanitizeSlug(input) {
+  if (typeof input !== 'string') return '';
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+}
+
+/**
+ * @typedef {Object} ProvisionedNames
+ * @property {string} databaseName  ≤63 chars, [a-z0-9_]+
+ * @property {string} roleName      ≤63 chars, [a-z0-9_]+
+ * @property {string} slug          the sanitized publisher slug used
+ * @property {string} fingerprintHex first 12 chars of the fingerprint
+ */
+
+/**
+ * Derive the database + role name pair from a fingerprint + publisher.
+ *
+ * @param {object} args
+ * @param {string} args.fingerprint    sha256-hex from resolveFingerprint
+ * @param {string} args.publisher      e.g. '@automagik/genie' (may be '')
+ * @returns {ProvisionedNames}
+ */
+export function deriveProvisionedNames({ fingerprint, publisher } = {}) {
+  if (typeof fingerprint !== 'string' || fingerprint.length === 0) {
+    throw new TypeError('deriveProvisionedNames: fingerprint must be a non-empty string');
+  }
+  // Hex encoding is the typical case (sha256-hex). For pinned-string
+  // fingerprints (operator escape hatch) we still accept any chars, but
+  // we strip them through the same sanitizer so the database identifier
+  // stays valid.
+  const hexLike = /^[0-9a-f]+$/.test(fingerprint);
+  const fingerprintHex = hexLike
+    ? fingerprint.slice(0, FINGERPRINT_HEX_LEN)
+    : sanitizeSlug(fingerprint).slice(0, FINGERPRINT_HEX_LEN);
+  if (fingerprintHex.length === 0) {
+    throw new Error('deriveProvisionedNames: fingerprint produced an empty hex segment');
+  }
+
+  // Database identifier:
+  //   PREFIX + slug + '_' + fingerprintHex   ≤ 63
+  // → slug budget = 63 - len(PREFIX) - 1 - len(fingerprintHex)
+  const dbSlugBudget = POSTGRES_MAX_IDENTIFIER - PREFIX.length - 1 - fingerprintHex.length;
+
+  // Role identifier (separate budget — has to also fit ROLE_SUFFIX):
+  //   PREFIX + slug + '_' + fingerprintHex + ROLE_SUFFIX   ≤ 63
+  // → slug budget = 63 - len(PREFIX) - 1 - len(fingerprintHex) - len(ROLE_SUFFIX)
+  const roleSlugBudget = dbSlugBudget - ROLE_SUFFIX.length;
+
+  // We use the smaller of the two budgets so the same slug appears in
+  // both names — operators reading `\l` and `\du` in psql see matched
+  // pairs without surprise truncation.
+  const slugBudget = Math.max(0, Math.min(dbSlugBudget, roleSlugBudget));
+
+  const fullSlug = sanitizeSlug(publisher);
+  const slug = fullSlug.slice(0, slugBudget);
+
+  const databaseName = slug.length > 0
+    ? `${PREFIX}${slug}_${fingerprintHex}`
+    : `${PREFIX}${fingerprintHex}`;
+
+  const roleName = slug.length > 0
+    ? `${PREFIX}${slug}_${fingerprintHex}${ROLE_SUFFIX}`
+    : `${PREFIX}${fingerprintHex}${ROLE_SUFFIX}`;
+
+  return {
+    databaseName,
+    roleName,
+    slug,
+    fingerprintHex,
+  };
+}
+
+export const __testInternals = Object.freeze({
+  POSTGRES_MAX_IDENTIFIER,
+  PREFIX,
+  FINGERPRINT_HEX_LEN,
+  ROLE_SUFFIX,
+});

package/src/provision/fingerprint.js

@@ -0,0 +1,144 @@
+/**
+ * Fingerprint resolver for `pgserve provision`.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3.
+ *
+ * Goal: deterministically map a consumer location (cwd / explicit path /
+ * package.json contents) to a stable fingerprint string + the metadata
+ * `pgserve provision` needs to write a row into `pgserve_meta`.
+ *
+ * Fingerprint precedence (matches Decision in WISH.md §2.4):
+ *   1. If a package.json is found and declares `pgserve.fingerprint`,
+ *      use that string verbatim. (Operator escape hatch — pinned across
+ *      moves.)
+ *   2. Else if a package.json declares `name` + `version`, fingerprint =
+ *      sha256(`<name>@<version>`).
+ *   3. Else if a package.json declares `name` only, fingerprint =
+ *      sha256(`<name>`).
+ *   4. Else (no package.json or empty), fingerprint = sha256(absolute
+ *      cwd path). This is the "fallback fingerprint" the wish describes.
+ *
+ * `publisher` resolution:
+ *   - prefers `package.json#pgserve.publisher`
+ *   - falls back to `package.json#name`
+ *   - empty string when no package.json was found
+ *
+ * `sourcePath` is always the absolute filesystem path (cwd or supplied)
+ * — used by gc to detect "directory removed" orphans.
+ *
+ * Side effects: synchronous filesystem read of `<cwd>/package.json`
+ * (one open + one read; no recursion). No postgres I/O, no network, no
+ * globals. Hot-loop callers should cache the result themselves.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+/**
+ * @typedef {Object} ResolvedFingerprint
+ * @property {string} fingerprint   sha256-hex (64 chars) OR a literal
+ *                                  string if pgserve.fingerprint was set.
+ * @property {string} sourcePath    absolute path that was inspected.
+ * @property {string} publisher     resolved publisher; '' when unknown.
+ * @property {string} kind          'pinned' | 'name+version' | 'name' | 'cwd'
+ * @property {object} packageJson   the parsed object; null when absent.
+ */
+
+function sha256Hex(input) {
+  return crypto.createHash('sha256').update(input, 'utf8').digest('hex');
+}
+
+function readPackageJson(absDir) {
+  const candidate = path.join(absDir, 'package.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(candidate, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch (err) {
+    const e = new Error(`pgserve provision: package.json at ${candidate} is not valid JSON: ${err.message}`);
+    e.code = 'EFINGERPRINTPKG';
+    throw e;
+  }
+}
+
+/**
+ * Resolve a fingerprint for the given directory (defaults to cwd).
+ * @param {object} opts
+ * @param {string} [opts.cwd]            absolute or relative path to inspect
+ * @param {string} [opts.explicit]       caller-supplied fingerprint; bypasses package.json
+ * @returns {ResolvedFingerprint}
+ */
+export function resolveFingerprint(opts = {}) {
+  const cwd = path.resolve(opts.cwd || process.cwd());
+  if (typeof opts.explicit === 'string' && opts.explicit.length > 0) {
+    // Caller passed an explicit fingerprint (CLI flag / config file).
+    // We still load package.json so callers get the full publisher
+    // metadata, but the fingerprint itself comes from the operator.
+    const pkg = readPackageJson(cwd);
+    return {
+      fingerprint: opts.explicit,
+      sourcePath: cwd,
+      publisher: derivePublisher(pkg),
+      kind: 'pinned',
+      packageJson: pkg,
+    };
+  }
+  const pkg = readPackageJson(cwd);
+  if (pkg && typeof pkg.pgserve === 'object' && pkg.pgserve !== null
+      && typeof pkg.pgserve.fingerprint === 'string'
+      && pkg.pgserve.fingerprint.length > 0) {
+    return {
+      fingerprint: pkg.pgserve.fingerprint,
+      sourcePath: cwd,
+      publisher: derivePublisher(pkg),
+      kind: 'pinned',
+      packageJson: pkg,
+    };
+  }
+  if (pkg && typeof pkg.name === 'string' && pkg.name.length > 0) {
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+      return {
+        fingerprint: sha256Hex(`${pkg.name}@${pkg.version}`),
+        sourcePath: cwd,
+        publisher: derivePublisher(pkg),
+        kind: 'name+version',
+        packageJson: pkg,
+      };
+    }
+    return {
+      fingerprint: sha256Hex(pkg.name),
+      sourcePath: cwd,
+      publisher: derivePublisher(pkg),
+      kind: 'name',
+      packageJson: pkg,
+    };
+  }
+  return {
+    fingerprint: sha256Hex(cwd),
+    sourcePath: cwd,
+    publisher: '',
+    kind: 'cwd',
+    packageJson: null,
+  };
+}
+
+function derivePublisher(pkg) {
+  if (!pkg || typeof pkg !== 'object') return '';
+  if (typeof pkg.pgserve === 'object' && pkg.pgserve !== null
+      && typeof pkg.pgserve.publisher === 'string'
+      && pkg.pgserve.publisher.length > 0) {
+    return pkg.pgserve.publisher;
+  }
+  if (typeof pkg.name === 'string' && pkg.name.length > 0) return pkg.name;
+  return '';
+}
+
+export const __testInternals = Object.freeze({ sha256Hex, derivePublisher, readPackageJson });

package/src/schema/pgserve-meta.js

@@ -0,0 +1,120 @@
+/**
+ * `pgserve_meta` table bootstrap.
+ *
+ * pgserve singleton (v2.4) — `pgserve-singleton-no-proxy` wish, Group 3
+ * (foundation for `pgserve provision` and `pgserve gc`).
+ *
+ * Schema rationale (Decision P4 — additive across the cohort):
+ *
+ *   `pgserve_meta` is the single source of truth for "which postgres
+ *   databases on this host belong to a known pgserve consumer."
+ *   `pgserve provision` writes a row when it idempotently CREATEs a DB +
+ *   role for a fingerprint. `pgserve gc` scans the table and DROPs DBs
+ *   whose `last_used_at` is older than the configured stale threshold or
+ *   whose source_path no longer exists. The cosign verify columns
+ *   (`verified_at`, `verified_identity`, `verified_tier`) are layered on
+ *   top via `src/cosign/schema.js#applyVerifiedColumns`; they ALTER this
+ *   table after CREATE.
+ *
+ * Why a separate module from cosign/schema.js: cosign owns the
+ * verification *delta*; this module owns the *base* table. Splitting
+ * them keeps the cosign migration genuinely additive (it's a no-op on
+ * fresh DBs that haven't bootstrapped, exactly as documented in
+ * cosign-meta-migration.js).
+ *
+ * Idempotency: every statement uses `IF NOT EXISTS` (table, columns,
+ * indexes). Re-running on an already-bootstrapped database is a no-op.
+ */
+
+export const PGSERVE_META_TABLE = 'pgserve_meta';
+
+/**
+ * Base columns owned by this module. Cosign columns are owned by
+ * src/cosign/schema.js and ALTERed in afterwards.
+ */
+export const PGSERVE_META_COLUMNS = Object.freeze([
+  'fingerprint',
+  'database_name',
+  'role_name',
+  'publisher',
+  'source_path',
+  'created_at',
+  'last_used_at',
+]);
+
+/**
+ * Idempotent statements that CREATE the table + supporting indexes.
+ * Returned as an array so callers can run each one individually for
+ * clear error reporting (mirrors cosign/schema.js#getMigrationStatements).
+ *
+ * Constraints:
+ *   - fingerprint:    PRIMARY KEY — the package.json sha256 fingerprint
+ *   - database_name:  UNIQUE NOT NULL — guards against accidental dupes
+ *   - role_name:      NOT NULL — every provisioned DB has a paired role
+ *   - publisher:      nullable — older path-tier installs may have none
+ *   - source_path:    nullable — fallback fingerprint may not have one
+ *   - created_at:     NOT NULL DEFAULT now() — set on insert
+ *   - last_used_at:   NOT NULL DEFAULT now() — touched by provision; gc
+ *                     uses it as the staleness signal
+ */
+// Schema-qualified name. The upgrade pipeline probes
+// `to_regclass('public.pgserve_meta')` (cosign-meta-migration.js); if a
+// non-default search_path is configured on the active role, an
+// unqualified CREATE TABLE could land the bootstrap in a non-public
+// schema while later migrations + gc continue to look in `public.`. The
+// only safe option is to qualify both halves consistently.
+const QUALIFIED = `public.${PGSERVE_META_TABLE}`;
+
+export function getBootstrapStatements() {
+  return [
+    [
+      `CREATE TABLE IF NOT EXISTS ${QUALIFIED} (`,
+      '  fingerprint   TEXT        PRIMARY KEY,',
+      '  database_name TEXT        NOT NULL UNIQUE,',
+      '  role_name     TEXT        NOT NULL,',
+      '  publisher     TEXT,',
+      '  source_path   TEXT,',
+      '  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),',
+      '  last_used_at  TIMESTAMPTZ NOT NULL DEFAULT now()',
+      ')',
+    ].join('\n'),
+    `CREATE INDEX IF NOT EXISTS ${PGSERVE_META_TABLE}_last_used_at_idx ON ${QUALIFIED} (last_used_at)`,
+    `CREATE INDEX IF NOT EXISTS ${PGSERVE_META_TABLE}_publisher_idx ON ${QUALIFIED} (publisher)`,
+  ];
+}
+
+/**
+ * Single SQL string variant — convenient for embedding the bootstrap in
+ * a transaction or pg-init script.
+ */
+export function getBootstrapSQL() {
+  return `${getBootstrapStatements().join(';\n\n')};\n`;
+}
+
+/**
+ * Apply the bootstrap via a node-postgres-compatible client. The client
+ * must expose an async `query(sql)` method (matches both `pg.Client` and
+ * `pg.PoolClient`). Returns the list of statements executed.
+ *
+ * Statements run sequentially so a failure on the index half doesn't
+ * masquerade as success after the table half ran.
+ */
+export async function bootstrapPgserveMeta(client) {
+  if (!client || typeof client.query !== 'function') {
+    throw new TypeError('bootstrapPgserveMeta: client must expose an async query() method');
+  }
+  const statements = getBootstrapStatements();
+  for (const sql of statements) {
+    await client.query(sql);
+  }
+  return statements;
+}
+
+/**
+ * Predicate the upgrade pipeline calls before deciding whether to run
+ * the cosign-verify ALTER chain. We avoid loading pg here — callers pass
+ * the result of `SELECT to_regclass('public.pgserve_meta') IS NOT NULL`.
+ */
+export function tableExistsFromRegclass(toRegclassResult) {
+  return toRegclassResult === true;
+}

package/src/security/blocked-versions.js

@@ -0,0 +1,103 @@
+/**
+ * Hardcoded blocklist — pgserve-singleton-no-proxy wish, Group 5.
+ *
+ * Compile-time list of pgserve versions that `pgserve install` and
+ * `pgserve update` MUST refuse, with a clear diagnostic. The trust root
+ * is opaque to operators: they cannot edit this file at runtime, only
+ * receive an updated list via `pgserve update`.
+ *
+ * Per SHARED-DESIGN.md §2.5: this is the ONLY revocation surface for v2.4+.
+ * No Rekor consultation, no revoked.json sync, no DNS-served blocklist.
+ * The list grows when a known-bad version ships and gets pinned here, then
+ * an updated pgserve release rolls out via the normal channel.
+ *
+ * Format: array of { version, reason, advisoryUrl? } records.
+ *   - version: exact semver string. Range matchers are intentionally
+ *     unsupported — every blocked version is named explicitly so an
+ *     auditor reading this file knows exactly what is rejected.
+ *   - reason: one-line operator-facing explanation (printed on refusal).
+ *   - advisoryUrl: optional pointer to a CVE/security advisory for the
+ *     blocked release.
+ */
+
+/**
+ * @typedef {Object} BlockedVersion
+ * @property {string} version  Exact semver string (no ranges).
+ * @property {string} reason   Operator-facing diagnostic line.
+ * @property {string} [advisoryUrl]  Pointer to CVE/security advisory.
+ */
+
+/** @type {readonly BlockedVersion[]} */
+export const BLOCKED_VERSIONS = Object.freeze([
+  // Empty by default. Populate as known-bad versions are identified.
+  // Example shape (uncomment + edit when a real block is needed):
+  //   { version: '2.6.0', reason: 'Postmaster crash on Linux ARM64 — see #999', advisoryUrl: 'https://github.com/namastexlabs/pgserve/security/advisories/GHSA-xxxx' },
+]);
+
+/**
+ * Test-only override. The compile-time list is frozen so production code
+ * cannot mutate it; tests need a way to inject blocked entries to exercise
+ * the throw path. Populated via __addBlockedForTest() and consulted by
+ * findBlocked() when non-empty. Cleared via __clearBlockedTestOverridesForTest().
+ *
+ * @type {BlockedVersion[]}
+ */
+const _testOverrides = [];
+
+/**
+ * Test-only — register an additional blocked entry for the lifetime of a
+ * test. Call __clearBlockedTestOverridesForTest() in afterEach to keep
+ * tests isolated.
+ *
+ * @param {BlockedVersion} entry
+ */
+export function __addBlockedForTest(entry) {
+  if (!entry || typeof entry.version !== 'string' || typeof entry.reason !== 'string') {
+    throw new Error('__addBlockedForTest: entry needs { version, reason }');
+  }
+  _testOverrides.push(entry);
+}
+
+/** Test-only — drop all entries registered via __addBlockedForTest. */
+export function __clearBlockedTestOverridesForTest() {
+  _testOverrides.length = 0;
+}
+
+/**
+ * Find the blocklist entry for an exact version string, if any.
+ * Considers both the compile-time BLOCKED_VERSIONS list and any test
+ * overrides registered via __addBlockedForTest().
+ *
+ * @param {string} version
+ * @returns {BlockedVersion | undefined}
+ */
+export function findBlocked(version) {
+  if (typeof version !== 'string' || version.length === 0) return undefined;
+  const fromOverrides = _testOverrides.find((b) => b.version === version);
+  if (fromOverrides) return fromOverrides;
+  return BLOCKED_VERSIONS.find((b) => b.version === version);
+}
+
+/**
+ * Assert that a version is not blocked. Throws an Error with a stable,
+ * grep-able prefix (`EBLOCKEDVERSION`) when the version is blocked, so
+ * callers (cli-install / upgrade) can detect it and exit with a known code.
+ *
+ * @param {string} version
+ * @throws {Error} when version is blocked
+ */
+export function assertNotBlocked(version) {
+  const hit = findBlocked(version);
+  if (!hit) return;
+  const lines = [
+    `EBLOCKEDVERSION: pgserve@${version} is blocked.`,
+    `  reason: ${hit.reason}`,
+  ];
+  if (hit.advisoryUrl) lines.push(`  advisory: ${hit.advisoryUrl}`);
+  lines.push('  remediation: install a different version (run `pgserve update` for the latest).');
+  const err = new Error(lines.join('\n'));
+  err.code = 'EBLOCKEDVERSION';
+  err.version = version;
+  err.reason = hit.reason;
+  throw err;
+}

package/src/upgrade/steps/binary-cache-flush.js

@@ -57,8 +57,8 @@ export async function execute({ log, warn }) {
 
   if (!downloadFn) {
     warn(`binary needs refresh (pinned=${pinned}, cached=${marker || 'missing'}) but autopg postgres module not exposing download API`);
-    warn(`operator action: rerun \`bun install -g @automagik/autopg@latest\``);
-    return { status: 'FAIL', detail: 'binary refresh needs autopg npm reinstall' };
+    warn(`operator action: rerun \`curl -fsSL https://raw.githubusercontent.com/namastexlabs/pgserve/main/install.sh | bash\` to refresh from GitHub Releases`);
+    return { status: 'FAIL', detail: 'binary refresh needs install.sh rerun (no npm dependency)' };
   }
   log(`re-downloading PG ${pinned} into ${cacheDir}`);
   await downloadFn({ version: pinned, targetDir: cacheDir });