Skip to content

0030: A separate dev database, no Postgres port on the LAN, and how local Claude Code reaches real data ​

Note 2026-11-06: the git host and CI moved to GitHub (FEAW-Serv/getmy-books), ADR 0046. References below to the previous host are history; ADR 0046 says what replaces them.

Status ​

Accepted by the Product Owner on 2026-11-06. DH-9 was decided as recommended the same day: keep the production Xero app, rotate its secret, and add a dev app on the Demo Company.

Proposed, with docs/plans/deploy-hardening.md (slice 3). It depends on ADR 0029, because migrations must stop using the LAN port first. It builds on #63 (separating prd secrets from dev): it answers #63's first question (how dev stops sharing the production database), and it changes #63 step 3 (see decision 4). It amends ADR 0014's statement that the migrate-nas runner reaches the NAS database.

Context ​

Issue #73. There is one Postgres, on the NAS, used by three things:

  • The production app, over the compose network.
  • The owner's local Claude Code. .mcp.json runs it with Doppler dev, and it reaches the database over the LAN at 192.168.0.80:5433.
  • migrate-nas, also over the LAN.

The postgres service publishes 5433 on every interface, with password login.

Consequences today:

  • Local testing changes production data and the real FEAW Xero.
  • Every laptop that holds dev has the owner password.
  • Nothing stops the test suite pointing its destructive fixtures at the NAS.
  • The local route and the NAS app refresh the same Xero token row, which can race into invalid_grant.

The local route is also the only route today with:

  • Xero writes. (Changed 2026-10-01: the web route now has them too, each approved in the approval card, AUDIT C5.)
  • Amex statement files, which are read from the laptop's disk.
  • The connect scripts (xero-connect, starling-connect, statement-account-add), which write to whatever database APP_DATABASE_URL names.

