docs: add device_identifier investigation to implementation plan

- Add Section 16.1: Codebase investigation results
- Document that device_identifier was added in Phase 1 (commit 3b2075f)
- Clarify it's for device management, not authentication
- Show active usage in device registration (line 37: validate:"required,min=1,max=255")
- Identify dead code: GetDeviceByIdentifier query exists but not called
- Confirm OPDS uses device.id for lookup (not device_identifier)
- Distinguish authentication (auth_token) from device identification (device_identifier)
This commit is contained in:
2026-02-12 11:17:46 -05:00
parent 1117c0a02f
commit 1db89669fb
+70 -1
View File
@@ -607,7 +607,76 @@ Based on user feedback, the following decisions have been finalized:
**Note:** This is about device MANAGEMENT, not authentication. Authentication uses `auth_token` (API keys) for all devices. Device identifier is for tracking multiple installations of the same physical device.
**Decision:** Self-registration with plugin-generated device ID that persists across KOReader reinstalls.
---
## 16.1 Codebase Investigation: device_identifier Field
**Investigation Date:** 2026-02-12
**Purpose:** Clarify the role and usage of `device_identifier` field in the devices table
### Git History Analysis
**Introduction (Commit 3b2075f, Phase 1 - "highlights and notes annotation system"):**
- Added as part of broader annotation system feature
- Original intent: Track physical device identity across software reinstalls
- Has existed since early project history (not legacy code)
### Current Codebase Usage
**Active Usage:**
```go
// internal/handlers/devices.go:37
DeviceIdentifier string `json:"device_identifier" validate:"required,min=1,max=255"`
```
- Required field in device registration requests
- Stored in `devices.device_identifier` (VARCHAR(255) UNIQUE NOT NULL)
- Used in registration flow to track device identity
**Dead Code:**
```sql
-- internal/database/queries/queries.sql:731
-- name: GetDeviceByIdentifier :one
SELECT * FROM devices WHERE device_identifier = $1;
```
- Function exists in generated database code (`internal/database/querier.go:130`)
- **NOT called** anywhere in handlers or tests (0 references)
- Can be considered for removal during code cleanup
### OPDS Handler Behavior
**Current Implementation (internal/handlers/opds.go:56-89):**
```go
deviceID := c.Param("deviceId") // Extracts UUID from URL
deviceUUID, err := uuid.Parse(deviceID)
device, err := h.db.GetDevice(c.Request().Context(), pgtype.UUID{Bytes: deviceUUID, Valid: true})
```
**Finding:** OPDS handler uses device `id` (UUID) for lookup, NOT `device_identifier`
### Authentication vs Device Identification
**Authentication (what currently works):**
- `auth_token` field stores revocable API keys
- Used by `DeviceAuthMiddleware` for all device authentication
- Bearer token or URL path parameter lookup via `GetDeviceByAuthToken`
**Device Identification (what this is about):**
- `device_identifier` field tracks physical device identity
- Helps prevent duplicate device registrations for same physical device
- NOT used for authentication (only for device management/registration)
### Conclusion
**No inconsistency found.** The implementation plan's handling of `device_identifier` is accurate:
- Field exists for device management purposes
- Required in current registration flow
- Auth uses `auth_token` only (no confusion)
- Dead query (`GetDeviceByIdentifier`) can be removed during cleanup
**Decision:** **Keep Section 9.6** - The KOReader Device Identification Strategy is valid for solving the `max_devices` exhaustion problem. The plan correctly distinguishes between device identification (management) and authentication (security).
---
**Architecture:**
- Plugin generates unique `device_id` on first launch (stored in KOReader settings)