feat(devices): pairing codes replace the registration broadcast
A pending device registration used to be announced to EVERY account's Devices page, and whoever clicked Approve first bound the device — and its freshly minted sync token — to their account. Worse, the pending card displayed the registration UUID, which is also the bearer credential on the unauthenticated /api/devices/register/status poll channel: any family user who could see the list already held everything needed to take the device. On a family server that is a wrong-account-binding bug (accidental or deliberate); this commit removes the class of problem rather than patching the race. The new model is the Netflix/YouTube TV device flow: the registering device displays a 6-digit pairing code, and the only person who can read it — whoever holds the device — types it into THEIR account on the Devices page. Possession of the device screen becomes the credential; nothing is broadcast; the reject-on-someone-else's-behalf hole dies with the list. Server changes: - POST /api/devices/register now mints pairing_code (crypto/rand, rejection-sampled for uniformity, collision-checked against live registrations) and retires prior unclaimed registrations with the same device_identifier, so re-registering leaves exactly one live attempt. - POST /api/devices/claim (JWT) binds the registration behind a code to the caller's account, reusing the rotate-or-create approval logic factored out of ApproveDevice (shared bindRegistrationToUser helper; the Android self-approval route keeps working unchanged). - POST /api/devices/claim/lookup (JWT) returns the confirm-card data without binding. Lookup and claim share a per-account budget (12 attempts/min, DeviceRateLimiter gained a claim case) — the 1M-code space over a 5-minute TTL makes guessing infeasible without it. - POST /api/devices/register/cancel lets the registering device end its own attempt (registration UUID bearer, idempotent, never touches a claimed registration). - ListPendingRegistrations / GetPendingRegistrationsData are deprecated-by-emptiness: unclaimed registrations return to nobody. - RejectDevice and its route are deleted — the broadcast list was its only consumer, and there is nothing left for anyone to reject. Additive-only for pinned surfaces: the register response gains pairing_code (Android DTO untouched), the four KOReader sync surfaces and approve keep byte-identical shapes. contract_pins.md changelog records the widening and the reject removal. Docs, schema registry, and bruno mirrors move together per the drift gate; bruno_gen.go now keeps hand-authored bruno/podcasts/ (API docs never existed for them, so the next -update run would have swept them — latent landmine, defused). Unit tests: code shape, live-collision avoidance, typed-code normalization, and the resolve scopes (live/expired/claimed/miss).
This commit is contained in:
1 parent
ab5c52c709
commit
8fbacd9f46
47 files changed
+935
-273
No files matched your search
@@ -0,0 +1,66 @@
|
||||
---
|
||||
method: POST
|
||||
path: /api/devices/claim
|
||||
auth: jwt
|
||||
area: devices
|
||||
---
|
||||
<!-- source: internal/handlers/devices.go DeviceHandler.ClaimDevice -->
|
||||
|
||||
# Claim Device (Pairing Code)
|
||||
|
||||
Bind a pending device registration to the CALLER's account by entering the
|
||||
6-digit pairing code shown on the registering device's screen. This is the
|
||||
web-side replacement for the retired broadcast-list approve: unclaimed
|
||||
registrations appear in no account's pending list, and only whoever reads the
|
||||
code — the person holding the device — can claim it.
|
||||
|
||||
**Endpoint**: `POST /api/devices/claim`
|
||||
**Auth**: JWT
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
The code is normalized before matching: spaces and dashes typed around the
|
||||
digits ("583 912") are stripped. Lookups and claims share a per-account rate
|
||||
limit (12 attempts/minute).
|
||||
|
||||
## Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
| ------------ | ------ | -------- | -------------------------------------------- |
|
||||
| pairing_code | string | Yes | The 6-digit code shown on the device's screen |
|
||||
|
||||
### Example Request
|
||||
|
||||
```json example-request
|
||||
{
|
||||
"pairing_code": "583912"
|
||||
}
|
||||
```
|
||||
|
||||
## Response (200 OK)
|
||||
|
||||
```json example-response
|
||||
{
|
||||
"message": "device paired successfully",
|
||||
"device_name": "My Kindle Paperwhite",
|
||||
"device_type": "koreader",
|
||||
"approved": true
|
||||
}
|
||||
```
|
||||
|
||||
HTMX callers (the Devices page confirm button) receive `HX-Refresh` instead of
|
||||
a JSON body. On success the registering device's status poll returns the fresh
|
||||
`auth_token` and sync endpoints, exactly as in the old approve flow.
|
||||
|
||||
## Error Responses
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ------------------------------------------------------ |
|
||||
| 400 | Invalid pairing code (generic — never confirms whether a registration exists) |
|
||||
| 409 | Pairing code already used, or the device identifier is registered to another user |
|
||||
| 410 | Pairing code expired |
|
||||
| 429 | Too many pairing attempts |
|
||||
|
||||
## Related
|
||||
|
||||
- `POST /api/devices/claim/lookup` — the confirm card's data, without binding
|
||||
- `POST /api/devices/register` — starts the registration and mints the code
|
||||
Reference in new issue
Block a user