Decision ​

  1. Doppler dev and dev_personal point at a local throwaway Postgres (localhost:55432, getmy_books_dev). They get their own XERO_TOKEN_ENCRYPTION_KEY and a separate Xero app, GetMy Books (dev), that is connected only to Xero's UK Demo Company. They lose POSTGRES_PASSWORD and GETMY_BOOKS_TUNNEL_TOKEN.
    • The dev entity is named "Demo", never "FEAW", because migration 0005 grants FEAW by name.
    • The local stdio server keeps its name until decision 3's spike settles naming. Renaming it breaks CLAUDE.md line 40, README lines 79-80 and tool allowlists. More importantly, once dev is the Demo database, a local server's conversation-start heads-up (SPEC-004) would show Demo's deadlines, not FEAW's. The owner's default Claude Code session must still show FEAW's real heads-up (FEAW's Jun-Aug VAT return is due 7 October) before the split.
  2. Postgres publishes no port.
    • The compose file drops ports:.
    • The root compose check refuses ports: on every service, so a closed port is enforced, not just configured.
    • Acceptance: nc -z 192.168.0.80 5433 fails from the LAN.
  3. The owner's real FEAW work goes through the deployed endpoint (https://mcp.getmy.group/mcp, added to Claude Code as an HTTP server and signed in through Cloudflare Access), subject to a spike first. The app reads only cf-access-jwt-assertion, so this works only if Claude Code completes the Access sign-in. Before this option is confirmed, and before the write gate or the CSV tool is built, a spike checks that sign-in for each owner, how ADR 0020's short sessions behave in Claude Code, and that the FEAW deadline heads-up appears through this route. If it fails, option (b) is reconsidered. The port closes only once that route covers today's local work:
    • Xero writes: on the web route for named principals only (XERO_WRITE_PRINCIPALS, in the root-owned config.env on the NAS, not in prd or the deploy env, per ADR 0028). Preview then confirm by ID is unchanged, and no tool files or submits anything (rule 5). This is a product change, made through a spec and the README first.
    • Amex statement files: a statement tool that takes the CSV content from the client and parses it in pure code, with the entity from the session. It must fit within the approved 1 MiB HTTP request limit (C4) for a full Amex statement, taking the statement in pages if not.
    • Reconnecting Xero or Starling for production: a break-glass runbook that runs the compiled connect script in the current image, on the compose network, from an administrator's DSM session. The OAuth callback is forwarded over SSH to 127.0.0.1 only. The connect scripts are compiled with their own build config into dist-tools/; tsconfig.build.json keeps rootDir: "src", so dist/main.js and the image's CMD and HEALTHCHECK do not move.
  4. Separate Xero apps. The dev app is new. The production app stays, and gets a new client secret because the old one sat on laptops. Keeping it avoids reconnecting FEAW. This replaces #63 step 3's "new production app".
  5. Production passwords are rotated after the split, because they sat in dev:
    • The owner password is changed by hand with psql's \password over the container's local socket, so it never appears in shell history, the process list or the Postgres log, then updated in Doppler.
    • The app password is changed in Doppler. The deploy's migrate step then sets it as a SCRAM verifier (ADR 0029). If that deploy fails /health, the rollback reuses the new env (ADR 0028), so production stays up.
  6. Guards stay in place. Every script and test that takes a database URL refuses any host other than localhost, 127.0.0.1, ::1 or postgres. That is the pattern in perf/load/server.ts.
  7. Never copy xero_connection, bank_account.credentials_encrypted, or a production dump into a dev database. Never connect a dev database to the real FEAW Xero. The ledger_write duplicate guard must stay single, or a Starling line could be entered twice.

Options considered for local Claude Code ​

OptionVerdict
(a) The deployed endpoint for real workChosen, subject to the spike. No database credentials on laptops; one token refresher; one duplicate guard; identity per person. It needs the Access sign-in from Claude Code to work, then the write gate and the CSV tool
(b) An SSH tunnel to a loopback-bound Postgres, with a prd_local configFallback, if the Product Owner refuses web-route writes. Everything local keeps working, but production app credentials stay on laptops. It needs a forwarding-only DSM user, which DSM resets to /sbin/nologin (#69)
(c) A local dev database on the Demo CompanyChosen for development and all agents. It cannot replace real work on its own

What changes, and where ​

WhereChange
Repo.mcp.json; infra/nas/docker-compose.yml (no ports, header comment); infra/nas/deploy/getmy-books-compose-check (refuses ports); the connect scripts compiled into dist-tools/; host guards; README lines 79-84 and CLAUDE.md if the server name changes; docs/dev/local-postgres-tests.md; ADR 0014
Dopplerdev and dev_personal repointed, with a new key, a new Xero app, and production secrets removed; prd POSTGRES_PASSWORD, APP_DB_PASSWORD and XERO_CLIENT_SECRET rotated
XeroNew dev app; new production client secret
NASCompose file and compose check reinstalled; the owner password changed by hand with \password; XERO_WRITE_PRINCIPALS in the root config.env if the write gate is approved (a window)
CloudflareNothing expected. The spike confirms that Claude Code completes the Access sign-in to the endpoint

Consequences ​

  • Development and agents can no longer reach production data, and a stray pnpm test cannot touch the NAS.
  • The LAN no longer offers a Postgres login.
  • The owner's real work moves to the same endpoint as the claude.ai connector: one database, one Xero refresher, one duplicate guard.
  • Until the write gate and the CSV tool ship, the port stays open. After they ship, anything they do not cover (for example a new kind of statement file) needs its own route before it can be used on real data.
  • Production reconnects become a rare runbook step. Because it is rarely used, it is easy to get wrong, so it is written down and rehearsed on the dev database.
  • XERO_TOKEN_ENCRYPTION_KEY for production was also on laptops, and is in every release env on the NAS next to the dumps. Rotating it needs the re-encrypt tool in #63, and stays open until then. (Changed 2026-11-03, #63: the tool now exists. scripts/reencrypt-credentials.ts moves every stored credential from the old key to the new one in one transaction, guarded on token_version, and scripts/check-encryption-key.ts gives the counts-only check; the steps are in the developer guide, 'Rotate the encryption key'. The production rotation is not done: the Product Owner can now schedule it for a maintenance window.)
  • Until the owner's route shows FEAW's deadlines at the start of a conversation, the split does not happen: losing that heads-up would be a product regression.