From 631fe3e6b54e4b18022f4aa42ec64eff23f21482 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Sun, 12 Apr 2026 17:32:58 +0200 Subject: [PATCH] docs(28): capture phase context --- .../28-CONTEXT.md | 119 ++++++++++++++++++ .../28-DISCUSSION-LOG.md | 119 ++++++++++++++++++ 2 files changed, 238 insertions(+) create mode 100644 .planning/phases/28-profile-and-logto-integration/28-CONTEXT.md create mode 100644 .planning/phases/28-profile-and-logto-integration/28-DISCUSSION-LOG.md diff --git a/.planning/phases/28-profile-and-logto-integration/28-CONTEXT.md b/.planning/phases/28-profile-and-logto-integration/28-CONTEXT.md new file mode 100644 index 0000000..befc044 --- /dev/null +++ b/.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 + + +## 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 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 + + + + +## 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 + + + + +## 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* diff --git a/.planning/phases/28-profile-and-logto-integration/28-DISCUSSION-LOG.md b/.planning/phases/28-profile-and-logto-integration/28-DISCUSSION-LOG.md new file mode 100644 index 0000000..4720860 --- /dev/null +++ b/.planning/phases/28-profile-and-logto-integration/28-DISCUSSION-LOG.md @@ -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