docs(15): create phase plan for external authentication

2026-04-04 20:30:27 +02:00
parent 7ba931352a
commit f2c1d04cfc
4 changed files with 1212 additions and 9 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -5,7 +5,7 @@
 - ✅ **v1.0 MVP** — Phases 1-3 (shipped 2026-03-15)
 - ✅ **v1.1 Fixes & Polish** — Phases 4-6 (shipped 2026-03-15)
 - ✅ **v1.2 Collection Power-Ups** — Phases 7-9 (shipped 2026-03-16)
- 🚧 **v1.3 Research & Decision Tools** — Phases 10-13 (in progress)
+- ✅ **v1.3 Research & Decision Tools** — Phases 10-13 (shipped)
 - 📋 **v2.0 Platform Foundation** — Phases 14-18 (planned)

 ## Phases
@@ -37,14 +37,15 @@

 </details>

-### v1.3 Research & Decision Tools (In Progress)
+<details>
+<summary>✅ v1.3 Research & Decision Tools (Phases 10-13) — SHIPPED</summary>

-**Milestone Goal:** Give users the tools to actually decide between candidates — compare details side-by-side, see how a pick impacts their setup, and rank/annotate their options.
+- [x] Phase 10: Schema Foundation + Pros/Cons Fields (1/1 plans) — completed 2026-03-16
+- [x] Phase 11: Candidate Ranking (2/2 plans) — completed 2026-03-16
+- [x] Phase 12: Comparison View (1/1 plans) — completed 2026-03-17
+- [x] Phase 13: Setup Impact Preview (completed outside GSD)

- [x] **Phase 10: Schema Foundation + Pros/Cons Fields** — Migrate schema and deliver pros/cons annotation UI (completed 2026-03-16)
- [x] **Phase 11: Candidate Ranking** — Drag-to-reorder priority ranking with rank badges (completed 2026-03-16)
- [x] **Phase 12: Comparison View** — Side-by-side tabular comparison with relative deltas (completed 2026-03-17)
- [ ] **Phase 13: Setup Impact Preview** — Per-candidate weight and cost delta against a selected setup
+</details>

 ### v2.0 Platform Foundation (Planned)

@@ -133,7 +134,11 @@ Plans:
  3. API keys continue to work for MCP tools and programmatic access without involving the auth provider
  4. E2E tests run successfully using API key authentication, with no dependency on the external auth provider being available
  5. The auth provider runs self-hosted in Docker Compose alongside Postgres and the application
-**Plans**: TBD
+**Plans:** 3 plans
+Plans:
+- [ ] 15-01-PLAN.md — Docker Compose Logto service + schema migration (drop users/sessions)
+- [ ] 15-02-PLAN.md — Server-side OIDC auth integration (middleware, routes, services, MCP)
+- [ ] 15-03-PLAN.md — Client auth refactor + E2E seed + test updates

 ### Phase 16: Multi-User Data Model
 **Goal**: Every piece of user-created data is owned by a specific user, with complete isolation between users
@@ -189,7 +194,7 @@ Plans:
 | 12. Comparison View | v1.3 | 1/1 | Complete | 2026-03-17 |
 | 13. Setup Impact Preview | v1.3 | 0/2 | Not started | - |
 | 14. PostgreSQL Migration | v2.0 | 6/6 | Complete   | 2026-04-04 |
-| 15. External Authentication | v2.0 | 0/? | Not started | - |
+| 15. External Authentication | v2.0 | 0/3 | Not started | - |
 | 16. Multi-User Data Model | v2.0 | 0/? | Not started | - |
 | 17. Object Storage | v2.0 | 0/? | Not started | - |
 | 18. Global Items & Public Profiles | v2.0 | 0/? | Not started | - |
