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