@hilbras/keystone 2.5.0 → 3.0.0

package/docs/adrs/002-versioned-event-bus.md

@@ -0,0 +1,30 @@
+# ADR 002: Versioned Event Bus
+
+## Status
+
+Accepted
+
+## Context
+
+Keystone emits events for audit logging, webhooks, analytics, anomaly detection, and workflow triggers. Without versioning, a change to an event payload could break external subscribers or downstream internal consumers.
+
+## Decision
+
+Every event emitted by the event bus includes a monotonic version number:
+
+```json
+{
+  "type": "user.login",
+  "version": 1,
+  "timestamp": "...",
+  "payload": {}
+}
+```
+
+Subscribers are expected to handle versions they understand and ignore or reject unknown versions.
+
+## Consequences
+
+- Events can evolve without breaking existing integrations.
+- Consumers must document the versions they support.
+- Event producers must increment the version for backward-incompatible payload changes.

package/docs/adrs/003-bullmq-for-background-work.md

@@ -0,0 +1,20 @@
+# ADR 003: BullMQ for Background Work
+
+## Status
+
+Accepted
+
+## Context
+
+Sending emails, delivering webhooks, running analytics, and executing workflow actions synchronously would slow API responses and reduce reliability. The project started with an in-process event bus for simplicity.
+
+## Decision
+
+Introduce a BullMQ-backed queue as the production default when Redis is available, falling back to an in-process queue for local development. The queue abstraction (`src/services/queue/types.ts`) keeps core code independent of BullMQ specifics.
+
+## Consequences
+
+- API responses stay fast.
+- Failed jobs are retried with exponential backoff.
+- Redis becomes a runtime dependency for production queues.
+- Local development can still run without Redis.

package/docs/adrs/004-argon2id-password-hashing.md

@@ -0,0 +1,19 @@
+# ADR 004: Argon2id Password Hashing
+
+## Status
+
+Accepted
+
+## Context
+
+Keystone originally hashed passwords with scrypt. While scrypt is still secure, argon2id is the current OWASP recommendation and provides stronger resistance to GPU attacks with simpler parameter tuning.
+
+## Decision
+
+New password hashes use argon2id with parameters `m=65536, t=3, p=4`. Existing scrypt hashes remain verifiable through a legacy verifier so no user passwords are invalidated.
+
+## Consequences
+
+- New hashes follow modern best practices.
+- No password migration is required.
+- The project gains a native dependency (`argon2`) that must compile on target platforms.

package/docs/plans/KEYSTONE_IMPROVEMENT_PLAN.md

