@bongos/core 1.19.888 → 1.19.889

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.888",
-  "core_contract": "1.19.888",
-  "source_commit": "7ccf0b2f4cc7f7bafb93762cbd5cfb9ed37cf546",
+  "core_version": "1.19.889",
+  "core_contract": "1.19.889",
+  "source_commit": "b7871cd73a1ce5f73988d99ef63101a6a2d23050",
   "source_ref": "HEAD",
-  "built_at": "2026-09-19T20:57:53.725Z",
+  "built_at": "2026-09-19T21:23:27.620Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 497,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2266,
+    "functional_verbatim": 2269,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2789,
-  "tree_sha256": "42c331016e53b14ca5416a325790e2846ea0ee2c6a24177222b823a1d2977b9c",
+  "file_count": 2792,
+  "tree_sha256": "b7b8bc9e53808070c5d46a211481ceef0dea2c901bc79e2b0dc0871e60c362b1",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2607,7 +2607,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7f60dfa2c479fecbd5a81de040689b9ff6f9d2aa5a907f9a7fcf86b77b476fea"
+      "sha256": "01a90a40951ae88d4c36c5fabbaf3debc0e02bcaa9fa8a7b70e247aa5d61d236"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2742,7 +2742,7 @@
     {
       "path": "docs/recipes/gds-db-backup.md",
       "mode": "0000644",
-      "sha256": "b3d6a3e3a400bf593b0f2d671f35cb1a60279f495c8763d311f8cdb68a6d603a"
+      "sha256": "d3e628bc627cb29874e977bf2e93c6557dc72a210506c22515a983f4f513d627"
     },
     {
       "path": "docs/recipes/instance-deploy.md",
@@ -3699,6 +3699,11 @@
       "mode": "0000644",
       "sha256": "4f35f87050a532f26b7c9cd0a9bc6f298ab5c0e15eb1c36ddcdd4d261201291d"
     },
