Add session auth: FastAPI login/logout/me endpoints, uv-managed deps, fix cookie on JSONResponse

2026-04-23 15:29:56 +02:00
parent f5a38b2ca8
commit 3632ab3e9a
7 changed files with 910 additions and 17 deletions
@@ -0,0 +1,109 @@
+# bincio_wiki — development notes
+
+## Project overview
+
+A private wiki for the bincio group of friends. Built on Astro 6 using the
+`brutsalvadi/astro-bloomz` fork as a git submodule at `site/`. Content lives
+in `pages/` at the repo root, symlinked into `site/src/content/entries/_wiki`.
+
+## Directory layout
+
+```
+bincio_wiki/
+  pages/          wiki content (*.md files the community edits)
+    _docs/        software documentation (moved here, shown as separate section)
+  site/           Astro 6 app (git submodule → brutsalvadi/astro-bloomz)
+  edit/           FastAPI edit server (Python, port 8001)
+  pyproject.toml  Python dependencies (managed by uv)
+  uv.lock         uv lockfile (committed)
+  scripts/        dev.sh — starts both Astro and FastAPI together
+  docs/           repo-level documentation (not served as wiki pages)
+```
+
+## Running locally
+
+```bash
+bash scripts/dev.sh          # Astro only (port 4321)
+bash scripts/dev.sh --edit   # Astro + FastAPI edit sidecar (port 8001)
+```
+
+Python dependencies are managed by `uv`. `uv sync` is called automatically
+by `dev.sh --edit` — no manual setup needed. To add a dependency:
+`uv add <package>` (updates `pyproject.toml` and `uv.lock`).
+
+## Content architecture
+
+- Wiki pages: `pages/*.md` (IDs in Astro content store are the bare filename
+  without extension, e.g. `digital-garden`)
+- Docs section: `pages/_docs/*.md` (IDs start with `_docs/`)
+- Bonsai index: stored in `site/src/content/index/` — the `i.bonsai.md` file
+  defines the semantic tree structure
+- The homepage (`site/src/pages/index.astro`) splits entries by `_docs/` prefix
+  into "Pagine recenti" and "Documentazione" sections
+
+## Astro 6 content layer notes
+
+- Collections use glob loaders in `site/src/content.config.ts`
+- Custom `generateId` on the `entries` collection strips `_wiki/` prefix
+- Custom `generateId` on the `index` collection preserves dots (Astro 6's
+  default `generateId` applies `githubSlug()` which strips them — `i.bonsai`
+  would become `ibonsai`, breaking semtree lookup)
+- Use `entry.id` not `entry.slug`
+- Use `import { render } from 'astro:content'; render(entry)` not `entry.render()`
+
+## Language / i18n
+
+Italian is the default language. All documentation in `pages/_docs/` is in
+Italian. Technical terms (WikiRefs, Astro, plugin names, wikilink syntax,
+code) stay in English. See `docs/lingua.md` for the full rationale.
+
+## Authentication
+
+### Current approach (same as bincio_activity)
+
+**Not yet implemented in bincio_wiki** — pending.
+
+Planned pattern:
+- nginx serves the static Astro build publicly (no nginx-level auth)
+- Every Astro page layout calls `GET /api/me` on load
+- If the API returns 401/error, the page JS redirects to `/login/`
+- FastAPI (`edit/server.py`) handles sessions: SQLite users table, bcrypt
+  passwords, HTTP-only session cookie
+- Login page at `/login/` — a static Astro page that POSTs credentials to
+  `/api/auth/login`
+
+### Security assessment
+
+This is **client-side enforcement only**. The HTML is technically accessible
+to anyone who:
+- Uses `curl` or `wget` directly
+- Disables JavaScript in the browser
+- Views page source
+
+For bincio_wiki this is an acceptable tradeoff. The content is community
+memories and shared activities (not financial/medical data), members are not
+adversarial, and the goal is keeping casual visitors and search engine crawlers
+out — not resisting determined attackers.
+
+### Future: making specific pages public
+
+With this architecture, making a page public later is trivial: just use a
+layout variant that skips the `/api/me` check. No nginx changes needed since
+nginx already serves everything publicly at the static file level.
+
+For stricter enforcement on genuinely sensitive pages, the alternative is
+**Astro SSR** with a server middleware that checks the session cookie before
+rendering any HTML. This would require migrating from static output to SSR
+mode — a bigger change, not warranted for now.
+
+### VPS deployment target
+
+Debian 12 VPS. nginx serves the built site from `/var/www/bincio/wiki/`.
+FastAPI proxied from `localhost:8001` via nginx `location /api/ { proxy_pass }`.
+See `docs/vps.md` for full nginx config and deployment steps.
+
+## Git conventions
+
+- No `Co-Authored-By: Claude` trailers in commits
+- Commit messages in English
+- Do not push without explicit user instruction