# Supabase JWKS Auth Reliability Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 让后端在云 Supabase 场景下稳定使用 JWKS/RS256 验签，并把 Auth 上游超时错误正确暴露为 503，保障注册/登录/重置密码链路可观测。

**Architecture:** 保留 `PUBLIC_URL -> issuer/jwks` 自动推导，JWT 验签继续强制 RS256，但给 JWKS 拉取添加 `apikey` 与 `Authorization` 头。Auth Gateway 新增统一错误映射，将上游 timeout/网关错误归类为服务不可用（503），其余保持既有 401/422 语义。

**Tech Stack:** FastAPI, Pydantic, PyJWT (`PyJWKClient`), Supabase Python SDK, pytest。

---

### Task 1: JWKS Header 支持（测试先行）

**Files:**
- Modify: `backend/tests/unit/core/auth/test_jwt_verifier.py`
- Modify: `backend/src/core/auth/jwt_verifier.py`
- Modify: `backend/src/v1/users/dependencies.py`

**Step 1: Write failing test**
- 为 `JwtVerifier` 新增用例，断言初始化 `PyJWKClient` 时会传入 `apikey` 与 `Authorization: Bearer <anon_key>`。

**Step 2: Run test to verify it fails**
- Run: `uv run pytest backend/tests/unit/core/auth/test_jwt_verifier.py -v`

**Step 3: Write minimal implementation**
- `JwtVerifier.__init__` 新增 `apikey` 参数并注入 JWKS 请求头。
- `get_jwt_verifier()` 传入 `config.supabase.anon_key`。

**Step 4: Run test to verify it passes**
- Run: `uv run pytest backend/tests/unit/core/auth/test_jwt_verifier.py -v`

### Task 2: Auth 上游超时错误映射为 503（测试先行）

**Files:**
- Modify: `backend/tests/unit/v1/auth/test_auth_gateway.py`
- Modify: `backend/src/v1/auth/gateway.py`

**Step 1: Write failing test**
- 新增 `create_verification` 的超时错误测试，期望返回 `HTTPException(status_code=503)`。

**Step 2: Run test to verify it fails**
- Run: `uv run pytest backend/tests/unit/v1/auth/test_auth_gateway.py -v`

**Step 3: Write minimal implementation**
- 增加 AuthError 分类函数，识别 timeout/request_timeout/upstream timeout。
- 在注册、登录、刷新、重置相关分支中映射为 503。

**Step 4: Run test to verify it passes**
- Run: `uv run pytest backend/tests/unit/v1/auth/test_auth_gateway.py -v`

### Task 3: 回归验证

**Files:**
- Modify: `backend/tests/unit/test_settings_supabase_env.py` (if needed)

**Step 1: Run targeted suites**
- Run: `uv run pytest backend/tests/unit/core/auth/test_jwt_verifier.py backend/tests/unit/v1/auth/test_auth_gateway.py backend/tests/unit/test_settings_supabase_env.py -v`

**Step 2: Run quality gates**
- Run: `uv run ruff check backend/src backend/tests`
- Run: `uv run basedpyright backend/src`

**Step 3: Document runtime checks**
- 记录 JWT/JWKS 必备环境变量和手工联调命令。