docs(07.4): create phase plan — 2 plans, Wave 0 xfail stubs + Wave 1 fgp implementation
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
curo1305
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
50668cc916
commit
de0f3fb7c3
+188
@@ -0,0 +1,188 @@
|
||||
---
|
||||
phase: "07.4"
|
||||
plan: "01"
|
||||
type: execute
|
||||
wave: 0
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- 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:
|
||||
- "test_auth_fgp.py exists with exactly 4 test functions"
|
||||
- "All 4 tests are decorated with @pytest.mark.xfail(strict=False, reason='not implemented yet')"
|
||||
- "pytest -v reports all 4 as XFAIL — no failures, no errors"
|
||||
- "No production source files are modified"
|
||||
artifacts:
|
||||
- path: "backend/tests/test_auth_fgp.py"
|
||||
provides: "Wave 0 xfail stubs for FGP-01..FGP-04"
|
||||
contains: "test_fgp_match_returns_200"
|
||||
key_links:
|
||||
- from: "backend/tests/test_auth_fgp.py"
|
||||
to: "backend/tests/test_auth_deps.py"
|
||||
via: "imports FakeRedis, copies make_test_app / auth_client / _create_user patterns"
|
||||
pattern: "from tests.test_auth_api import FakeRedis"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Create the Wave 0 test scaffold for Phase 7.4: a new test file `backend/tests/test_auth_fgp.py` containing 4 xfail stubs covering the four fingerprint behaviours (FGP-01..FGP-04). No production code is touched in this plan.
|
||||
|
||||
Purpose: Establishes the Nyquist test harness before any production code changes. Follows the xfail(strict=False) Wave 0 convention established in Phases 7.2 and 7.3.
|
||||
Output: `backend/tests/test_auth_fgp.py` with 4 stubs; full test suite still passes with zero failures.
|
||||
</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
|
||||
|
||||
<interfaces>
|
||||
<!-- Key patterns the executor needs. Extracted from codebase. -->
|
||||
|
||||
From backend/tests/test_auth_deps.py (full harness to copy):
|
||||
|
||||
Imports:
|
||||
import uuid
|
||||
import pytest
|
||||
import pytest_asyncio
|
||||
from httpx import ASGITransport, AsyncClient
|
||||
from fastapi import FastAPI, Depends
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from tests.test_auth_api import FakeRedis
|
||||
|
||||
make_test_app():
|
||||
Creates minimal FastAPI app with /test/me route wired to get_current_user.
|
||||
Sets app.state.redis = FakeRedis() so NBF check and fgp check can access request.app.state.redis.
|
||||
|
||||
auth_client fixture:
|
||||
@pytest_asyncio.fixture
|
||||
async def auth_client(db_session: AsyncSession):
|
||||
app = make_test_app()
|
||||
app.dependency_overrides[get_db] = lambda: db_session
|
||||
async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:
|
||||
yield c
|
||||
app.dependency_overrides.clear()
|
||||
|
||||
_create_user helper (no decorator — plain async function):
|
||||
Inserts minimal User row; returns User ORM object.
|
||||
Fields: id=uuid.uuid4(), handle, email, password_hash, role, is_active=True
|
||||
|
||||
Test function pattern:
|
||||
@pytest.mark.asyncio
|
||||
async def test_name(auth_client, db_session):
|
||||
from services.auth import create_access_token
|
||||
user = await _create_user(db_session)
|
||||
token = create_access_token(str(user.id), "user")
|
||||
resp = await auth_client.get("/test/me", headers={"Authorization": f"Bearer {token}"})
|
||||
assert resp.status_code == 200
|
||||
|
||||
conftest _patch_es256_test_keys is autouse=True at session scope — no explicit reference needed in this file.
|
||||
|
||||
From backend/tests/test_auth_es256.py (xfail stub pattern for Phase 7.3):
|
||||
@pytest.mark.xfail(strict=False, reason="not implemented yet")
|
||||
@pytest.mark.asyncio
|
||||
async def test_stub_name(...):
|
||||
pytest.xfail("not implemented yet")
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: Create test_auth_fgp.py with 4 xfail stubs (FGP-01..FGP-04)</name>
|
||||
<files>backend/tests/test_auth_fgp.py</files>
|
||||
<read_first>
|
||||
- backend/tests/test_auth_deps.py — copy the full harness (make_test_app, auth_client fixture, _create_user helper, imports block). This is the structural template; copy verbatim then modify test functions only.
|
||||
- backend/tests/test_auth_es256.py — xfail stub decoration pattern used in Phase 7.3. Stubs use @pytest.mark.xfail(strict=False, reason="not implemented yet") and body is only pytest.xfail("not implemented yet").
|
||||
- .planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-RESEARCH.md §"Test Case Structure" — exact test names and behaviour descriptions for all 4 tests.
|
||||
</read_first>
|
||||
<behavior>
|
||||
- FGP-01 test_fgp_match_returns_200: issues token with user_agent="Mozilla/5.0" accept_lang="en", sends request with matching headers — expects 200
|
||||
- FGP-02 test_fgp_mismatch_returns_401: issues token with user_agent="Mozilla/5.0" accept_lang="en", sends request with user_agent="different-agent" — expects 401 and detail="Token fingerprint mismatch"
|
||||
- FGP-03 test_no_fgp_claim_allowed: crafts token manually without "fgp" key in payload — expects 200 (migration grace)
|
||||
- FGP-04 test_missing_headers_empty_string_binding: issues token with no user_agent/accept_lang args (defaults to ""), sends request with no User-Agent/Accept-Language headers — expects 200
|
||||
</behavior>
|
||||
<action>
|
||||
Create backend/tests/test_auth_fgp.py. Structure:
|
||||
|
||||
1. Module docstring explaining Phase 7.4 fgp test coverage (FGP-01..04).
|
||||
|
||||
2. Imports: copy the exact imports block from test_auth_deps.py. Add these additional imports needed for FGP-03 (manual token craft): `import base64`, `import time`, `import jwt as _jwt`, and `from config import settings`.
|
||||
|
||||
3. Copy make_test_app() verbatim from test_auth_deps.py (includes app.state.redis = FakeRedis()). Do NOT add a /test/admin route — not needed here.
|
||||
|
||||
4. Copy auth_client fixture verbatim from test_auth_deps.py.
|
||||
|
||||
5. Copy _create_user helper verbatim from test_auth_deps.py.
|
||||
|
||||
6. Write 4 test functions in this order:
|
||||
- test_fgp_match_returns_200 (FGP-01)
|
||||
- test_fgp_mismatch_returns_401 (FGP-02)
|
||||
- test_no_fgp_claim_allowed (FGP-03)
|
||||
- test_missing_headers_empty_string_binding (FGP-04)
|
||||
|
||||
Each test function:
|
||||
- Decorated with @pytest.mark.xfail(strict=False, reason="not implemented yet") ABOVE @pytest.mark.asyncio
|
||||
- Decorated with @pytest.mark.asyncio
|
||||
- Accepts (auth_client, db_session) as parameters
|
||||
- Body is a single line: pytest.xfail("not implemented yet")
|
||||
|
||||
Do NOT write any assertion logic, token construction, or request code inside the stubs. The stub body is ONLY the pytest.xfail() call. Implementation comes in Wave 1 (Plan 07.4-02).
|
||||
|
||||
7. No production files (services/auth.py, deps/auth.py, api/auth.py) may be modified in this task.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /Users/nik/Documents/Progamming/document_scanner/backend && pytest tests/test_auth_fgp.py -v 2>&1 | tail -20</automated>
|
||||
</verify>
|
||||
<done>
|
||||
- backend/tests/test_auth_fgp.py exists
|
||||
- pytest tests/test_auth_fgp.py -v shows exactly 4 tests, all reported as XFAIL
|
||||
- Zero FAILED, zero ERROR entries in the output
|
||||
- pytest -v (full suite) still passes with zero failures
|
||||
</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| test harness → test DB | xfail stubs create no DB state; no trust boundary crossed in Wave 0 |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|-------------|-----------------|
|
||||
| T-07.4-SC | Tampering | npm/pip/cargo installs | accept | No new packages installed in this plan; stdlib only |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
After this plan completes:
|
||||
- `pytest tests/test_auth_fgp.py -v` shows 4 XFAIL
|
||||
- `pytest -v` (full suite) exits 0 with the same pass count as before this plan (411+) plus 4 new XFAIL
|
||||
- No changes to backend/services/auth.py, backend/deps/auth.py, or backend/api/auth.py
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- `backend/tests/test_auth_fgp.py` exists with 4 test stubs (FGP-01..04)
|
||||
- All 4 stubs use `@pytest.mark.xfail(strict=False, reason="not implemented yet")`
|
||||
- Full test suite passes with zero failures; 4 new XFAIL added
|
||||
- No production code modified
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/07.4-security-token-fingerprinting-token-binding-inserted/07.4-01-SUMMARY.md` when done
|
||||
</output>
|
||||
+348
@@ -0,0 +1,348 @@
|
||||
---
|
||||
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>
|
||||
Reference in New Issue
Block a user