feat(koreader): add EPUB progress sync, permission model, and API key editing

Convert between KOReader's DocFragment format and Codex's R2Progression
so EPUB reading progress is shared across all clients (web reader,
KOReader, OPDS apps). Previously, KOReader sync only stored raw page
numbers, breaking cross-client EPUB progress.

Fix the KOReader partial hash algorithm to match LuaJIT's bit.lshift
32-bit wrapping semantics (i=-1 offset is 0, not 256). Recompute
koreader_hash during both scan and analysis, and expose it in the
book API/DTOs.

Add ProgressRead/ProgressWrite permissions so API keys can be scoped
for progress sync without granting broader access. Include these in
all role presets (reader, maintainer, admin) and the OPDS preset.

Add x-auth-user header authentication for KOReader's login flow, which
sends the API key as a username rather than a Bearer token.

Add API key permission editing UI with an edit modal on the profile
settings page. Update OPDS preset to include progress permissions.

Add KOReader setup documentation with troubleshooting guide.

Author: AshDevFr

config/config.docker.yaml

@@ -136,7 +136,6 @@ komga_api:
   enabled: true
   prefix: komga # URL prefix: /{prefix}/api/v1/...
 
-
 # Rate Limiting (enabled by default)
 # ==================================
 # Protects API endpoints from abuse using token bucket algorithm
@@ -153,3 +152,6 @@ komga_api:
 #     - /api/v1/books/*/thumbnail   # Exempt book thumbnails
 #   cleanup_interval_secs: 60  # How often to clean up stale buckets
 #   bucket_ttl_secs: 300       # Time before a bucket is considered stale
+
+koreader_api:
+  enabled: true

docs/api/openapi.json

@@ -17307,6 +17307,13 @@
             "description": "Book unique identifier",
             "example": "550e8400-e29b-41d4-a716-446655440001"
           },
+          "koreaderHash": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "KOReader-compatible partial MD5 hash for sync"
+          },
           "libraryId": {
             "type": "string",
             "format": "uuid",
@@ -22701,6 +22708,13 @@
             "description": "Book unique identifier",
             "example": "550e8400-e29b-41d4-a716-446655440001"
           },
+          "koreaderHash": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "KOReader-compatible partial MD5 hash for sync"
+          },
           "libraryId": {
             "type": "string",
             "format": "uuid",
@@ -27014,6 +27028,13 @@
                   "description": "Book unique identifier",
                   "example": "550e8400-e29b-41d4-a716-446655440001"
                 },
