lockwatch 0.1.0__tar.gz

lockwatch-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"          # trigger on v0.1.0, v1.2.3, etc.
+  workflow_dispatch:  # allow manual trigger for testing
+
+jobs:
+  test:
+    name: Run tests before publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Run tests
+        run: hatch run test
+
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    needs: test
+    # Use PyPI's trusted publisher (OIDC) — no API token needed in secrets
+    permissions:
+      id-token: write   # required for OIDC token exchange with PyPI
+      contents: read
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/lockwatch/
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install hatch build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify distribution files
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Publish to PyPI
+        # Uses OIDC trusted publisher — configure at https://pypi.org/manage/account/publishing/
+        # Project name: lockwatch, workflow: publish.yml, environment: pypi
+        uses: pypa/gh-action-pypi-publish@release/v1

lockwatch-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: lockwatch
+Version: 0.1.0
+Summary: API security middleware for FastAPI and Flask: rate limiting, JWT rotation, anomaly detection, audit logging
+Project-URL: Homepage, https://github.com/jordanho/lockwatch
+Project-URL: Repository, https://github.com/jordanho/lockwatch
+Project-URL: Issues, https://github.com/jordanho/lockwatch/issues
+Author-email: Jordan Ho <jordanjho@gmail.com>
+License: MIT
+Keywords: fastapi,flask,jwt,middleware,rate-limiting,redis,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: redis[asyncio]>=5.0.0
+Provides-Extra: all
+Requires-Dist: alembic>=1.13.0; extra == 'all'
+Requires-Dist: asyncpg>=0.29.0; extra == 'all'
+Requires-Dist: fastapi>=0.111.0; extra == 'all'
+Requires-Dist: flask>=3.0.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'all'
+Requires-Dist: starlette>=0.37.0; extra == 'all'
+Requires-Dist: werkzeug>=3.0.0; extra == 'all'
+Provides-Extra: audit
+Requires-Dist: alembic>=1.13.0; extra == 'audit'
+Requires-Dist: asyncpg>=0.29.0; extra == 'audit'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'audit'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.111.0; extra == 'fastapi'
+Requires-Dist: starlette>=0.37.0; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0.0; extra == 'flask'
+Requires-Dist: werkzeug>=3.0.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+[![PyPI version](https://badge.fury.io/py/lockwatch.svg)](https://badge.fury.io/py/lockwatch)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# LockWatch
+
+Drop-in API security middleware for FastAPI and Flask: sliding-window rate limiting (Redis sorted set), JWT rotation with refresh-token blacklist, IP burst anomaly detection with webhook alerts, and Postgres audit logging — all wired into a single `add_middleware` call.
+
+---
+
+## Architecture
+
+```
+                    ┌─────────────────────────────────────────────┐
+  Incoming          │            LockWatchMiddleware               │
+  Request  ────────►│                                             │
+                    │  ┌──────────────┐   ┌───────────────────┐  │
+                    │  │  RateLimiter │   │  AnomalyDetector  │  │
+                    │  │              │   │                   │  │
+                    │  │ Redis sorted │   │ burst window +    │  │
+                    │  │ set sliding  │   │ webhook alert     │  │
+                    │  │ window       │   │ (fire-and-forget) │  │
+                    │  └──────┬───────┘   └────────┬──────────┘  │
+                    │         │ 429 if over limit   │             │
+                    │         ▼                     ▼             │
+                    │  ┌─────────────────────────────────────┐    │
+                    │  │          Application Handler        │    │
+                    │  └─────────────────┬───────────────────┘    │
+                    │                    │                         │
+                    │                    ▼                         │
+                    │  ┌─────────────────────────────────────┐    │
+                    │  │  AuditLogger (background task)      │    │
+                    │  │  → Postgres lockwatch_audit_log     │    │
+                    │  └─────────────────────────────────────┘    │
+                    └─────────────────────────────────────────────┘
+                                         │
+                               Response ◄┘
+```
+
+Every request flows through the rate limiter first (hard block at 429), then the anomaly detector (non-blocking webhook alert), then your application, then an async audit log write that is never on the response critical path.
+
+---
+
+## Why I Built This
+
+Bolting rate limiters, audit logs, and JWT rotation into every FastAPI project is tedious boilerplate — the same 50 lines of Redis plumbing, every time. LockWatch makes it a single `add_middleware` call so the security layer doesn't crowd the application logic.
+
+---
+
+## Install
+
+```bash
+# FastAPI / Starlette
+pip install lockwatch[fastapi]
+
+# Flask / WSGI
+pip install lockwatch[flask]
+
+# Postgres audit log
+pip install lockwatch[audit]
+
+# Everything
+pip install lockwatch[all]
+```
+
+---
+
+## Quickstart — FastAPI
+
+```python
+from fastapi import FastAPI
+from lockwatch import LockWatchMiddleware
+
+app = FastAPI()
+
+app.add_middleware(
+    LockWatchMiddleware,
+    redis_url="redis://localhost:6379",
+    rate_limit_requests=100,          # allow 100 requests …
+    rate_limit_window_seconds=60,     # … per 60-second sliding window
+    burst_threshold=50,               # anomaly alert if >50 req in 10s
+    burst_window_seconds=10,
+    webhook_urls=["https://hooks.example.com/lockwatch-alert"],
+    audit_database_url="postgresql+asyncpg://user:pass@host/db",  # optional
+)
+
+@app.get("/items")
+async def list_items():
+    return {"items": []}
+```
+
+When a client exceeds the limit, LockWatch automatically returns:
+
+```json
+HTTP 429 Too Many Requests
+Retry-After: 42
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1717516800
+
+{"error": "rate_limit_exceeded", "retry_after": 42}
+```
+
+---
+
+## Quickstart — Flask
+
+```python
+from flask import Flask
+from lockwatch.middleware import LockWatchFlaskMiddleware
+
+app = Flask(__name__)
+app.wsgi_app = LockWatchFlaskMiddleware(
+    app.wsgi_app,
+    redis_url="redis://localhost:6379",
+    rate_limit_requests=200,
+    rate_limit_window_seconds=60,
+)
+```
+
+---
+
+## Flask — Anomaly Detection + JWT Verification
+
+```python
+from flask import Flask, g
+from lockwatch import JWTRotationManager, JWTConfig
+from lockwatch.middleware import flask_jwt_required, LockWatchFlaskMiddleware
+
+app = Flask(__name__)
+
+# Rate limiting + anomaly detection wired at the WSGI layer
+app.wsgi_app = LockWatchFlaskMiddleware(
+    app.wsgi_app,
+    redis_url="redis://localhost:6379",
+    rate_limit_requests=200,
+    rate_limit_window_seconds=60,
+    burst_threshold=50,           # enables anomaly detection; 0 = disabled
+    burst_window_seconds=10,
+    webhook_urls=["https://hooks.example.com/alert"],
+)
+
+# JWT verification per route via decorator
+jwt_mgr = JWTRotationManager(redis_client, JWTConfig(rsa_private_key_pem=pem))
+
+@app.route("/protected")
+@flask_jwt_required(jwt_mgr)
+def protected():
+    return {"user": g.jwt_claims["sub"]}
+```
+
+---
+
+## JWT Rotation
+
+Manage short-lived access tokens and refresh-token blacklisting without a database round-trip on every request:
+
+```python
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.serialization import (
+    Encoding, PrivateFormat, NoEncryption,
+)
+from lockwatch import JWTRotationManager, JWTConfig
+
+# Generate once; persist the PEM in your secrets store
+private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+pem = private_key.private_bytes(Encoding.PEM, PrivateFormat.TraditionalOpenSSL, NoEncryption()).decode()
+
+manager = JWTRotationManager(
+    redis_client=redis,
+    config=JWTConfig(rsa_private_key_pem=pem),
+)
+
+pair = await manager.issue_token_pair(subject="user:42", claims={"role": "admin"})
+# pair.access_token  — RS256 JWT, 15-minute TTL
+# pair.refresh_token — RS256 JWT, 7-day TTL, hash stored in Redis
+
+new_pair = await manager.rotate(pair.refresh_token)  # atomic swap via WATCH/MULTI/EXEC
+```
+
+---
+
+## Anomaly Detection
+
+Standalone burst detector — usable without the full middleware:
+
+```python
+from lockwatch import AnomalyDetector, AnomalyConfig
+
+detector = AnomalyDetector(
+    redis_client=redis,
+    config=AnomalyConfig(
+        burst_threshold=50,
+        burst_window_seconds=10,
+        webhook_urls=["https://hooks.example.com/alert"],
+    ),
+)
+
+is_burst = await detector.check(ip="1.2.3.4", endpoint="/api/login", method="POST")
+```
+
+---
+
+## Audit Log
+
+Query who did what and when:
+
+```python
+from lockwatch import AuditLogger, AuditQuery
+
+logger = AuditLogger(database_url="postgresql+asyncpg://user:pass@host/db")
+await logger.init()  # creates table if not exists (idempotent)
+
+entries = await logger.query(AuditQuery(
+    user_id="user:42",
+    anomalies_only=True,
+    limit=50,
+))
+```
+
+Run Alembic migrations against your Postgres instance:
+
+```bash
+export LOCKWATCH_DATABASE_URL="postgresql+asyncpg://user:pass@host/db"
+alembic upgrade head
+```
+
+---
+
+## Configuration Reference
+
+| Parameter | Env var override | Default | Description |
+|---|---|---|---|
+| `redis_url` | `REDIS_URL` | — | Redis connection URL (required) |
+| `rate_limit_requests` | — | `100` | Max requests per window |
+| `rate_limit_window_seconds` | — | `60` | Sliding window size in seconds |
+| `burst_threshold` | — | `50` | Request count that triggers anomaly alert |
+| `burst_window_seconds` | — | `10` | Burst detection window in seconds |
+| `webhook_urls` | — | `[]` | List of HTTPS endpoints for anomaly alerts |
+| `audit_database_url` | `LOCKWATCH_DATABASE_URL` | `None` | Postgres URL for audit log |
+| `on_redis_failure` | — | `"allow"` | `"allow"` (fail open) or `"deny"` (fail closed) |
+| `jwt_secret` | `JWT_SECRET` | — | HMAC secret for JWT signing |
+| `access_token_ttl` | — | `900` | Access token lifetime in seconds |
+| `anomaly_window` | — | `10` | Alias for `burst_window_seconds` |
+
+---
+
+## What it Does
+
+- **Sliding-window rate limiter** — Redis sorted set records each request timestamp; window is computed by pruning entries older than `rate_limit_window_seconds`. O(log N) per operation, true sliding semantics (no thundering-herd at window boundary), atomic pipeline.
+- **JWT rotation with refresh blacklist** — issues short-lived access tokens backed by opaque refresh tokens stored in Redis. `rotate()` atomically swaps old for new and blacklists the old refresh token with a TTL — no stale token reuse.
+- **IP burst anomaly detection** — separate Redis sorted set per IP in a short burst window. When the threshold is crossed, fires async webhook alerts with a 60-second dedup window (one alert per IP per minute). Non-blocking — never delays the response.
+- **Postgres audit log** — every request gets one row in `lockwatch_audit_log` including timestamp, IP, user_id, endpoint, method, status code, rate_limit_hit flag, anomaly_detected flag, and response latency. Writes are background tasks (`asyncio.create_task`) — a failed write logs a warning but never affects the response.
+
+---
+
+## Running Tests
+
+```bash
+pip install lockwatch[all]
+pip install pytest pytest-asyncio fakeredis[aioredis] aiosqlite
+pytest --cov=lockwatch --cov-report=term-missing
+```
+
+---
+
+## License
+
+MIT © Jordan Ho

lockwatch-0.1.0/PLAN.md

@@ -0,0 +1,173 @@
+# LockWatch — Implementation Plan
+
+> Status: 📋 Plan written | Last updated: 2026-06-03
+
+## Overview
+
+LockWatch is an open-source API security middleware library for Python (FastAPI and Flask), published to PyPI. It provides production-grade security primitives — sliding-window rate limiting, JWT rotation with refresh token blacklisting, IP burst anomaly detection with webhook alerts, and a Postgres audit log — as drop-in middleware. The goal is a single `pip install lockwatch` that gives any FastAPI or Flask app the security layer that teams typically wire together from multiple half-baked packages.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   FastAPI / Flask App                    │
+│                                                         │
+│   ┌─────────────────────────────────────────────────┐   │
+│   │              LockWatch Middleware                │   │
+│   │                                                 │   │
+│   │  ┌──────────────┐   ┌───────────────────────┐  │   │
+│   │  │ RateLimiter  │   │    AnomalyDetector    │  │   │
+│   │  │  (per-key    │   │  (burst detection +   │  │   │
+│   │  │   sliding    │   │   webhook alerts)     │  │   │
+│   │  │   window)    │   └───────────┬───────────┘  │   │
+│   │  └──────┬───────┘               │              │   │
+│   │         │                       │              │   │
+│   │  ┌──────▼───────────────────────▼───────────┐  │   │
+│   │  │               Redis                      │  │   │
+│   │  │  rate_limit:{key} → sorted set           │  │   │
+│   │  │  refresh_token:{jti} → hash              │  │   │
+│   │  │  blacklist:{jti} → 1                     │  │   │
+│   │  └──────────────────────────────────────────┘  │   │
+│   │                                                 │   │
+│   │  ┌─────────────────────────────────────────┐   │   │
+│   │  │           JWTRotationManager            │   │   │
+│   │  │   access (15min RS256) + refresh (7d)  │   │   │
+│   │  └─────────────────────────────────────────┘   │   │
+│   │                                                 │   │
+│   │  ┌─────────────────────────────────────────┐   │   │
+│   │  │             AuditLogger                 │   │   │
+│   │  │   Postgres: requests, user, endpoint,   │   │   │
+│   │  │   status_code, rate_limit_hit           │   │   │
+│   │  └─────────────────────────────────────────┘   │   │
+│   └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Tech Stack
+
+- **Python 3.11** — match modern FastAPI/production deployments; 3.11 perf improvements matter for middleware hot path
+- **FastAPI** — target framework; async-first design maps cleanly to starlette middleware base
+- **Flask** — second target; WSGI middleware via `werkzeug.wsgi.DispatcherMiddleware`; covers the large Flask user base
+- **redis-py (async)** — `aioredis`-compatible async client; sorted set primitives are exactly what sliding-window needs (ZADD/ZREMRANGEBYSCORE/ZCARD in a pipeline = atomic window check)
+- **SQLAlchemy 2 + asyncpg** — async ORM for audit log writes; asyncpg is the fastest Postgres driver available; SQLAlchemy gives portability
+- **python-jose[cryptography]** — RS256 JWT signing/verification; JWK support needed for JWKS endpoint later; well-audited
+- **hatchling** — PEP 517 build backend; simpler than setuptools; native pyproject.toml support; used by major OSS projects (FastAPI itself)
+- **pytest + pytest-asyncio + fakeredis** — unit tests without needing a live Redis; fakeredis implements the full sorted set API
+
+## Implementation Checklist
+
+### Phase 1 — Project scaffold
+- [x] Create directory structure (done by scaffolding agent)
+- [ ] Write `pyproject.toml` (hatchling, optional deps: `[fastapi]`, `[flask]`, `[audit]`)
+- [ ] Write `src/lockwatch/__init__.py` with public API exports
+- [ ] Set up `tests/conftest.py` with fakeredis + SQLite fixtures
+
+### Phase 2 — Sliding-window rate limiter
+- [ ] Implement `RateLimiter` class in `rate_limiter.py`
+  - [ ] `async def is_allowed(key: str) -> tuple[bool, RateLimitState]`
+  - [ ] Redis pipeline: `ZADD`, `ZREMRANGEBYSCORE` (prune old), `ZCARD`, `EXPIRE`
+  - [ ] Config dataclass: `requests_per_window`, `window_seconds`, `key_func` (callable)
+  - [ ] Built-in key functions: `key_by_ip`, `key_by_user_id`, `key_by_api_key`
+  - [ ] Return headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
+- [ ] Write `tests/test_rate_limiter.py` (5 test cases, fakeredis)
+
+### Phase 3 — JWT rotation
+- [ ] Implement `JWTRotationManager` in `jwt_rotation.py`
+  - [ ] `issue_token_pair(subject, claims) -> TokenPair` (access 15min + refresh 7d)
+  - [ ] Store `SHA256(refresh_token)` in Redis with 7d TTL
+  - [ ] `rotate(refresh_token) -> TokenPair` — validate hash, blacklist old jti, issue new pair
+  - [ ] `blacklist(jti)` — add to Redis blacklist set (TTL = remaining token lifetime)
+  - [ ] `verify_access(token) -> Claims` — check signature + blacklist
+  - [ ] Config: RSA private key path or inline PEM, issuer, audience
+
+### Phase 4 — Anomaly detection
+- [ ] Implement `AnomalyDetector` in `anomaly.py`
+  - [ ] Per-IP sliding window (separate Redis sorted set from rate limiter)
+  - [ ] Config: `burst_threshold` (requests), `burst_window_seconds`, `webhook_urls: list[str]`
+  - [ ] `async def check(ip: str, request_info: dict) -> bool` — returns True if anomaly
+  - [ ] Async webhook dispatch (httpx, non-blocking, fire-and-forget with timeout)
+  - [ ] Alert payload: `{ ip, timestamp, request_count, window_seconds, endpoint }`
+  - [ ] Deduplicate alerts: one alert per IP per 60s (Redis key with TTL)
+
+### Phase 5 — Postgres audit log
+- [ ] Implement `AuditLogger` in `audit.py`
+  - [ ] SQLAlchemy model `AuditLogEntry`: `id`, `timestamp`, `user_id`, `ip`, `endpoint`, `method`, `status_code`, `rate_limit_hit`, `anomaly_detected`, `latency_ms`
+  - [ ] `async def log(entry: AuditLogEntry) -> None` (background task — don't block response)
+  - [ ] `async def query(filters: AuditQuery) -> list[AuditLogEntry]`
+  - [ ] Alembic migration in `src/lockwatch/migrations/`
+  - [ ] Index on `(timestamp, user_id)` and `(timestamp, ip)`
+
+### Phase 6 — Middleware classes
+- [ ] `LockWatchMiddleware` (FastAPI/Starlette) in `middleware.py`
+  - [ ] Extends `starlette.middleware.base.BaseHTTPMiddleware`
+  - [ ] Call order: rate check → anomaly check → dispatch → audit log
+  - [ ] Inject `request.state.lockwatch` with rate limit state for downstream use
+  - [ ] 429 response with `Retry-After` header on rate limit
+  - [ ] Config object passed at init time
+- [ ] `LockWatchFlaskMiddleware` (WSGI) in `middleware.py`
+  - [ ] Wrap WSGI app, extract IP + headers pre-dispatch
+  - [ ] Note: Flask middleware is sync-only; use `asyncio.run()` bridge or sync Redis client fallback
+
+### Phase 7 — PyPI publish
+- [ ] Add `__version__` to `__init__.py` (semver, start at `0.1.0`)
+- [ ] Write `.github/workflows/publish.yml` — trigger on `v*` tag push, build + twine upload
+- [ ] Set up PyPI trusted publisher (OIDC, no token in secrets)
+- [ ] Write `CHANGELOG.md` template
+
+### Phase 8 — Tests + docs
+- [ ] Achieve 80%+ pytest coverage
+- [ ] Integration test: spin up fakeredis + SQLite, run full request through FastAPI test client
+- [ ] Write `README.md` with install instructions + 10-line quickstart
+- [ ] Add Chronobot + Livestotell as example integrations
+
+## File Structure
+
+```
+LockWatch/
+├── PLAN.md
+├── pyproject.toml
+├── README.md                         (create later)
+├── CHANGELOG.md                      (create later)
+├── .github/
+│   └── workflows/
+│       └── publish.yml
+├── src/
+│   └── lockwatch/
+│       ├── __init__.py               (public API exports)
+│       ├── rate_limiter.py           (RateLimiter class)
+│       ├── jwt_rotation.py           (JWTRotationManager)
+│       ├── anomaly.py                (AnomalyDetector)
+│       ├── audit.py                  (AuditLogger + SQLAlchemy model)
+│       ├── middleware.py             (FastAPI + Flask middleware)
+│       ├── config.py                 (LockWatchConfig dataclass)  [create later]
+│       └── migrations/
+│           ├── env.py                [create later]
+│           └── versions/             [create later]
+└── tests/
+    ├── conftest.py                   [create later]
+    ├── test_rate_limiter.py
+    ├── test_jwt_rotation.py          [create later]
+    ├── test_anomaly.py               [create later]
+    └── test_middleware.py            [create later]
+```
+
+## Resume Bullets (multi-domain)
+
+**V3 Security/Infra:**
+- Built and published LockWatch to PyPI — a Python middleware library (FastAPI/Flask) implementing sliding-window rate limiting via Redis sorted sets, RS256 JWT rotation with Redis-backed refresh token blacklisting, and IP burst anomaly detection with configurable webhook alerting; integrated into Chronobot and Livestotell
+
+**V1 General SWE / V5 Systems:**
+- Designed LockWatch as a zero-dependency security layer: atomic Redis pipeline (ZADD → ZREMRANGEBYSCORE → ZCARD) achieves O(log N) rate limit checks at <1ms overhead per request; Postgres audit log uses async background tasks to avoid adding latency to the hot path
+
+**V7 Data / Observability angle:**
+- Implemented per-request audit logging to Postgres via async SQLAlchemy with indexed queries on (timestamp, user_id); anomaly detector emits structured webhook payloads enabling downstream SIEM ingestion
+
+## Interview Narrative
+
+- **Origin (30s):** At Dialpad I saw how teams bolt on rate limiting as an afterthought — usually a janky NGINX config that doesn't know about users, just IPs. I wanted a Python-native library where you say "limit this user to 100 requests per minute" in two lines, with JWT rotation and audit logging included, not as separate packages.
+
+- **Differentiator (30s):** Most rate limit libraries use fixed windows — they have a thundering herd problem at window boundaries. LockWatch uses Redis sorted sets for true sliding windows: ZADD the current timestamp, ZREMRANGEBYSCORE to prune entries older than the window, ZCARD for the count — all in one pipeline, atomic. The JWT rotation piece is rarer: refresh tokens are stored as SHA-256 hashes in Redis (never the raw token), and rotating always blacklists the old JTI before issuing a new pair, so token theft gets caught on the next use.
+
+- **Tradeoffs (2 min):** The main tradeoff is Redis dependency — if Redis goes down, you're choosing between failing open (allow all requests, security risk) or failing closed (block all requests, availability risk). I made it configurable: `on_redis_failure='allow'` vs `'deny'`, defaulting to `allow` with an error log, because most APIs would rather serve traffic than go dark. The audit log is async/fire-and-forget — if the Postgres write fails, the request still completes. That's intentional: audit logging should never be in the critical path. The Flask middleware is necessarily sync because WSGI is sync; I bridge to async Redis with a dedicated event loop, which adds ~0.5ms. A pure sync Redis client would be faster but I wanted one code path, not two.
+
+- **Extension (1 min):** Natural extensions: (1) distributed rate limiting across multiple Redis nodes using Redlock for the counter key — right now two app servers could both think a key is at N-1 and both allow a request that should be blocked; (2) machine learning on the audit log to detect credential stuffing patterns that don't trigger the burst detector (slow, distributed attacks); (3) a Rust extension module for the hot-path key hashing to get sub-100μs overhead.