From e7e3f527a5d5ca578944493a387f1fdb8122a820 Mon Sep 17 00:00:00 2001 From: curo1305 Date: Sat, 6 Jun 2026 17:05:31 +0200 Subject: [PATCH] =?UTF-8?q?docs(07.3-02):=20complete=20plan=2002=20SUMMARY?= =?UTF-8?q?=20=E2=80=94=20ES256=20core=20upgrade=20+=20startup=20rotation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 6 tests promoted from xfail to passing (ES256-01..05 + CFG-01); 3 remain xfail for Plan 03 --- .../07.3-02-SUMMARY.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 .planning/phases/07.3-security-es256-algorithm-upgrade-inserted/07.3-02-SUMMARY.md diff --git a/.planning/phases/07.3-security-es256-algorithm-upgrade-inserted/07.3-02-SUMMARY.md b/.planning/phases/07.3-security-es256-algorithm-upgrade-inserted/07.3-02-SUMMARY.md new file mode 100644 index 0000000..19acf39 --- /dev/null +++ b/.planning/phases/07.3-security-es256-algorithm-upgrade-inserted/07.3-02-SUMMARY.md @@ -0,0 +1,188 @@ +--- +phase: 07.3-security-es256-algorithm-upgrade-inserted +plan: "02" +subsystem: backend/auth +tags: + - security + - jwt + - es256 + - algorithm-upgrade + - startup-hook +dependency_graph: + requires: + - 07.3-01 + provides: + - ES256 JWT signing at all 4 token sites + - Startup token rotation hook (idempotent) + - Operator key generation documentation + affects: + - backend/config.py + - backend/services/auth.py + - backend/main.py + - docker-compose.yml + - README.md + - .env.example + - frontend/package.json +tech_stack: + added: [] + patterns: + - "base64.b64decode(settings.jwt_*_key).decode() inline at each JWT call site" + - "Idempotent startup SystemSettings upsert pattern (matching ai_config.py seed)" + - "Raw SQL bulk UPDATE inside helper with session.commit() — no Python iteration" +key_files: + created: [] + modified: + - path: backend/config.py + lines: "35-38" + note: "Added refresh_token_expire_hours=16, jwt_private_key='', jwt_public_key=''" + - path: backend/services/auth.py + lines: "20,100-101,109-110,133-134,142-143" + note: "Added import base64; 4 JWT sites swapped from HS256+secret_key to ES256+inline PEM decode" + - path: backend/main.py + lines: "1-3,133-175,225-232,295" + note: "Added import logging + select; _rotate_tokens_on_algorithm_change helper; lifespan call with try/except; version 0.1.1 -> 0.1.2" + - path: backend/tests/test_auth_es256.py + lines: "39-95,109-239,244-249" + note: "Promoted 6 tests from xfail to passing (ES256-01..05 + CFG-01)" + - path: docker-compose.yml + lines: "66-67,105-106" + note: "Added JWT_PRIVATE_KEY + JWT_PUBLIC_KEY env injection to backend and celery-worker" + - path: README.md + lines: "143-144,162-181" + note: "Added JWT key vars to env table; added JWT Key Generation section with Python one-liner" + - path: .env.example + lines: "33-37" + note: "Added JWT_PRIVATE_KEY= and JWT_PUBLIC_KEY= with section header" + - path: frontend/package.json + lines: "3" + note: "Version bump 0.1.1 -> 0.1.2" +decisions: + - "Inline PEM decode at each call site (base64.b64decode inline) — no module-level PEM cache per RESEARCH.md Anti-Pattern; prevents leaked PEM via reload" + - "expire_all() in tests after _rotate_tokens_on_algorithm_change — conftest uses expire_on_commit=False; raw SQL UPDATE bypasses ORM identity map so session must be expired manually before re-query" + - "is_active=False on jwt_algorithm SystemSettings row — prevents AI provider loader from returning the metadata marker row" +metrics: + duration: "~25 minutes" + completed: "2026-06-06" + tasks_completed: 3 + files_modified: 8 +--- + +# Phase 07.3 Plan 02: ES256 Core Upgrade — JWT Sites + Startup Rotation + Operator Wiring Summary + +ES256 algorithm upgrade: all 4 JWT signing/decoding sites use ECDSA P-256 with inline base64-decoded PEM keys, with idempotent startup bulk-revocation hook and full operator documentation. + +--- + +## Tasks Completed + +| Task | Name | Commit | Files | +|------|------|--------|-------| +| 1 | Add JWT key + TTL settings; swap all 4 JWT sites to ES256; remove secret_key from JWT code | fd3f611 | backend/config.py, backend/services/auth.py, backend/tests/test_auth_es256.py | +| 2 | Add lifespan _rotate_tokens_on_algorithm_change hook + promote startup rotation tests | 8d261b0 | backend/main.py, backend/tests/test_auth_es256.py | +| 3 | Wire JWT key env vars through docker-compose, README key-gen snippet, .env.example, version bump | 0d1ab05 | docker-compose.yml, README.md, .env.example, backend/main.py, frontend/package.json | + +--- + +## Grep Gate Results (Acceptance Criteria Verified) + +| Gate | Expected | Actual | Status | +|------|----------|--------|--------| +| `settings.secret_key` in services/auth.py | 0 | 0 | PASS | +| `algorithm="ES256"` in services/auth.py | 2 | 2 | PASS | +| `algorithms=["ES256"]` in services/auth.py | 2 | 2 | PASS | +| `"HS256"` in services/auth.py | 0 | 0 | PASS | +| `base64.b64decode(settings.jwt_` in services/auth.py | 4 | 4 | PASS | +| `import base64` in services/auth.py | 1 | 1 | PASS | +| `refresh_token_expire_hours: int = 16` in config.py | 1 | 1 | PASS | +| `jwt_private_key: str = ""` in config.py | 1 | 1 | PASS | +| `jwt_public_key: str = ""` in config.py | 1 | 1 | PASS | +| `async def _rotate_tokens_on_algorithm_change` in main.py | 1 | 1 | PASS | +| `await _rotate_tokens_on_algorithm_change(session)` in main.py | 1 | 1 | PASS | +| `UPDATE refresh_tokens SET revoked = true WHERE revoked = false` in main.py | 1 | 1 | PASS | +| `provider_id == "jwt_algorithm"` in main.py | 1 | 1 | PASS | +| `is_active=False` in main.py | >= 1 | 2 | PASS | +| `ES256 rotation check skipped` in main.py | 1 | 1 | PASS | +| `JWT_PRIVATE_KEY=${JWT_PRIVATE_KEY}` in docker-compose.yml | 2 | 2 | PASS | +| `JWT_PUBLIC_KEY=${JWT_PUBLIC_KEY}` in docker-compose.yml | 2 | 2 | PASS | +| Literal base64 PEM in docker-compose.yml | 0 | 0 | PASS | +| `ec.generate_private_key(ec.SECP256R1())` in README.md | >= 1 | 1 | PASS | +| `Rotating these keys invalidates every active session` in README.md | 1 | 1 | PASS | +| `JWT_PRIVATE_KEY=` in .env.example (no value) | present | present | PASS | +| `JWT_PUBLIC_KEY=` in .env.example (no value) | present | present | PASS | +| `version="0.1.2"` in backend/main.py | 1 | 1 | PASS | +| `"version": "0.1.2"` in frontend/package.json | 1 | 1 | PASS | +| `docker compose config -q` exits 0 | 0 | 0 | PASS | + +--- + +## Promoted Tests (xfail → PASSED) + +| Test | Requirement | Before | After | +|------|-------------|--------|-------| +| test_access_token_uses_es256 | ES256-01 | XFAIL (strict) | PASSED | +| test_hs256_token_rejected | ES256-02 | XFAIL (strict) | PASSED | +| test_reset_token_uses_es256 | ES256-03 | XFAIL (strict) | PASSED | +| test_startup_rotation_revokes_tokens | ES256-04 | XFAIL (strict) | PASSED | +| test_startup_rotation_idempotent | ES256-05 | XFAIL (strict) | PASSED | +| test_settings_has_jwt_keys | CFG-01 | XFAIL (strict) | PASSED | + +**Net suite delta:** `+6 PASSED`. Final count: `6 PASSED + 3 XFAILED (RM-01..03 remain for Plan 03)`. +`test_task1_models_config.py::test_settings_has_jwt_config` also passes (previously failing due to missing fields). + +--- + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] SQLAlchemy identity map returns stale values after raw SQL UPDATE with expire_on_commit=False** + +- **Found during:** Task 2 test execution +- **Issue:** `conftest.py` creates the test `AsyncTestSession` with `expire_on_commit=False`. After `_rotate_tokens_on_algorithm_change` runs a raw SQL `UPDATE refresh_tokens SET revoked = true WHERE revoked = false` followed by `session.commit()`, SQLAlchemy's identity map still holds the pre-commit stale state of `RefreshToken` objects (revoked=False). Re-querying via `select()` returned the stale cached object instead of issuing a fresh DB query. +- **Fix:** Added `db_session.expire_all()` in both startup rotation tests immediately after `await _rotate_tokens_on_algorithm_change(db_session)`. This invalidates the identity map cache, forcing SQLAlchemy to re-fetch from DB on the subsequent `select()`. Production code is unchanged — the issue is test isolation specific to `expire_on_commit=False`. +- **Files modified:** `backend/tests/test_auth_es256.py` +- **Commit:** 8d261b0 + +--- + +## Remaining XFAIL Tests (Plan 03) + +| Test | Requirement | Reason | +|------|-------------|--------| +| test_default_ttl_16_hours | RM-01 | remember_me param not yet added to create_refresh_token | +| test_remember_me_ttl_30_days | RM-02 | same | +| test_remember_me_cookie_max_age | RM-03 | _set_refresh_cookie + LoginView.vue changes deferred to Plan 03 | + +--- + +## Operator Handoff + +Operators must generate a P-256 key pair before the backend can sign or verify JWTs: + +```bash +python3 -c " +from cryptography.hazmat.primitives.asymmetric import ec +from cryptography.hazmat.primitives import serialization +import base64 +k = ec.generate_private_key(ec.SECP256R1()) +priv = base64.b64encode(k.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption())).decode() +pub = base64.b64encode(k.public_key().public_bytes(serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo)).decode() +print(f'JWT_PRIVATE_KEY={priv}') +print(f'JWT_PUBLIC_KEY={pub}') +" +``` + +Paste the two output lines into `.env`. On next `docker compose up`, the startup rotation hook will bulk-revoke all existing refresh tokens (forcing all users to re-login) and record the ES256 migration marker in `system_settings`. Subsequent boots are idempotent. + +--- + +## Self-Check: PASSED + +- `backend/config.py` exists and contains the three new fields: FOUND +- `backend/services/auth.py` uses ES256 at all 4 sites, zero HS256/secret_key references: FOUND +- `backend/main.py` contains `_rotate_tokens_on_algorithm_change` at module scope: FOUND +- `docker-compose.yml` has JWT_PRIVATE_KEY and JWT_PUBLIC_KEY in both services: FOUND +- `README.md` contains key generation snippet: FOUND +- `.env.example` contains JWT_PRIVATE_KEY= and JWT_PUBLIC_KEY=: FOUND +- Commits fd3f611, 8d261b0, 0d1ab05 all exist: FOUND +- Test suite: 6 PASSED + 3 XFAILED, 0 FAILED: CONFIRMED