159 lines
8.9 KiB
Markdown
159 lines
8.9 KiB
Markdown
---
|
|
phase: 07.4-security-token-fingerprinting-token-binding-inserted
|
|
plan: "02"
|
|
subsystem: auth
|
|
tags: [jwt, fgp, token-binding, token-fingerprinting, hmac, security, wave-1]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 07.4-01
|
|
provides: Wave 0 xfail stubs for FGP-01..FGP-04 in test_auth_fgp.py
|
|
|
|
provides:
|
|
- _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)
|
|
|
|
affects:
|
|
- All API endpoints using get_current_user — fgp now validated on every request
|
|
- Test infrastructure — _TEST_USER_AGENT constant added to conftest.py
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
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"
|
|
|
|
key-files:
|
|
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
|
|
|
|
key-decisions:
|
|
- "_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"
|
|
|
|
# Metrics
|
|
duration: 35min
|
|
completed: 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
|