+    {
+      "path": "migrations/core_249_session_token_hash.sql",
+      "mode": "0000644",
+      "sha256": "ae3e405c7e59fbc13e23ae2a4ba945176f2369a150c997d9b8134e49991f273b"
+    },
     {
       "path": "modules/agents/CLAUDE.md",
       "mode": "0000644",
@@ -7697,12 +7702,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d3b1b9f84e1713ff7815c19a9bd02b6c4de4dd3b44a5ede68ff56fbd5ad0cfcd"
+      "sha256": "d1348f68cd79ad102a381e3d7f90b784d9df605e859269ede84ad859cc831deb"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4cd9682e13a9a2e1e358c7bd500286378e7b5b8ceb1bb284a925b91ab8de2a08"
+      "sha256": "36e895c05e2aed3f97ce34ae3b3f73b0492fff7185077519068bc69dda6a8fd6"
     },
     {
       "path": "public-docs/index.html",
@@ -8132,7 +8137,7 @@
     {
       "path": "scripts/gds/db-backup-offsite.sh",
       "mode": "0000644",
-      "sha256": "f455e4a6fdd69f0105104752c86099e3a17dad7b4802fa715191cedab9762cd2"
+      "sha256": "97f52f6aff95e1c81e069c1d4228eecb514af6068c810441465b5f5b7ee0f2ce"
     },
     {
       "path": "scripts/gds/demote.js",
@@ -8807,7 +8812,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "8227fe5256b530d22192cd86f3624d52cc1dc34ac82099a8bb9e3d6a28482eb9"
+      "sha256": "a40a90ba6255820130aa6a94ddc314b643177e4a153750dc6290550a75e1a4e8"
     },
     {
       "path": "scripts/gds/runner-drift.js",
@@ -9447,12 +9452,12 @@
     {
       "path": "src/bongos/db-kernel.js",
       "mode": "0000644",
-      "sha256": "1fffc39fb9b70cd009d7d239729a9ff329cd41ca1f35b50b7c9e6b89aa83624e"
+      "sha256": "dd16328ac569aa8c6af09b2700957634e2c6d368d291b015a74a8dc452dc340a"
     },
     {
       "path": "src/bongos/db.js",
       "mode": "0000644",
-      "sha256": "e88c470ed9399be2930ec2d925e0864c30e355bf20d89486fb57dbe7561f6d78"
+      "sha256": "def84475a0470dafb894e7ca3f96f9db27cea78964f90ac3e81ed748fe9efa48"
     },
     {
       "path": "src/bongos/github-repos.js",
@@ -9707,7 +9712,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "ae3867dc81f944026ce67bae25ca927232b84accc4ed03d4ef45798526c72c46"
+      "sha256": "541b09991f4858b3255f250ef7e52e86b0d561ec69d058e74bc218fe1a104932"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10092,7 +10097,7 @@
     {
       "path": "tests/auth_session_expiry_db.mjs",
       "mode": "0000644",
-      "sha256": "880cbfa0304ab037db980f22471a2b46bcdbad0e7dca57af359402dbb068d6a4"
+      "sha256": "89730864ff5aa36271582c7e2717bf434bc84cbc20b615026005a1ef662ff31c"
     },
     {
       "path": "tests/auth_session_ttl.mjs",
@@ -11357,7 +11362,7 @@
     {
       "path": "tests/government_live_proof.mjs",
       "mode": "0000644",
-      "sha256": "6d829af6ef71bfa744a4ff457a4766b5cce021f317661579b06ecfc14298a523"
+      "sha256": "ca29425b30e726e6a7e939b008f0e5ca71877fa88fdcbfe1bf6356482f47c1e8"
     },
     {
       "path": "tests/government_live_proof_shape.mjs",
@@ -12372,7 +12377,7 @@
     {
       "path": "tests/own_session_revoke.mjs",
       "mode": "0000644",
-      "sha256": "34ae2846e314ad4ba732a40257fb81f7b4e4be3e81e3b6d1f478c3bb0690f23d"
+      "sha256": "ff24d3753a52a64f426e0602bc2411aad13c1426c2bc0774b7618a1d20cebfad"
     },
     {
       "path": "tests/package_core.mjs",
@@ -13234,6 +13239,16 @@
       "mode": "0000644",
       "sha256": "a630ac72981f230e8aa6609152765c13e8928ac329cb0ff3fe615371f31208d2"
     },
+    {
+      "path": "tests/session_token_hash.mjs",
+      "mode": "0000644",
+      "sha256": "ff4cea59acb15ce383d9346793206865f0aababc5e2f4144c957bb93d45f62b4"
+    },
+    {
+      "path": "tests/session_token_hash_db.mjs",
+      "mode": "0000644",
+      "sha256": "4a757c27f11cde314649e46ab24e51600d24c2f503f1aa7f055cdb4fa60ea6ce"
+    },
     {
       "path": "tests/session_type.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2250,5 +2250,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.886 with no explicit bump. run 35468511941. (task 1002620)
   1.19.888 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.887 with no explicit bump. run 35468948342. (task 1002620)
+  1.19.889 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.888 with no explicit bump. run 35470239834. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/gds-db-backup.md

@@ -46,8 +46,33 @@ gds-db-offsite.timer ──→ gds-db-offsite.service ──→ db-backup-offsit
 - **It does not take its own `pg_dump`.** It uploads the newest `/var/backups/gds/<db>-*.sql.gz` that the local nightly already produced. Runs at 05:00 UTC — one hour after the 04:00 local dump — so the copy is same-day-fresh.
 - **Bucket layout:** objects land under the `gds-offsite/` key prefix in the Space.
 - **Retention:** 4 weekly copies (`GDS_OFFSITE_KEEP=4` — ~1 month), pruned oldest-first under that prefix. Sub-1 MB each.
-- **Credentials** live at `/etc/example/spaces.env` (chmod 600, owned by `lars`), never in the repo (ADR 0022). Required vars: `SPACES_KEY`, `SPACES_SECRET`, `SPACES_BUCKET`, `SPACES_REGION`, `SPACES_ENDPOINT`. systemd injects them via `EnvironmentFile`; a manual run sources the same file.
-- **Dependency:** `python3` + the `boto3` module on the droplet. The script fails loudly if either is missing.
+- **Credentials** live at `/etc/example/spaces.env` (chmod 600, owned by `lars`), never in the repo (ADR 0022). Required vars: `SPACES_KEY`, `SPACES_SECRET`, `SPACES_BUCKET`, `SPACES_REGION`, `SPACES_ENDPOINT`, `GDS_OFFSITE_AGE_RECIPIENT`. systemd injects them via `EnvironmentFile`; a manual run sources the same file.
+- **Dependency:** `age`, plus `python3` + the `boto3` module on the droplet. The script fails loudly if any is missing.
+- **The uploaded object is encrypted** (`<db>-<date>.sql.gz.age`) and the retention count applies to those. Any legacy plaintext `.sql.gz` object still under the prefix is **deleted on the next run**, outside the retention count — see below.
+
+#### Offsite dumps are encrypted (task [#1003372](https://cloudbongos.com/builders#/task/1003372), audit A1)
+
+Until this task the weekly job uploaded the raw `pg_dump`. A dump is not merely "a backup": it is every secret the platform holds, in one file, on storage the platform does not own — OAuth credentials, the GitHub App private key, and (before `core_249`) every builder's live session bearer in plaintext. A breach of the Space, a mis-set bucket ACL or a leaked read-only S3 key was a total compromise with no trace in any log we keep.
+
+The dump is now encrypted with [`age`](https://github.com/FiloSottile/age) **to a public key**, so the droplet can produce backups it cannot itself read. That asymmetry is the point: an attacker who owns the droplet already has the live database, but they do not also get the archive of every previous state, and they cannot decrypt what is already in the Space. **Keep the private key off the server.**
+
+```bash
+# ONE-TIME, on a machine that is NOT the server:
+age-keygen -o bongos-backup.key      # store safe + OFFLINE — this is the only way back
+# it prints:  Public key: age1xxxxxxxx...
+```
+
+Add the **public** key to `/etc/example/spaces.env` as `GDS_OFFSITE_AGE_RECIPIENT=age1...`.
+
+> **Without a recipient the job refuses to run**, and does not fall back to a plaintext upload — that fallback is the vulnerability, and a silent one, since a backup that "worked" looks identical either way. A failing timer is visible in `systemctl status gds-db-offsite.timer`; an unencrypted dump in a bucket is visible to nobody until it matters. **If offsite backups stop after this deploy, this is why** — set the recipient.
+>
+> **The first successful run also PURGES every unencrypted `.sql.gz` already in the Space**, unconditionally and outside the retention count. Encrypting from here on does nothing about the copies already up there, and retaining four of them "for safety" would retain the finding. Local nightly dumps on the droplet are untouched, so this removes copies, never the last copy.
+
+To restore an offsite object:
+
+```bash
+age -d -i bongos-backup.key <db>-<date>.sql.gz.age | gunzip | psql <db>
+```
 
 > **History:** an earlier task ([#7](https://example.com/builders#/task/7)) shipped a `scripts/backup.sh` + `/etc/cron.d/otb-backup` daily-to-Spaces cron that was forgotten and never worked (empty credentials, no Space, no log). [#415](https://example.com/builders#/task/415) retired it and replaced it with the systemd unit above. If you find any trace of `otb-backup.cron`, `scripts/backup.sh`, or `~/.config/otb/spaces.env` on a host, it's dead — remove it.
 >
@@ -65,6 +90,9 @@ SPACES_SECRET=...
 SPACES_BUCKET=otb-gds-backups
 SPACES_REGION=nyc3
 SPACES_ENDPOINT=https://nyc3.digitaloceanspaces.com
+# The age PUBLIC key from `age-keygen`, generated OFF this box (see above).
+# Without it the job refuses to run rather than upload plaintext.
+GDS_OFFSITE_AGE_RECIPIENT=age1...
 ENV
 sudo chmod 600 /etc/example/spaces.env
 

package/migrations/core_249_session_token_hash.sql

@@ -0,0 +1,103 @@
+-- core_249 — builder_sessions stores a HASH of the bearer, never the bearer
+-- (task 1003372, audit ref A1 from the 2026-08-29 security audit, goal 1000084).
+--
+-- forward-unsafe: drops builder_sessions.token and makes token_hash NOT NULL.
+-- Both are the point of the migration, not incidental to it. The whole finding is
+-- that the plaintext bearer is READABLE AT REST, so a version of this that kept the
+-- column would not fix anything; and the NOT NULL is what stops a future writer
+-- inserting a session no lookup can ever match. Neither is reversible, and neither
+-- should be: rolling back to code that reads `token` finds it gone, but a variant
+-- that merely emptied the column would leave that code finding NULL and signing
+-- everyone out just the same — so the unsafety is in the rollback direction only,
+-- and is identical either way. Forward, nobody is signed out: the backfill below
+-- derives every existing row's hash from the plaintext before the column goes.
+--
+-- WHAT WAS WRONG. `token` held the live bearer in plaintext, NOT NULL UNIQUE and
+-- INDEXED. Every row was a directly replayable credential for the builder it
+-- belonged to — Archons included — so ANY read of this table was a complete
+-- takeover of every account holding a session. That is the exact credential the
+-- whole ADR 0016 trust boundary rests on: the server re-resolves authority per
+-- request from a token, so a token IS the authority. `token_hash` had zero
+-- occurrences repo-wide before this migration.
+--
+-- A read of the table is not hypothetical. The offsite dump was uploaded
+-- unencrypted (same task, `scripts/gds/db-backup-offsite.sh`), and a co-tenant
+-- Postgres role reached this table across tenants until task 1003369 split the
+-- unix accounts. Hashing at rest is what makes those reads worthless rather than
+-- catastrophic.
+--
+-- WHY A BACKFILL AND NOT A FORCED RE-AUTH. The hash is computable from the
+-- plaintext we already hold, so every live session survives the change: the row
+-- keeps working and its holder notices nothing. The alternative — ship the code
+-- and let sessions re-mint — would sign out every builder and every dev box on
+-- deploy day to reach a state this statement reaches for free. Migration 035 and
+-- core_243 both reasoned this way in their own direction: do not put a policy
+-- change on the backs of the people holding live sessions when it lands.
+--
+-- WHY sha256 WITH NO EXTENSION. Postgres 16 (docs/architecture.md) carries
+-- `sha256(bytea)` as a built-in, so the backfill needs no pgcrypto — one less
+-- extension to have installed on a box before a migration will run. It is the
+-- same digest `db-kernel.js` computes in Node, so a row backfilled here and a row
+-- minted by the code resolve identically.
+--
+-- WHY A FAST HASH IS THE RIGHT ONE. A session token is 256 bits of CSPRNG, not a
+-- password: there is no dictionary to run and nothing to slow an attacker down,
+-- so bcrypt/argon would buy nothing and cost a KDF on every authenticated
+-- request. The same reasoning is written out at
+-- `modules/platform-identity/platform-identity.js` (`sha256hex`), which hashes
+-- its client secrets and authorization codes for exactly this reason.
+--
+-- WHY THE PLAINTEXT COLUMN IS DROPPED, NOT NULLED. Nulling it would leave a dead
+-- column that still has to be kept empty by every future writer, and it buys no
+-- rollback safety: rolling back to code that reads `token` finds it NULL and
+-- signs everyone out either way. Dropping it is the honest end state, and the
+-- unique index moves to `token_hash` so the uniqueness guarantee is unbroken.
+--
+-- WHAT THIS DOES NOT CHANGE. Expiry is untouched. ADR 0294 (CLI sessions do not
+-- expire) and ADR 0206 (no absolute ceiling) both stand exactly as written; this
+-- migration does not read, write or reason about `expires_at`. The audit also
+-- asked for refresh-on-use to stop and an absolute lifetime to be added — both are
+-- decisions those two ADRs have already taken the other way, with the owner as
+-- decider, AFTER this audit was filed. Changing them is not this task's to do.
+--
+-- IDEMPOTENT. The whole body is guarded on the plaintext column still existing,
+-- so a second run is a no-op rather than an error about a column that is gone.
+
+BEGIN;
+
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_name = 'builder_sessions' AND column_name = 'token'
+  ) THEN
+
+    ALTER TABLE builder_sessions ADD COLUMN IF NOT EXISTS token_hash text;
+
+    -- Every live row keeps working: the hash is derived from the bearer already
+    -- stored, so no holder is signed out by this deploy.
+    UPDATE builder_sessions
+       SET token_hash = encode(sha256(token::bytea), 'hex')
+     WHERE token_hash IS NULL;
+
+    -- The invariant the lookup depends on. Enforced only after the backfill has
+    -- given every existing row a value.
+    ALTER TABLE builder_sessions ALTER COLUMN token_hash SET NOT NULL;
+
+    -- Carries over `token`'s UNIQUE: two sessions may not share a bearer, and the
+    -- hash is what the lookup now keys on, so it needs the same index the
+    -- plaintext had for the same reason.
+    CREATE UNIQUE INDEX IF NOT EXISTS ux_builder_sessions_token_hash
+      ON builder_sessions (token_hash);
+
+    DROP INDEX IF EXISTS idx_builder_sessions_token;
+    ALTER TABLE builder_sessions DROP COLUMN token;
+
+  END IF;
+END
+$$;
+
+COMMENT ON COLUMN builder_sessions.token_hash IS
+  'SHA-256 hex of the bearer token. The plaintext is NEVER stored (core_249, audit A1): it exists only in the response that mints it and in the client that holds it. lookupSession hashes the presented bearer and keys on this column, so a read of this table yields nothing replayable.';
+
+COMMIT;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.888",
+  "version": "1.19.889",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.888",
+      "version": "1.19.889",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.888",
+  "version": "1.19.889",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/db-backup-offsite.sh

@@ -17,6 +17,36 @@
 # ADR 0022. The systemd unit injects them via EnvironmentFile; a manual run
 # sources the same file. Required vars:
 #   SPACES_KEY SPACES_SECRET SPACES_BUCKET SPACES_REGION SPACES_ENDPOINT
+#   GDS_OFFSITE_AGE_RECIPIENT
+#
+# ENCRYPTION IS MANDATORY (task 1003372, audit ref A1). Until that task this
+# script uploaded the raw pg_dump to the Space. A database dump is not "a backup"
+# from a security standpoint — it is every secret the platform holds, in one
+# file, on someone else's disk: OAuth credentials, the GitHub App private key,
+# and (before core_249) every builder's live session bearer in plaintext. A
+# breach of the Space, a mis-set bucket ACL, or a leaked read-only S3 key was a
+# total compromise of the instance with no trace in any log the platform keeps.
+#
+# The dump is encrypted to a PUBLIC key (`age`), so this box can produce backups
+# it cannot itself read. That asymmetry is the point: an attacker who owns the
+# droplet gets the live database anyway, but they do not also get the archive of
+# every previous state, and they cannot decrypt what is already in the Space.
+# Keep the private key OFF this machine.
+#
+# One-time setup, on a machine that is NOT the server:
+#   age-keygen -o bongos-backup.key      # store this somewhere safe and offline
+#   # it prints:  Public key: age1xxxxxxxx...
+# Then on the server, add to $ENV_FILE:
+#   GDS_OFFSITE_AGE_RECIPIENT=age1xxxxxxxx...
+#
+# To restore:
+#   age -d -i bongos-backup.key <dump>.sql.gz.age | gunzip | psql <db>
+#
+# WITHOUT A RECIPIENT THIS SCRIPT REFUSES TO RUN. It does not fall back to a
+# plaintext upload: that fallback is the vulnerability, and a silent one, since
+# a backup that "worked" looks identical either way. A failing timer is visible
+# in `systemctl status gds-db-offsite.timer`; an unencrypted dump in a bucket is
+# visible to nobody until it matters.
 #
 # Manual one-shot:
 #   <instance-root>/scripts/gds/db-backup-offsite.sh
@@ -72,13 +102,17 @@ ENV_FILE="${GDS_SPACES_ENV:-${CONFIG_DIR_NAME:+/etc/$CONFIG_DIR_NAME/spaces.env}
 # extract only the five expected KEY=VALUE lines. `read -r k v` with IFS='='
 # splits on the FIRST '=' only, so base64 secrets containing '/', '+' or '='
 # survive intact.
-if [ -z "${SPACES_KEY:-}" ] && [ -f "$ENV_FILE" ]; then
+# Read the file when EITHER the credentials or the encryption recipient is still
+# unset. Keying this on SPACES_KEY alone would skip the file on a box where
+# systemd injects the S3 vars but the recipient was added to the file later —
+# and the script would then refuse to run while the key it needs sat right there.
+if { [ -z "${SPACES_KEY:-}" ] || [ -z "${GDS_OFFSITE_AGE_RECIPIENT:-}" ]; } && [ -f "$ENV_FILE" ]; then
   while IFS='=' read -r _k _v; do
     case "$_k" in
-      SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT)
+      SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT|GDS_OFFSITE_AGE_RECIPIENT)
         export "$_k=$_v" ;;
     esac
-  done < <(grep -E '^(SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT)=' "$ENV_FILE" || true)
+  done < <(grep -E '^(SPACES_KEY|SPACES_SECRET|SPACES_BUCKET|SPACES_REGION|SPACES_ENDPOINT|GDS_OFFSITE_AGE_RECIPIENT)=' "$ENV_FILE" || true)
 fi
 
 missing=()
@@ -91,8 +125,30 @@ if [ "${#missing[@]}" -gt 0 ]; then
   exit 2
 fi
 
+# The encryption recipient is as required as the credentials — a dump this box
+# can upload but nobody can decrypt is useless, and a dump it uploads in the
+# clear is the finding this refusal exists to close (task 1003372, audit A1).
+if [ -z "${GDS_OFFSITE_AGE_RECIPIENT:-}" ]; then
+  echo "ERROR: GDS_OFFSITE_AGE_RECIPIENT is not set — refusing to ship an unencrypted database dump offsite." >&2
+  echo "       A dump is every secret this platform holds, in one file, on storage the platform does not own." >&2
+  echo "" >&2
+  echo "       Fix, on a machine that is NOT this server:" >&2
+  echo "         age-keygen -o bongos-backup.key     # keep this file safe and OFFLINE — it is the only way back" >&2
+  echo "       then add the age1... public key it prints to $ENV_FILE:" >&2
+  echo "         GDS_OFFSITE_AGE_RECIPIENT=age1..." >&2
+  echo "" >&2
+  echo "       This is deliberately not optional: falling back to a plaintext upload would look identical in the logs." >&2
+  exit 2
+fi
+
+
 # ---- preconditions ----------------------------------------------------------
 
+if ! command -v age >/dev/null 2>&1; then
+  echo "ERROR: 'age' not on PATH — it is what encrypts the dump before it leaves this box." >&2
+  echo "       Install with: apt install age   (or fetch the static binary from https://github.com/FiloSottile/age/releases)" >&2
+  exit 2
+fi
 if ! command -v python3 >/dev/null 2>&1; then
   echo "ERROR: python3 not on PATH (needed for the boto3 S3 client)." >&2
   exit 2
@@ -113,14 +169,38 @@ if [ -z "$LATEST" ]; then
 fi
 
 BASENAME=$(basename "$LATEST")
-KEY="${PREFIX}${BASENAME}"
 BYTES=$(stat -c '%s' "$LATEST")
 
-echo "[$(date -u +%FT%TZ)] gds-db-offsite: archiving ${LATEST} (${BYTES} bytes) → s3://${SPACES_BUCKET}/${KEY}"
+# ---- encrypt before it leaves the box ---------------------------------------
+#
+# To a temp file under the backup dir (same filesystem, so no cross-device copy
+# of plaintext through /tmp) with a 0600 umask, and removed on every exit path
+# including failure — the cleartext dump already lives beside it, so the
+# ciphertext is not sensitive in itself, but leaving files behind on a failing
+# weekly timer fills a disk nobody is watching.
+umask 077
+ENC="$(mktemp "${BACKUP_DIR}/.${BASENAME}.age.XXXXXX")"
+trap 'rm -f "$ENC"' EXIT
+
+if ! age -r "$GDS_OFFSITE_AGE_RECIPIENT" -o "$ENC" "$LATEST"; then
+  echo "ERROR: age refused to encrypt — is GDS_OFFSITE_AGE_RECIPIENT a valid age1... public key?" >&2
+  exit 2
+fi
+
+# A zero-byte or missing ciphertext would upload happily and restore to nothing.
+# Checked here rather than trusted, because the failure is silent for a month.
+ENC_BYTES=$(stat -c '%s' "$ENC")
+if [ "$ENC_BYTES" -lt 1 ]; then
+  echo "ERROR: encryption produced an empty file — refusing to upload it as a backup." >&2
+  exit 2
+fi
+
+KEY="${PREFIX}${BASENAME}.age"
+echo "[$(date -u +%FT%TZ)] gds-db-offsite: archiving ${LATEST} (${BYTES} bytes → ${ENC_BYTES} encrypted) → s3://${SPACES_BUCKET}/${KEY}"
 
 # ---- upload + prune (single boto3 session) ----------------------------------
 
-GDS_OFFSITE_LOCAL="$LATEST" \
+GDS_OFFSITE_LOCAL="$ENC" \
 GDS_OFFSITE_KEY="$KEY" \
 GDS_OFFSITE_KEEP="$KEEP" \
 GDS_OFFSITE_PREFIX="$PREFIX" \
@@ -151,10 +231,25 @@ s3 = boto3.client(
 s3.upload_file(local, bucket, objkey)
 print(f"[gds-db-offsite] uploaded {objkey}")
 
-# Prune: keep the newest `keep` objects under our prefix, delete the rest.
 resp = s3.list_objects_v2(Bucket=bucket, Prefix=prefix)
+contents = resp.get("Contents", [])
+
+# PURGE THE PLAINTEXT ALREADY UP THERE (task 1003372, audit A1). Every `.sql.gz`
+# under this prefix was uploaded unencrypted by an earlier version of this
+# script, and each one is a live copy of every secret the platform held on the
+# day it was taken — including, before core_249, directly replayable session
+# bearers. Encrypting from now on does nothing about them. They are deleted
+# OUTSIDE the retention count, and unconditionally: retaining four of them
+# "for safety" would retain the finding. The local nightly dumps on the droplet
+# are untouched, so this removes copies, never the last copy.
+legacy = [o for o in contents if o["Key"].endswith(".sql.gz")]
+for obj in legacy:
+    s3.delete_object(Bucket=bucket, Key=obj["Key"])
+    print(f"[gds-db-offsite] PURGED unencrypted legacy dump {obj['Key']}")
+
+# Prune: keep the newest `keep` ENCRYPTED objects under our prefix.
 objects = sorted(
-    [o for o in resp.get("Contents", []) if o["Key"].endswith(".sql.gz")],
+    [o for o in contents if o["Key"].endswith(".sql.gz.age")],
     key=lambda o: o["LastModified"],
 )
 to_delete = objects[:-keep] if len(objects) > keep else []
@@ -163,7 +258,8 @@ for obj in to_delete:
     print(f"[gds-db-offsite] pruned {obj['Key']}")
 
 kept = min(len(objects), keep)
-print(f"[gds-db-offsite] ok · {kept} offsite dump(s) retained · pruned {len(to_delete)}")
+print(f"[gds-db-offsite] ok · {kept} offsite dump(s) retained · pruned {len(to_delete)}"
+      + (f" · purged {len(legacy)} unencrypted legacy dump(s)" if legacy else ""))
 PYEOF
 
 echo "[$(date -u +%FT%TZ)] gds-db-offsite: done"

package/scripts/gds/run-unit-tests.js

@@ -171,6 +171,14 @@ const INTEGRATION = new Set([
   // real engine can show the CASE guard leaving a NULL alone on an actual use,
   // which is exactly where the removed timeout would come back.
   'auth_session_expiry_db',
+  // task 1003372 (audit A1, core_249): that hashing the bearer at rest does not
+  // sign anybody out. The DB-free sibling (session_token_hash) stands in front of
+  // the pool and proves the plaintext never reaches a query — the negative that
+  // matters — but it cannot show that Postgres accepts the migration, nor that
+  // the digest the backfill computes in SQL equals the one the kernel computes in
+  // Node. That mismatch would leave every new session working and every migrated
+  // one dead, which is the failure a source-reading test walks straight past.
+  'session_token_hash_db',
   'scouting_rollup_fanout', 'session_records',
   // task 1003217: the cost-row RAISE against real SQL. Every claim in it IS the
   // SQL — an ON CONFLICT DO UPDATE guarded to move a row only upward, and a

package/src/bongos/db-kernel.js

@@ -23,6 +23,7 @@
 
 'use strict';
 
+const crypto = require('node:crypto');
 const { pool } = require('./pool');
 const seams = require('../module-seams');
 
@@ -277,8 +278,37 @@ async function accessStateByLogin(login) {
 // code agree on one number.
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 
+// sessionTokenHash — the ONE place a bearer becomes the value this table stores
+// (task 1003372, audit A1, migration core_249). SHA-256 hex, matching the
+// migration's `encode(sha256(token::bytea), 'hex')` byte for byte, so a row
+// backfilled in SQL and a row minted here resolve identically.
+//
+// WHY A FAST HASH. A session token is 256 bits of CSPRNG, not a password: there
+// is no dictionary to run, so a KDF would buy nothing and cost real latency on
+// every authenticated request. Same reasoning, written out at length, in
+// modules/platform-identity/platform-identity.js (`sha256hex`).
+//
+// WHY NO timingSafeEqual HERE, THOUGH THE TASK NAMED IT. The pattern the task
+// points at compares a presented secret against one it already fetched by
+// client_id, so the comparison happens in JS and must be constant-time. A session
+// has no second identifier — the bearer IS the lookup key — so the comparison is
+// the indexed `WHERE token_hash = $1` below, and there is no JS compare to make
+// constant-time. Adding a timingSafeEqual after that lookup would compare the
+// hash to itself: vacuously true, and worse than nothing, because it would read
+// as a control that is doing something. The property the task wanted — a guessed
+// token leaks no information about how close it was — holds here because the
+// index is probed with a full digest, never a prefix.
+function sessionTokenHash(token) {
+  return crypto.createHash('sha256').update(String(token), 'utf8').digest('hex');
+}
+
 // createSession — mint a builder_sessions row.
 //
+// THE PLAINTEXT BEARER IS NEVER STORED (task 1003372). `token` is hashed on the
+// way in and the column that held it is gone (core_249). The raw value is
+// returned to the caller — it is their input, handed back so the mint response
+// can carry it to the client — and after that it exists only in the client.
+//
 // A null/undefined expiresAt means NO EXPIRY (expires_at NULL), which
 // lookupSession honours as never-expires. That is the CLI's contract (ADR 0294,
 // restoring 003_pms.sql's original one): a `bongos` sign-in lasts until it is
@@ -290,12 +320,15 @@ const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 async function createSession({ builderId, token, source, userAgent, expiresAt }) {
   const effectiveExpiresAt = expiresAt ?? null;
   const { rows } = await pool.query(
-    `INSERT INTO builder_sessions (builder_id, token, source, user_agent, expires_at)
+    `INSERT INTO builder_sessions (builder_id, token_hash, source, user_agent, expires_at)
      VALUES ($1, $2, $3, $4, $5)
-     RETURNING id, builder_id, token, source, created_at, expires_at`,
-    [builderId, token, source, userAgent ?? null, effectiveExpiresAt]
+     RETURNING id, builder_id, source, created_at, expires_at`,
+    [builderId, sessionTokenHash(token), source, userAgent ?? null, effectiveExpiresAt]
   );
-  return rows[0];
+  // `token` is re-attached from the ARGUMENT, never read back from the row — the
+  // row no longer holds it. Callers that pass a token and read one back are
+  // unchanged; what changed is that the database never saw the plaintext.
+  return { ...rows[0], token };
 }
 
 // lookupSession — resolve a live (unrevoked, unexpired) session token to its
@@ -346,8 +379,8 @@ async function lookupSession(token) {
             b.rank, b.status, b.system_role, b.anthropic_user_id${sessionPermsSelect()}
        FROM builder_sessions s
        JOIN builders b ON b.id = s.builder_id
-      WHERE s.token = $1`,
-    [token]
+      WHERE s.token_hash = $1`,
+    [sessionTokenHash(token)]
   );
   const row = rows[0];
   if (!row) return null;
@@ -376,6 +409,9 @@ async function lookupSession(token) {
 module.exports = {
   withTx,
   sessionPermsSelect,
+  // Exported for db.js's revokeSession (which is handed a bearer, not an id) and
+  // for the tests that assert the plaintext never reaches a query parameter.
+  sessionTokenHash,
   getBuilderById,
   getFoundingBuilder,
   listActiveBuilders,

package/src/bongos/db.js

@@ -44,6 +44,9 @@ const {
   // internal uses (setBuilderRank's RANKS.indexOf, etc.) stay byte-identical.
   RANKS, SESSION_TTL_MS, upsertBuilder, seatFirstAdminIfUnclaimed,
   getBuilderByGithubId, hasInvitedAccessRequest, createSession, lookupSession,
+  // The bearer → stored-value transform (task 1003372, core_249). revokeSession
+  // below is the one helper here still handed a raw bearer rather than an id.
+  sessionTokenHash,
 } = require('./db-kernel');
 
 // gradePassCount removed with builderRollingAvgGrade (its only core user) — that
@@ -728,10 +731,14 @@ async function hasCliSession(builderId) {
 // lookupSession — carved to ./db-kernel (ADR 0102). Re-exported above.
 
 
+// Takes the raw bearer (its callers are sign-out paths holding a cookie or an
+// Authorization header, not a session id) and matches on the stored hash —
+// core_249 dropped the plaintext column, so the bearer itself is no longer
+// something this table can be searched by.
 async function revokeSession(token) {
   await pool.query(
-    `UPDATE builder_sessions SET revoked_at = now() WHERE token = $1 AND revoked_at IS NULL`,
-    [token]
+    `UPDATE builder_sessions SET revoked_at = now() WHERE token_hash = $1 AND revoked_at IS NULL`,
+    [sessionTokenHash(token)]
   );
 }
 

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.888'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.889'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/auth_session_expiry_db.mjs

@@ -67,7 +67,7 @@ await pool.query(`
     display_name text, avatar_url text, total_credits int DEFAULT 0, rank text DEFAULT 'archon',
     status text DEFAULT 'active', system_role text, anthropic_user_id text);
   CREATE TABLE builder_sessions (id bigserial PRIMARY KEY, builder_id bigint REFERENCES builders(id),
-    token text UNIQUE, source text, user_agent text, created_at timestamptz DEFAULT now(),
+    token_hash text UNIQUE, source text, user_agent text, created_at timestamptz DEFAULT now(),
     last_used_at timestamptz DEFAULT now(), expires_at timestamptz, revoked_at timestamptz);
   INSERT INTO builders (github_login) VALUES ('probe');
 `);
@@ -86,6 +86,11 @@ const t = async (name, fn) => {
   catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
 };
 const row = async (sql, p) => (await client.query(sql, p)).rows[0];
+// core_249: the bearer is no longer a column, so a probe that wants "the row for
+// this token" has to ask by the stored digest. Uses the kernel's OWN helper, so a
+// change to the hash cannot leave this file quietly matching nothing — a mismatch
+// would make every assertion below read a missing row and fail loudly.
+const h = (token) => kernel.sessionTokenHash(token);
 // refresh-on-use is fire-and-forget: let the UPDATE land before reading it back.
 const settle = () => new Promise((r) => setTimeout(r, 300));
 
@@ -110,67 +115,67 @@ await t('lookupSession resolves a CLI bearer to its builder', async () => {
 await t('after a real use, a CLI session STILL has no expiry (the CASE guard)', async () => {
   await kernel.lookupSession('cli-tok');
   await settle();
-  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token='cli-tok'`)).expires_at, null);
+  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('cli-tok')}'`)).expires_at, null);
 });
 
 await t('refresh-on-use still bumps last_used_at on that same row', async () => {
-  const before = (await row(`SELECT last_used_at FROM builder_sessions WHERE token='cli-tok'`)).last_used_at;
-  await client.query(`UPDATE builder_sessions SET last_used_at = now() - interval '1 hour' WHERE token='cli-tok'`);
+  const before = (await row(`SELECT last_used_at FROM builder_sessions WHERE token_hash='${h('cli-tok')}'`)).last_used_at;
+  await client.query(`UPDATE builder_sessions SET last_used_at = now() - interval '1 hour' WHERE token_hash='${h('cli-tok')}'`);
   await kernel.lookupSession('cli-tok');
   await settle();
-  const after = (await row(`SELECT last_used_at FROM builder_sessions WHERE token='cli-tok'`)).last_used_at;
+  const after = (await row(`SELECT last_used_at FROM builder_sessions WHERE token_hash='${h('cli-tok')}'`)).last_used_at;
   assert.ok(after > new Date(Date.now() - 60_000), `last_used_at did not move: ${after} (was ${before})`);
 });
 
 await t('a web session still rolls its expiry forward (refresh-on-use intact)', async () => {
   await kernel.lookupSession('web-tok');
   await settle();
-  const got = (await row(`SELECT expires_at FROM builder_sessions WHERE token='web-tok'`)).expires_at;
+  const got = (await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('web-tok')}'`)).expires_at;
   assert.ok(got !== null && got < thirtyDays, `expected a rolled-forward date below 30d, got ${got}`);
 });
 
 await t('an expired session is still REFUSED (expiry honoured where present)', async () => {
-  await client.query(`INSERT INTO builder_sessions (builder_id, token, source, expires_at)
-                      VALUES (1,'dead-tok','web', now() - interval '1 hour')`);
+  await client.query(`INSERT INTO builder_sessions (builder_id, token_hash, source, expires_at)
+                      VALUES (1,'${h('dead-tok')}','web', now() - interval '1 hour')`);
   assert.equal(await kernel.lookupSession('dead-tok'), null);
 });
 
 await t('a revoked CLI session is still REFUSED', async () => {
-  await client.query(`INSERT INTO builder_sessions (builder_id, token, source, revoked_at)
-                      VALUES (1,'revoked-tok','cli', now())`);
+  await client.query(`INSERT INTO builder_sessions (builder_id, token_hash, source, revoked_at)
+                      VALUES (1,'${h('revoked-tok')}','cli', now())`);
   assert.equal(await kernel.lookupSession('revoked-tok'), null);
 });
 
 // The migration, against rows shaped like the ones live instances actually hold.
 const migrationSql = readFileSync(MIGRATION, 'utf8');
-await client.query(`INSERT INTO builder_sessions (builder_id, token, source, expires_at) VALUES
-  (1,'old-cli','cli', now() + interval '24 hours'),
-  (1,'old-web','web', now() + interval '30 days'),
-  (1,'old-revoked','cli', now() + interval '24 hours')`);
-await client.query(`UPDATE builder_sessions SET revoked_at = now() WHERE token='old-revoked'`);
+await client.query(`INSERT INTO builder_sessions (builder_id, token_hash, source, expires_at) VALUES
+  (1,'${h('old-cli')}','cli', now() + interval '24 hours'),
+  (1,'${h('old-web')}','web', now() + interval '30 days'),
+  (1,'${h('old-revoked')}','cli', now() + interval '24 hours')`);
+await client.query(`UPDATE builder_sessions SET revoked_at = now() WHERE token_hash='${h('old-revoked')}'`);
 await client.query(migrationSql);
 
 await t('core_243 clears a pre-existing CLI expiry', async () => {
-  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-cli'`)).expires_at, null);
+  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-cli')}'`)).expires_at, null);
 });
 
 await t('core_243 leaves a WEB row dated — the source filter is its safety property', async () => {
-  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-web'`)).expires_at, null);
+  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-web')}'`)).expires_at, null);
 });
 
 await t('core_243 leaves a revoked row alone (it is the audit trail)', async () => {
-  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-revoked'`)).expires_at, null);
+  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-revoked')}'`)).expires_at, null);
 });
 
 await t('core_243 is idempotent — a re-run changes nothing', async () => {
   await client.query(migrationSql);
-  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-cli'`)).expires_at, null);
-  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token='old-web'`)).expires_at, null);
+  assert.equal((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-cli')}'`)).expires_at, null);
+  assert.notEqual((await row(`SELECT expires_at FROM builder_sessions WHERE token_hash='${h('old-web')}'`)).expires_at, null);
 });
 
 // The whole point of the task, stated as a test.
 await t('a CLI session idle for 21 DAYS still authenticates', async () => {
-  await client.query(`UPDATE builder_sessions SET last_used_at = now() - interval '21 days' WHERE token='cli-tok'`);
+  await client.query(`UPDATE builder_sessions SET last_used_at = now() - interval '21 days' WHERE token_hash='${h('cli-tok')}'`);
   assert.notEqual(await kernel.lookupSession('cli-tok'), null);
 });
 

