praxis/docs/RESEARCH-operator-postgres-auth.md

# RESEARCH: Operator Tier — Postgres-in-LXC + Auth for v0.3

**Scope:** Research only. No code changes. Grounded in the current Praxis repo
(`docker-compose.yml` single `praxis` service; `db/store.py` aiosqlite
`PraxisStore`; `db/migrate.py` ordered `.sql` migrations; SQLite schema at
`db/schema.sql`).

**Decisions honored:** D-007 (SQLite learner, preserved), D-031 (hybrid:
SQLite for learner, Postgres for operator), D-040 (Postgres = second
docker-compose service in the existing LXC CT), D-041 (session-cookie auth,
argon2id, single operator role, rate-limited).

**Confidence scores** are 0–1 (1 = well-established practice / low risk).

---

## 1. Docker-Compose Shape  *(confidence: 0.90)*

Add a `postgres` service alongside the existing `praxis` service. Key
best-practices for a second service in an already-running LXC CT:

- **Image:** `postgres:16-slim` (Debian-slim base, glibc — matches the
  praxis Dockerfile rationale; avoids Alpine musl locale issues with
  `pg_*` clients).
- **Persistence:** named volume `pgdata` (driver: local). Never bind-mount
  `/var/lib/postgresql/data` to the CT filesystem — Postgres requires
  `chown 999` and a specific directory layout; named volumes handle this.
