GearBox/.planning/phases/15-external-authentication/15-CONTEXT.md

# Phase 15: External Authentication - Context

**Gathered:** 2026-04-04
**Status:** Ready for planning

<domain>
## Phase Boundary

Replace GearBox's built-in username/password authentication with Logto, a self-hosted open-source OIDC provider. Users register and log in through Logto. GearBox validates OIDC tokens instead of managing its own user credentials and sessions. API keys remain functional for programmatic access (MCP, scripts).

</domain>

<decisions>
## Implementation Decisions

### Auth Provider Choice
- **D-01:** Use **Logto** as the external auth provider (not Authentik). Logto is purpose-built for auth, lighter-weight, no Redis required, first-class OIDC support, simpler deployment.

### Session Strategy
- **D-02:** Replace GearBox's cookie-session system with OIDC-based authentication. Logto manages user sessions. GearBox validates tokens on each request.
- **D-03:** Remove the `users` and `sessions` tables from GearBox schema — user identity comes from Logto. Keep `apiKeys` table for programmatic access.
- **D-04:** The `requireAuth` middleware validates either an API key (X-API-Key header) OR an OIDC token/session from Logto. Both paths resolve to a user identity.

### Login Flow
- **D-05:** Standard OIDC redirect flow. User clicks "Login" on GearBox → redirected to Logto login page → authenticated → redirected back with authorization code → GearBox exchanges code for tokens.
- **D-06:** Registration happens on Logto's side — GearBox does not have its own registration form. Logto handles password reset, email verification, etc.
- **D-07:** The existing `/login` route becomes a redirect trigger to Logto, not a credential form.

### Existing User Migration
- **D-08:** Single user re-registers manually on Logto (one-time operation). A migration step links the Logto user ID to existing GearBox data.
- **D-09:** No automated user import — only one existing user.

### API Key Continuity
- **D-10:** API keys continue to work exactly as they do now. The `apiKeys` table remains in GearBox's schema.
- **D-11:** API key management UI stays in Settings. Creating/deleting keys requires an authenticated OIDC session.

### MCP OAuth Coexistence
- **D-12:** The existing MCP OAuth 2.1 + PKCE flow (for Claude mobile/web) coexists with Logto. MCP OAuth uses GearBox's own oauth tables; user-facing auth uses Logto. These are separate auth domains.

### Docker Compose
- **D-13:** Logto runs as a service in docker-compose alongside Postgres. Logto uses the same Postgres instance (separate database) or its own.
- **D-14:** Development docker-compose includes Logto for local auth testing.

### Claude's Discretion
- Logto SDK choice (official `@logto/node` vs generic OIDC client library)
- Token storage mechanism (httpOnly cookie with OIDC tokens, or server-side session backed by Logto)
- Logto configuration details (sign-in experience, branding, connector setup)
- Whether to use Logto's user ID directly as the foreign key in GearBox tables or maintain a mapping table
- E2E test authentication strategy (likely API keys per AUTH-05, bypassing Logto)

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Existing Auth Code (to be replaced)
- `src/server/routes/auth.ts` — Current login/logout/setup/password/keys routes
- `src/server/services/auth.service.ts` — Current user/session/API key management
- `src/server/middleware/auth.ts` — Current requireAuth middleware (API key + cookie session)
- `src/client/routes/login.tsx` — Current login page UI

### Existing MCP OAuth (to preserve)
- `src/server/routes/oauth.ts` — MCP OAuth 2.1 routes (keep separate from Logto)
- `src/server/services/oauth.service.ts` — MCP OAuth service
- `docs/superpowers/specs/2026-04-04-mcp-oauth-design.md` — MCP OAuth design spec

### Database Schema
- `src/db/schema.ts` — Current schema with users, sessions, apiKeys, oauthClients/Codes/Tokens tables

### Docker
- `docker-compose.yml` — Production compose (add Logto service)
- `docker-compose.dev.yml` — Dev compose (add Logto service)

### Requirements
- `.planning/REQUIREMENTS.md` — AUTH-01 through AUTH-05 requirements

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `requireAuth` middleware pattern — will be refactored but same middleware slot in Hono
- API key verification logic (`verifyApiKey`) — keeps working unchanged
- `apiKeys` table and CRUD — no changes needed
- MCP OAuth routes and service — preserved as-is, separate auth domain

### Established Patterns
- **Middleware DI**: `requireAuth` gets `db` from Hono context — same pattern continues
- **Service layer**: Auth service functions take `db` as first param — new OIDC validation functions follow same pattern
- **Cookie handling**: `hono/cookie` helpers for set/get/delete — may shift to OIDC token cookies

### Integration Points
- `src/server/middleware/auth.ts` — Primary integration point for OIDC token validation
- `src/server/index.ts` — Route registration (remove old auth routes, add OIDC callback route)
- `src/client/routes/login.tsx` — Replace credential form with Logto redirect
- `src/client/hooks/` — Auth state hooks (useAuth, etc.) need OIDC awareness
- `docker-compose.yml` / `docker-compose.dev.yml` — Add Logto service

</code_context>

<specifics>
## Specific Ideas

No specific requirements — open to standard approaches for Logto OIDC integration with Hono.

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 15-external-authentication*
*Context gathered: 2026-04-04*