From b1345e1ad74255b5d0b303a7a7f53c7e3fbe7de5 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Wed, 11 Feb 2026 21:03:39 -0500 Subject: [PATCH] docs: add critical modifications section to implementation plan - Section 14: Critical Modifications Required - Missing GetDeviceByDeviceIdentifier query requirement - Incorrect Kobo documentation (wrong auth mechanism) - OPDS authentication inconsistency (needs dual header/URL fallback) - Enhanced security documentation requirements - Section 15: Updated success criteria - Database query requirements - Documentation accuracy requirements - Dual authentication support These modifications address blockers identified during codebase review before implementation begins. --- IMPLEMENTATION_PLAN.md | 179 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md index a4933f6..ba78cff 100644 --- a/IMPLEMENTATION_PLAN.md +++ b/IMPLEMENTATION_PLAN.md @@ -758,3 +758,182 @@ This implementation plan emerged from a detailed analysis of the current authent 4. Weekly check-ins on progress **Ready to proceed?** + +--- + +## 14. Critical Modifications Required + +### Issues Discovered During Review + +The following issues were identified during codebase analysis and must be addressed before or during implementation: + +### 14.1 Missing Database Query + +**Issue**: Phase 1 references `GetDeviceByDeviceIdentifier` query but it doesn't exist in queries.sql + +**Location**: `internal/database/queries/queries.sql` + +**Required Addition**: +```sql +-- name: GetDeviceByDeviceIdentifier :one +SELECT * FROM devices WHERE device_identifier = $1; +``` + +**Impact**: Blocker - cannot implement serial-based auth without this query + +--- + +### 14.2 Incorrect Documentation + +**Issue**: Current `docs/user/devices/kobo-setup.md` contains WRONG authentication information + +**Problems**: +- States Kobo uses "Username/Password" in config file (lines 116-118) +- Kobo firmware sends `Authorization: Bearer {kobo-store-token}` - NOT configurable +- Kobo sends `x-kobo-device: {"SerialNumber":"..."}` header - this is what we must use +- Kobo CANNOT send custom Bearer tokens through `eReader.conf` + +**Required Rewrite**: Section "Configure Kobo Sync" (lines 100-133) must be updated to: +1. Remove Username/Password references +2. Explain serial-based auth works via `x-kobo-device` header (sent automatically by Kobo) +3. Clarify that NO manual token configuration is needed for Kobo +4. Update troubleshooting section to reflect serial auth approach + +--- + +### 14.3 OPDS Authentication Inconsistency + +**Issue**: OPDS clients (including Kobo's native browser and KOReader) have limited header support + +**Problem**: +- Kobo OPDS browser: Cannot send custom `Authorization` headers +- KOReader OPDS client: Can send headers via plugin, but native OPDS support varies +- Current plan relies on `DeviceAuthMiddleware` checking `Authorization` header + +**Proposed Solution**: Implement **dual authentication** for OPDS endpoints: + +1. **Header-based** (existing): Check `Authorization: Bearer {token}` for KOReader plugin +2. **URL-based** (new): Check `?token=...` query parameter for Kobo and other clients + +**Implementation**: +```go +// In internal/middleware/device_auth.go +func (m *DeviceAuthMiddleware) authenticateWithFallback(c echo.Context) error { + // Try Bearer token first + authHeader := c.Request().Header.Get("Authorization") + if authHeader != "" { + token := strings.TrimPrefix(authHeader, "Bearer ") + device, err := m.db.GetDeviceByAuthToken(c.Request().Context(), token) + if err == nil { + return m.setDeviceContext(c, device) + } + } + + // Fallback: Check URL token parameter for OPDS + urlToken := c.QueryParam("token") + if urlToken != "" { + device, err := m.db.GetDeviceByAuthToken(c.Request().Context(), urlToken) + if err == nil { + return m.setDeviceContext(c, device) + } + } + + return c.JSON(http.StatusUnauthorized, map[string]string{"error": "authentication required"}) +} +``` + +**Why This Matters**: Without URL-based fallback, Kobo devices cannot access OPDS catalogs regardless of authentication method. + +--- + +### 14.4 Enhanced Security Documentation + +**Issue**: Security implications of serial-based auth need stronger emphasis + +**Add to `docs/user/security.md`** (new file): + +```markdown +## Serial-Based Authentication Security Considerations + +### Risks + +- **Predictable Identifiers**: Kobo serial numbers follow known patterns (N + 12 digits) +- **No Rotation**: Unlike Bearer tokens, serial numbers cannot be changed +- **Device Theft**: Physical access to device grants permanent access until manually revoked +- **Network Exposure**: On public networks, serial could be intercepted + +### Recommended Mitigations + +1. **Network Security** (REQUIRED for serial auth) + - Use VPN for remote access + - Restrict Bookhoard to local network only + - Use reverse proxy with SSL/TLS termination + - Implement firewall rules limiting access by IP + +2. **Monitor Access Logs** + - Review device sync logs regularly + - Set up alerts for: + - Unknown serial numbers + - Sync attempts from unusual locations + - Rapid sync failures (possible brute force) + +3. **Device Management** + - Revoke unrecognized devices immediately + - Use device approval workflow (already implemented) + - Regular audit of registered devices + +4. **HTTPS is Mandatory for Remote Access** + - Never expose Bookhoard over plain HTTP publicly + - Use valid SSL/TLS certificates + - Consider client certificate authentication for high-security deployments + +### Comparison + +| Method | Security | Usability | Revocable | Rotation | +|---------|-----------|-------------|------------|----------| +| Serial Number | ⭐⭐ Medium | ⭐⭐⭐⭐⭐ Excellent | No | No | +| Bearer Token | ⭐⭐⭐⭐ High | ⭐⭐⭐ Good | Yes | Yes | + +**Recommendation**: For self-hosted personal use with trusted local network, serial auth provides acceptable security/usability trade-off. +``` + +--- + +### 14.5 Implementation Order Adjustment + +**Modified Phase 1 Tasks**: + +1. **[CRITICAL]** Add `GetDeviceByDeviceIdentifier` to queries.sql +2. **[CRITICAL]** Update kobo-setup.md documentation with correct auth flow +3. Implement enhanced DeviceAuthMiddleware with dual header/URL support +4. Add device_identifier index if not exists +5. Update tests to verify both auth methods work + +**Why This Order**: Database query must exist BEFORE middleware can use it. Documentation must be correct BEFORE users attempt setup. + +--- + +## 15. Updated Success Criteria + +Add to Section 7: + +**Authentication**: +- ✅ Kobo serial-based auth working via `x-kobo-device` header +- ✅ KOReader Bearer token auth working via `Authorization` header +- ✅ OPDS accessible via BOTH header and URL token fallback +- ✅ Security implications documented with mitigation strategies + +**Database**: +- ✅ `GetDeviceByDeviceIdentifier` query implemented and indexed +- ✅ `device_identifier` column has UNIQUE constraint (already exists in schema) + +**Documentation**: +- ✅ kobo-setup.md reflects actual auth mechanism (no username/password) +- ✅ security.md created with serial auth considerations +- ✅ OPDS dual-auth documented in troubleshooting + +--- + +**Modified Plan Status**: Critical issues identified and resolved. Ready for implementation. + +**Last Updated**: Based on codebase review - added Section 14 modifications \ No newline at end of file