@@ -0,0 +1,334 @@
+# Keystone Comprehensive Improvement Plan
+
+**Goal:** Make Hilbras Keystone the simplest identity platform for beginners and the most capable platform for advanced users — while staying secure, fast, and mobile-friendly.
+
+**Principles:**
+- *Progressive disclosure* — show only what is needed, never hide the path to more control.
+- *Secure by default* — every feature ships with safe defaults.
+- *Mobile-first* — every screen must be usable on a phone.
+- *API-first* — every UI action is backed by a documented, automatable API.
+
+---
+
+## 1. Mobile Responsiveness & Accessibility
+
+### 1.1 Complete responsive audit
+Audit every panel and fix overflow, truncation, and unreachable controls on screens < 640 px.
+
+Priority files:
+- `frontend/src/components/ApplicationsPanel.tsx`
+- `frontend/src/components/OrganizationsPanel.tsx`
+- `frontend/src/components/EnterpriseSsoPanel.tsx`
+- `frontend/src/components/WorkflowPanel.tsx`
+- `frontend/src/components/BillingPanel.tsx`
+- `frontend/src/components/ui/DataTable.tsx`
+- `frontend/src/components/wizard/SimpleWizard.tsx`
+- `frontend/src/components/wizard/Wizard.tsx`
+
+Concrete rules:
+- All button groups use `flex-col sm:flex-row` and `w-full sm:w-auto`.
+- All tables become horizontal-scroll cards on mobile or switch to a stacked row layout.
+- Forms use full-width inputs with labels above.
+- Modals/dialogs become bottom sheets on mobile.
+
+### 1.2 Mobile navigation redesign
+Replace the desktop sidebar with a responsive pattern:
+- Desktop: collapsible sidebar.
+- Tablet: icon-only rail.
+- Mobile: bottom tab bar for top-level sections plus a hamburger menu for the rest.
+
+Files to update:
+- `frontend/src/components/layout/Sidebar.tsx`
+- `frontend/src/components/layout/MobileNav.tsx`
+- `frontend/src/components/layout/AppShell.tsx`
+
+### 1.3 Touch-friendly components
+- Minimum tap target 44 × 44 px.
+- Larger checkboxes, toggles, and select controls on mobile.
+- Pull-to-refresh on data tables.
+- Swipe gestures on cards (e.g., delete with confirmation).
+
+### 1.4 Accessibility (a11y)
+- Add `aria-label`, `aria-describedby`, and `role` attributes to all icon buttons.
+- Ensure focus order is logical in modals and wizards.
+- Add keyboard shortcuts documentation panel.
+- Run automated a11y checks with `axe-core` in CI.
+- Support reduced-motion preferences.
+
+---
+
+## 2. Security Hardening
+
+### 2.1 Session security
+- Enforce `SameSite=strict` for cookies in production unless cross-origin login is explicitly enabled.
+- Add session binding to IP + user-agent fingerprint with optional strict mode.
+- Implement idle timeout and absolute session lifetime with configurable defaults (30 min idle, 7 days absolute).
+- Add concurrent session limits per user.
+
+### 2.2 Authentication hardening
+- Enable password breach detection via Have I Been Pwned (or self-hosted `hibp` service) by default.
+- Add account lockout after failed attempts with exponential backoff.
+- Require email verification before owner/admin actions.
+- Add device trust: prompt for MFA when a new device is detected.
+
+### 2.3 API and token security
+- Rotate JWT signing keys automatically on a schedule (daily check, rotate if older than 90 days).
+- Add key version metadata to the JWKS endpoint.
+- Enforce strict audience (`aud`) and issuer (`iss`) validation.
+- Scope API keys to organizations and applications with fine-grained permissions.
+- Add API key usage quotas and expiration warnings.
+- Implement signed webhook payloads so consumers can verify authenticity.
+
+### 2.4 Secrets provider hardening
+- Default to `EnvironmentSecretsProvider` in production instead of `DatabaseSecretsProvider`.
+- Add built-in providers for AWS KMS, HashiCorp Vault, Azure Key Vault, and Google Cloud KMS.
+- Encrypt all secrets at rest with AES-256-GCM.
+- Audit every secret read/write/rotate event.
+
+### 2.5 Audit and compliance
+- Make audit logs tamper-evident with a hash chain or append-only stream.
+- Add export formats: CSV, JSON, NDJSON, and CEF for SIEMs.
+- Add retention policies and automatic archiving.
+- Add GDPR-style data export and deletion workflows.
+
+---
+
+## 3. Backend Architecture Improvements
+
+### 3.1 Domain service consolidation
+Create explicit orchestration services to reduce coupling:
+- `AuthenticationApplicationService`
+- `AuthorizationApplicationService`
+- `IdentityApplicationService`
+- `OrganizationApplicationService`
+- `SetupApplicationService`
+
+Move ad-hoc orchestration out of route files and thin services into these application services.
+
+### 3.2 Background job queue productionization
+- Default to BullMQ when Redis is available; keep in-process queue for local dev.
+- Add job retries with exponential backoff and dead-letter queues.
+- Add a jobs dashboard UI to inspect/retry failed jobs.
+- Queue categories: emails, webhooks, analytics, workflows, exports.
+
+### 3.3 Plugin architecture GA
+- Stabilize the plugin manifest format.
+- Add hot-reload for plugins in development.
+- Add plugin marketplace UI (list installed, enable/disable, configure).
+- Provide official plugin templates for identity providers, email providers, and workflow steps.
+
+### 3.4 Configuration management
+- Complete the `ConfigStore` abstraction (`EnvFileConfigStore`, `JsonConfigStore`, `KubernetesSecretConfigStore`, `VaultConfigStore`).
+- Add configuration profiles: Development, Production, Docker, Docker Compose, Kubernetes, High Availability.
+- Add configuration validation with actionable error messages.
+- Add dry-run mode and automatic backup before writes.
+
+### 3.5 Database and migrations
+- Add migration status endpoint and UI.
+- Add zero-downtime migration strategy documentation.
+- Add connection pooling metrics.
+- Support read replicas for analytics queries.
+
+### 3.6 Observability
+- Add structured health checks with dependency details.
+- Add OpenTelemetry tracing (optional, disabled by default).
+- Add metrics endpoint (`/metrics`) for Prometheus.
+- Add structured logging conventions across all services.
+
+---
+
+## 4. New User-Facing Features
+
+### 4.1 Smart Setup Wizard 2.0
+Make first-run setup fully UI-driven with no file editing required.
+
+Steps:
+1. **Welcome & profile** — pick environment, auto-fill defaults.
+2. **Dependencies** — detect or install PostgreSQL/Redis via Docker, test connections.
+3. **URLs & security** — suggest public URLs, generate secrets, set CORS origins.
+4. **Owner account** — create first admin with password strength meter.
+5. **First application** — ask for project URL/framework, auto-create org + app.
+6. **Done** — show one-line drop-in script and "Test login" button.
+
+Add to wizard:
+- Configuration change summary before apply.
+- Automatic configuration backup.
+- Dry-run validation.
+- Rollback on failure.
+- Final diagnostics report.
+
+### 4.2 One-click project connection
+The Connect Project panel should generate a single copy-paste script for any framework.
+
+Supported frameworks in simple view:
+- HTML/Vanilla JS
+- React / Next.js
+- Vue / Nuxt
+- Angular
+- Svelte / SvelteKit
+- Django
+- Ruby on Rails
+- Go templates
+
+Each template pre-fills:
+- Correct redirect URI
+- Allowed origin
+- Recommended scopes
+- Framework-specific initialization code
+
+Add "Test login" button that opens a popup and reports success/failure with clear fixes.
+
+### 4.3 Identity provider presets
+Guided setup for:
+- Google
+- GitHub
+- Microsoft / Azure AD
+- Apple
+- Okta
+- Keycloak
+- Zitadel
+- Custom OIDC
+
+Each preset shows:
+- Exact callback URL to paste in the provider
+- Link to official provider docs
+- Field-by-field guidance
+- One-click enable/disable
+
+### 4.4 Role and permission templates
+Default roles:
+- Owner
+- Admin
+- Editor
+- Viewer
+- Member
+
+Each template ships with sensible permissions and is editable. Allow cloning custom roles.
+
+### 4.5 Organization onboarding flow
+When a new organization is created:
+- Optional wizard to invite members.
+- Default application created automatically.
+- Quick-start checklist per organization.
+
+### 4.6 User self-service portal
+Allow end users to:
+- View and update their profile.
+- Change password.
+- Manage MFA (TOTP, WebAuthn, backup codes).
+- View active sessions and revoke them.
+- Download their data.
+- Request account deletion.
+
+### 4.7 Security dashboard
+A dedicated panel showing:
+- Recent login activity map.
+- Failed login attempts.
+- Active sessions.
+- MFA adoption rate.
+- Password strength distribution.
+- Recommended security actions.
+
+### 4.8 Workflow & automation engine improvements
+- Visual workflow builder (drag-and-drop nodes).
+- Pre-built templates:
+  - Post-signup email + default role + organization + workspace.
+  - Failed login alert + temporary lockout.
+  - New member invite sequence.
+- Trigger types: events, schedules, webhooks.
+- Action types: email, webhook, role change, notification, custom script.
+
+### 4.9 Billing and plans (if enabled)
+- Self-service plan selection.
+- Usage dashboards (MAU, API calls, emails, SMS).
+- Invoice history.
+- Trial reminders.
+
+---
+
+## 5. Developer Experience
+
+### 5.1 SDK improvements
+- Publish the browser SDK to npm as `@hilbras/keystone-sdk`.
+- Add React/Vue/Angular wrapper hooks.
+- Add TypeScript types for all public APIs.
+- Add server-side SDKs (Node.js, Python, Go) with examples.
+
+### 5.2 Documentation
+- Auto-generated OpenAPI docs from Fastify routes.
+- Interactive API explorer in the admin UI.
+- Step-by-step integration guides per framework.
+- Video walkthroughs for first-time setup.
+
+### 5.3 Local development
+- `docker compose up` should start the full stack including PostgreSQL, Redis, and Keystone.
+- `npm run dev` starts backend + frontend with hot reload.
+- Add seed scripts for demo data.
+- Add Playwright E2E tests for critical flows.
+
+### 5.4 CLI improvements
+- `keystone setup` — interactive first-run setup.
+- `keystone config validate` — validate current configuration.
+- `keystone db migrate` / `keystone db rollback`.
+- `keystone plugin install <name>`.
+- `keystone status` — health and diagnostics.
+
+---
+
+## 6. Implementation Phases
+
+### Phase 1 — Foundation (2 weeks)
+- Complete mobile responsive audit and fixes.
+- Add hash-based routing improvements and URL persistence.
+- Stabilize Simple/Advanced mode across dashboard and wizard.
+- Add a11y basics and touch-friendly components.
+
+### Phase 2 — Security & Backend (2 weeks)
+- Harden sessions, cookies, and token rotation.
+- Implement secrets provider backends (KMS, Vault, Azure Key Vault).
+- Add signed webhooks and API key scopes.
+- Add structured metrics and health endpoints.
+
+### Phase 3 — Setup & Onboarding (2 weeks)
+- Rewrite setup wizard with dependency auto-detection.
+- Add configuration profiles, dry-run, backup, and rollback.
+- Add onboarding checklist and first-app auto-creation.
+- Add final diagnostics report.
+
+### Phase 4 — Connect & Templates (2 weeks)
+- Build framework selector in Connect Project panel.
+- Add identity provider presets.
+- Add role templates.
+- Add "Test login" flow.
+
+### Phase 5 — Self-Service & Workflows (2 weeks)
+- Build user self-service portal.
+- Add security dashboard.
+- Add visual workflow builder and templates.
+- Add organization onboarding flow.
+
+### Phase 6 — Scale & Polish (2 weeks)
+- Productionize background queue with BullMQ dashboard.
+- Add plugin marketplace and templates.
+- Performance optimization pass.
+- E2E test coverage for critical paths.
+
+---
+
+## 7. Success Metrics
+
+- **Onboarding:** A new user completes setup and connects a website in under 10 minutes without reading docs.
+- **Mobile:** All dashboard panels are usable on a 375 px wide screen without horizontal overflow.
+- **Security:** 100% of security-relevant actions emit versioned audit events; secrets are never logged.
+- **Reliability:** Background jobs have < 0.1% failure rate; failed jobs are visible and retryable.
+- **Adoption:** 80% of new users enable at least one login method within the first session.
+- **Developer satisfaction:** Integration requires one copy-paste script for common frameworks.
+
+---
+
+## Notes
+
+- Keep all existing public APIs backward-compatible.
+- Introduce feature flags for every major UI change so they can be rolled out gradually.
+- Maintain dark mode and theme consistency.
+- Update `docs/SECURITY.md`, `docs/PERFORMANCE.md`, and `docs/ARCHITECTURE.md` as features land.

