kite/.planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-02-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, duration, completed

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	duration	completed
07.4-security-token-fingerprinting-token-binding-inserted	02	auth	jwt fgp token-binding token-fingerprinting hmac security wave-1	phase provides 07.4-01 Wave 0 xfail stubs for FGP-01..FGP-04 in test_auth_fgp.py	_compute_fgp helper in services/auth.py (16-char hex HMAC-SHA256 fingerprint) fgp claim in every issued JWT access token fgp validation block in get_current_user (deps/auth.py) Login + refresh call sites in api/auth.py pass User-Agent + Accept-Language 4 passing FGP integration tests (promoted from xfail stubs)	All API endpoints using get_current_user — fgp now validated on every request Test infrastructure — _TEST_USER_AGENT constant added to conftest.py	added patterns _compute_fgp HMAC-SHA256 with settings.secret_key as HMAC key (D-04) hmac.compare_digest for constant-time fgp comparison (SEC-06) Empty fgp_claim allows request — migration grace for pre-7.4 tokens (D-06) _TEST_USER_AGENT constant in conftest.py for test infrastructure fgp consistency	created modified backend/services/auth.py backend/deps/auth.py backend/api/auth.py backend/tests/test_auth_fgp.py backend/tests/conftest.py backend/tests/test_auth_deps.py backend/tests/test_cloud.py backend/tests/test_documents.py backend/tests/test_security_headers.py backend/main.py frontend/package.json	_compute_fgp defined in services/auth.py (not deps/auth.py) so both token issuance and validation call the same implementation via auth_service._compute_fgp fgp validation block outside try/except — pure computation with no I/O, so no fail-open path needed (unlike user_nbf Redis check) _TEST_USER_AGENT='docuvault-test/1.0' added to conftest.py; async_client fixture and all token-issuing fixtures now use this constant to ensure fgp consistency in test environments FGP-04 test sends User-Agent='' explicitly because httpx.AsyncClient defaults to python-httpx/X.Y.Z which would mismatch the empty-string fgp	35min	2026-06-06

Phase 07.4 Plan 02: Token Fingerprinting (FGP) Implementation Summary

Token fingerprinting end-to-end: HMAC-SHA256 fgp claim embedded in every access token; validated in get_current_user with hmac.compare_digest; login+refresh pass headers; all 4 FGP tests passing

Performance

• Duration: ~35 min
• Started: 2026-06-06T20:00:00Z
• Completed: 2026-06-06T20:35:00Z
• Tasks: 3
• Files modified: 11

Accomplishments

• Added _compute_fgp(user_agent, accept_lang) helper to backend/services/auth.py
  • Returns 16-char hex HMAC-SHA256 prefix using settings.secret_key as key
  • Uses existing import hmac and import hashlib — no new imports needed
• Extended create_access_token signature with user_agent: str = "" and accept_lang: str = ""
  • Backward-compatible defaults (D-05)
  • Embeds "fgp": _compute_fgp(user_agent, accept_lang) in JWT payload
• Added fgp validation block to get_current_user in backend/deps/auth.py
  • Added import hmac
  • Placed after user_nbf check and before UUID parse
  • Empty fgp_claim → skip (migration grace for pre-7.4 tokens, D-06)
  • Non-empty fgp_claim → recompute and compare with hmac.compare_digest
  • Mismatch → HTTP 401 "Token fingerprint mismatch" (D-03)
  • Not wrapped in try/except — pure computation, no I/O (T-07.4-04 mitigated)
• Updated both create_access_token call sites in backend/api/auth.py
  • Login handler: passes User-Agent and Accept-Language headers
  • Refresh handler: same header passthrough
• Promoted all 4 xfail stubs in test_auth_fgp.py to real assertions (0 xfail → 4 passed)
• Version bumped to 0.1.3 (backend/main.py and frontend/package.json)
• Full pytest suite: 404 passed, 4 skipped, 7 xfailed, 0 failed

Task Commits

1. Task 1: Add _compute_fgp + extend create_access_token - 25c9142
2. Task 2: Add fgp validation block to get_current_user - 1420180
3. Task 3: Update call sites, promote tests, version bump (+ Rule 1 fix) - 61b1e04

Files Created/Modified

