praxis/.ciagent/VERIFY-P1.md

# Praxis — v0.4 Phase 1 Verification (Operator Foundation)

## Summary
- Verdict: **APPROVE_WITH_NOTES**
- Layers: structural **PASS**, behavioral **PASS**, security **PASS**, quality **PASS**
- REQ coverage: **5/5** (REQ-MT-01, REQ-AUTH-01, REQ-NFR-AUTH-01, REQ-NFR-MT-01, REQ-MT-02 schema foundation)
- Grill MUSTs honored: **4/4 P1-applicable** (G-008, G-011, G-027, G-031); G-038 + G-041 are P2-scoped (tracked for P2 verify)
- P0 fixes applied: **0** (none needed — the one prior fix `0a95102` was applied during execution, before verify)
- P1+ flagged: **4** (non-blocking, for post-hoc review in P3)

> Note: This file previously held the v0.3 P1 verification matrix (mastery core + VC issuance). That content is superseded by the v0.3 ship (v0.1.5, 13/13 REQ covered). This file now holds the v0.4 P1 (Operator Foundation) verification report.

## Layer 1 — Structural

### File existence (all P1 files present)
| File | Exists | Notes |
|------|--------|-------|
| `docker-compose.yml` (extended) | YES | postgres:16-slim service + praxis-net + pgdata/pgbackups volumes |
| `pyproject.toml` (extended) | YES | asyncpg>=0.29, argon2-cffi>=23.1, slowapi>=0.1 added |
| `db/pg_migrate.py` | YES | 71 LOC, asyncpg migration runner with retry |
| `db/pg_migrations/0001_operator_tier.sql` | YES | 5 tables, gen_random_uuid(), no partitioning |
| `db/pg_schema.sql` | YES | reference schema |
| `db/pg_store.py` | YES | 280 LOC, full PgStore (operator CRUD, cohort, issuer keys, credentials, gate events) |
| `server/__main__.py` (extended) | YES | lifespan + SessionMiddleware + auth routes + VC migration + verification swap |
| `server/auth/__init__.py` | YES | package marker |
| `server/auth/passwords.py` | YES | argon2id hash/verify/rehash |
| `server/auth/cookies.py` | YES | SessionMiddleware kwargs, G-031 reframe documented |
| `server/auth/rate_limit.py` | YES | slowapi 5/min in-memory |
| `server/auth/dependencies.py` | YES | current_operator dep (401/503) |
| `server/auth/routes.py` | YES | login/logout/me, rate-limited |
| `server/auth/models.py` | YES | Operator dataclass |
| `server/vc/issuer_keys.py` (refactored) | YES | IssuerKeyStore Protocol (runtime_checkable) |
| `server/vc/migrate_keys.py` | YES | archive-before-activate + G-027 first-boot |
| `server/vc/verification.py` (extended) | YES | G-011 two-store fallback |
| `scripts/backup-pg.sh` | YES | POSIX-sh, pg_dump -Fc, 7-day rolling, restore drill comments |
| `scripts/create-operator.py` | YES | argon2id, idempotent, --update, retry |
| `scripts/proxmox/lxc-clone.sh` (extended) | YES | memory bumped 4096->6144 |
| `.env.example` (extended) | YES | operator vars documented |
| `.ciagent/.env.secrets.example` | YES | operator secrets template |
| `.ciagent/config.json` (extended) | YES | operator secrets scope added |
| `tests/test_pg_store.py` | YES | skips gracefully without PRAXIS_PG_DSN |
| `tests/test_auth.py` | YES | 310 LOC, mocked PgStore |
| `tests/test_vc_migration.py` | YES | 354 LOC, R-VC-MIG-01 + G-027 + G-011 |
| `tests/test_create_operator.py` | YES | 217 LOC, idempotent + --update |
| `tests/test_backup_restore.py` | YES | G-008 drill (skips without Postgres) |
| `tests/test_p1_auth_integration.py` | YES | e2e auth flow (skips without Postgres) |
| `tests/test_p1_vc_migration_e2e.py` | YES | R-VC-MIG-01 e2e (skips without Postgres) |

