GearBox/.planning/milestones/v2.2-phases/28-profile-and-logto-integration/28-CONTEXT.md

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