kite/.planning/phases/07.2-security-jti-claim-redis-access-token-revocation-inserted/07.2-02-SUMMARY.md

---
phase: 07.2-security-jti-claim-redis-access-token-revocation-inserted
plan: "02"
subsystem: auth
tags:
  - security
  - jwt
  - redis
  - access-control
  - wave-1

dependency_graph:
  requires:
    - "07.2-01: FakeRedis mounted on test_auth_deps + xfail stubs"
  provides:
    - "jti UUID claim in every access token issued by create_access_token"
    - "user_nbf Redis NBF check in get_current_user with fail-open + HTTPException re-raise guard"
    - "Wave 2 write sites (Plan 03) can now write user_nbf:{user_id} and the check will fire"
  affects:
    - "backend/services/auth.py"
    - "backend/deps/auth.py"
    - "backend/tests/test_task2_auth_service.py"
    - "backend/tests/test_auth_deps.py"

tech_stack:
  added: []
  patterns:
    - "jti=str(uuid.uuid4()) inserted into access token payload — uuid already imported, no new deps"
    - "user_nbf Redis check in get_current_user: read-then-compare with fail-open and HTTPException re-raise guard"
    - "Bytes/str tolerance for FakeRedis test fixtures: decode() only if isinstance bytes/bytearray"
    - "except HTTPException: raise MUST precede except Exception — T-7.2-02 Pitfall 1 guard"

key_files:
  created: []
  modified:
    - backend/services/auth.py
    - backend/deps/auth.py
    - backend/tests/test_task2_auth_service.py
    - backend/tests/test_auth_deps.py

decisions:
  - "jti added as the last key in the payload dict (after exp) for grep-ability; no function signature change"
  - "NBF comparison uses strict < not <= (token issued exactly at event second is allowed — edge case per D-02)"
  - "Bytes/str tolerance guard added: nbf_bytes.decode() if isinstance(bytes|bytearray) else nbf_bytes — FakeRedis may return str in tests"
  - "No get_redis FastAPI dependency added — direct access via request.app.state.redis per D-03"
  - "get_current_admin and get_regular_user not touched — they inherit via Depends(get_current_user)"
  - "test_extract_docx failure confirmed pre-existing (missing python-docx module in local env) — unrelated to this plan"

metrics:
  duration: "600s (10m)"
  completed_date: "2026-06-05T18:00:00Z"
  tasks_completed: 2
  tasks_total: 2
  files_changed: 4
---

# Phase 07.2 Plan 02: jti Claim + user_nbf NBF Check Summary

**One-liner:** jti UUID claim added to all access tokens; user_nbf Redis NBF check with fail-open and HTTPException re-raise guard wired into get_current_user, closing the 15-minute revocation window.

## What Was Built

### Task 1: Add jti claim to create_access_token (TDD)

**services/auth.py** — one-line surgical edit to `create_access_token`:

```python
"jti": str(uuid.uuid4()),
```

Added as the last key after `exp` in the payload dict. The `uuid` module was already imported at module top (line 25) — no new imports. PyJWT encodes the `jti` key verbatim into the signed token and decodes it back as a plain string after verification.

**Tests promoted from xfail:**

- `test_create_access_token_includes_jti_claim` — verifies `"jti"` key present, value is a `str`, and parseable as `uuid.UUID`
- `test_create_access_token_jti_is_unique_per_call` — verifies two consecutive calls produce different `jti` values (new test)

Both promoted to PASS. All existing tests (`test_create_access_token_jwt_format`, `test_decode_access_token_valid`) remain PASSED — no regressions.

### Task 2: Add user_nbf Redis check to get_current_user (TDD)

**deps/auth.py** — module-level additions:

```python
import logging
_logger = logging.getLogger(__name__)
```

**get_current_user** — new block inserted after `decode_access_token` try/except and before the `uuid.UUID(payload["sub"])` parse:

```python
try:
    redis_client = request.app.state.redis
    nbf_bytes = await redis_client.get(f"user_nbf:{payload['sub']}")
    if nbf_bytes is not None:
        nbf_str = nbf_bytes.decode() if isinstance(nbf_bytes, (bytes, bytearray)) else nbf_bytes
        if payload["iat"] < int(nbf_str):
            raise HTTPException(
                status_code=status.HTTP_401_UNAUTHORIZED,
                detail="Session invalidated",
                headers={"WWW-Authenticate": "Bearer"},
            )
except HTTPException:
    raise  # re-raise the 401 we just constructed (T-7.2-02: Pitfall 1 guard)
except Exception as exc:
    _logger.warning("Redis user_nbf check failed (fail-open): %s", exc)
```

**Tests promoted from xfail:**