+                "koreaderHash": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "KOReader-compatible partial MD5 hash for sync"
+                },
                 "libraryId": {
                   "type": "string",
                   "format": "uuid",

docs/docs/third-party-apps.md

@@ -38,6 +38,76 @@ While Codex is primarily tested with Komic, other Komga-compatible apps may also
 Compatibility with apps other than Komic is not officially tested. Your experience may vary.
 :::
 
+### KOReader
+
+[KOReader](https://koreader.rocks/) is an open-source e-book reader for E Ink devices and other platforms. Codex supports the KOReader sync protocol, allowing you to sync reading progress between KOReader and Codex.
+
+**Supported formats:** EPUB, PDF, CBZ, CBR
+
+#### Prerequisites
+
+1. **Enable the KOReader API** in your Codex configuration (see [Enabling the KOReader API](#enabling-the-koreader-api) below)
+2. **Create an API key** in Codex (see [API Keys](./users/api-keys))
+3. **Run a deep scan** so Codex computes KOReader-compatible hashes for your books (see [Deep Scan](./libraries#deep-scan))
+
+#### Setup in KOReader
+
+1. Open a book in KOReader
+2. Go to **Top Menu** > **Tools** (🔧) > **Progress sync**
+3. Select **Custom sync server**
+4. Enter the server settings:
+   - **Server URL**: `http://your-server:8080/koreader`
+   - **Username**: Your Codex **API key** (e.g., `codex_abc12345_secretpart123456789`)
+   - **Password**: Any value (ignored by Codex)
+5. Tap **Login** to verify the connection
+
+:::info
+KOReader uses the `x-auth-user` header to send the username, which Codex treats as an API key. The password field (`x-auth-key`) is ignored because KOReader MD5-hashes the password before sending it, making direct password verification impossible.
+:::
+
+#### How It Works
+
+KOReader identifies books by computing an MD5 hash of the first 4096 bytes of the file. When you enable the KOReader API and run a **deep scan**, Codex computes the same hash for each book and stores it. This allows KOReader to look up books and sync progress.
+
+- **Progress sync is per-user**: Each user's reading progress is tracked independently
+- **EPUB progress**: Codex converts between KOReader's DocFragment format and its internal position tracking
+- **PDF/CBZ/CBR progress**: Page numbers are synced directly
+
+#### Troubleshooting KOReader
+
+**"Login failed" or 401 Unauthorized:**
+- Make sure you're using a Codex **API key** as the username, not your regular username/password
+- Verify the API key hasn't expired or been revoked
+- Check that `koreader_api.enabled` is `true` in your config
+
+**"Book not found" (404):**
+- Run a **deep scan** on your library so Codex computes KOReader hashes
+- The book must be in a Codex library; KOReader identifies books by file hash, not filename
+
+**Progress not syncing:**
+- Ensure both devices are using the same Codex server and user account
+- Check that the book files are identical (same hash) across devices
+
+## Enabling the KOReader API
+
+The KOReader sync API is disabled by default. To enable it:
+
+### Via Configuration File
+
+```yaml
+# codex.yaml
+koreader_api:
+  enabled: true
+```
+
+### Via Environment Variables
+
+```bash
+CODEX_KOREADER_API_ENABLED=true
+```
+
+After enabling, restart Codex and run a **deep scan** on your libraries to compute KOReader-compatible file hashes.
+
 ## Enabling the Komga API
 
 The Komga-compatible API is disabled by default for security. To enable it:

docs/docs/users/api-keys.md

@@ -141,15 +141,17 @@ The prefix is stored in plaintext for lookup, but the secret is hashed - Codex c
 
 ### OPDS / Reader Apps
 
-Minimal permissions for read-only access:
+Permissions for e-reader apps, OPDS clients, and KOReader sync:
 
 ```json
 {
   "name": "OPDS Reader",
-  "permissions": ["LibrariesRead", "SeriesRead", "BooksRead", "PagesRead"]
+  "permissions": ["LibrariesRead", "SeriesRead", "BooksRead", "PagesRead", "ProgressRead", "ProgressWrite"]
 }
 ```
 
+`ProgressRead` and `ProgressWrite` are needed for apps that sync reading progress (e.g., KOReader).
+
 ### Automation Script
 
 For scripts that trigger scans and monitor progress:

src/api/extractors/auth.rs

@@ -1,3 +1,5 @@
+use tracing::debug;
+
 use crate::api::error::ApiError;
 use crate::api::permissions::{Permission, UserRole};
 use crate::db::repositories::{ApiKeyRepository, UserRepository};
@@ -256,6 +258,14 @@ impl FromRequestParts<Arc<AppState>> for AuthContext {
             return extract_from_api_key(api_key, state).await;
         }
 
+        // Try KOReader-style x-auth-user header (value is an API key, x-auth-key is ignored)
+        if let Some(api_key_header) = parts.headers.get("x-auth-user")
+            && let Ok(api_key) = api_key_header.to_str()
+        {
+            debug!("Attempting KOReader x-auth-user API key authentication");
+            return extract_from_api_key(api_key, state).await;
+        }
+
         Err(ApiError::Unauthorized(
             "Missing or invalid authentication credentials".to_string(),
         ))
@@ -433,6 +443,17 @@ async fn extract_from_basic_auth(
     let username = parts[0];
     let password = parts[1];
 
+    extract_from_credentials(username, password, state).await
+}
+
+/// Extract auth context from username/password credentials
+///
+/// Shared by Basic Auth and KOReader x-auth-user/x-auth-key header authentication.
+async fn extract_from_credentials(
+    username: &str,
+    password: &str,
+    state: &AppState,
+) -> Result<AuthContext, ApiError> {
     // Look up user by username
     let user = UserRepository::get_by_username(&state.db, username)
         .await
@@ -516,6 +537,15 @@ impl FromRequestParts<Arc<AppState>> for FlexibleAuthContext {
                 .map(FlexibleAuthContext);
         }
 
+        // Try KOReader-style x-auth-user header (API key)
+        if let Some(api_key_header) = parts.headers.get("x-auth-user")
+            && let Ok(api_key) = api_key_header.to_str()
+        {
+            return extract_from_api_key(api_key, state)
+                .await
+                .map(FlexibleAuthContext);
+        }
+
         // Try cookie as fallback
         if let Some(cookie_header) = parts.headers.get(COOKIE)
             && let Ok(cookie_str) = cookie_header.to_str()

src/api/permissions.rs

@@ -94,6 +94,10 @@ pub enum Permission {
     // Pages (image serving)
     PagesRead,
 
+    // Progress (reading progress tracking)
+    ProgressRead,
+    ProgressWrite,
+
     // Users (admin only)
     UsersRead,
     UsersWrite,
@@ -131,6 +135,8 @@ impl Permission {
             Permission::BooksWrite => "books:write",
             Permission::BooksDelete => "books:delete",
             Permission::PagesRead => "pages:read",
+            Permission::ProgressRead => "progress:read",
+            Permission::ProgressWrite => "progress:write",
             Permission::UsersRead => "users:read",
             Permission::UsersWrite => "users:write",
             Permission::UsersDelete => "users:delete",
@@ -161,6 +167,8 @@ impl FromStr for Permission {
             "books:write" => Ok(Permission::BooksWrite),
             "books:delete" => Ok(Permission::BooksDelete),
             "pages:read" => Ok(Permission::PagesRead),
+            "progress:read" => Ok(Permission::ProgressRead),
+            "progress:write" => Ok(Permission::ProgressWrite),
             "users:read" => Ok(Permission::UsersRead),
             "users:write" => Ok(Permission::UsersWrite),
             "users:delete" => Ok(Permission::UsersDelete),
@@ -199,6 +207,8 @@ lazy_static::lazy_static! {
         set.insert(Permission::SeriesRead);
         set.insert(Permission::BooksRead);
         set.insert(Permission::PagesRead);
+        set.insert(Permission::ProgressRead);
+        set.insert(Permission::ProgressWrite);
         set.insert(Permission::SystemHealth);
         set
     };
@@ -217,6 +227,9 @@ lazy_static::lazy_static! {
         set.insert(Permission::SeriesRead);
         set.insert(Permission::BooksRead);
         set.insert(Permission::PagesRead);
+        // Progress tracking
+        set.insert(Permission::ProgressRead);
+        set.insert(Permission::ProgressWrite);
         // Own API keys
         set.insert(Permission::ApiKeysRead);
         set.insert(Permission::ApiKeysWrite);
@@ -333,7 +346,7 @@ mod tests {
         assert!(READONLY_PERMISSIONS.contains(&Permission::LibrariesRead));
         assert!(READONLY_PERMISSIONS.contains(&Permission::BooksRead));
         assert!(!READONLY_PERMISSIONS.contains(&Permission::LibrariesWrite));
-        assert_eq!(READONLY_PERMISSIONS.len(), 5);
+        assert_eq!(READONLY_PERMISSIONS.len(), 7);
     }
 
     // ============== Role permission preset tests ==============
@@ -354,6 +367,9 @@ mod tests {
         // Reader cannot view or manage tasks
         assert!(!READER_PERMISSIONS.contains(&Permission::TasksRead));
         assert!(!READER_PERMISSIONS.contains(&Permission::TasksWrite));
+        // Reader can track reading progress
+        assert!(READER_PERMISSIONS.contains(&Permission::ProgressRead));
+        assert!(READER_PERMISSIONS.contains(&Permission::ProgressWrite));
         // Reader cannot modify content
         assert!(!READER_PERMISSIONS.contains(&Permission::BooksWrite));
         assert!(!READER_PERMISSIONS.contains(&Permission::SeriesWrite));
@@ -362,7 +378,7 @@ mod tests {
         assert!(!READER_PERMISSIONS.contains(&Permission::UsersRead));
         assert!(!READER_PERMISSIONS.contains(&Permission::SystemAdmin));
 
-        assert_eq!(READER_PERMISSIONS.len(), 8);
+        assert_eq!(READER_PERMISSIONS.len(), 10);
     }
 
     #[test]
@@ -389,7 +405,7 @@ mod tests {
         assert!(!MAINTAINER_PERMISSIONS.contains(&Permission::UsersRead));
         assert!(!MAINTAINER_PERMISSIONS.contains(&Permission::SystemAdmin));
 
-        assert_eq!(MAINTAINER_PERMISSIONS.len(), 15);
+        assert_eq!(MAINTAINER_PERMISSIONS.len(), 17);
     }
 
     #[test]
@@ -413,7 +429,7 @@ mod tests {
         // Admin has system admin
         assert!(ADMIN_PERMISSIONS.contains(&Permission::SystemAdmin));
 
-        assert_eq!(ADMIN_PERMISSIONS.len(), 21); // All permissions
+        assert_eq!(ADMIN_PERMISSIONS.len(), 23); // All permissions
     }
 
     // ============== UserRole tests ==============