screen-locker/docs/DOCS-workout-poke-contract.md
Krzysztof kuhy Rudnicki ad849aff02 Drop gaming from credit toast and poke
Pin earned-time-v0.22.0. The toast and the poke reply show only the
shutdown gain; gaming_budget_minutes leaves the reply and the phone
app's result line (an older PC's field is ignored).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWViGJJaqBKGr1Hbppr
2026-11-16 16:13:46 +01:00

79 lines
3.4 KiB
Markdown

# Workout poke: phone -> PC wire contract (v1)
The phone sends a finished StrongLifts session straight to the PC over the
home LAN, so the credit (shutdown time, notification) lands in
under a second instead of waiting for the GitHub/Firebase round trip. The
normal sync push still runs in parallel; the PC dedups by record id, so a
session that arrives both ways is credited once.
## Transport
- `POST http://<pc-host>:8774/v1/workout`, `Content-Type: application/json`.
(8773 until 2026-10-10: that is book-guard's desktop wrapper's port.)
- `<pc-host>` is a phone setting, default `192.168.1.43` (static on the PC).
LAN only: the PC firewall accepts tcp/8774 from `192.168.1.0/24` and nothing
else. No WireGuard. Off the home LAN the poke fails fast and the regular
sync is the only path.
- Header `X-Poke-Signature: <hex HMAC-SHA256(key, raw body bytes)>`.
The PC verifies the MAC over the bytes **as received** and only then parses
them. Neither side may re-serialize JSON to compute or check the MAC.
- Key: 32 random bytes, hex, PC copy at `~/.config/workout_poke/key`
(mode 600); phone copy in the Android keystore, put there by
`scripts/pair_phone.sh` over adb.
## Request body
```json
{"v":1,"sent_at_ms":<int epoch ms>,"nonce":"<uuid4>","sandbox":<bool>,
"record_id":"<sync record id>","payload":{<session exactly as synced>}}
```
- `payload` is the same map the phone puts in its sync log for the session;
the PC feeds `(record_id, payload)` to `ingest_session_records`, which
re-validates it (never trusts `succeeded`).
- `sandbox` is inside the signed body. A sandbox request is verified, timed
and answered, but **never written anywhere** and never credited.
## PC checks, in order (each rejection is logged at warning)
1. Signature matches -> else `401`.
2. `|now - sent_at_ms| <= 120 s` -> else `401` (replay window).
3. `nonce` not seen within the window -> else `409`.
4. `v == 1` and fields present -> else `400`.
## Response (always JSON)
```json
{"ok":<bool>,"credited":<bool>,"duplicate":<bool>,"sandbox":<bool>,
"shutdown":"HH:MM"|null,"pc_ms":<int>,
"reason":"<sentence a human can act on>"}
```
The phone must treat `shutdown` as nullable. `gaming_budget_minutes` was dropped
when the gaming budget was removed (2026-11-16); a phone ignores it if an older
PC still sends it.
Outcomes of a verified (200) request:
| case | ok | credited | duplicate |
|---|---|---|---|
| newly credited | true | true | false |
| already in `log.json` (e.g. the sync got there first) | true | false | true |
| logged, but today's credit slot was already paid by another copy of the same workout | true | false | false |
| signed but does not count (too short, no date): `reason` says why | false | false | false |
| sandbox | true | false | false |
Refusals are never 200. Besides the four checks above, the PC may answer
`404` (wrong path), `405` (not POST), `411` (no Content-Length), `413` (body
over 64 KiB) and `500` (internal error; the regular sync still credits). All
of them carry the same JSON shape with `ok:false` and `shutdown`
`null`. The PC answers a `413` without reading
the body, so the phone may see a connection reset instead of the reply.
## Shared fixture
`contracts/workout_poke_v1.json` holds a literal key, body and expected
signature (with a float and non-ASCII text, the usual cross-language traps).
The Python receiver and the Dart sender both test against it, so a drift on
either side fails that side's tests.