kite/.planning/phases/07.3-security-es256-algorithm-upgrade-inserted/07.3-02-SUMMARY.md

---
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