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:
+70
-1
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user