x

docs/architecture/share-integration.md

@@ -36,8 +36,43 @@ What used to live on the share row but is now resolved through ReBAC:
 
 | Method | Path | Description |
 | --- | --- | --- |
-| `GET` | `/api/s/{token}` | Access a shared item |
-| `POST` | `/api/s/{token}/verify` | Verify a password-protected share |
+| `GET` | `/api/s/{token}` | Share landing metadata (see [landing enrichment](#share-landing-metadata-enrichment)) |
+| `POST` | `/api/s/{token}/verify` | Verify a password-protected share (sets the unlock-JWT cookie) |
+| `GET` | `/api/s/{token}/download` | Download a **file share** (Range / 206 / 304 / 416 aware) |
+| `GET` | `/api/s/{token}/contents` | List a **folder share's** root (folders + files) |
+| `GET` | `/api/s/{token}/contents/{folder_id}` | List a subfolder inside the shared subtree |
+| `GET` | `/api/s/{token}/file/{file_id}` | Stream one file — the landing page's inline preview and per-file download path (Range aware) |
+| `GET` | `/api/s/{token}/zip` | ZIP archive of a **folder share's** root |
+| `GET` | `/api/s/{token}/zip/{folder_id}` | ZIP archive of a subfolder inside the shared subtree |
+
+#### File scoping on `/file/{file_id}`
+
+The AuthZ gate (`ShareBrowseService::assert_file_in_share`) branches on the
+share's `item_type` — a single-file share and a folder share scope the
+endpoint differently:
+
+- **File share** — only the shared item itself may be streamed
+  (`file_id == share.item_id`). This is what renders the public landing
+  page's inline media preview (video player / image) and it is also the
+  NextCloud-desktop-style per-file fetch path.
+- **Folder share** — the file must live inside the shared subtree
+  (ltree `is_file_in_subtree` against the share's root folder).
+- Anything else → **404**, the same shape as "file doesn't exist", so the
+  endpoint cannot be used to enumerate ids.
+
+Password and expiry checks happen inside `get_shared_link_with_unlock`
+before the scope decision; a password-protected share answers 401 with
+`requiresPassword: true` until the unlock cookie is presented.
+
+#### Share landing metadata enrichment
+
+`GET /api/s/{token}` resolves the shared **file's** `mime_type` + `size`
+at read time so anonymous viewers get an inline media preview (video
+player / image) instead of a bare download button. The enrichment is
+display-only and never fails the response: a failed file lookup (transient
+DB error, race with a delete) leaves the fields absent and the download
+endpoints surface the real error — a read failure is never proof that the
+data is absent. Folder shares pass through unenriched.
 
 ## Service Responsibilities