# 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