docs: production proxy path + capability-URL guidance
Two small documentation gaps the second-pass audit flagged:
- CLAUDE.md described only the Vite dev proxy ("Vite dev-proxies to
the backend"), which left the production path opaque. Now lists
both: the Vite proxy for `npm run dev` and
`frontend/src/hooks.server.ts` for adapter-node. Same-origin cookie
story called out explicitly.
- `/api/v1/files/{key}` is an unauthenticated capability URL by
design — reads stay public, keys are unguessable v4 UUIDs, leaked
URL leaks one file. Documented both in `backend/src/api/files.rs`'s
module doc (with a pointer at the seam a future
feat/private-libraries branch would use) and in a new "Capability
URLs" section in README so a casual reader doesn't mistake the lack
of auth for an oversight.
No code or behaviour change.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -86,7 +86,7 @@ Everything is namespaced under `/api/v1/`. `/api/*` outside the version prefix i
|
||||
| GET | `/api/v1/mangas/{id}/chapters` | Paginated chapter list, ordered by number. |
|
||||
| GET | `/api/v1/mangas/{id}/chapters/{n}` | Single chapter. |
|
||||
| GET | `/api/v1/mangas/{id}/chapters/{n}/pages` | Page metadata (storage keys + MIME). |
|
||||
| GET | `/api/v1/files/{key}` | Streams a blob (cover or page). |
|
||||
| GET | `/api/v1/files/{key}` | Streams a blob (cover or page). See [Capability URLs](#capability-urls) below. |
|
||||
|
||||
### Write endpoints (require authentication)
|
||||
|
||||
@@ -144,6 +144,10 @@ Everything is namespaced under `/api/v1/`. `/api/*` outside the version prefix i
|
||||
|
||||
The frontend handles this for you: register → cookie set → writes work. Cookies are `HttpOnly; SameSite=Lax; Secure` (configurable via `COOKIE_SECURE`).
|
||||
|
||||
### Capability URLs
|
||||
|
||||
`GET /api/v1/files/{key}` is unauthenticated by design: reads stay public so embedded `<img>` tags and external readers work without round-tripping a cookie or token. The keys themselves are unguessable — they're scoped under v4 UUIDs (`mangas/{manga-uuid}/cover.png`, `mangas/{manga-uuid}/chapters/{chapter-uuid}/pages/0001.png`) — so a leaked URL leaks at most the one file. Treat the URLs as bearer tokens for the bytes they reference and don't paste them into public chat. A future private-libraries feature would gate this endpoint behind a per-key ownership check; the architectural seam is documented in `backend/src/api/files.rs`.
|
||||
|
||||
### Bots / scripts (bearer tokens)
|
||||
|
||||
The frontend on `:3000` proxies `/api/*` through to the backend, so any URL below works against `http://localhost:3000` in the default compose deploy. If you publish the backend port directly, swap in `http://localhost:8080`.
|
||||
|
||||
Reference in New Issue
Block a user