60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# Phase 7.4: Security — Token Fingerprinting / Token Binding - 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-06
|
|
**Phase:** 07.4-security-token-fingerprinting-token-binding-inserted
|
|
**Areas discussed:** HMAC key source, Missing-header behavior, Mismatch enforcement
|
|
|
|
---
|
|
|
|
## HMAC Key Source
|
|
|
|
| Option | Description | Selected |
|
|
|--------|-------------|----------|
|
|
| SECRET_KEY | Already in docker-compose; Phase 7.3 D-03 explicitly reserved it for this use. No new env var needed. | ✓ |
|
|
| New FGP_HMAC_KEY env var | Dedicated key — key-separation principle. Requires adding to config.py, docker-compose.yml, .env, and README. | |
|
|
|
|
**User's choice:** SECRET_KEY
|
|
**Notes:** The prior-phase decision (7.3 D-03) already pointed here; confirmed.
|
|
|
|
---
|
|
|
|
## Missing-Header Behavior
|
|
|
|
| Option | Description | Selected |
|
|
|--------|-------------|----------|
|
|
| Empty string fallback | Use "" for any absent header; fgp always computed and validated. CLI tools and Postman work fine, binding to fgp("",""). | ✓ |
|
|
| Skip fingerprint check entirely | Omit fgp claim when headers absent; skip validation when claim absent. Weakens protection. | |
|
|
| Reject at issuance (401) | Login fails if User-Agent missing. Strongest binding but breaks all non-browser clients. | |
|
|
|
|
**User's choice:** Empty string fallback
|
|
**Notes:** Graceful handling — no client breakage, consistent enforcement.
|
|
|
|
---
|
|
|
|
## Mismatch Enforcement
|
|
|
|
| Option | Description | Selected |
|
|
|--------|-------------|----------|
|
|
| Hard 401 always | Token rejected immediately. Correct security posture. Browser updates are rare. | ✓ |
|
|
| Log-only soft mode | Log WARNING, allow request through. Safe for rollout but provides zero protection. | |
|
|
|
|
**User's choice:** Hard 401 always
|
|
**Notes:** The feature is meaningless if not enforced. Ship it enforced.
|
|
|
|
---
|
|
|
|
## Claude's Discretion
|
|
|
|
- Placement of fgp check in `get_current_user` (after user_nbf block)
|
|
- Migration grace: tokens without `fgp` claim allowed (forward-compat for existing sessions)
|
|
- `_compute_fgp` as a module-private helper called from both issuance and validation sites
|
|
- Test coverage cases (4 scenarios specified in CONTEXT.md specifics)
|
|
|
|
## Deferred Ideas
|
|
|
|
- Production key-rotation ceremony for SECRET_KEY — RUNBOOK documentation, future milestone
|
|
- Per-request device key pinning (stronger binding) — not needed for v1
|