1password
Monarch
Tax_Amendment
Test
melon-monarch-cfo
melon-monarch-cfo-30
melon-monarch-cfo-auth
melon-monarch-cfo-m4
melon-monarch-cfo-m8
melon-monarch-cfo-policy
melon-monarch-ingest
Projects
/Users/openclaw-service/Documents/Claude/Projects/melon-monarch-cfo

OPEN | [M7.5 PR-4] Real auth: Google OIDC middleware + routes + validators per ADR-0012

Implementation of the auth design specified in [ADR-0012](docs/decisions/0012-auth-strategy-google-oidc.md). This is the M7.5 PR-4 referenced in #35 and gates the post-PR-4 go/no-go real-data PR (which is a separate issue).

**Pre-reqs:** [#117](https://github.com/melon-lab-com/melon-monarch-cfo/pull/117) (ADR-0012) merged with SHA-anchored APPROVED sentinel.
**Refs:** #110 (the revisit decision), #35 (M7.5 epic), #107 / #114 / #116 (PRs 1–3, all merged).

## Scope

PR-4 ships the **code** for Google OIDC auth — middleware, routes, validators, tests, runbook — but does NOT flip the deployed env vars. After PR-4 lands, deployed behaviour is unchanged from PR-3 (still 503-gated). The actual `AUTH_ENABLED=true` flip lives in the post-PR-4 go/no-go PR per ADR-0012 §Cutover and AGENTS.md §"Standing scope fences" item 1.

## Acceptance checklist

### Code

- [ ] `src/monarch_cfo/api/auth.py` — `OAuthAuthMiddleware` (session check, public-allowlist routing, 401 JSON / 302 HTMX content negotiation), `OAuth` client factory against Google's discovery doc via `authlib`, ID-token verification helper, `sub`-allowlist check, slowapi limiter setup.
- [ ] `src/monarch_cfo/api/routers/auth.py` — `GET /auth/login`, `GET /auth/callback`, `POST /auth/logout`, `GET /auth/logged-out`. All `include_in_schema=False`. `?next=` validated against same-origin (rejects `//evil.com`, `https://evil.com`, `/\evil.com`).
- [ ] `src/monarch_cfo/api/settings.py` — five new fields per ADR-0012 §Operational posture (`google_oauth_client_id: str`, `google_oauth_client_secret: SecretStr`, `auth_cookie_secret: SecretStr`, `auth_allowed_google_subs: list[str]`, `auth_oauth_redirect_uri: HttpUrl`). Each with `validation_alias=AliasChoices(unprefixed, prefixed)` matching the existing pattern at `settings.py:42-49`. Extend `_check_auth_state` → `_check_auth_secrets` so `auth_enabled=True` requires non-empty `google_oauth_client_id`, non-empty `google_oauth_client_secret`, `auth_cookie_secret` length ≥ 32 bytes, non-empty `auth_allowed_google_subs` with each entry matching `^\d{10,}$`, and `https://...` redirect URI when not localhost.
- [ ] `src/monarch_cfo/api/app.py` — register `SessionMiddleware` then `OAuthAuthMiddleware` **after** the existing `BootstrapGate503Middleware` registration at `app.py:120` (last-added = innermost in Starlette's reverse-iteration build; see ADR-0012 §Interaction).
- [ ] `src/monarch_cfo/web/templates/auth/logged_out.html`, `forbidden.html` (the 403 for an unallowlisted Google account; names the rejected email).
- [ ] `pyproject.toml` adds `authlib`, `slowapi`. `uv.lock` updated in the same commit. Image-size delta < 5 MB (post a number in the PR body).

### Tests (existing suite must pass with zero changes)

- [ ] Integration test: stub OIDC provider returning canned ID tokens; exercise `/auth/login → /auth/callback → /transactions` end-to-end.
- [ ] `state` mismatch returns 4xx (CSRF defence on the callback).
- [ ] Unallowlisted `sub` returns 403 with the named-email page.
- [ ] 503 gate wins over auth middleware (registration-order verification — explicit assertion that `BootstrapGate503Middleware` short-circuits before `OAuthAuthMiddleware` reads `request.session`).
- [ ] Boot-time validator failure for each missing/malformed-secret cell (5 cases: missing client ID, missing client secret, short cookie secret, empty allowlist, http:// redirect URI on non-localhost).
- [ ] `?next=` open-redirect: at minimum `?next=//evil.com`, `?next=https://evil.com`, `?next=/\evil.com` all rejected.
- [ ] Logout double-submit-CSRF: missing token → 4xx; mismatched cookie/form → 4xx.
- [ ] **Existing test suite passes with zero fixture changes** (`AUTH_ENABLED=false` default honoured).

### Deploy + secrets surface (PR adds, does NOT activate)

- [ ] `config/deploy.yml` `env: clear` adds `GOOGLE_OAUTH_CLIENT_ID`, `AUTH_OAUTH_REDIRECT_URI`, `AUTH_ALLOWED_GOOGLE_SUBS`. **`AUTH_ENABLED` stays `"false"` and `AUTH_BOOTSTRAP_503` stays `"true"`** (the flip is the go/no-go PR's job).
- [ ] `config/deploy.yml` `env: secret` adds `GOOGLE_OAUTH_CLIENT_SECRET` and `AUTH_COOKIE_SECRET`.
- [ ] `.kamal/secrets.example` updated with the two new secret entries; `.kamal/secrets` itself stays gitignored (`gitleaks` confirms).
- [ ] Three GHA repo secrets (`GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `AUTH_COOKIE_SECRET`) verified set in the repo before the deploy tag fires (operator confirms in the PR body).
- [ ] PR body confirms the post-deploy 7-day Logfire span-count probe commitment (per ADR-0012 §Logfire spend impact) — re-verify the Logfire free-tier ceiling on the dashboard before merging.

### Docs

- [ ] New `docs/auth.md` runbook (sister to `docs/deploy.md`): one-time Google Cloud Console OAuth client setup (project, consent-screen, redirect URI), allowlist mutation as a code-change PR, secret rotation flow for both `AUTH_COOKIE_SECRET` and `GOOGLE_OAUTH_CLIENT_SECRET`, three kill-switch paths, and the IdP-side WebAuthn / Advanced Protection prerequisite for the go/no-go PR.
- [ ] `docs/deploy.md` updated:
  - "What's NOT on auto-pilot" mentions Google OAuth client-secret rotation.
  - "Pre-swap verification" checklist drops "Tailscale edge confirmed blocking non-enrolled clients" and adds the smoke checks from ADR-0012 §Validation steps.
  - Day-2 workflow table gains "Disable auth in emergency" → the `kamal env push` + `kamal app boot` recipe.

### Cross-cutting

- [ ] `Dockerfile` line 110 (`--forwarded-allow-ips=...`) is documented in the diff or PR body as load-bearing for slowapi's per-IP rate limits in addition to its original PR-1 purpose. Do NOT change the line; flag it for the deploy reviewer.
- [ ] `csrftoken` cookie set with `HttpOnly=True` (the form template renders the value via Jinja, so JavaScript access isn't needed).
- [ ] `cloud-ops-specialist` review passes (PR touches `config/deploy.yml`, `.kamal/secrets.example`, `docs/deploy.md`, ADR-0012; AGENTS.md mandates the specialist on each).
- [ ] `code-reviewer` SHA-anchored APPROVED sentinel posted; `code-reviewer-gate` CI green.
- [ ] M7.6 follow-up issue filed: "WebAuthn second-factor at the application layer" with the outline from ADR-0012 §WebAuthn (table, routes, `AUTH_REQUIRE_WEBAUTHN` flag, M7.6 milestone).

## Out of scope (handled in the post-PR-4 go/no-go PR)

- Flipping `AUTH_ENABLED=true` and `AUTH_BOOTSTRAP_503=false` in `config/deploy.yml`.
- Real-data swap on the Hetzner volume (per AGENTS.md synthetic-data fence).
- Operator-confirmed prerequisites checklist (allowlisted Google accounts have phishing-resistant 2FA at the IdP layer; Google OAuth client created with the production redirect URI; secrets present in GHA).
- "Intentionally break a secret, push a deploy tag, confirm the bad container does not become the proxy target" smoke (ADR-0012 §Operational posture validator-and-Kamal contract).

## Out of scope (deferred to M7.6)

- WebAuthn second factor at the application layer. PR-4's go/no-go prerequisite is **operator-confirmed phishing-resistant 2FA at the Google account itself** (passkey, security key, or Advanced Protection enrolment); app-layer WebAuthn lands as the M7.6 follow-up.

   5ef5e6e..514fcc6  main       -> origin/main
514fcc6 hotfix(gate): force GET on issues/comments — `gh api --field` was POSTing (#120)
5ef5e6e M7.5 PR-3: Logfire observability + Hetzner spend tripwire + docs sweep (#116)
4118497 M7.5: Dockerfile — add service=monarch-cfo label (Kamal 2 requirement)
f30debe M7.5: deploy workflow — drop -H from ssh-keyscan (Net::SSH parse)
f1f3196 M7.5: deploy workflow — use GITHUB_TOKEN for GHCR push, PAT only for pull
0001-stack-choice.md
0002-csv-validation-and-hashing.md
0003-sqlalchemy-sync.md
0004-cli-typer.md
0005-branch-protection-deferred.md
0006-cloud-deployment-target.md
README.md
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

1	# AGENTS.md
2	
3	Conventions for agent-driven work on `melon-monarch-cfo`. A fresh
4	agent should be able to open this file and work on the repo without
5	reading anything else first.
6	
7	`melon-monarch-cfo` is the private CFO application. The sibling
8	public library [`melon-monarch-ingest`](https://github.com/melon-lab-com/melon-monarch-ingest)
9	(MIT) owns CSV parsers, dedup hashing, ORM models, Alembic
10	migrations for Monarch-native tables, and the `monarch-ingest` CLI.
11	Both repos share the same agent-team conventions; ingest has its
12	own `AGENTS.md` that mirrors most of this file.
13	
14	## TL;DR for an incoming agent
15	
16	1. Read the PR or issue you're about to work on. Don't start coding
17	   before you know what "done" means.
18	2. Branch off `main`. **Every PR off `main`, no stacking** — see
19	   "Reland rule" below.
20	3. Before every commit: `uv run ruff check .`, `uv run ruff format
21	   --check .`, `uv run mypy`, `uv run pytest -q`. Pre-commit
22	   enforces; you still verify before pushing.
23	4. Spawn the `code-reviewer` agent on your own PR and address its
24	   feedback before merging. UI or deploy PRs get additional
25	   specialist review (see "Agent team" below).
26	5. Small atomic commits > big mega-commits.
27	6. On merge: `--squash --delete-branch`. No merge commits.
28	
29	## Repository layout
30	
31	```
32	src/monarch_cfo/         # the app
33	  ├─ api/                # FastAPI routers, settings, auth gate
34	  ├─ reports/            # report assemblers (annual, rental,
35	  │                      #   subscriptions, owners, net worth)
36	  ├─ web/                # HTMX frontend: templates, static, routes
37	  └─ ai/                 # (M8) chat provider abstraction + tools
38	tests/                   # pytest + fixtures; browser tests opt-in
39	docs/
40	  ├─ plan.md             # architecture plan — skim first
41	  ├─ decisions/          # ADRs
42	  ├─ deploy.md           # cloud deploy runbook (M7.5 owns this)
43	  ├─ reports.md          # report rules
44	  └─ web.md              # UI conventions + video-proof gate
45	.github/                 # CI + PR template + issue templates
46	.claude/agents/          # project-level custom subagents
47	scripts/                 # one-off helpers (recording, provisioning)
48	```
49	
50	The ingest library (`src/monarch_ingest/`) is NOT in this repo —
51	it lives in `melon-monarch-ingest` and is pinned by commit SHA in
52	`pyproject.toml`.
53	
54	## Workflow preferences
55	
56	### Small, atomic commits
57	
58	One coherent change per commit. One coherent concern per PR.
59	
60	### Reland rule — branch off `main`, no stacking
61	
62	Every PR starts from `main`. Do not chain `pr-2` off `pr-1`. If
63	`pr-1` is squash-merged with `--delete-branch`, `pr-2`'s base
64	vanishes and GitHub auto-closes the stack. This has bitten the
65	project multiple times and is non-negotiable.
66	
67	### Pre-commit is a hard gate
68	
69	Install once: `uv run pre-commit install`. Thereafter every commit
70	goes through the full stack. Notable hooks:
71	
72	- `ruff-format --check` — **fails on drift, does NOT auto-fix.**
73	  If it fails, run `uv run ruff format .` manually, re-stage,
74	  re-commit. This is deliberate: auto-fix silently hides the exact
75	  drift CI is there to catch.
76	- `ruff-check --fix` — may auto-fix lints; re-stage if it does.
77	- `mypy --strict`, `gitleaks`, `block-real-monarch-csv`.
78	
79	Hook bypasses (`--no-verify`) are reserved for explicit, narrow
80	reasons. Default answer is "run the hooks."
81	
82	### Milestone close-out ritual
83	
84	At every milestone close:
85	
86	1. **Drift check.** Verify every exit-criteria checkbox on the
87	   milestone issue matches reality. File drift fixes as follow-up
88	   PRs before closing the milestone.
89	2. **Simplify pass.** Run the `simplify` Claude Code skill against
90	   everything the milestone touched. Output becomes one cleanup PR.
91	3. **Specialist reviews, if applicable.**
92	   - **UI-touching milestones** → video-proof gate per
93	     [`docs/web.md`](docs/web.md); `needs:video-proof` label on
94	     every UI PR.
95	   - **Deploy-touching milestones** → `cloud-ops-specialist`
96	     review (see "Agent team" below) in addition to the standard
97	     `code-reviewer` gate.
98	4. **Retro issue (required gate).** File a `M{N} Retro` issue
99	   linked from the milestone epic before the milestone can close.
100	   The `quality-steward` subagent drafts it (see
101	   [`.claude/agents/quality-steward.md`](.claude/agents/quality-steward.md));
102	   the human approves. The retro's "Standing rules changed" section
103	   is canonical — any rule changes must be committed to `AGENTS.md`
104	   (and affected persona files under `.claude/agents/`) in the same
105	   PR that closes the retro. Code-reviewer verifies the update
106	   verbatim before approving. **No retro issue = milestone stays
107	   open.** A retro issue may be minimal — `"No regressions; no
108	   standing-rule changes; no action items"` is acceptable for an
109	   uneventful milestone. The gate requires the issue to exist and
110	   be approved, not a minimum word count. See ADR-0011 for the
111	   full rationale.
112	5. **Close the milestone issue** with a summary comment listing
113	   every merged PR, the exit-criteria table, and what's deferred.
114	
115	### Incident retro — hotfix / revert PRs
116	
117	Any post-merge hotfix or revert PR (including any PR that changes
118	`main` to restore CI or fix a regression introduced by a prior
119	merge) must link an `Incident: <description>` issue before merge.
120	The incident issue uses the same 4-section format as a milestone
121	retro (🔴 what broke / ✅ what held / 📋 standing rules changed /
122	🎯 action items) and is treated as a mini-retro. This is the
123	unscheduled trigger that complements the milestone-boundary ritual.
124	
125	### Stacked retro merges — CI matrix hard gate
126	
127	When a retro or audit involves merging multiple PRs in sequence
128	(e.g., the M8.4–M8.7 retro audit stack that produced #97–#99,
129	#96, #102, #103), GitHub Actions may suppress full-matrix runs
130	on the retro branches after branch retargeting — so local pass
131	on one matrix row does **not** imply all rows pass. Before
132	merging each PR in the stack, confirm every adapter row by
133	inspecting job-level conclusions:
134	
135	```bash
136	# Step 1: get the most recent completed run ID for this branch
137	RUN_ID=$(gh run list --repo melon-lab-com/melon-monarch-cfo \
138	  --branch <retro-branch> --workflow ci.yml \
139	  --json databaseId,status,conclusion \
140	  --jq '[.[] | select(.status=="completed")][0].databaseId')
141	
142	# Step 2: inspect job-level conclusions for all adapter rows
143	gh run view "$RUN_ID" --repo melon-lab-com/melon-monarch-cfo \
144	  --json jobs \
145	  --jq '.jobs[] | select(.name | test("chat-")) | [.name, .conclusion]'
146	```
147	
148	Every adapter row (`chat-gemini`, `chat-anthropic`, `chat-openai`)
149	must show `"success"` before merging. This is a hard gate. Origin:
150	M8 post-mortem (see close-out comment on #16 and ADR-0011).
151	
152	### Commit trailers
153	
154	Every agent-authored commit ends with:
155	
156	```
157	Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
158	```
159	
160	## Merge policy
161	
162	`main` is protected. Enforced by the GitHub branch-protection rule
163	applied via `scripts/apply_branch_protection.sh` (idempotent — reads
164	`scripts/branch_protection_config.json`).
165	
166	This mirrors the same policy on the public sibling
167	[`melon-monarch-ingest`](https://github.com/melon-lab-com/melon-monarch-ingest)
168	— same workflow, same sentinel format, same SHA-anchoring. Cross-repo
169	reviewers shouldn't have to context-switch.
170	
171	### What "merged into main" actually requires
172	
173	Every PR, including those authored by agents, must clear:
174	
175	1. **All CI status checks green.**
176	   - `lint + types + tests` (one per chat-adapter matrix row)
177	   - `pre-commit hooks`
178	   - `code-reviewer-gate` (described below)
179	   - `video-proof` (when the `needs:video-proof` label is applied)
180	
181	2. **A SHA-anchored `code-reviewer` verdict of APPROVED posted as a
182	   PR comment.** See the sentinel format below. The workflow at
183	   [`.github/workflows/code-reviewer-gate.yml`](.github/workflows/code-reviewer-gate.yml)
184	   parses comments via [`scripts/check_reviewer_verdict.py`](scripts/check_reviewer_verdict.py)
185	   and posts the `code-reviewer-gate` commit status accordingly.
186	
187	3. **Linear history.** `--squash --delete-branch` on merge. No merge
188	   commits; rebase-merges are fine if someone needs them, but the
189	   default is squash. Force-push to `main` is prohibited.
190	
191	4. **Admin enforcement is ON.** `enforce_admins: true` — even repo
192	   admins cannot bypass the rules. To genuinely bypass, the rule is
193	   temporarily relaxed via a visible PR that edits
194	   `scripts/branch_protection_config.json`, not by a silent
195	   `gh api` call.
196	
197	5. **No additional human approving review required.**
198	   `required_approving_review_count: 0` — this is a single-contributor
199	   repo where the code-reviewer agent runs as the repo owner. The
200	   SHA-anchored verdict comment IS the review. Multi-contributor
201	   adoption would flip this to `1` and add a `PR_AUTHOR` author-check
202	   to `check_reviewer_verdict.py` (the script's docstring explains
203	   how).
204	
205	### `code-reviewer-gate` — how the sentinel works
206	
207	The code-reviewer agent runs against every PR. When it finishes, post
208	the verdict as a PR comment whose **first line** is the sentinel and
209	whose body includes a `reviewed-sha:` line binding the verdict to the
210	exact commit that was reviewed:
211	
212	- **To approve merge:**
213	  ```
214	  [code-reviewer] verdict: APPROVED
215	  reviewed-sha: <full 40-char head SHA of the PR>
216	
217	  <rest of the review body — summary, findings, tradeoffs…>
218	  ```
219	
220	- **To block merge:**
221	  ```
222	  [code-reviewer] verdict: CHANGES REQUESTED
223	  reviewed-sha: <full 40-char head SHA of the PR>
224	
225	  <findings that must be fixed before re-review…>
226	  ```
227	
228	Rules the workflow encodes:
229	
230	- **SHA-anchored.** The `reviewed-sha:` must match the PR's current
231	  HEAD SHA. If you push new commits, the prior verdict's SHA no
232	  longer matches and the gate auto-resets to `failure` ("No verdict
233	  for SHA <new>").
234	- **Last matching verdict for the current SHA wins.** A CHANGES
235	  REQUESTED posted after an APPROVED for the same SHA revokes
236	  approval (e.g. follow-up review spotting something).
237	- **No verdict = failure.** Branch protection blocks merge until a
238	  matching verdict comment lands.
239	
240	### How to invoke the code-reviewer
241	
242	From Claude Code:
243	
244	```
245	Agent tool, subagent_type="code-reviewer", with the PR diff + context.
246	```
247	
248	After the agent returns its review, post a PR comment with the
249	sentinel (above), `reviewed-sha:` line, and the agent's review body.
250	The agent's internal review text alone does not flip the gate — the
251	sentinel comment is what the workflow sees.
252	
253	### Regenerating the verdict after addressing findings
254	
255	1. Fix the findings in new commits on the PR branch.
256	2. The new HEAD SHA invalidates the prior verdict (SHA mismatch).
257	3. Re-invoke the code-reviewer against the updated PR.
258	4. Post a fresh verdict comment with the new `reviewed-sha:`. The
259	   prior comment stays in history for the audit trail; the workflow
260	   picks up the new one automatically.
261	
262	## Agent team
263	
264	This repo runs a documented agent team. Definitions for custom
265	personas live in [`.claude/agents/`](.claude/agents/). Each
266	persona is invocable in two ways: as a one-shot **subagent** via
267	Claude Code's `Agent` tool (`subagent_type` matches the
268	filename), or as a **teammate** in a multi-session agent team
269	(as of 2026-04-21). Pick the coordination mode first; then pick
270	the persona(s).
271	
272	### Coordination modes
273	
274	Solo session vs. subagent vs. agent team — pick the smallest
275	mode that fits the task:
276	
277	| Mode | Use for | Don't use for |
278	| --- | --- | --- |
279	| **Solo session** | Routine sequential work, single-file edits, long-running tasks that rely on `/resume` or `/rewind`, cloud deploy / infra work where the shell may be interrupted. | Workloads that genuinely fan out. |
280	| **Subagent (`Agent` tool)** | Focused helper for research, verification, or one-off review within a session. The result matters, not the conversation. The SHA-anchored `code-reviewer` verdict on every PR runs here by default. | Workflows where the helper needs to talk to a peer before reporting back. |
281	| **Agent team** | 3–5 parallel workstreams that need to talk to each other: parallel review (correctness + perf + ops simultaneously), adversarial debugging (competing hypotheses), cross-layer features (frontend / backend / tests owned separately), multi-angle research. | Long-running deploy or infra work — no `/resume` restoration of in-process teammates; a shell interruption loses the team. Short sequential tasks (overhead not justified). Nested teams (not supported). |
282	
283	### Personas
284	
285	| Agent                       | File                                              | Owns                                                              | Triggers                                                                                                              |
286	| ---                         | ---                                               | ---                                                                | ---                                                                                                                   |
287	| `code-reviewer`             | built-in Claude Code                              | Adversarial review across correctness, security, perf, design.    | Every PR before merge.                                                                                                |
288	| `cloud-ops-specialist`      | [`.claude/agents/cloud-ops-specialist.md`](.claude/agents/cloud-ops-specialist.md) | Hetzner / Kamal / Dockerfile / cloud-init / Tailscale / TLS / DNS / Logfire / spend / secret flow / release tagging.  | PRs touching `Dockerfile*`, `.kamal/`, `config/deploy.yml`, `cloud-init*`, `deploy/`, `.github/workflows/deploy*.yml`, `docs/deploy.md`, ADR-0006, ADR-0008; release-tag PRs; incident / rollback; spend questions. |
289	| `simplify` skill            | bundled Claude Code skill                         | End-of-milestone pruning of premature abstractions.               | Milestone close.                                                                                                       |
290	| drift-check (convention)    | (no bespoke agent — `code-reviewer` with prompt)  | Repo-state vs. plan / ADR / exit-criteria verification.           | Milestone close.                                                                                                       |
291	| `quality-steward`           | [`.claude/agents/quality-steward.md`](.claude/agents/quality-steward.md) | Periodic retrospection + proactive quality/architecture improvement. Drafts milestone retros and periodic pulse checks. | Milestone close (required retro draft); quarterly scheduled pulse check + 60-day backstop if no milestone closed. Covers both cfo and ingest from a single trigger. Kill switch: `quality-steward: paused` label. |
292	
293	### When to invoke `cloud-ops-specialist`
294	
295	- Any PR that modifies: `Dockerfile`, `.dockerignore`, `config/deploy.yml`,
296	  `.kamal/**`, `cloud-init*`, `deploy/**`, `.github/workflows/deploy*.yml`,
297	  `docs/deploy.md`, `docs/decisions/0006-cloud-deployment-target.md`, or
298	  `docs/decisions/0008-auth-strategy.md`.
299	- Any PR that changes env-var surfaces in `src/monarch_cfo/api/settings.py`
300	  auth / observability / chat-provider fields.
301	- Release-tag PRs (`v<date>` tags that trigger GHA deploy).
302	- Incident response and rollback decisions.
303	- Spend/capacity/retention questions.
304	
305	### Agent teams
306	
307	When coordination mode is "agent team" (above):
308	
309	- **Team size:** 3–5 teammates is the sweet spot; token cost
310	  scales roughly with teammate count — budget accordingly.
311	- **No resumption.** Teams cannot be restored via `/resume` or
312	  `/rewind`. Long-running `cloud-ops-specialist` deploy runs
313	  therefore stay solo until Claude Code adds in-process
314	  teammate restoration.
315	- **One team per session; no nesting.** If a teammate needs
316	  fan-out, it uses subagents, not a nested team.
317	- **Shared permission mode.** All teammates inherit the lead's
318	  permission mode.
319	- **Direct mailbox.** Teammates `message` / `broadcast` each
320	  other without routing through the lead.
321	- **Persona carryover.** Spawning a `.claude/agents/*.md` file
322	  as a teammate appends the persona body to the teammate's
323	  system prompt and honors the `tools` allowlist + `model`
324	  fields. The `skills` and `mcpServers` frontmatter fields are
325	  **not** carried — teammates load those from project / user
326	  settings. Source: [agent-teams docs](https://code.claude.com/docs/en/agent-teams);
327	  re-verify if Claude Code releases change teammate behavior.
328	
329	Concrete team-mode opportunities on this repo:
330	
331	- **PR review** — `code-reviewer` + `cloud-ops-specialist` +
332	  `Plan` (built-in Claude Code sub-agent, architecture-owner
333	  framing) on deploy-adjacent or cross-layer PRs. A debate instead of three sequential reviews.
334	  Post one consolidated SHA-anchored verdict — the gate doesn't
335	  care how many agents produced it.
336	- **Milestone retro (ADR-0011)** — `quality-steward` as lead,
337	  with "what broke" / "what held" / "standing rules" teammates.
338	  Pilot at the next milestone close.
339	- **Adversarial debugging** — multi-regression hunts or
340	  competing-hypothesis debugging (the M8 close-out's
341	  5-CI-regression hunt is the historical example).
342	- **Cross-layer feature work** — UI + API + tests teammates
343	  when the surfaces have independent ownership.
344	
345	### Standing scope fences applied to every agent
346	
347	1. **Synthetic data only on the Hetzner VM until M7.5 PR-4 ships.**
348	   No real Monarch exports on the cloud instance until the
349	   ADR-0008 cookie-session auth is live and verified by an
350	   explicit follow-up go/no-go PR. PR-1 / PR-2 seed the synthetic
351	   fixtures; `docs/deploy.md` must not document a real-data path
352	   until the go/no-go PR.
353	2. **Never commit secrets.** Local dev reads
354	   `/Users/openclaw-service/Documents/Claude/Projects/.env`.
355	   Production secrets flow through GHA → Kamal → container env.
356	3. **Verify pricing from the live Hetzner API before provisioning.**
357	   Training-era pricing memory is not authoritative.
358	4. **No writes by AI in M8.** The chat analyst is read-only
359	   through M8 per ADR-0009 and issue #16.
360	5. **`code-reviewer` gate applies to every PR**, including ones
361	   authored by the `cloud-ops-specialist`. Specialist ≠
362	   substitute for review.
363	
364	## Useful one-liners
365	
366	```sh
367	uv sync --extra dev                 # install dev deps
368	uv run ruff check .                 # lint
369	uv run ruff format .                # format in place
370	uv run ruff format --check .        # what CI + pre-commit run
371	uv run mypy                         # type-check (strict)
372	uv run pytest                       # tests + coverage (75% overall)
373	uv run pytest -m browser            # Playwright smoke (opt-in)
374	uv run pre-commit run --all-files   # every hook over the tree
375	uv run uvicorn monarch_cfo.api.app:app --reload   # local API
376	monarch-ingest status               # ingest CLI (from the pinned lib)
377	```
378	
379	## Cross-repo coordination
380	
381	Public-API changes in
382	[`melon-monarch-ingest`](https://github.com/melon-lab-com/melon-monarch-ingest)
383	require a coordinated pin bump in this repo's `pyproject.toml`
384	(`melon-monarch-ingest @ git+https://…@<sha>`). Ingest PRs flag
385	downstream impact in the "Downstream" checkbox on the PR template;
386	cfo lands the matching bump alongside whatever milestone needs the
387	new API.
388	

0001-stack-choice.md
0005-branch-protection-deferred.md
0006-cloud-deployment-target.md
0008-auth-strategy.md
0009-chat-provider-abstraction.md
0011-retro-and-quality-steward.md
README.md
__init__.py
app.py
deps.py
middleware.py
routers
schemas
settings.py
decisions
deploy.md
media
plan.md
reports.md
web.md
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

UNKNOWN
code-reviewer-gate FAILURE
UNKNOWN
lint + types + tests (py3.12, chat-gemini) FAILURE
UNKNOWN
video-proof gate FAILURE
UNKNOWN
lint + types + tests (py3.12, chat-anthropic) FAILURE
UNKNOWN
lint + types + tests (py3.12, chat-openai) FAILURE
UNKNOWN
pre-commit hooks FAILURE
UNKNOWN
code-reviewer-gate SUCCESS
UNKNOWN
lint + types + tests (py3.12, chat-gemini) SUCCESS
UNKNOWN
video-proof gate SUCCESS
UNKNOWN
lint + types + tests (py3.12, chat-anthropic) SUCCESS
---comments---
[code-reviewer] verdict: APPROVED
reviewed-sha: 966b5ebb27a9e69029755dcf4fce5a154e03c400

## Summary

name: code-reviewer gate

on:
  pull_request:
    types: [opened, synchronize, reopened]
  issue_comment:
    types: [created]

# statuses: write — needed to POST a commit status to the PR's HEAD SHA.
# For issue_comment events the workflow runs on the default branch, not the
# PR head, so we cannot rely on the Actions check-run being associated with
# the right commit.  We post the status explicitly via the Statuses API.
permissions:
  contents: read
  pull-requests: read
  statuses: write
  # issues: read — the workflow lists PR comments via
  # `repos/$REPO/issues/$PR_NUMBER/comments`, which is an Issues API
  # endpoint.  Without this scope the gh api call returns 403 and the
  # gate fails even on PRs that have a valid verdict comment.  Matches
  # the ingest version.
  issues: read

jobs:
  code-reviewer-gate:
    name: code-reviewer-gate
    runs-on: ubuntu-latest
    # Skip regular issue comments (not on a PR).
    if: >
      github.event_name == 'pull_request' ||
      github.event.issue.pull_request != null
    steps:
      - uses: actions/checkout@v4

      - name: Resolve PR number and HEAD SHA
        id: pr
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          REPO: ${{ github.repository }}
        run: |
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

1	# 0012 — Authentication strategy: Google OIDC + signed session cookie + `sub` allowlist
2	
3	- **Status:** Accepted
4	- **Date:** 2026-04-26
5	- **Milestone:** M7.5 (PR-4 implements)
6	- **Supersedes:** [ADR-0008](0008-auth-strategy.md) — Tailscale edge + self-hosted signed-cookie auth
7	- **Related:** [#110](https://github.com/melon-lab-com/melon-monarch-cfo/issues/110) (the revisit issue), [#107](https://github.com/melon-lab-com/melon-monarch-cfo/pull/107) (PR-1, 503 bootstrap gate already shipped)
8	
9	## Context — why ADR-0008 is being reconsidered
10	
11	ADR-0008 (accepted 2026-04-19) picked Option D: a Tailscale funnel at
12	the network edge layered with a self-hosted signed-cookie auth at the
13	app layer. Two days later, [#110](https://github.com/melon-lab-com/melon-monarch-cfo/issues/110)
14	recorded the user's preference reversal in favour of Option B (Google
15	OAuth on the public internet, no Tailscale). The reasons surfaced in
16	that issue and in the user's stated framing:
17	
18	1. **Tailscale enrolment is real friction for a household tool used
19	   from devices the operator does not control device policy on**
20	   (phones reinstalled by the household, occasional borrowed laptops).
21	   Re-enrolment failure modes are silent — the app simply becomes
22	   unreachable, with no log on our side.
23	2. **Tailscale is itself a vendor.** ADR-0008 §Negative already
24	   acknowledged this conflicts partially with ADR-0006's prefer-OSS
25	   stance. The user is willing to consolidate vendors on Google rather
26	   than carry both Google (for everything else in their life) AND
27	   Tailscale (only for this one app).
28	3. **PR-1, PR-2, PR-3 of M7.5 all assume the 503 bootstrap gate, not
29	   a specific auth scheme.** PR-1 (#107) shipped only the 503 cell of
30	   the three-state model. So the cost of revisiting at PR-4 is the
31	   design pivot only — no shipped code is being thrown away.
32	
33	The honest framing: **we are choosing Google as a known-good
34	authenticator over Tailscale as a known-good network gate.** The bet
35	is that Google's IdP hardening (HSTS, anti-phishing, hardware-key
36	support at the account level, Google Advanced Protection) is a
37	stronger guarantee for the household than a Tailscale layer they will
38	accidentally disable on a phone reinstall. The mechanisms below exist
39	to bound the blast radius of that bet.
40	
41	## Constraints — disposition vs ADR-0008
42	
43	ADR-0008's five constraints in §Context are addressed individually
44	here. Two are honoured by the new mechanism, one is materially
45	revised, one is explicitly waived with rationale, and one is honoured
46	unchanged.
47	
48	| #   | ADR-0008 constraint                                   | Disposition  | Mechanism / rationale                                                                                                                                                                                                                                                          |
49	| --- | ----------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
50	| 1   | Household-scale (1–2 humans, no signup, no reset)     | **Honour**   | No signup flow exists. The `sub` allowlist (below) IS the user table. Adding a permitted account is a code-change PR — the right friction at this scale.                                                                                                                       |
51	| 2   | No third-party identity provider                      | **Waive**    | This is THE waiver this ADR makes. Defended below: scope is restricted to `openid email profile` only (no Drive, Calendar, contacts), Google issues an identity assertion and is then out of the request path, financial data never touches Google's servers. Costs documented in §Failure modes. |
52	| 3   | Localhost zero-friction                               | **Honour**   | `AUTH_ENABLED=false` (existing default in `src/monarch_cfo/api/settings.py:42`) keeps every middleware inert. The new OAuth middleware uses the same flag. `uv run uvicorn` against `127.0.0.1` continues to behave as today.                                                  |
53	| 4   | Agent-operable                                        | **Honour**   | Allowlist mutation is a code-change PR (agent-authorable). Cookie-secret rotation is one `gh secret set` + tag push. Google client-secret rotation matches the same pattern plus a one-time browser touch in Google Cloud Console (matches ADR-0006's accepted pattern for IdP setup steps). |
54	| 5   | Defence in depth (one app-layer bug must not fully expose data) | **Revised** | Tailscale's network-layer gate is gone. The new second layer is **(a)** the `sub` allowlist (a Google login alone is insufficient — must be one of the enumerated `sub` values), **(b)** boot-time validators that fail-closed if any auth secret is missing or malformed, **(c)** per-IP rate-limits on `/auth/login` and `/auth/callback`, and **(d)** the 503 bootstrap gate preserved as a one-env-flag emergency cutoff. WebAuthn at the app layer is the M7.6 follow-up that adds a true second factor. The honest read: this is weaker than two independent vendor gates; the trade is documented. |
55	
56	## Decision
57	
58	Ship **Google OIDC + signed session cookie + hardcoded-but-empty-fails-closed Google `sub` allowlist** at M7.5 PR-4, on the public internet, with no Tailscale or Cloudflare layer. The three-state `AUTH_ENABLED` / `AUTH_BOOTSTRAP_503` model from ADR-0008 carries over verbatim, with one row's behaviour revised:
59	
60	| `AUTH_ENABLED` | `AUTH_BOOTSTRAP_503` | Behaviour                                                                              | Used for                 |
61	| -------------- | -------------------- | -------------------------------------------------------------------------------------- | ------------------------ |
62	| `false`        | `false`              | Every route open (no auth check).                                                      | Local dev (M3–M6 flows). |
63	| `false`        | `true`               | Every route → 503 except `/healthz`. Auth middleware inert.                            | First cloud boot, kill-switch. |
64	| `true`         | `false`              | Auth middleware active. 401 on JSON, 302 → `/auth/login` on HTMX. **Now Google OIDC.** | Production.              |
65	
66	The illegal cell (`true` + `true`) continues to be rejected at boot
67	by `_check_auth_state` in `src/monarch_cfo/api/settings.py`. Three new
68	boot-time validators land alongside it (see §Operational posture).
69	
70	## Architecture
71	
72	### OIDC library + OAuth flow
73	
74	**Library: `authlib` (`authlib.integrations.starlette_client.OAuth`).**
75	
76	Picked over `google-auth-oauthlib` and over a hand-rolled `httpx`
77	client:
78	
79	- `authlib` ships a Starlette integration that handles the discovery-
80	  document fetch, JWKS rotation, ID-token verification (signature,
81	  `iss`, `aud`, `exp`, `nonce`), and PKCE generation as one
82	  configured client. Smallest amount of code we own; smallest place
83	  we can be wrong about JWT verification.
84	- `google-auth-oauthlib` is Google-specific (slight dependency lock-
85	  in flavour), aimed at server-to-server / installed-app flows; its
86	  Starlette web-flow path is less polished. Switching IdPs later
87	  (Microsoft, GitHub) would mean rewriting the integration.
88	- A hand-rolled discovery-doc client minimises deps but maximises
89	  the "we own JWT verification" footgun (JWKS caching, key rotation,
90	  clock skew on `exp`, `nonce` binding). Not the right amount of
91	  trust to delegate.
92	
93	**Flow: Authorization Code + PKCE.**
94	
95	- **PKCE** (RFC 7636) is non-negotiable even though Google still
96	  issues a client secret for confidential clients. Defends against
97	  authorisation-code interception (a malicious browser extension
98	  grabbing the `code` from the callback URL before our server
99	  consumes it). `authlib` generates `code_verifier` and stores it
100	  in the request session before redirect.
101	- **`state`** parameter: 32-byte URL-safe random token, stored in
102	  the temporary pre-login session cookie, validated on
103	  `/auth/callback`. CSRF defence for the callback (see §CSRF).
104	- **`nonce`** parameter: binds the ID token to the specific
105	  authentication request — `authlib` generates and verifies it.
106	  Defends against ID-token replay across sessions.
107	- **Scopes:** `openid email profile` — and *only* these. `openid` is
108	  required for OIDC; `email` for human-readable logging; `profile`
109	  for the display name in the UI header. **Principle: we ask Google
110	  for an identity assertion, not for data.** Any future scope
111	  addition requires an ADR addendum; the code-reviewer gate must
112	  flag scope-list edits as security-sensitive.
113	- **`prompt=select_account`** on the auth request URL. Forces
114	  Google's account-chooser UI rather than silently using the
115	  browser's default Google account. Important when the user's
116	  primary Google account is not the household-finance one.
117	- **`redirect_uri`:** a single registered URI at
118	  `https://monarch.melon-lab.com/auth/callback`. No path variables,
119	  no wildcards. The value is env-driven (`AUTH_OAUTH_REDIRECT_URI`)
120	  so a staging deploy or local OAuth test can override without code
121	  change, but the production deploy hardcodes the production value
122	  in `config/deploy.yml`'s `env: clear` block (the cloud-ops slice
123	  owns this).
124	- **Discovery document:**
125	  `https://accounts.google.com/.well-known/openid-configuration`.
126	  `authlib` fetches once at app startup and caches; JWKS keys are
127	  refetched on `kid` mismatch.
128	
129	### FastAPI plug points
130	
131	Three middleware register in this order in
132	`src/monarch_cfo/api/app.py:120` (Starlette runs the **last-added**
133	middleware closest to the route handler — requests flow through
134	middleware in **reverse** registration order, then back out in
135	registration order):
136	
137	```
138	api.add_middleware(BootstrapGate503Middleware, active=...)   # outermost — runs first on request
139	api.add_middleware(SessionMiddleware, secret_key=..., ...)   # middle — provides request.session
140	api.add_middleware(OAuthAuthMiddleware, settings=...)        # innermost — runs last; first to see route
141	```
142	
143	Reasoning, top to bottom:
144	
145	1. **`BootstrapGate503Middleware` stays outermost.** Load-bearing.
146	   The 503 kill-switch must short-circuit BEFORE the OAuth
147	   middleware tries to read `request.session`, because in an
148	   emergency we may have a misconfigured Google client that throws
149	   on session decode and we still need `/healthz` to respond. The
150	   existing implementation in `middleware.py:51` already returns
151	   immediately for the allowlist; we only confirm registration
152	   order.
153	2. **`SessionMiddleware`** (Starlette built-in). Provides
154	   `request.session` as a signed-cookie-backed dict. Uses
155	   `itsdangerous` under the hood. The OAuth middleware reads
156	   `request.session["sub"]`, `["email"]`, `["issued_at"]` from this.
157	3. **`OAuthAuthMiddleware`** (new, lives in
158	   `src/monarch_cfo/api/auth.py` — the module name ADR-0008's
159	   PR-4 deliverable list reserved). Consults `request.session`,
160	   looks at `request.url.path`, decides:
161	   - Path in **public allowlist** (`/healthz`, `/auth/login`,
162	     `/auth/callback`, `/auth/logged-out`, `/ui/static/*`) → pass
163	     through.
164	   - `/openapi.json`, `/docs`, `/redoc` → require valid session
165	     (these leak schema info; ADR-0008 §Interaction with existing
166	     code noted this).
167	   - Otherwise → require valid session. If absent: 401 JSON
168	     response when `Accept: application/json`, 302 to
169	     `/auth/login?next=<original-url>` for HTMX/HTML requests.
170	
171	**New routes** (all in `src/monarch_cfo/api/routers/auth.py`,
172	`include_in_schema=False`):
173	
174	| Route | Method | Purpose | Auth required? |
175	| ----- | ------ | ------- | -------------- |
176	| `/auth/login` | GET | Initiate OAuth flow. Sets `state`+`code_verifier`+`nonce` in `request.session`, returns 302 to Google. Reads `?next=` query, validates same-origin, stores in session for post-callback redirect. | No |
177	| `/auth/callback` | GET | Receives `?code=&state=` from Google. Validates `state`, exchanges code for tokens via PKCE, verifies ID token, checks `sub` against allowlist, populates `request.session["sub"]` etc., redirects to stored `next` (or `/ui/`). | No (validates own state) |
178	| `/auth/logout` | POST | Clears `request.session`, sets fresh empty cookie, redirects to `/auth/logged-out`. **POST + double-submit-cookie CSRF** (see §CSRF). | Yes |
179	| `/auth/logged-out` | GET | Renders a Jinja "you have been signed out — sign in again" page. Includes a link to `https://accounts.google.com/Logout` for users who explicitly want to drop the IdP-side session too. | No |
180	
181	The SSE chat endpoints (`/chat/stream`, `/chat/sessions/{id}/turn`)
182	work over the same cookie. EventSource sends cookies on same-origin
183	reconnects; the 24 h `max_age` (below) does not break long-running
184	streams that started on a fresh cookie. **One sharp edge:** if the
185	cookie expires mid-stream and EventSource auto-reconnects, the
186	reconnect 401s and EventSource retries forever. The chat UI must
187	listen for the `error` event and surface "session expired — sign in
188	again" instead of silently spinning. Flagged for PR-4's UI work.
189	
190	### Session cookie
191	
192	**Use `starlette.middleware.sessions.SessionMiddleware`. No server-
193	side store.** The cookie IS the session — same revocation model as
194	ADR-0008 (revocation = rotate the signing key).
195	
196	| Attribute     | Value                              | Reasoning                                                                                                                                                                                                                                                                       |
197	| ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
198	| `name`        | `monarch_session`                  | Distinct from any `csrftoken` cookie.                                                                                                                                                                                                                                          |
199	| `secret_key`  | `AUTH_COOKIE_SECRET` (≥ 32 random bytes) | Same env-var name as ADR-0008's PR-1 placeholder. PR-4 rotates the placeholder and pushes the rotated value via `gh secret set`. |
200	| `max_age`     | 86400 (24 hours)                   | **Shorter than ADR-0008's 30-day rolling.** Reasoning: Google IS a vendor in the path now; a 30-day window where we can't see Google revocation events is too long. 24 h means at worst the user re-clicks "Sign in with Google" once a day — tolerable, especially since Google itself silently re-auths if the user's Google session is fresh. |
201	| `same_site`   | `lax`                              | Allows top-level navigation from external sites to land authenticated (so a bookmark works) but blocks cross-site POSTs with the cookie. The OAuth callback IS a cross-site GET from `accounts.google.com`; `lax` permits it. `strict` would break the callback. |
202	| `https_only`  | `True` (Secure)                    | Production-only enforcement. Local dev (`AUTH_ENABLED=false`) leaves the cookie path unused.                                                                                                                                                                                                                                                  |
203	| `httponly`    | `True` (default)                   | Defence against `document.cookie` exfiltration via XSS. The HTMX UI does not need JS access to the session cookie.                                                                                                                                                                                                                            |
204	| `path`        | `/`                                | Cookie applies to all paths; intentional — the OAuth flow needs the cookie on `/auth/callback` too.                                                                                                                                                                                                                                              |
205	
206	**Session payload** (the dict put into `request.session`):
207	
208	```python
209	{
210	    "sub": "108476937...",          # Google subject ID — the allowlist key
211	    "email": "user@example.com",    # for log lines and the UI header; NOT a security identifier
212	    "issued_at": 1714125600,        # unix seconds; rolling re-stamp at half max_age
213	    "name": "User Display Name",    # for UI greeting
214	}
215	```
216	
217	**Rolling re-stamp:** half-rolling. On every request, if `issued_at`
218	is older than `max_age / 2` (12 h), the middleware re-stamps
219	`issued_at` and Starlette re-emits the cookie. Avoids a Set-Cookie
220	header on every request while still extending active sessions.
221	
222	**Idle timeout vs absolute timeout:** absolute 24 h, no separate idle
223	timeout. The use case is a user who logs in once a day and uses the
224	app intermittently throughout the day; an idle timeout would force
225	re-login mid-session for anyone who left the tab open during dinner.
226	
227	**Cookie size budget:** stay under 4 KB to avoid browser cookie
228	fragmentation. The payload above is ~200 bytes signed; we have
229	plenty of headroom but must not balloon by storing full ID-token
230	claims or per-request state.
231	
232	### CSRF posture
233	
234	Three classes of state-changing request:
235	
236	1. **OAuth callback (`GET /auth/callback`)** — protected by the
237	   OAuth `state` parameter generated and validated by `authlib`.
238	   Defends against the attack where an adversary tricks the browser
239	   into hitting `/auth/callback?code=ATTACKER_CODE&state=...` to log
240	   the victim into the attacker's Google account.
241	2. **`POST /auth/logout`** — protected by **double-submit-cookie
242	   CSRF token**. On every authenticated GET, the middleware ensures
243	   a `csrftoken` cookie (random 32 bytes) exists. The logout form
244	   renders the value in a hidden `csrf_token` field via Jinja (no JS
245	   read of the cookie needed). The route handler verifies cookie
246	   and form fields match. Justification: ADR-0008 explicitly
247	   documented that `SameSite=Lax` does not cover login POSTs; we
248	   extend that prudence to logout. The double-submit pattern needs
249	   no server-side store.
250	3. **Chat endpoints (`POST /chat/once`, `POST /chat/stream`,
251	   `POST /chat/sessions`, `POST /chat/sessions/{id}/turn`)** —
252	   currently rely on the auth cookie. **CSRF posture: rely on
253	   `SameSite=Lax` + the requirement that JSON-content-type POSTs
254	   include `Content-Type: application/json` headers.** Browsers
255	   won't send a custom Content-Type on cross-site form POSTs
256	   without a preflight; SameSite=Lax blocks the cookie on cross-
257	   site POSTs anyway. The HTMX chat form uses a same-origin POST,
258	   which is unaffected. **Decision: do NOT add per-route CSRF
259	   tokens to chat endpoints.** Document explicitly in the runbook
260	   so a future M9 PR adding a true cross-origin write doesn't
261	   quietly remove the protection.
262	
263	### Account allowlist
264	
265	**Env-driven list of Google `sub` claims, fail-closed if empty.**
266	
267	```python
268	# src/monarch_cfo/api/settings.py — sketch only; PR-4 implements
269	
270	class ApiSettings(BaseSettings):
271	    auth_allowed_google_subs: list[str] = Field(
272	        default_factory=list,
273	        validation_alias=AliasChoices(
274	            "AUTH_ALLOWED_GOOGLE_SUBS",
275	            "MONARCH_API_AUTH_ALLOWED_GOOGLE_SUBS",
276	        ),
277	    )
278	    # comma-separated parsing in field_validator; each entry must match
279	    # ^\d{10,}$ (Google sub claims are numeric strings ≥ ~10 digits).
280	
281	    @model_validator(mode="after")
282	    def _check_auth_secrets(self) -> ApiSettings:
283	        if self.auth_enabled and not self.auth_allowed_google_subs:
284	            raise ValueError(
285	                "AUTH_ENABLED=true with no allowlisted Google subject IDs "
286	                "would accept any Google login; refusing to boot."
287	            )
288	        # ... and the other secret-presence checks; see §Operational posture
289	        return self
290	```
291	
292	Reasoning for **env-driven, no hardcoded default** (the architecture-
293	owner's slice originally proposed a hardcoded `frozenset` literal as
294	a security floor; the integration sides with the cloud-ops position):
295	
296	- **A hardcoded default would mean committing the production `sub`
297	  values to source.** Even though `sub` claims are not secrets, they
298	  uniquely identify which Google accounts gate the household's
299	  finance app — household-PII-adjacent.
300	- **Fail-closed validator** at boot time provides the same "deploy
301	  cannot silently accept anyone" guarantee without leaking the
302	  identifiers into git. A misconfigured deploy with empty
303	  `AUTH_ALLOWED_GOOGLE_SUBS` raises `ValueError` before `uvicorn`
304	  is ready; the container exits non-zero; kamal-proxy fails the
305	  health check and keeps the prior good container in the proxy
306	  pool — no traffic reaches the bad container. The household is
307	  never exposed to a half-configured auth. (See §Cutover for the
308	  explicit Kamal 2 behaviour and PR-4's verification step.)
309	- **The `sub` claim, NOT email.** Email aliases can be reassigned
310	  by Google Workspace admins or recycled if the account is deleted;
311	  `sub` is stable for the lifetime of the Google account and unique
312	  per (account × OAuth client). This is THE single most important
313	  defence against the "compromised email" attack vector.
314	
315	**Failure mode for an unlisted-but-valid Google account:**
316	
317	- `/auth/callback` runs ID-token verification → succeeds.
318	- `sub` is checked against `auth_allowed_google_subs` → not found.
319	- Response: 403 Forbidden, render a Jinja page that names the
320	  rejected email and tells the visitor to use the household account
321	  or contact the operator.
322	- **Log a WARNING** with rejected `sub` (last 4 chars only) and
323	  email (full) via Logfire (PR-3 wiring) so the operator sees
324	  real-world login attempts that hit the allowlist wall.
325	- The session is NOT populated; the cookie is cleared.
326	- The per-IP rate-limit on `/auth/callback` (below) bounds anyone
327	  spinning the OAuth flow trying to brute-force allowlisted `sub`
328	  values — not really a feasible attack since they'd need to log
329	  into many Google accounts, but the rate limit is cheap.
330	
331	### Logout
332	
333	Three layers, each handled differently:
334	
335	1. **Local session cookie:** cleared on `POST /auth/logout` via
336	   `request.session.clear()`. SessionMiddleware emits a Set-Cookie
337	   that empties the session. Effective immediately.
338	2. **Google's session in the browser:** **CANNOT BE REVOKED BY US.**
339	   Documented residual risk. After our logout, the user is still
340	   logged into Google in their browser, so clicking "Sign in with
341	   Google" again is silent (no password prompt). Mitigation: the
342	   logged-out page links to `https://accounts.google.com/Logout`
343	   for the "shared computer" use case.
344	3. **Google's grant of our app's permission:** We do NOT call
345	   Google's revocation endpoint
346	   (`https://oauth2.googleapis.com/revoke`) on logout. Reasoning:
347	   revoking the grant means the next login re-displays the consent
348	   screen, which is annoying for a household tool used daily. The
349	   grant only contains `openid email profile` so leaving it intact
350	   is low-impact. Operators who want to nuke the grant for a
351	   specific account can do it via Google account settings →
352	   Security → Third-party access.
353	
354	**What we cannot prevent:** if a user removes the app's permission
355	via Google account settings externally, **we are not notified**.
356	Their existing session cookie continues to work for up to 24 h until
357	expiry. Discussion in §Failure modes.
358	
359	### WebAuthn — deferred to M7.6
360	
361	Issue [#110](https://github.com/melon-lab-com/melon-monarch-cfo/issues/110)
362	proposes WebAuthn as a second factor on top of Google. **Defer to a
363	follow-up PR (M7.6).** Reasoning:
364	
365	- WebAuthn at the application layer requires: a `webauthn` PyPI
366	  package, a credentials table (id, sub, public_key_cose,
367	  sign_count, transports, device_name, registered_at), a
368	  registration ceremony route (post-first-login), an authentication
369	  ceremony route, and HTMX wiring on the login page. Non-trivial
370	  surface — better designed and shipped as its own PR than rushed
371	  into PR-4.
372	- The Google account itself can be (and per the runbook **must
373	  be**) hardened with WebAuthn at the IdP layer. **PR-4's
374	  prerequisite is operator confirmation** that each allowlisted
375	  Google account has at least one phishing-resistant second factor
376	  enabled at Google (passkey, security key, or Advanced Protection
377	  enrolment). This gives us most of WebAuthn's blast-radius
378	  reduction without building it ourselves.
379	- Issue #110 lists WebAuthn under "risk mitigations to evaluate" —
380	  it does not mandate it for PR-4.
381	
382	**M7.6 outline** (so we're not punting blind): add
383	`webauthn_credentials` table (Alembic migration, cfo-side because
384	user identity lives here, not in ingest); add
385	`/auth/webauthn/register/{begin,complete}` and
386	`/auth/webauthn/auth/{begin,complete}` routes; flag-gate via a new
387	`AUTH_REQUIRE_WEBAUTHN: bool = False`; when true, the OAuth
388	callback redirects to `/auth/webauthn/auth` instead of populating
389	`sub` directly. File the M7.6 issue alongside PR-4's follow-up
390	issue.
391	
392	## What protects what (route-by-route)
393	
394	| Route                                    | 503 gate | Google login | WebAuthn (M7.6) | Open |
395	| ---------------------------------------- | :------: | :----------: | :-------------: | :--: |
396	| `/healthz`                               | open     | open         | open            |  ✓   |
397	| `/auth/login`                            | gated    | open         | open            |  ✓   |
398	| `/auth/callback`                         | gated    | open (state) | open            |  ✓   |
399	| `/auth/logout`                           | gated    | required     | required        |      |
400	| `/auth/logged-out`                       | gated    | open         | open            |  ✓   |
401	| `/ui/static/*`                           | gated    | open         | open            |  ✓   |
402	| `/openapi.json`, `/docs`, `/redoc`       | gated    | required     | required        |      |
403	| `/ui/*` (UI routes)                      | gated    | required     | required        |      |
404	| `/transactions`, `/accounts`, `/categories`, `/balances/*`, `/net-worth/*`, `/merchants/*`, `/reports/*` | gated | required | required |  |
405	| `/chat/once`, `/chat/stream`             | gated    | required     | required        |      |
406	| `/chat/sessions[/...]` (CRUD + turn)     | gated    | required     | required        |      |
407	
408	## Operational posture
409	
410	### What we delete (the Tailscale layer): impact accounting
411	
412	Tailscale was the **bug-containment tier** — a network-layer gate
413	from a different vendor that required two simultaneous failures (an
414	app-layer auth bug AND a Tailscale compromise) to expose data.
415	Without it, a regression in the auth middleware (a misordered
416	`add_middleware`, a route mounted before the auth gate, an
417	`if not session.get("user")` typo, an `@router.get("/transactions")`
418	accidentally placed outside the protected prefix) goes from
419	"exposes data only to nodes already enrolled in our tailnet"
420	(≈ 2 humans + their devices) to "exposes data to anyone running
421	curl". A misconfigured deploy goes from "503s for tailnet members"
422	to "open transactions endpoint on the public internet" — except
423	that the boot-time validators below are designed to make this case
424	impossible-at-boot.
425	
426	**Public attack-surface delta** (empirical baseline for any
427	unbranded Hetzner VM with an A-record):
428	
429	- TLS-handshake probes within minutes of DNS propagation (Censys,
430	  Shodan, the standard internet-scanner cohort). Quiet.
431	- HTTP path-probing within hours: `/.env`, `/wp-login.php`,
432	  `/admin`, `/api/v1/users`, `/.git/config`. Order-of-magnitude
433	  10²–10³ requests/day. Not a load issue at this scale; an
434	  observability-noise issue.
435	- Brute-force on the login form within days–weeks of `/auth/login`
436	  becoming a real endpoint. Botnets enumerate via Common Crawl /
437	  cert-transparency, see a Google-OIDC button (no password field),
438	  and most move on. The risk shifts to the callback handler
439	  accepting unauthenticated POSTs — defended by `state` validation
440	  + per-IP rate-limit.
441	
442	**DDoS exposure** is unchanged from the "single Hetzner CPX11 with
443	a public IP" baseline — see §"DDoS / scraping honest read" below.
444	
445	### New env vars on `ApiSettings` and Kamal
446	
447	| Env var                          | Type        | `validation_alias`                                                       | Boot-time validator (when `AUTH_ENABLED=true`)                                      | Kamal placement |
448	| -------------------------------- | ----------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------- |
449	| `GOOGLE_OAUTH_CLIENT_ID`         | `str`       | `("GOOGLE_OAUTH_CLIENT_ID", "MONARCH_API_GOOGLE_OAUTH_CLIENT_ID")`       | non-empty                                                                           | `env: clear`    |
450	| `GOOGLE_OAUTH_CLIENT_SECRET`     | `SecretStr` | `("GOOGLE_OAUTH_CLIENT_SECRET", "MONARCH_API_GOOGLE_OAUTH_CLIENT_SECRET")` | non-empty                                                                         | `env: secret`   |
451	| `AUTH_COOKIE_SECRET`             | `SecretStr` | `("AUTH_COOKIE_SECRET", "MONARCH_API_AUTH_COOKIE_SECRET")`               | length ≥ 32 bytes                                                                   | `env: secret`   |
452	| `AUTH_ALLOWED_GOOGLE_SUBS`       | `list[str]` (comma-sep) | `("AUTH_ALLOWED_GOOGLE_SUBS", "MONARCH_API_AUTH_ALLOWED_GOOGLE_SUBS")` | non-empty; each entry matches `^\d{10,}$`                                          | `env: clear`    |
453	| `AUTH_OAUTH_REDIRECT_URI`        | `HttpUrl`   | `("AUTH_OAUTH_REDIRECT_URI", "MONARCH_API_AUTH_OAUTH_REDIRECT_URI")`     | must be `https://...` if not `localhost`                                            | `env: clear`    |
454	
455	`SecretStr` is load-bearing: `pydantic_settings` redacts it from
456	`__repr__`, so an accidental `print(settings)` or Logfire auto-
457	context capture does not ship the cookie / client secret off-box.
458	
459	The contract between the validator and Kamal: if any check raises,
460	`uvicorn` exits non-zero, kamal-proxy fails the post-deploy health
461	check and keeps the prior good container serving — no traffic to
462	the bad container, no proxy cutover. **A misconfigured go/no-go
463	cutover yields downtime on the new image, not data exposure.**
464	PR-4 must verify the deploy workflow does not mask this exit by
465	retrying or hiding container logs, and the go/no-go PR's smoke
466	must include "intentionally break a secret, push a deploy tag,
467	confirm the bad container does not become the proxy target."
468	
469	`/healthz` stays unauthenticated (per the existing
470	`_BOOTSTRAP_503_ALLOWLIST` in `middleware.py:24` and per the Kamal
471	healthcheck contract). PR-4 must NOT mount the auth middleware in
472	front of `/healthz`.
473	
474	`AUTH_ALLOWED_GOOGLE_SUBS` is in `env: clear` (committed to git in
475	`config/deploy.yml`) — a judgement call: the values are not crypto
476	secrets but they identify who has access. The benefit of having
477	the allowlist diff visible in PR review (rather than mutated out-
478	of-band via `gh secret set`) outweighs the mild PII leakage.
479	Document in the runbook so adding a household member is understood
480	as a code-change PR.
481	
482	`GOOGLE_OAUTH_CLIENT_ID` is in `env: clear` because it's emitted in
483	the OAuth redirect URL the browser sees anyway — not a secret in
484	the cryptographic sense. Visible in deploy.yml diff, easier to
485	spot a misconfiguration.
486	
487	### TLS, DNS, kamal-proxy — what changes (nothing)
488	
489	- **TLS:** unchanged. kamal-proxy + Let's Encrypt for
490	  `monarch.melon-lab.com` already terminate on :443; Google's
491	  callback hits `/auth/callback` over the same listener. Google
492	  REQUIRES `https://` (also enforced by the validator above).
493	- **DNS:** unchanged. Squarespace A-record `monarch` →
494	  `5.78.192.165` (per `config/deploy.yml:56` and `docs/deploy.md`)
495	  is what Google's consent redirect sends the browser to. No new
496	  records needed.
497	- **kamal-proxy:** unchanged at the proxy level. Auth middleware
498	  lives inside FastAPI; kamal-proxy continues to terminate TLS,
499	  forward to `:3000`, and rely on
500	  `--forwarded-allow-ips=127.0.0.1,172.16.0.0/12` (Dockerfile:110)
501	  to keep the upstream IP non-spoofable. **This Dockerfile line is
502	  now load-bearing for abuse mitigation** (the per-IP rate
503	  limiter needs an honest client IP to bucket on); flag in PR-4
504	  review.
505	
506	### Rate-limiting
507	
508	Verified via web fetch of the kamal-deploy.org and basecamp/kamal-
509	proxy docs as of 2026-04-26: **kamal-proxy does NOT support rate
510	limiting, IP allowlists, or fail2ban-style abuse mitigation in
511	any version.** This is by design (rate-limiting is treated as an
512	app-layer concern). So the choice is in-app or edge.
513	
514	**In-app rate-limit middleware: `slowapi`.** Pure Python, ~50 KB
515	image delta, integrates with Pydantic settings, per-IP buckets via
516	`request.client.host` (which the `--forwarded-allow-ips` allow-
517	list already makes trustworthy).
518	
519	| Route             | Per-IP limit         | Reasoning                                                                        |
520	| ----------------- | -------------------- | -------------------------------------------------------------------------------- |
521	| `/auth/login`     | 5 / 15 minutes       | Matches ADR-0008's policy for the (now-deleted) password-login form. Defends against flooding `state`-token issuance. |
522	| `/auth/callback`  | 20 / 15 minutes      | Slightly looser because legitimate redirects can race. Defends against an adversary triggering many full OAuth flows from one IP (resource exhaustion + log-noise + Logfire-span pressure). Code-replay is NOT the threat the limit covers — Google enforces single-use on auth codes, so a replayed `code=` is rejected upstream of our handler. |
523	
524	Both return 429 with a small JSON body. The cloud-ops slice owns
525	the budget; the architecture-owner agrees the policy is consistent
526	with the callback's `state`-validator design.
527	
528	**Host-level fail2ban** (filter on the kamal-proxy access log) was
529	considered and rejected: brittle (depends on exact log format; a
530	future Kamal upgrade silently breaks abuse mitigation).
531	
532	### DDoS / scraping honest read
533	
534	A single Hetzner CPX11 (2 GB RAM, 2 shared vCPU) has **no
535	upstream DDoS protection** that matters against a real botnet.
536	Hetzner has anti-flood at the network edge for genuine volumetric
537	attacks (multi-Gbps SYN floods), but a layer-7 attack from 10K IPs
538	each doing one HTTP/2 request per second is not something Hetzner
539	mitigates for us — it lands in kamal-proxy, exhausts file
540	descriptors, and the box becomes unreachable. CPX11 has no
541	meaningful headroom for any sustained attack.
542	
543	**Whether this matters:** **probably not**, for the threat model of
544	"single household, one operator + family, financial data with no
545	broader resale value to a botnet". The realistic attacker is (a)
546	automated scanners that try every `/.env` and move on, or (b)
547	targeted attacks against which a CPX11 is no match regardless of
548	edge protection. Household-finance threat model is "passive
549	scanners and curiosity", not "targeted DDoS".
550	
551	**Cloudflare-proxy in front, as an OPTIONAL add-on (not adopted
552	in PR-4, documented as follow-up):** free tier covers DDoS, basic
553	WAF, edge cache for the static UI, and a "challenge unfamiliar
554	IPs" rule. Pushes scanner noise off our box entirely. Cuts the
555	Logfire log-volume delta from "10²–10³ probes/day" to "what we
556	want to log". Adds geo-blocking if we ever decide we don't need
557	traffic from outside the operator's country. **Cons:** (a)
558	reintroduces a vendor in the data path — Cloudflare can MITM TLS
559	in proxy mode by definition (the same vendor concern that
560	ADR-0008 constraint 2 originally rejected for IdP, applied to the
561	network path); (b) DNS migration from Squarespace to Cloudflare
562	nudges further from ADR-0006's "agent-operable" goal; (c) free-
563	tier ToS reservations apply to non-HTML payloads. **Decision:
564	revisit only if Logfire spend or kamal-proxy log volume becomes
565	operationally noisy.**
566	
567	### Logfire spend impact
568	
569	PR-3 wired Logfire via `telemetry.configure()` with a `LOGFIRE_TOKEN`
570	GHA secret and a spend tripwire workflow.
571	
572	- **Today (503 gate):** Kamal proxy access logs cover `/healthz`
573	  polls (every 10 s per `deploy.yml` healthcheck) plus whatever
574	  bots find. FastAPI access log = `/healthz` only. Logfire spans
575	  emitted = effectively zero.
576	- **Post-PR-4:** ~20K–50K spans/month estimated total (~500/day
577	  scanner noise + 100–500/day real traffic + login-page probes).
578	- **Logfire free-tier ceiling** is in the millions of traces/month
579	  — we are < 1% of the cap at this estimate. **Re-verify the cap
580	  on the Logfire dashboard before merging PR-4.**
581	
582	The risk vector that *would* push us over is M8's chat-agent loop
583	emitting many spans per chat turn — that's M8's problem, not
584	PR-4's. PR-3's spend tripwire stays as-is; PR-4's PR body commits
585	to a 7-day post-deploy span-count probe and posts a follow-up
586	comment with the actual number.
587	
588	### Image-size delta
589	
590	`authlib` ~600 KB installed (pure-Python). `slowapi` ~50 KB.
591	`SecretStr` already in `pydantic`. **Total image-size delta < 2 MB**
592	on top of the current ~150 MB runtime image. Negligible.
593	Dockerfile change is one extra `--extra <name>` in the `uv sync`
594	lines (no new system packages, no `apt-get install` deltas).
595	
596	### Backup / restore
597	
598	Unchanged. Auth metadata (cookie signing secret, Google client
599	secret, allowlist) lives in environment variables and the
600	encrypted Kamal secret-bag, not on the `/data` volume; the SQLite
601	DB on `/data/monarch.db` carries no auth state under Option B (no
602	`user` table, no `password_hash`). The existing "Hetzner Backups
603	covers OS only; volume backup TBD in go/no-go PR" posture in
604	`docs/deploy.md` is not affected.
605	
606	### Net monthly $ delta vs ADR-0008
607	
608	**$0/mo.** Option B requires no new infra (no additional VM, no
609	Tailscale tier — we never deployed Tailscale, so there's nothing
610	to delete from the bill — no Cloudflare add-on under the
611	recommendation above). The dropped *future* obligation of a
612	Tailscale paid plan once we exceeded 3 free users was never
613	incurred. Total platform cost remains ~$9.16/mo.
614	
615	## Failure modes
616	
617	- **Session hijacking via stolen cookie** (browser extension or
618	  laptop compromise). Mitigations: `HttpOnly` blocks
619	  `document.cookie` reads (no XSS exfil); `Secure` blocks
620	  plaintext-network sniff; 24 h `max_age` limits the window; the
621	  M7.6 WebAuthn follow-up reduces this to "stolen cookie alone is
622	  useless without the second factor". **Residual risk accepted at
623	  PR-4:** a compromised laptop yields up to 24 h of unauthenticated
624	  access. The `AUTH_COOKIE_SECRET` rotation kill-switch is the in-
625	  incident response.
626	- **Google OAuth provider downtime.** Existing sessions:
627	  unaffected (we don't call Google on every request — only at
628	  login). New logins: blocked until Google recovers. The 24 h
629	  session lifetime means most household users have a fresh-enough
630	  cookie to ride out a typical multi-hour Google outage.
631	  **Residual risk accepted:** during a Google outage longer than
632	  24 h, no one can log in. This is the cost of the IdP dependency
633	  we explicitly waived constraint 2 for.
634	- **OAuth scope creep.** Bound by the principle stated in the OAuth
635	  flow section (`openid email profile`, no app data scopes). Any
636	  future scope addition requires an ADR addendum. Code-reviewer
637	  gate on `monarch_cfo/api/auth.py` should treat scope-list edits
638	  as security-sensitive diffs.
639	- **Account takeover via email reuse / Google account compromise.**
640	  The `sub` allowlist is the answer for the email-reuse case (a
641	  recycled email at the same Google domain gets a NEW `sub` and
642	  is rejected). For a fully compromised Google account whose `sub`
643	  is allowlisted, IdP-side WebAuthn (Google Advanced Protection)
644	  is the load-bearing defence — **PR-4's go/no-go prerequisite**.
645	  M7.6 app-side WebAuthn becomes the second layer.
646	- **External revocation of our Google grant.** If the user clicks
647	  "Remove access" in Google account settings, their existing
648	  cookie keeps working for up to 24 h (we don't poll Google).
649	  Their next login attempt hits Google's consent screen. **Residual
650	  risk accepted:** there's no mechanism to push-revoke from Google
651	  to us short of subscribing to Google's RISC events (Risk and
652	  Incident Sharing and Coordination protocol), which is an
653	  enterprise feature out of scope for household-scale.
654	- **`sub` allowlist drift / stale entries.** If a household member
655	  changes their Google account (rare), the old `sub` stays in the
656	  allowlist forever. The runbook calls for an annual review.
657	  Low-priority residual risk.
658	- **OAuth state replay across tabs.** `authlib` stores `state` in
659	  the session; if the user opens two tabs and starts two logins,
660	  the second clobbers the first. Acceptable — they complete
661	  whichever flow finishes first.
662	- **Open-redirect via `?next=` query on `/auth/login`.** The
663	  middleware MUST validate `next` is a same-origin relative path
664	  (starts with `/`, no `//` prefix, no scheme). PR-4 has a unit
665	  test for this.
666	
667	## Rollout
668	
669	### How PR-4 lands on top of the 503 bootstrap gate
670	
671	1. Branch from `main` (per AGENTS.md "every PR off main, no stacking").
672	2. Add `authlib` and `slowapi` to `pyproject.toml`. Lock with
673	   `uv sync`. Confirm image delta < 5 MB.
674	3. Implement `src/monarch_cfo/api/auth.py` (`OAuthAuthMiddleware`,
675	   OAuth client factory, ID-token verification helper, `sub`
676	   allowlist check, `slowapi` limiter setup).
677	4. Implement `src/monarch_cfo/api/routers/auth.py` (the four
678	   routes above, all `include_in_schema=False`).
679	5. Extend `ApiSettings` with the five new env vars and the
680	   extended `_check_auth_secrets` validator.
681	6. Wire middleware in `app.py:120` in the documented order
682	   (BootstrapGate503Middleware registered first, then
683	   SessionMiddleware, then OAuthAuthMiddleware last — see
684	   §Interaction with existing code for why this is the order).
685	   The existing `active=` predicate already handles the
686	   `(auth_enabled=true, auth_bootstrap_503=false)` cell correctly;
687	   no change to it is required.
688	7. Add Jinja templates under `web/templates/auth/`
689	   (`logged_out.html`, `forbidden.html` for the 403 from a non-
690	   allowlisted account).
691	8. Tests:
692	   - Integration test that boots the app with a stub OIDC
693	     provider (mock returning canned ID tokens), exercises
694	     `/auth/login → /auth/callback → /transactions`.
695	   - `state` mismatch case (CSRF defence).
696	   - Unallowlisted `sub` returning 403.
697	   - 503 gate wins over auth middleware (registration-order
698	     verification).
699	   - Boot-time validator failure for each missing-secret case.
700	   - Open-redirect case: `?next=//evil.com` must not redirect.
701	   - **Existing test suite passes with zero changes** — confirms
702	     `AUTH_ENABLED=false` is honoured everywhere.
703	9. New `docs/auth.md` runbook (sister to `docs/deploy.md`).
704	10. Update `config/deploy.yml` `env:` block (clear + secret) per
705	    §Operational posture. **Add** the new entries; do NOT change
706	    `AUTH_ENABLED` or `AUTH_BOOTSTRAP_503` from their current
707	    PR-1 values (`"false"` / `"true"` respectively). The flip is
708	    the go/no-go PR's job per §Cutover; PR-4's deployed behaviour
709	    is identical to PR-3's (still 503-gated). This is what allows
710	    PR-4 to merge without tripping the AGENTS.md synthetic-data
711	    fence.
712	11. Update `.kamal/secrets.example` with `GOOGLE_OAUTH_CLIENT_SECRET`
713	    and `AUTH_COOKIE_SECRET`.
714	12. Update `docs/deploy.md`:
715	    - "What's NOT on auto-pilot" mentions Google OAuth client-secret
716	      rotation.
717	    - "Pre-swap verification" checklist drops "Tailscale edge
718	      confirmed blocking non-enrolled clients" and adds the smoke
719	      checks below.
720	    - Day-2 workflow table gains a "Disable auth in emergency" row
721	      pointing at the kill-switch recipe.
722	13. **PR scope:** auth code + tests + ADR + runbook + deploy.yml /
723	    secrets.example only. The actual flip of `AUTH_ENABLED=true` on
724	    the deployed VM happens in **the post-PR-4 go/no-go PR** (per
725	    AGENTS.md §"Standing scope fences" item 1 on synthetic data).
726	
727	### Pre-flight: secret installation
728	
729	Before pushing the deploy tag, with secrets already present in GHA:
730	
731	```sh
732	gh secret set GOOGLE_OAUTH_CLIENT_ID --body "<value>" --repo melon-lab-com/melon-monarch-cfo
733	gh secret set GOOGLE_OAUTH_CLIENT_SECRET --body "<value>" --repo melon-lab-com/melon-monarch-cfo
734	NEW_SECRET=$(openssl rand -hex 32)
735	gh secret set AUTH_COOKIE_SECRET --body "$NEW_SECRET" --repo melon-lab-com/melon-monarch-cfo
736	unset NEW_SECRET
737	gh secret list --repo melon-lab-com/melon-monarch-cfo | grep -E 'GOOGLE_OAUTH|AUTH_COOKIE'
738	```
739	
740	Verify with a local `kamal env push` smoke against the current
741	`config/deploy.yml`. It will fail with a clear "secret not found in
742	`.kamal/secrets`" error if any of the three weren't set; that's the
743	desired smoke. Don't `kamal app boot` after the failure — just
744	confirm and fix.
745	
746	### Cutover: env-var flip sequence (executed by the go/no-go PR, NOT PR-4)
747	
748	**The env-var flip lives in the post-PR-4 go/no-go PR**, not in PR-4
749	itself. PR-4 ships the auth code, the validator, the new env-var
750	schema in `ApiSettings`, and the new `env:` entries in
751	`config/deploy.yml` — but keeps `AUTH_ENABLED: "false"` and
752	`AUTH_BOOTSTRAP_503: "true"` so the deployed behaviour after PR-4
753	merges is unchanged from PR-3 (still 503-gated). This separation is
754	required by AGENTS.md §"Standing scope fences" item 1 (synthetic-
755	data fence stays in force until the go/no-go PR completes its
756	checklist; the auth flip is part of that PR, not PR-4).
757	
758	The go/no-go PR's deploy.yml diff is small: flip
759	`AUTH_ENABLED: "false"` → `"true"` and `AUTH_BOOTSTRAP_503: "true"`
760	→ `"false"` in `env: clear`. **Single-deploy cutover (chosen, ~30 s
761	downtime).** Operator pushes a deploy tag
762	(`git tag v$(date +%Y-%m-%d) && git push origin v$(date +%Y-%m-%d)`)
763	after the go/no-go PR merges. The new container starts with
764	`AUTH_ENABLED=true`; the boot-time validator chain runs; if any
765	secret is malformed, the container exits non-zero, kamal-proxy
766	fails the healthcheck (Kamal 2 fails an unhealthy deploy and keeps
767	the prior container in the proxy pool — no traffic to the bad
768	container, no auto-rollback to a different image; PR-4 verifies
769	this behaviour as part of its checklist). The household is never
770	exposed to a half-configured auth.
771	
772	**Two-deploy cutover** (flip `AUTH_BOOTSTRAP_503=false` first, then
773	`AUTH_ENABLED=true`) was rejected: the intermediate state would be
774	"every route open" — under no scenario acceptable.
775	
776	### Validation steps before real data is allowed (the post-PR-4 go/no-go PR's checklist)
777	
778	The post-PR-4 go/no-go PR owns the actual real-data swap. Its
779	acceptance criteria:
780	
781	1. PR-4 merged, `code-reviewer` verdict APPROVED + SHA-anchored.
782	2. `cloud-ops-specialist` review APPROVED on `config/deploy.yml`
783	   env block, secret flow, and runbook updates.
784	3. **Operator-confirmed prerequisites** (recorded in the go/no-go
785	   PR description as checklist items):
786	   - Each allowlisted Google account has at least one phishing-
787	     resistant second factor enabled at Google (passkey, security
788	     key, or Google Advanced Protection enrolment).
789	   - DNS A-record for `monarch.melon-lab.com` resolves to the
790	     Hetzner CPX11.
791	   - Google OAuth client created in Google Cloud Console with the
792	     production redirect URI (`https://monarch.melon-lab.com/auth/callback`)
793	     registered.
794	   - All required secrets (`GOOGLE_OAUTH_CLIENT_ID`,
795	     `GOOGLE_OAUTH_CLIENT_SECRET`, `AUTH_COOKIE_SECRET`) present in
796	     GHA repo secrets.
797	4. **End-to-end smoke** on the deployed staging URL (with
798	   synthetic data still loaded):
799	
800	   ```sh
801	   # Liveness — must return 200; auth doesn't gate /healthz.
802	   curl -fsS https://monarch.melon-lab.com/healthz
803	   # Unauthenticated access must redirect (HTMX) or 401 (JSON);
804	   # NEVER 200, NEVER 503.
805	   curl -i -s -o /dev/null -w '%{http_code}\n' https://monarch.melon-lab.com/transactions
806	   # Auth-initiate must redirect to accounts.google.com.
807	   curl -i -s -o /dev/null -w '%{http_code} %{redirect_url}\n' \
808	     https://monarch.melon-lab.com/auth/login
809	   # Real browser login: open https://monarch.melon-lab.com, click
810	   # sign-in, complete Google flow, land back on the UI.
811	   # Rate-limit smoke: 6 rapid `/auth/login` from one IP — 6th returns 429.
812	   ```
813	
814	5. Each allowlisted user logs in, sees the UI, logs out. A non-
815	   allowlisted Google account is tested and confirmed to hit the
816	   403 page.
817	6. **Logfire traces verified:** login, logout, and rejected-
818	   allowlist events all appear in Logfire (PR-3 observability) with
819	   the expected attributes (sub redacted to last 4 chars, email
820	   full, IP, user-agent).
821	7. **Kill-switch tested:** flip `AUTH_BOOTSTRAP_503=true` +
822	   `AUTH_ENABLED=false`, `kamal env push && kamal app boot`,
823	   confirm every route 503s within 30 s. Flip back, confirm normal
824	   operation resumes.
825	8. **Only then:** manually `scp` the real Monarch CSV export to the
826	   volume, run `monarch-ingest`, confirm the data loads, and
827	   remove the synthetic-data seed path from the entrypoint per
828	   AGENTS.md §"Standing scope fences" item 1.
829	
830	### Kill switches
831	
832	Three independent kill paths, ordered by speed:
833	
834	1. **Fastest (~30 s) — the 503 bootstrap gate.** Local edit to
835	   `config/deploy.yml`'s `env: clear`: `AUTH_ENABLED: "false"`,
836	   `AUTH_BOOTSTRAP_503: "true"`. Then `kamal env push` (writes the
837	   new env to the box) and `kamal app boot` (restarts the
838	   container with the new env). Verify with `curl -i .../`
839	   returning 503 and `curl .../healthz` returning 200. The "we
840	   think we're under attack right now" button. **After the dust
841	   settles, open a hotfix PR that commits the deploy.yml change**
842	   (the local edit only survives until the next deploy tag); link
843	   an `Incident: <description>` issue per AGENTS.md §"Incident
844	   retro".
845	2. **Cookie-secret rotation (~30 s, but logs everyone out).**
846	   `gh secret set AUTH_COOKIE_SECRET` with a fresh `openssl rand
847	   -hex 32`, then `git tag` + `git push origin <tag>` to fire the
848	   GHA deploy. All existing sessions invalidate; legitimate users
849	   re-log-in via Google. The "stolen-laptop cookie" response.
850	3. **Google client revocation (~minutes, requires browser).**
851	   Disable or rotate the OAuth client in Google Cloud Console.
852	   New logins fail; existing 24 h cookies still work until expiry
853	   (combine with #2 for total cutoff). The "Google client itself
854	   was leaked" response.
855	
856	The first two are agent-operable. The third requires a browser
857	touch and is documented as such in the runbook (matches ADR-0006's
858	acceptance of one-time browser touches for IdP setup).
859	
860	## Consequences
861	
862	**Positive**
863	
864	- One vendor in the household (Google), not two (Tailscale +
865	  Google). The user already has hardware-key-protected Google
866	  accounts; PR-4 leverages that hardening.
867	- Zero device-policy friction. Logging in from a borrowed laptop
868	  or a freshly reinstalled phone "just works" via Google sign-in.
869	- Boot-time validators on auth secrets make a misconfigured deploy
870	  exit non-zero before serving traffic — kamal-proxy keeps the
871	  prior good container serving and the bad container never
872	  becomes a proxy target. The misconfigured-deploy case is
873	  impossible-at-boot rather than "open transactions endpoint on
874	  the public internet".
875	- 503 bootstrap gate is preserved as a permanent kill-switch, not
876	  just a first-boot state. Cheap to flip.
877	- Net monthly cost: $0 delta. No new infra.
878	- Local dev unchanged.
879	- Smaller code surface in cfo (no `user` table, no `password_hash`,
880	  no bcrypt dependency, no rate-limited password-login form).
881	
882	**Negative**
883	
884	- **Constraint 2 of ADR-0008 is waived.** Google IS in the
885	  identity path. We accept that Google learns login times and the
886	  redirect target hostname (it does not learn financial data —
887	  the app does not call Google with that data and Google is not in
888	  the per-request data path).
889	- **Constraint 5 of ADR-0008 is materially weakened.** The two-
890	  vendor-gate property is gone; we replaced it with single-vendor
891	  app-layer defences (allowlist + boot-time validators + rate
892	  limits + 503 kill-switch). A single auth-middleware bug now has
893	  larger blast radius than ADR-0008 originally accepted.
894	- 24 h session lifetime is shorter than ADR-0008's 30 d rolling —
895	  one Google re-click per day is a small UX cost.
896	- No mechanism to push-revoke from Google to us when a user
897	  removes the app's permission externally; the cookie keeps
898	  working until 24 h expiry.
899	- DDoS / abuse exposure widens from "tailnet-only" to "open
900	  internet". Realistic threat model for household-scale finance
901	  data is "passive scanners and curiosity", which the slowapi
902	  limiter handles; targeted L7 attacks would overwhelm the CPX11
903	  regardless. Cloudflare-proxy is the documented follow-up if
904	  noise becomes operationally noisy.
905	- Google client-secret rotation requires a one-time browser touch
906	  in Google Cloud Console (matches ADR-0006's accepted pattern
907	  for IdP setup steps).
908	
909	## Follow-ups (deferred)
910	
911	- **M7.6: WebAuthn second factor at the app layer.** Adds a
912	  `webauthn_credentials` table, registration + authentication
913	  ceremonies, flag-gated by `AUTH_REQUIRE_WEBAUTHN`. Reduces the
914	  "stolen Google session cookie" blast radius. File the issue
915	  alongside PR-4's follow-up.
916	- **Cloudflare-proxy in front of `monarch.melon-lab.com`** if
917	  scanner traffic materially affects Logfire spend or kamal-proxy
918	  log volume. Trade: reintroduces a vendor in the network path.
919	- **RISC (Google Risk and Incident Sharing) subscription** if we
920	  ever decide push-revocation matters more than the enterprise
921	  setup cost.
922	- **Periodic allowlist review** added to the milestone close-out
923	  checklist (annual cadence).
924	
925	## Interaction with existing code
926	
927	- `src/monarch_cfo/api/middleware.py` keeps the existing
928	  `BootstrapGate503Middleware` unchanged. PR-4 adds an
929	  `OAuthAuthMiddleware` class to the same module per the file
930	  header's existing intent ("Cookie-session auth middleware lands
931	  in M7.5 PR-4 and will live alongside it in this module" —
932	  middleware.py:5).
933	- `src/monarch_cfo/api/settings.py` extends `_check_auth_state`
934	  (currently rejecting only the illegal cell) into the broader
935	  `_check_auth_secrets` model_validator described above.
936	- `src/monarch_cfo/api/app.py:120` adds two `add_middleware`
937	  calls (SessionMiddleware, then OAuthAuthMiddleware) **after**
938	  the existing `BootstrapGate503Middleware` registration. Starlette
939	  builds the middleware stack by reversing the registration list,
940	  so the **first-registered** middleware is **outermost** (runs
941	  first on the request) and the **last-registered** is
942	  **innermost** (runs last, closest to the route). The required
943	  registration order to match §FastAPI plug points is therefore:
944	  `BootstrapGate503Middleware` (registered first, outermost) →
945	  `SessionMiddleware` (registered second) → `OAuthAuthMiddleware`
946	  (registered last, innermost). PR-4 keeps the existing
947	  `BootstrapGate503Middleware` registration in place and appends
948	  the two new `add_middleware` calls below it; do NOT insert them
949	  above it. The existing `active=` predicate
950	  (`settings.auth_bootstrap_503 and not settings.auth_enabled`) is
951	  already correct for the `(true, false)` cell (gate inert when
952	  real auth is on) — no change to the predicate itself is
953	  required.
954	- `src/monarch_cfo/api/routers/` gains an `auth.py` for the four
955	  new routes; `include_in_schema=False` matches the `web/`
956	  routes' convention.
957	- `web/templates/` gains an `auth/` directory for `logged_out.html`
958	  and `forbidden.html`.
959	- `pyproject.toml` adds `authlib` and `slowapi`. `uv.lock` updates
960	  in the same commit.
961	- `Dockerfile` line 110 (`--forwarded-allow-ips=...`) is now
962	  load-bearing for abuse mitigation in addition to its original
963	  ADR-0008 PR-1 purpose. PR-4 does not change the line; the ADR
964	  flags it so a future deploy-config refactor doesn't inadvertently
965	  remove it.
966	- `config/deploy.yml` `env: clear` and `env: secret` blocks gain
967	  the entries listed in §Operational posture.
968	- `.kamal/secrets.example` updated with the two new secret entries.
969	- `docs/deploy.md` updated with Day-2 emergency-disable recipe and
970	  the revised pre-swap verification checklist.
971	- New `docs/auth.md` runbook documenting the OAuth client setup,
972	  allowlist mutation, secret rotation, and kill-switch flows.
973	

1	"""HTTP middleware for `monarch_cfo.api`.
2	
3	Currently ships only the 503 bootstrap gate (ADR-0006 PR-1, ADR-0008
4	three-state model). Cookie-session auth middleware lands in M7.5 PR-4
5	and will live alongside it in this module.
6	"""
7	
8	from __future__ import annotations
9	
10	from collections.abc import Awaitable, Callable
11	
12	from starlette.middleware.base import BaseHTTPMiddleware
13	from starlette.requests import Request
14	from starlette.responses import JSONResponse, Response
15	from starlette.types import ASGIApp
16	
17	# Paths that must keep responding even when the 503 bootstrap gate is
18	# active. `/healthz` is the Kamal + external uptime probe; closing it
19	# would make the deploy permanently "unhealthy" and block tag-triggered
20	# rollouts. No other path belongs here — in particular, `/openapi.json`
21	# and the Swagger / ReDoc UIs stay gated, because leaking the schema of
22	# every endpoint to an unauthenticated caller is data disclosure in
23	# spirit even when the endpoints themselves 503.
24	_BOOTSTRAP_503_ALLOWLIST: frozenset[str] = frozenset({"/healthz"})
25	
26	
27	class BootstrapGate503Middleware(BaseHTTPMiddleware):
28	    """Short-circuit every non-allowlisted request to 503.
29	
30	    Active only when ``AUTH_BOOTSTRAP_503=true`` AND ``AUTH_ENABLED=false``
31	    (the "first cloud boot" cell of the ADR-0008 three-state table).
32	    The request never reaches the router; the response body advertises
33	    the state so an operator probing with ``curl`` sees *why* they got
34	    503 rather than a generic error page.
35	
36	    The gate is registered unconditionally at app build time; the
37	    per-request fast path lets it stay inert when auth is off and
38	    bootstrap is off (local dev) or when real auth is live (production
39	    after PR-4).
40	    """
41	
42	    def __init__(self, app: ASGIApp, *, active: bool) -> None:
43	        super().__init__(app)
44	        self._active = active
45	
46	    async def dispatch(
47	        self,
48	        request: Request,
49	        call_next: Callable[[Request], Awaitable[Response]],
50	    ) -> Response:
51	        if not self._active or request.url.path in _BOOTSTRAP_503_ALLOWLIST:
52	            return await call_next(request)
53	        return JSONResponse(
54	            status_code=503,
55	            content={
56	                "detail": (
57	                    "Service unavailable: bootstrap gate active "
58	                    "(AUTH_BOOTSTRAP_503=true). Real auth has not yet "
59	                    "been configured; only /healthz responds. See "
60	                    "ADR-0008."
61	                )
62	            },
63	            headers={"Retry-After": "3600"},
64	        )
65	

1	"""API settings — env-driven configuration for `monarch_cfo.api`.
2	
3	DB URL falls through to `monarch_ingest.db.get_db_url()` so API and
4	ingest CLI resolve the same `MONARCH_DB_URL` without duplicating the
5	chain.
6	
7	Auth gate (ADR-0008) exposes `AUTH_ENABLED` + `AUTH_BOOTSTRAP_503`
8	unprefixed at the deployment boundary (matches Kamal `env:` blocks
9	and `docs/deploy.md`), while other fields keep the `MONARCH_API_`
10	prefix.
11	"""
12	
13	from __future__ import annotations
14	
15	from pydantic import AliasChoices, Field, model_validator
16	from pydantic_settings import BaseSettings, SettingsConfigDict
17	
18	
19	class ApiSettings(BaseSettings):
20	    """Settings backed by env vars prefixed `MONARCH_API_`."""
21	
22	    model_config = SettingsConfigDict(
23	        env_prefix="MONARCH_API_",
24	        env_file=None,
25	        extra="ignore",
26	        # Load-bearing for the auth-gate fields below: without this,
27	        # fields with `validation_alias=` can ONLY be populated via
28	        # the alias, and direct constructor calls like
29	        # `ApiSettings(auth_enabled=False, auth_bootstrap_503=True)`
30	        # would silently use the defaults. Tests — and any caller
31	        # passing settings to `create_app` — rely on the Python name.
32	        populate_by_name=True,
33	    )
34	
35	    title: str = "melon-monarch-cfo"
36	    version: str = "0.1.0"
37	
38	    # ADR-0008 three-state auth gate. Exposed unprefixed at the env
39	    # boundary so `kamal env:` blocks can set `AUTH_ENABLED=false` /
40	    # `AUTH_BOOTSTRAP_503=true` the same way `docs/deploy.md` describes.
41	    # Prefixed aliases are also accepted for symmetry with other fields.
42	    auth_enabled: bool = Field(
43	        default=False,
44	        validation_alias=AliasChoices("AUTH_ENABLED", "MONARCH_API_AUTH_ENABLED"),
45	    )
46	    auth_bootstrap_503: bool = Field(
47	        default=False,
48	        validation_alias=AliasChoices("AUTH_BOOTSTRAP_503", "MONARCH_API_AUTH_BOOTSTRAP_503"),
49	    )
50	
51	    @model_validator(mode="after")
52	    def _check_auth_state(self) -> ApiSettings:
53	        # ADR-0008 §Decision: the (enabled, bootstrap_503) state space
54	        # has three legal cells and one illegal one. Refuse to boot
55	        # rather than silently pick a winner between two conflicting
56	        # intents.
57	        if self.auth_enabled and self.auth_bootstrap_503:
58	            raise ValueError(
59	                "AUTH_ENABLED=true with AUTH_BOOTSTRAP_503=true is a "
60	                "config error (ADR-0008): either real auth is live "
61	                "(bootstrap off) or the 503 gate is live (auth off). "
62	                "Pick one."
63	            )
64	        return self
65	

1	"""FastAPI app factory.
2	
3	`create_app()` returns a configured `FastAPI` with all routers wired.
4	A module-level `app = create_app()` lets `uvicorn monarch_cfo.api.app:app`
5	boot the server without extra glue. The M7.5 auth gate (ADR-0006)
6	lands when the middleware itself ships.
7	"""
8	
9	from __future__ import annotations
10	
11	from fastapi import FastAPI
12	from fastapi.staticfiles import StaticFiles
13	
14	from monarch_cfo.api.middleware import BootstrapGate503Middleware
15	from monarch_cfo.api.routers import (
16	    accounts,
17	    balances,
18	    categories,
19	    chat,
20	    health,
21	    merchants,
22	    networth,
23	    reports,
24	    transactions,
25	)
26	from monarch_cfo.api.settings import ApiSettings
27	from monarch_cfo.web import routes as web_routes
28	from monarch_cfo.web.templating import STATIC_DIR
29	
30	_DESCRIPTION = """\
31	Read-only API over the `monarch_ingest` data model. All monetary
32	values are **signed integer cents** (divide by 100 for dollars).
33	
34	## Endpoints
35	
36	- `GET /healthz` — liveness probe (checks the DB).
37	- `GET /accounts` — list accounts.
38	- `GET /categories` — list categories.
39	- `GET /transactions` — paginated transactions with date-range +
40	  id filters.
41	- `GET /balances/timeseries` — per-account daily balance series.
42	- `GET /net-worth/timeseries` — daily total with book-value split.
43	- `GET /merchants/top` — top-N merchants by spend in a year.
44	- `GET /reports/annual/{year}` — CFO annual report (net worth, cash
45	  flow, categories, merchants, per-owner split, subscriptions, rental).
46	- `GET /reports/annual/{year}/compare/{prior}` — YoY delta (absolute
47	  + percent) between two annual reports.
48	- `GET /reports/rental/{year}` — rental P&L breakout.
49	- `GET /reports/subscriptions/{year}` — detected recurring subscriptions.
50	- `GET /reports/owners/{year}` — per-owner household split.
51	
52	## AI Analyst
53	
54	- `POST /chat/once` — non-streaming one-shot AI query.
55	- `POST /chat/stream` — SSE streaming AI query.
56	
57	## Web UI
58	
59	Server-rendered Jinja pages under `/ui/`. Not included in the OpenAPI
60	schema (read-only human surface over the same data; M6 plan §9).
61	
62	Auth lands in M7.5 (ADR-0006); this build binds to localhost.
63	""".strip()
64	
65	_TAGS_METADATA = [
66	    {
67	        "name": "health",
68	        "description": "Liveness / readiness. Never auth-gated.",
69	    },
70	    {
71	        "name": "accounts",
72	        "description": "Household accounts (full list, no pagination).",
73	    },
74	    {
75	        "name": "categories",
76	        "description": "Categories (flat list; client reconstructs tree).",
77	    },
78	    {
79	        "name": "transactions",
80	        "description": "Transaction search with pagination and filters.",
81	    },
82	    {
83	        "name": "balances",
84	        "description": "Per-account daily balance series.",
85	    },
86	    {
87	        "name": "net-worth",
88	        "description": "Aggregate net-worth series with book-value split.",
89	    },
90	    {
91	        "name": "merchants",
92	        "description": "Merchant aggregations (top-N by spend).",
93	    },
94	    {
95	        "name": "reports",
96	        "description": "CFO reports (annual summary, YoY compare).",
97	    },
98	    {
99	        "name": "chat",
100	        "description": "AI analyst chat (one-shot and SSE streaming).",
101	    },
102	]
103	
104	
105	def create_app(settings: ApiSettings | None = None) -> FastAPI:
106	    """Build the API. Accepts an injected settings instance for tests."""
107	    from monarch_cfo.ai.telemetry import configure as _configure_telemetry
108	
109	    _configure_telemetry()
110	    settings = settings or ApiSettings()
111	    api = FastAPI(
112	        title=settings.title,
113	        version=settings.version,
114	        description=_DESCRIPTION,
115	        openapi_tags=_TAGS_METADATA,
116	        contact={"name": "melon-lab-com", "url": "https://github.com/melon-lab-com"},
117	    )
118	    # ADR-0008 three-state auth gate. PR-1 ships only the 503 bootstrap
119	    # cell; cookie-session auth middleware joins this stack in PR-4.
120	    api.add_middleware(
121	        BootstrapGate503Middleware,
122	        active=settings.auth_bootstrap_503 and not settings.auth_enabled,
123	    )
124	    api.include_router(health.router)
125	    api.include_router(accounts.router)
126	    api.include_router(categories.router)
127	    api.include_router(transactions.router)
128	    api.include_router(balances.router)
129	    api.include_router(networth.router)
130	    api.include_router(merchants.router)
131	    api.include_router(reports.router)
132	    api.include_router(chat.router)
133	    api.include_router(web_routes.router)
134	    api.mount("/ui/static", StaticFiles(directory=str(STATIC_DIR)), name="ui-static")
135	    return api
136	
137	
138	app = create_app()
139	

1	# Kamal 2 deployment config for melon-monarch-cfo.
2	#
3	# PR-1 scope: every field the deploy pipeline references is set; the
4	# fields that depend on "the VM is up and DNS points at it" carry
5	# explicit TODO markers so a caller can't deploy this file against a
6	# placeholder host by mistake. PR-2 fills in the volume + CI deploy
7	# workflow; PR-4 swaps the 503 gate for real auth env.
8	#
9	# See:
10	#   docs/deploy.md                                    — operator runbook
11	#   docs/decisions/0006-cloud-deployment-target.md    — host + backup posture
12	#   docs/decisions/0008-auth-strategy.md              — three-state auth env
13	
14	service: monarch-cfo
15	
16	# GHCR image. Tag is supplied by the deploy workflow (either
17	# `<short-sha>` for a tag-driven release or `latest` for a manual
18	# promote). Kamal appends its own version tag on every deploy so
19	# `kamal rollback` has an anchor.
20	image: melon-lab-com/monarch-cfo
21	
22	# Kamal 2 defaults left unspecified (all load-bearing on a rollout):
23	#   deploy_timeout: 30      # seconds to wait for new containers to be healthy
24	#   drain_timeout: 30       # seconds to let old containers finish in-flight reqs
25	#   retain_containers: 5    # rollback depth
26	#   readiness_delay: 7      # grace period after healthcheck before cutover
27	# Bump these if the CPX11 proves too slow at container start; default is
28	# fine for a FastAPI + SQLite boot (~3 s cold).
29	
30	registry:
31	  server: ghcr.io
32	  # Parameterised via Kamal secret so PR-2's GHA deploy workflow can
33	  # pass the personal GitHub handle that owns the PAT without a config
34	  # edit. Org slug `melon-lab-com` is NOT valid here for GHCR — the
35	  # registry expects the PAT's owning account. Populated in
36	  # `.kamal/secrets` alongside the matching PAT.
37	  username:
38	    - KAMAL_REGISTRY_USERNAME
39	  password:
40	    - KAMAL_REGISTRY_PASSWORD
41	
42	# The CPX11 VM is amd64 (AMD shared vCPU); building multi-arch is
43	# wasted cost for a single-host deploy. The deploy workflow sets
44	# `platforms: linux/amd64` on `docker buildx` accordingly.
45	builder:
46	  arch: amd64
47	
48	# Single-host web role. Hetzner CPX11 at Hillsboro (US-OR), provisioned
49	# 2026-04-21 via `scripts/provision.sh`. If this host changes (e.g. on
50	# a rebuild from backup), update both this IPv4 AND the KAMAL_HOSTS
51	# GHA secret (or leave that secret empty and let the workflow parse
52	# this file).
53	servers:
54	  web:
55	    hosts:
56	      - 5.78.192.165
57	
58	ssh:
59	  # cloud-init (PR-2) provisions the non-root `deploy` user; Kamal SSHes
60	  # in as that user. No direct root SSH.
61	  user: deploy
62	
63	# kamal-proxy terminates TLS with Let's Encrypt and load-balances into
64	# the app container on port 3000. One proxy, N apps — adding a second
65	# household app on the same host only needs a new `proxy.host` entry in
66	# that app's own deploy.yml.
67	proxy:
68	  ssl: true
69	  # Squarespace-managed A-record monarch.melon-lab.com → 5.78.192.165
70	  # (added 2026-04-21). kamal-proxy terminates TLS with Let's Encrypt
71	  # on first deploy.
72	  host: monarch.melon-lab.com
73	  app_port: 3000
74	  # This healthcheck is what kamal-proxy polls before routing traffic
75	  # to a freshly-rolled-out container. Integer seconds per the Kamal 2
76	  # proxy schema (NOT "10s"/"5s" strings — those fail type validation).
77	  # Kamal's own orchestrator-level readiness is controlled by
78	  # top-level `readiness_delay:` + `deploy_timeout:` above, not by a
79	  # separate top-level `healthcheck:` block (which was removed in the
80	  # Kamal 1 → 2 migration and will fail `kamal config` validation).
81	  healthcheck:
82	    path: /healthz
83	    interval: 10
84	    timeout: 5
85	
86	# Clear env is baked into the image layer; Kamal merges `secret:` on
87	# top at deploy time from `.kamal/secrets`. PR-1 only needs unprefixed
88	# AUTH_* and the DB URL — chat-provider keys + SESSION_SECRET join in
89	# PR-3/PR-4.
90	env:
91	  clear:
92	    # ADR-0008 three-state auth gate. This `(false, true)` cell is the
93	    # "first cloud boot" row: every route 503s except /healthz. Flip to
94	    # `AUTH_ENABLED=true, AUTH_BOOTSTRAP_503=false` in PR-4 after the
95	    # cookie middleware lands AND the go/no-go PR ticks every box in
96	    # docs/deploy.md §"Pre-swap verification".
97	    AUTH_ENABLED: "false"
98	    AUTH_BOOTSTRAP_503: "true"
99	    # SQLite on the persistent /data volume. Host `/data` is a symlink
100	    # maintained by `cloud-init/user-data.yml::monarch-data-link` that
101	    # points at whichever `/mnt/HC_Volume_<id>` Hetzner auto-mounts for
102	    # the attached 10 GB volume. The symlink is stable across reboots
103	    # and container restarts.
104	    MONARCH_DB_URL: "sqlite:////data/monarch.db"
105	  secret:
106	    # Kamal resolves these names from `.kamal/secrets`, which itself
107	    # reads them from the deployer's env. The GHA deploy workflow
108	    # (PR-2) exports them via `::add-mask::`-guarded `echo` from the
109	    # matching GitHub Actions Secret.
110	    - KAMAL_REGISTRY_PASSWORD
111	    # Logfire write token (project-scoped). telemetry.configure() is
112	    # a no-op when this is unset or the `logfire` extra is missing;
113	    # PR-3 installs the extra in the image and feeds the token here
114	    # so the production deploy emits spans to the Logfire cloud.
115	    # Rotation: `gh secret set LOGFIRE_TOKEN` + push a fresh deploy
116	    # tag; Kamal re-reads secrets on each deploy.
117	    - LOGFIRE_TOKEN
118	
119	# Bind-mount the host `/data` symlink (pointing at the Hetzner auto-
120	# mounted volume) into the container at the same path. The Dockerfile
121	# creates /data inside the container as uid 10001; cloud-init chowns
122	# the host volume to 10001:10001 on boot (`monarch-data-link.service`);
123	# they line up so uvicorn can write `/data/monarch.db` without a
124	# permission crash.
125	#
126	# Using `/data:/data` (rather than a named Docker volume) because:
127	# 1. The host-side volume can be detached from this VM and re-attached
128	#    to a replacement without an export/import step. Hetzner Volumes
129	#    persist across server rebuilds by design.
130	# 2. Any volume-backup mechanism we add (e.g. a `sqlite3 .backup` cron
131	#    on the host dumping into /var/backups) operates on the host path
132	#    directly, which is easier to reason about than a Docker-managed
133	#    volume.
134	#
135	# NOTE — backup coverage: Hetzner Cloud Server Backups do NOT include
136	# attached Volumes (per Hetzner's Backups/Snapshots docs). `/data`
137	# therefore has no managed backup in PR-2/PR-3. See
138	# docs/deploy.md §"Volume backup gap" and the 2026-04-21 addendum to
139	# ADR-0006 for the synthetic-phase acceptance and the hard blocker
140	# this places on the post-PR-4 go/no-go PR.
141	volumes:
142	  - "/data:/data"
143	
144	# Migrations run from the Dockerfile entrypoint before `uvicorn`, so
145	# Kamal doesn't need a separate pre-deploy hook. A future hook block
146	# would live here if we ever needed one.
147	

1	# Cloud deployment — setup guide
2	
3	> Pre-implementation guide for bringing up `melon-monarch-cfo` on
4	> Hetzner + Kamal 2 per [ADR-0006](decisions/0006-cloud-deployment-target.md).
5	> Read this before kicking off M7.5. Commands are verified against
6	> documentation; live-verified commands land progressively with
7	> PR-1..PR-4 of the M7.5 milestone.
8	
9	## What you're paying for
10	
11	Live-verified against the Hetzner API on 2026-04-21. CX-class isn't
12	offered in Hillsboro (US-OR); the closest US-region match to the
13	original CX22 target is CPX11 (see ADR-0006 §"Addendum — CX22 → CPX11"
14	for the full substitution rationale + resize path).
15	
16	| Item | Monthly (USD gross) | Notes |
17	|---|---|---|
18	| Hetzner CPX11 (Hillsboro) | $6.99 | 2 AMD shared vCPU, 2 GB RAM, 40 GB NVMe |
19	| Hetzner Volume 10 GB | $0.77 | SQLite DB + Alembic state at `/data`; $0.077/GB/mo |
20	| Hetzner Backups | $1.40 | 20% of CPX11; daily snapshots, 7-day retention |
21	| DNS (Squarespace, existing) | $0 | Manage A-record in Squarespace's DNS UI |
22	| GHCR (private image storage) | $0 | Included with `melon-lab-com` org |
23	| Domain | $0 | Reusing `melon-lab.com` (Squarespace-registered) |
24	| **Total platform cost** | **~$9.16/mo** | **~2.2 months runway on $20 credit** |
25	
26	Variable costs:
27	
28	- **Chat-provider API keys** (`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`,
29	  `OPENAI_API_KEY`) — depend on M8 usage. Keep ingest + report runs on
30	  manual triggers until the PR-3 spend-tracking cron lands cost data;
31	  revisit for cron later.
32	- **Hetzner traffic overage** — 20 TB/mo included. Not a concern.
33	- **Snapshot storage** — $0.0199/GB/mo if we take ad-hoc snapshots via
34	  `hcloud server create-image` (separate from the daily Backups).
35	
36	**Adding a second household app: $0 marginal.** Same VM, same volume
37	(different `/data/<app>` path), same `kamal-proxy` routing by hostname.
38	If we ever need more RAM / CPU: `hcloud server change-type monarch-cfo-1
39	cpx21` (3 vCPU / 4 GB / 80 GB / $13.99/mo) is a single reboot and the
40	volume + backups survive.
41	
42	## One-time setup (your part, ~15 min + Hetzner ID-verification wait)
43	
44	The agent team can't do these — they need a browser or a verified
45	identity. Do these before PR-1 opens.
46	
47	1. **Hetzner Cloud account.**
48	   - Sign up at `console.hetzner.cloud`; complete ID verification
49	     (can take minutes, occasionally hours for first-time accounts).
50	   - Add €20 credit.
51	   - Create a new project `melon-lab`.
52	   - Generate a Cloud API token (Read+Write) scoped to that project.
53	   - `scripts/provision.sh` creates the VM with `--enable-backup` at
54	     creation time — 20 % of server price, daily automatic, 7-day
55	     retention (~$1.40/mo for CPX11).
56	
57	2. **Squarespace DNS.** No new provider — use your existing
58	   Squarespace domain. After the VM is provisioned, log into
59	   Squarespace, open your domain's DNS settings, and add one `A`
60	   record: `monarch` → `<VM IP>`. ~2 minutes, one time. Squarespace
61	   is your registrar *and* DNS host; nothing about that needs to
62	   change.
63	
64	3. **Squarespace DNS — wait until the VM exists.** The agent's
65	   `scripts/provision.sh` prints the VM IPv4 at the end. Add the
66	   A-record then: Squarespace → Settings → Domains → `melon-lab.com` →
67	   DNS Settings → Custom Records → Add record: host `monarch`, data
68	   `<IP from provision.sh>`, TTL 1 hour. Verify with
69	   `dig +short monarch.melon-lab.com` from your laptop.
70	
71	4. **GitHub repo secrets.** `scripts/provision.sh` sets most of these
72	   for you via `gh secret set`; the only one you mint manually is
73	   `KAMAL_REGISTRY_PASSWORD`.
74	
75	   | Secret | Set by | Value |
76	   |---|---|---|
77	   | `HCLOUD_TOKEN` | provision.sh | the API token from step 1 |
78	   | `KAMAL_SSH_KEY` | provision.sh | ed25519 private key from `./.local/ssh/monarch-deploy` |
79	   | `KAMAL_REGISTRY_USERNAME` | provision.sh | defaults to `melon-claw` (override via `$KAMAL_REGISTRY_USERNAME` env var before running) |
80	   | `KAMAL_REGISTRY_PASSWORD` | **you** | a GHCR PAT with `read:packages` scope. `gh auth token` works if you want personal-tie auth; otherwise mint a fine-grained PAT. |
81	   | `SESSION_SECRET` | provision.sh | `openssl rand -hex 32` placeholder (PR-4 will rotate to a real one) |
82	   | `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `OPENAI_API_KEY` | **you** | when M8 deploys to the VM (not yet). Lazy-loaded by the chat adapters, so absence is fine until then. |
83	
84	   No 1Password integration: 1Password Family does not include service
85	   accounts, so the pipeline reads secrets directly from GHA. Personal
86	   1Password storage of the same tokens is fine and orthogonal.
87	
88	## Scripted setup (agent's part)
89	
90	PR-2 provides `scripts/provision.sh` that runs the one-time Hetzner
91	dance. Idempotent — safe to re-run after partial success. Resources
92	(SSH key, volume, server) are looked up by name before each create,
93	so a second invocation skips what already exists.
94	
95	```sh
96	./scripts/provision.sh
97	# prints the VM IPv4 when done; propagates secrets into GHA.
98	```
99	
100	What it does (full detail in the script's top-of-file comment):
101	
102	1. Mints an ed25519 keypair at `./.local/ssh/monarch-deploy` if absent,
103	   then registers the pubkey with Hetzner as `monarch-deploy`.
104	2. Renders `cloud-init/user-data.yml` with `SSH_PUBKEY` substituted,
105	   then creates:
106	   - A 10 GB ext4 volume (`monarch-data`) in Hillsboro (`hil`).
107	   - A CPX11 server (`monarch-cfo-1`) with `--enable-backup` from the
108	     outset (20 % surcharge, daily, 7-day retention).
109	   - Attaches the volume with `--automount` — Hetzner formats + mounts
110	     it at `/mnt/HC_Volume_<id>`; cloud-init symlinks that to `/data`
111	     and chowns to UID 10001 on first boot.
112	3. Cloud-init on the VM creates the `deploy` user (UID 10001, matches
113	   the Dockerfile's `app` user so `/data` perms line up), installs
114	   Docker CE, enables `ufw` default-deny + 22/80/443, `fail2ban`, and
115	   `unattended-upgrades` security-only.
116	4. Sets the GHA repo secrets — all but `KAMAL_REGISTRY_PASSWORD`, which
117	   you mint manually. Prints the IPv4 and the human-next-steps block.
118	
119	Human follow-up after the script finishes:
120	
121	1. **Add the Squarespace A-record** (see §One-time setup above).
122	2. **Verify DNS:** `dig +short monarch.melon-lab.com` returns the VM
123	   IPv4.
124	3. **Update `config/deploy.yml`** — replace the two TODO placeholders:
125	   - `servers.web.hosts: [<IP>]`
126	   - `proxy.host: monarch.melon-lab.com`
127	4. **Push a deploy tag:**
128	   ```sh
129	   git tag v$(date +%Y-%m-%d)
130	   git push origin v$(date +%Y-%m-%d)
131	   ```
132	   GHA builds the image, pushes to GHCR, runs `kamal deploy`. First
133	   deploy also runs `kamal setup` implicitly (installs the proxy on
134	   the host). Subsequent tag pushes are normal rollouts.
135	
136	After that:
137	
138	- **503 gate live:** `curl https://monarch.melon-lab.com/healthz`
139	  returns 200; `curl https://monarch.melon-lab.com/` returns 503 until
140	  PR-4 real auth replaces the gate and a separate go/no-go PR swaps
141	  the synthetic DB for real Monarch data.
142	
143	## Day-2 workflow
144	
145	Every operation is a CLI command. No dashboards.
146	
147	| Need to... | Command |
148	|---|---|
149	| Deploy latest `main` | `git tag v2026-MM-DD && git push origin v2026-MM-DD` (GHA runs `kamal deploy`) |
150	| Roll back to previous | `kamal rollback` from your local repo checkout |
151	| Roll back to specific | `kamal rollback <version-tag>` |
152	| List running containers | `kamal app containers` |
153	| Tail live logs | `kamal app logs -f` |
154	| Search logs | `kamal app logs --grep <pattern>` |
155	| Shell into container | `kamal app exec -i bash` |
156	| Rotate a secret | `gh secret set <NAME>` → push new deploy tag (or `kamal env push` locally, then `kamal app boot` to pick up) |
157	| Restore OS from backup | `hcloud server rebuild --image <backup-id> monarch-cfo-1` → `kamal app boot`. **Does NOT restore `/data`; the volume is separate.** See §Backup/restore runbook for the full coverage matrix. |
158	| Add a second household app | copy `config/deploy.yml` to new repo, edit `service` + `proxy.host`, run `kamal setup` once on the shared host, then normal `kamal deploy` |
159	| Check proxy / LE status | `kamal proxy logs` |
160	| Force LE renewal | `kamal proxy reboot` |
161	
162	Conventions:
163	
164	- **Never `ssh` in and edit `.env` by hand.** The deploy pipeline owns
165	  secrets. Hand edits get overwritten by the next `kamal deploy` silently.
166	- **Tag-driven deploys only.** Pushing to `main` doesn't deploy; tag
167	  pushes do. Keeps the history auditable.
168	- **Rollbacks are `kamal rollback`, not `git revert` + new tag.**
169	  Much faster, preserves the bad version for post-mortem.
170	
171	## Data posture by phase
172	
173	**Standing constraint:** the Hetzner VM runs on **synthetic data
174	only** until ADR-0008 cookie-session auth ships (M7.5 PR-4) **and**
175	a separate follow-up PR with an explicit go/no-go checkpoint lands.
176	Real Monarch exports never touch the instance in PR-1 through PR-3.
177	
178	| Phase         | What's on the VM                                   | How it gets there                                                                    |
179	| ---           | ---                                                | ---                                                                                  |
180	| PR-1          | Empty SQLite DB inside the container's ephemeral FS | No volume yet; entrypoint runs Alembic `upgrade head` on boot, creating tables. The 503 gate means no data-reading route is reachable anyway — this phase proves the image + Kamal config build and deploy cleanly. |
181	| PR-2          | Synthetic fixtures on the 10 GB mounted volume     | Volume attached at `/data`; entrypoint seeds from `tests/fixtures/sample_*.csv` (baked into the image) when the DB is empty; synthetic data persists across restarts. |
182	| PR-3          | Synthetic fixtures + Logfire telemetry             | No data-layer change. Observability layer only.                                      |
183	| PR-4          | Synthetic fixtures + cookie-auth gate live         | Auth middleware swaps in; 503 gate retires.                                          |
184	| Post-PR-4 PR  | Real Monarch exports                               | Operator-driven CSV import over SSH, gated by a fresh go/no-go PR approval.          |
185	
186	Synthetic data through PR-4 means every deploy iteration shakes out
187	pipeline bugs against the same bytes CI exercises — one fewer moving
188	part when something goes wrong on first cloud boot. It also means
189	that if the auth gate has an unseen hole, the blast radius is an
190	opinionated-but-public demo, not the household's finances.
191	
192	The real-data PR is its own change, with its own `code-reviewer`
193	review, its own `cloud-ops-specialist` sign-off, and an explicit
194	`# Pre-swap verification` checklist in the PR body:
195	
196	- [ ] `AUTH_ENABLED=true` and the chosen auth scheme valid end-to-end
197	  (see [cfo#110](https://github.com/melon-lab-com/melon-monarch-cfo/issues/110)
198	  — the ADR-0008 decision is being revisited; the "Tailscale edge
199	  confirmed blocking non-enrolled clients" check only applies if the
200	  revisit lands on Option D)
201	- [ ] TLS certificate valid; HSTS header present
202	- [ ] Snapshot of the synthetic DB taken immediately before import
203	  (rollback target)
204	- [ ] Import run against a re-runnable CSV (hash + dedup verified)
205	
206	Backup coverage (Hetzner Backups, daily + 7-day retention) is on from
207	VM creation, so there's no second-replica follow-on and no WAL-spike
208	pre-flight. RPO is ~24 h; Monarch source data is re-importable
209	(`content_hash` dedup + `(date, account_id)` upsert), so a lost day of
210	ingest costs re-running the importer, not re-creating data.
211	
212	## Rollbacks
213	
214	Kamal stores the previous N image tags on the host (`retain_containers:
215	5` default). Rollback is a single command:
216	
217	```sh
218	kamal rollback                   # roll to the immediately previous version
219	kamal rollback v2026-04-21       # roll to a specific prior tag
220	kamal app containers             # list retained versions with timestamps
221	```
222	
223	A rollback cuts traffic over to the prior container within a few seconds.
224	kamal-proxy handles draining; there's no DNS or LB change.
225	
226	**Migration caveat — schema ahead of binary.** The container entrypoint
227	runs `alembic upgrade head` on every boot. If you roll forward through
228	a destructive forward migration (e.g. column drop), then roll back, the
229	OLD image's entrypoint will `upgrade head` against a DB that's already
230	at the new revision — `upgrade head` is a no-op in that direction, but
231	the old code's queries may reference dropped columns and fail at runtime.
232	This is inherent to any deploy model that ships app + schema together.
233	Mitigations:
234	
235	- Write destructive migrations as two-step: one release adds the
236	  new shape + dual-writes, the next removes the old. Normal practice.
237	- Before a risky migration goes out, take an ad-hoc snapshot:
238	  `hcloud server create-image monarch-cfo-1 --type snapshot
239	   --description "pre-<migration-name>-$(date +%Y%m%d)"`. Rollback
240	  from that snapshot is below.
241	
242	**If you cannot roll back with `kamal rollback` (host in a bad state):**
243	reach for the snapshot restore path below. Don't `git revert` + retag
244	— rolling a fresh image deploy is usually slower than `kamal rollback`
245	and loses the bad version for post-mortem.
246	
247	### Post-rollback verification
248	
249	After every rollback, run:
250	
251	```sh
252	curl -fsS https://monarch.melon-lab.com/healthz      # expect 200
253	curl -s -o /dev/null -w '%{http_code}' \
254	  https://monarch.melon-lab.com/                     # expect 503 until PR-4
255	kamal app logs --lines 100                           # confirm old image-sha is serving
256	kamal app containers                                 # confirm one-and-only-one container running
257	```
258	
259	### Emergency: bad forward migration just shipped, DB may be at risk
260	
261	Run in this order; don't skip the stop step.
262	
263	1. **Stop writes immediately.** `kamal app stop` — halts the app
264	   before any more writes hit the now-wrong schema.
265	2. **Snapshot current state for post-mortem** (root fs only, see the
266	   backup coverage note below):
267	   ```sh
268	   hcloud server create-image monarch-cfo-1 --type snapshot \
269	     --description "pre-rollback-incident-$(date +%Y%m%d-%H%M)"
270	   ```
271	3. **Dump the DB file out** (the snapshot above doesn't cover it):
272	   ```sh
273	   ssh deploy@<ip> 'sqlite3 /data/monarch.db ".backup /tmp/monarch-incident.db"'
274	   scp deploy@<ip>:/tmp/monarch-incident.db ./incident-dbs/
275	   ```
276	4. **Decide forward vs. back** BEFORE restarting the app:
277	   - **Forward** (schema + code are both valid, data is recoverable):
278	     write a corrective migration + fix-forward PR. Keep the app
279	     stopped until the fix-forward deploy lands.
280	   - **Backward** (the forward migration was destructive and the
281	     drop/alter is unrecoverable): `kamal rollback <previous-tag>`
282	     to a known-good image. The rolled-back container's entrypoint
283	     runs `upgrade head` — which is a no-op when the DB is past-head
284	     — but the old code may fail runtime queries against dropped
285	     columns. If so, you're in the same "forward" bucket as above.
286	5. **Never** try to edit the DB by hand while the app container is
287	   running. Kamal's `kamal app exec bash` can inject sqlite3
288	   commands, but any DDL while the app has active connections risks
289	   locking. Use steps 1 + 3 first.
290	
291	## Backup / restore runbook
292	
293	> **Important coverage note.** Hetzner Cloud Backups snapshot the
294	> **server's root disk only** (OS, Docker images, container layers).
295	> Attached Volumes — including the 10 GB `monarch-data` Volume that
296	> holds `/data/monarch.db` — are **NOT** included, per Hetzner's
297	> [Backups/Snapshots overview](https://docs.hetzner.com/cloud/servers/backups-snapshots/overview/):
298	> *"Backups and Snapshots do not include any Volumes which are
299	> attached to your server."* The runbook below reflects that split:
300	> server backups cover the rebuild-the-VM path; the Volume (and
301	> therefore the DB file) has no managed backup in PR-2. See
302	> **§"Volume backup gap"** below for the synthetic-data interim and
303	> the blocker this places on the post-PR-4 go/no-go.
304	
305	### List available backups
306	
307	```sh
308	hcloud server describe monarch-cfo-1 -o json \
309	  | jq '.backup_window, [.id, .name]'
310	hcloud image list --type backup --label name=monarch-cfo-1
311	```
312	
313	Each backup's `id` is what you restore from. The `backup_window`
314	is the UTC time band Hetzner takes the daily snapshot; align any
315	planned maintenance outside that window.
316	
317	### Ad-hoc snapshot (before a risky operation)
318	
319	Same coverage scope as daily Backups — server root disk only.
320	**Does not include the attached Volume.** Use `sqlite3 .backup` for
321	the DB file itself (see §"Volume backup gap" below).
322	
323	```sh
324	hcloud server create-image monarch-cfo-1 --type snapshot \
325	  --description "pre-<reason>-$(date +%Y%m%d)"
326	# $0.0199/GB/mo for as long as the snapshot exists.
327	# Delete with `hcloud image delete <id>` when you no longer need it.
328	```
329	
330	### Restore the whole VM from a backup
331	
332	Rebuilds the VM's root disk from the chosen backup image. The
333	attached Volume is **not** affected by a rebuild — Hetzner reattaches
334	it untouched — so `/data/monarch.db` survives the rebuild intact.
335	cloud-init's `monarch-data-link.service` re-creates the `/data`
336	symlink to `/mnt/HC_Volume_<id>` on first boot.
337	
338	```sh
339	# Stop the app first for an app-consistent restore of the OS image.
340	kamal app stop
341	
342	# Rebuild from the backup image id.
343	hcloud server rebuild monarch-cfo-1 --image <backup-id>
344	
345	# Wait for cloud-init to finish (can be 2-3 min on a cold VM).
346	ssh deploy@<ip> 'cloud-init status --wait'
347	
348	# Re-push the Kamal state to re-create the proxy + app containers.
349	kamal setup                      # idempotent; safe to re-run
350	kamal app boot                   # start the app against the restored OS
351	```
352	
353	Verify:
354	
355	```sh
356	curl https://monarch.melon-lab.com/healthz      # 200
357	curl https://monarch.melon-lab.com/             # 503 until PR-4
358	```
359	
360	This path recovers from:
361	- OS disk corruption / ransomware on the root filesystem.
362	- Docker state gone sideways.
363	- Accidental `apt` damage.
364	
365	It does **NOT** recover from: DB corruption, volume loss, accidental
366	`DROP TABLE`, or a destructive app-side write. Those are covered by
367	the DB-level procedure below.
368	
369	### Volume backup gap (synthetic-data phase, and what PR-4 go/no-go must resolve)
370	
371	`/data/monarch.db` has **no automated backup** through PR-3. This is
372	acceptable TODAY because:
373	
374	- The only data on the volume is the synthetic seed from
375	  `tests/fixtures/sample_*.csv` — the entrypoint re-hydrates it on
376	  first boot if the DB is empty (no WAL / structural loss possible).
377	- The scope fence (`cloud-ops-specialist` persona + `docs/deploy.md`
378	  §"Data posture by phase") keeps real Monarch exports off the VM
379	  until PR-4 ships AND a separate go/no-go PR lands.
380	
381	**Before the post-PR-4 go/no-go lands, the volume must have managed
382	backup coverage.** The options (pick one in the go/no-go PR):
383	
384	1. **`sqlite3 .backup` cron on the VM.** `systemd` timer every N h
385	   runs `sqlite3 /data/monarch.db ".backup /var/backups/monarch/monarch-$(date +%Y%m%d-%H).db"`.
386	   `/var/backups/` is on the root disk, so each dump is captured by
387	   the next daily Hetzner Backup — giving ~24 h RPO on whatever dump
388	   cadence you pick. Cheap; no extra services.
389	2. **Off-server replica.** Litestream to Backblaze B2 (the ADR-0006
390	   runner-up), or periodic `rsync` to a second Hetzner Volume on a
391	   different host. Closer to seconds-level RPO, adds an external
392	   service + monthly cost + restore-drill discipline.
393	3. **Switch the DB layer.** Managed Postgres (Neon is the documented
394	   upgrade path in ADR-0006 if DB management becomes a priority).
395	   Backup is then the provider's concern.
396	
397	For PR-2 / PR-3 the recovery path for volume loss is to reseed:
398	
399	```sh
400	hcloud volume detach monarch-data
401	hcloud volume delete monarch-data
402	hcloud volume create --name monarch-data --size 10 --location hil \
403	  --format ext4
404	hcloud volume attach --server monarch-cfo-1 --automount monarch-data
405	ssh deploy@<ip> 'sudo systemctl start monarch-data-link.service'
406	kamal app boot        # entrypoint's seed-if-empty path re-seeds /data/monarch.db
407	```
408	
409	### RPO / RTO
410	
411	| Layer | Coverage | RPO | RTO |
412	|---|---|---|---|
413	| OS disk (root fs) | Hetzner Backups, daily, 7-day retention | ≤ 24 h | ~10 min (`hcloud server rebuild` + `kamal setup` + `kamal app boot`) |
414	| `/data` volume — SYNTHETIC PHASE (PR-2 / PR-3) | None needed; entrypoint re-seeds on empty DB | ≤ 0 — the synthetic source is in the image | ~2 min to re-seed from the baked fixtures |
415	| `/data` volume — REAL DATA (post PR-4 go/no-go) | **TO BE DECIDED in the go/no-go PR** — see §"Volume backup gap" above | **TBD — hard blocker on the go/no-go** | **TBD** |
416	
417	## Observability (M7.5 PR-3)
418	
419	Two signals ship with PR-3:
420	
421	### Logfire tracing
422	
423	`telemetry.configure()` is called at `create_app()` startup. When both
424	the `logfire` Python extra is installed (PR-3 Dockerfile update) AND
425	the `LOGFIRE_TOKEN` env var is set, spans emitted from the M8 agent
426	loop (`agent_span("run_once", ...)`) and any downstream HTTP / DB
427	instrumentation land in the Logfire cloud dashboard. Absent either
428	the extra or the token, every span-context is a silent no-op — the
429	container still deploys, there's just no cloud telemetry export.
430	
431	Rotating the token: `gh secret set LOGFIRE_TOKEN` + push any fresh
432	deploy tag. Kamal re-reads secrets on every deploy.
433	
434	The dashboard URL is project-scoped and set once in the Logfire UI;
435	paste it here after PR-3 lands on the box:
436	
437	    LOGFIRE_URL=https://logfire-us.pydantic.dev/<org>/monarch-cfo
438	
439	### Hetzner spend tripwire
440	
441	`.github/workflows/hetzner-spend.yml` runs daily at 14:00 UTC (and on
442	`workflow_dispatch` for manual checks). It calls
443	`scripts/check_hetzner_spend.py`, which:
444	
445	1. Pulls the live Hetzner pricing + running-resource catalog.
446	2. Projects month-to-date spend against the $20 cap (see §"What
447	   you're paying for").
448	3. Posts a `::warning::` at 50 % and 75 %, fails red at 90 %.
449	4. Upserts a pinned `[spend]` comment on the M7.5 milestone issue
450	   (cfo#35) so the most recent reading is always one link away.
451	
452	Trigger manually:
453	
454	    gh workflow run hetzner-spend --repo melon-lab-com/melon-monarch-cfo
455	    # Watch the latest run:
456	    gh run list --workflow hetzner-spend --limit 1
457	
458	Thresholds are repo-var-overridable (`MONARCH_SPEND_CAP_USD`,
459	`MONARCH_SPEND_WARN_LOW_PCT`, `MONARCH_SPEND_WARN_HIGH_PCT`,
460	`MONARCH_SPEND_FAIL_PCT`) if the cap or the escalation tiers ever
461	change.
462	
463	## Things you need to be aware of
464	
465	### Before any real Monarch data lands on the box
466	
467	Two gates:
468	
469	1. **Auth gate shipped** (PR-4 of M7.5). `AUTH_ENABLED=true`,
470	   `AUTH_BOOTSTRAP_503=false`, a real auth mechanism in front of
471	   every non-`/healthz` route.
472	2. **Go/no-go PR merged** with the "Pre-swap verification" list
473	   above ticked and a `cloud-ops-specialist` review verdict on
474	   file.
475	
476	### Secret discipline
477	
478	- Secrets live only in GHA (encrypted at rest, masked in logs) and
479	  in the running container's environment. Neither is in git.
480	- GHA `::add-mask::` every secret value before using it; never `echo`
481	  raw secrets in workflow output.
482	- Rotate any secret in ~30 seconds: `gh secret set <NAME>` → push
483	  a new deploy tag, which triggers a normal rolling deploy that
484	  picks up the new value. Ad-hoc local path is `kamal env push`
485	  followed by `kamal app boot` — `env push` alone only updates the
486	  env file on the host; the container sees it on the next boot.
487	- Container runs as non-root user (declared in Dockerfile). Any
488	  host-side secret file is `chmod 600` owned by the `deploy` user.
489	
490	### What's NOT on auto-pilot
491	
492	- **Kernel patches requiring reboot.** `unattended-upgrades` handles
493	  security patches but won't reboot. Budget a ~5-minute manual reboot
494	  during a quiet window monthly-ish; a GHA cron will warn if the host
495	  is > 14 days stale on `apt list --upgradable`.
496	- **Hetzner payment.** Top up or enable auto-pay. A lapse pauses the
497	  VM; everything rebuilds from Litestream + image on the next deploy,
498	  but the household gets downtime.
499	- **Certificate renewals** happen automatically via `kamal-proxy` +
500	  Let's Encrypt, but can fail if DNS changes or the VM is offline > 30
501	  days. `kamal proxy logs` surfaces warnings; `kamal proxy reboot`
502	  re-triggers renewal.
503	- **`ANTHROPIC_API_KEY` spend after M8 ships** — keep ingest + report
504	  runs on manual triggers until cost data lands, then move to cron
505	  with budgeted alerting.
506	
507	### The "it's just a Docker container" escape hatch
508	
509	Kamal 2 is a thin wrapper around Docker + SSH + a reverse proxy. If
510	Kamal breaks in a way that blocks a deploy, SSH to the VM and use
511	Docker directly: `docker ps`, `docker logs <container>`, `docker exec`.
512	The app listens on port 3000 inside the container; `kamal-proxy`
513	routes `:443` → `:3000`. If `kamal-proxy` itself is broken:
514	`docker logs kamal-proxy`. Nothing here is proprietary Kamal glue.
515	
516	**Documented fallback** (from ADR-0006): if > 2 consecutive deploys
517	fail inside Kamal's own machinery (not the app), drop to plain
518	`docker-compose` + a small GHA deploy script. You lose rolling deploys
519	and declarative rollback but keep everything else. Trigger and migration
520	plan are in the ADR's Consequences section.
521	
522	### Multi-app isolation
523	
524	Each app on the shared VM gets:
525	
526	- Its own `/data/<app>/` path on the volume.
527	- Its own DB file (no shared SQLite).
528	- Its own hostname, routed by `kamal-proxy`.
529	- Its own `.kamal/secrets` in its own repo.
530	- Its own GHA deploy workflow.
531	
532	The apps share: the VM, the OS, the Docker daemon, the `kamal-proxy`
533	instance, the snapshot cadence. If one app eats all the RAM, the other
534	suffers — that's the "apartment building" trade-off. At our household
535	scale it's a non-issue; if it becomes one, CPX11 → CPX21 is a ~$7/mo
536	bump via `hcloud server change-type`.
537	
538	## Emergency: "stop paying tomorrow"
539	
540	Full teardown, ~5 minutes:
541	
542	```sh
543	# Graceful shutdown FIRST so the snapshot is app-consistent
544	# (SQLite has no in-flight writes; no chance of a corrupted WAL
545	# landing in the saved image)
546	kamal app stop
547	
548	# Take a final snapshot after shutdown
549	hcloud server create-image monarch-cfo-1 --type snapshot \
550	    --description "final-backup-$(date +%Y%m%d)"
551	
552	# Hetzner cleanup
553	hcloud server delete monarch-cfo-1   # backups auto-delete with the server
554	hcloud volume delete <volume-id>
555	
556	# (Optional) tidy external resources
557	# - Squarespace: remove the A record for monarch.<yourdomain>
558	# - GitHub: remove the repo secrets and the deploy workflow if you want
559	```
560	
561	What you keep:
562	
563	- The repo, with its Dockerfile + Kamal config (redeployable anywhere
564	  in ~15 minutes from a fresh VM).
565	- The local `monarch-backup.db` SQLite file.
566	- Your 1Password vault with the secrets (rotate any you don't trust).
567	
568	Total time to rebuild on any other provider: about a workday, most of
569	which is waiting for a new VM to provision and DNS to propagate. This
570	is the literal meaning of "no lock-in."
571	
572	## Who does what
573	
574	| Task | You | Agent |
575	|---|---|---|
576	| Hetzner account, ID verification, API token | ✓ | |
577	| Squarespace DNS A-record (one-time, after VM is up) | ✓ | |
578	| GHA secrets (4 values via `gh secret set`) | ✓ | |
579	| VM provisioning, hardening | | ✓ (PR-1) |
580	| First Kamal deploy | | ✓ (PR-1) |
581	| CI deploy pipeline | | ✓ (PR-2) |
582	| Real auth | | ✓ (PR-4) |
583	| Day-2 deploys, rollbacks, log tailing | agent-operable, you can too | ✓ |
584	| Monthly OS reboot | ✓ | (agent can warn via cron) |
585	| Payment, top-ups | ✓ | |
586	
587	## References
588	
589	- [ADR-0006](decisions/0006-cloud-deployment-target.md) — full decision
590	  record: context, consequences, alternatives considered and rejected.
591	- [Issue #28](https://github.com/melon-lab-com/melon-monarch-cfo/issues/28)
592	  — decision thread including Plan agent proposal, code-reviewer review,
593	  and Kamal-vs-Coolify research.
594	- [Issue #16](https://github.com/melon-lab-com/melon-monarch-cfo/issues/16)
595	  — M8 AI analyst, the milestone this unblocks.
596	- [Kamal 2 docs](https://kamal-deploy.org/)
597	- [Hetzner Cloud API reference](https://docs.hetzner.cloud/)
598	- [Hetzner Backups product page](https://docs.hetzner.com/cloud/servers/backups-snapshots/overview/)
599	- [Neon serverless Postgres](https://neon.tech/) — documented upgrade path if DB management ever becomes a priority
600	

# Kamal secrets template. Copy to `.kamal/secrets` locally when
# operating the box by hand; the CI deploy workflow (PR-2) renders this
# same file from GitHub Actions secrets on every deploy.
#
# `.kamal/secrets` itself is gitignored; only this `.example` lives in
# the tree. Every name on the left must match a corresponding entry in
# `config/deploy.yml` (either `env.secret:` or a field like
# `registry.username` that pulls from secrets).
#
# Each right-hand side is a *shell* expansion performed at deploy time:
# Kamal reads the literal text `$NAME` and expands it against the
# deployer's environment. The value never lands in this file — only
# the reference does. Inline a real token only if you want it in git.
#
# PR-2's GHA deploy workflow materialises `.kamal/secrets` from GitHub
# Actions secrets via `::add-mask::`-guarded exports BEFORE invoking
# `kamal deploy`, and never commits the rendered file. Keep the same
# pattern in any local `.kamal/secrets` you write by hand.

# GHCR authentication for `kamal deploy`. The USERNAME is the personal
# GitHub handle that owns the PAT — NOT the `melon-lab-com` org slug
# (GHCR rejects org slugs here even when the image path uses one).
# The password is a PAT / fine-grained token with `read:packages` scope.
# Generate with `gh auth token` for a personal tie, or mint a dedicated
# GitHub App token if the deploy user needs to be separable.
KAMAL_REGISTRY_USERNAME=$KAMAL_REGISTRY_USERNAME
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

# Logfire write token (project-scoped). Mint a write token from the
# Logfire dashboard (https://logfire-us.pydantic.dev/ → project →
# Settings → Write tokens) and paste into the matching GitHub Actions
# secret. The `logfire` Python extra (Dockerfile) + telemetry.configure()
# in src/monarch_cfo/ai/telemetry.py pick it up on container start.
# Absent token = silent no-op (safe).
LOGFIRE_TOKEN=$LOGFIRE_TOKEN

# --- lands in PR-4 (cookie auth, ADR-0008) ---
# AUTH_COOKIE_SECRET=$AUTH_COOKIE_SECRET
# SESSION_SECRET=$SESSION_SECRET

# --- lands with M8 chat on cloud (per docs/deploy.md §Secret rotation) ---
# ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY
# OPENAI_API_KEY=$OPENAI_API_KEY
# GEMINI_API_KEY=$GEMINI_API_KEY
=== pyproject deps ===
dependencies = [
    # The Monarch CSV ingest library (parsers, dedup hashing, ORM,
    # migrations, CLI) lives in its own MIT-licensed public repo
    # after M7 PR-4. Pin by commit SHA rather than `@main` so a
    # force-push upstream cannot retroactively alter our builds;
    # bump this line deliberately alongside a local test run.
    "melon-monarch-ingest @ git+https://github.com/melon-lab-com/melon-monarch-ingest@db78fe6",
    # FastAPI + Pydantic are cfo-specific (read API + reports layer).
    # SQLAlchemy / Alembic are transitive via melon-monarch-ingest.
    "pydantic>=2.7",
    "fastapi>=0.115",
    # Jinja2 templating for the HTMX frontend (M6). Served in-process
    # by FastAPI; no Node build step (plan §9). HTMX + Chart.js ship
    # as vendored static assets rather than package deps.
    "jinja2>=3.1",
]

[project.scripts]
=== routers ===
__init__.py
accounts.py
balances.py
categories.py
chat.py
health.py
merchants.py
networth.py
reports.py
transactions.py
=== web ===
src/monarch_cfo/web/:
__init__.py
routes.py
static
templates
templating.py

src/monarch_cfo/web/templates/:
_transactions_rows.html
annual.html
base.html
chat.html
index.html
networth.html
owners.html
rental.html
subscriptions.html
transactions.html
=== tests ===
tests/:
api
browser
conftest.py
fixtures
goldens
scripts
unit

tests/api/:
__init__.py
conftest.py
integration
test_auth_gate.py
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "pytest-cov>=5.0",
    "hypothesis>=6.100",
    # httpx is FastAPI's TestClient transport; only needed in tests.
    "httpx>=0.27",
    # Pin ruff and mypy to the same minor as the pre-commit hooks so the
    # linter / type-checker in the venv never diverges from the one
    # pre-commit enforces. Bump both sides together.
    "ruff~=0.15.11",
    "mypy~=1.20.1",
    "pre-commit>=3.8",
    # Typer is transitive via melon-monarch-ingest but tests that
    # drive the ingest CLI's `rules` subcommand need CliRunner; the
    # ingest lib already depends on it, we just surface it here so
    # `uv sync --extra dev` includes it.
    "typer>=0.13,<0.30",
    # pytest-recording gives us VCR cassette support for the Gemini
    # adapter smoke test. Network-replay keeps the smoke test hermetic
    # without pretending the wire protocol away (see ADR-0009).
    "pytest-recording>=0.13",
]
# ASGI server for running the read API locally — not a runtime dep
# because the CLI + ingest layer don't need it, and the test suite
# hits the app in-process via FastAPI's TestClient. Install with
# `uv sync --extra serve` when you actually want to serve HTTP.
serve = ["uvicorn>=0.29"]
# Playwright smoke tests for the M6 HTMX frontend. Heavy (~500MB
# browser binary) so kept opt-in. Install with
#   `uv sync --extra browser && uv run playwright install chromium`
# then run with
#   `uv run pytest -m browser`.
# The `browser` pytest marker is skipped by default (see
# `[tool.pytest.ini_options].addopts` → `-m "not browser"`).
browser = [
    "uvicorn>=0.29",
    "pytest-playwright>=0.5",
]
# Google Gemini SDK adapter (M8 primary provider, ADR-0009). Opt-in so
# a bare `uv sync` stays light; enable with
# `uv sync --extra chat-gemini`.
chat-gemini = ["google-genai>=1.0"]
# Anthropic Claude SDK adapter (M8.3). Opt-in for the same reason —
# enable with `uv sync --extra chat-anthropic`.
chat-anthropic = ["anthropic>=0.39"]
# OpenAI SDK adapter (M8.3). Opt-in; enable with
# `uv sync --extra chat-openai`.
chat-openai = ["openai>=1.50"]
# Umbrella extra that pulls in every chat adapter we ship. CI runs a
# per-extra isolation matrix against each one individually so an
# accidental cross-provider import would fail its isolated row.
chat-all = ["melon-monarch-cfo[chat-gemini,chat-anthropic,chat-openai]"]
# Logfire optional observability integration (M8.7). When installed,
# the agent loop and session endpoint emit structured spans that surface
# in the Logfire cloud dashboard or any OpenTelemetry-compatible backend.
# Enable with `uv sync --extra logfire`.
logfire = ["logfire>=0.50"]

[tool.hatch.metadata]
=== Dockerfile 100-120 ===
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
    CMD /app/.venv/bin/python -c "import urllib.request, sys; resp = urllib.request.urlopen('http://127.0.0.1:3000/healthz', timeout=3); sys.exit(0 if resp.status == 200 else 1)"

ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
# --proxy-headers trusts X-Forwarded-* from the upstream; the narrow
# allow-list restricts that trust to the loopback + Docker default
# bridge range where kamal-proxy actually sits. `*` would make the
# client IP attacker-controllable once the box is on the internet —
# concretely, the ADR-0008 per-IP login rate limiter (PR-4) could be
# spoofed to burn another user's attempt budget.
CMD ["uvicorn", "monarch_cfo.api.app:app", "--host", "0.0.0.0", "--port", "3000", "--proxy-headers", "--forwarded-allow-ips=127.0.0.1,172.16.0.0/12"]
=== gate status ===
code-reviewer-gate	fail	8s	https://github.com/melon-lab-com/melon-monarch-cfo/actions/runs/24977788979/job/73133062355	
code-reviewer-gate	pass	0		code-reviewer approved this commit
video-proof gate	pass	3s	https://github.com/melon-lab-com/melon-monarch-cfo/actions/runs/24977788973/job/73133062498
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

1	"""Auth-gate / 503 bootstrap middleware (ADR-0008 PR-1 slice).
2	
3	Cookie-session auth (`AUTH_ENABLED=true`) lands in PR-4. This suite
4	covers only the three-state table's bootstrap cell — the "first cloud
5	boot" surface — plus the config-error assertion.
6	
7	These tests construct `ApiSettings` directly and hand them to the
8	`client_for` conftest factory, so the autouse `_clear_settings_cache`
9	fixture (which covers the `Depends(get_settings)` resolution path) is
10	inert for them. The env-variable tests below use `monkeypatch.setenv`
11	and `ApiSettings()` without the cache, which is also outside the
12	autouse fixture's blast radius. Noted so a reader doesn't assume the
13	two things interact.
14	"""
15	
16	from __future__ import annotations
17	
18	from collections.abc import Callable
19	
20	import pytest
21	from fastapi.testclient import TestClient
22	from pydantic import ValidationError
23	from sqlalchemy.orm import Session
24	
25	from monarch_cfo.api.settings import ApiSettings
26	
27	
28	def test_bootstrap_gate_blocks_root_with_503(
29	    client_for: Callable[..., TestClient], session: Session
30	) -> None:
31	    settings = ApiSettings(auth_enabled=False, auth_bootstrap_503=True)
32	    client = client_for(session, settings=settings)
33	    try:
34	        response = client.get("/accounts")
35	    finally:
36	        client.close()
37	    assert response.status_code == 503
38	    body = response.json()
39	    assert "AUTH_BOOTSTRAP_503" in body["detail"]
40	    assert response.headers.get("Retry-After") == "3600"
41	
42	
43	def test_bootstrap_gate_allows_healthz(
44	    client_for: Callable[..., TestClient], session: Session
45	) -> None:
46	    settings = ApiSettings(auth_enabled=False, auth_bootstrap_503=True)
47	    client = client_for(session, settings=settings)
48	    try:
49	        response = client.get("/healthz")
50	    finally:
51	        client.close()
52	    assert response.status_code == 200
53	    assert response.json()["status"] == "ok"
54	
55	
56	def test_bootstrap_gate_blocks_openapi_schema(
57	    client_for: Callable[..., TestClient], session: Session
58	) -> None:
59	    # Defence-in-depth: leaking the OpenAPI schema while the rest of
60	    # the surface is 503'd advertises every route to an unauthenticated
61	    # caller. Keep it gated.
62	    settings = ApiSettings(auth_enabled=False, auth_bootstrap_503=True)
63	    client = client_for(session, settings=settings)
64	    try:
65	        response = client.get("/openapi.json")
66	    finally:
67	        client.close()
68	    assert response.status_code == 503
69	
70	
71	def test_gate_inert_when_bootstrap_false(
72	    client_for: Callable[..., TestClient], session: Session
73	) -> None:
74	    # Default local-dev state: everything open. Existing M4/M6/M8 test
75	    # suites depend on this cell.
76	    settings = ApiSettings(auth_enabled=False, auth_bootstrap_503=False)
77	    client = client_for(session, settings=settings)
78	    try:
79	        response = client.get("/accounts")
80	    finally:
81	        client.close()
82	    assert response.status_code == 200
83	
84	
85	def test_gate_inert_when_auth_enabled_bootstrap_false(
86	    client_for: Callable[..., TestClient], session: Session
87	) -> None:
88	    # The PR-4 state (real auth wired). This middleware must step aside
89	    # so the cookie middleware can take the decision.
90	    settings = ApiSettings(auth_enabled=True, auth_bootstrap_503=False)
91	    client = client_for(session, settings=settings)
92	    try:
93	        response = client.get("/accounts")
94	    finally:
95	        client.close()
96	    assert response.status_code == 200
97	
98	
99	def test_invalid_auth_state_raises_at_construction() -> None:
100	    # AUTH_ENABLED=true AND AUTH_BOOTSTRAP_503=true is the ambiguous
101	    # cell of the three-state table (ADR-0008 §Decision). Pydantic's
102	    # model_validator raises ValidationError; the container should fail
103	    # to boot.
104	    with pytest.raises(ValidationError) as exc_info:
105	        ApiSettings(auth_enabled=True, auth_bootstrap_503=True)
106	    assert "ADR-0008" in str(exc_info.value)
107	
108	
109	def test_env_vars_are_unprefixed(monkeypatch: pytest.MonkeyPatch) -> None:
110	    # The Kamal `env:` block + docs/deploy.md set AUTH_ENABLED /
111	    # AUTH_BOOTSTRAP_503 raw, not MONARCH_API_AUTH_ENABLED. Keep the
112	    # alias contract.
113	    monkeypatch.setenv("AUTH_BOOTSTRAP_503", "true")
114	    monkeypatch.setenv("AUTH_ENABLED", "false")
115	    settings = ApiSettings()
116	    assert settings.auth_bootstrap_503 is True
117	    assert settings.auth_enabled is False
118	
119	
120	def test_prefixed_alias_still_accepted(monkeypatch: pytest.MonkeyPatch) -> None:
121	    # Belt-and-braces: MONARCH_API_* also works, so an operator who
122	    # types the prefixed form by reflex doesn't get a silent default.
123	    monkeypatch.setenv("MONARCH_API_AUTH_BOOTSTRAP_503", "true")
124	    settings = ApiSettings()
125	    assert settings.auth_bootstrap_503 is True
126	

1	"""Fixtures for the API tests.
2	
3	- `client(session)`: a FastAPI `TestClient` with `get_session`
4	  overridden to yield the caller's `Session`. App rebuilt per test.
5	- `seeded_session(session)`: imports the M2 sample CSVs and returns
6	  the session, for integration tests that want the full ORM fabric.
7	- `client_for(session)`: a builder variant for tests that construct
8	  ORM rows *after* the `session` fixture runs — returns a non-context-
9	  managed `TestClient` the caller closes in a `finally` block. Shared
10	  helper to avoid per-file `_client_for` duplicates.
11	"""
12	
13	from __future__ import annotations
14	
15	import json
16	import os
17	from collections.abc import Callable, Iterator
18	from pathlib import Path
19	
20	import pytest
21	from fastapi.testclient import TestClient
22	from monarch_ingest.importers import import_balances, import_transactions
23	from sqlalchemy.orm import Session
24	
25	from monarch_cfo.api.app import create_app
26	from monarch_cfo.api.deps import get_session, get_settings
27	from monarch_cfo.api.settings import ApiSettings
28	
29	FIXTURES_DIR = Path(__file__).parent.parent / "fixtures"
30	GOLDENS_DIR = Path(__file__).parent.parent / "goldens"
31	
32	
33	@pytest.fixture
34	def compare_or_regen() -> Callable[[Path, object], None]:
35	    """Return the golden-comparison helper.
36	
37	    Usage:
38	      def test_foo(compare_or_regen, client_for, seeded_session):
39	          compare_or_regen(GOLDENS_DIR / "foo.json", response.json())
40	
41	    Compare behavior is default; `MONARCH_REGEN_GOLDENS=1` overwrites
42	    the file instead. A CI-side guard refuses regen when `CI=true`
43	    so a stray local env var can't silently accept all goldens.
44	    """
45	
46	    def _helper(path: Path, body: object) -> None:
47	        serialized = json.dumps(body, indent=2, sort_keys=True) + "\n"
48	        if os.environ.get("MONARCH_REGEN_GOLDENS") == "1":
49	            assert os.environ.get("CI") != "true", (
50	                "MONARCH_REGEN_GOLDENS=1 must not run in CI — regenerating "
51	                "goldens there would hide the regression the test is meant "
52	                "to catch."
53	            )
54	            path.parent.mkdir(parents=True, exist_ok=True)
55	            path.write_text(serialized, encoding="utf-8")
56	            return
57	        assert path.exists(), (
58	            f"golden {path} missing. Run with MONARCH_REGEN_GOLDENS=1 to create it."
59	        )
60	        expected = json.loads(path.read_text(encoding="utf-8"))
61	        assert body == expected, (
62	            f"golden drift at {path.name}; diff the response above and either "
63	            "regenerate (MONARCH_REGEN_GOLDENS=1) or fix the code."
64	        )
65	
66	    return _helper
67	
68	
69	@pytest.fixture(autouse=True)
70	def _clear_settings_cache() -> Iterator[None]:
71	    """Clear `get_settings` LRU cache so tests see env overrides.
72	
73	    Without this, a test that sets `MONARCH_API_*` via `monkeypatch.setenv`
74	    before hitting the API would see the stale first-call instance. No
75	    current test exercises that path, but M7.5 will add auth config to
76	    `ApiSettings` and this discipline prevents mysteriously
77	    environment-insensitive tests when it lands.
78	    """
79	    get_settings.cache_clear()
80	    yield
81	    get_settings.cache_clear()
82	
83	
84	@pytest.fixture
85	def client(session: Session) -> Iterator[TestClient]:
86	    app = create_app()
87	
88	    def _override() -> Iterator[Session]:
89	        yield session
90	
91	    app.dependency_overrides[get_session] = _override
92	    with TestClient(app) as c:
93	        yield c
94	
95	
96	@pytest.fixture
97	def seeded_session(session: Session) -> Session:
98	    """Imports M2 sample CSVs into `session` and returns it."""
99	    import_transactions(session, FIXTURES_DIR / "sample_transactions.csv", accept_new=True)
100	    import_balances(session, FIXTURES_DIR / "sample_balances.csv", accept_new=True)
101	    session.commit()
102	    return session
103	
104	
105	@pytest.fixture
106	def client_for() -> Callable[..., TestClient]:
107	    """Factory that builds a TestClient bound to a caller-supplied session.
108	
109	    Variant of the `client` fixture for tests that seed ORM rows before
110	    constructing the client, or that need a non-default `ApiSettings`
111	    (e.g. auth-gate tests that exercise the ADR-0008 three-state table).
112	    The caller closes the returned client in a `try/finally` (tests are
113	    explicit about lifetime — the fixture doesn't context-manage because
114	    the data-flow is clearer when the client is visibly opened after the
115	    seeding.)
116	    """
117	
118	    def _build(session: Session, *, settings: ApiSettings | None = None) -> TestClient:
119	        app = create_app(settings=settings)
120	
121	        def _override() -> Iterator[Session]:
122	            yield session
123	
124	        app.dependency_overrides[get_session] = _override
125	        return TestClient(app)
126	
127	    return _build
128	

1	"""Jinja environment + shared template helpers.
2	
3	One `Templates` instance per app. Exposes small filters (cents →
4	dollars, percent formatting) so templates don't have to do integer
5	math inline.
6	"""
7	
8	from __future__ import annotations
9	
10	from decimal import Decimal
11	from pathlib import Path
12	
13	from fastapi.templating import Jinja2Templates
14	
15	TEMPLATES_DIR = Path(__file__).parent / "templates"
16	STATIC_DIR = Path(__file__).parent / "static"
17	
18	
19	def _format_dollars(cents: int | None) -> str:
20	    """Render integer cents as `$1,234.56`, signed. None → `—`."""
21	    if cents is None:
22	        return "—"
23	    sign = "-" if cents < 0 else ""
24	    whole, frac = divmod(abs(cents), 100)
25	    return f"{sign}${whole:,}.{frac:02d}"
26	
27	
28	def _format_pct(value: str | Decimal | float | None) -> str:
29	    """Render a 4dp Decimal-or-string as a signed percent.
30	
31	    `0.0690` → `+6.90%`. `-0.1000` → `-10.00%`. None → `—`.
32	    Accepts the API wire format (string) or Decimal/float.
33	    """
34	    if value is None:
35	        return "—"
36	    dec = Decimal(str(value))
37	    # Two-decimal percent: shift by 100, quantize to 2dp.
38	    pct = (dec * 100).quantize(Decimal("0.01"))
39	    sign = "+" if pct >= 0 else ""
40	    return f"{sign}{pct}%"
41	
42	
43	def build_templates() -> Jinja2Templates:
44	    templates = Jinja2Templates(directory=str(TEMPLATES_DIR))
45	    templates.env.filters["dollars"] = _format_dollars
46	    templates.env.filters["pct"] = _format_pct
47	    return templates
48	
49	
50	templates = build_templates()
51	

1	"""FastAPI dependency wiring.
2	
3	The API layer is read-only: `get_session` yields a per-request session
4	without `monarch_ingest.db.session_scope` because that helper commits
5	on exit. The engine + sessionmaker are memoized on the resolved DB URL
6	so tests that override `MONARCH_DB_URL` pick up a distinct target.
7	"""
8	
9	from __future__ import annotations
10	
11	import datetime as dt
12	from collections.abc import Iterator
13	from functools import lru_cache
14	from typing import Annotated
15	
16	from fastapi import Depends, HTTPException, Query, status
17	from monarch_ingest.db import get_db_url, make_engine, make_session_factory
18	from sqlalchemy.orm import Session, sessionmaker
19	
20	from monarch_cfo.ai.provider import ChatProvider
21	from monarch_cfo.api.settings import ApiSettings
22	
23	
24	@lru_cache(maxsize=8)
25	def _session_factory_for_url(url: str) -> sessionmaker[Session]:
26	    return make_session_factory(make_engine(url))
27	
28	
29	def get_session() -> Iterator[Session]:
30	    """Yield a per-request read-only Session; close it on teardown."""
31	    factory = _session_factory_for_url(get_db_url())
32	    session = factory()
33	    try:
34	        yield session
35	    finally:
36	        session.close()
37	
38	
39	def get_cfo_session() -> Iterator[Session]:
40	    """Yield a per-request writable CFO Session; commit + close on teardown.
41	
42	    Distinct from `get_session`: the CFO-owned tables (chat_session,
43	    chat_message; see `monarch_cfo.db.models`) are writable, so the
44	    request handler may mutate rows and the dependency must commit on
45	    clean return and rollback on exception.
46	    """
47	    from monarch_cfo.db import get_cfo_session_factory
48	
49	    factory = get_cfo_session_factory()
50	    session = factory()
51	    try:
52	        yield session
53	        session.commit()
54	    except Exception:
55	        session.rollback()
56	        raise
57	    finally:
58	        session.close()
59	
60	
61	@lru_cache(maxsize=1)
62	def get_settings() -> ApiSettings:
63	    """Return the process-wide ApiSettings, read once from the env."""
64	    return ApiSettings()
65	
66	
67	def today_utc() -> dt.date:
68	    """Return today's date in UTC. Monkeypatchable in tests."""
69	    return dt.datetime.now(dt.UTC).date()
70	
71	
72	class DateRangeParams:
73	    """Shared `date_from` / `date_to` query dependency.
74	
75	    `date_from` is required; `date_to` defaults to UTC today. Raises
76	    400 if `date_from > date_to`. The resolved upper bound is exposed
77	    as `effective_to` so callers don't re-run the defaulting.
78	    """
79	
80	    def __init__(
81	        self,
82	        date_from: Annotated[
83	            dt.date,
84	            Query(description="Inclusive lower bound on `date` (ISO-8601)."),
85	        ],
86	        date_to: Annotated[
87	            dt.date | None,
88	            Query(description="Inclusive upper bound. Defaults to today (UTC)."),
89	        ] = None,
90	    ) -> None:
91	        self.date_from = date_from
92	        self.effective_to = date_to if date_to is not None else today_utc()
93	        if self.date_from > self.effective_to:
94	            raise HTTPException(
95	                status_code=status.HTTP_400_BAD_REQUEST,
96	                detail="date_from must not exceed date_to",
97	            )
98	
99	
100	DateRange = Annotated[DateRangeParams, Depends()]
101	
102	
103	def get_chat_provider() -> ChatProvider:
104	    """Build and return the configured chat provider. Overridable in tests."""
105	    from monarch_cfo.ai.config import (
106	        check_extras_installed,
107	        get_api_key,
108	        get_model,
109	        get_provider,
110	    )
111	    from monarch_cfo.ai.errors import ChatConfigError
112	
113	    try:
114	        prov = get_provider()
115	        check_extras_installed(prov)
116	        api_key = get_api_key(prov)
117	        model_str = get_model(prov)
118	    except ChatConfigError as exc:
119	        raise HTTPException(
120	            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
121	            detail=f"Chat configuration error: {exc}",
122	        ) from exc
123	
124	    provider: ChatProvider
125	    if prov == "gemini":
126	        from monarch_cfo.ai.providers.gemini import GeminiChatProvider
127	
128	        provider = GeminiChatProvider(api_key=api_key, model=model_str)
129	    elif prov == "anthropic":
130	        from monarch_cfo.ai.providers.anthropic import AnthropicChatProvider
131	
132	        provider = AnthropicChatProvider(api_key=api_key, model=model_str)
133	    elif prov == "openai":
134	        from monarch_cfo.ai.providers.openai import OpenAIChatProvider
135	
136	        provider = OpenAIChatProvider(api_key=api_key, model=model_str)
137	    else:
138	        raise AssertionError(f"unreachable: get_provider returned {prov!r}")
139	    return provider
140	

"""UI routes — Jinja-rendered pages under `/ui/`.

Pages read the same `monarch_cfo.reports` assemblers the JSON API
uses; there is no UI-specific data model. HTMX filter partials land
in M6 PR-4.
"""

from __future__ import annotations

import datetime as dt
from typing import Annotated
from urllib.parse import urlencode

from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request, status
from fastapi.responses import HTMLResponse
from monarch_ingest.models import Account
from sqlalchemy import select
from sqlalchemy.orm import Session

from monarch_cfo.api.deps import get_cfo_session, get_session, today_utc
from monarch_cfo.api.routers.transactions import list_transactions
from monarch_cfo.db.models import ChatSession as DbChatSession
from monarch_cfo.reports.annual import build_annual_report, fetch_lookups
from monarch_cfo.reports.compare import compare_reports
from monarch_cfo.web.templating import templates

# Default net-worth chart window when the user hasn't passed an
# explicit range. Five years is long enough to show trends, short
# enough to keep the chart readable on a phone screen. Fixed 1825
# days rather than calendar-aware relativedelta — the leap-year
# drift of ~1 day is irrelevant for a chart default, and avoids
# adding `python-dateutil` as a dep.
_DEFAULT_NETWORTH_WINDOW_DAYS = 365 * 5

router = APIRouter(include_in_schema=False)


def _base_context(**extra: object) -> dict[str, object]:
    """Shared context injected into every UI render.

    `latest_year` drives the header "Annual report" link; pulling it
    from `today_utc()` (monkeypatchable in tests) keeps the nav year
    fresh without a hardcoded value that rots on January 1.
    """
    return {"latest_year": today_utc().year, **extra}


@router.get("/ui/", response_class=HTMLResponse)
def index(request: Request) -> HTMLResponse:
    return templates.TemplateResponse(request, "index.html", _base_context())


@router.get("/ui/reports/annual/{year}", response_class=HTMLResponse)
def annual_report_page(
    request: Request,
    year: Annotated[int, Path(ge=1900, le=9999)],
    session: Annotated[Session, Depends(get_session)],
) -> HTMLResponse:
    """Render the CFO annual report for a calendar year.

=== telemetry ===
"""Optional Logfire instrumentation (M8.7).

Logfire (``pip install logfire``) provides structured tracing for Python
applications.  This module wraps the Logfire API behind a thin layer that
gracefully degrades to no-ops when the ``logfire`` package is not installed,
keeping the ``chat-logfire`` extra truly optional.

Usage::

    from monarch_cfo.ai.telemetry import agent_span, configure

    configure()  # call once at app startup; no-op if logfire absent

    with agent_span("run_once", model="gemini-2.5-pro", turn=1):
        ...
"""

from __future__ import annotations

from contextlib import contextmanager, nullcontext
from typing import Any

# Resolved once at import time; None means logfire is not installed.
try:
    import logfire as _logfire_mod

    _LOGFIRE: Any = _logfire_mod
except ImportError:
    _LOGFIRE = None


def configure() -> None:
    """Configure Logfire if installed; silently skip otherwise.

    Logfire reads ``LOGFIRE_TOKEN`` from the environment for the
    send-to-cloud path. We pass ``send_to_logfire="if-token-present"``
    so Logfire does NOT attempt to ``initialize_project()`` when the
    token is absent or empty — the default ``send_to_logfire=True``
    raises ``LogfireConfigError("You are not logged into Logfire")``
    at startup on a container with no ``~/.logfire/default.toml``,
    which crashes the app at boot.

    The M7.5 PR-3 deploy wires ``LOGFIRE_TOKEN`` as an OPTIONAL Kamal
    secret; an unset GitHub Actions secret materialises as an empty
    env var rather than an unset one. ``"if-token-present"`` treats
    empty as absent and short-circuits cleanly.

    Effect:
    - Token set   → cloud export active.
    - Token empty → local-only tracing; no auth attempt, no crash.
    - Extra absent → early-return above; no call at all.
    """
    if _LOGFIRE is not None:
        _LOGFIRE.configure(
            service_name="monarch-cfo",
            send_to_logfire="if-token-present",
        )


@contextmanager
def agent_span(name: str, **attrs: Any) -> Any:
    """Yield a Logfire span named *name* with *attrs*, or a no-op context."""
    if _LOGFIRE is None:
        with nullcontext():
            yield
        return
    with _LOGFIRE.span(name, **attrs):
        yield
=== ruff cfg ===
[tool.ruff]
line-length = 100
target-version = "py312"
src = ["src", "tests"]

[tool.ruff.lint]
select = [
    "E", "F", "W",  # pycodestyle + pyflakes
    "I",            # isort
    "B",            # bugbear
    "UP",           # pyupgrade
    "SIM",          # simplify
    "RUF",          # ruff-specific
]
--
[tool.ruff.lint.per-file-ignores]
"tests/**" = ["B"]

[tool.ruff.lint.isort]
# `monarch_ingest` lives in the external public repo since M7 PR-4
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

{# ---- macros ---- #}
{%- macro year_nav(year, base_path) -%}
<nav class="year-nav">
  {% if year > 1900 %}
    <a href="{{ base_path }}/{{ year - 1 }}">← {{ year - 1 }}</a>
  {% endif %}
  {% if year < 9999 %}
    <a href="{{ base_path }}/{{ year + 1 }}">{{ year + 1 }} →</a>
  {% endif %}
</nav>
{%- endmacro -%}

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{% block title %}melon-monarch-cfo{% endblock %}</title>
    <link rel="stylesheet" href="/ui/static/app.css" />
    {# HTMX + Chart.js vendored assets land in later M6 PRs. #}
  </head>
  <body>
    <header class="site-header">
      <a href="/ui/" class="brand">melon-monarch-cfo</a>
      <nav class="site-nav">
        <a href="/ui/reports/annual/{{ latest_year }}">Annual report</a>
        <a href="/ui/net-worth">Net worth</a>
        <a href="/ui/transactions">Transactions</a>
        <a href="/ui/chat">Chat</a>
      </nav>
    </header>
    <main class="container">
      {% block content %}{% endblock %}
    </main>
    <footer class="site-footer">
      <small>Localhost-only. JSON API at
        <a href="/docs">/docs</a>.</small>
    </footer>
  </body>
</html>

1	[build-system]
2	requires = ["hatchling"]
3	build-backend = "hatchling.build"
4	
5	[project]
6	name = "melon-monarch-cfo"
7	version = "0.0.1"
8	description = "Personal-finance CFO and CSV ingest on top of Monarch."
9	readme = "README.md"
10	requires-python = ">=3.12,<3.13"
11	license = { file = "LICENSE" }
12	authors = [{ name = "melon-lab-com" }]
13	dependencies = [
14	    # The Monarch CSV ingest library (parsers, dedup hashing, ORM,
15	    # migrations, CLI) lives in its own MIT-licensed public repo
16	    # after M7 PR-4. Pin by commit SHA rather than `@main` so a
17	    # force-push upstream cannot retroactively alter our builds;
18	    # bump this line deliberately alongside a local test run.
19	    "melon-monarch-ingest @ git+https://github.com/melon-lab-com/melon-monarch-ingest@db78fe6",
20	    # FastAPI + Pydantic are cfo-specific (read API + reports layer).
21	    # SQLAlchemy / Alembic are transitive via melon-monarch-ingest.
22	    "pydantic>=2.7",
23	    "fastapi>=0.115",
24	    # Jinja2 templating for the HTMX frontend (M6). Served in-process
25	    # by FastAPI; no Node build step (plan §9). HTMX + Chart.js ship
26	    # as vendored static assets rather than package deps.
27	    "jinja2>=3.1",
28	]
29	
30	[project.scripts]
31	monarch-cfo = "monarch_cfo.cli:app"
32	
33	[project.optional-dependencies]
34	dev = [
35	    "pytest>=8.0",
36	    "pytest-cov>=5.0",
37	    "hypothesis>=6.100",
38	    # httpx is FastAPI's TestClient transport; only needed in tests.
39	    "httpx>=0.27",
40	    # Pin ruff and mypy to the same minor as the pre-commit hooks so the
41	    # linter / type-checker in the venv never diverges from the one
42	    # pre-commit enforces. Bump both sides together.
43	    "ruff~=0.15.11",
44	    "mypy~=1.20.1",
45	    "pre-commit>=3.8",
46	    # Typer is transitive via melon-monarch-ingest but tests that
47	    # drive the ingest CLI's `rules` subcommand need CliRunner; the
48	    # ingest lib already depends on it, we just surface it here so
49	    # `uv sync --extra dev` includes it.
50	    "typer>=0.13,<0.30",
51	    # pytest-recording gives us VCR cassette support for the Gemini
52	    # adapter smoke test. Network-replay keeps the smoke test hermetic
53	    # without pretending the wire protocol away (see ADR-0009).
54	    "pytest-recording>=0.13",
55	]
56	# ASGI server for running the read API locally — not a runtime dep
57	# because the CLI + ingest layer don't need it, and the test suite
58	# hits the app in-process via FastAPI's TestClient. Install with
59	# `uv sync --extra serve` when you actually want to serve HTTP.
60	serve = ["uvicorn>=0.29"]
61	# Playwright smoke tests for the M6 HTMX frontend. Heavy (~500MB
62	# browser binary) so kept opt-in. Install with
63	#   `uv sync --extra browser && uv run playwright install chromium`
64	# then run with
65	#   `uv run pytest -m browser`.
66	# The `browser` pytest marker is skipped by default (see
67	# `[tool.pytest.ini_options].addopts` → `-m "not browser"`).
68	browser = [
69	    "uvicorn>=0.29",
70	    "pytest-playwright>=0.5",
71	]
72	# Google Gemini SDK adapter (M8 primary provider, ADR-0009). Opt-in so
73	# a bare `uv sync` stays light; enable with
74	# `uv sync --extra chat-gemini`.
75	chat-gemini = ["google-genai>=1.0"]
76	# Anthropic Claude SDK adapter (M8.3). Opt-in for the same reason —
77	# enable with `uv sync --extra chat-anthropic`.
78	chat-anthropic = ["anthropic>=0.39"]
79	# OpenAI SDK adapter (M8.3). Opt-in; enable with
80	# `uv sync --extra chat-openai`.

default ok [] http://localhost:8000/auth/callback
parsed ['12345678901', '98765432109876']
full config ok
raised ok: no client id
raised ok: no client secret
raised ok: short cookie
raised ok: empty allowlist
raised ok: http non-localhost
raised ok: bad sub format
localhost http ok
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

            service_name="monarch-cfo",
            send_to_logfire="if-token-present",
        )


@contextmanager
def agent_span(name: str, **attrs: Any) -> Any:
    """Yield a Logfire span named *name* with *attrs*, or a no-op context."""
    if _LOGFIRE is None:
        with nullcontext():
            yield
        return
    with _LOGFIRE.span(name, **attrs):
        yield
      68 src/monarch_cfo/ai/telemetry.py
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

55	            service_name="monarch-cfo",
56	            send_to_logfire="if-token-present",
57	        )
58	
59	
60	@contextmanager
61	def agent_span(name: str, **attrs: Any) -> Any:
62	    """Yield a Logfire span named *name* with *attrs*, or a no-op context."""
63	    if _LOGFIRE is None:
64	        with nullcontext():
65	            yield
66	        return
67	    with _LOGFIRE.span(name, **attrs):
68	        yield

[tool.mypy]
python_version = "3.12"
strict = true
files = ["src", "tests", "scripts"]
mypy_path = ["src", "scripts"]
pretty = true
show_error_codes = true
explicit_package_bases = true

[[tool.mypy.overrides]]
[[tool.mypy.overrides]]
module = ["playwright.*", "uvicorn", "uvicorn.*"]
ignore_missing_imports = true

# google-genai ships no py.typed and is only installed via the
# opt-in `chat-gemini` extra. Treat as untyped so mypy on the base
# sync stays clean.
[[tool.mypy.overrides]]
[[tool.mypy.overrides]]
module = ["anthropic", "anthropic.*"]
ignore_missing_imports = true

[[tool.mypy.overrides]]
[[tool.mypy.overrides]]
module = ["logfire", "logfire.*"]
ignore_missing_imports = true

# ---- pytest ----
[tool.pytest.ini_options]
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

159:[[tool.mypy.overrides]]
168:[[tool.mypy.overrides]]
175:[[tool.mypy.overrides]]
183:[[tool.mypy.overrides]]
187:[[tool.mypy.overrides]]
193:[[tool.mypy.overrides]]
108:# Enable with `uv sync --extra logfire`.
109:logfire = ["logfire>=0.50"]
191:# logfire is only installed via the opt-in `logfire` extra; treat as
194:module = ["logfire", "logfire.*"]
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

155	pretty = true
156	show_error_codes = true
157	explicit_package_bases = true
158	
159	[[tool.mypy.overrides]]
160	module = ["tests.*"]
161	disallow_untyped_decorators = false
162	
163	# Playwright + uvicorn are only installed via the opt-in `browser`
164	# / `serve` extras; treat them as untyped when absent so mypy on
165	# the main check doesn't need the heavy deps. Browser tests and
166	# the recording script tolerate the runtime import through a
167	# pytestmark skip or direct runtime guard.
168	[[tool.mypy.overrides]]
169	module = ["playwright.*", "uvicorn", "uvicorn.*"]
170	ignore_missing_imports = true
171	
172	# google-genai ships no py.typed and is only installed via the
173	# opt-in `chat-gemini` extra. Treat as untyped so mypy on the base
174	# sync stays clean.
175	[[tool.mypy.overrides]]
176	module = ["google", "google.*", "google.genai", "google.genai.*"]
177	ignore_missing_imports = true
178	
179	# anthropic + openai SDKs are only installed via their opt-in extras.
180	# The adapters import them lazily inside __init__/stream() so mypy on
181	# the base sync never needs the modules present. Keep these in sync
182	# with the google.* override above.
183	[[tool.mypy.overrides]]
184	module = ["anthropic", "anthropic.*"]
185	ignore_missing_imports = true
186	
187	[[tool.mypy.overrides]]
188	module = ["openai", "openai.*"]
189	ignore_missing_imports = true
190	
191	# logfire is only installed via the opt-in `logfire` extra; treat as
192	# untyped so mypy on the base sync stays clean.
193	[[tool.mypy.overrides]]
194	module = ["logfire", "logfire.*"]
195	ignore_missing_imports = true
196	
197	# ---- pytest ----
198	[tool.pytest.ini_options]
199	minversion = "8.0"

1	{# ---- macros ---- #}
2	{%- macro year_nav(year, base_path) -%}
3	<nav class="year-nav">
4	  {% if year > 1900 %}
5	    <a href="{{ base_path }}/{{ year - 1 }}">← {{ year - 1 }}</a>
6	  {% endif %}
7	  {% if year < 9999 %}
8	    <a href="{{ base_path }}/{{ year + 1 }}">{{ year + 1 }} →</a>
9	  {% endif %}
10	</nav>
11	{%- endmacro -%}
12	
13	<!doctype html>
14	<html lang="en">
15	  <head>
16	    <meta charset="utf-8" />
17	    <meta name="viewport" content="width=device-width, initial-scale=1" />
18	    <title>{% block title %}melon-monarch-cfo{% endblock %}</title>
19	    <link rel="stylesheet" href="/ui/static/app.css" />
20	    {# HTMX + Chart.js vendored assets land in later M6 PRs. #}
21	  </head>
22	  <body>
23	    <header class="site-header">
24	      <a href="/ui/" class="brand">melon-monarch-cfo</a>
25	      <nav class="site-nav">
26	        <a href="/ui/reports/annual/{{ latest_year }}">Annual report</a>
27	        <a href="/ui/net-worth">Net worth</a>
28	        <a href="/ui/transactions">Transactions</a>
29	        <a href="/ui/chat">Chat</a>
30	      </nav>
31	    </header>
32	    <main class="container">
33	      {% block content %}{% endblock %}
34	    </main>
35	    <footer class="site-footer">
36	      <small>Localhost-only. JSON API at
37	        <a href="/docs">/docs</a>.</small>
38	    </footer>
39	  </body>
40	</html>
41	

RUF002 Docstring contains ambiguous `–` (EN DASH). Did you mean `-` (HYPHEN-MINUS)?
   --> src/monarch_cfo/api/auth.py:159:24
    |
157 |     decode would crash) and INSIDE `SessionMiddleware` (which provides
158 |     `request.session`). Inert when ``AUTH_ENABLED=false`` so local dev
159 |     and the existing M3–M8 test suites are untouched.
    |                        ^
160 |
161 |     On authenticated requests it also:
    |

Found 1 error.
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

All checks passed!
127 files already formatted
Success: no issues found in 127 source files
FAILED tests/api/integration/test_ui_breakouts.py::TestSubscriptionsPage::test_renders_with_year_heading
FAILED tests/api/integration/test_ui_breakouts.py::TestSubscriptionsPage::test_empty_year_shows_none_message
FAILED tests/api/integration/test_ui_breakouts.py::TestSubscriptionsPage::test_year_boundary_clamps_prev_link
FAILED tests/api/integration/test_ui_breakouts.py::TestOwnersPage::test_renders_with_year_heading
FAILED tests/api/integration/test_ui_breakouts.py::TestOwnersPage::test_empty_year_shows_no_data_message
FAILED tests/api/integration/test_ui_breakouts.py::TestOwnersPage::test_year_boundary_clamps_next_link
FAILED tests/api/test_auth_gate.py::test_gate_inert_when_auth_enabled_bootstrap_false
16 failed, 399 passed, 12 skipped in 84.15s (0:01:24)
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

    |     {% if request.state.csrftoken %}
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^
    |   File "/Users/openclaw-service/Documents/Claude/Projects/melon-monarch-cfo-pr4/.venv/lib/python3.12/site-packages/jinja2/environment.py", line 490, in getattr
    |     return getattr(obj, attribute)
    |            ^^^^^^^^^^^^^^^^^^^^^^^
    | jinja2.exceptions.UndefinedError: 'request' is undefined
--
    {% if request.state.csrftoken %}
    ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/openclaw-service/Documents/Claude/Projects/melon-monarch-cfo-pr4/.venv/lib/python3.12/site-packages/jinja2/environment.py", line 490, in getattr
    return getattr(obj, attribute)
           ^^^^^^^^^^^^^^^^^^^^^^^
jinja2.exceptions.UndefinedError: 'request' is undefined
--
        Unlike :meth:`getitem` the attribute *must* be a string.
        """
        try:
>           return getattr(obj, attribute)
                   ^^^^^^^^^^^^^^^^^^^^^^^
E           jinja2.exceptions.UndefinedError: 'request' is undefined

.venv/lib/python3.12/site-packages/jinja2/environment.py:490: UndefinedError
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

 M pyproject.toml
 M src/monarch_cfo/ai/telemetry.py
 M src/monarch_cfo/api/app.py
 M src/monarch_cfo/api/middleware.py
 M src/monarch_cfo/api/settings.py
 M src/monarch_cfo/web/templates/base.html
 M tests/api/test_auth_gate.py
 M uv.lock
?? src/monarch_cfo/api/auth.py
?? src/monarch_cfo/api/routers/auth.py
?? src/monarch_cfo/web/templates/auth/
pre-commit installed at /Users/openclaw-service/Documents/Claude/Projects/melon-monarch-cfo/.git/hooks/pre-commit
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

8242690 feat(auth): OAuth settings fields + fail-closed boot validators
b5a717b feat(auth): add authlib, slowapi, itsdangerous, httpx runtime deps
6cc4139 ADR-0012: Google OIDC + sub allowlist supersedes ADR-0008 (Tailscale-edge) (#117)
514fcc6 hotfix(gate): force GET on issues/comments — `gh api --field` was POSTing (#120)
M  src/monarch_cfo/api/app.py
A  src/monarch_cfo/api/auth.py
M  src/monarch_cfo/api/middleware.py
A  src/monarch_cfo/api/routers/auth.py
A  src/monarch_cfo/web/templates/auth/forbidden.html
A  src/monarch_cfo/web/templates/auth/logged_out.html
M  src/monarch_cfo/web/templates/base.html
M  tests/api/test_auth_gate.py
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

- exit code: 1

○
    │╲
    │ ○
    ○ ░
    ░    gitleaks

Finding:     auth_cookie_secret="REDACTED"
Secret:      REDACTED
RuleID:      generic-api-key
Entropy:     4.000000
File:        tests/api/test_auth_gate.py
Line:        99
Fingerprint: tests/api/test_auth_gate.py:generic-api-key:99

7:58AM INF 0 commits scanned.
7:58AM INF scanned ~22152 bytes (22.15 KB) in 83.7ms
7:58AM WRN leaks found: 1
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch

        # manually before committing.
        args: ["--check"]

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.20.1
    hooks:
      - id: mypy
        args: ["--config-file=pyproject.toml"]
        additional_dependencies:
          - "pytest>=8.0"
          - "pydantic>=2.7"
          - "pydantic-settings>=2.3"
          - "hypothesis>=6.100"
          - "fastapi>=0.115"
          - "httpx>=0.27"
          # SQLAlchemy + Alembic + Typer are transitive via
          # melon-monarch-ingest; pinning them here keeps the
          # pre-commit mypy env matching what the venv sees.
          - "sqlalchemy>=2.0.36"
          - "alembic>=1.13"
          - "typer>=0.13,<0.30"
          # The ingest library lives in its own public repo (M7 PR-4).
          # Mypy needs it on sys.path to resolve `monarch_ingest.*`
          # symbols; pin by git URL to the same commit the project
          # pyproject.toml installs at runtime.
          - "melon-monarch-ingest @ git+https://github.com/melon-lab-com/melon-monarch-ingest@db78fe6"

  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.0
    hooks:
Shell cwd was reset to /Users/openclaw-service/Documents/Claude/Projects/Monarch