package/tests/government_live_proof.mjs

@@ -42,6 +42,9 @@ if (!process.env.DATABASE_URL) {
 }
 
 const { Pool } = require('pg');
+// The kernel's own bearer → stored-digest transform (core_249), so this fixture
+// cannot drift from how production mints a session.
+const { sessionTokenHash } = require('../src/bongos/db-kernel.js');
 const pool = new Pool({ connectionString: process.env.DATABASE_URL });
 
 // ── THE READINESS GUARD, AND WHY ITS SHAPE MATTERS (task 1003091) ────────────
@@ -137,9 +140,12 @@ async function seed() {
     [ARCHON, THETES]
   );
   await q(
-    `INSERT INTO builder_sessions (builder_id, token, source)
+    // core_249: the bearer is stored as its SHA-256, so a fixture session has to
+    // be seeded the same way the kernel mints one — otherwise the HTTP calls
+    // below authenticate as nobody.
+    `INSERT INTO builder_sessions (builder_id, token_hash, source)
      VALUES ($1,$2,'web'), ($3,$4,'web')`,
-    [ARCHON, ARCHON_TOKEN, THETES, THETES_TOKEN]
+    [ARCHON, sessionTokenHash(ARCHON_TOKEN), THETES, sessionTokenHash(THETES_TOKEN)]
   );
   const [idea] = await q(
     `INSERT INTO idea_inbox (title, body_md, captured_by)

package/tests/own_session_revoke.mjs

@@ -30,6 +30,7 @@
 // Run:  node tests/own_session_revoke.mjs
 
 import { strict as assert } from 'node:assert';
+import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
 import http from 'node:http';
 import { readFileSync } from 'node:fs';
@@ -37,6 +38,13 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
 const require = createRequire(import.meta.url);
+// core_249: the bearer is stored and matched as its SHA-256. Computed here with
+// node:crypto rather than imported from db-kernel — requiring the kernel at this
+// point would bind the REAL pool before the fake below is installed in the
+// require cache, and every case would then try to reach Postgres. The two cannot
+// drift unnoticed: tests/session_token_hash.mjs pins the kernel's helper against
+// exactly this expression.
+const sessionTokenHash = (t) => crypto.createHash('sha256').update(String(t), 'utf8').digest('hex');
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
 let passed = 0;
@@ -124,7 +132,11 @@ function predicateFor(sql, params) {
   // would tear it in half and leave a dangling `OR` behind.
   take(/\(?expires_at IS NULL OR expires_at > now\(\)\)?/,
     () => (r) => r.expires_at === null || r.expires_at > new Date());
-  take(/\b(?:s\.)?token = \$(\d+)/, (v) => (r) => r.token === v);
+  // core_249: the bearer is matched as its SHA-256, never as itself. The fixture
+  // rows below carry `token` as the plaintext a client would present, so the
+  // predicate hashes the row rather than the parameter — which also means a
+  // regression to `token = $1` stops matching here instead of quietly passing.
+  take(/\b(?:s\.)?token_hash = \$(\d+)/, (v) => (r) => sessionTokenHash(r.token) === v);
   take(/(?<!_)\b(?:s\.)?id = \$(\d+)/, (v) => (r) => String(r.id) === String(v));
   take(/\bbuilder_id = \$(\d+)/, (v) => (r) => String(r.builder_id) === String(v));
   take(/\brevoked_at IS NULL/, () => (r) => r.revoked_at === null);

package/tests/session_token_hash.mjs

@@ -0,0 +1,139 @@
+// tests/session_token_hash.mjs — core_249 / task 1003372 (audit A1). DB-FREE.
+//
+// The property this file exists to hold is NEGATIVE: the plaintext bearer must
+// never reach the database. A negative is exactly what a green test suite is
+// worst at — the code can stop hashing and every functional assertion still
+// passes, because a system that stores and compares plaintext works perfectly.
+// So this file does not check that sessions resolve (the DB sibling does that);
+// it checks what the kernel HANDS THE POOL, by standing in front of it and
+// reading every query and parameter that goes past.
+//
+// The real-DB sibling `session_token_hash_db.mjs` proves the halves this cannot:
+// that Postgres accepts the migration, that the SQL digest equals the Node one,
+// and that a bearer minted before the migration still authenticates after it.
+// It self-skips without a database, and a skipped case is not a passing one —
+// which is the whole reason this file is not optional.
+//
+// Run:  node tests/session_token_hash.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+import crypto from 'node:crypto';
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+
+// Stand in front of the pool BEFORE the kernel binds it, and record everything.
+const seen = [];
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = {
+  id: poolPath, filename: poolPath, loaded: true,
+  exports: {
+    pool: {
+      query: async (text, params) => {
+        seen.push({ text, params: params || [] });
+        return { rows: [], rowCount: 0 };
+      },
+    },
+  },
+};
+const kernel = require('../src/bongos/db-kernel.js');
+
+let passed = 0, failed = 0;
+const t = async (name, fn) => {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+
+const BEARER = 'a-perfectly-ordinary-looking-bearer-token-5f21c9';
+const DIGEST = crypto.createHash('sha256').update(BEARER, 'utf8').digest('hex');
+
+await t('sessionTokenHash is SHA-256 hex, pinned against an independent digest', () => {
+  assert.equal(kernel.sessionTokenHash(BEARER), DIGEST);
+  assert.equal(kernel.sessionTokenHash(BEARER).length, 64);
+  assert.match(kernel.sessionTokenHash(BEARER), /^[0-9a-f]{64}$/);
+});
+
+await t('it is the SAME digest the migration computes, spelled the SQL way', () => {
+  // Not a re-derivation of the value — a check that the migration's expression
+  // is the one this hash corresponds to. If someone changes either side to
+  // sha512, base64, or a salted form, the two stop agreeing and every session
+  // that predates the deploy dies. The DB sibling proves the values match by
+  // running both; this catches the edit that causes it.
+  const sql = readFileSync(join(here, '..', 'migrations', 'core_249_session_token_hash.sql'), 'utf8');
+  assert.match(sql, /encode\(\s*sha256\(\s*token::bytea\s*\)\s*,\s*'hex'\s*\)/,
+    'the backfill no longer computes sha256-hex of the plaintext');
+});
+
+await t('THE NEGATIVE: createSession never hands the pool the plaintext', async () => {
+  seen.length = 0;
+  await kernel.createSession({ builderId: '1', token: BEARER, source: 'cli', userAgent: 'probe', expiresAt: null });
+  assert.equal(seen.length, 1, 'expected exactly one query');
+  const [q] = seen;
+  assert.ok(!q.params.includes(BEARER), 'the plaintext bearer was passed as a query parameter');
+  assert.ok(q.params.includes(DIGEST), 'the digest was not passed');
+  assert.ok(!q.text.includes('token,') && !/\btoken\b\s*=/.test(q.text),
+    'the statement still names the dropped plaintext column');
+  assert.match(q.text, /token_hash/);
+});
+
+await t('THE NEGATIVE: lookupSession never hands the pool the plaintext', async () => {
+  seen.length = 0;
+  await kernel.lookupSession(BEARER);
+  const read = seen[0];
+  assert.ok(read, 'no query was issued');
+  assert.ok(!read.params.includes(BEARER), 'the plaintext bearer was used as the lookup key');
+  assert.deepEqual(read.params, [DIGEST]);
+  assert.match(read.text, /s\.token_hash = \$1/);
+});
+
+await t('THE NEGATIVE: revokeSession never hands the pool the plaintext', async () => {
+  seen.length = 0;
+  const db = require('../src/bongos/db.js');
+  await db.revokeSession(BEARER);
+  const q = seen.find((s) => /revoked_at = now\(\)/.test(s.text));
+  assert.ok(q, 'no revoke statement was issued');
+  assert.ok(!q.params.includes(BEARER), 'revoke still matches on the plaintext bearer');
+  assert.deepEqual(q.params, [DIGEST]);
+  assert.match(q.text, /token_hash = \$1/);
+});
+
+await t('the probe would CATCH a regression — it is not vacuously green', async () => {
+  // A negative assertion is worth nothing unless it can fail. This runs the same
+  // checks against a deliberately-wrong call (the plaintext passed straight
+  // through) and requires them to reject it. Without this, a stub that recorded
+  // nothing, or an `includes` against the wrong array, would pass every case
+  // above while the kernel stored plaintext.
+  seen.length = 0;
+  const fakePool = { query: async (text, params) => { seen.push({ text, params }); return { rows: [] }; } };
+  await fakePool.query('SELECT 1 FROM builder_sessions WHERE token = $1', [BEARER]);
+  const bad = seen[0];
+  assert.ok(bad.params.includes(BEARER), 'the recorder is not capturing parameters at all');
+  assert.ok(!bad.params.includes(DIGEST), 'the recorder would accept a plaintext query as hashed');
+});
+
+await t('the migration drops the plaintext column rather than emptying it', () => {
+  const sql = readFileSync(join(here, '..', 'migrations', 'core_249_session_token_hash.sql'), 'utf8');
+  assert.match(sql, /ALTER TABLE builder_sessions DROP COLUMN token\b/);
+  assert.match(sql, /CREATE UNIQUE INDEX IF NOT EXISTS ux_builder_sessions_token_hash/);
+  assert.match(sql, /DROP INDEX IF EXISTS idx_builder_sessions_token/);
+});
+
+await t('the migration does NOT touch expiry — ADR 0294 and ADR 0206 stand', () => {
+  // The audit also asked for refresh-on-use to stop and an absolute session
+  // lifetime to be added. Both were decided the other way, by the owner, AFTER
+  // the audit was written: ADR 0294 keeps the roll-forward for rows that have an
+  // expiry, and ADR 0206 + ADR 0294 both reject an absolute ceiling by name. A
+  // hashing migration that quietly reintroduced either would be the tail wagging
+  // the dog, so the absence is asserted rather than left to reading.
+  const sql = readFileSync(join(here, '..', 'migrations', 'core_249_session_token_hash.sql'), 'utf8');
+  const statements = sql.split('\n').filter((l) => !l.trim().startsWith('--')).join('\n');
+  assert.ok(!/expires_at/.test(statements),
+    'core_249 writes expires_at — that belongs to ADR 0294, not to a hashing migration');
+});
+
+console.log(`\nsession_token_hash: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/session_token_hash_db.mjs

@@ -0,0 +1,193 @@
+// tests/session_token_hash_db.mjs — core_249 / task 1003372 (audit A1, real DB).
+//
+// The bearer stored in `builder_sessions` was plaintext, NOT NULL UNIQUE and
+// INDEXED: every row was a directly replayable credential. This file proves the
+// two properties that fix has to carry, and they pull against each other:
+//
+//   1. NOTHING REPLAYABLE IS LEFT. The plaintext column is gone, and a dump of
+//      the table yields no value that authenticates.
+//   2. NOBODY IS SIGNED OUT. A session minted BEFORE the migration still
+//      authenticates AFTER it, with the same bearer its holder is still carrying.
+//
+// (2) is the one worth a real database. It is the whole reason the migration
+// backfills instead of letting sessions re-mint, and it can only be proved by
+// running the actual SQL against rows in the actual old shape. A mistake here
+// does not fail loudly in review — it signs out every builder and every dev box
+// on deploy day, including whoever would have to log in to fix it.
+//
+// The sibling `session_token_hash.mjs` is DB-free and pins the hash itself plus
+// the statements' shape. What it cannot see is whether Postgres accepts the
+// migration at all, or whether the digest the migration computes in SQL equals
+// the one the kernel computes in Node — a mismatch that would leave every
+// pre-existing session dead while every new one worked, which is exactly the
+// failure a code-only test reads straight past.
+//
+// Real-DB integration test: self-skips without a reachable Postgres.
+//
+// Run:  DATABASE_URL=... node tests/session_token_hash_db.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MIGRATION = join(here, '..', 'migrations', 'core_249_session_token_hash.sql');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`session_token_hash_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const SCHEMA = `tokhash_probe_${process.pid}`;
+await pool.query(`CREATE SCHEMA ${SCHEMA}`);
+await pool.query(`SET search_path TO ${SCHEMA}`);
+
+// The table in its PRE-migration shape — plaintext `token`, NOT NULL UNIQUE,
+// indexed. Copied from migrations/003_pms.sql so the migration is exercised
+// against what it will actually meet on a live instance.
+await pool.query(`
+  CREATE TABLE builders (id bigserial PRIMARY KEY, github_id text, github_login text,
+    display_name text, avatar_url text, total_credits int DEFAULT 0, rank text DEFAULT 'archon',
+    status text DEFAULT 'active', system_role text, anthropic_user_id text);
+  CREATE TABLE builder_sessions (id bigserial PRIMARY KEY, builder_id bigint REFERENCES builders(id),
+    token text NOT NULL UNIQUE, source text, user_agent text, created_at timestamptz DEFAULT now(),
+    last_used_at timestamptz DEFAULT now(), expires_at timestamptz, revoked_at timestamptz);
+  CREATE INDEX idx_builder_sessions_token ON builder_sessions (token);
+  INSERT INTO builders (github_login) VALUES ('probe');
+`);
+
+const client = await pool.connect();
+await client.query(`SET search_path TO ${SCHEMA}`);
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: client } };
+const kernel = require('../src/bongos/db-kernel.js');
+
+let passed = 0, failed = 0;
+const t = async (name, fn) => {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+const row = async (sql, p) => (await client.query(sql, p)).rows[0];
+
+// Sessions that exist BEFORE the migration, written the old way. These stand in
+// for every builder holding a live bearer on deploy day.
+const LIVE_CLI = 'pre-existing-cli-bearer-2f8a';
+const LIVE_WEB = 'pre-existing-web-bearer-91cd';
+await client.query(
+  `INSERT INTO builder_sessions (builder_id, token, source, expires_at)
+   VALUES (1,$1,'cli',NULL), (1,$2,'web', now() + interval '30 days')`,
+  [LIVE_CLI, LIVE_WEB]
+);
+
+// ── the migration, for real ───────────────────────────────────────────────────
+
+const migrationSql = readFileSync(MIGRATION, 'utf8');
+await client.query(migrationSql);
+
+await t('THE ONE THAT MATTERS: a bearer minted before the migration still authenticates after it', async () => {
+  // If this fails, the deploy signs out every builder holding a session — the
+  // failure the backfill exists to prevent, and the one nobody can undo from
+  // outside because fixing it needs a session.
+  const got = await kernel.lookupSession(LIVE_CLI);
+  assert.ok(got, 'the pre-existing CLI bearer no longer resolves');
+  assert.equal(got.github_login, 'probe');
+});
+
+await t('a pre-existing WEB session survives too, expiry intact', async () => {
+  const got = await kernel.lookupSession(LIVE_WEB);
+  assert.ok(got, 'the pre-existing web bearer no longer resolves');
+  assert.ok(got.expires_at instanceof Date, 'the web row lost its expiry');
+});
+
+await t('the SQL digest equals the Node digest — the two halves agree', async () => {
+  // The backfill computes encode(sha256(token::bytea),'hex') in Postgres; the
+  // kernel computes sha256 hex in Node. If these ever diverge, new sessions work
+  // and every migrated one is dead — a split nothing else here would localise.
+  const got = await row(`SELECT token_hash FROM builder_sessions WHERE source='cli'`);
+  assert.equal(got.token_hash, kernel.sessionTokenHash(LIVE_CLI));
+});
+
+// ── nothing replayable is left ────────────────────────────────────────────────
+
+await t('the plaintext column is GONE, not merely emptied', async () => {
+  const got = await row(
+    `SELECT count(*)::int AS n FROM information_schema.columns
+      WHERE table_schema=$1 AND table_name='builder_sessions' AND column_name='token'`,
+    [SCHEMA]
+  );
+  assert.equal(got.n, 0, 'builder_sessions.token still exists');
+});
+
+await t('no stored value authenticates — a dump of the table is inert', async () => {
+  // The actual security claim, asserted the way an attacker would test it: take
+  // everything the table holds and try to log in with it. Reading token_hash and
+  // presenting it must NOT work — if lookupSession hashed nothing, or compared
+  // the presented value to itself, this is where that shows.
+  const { rows } = await client.query(`SELECT token_hash FROM builder_sessions`);
+  assert.ok(rows.length >= 2, 'fixture rows missing — the assertion would be vacuous');
+  for (const r of rows) {
+    assert.equal(await kernel.lookupSession(r.token_hash), null,
+      'a value read straight out of the table authenticated');
+  }
+});
+
+await t('the uniqueness guarantee moved with the column', async () => {
+  await assert.rejects(
+    () => client.query(
+      `INSERT INTO builder_sessions (builder_id, token_hash, source) VALUES (1,$1,'cli')`,
+      [kernel.sessionTokenHash(LIVE_CLI)]
+    ),
+    /duplicate key|unique/i,
+    'two sessions may not share a bearer'
+  );
+});
+
+// ── round-trip through the live code path ─────────────────────────────────────
+
+await t('a session minted AFTER the migration resolves, and stores only its digest', async () => {
+  const fresh = 'freshly-minted-bearer-77b0';
+  await kernel.createSession({ builderId: '1', token: fresh, source: 'cli', userAgent: 'probe', expiresAt: null });
+  const got = await kernel.lookupSession(fresh);
+  assert.ok(got && got.github_login === 'probe', 'a new session did not resolve');
+  const stored = await row(`SELECT token_hash FROM builder_sessions WHERE token_hash = $1`,
+    [kernel.sessionTokenHash(fresh)]);
+  assert.ok(stored, 'the new row is not keyed on the digest');
+});
+
+await t('createSession hands the caller back the bearer it was given', async () => {
+  // The mint response has to carry the plaintext to the client — it is the only
+  // copy that will ever exist. It now comes from the ARGUMENT, since the row
+  // cannot return it.
+  const tok = 'returned-to-caller-a301';
+  const s = await kernel.createSession({ builderId: '1', token: tok, source: 'cli', userAgent: 'probe', expiresAt: null });
+  assert.equal(s.token, tok);
+});
+
+await t('revokeSession still kills a session it is handed by bearer', async () => {
+  const db = require('../src/bongos/db.js');
+  const tok = 'to-be-revoked-5e12';
+  await kernel.createSession({ builderId: '1', token: tok, source: 'cli', userAgent: 'probe', expiresAt: null });
+  assert.ok(await kernel.lookupSession(tok), 'precondition: the session should resolve first');
+  await db.revokeSession(tok);
+  assert.equal(await kernel.lookupSession(tok), null, 'revoke by bearer no longer reaches the row');
+});
+
+await t('the migration is idempotent — a second run is a no-op, not an error', async () => {
+  await client.query(migrationSql);
+  assert.ok(await kernel.lookupSession(LIVE_CLI), 'a re-run broke a live session');
+});
+
+client.release();
+await pool.query(`DROP SCHEMA ${SCHEMA} CASCADE`);
+await pool.end();
+console.log(`\nsession_token_hash_db: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);