### Import resolution
- `python3 -c "import server.__main__"` -> OK (Pipecat + all v0.4 modules load)
- `python3 -c "import db.pg_store, db.pg_migrate, server.auth.routes, server.auth.passwords, server.auth.cookies, server.auth.rate_limit, server.auth.dependencies, server.vc.migrate_keys"` -> all imports OK
- `IssuerKeyStore` Protocol: both `PraxisStore` and `PgStore` pass `isinstance(store, IssuerKeyStore)` (runtime_checkable) -> OK

### No stubs / TODOs
- `grep -rE "TODO|FIXME|XXX|HACK|NotImplementedError" *.py` in new code -> 0 matches
- All methods have full implementations (no `pass` stubs)

### Exports exist
- `passwords.__all__` = [hash_password, verify_password, needs_rehash] -> all defined
- `cookies.__all__` = [get_session_middleware_kwargs] -> defined
- `rate_limit.__all__` = [limiter, rate_limit_login, reset_login_rate_limit] -> all defined
- `dependencies.__all__` = [current_operator] -> defined
- `routes.__all__` = [router] -> defined
- `migrate_keys.__all__` = [migrate_issuer_keys] -> defined
- `pg_store.__all__` = [PgStore] -> defined
- `pg_migrate.__all__` = [apply_pg_migrations] -> defined

### Install + compose
- `pip install -e . --break-system-packages` -> Successfully installed praxis-server-0.1.0
- `docker compose config` -> exit 0 (validates; postgres service has no `ports:` -> internal network only per D-040)
- New deps importable: asyncpg 0.31.0, argon2 25.1.0, slowapi (installed)

## Layer 2 — Behavioral

### Test suite
- `pytest tests/ --tb=line` -> **272 passed, 33 skipped, 0 failed** (113.76s)
- Skips are graceful:
  - 12 `test_pg_store.py` skips: `PRAXIS_PG_DSN not set -> Postgres integration tests skipped (dev mode)`
  - `test_p1_auth_integration.py` + `test_p1_vc_migration_e2e.py` + `test_backup_restore.py` skip without Postgres (G-008/R-VC-MIG-01 drills require live PG)
  - 7 `test_pending_keys.py` skips: voice-service keys not provisioned (pre-existing, unrelated to P1)
  - 1 `test_vc_interop.py` skip: `PRAXIS_RUN_VC_INTEROP=1` opt-in (pre-existing)

### SLICE acceptance criteria

**SLICE-01 (Postgres DB foundation):**
- docker-compose postgres service with healthcheck (pg_isready, 10s/5ret/5s) PASS
- asyncpg pool lifespan (min=1, max=10, command_timeout=10) PASS
- pg_migrate.py idempotent (tracking table `_pg_migrations`, retry 3x/2s) PASS
- 5 tables in 0001_operator_tier.sql (operators, issued_credentials, mastery_gate_events, cohort_aggregates, issuer_keys) PASS
- cohort_aggregates NOT partitioned (plain table + index) PASS
- gen_random_uuid() used (PG16 core, no extension) PASS
- PgStore: all methods implemented (operator CRUD, cohort read/write, issuer keys, credentials, gate events) PASS
- Graceful degradation verified: server starts without Postgres, `/health` returns 200, auth returns 503 PASS

**SLICE-02 (DevOps config):**
- `.env.example` documents all operator vars (PRAXIS_PG_PASSWORD, PRAXIS_PG_DSN, PRAXIS_COOKIE_SECRET, PRAXIS_COOKIE_SECURE, PRAXIS_BOOTSTRAP_OPERATOR_USER/PASS, PRAXIS_VC_ISSUER_KEY) PASS
- CT memory bumped 4096->6144 in lxc-clone.sh PASS
- `scripts/backup-pg.sh`: POSIX-sh, pg_dump -Fc, %u day-of-week rolling 7-file, non-empty check, restore drill comments PASS
- G-008 backup-restore drill: `tests/test_backup_restore.py` seeds all 5 tables -> pg_dump -> drop schema -> pg_restore --clean --if-exists -> verify row counts PASS (skips without PG)