--- a/.planning/phases/15-external-authentication/15-01-PLAN.md
+++ b/.planning/phases/15-external-authentication/15-01-PLAN.md
@@ -0,0 +1,220 @@
+---
+phase: 15-external-authentication
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - docker-compose.yml
+  - docker-compose.dev.yml
+  - docker/init-logto-db.sql
+  - src/db/schema.ts
+  - .env.example
+autonomous: true
+requirements: [AUTH-04]
+
+must_haves:
+  truths:
+    - "Logto container starts alongside Postgres in docker-compose"
+    - "Logto admin console is accessible at port 3002"
+    - "Logto OIDC discovery endpoint responds at /oidc/.well-known/openid-configuration"
+    - "GearBox schema no longer contains users or sessions tables"
+    - "A separate logto database is created automatically on Postgres first boot"
+  artifacts:
+    - path: "docker-compose.yml"
+      provides: "Production Logto service definition"
+      contains: "svhd/logto"
+    - path: "docker-compose.dev.yml"
+      provides: "Dev Logto service definition"
+      contains: "svhd/logto"
+    - path: "docker/init-logto-db.sql"
+      provides: "Postgres init script creating logto database"
+      contains: "CREATE DATABASE logto"
+    - path: "src/db/schema.ts"
+      provides: "Schema without users/sessions tables"
+    - path: ".env.example"
+      provides: "Documentation of required OIDC env vars"
+      contains: "OIDC_ISSUER"
+  key_links:
+    - from: "docker-compose.yml"
+      to: "docker/init-logto-db.sql"
+      via: "postgres volume mount to docker-entrypoint-initdb.d"
+      pattern: "init-logto-db.sql:/docker-entrypoint-initdb.d"
+    - from: "docker-compose.yml logto service"
+      to: "docker-compose.yml postgres service"
+      via: "depends_on with service_healthy"
+      pattern: "condition: service_healthy"
+---
+
+<objective>
+Add Logto as a Docker Compose service and remove the users/sessions tables from the GearBox schema.
+
+Purpose: Establishes the infrastructure foundation for OIDC authentication -- Logto must be running before server-side auth code can be integrated. Schema changes remove the old auth tables that will be replaced by Logto-managed identity.
+
+Output: Updated docker-compose files with Logto, cleaned schema, env var documentation.
+</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/15-external-authentication/15-CONTEXT.md
+@.planning/phases/15-external-authentication/15-RESEARCH.md
+@src/db/schema.ts
+@docker-compose.yml
+@docker-compose.dev.yml
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add Logto service to Docker Compose and create init script</name>
+  <files>docker-compose.yml, docker-compose.dev.yml, docker/init-logto-db.sql, .env.example</files>
+  <read_first>
+    - docker-compose.yml (current production compose)
+    - docker-compose.dev.yml (current dev compose)
+    - .planning/phases/15-external-authentication/15-RESEARCH.md (Pattern 4: Logto Docker Compose Integration, Pitfall 1: OIDC Issuer URL Mismatch)
+  </read_first>
+  <action>
+    **Per D-13 and D-14:** Add Logto as a service in both docker-compose files.
+
+    1. Create `docker/init-logto-db.sql` with content:
+    ```sql
+    -- Creates a separate database for Logto on the shared Postgres instance
+    CREATE DATABASE logto;
+    ```
+
+    2. Update `docker-compose.yml` (production):
+    - Add volume mount on postgres service: `./docker/init-logto-db.sql:/docker-entrypoint-initdb.d/init-logto-db.sql`
+    - Add `logto` service:
+      ```yaml
+      logto:
+        image: svhd/logto:latest
+        depends_on:
+          postgres:
+            condition: service_healthy
+        entrypoint: ["sh", "-c", "npm run cli db seed -- --swe && npm start"]
+        ports:
+          - "3001:3001"
+          - "3002:3002"
+        environment:
+          TRUST_PROXY_HEADER: "1"
+          DB_URL: postgres://gearbox:${POSTGRES_PASSWORD}@postgres:5432/logto
+          ENDPOINT: ${LOGTO_ENDPOINT:-http://localhost:3001}
+          ADMIN_ENDPOINT: ${LOGTO_ADMIN_ENDPOINT:-http://localhost:3002}
+      ```
+    - Add to `app` service environment:
+      ```yaml
+      OIDC_ISSUER: ${LOGTO_ENDPOINT:-http://localhost:3001}/oidc
+      OIDC_CLIENT_ID: ${LOGTO_CLIENT_ID}
+      OIDC_CLIENT_SECRET: ${LOGTO_CLIENT_SECRET}
+      OIDC_AUTH_SECRET: ${OIDC_AUTH_SECRET}
+      ```
+    - Add `depends_on` for app -> logto: `condition: service_started`
+
+    3. Update `docker-compose.dev.yml`:
+    - Add the same postgres init volume mount
+    - Add same `logto` service definition (ports 3001, 3002)
+    - Logto environment uses hardcoded dev password: `DB_URL: postgres://gearbox:gearbox@postgres:5432/logto`
+
+    4. Create or update `.env.example` with all new OIDC env vars:
+    ```
+    # PostgreSQL
+    POSTGRES_PASSWORD=changeme
+
+    # Logto OIDC (get from Logto Admin Console at http://localhost:3002)
+    LOGTO_ENDPOINT=http://localhost:3001
+    LOGTO_ADMIN_ENDPOINT=http://localhost:3002
+    LOGTO_CLIENT_ID=your-app-client-id
+    LOGTO_CLIENT_SECRET=your-app-client-secret
+    OIDC_AUTH_SECRET=generate-a-random-32-char-string-here
+
+    # GearBox
+    GEARBOX_URL=http://localhost:3000
+    ```
+
+    **IMPORTANT (Pitfall 1):** The `ENDPOINT` on Logto and `OIDC_ISSUER` on the app must both use the *externally accessible* URL (e.g., `http://localhost:3001`), NOT Docker-internal hostnames. The browser redirect and server-side JWT validation must agree on the issuer string.
+  </action>
+  <verify>
+    <automated>grep -q "svhd/logto" docker-compose.yml && grep -q "svhd/logto" docker-compose.dev.yml && grep -q "CREATE DATABASE logto" docker/init-logto-db.sql && grep -q "OIDC_ISSUER" .env.example && echo "PASS" || echo "FAIL"</automated>
+  </verify>
+  <acceptance_criteria>
+    - docker-compose.yml contains `image: svhd/logto:latest`
+    - docker-compose.yml logto service has `depends_on: postgres: condition: service_healthy`
+    - docker-compose.yml logto service exposes ports 3001 and 3002
+    - docker-compose.yml postgres service has volume mount containing `init-logto-db.sql:/docker-entrypoint-initdb.d/init-logto-db.sql`
+    - docker-compose.yml app service has `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_AUTH_SECRET` env vars
+    - docker-compose.dev.yml contains matching logto service definition
+    - docker/init-logto-db.sql contains `CREATE DATABASE logto;`
+    - .env.example contains `LOGTO_CLIENT_ID`, `LOGTO_CLIENT_SECRET`, `OIDC_AUTH_SECRET`, `LOGTO_ENDPOINT`
+  </acceptance_criteria>
+  <done>Both docker-compose files have Logto service, init SQL creates logto database, env vars documented</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Remove users and sessions tables from schema and generate migration</name>
+  <files>src/db/schema.ts</files>
+  <read_first>
+    - src/db/schema.ts (current full schema with users, sessions, apiKeys, oauth* tables)
+    - .planning/phases/15-external-authentication/15-CONTEXT.md (D-03: Remove users and sessions tables)
+  </read_first>
+  <action>
+    **Per D-03:** Remove the `users` and `sessions` table definitions from `src/db/schema.ts`. Keep everything else: `categories`, `items`, `threads`, `threadCandidates`, `setups`, `setupItems`, `settings`, `apiKeys`, `oauthClients`, `oauthCodes`, `oauthTokens`.
+
+    Specifically:
+    1. Delete the `users` table definition (lines defining `export const users = pgTable("users", { ... })`)
+    2. Delete the `sessions` table definition (lines defining `export const sessions = pgTable("sessions", { ... })`)
+    3. Remove the `boolean` import from `drizzle-orm/pg-core` if no longer used (check: `oauthCodes` uses `boolean` for `used` field, so keep it)
+    4. Do NOT remove `apiKeys` table -- it stays per D-10
+
+    After editing schema, run migration generation:
+    ```bash
+    bun run db:generate
+    ```
+
+    This creates a Drizzle migration SQL file in `drizzle/` that drops the `users` and `sessions` tables. Review the generated migration to confirm it only drops `users` and `sessions` -- no other tables.
+
+    **Do NOT run `bun run db:push` yet** -- that will be done when the full auth refactor is ready.
+  </action>
+  <verify>
+    <automated>! grep -q "export const users" src/db/schema.ts && ! grep -q "export const sessions" src/db/schema.ts && grep -q "export const apiKeys" src/db/schema.ts && echo "PASS" || echo "FAIL"</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/db/schema.ts does NOT contain `export const users`
+    - src/db/schema.ts does NOT contain `export const sessions`
+    - src/db/schema.ts DOES contain `export const apiKeys`
+    - src/db/schema.ts DOES contain `export const oauthClients`
+    - src/db/schema.ts DOES contain `export const oauthCodes`
+    - src/db/schema.ts DOES contain `export const oauthTokens`
+    - A new migration file exists in drizzle/ directory
+  </acceptance_criteria>
+  <done>Users and sessions tables removed from schema, migration generated to drop them</done>
+</task>
+
+</tasks>
+
+<verification>
+- `grep -q "svhd/logto" docker-compose.yml` succeeds
+- `grep -q "svhd/logto" docker-compose.dev.yml` succeeds
+- `docker/init-logto-db.sql` exists with CREATE DATABASE logto
+- `src/db/schema.ts` has no `users` or `sessions` exports
+- `src/db/schema.ts` retains `apiKeys`, `oauthClients`, `oauthCodes`, `oauthTokens`
+- New Drizzle migration file exists in `drizzle/`
+</verification>
+
+<success_criteria>
+- Logto service defined in both docker-compose files with correct ports, env vars, and Postgres dependency
+- Postgres init script creates the logto database
+- GearBox schema has users and sessions tables removed
+- Drizzle migration generated for the table drops
+- All OIDC-related environment variables documented in .env.example
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/15-external-authentication/15-01-SUMMARY.md`
+</output>
--- a/.planning/phases/15-external-authentication/15-02-PLAN.md
+++ b/.planning/phases/15-external-authentication/15-02-PLAN.md
@@ -0,0 +1,555 @@
+---
+phase: 15-external-authentication
+plan: 02
+type: execute
+wave: 2
+depends_on: ["15-01"]
+files_modified:
+  - src/server/middleware/auth.ts
+  - src/server/services/auth.service.ts
+  - src/server/routes/auth.ts
+  - src/server/routes/oauth.ts
+  - src/server/mcp/index.ts
+  - src/server/index.ts
+  - package.json
+autonomous: true
+requirements: [AUTH-01, AUTH-02, AUTH-03]
+
+must_haves:
+  truths:
+    - "requireAuth middleware validates API keys, MCP Bearer tokens, and OIDC session cookies"
+    - "GET /login redirects unauthenticated users to Logto"
+    - "GET /callback processes the OIDC authorization code and sets a session cookie"
+    - "GET /api/auth/me returns user identity from OIDC claims or null"
+    - "API keys continue to authenticate programmatic requests without Logto"
+    - "MCP OAuth Bearer tokens continue to work for Claude mobile/web"
+    - "MCP OAuth /oauth/authorize validates via OIDC session instead of username/password"
+  artifacts:
+    - path: "src/server/middleware/auth.ts"
+      provides: "Three-way auth middleware (API key, MCP Bearer, OIDC session)"
+      exports: ["requireAuth"]
+    - path: "src/server/services/auth.service.ts"
+      provides: "API key CRUD only (user/session functions removed)"
+      exports: ["createApiKey", "verifyApiKey", "listApiKeys", "deleteApiKey"]
+    - path: "src/server/routes/auth.ts"
+      provides: "OIDC login/callback/logout routes + API key CRUD routes"
+      exports: ["authRoutes"]
+    - path: "src/server/routes/oauth.ts"
+      provides: "MCP OAuth with OIDC session validation instead of password"
+    - path: "src/server/index.ts"
+      provides: "Updated route registration with OIDC callback"
+  key_links:
+    - from: "src/server/middleware/auth.ts"
+      to: "@hono/oidc-auth"
+      via: "getAuth() for OIDC session check"
+      pattern: "getAuth"
+    - from: "src/server/middleware/auth.ts"
+      to: "src/server/services/auth.service.ts"
+      via: "verifyApiKey for API key path"
+      pattern: "verifyApiKey"
+    - from: "src/server/routes/auth.ts"
+      to: "@hono/oidc-auth"
+      via: "oidcAuthMiddleware for login redirect, processOAuthCallback for callback"
+      pattern: "oidcAuthMiddleware|processOAuthCallback"
+    - from: "src/server/routes/oauth.ts"
+      to: "@hono/oidc-auth"
+      via: "getAuth() replaces verifyPassword in authorize POST"
+      pattern: "getAuth"
+---
+
+<objective>
+Rewrite the server-side authentication layer to use OIDC via @hono/oidc-auth for browser sessions while preserving API key and MCP OAuth authentication paths.
+
+Purpose: This is the core auth integration -- replacing GearBox's custom user/session management with Logto OIDC. After this plan, browser users authenticate via Logto, API keys work unchanged, and MCP OAuth coexists cleanly.
+
+Output: Refactored middleware, routes, and services implementing three-way authentication.
+</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/15-external-authentication/15-CONTEXT.md
+@.planning/phases/15-external-authentication/15-RESEARCH.md
+@.planning/phases/15-external-authentication/15-01-SUMMARY.md
+@src/server/middleware/auth.ts
+@src/server/services/auth.service.ts
+@src/server/routes/auth.ts
+@src/server/routes/oauth.ts
+@src/server/mcp/index.ts
+@src/server/index.ts
+
+<interfaces>
+<!-- Current auth service exports that will be modified -->
+From src/server/services/auth.service.ts (KEEP these):
+```typescript
+export async function createApiKey(db: Db, name: string): Promise<{...}>
+export async function verifyApiKey(db: Db, rawKey: string): Promise<boolean>
+export async function listApiKeys(db: Db): Promise<{...}[]>
+export async function deleteApiKey(db: Db, id: number): Promise<void>
+```
+
+From src/server/services/auth.service.ts (REMOVE these):
+```typescript
+export async function createUser(db: Db, username: string, password: string)
+export async function verifyPassword(db: Db, username: string, password: string)
+export async function getUserCount(db: Db): Promise<number>
+export async function changePassword(db: Db, ...)
+export async function createSession(db: Db, userId: number, ...)
+export async function getSession(db: Db, sessionId: string)
+export async function deleteSession(db: Db, sessionId: string)
+export async function refreshSession(db: Db, sessionId: string, ...)
+```
+
+From src/server/services/oauth.service.ts (KEEP, used by MCP OAuth):
+```typescript
+export async function verifyAccessToken(db: Db, token: string): Promise<boolean>
+```
+
+From @hono/oidc-auth (NEW - to be installed):
+```typescript
+import { oidcAuthMiddleware, getAuth, revokeSession, processOAuthCallback } from "@hono/oidc-auth";
+// getAuth(c) returns { sub: string, email?: string, ... } | null
+// oidcAuthMiddleware() redirects to OIDC provider if no session
+// processOAuthCallback(c) handles the /callback redirect
+// revokeSession(c) clears the OIDC session
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Install OIDC dependencies and rewrite auth middleware + service</name>
+  <files>package.json, src/server/middleware/auth.ts, src/server/services/auth.service.ts</files>
+  <read_first>
+    - src/server/middleware/auth.ts (current middleware with getUserCount, getSession, refreshSession)
+    - src/server/services/auth.service.ts (current service with user/session/apiKey functions)
+    - src/server/mcp/index.ts (imports getUserCount, verifyApiKey from auth.service)
+    - .planning/phases/15-external-authentication/15-RESEARCH.md (Pattern 1: Auth Middleware, Pitfall 5: getUserCount, Pitfall 6: OIDC_AUTH_SECRET)
+  </read_first>
+  <action>
+    **Install dependencies:**
+    ```bash
+    bun add @hono/oidc-auth jose
+    ```
+
+    **Rewrite `src/server/services/auth.service.ts`:**
+    - Remove ALL user management functions: `createUser`, `verifyPassword`, `getUserCount`, `changePassword`
+    - Remove ALL session management functions: `createSession`, `getSession`, `deleteSession`, `refreshSession`
+    - Remove imports of `users` and `sessions` from schema
+    - Remove `count` from drizzle-orm imports (only needed by getUserCount)
+    - KEEP all API key functions unchanged: `createApiKey`, `verifyApiKey`, `listApiKeys`, `deleteApiKey`
+    - Keep `randomBytes` import (used by createApiKey)
+    - Keep `eq` from drizzle-orm (used by API key functions)
+    - Keep `apiKeys` schema import
+    - Keep the `Db` type alias
+
+    The file should export exactly: `createApiKey`, `verifyApiKey`, `listApiKeys`, `deleteApiKey`.
+
+    **Rewrite `src/server/middleware/auth.ts`:**
+
+    Per D-04, implement three-way auth check. Replace the entire file with:
+
+    ```typescript
+    import type { Context, Next } from "hono";
+    import { getAuth } from "@hono/oidc-auth";
+    import { verifyApiKey } from "../services/auth.service";
+    import { verifyAccessToken } from "../services/oauth.service";
+
+    export async function requireAuth(c: Context, next: Next) {
+      const db = c.get("db");
+
+      // 1. Check API key (programmatic access) -- per D-10
+      const apiKey = c.req.header("X-API-Key");
+      if (apiKey) {
+        const valid = await verifyApiKey(db, apiKey);
+        if (valid) return next();
+        return c.json({ error: "Invalid API key" }, 401);
+      }
+
+      // 2. Check MCP OAuth Bearer token -- per D-12
+      const authHeader = c.req.header("Authorization");
+      if (authHeader?.startsWith("Bearer ")) {
+        const token = authHeader.slice(7);
+        if (await verifyAccessToken(db, token)) return next();
+        return c.json({ error: "invalid_token" }, 401);
+      }
+
+      // 3. Check OIDC session (browser users) -- per D-02
+      const auth = await getAuth(c);
+      if (auth) return next();
+
+      return c.json({ error: "Authentication required" }, 401);
+    }
+    ```
+
+    Key changes from old middleware:
+    - Removed `getUserCount` check (Pitfall 5) -- first-run setup happens on Logto admin console
+    - Removed `getCookie`/`getSession`/`refreshSession` -- replaced by `getAuth()` from @hono/oidc-auth
+    - Added MCP OAuth Bearer token check (was only in MCP routes, now centralized)
+    - No `hono/cookie` import needed
+  </action>
+  <verify>
+    <automated>grep -q "@hono/oidc-auth" package.json && grep -q "getAuth" src/server/middleware/auth.ts && ! grep -q "getUserCount" src/server/middleware/auth.ts && ! grep -q "getUserCount" src/server/services/auth.service.ts && grep -q "verifyApiKey" src/server/services/auth.service.ts && echo "PASS" || echo "FAIL"</automated>
+  </verify>
+  <acceptance_criteria>
+    - package.json contains `@hono/oidc-auth` dependency
+    - package.json contains `jose` dependency
+    - src/server/middleware/auth.ts imports `getAuth` from `@hono/oidc-auth`
+    - src/server/middleware/auth.ts imports `verifyAccessToken` from `../services/oauth.service`
+    - src/server/middleware/auth.ts does NOT import `getUserCount`, `getSession`, `refreshSession`
+    - src/server/middleware/auth.ts does NOT import from `hono/cookie`
+    - src/server/services/auth.service.ts does NOT contain `export async function createUser`
+    - src/server/services/auth.service.ts does NOT contain `export async function verifyPassword`
+    - src/server/services/auth.service.ts does NOT contain `export async function getUserCount`
+    - src/server/services/auth.service.ts does NOT contain `export async function createSession`
+    - src/server/services/auth.service.ts does NOT contain `export async function getSession`
+    - src/server/services/auth.service.ts does NOT import `users` or `sessions` from schema
+    - src/server/services/auth.service.ts DOES contain `export async function verifyApiKey`
+    - src/server/services/auth.service.ts DOES contain `export async function createApiKey`
+    - src/server/services/auth.service.ts DOES contain `export async function listApiKeys`
+    - src/server/services/auth.service.ts DOES contain `export async function deleteApiKey`
+  </acceptance_criteria>
+  <done>@hono/oidc-auth installed, middleware does three-way auth check, service only has API key functions</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Rewrite auth routes for OIDC login/callback/logout + API key CRUD</name>
+  <files>src/server/routes/auth.ts, src/server/index.ts</files>
+  <read_first>
+    - src/server/routes/auth.ts (current routes with login form, setup, password change, API key CRUD)
+    - src/server/index.ts (current route registration and middleware application order)
+    - .planning/phases/15-external-authentication/15-RESEARCH.md (Code Examples: @hono/oidc-auth Configuration, Pattern 2: OIDC Middleware Selective Application)
+  </read_first>
+  <action>
+    **Rewrite `src/server/routes/auth.ts`:**
+
+    Per D-05, D-06, D-07: Replace credential-based auth routes with OIDC redirect flow.
+
+    Remove:
+    - `POST /login` (credential login) -- replaced by OIDC redirect
+    - `POST /setup` (first-time account creation) -- happens on Logto now per D-06
+    - `PUT /password` (password change) -- managed by Logto now
+    - All Zod schemas: `loginSchema`, `setupSchema`, `changePasswordSchema`
+    - All cookie handling (`COOKIE_NAME`, `COOKIE_MAX_AGE`, `setCookie`, `getCookie`, `deleteCookie`)
+    - Imports of `users` from schema, `verifyPassword`, `createUser`, `changePassword`, `createSession`, `getSession`, `deleteSession`, `getUserCount`
+
+    Keep (with modifications):
+    - `GET /me` -- rewrite to use `getAuth()` from @hono/oidc-auth
+    - `GET /keys`, `POST /keys`, `DELETE /keys/:id` -- keep unchanged, still protected by requireAuth
+
+    Add:
+    - `GET /login` -- applies `oidcAuthMiddleware()` which redirects to Logto if no session; if session exists, redirects to `/`
+    - `GET /callback` -- calls `processOAuthCallback(c)` to handle OIDC redirect back from Logto
+    - `GET /logout` -- calls `revokeSession(c)` then redirects to `/login`
+
+    New file structure:
+    ```typescript
+    import { zValidator } from "@hono/zod-validator";
+    import { Hono } from "hono";
+    import { z } from "zod";
+    import {
+      oidcAuthMiddleware,
+      getAuth,
+      revokeSession,
+      processOAuthCallback,
+    } from "@hono/oidc-auth";
+    import { parseId } from "../lib/params.ts";
+    import { requireAuth } from "../middleware/auth.ts";
+    import {
+      createApiKey,
+      deleteApiKey,
+      listApiKeys,
+    } from "../services/auth.service.ts";
+
+    type Env = { Variables: { db?: any } };
+    const createKeySchema = z.object({ name: z.string().min(1) });
+    const app = new Hono<Env>();
+
+    // ── OIDC Browser Auth ────────────────────────────────────────────────
+
+    // Login: redirect to Logto if not authenticated
+    app.get("/login", oidcAuthMiddleware(), async (c) => {
+      // Middleware redirects to Logto if no session. If we reach here, user is authenticated.
+      return c.redirect("/");
+    });
+
+    // Callback: process OIDC redirect from Logto
+    app.get("/callback", async (c) => {
+      return processOAuthCallback(c);
+    });
+
+    // Logout: revoke OIDC session and redirect
+    app.get("/logout", async (c) => {
+      await revokeSession(c);
+      return c.redirect("/login");
+    });
+
+    // ── Auth Status ──────────────────────────────────────────────────────
+
+    app.get("/me", async (c) => {
+      const auth = await getAuth(c);
+      if (auth) {
+        return c.json({
+          user: { id: auth.sub, email: auth.email },
+          authenticated: true,
+        });
+      }
+      return c.json({ user: null, authenticated: false });
+    });
+
+    // ── API Key Management (protected) ───────────────────────────────────
+
+    app.get("/keys", requireAuth, async (c) => {
+      const db = c.get("db");
+      const keys = await listApiKeys(db);
+      return c.json(keys);
+    });
+
+    app.post("/keys", requireAuth, zValidator("json", createKeySchema), async (c) => {
+      const db = c.get("db");
+      const { name } = c.req.valid("json");
+      const result = await createApiKey(db, name);
+      return c.json({ id: result.id, name: result.name, key: result.rawKey, prefix: result.keyPrefix }, 201);
+    });
+
+    app.delete("/keys/:id", requireAuth, async (c) => {
+      const db = c.get("db");
+      const id = parseId(c.req.param("id"));
+      if (!id) return c.json({ error: "Invalid key ID" }, 400);
+      await deleteApiKey(db, id);
+      return c.json({ ok: true });
+    });
+
+    export const authRoutes = app;
+    ```
+
+    **Update `src/server/index.ts`:**
+
+    The OIDC auth routes (`/login`, `/callback`, `/logout`) need to be accessible at the root level, not under `/api/auth`. But API key routes stay at `/api/auth/keys`.
+
+    Changes to index.ts:
+    1. Add a new top-level route group for OIDC browser auth (login, callback, logout):
+       ```typescript
+       // OIDC browser auth routes (top-level, not under /api)
+       app.get("/login", ...); // Delegate to authRoutes
+       app.get("/callback", ...); // Delegate to authRoutes
+       app.get("/logout", ...); // Delegate to authRoutes
+       ```
+
+       Actually, simpler approach: mount authRoutes at root level for the OIDC routes AND at `/api/auth` for the API routes. But since Hono route() mounts all routes under a prefix, we need to split.
+
+       Better approach: Keep authRoutes mounted at `/api/auth` for /me, /keys. Create separate top-level routes for /login, /callback, /logout:
+
+       ```typescript
+       import { oidcAuthMiddleware, processOAuthCallback, revokeSession } from "@hono/oidc-auth";
+
+       // OIDC browser auth (before /api/* middleware)
+       app.get("/login", oidcAuthMiddleware(), async (c) => c.redirect("/"));
+       app.get("/callback", async (c) => processOAuthCallback(c));
+       app.get("/logout", async (c) => { await revokeSession(c); return c.redirect("/login"); });
+       ```
+
+       Then remove the /login, /callback, /logout routes from authRoutes (keep only /me and /keys/* in authRoutes).
+
+    2. Place these OIDC routes BEFORE the `/api/*` middleware blocks and BEFORE static file serving
+    3. Keep `app.route("/api/auth", authRoutes)` for /me and /keys endpoints
+    4. Ensure the auth middleware skip for `/api/auth` still works (it does -- /api/auth/me is GET, /api/auth/keys POST/DELETE go through requireAuth within the route handler)
+
+    So the final authRoutes file should NOT contain /login, /callback, /logout. Those go directly in index.ts. authRoutes contains: GET /me, GET /keys, POST /keys, DELETE /keys/:id.
+
+    **IMPORTANT (Pattern 2):** Do NOT apply `oidcAuthMiddleware()` globally. Only apply it to the `/login` route. The `/api/*` routes use the custom `requireAuth` middleware.
+  </action>
+  <verify>
+    <automated>grep -q "processOAuthCallback" src/server/index.ts && grep -q "oidcAuthMiddleware" src/server/index.ts && ! grep -q "verifyPassword" src/server/routes/auth.ts && ! grep -q "createUser" src/server/routes/auth.ts && grep -q "getAuth" src/server/routes/auth.ts && echo "PASS" || echo "FAIL"</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/server/routes/auth.ts does NOT contain `POST /login`, `POST /setup`, `PUT /password` handlers
+    - src/server/routes/auth.ts does NOT import `verifyPassword`, `createUser`, `changePassword`, `createSession`, `deleteSession`, `getSession`, `getUserCount`
+    - src/server/routes/auth.ts does NOT import `users` from schema
+    - src/server/routes/auth.ts does NOT import `setCookie`, `getCookie`, `deleteCookie` from `hono/cookie`
+    - src/server/routes/auth.ts DOES contain `GET /me` using `getAuth()` from @hono/oidc-auth
+    - src/server/routes/auth.ts DOES contain API key CRUD routes (GET /keys, POST /keys, DELETE /keys/:id)
+    - src/server/index.ts contains `app.get("/login"` with `oidcAuthMiddleware()`
+    - src/server/index.ts contains `app.get("/callback"` with `processOAuthCallback`
+    - src/server/index.ts contains `app.get("/logout"` with `revokeSession`
+    - These OIDC routes appear BEFORE the `/api/*` middleware blocks in index.ts
+  </acceptance_criteria>
+  <done>Auth routes serve OIDC login/callback/logout at root, /me returns OIDC claims, API key CRUD preserved</done>
+</task>
+
+<task type="auto">
+  <name>Task 3: Update MCP OAuth authorize and MCP auth middleware for OIDC</name>
+  <files>src/server/routes/oauth.ts, src/server/mcp/index.ts</files>
+  <read_first>
+    - src/server/routes/oauth.ts (current MCP OAuth with verifyPassword in POST /authorize)
+    - src/server/mcp/index.ts (current MCP auth middleware with getUserCount check)
+    - .planning/phases/15-external-authentication/15-RESEARCH.md (Pitfall 3: MCP OAuth POST /authorize, Pitfall 5: getUserCount)
+  </read_first>
+  <action>
+    **Per D-12:** MCP OAuth coexists with Logto. These are separate auth domains. But the MCP OAuth authorize form currently uses `verifyPassword()` against the removed `users` table -- this must be fixed.
+
+    **Update `src/server/routes/oauth.ts`:**
+
+    1. Remove `import { verifyPassword } from "../services/auth.service.ts"` -- this function no longer exists
+    2. Add `import { getAuth } from "@hono/oidc-auth"`
+    3. Replace the `POST /authorize` handler logic:
+       - Instead of parsing username/password from the form and calling `verifyPassword()`, check for an active OIDC session using `getAuth(c)`
+       - If the user has a valid OIDC session (`getAuth(c)` returns non-null), proceed with authorization code creation
+       - If no OIDC session, redirect to `/login` with a return URL that brings them back to the authorize page after Logto login
+
+    Updated POST /authorize:
+    ```typescript
+    oauthRoutes.post("/authorize", async (c) => {
+      const db = c.get("db") ?? prodDb;
+
+      // Check for OIDC session instead of username/password
+      const auth = await getAuth(c);
+      if (!auth) {
+        // No session -- redirect to login, then back to authorize
+        const currentUrl = c.req.url;
+        return c.redirect(`/login?redirect=${encodeURIComponent(currentUrl)}`);
+      }
+
+      const body = await c.req.parseBody();
+      const clientId = body.client_id as string;
+      const redirectUri = body.redirect_uri as string;
+      const codeChallenge = body.code_challenge as string;
+      const codeChallengeMethod = body.code_challenge_method as string;
+      const state = (body.state as string) ?? "";
+
+      const client = await getClient(db, clientId);
+      if (!client) {
+        return c.json({ error: "Unknown client_id" }, 400);
+      }
+
+      const allowedUris: string[] = JSON.parse(client.redirectUris);
+      if (!allowedUris.includes(redirectUri)) {
+        return c.json({ error: "redirect_uri not allowed" }, 400);
+      }
+
+      const { code } = await createAuthorizationCode(
+        db,
+        clientId,
+        codeChallenge,
+        codeChallengeMethod,
+        redirectUri,
+      );
+
+      const url = new URL(redirectUri);
+      url.searchParams.set("code", code);
+      if (state) url.searchParams.set("state", state);
+
+      return c.redirect(url.toString(), 302);
+    });
+    ```
+
+    4. Update the `GET /authorize` handler to also check for OIDC session:
+       - If user has OIDC session, show a simplified consent screen (just an "Authorize" button, no login form)
+       - If no OIDC session, redirect to `/login` with return URL
+
+    Replace `renderLoginForm` with a simpler `renderConsentForm` that shows the client name and an "Authorize" button (no username/password fields). The consent form POSTs to `/oauth/authorize` with the hidden fields (client_id, redirect_uri, code_challenge, code_challenge_method, state).
+
+    If no OIDC session on GET /authorize, redirect:
+    ```typescript
+    oauthRoutes.get("/authorize", async (c) => {
+      const auth = await getAuth(c);
+      if (!auth) {
+        return c.redirect(`/login?redirect=${encodeURIComponent(c.req.url)}`);
+      }
+      // ... show consent form ...
+    });
+    ```
+
+    5. Keep all other oauth routes unchanged: POST /register, POST /token, well-known endpoints
+
+    **Update `src/server/mcp/index.ts`:**
+
+    Per Pitfall 5, remove the `getUserCount` check from MCP auth middleware.
+
+    1. Remove `import { getUserCount } from "../services/auth.service.ts"` (only keep `verifyApiKey`)
+    2. Remove the `if (getUserCount(db) <= 0) { return next(); }` block
+    3. The MCP auth middleware should now only check Bearer token and API key -- no "skip if no users" bypass
+
+    Updated MCP auth middleware:
+    ```typescript
+    mcpRoutes.use("/*", async (c, next) => {
+      const db = c.get("db") ?? prodDb;
+
+      // Try Bearer token first (OAuth)
+      const authHeader = c.req.header("Authorization");
+      if (authHeader?.startsWith("Bearer ")) {
+        const token = authHeader.slice(7);
+        if (await verifyAccessToken(db, token)) {
+          return next();
+        }
+        return c.json({ error: "invalid_token" }, 401);
+      }
+
+      // Try API key
+      const apiKey = c.req.header("X-API-Key");
+      if (apiKey) {
+        const valid = await verifyApiKey(db, apiKey);
+        if (valid) {
+          return next();
+        }
+        return c.json({ error: "Invalid API key" }, 401);
+      }
+
+      // No auth provided
+      const baseUrl = (process.env.GEARBOX_URL || new URL(c.req.url).origin).replace(/\/$/, "");
+      return c.text("Unauthorized", 401, {
+        "WWW-Authenticate": `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource"`,
+      });
+    });
+    ```
+  </action>
+  <verify>
+    <automated>! grep -q "verifyPassword" src/server/routes/oauth.ts && ! grep -q "getUserCount" src/server/mcp/index.ts && grep -q "getAuth" src/server/routes/oauth.ts && echo "PASS" || echo "FAIL"</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/server/routes/oauth.ts does NOT import `verifyPassword`
+    - src/server/routes/oauth.ts DOES import `getAuth` from `@hono/oidc-auth`
+    - src/server/routes/oauth.ts POST /authorize checks OIDC session via `getAuth(c)` instead of username/password
+    - src/server/routes/oauth.ts GET /authorize redirects to `/login` if no OIDC session
+    - src/server/routes/oauth.ts does NOT contain `renderLoginForm` with username/password fields
+    - src/server/routes/oauth.ts DOES contain a consent form with just an "Authorize" button (no credential fields)
+    - src/server/mcp/index.ts does NOT import `getUserCount`
+    - src/server/mcp/index.ts does NOT contain `getUserCount` call
+    - src/server/mcp/index.ts DOES still import `verifyApiKey`
+    - src/server/mcp/index.ts DOES still import `verifyAccessToken`
+    - All well-known routes, POST /register, POST /token remain unchanged
+  </acceptance_criteria>
+  <done>MCP OAuth uses OIDC session for authorization, MCP middleware has no getUserCount bypass, both auth domains coexist cleanly</done>
+</task>
+
+</tasks>
+
+<verification>
+- `bun run build` succeeds (TypeScript compiles without errors referencing removed functions/tables)
+- `grep -rn "getUserCount\|createUser\|verifyPassword\|createSession\|getSession\|deleteSession\|refreshSession" src/server/` returns NO matches
+- `grep -rn "getAuth" src/server/middleware/auth.ts src/server/routes/auth.ts src/server/routes/oauth.ts` shows usage in all three files
+- `grep "verifyApiKey" src/server/middleware/auth.ts` confirms API key path preserved
+- `grep "verifyAccessToken" src/server/middleware/auth.ts` confirms MCP Bearer path preserved
+</verification>
+
+<success_criteria>
+- Three-way auth middleware works: API key, MCP Bearer, OIDC session
+- Browser auth flow: /login redirects to Logto, /callback processes return, /logout clears session
+- /api/auth/me returns OIDC user identity or null
+- API key CRUD at /api/auth/keys preserved and functional
+- MCP OAuth authorize uses OIDC session instead of removed password verification
+- MCP auth middleware has no getUserCount bypass
+- No references to removed user/session functions anywhere in src/server/
+- TypeScript compiles cleanly
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/15-external-authentication/15-02-SUMMARY.md`
+</output>
--- a/.planning/phases/15-external-authentication/15-03-PLAN.md
+++ b/.planning/phases/15-external-authentication/15-03-PLAN.md
@@ -0,0 +1,423 @@
+---
+phase: 15-external-authentication
+plan: 03
+type: execute
+wave: 3
+depends_on: ["15-02"]
+files_modified:
+  - src/client/routes/login.tsx
+  - src/client/hooks/useAuth.ts
+  - e2e/seed.ts
+  - tests/middleware/auth.test.ts
+  - tests/services/auth.service.test.ts
+  - tests/routes/auth.test.ts
+autonomous: false
+requirements: [AUTH-05, AUTH-01, AUTH-02]
+
+must_haves:
+  truths:
+    - "Login page redirects users to Logto instead of showing a credential form"
+    - "useAuth hook returns OIDC-based user identity (sub string, not integer id)"
+    - "E2E seed script creates API keys directly without inserting into users table"
+    - "E2E tests authenticate via API key header, not Logto"
+    - "Unit tests for auth middleware and service pass without users/sessions tables"
+  artifacts:
+    - path: "src/client/routes/login.tsx"
+      provides: "Login page that redirects to /login (OIDC redirect)"
+    - path: "src/client/hooks/useAuth.ts"
+      provides: "Auth hooks without useLogin, useSetup, useChangePassword"
+      exports: ["useAuth", "useLogout", "useApiKeys", "useCreateApiKey", "useDeleteApiKey"]
+    - path: "e2e/seed.ts"
+      provides: "E2E seed without users table insert"
+    - path: "tests/middleware/auth.test.ts"
+      provides: "Middleware tests for three-way auth"
+    - path: "tests/services/auth.service.test.ts"
+      provides: "Service tests for API key functions only"
+    - path: "tests/routes/auth.test.ts"
+      provides: "Route tests for /me and /keys endpoints"
+  key_links:
+    - from: "src/client/hooks/useAuth.ts"
+      to: "/api/auth/me"
+      via: "apiGet fetch"
+      pattern: "apiGet.*api/auth/me"
+    - from: "src/client/routes/login.tsx"
+      to: "/login"
+      via: "window.location redirect to OIDC login"
+      pattern: "window.location|/login"
+    - from: "e2e/seed.ts"
+      to: "apiKeys table"
+      via: "direct insert"
+      pattern: "apiKeys"
+---
+
+<objective>
+Update the client-side auth UI, auth hooks, E2E seed script, and all auth-related tests to work with the new OIDC-based authentication.
+
+Purpose: The server-side auth was rewritten in Plan 02. This plan brings the client and tests into alignment -- login page redirects to Logto, hooks match new API responses, E2E tests use API keys per AUTH-05, and unit/integration tests validate the new auth architecture.
+
+Output: Working client auth flow, passing unit tests, E2E-ready seed script.
+</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/15-external-authentication/15-CONTEXT.md
+@.planning/phases/15-external-authentication/15-RESEARCH.md
+@.planning/phases/15-external-authentication/15-01-SUMMARY.md
+@.planning/phases/15-external-authentication/15-02-SUMMARY.md
+@src/client/routes/login.tsx
+@src/client/hooks/useAuth.ts
+@e2e/seed.ts
+@tests/middleware/auth.test.ts
+@tests/services/auth.service.test.ts
+@tests/routes/auth.test.ts
+
+<interfaces>
+<!-- New server API contracts from Plan 02 -->
+
+GET /api/auth/me response (new shape):
+```typescript
+// Authenticated (OIDC session):
+{ user: { id: string, email?: string }, authenticated: true }
+// Not authenticated:
+{ user: null, authenticated: false }
+```
+Note: user.id is now a string (Logto sub claim), NOT an integer.
+
+GET /login behavior: Redirects to Logto OIDC provider (server-side redirect via @hono/oidc-auth)
+GET /callback behavior: Processes OIDC callback, sets session cookie, redirects to /
+GET /logout behavior: Revokes OIDC session, redirects to /login
+
+API key routes unchanged:
+GET /api/auth/keys -> ApiKeyListItem[]
+POST /api/auth/keys { name: string } -> { id, name, key, prefix }
+DELETE /api/auth/keys/:id -> { ok: true }
+
+Auth middleware (from Plan 02):
+```typescript
+export async function requireAuth(c: Context, next: Next)
+// Checks: X-API-Key header -> Bearer token -> OIDC session cookie
+```
+
+Auth service exports (from Plan 02):
+```typescript
+export async function createApiKey(db, name): Promise<{id, name, keyHash, keyPrefix, createdAt, rawKey}>
+export async function verifyApiKey(db, rawKey): Promise<boolean>
+export async function listApiKeys(db): Promise<{id, name, keyPrefix, createdAt}[]>
+export async function deleteApiKey(db, id): Promise<void>
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Rewrite login page and auth hooks for OIDC</name>
+  <files>src/client/routes/login.tsx, src/client/hooks/useAuth.ts</files>
+  <read_first>
+    - src/client/routes/login.tsx (current login form with username/password)
+    - src/client/hooks/useAuth.ts (current hooks: useAuth, useLogin, useSetup, useChangePassword, useLogout, useApiKeys, useCreateApiKey, useDeleteApiKey)
+    - .planning/phases/15-external-authentication/15-CONTEXT.md (D-07: /login becomes redirect trigger, D-06: registration on Logto)
+  </read_first>
+  <action>
+    **Rewrite `src/client/hooks/useAuth.ts`:**
+
+    Per D-07 and D-06, remove hooks that relied on credential-based auth:
+    - Remove `useLogin` (no more POST /api/auth/login)
+    - Remove `useSetup` (no more POST /api/auth/setup)
+    - Remove `useChangePassword` (no more PUT /api/auth/password)
+
+    Update `useAuth`:
+    - Change `AuthState` interface: `user` is now `{ id: string; email?: string } | null` (id changed from number to string per Logto sub claim)
+    - Remove `setupRequired` field -- first-run setup is on Logto admin console
+    - New interface:
+      ```typescript
+      interface AuthState {
+        user: { id: string; email?: string } | null;
+        authenticated: boolean;
+      }
+      ```
+
+    Update `useLogout`:
+    - Change from `apiPost("/api/auth/logout", {})` to `window.location.href = "/logout"` (server-side OIDC logout via redirect)
+    - Since this is a redirect (not an API call), use a simple function instead of useMutation:
+      ```typescript
+      export function useLogout() {
+        const logout = () => {
+          window.location.href = "/logout";
+        };
+        return { logout };
+      }
+      ```
+
+    Keep unchanged: `useApiKeys`, `useCreateApiKey`, `useDeleteApiKey` (API key CRUD routes are the same).
+
+    Final exports: `useAuth`, `useLogout`, `useApiKeys`, `useCreateApiKey`, `useDeleteApiKey`.
+
+    **Rewrite `src/client/routes/login.tsx`:**
+
+    Per D-07: The login page becomes a redirect trigger to Logto, not a credential form.
+
+    Replace the entire form with a simple page that:
+    1. On mount, checks if user is already authenticated via `useAuth()`
+    2. If authenticated, redirects to `/` via TanStack Router `navigate`
+    3. If not authenticated, shows a centered card with "Sign in to GearBox" heading and a "Sign in" button
+    4. The "Sign in" button sets `window.location.href = "/login"` which triggers the server-side OIDC redirect to Logto
+
+    ```typescript
+    import { createFileRoute, useNavigate } from "@tanstack/react-router";
+    import { useEffect } from "react";
+    import { useAuth } from "../hooks/useAuth";
+
+    export const Route = createFileRoute("/login")({
+      component: LoginPage,
+    });
+
+    function LoginPage() {
+      const navigate = useNavigate();
+      const { data: auth, isLoading } = useAuth();
+
+      useEffect(() => {
+        if (auth?.authenticated) {
+          navigate({ to: "/" });
+        }
+      }, [auth, navigate]);
+
+      if (isLoading) {
+        return (
+          <div className="min-h-screen bg-gray-50 flex items-center justify-center">
+            <p className="text-gray-500 text-sm">Loading...</p>
+          </div>
+        );
+      }
+
+      return (
+        <div className="min-h-screen bg-gray-50 flex items-center justify-center px-4">
+          <div className="w-full max-w-sm">
+            <h1 className="text-xl font-semibold text-gray-900 text-center mb-6">
+              Sign in to GearBox
+            </h1>
+            <div className="bg-white rounded-xl border border-gray-100 p-6 space-y-4">
+              <p className="text-sm text-gray-500 text-center">
+                You will be redirected to sign in with your account.
+              </p>
+              <button
+                type="button"
+                onClick={() => { window.location.href = "/login"; }}
+                className="w-full py-2 px-4 text-sm font-medium text-white bg-gray-700 hover:bg-gray-800 rounded-lg transition-colors"
+              >
+                Sign In
+              </button>
+            </div>
+          </div>
+        </div>
+      );
+    }
+    ```
+
+    Note: The client route is `/login` (TanStack Router) and the server route is also `GET /login` (OIDC redirect). The client-side route renders the UI. When the user clicks "Sign In", `window.location.href = "/login"` does a full-page navigation to the server's GET /login which triggers the OIDC redirect to Logto. This works because in dev mode, Vite proxies unmatched paths to the Hono server, and in production, the SPA serves index.html for client routes but the server handles `/login` before the SPA fallback.
+
+    **IMPORTANT:** Check `src/server/index.ts` from Plan 02 -- the server-side `/login` route must be registered BEFORE the SPA static file fallback so it takes priority.
+  </action>
+  <verify>
+    <automated>! grep -q "useLogin\|useSetup\|useChangePassword" src/client/hooks/useAuth.ts && grep -q "authenticated" src/client/hooks/useAuth.ts && ! grep -q "setupRequired" src/client/hooks/useAuth.ts && ! grep -q 'id: number' src/client/hooks/useAuth.ts && grep -q "window.location.href" src/client/routes/login.tsx && ! grep -q "handleSubmit" src/client/routes/login.tsx && echo "PASS" || echo "FAIL"</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/client/hooks/useAuth.ts does NOT export `useLogin`, `useSetup`, or `useChangePassword`
+    - src/client/hooks/useAuth.ts AuthState has `user: { id: string; email?: string } | null`
+    - src/client/hooks/useAuth.ts AuthState has `authenticated: boolean` (not `setupRequired`)
+    - src/client/hooks/useAuth.ts useLogout uses `window.location.href = "/logout"` (not apiPost)
+    - src/client/hooks/useAuth.ts DOES export `useAuth`, `useLogout`, `useApiKeys`, `useCreateApiKey`, `useDeleteApiKey`
+    - src/client/routes/login.tsx does NOT contain a `<form>` element
+    - src/client/routes/login.tsx does NOT contain username/password `<input>` elements
+    - src/client/routes/login.tsx DOES contain `window.location.href = "/login"` in button onClick
+    - src/client/routes/login.tsx DOES import `useAuth` from hooks
+  </acceptance_criteria>
+  <done>Login page redirects to Logto via server, auth hooks match new OIDC-based API responses, no credential forms remain</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Update E2E seed script and auth-related tests</name>
+  <files>e2e/seed.ts, tests/middleware/auth.test.ts, tests/services/auth.service.test.ts, tests/routes/auth.test.ts</files>
+  <read_first>
+    - e2e/seed.ts (current seed creates user with password hash in users table)
+    - tests/middleware/auth.test.ts (current tests for requireAuth middleware)
+    - tests/services/auth.service.test.ts (current tests for user/session/apiKey service functions)
+    - tests/routes/auth.test.ts (current tests for auth routes)
+    - tests/helpers/db.ts (test database setup helper)
+    - src/server/middleware/auth.ts (new middleware from Plan 02 -- to understand what to test)
+    - src/server/services/auth.service.ts (new service from Plan 02 -- only API key functions)
+    - src/server/routes/auth.ts (new routes from Plan 02 -- /me and /keys)
+  </read_first>
+  <action>
+    **Update `e2e/seed.ts`:**
+
+    Per AUTH-05 and Pitfall 4: E2E tests authenticate via API keys, no Logto dependency.
+
+    1. Remove the user creation block:
+       ```typescript
+       // DELETE THIS:
+       const passwordHash = await Bun.password.hash("password123");
+       db.insert(schema.users).values({ username: "admin", passwordHash }).run();
+       ```
+
+    2. Add API key creation instead:
+       ```typescript
+       // Create API key for E2E test authentication
+       const rawKey = "e2e-test-api-key-for-gearbox-testing";
+       const keyHash = await Bun.password.hash(rawKey);
+       const keyPrefix = rawKey.slice(0, 8);
+       db.insert(schema.apiKeys)
+         .values({ name: "E2E Test Key", keyHash, keyPrefix })
+         .run();
+       ```
+
+    3. Remove `import { users } from "../src/db/schema"` if it was used only for user creation. The seed script imports `* as schema`, so just remove the `schema.users` usage.
+
+    4. The seed script still uses `bun:sqlite` and Drizzle SQLite adapter for now (E2E tests run against SQLite). This is fine -- the `users` table won't exist in the generated schema migration. However, the seed script uses `migrate(db, { migrationsFolder: "./drizzle" })` which will apply the latest migration that drops the users table. So removing the users insert is necessary to prevent a "table not found" error.
+
+    **IMPORTANT:** The seed script will also need to handle that the `sessions` table is dropped. Verify there are no references to `schema.sessions` in the seed script (there shouldn't be based on current code).
+
+    **Update `tests/services/auth.service.test.ts`:**
+
+    Remove ALL tests for removed functions:
+    - Tests for `createUser`, `verifyPassword`, `getUserCount`, `changePassword`
+    - Tests for `createSession`, `getSession`, `deleteSession`, `refreshSession`
+
+    Keep ALL tests for API key functions:
+    - Tests for `createApiKey`, `verifyApiKey`, `listApiKeys`, `deleteApiKey`
+
+    Update imports to only import the kept functions from `auth.service.ts`. Remove imports of `users`, `sessions` from schema if present.
+
+    The test db helper creates tables from migrations, so after Plan 01's migration drops users/sessions, the test DB won't have those tables either. API key tests should work unchanged.
+
+    **Update `tests/middleware/auth.test.ts`:**
+
+    The middleware now has three auth paths. Rewrite tests:
+
+    Remove:
+    - Tests for `setup_required` response (getUserCount === 0 case -- removed)
+    - Tests for cookie session auth path
+    - Any mocking of `getSession`, `refreshSession`, `getUserCount`
+
+    Update/Add:
+    - Test: API key in `X-API-Key` header -> valid -> 200 (keep existing)
+    - Test: API key in `X-API-Key` header -> invalid -> 401 (keep existing)
+    - Test: Bearer token in Authorization header -> valid -> 200 (new)
+    - Test: Bearer token in Authorization header -> invalid -> 401 (new)
+    - Test: No auth headers, no OIDC session -> 401 (update existing)
+    - Test: OIDC session exists -> 200 (new -- mock `getAuth` from @hono/oidc-auth)
+
+    For mocking `getAuth` from `@hono/oidc-auth`, use `mock.module` (Bun's mock facility):
+    ```typescript
+    import { mock } from "bun:test";
+
+    // Mock @hono/oidc-auth
+    const mockGetAuth = mock(() => null);
+    mock.module("@hono/oidc-auth", () => ({
+      getAuth: mockGetAuth,
+      oidcAuthMiddleware: () => async (c, next) => next(),
+      processOAuthCallback: async (c) => c.json({ ok: true }),
+      revokeSession: async () => {},
+    }));
+    ```
+
+    Then in tests, set `mockGetAuth.mockReturnValue(...)` to simulate authenticated/unauthenticated OIDC sessions.
+
+    **Update `tests/routes/auth.test.ts`:**
+
+    Remove tests for:
+    - POST /auth/login (removed)
+    - POST /auth/setup (removed)
+    - PUT /auth/password (removed)
+
+    Update tests for:
+    - GET /auth/me -- now returns `{ user: { id: string, email: string }, authenticated: true }` or `{ user: null, authenticated: false }`
+    - Mock `getAuth` to simulate OIDC session for /me tests
+
+    Keep tests for:
+    - GET /auth/keys (requires auth -- use API key in test)
+    - POST /auth/keys (requires auth)
+    - DELETE /auth/keys/:id (requires auth)
+
+    Note: GET /login, GET /callback, GET /logout are registered in index.ts not authRoutes, so they are NOT tested in auth route tests. They would be E2E-level tests.
+  </action>
+  <verify>
+    <automated>! grep -q "schema.users" e2e/seed.ts && grep -q "apiKeys" e2e/seed.ts && ! grep -q "createUser\|verifyPassword\|getUserCount\|createSession\|getSession" tests/services/auth.service.test.ts && grep -q "verifyApiKey\|createApiKey" tests/services/auth.service.test.ts && echo "PASS" || echo "FAIL"</automated>
+  </verify>
+  <acceptance_criteria>
+    - e2e/seed.ts does NOT insert into `schema.users`
+    - e2e/seed.ts DOES insert an API key into `schema.apiKeys` with name "E2E Test Key"
+    - e2e/seed.ts still seeds categories, items, threads, setups, settings
+    - tests/services/auth.service.test.ts does NOT test `createUser`, `verifyPassword`, `getUserCount`, `changePassword`, `createSession`, `getSession`, `deleteSession`, `refreshSession`
+    - tests/services/auth.service.test.ts DOES test `createApiKey`, `verifyApiKey`, `listApiKeys`, `deleteApiKey`
+    - tests/middleware/auth.test.ts does NOT test `setup_required` response
+    - tests/middleware/auth.test.ts DOES test API key auth path
+    - tests/middleware/auth.test.ts DOES test Bearer token auth path
+    - tests/middleware/auth.test.ts DOES mock and test OIDC session auth path via `getAuth`
+    - tests/routes/auth.test.ts does NOT test POST /login, POST /setup, PUT /password
+    - tests/routes/auth.test.ts DOES test GET /me with mocked OIDC session
+    - tests/routes/auth.test.ts DOES test API key CRUD routes
+  </acceptance_criteria>
+  <done>E2E seed uses API keys, all auth tests updated for OIDC architecture, no references to removed user/session functions</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 3: Verify OIDC login flow with running Logto</name>
+  <what-built>Complete OIDC authentication integration: Logto in Docker Compose, server-side OIDC middleware, client-side login redirect, API key continuity, updated tests</what-built>
+  <how-to-verify>
+    1. Start infrastructure: `docker compose -f docker-compose.dev.yml up -d`
+    2. Verify Logto is running: visit http://localhost:3002 (Logto Admin Console)
+    3. In Logto Admin Console:
+       a. Create a "Traditional Web" application
+       b. Set redirect URI: `http://localhost:3000/callback`
+       c. Set post-logout redirect URI: `http://localhost:3000/login`
+       d. Copy App ID and App Secret
+    4. Create a `.env` file with:
+       ```
+       OIDC_ISSUER=http://localhost:3001/oidc
+       OIDC_CLIENT_ID=<copied app id>
+       OIDC_CLIENT_SECRET=<copied app secret>
+       OIDC_AUTH_SECRET=a-random-string-at-least-32-characters-long
+       ```
+    5. Start GearBox: `bun run dev`
+    6. Visit http://localhost:5173/login -- should see "Sign in to GearBox" page
+    7. Click "Sign In" -- should redirect to Logto login page
+    8. Register a new account on Logto
+    9. After registration, should redirect back to GearBox dashboard
+    10. Visit http://localhost:5173 -- should show authenticated state
+    11. Run unit tests: `bun test` -- all should pass
+    12. Verify API key auth still works: create a key in Settings, test with curl:
+        `curl -H "X-API-Key: <key>" http://localhost:3000/api/items`
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues found during verification</resume-signal>
+</task>
+
+</tasks>
+
+<verification>
+- `bun test` passes (all auth-related tests updated)
+- `bun run build` succeeds (no TypeScript errors)
+- E2E seed script runs without error: `bun run e2e/seed.ts`
+- No references to removed hooks in client code: `grep -rn "useLogin\|useSetup\|useChangePassword" src/client/`
+- No references to removed auth functions in test code: `grep -rn "createUser\|verifyPassword\|getUserCount" tests/`
+</verification>
+
+<success_criteria>
+- Login page shows redirect button, not credential form
+- Auth hooks match new OIDC API response shape
+- E2E seed creates API key, not user
+- All unit/integration tests pass
+- Full OIDC login flow works end-to-end with Logto (verified by human checkpoint)
+- API keys still work for programmatic access
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/15-external-authentication/15-03-SUMMARY.md`
+</output>