kvitt/PLAN-K1.md

PLAN-K1: Card purchases, server

1. Goal

The server side of card purchases (FR-22, SPEC §9.12, D-158 to D-175): migration 0004 (server schema 4), the provider registry and the Enable Banking adapter, the connect flow with the callback page, fetching with de-duplication, the background poller, the endpoints E-36 to E-44, the link clearing on expense delete, the configuration, and the contract (OpenAPI, examples, migration text, the match_card_purchase vectors). It is a contract change (§14.8) and owns the contract the Android (K2) and web (K3) plans build on; it lands first.

2. Read first

1. SPEC §9.12 (all of it, CP-1 to CP-14) with the K0 answers recorded in v0.36, FR-22, §5.1, §6.1, §6.3, §7, §8 (§8.1, §8.4, §8.6, §8.7, §8.9), §9.6, §10.1, §10.2, §10.4, §10.5.2, §10.9, §10.10, §14.1 (§14.1.3 is the migration), §14.3 (error codes, wire objects, E-36 to E-44), §14.4.1, §14.4.4 step 7, §14.5.5, §14.5.8, §14.6, §14.7, §14.8; D-158 to D-180 (D-177 to D-179 are K0's results).
2. docs/spikes/K0-enable-banking.md (K0's findings) and docs/spikes/k0/app.py (a working client of the same API: JWT, /auth, /sessions, transactions with PSU headers and continuation_key).
3. Enable Banking's official API reference at implementation time (CLAUDE.md "Fast-moving APIs"): JWT claims, /aspsps, /auth, /sessions, /accounts/{uid}/transactions, DELETE /sessions/{id}, error codes (WRONG_TRANSACTIONS_PERIOD, rate-limit and expired-session errors), PSU headers.
4. server/README.md, src/router.rs, src/api/rate_limit.rs, src/tasks/, src/push/ (the FCM JWT and the reqwest client to reuse), src/api/landing.rs (the model for a bilingual HTML page), src/sync/ (where step 7 of §14.4.4 lives), tests/common/; contracts/openapi.yaml, tools/contracts-check.py; infra/pi/compose.yaml, infra/pi/.env.example, infra/dev/**, infra/npm/kvitt.conf, infra/README.md.
5. CLAUDE.md (server gate, no unwrap/expect, vendor adapters, contracts, personal data).

3. Already established

• Everything in §9.12 and §14 for cards is binding. K0 answered every TODO(spec) of §9.12 (SPEC v0.36, D-177 to D-179); none is left.
• K0's facts the server is built on (report docs/spikes/K0-enable-banking.md): ASPSP SJ Prio Mastercard, SE; maximum_consent_validity 180 days; required_psu_headers [psu-ip-address] (lower case: compare case-insensitively); one CARD account per session; background fetches without PSU headers accepted. At most 100 transactions per response and never a continuation_key: hence the windowed fetch of CP-7 (D-178: windows of at most 30 days, newest first, date_from and date_to; a window at 100 rows split in half down to one day; strategy never sent; WRONG_TRANSACTIONS_PERIOD ends the walk back; rows de-duplicated across windows by provider_ref, since a window may return rows dated a day or two outside it; only a complete fetch deletes vanished pending purchases). Mapping (D-179): merchant from remittance_information (one line), creditor.name absent; purchase_date = booking_date, else value_date; every row in SEK; entry_reference on every row, pending ones included; bank_transaction_code unused (a debit FEE is a purchase to handle); debtor.name, debtor_account (CPAN), creditor.postal_address, transaction_id never stored, logged or served.
• Assumed by the owner's decision, not measured (D-177): the partner's card links to the owner's application; a pending row keeps its entry_reference when booked; the session is reused on later days without BankID. §8 steps 5 to 7 verify them after deploy; the code needs nothing extra beyond the card_fetch counters booked_by_ref and booked_by_match (§8.7).
• Module layout (§14.7, D-160): src/cards/{mod.rs, providers.rs, api.rs, fetch.rs, poller.rs, callback.rs} and src/cards/enable_banking/ (the only code naming the vendor or parsing its JSON, behind a CardSource trait; mapped into Kvitt's own records before anything else sees them). Provider ids are open strings. No new crate unless the report justifies it.
• Credentials (D-161, D-175): the private key is read from KVITT_EB_KEY_FILE (and the member's), never logged, never in data/; JWT RS256 with kid = the application id, iss enablebanking.com, aud api.enablebanking.com, short expiry, cached like the FCM token. Session ids are never logged or sent to a client.
• The attempt's state is stored only as its SHA-256 hash; E-39's response does not reveal whether a state existed (CP-2).
• Card rows use card_sequence and never touch server_version (§14.1.3). E-40 mirrors §14.4.2's paging and cursor_ahead.
• Logging (§8.7): one aggregate card_fetch info line per fetch; no merchant, amount, purchase date, session id, account uid, code or state, no vendor response body. A test asserts the log output of a fetch and of a callback holds none of the fixture's merchant texts, amounts or the state.
• The poller (CP-4) runs from tasks::start and reads AppState.clock like the scheduler (§9.5), so tests drive it with a scripted clock.
• The vectors contracts/test-vectors/match_card_purchase.json and their stdlib Python reference in tools/contracts-check.py are this plan's (§14.5.8: the cases listed there at least); Rust implements no matching.
• web/src/api/schema.d.ts is regenerated in the same landing (npm run api:types in web/, §15.3); it is the one file under web/ this plan writes.

4. Owned paths

From SPEC §14.7 (row K1): server/**, contracts/**, tools/contracts-check.py, infra/pi/compose.yaml, infra/pi/.env.example, infra/dev/**, infra/npm/kvitt.conf, infra/README.md (step 4's block and a new "Card purchases" runbook section only), and web/src/api/schema.d.ts for its regeneration. Not SPEC.md, docs/**, android/**, the rest of web/**, .gitea/**.

5. Deliverables

• Migration 0004_card_purchases.sql in contracts/schema/migrations/ and server/crates/kvitt-server/migrations/, byte-identical (identity test), SCHEMA_VERSION 4, the importer's check follows; the migration test of §14.1.3; pruning of card_auth_attempts in the 04:00 job.
• The registry with the one entry of CP-1 (ASPSP SJ Prio Mastercard, SE), the adapter, the windowed fetch and the mapping of CP-7 (D-178, D-179), the de-duplication of CP-8, the consent rules of CP-6, the errors of CP-14, the disconnect of CP-12.
• E-36 to E-44 in the server and in contracts/openapi.yaml (the OpenAPI equality test passes), the four new error codes of §14.3.2, examples per §14.3.5, tools/contracts-check.py following them (operations E-1 to E-44).
• E-39's page with the strings of §13.3 "Card callback page", in both languages, with Cache-Control: no-store and Referrer-Policy: no-referrer.
• The link clearing in the sync push's delete step (§14.4.4 step 7) with a test (a linked expense deleted by the other user moves the purchase back, bumps card_version, writes no audit entry and no push).
• Rate limits of §8.6 for E-39, E-37 and E-42; authorization of §8.4 (the other user's ids are not_found) tested per endpoint.
• Integration tests against a local Enable Banking stub (an axum server in the test harness, pointed at by KVITT_EB_API_URL), fixtures built from K0's field-presence findings (D-179; the stub caps every response at 100 rows and returns no continuation key unless a test asks for one) with invented merchants and amounts: connect success, cancel, unknown and replayed state, expired attempt, several accounts, the windowed first fetch (180 days in 6 windows, date_from and date_to per window, no strategy parameter), a window at the 100-row cap split and refetched down to a truncated one-day window, rows dated outside their window de-duplicated, a continuation_key still followed, WRONG_TRANSACTIONS_PERIOD ending the walk back, an incomplete fetch deleting no pending purchase, pending then booked with the same entry_reference (the expected case on this card, booked_by_ref) and with a new one (CP-8's secondary rule, booked_by_match), a vanished pending row, a credit, a debit FEE row to handle, a non-SEK row, a zero row, rows carrying debtor.name, a CPAN debtor_account and a creditor address that are never stored, logged or served, background quota (4 per 24 hours, the 2-hour skip, no backlog after downtime), user-present PSU headers (the ASPSP's required set, all or none), the 60-second rule, consent expiry and renewal keeping purchases, disconnect with and without erase_handled, bank errors recorded per CP-14, E-40 paging and cursor_ahead, E-44's rules and expense_already_linked.
• Configuration (§10.4): KVITT_EB_APP_ID, KVITT_EB_KEY_FILE, KVITT_EB_MEMBER_APP_ID, KVITT_EB_MEMBER_KEY_FILE, KVITT_EB_API_URL; card features off with one start-up warning when missing.
• Infra: infra/pi/compose.yaml mounts ./secrets/cards:/secrets/cards:ro (create_host_path: false) and passes the two ids; infra/pi/.env.example gains the two optional keys (empty); infra/dev/up.sh copies infra/secrets/cards/ into infra/dev/secrets/cards/ (only that folder and the FCM key, D-117); infra/npm/kvitt.conf and infra/README.md step 4 carry the §10.5.2 block with the gate line and location = /cards/callback, checked with nginx -t and a request from a non-LAN address that reaches a stub upstream and leaves no access-log line; a "Card purchases" section in infra/README.md (key files, mode 0600, the folder 0700, .env ids, renewing every ≤180 days in the app, the card_fetch log line).

6. Steps

1. Worktree: from /Users/jhag/projects/kvitt, git worktree add .claude/worktrees/agent-k1 -b agent-k1 main; in it git reset --hard main, tools/install-git-hooks.sh. Copy from the main checkout only what a dev-stack check needs (infra/secrets/fcm-service-account.json); no real Enable Banking key is needed (tests use the stub and a key generated in the test). Confirm SPEC v0.36 (K0's answers) is on main; if not, stop and report.
2. cargo dependency check (cargo outdated is not installed; read Cargo.lock against crates.io for the crates you touch) and python3 tools/dependency-report/latest.py for the record.
3. Contract first: the migration text, the OpenAPI operations and examples, the vectors and the checker; then the server; then infra.
4. Never call the real Enable Banking API from a test. A manual end-to-end check with the real card is the owner's (§8), against the development stack on the Mac only if the orchestrator's brief allows it (it needs the Kvitt callback URL to reach the Mac, which it does not; so the real flow is checked after the Pi deploy).
5. Gates (§7). Commit on agent-k1, git rebase main, rerun the gates. Never merge, push or remove the worktree.

7. Gate

The server gate, from server/: cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo audit && cargo test; python3 tools/contracts-check.py; the web gate (npm run check in web/, for the regenerated types); docker compose -f infra/pi/compose.yaml --env-file infra/pi/.env.example config and docker compose -f infra/dev/compose.yaml --env-file infra/dev/.env.example config; shellcheck on changed scripts; the nginx check of §5. Report the real result lines.

8. HUMAN steps (relayed by the orchestrator in chat, after K1 has landed and its image is built)

1. No owner step: the key already exists on the Mac (K0), at docs/spikes/k0/.local/<application id>.pem in the main checkout (git-ignored); it is never downloaded again. The orchestrator copies it to infra/secrets/cards/enable-banking.pem in the main checkout (git-ignored, mode 0600, folder 0700; never committed). No enable-banking-member.pem: the partner's card is assumed to link to the owner's application (D-177; step 5 checks it).
2. On the Kvitt Pi in ~/kvitt: mkdir -p secrets/cards && chmod 700 secrets/cards; from the Mac copy the key with scp infra/secrets/cards/enable-banking.pem jacobhagstedt@<kvitt-pi-address>:kvitt/secrets/cards/, then on the Pi chmod 600 secrets/cards/*; copy the new compose.yaml; in .env set KVITT_EB_APP_ID= to the application id (the orchestrator gives it in chat: the key file's name before .pem) and leave KVITT_EB_MEMBER_APP_ID= empty.
3. NPM › Hosts › Proxy Hosts › the Kvitt row › Edit › Advanced: replace the Custom Nginx Configuration with the current infra/npm/kvitt.conf content (with the key in place of KVITT_APP_KEY), Save. Expected: row Online (yes/no).
4. Deploy the new image (§10.10: backup first, then KVITT_TAG, docker compose pull && docker compose up -d). Expected: server healthy (yes/no); curl -s localhost:8080/health shows "schema_version":4 (yes/no).

Verification of K0's assumptions (D-177), relayed once a client with the card screens runs against the deployed server (K2's release APK or an image with K3); the owner's own card is connected through that client's steps first (PLAN-K2 §8 step 1 or PLAN-K3 §8): 5. The partner's card (D-177 a): Enable Banking Control Panel › the Kvitt application › "Activate by linking accounts": Sweden, SJ Prio Mastercard, the partner signs with her own BankID. Expected: a second linked account (yes/no; if refused, the exact message). Then on her phone: Inställningar › Anslut kort › SJ Prio Mastercard › "Anslut med BankID", she signs. Expected: "Kortet är anslutet" and Kortköp lists her purchases (yes/no). If either fails, the orchestrator plans the fallback of D-175 (her own application, KVITT_EB_MEMBER_APP_ID). 6. The next day, without BankID (D-177 c, and CP-5's PSU headers from the Pi): during the day (07:00 to 22:00) open Kortköp; before tapping anything, "Uppdaterad" shows a time within the last 5 hours (a background fetch ran without BankID, yes/no). Then "Uppdatera". Expected: it updates without asking for BankID (yes/no). 7. Pending to booked (D-177 b), a few days after connecting: a purchase that showed "Preliminär" now shows without it, listed once, not twice (yes/no). Then on the Pi in ~/kvitt: docker compose logs server | grep card_fetch | tail -n 20, and paste the output in chat (aggregate counts only, no purchase data): the orchestrator checks that booked_by_ref counts the bookings and booked_by_match stays 0; if booked_by_match carries them instead, the assumption was wrong but CP-8's secondary rule handled it, and the orchestrator records that in the spec.

9. Out of scope

• The Android app (K2) and the web pages (K3); docs/ux/strings.csv (K2).
• SPEC.md, docs/decisions.md (proposed in the report); .gitea/** (the workflow needs no change: server/** and contracts/** already trigger it).
• Push for card purchases, bulk add, automatic linking (D-171).

10. Report

• Branch agent-k1, head commit after rebasing; gate result lines (server tests, contracts-check count, web gate, compose config, nginx check).
• Every K0 default that was kept, and every deviation from §9.12 or §14 with the proposed SPEC text and decision entry (numbered from the brief): in particular the exact OpenAPI shapes if they differ from §14.3.3, the vendor error codes mapped to CP-14, the PSU header handling.
• Contract files changed; web/src/api/schema.d.ts regenerated; the owner steps worded for relay; open questions with SPEC section numbers.

11. Numbering

Server schema 4 (migration 0004), sync protocol and push payload unchanged; decisions from the start prompt (TODO(spec) if none was given). Proposed spec text goes into SPEC v0.37 (v0.36 recorded K0's results; K1, K2 and K3 share v0.37, recorded by a docs agent when they land).