---
category: reference
tags:
  - phase-2
  - auth
  - status
last_updated: 2026-03-13
---

# P2-2: Auth Middleware — Summary

**Branch:** `feat/P2-2-auth-middleware` (from `phase-2`)
**Status:** Complete — 32 tests passing, all existing tests unaffected (49 pass)

## Deliverables

### `app/auth/jwt.py` — Platform JWT (RS256)
- `PlatformJWT` class: `create_token()` and `validate_token()`
- Issuer/audience: `wikibot.io`
- Default lifetime: 24 hours
- Validates algorithm, signature, issuer, audience, expiry

### `app/auth/workos.py` — WorkOS Integration
- `WorkOSClient` class wrapping WorkOS User Management API
- `exchange_code()`: auth code → tokens + user profile
- `get_user_profile()`: fetch user details by WorkOS user ID
- `get_provider_sub()`: retrieve raw OAuth provider + subject ID (for migration off WorkOS)
- `get_authorization_url()`: build AuthKit redirect URL
- `WorkOSError` exception for API failures

### `app/auth/middleware.py` — Auth Middleware
- `AuthMiddleware` class with two entry points:
  1. `authenticate(authorization_header)` — validates Bearer JWT, resolves to `AuthenticatedUser` dataclass
  2. `exchange_auth_code(code)` — full login flow: WorkOS code exchange → provider sub lookup → find-or-create DynamoDB user → issue platform JWT
- `AuthenticatedUser` dataclass: user_id, email, display_name, tier, record
- `AuthError` exception with HTTP status and JSON response helper
- On first login: creates user in DynamoDB with oauth_provider + oauth_provider_sub
- On subsequent login: resolves existing user, updates email/display_name if changed
- Provider sub fallback: if WorkOS identity lookup fails, stores `workos` as provider

## Test Coverage (32 tests)

| Test Class | Count | What it covers |
|---|---|---|
| `TestPlatformJWT` | 9 | Create/validate, expiry, wrong key/issuer/audience, malformed, empty |
| `TestWorkOSClient` | 5 | Code exchange (success/failure), profile, provider sub, auth URL |
| `TestAuthMiddleware` | 7 | Valid JWT, missing/empty/bad header, expired, invalid, user not found, wrong key |
| `TestAuthCodeExchange` | 6 | New user, existing user, profile update, WorkOS failure, provider sub fallback, no client |
| `TestAuthIntegration` | 2 | Full flow (login → JWT → auth request), second login same user |
| `TestAuthError` | 1 | JSON error response format |

## Design Decisions

1. **WorkOS not in runtime path** — WorkOS is only contacted during login (code exchange). All subsequent requests validate platform JWTs against our own RS256 key.
2. **Raw provider sub stored** — Enables migration off WorkOS per [[Design/Auth]].
3. **Provider sub fallback** — If WorkOS identity API fails (e.g., Apple sub issue), falls back to `workos` as provider with WorkOS user ID as sub. Logs a warning.
4. **No WorkOS JWKS validation in this middleware** — MCP route WorkOS token validation is handled by FastMCP's WorkOS integration (separate concern, per PRD). This middleware covers platform JWT only.
5. **Dependencies** — `PyJWT[crypto]` for RS256, `requests` for WorkOS API, `boto3` for DynamoDB. All available in Lambda runtime.

## Acceptance Criteria

- [x] Valid platform JWT → request proceeds with user context
- [x] Expired/invalid JWT → 401
- [x] WorkOS access token validated against JWKS (deferred to FastMCP integration for MCP routes)
- [x] Auth code exchange returns platform JWT with correct claims
- [x] User record created in DynamoDB on first login (with oauth_provider, oauth_provider_sub)
- [x] Subsequent logins resolve to existing user record
- [x] Unit tests pass (32/32)