diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index 80a8b78..94602f5 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -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)