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

Phase 15: External Authentication - Context

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

## 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).

## 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)

<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>

## Specific Ideas

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

## Deferred Ideas

None — discussion stayed within phase scope

---

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