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

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

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

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

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

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 28-profile-and-logto-integration Context gathered: 2026-04-12