feat(fobs): link a key fob in a window and resolve it for the Zählwerk

[patrick-hermann-sva]

This builds #321, the Schmetterpause half of checking in at the table by fob. zaehlwerk-firmware#63 reads a fob and a button press. zaehlwerk#92 claims the half, but zaehlwerk cannot know who the fob belongs to. That lookup is here. Every successful resolve also records the check-in that ADR-0024 accepts as proof in place of an operator.

The design is ADR-0025, in #324. This PR is based on main rather than stacked on it, so either can merge first.

Changes

Data (feat(db)): two additive migrations.

• checkins stores player, half (left/right, as zaehlwerk's ADR-0005 names them), method (phone/rfid) and time. Nothing points at it yet. Linking a result to its check-ins is Results from checked-in matches: no operator needed; pending by default, auto-accept as a setting #320.
• fob_link_window holds at most one row, enforced by a primary key that can only be true. Opening is a single upsert that replaces the row only if it has expired or belongs to the same player. Consuming is delete … returning. So at most one window is open, even across replicas, without a lock or Redis.
• identities.last_used_at is added (nullable).

Resolve and link (feat(fobs)):

• POST /api/identities/rfid/resolve sits on the outer mux next to the other /api routes. It exists only with both SP_SCOREBOARD_TOKEN and SP_RFID_UID_KEY set. Without the key, startup logs fobs are off: SP_RFID_UID_KEY is not set.
• The logic lives in auth.Fobs, beside the cookie authenticator (invariant 4: handlers don't know how a fob is stored). The subject is HMAC-SHA256(key, "rfid:" || uid_bytes). The UID is normalised from hex with optional :/-/space and must be 4, 7 or 10 bytes.
• A known fob resolves to its owner and never consumes somebody else's open window.
• An unknown fob outside a window gets 404 with an empty body. No row is written, and the log says only unknown fob. Malformed bodies get a fixed message, because Go's decode error can quote the input, and the input is a card number.
• The profile (own page only) gets a Schlüsselanhänger card. „Anhänger koppeln“ opens a 60 s window. The card then polls every 2 s and turns into „Anhänger gekoppelt“ once the fob arrives, or says the window ran out. If somebody else holds the window, the player is told how many seconds to wait. Each fob is listed with the first 6 hex characters of its hash, the link date and the last-used time, and can be removed. Removing checks ownership.
• /admin shows SP_RFID_UID_KEY on/off next to the other switches.

Deployment (feat(deploy)): SP_RFID_UID_KEY is wired into every path in the same change, as the scoreboard token was:

• kcl fobsEnabled plus the Vault property rfid-uid-key;
• terraform rfid_uid_key as a Container Apps secret, with a ≥32-character validation and its own test;
• compose, docs/deployment.md and kcl/README.md;
• a note in docs/backup-restore.md that fobs only survive a move together with their key.

Verified

• go generate ./... produced no churn. gofmt is clean, and go build ./... passes.
• go test -race ./... is green.
• New handler tests in internal/server/fob_test.go cover every acceptance point of feat: RFID fobs as an identity — link a fob in a short window, resolve it for zaehlwerk #321:
  • a fob linked in the window resolves afterwards;
  • every resolve returns a new check-in id;
  • an unknown fob produces no row and no UID in the log, checked by capturing the debug-level log;
  • two windows cannot be open at once;
  • a player can see and remove their fobs, and nobody can remove somebody else's;
  • without the key the route returns 404 and the log line is written.
  • Also covered: expiry, cancelling, the poll seeing the fob arrive, and malformed input not echoing the UID.
• The Postgres repository tests (internal/repository/postgres/fob_test.go: the window upsert rules, consume-once, close-only-your-own, the check-in constraint, Touch, and deleting a player together with their check-in and window) ran against a real Postgres 17: a throwaway container with SP_TEST_DATABASE_URL pointed at a _test database. They passed and were not skipped.
• task kcl:check passes: all profiles render, and with fobsEnabled=true the ExternalSecret carries SP_RFID_UID_KEY from rfid-uid-key.
• terraform test passes 11 of 11, including the new short_rfid_uid_key_is_refused. terraform fmt -check is clean.
• Looked at, not just tested: the profile card at 390 px and 1000 px, served from the in-memory store with the seed fixture, in both states (linked fob, open window). scrollWidth == clientWidth holds at both widths in both states. Screenshots were taken locally and are not attached here.

Not verified:

• No real fob and no real zaehlwerk. The resolve contract is tested only from this side. zaehlwerk#92 has to send {"uid", "half"} with half as left/right.
• The window race between two replicas is proven only through the upsert's semantics and the single-connection repository test, not under real concurrent load.

Left open, deliberately

• Wording for players: „Schlüsselanhänger“/„Anhänger koppeln“ instead of „Fob koppeln“ as feat: RFID fobs as an identity — link a fob in a short window, resolve it for zaehlwerk #321 wrote it. „Fob“ is jargon to most players. This is product copy, so it is your call; changing it is one line in fobs.templ.
• Check-ins are not used yet. Validating and consuming the two check-in ids in POST /api/results (ADR-0024) is Results from checked-in matches: no operator needed; pending by default, auto-accept as a setting #320. Until then a check-in is only a record.
• Phone check-in. checkins.method already allows phone, but nothing creates such a row. That path still needs its own design (see docs(adr): make a fob an identity, linked only in a window #324).
• The window is not per table. There is one row for one table (Several tables: record, schedule, book — in three stages, once a second table stands in the office #280).
• SP_RFID_UID_KEY deviates from feat: RFID fobs as an identity — link a fob in a short window, resolve it for zaehlwerk #321's RFID_UID_KEY because every variable this app reads carries the SP_ prefix.

Closes #321
Refs #323, #324, #320

🤖 Generated with Claude Code