- **Network isolation:** declare an explicit internal compose network and
  attach **only** `praxis` and `postgres` to it. Do **not** publish
  `5432` via `ports:`. The `praxis` service keeps its published `8789`.
  - `internal: true` on the network blocks egress to the host bridge, but
    note: with `internal: true` the postgres container cannot reach the
    internet (fine — it doesn't need to). If you later want outbound
    backups via network, drop `internal: true` and instead rely on
    *not* publishing the port. The simpler, robust choice for a pilot is:
    explicit named network, no `ports:` on postgres, no `internal: true`.
- **Healthcheck:** `pg_isready -U praxis -d praxis` every 10s, 5 retries,
  5s timeout. `depends_on: { postgres: { condition: service_healthy } }`
  on the `praxis` service so the app waits for accept-connections, not
  just container start.
- **Init scripts:** mount `./db/pg/init/*.sql` (or `.sh`) at
  `/docker-entrypoint-initdb.d/`. These run **only on first boot** (empty
  `pgdata`). Use them for: role/db creation, schema bootstrap, and
  idempotent seed. For *versioned* schema changes use a migration runner
  (see §6) — init scripts are one-shot.
- **Env:** `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` from the
  existing `/etc/praxis/server.env` (do **not** commit secrets to the
  compose file). Add `PGDATA=/var/lib/postgresql/data/pgdata` to pin the
  subdirectory (survives image upgrades).
- **Restart:** `restart: unless-stopped` (matches praxis).
- **Resources:** for a pilot on a small LXC CT, set a mem limit
  (`deploy.resources.limits.memory: 512m`) and rely on Postgres default
  `shared_buffers`. Tune later.

**Sketch (shape only, not for commit):**

```yaml
services:
  praxis:
    # ... existing v0.2 fields unchanged ...
    depends_on:
      postgres:
        condition: service_healthy
    networks: [praxis-net]

  postgres:
    image: postgres:16-slim
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${PG_USER}
      POSTGRES_PASSWORD: ${PG_PASSWORD}
      POSTGRES_DB: ${PG_DB:-praxis_operator}
      PGDATA: /var/lib/postgresql/data/pgdata
    env_file:
      - path: /etc/praxis/server.env
        required: false
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./db/pg/init:/docker-entrypoint-initdb.d:ro
      - pgbackups:/backups
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${PG_USER:-praxis} -d ${PG_DB:-praxis_operator}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks: [praxis-net]
    # NOTE: no `ports:` — not exposed to the LXC host bridge.

volumes:
  praxis-data:
    driver: local
  pgdata:
    driver: local
  pgbackups:
    driver: local

networks:
  praxis-net:
    driver: bridge
```

**Risk callouts:**
- If `praxis` currently has no explicit network, compose assigns the
  default bridge; adding an explicit network means the *existing*
  `praxis` service gets recreated on `up`. Plan a brief downtime window
  (see §6).
- `pg_isready` returns healthy before the DB is fully ready for migration
  load; `depends_on: service_healthy` is necessary but not sufficient —
  the app must still retry the first migration attempt.

---

## 2. Connection Management  *(confidence: 0.85)*

Two async DB drivers in one process: **aiosqlite** (already a dep) for the
learner store, **asyncpg** for the operator store.

- **Pools are independent and must not be shared.** asyncpg uses a
  `asyncpg.create_pool(...)` (sized pool, real connections). aiosqlite
  opens a fresh connection per `async with aiosqlite.connect(...)` (the
  current `PraxisStore._connect` pattern). They have nothing in common —
  different backends, different lifecycles. **Do not** wrap them in a
  single shared `AsyncSession` object; SQLAlchemy's async session is an
  option *only if* you adopt SQLAlchemy for both — that's a larger
  refactor and not warranted for v0.3.
- **Pool sizing (avoid exhaustion):**
  - asyncpg pool: `min_size=2, max_size=10` for a pilot single-instance.
    Operator endpoints are low-frequency (cohort dashboard, VC issuance).
  - aiosqlite: no pool; the current pattern opens/closes per call. SQLite
    is single-writer; keep `WAL` mode and short transactions. This is
    already fine for one learner.
  - Total concurrent DB connections ≈ asyncpg(10) + aiosqlite(1-2). On a
    small CT this is trivial. Exhaustion risk is essentially zero at
    pilot scale; revisit if operator endpoints are hit by N concurrent
    cohort users.
- **Lifecycle:** create the asyncpg pool once at FastAPI startup
  (`lifespan` context manager), close on shutdown. Store on
  `app.state.pg_pool`. The `PraxisStore` keeps its current per-call
  connect pattern (no change to D-007 code path).
- **Transaction boundaries:** asyncpg use `pool.acquire()` +
  `conn.transaction()` for multi-statement writes; aiosqlite unchanged.
- **Config:** `PG_DSN` env var, e.g.
  `postgresql://praxis:***@postgres:5432/praxis_operator` (host =
  service name on `praxis-net`).
- **Statement timeout:** set `command_timeout=10` on the asyncpg pool to
  prevent a slow operator query from blocking the event loop.

**Pip:** `asyncpg>=0.29` (new dep). `aiosqlite>=0.20` already present.

---

## 3. Auth Stack  *(confidence: 0.90 for the stack; 0.70 for rate-limit choice)*

D-041 spec: session-cookie, argon2id, single operator role, rate-limited.

### 3a. Session cookie
- **`starlette` `SessionMiddleware`** (FastAPI bundles Starlette). Uses
  `itsdangerous` to sign the cookie — no server-side session store
  needed (stateless, fits single-instance LXC). Data lives in the cookie
  itself, signed with `SECRET_KEY`.
- **Settings:**
  - `secret_key`: from env, ≥32 bytes random. **Rotate** by changing the
    key (invalidates all sessions — acceptable for a pilot).
  - `session_cookie`: `"praxis_op"` (distinct from any future learner
    cookie name).
  - `max_age`: `28800` (8h, per D-041).
  - `path`: `/` (or scope to `/op` if operator routes live under a
    prefix — cleaner).
  - `https_only`: `True` (Secure flag). **Requires TLS** — the LXC
    deployment must terminate TLS (reverse proxy / Caddy / Proxmox
    level). If running plain HTTP on the LAN for the pilot, set to
    `False` *temporarily* and document the risk; never ship False.
  - `httponly`: `True` (the middleware sets this by default; verify).
  - `samesite`: `"strict"` (D-041). CSRF defense-in-depth; with Strict,
    no credential is sent on cross-site navigations.
- **Cookie contents:** store `{operator_id: str, issued_at: epoch}`.
  **Never** store the password hash or any PII. Roles aren't needed in
  the cookie yet (single role — see §4).

### 3b. Password hashing — argon2id
- **`argon2-cffi`** (`PasswordHasher` default is argon2id, RFC 9106).
  Pip: `argon2-cffi>=23.1`.
- On login: `ph.verify(stored_hash, password)` → on success,
  `ph.check_needs_rehash(stored_hash)` → rehash if params bumped.
- Params: keep `PasswordHasher()` defaults for v0.3
  (`time_cost=3, memory_cost=64MiB, parallelism=4` — reasonable on a
  small CT; benchmark and tune if login latency > 1s).
- Store the hash as `TEXT` in `operators.password_hash`.

### 3c. Rate limiting
Two options:
1. **`slowapi`** (pip `slowapi>=0.1`) — the idiomatic FastAPI choice.
   Decorator/IP-based limiter. Default in-memory backend is fine for
   single-instance. **Confidence 0.70** — it works, but it's a young lib
   and the in-memory backend is per-process (breaks if you ever scale to
   >1 praxis process; not a v0.3 concern).
2. **In-memory counter** (a simple `dict[remote_ip, (count, window_start)]`
   in a small dependency) — zero deps, trivially auditable. For a single
   operator login endpoint this is enough. **Confidence 0.80** for the
   pilot specifically.

**Recommendation:** start with `slowapi` on the login route only
(`@limiter.limit("5/minute")`), in-memory backend. Migrate to a Redis
backend only if/when you go multi-instance. Threshold: 5 failed
attempts/minute/IP → 429 + exponential backoff marker.

**Pip additions:** `argon2-cffi>=23.1`, `slowapi>=0.1`. (`starlette` and
`itsdangerous` come with FastAPI.)

---

## 4. Auth Dependency Pattern  *(confidence: 0.90)*

Single-role v0.3 → **no RBAC framework needed.** A single FastAPI
`Depends` that resolves the operator from the signed session is the
minimal secure shape.

Concept (not committed code):

```python
# pseudo — shape only
async def current_operator(request: Request) -> Operator:
    sess = request.session  # populated by SessionMiddleware
    op_id = sess.get("operator_id")
    if not op_id:
        raise HTTPException(401, "not authenticated")
    op = await pg_store.get_operator(op_id)
    if not op or not op.is_active:
        # invalidate the cookie
        request.session.clear()
        raise HTTPException(401, "operator not found / disabled")
    return op
```

- Apply via `Depends(current_operator)` on every operator-tier router.
  Group operator routes under an `APIRouter(prefix="/op")` and attach
  the dependency at the router level
  (`dependencies=[Depends(current_operator)]`) — one declaration, not
  per-endpoint.
- Login/logout are **outside** the protected router (login is rate-
  limited, not auth-gated).
- **CSRF:** with `SameSite=Strict` + `httponly` cookies, CSRF surface is
  minimal for state-changing requests. If any operator endpoint accepts
  `Content-Type: application/x-www-form-urlencoded`/`multipart` (form
  posts), add a double-submit token or require `Content-Type:
  application/json` only (the latter is the cheaper defense — JSON
  bodies are not auto-sent by browsers across origins).

### When to migrate to RBAC
Migrate when **any** of these become true:
- A second role appears (admin, auditor, reviewer) — i.e. v0.4+ if the
  pilot expands.
- Permissions diverge *within* a role (e.g. some operators can issue
  VCs, others can only view cohorts).
- You need row-level visibility rules (operator A sees only their
  cohort).

At that point the cheapest upgrade is: add a `role` column to
`operators`, split `current_operator` into `current_operator` (any
authenticated) + `require_role("admin")` (a parametrized dependency
checking `op.role`). Reach for a full RBAC lib (`casbin`,
`fastapi-permissions`) only when the role matrix exceeds ~3 roles × ~5
permissions. **Don't pre-build it.**

---

## 5. Postgres Schema  *(confidence: 0.80)*

Operator-tier tables. Types chosen for Postgres 16 specifically
(`TIMESTAMPTZ`, `BIGSERIAL`, `GENERIC` via `JSONB`).

### `operators`
```
id              UUID PRIMARY KEY DEFAULT gen_random_uuid()
username        TEXT NOT NULL UNIQUE
password_hash   TEXT NOT NULL                 -- argon2id
display_name    TEXT NOT NULL
role            TEXT NOT NULL DEFAULT 'operator'  -- reserved for §4 migration
is_active       BOOLEAN NOT NULL DEFAULT TRUE
created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
last_login_at   TIMESTAMPTZ
```
- Index: unique on `username` (covered by constraint). No extra index
  needed at single-operator scale.
- Requires `pgcrypto` extension **or** Postgres 13+ (where
  `gen_random_uuid()` is built-in via `pgcrypto` shipped default —
  actually: `gen_random_uuid()` is built into core as of PG 13). So no
  extension needed on PG16. ✓

### `issued_credentials`
```
id              BIGSERIAL PRIMARY KEY
operator_id     UUID NOT NULL REFERENCES operators(id)
learner_ref     TEXT,                         -- opaque ref into SQLite side (no FK cross-DB)
vc_type         TEXT NOT NULL                 -- 'mastery' | 'completion' | ...
payload_jsonb   JSONB NOT NULL                -- the W3C VC document (signed elsewhere)
issued_at       TIMESTAMPTZ NOT NULL DEFAULT now()
revoked_at      TIMESTAMPTZ
```
- Indices:
  - `issued_credentials(operator_id, issued_at DESC)` — operator's
    issuance log.
  - `issued_credentials(learner_ref)` — lookup by learner (k-anon
    aggregate joins).
  - `issued_credentials(vc_type)` if filtering by type is a dashboard
    query.

### `mastery_gate_events`
```
id              BIGSERIAL PRIMARY KEY
learner_ref     TEXT NOT NULL
scenario_id     TEXT NOT NULL
path_id         TEXT NOT NULL                 -- learning path
gate_outcome    TEXT NOT NULL                 -- 'pass' | 'fail' | 'retry'
recorded_at     TIMESTAMPTZ NOT NULL DEFAULT now()
source          TEXT NOT NULL DEFAULT 'sync'  -- 'sync' from SQLite learner store
```
- Indices:
  - `(learner_ref, recorded_at DESC)` — per-learner timeline.
  - `(path_id, recorded_at)` — feeds the cohort aggregate.

### `cohort_aggregates` — k-anonymized
Model as **pre-materialized rows** partitioned by `(path_id, week)` with
a minimum bin size enforced at write time (k≥K, e.g. K=5). A 7-day
window is a rolling construct over the weekly partitions.

```
path_id         TEXT NOT NULL
week_start      DATE NOT NULL                 -- ISO week Monday
bin_count       INTEGER NOT NULL              -- learners in this bin
k_anon_pass     INTEGER NOT NULL              -- pass count, suppressed if < K
k_anon_fail     INTEGER NOT NULL              -- fail count, suppressed if < K
median_attempts INTEGER
updated_at      TIMESTAMPTZ NOT NULL DEFAULT now()
PRIMARY KEY (path_id, week_start)
```
- **k-anon rule:** when materializing, if `bin_count < K` emit
  `bin_count = <K-masked>` and null-out the count columns (or clamp
  them to K). Enforce in the aggregation job, **not** in a SQL view, so
  the suppression is auditable at write time.
- **7-day window:** compute on read as a window function over the last
  ≤2 weekly partitions, or maintain a parallel rolling table. For a
  pilot, compute on read:
  `SUM(k_anon_pass) ... WHERE week_start >= now()::date - interval '7 days'`.
- Indices: PK covers `(path_id, week_start)`. Add a secondary
  `(week_start DESC)` only if you query "all paths for the latest week"
  frequently.

**General indices summary:** 4 indices beyond PKs/constraints for v0.3
— keep it lean; add per slow-query evidence.

---

## 6. Migration Strategy  *(confidence: 0.85)*

Goal: add Postgres to the **running** v0.2 LXC CT without breaking the
learner service.

### Steps (ordered, low-risk)
1. **Prepare on a staging CT first** (clone the production LXC CT in
   Proxmox). Never test the migration path on the live CT.
2. **Add the `postgres` service + `praxis-net` + volumes** to
   `docker-compose.yml`. The `praxis` service gains
   `depends_on: postgres (service_healthy)` and joins `praxis-net`.
3. **Add init scripts** under `db/pg/init/`:
   - `00_create_schema.sql` — the four tables from §5.
   - `01_seed_operator.sh` — creates the initial operator with an
     argon2id hash (run from env-supplied temp password; force password
     change on first login).
   These run **only on first boot** of an empty `pgdata` volume.
4. **Add the asyncpg pool + operator store + auth wiring** to the praxis
   image (new code paths, new deps in `pyproject.toml`). Learner paths
   (`db/store.py`, `db/migrate.py`) **unchanged** — D-007 preserved.
5. **Build the new image** (`docker compose build praxis`) — does not
   touch the running container.
6. **Controlled cutover:**
   - `docker compose up -d postgres` → wait for healthy.
   - `docker compose up -d praxis` → recreate the praxis container with
     the new image. Expect ~5–15s of downtime (the learner voice loop
     is not HA anyway). The SQLite volume (`praxis-data`) is untouched,
     so learner state is preserved across the recreate.
7. **Smoke tests:** `/health`, learner voice loop, operator login, one
   cohort-dashboard read.
8. **Rollback plan:** if operator endpoints misbehave, revert the
   praxis image tag and `docker compose up -d praxis` again — Postgres
   stays up but unused. Learner path is independent, so a bad operator
   rollout does **not** regress v0.2 learner behavior. This is the
   core safety property of the hybrid (D-031) design.

### Versioned migrations beyond first boot
The SQLite side already has `db/migrate.py` (ordered `.sql`, `_migrations`
table). For Postgres, two options:
- **(a) Reuse the pattern:** a `pg_migrate.py` mirroring the SQLite
  runner, against a `_pg_migrations` table. Lowest cognitive load —
  same mental model, same directory convention (`db/pg/migrations/`).
- **(b) Adopt `yoyo-migrations` or `alembic`:** more machinery, not
  warranted at 4 tables.

**Recommendation (a):** mirror the existing runner. Run on praxis
startup (after the pool is up), idempotent. **Confidence 0.80** on the
pattern; it's exactly what v0.2 already does for SQLite.

---

## 7. Backup  *(confidence: 0.85)*

Minimum viable backup for a pilot operator Postgres in LXC:

- **Method:** `pg_dump -Fc` (custom compressed format) → file in the
  `pgbackups` volume. `-Fc` gives you selective restore and parallel
  restore later.
- **Frequency:** daily is enough for a pilot. A cron job *inside the
  postgres container* (or a sidecar) runs:
  ```
  pg_dump -U praxis -Fc praxis_operator > /backups/pg_$(date +%u).dump
  ```
  Using `%u` (day-of-week 1–7) gives a rolling 7-file retention with
  zero cleanup logic.
- **Where:** `/backups` is the `pgbackups` named volume. Keep backups
  **inside the compose stack** so they move with the CT. For off-CT
  safety: a Proxmox-level cron `pct push`/`rsync` of the `pgbackups`
  volume to the Proxmox host or a NAS — out of scope for the app, but
  the named volume makes it a one-line host-side copy.
- **Restore (drill it once):**
  ```
  docker compose exec postgres pg_restore -U praxis -d praxis_operator \
     --clean --if-exists /backups/pg_3.dump
  ```
  `--clean --if-exists` drops+recreates objects; safe against a
  partially-populated DB. **Never** restore into the live DB without
  stopping the praxis service first.
- **Don't back up** the SQLite side here — it's already on the
  `praxis-data` volume and covered by whatever volume backup the CT
  already has. Keep the two backup streams separate (matches the hybrid
  design).
- **Encryption at rest:** out of scope for the MVP; rely on LXC/Proxmox
  disk encryption. If the `pgbackups` volume is ever pulled off-host,
  `gpg -c` the dump in the cron step.

**Pip:** none new for backup (uses `pg_dump`/`pg_restore` shipped with
the postgres image).

---

## Summary table — new pip dependencies

| Dep | Purpose | Confidence |
|---|---|---|
| `asyncpg>=0.29` | Postgres async driver / pool | 0.90 |
| `argon2-cffi>=23.1` | argon2id password hashing | 0.95 |
| `slowapi>=0.1` | login rate limiting (in-memory) | 0.70 |
| `starlette` (already via FastAPI) | `SessionMiddleware` signed cookies | 0.95 |
| `itsdangerous` (already via Starlette) | cookie signing | 0.95 |

## Cross-cutting risks (watch list)

1. **TLS or not:** Secure cookie flag requires TLS. Confirm the LXC
   fronting layer terminates HTTPS before enabling `https_only=True`.
2. **First-boot-only init scripts:** if `pgdata` already exists (e.g.
   after a failed first boot), seed scripts **won't re-run** — keep a
   separate re-runnable seed path (the `01_seed_operator.sh` should be
   idempotent via `ON CONFLICT DO NOTHING` or a shell guard).
3. **Two migration runners** (SQLite + Postgres) — keep directory
   layouts visually distinct: `db/migrations/` (SQLite, existing) vs
   `db/pg/migrations/` (Postgres, new). Don't merge.
4. **Event-loop blocking:** argon2id hashing is CPU-bound
   (`time_cost=3` ≈ 30–80ms). For a single operator login this is fine
   on the main event loop; if you ever batch-hashed, move to
   `run_in_executor`. Not a v0.3 concern.
5. **Cross-DB joins are impossible** (SQLite ↔ Postgres). Anything that
   needs both (e.g. a dashboard joining learner sessions to issued VCs)
   must be assembled in application code. The `learner_ref` opaque key
   in `issued_credentials`/`mastery_gate_events` is the join handle —
   keep it stable and never reuse SQLite rowids directly (use the
   existing `sess-…`/`learner-1` string ids).