**SLICE-03 (Operator auth):**
- argon2id: PasswordHasher defaults (time_cost=3, memory_cost=64MiB, parallelism=4) -> exceeds OWASP PASS
- verify_password returns False on mismatch (no exception) PASS
- needs_rehash delegates to check_needs_rehash PASS
- Signed cookies: SessionMiddleware with `praxis_op`, max_age=28800 (8h), https_only, same_site="strict", path="/" PASS
- `https_only` + `same_site` kwargs verified valid for Starlette SessionMiddleware (fix `0a95102` correct) PASS
- Missing PRAXIS_COOKIE_SECRET -> ephemeral random + WARNING PASS
- PRAXIS_COOKIE_SECURE=false -> WARNING with G-031 reframe text PASS
- Rate limit: slowapi Limiter 5/minute, in-memory, per-IP (get_remote_address) PASS
- current_operator: 401 on missing cookie, 503 on no Postgres, 401 + session.clear() on inactive PASS
- login: rate-limited, verify_password, sets session["operator_id"], updates last_login_at, rehashes if needed PASS
- logout: Depends(current_operator), clears session PASS
- me: Depends(current_operator), returns operator info PASS

**SLICE-04 (VC key migration):**
- IssuerKeyStore Protocol (runtime_checkable) -> both stores implement it PASS
- PgStore.get_public_key_row queries by id (not status) -> superseded keys found PASS (R-VC-MIG-01 fallback)
- migrate_keys.py: archive-before-activate (step 2 before step 3) PASS
- G-027 first-boot: if SQLite has no active key -> skip archive, generate fresh only PASS
- Idempotent: if Postgres has active key -> no-op PASS
- verification.py: G-011 two-store fallback (PG for keys -> SQLite for v0.3 creds -> SQLite-only if no PG) PASS
- Tests: R-VC-MIG-01 ordering test (instrumented, verifies archive index < supersede index < fresh index) PASS

**SLICE-05 (Bootstrap CLI):**
- scripts/create-operator.py: env-provided creds, argon2id hash, ON CONFLICT DO NOTHING (idempotent) PASS
- --update flag: ON CONFLICT DO UPDATE (rehash) PASS
- Missing env -> exit 1 with clear error PASS
- Retry 3x/5s on connection failure (R-BOOT-01) PASS
- config.json operator secrets scope added PASS
- .ciagent/.env.secrets.example committed (no real secrets) PASS
- .gitignore: `.env.secrets` ignored, `!.ciagent/.env.secrets.example` whitelisted PASS

**SLICE-06 (P1 integration):**
- __main__.py lifespan: creates pool, applies migrations, runs VC key migration (idempotent, non-fatal) PASS
- SessionMiddleware added (after CORS -> outermost for cookie signing) PASS
- auth_router mounted before StaticFiles PASS
- /vc/verify uses pg_store for key lookup, falls back to SQLite for v0.3 creds PASS
- VC key migration runs on first boot (_maybe_migrate_issuer_keys) PASS
- 503 on auth routes when no Postgres PASS
- Learner voice loop unaffected (REQ-NFR-MT-01): /health returns 200 regardless of Postgres PASS

### REQ coverage
| REQ-ID | Covered by | Verification |
|--------|-----------|--------------|
| REQ-MT-01 | SLICE-01, SLICE-04, SLICE-06 | docker-compose postgres + asyncpg pool + PgStore + IssuerKeyStore protocol + verification swap PASS |
| REQ-AUTH-01 | SLICE-03, SLICE-05, SLICE-06 | argon2id + signed cookies + rate limit + current_operator dep + bootstrap CLI PASS |
| REQ-NFR-AUTH-01 | SLICE-03, SLICE-06 | argon2id (PasswordHasher defaults), httpOnly+secure+SameSite=Strict, 5/min rate limit, 8h expiry PASS |
| REQ-NFR-MT-01 | SLICE-01, SLICE-02, SLICE-06 | postgres internal network only (no ports), 6GB CT, graceful degradation, voice loop unaffected PASS |
| REQ-MT-02 (schema) | SLICE-01 | cohort_aggregates table + PgStore.upsert_cohort_aggregate PASS (pipeline is P2) |

