349 lines
22 KiB
Markdown
349 lines
22 KiB
Markdown
---
|
|
phase: "07.4"
|
|
plan: "02"
|
|
type: execute
|
|
wave: 1
|
|
depends_on:
|
|
- "07.4-01"
|
|
files_modified:
|
|
- backend/services/auth.py
|
|
- backend/deps/auth.py
|
|
- backend/api/auth.py
|
|
- backend/tests/test_auth_fgp.py
|
|
autonomous: true
|
|
requirements:
|
|
- FGP-CONCERN # tracked in .planning/codebase/CONCERNS.md §"No Token Fingerprint / Token Binding"
|
|
|
|
must_haves:
|
|
truths:
|
|
- "Every issued access token contains a 'fgp' claim (16-char hex)"
|
|
- "A request presenting a token whose fgp was computed from different headers receives HTTP 401 'Token fingerprint mismatch'"
|
|
- "A token without a 'fgp' claim is accepted (migration grace — old sessions not broken)"
|
|
- "Missing User-Agent / Accept-Language headers both default to empty string and still produce a valid, consistent fingerprint"
|
|
- "All 4 FGP tests in test_auth_fgp.py pass (promoted from xfail stubs)"
|
|
- "Full pytest suite passes with zero failures"
|
|
artifacts:
|
|
- path: "backend/services/auth.py"
|
|
provides: "_compute_fgp helper + extended create_access_token signature"
|
|
contains: "_compute_fgp"
|
|
- path: "backend/deps/auth.py"
|
|
provides: "fgp validation block after user_nbf check"
|
|
contains: "Token fingerprint mismatch"
|
|
- path: "backend/api/auth.py"
|
|
provides: "login + refresh call sites pass request headers"
|
|
contains: "user_agent=request.headers.get"
|
|
- path: "backend/tests/test_auth_fgp.py"
|
|
provides: "4 promoted tests (FGP-01..04) — all passing"
|
|
contains: "test_fgp_match_returns_200"
|
|
key_links:
|
|
- from: "backend/api/auth.py (login handler)"
|
|
to: "backend/services/auth.create_access_token"
|
|
via: "user_agent=request.headers.get('User-Agent',''), accept_lang=request.headers.get('Accept-Language','')"
|
|
pattern: "user_agent=request.headers.get"
|
|
- from: "backend/deps/auth.get_current_user"
|
|
to: "backend/services/auth._compute_fgp"
|
|
via: "auth_service._compute_fgp(...) + hmac.compare_digest"
|
|
pattern: "hmac.compare_digest\\(fgp_claim, fgp_actual\\)"
|
|
---
|
|
|
|
<objective>
|
|
Implement token fingerprinting end-to-end: add `_compute_fgp` to `services/auth.py`, embed the `fgp` claim in every issued access token, add the fgp validation block to `get_current_user` in `deps/auth.py`, update the two call sites in `api/auth.py`, and promote all 4 xfail stubs in `test_auth_fgp.py` to passing integration tests.
|
|
|
|
Purpose: Closes the "No Token Fingerprint / Token Binding" concern in CONCERNS.md. A stolen access token can only be replayed from the same User-Agent + Accept-Language context in which it was issued.
|
|
Output: Three production files modified (~27 lines total), one test file promoted (4 tests now passing).
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
|
|
@$HOME/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/STATE.md
|
|
@.planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-CONTEXT.md
|
|
@.planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-RESEARCH.md
|
|
@.planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-PATTERNS.md
|
|
@.planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-01-SUMMARY.md
|
|
|
|
<interfaces>
|
|
<!-- Exact current state of each file being modified. Verified against codebase. -->
|
|
|
|
From backend/services/auth.py:
|
|
Existing imports at lines 18-39 — both `import hashlib` (line 21) and `import hmac` (line 22) already present.
|
|
Current create_access_token signature (line 87):
|
|
def create_access_token(user_id: str, role: str) -> str:
|
|
Existing payload dict (lines 93-99):
|
|
payload = {
|
|
"sub": str(user_id),
|
|
"role": role,
|
|
"typ": "access",
|
|
"iat": now,
|
|
"exp": now + timedelta(minutes=settings.access_token_expire_minutes),
|
|
"jti": str(uuid.uuid4()),
|
|
}
|
|
Existing hmac.compare_digest usage (line ~419):
|
|
if hmac.compare_digest(candidate_suffix.upper(), suffix):
|
|
|
|
From backend/deps/auth.py:
|
|
Existing imports (lines 23-33) — `hmac` NOT imported. Add `import hmac` here.
|
|
`from services import auth as auth_service` at line 32 — use auth_service._compute_fgp(...) for cross-module call.
|
|
get_current_user signature (lines 41-44) — request: Request already present.
|
|
End of user_nbf block (line 85):
|
|
# ── end user_nbf check ──────────────────────────────────────────────────────
|
|
Line 87 (first line AFTER the block):
|
|
try:
|
|
user_uuid = uuid.UUID(payload["sub"])
|
|
Insert fgp block BETWEEN line 85 and line 87.
|
|
|
|
From backend/api/auth.py:
|
|
Login call site (line 290):
|
|
access_token = auth_service.create_access_token(str(user.id), user.role)
|
|
Refresh call site (line 364):
|
|
access_token = auth_service.create_access_token(user_id_str, user.role)
|
|
Both handlers already have `request: Request` in their signature.
|
|
|
|
From backend/tests/test_auth_deps.py:
|
|
FakeRedis import: from tests.test_auth_api import FakeRedis
|
|
make_test_app() sets app.state.redis = FakeRedis()
|
|
_create_user(db_session, role="user", is_active=True) helper pattern
|
|
auth_client fixture uses ASGITransport + AsyncClient
|
|
|
|
For FGP-03 (manual token without fgp claim):
|
|
Import `import jwt as _jwt`, `import base64`, `import time`
|
|
Decode private key: base64.b64decode(settings.jwt_private_key).decode()
|
|
Encode: _jwt.encode(payload_no_fgp, private_pem, algorithm="ES256")
|
|
payload_no_fgp must contain sub, role, typ="access", iat (as datetime or int), exp, jti
|
|
Use datetime.now(timezone.utc) for iat, iat + timedelta(minutes=15) for exp, str(uuid.uuid4()) for jti
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 1: Add _compute_fgp and extend create_access_token in services/auth.py</name>
|
|
<files>backend/services/auth.py</files>
|
|
<read_first>
|
|
- backend/services/auth.py — read lines 80-105 to see the exact current signature of create_access_token, the payload dict, and the line immediately before it (the JWT helpers comment at line 85). Insert _compute_fgp between line 85 and line 87.
|
|
- .planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-CONTEXT.md §D-04, D-05 — locked function signature and return value formula.
|
|
- .planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-PATTERNS.md §"backend/services/auth.py" — exact code to insert.
|
|
</read_first>
|
|
<behavior>
|
|
- _compute_fgp("Mozilla/5.0", "en") returns a 16-char hex string
|
|
- _compute_fgp("", "") returns a deterministic 16-char hex string (not empty, not None)
|
|
- create_access_token(user_id, role) still works without new params (backward-compatible defaults)
|
|
- create_access_token(user_id, role, user_agent="X", accept_lang="Y") embeds fgp=_compute_fgp("X","Y") in payload
|
|
- JWT payload from create_access_token contains a "fgp" key
|
|
</behavior>
|
|
<action>
|
|
Make two targeted edits to backend/services/auth.py:
|
|
|
|
Edit 1 — Insert `_compute_fgp` helper function.
|
|
Insertion point: immediately before the `def create_access_token` line (currently line 87), after the `# ── JWT helpers ──...` comment.
|
|
Function body per D-04: `hmac.new(settings.secret_key.encode(), (user_agent + accept_lang).encode(), hashlib.sha256).hexdigest()[:16]`
|
|
Add a one-line docstring: "Return 16-char hex fingerprint binding a token to its client context (D-04)."
|
|
No new imports are needed — `import hmac` and `import hashlib` already exist at lines 21-22.
|
|
|
|
Edit 2 — Extend create_access_token signature (D-05) and embed fgp claim in payload.
|
|
Change signature from `def create_access_token(user_id: str, role: str) -> str:` to:
|
|
`def create_access_token(user_id: str, role: str, user_agent: str = "", accept_lang: str = "") -> str:`
|
|
Add `"fgp": _compute_fgp(user_agent, accept_lang)` as a new key in the payload dict, alongside the existing sub/role/typ/iat/exp/jti keys.
|
|
|
|
Do NOT modify the return statement or any other logic in the function.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /Users/nik/Documents/Progamming/document_scanner/backend && python -c "from services.auth import create_access_token, _compute_fgp; t = create_access_token('00000000-0000-0000-0000-000000000001', 'user', user_agent='test', accept_lang='en'); import jwt, base64; from config import settings; pub = base64.b64decode(settings.jwt_public_key).decode(); p = jwt.decode(t, pub, algorithms=['ES256'], options={'verify_exp':False}); assert 'fgp' in p and len(p['fgp']) == 16, f'fgp missing or wrong length: {p}'; print('OK:', p['fgp'])"</automated>
|
|
</verify>
|
|
<done>
|
|
- backend/services/auth.py contains `def _compute_fgp(user_agent: str, accept_lang: str) -> str:`
|
|
- backend/services/auth.py contains `"fgp": _compute_fgp(user_agent, accept_lang)` in create_access_token payload
|
|
- create_access_token signature now has `user_agent: str = ""` and `accept_lang: str = ""` parameters
|
|
- Python inline verify command prints "OK:" followed by a 16-char hex string
|
|
</done>
|
|
</task>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 2: Add fgp validation block to get_current_user in deps/auth.py</name>
|
|
<files>backend/deps/auth.py</files>
|
|
<read_first>
|
|
- backend/deps/auth.py — read lines 23-35 (imports block) and lines 62-95 (user_nbf block + lines immediately after). The fgp block inserts AFTER the `# ── end user_nbf check ──` comment (currently line 85) and BEFORE the `try: user_uuid = uuid.UUID(payload["sub"])` block (currently line 87).
|
|
- .planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-PATTERNS.md §"backend/deps/auth.py" — exact fgp block code, exact insertion point, note that `import hmac` must be added to the imports block.
|
|
- .planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-CONTEXT.md §D-03, D-06 — mismatch raises 401 immediately; empty fgp_claim (old tokens) is allowed.
|
|
</read_first>
|
|
<behavior>
|
|
- Request with token whose fgp matches recomputed value: no exception raised, flow continues normally
|
|
- Request with token whose fgp does NOT match recomputed value: raises HTTPException(401, detail="Token fingerprint mismatch")
|
|
- Token without "fgp" key in payload (payload.get("fgp","") == ""): fgp block is skipped entirely, flow continues (migration grace per D-06)
|
|
- fgp comparison uses hmac.compare_digest (constant-time, per SEC-06)
|
|
</behavior>
|
|
<action>
|
|
Make two targeted edits to backend/deps/auth.py:
|
|
|
|
Edit 1 — Add `import hmac` to the imports block.
|
|
Insert `import hmac` after `import logging` and before `import uuid` (maintain alphabetical order within stdlib imports). Do not duplicate — verify `import hmac` is not already present before adding.
|
|
|
|
Edit 2 — Insert fgp validation block.
|
|
Insertion point: after the `# ── end user_nbf check ──────────────────────────────────────────────────────` comment line and before the next `try:` block (the one that does `user_uuid = uuid.UUID(payload["sub"])`).
|
|
|
|
The block to insert (per D-06 and RESEARCH.md Pattern 3):
|
|
|
|
# ── fgp check (D-06, Phase 7.4) ────────────────────────────────────────────
|
|
# Validates the fgp claim embedded by create_access_token. Empty claim means
|
|
# the token predates Phase 7.4 — allow gracefully (migration window, D-06).
|
|
# NOT wrapped in try/except: _compute_fgp is pure computation with no I/O.
|
|
fgp_claim = payload.get("fgp", "")
|
|
if fgp_claim:
|
|
fgp_actual = auth_service._compute_fgp(
|
|
request.headers.get("User-Agent", ""),
|
|
request.headers.get("Accept-Language", ""),
|
|
)
|
|
if not hmac.compare_digest(fgp_claim, fgp_actual):
|
|
raise HTTPException(
|
|
status_code=status.HTTP_401_UNAUTHORIZED,
|
|
detail="Token fingerprint mismatch",
|
|
headers={"WWW-Authenticate": "Bearer"},
|
|
)
|
|
# ── end fgp check ───────────────────────────────────────────────────────────
|
|
|
|
Do NOT wrap this block in a try/except. Do NOT modify any other part of get_current_user.
|
|
The `auth_service._compute_fgp(...)` call uses the existing `from services import auth as auth_service` import at line 32 — no new import needed.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /Users/nik/Documents/Progamming/document_scanner/backend && python -c "import ast, sys; src=open('deps/auth.py').read(); ast.parse(src); print('syntax OK')" && grep -c "Token fingerprint mismatch" deps/auth.py</automated>
|
|
</verify>
|
|
<done>
|
|
- backend/deps/auth.py contains `import hmac` in its imports block
|
|
- backend/deps/auth.py contains the string "Token fingerprint mismatch"
|
|
- backend/deps/auth.py contains `fgp_claim = payload.get("fgp", "")`
|
|
- backend/deps/auth.py contains `hmac.compare_digest(fgp_claim, fgp_actual)`
|
|
- Python syntax check passes (ast.parse exits 0)
|
|
- grep -c "Token fingerprint mismatch" deps/auth.py prints 1
|
|
</done>
|
|
</task>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 3: Update login + refresh call sites in api/auth.py; promote all 4 stubs to passing tests</name>
|
|
<files>backend/api/auth.py, backend/tests/test_auth_fgp.py</files>
|
|
<read_first>
|
|
- backend/api/auth.py — read lines 285-295 (login call site, current: `access_token = auth_service.create_access_token(str(user.id), user.role)`) and lines 360-370 (refresh call site, current: `access_token = auth_service.create_access_token(user_id_str, user.role)`). Both handlers already have `request: Request` in their signatures.
|
|
- backend/tests/test_auth_fgp.py — read the full file (created in Wave 0). Replace all 4 stub bodies (currently only `pytest.xfail("not implemented yet")`) with real test logic per RESEARCH.md §"Test Case Structure".
|
|
- .planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-RESEARCH.md §"Test Case Structure" and §"Pattern 4: Caller updates in api/auth.py" — exact before/after forms for both call sites and exact test logic for all 4 tests.
|
|
- backend/tests/test_auth_deps.py — confirm the FGP-03 pattern for crafting a token without fgp claim (PyJWT direct encode with ES256, import jwt as _jwt, base64.b64decode settings.jwt_private_key).
|
|
</read_first>
|
|
<behavior>
|
|
api/auth.py:
|
|
- Login handler: create_access_token call passes user_agent=request.headers.get("User-Agent","") and accept_lang=request.headers.get("Accept-Language","")
|
|
- Refresh handler: same header passthrough
|
|
|
|
test_auth_fgp.py promoted tests:
|
|
- FGP-01 test_fgp_match_returns_200: token issued with user_agent="Mozilla/5.0" accept_lang="en"; request sent with same headers → 200
|
|
- FGP-02 test_fgp_mismatch_returns_401: token issued with user_agent="Mozilla/5.0" accept_lang="en"; request sent with user_agent="different-agent" → 401 and response JSON detail == "Token fingerprint mismatch"
|
|
- FGP-03 test_no_fgp_claim_allowed: token manually crafted with PyJWT (no "fgp" key in payload); request sent without extra headers → 200
|
|
- FGP-04 test_missing_headers_empty_string_binding: token issued with no user_agent/accept_lang args (empty defaults); request sent with no User-Agent or Accept-Language headers → 200
|
|
</behavior>
|
|
<action>
|
|
Edit 1 — backend/api/auth.py, login call site.
|
|
Find: `access_token = auth_service.create_access_token(str(user.id), user.role)`
|
|
Replace with:
|
|
access_token = auth_service.create_access_token(
|
|
str(user.id),
|
|
user.role,
|
|
user_agent=request.headers.get("User-Agent", ""),
|
|
accept_lang=request.headers.get("Accept-Language", ""),
|
|
)
|
|
|
|
Edit 2 — backend/api/auth.py, refresh call site.
|
|
Find: `access_token = auth_service.create_access_token(user_id_str, user.role)`
|
|
Replace with:
|
|
access_token = auth_service.create_access_token(
|
|
user_id_str,
|
|
user.role,
|
|
user_agent=request.headers.get("User-Agent", ""),
|
|
accept_lang=request.headers.get("Accept-Language", ""),
|
|
)
|
|
|
|
Edit 3 — backend/tests/test_auth_fgp.py: add required imports and replace stub bodies.
|
|
|
|
Add to the imports block (if not already present from Wave 0):
|
|
import base64
|
|
import uuid as _uuid
|
|
import jwt as _jwt
|
|
from datetime import datetime, timezone, timedelta
|
|
from config import settings
|
|
|
|
For FGP-01 (test_fgp_match_returns_200):
|
|
Remove @pytest.mark.xfail decorator. Keep @pytest.mark.asyncio.
|
|
Body: create user, issue token with user_agent="Mozilla/5.0" and accept_lang="en", send GET /test/me with headers Authorization + User-Agent: Mozilla/5.0 + Accept-Language: en, assert status_code == 200.
|
|
|
|
For FGP-02 (test_fgp_mismatch_returns_401):
|
|
Remove @pytest.mark.xfail decorator. Keep @pytest.mark.asyncio.
|
|
Body: create user, issue token with user_agent="Mozilla/5.0" and accept_lang="en", send GET /test/me with Authorization + User-Agent: different-agent + Accept-Language: en, assert status_code == 401, assert response.json()["detail"] == "Token fingerprint mismatch".
|
|
|
|
For FGP-03 (test_no_fgp_claim_allowed):
|
|
Remove @pytest.mark.xfail decorator. Keep @pytest.mark.asyncio.
|
|
Body: create user, manually craft JWT payload dict with keys sub=str(user.id), role="user", typ="access", iat=datetime.now(timezone.utc), exp=datetime.now(timezone.utc)+timedelta(minutes=15), jti=str(_uuid.uuid4()) — do NOT include "fgp" key. Encode using _jwt.encode(payload_no_fgp, base64.b64decode(settings.jwt_private_key).decode(), algorithm="ES256"). Send GET /test/me with only Authorization header. Assert status_code == 200.
|
|
|
|
For FGP-04 (test_missing_headers_empty_string_binding):
|
|
Remove @pytest.mark.xfail decorator. Keep @pytest.mark.asyncio.
|
|
Body: create user, issue token with no user_agent/accept_lang args (defaults to ""), send GET /test/me with only Authorization header (no User-Agent, no Accept-Language), assert status_code == 200.
|
|
|
|
All four tests import create_access_token inline: `from services.auth import create_access_token`
|
|
</action>
|
|
<verify>
|
|
<automated>cd /Users/nik/Documents/Progamming/document_scanner/backend && pytest tests/test_auth_fgp.py -v && pytest tests/test_auth_api.py tests/test_auth_deps.py -x -q</automated>
|
|
</verify>
|
|
<done>
|
|
- pytest tests/test_auth_fgp.py -v shows 4 PASSED (0 xfail, 0 failed)
|
|
- pytest tests/test_auth_api.py tests/test_auth_deps.py -x -q passes (existing auth tests unbroken)
|
|
- backend/api/auth.py login call site contains `user_agent=request.headers.get("User-Agent", "")`
|
|
- backend/api/auth.py refresh call site contains `accept_lang=request.headers.get("Accept-Language", "")`
|
|
- Full suite: cd backend && pytest -v exits 0 with zero failures
|
|
</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<threat_model>
|
|
## Trust Boundaries
|
|
|
|
| Boundary | Description |
|
|
|----------|-------------|
|
|
| client → API (login/refresh) | Client headers are untrusted input; HMAC treats them as opaque bytes — no injection vector |
|
|
| JWT payload → get_current_user | fgp claim extracted from decoded (signature-verified) JWT; attacker cannot forge without ES256 private key |
|
|
| fgp comparison | Fixed-length (16-char hex) strings compared with hmac.compare_digest — timing-safe |
|
|
|
|
## STRIDE Threat Register
|
|
|
|
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|
|
|-----------|----------|-----------|-------------|-----------------|
|
|
| T-07.4-01 | Spoofing | access token replay from different device | mitigate | fgp mismatch → HTTP 401; attacker must match UA + Accept-Language from original context |
|
|
| T-07.4-02 | Information Disclosure | timing attack on fingerprint comparison | mitigate | `hmac.compare_digest` (constant-time) — SEC-06 requirement; already established in codebase |
|
|
| T-07.4-03 | Spoofing | empty-string collision (CLI clients share one fingerprint) | accept | D-02 deliberate design decision: CLI tools with no UA headers bind to fgp("","") and are internally consistent; equivalent to pre-7.4 security for those clients |
|
|
| T-07.4-04 | Tampering | fgp HTTPException swallowed by broad except | mitigate | fgp block placed OUTSIDE try/except (pure computation, no I/O); not wrapped in broad except so 401 always propagates |
|
|
| T-07.4-SC | Tampering | npm/pip/cargo installs | accept | No new packages installed; stdlib hmac/hashlib only |
|
|
</threat_model>
|
|
|
|
<verification>
|
|
After this plan completes:
|
|
1. `pytest tests/test_auth_fgp.py -v` — 4 PASSED
|
|
2. `pytest -v` — full suite exits 0 with zero failures; total count increases by 4 (previously xfail stubs are now passing tests)
|
|
3. `grep -n "fgp" backend/services/auth.py` — shows _compute_fgp definition and payload["fgp"] insertion
|
|
4. `grep -n "Token fingerprint mismatch" backend/deps/auth.py` — shows 1 match
|
|
5. `grep -n "user_agent=request.headers" backend/api/auth.py` — shows 2 matches (login + refresh)
|
|
6. Security gate: `bandit -r backend/` exits with zero HIGH findings
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
- _compute_fgp helper exists in backend/services/auth.py with correct HMAC-SHA256 formula (per D-04)
|
|
- create_access_token embeds "fgp" claim in every issued JWT (per D-05)
|
|
- get_current_user validates fgp with hmac.compare_digest; empty claim allowed; mismatch raises 401 "Token fingerprint mismatch" (per D-06)
|
|
- Login and refresh call sites in api/auth.py pass User-Agent and Accept-Language headers (per D-05)
|
|
- All 4 FGP tests pass: FGP-01 (match→200), FGP-02 (mismatch→401), FGP-03 (no claim→200), FGP-04 (missing headers→200)
|
|
- Full pytest suite exits 0 with zero failures
|
|
</success_criteria>
|
|
|
|
<output>
|
|
Create `.planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-02-SUMMARY.md` when done
|
|
</output>
|