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
|
- [ ] Security warning about API keys in logs
|
||||||
- [ ] Network security recommendations (VPN, local network)
|
- [ ] Network security recommendations (VPN, local network)
|
||||||
- [ ] Instructions for regenerating token if compromised
|
- [ ] 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`)
|
2. **Kobo Sync Validation** (`cmd/server/tests/kobo_test.go`)
|
||||||
- [ ] Update tests to use API key in URL path
|
- [ ] 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
|
## 10. Risk Assessment
|
||||||
|
|
||||||
**Low Risk:**
|
**Low Risk:**
|
||||||
@@ -1204,15 +1246,26 @@ http://IP:8765/opds/devices/{DEVICE_ID}/catalog
|
|||||||
- Return new token to user
|
- Return new token to user
|
||||||
|
|
||||||
4. **[CRITICAL]** Update kobo-setup.md documentation:
|
4. **[CRITICAL]** Update kobo-setup.md documentation:
|
||||||
- Remove Username/Password references (lines 116-118)
|
- Remove Username/Password references (if any remain)
|
||||||
- Explain API key in URL configuration
|
- Verify registration flow reflects API key generation:
|
||||||
- Show full URL with token: `http://IP:8765/api/sync/kobo/{API_KEY}`
|
- Device registration automatically generates `auth_token`
|
||||||
- Document token regeneration process
|
- 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:
|
5. **[CRITICAL]** Update koreader-setup.md documentation:
|
||||||
- Change "Basic Auth" to "Bearer Token" authentication
|
- Change "Basic Auth" to "Bearer Token" authentication (line 126)
|
||||||
- Remove incorrect username/password references (lines 26-27)
|
- Remove incorrect username/password references (lines 127-128)
|
||||||
- Explain plugin token management
|
- 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:
|
6. **[TESTING]** Update test coverage:
|
||||||
- Test Kobo sync with API key in URL path
|
- Test Kobo sync with API key in URL path
|
||||||
|
|||||||
Reference in New Issue
Block a user