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.
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user