2.5 KiB
2.5 KiB
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
fgpclaim allowed (forward-compat for existing sessions) _compute_fgpas 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