hsa-app/plan.md

HSA Receipt Tracker — Implementation Plan (v1)

Companion to spec.md. This is the how and the order; spec.md is the what. Strategy: red/green (write a failing test, make it pass) wherever the logic is pure and deterministic. Where behaviour depends on the live world (the real OIDC round-trip against Authelia, a camera, a browser), we verify manually instead and say so explicitly.

---

Decisions locked (from consultation)

Topic	Decision
Stack	Go — single static binary, systemd in LXC, SQLite
App domain	hsa.maisym.com
Auth issuer	auth.maisym.com
OIDC client	Confidential + PKCE
Auth group	hsa-users (gates access; not in group → 403)
Session	Encrypted, signed cookie (stateless, no server-side store)
Edit	Designed-for, not built in v1
Export	/export/db only, with include-blobs yes/no toggle
Files	PDF + images, accepted as-is; client compression is phase 2
View list/detail	Out of scope for v1
Auth testing	Unit-test pure pieces; verify live round-trip manually

---

Build order (milestones)

• M0 — Auth flow only. App authenticates against live Authelia and shows a "you're logged in" result, including the group gate. This is the first thing JM wants to see running. Detailed below.
• M1 — Storage layer. SQLite schema + receipts data access (insert, soft-delete, fetch). Dual-write (filesystem + BLOB) in one transaction.
• M2 — Upload flow. Mobile-first capture/upload form (amount, date, category), PDF+image handling, validation, store both copies, confirmation page.
• M3 — Export. GET /export/db with include-blobs toggle, via point-in-time snapshot (never the live DB file).
• Phase 2 / later. Client-side image compression; edit functionality.

Only M0 is planned in detail below — we plan the next milestone when we get there, so the plan stays honest.

---

Milestone 0 — Auth flow

Goal / acceptance: Open hsa.maisym.com in a phone/browser → redirected to auth.maisym.com → log in → land back on a page that reads roughly:

Logged in as jeanmi.tremblay@gmail.com · groups: [hsa-users] · access: GRANTED

…and a user who is not in hsa-users gets a 403. That single screen proves the entire chain: OIDC+PKCE round-trip, identity claims, group claim, and the authorization gate.

Step 0.1 — Prerequisites (setup, not tested)

• Install Go toolchain (not currently present on this machine).
• git init the repo.
• go mod init — module path TBD (see Open Questions). Default proposal: maisym.com/hsa.
• Project skeleton: cmd/hsa/main.go, internal/auth/, internal/web/, internal/config/.

Step 0.2 — JM's Authelia-side config (your action; app can't do this)

Enumerated here so the app and Authelia agree on every value:

• Create group hsa-users; add both users.
• Register a confidential OIDC client in identity_providers.oidc.clients:
  • client_id: e.g. hsa-tracker
  • client_secret: random, stored hashed (via authelia crypto hash generate)
  • redirect_uris: https://hsa.maisym.com/callback (+ a dev redirect, e.g. http://localhost:8080/callback — see Open Questions)
  • scopes: openid, profile, email, groups
  • response_types: code; grant_types: authorization_code
  • PKCE: require S256
  • token endpoint auth method: client_secret_basic (confirm at execution)
• Reload Authelia.

Step 0.3 — App config (env vars)

ISSUER_URL, CLIENT_ID, CLIENT_SECRET, REDIRECT_URL, REQUIRED_GROUP (=hsa-users), SESSION_KEY (cookie encryption key), LISTEN_ADDR. Loaded and validated at startup (fail fast if any missing).

Step 0.4 — Red/green units (pure logic)

Each is a failing test first, then the implementation:

1. PKCE — GenerateVerifier() (43–128 URL-safe chars) and ChallengeS256(verifier). Test with the RFC 7636 Appendix B known vector (fixed verifier → known challenge) so the encoding is provably correct.
2. State / nonce — sufficient length, two calls differ (CSRF + replay defense).
3. Session codec — Encode(session)/Decode(cookie) round-trips; a tampered value is rejected; a value signed with the wrong key is rejected.
4. Authorization decision — IsAuthorized(groups, required) bool. Table tests: in-group → true; empty groups → false; other-group-only → false. This is the 403 rule, tested in isolation.
5. Authorize-URL builder — construct oauth2.Config with fixed endpoints (no network/discovery) and assert AuthCodeURL carries state, code_challenge, code_challenge_method=S256, and the right scopes.

Step 0.5 — Handlers tested via httptest (no live Authelia)

• GET /healthz → 200.
• GET / (protected) behind RequireAuth: forged valid session cookie → 200 and the page shows identity + groups; no/invalid cookie → 302 to /login.
• GET /logout → clears cookie, 302.

Step 0.6 — Live round-trip (manual verification — the M0 acceptance)

Not unit-testable (needs real Authelia + a human clicking login):

• GET /login → builds PKCE+state, stashes verifier/state in a short-lived cookie, 302 to Authelia's authorize endpoint.
• GET /callback → validate state, exchange code (with PKCE verifier), verify the ID token, extract claims, run IsAuthorized, set the session cookie, redirect to /. (The pure sub-parts — claim extraction, group gate — are already red/green from 0.4.)

Manual test script:

1. Run the app with real config (locally with the dev redirect, or deployed in the LXC behind Caddy).
2. Browser → app → redirected to auth.maisym.com → log in → returned to success page showing identity + [hsa-users] + GRANTED.
3. Negative path: an account not in hsa-users → 403.

M0 done =

All red/green units green, httptest handler tests green, and the manual round-trip (both positive and 403 paths) confirmed against live Authelia.

---

Open questions (revisit before/at execution — not guessing)

1. Module path / repo name — maisym.com/hsa? a GitHub path? Will there be a GitHub remote, or local-only for now?
2. Dev redirect URI — do you want to test M0 locally first (needs a http://localhost:8080/callback redirect added to the Authelia client), or deploy-to-LXC-first and test only at https://hsa.maisym.com?
3. Token endpoint auth method — client_secret_basic vs _post. Pick when we wire it; basic is the default assumption.
4. Infra ownership — Caddy vhost + systemd unit: you handle, or you want me to draft the unit file / Caddyfile snippet as part of M0?

Deferred to later milestones (noted so we don't design against them)

• SQLite driver choice — lean modernc.org/sqlite (pure Go, keeps the static binary, no cgo). Decide at M1.
• Edit (v1: schema/storage must not preclude it — on a future edit, update FS file and BLOB in one transaction, keep file_path UUID stable).
• Client-side image compression (phase 2): re-encode camera images to JPEG/WebP at a quality factor before upload; PDFs pass through untouched.