136 lines
4.9 KiB
Markdown
136 lines
4.9 KiB
Markdown
# Phase 7.3: Security — ES256 Algorithm Upgrade - Discussion Log
|
||
|
||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||
|
||
**Date:** 2026-06-05
|
||
**Phase:** 07.3-security-es256-algorithm-upgrade-inserted
|
||
**Areas discussed:** Key format in env vars, Startup refresh-token rotation, Key generation workflow, JWT TTL / Remember Me
|
||
|
||
---
|
||
|
||
## Key Format in Env Vars
|
||
|
||
### Q1: How should P-256 PEM keys be stored in env vars?
|
||
|
||
| Option | Description | Selected |
|
||
|--------|-------------|----------|
|
||
| Base64-encoded | Single line, shell-safe, decoded in config.py | ✓ |
|
||
| Escaped `\n` in .env | python-dotenv expands `\n`; loader-dependent | |
|
||
| Multiline .env block | Breaks in docker-compose environment: block | |
|
||
|
||
**User's choice:** Base64-encoded
|
||
**Notes:** Standard 12-factor approach; no loader ambiguity.
|
||
|
||
---
|
||
|
||
### Q2: Both keys required, or derive public from private at startup?
|
||
|
||
| Option | Description | Selected |
|
||
|--------|-------------|----------|
|
||
| Both required env vars | Clean separation; workers can hold public key only | ✓ |
|
||
| Private key only — derive public | Fewer env vars but more magic in config.py | |
|
||
|
||
**User's choice:** Both required env vars
|
||
|
||
---
|
||
|
||
### Q3: What happens to SECRET_KEY after ES256?
|
||
|
||
| Option | Description | Selected |
|
||
|--------|-------------|----------|
|
||
| Remove from JWT code | SECRET_KEY no longer used for signing; stays in env for future HMAC | ✓ |
|
||
| Repurpose as HMAC key for Phase 7.4 | Forward-compatible but couples phases | |
|
||
|
||
**User's choice:** Remove SECRET_KEY from JWT code
|
||
|
||
---
|
||
|
||
## Startup Refresh-Token Rotation
|
||
|
||
### Q1: How to implement startup rotation?
|
||
|
||
| Option | Description | Selected |
|
||
|--------|-------------|----------|
|
||
| DELETE all refresh_tokens | Simple, one-shot; no schema change | |
|
||
| Bulk revoke (set revoked=True) | Cleaner audit trail; same user impact | ✓ |
|
||
| Let natural expiry handle it | Doesn't satisfy ROADMAP requirement | |
|
||
|
||
**User's choice:** Bulk revoke (set revoked=True)
|
||
|
||
---
|
||
|
||
### Q2: How to detect "first boot after ES256 migration"?
|
||
|
||
| Option | Description | Selected |
|
||
|--------|-------------|----------|
|
||
| Check system_settings table | Stores `jwt_algorithm`; idempotent on restart | ✓ |
|
||
| New env var JWT_TOKEN_GENERATION=N | Simple but requires operator bump on deploy | |
|
||
| One-time Alembic migration | Runs at migrate time, not startup | |
|
||
|
||
**User's choice:** Check system_settings table (`jwt_algorithm` key)
|
||
|
||
---
|
||
|
||
## Key Generation Workflow
|
||
|
||
### Q1: How should developers generate the key pair?
|
||
|
||
| Option | Description | Selected |
|
||
|--------|-------------|----------|
|
||
| Python one-liner in README | Uses existing `cryptography` dep; no extra tooling | ✓ |
|
||
| openssl CLI command | Familiar to ops but multi-step, requires openssl | |
|
||
| Auto-generate on first boot | Convenient for dev; dangerous in prod (ephemeral keys) | |
|
||
|
||
**User's choice:** Python one-liner documented in README
|
||
|
||
---
|
||
|
||
### Q2: docker-compose key placeholder vs. .env reference?
|
||
|
||
| Option | Description | Selected |
|
||
|--------|-------------|----------|
|
||
| .env file reference only | Follows existing ${SECRET_KEY} pattern | ✓ |
|
||
| Placeholder comment in docker-compose | Helpful but could mislead | |
|
||
|
||
**User's choice:** .env file reference only
|
||
|
||
---
|
||
|
||
## JWT TTL / Remember Me
|
||
|
||
### Q1 (freeform): What token should default to 12 hours?
|
||
|
||
User note: "JWT Tokens should only be valid for 12 hours and the user can opt-in to create a token which is valid for 30 days."
|
||
|
||
Asked for clarification on whether this applied to the access token or refresh token. User asked: "What do you think is the most secure way to handle tokens?"
|
||
|
||
**Claude's recommendation:** Keep access token at 15 min (CLAUDE.md requirement). Change refresh token default to 16–24 hours with explicit "remember me" opt-in for 30 days.
|
||
|
||
**User's decision:** 16 hours — covers a full workday; guarantees session is revoked overnight.
|
||
|
||
---
|
||
|
||
### Q2: Fold "remember me" into Phase 7.3 or separate phase?
|
||
|
||
| Option | Description | Selected |
|
||
|--------|-------------|----------|
|
||
| Fold into Phase 7.3 | Already touching token creation code; incremental work | ✓ |
|
||
| Separate phase 7.5 | Keeps 7.3 purely as ES256 upgrade | |
|
||
|
||
**User's choice:** Fold into Phase 7.3
|
||
|
||
---
|
||
|
||
## Claude's Discretion
|
||
|
||
- PyJWT API form: `jwt.encode(payload, pem_str, algorithm="ES256")` — PEM strings passed directly, no key object conversion needed
|
||
- Bulk revoke via raw SQL `UPDATE` rather than ORM row-by-row — efficiency decision
|
||
- "Stay signed in for 30 days" as checkbox label (clearer than "Remember me")
|
||
- system_settings key name: `jwt_algorithm`, value `"ES256"`
|
||
|
||
## Deferred Ideas
|
||
|
||
- **Phase 7.4:** Token fingerprinting / token binding (`fgp` claim = HMAC of User-Agent + Accept-Language)
|
||
- **Key rotation ceremony:** Dual-key overlap process for rotating P-256 keys in production — deferred until production hardening milestone
|