Tray ↔ Web Auth + Multi-Machine Sync

[ntatschner]

Problem

The tray and web companion currently authenticate independently, and there is no first-class concept of "the same user on two machines". A user who runs the tray on a desktop and a laptop has no pairing flow; concurrent captures from two machines can also produce duplicate events server-side.

Approach

Device-code OIDC flow for pairing the tray to the web companion. The web side initiates pairing; the tray surfaces a one-time device code; the user confirms on the trusted device. Each paired device is independently revocable from Settings.

Server-side dedup of overlapping captures when the same user runs the tray on two machines simultaneously — the canonical event-id derivation must collapse duplicates rather than store both.

Acceptance criteria

• Device-code pairing flow works tray → web → confirm
• Per-device revocation in Settings (each device shows last-seen + revoke action)
• Concurrent-capture dedup verified by an integration test (two trays, same user, same window)
• Revoked devices stop accepting new pushes within one heartbeat cycle
• Pairing audit-logged via the existing audit_log chain

Risks / Open questions

• Device-code UX: tray must surface the code prominently without leaking it to logs/screenshots
• Dedup key choice — collision risk if two captures of the same event have slightly different timestamps
• Revocation race — what happens to an in-flight push from a device revoked mid-batch? (likely needs server-side rejection with clear status code)
• Pairing flow needs to handle the case where the user has zero web-side devices yet (chicken-and-egg)

Original draft notes

Device-code OIDC for tray ↔ web pairing. Per-device revocation in Settings. Server-side dedup of overlapping captures when the same user runs the tray on two machines simultaneously.

---

Tracking

• Roadmap slug: tray-web-auth-multi-machine-sync
• Public roadmap: https://starstats.app/roadmap/tray-web-auth-multi-machine-sync
• Project board: https://github.com/orgs/TheCodeSaiyan/projects/1
• eta_band: tbd (set on the Project board when scoping firms up)
• Channel targeting: likely live + beta + alpha — foundational auth/sync feature; needs validation on each track before going live. Add channel/<name> labels when targeting firms up.