Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,9 @@ Then open **http://localhost:8080** — nginx serves the app and proxies the API
| frontend | http://localhost:5173 | SvelteKit dev server (direct) |
| api | http://localhost:5050 | Flask API (direct) |
| postgres | localhost:5433 | Database |
| redis | (internal) | Rate-limit counters (prod) |

The development stack runs without Redis — the API then keeps rate-limit
counters in memory. Production adds a Redis container for them (see Tech stack).

A `SECRET_KEY` of 32+ characters is mandatory — the API refuses to start
without it. Generate one with `python -c 'import secrets; print(secrets.token_hex(32))'`.
Expand All @@ -68,7 +70,7 @@ without it. Generate one with `python -c 'import secrets; print(secrets.token_he

## Tech stack

- **Frontend** — SvelteKit + TypeScript, Vite, client-side WebCrypto + Argon2id (WASM)
- **Frontend** — SvelteKit 3 (Svelte 5) + TypeScript, Vite 8, served by `@sveltejs/adapter-node`; client-side WebCrypto + Argon2id (WASM)
- **API** — Flask (Python 3.11), gunicorn (schema initialised via `api/entrypoint.sh`), JWT auth
- **Database** — PostgreSQL 15, one opaque encrypted-document table
- **Rate-limit store** — Redis (in-memory only, lives in the data plane so counters survive app restarts)
Expand Down
15 changes: 10 additions & 5 deletions THIRD-PARTY-NOTICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,15 @@ file covers third-party code that ships *inside* ciphra and therefore carries
its own license along with it.

Ordinary dependencies are not listed here. npm and pip packages ship their own
`LICENSE` files inside `node_modules/` and `site-packages/`, and the resolved
set is pinned in `frontend/package-lock.json` and `api/requirements.txt`. Every
one of them is MIT, BSD-3-Clause, Apache-2.0, or LGPL-3.0+ — all compatible
with AGPL-3.0.
`LICENSE` files inside `node_modules/` and `site-packages/`. The frontend set is
pinned in `frontend/package-lock.json`; `api/requirements.txt` sets minimum
versions, and the API image resolves them when it is built. The licenses in
that set are permissive — MIT, MIT-0, BSD-2-Clause, BSD-3-Clause,
Apache-2.0, Zlib (`pako`) and PSF-2.0 (`typing_extensions`) — plus
`dompurify`, offered under MPL-2.0 *or* Apache-2.0 (ciphra takes it under
Apache-2.0), and `psycopg2-binary`, under LGPL-3.0-or-later. All are compatible
with AGPL-3.0. The base images (Node.js on Alpine, Python on Debian, nginx on
Alpine) carry their own license information inside the image.

---

Expand Down Expand Up @@ -68,5 +73,5 @@ SOFTWARE.
## Brand assets

`brand_assets/` and the ciphra wordmark, asterisk and icons in
`frontend/static/` are **not** covered by the AGPL. The code is free; the name
`frontend/static/` (`wordmark-*.svg`, `icon*`, `favicon*`, `og-image.png`) are **not** covered by the AGPL. The code is free; the name
and the marks are not. See the trademark note in [`README.md`](README.md#license).
12 changes: 8 additions & 4 deletions changelog.d/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,11 @@ The content is written exactly like a slice of the changelog — one or more

- `node scripts/changelog.mjs check` — every fragment parses (CI).
- `scripts/changelog-guard.sh` — a PR with `feat`/`fix` commits carries a
fragment, and only a release PR edits `CHANGELOG.md` (CI). Nothing to tell
users? Put `[skip changelog]` in the commit message or PR description.
Correcting notes that already shipped? `[changelog edit]`.
fragment, and only a release PR (one that changes `VERSION`) edits
`CHANGELOG.md` (CI, required for merge). Nothing to tell users? Put
`[skip changelog]` in the commit message, PR title or PR description.
Correcting notes that already shipped? `[changelog edit]` in a commit message
or the PR description.
- `node scripts/changelog.mjs preview` — what the next release would say.

## Releasing
Expand All @@ -56,4 +58,6 @@ set. The full process is in [`docs/VERSIONING.md`](../docs/VERSIONING.md).

Until then the app already shows pending entries under **Unreleased** at
`/docs → Changelog`, so a change that is deployed but not yet released is not
invisible to the people using it.
invisible to the people using it. The deploy wizard warns before it ships a
commit that still carries fragments (`scripts/release-state.sh`) — a warning,
not a block.
42 changes: 28 additions & 14 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,20 @@ model, key hierarchy, what the browser caches — see

## The shape of it

Five containers, one bridge network:
Five containers in production (four locally — redis is prod-only), one
bridge network:

```
browser ──► nginx :8080 ──┬──► frontend (SvelteKit) :5173
└──► /api/* ──► api (Flask) :5050 ──┬──► postgres :5432
└──► /api/* ──► api (Flask) :5000 ──┬──► postgres :5432
└──► redis :6379
```

Ports above are the **local dev** layout. In **production** the frontend
is built to `build/index.js` (adapter-node) and listens on `:3000`;
nginx (`:443`, Cloudflare-fronted) proxies there. Images are CI-built +
Ports above are the **local dev** layout, container-internal (on the host,
the API is published as `:5050` and postgres as `:5433`). In **production**
the frontend is built to `build/index.js` (adapter-node 6) and listens on
`:3000`; nginx (`:443`, Cloudflare-fronted, `nginx/ciphra.conf`) proxies
there. Images are CI-built +
cosign-signed and deployed via pull-based CD — see
[OPERATIONS.md](OPERATIONS.md) and [THREAT_MODEL.md](THREAT_MODEL.md).

Expand All @@ -26,8 +29,11 @@ cosign-signed and deployed via pull-based CD — see
relies on for rate-limiting and HSTS. In production, also rewrites
`$remote_addr` from the Cloudflare `CF-Connecting-IP` header and trusts the
docker bridge gateway so the real client IP reaches the rate-limiter.
- **frontend** — SvelteKit + TypeScript. All cryptography runs here.
- **api** — Flask (Python 3.11), run under gunicorn. A thin authenticated
- **frontend** — SvelteKit 3 + TypeScript. All cryptography runs here. The
kit config (including the hash-mode CSP) is the `kitConfig` export of
`frontend/vite.config.ts`; there is no `svelte.config.js`.
- **api** — Flask (Python 3.11), run under gunicorn in production (the
local-dev compose runs `python server.py` instead). A thin authenticated
store: it never decrypts anything. Schema is created and migrated at boot by
`api/entrypoint.sh` (which calls `init_db()` once before exec-ing gunicorn,
so workers don't race on `CREATE TABLE IF NOT EXISTS`). Migrations are a
Expand Down Expand Up @@ -146,9 +152,14 @@ SvelteKit, file-based routing under `frontend/src/routes/`:
| `/settings` | Account, language, family sharing |
| `/migrate`, `/join/[grantId]` | epilepc import; family-sharing claim |
| `/admin` | Operator dashboard — metadata only |
| `/docs`, `/docs/[slug]` | In-app viewer for the repo's documentation and pending changelog |
| `/privacy`, `/terms` | Public legal pages |
| `/sitemap.xml` | Generated sitemap (server route) |
| `/protocol`, `/stream` | Legacy URLs — client-side redirects to `/log/…` / `/reports` and `/journal` |

Shared code lives in `frontend/src/lib/`: `stores/` (auth, documents),
Shared code lives in `frontend/src/lib/` (imported as `#lib/…` via the
`imports` map in `frontend/package.json` — the `$lib` alias is gone since
SvelteKit 3): `stores/` (auth, documents),
`crypto.ts` (all browser-side crypto), `i18n/` (DE/EN/FR/IT), `blueprint/`
(presets, cohorts, types), `pdf.ts` (the doctor PDF), and `components/` (the
design-system primitives — see `components/README.md`).
Expand All @@ -159,12 +170,15 @@ Flask, defined in `api/server.py`. Grouped roughly as:

- **Auth** — `register`, `login/init` + `login`, `recover/init` + `recover`,
`change-password`, `delete-account` (GDPR self-service erasure).
- **Documents** — `GET/POST/PUT/DELETE /api/documents` — encrypted-blob CRUD.
- **Family sharing** — `family/grants` create/list/revoke, `claim/init` +
`claim`, and `family/documents` for caregiver access.
- **Admin** — `admin/stats`, `admin/users` (+ lock/unlock/promote/demote),
`admin/audit`.
- **`/health`** — liveness probe.
- **Documents** — `GET/POST/PUT/DELETE /api/documents` — encrypted-blob CRUD,
plus `documents/batch` (bulk import, idempotent via `client_key`) and
`documents/classify` (backfills `share_class` on the caller's own docs).
- **Family sharing** — `family/grants` create/list/revoke (+ `revoke-all`,
per-grant `scope`), `family/claimed`, `claim/init` + `claim`, and
`family/documents` for caregiver access.
- **Admin** — `admin/stats` (+ `stats/timeseries`), `admin/users`
(+ lock/unlock/promote/demote/delete), `admin/audit` (+ `audit/retention`).
- **`/health`** — liveness probe; also reports `schema` and `app_schema`.

Auth is a JWT bearer token issued at login; `password_version` on the user row
invalidates old tokens after a password change or recovery.
47 changes: 35 additions & 12 deletions docs/DEVELOPING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,12 @@ Local setup, demo data, tests, and project layout. For the system design see

- Docker + Docker Compose — the supported way to run the stack.
- For running frontend tooling directly on the host: Node.js **22** (the
baseline — `frontend/Dockerfile` is `node:22-alpine`; Vite 8 requires
≥20.19/22.12 and crashes on Node 18). See the vitest note under
[Tests](#tests).
baseline — the dev `frontend/Dockerfile` is `node:22.x-alpine`; the
production `frontend/Dockerfile.prod` builds and runs on `node:24.x-alpine`;
Vite 8 requires ≥20.19/22.12 and crashes on Node 18). See the vitest note
under [Tests](#tests).
- For running the API tests directly on the host: Python **3.11** (the API
image is `python:3.11.18-slim`).

## First run

Expand Down Expand Up @@ -37,17 +40,18 @@ docker compose up --build
| frontend | 5173 | 5173 | SvelteKit dev server, HMR |
| api | 5050 | 5000 | Flask; host port avoids the macOS :5000 AirPlay collision |
| postgres | 5433 | 5432 | host port 5433 avoids a local Postgres clash |
| redis | — | 6379 | rate-limit counter store (optional in dev — falls back to `memory://` if `REDIS_URL` is unset) |
| redis | — | — | **not in the dev compose** — prod only. Locally the rate limiter falls back to `memory://` because `REDIS_URL` is unset |

The database schema is created automatically by the API on first start.

### How schema init runs

- **Dev (`python server.py`):** Flask's built-in server triggers the
`if __name__ == '__main__': init_db()` block at the bottom of `server.py`.
`if __name__ == '__main__':` block at the bottom of `server.py`, which runs
`init_db()` + `apply_audit_retention()`.
- **Production (gunicorn):** the `__main__` block never fires — gunicorn
imports `server:app` as a module. Instead `api/entrypoint.sh` calls
`init_db()` once and then `exec`s gunicorn, so the schema is guaranteed
`init_db()` + `apply_audit_retention()` once and then `exec`s gunicorn, so the schema is guaranteed
to exist before any worker accepts a request and workers don't race on
`CREATE TABLE IF NOT EXISTS`.

Expand All @@ -59,9 +63,12 @@ Both paths are intentional. Don't remove the `__main__` block — it keeps
The `api/seed_*.py` scripts create demo accounts with realistic multi-year
histories — one per persona/condition (`seed_hans_epilepsy.py`,
`seed_anna_bipolar.py`, `seed_thomas_burnout.py`, …). All use the password
`Test$12345_`.
`Test$12345_`. The persona scripts are **gitignored** (`api/seed_*.py`), so
a fresh clone does not have them; only the guard they import,
`api/seed_guardrail.py`, is tracked.

Seeding is gated behind an env flag so it can never run by accident:
Seeding is gated behind an env flag (enforced by `api/seed_guardrail.py`)
so it can never run by accident:

```bash
cd api && CIPHRA_ALLOW_DEMO_SEED=1 \
Expand All @@ -79,16 +86,24 @@ password is whatever you set for `POSTGRES_PASSWORD` in `.env`.
```bash
cd frontend
npm run test # vitest (unit/component)
npm run check # svelte-check — type + Svelte diagnostics
npm run check # svelte-kit sync + svelte-check — type + Svelte diagnostics
npm run build # vite build (adapter-node)
```

The SvelteKit config lives in `frontend/vite.config.ts` (the exported
`kitConfig`, passed to `sveltekit(kitConfig)` and reused by
`vitest.config.ts`); there is no `svelte.config.js` since SvelteKit 3. The
CSP is in there too (`csp.mode: 'hash'`), pinned by
`src/app-html-csp.test.ts`. Shared code is imported as `#lib/…` with an
explicit file extension (the `imports` map in `package.json`), not `$lib`.

> **Gotcha:** run vitest via `npm run test` or `./node_modules/.bin/vitest`,
> **not** `npx vitest`. A cached npx vitest can require a newer Node than the
> repo's baseline and fail confusingly. If npx was used by mistake,
> `rm -rf ~/.npm/_npx` clears the cache.

The bar before shipping: vitest green, `svelte-check` 0 errors / 0 warnings,
`vite build` clean.
`vite build` clean, `pytest` green.

### Frontend — end-to-end (Playwright)

Expand Down Expand Up @@ -151,10 +166,13 @@ The API test tooling ships only in the Docker `dev` build target:
docker compose run --rm --build api pytest -q
```

Or on the host, with `requirements-dev.txt` installed:
`cd api && python -m pytest tests/ -v`.

## Building for production

```bash
cd frontend && npm run build # static SvelteKit build
cd frontend && npm run build # adapter-node build → build/index.js
docker build --target prod ./api # minimal API image (no test tooling)
```

Expand All @@ -172,7 +190,10 @@ production deploys should build `--target prod`.
ciphra/
├── README.md project overview + quick start
├── SECURITY.md vulnerability reporting policy
├── docker-compose.yml the 4-service stack
├── VERSION the product's SemVer (see docs/VERSIONING.md)
├── CHANGELOG.md compiled at release time from changelog.d/
├── changelog.d/ one fragment per user-facing change
├── docker-compose.yml the 4-service dev stack
├── .env.example env template
├── docs/ ARCHITECTURE, DEVELOPING, FEATURES, OPERATIONS,
│ SECURITY_MODEL, THREAT_MODEL, INCIDENT_RESPONSE,
Expand All @@ -181,6 +202,8 @@ ciphra/
│ ├── server.py the whole Flask API
│ ├── seed_*.py demo-data seed scripts
│ └── tests/ pytest suite
├── nginx/ edge config (default.conf dev, ciphra.conf prod)
├── scripts/ deploy wizard, changelog + version tooling, scan helpers
└── frontend/
└── src/
├── routes/ SvelteKit pages
Expand Down
Loading
Loading