From 68b7f325686bc84dec822fbb39461482716c9f8b Mon Sep 17 00:00:00 2001 From: MechaCat02 Date: Sat, 16 May 2026 23:57:30 +0200 Subject: [PATCH] docs: production proxy path + capability-URL guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- CLAUDE.md | 4 +++- README.md | 6 +++++- backend/src/api/files.rs | 11 +++++++++++ 3 files changed, 19 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3c561fa..2954f15 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -102,7 +102,9 @@ Do not call `tokio::fs` or any filesystem API from handlers. Go through `state.s ## Frontend layout -- [frontend/src/lib/api/](frontend/src/lib/api/) — typed API client. **All backend calls go through here**, not raw `fetch` in components. The base URL is `import.meta.env.VITE_API_BASE`, defaulting to `/api` (which Vite dev-proxies to the backend). +- [frontend/src/lib/api/](frontend/src/lib/api/) — typed API client. **All backend calls go through here**, not raw `fetch` in components. The base URL is `import.meta.env.VITE_API_BASE`, defaulting to `/api`. Two layers route `/api/*` to axum depending on environment: + - **`npm run dev`** uses the Vite proxy in [vite.config.ts](frontend/vite.config.ts) to forward `/api` to `http://localhost:8080`. + - **Production / adapter-node** uses [frontend/src/hooks.server.ts](frontend/src/hooks.server.ts) to reverse-proxy `/api/*` to `BACKEND_URL` (compose wires `http://backend:8080`). The browser only ever talks to the SvelteKit container on `:3000`, so cookies stay same-origin and `CORS_ALLOWED_ORIGINS` can stay empty. - [frontend/src/routes/](frontend/src/routes/) — SvelteKit routes. - Use Svelte 5 runes (`$state`, `$derived`, `$effect`, `$props`). Do not use the legacy `let`-reactive syntax or `on:event=` directive form — prefer `onevent={...}`. - The Node adapter is configured for production; `npm run build && node build` is what the Dockerfile runs. diff --git a/README.md b/README.md index b725f05..6bf231e 100644 --- a/README.md +++ b/README.md @@ -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 `` 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`. diff --git a/backend/src/api/files.rs b/backend/src/api/files.rs index 6cff2b8..39befa4 100644 --- a/backend/src/api/files.rs +++ b/backend/src/api/files.rs @@ -4,6 +4,17 @@ //! //! The handler uses `Storage::get_stream` so a multi-MB page is piped to //! the client a chunk at a time instead of buffered server-side. +//! +//! **Auth model — capability URLs by design.** This endpoint is +//! deliberately unauthenticated: reads stay public per the project +//! brief, and per-page authorisation would require either a per-request +//! ownership lookup (covers + pages are scoped by manga, not user) or a +//! signed-URL scheme. Mangalord instead relies on the keys being +//! unguessable — `mangas/{uuid}/...` and +//! `mangas/{uuid}/chapters/{uuid}/...` — so a leaked URL leaks at most +//! the one referenced file. A future feat/private-libraries branch +//! would gate this endpoint behind a `Storage::owner_of(key)` check; +//! the seam is intentional. use axum::body::Body; use axum::extract::{Path, State};