docs(28): capture phase context

.planning/phases/28-profile-and-logto-integration/28-CONTEXT.md

@@ -0,0 +1,119 @@
+# Phase 28: Profile & Logto Integration - Context
+
+**Gathered:** 2026-04-12
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Fix the profile page to show real account information (email, member since), integrate Logto Management API for in-app account management (password change, email change, account deletion), and customize the Logto sign-in experience to match GearBox branding. Users must never be redirected to Logto's admin UI — all account management happens within GearBox.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Profile Page Content
+- **D-01:** Profile becomes a dedicated page at `/profile` (or `/account`), separate from `/settings`. Settings page keeps only app preferences (weight unit, currency, import/export, API keys).
+- **D-02:** Profile page shows: displayName, bio, avatar (editable, existing ProfileSection), plus email (from Logto, editable via Management API) and member-since date.
+- **D-03:** Keep it simple — no gear stats on the profile page. Stats belong in the collection view.
+
+### Account Management Flow
+- **D-04:** Users NEVER see or interact with Logto directly. All account management is proxied through GearBox's UI, calling Logto's Management API on the backend.
+- **D-05:** Three account management actions available: change password, change email, delete account.
+- **D-06:** Account deletion anonymizes public content (public setups, catalog contributions attributed to "deleted user") but deletes personal items, threads, and private data. User is also removed from Logto.
+
+### Claude's Discretion
+- Layout of the profile/account page — whether to use tabs (Profile | Security | Danger Zone) or sections on a single page. Claude picks what fits best.
+- Logto Management API integration details (M2M token, API endpoints).
+- Email change verification flow (Logto handles verification email, GearBox UI shows pending state).
+- Password change form design (current password + new password fields).
+- Account deletion confirmation UX (typed confirmation, cooldown period, etc.).
+
+### Login/Registration Branding
+- **D-07:** Full brand match on Logto sign-in page — custom CSS/logo matching GearBox's look. Users should not notice they've left the app.
+- **D-08:** Custom domain for Logto auth (auth.gearbox.de) if supported by the deployment.
+- **D-09:** Add Google and GitHub as social sign-in connectors in Logto.
+
+### Logto Configuration
+- **D-10:** Email verification required at signup — account not usable until verified.
+- **D-11:** Strong password policy: minimum 8 characters, mixed case, at least one number.
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Existing Auth & Profile Code
+- `src/server/routes/auth.ts` — Current auth routes (/me, /keys, /profile) using @hono/oidc-auth
+- `src/server/middleware/auth.ts` — requireAuth middleware (API key, OAuth bearer, OIDC session)
+- `src/server/services/auth.service.ts` — getOrCreateUser, API key CRUD
+- `src/server/services/profile.service.ts` — updateProfile service
+- `src/client/components/ProfileSection.tsx` — Current profile form (displayName, bio, avatar)
+- `src/client/routes/settings.tsx` — Current settings page containing ProfileSection
+
+### OIDC Integration
+- `src/server/index.ts` — OIDC middleware setup, route registration, Logto discovery check
+- `@hono/oidc-auth` — Current OIDC library (getAuth, oidcAuthMiddleware, processOAuthCallback)
+
+### Database
+- `src/db/schema.ts` — Users table (has displayName, avatarUrl, bio columns)
+
+### Prior Phase Context
+- `.planning/phases/15-external-authentication/15-CONTEXT.md` — Original Logto integration decisions
+- `.planning/phases/18-global-items-public-profiles/18-CONTEXT.md` — Profile and public setup decisions
+- `.planning/phases/24-public-access-infrastructure/24-CONTEXT.md` — Public access auth model
+
+### Logto Documentation
+- Logto Management API docs — needed for M2M token setup, user CRUD, password/email operations
+- Logto sign-in experience customization — CSS, branding, connectors
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `ProfileSection` component — form for displayName, bio, avatar. Needs to be moved to new /profile page and extended with email and account actions.
+- `useAuth` hook — returns `{ user: { id, email }, authenticated }`. Email already available from Logto session.
+- `usePublicProfile` / `useUpdateProfile` hooks — profile data fetching and mutation.
+- `apiUpload` — avatar upload to MinIO (already working).
+- API key management section — stays in Settings, extracted from profile.
+
+### Established Patterns
+- Service DI (db, userId) — new Logto Management API service follows same pattern
+- Zod validation schemas in shared/schemas.ts
+- TanStack Router file-based routing — add /profile route file
+- TanStack Query hooks for data fetching and mutation
+
+### Integration Points
+- `src/client/routes/` — New `/profile` route file (auto-registered by TanStack Router)
+- `src/server/routes/auth.ts` — Add password change, email change, account deletion endpoints
+- `src/server/index.ts` — Register any new route groups
+- Logto Management API — new backend service for M2M communication
+- Docker Compose — may need Logto M2M application configuration
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Users should NEVER be aware that Logto exists. The login page is the only place Logto's UI appears, and it must be fully branded to look like GearBox.
+- Account deletion must preserve public content (setups, catalog contributions) attributed to "deleted user" — important for platform data integrity.
+- The profile/account page is separate from Settings. Settings is for app preferences only.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 28-profile-and-logto-integration*
+*Context gathered: 2026-04-12*