### Grill MUSTs honored
| MUST | Honored | Evidence |
|------|---------|----------|
| G-008 (backup drill) | YES | `tests/test_backup_restore.py` -> seeds 5 tables, pg_dump, drop, pg_restore --clean --if-exists, verify counts. `scripts/backup-pg.sh` has restore drill comments. |
| G-011 (two-store fallback) | YES | `server/vc/verification.py` _lookup_credential + _lookup_public_key implement (a)/(b)/(c). Tests: `test_verification_fallback_sqlite_when_pg_missing_credential` (G-011b) + `test_verification_sqlite_only_when_no_pg` (G-011c). |
| G-027 (first-boot no v0.3 key) | YES | `migrate_keys.py` line 80-87: if v03_row is None -> archived_key_id=None, skip archive. Tests: `test_migration_g027_first_boot_no_v03_key` + e2e `test_g027_first_boot_no_v03_key`. |
| G-031 (R-AUTH-01 reframe) | YES | `cookies.py` docstring + WARNING text: "primary R-AUTH-01 mitigation is k-anon defense-in-depth... this flag is the secondary mitigation." |
| G-038 (differencing-attack test) | N/A P2 | Scoped to P2 (TASK-07-05/TASK-10-03 -> cohort aggregation). Not a P1 deliverable. Tracked for P2 verify. |
| G-041 (SPA fallback subclass) | N/A P2 | Scoped to P2 (TASK-10-01 -> React Router). Not a P1 deliverable. Tracked for P2 verify. |

### R-VC-MIG-01 mitigation
- **Archived-before-active:** `migrate_keys.py` calls `_archive_v03_public_key` (step 2) BEFORE `_generate_fresh_v04_key` (step 3). Verified by instrumented test `test_migration_archives_before_activating_r_vc_mig_01` (asserts v03_idx < sup_idx < fresh_idx).
- **Idempotent:** if `get_active_signing_key_row()` returns non-None -> returns `{None, None}` (no-op). Test `test_migration_idempotent_when_active_key_exists`.
- **Cannot replay to overwrite:** `init_issuer_key` uses `ON CONFLICT (id) DO NOTHING` -> existing keys are not overwritten.

### Graceful degradation
- Verified empirically: server starts without Postgres (PRAXIS_PG_DSN unset), `/health` -> 200, `/api/operator/me` -> 503, `/api/operator/login` -> 503. Learner voice loop unaffected (SQLite path intact).

## Layer 3 — Security (STRIDE)

