docs: add documentation update checklist to implementation plan

- Add Section 16: Documentation Updates Required
- Detail specific line numbers and changes for koreader-setup.md:
  - Line 126: Change "Basic Auth" to "Bearer Token"
  - Lines 127-128: Remove username/password references
- Detail verification needed for kobo-setup.md:
  - Lines 37-53: Confirm no serial number references
  - Verify registration flow describes automatic token generation
- Update Phase 1 tasks with specific line number references
- Update Phase 2 Kobo documentation tasks with verification notes
This commit is contained in:
2026-02-12 10:58:39 -05:00
parent 416773663c
commit 51c39f94cf
+60 -7
View File
@@ -274,6 +274,8 @@ func (m *DeviceAuthMiddleware) Authenticate(next echo.HandlerFunc) echo.HandlerF
- [ ] Security warning about API keys in logs
- [ ] Network security recommendations (VPN, local network)
- [ ] Instructions for regenerating token if compromised
- **Note**: Documentation was updated on 2026-02-12 to reflect API key authentication
- **Verification**: Confirm lines 37-53 don't reference entering serial number (device registration generates token automatically)
2. **Kobo Sync Validation** (`cmd/server/tests/kobo_test.go`)
- [ ] Update tests to use API key in URL path
@@ -978,6 +980,46 @@ This implementation plan emerged from a detailed analysis of the current authent
---
## 16. Documentation Updates Required (Pre-Implementation Checklist)
Based on codebase analysis, the following documentation updates are needed:
### koreader-setup.md (docs/user/devices/koreader-setup.md)
**Current Issues:**
- Line 126: Says "Basic Auth" - should be "Bearer Token"
- Lines 127-128: Reference username/password - should reference auth_token
- Documentation states KOReader uses Basic Auth (incorrect)
**Required Changes:**
```diff
- 1. **Authentication Method**: Select "Basic Auth"
- 2. **Username**: Your Bookhoard email or username
- 3. **Password**: Your Bookhoard password
+ 1. **Authentication Method**: Bearer Token (API Key)
+ 2. **Auth Token**: Copy from Bookhoard Device Management page
+ 3. **Setup**: Plugin will include token in Authorization header automatically
```
### kobo-setup.md (docs/user/devices/kobo-setup.md)
**Current Status:**
- Updated on 2026-02-12 to reflect API key authentication
- Shows full URL format with token
**Verification Needed:**
- Confirm lines 37-53 (device registration) don't mention entering serial number
- Verify registration flow describes automatic API key generation
- Ensure "Copy Full Sync URL" button is documented
### New Documentation: security.md
**Required Content:**
- API key in URL path security considerations
- Comparison: API key (URL) vs Bearer token (header)
- Network security recommendations (HTTPS, VPN, local-only)
- Token regeneration best practices
- Risk mitigations for self-hosted deployments
---
## 10. Risk Assessment
**Low Risk:**
@@ -1204,15 +1246,26 @@ http://IP:8765/opds/devices/{DEVICE_ID}/catalog
- Return new token to user
4. **[CRITICAL]** Update kobo-setup.md documentation:
- Remove Username/Password references (lines 116-118)
- Explain API key in URL configuration
- Show full URL with token: `http://IP:8765/api/sync/kobo/{API_KEY}`
- Document token regeneration process
- Remove Username/Password references (if any remain)
- Verify registration flow reflects API key generation:
- Device registration automatically generates `auth_token`
- User copies full sync URL from device management page (not just token)
- Example: `http://IP:8765/api/sync/kobo/{API_KEY}`
- Explain API key in URL configuration
- Show full URL with token: `http://IP:8765/api/sync/kobo/{API_KEY}`
- Document token regeneration process
- **Status**: Documentation was updated on 2026-02-12 to reflect API key auth
- **Verification Needed**: Ensure no references to entering serial number remain (lines 37-53)
5. **[CRITICAL]** Update koreader-setup.md documentation:
- Change "Basic Auth" to "Bearer Token" authentication
- Remove incorrect username/password references (lines 26-27)
- Explain plugin token management
- Change "Basic Auth" to "Bearer Token" authentication (line 126)
- Remove incorrect username/password references (lines 127-128)
- Currently: "Username: Your Bookhoard email or username"
- Currently: "Password: Your Bookhoard password"
- Should be: "Auth Token: Your device API key from Bookhoard"
- Explain plugin token management
- **Note**: Current docs mention "Basic Auth" which is INCORRECT
- **Note**: KOReader uses Bearer token in Authorization header (not Basic Auth)
6. **[TESTING]** Update test coverage:
- Test Kobo sync with API key in URL path