pgserve 2.6.1 → 2.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.6.1",
+  "version": "2.6.4",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",

package/scripts/aggregate-manifest.sh

@@ -29,7 +29,7 @@ DIST_DIR="${AUTOPG_DIST_DIR:-${REPO_ROOT}/dist}"
 
 usage() {
   cat <<EOF
-Usage: $0 --version <v> [--base-url <url>] [--channel <c>] [--cosign-pub-url <url>]
+Usage: $0 --version <v> [--base-url <url>] [--channel <c>] [--trust-regex <re>]
 
   --version          autopg version, e.g. 2.260503.1 (or read from package.json)
   --base-url         absolute base URL prefix for tarball URLs
@@ -37,14 +37,18 @@ Usage: $0 --version <v> [--base-url <url>] [--channel <c>] [--cosign-pub-url <ur
                       directory the manifest sits in).
   --channel          channel hint embedded in the manifest (stable|beta|canary).
                      default: stable
-  --cosign-pub-url   absolute URL to the published cosign public key.
-                     default: <base-url>/../../keys/cosign.pub for production
-                     (cdn.automagik.dev layout) or "keys/cosign.pub" relative.
+  --trust-regex      cosign keyless identity regex consumers verify against.
+                     default: pgserve's own sign-attest.yml@refs/tags/v.*
+                     anchor (mirrors src/cosign/trust-list.js
+                     automagik-pgserve-release entry).
+  --oidc-issuer      Sigstore OIDC issuer URL.
+                     default: https://token.actions.githubusercontent.com
 
 Reads:
   dist/autopg-<version>-<platform>.tar.gz
   dist/autopg-<version>-<platform>.tar.gz.sha256
   dist/autopg-<version>-<platform>.tar.gz.sig          (optional)
+  dist/autopg-<version>-<platform>.tar.gz.cert         (optional, Wave A keyless)
   dist/autopg-<version>-<platform>.tar.gz.intoto.jsonl (optional)
 
 Writes:
@@ -56,13 +60,17 @@ parse_args() {
   VERSION="${AUTOPG_VERSION:-}"
   BASE_URL=""
   CHANNEL="stable"
-  COSIGN_PUB_URL=""
+  TRUST_REGEX_DEFAULT='^https://github.com/namastexlabs/pgserve/.github/workflows/sign-attest.yml@refs/tags/v.*$'
+  TRUST_REGEX=""
+  OIDC_ISSUER_DEFAULT="https://token.actions.githubusercontent.com"
+  OIDC_ISSUER=""
   while [[ $# -gt 0 ]]; do
     case "$1" in
-      --version)        VERSION="$2";        shift 2 ;;
-      --base-url)       BASE_URL="$2";       shift 2 ;;
-      --channel)        CHANNEL="$2";        shift 2 ;;
-      --cosign-pub-url) COSIGN_PUB_URL="$2"; shift 2 ;;
+      --version)        VERSION="$2";      shift 2 ;;
+      --base-url)       BASE_URL="$2";     shift 2 ;;
+      --channel)        CHANNEL="$2";      shift 2 ;;
+      --trust-regex)    TRUST_REGEX="$2";  shift 2 ;;
+      --oidc-issuer)    OIDC_ISSUER="$2";  shift 2 ;;
       -h|--help)        usage; exit 0 ;;
       *) echo "unknown arg: $1" >&2; usage; exit 2 ;;
     esac
@@ -73,6 +81,8 @@ parse_args() {
   if [[ -z "$VERSION" ]]; then
     echo "error: --version required (or set in package.json)" >&2; exit 2
   fi
+  [[ -n "$TRUST_REGEX" ]] || TRUST_REGEX="$TRUST_REGEX_DEFAULT"
+  [[ -n "$OIDC_ISSUER" ]] || OIDC_ISSUER="$OIDC_ISSUER_DEFAULT"
 }
 
 # Portable SHA256 — sha256sum on linux, shasum -a 256 on macOS.