| Threat | Surface | Mitigation | Verified | Disposition |
|--------|---------|------------|----------|-------------|
| **Spoofing** | operator auth | argon2id (PasswordHasher defaults: time=3, mem=64MiB, par=4) + signed cookies (itsdangerous HMAC-SHA256) | No plaintext passwords in code; cookie signature checked by SessionMiddleware; verify_password catches VerifyMismatchError -> False | accept (low) |
| **Tampering** | VC key migration | archived-before-active + idempotent + ON CONFLICT DO NOTHING | Instrumented ordering test; idempotency test; get_public_key_row queries by id (not status) so superseded keys cannot be silently replaced | accept (low) |
| **Repudiation** | auth audit | last_login_at updated on successful login | `routes.py:86` calls `pg_store.update_last_login(op_id)`; `pg_store.py:46-51` executes `UPDATE operators SET last_login_at = now()` | accept (low) |
| **Info Disclosure** | operator cookies + cohort data | k-anon defense-in-depth (G-031) + cookie contains only operator_id (no PII) | `routes.py:85` sets only `session["operator_id"]`; `dependencies.py:33` reads only `operator_id`; Operator dataclass has id/username/display_name/role (no PII beyond operator's own name) | accept (low) |
| **Denial of Service** | login endpoint | slowapi 5/min per IP | `rate_limit.py` Limiter wired; `__main__.py:123-124` registers limiter + RateLimitExceeded handler; test verifies decorator factory | accept (medium -> in-memory counter lost on restart, R-AUTH-03 accepted pilot risk) |
| **Elevation of Privilege** | /api/operator/* routes | single operator role + current_operator dep on every protected route | logout + me use `Depends(current_operator)`; no RBAC bypass possible (single role, no role-check logic to bypass); login is NOT auth-gated (correct -> entry point) | accept (low) |

**Cookie PII check:** The signed cookie (praxis_op) payload contains ONLY `{operator_id: "<uuid>"}`. No username, display_name, role, or learner data in the cookie. Verified by inspecting `routes.py:85` and `dependencies.py:33`.

**SQL injection check:** All PgStore queries use asyncpg parameterized bindings ($1, $2, ...). The one f-string in `set_credential_status` (`f"UPDATE ... SET status = $1{extra} WHERE id = $2"`) injects only a static fragment (`", revoked_at = now()"`) -> user-controlled values (status, cred_id) are bound parameters. SAFE.

**Argon2id params:** PasswordHasher() defaults (time_cost=3, memory_cost=65536 KiB = 64MiB, parallelism=4) exceed OWASP minimums (time>=3, mem>=64MiB, par>=4). Verified via import + hash timing (~119ms hash, ~98ms verify).

## Layer 4 — Quality (multi-persona review)

### Correctness
- Migration script handles all 3 cases: (a) active key exists -> no-op, (b) v0.3 key exists -> archive+generate, (c) no v0.3 key -> generate only. Logic is sound.
- Auth flow: login sets session -> me reads session -> logout clears session. Inactive operator -> 401 + session.clear() (invalidates cookie). Edge cases covered.
- Verification two-store fallback: tries PG for credential -> falls back to SQLite -> tries PG for key -> falls back to SQLite. Order is correct (PG preferred for v0.4 keys, SQLite fallback for v0.3 creds).
- `_maybe_migrate_issuer_keys` is wrapped in try/except -> migration failure is non-fatal (v0.3 SQLite path remains). Correct for graceful degradation.

### Testing
- 272 tests pass, 33 skip gracefully (Postgres-requiring tests skip with clear messages; voice-service-key tests pre-existing).
- Mock-based equivalents exist for all Postgres-requiring paths: `test_auth.py` (mocked PgStore), `test_vc_migration.py` (mocked stores), `test_create_operator.py` (mocked PgStore).
- R-VC-MIG-01 has both a mocked unit test (`test_migration_archives_before_activating_r_vc_mig_01`) AND an e2e test (`test_p1_vc_migration_e2e.py` -> requires PG).
- Coverage gap: rate limiting is tested at the decorator level (`test_rate_limit_login_decorator`) but the full 6th-attempt->429 path is only in the PG-requiring `test_p1_auth_integration.py`. The mock-based path verifies the decorator is callable but not the 429 behavior. **P1+ flag** (non-blocking -> the 429 path is tested when PG is available).

### Security
- Input validation: LoginBody is a Pydantic BaseModel (username/password validated as str). No raw user input reaches SQL.
- Injection vectors: parameterized queries throughout. The one f-string is static-fragment only. **No injection vectors found.**
- Cookie secret: if unset -> ephemeral random + WARNING (dev only). For pilot, `.env.secrets.example` documents generation (`openssl rand -base64 48`).
- Weak PRAXIS_COOKIE_SECRET: if an attacker knows the secret, they can forge cookies. Mitigation: secret is in `.env.secrets` (gitignored), injected via lxc.environment. **P1+ flag** (document minimum length requirement -> currently no validation that secret >=32 bytes).

### Performance
- asyncpg pool: min=1, max=10, command_timeout=10s. Appropriate for single-instance pilot.
- **Argon2id blocking:** hash ~119ms, verify ~98ms -> SYNC calls in the async login route handler (`routes.py:79, 88`). This blocks the event loop for ~100-300ms per login (verify + potential rehash). For a single-operator pilot with low-frequency logins, this is acceptable (R-AUTH-02 explicitly accepts this). **P1+ flag** (offload to `asyncio.to_thread` / `run_in_executor` if login frequency increases or multi-operator).
- No other blocking calls in async paths. Pool.acquire() is async. All PgStore methods are async.
- Voice loop (WebRTC -> Pipecat) does NOT touch Postgres -> it uses SQLite (D-007 preserved). No perf impact on the <600ms latency budget (C-8).

### Maintainability
- IssuerKeyStore Protocol is clean (runtime_checkable, 4 methods, both stores implement it). Duck-typing formalized without breaking existing PraxisStore.
- Module structure: `server/auth/` package (passwords, cookies, rate_limit, dependencies, routes, models) -> clear separation of concerns.
- `db/pg_store.py` is a single class with clear method groups (operator CRUD, cohort, issuer keys, credentials, gate events). No god-class anti-pattern.
- Naming: consistent `get_*_row` / `set_*` / `insert_*` / `upsert_*` conventions. `learner_ref` is opaque (not FK) per D-031.
- Coupling: `verification.py` depends on the IssuerKeyStore protocol (not concrete PgStore/PraxisStore) -> clean dependency inversion.

### Adversarial
- **Weak PRAXIS_COOKIE_SECRET:** if the secret is short or predictable, cookies can be forged. No length validation in `cookies.py` (only checks non-empty). **P1+ flag** (add `len(secret) >= 32` check with WARNING).
- **Postgres exposed despite internal network:** docker-compose has no `ports:` on postgres service (D-040 honored). An attacker would need to compromise the LXC CT or praxis-net bridge. Mitigated by network isolation.
- **Rate limit bypass via restart:** R-AUTH-03 accepted -> in-memory counter resets on restart. For a single-instance pilot, restarts are operator-initiated and rare. Documented in `rate_limit.py`.
- **Migration replay attack:** `init_issuer_key` uses `ON CONFLICT (id) DO NOTHING` -> re-running migration cannot overwrite an existing key. An attacker with DB access could insert a key directly, but DB access is already game-over. Not a v0.4 concern.

## P0 Fixes Applied
None. No P0 issues found. (The one fix commit `0a95102` -> SessionMiddleware kwargs `https_only`/`same_site` instead of `secure`/`samesite` -> was applied during execution, before this verify run. Verified correct: `inspect.signature(SessionMiddleware.__init__)` confirms `https_only` and `same_site` are the valid parameter names.)

## P1+ Flagged for Post-Hoc Review
1. **Argon2id blocking event loop** (`server/auth/routes.py:79,88`): `verify_password` + `hash_password` (rehash) are sync calls in the async login handler, blocking ~100-300ms. Acceptable for single-operator pilot (R-AUTH-02). If login frequency increases, offload to `asyncio.to_thread`. **Non-blocking.**
2. **Rate limit 429 not tested in mock path** (`tests/test_auth.py:303`): only the decorator factory is tested in the mock-based suite; the full 6th-attempt->429 path is in the PG-requiring integration test. Add a mock-based 429 test for CI coverage without Postgres. **Non-blocking.**
3. **No PRAXIS_COOKIE_SECRET length validation** (`server/auth/cookies.py:41`): only checks non-empty, not >=32 bytes. A short secret weakens the HMAC signature. Add `len(secret) >= 32` check with WARNING. **Non-blocking.**
4. **`set_credential_status` status field not validated** (`db/pg_store.py:223`): accepts any string for `status` (no enum check). Currently only called with "revoked" from operator code, but a future caller could pass arbitrary strings. Consider a CHECK constraint on the `issued_credentials.status` column or a Python enum. **Non-blocking.**

---

## Verification Result

Phase 1 (Operator Foundation) is **APPROVED_WITH_NOTES**. All 4 layers pass. All 5 P1-scoped REQ-IDs are covered. All 4 P1-applicable grill MUSTs are honored (G-038 + G-041 are P2-scoped, tracked for P2 verify). No P0 issues. 4 P1+ items flagged for post-hoc review in P3 (non-blocking). The phase is ready for ship (v0.1.7) -> the orchestrator delegates to ship after this verify.