docs(15): capture phase context
This commit is contained in:
121
.planning/phases/15-external-authentication/15-CONTEXT.md
Normal file
121
.planning/phases/15-external-authentication/15-CONTEXT.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# 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*
|
||||
@@ -0,0 +1,72 @@
|
||||
# Phase 15: External Authentication - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-04-04
|
||||
**Phase:** 15-external-authentication
|
||||
**Areas discussed:** Auth Provider Choice, Session Migration Strategy, Login Flow UX, Existing User Migration
|
||||
**Mode:** --auto --batch (all decisions auto-selected)
|
||||
|
||||
---
|
||||
|
||||
## Auth Provider Choice
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Logto | Lightweight, purpose-built auth, no Redis, first-class OIDC, simpler deployment | ✓ |
|
||||
| Authentik | Full IdP suite, more features but heavier, may need Redis, more complex setup | |
|
||||
|
||||
**User's choice:** Logto (auto-selected)
|
||||
**Notes:** Matches project's "no Redis" out-of-scope constraint. Logto is simpler to deploy and maintain for a single-app use case.
|
||||
|
||||
---
|
||||
|
||||
## Session Migration Strategy
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Replace with OIDC session management | Logto handles sessions, remove users/sessions tables from GearBox | ✓ |
|
||||
| Hybrid — keep GearBox sessions populated from OIDC | Validate OIDC on login, create local session for subsequent requests | |
|
||||
| Token-only — validate OIDC token on every request | No local sessions, every request validates against Logto | |
|
||||
|
||||
**User's choice:** Replace with OIDC session management (auto-selected)
|
||||
**Notes:** Simplifies the codebase by removing credential management from GearBox entirely. API keys remain as the programmatic access path.
|
||||
|
||||
---
|
||||
|
||||
## Login Flow UX
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Redirect to Logto login page | Standard OIDC redirect, Logto handles UI for login/register/reset | ✓ |
|
||||
| Embedded login form via Logto SDK | Use Logto's SDK to render login inline within GearBox | |
|
||||
|
||||
**User's choice:** Redirect to Logto login page (auto-selected)
|
||||
**Notes:** Standard OIDC pattern. More secure, less maintenance — Logto owns the login/registration UX.
|
||||
|
||||
---
|
||||
|
||||
## Existing User Migration
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Manual re-registration on Logto | User creates account on Logto, migration script links to GearBox data | ✓ |
|
||||
| Automated import from GearBox users table | Script creates Logto user from existing credentials | |
|
||||
|
||||
**User's choice:** Manual re-registration on Logto (auto-selected)
|
||||
**Notes:** Only one existing user — automation not worth the complexity.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Logto SDK choice
|
||||
- Token storage mechanism
|
||||
- Logto configuration and branding
|
||||
- User ID mapping strategy
|
||||
- E2E test auth approach
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
None — discussion stayed within phase scope
|
||||
Reference in New Issue
Block a user