@@ -109,10 +119,13 @@ emit_entry() {
   sha=$(awk '{print $1}' "${tarball}.sha256")
   sz=$(stat -c %s "$tarball" 2>/dev/null || stat -f %z "$tarball")
 
-  local sig_url="" prov_url=""
+  local sig_url="" cert_url="" prov_url=""
   if [[ -f "${tarball}.sig" ]]; then
     sig_url=$(prefix_url "${base}.sig")
   fi
+  if [[ -f "${tarball}.cert" ]]; then
+    cert_url=$(prefix_url "${base}.cert")
+  fi
   if [[ -f "${tarball}.intoto.jsonl" ]]; then
     prov_url=$(prefix_url "${base}.intoto.jsonl")
   fi
@@ -124,8 +137,9 @@ emit_entry() {
   printf '      "url": "%s",\n'      "$(prefix_url "$base")"
   printf '      "sha256": "%s",\n'   "$sha"
   printf '      "size": %d,\n'       "$sz"
-  printf '      "signature_url": "%s",\n' "$sig_url"
-  printf '      "provenance_url": "%s"\n' "$prov_url"
+  printf '      "signature_url": "%s",\n'   "$sig_url"
+  printf '      "certificate_url": "%s",\n' "$cert_url"
+  printf '      "provenance_url": "%s"\n'   "$prov_url"
   printf '    }'
 }
 
@@ -154,20 +168,22 @@ main() {
     printf '  "channel": "%s",\n' "$CHANNEL"
     printf '  "schemaVersion": 1,\n'
     printf '  "generated_at": "%s",\n' "$generated_at"
-    local cpub
-    if [[ -n "$COSIGN_PUB_URL" ]]; then
-      cpub="$COSIGN_PUB_URL"
-    elif [[ -n "$BASE_URL" ]]; then
-      # CDN layout: <base>/autopg/<channel>/<version>/manifest.json
-      # Public key lives at: <base>/autopg/keys/cosign.pub
-      # If caller passes the full <base>/autopg/<channel>/<version> as
-      # base-url, walk two levels up to reach the keys/ sibling.
-      cpub="${BASE_URL%/*}"
-      cpub="${cpub%/*}/keys/cosign.pub"
-    else
-      cpub="keys/cosign.pub"
-    fi
-    printf '  "cosign_pub_url": "%s",\n' "$cpub"
+    # Wave A: keyless OIDC verification metadata. Consumers feed these
+    # into `cosign verify-blob --certificate-identity-regexp <regex>
+    # --certificate-oidc-issuer <url> --signature <sig> --certificate
+    # <cert> <tarball>`. Replaces the legacy `cosign_pub_url` field
+    # (which pointed at a pinned long-lived public key).
+    printf '  "cosign_verification": {\n'
+    printf '    "method": "keyless",\n'
+    # Escape backslashes + double quotes for JSON string safety. The
+    # trust regex commonly contains both; the issuer URL is unlikely to
+    # but a custom --oidc-issuer could carry them, so apply uniformly.
+    local trust_escaped issuer_escaped
+    trust_escaped=$(printf '%s' "$TRUST_REGEX" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g')
+    issuer_escaped=$(printf '%s' "$OIDC_ISSUER" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g')
+    printf '    "trust_identity_regexp": "%s",\n' "$trust_escaped"
+    printf '    "oidc_issuer": "%s"\n' "$issuer_escaped"
+    printf '  },\n'
     printf '  "platforms": [\n'
     local first=1
     for t in "${tarballs[@]}"; do

package/scripts/verify-published-artifacts.sh

@@ -1,10 +1,13 @@
 #!/usr/bin/env bash
 #
-# verify-published-artifacts.sh — Group 8 of autopg-distribution-cutover.
+# verify-published-artifacts.sh — operator post-release verification.
+# Wave A keyless rewrite (PR-B follow-up D13 companion).
 #
 # Validates that every autopg tarball in the given directory is:
 #   1. accompanied by its outer .sha256 and that the hash matches.
-#   2. cosign-signed (verifies against keys/cosign.pub or AUTOPG_COSIGN_PUB).
+#   2. cosign keyless-OIDC-signed — cert subject matches the trust regex
+#      (override via AUTOPG_TRUST_REGEX) under the Sigstore GH Actions
+#      OIDC issuer.
 #   3. accompanied by a SLSA L3 in-toto provenance attestation that
 #      slsa-verifier can verify against the source repo URI.
 #   4. listed in the aggregated manifest.json with matching metadata.
@@ -12,26 +15,39 @@
 # Usage:
 #   bash scripts/verify-published-artifacts.sh dist/
 #   bash scripts/verify-published-artifacts.sh dist/ --skip-slsa
-#   AUTOPG_COSIGN_PUB=tests/fixtures/cosign/cosign.pub \
+#   AUTOPG_TRUST_REGEX='^https://github.com/my-org/.+/.github/workflows/release\.yml@refs/tags/v.*$' \
 #     bash scripts/verify-published-artifacts.sh dist/
 #
 # Exit codes:
 #   0  all artifacts verified
 #   1  verification failure (any tarball fails any check)
 #   2  invalid args / missing inputs
-#
-# Group 8 acceptance criteria:
-#   - cosign verify-blob succeeds for every platform tarball
-#   - slsa-verifier verify-artifact succeeds for every platform tarball
-#   - tampered tarball fails both verifications
-#   - script exits non-zero if any tarball ships without sig + provenance
 
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-COSIGN_PUB_DEFAULT="${REPO_ROOT}/keys/cosign.pub"
-COSIGN_PUB="${AUTOPG_COSIGN_PUB:-${COSIGN_PUB_DEFAULT}}"
-SOURCE_URI_DEFAULT="github.com/automagik-dev/autopg"
+# Wave A: keyless OIDC verification is the default. Override mode is
+# selected by setting AUTOPG_COSIGN_PUB to a public-key path — that
+# triggers KEYED verification with `--key <path>`, used exclusively by
+# tests/integration/sign-attest-smoke.sh which signs offline with a
+# checked-in fixture keypair (cosign keyless requires Sigstore network
+# + OIDC, neither of which are available during the offline smoke).
+#
+# KEYLESS mode (default — production):
+#   - requires <tarball>.sig + <tarball>.cert
+#   - trust regex from AUTOPG_TRUST_REGEX (default below)
+#   - OIDC issuer from AUTOPG_OIDC_ISSUER (default below)
+#
+# KEYED mode (opt-in via AUTOPG_COSIGN_PUB):
+#   - requires <tarball>.sig only
+#   - public key path: $AUTOPG_COSIGN_PUB
+#   - trust regex / oidc issuer ignored
+COSIGN_PUB="${AUTOPG_COSIGN_PUB:-}"
+TRUST_REGEX_DEFAULT='^https://github.com/namastexlabs/pgserve/.github/workflows/sign-attest.yml@refs/tags/v.*$'
+TRUST_REGEX="${AUTOPG_TRUST_REGEX:-${TRUST_REGEX_DEFAULT}}"
+OIDC_ISSUER_DEFAULT="https://token.actions.githubusercontent.com"
+OIDC_ISSUER="${AUTOPG_OIDC_ISSUER:-${OIDC_ISSUER_DEFAULT}}"
+
+SOURCE_URI_DEFAULT="github.com/namastexlabs/pgserve"
 SOURCE_URI="${AUTOPG_SOURCE_URI:-${SOURCE_URI_DEFAULT}}"
 
 PASS=0
@@ -47,18 +63,26 @@ usage() {
   cat <<EOF
 Usage: $0 <dist-dir> [--skip-slsa] [--skip-manifest]
 
-Verifies every autopg-*.tar.gz in <dist-dir> using:
-  - keys/cosign.pub    (override with AUTOPG_COSIGN_PUB=<path>)
+KEYLESS mode (default — production):
+  - trust regex        ${TRUST_REGEX_DEFAULT}
+                       (override with AUTOPG_TRUST_REGEX=<regex>)
+  - oidc issuer        ${OIDC_ISSUER_DEFAULT}
+                       (override with AUTOPG_OIDC_ISSUER=<url>)
+  - required siblings  <tarball>.sha256 + .sig + .cert
+                       + .intoto.jsonl (skip with --skip-slsa)
+
+KEYED mode (opt-in for offline fixture smoke — set AUTOPG_COSIGN_PUB):
+  - public key path    \$AUTOPG_COSIGN_PUB
+  - required siblings  <tarball>.sha256 + .sig
+                       + .intoto.jsonl (skip with --skip-slsa)
+  - trust regex / oidc issuer ignored
+
+Always:
   - source URI         ${SOURCE_URI_DEFAULT}
                        (override with AUTOPG_SOURCE_URI=<uri>)
 
-Required siblings per tarball:
-  <tarball>.sha256
-  <tarball>.sig
-  <tarball>.intoto.jsonl    (skip with --skip-slsa)
-
 Optional:
-  manifest.json            (skip with --skip-manifest)
+  manifest.json        (skip with --skip-manifest)
 EOF
 }
 
@@ -76,8 +100,9 @@ parse_args() {
   if [[ ! -d "$DIST_DIR" ]]; then
     echo "error: dist dir not found: $DIST_DIR" >&2; exit 2
   fi
-  if [[ ! -f "$COSIGN_PUB" ]]; then
-    echo "error: cosign public key not found: $COSIGN_PUB" >&2; exit 2
+  if [[ -n "$COSIGN_PUB" && ! -f "$COSIGN_PUB" ]]; then
+    echo "error: AUTOPG_COSIGN_PUB set but file not found: $COSIGN_PUB" >&2
+    exit 2
   fi
 }
 
@@ -127,14 +152,35 @@ verify_cosign() {
     bad "$(basename "$tarball"): missing .sig sibling"
     return 1
   fi
-  if cosign verify-blob \
-        --key "$COSIGN_PUB" \
-        --signature "$sig" \
-        "$tarball" >/dev/null 2>&1; then
-    ok "$(basename "$tarball"): cosign signature verifies"
+  if [[ -n "$COSIGN_PUB" ]]; then
+    # KEYED mode (offline fixture smoke).
+    if cosign verify-blob \
+          --key "$COSIGN_PUB" \
+          --signature "$sig" \
+          "$tarball" >/dev/null 2>&1; then
+      ok "$(basename "$tarball"): cosign keyed signature verifies"
+    else
+      bad "$(basename "$tarball"): cosign verify-blob FAILED (key=${COSIGN_PUB})"
+      return 1
+    fi
   else
-    bad "$(basename "$tarball"): cosign verify-blob FAILED"
-    return 1
+    # KEYLESS mode (default — production).
+    local cert="${tarball}.cert"
+    if [[ ! -f "$cert" ]]; then
+      bad "$(basename "$tarball"): missing .cert sibling (keyless OIDC requires it)"
+      return 1
+    fi
+    if cosign verify-blob \
+          --certificate-identity-regexp "$TRUST_REGEX" \
+          --certificate-oidc-issuer "$OIDC_ISSUER" \
+          --signature "$sig" \
+          --certificate "$cert" \
+          "$tarball" >/dev/null 2>&1; then
+      ok "$(basename "$tarball"): cosign keyless signature verifies"
+    else
+      bad "$(basename "$tarball"): cosign verify-blob FAILED (regex=${TRUST_REGEX})"
+      return 1
+    fi
   fi
 }
 
@@ -172,8 +218,15 @@ main() {
   require_tools
 
   echo "==> verify-published-artifacts: $DIST_DIR"
-  echo "    cosign pub: $COSIGN_PUB"
-  echo "    source uri: $SOURCE_URI"
+  if [[ -n "$COSIGN_PUB" ]]; then
+    echo "    mode:        KEYED (AUTOPG_COSIGN_PUB set)"
+    echo "    cosign pub:  $COSIGN_PUB"
+  else
+    echo "    mode:        KEYLESS"
+    echo "    trust regex: $TRUST_REGEX"
+    echo "    oidc issuer: $OIDC_ISSUER"
+  fi
+  echo "    source uri:  $SOURCE_URI"
 
   local tarballs=()
   while IFS= read -r line; do

package/src/admin/admin-bootstrap.js

@@ -0,0 +1,296 @@
+/**
+ * Per-consumer admin + manifest bootstrap.
+ *
+ * pgserve singleton (v2.6) — `autopg-distribution-cutover-finalize`
+ * wish, Group 3 (`pgserve create-app` + manifest LOCK 1) deliverable D2.
+ *
+ * Writes two files to disk for a registered consumer:
+ *
+ *   ~/.autopg/<sanitized-slug>/admin.json    (mode 0600)
+ *   ~/.autopg/<sanitized-slug>/manifest.json (mode 0600)
+ *
+ * The containing directory is `0700`. Both files are derived caches of
+ * the authoritative `autopg_meta` row; cache-recovery (when divergence
+ * is detected by future doctor surfaces) is the V1 manual story:
+ * operator deletes the per-consumer dir + re-runs `pgserve create-app
+ * <slug>` (idempotent; preserves `locked_roots` from the table).
+ *
+ * Schema:
+ *
+ *   admin.json      { slug, manifestPath, lockedRoots: [...],
+ *                     createdAt, lastUpdated }
+ *
+ *   manifest.json   { schemaVersion: 1, slug, lockedRoots: [...],
+ *                     createdAt, lastUpdated }
+ *
+ *   The two files share the `slug` + `lockedRoots` fields by design —
+ *   admin.json is the orchestrator-facing record, manifest.json is the
+ *   verifier-facing copy with an explicit `schemaVersion` for future
+ *   migrations.
+ *
+ * Orthogonality: this per-consumer admin.json sits ONE directory level
+ * deeper than the host-level `~/.autopg/admin.json` (owned by
+ * `canonical-pgserve-pm2-supervision` G1, src/lib/admin-json.js). They
+ * never collide; the host record is `~/.autopg/admin.json`, the
+ * per-consumer record is `~/.autopg/<slug>/admin.json`.
+ *
+ * Slug sanitization: REUSES `sanitizeSlug` from
+ * src/provision/db-naming.js — the same canonical helper used to build
+ * provision database/role names. This guarantees the per-consumer dir
+ * for `@demo/app` resolves to `~/.autopg/demo_app/`, matching whatever
+ * provision/gc derived from the same input.
+ *
+ * TOCTOU defense: after mkdir, the resolved path is verified to still
+ * land inside the canonical autopg root via `fs.realpathSync` — refuses
+ * to write through a symlink that points outside `~/.autopg/`. The
+ * file writes themselves use the standard tmp + rename + chmod pattern
+ * already in src/lib/admin-json.js.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import { sanitizeSlug } from '../provision/db-naming.js';
+import { getDefaultConfigDir } from '../lib/admin-json.js';
+
+export const PER_CONSUMER_ADMIN_FILE = 'admin.json';
+export const PER_CONSUMER_MANIFEST_FILE = 'manifest.json';
+export const PER_CONSUMER_FILE_MODE = 0o600;
+export const PER_CONSUMER_DIR_MODE = 0o700;
+export const MANIFEST_SCHEMA_VERSION = 1;
+
+/**
+ * Resolve the per-consumer config directory for a given slug.
+ *
+ * `<configDir>/<sanitized-slug>` — defaults `<configDir>` to whatever
+ * `getDefaultConfigDir()` returns (`AUTOPG_CONFIG_DIR` >
+ * `PGSERVE_CONFIG_DIR` > `$HOME/.autopg`).
+ *
+ * Throws on empty/whitespace slug input — never silently coerce a bad
+ * slug to a flat path that would clobber the host-level admin.json or
+ * an unrelated consumer.
+ */
+export function getConsumerDir(slug, { configDir = getDefaultConfigDir() } = {}) {
+  if (typeof slug !== 'string' || slug.trim().length === 0) {
+    throw new TypeError('admin-bootstrap: slug must be a non-empty string');
+  }
+  const sanitized = sanitizeSlug(slug);
+  if (sanitized.length === 0) {
+    throw new TypeError(
+      `admin-bootstrap: slug "${slug}" sanitizes to empty; pick a slug `
+      + 'with at least one alphanumeric character',
+    );
+  }
+  return {
+    sanitized,
+    consumerDir: path.join(configDir, sanitized),
+    configDir,
+  };
+}
+
+export function getConsumerAdminPath(slug, opts) {
+  const { consumerDir } = getConsumerDir(slug, opts);
+  return path.join(consumerDir, PER_CONSUMER_ADMIN_FILE);
+}
+
+export function getConsumerManifestPath(slug, opts) {
+  const { consumerDir } = getConsumerDir(slug, opts);
+  return path.join(consumerDir, PER_CONSUMER_MANIFEST_FILE);
+}
+
+function ensureConfigRoot(configDir) {
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true, mode: PER_CONSUMER_DIR_MODE });
+  }
+}
+
+function ensureConsumerDir(configDir, consumerDir) {
+  ensureConfigRoot(configDir);
+  if (!fs.existsSync(consumerDir)) {
+    fs.mkdirSync(consumerDir, { recursive: true, mode: PER_CONSUMER_DIR_MODE });
+  }
+  // TOCTOU defense: refuse to write through a symlink that escapes the
+  // canonical config root. Resolve both the root and the consumer dir
+  // and assert containment.
+  let realRoot;
+  let realConsumer;
+  try {
+    realRoot = fs.realpathSync(configDir);
+    realConsumer = fs.realpathSync(consumerDir);
+  } catch (err) {
+    throw new Error(
+      `admin-bootstrap: failed to resolve real path for "${consumerDir}": ${err.message}`,
+    );
+  }
+  const rootWithSep = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep;
+  if (realConsumer !== realRoot && !realConsumer.startsWith(rootWithSep)) {
+    const err = new Error(
+      `admin-bootstrap: refusing to write — "${consumerDir}" resolves to `
+      + `"${realConsumer}", which is outside config root "${realRoot}". `
+      + 'Possible symlink attack; remove the symlink and retry.',
+    );
+    err.code = 'EAUTOPGCONSUMERESCAPE';
+    err.consumerDir = consumerDir;
+    err.realConsumer = realConsumer;
+    err.configRoot = realRoot;
+    throw err;
+  }
+  fs.chmodSync(consumerDir, PER_CONSUMER_DIR_MODE);
+  return realConsumer;
+}
+
+function atomicWrite(filePath, body) {
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, body, { mode: PER_CONSUMER_FILE_MODE });
+  fs.renameSync(tmp, filePath);
+  fs.chmodSync(filePath, PER_CONSUMER_FILE_MODE);
+}
+
+function jsonBody(payload) {
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}
+
+function deepCloneRoots(lockedRoots) {
+  if (!Array.isArray(lockedRoots)) {
+    throw new TypeError('admin-bootstrap: lockedRoots must be an array');
+  }
+  // Use JSON round-trip to drop any Object.freeze wrappers AND defensively
+  // copy nested fields. TRUSTED_IDENTITIES entries are plain objects with
+  // string values — no Date / Buffer / function / undefined that would
+  // round-trip badly.
+  return JSON.parse(JSON.stringify(lockedRoots));
+}
+
+/**
+ * Compose the on-disk records for a consumer. Pure function — no fs.
+ *
+ * Used by `bootstrapConsumerAdmin` (which writes them) and by the
+ * doctor surface (which compares against on-disk + table state).
+ */
+export function buildConsumerRecords({ slug, lockedRoots, createdAt, lastUpdated, configDir }) {
+  const { sanitized, consumerDir } = getConsumerDir(slug, { configDir });
+  const manifestPath = path.join(consumerDir, PER_CONSUMER_MANIFEST_FILE);
+  const cloned = deepCloneRoots(lockedRoots);
+
+  const adminRecord = {
+    slug: sanitized,
+    manifestPath,
+    lockedRoots: cloned,
+    createdAt,
+    lastUpdated,
+  };
+
+  const manifestRecord = {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    slug: sanitized,
+    lockedRoots: cloned,
+    createdAt,
+    lastUpdated,
+  };
+
+  return {
+    consumerDir,
+    sanitized,
+    manifestPath,
+    adminRecord,
+    manifestRecord,
+  };
+}
+
+/**
+ * Write the per-consumer admin.json + manifest.json pair.
+ *
+ * Inputs:
+ *   - slug         the input slug (will be sanitized via sanitizeSlug)
+ *   - lockedRoots  array of TRUSTED_IDENTITIES-shaped entries (frozen
+ *                  at create-app time); deep-cloned before write
+ *   - createdAt    ISO 8601 string; on first create-app
+ *   - lastUpdated  ISO 8601 string; touched every create-app re-run
+ *
+ * Idempotent: callers that re-run `pgserve create-app <slug>` should
+ * leave `createdAt` untouched (read it back from the autopg_meta row,
+ * not regenerated) and only refresh `lastUpdated`. The verb in D3
+ * threads this through.
+ *
+ * Returns the written records + paths so the caller can echo them in
+ * logs or feed them to a downstream reporter.
+ */
+export function bootstrapConsumerAdmin({
+  slug,
+  lockedRoots,
+  createdAt,
+  lastUpdated,
+  configDir = getDefaultConfigDir(),
+} = {}) {
+  if (typeof createdAt !== 'string' || createdAt.length === 0) {
+    throw new TypeError('admin-bootstrap: createdAt must be a non-empty ISO 8601 string');
+  }
+  if (typeof lastUpdated !== 'string' || lastUpdated.length === 0) {
+    throw new TypeError('admin-bootstrap: lastUpdated must be a non-empty ISO 8601 string');
+  }
+
+  const { sanitized, consumerDir, adminRecord, manifestRecord } =
+    buildConsumerRecords({ slug, lockedRoots, createdAt, lastUpdated, configDir });
+
+  const realConsumerDir = ensureConsumerDir(configDir, consumerDir);
+  // Recompute the manifest path to live under the resolved real dir so
+  // the manifestPath stored in admin.json matches what we actually
+  // wrote, even if the consumerDir we computed above was a symlink
+  // alias of the canonical realConsumerDir.
+  const adminFilePath = path.join(realConsumerDir, PER_CONSUMER_ADMIN_FILE);
+  const manifestFilePath = path.join(realConsumerDir, PER_CONSUMER_MANIFEST_FILE);
+  adminRecord.manifestPath = manifestFilePath;
+
+  atomicWrite(manifestFilePath, jsonBody(manifestRecord));
+  atomicWrite(adminFilePath, jsonBody(adminRecord));
+
+  return {
+    sanitized,
+    consumerDir: realConsumerDir,
+    adminPath: adminFilePath,
+    manifestPath: manifestFilePath,
+    adminRecord,
+    manifestRecord,
+  };
+}
+
+/**
+ * Read the consumer admin.json. Returns the parsed object on success,
+ * `null` when the file is missing or unreadable. Mirrors the read
+ * semantics of `readAdminJson` in src/lib/admin-json.js — never throws
+ * on missing/broken file.
+ */
+export function readConsumerAdmin(slug, { configDir = getDefaultConfigDir() } = {}) {
+  const file = getConsumerAdminPath(slug, { configDir });
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the consumer manifest.json. Same semantics as readConsumerAdmin.
+ */
+export function readConsumerManifest(slug, { configDir = getDefaultConfigDir() } = {}) {
+  const file = getConsumerManifestPath(slug, { configDir });
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : null;
+  } catch {
+    return null;
+  }
+}

package/src/cli-config.cjs

@@ -256,12 +256,49 @@ function cmdEdit() {
   return result.status ?? EXIT_OK;
 }
 
+const CONFIG_USAGE = `autopg config <subcommand> [args]
+
+Subcommands:
+  list                 - print every leaf as key|value|source (default with no subverb)
+  get <key>            - print the resolved value (machine-friendly)
+  set <key> <value>    - validate + atomic write
+  path                 - print the absolute path to settings.json
+  init [--force]       - write schema defaults; refuses to clobber unless --force
+  edit                 - open $EDITOR on settings.json
+
+Exit codes:
+  0  success
+  1  unknown subcommand / IO error / EDITOR not set / settings file unreadable
+  2  validation error (stable shape: \`error: <field> — <CODE>: <detail>\`)
+
+Reachable as either \`autopg config\` or \`pgserve config\` (single dispatch
+per Decision #7).`;
+
+function printConfigUsage() {
+  process.stdout.write(`${CONFIG_USAGE}\n`);
+}
+
 /**
  * Subcommand dispatch. Returns the exit code; the parent dispatcher
  * uses the return value as `process.exit(code)` directly.
  */
 function dispatch(subcommand, args = []) {
   switch (subcommand) {
+    // B6 (v2.6.3): honor --help / -h as a verb-level help request, NOT
+    // as an unknown subcommand. Pre-fix, the dispatcher hit the default
+    // branch which emitted `error: --help — INVALID_KEY: unknown config
+    // subcommand "--help"` AND printed the usage block AND returned
+    // EXIT_UNKNOWN. The wrapper at bin/pgserve-wrapper.cjs translated
+    // EXIT_UNKNOWN to a non-zero exit BUT the parent shell saw exit 0
+    // because of a stale process.exit path; either way the message
+    // shape "error:" + exit-code-status disagreed (the exact bug B6
+    // documented). Honoring --help removes the contradiction. Branch
+    // A in the QA recipe; truly unknown subverbs (T4) still hit the
+    // default branch + return EXIT_UNKNOWN.
+    case '--help':
+    case '-h':
+      printConfigUsage();
+      return EXIT_OK;
     case 'list':
       return cmdList();
     case 'get':