- `test_get_current_user_rejects_token_when_iat_before_user_nbf` — sets future `user_nbf`, verifies HTTP 401 + `"Session invalidated"` + `WWW-Authenticate: Bearer`
- `test_get_current_user_allows_token_when_iat_after_user_nbf` — sets past `user_nbf`, verifies HTTP 200
- `test_get_current_user_failopen_on_redis_error` — replaces `app.state.redis` with `_BrokenRedis` that raises `RuntimeError`, verifies HTTP 200 (not 5xx, not 401)

All 3 promoted to PASS. All existing tests (7 baseline auth-dep tests) still PASSED. Wave 2 write stubs in `test_auth_api.py` (3 XFAIL) and admin stubs in `test_admin_api.py` (2 XFAIL) correctly remain XFAIL — they are Wave 2's job.

## Verification

Full suite after this plan: **382 passed, 12 xfailed** (1 pre-existing `test_extract_docx` failure from missing `python-docx` module in local env — confirmed pre-existing before Wave 0 baseline; unrelated to this plan's changes).

Target file suites: `tests/test_auth_deps.py tests/test_task2_auth_service.py` — **29 passed, 0 xfailed, 0 failures**.

## Commits

| Task | Commit | Description |
|------|--------|-------------|
| 1 | c00c1fb | feat(07.2-02): add jti UUID claim to create_access_token |
| 2 | 30ad9fd | security(07.2-02): add user_nbf Redis NBF check to get_current_user |

## Deviations from Plan

None — plan executed exactly as written.

## Known Stubs

None — this plan contains no stubs. All 4 Wave 1 stubs (1 jti + 3 NBF-check) were promoted to fully-passing tests. The 5 remaining XFAIL tests in `test_auth_api.py` and `test_admin_api.py` are Wave 2 stubs created in Plan 01 — they are out of scope for this plan.

## Patterns Established

- **NBF check pattern in get_current_user**: read `user_nbf:{payload['sub']}` from `request.app.state.redis`; compare `payload["iat"] < int(nbf_str)` to reject; strict `<` not `<=`
- **HTTPException re-raise guard before broad catch**: `except HTTPException: raise` MUST precede `except Exception` — verified by line-number ordering grep. This is T-7.2-02 / Pitfall 1 and the single highest-impact correctness invariant in this plan.
- **bytes/str tolerance for FakeRedis**: `nbf_bytes.decode() if isinstance(nbf_bytes, (bytes, bytearray)) else nbf_bytes` before `int(...)` — ensures tests using `FakeRedis.set(..., value.encode())` work identically to production `aioredis` returning raw bytes.
- **Fail-open on Redis errors**: `except Exception as exc: _logger.warning(...)` — no re-raise; mirrors HIBP fail-open pattern in services/auth.py

## Patterns to Avoid

- Do NOT use `<=` in the NBF comparison — a token issued at the exact same second as the event is intentionally allowed (strictly-before semantic matches D-02)
- Do NOT add a `get_redis` FastAPI dependency — access must be direct via `request.app.state.redis` per D-03
- Do NOT touch `get_current_admin` or `get_regular_user` — they inherit the NBF check transparently via `Depends(get_current_user)`
- Do NOT move the broad `except Exception` before `except HTTPException: raise` — this would swallow the intentional 401 and let revoked tokens through (T-7.2-02)

## Provides (for Wave 2)

Wave 2 (Plan 03) can now write `user_nbf:{user_id} = int(time.time())` with `ex=900` from the four security-event handlers (`change_password`, `enable_totp`, `disable_totp`, admin deactivation) and the check will fire on the very next request from any pre-event access token. The read side is complete; Wave 2 only needs to add the write sites.

## Threat Flags

None — no new network endpoints, auth paths, or schema changes introduced. The changes reduce the attack surface by closing the 15-minute revocation window (T-7.2-01 mitigated).

## Self-Check: PASSED

- [x] `backend/services/auth.py` modified with `"jti": str(uuid.uuid4())` — confirmed by grep
- [x] `backend/deps/auth.py` modified with NBF check block — confirmed by grep (user_nbf, logging, Session invalidated, request.app.state.redis)
- [x] `backend/tests/test_task2_auth_service.py` modified — xfail removed, real assertions, new uniqueness test
- [x] `backend/tests/test_auth_deps.py` modified — 3 xfail stubs promoted to passing assertions
- [x] Commit c00c1fb exists: `git log --oneline | grep c00c1fb`
- [x] Commit 30ad9fd exists: `git log --oneline | grep 30ad9fd`
- [x] 29 tests pass in target suites: `pytest tests/test_auth_deps.py tests/test_task2_auth_service.py`
- [x] HTTPException re-raise guard ordering verified: except HTTPException at line 81 < except Exception at line 83
- [x] jti pattern grep returns 1 match: `"jti": str(uuid.uuid4()),`