---
phase: 15-external-authentication
plan: 02
subsystem: auth
tags: [oidc, hono, logto, @hono/oidc-auth, jose, mcp-oauth]

# Dependency graph
requires:
  - phase: 15-external-authentication (plan 01)
    provides: Docker Compose with Logto service, env vars, schema without users/sessions tables
provides:
  - Three-way auth middleware (API key, MCP Bearer, OIDC session)
  - OIDC login/callback/logout routes at root level
  - Auth service stripped to API key CRUD only
  - MCP OAuth authorize using OIDC session instead of password
affects: [15-external-authentication plan 03, client-side login page, e2e tests]

# Tech tracking
tech-stack:
  added: ["@hono/oidc-auth@1.8.1", "jose@6.2.2"]
  patterns: [three-way-auth-middleware, oidc-session-validation, consent-form-pattern]

key-files:
  created: []
  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

key-decisions:
  - "OIDC routes (/login, /callback, /logout) placed at root level in index.ts, not under /api/auth"
  - "MCP OAuth authorize uses consent-only form (no credentials) backed by OIDC session"
  - "Three-way auth order: API key first, Bearer token second, OIDC session third"

patterns-established:
  - "Three-way auth: requireAuth checks API key -> MCP Bearer -> OIDC session in order"
  - "OIDC routes at root level, API routes under /api/auth"
  - "Consent form pattern: MCP OAuth shows authorize button only (no credential fields)"

requirements-completed: [AUTH-01, AUTH-02, AUTH-03]

# Metrics
duration: 4min
completed: 2026-04-04
---

# Phase 15 Plan 02: OIDC Auth Integration Summary

**Three-way auth middleware with @hono/oidc-auth for browser sessions, API keys for programmatic access, and MCP OAuth consent flow**

## Performance

- **Duration:** 4 min
- **Started:** 2026-04-04T18:42:20Z
- **Completed:** 2026-04-04T18:46:35Z
- **Tasks:** 3
- **Files modified:** 8

## Accomplishments
- Replaced custom cookie-session auth with OIDC via @hono/oidc-auth in requireAuth middleware
- Stripped auth service to API key functions only (removed all user/session management)
- Added /login, /callback, /logout OIDC routes at root level for browser auth flow
- Updated MCP OAuth to use OIDC session for authorization consent instead of password verification
- Removed getUserCount bypass from MCP auth middleware

## Task Commits

Each task was committed atomically:

1. **Task 1: Install OIDC dependencies and rewrite auth middleware + service** - `259dc2b` (feat)
2. **Task 2: Rewrite auth routes for OIDC login/callback/logout + API key CRUD** - `1b6a65b` (feat)
3. **Task 3: Update MCP OAuth authorize and MCP auth middleware for OIDC** - `c0e6db5` (feat)

## Files Created/Modified
- `package.json` - Added @hono/oidc-auth and jose dependencies
- `src/server/middleware/auth.ts` - Three-way auth: API key, MCP Bearer, OIDC session
- `src/server/services/auth.service.ts` - API key CRUD only (user/session functions removed)
- `src/server/routes/auth.ts` - GET /me with OIDC claims, API key CRUD routes
- `src/server/routes/oauth.ts` - Consent form replaces login form, getAuth replaces verifyPassword
- `src/server/mcp/index.ts` - Removed getUserCount import and bypass logic
- `src/server/index.ts` - Added root-level /login, /callback, /logout OIDC routes

## Decisions Made
- Placed OIDC browser auth routes (/login, /callback, /logout) at root level in index.ts rather than under /api/auth, keeping API key management at /api/auth/keys
- Auth check order in middleware: API key first (fast path for programmatic), Bearer token second (MCP), OIDC session third (browser)
- MCP OAuth authorize shows consent-only form when user has OIDC session, redirects to /login otherwise

## Deviations from Plan

None - plan executed exactly as written.

## Known Stubs

None - all data paths are wired to real implementations.

## Issues Encountered

None.

## User Setup Required

None - OIDC provider (Logto) configuration was handled in plan 15-01.

## Next Phase Readiness
- Server-side OIDC integration complete
- Client-side login page needs updating (plan 15-03) to redirect to /login instead of showing credential form
- E2E tests will need API key auth strategy (bypassing Logto)

## Self-Check: PASSED

All 6 modified files verified on disk. All 3 task commits verified in git log.

---
*Phase: 15-external-authentication*
*Completed: 2026-04-04*