package/docs/plans/UI_SIMPLIFICATION_IMPROVEMENT_PLAN.md

@@ -0,0 +1,271 @@
+# Keystone UI Simplification Improvement Plan
+
+**Goal:** Make Keystone feel simple enough for a first-time user, while keeping every advanced capability one click away for power users.
+
+**Principle:** *Progressive disclosure* — show only what is needed for the current task, but never hide the path to more control.
+
+---
+
+## 1. Unified "Simple / Advanced" Mode
+
+Introduce a global toggle in the dashboard header and setup wizard.
+
+- **Simple mode:**
+  - Hides optional fields.
+  - Uses plain-language labels ("App name" instead of "Client ID").
+  - Shows guided steps with defaults selected.
+  - Surfaces only the most common actions.
+- **Advanced mode:**
+  - Reveals all fields, raw IDs, scopes, claims, policies, webhooks.
+  - Shows JSON payloads, raw event logs, and migration details.
+  - Allows direct editing of configuration files.
+
+**Implementation:**
+- Store preference in `localStorage` (`keystone:ui-mode`).
+- Wrap advanced sections with `<Advanced>` component that reads the preference.
+- Default to **Simple** for the first login, prompt to switch when an action needs advanced fields.
+
+---
+
+## 2. Simplified Navigation & Home Dashboard
+
+Replace the current sidebar-heavy layout with a goal-oriented home screen.
+
+### Home cards (one-click actions)
+
+1. **Add login to my website** → opens Connect Project panel.
+2. **Create an organization** → opens a one-field modal.
+3. **Invite a team member** → opens invite modal.
+4. **View active users** → opens Users panel with default filter.
+5. **Enable Google sign-in** → opens Identity Providers with Google pre-selected.
+
+### Navigation redesign
+
+- Collapse secondary items into grouped menus:
+  - **Home**
+  - **Authentication** (users, apps, identity providers)
+  - **Access Control** (roles, permissions, organizations)
+  - **Platform** (audit, workflows, secrets, plugins, settings)
+- Add a global search bar (Cmd+K) to jump to any page, user, app, or setting.
+
+---
+
+## 3. Contextual Help & Inline Education
+
+Every screen should teach without forcing the user to read docs.
+
+- **Tooltips:** Explain every field on hover/focus. Examples:
+  - "Redirect URI" → "Where users land after signing in with Google."
+  - "Allowed Origins" → "Websites allowed to talk to Keystone from the browser."
+- **Inline examples:** Show a live example value next to each input.
+- **"Why do I need this?"** expandable help blocks for complex sections.
+- **Toast guidance:** After creating an app, show: "Next, copy the drop-in script to your website."
+
+---
+
+## 4. Setup Wizard 2.0 — Guided First Run
+
+The current setup wizard should become a clear, linear, 4-step flow.
+
+### Step 1: Welcome
+- One sentence value prop.
+- "Start with Docker (recommended)" vs "I already have PostgreSQL/Redis".
+- Profile selector (Development, Production, Docker Compose).
+
+### Step 2: Dependencies
+- Auto-detect Docker, PostgreSQL, Redis.
+- Big green checkmarks when each is ready.
+- One "Start services for me" button if Docker is available.
+- Plain error messages with a "Fix it for me" suggestion when possible.
+
+### Step 3: Owner Account
+- Email + password + confirm password.
+- Password strength meter.
+- Optional: "Generate a strong password for me".
+
+### Step 4: First Application
+- Ask for a website name and URL.
+- Auto-create the organization and application behind the scenes.
+- Generate the drop-in script immediately.
+- Final screen: "Your setup is complete. Here is your one-line install code."
+
+---
+
+## 5. Smart Defaults & Wizards for Complex Features
+
+Instead of empty forms, offer presets and guided creation.
+
+### Application templates
+- **Single-page app (React/Vue/Angular)**
+- **Server-rendered app (Next.js/Nuxt/Django)**
+- **Mobile app**
+- **Machine-to-machine API**
+
+Each template pre-fills:
+- Redirect URIs
+- Allowed origins
+- Token lifetime
+- Recommended scopes
+
+### Identity provider presets
+- Google
+- GitHub
+- Microsoft
+- Apple
+- Custom OIDC
+
+Each preset shows:
+- Link to provider docs
+- Exact callback URL to paste
+- Fields needed (Client ID, Client Secret)
+
+### Role templates
+- **Admin** — full access
+- **Editor** — read + write
+- **Viewer** — read only
+- **Member** — default user
+
+---
+
+## 6. Connect Project Panel — Beginner Path
+
+The Connect Project panel should have two views:
+
+### Simple view (default)
+- Ask: "What framework are you using?" (HTML, React, Vue, Next.js, etc.)
+- Ask: "What is your website URL?"
+- Show exactly one code block to copy.
+- Show a "Test login" button that opens a popup to verify the integration.
+- Hide client IDs, callback URLs, and allowed origins unless the user expands them.
+
+### Advanced view
+- Full control over all script attributes.
+- Custom callback paths.
+- Manual origin/redirect URI management.
+- Raw SDK API reference.
+
+---
+
+## 7. Plain-Language Error Handling
+
+Every error in the UI should answer three questions:
+1. What went wrong?
+2. Why did it happen?
+3. What should I do now?
+
+### Examples
+
+| Technical error | Plain message | Action |
+|---|---|---|
+| `401 Unauthorized` | "You are not signed in." | "Sign in" button |
+| `Invalid or missing setup token` | "Setup token is missing or has expired." | "Show token from server logs" |
+| `relation "secrets" does not exist` | "Database is not ready. Run migrations first." | "Run migrations" button |
+| CORS error | "This website is not allowed to talk to Keystone." | "Add origin to Allowed Origins" |
+
+---
+
+## 8. Live Status & Health Indicators
+
+Add a persistent status bar or footer showing:
+- Database connection: ✅ / ❌
+- Redis connection: ✅ / ❌
+- Setup complete: ✅ / ❌
+- API reachable: ✅ / ❌
+
+Clicking an indicator opens diagnostics with a "Fix issue" suggestion.
+
+---
+
+## 9. Onboarding Checklist
+
+After first login, show a dismissible checklist:
+
+- [ ] Create an organization
+- [ ] Register an application
+- [ ] Connect my website
+- [ ] Enable at least one login method
+- [ ] Invite a team member
+- [ ] Review audit logs
+
+Each item links directly to the action. Progress gives a sense of accomplishment.
+
+---
+
+## 10. Mobile-First Responsive Design
+
+The dashboard should work well on tablets and phones.
+
+- Collapsible sidebar into a bottom sheet or hamburger menu.
+- Stacked cards on small screens.
+- Touch-friendly buttons and inputs.
+- Reduce padding and font size on mobile (already partially done).
+
+---
+
+## 11. Consistent Design Tokens & Animations
+
+Polish the visual experience:
+- Consistent spacing scale (4px grid).
+- Subtle entrance animations for cards and modals.
+- Loading skeletons instead of spinners where appropriate.
+- Hover states on all interactive elements.
+- Empty states with illustrations and clear next steps.
+
+---
+
+## 12. Feedback & Confirmation Flows
+
+Any destructive or important action should be clear.
+
+- Deleting an app → confirmation modal with the app name typed.
+- Creating credentials → show a one-time copy dialog.
+- Saving settings → toast confirmation.
+- Long operations → progress indicator.
+
+---
+
+## Implementation Phases
+
+### Phase 1 — Foundation (1 week)
+- Add Simple/Advanced toggle.
+- Redesign navigation and home dashboard.
+- Add global search (Cmd+K).
+
+### Phase 2 — Setup Wizard (1 week)
+- Rewrite setup wizard as 4-step guided flow.
+- Add dependency auto-detection and "Fix it" helpers.
+- Add onboarding checklist.
+
+### Phase 3 — Contextual Help (1 week)
+- Add tooltips and inline examples everywhere.
+- Create reusable `<FieldHelp>` component.
+- Rewrite error messages into plain language.
+
+### Phase 4 — Smart Defaults (1 week)
+- Add application templates.
+- Add identity provider presets.
+- Add role templates.
+- Simplify Connect Project panel with framework selector.
+
+### Phase 5 — Polish (1 week)
+- Mobile responsiveness pass.
+- Animations and transitions.
+- Empty states and loading skeletons.
+- User testing with beginners.
+
+---
+
+## Success Metrics
+
+- A new user can complete setup in under 10 minutes without reading docs.
+- First login-to-connected-website flow takes under 5 minutes.
+- Support questions about "what is a redirect URI" drop by 50%.
+- Advanced users report no loss of control.
+
+---
+
+## Notes
+
+- Keep all existing APIs unchanged. These are frontend-only improvements.
+- Maintain dark mode support throughout.
+- Add feature flags for wizard steps so they can be iterated safely.