diff --git a/docs/developer/api/libraries/browse-folders.md b/docs/developer/api/libraries/browse-folders.md new file mode 100644 index 0000000..bd139b5 --- /dev/null +++ b/docs/developer/api/libraries/browse-folders.md @@ -0,0 +1,52 @@ +# Browse Library Folders + +Browse server directories for folder selection in library management. + +**Endpoint**: `GET /api/libraries/browse` +**Auth**: Required (Admin only) + +## Query Parameters + +| Parameter | Type | Required | Description | +|-----------|------|-----------|-------------| +| path | string | No | Directory path to browse (default: "/") | + +## Request Headers + +| Header | Type | Required | Description | +|--------|------|-----------|-------------| +| Authorization | string | Yes | Bearer token (admin only) | + +### Example Request + +```http +GET /api/libraries/browse?path=/home/user +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +## Response (200 OK) + +```json +{ + "current_path": "/home/user", + "parent_path": "/home", + "directories": ["Documents", "Downloads", "Books", "Music"] +} +``` + +## Error Responses + +| Code | Description | +|------|-------------| +| 400 | Path traversal attempt or invalid path | +| 401 | Invalid or expired token | +| 403 | User is not an admin | +| 400 | Path does not exist | +| 400 | Path is not a directory | + +## Security + +- **Path traversal protection**: Blocks requests containing ".." +- **Admin only**: Regular users receive 403 Forbidden +- **Directories only**: Returns only directory names, not file listings +- **Server filesystem**: Browses server's filesystem, not client's diff --git a/docs/user/admin-library-management.md b/docs/user/admin-library-management.md new file mode 100644 index 0000000..a00bf08 --- /dev/null +++ b/docs/user/admin-library-management.md @@ -0,0 +1,32 @@ +# Admin Library Management + +## Adding Library Folders + +When creating or managing a library, you can add folders containing your media files (ebooks, comics, manga). + +### Using the Folder Browser + +The admin library page includes a folder browser to help you select folders on the server: + +1. Navigate to **Admin → Library Management** +2. Find the library you want to manage +3. Click the **Folders** button +4. Click **Browse** next to "Add folder path" +5. Navigate through the server's filesystem +6. Select a folder by clicking **Select This Folder** + +### Security + +- The folder browser only shows directories (not files) +- Path traversal is protected (cannot access parent directories with `..`) +- Only admin users can browse the filesystem + +### Manual Entry + +Alternatively, you can manually type the full server path if you know it: + +``` +/home/user/books +/media/external/ebooks +/var/lib/manga +```