kvitt/PLAN-M3.md

PLAN-M3: Server core API

1. Goal

Implement the REST surface of the server other than sync: invites and pairing, profile and pictures, devices, accounts, categories, recurring templates, the settlement proposal, APK serving, the invite landing page, rate limiting, and the bootstrap and pair-device subcommands. Every endpoint is covered by integration tests for each error code it can return.

2. Read first

1. SPEC §7 API outline.
2. SPEC §14.3 OpenAPI 3.1 outline: 14.3.1 Common rules, 14.3.2 Error shape and error codes, 14.3.3 Wire objects, 14.3.4 Endpoints (E-2 to E-30, E-33), 14.3.5 Examples as contract.
3. SPEC §4 FR-1 Server bootstrap, FR-2 Invites and pairing, FR-3 Devices and revocation, FR-4 Profiles, FR-5 Household gate, FR-6 Expense accounts, FR-7 Categories, FR-9 Recurring expenses (AC-9.1, AC-9.7, AC-9.8), FR-11 AC-11.8, FR-16 AC-16.1.
4. SPEC §8.2 Device tokens, §8.3 Invite codes, §8.4 Authorization rules, §8.5 Transport (X-Forwarded-For), §8.6 Rate limiting and input limits, §8.7 Privacy and logging.
5. SPEC §9.4 Settlement allocation proposal, §9.5 Recurring generation (resume rule, next_occurrence_date, due-period generation on create), §9.6 Limits and validation, §9.7 Icon and colour tokens, §9.10 Other edge cases.
6. SPEC §10.4 Server configuration and CLI (bootstrap, pair-device), §10.6 APK hosting and release (latest.json, file name pattern).
7. SPEC §14.1 SQLite schema v1 and server-side rules; §14.5.2 Functions (propose_allocation).
8. SPEC §11.2 (row M3), §11.3, §14.7, §14.8.
9. Files: contracts/openapi.yaml, contracts/examples/**, the M2a code under server/ (router, error, auth, wire, db), CLAUDE.md (BUILD AND VERIFY, ARCHITECTURE RULES, ANTI-PATTERNS).

3. Already established

• Routes, the utoipa ApiDoc, error type, auth extractors, wire objects, DB pool and sequence exist from M2a; M3 fills in handler bodies in its own files (§11.3).
• bootstrap: no users → cancel any pending admin_setup, create a new one, print code, link <KVITT_PUBLIC_URL>/i/<CODE>, expiry, exit 0; users exist → already initialized on stderr, exit 2 (AC-1.1 to AC-1.3, §10.4). pair-device --user <id>: device invite, exit 3 for unknown user (AC-1.6, §10.4).
• Invite codes: 12 Crockford base32 characters, displayed XXXX-XXXX-XXXX, normalised (uppercase, strip - and spaces, O→0, I/L→1), stored as SHA-256 hex, single-use, 72 h expiry, cancellable; failures are invite_invalid without saying why (§8.3, AC-2.3).
• Tokens: kvt_ + base64url(32 CSPRNG bytes) without padding, 47 characters, stored as SHA-256 hex; never logged (§8.2).
• Partner invite refused with household_full at two users; a new partner invite cancels a pending one (AC-2.1). Accept returns token, user, device, household (AC-2.4, E-3).
• Landing page GET /i/{code}: Swedish if Accept-Language prefers sv, else English; app name, "Download Kvitt" to the latest APK, "Open in Kvitt" to kvitt://invite?server=<urlencoded KVITT_PUBLIC_URL>&code=<CODE>, code in groups of 4, one sentence of instructions; no validity hint, no personal data; any 1 to 32 character code gets 200, else 404 HTML (AC-2.5, E-4).
• Rate limits: unauthenticated 60/min per IP, authenticated 600/min per device, 429 rate_limited with Retry-After; more than 10 failed accepts per IP in 60 minutes → rate_limited for the rest of the window; in memory; X-Forwarded-For trusted only from the Caddy peer (KVITT_TRUSTED_PROXY) (§8.6, AC-2.12, §8.5, §10.4).
• Pictures: JPEG/PNG/WebP up to 5 MiB and 8000 × 8000, EXIF orientation applied, centre-crop square, JPEG q85 at 512 and 128, metadata stripped, picture_version incremented, files pictures/<user_id>/<v>-512.jpg and -128.jpg, older versions deleted after success; E-11 headers ETag, Cache-Control: private, max-age=31536000, immutable, size 128|512 default 512 (AC-4.4, §10.4, E-9 to E-11).
• Household gate: account create, template create and any expense or settlement mutation → household_incomplete below two users (AC-5.2).
• Accounts: names unique among non-deleted, case-insensitive after trim (Unicode lowercase) via name_key; delete only when unreferenced (account_not_empty), soft delete; ratio change affects only later expenses (FR-6).
• Categories: icon and colour validated against §9.7 lists; new sort_order = max + 10; name: null resets a default name, category_is_default on a non-default; delete blocked by use (category_in_use) or default key (category_is_default); no uniqueness (FR-7, E-23 to E-27).
• Recurring templates: E-28 generates an already-due period before responding; E-29 split_mode and splits together; resume does not backfill; next_occurrence_date per §9.5 (§14.3.4, §9.5).
• Every REST write that changes a synced row takes a new server_version in a BEGIN IMMEDIATE transaction and returns the row in wire form (§7, §14.1).
• E-33 uses kvitt-domain::propose_allocation over non-deleted rows, exclude_settlement_id honoured (AC-11.8, E-33).
• APK: GET /apk/latest reads apk/latest.json on each request; GET /apk/files/{file_name} only for ^kvitt-[0-9]+\.apk$ that exists, application/vnd.android.package-archive, Content-Length (§10.6, E-5, E-6).
• last_seen_at/app_version_code update at most hourly (§8.2); devices never deleted (AC-3.5).

4. Owned paths

From SPEC §14.7, verbatim: kvitt-server: src/api/{invites,landing,me,pictures,devices,accounts,categories,recurring,proposal,apk}.rs, src/ratelimit.rs, src/cli/{bootstrap,pair_device}.rs, tests/core_*.rs (owner M3; after landing: "later server plans"). Also from §14.7: M3 "may add a dependency line to a crate's Cargo.toml (second to land resolves Cargo.lock on rebase)" and "may add one line per new module to mod.rs files they need".

Edit nothing outside these paths; a needed change elsewhere is a contract request to the orchestrator.

Open points the orchestrator must settle in the start prompt's notes: (a) E-28's due-period generation, E-29's resume rule and next_occurrence_date use §9.5 logic, the audit writer and the push queue, which §14.7 places in M4's src/scheduler/**, src/audit/** and src/push/** while M3 and M4 run in parallel: which plan writes the shared generation function and in which order they land; (b) E-2 GET /setup/status is listed for M3 in §11.2 but implemented by M2a (src/api/setup.rs); M3 only tests it; (c) how the rate-limit layer and body limits attach to M2a's router.rs; (d) the landing page text (one sentence of instructions, English and Swedish) is not in §13 or docs/ux/strings.csv: who writes the Swedish copy.

5. Deliverables

• src/api/invites.rs: E-3, E-12, E-13, E-14.
• src/api/landing.rs: E-4 HTML in sv and en.
• src/api/me.rs: E-7, E-8.
• src/api/pictures.rs: E-9, E-10, E-11.
• src/api/devices.rs: E-15, E-16, E-17.
• src/api/accounts.rs: E-18 to E-22.
• src/api/categories.rs: E-23 to E-27.
• src/api/recurring.rs: E-28 to E-30.
• src/api/proposal.rs: E-33.
• src/api/apk.rs: E-5, E-6.
• src/ratelimit.rs: §8.6 limits and AC-2.12.
• src/cli/bootstrap.rs, src/cli/pair_device.rs: FR-1 subcommands.
• tests/core_*.rs: one or more integration test files per endpoint group covering success and every error code listed for each endpoint in §14.3.4, responses compared with contracts/examples/.

6. Steps

1. Worktree. From the main checkout /Users/jhag/projects/kvitt: git worktree add .claude/worktrees/agent-m3 -b agent-m3 main, then in .claude/worktrees/agent-m3: git reset --hard main. No git-ignored files are needed; copy none. Run tools/install-git-hooks.sh.
2. Read §2 in order. Confirm M2a has landed (server/crates/kvitt-server/src/router.rs exists on main); if not, stop and report.
3. Versions: any crate added (for example image decoding, HTML templating, a rate limiter) at its latest stable version from crates.io / docs.rs; confirm current API usage from official docs; record each.
4. Build the test harness first in tests/core_common.rs or equivalent (temp SQLite, injected clock, seeded two-user household helper, request helper that sends X-Kvitt-Protocol: 1).
5. Implement in this order, each with its tests before moving on: bootstrap and pair-device; E-3 accept (all three kinds) and E-12 to E-14; E-7, E-8; E-15 to E-17; E-18 to E-22; E-23 to E-27; E-28 to E-30 (per open point a); E-33; E-9 to E-11; E-5, E-6; E-4; rate limiting (per open point c).
6. For each endpoint, test every error code §14.3.4 lists for it, plus household_incomplete where AC-5.2 applies and forbidden for member on admin routes.
7. Compare response bodies with contracts/examples/<E-id>-<name>/response.json by JSON value (ids and timestamps normalised as the examples allow).
8. Check logs from one test run contain no token, code, name, description, note or amount (§8.7).
9. Run the gate (§7). Commit on agent-m3, git rebase main (resolve Cargo.lock if M4 landed first), rerun the gate. Never merge, push or remove the worktree.

7. Gate

From SPEC §11.2, verbatim: "Server gate; integration tests per endpoint and per error code listed for it". Command, from server/: cargo fmt --check && cargo clippy -- -D warnings && cargo test. Green means: all three exit 0 in this session; test result: lines show 0 failed; the report contains a table endpoint × error code → test name with no empty cell for E-2 to E-30 and E-33.

8. HUMAN steps

From SPEC §11.2, verbatim: "none".

9. Out of scope

• E-31, E-32 sync, audit writer and diff, push sender, scheduler, rotate-epoch, sync_mutations pruning (M4), except what open point (a) assigns.
• Router, error type, auth extractor, wire types, migrations (M2a; contract requests only).
• The importer (M9); infra/ (M2c-dev, M2c-pi); any Android work.
• Semantic changes to contracts/**.

10. Report

• Branch agent-m3, head commit hash after rebasing on main.
• Gate output: fmt and clippy exit status, every test result: line.
• The endpoint × error code → test table.
• Versions of crates added, with sources.
• How open points (a) to (d) were resolved.
• Numbering used (decision ids, spec version) or TODO(spec) occurrences.
• Contract requests (anything needed in M2a's files), open questions, spec gaps (with section numbers).

11. Numbering

Decision ids, spec version and schema version are assigned by the orchestrator in the start prompt; use TODO(spec) if none was given.