• backend/services/auth.py — added _compute_fgp helper + extended create_access_token signature + fgp payload key
• backend/deps/auth.py — added import hmac + fgp validation block after user_nbf check
• backend/api/auth.py — login and refresh call sites updated to pass User-Agent + Accept-Language headers
• backend/tests/test_auth_fgp.py — 4 xfail stubs promoted to real passing integration tests
• backend/tests/conftest.py — _TEST_USER_AGENT constant + updated async_client fixture + updated auth_user/second_auth_user/admin_user fixtures
• backend/tests/test_auth_deps.py — import _TEST_USER_AGENT; updated auth_client fixture + all create_access_token calls
• backend/tests/test_cloud.py — import _TEST_USER_AGENT; updated _create_user_and_token helper
• backend/tests/test_documents.py — updated 3 inline create_access_token calls
• backend/tests/test_security_headers.py — import _TEST_USER_AGENT; updated headers_client + token creation
• backend/main.py — version 0.1.2 → 0.1.3
• frontend/package.json — version 0.1.2 → 0.1.3

Decisions Made

• _compute_fgp is defined in services/auth.py (service layer) and accessed from deps/auth.py via the already-imported auth_service._compute_fgp — avoids circular import and keeps fingerprint logic centralized in the service layer
• fgp validation block is NOT wrapped in try/except because _compute_fgp is pure computation with no I/O infrastructure that could fail; unlike the Redis user_nbf check, there is no "fail-open" scenario needed
• _TEST_USER_AGENT = "docuvault-test/1.0" constant added to conftest.py; all test clients and token-issuing fixtures use this constant to ensure fgp consistency across the test suite

Deviations from Plan

Auto-fixed Issues

1. [Rule 1 - Bug] Test infrastructure fgp mismatch: httpx default User-Agent vs empty-string fgp binding

• Found during: Task 3 verification
• Issue: When running pytest tests/test_auth_api.py tests/test_auth_deps.py, 10 tests failed with 401. The root cause: auth_user, admin_user, second_auth_user fixtures call create_access_token(...) without user_agent, so tokens are bound to fgp(""). But httpx.AsyncClient sends User-Agent: python-httpx/0.28.1 by default. The fgp check in get_current_user recomputed the fingerprint from this non-empty User-Agent and found it didn't match the token's fgp("") → 401.
• Fix: Added _TEST_USER_AGENT = "docuvault-test/1.0" to conftest.py. Updated async_client fixture to send this constant as the User-Agent. Updated auth_user, second_auth_user, admin_user fixtures to pass user_agent=_TEST_USER_AGENT to create_access_token. Updated test_auth_deps.py, test_cloud.py, test_documents.py, and test_security_headers.py to use the same constant.
• Files modified: backend/tests/conftest.py, backend/tests/test_auth_deps.py, backend/tests/test_cloud.py, backend/tests/test_documents.py, backend/tests/test_security_headers.py
• Commit: 61b1e04 (part of Task 3 commit)

2. [Rule 1 - Bug] FGP-04 test logic: httpx sends default User-Agent even when not specified

• Found during: Task 3 first test run
• Issue: test_missing_headers_empty_string_binding created a token with empty-string fgp (no user-agent args) and sent a request "with no User-Agent". But httpx.AsyncClient adds User-Agent: python-httpx/0.28.1 automatically → fgp mismatch → 401 instead of 200.
• Fix: Updated the test to explicitly set "User-Agent": "" in the request headers, matching what the server would compute (_compute_fgp("", "")) and the token's fgp claim.
• Files modified: backend/tests/test_auth_fgp.py
• Commit: 61b1e04

Known Stubs

None. All 4 FGP tests are real assertions producing passing results.

Threat Flags

None — this plan implements the mitigations described in the threat model:

• T-07.4-01 (token replay): fgp mismatch now returns 401
• T-07.4-02 (timing attack): hmac.compare_digest used
• T-07.4-04 (exception swallowing): fgp block outside try/except

Self-Check: PASSED

• backend/services/auth.py contains def _compute_fgp and "fgp": _compute_fgp(user_agent, accept_lang)
• backend/deps/auth.py contains import hmac, "Token fingerprint mismatch", fgp_claim = payload.get("fgp", ""), hmac.compare_digest(fgp_claim, fgp_actual)
• backend/api/auth.py shows 2 matches for user_agent=request.headers
• backend/main.py version is 0.1.3
• frontend/package.json version is 0.1.3
• Commits 25c9142, 1420180, 61b1e04 exist in git log
• pytest tests/test_auth_fgp.py -v reports 4 PASSED
• Full suite: 404 passed, 4 skipped, 7 xfailed, 0 failed