postern: Instructions file for Claude Code

Postern — working notes for an agent in this repo

Neutral gateway for Postern (the Personal Context Gateway): connect the sectors of your life once, reach them from any agent through one surface. Read your life and act on it where the source allows; no cross-domain correlation. A faithful cache, not a derived store — the agent reasons; we authenticate, normalize, store, serve, and dispatch. Three properties decide ties: one place (one surface, one grant), lightning fast (reads from local cache in ms; actions add zero gateway overhead around the one unavoidable dispatch), harness-agnostic (swap the harness, keep the context, capabilities, permission and audit).

Build for the world, not one box. Every decision is for all the people who will run this. A real deployment with real accounts exists to verify a design against real data, never to decide one. When "right for this box" and "right for everyone" diverge, the holistic answer wins.

This file is for an agent working on the code. If you are setting a gateway up for someone, read setup-with-your-agent.md. If you are sending a patch, read CONTRIBUTING.md.

Gotchas

The things that are expensive to learn the hard way. Most were.

• Tests run ONLY against a *_test database. The *.db.test.ts suite issues real INSERT/DELETE. A run against a live application DB wiped ~700 finance rows on 2026-06-17. A fail-closed guard in vitest.globalSetup.ts aborts unless DATABASE_URL matches /_test$/; PCI_TEST_DB=1 is a full bypass of that guard and must never be set against a real database. Use npm run test:db — it brings its own throwaway Postgres and cannot touch a running gateway.
• npm test needs apps/web deps installed — root vitest collects the Console's .test.tsx files but a root-only install does not install them. Without npm ci --prefix apps/web (i.e. npm run setup) you get a wall of red suites and "Cannot find package 'react'". Never "fix" that by excluding apps/web from vitest.config.ts: it drops real tests and makes a loud failure silent.
• The vault master key lives in the container volume, NOT in a ./.pci/master.key on the host. Backing up a host copy yields a tarball that fails at restore with a silent SecretAuthError. Extract the key from the running container. Never docker compose down -v — removing the volume orphans every stored credential.
• Relative imports need .js extensions (ESM + NodeNext). npm run typecheck enforces it.
• amount is signed, negative = money out — so spending = amount < 0 is the provider-agnostic predicate. Plaid is positive-out and gets negated on write; SimpleFIN passes through. Account balances follow the same rule (a liability owed is negative everywhere). available_balance is left as each provider reports it.
• union:% is a reserved source_object_id namespace for dedup synthetics. applyRecords fail-closed rejects any provider record that plants or tombstones one.
• The loopback Host allowlist is the only authz on the admin/OAuth/Plaid routes. It is a same-origin/DNS-rebinding guard, not per-request auth. The erase confirm token is a fat-finger guard, not auth either. The bearer-gated read mirror is intentionally separate. SECURITY.md states the whole boundary.
• This project is Apache-2.0, so a GPL/AGPL/SSPL dependency poisons the distribution. Adding one is a licence violation, not a preference — check before you add a dep, and never resolve an audit finding by pulling in copyleft. One MPL-2.0 dependency (ical.js) is fine and already recorded in THIRD-PARTY-NOTICES.md.
• Cloud MCP clients egress on port 443 only. A tunnel on any other port silently TCP-resets — the client will simply never connect and tell you nothing.
• A test that cannot fail is this repo's signature defect. Correct code behind a vacuous guard accounts for most of the blocking review findings in its history. The only reliable check is to run the mutation: break what the test guards and confirm it goes red.