docs(28): capture phase context
This commit is contained in:
119
.planning/phases/28-profile-and-logto-integration/28-CONTEXT.md
Normal file
119
.planning/phases/28-profile-and-logto-integration/28-CONTEXT.md
Normal file
@@ -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*
|
||||
@@ -0,0 +1,119 @@
|
||||
# Phase 28: Profile & Logto Integration - 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-12
|
||||
**Phase:** 28-profile-and-logto-integration
|
||||
**Areas discussed:** Profile page content, Account management flow, Login/registration branding, Logto configuration
|
||||
|
||||
---
|
||||
|
||||
## Profile Page Content
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Account info + stats | Show email, member since, gear stats (item count, setup count, collection weight) | |
|
||||
| Account info only | Add email and member-since date from Logto. Keep it simple. | ✓ |
|
||||
| You decide | Claude picks what makes sense | |
|
||||
|
||||
**User's choice:** Account info only
|
||||
**Notes:** Stats belong on the collection page, not the profile.
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Keep in Settings | Profile section stays at top of /settings | |
|
||||
| Separate /profile page | Dedicated profile page with its own nav entry | ✓ |
|
||||
| You decide | Claude picks based on content | |
|
||||
|
||||
**User's choice:** Separate /profile page
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| View only in GearBox | Email read-only, changes in Logto | |
|
||||
| Editable via Logto API | Email change initiated from GearBox | ✓ |
|
||||
|
||||
**User's choice:** Editable via Logto Management API
|
||||
**Notes:** "I never want them going to Logto, it just handles auth etc." — Strong preference that Logto is invisible to users.
|
||||
|
||||
---
|
||||
|
||||
## Account Management Flow
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Full account management | Change email, password, delete, manage sessions | |
|
||||
| Essentials only | Change password and view email only | |
|
||||
| Password + email + delete | The three things users actually need | ✓ |
|
||||
|
||||
**User's choice:** Password + email + delete
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Section on profile page | Password change as collapsible section | |
|
||||
| Separate security section | Tabs: Profile / Security / Danger Zone | |
|
||||
| You decide | Claude picks the layout | ✓ |
|
||||
|
||||
**User's choice:** You decide (Claude's discretion)
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Full delete | Delete everything — items, setups, threads, profile. Remove from Logto. | |
|
||||
| Anonymize, keep content | Public setups/contributions stay (attributed to "deleted user"). Personal data deleted. | ✓ |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** Anonymize, keep content
|
||||
|
||||
---
|
||||
|
||||
## Login/Registration Branding
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Full brand match | Custom CSS/logo on Logto, custom domain, seamless experience | ✓ |
|
||||
| Logo + colors only | GearBox logo and primary colors, keep Logto default layout | |
|
||||
| Skip branding for now | Focus on functionality, brand later | |
|
||||
|
||||
**User's choice:** Full brand match
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Google + GitHub | Both social login providers | ✓ |
|
||||
| Google only | Just Google for widest reach | |
|
||||
| Not now | Email + password only for launch | |
|
||||
|
||||
**User's choice:** Google + GitHub
|
||||
|
||||
---
|
||||
|
||||
## Logto Configuration
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Required at signup | Email must be verified before account is usable | ✓ |
|
||||
| Required within 7 days | Can start using immediately, verify within a week | |
|
||||
| Optional | Available but not required | |
|
||||
|
||||
**User's choice:** Required at signup
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Strong (8+ chars, mixed case, number) | Standard security policy | ✓ |
|
||||
| Minimum only (8+ chars) | Just length, no complexity | |
|
||||
| You decide | Claude picks reasonable defaults | |
|
||||
|
||||
**User's choice:** Strong password policy
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Profile/account page layout (tabs vs sections)
|
||||
- Logto Management API integration details (M2M token setup)
|
||||
- Email change verification flow UX
|
||||
- Password change form design
|
||||
- Account deletion confirmation UX
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
None — discussion stayed within phase scope
|
||||
Reference in New Issue
Block a user