stack/docs/PRD-MS21.md

PRD: MS21 — Multi-Tenant Platform, RBAC Enforcement, and Data Migration

Metadata

• Owner: Jason Woltje
• Orchestrator: Jarvis (OpenClaw)
• Date: 2026-02-28
• Status: in-progress
• Version: 0.0.21

Problem Statement

Mosaic Stack is a single-user deployment. The Workspace, Team, WorkspaceMember, and RBAC infrastructure exist in the schema and codebase (PermissionGuard, WorkspaceGuard, roles: OWNER/ADMIN/MEMBER/GUEST), but there is no admin UI for managing users, workspaces, or teams. There is no invitation flow, no user management page, and no break-glass authentication mechanism for emergency access without OIDC. Additionally, the platform has no real operational data — jarvis-brain contains 106 projects and 95 tasks that need migrating into Mosaic Stack to make the dashboard, kanban, and project pages useful.

Objectives

1. Build admin UI for user management (list, invite, deactivate, assign roles)
2. Build workspace management UI (create, configure, manage members)
3. Build team management UI (create teams within workspaces, assign members)
4. Implement user invitation flow (email or link-based)
5. Implement break-glass local authentication (bypass OIDC for emergency access)
6. Enforce RBAC across all UI surfaces (show/hide based on role)
7. Build admin Settings pages for workspace and platform configuration
8. Migrate jarvis-brain data (95 tasks, 106 projects) into Mosaic Stack PostgreSQL
9. Build data import API endpoint for bulk task/project creation

Completed Work

Existing Infrastructure (Already Built)

Component	Status	Location
Prisma models: User, Workspace, WorkspaceMember, Team, TeamMember	Complete	apps/api/prisma/schema.prisma
WorkspaceMemberRole enum (OWNER, ADMIN, MEMBER, GUEST)	Complete	schema.prisma
TeamMemberRole enum (OWNER, ADMIN, MEMBER)	Complete	schema.prisma
PermissionGuard with role hierarchy	Complete	apps/api/src/common/guards/permission.guard.ts
Permission decorator (@RequirePermission)	Complete	apps/api/src/common/decorators/permissions.decorator.ts
Permission enum (WORKSPACE_OWNER, ADMIN, MEMBER, ANY)	Complete	permissions.decorator.ts
WorkspaceGuard	Complete	apps/api/src/common/guards/workspace.guard.ts
RBAC applied to 18+ controllers	Complete	All resource controllers
Workspaces CRUD API	Complete	apps/api/src/workspaces/
BetterAuth + Authentik OIDC	Complete	apps/api/src/auth/
AdminGuard	Complete	apps/api/src/auth/guards/admin.guard.ts

Scope

In Scope (MS21)

S1: Admin API Endpoints (Backend)

1. GET /api/admin/users — List all users with workspace memberships and roles
2. POST /api/admin/users/invite — Generate invitation (email or link)
3. PATCH /api/admin/users/:id — Update user metadata (deactivate, change global role)
4. DELETE /api/admin/users/:id — Deactivate user (soft delete, preserve data)
5. POST /api/admin/workspaces — Create workspace with owner assignment
6. PATCH /api/admin/workspaces/:id — Update workspace settings
7. POST /api/workspaces/:id/members — Add member to workspace with role
8. PATCH /api/workspaces/:id/members/:userId — Change member role
9. DELETE /api/workspaces/:id/members/:userId — Remove member from workspace
10. POST /api/workspaces/:id/teams — Create team within workspace
11. POST /api/workspaces/:id/teams/:teamId/members — Add member to team
12. DELETE /api/workspaces/:id/teams/:teamId/members/:userId — Remove from team
13. POST /api/import/tasks — Bulk import tasks from jarvis-brain format
14. POST /api/import/projects — Bulk import projects from jarvis-brain format

S2: Break-Glass Authentication

15. Add isLocalAuth boolean field to User model (Prisma migration)
16. Add passwordHash optional field to User model (for local auth users)
17. Implement /api/auth/local/login endpoint (email + password, bcrypt)
18. Implement /api/auth/local/setup endpoint (first-time break-glass user creation, requires admin token from env)
19. Break-glass user bypasses OIDC entirely — session-based auth via BetterAuth
20. Environment variable BREAKGLASS_SETUP_TOKEN controls initial setup access

S3: Admin UI Pages (Frontend)

21. /settings/users — User management page (table: name, email, role, status, workspaces, last login)
22. User detail/edit dialog (change role, deactivate, view workspace memberships)
23. Invite user dialog (email input, workspace selection, role selection)
24. /settings/workspaces — Workspace management page (list workspaces, member counts)
25. Workspace detail page (members list, team list, settings)
26. Add/remove workspace member dialog with role picker
27. /settings/teams — Team management within workspace context
28. Create team dialog, add/remove team members

S4: RBAC UI Enforcement

29. Navigation sidebar: show/hide admin items based on user role
30. Settings pages: restrict access to admin-only pages
31. Action buttons: disable/hide create/delete based on permission level
32. User profile: show current role and workspace memberships

S5: Data Migration

33. Build scripts/migrate-brain.ts — TypeScript migration script
34. Read jarvis-brain data/tasks/*.json (v2.0 format: { version, domain, tasks: [...] })
35. Read jarvis-brain data/projects/*.json (format: { version, project: {...}, tasks: [...] })
36. Map brain status to Mosaic TaskStatus (done->COMPLETED, in-progress->IN_PROGRESS, backlog/pending/scheduled/not-started/planned->NOT_STARTED, blocked/on-hold->PAUSED, cancelled->ARCHIVED)
37. Map brain priority to Mosaic TaskPriority (critical/high->HIGH, medium->MEDIUM, low->LOW)
38. Create Domain records for unique domains (work, homelab, finances, family, etc.)
39. Create Project records from project data, linking to domains
40. Create Task records linking to projects, preserving brain-specific fields in metadata JSON
41. Preserve blocks, blocked_by, repo, branch, current_milestone, notes in task/project metadata
42. Dry-run mode with validation report before actual import
43. Idempotent — skip records that already exist (match by metadata.brainId)

Out of Scope

• Federation (MS22)
• Agent task mapping and telemetry (MS23)
• Playwright E2E tests (MS24)
• Email delivery service (invitations stored as links for now)
• User self-registration (admin-only invitation model)

User/Stakeholder Requirements

1. Jason (admin) can invite Melanie to a shared workspace
2. Jason can create a "USC IT" workspace and invite employees
3. Each user sees only their workspace(s) data
4. Break-glass user can log in without Authentik being available
5. Admin pages are only visible to OWNER/ADMIN roles
6. Data from jarvis-brain appears in the dashboard, kanban, and project pages after migration
7. All existing tests continue to pass after changes

Functional Requirements

FR-001: Admin User Management API

• AdminGuard protects all /api/admin/* routes
• List users returns: id, name, email, emailVerified, createdAt, workspace memberships with roles
• Invite creates a User record with a pending invitation token
• Deactivate sets a deactivatedAt timestamp (new field), does not delete data
• ASSUMPTION: User deactivation is soft-delete via new deactivatedAt field on User model. Rationale: Hard delete would cascade and destroy workspace data.

FR-002: Workspace Member Management API

• Add member requires WORKSPACE_ADMIN or WORKSPACE_OWNER permission
• Role changes require equal or higher permission (MEMBER cannot promote to ADMIN)
• Cannot remove the last OWNER of a workspace
• Cannot change own role to lower than OWNER if sole owner

FR-003: Break-Glass Authentication

• Local auth is opt-in per deployment via ENABLE_LOCAL_AUTH=true env var
• Break-glass setup requires a one-time setup token from environment
• Password stored as bcrypt hash, minimum 12 characters
• Break-glass user gets OWNER role on default workspace
• Session management identical to OIDC users (BetterAuth session tokens)
• ASSUMPTION: BetterAuth supports custom credential providers alongside OIDC. Rationale: BetterAuth documentation confirms credential-based auth as a built-in feature.

FR-004: Admin UI

• User management table with search, sort, filter by role/status
• Inline role editing via dropdown
• Confirmation dialog for destructive actions (deactivate user, remove from workspace)
• PDA-friendly language: "Deactivate" not "Delete", "Pending" not "Expired"
• Responsive design matching existing Settings page patterns
• Dark/light theme support via existing design token system

FR-005: Data Migration Script

• Standalone TypeScript script in scripts/migrate-brain.ts
• Reads from jarvis-brain path (configurable via --brain-path flag)
• Connects to Mosaic Stack database via DATABASE_URL
• Requires target workspace ID (--workspace-id flag)
• Requires creator user ID (--user-id flag)
• Outputs validation report before writing (dry-run by default)
• --apply flag to execute the migration
• Creates Activity log entries for all imported records

Technical Design

Schema Changes (Prisma Migration)

Add to User model:

• deactivatedAt DateTime? (soft delete)
• isLocalAuth Boolean default(false)
• passwordHash String? (bcrypt hash for local auth)
• invitedBy String? Uuid (FK to inviting user)
• invitationToken String? unique
• invitedAt DateTime?

New NestJS Module: AdminModule

Location: apps/api/src/admin/ Files: admin.module.ts, admin.controller.ts, admin.service.ts, DTOs, specs

New NestJS Module: LocalAuthModule (Break-Glass)

Location: apps/api/src/auth/local/ Files: local-auth.controller.ts, local-auth.service.ts, DTOs, specs

Frontend Pages

Location: apps/web/app/(authenticated)/settings/

• users/page.tsx — User management
• workspaces/page.tsx — Workspace list
• workspaces/[id]/page.tsx — Workspace detail (members, teams)
• teams/page.tsx — Team management

Testing and Verification

1. Baseline: pnpm lint && pnpm build && pnpm test must pass
2. Unit tests for AdminService (user CRUD, invitation flow, permission checks)
3. Unit tests for LocalAuthService (bcrypt hashing, token validation)
4. Unit tests for AdminController (route guards, DTO validation)
5. Integration test: invitation -> acceptance -> workspace access
6. Integration test: break-glass setup -> login -> workspace access
7. Integration test: RBAC prevents unauthorized role changes
8. Migration script test: dry-run produces valid report, apply creates correct records
9. Frontend: admin pages render with correct role gating
10. All 4,772+ existing tests continue to pass

Quality Gates

pnpm lint && pnpm build && pnpm test

Delivery Phases

Phase	Focus	Tasks
P1: Schema + Admin API	Prisma migration, AdminModule, user/workspace/team management endpoints	S1 items 1-12
P2: Break-Glass Auth	LocalAuthModule, credential provider, setup flow	S2 items 15-20
P3: Data Migration	Migration script, jarvis-brain to PostgreSQL	S5 items 33-43
P4: Admin UI	Settings pages for users, workspaces, teams	S3 items 21-28
P5: RBAC UI Enforcement	Frontend permission gating, navigation filtering	S4 items 29-32
P6: Verification	Full test pass, deployment, smoke test	All quality gates

Risks and Open Questions

1. Risk: BetterAuth credential provider may require specific adapter configuration. Mitigation: Review BetterAuth docs for credential auth alongside OIDC; test in isolation first.
2. Risk: Schema migration on production database. Mitigation: Use Prisma migration with --create-only for review before applying.
3. Risk: jarvis-brain data has fields that don't map 1:1 to Mosaic schema. Mitigation: Use metadata JSON field for overflow; validate with dry-run.
4. Open: Should deactivated users retain active sessions? ASSUMPTION: No, deactivation immediately invalidates all sessions. Rationale: Security best practice.
5. Open: Should break-glass user be auto-created on first deployment? ASSUMPTION: No, requires explicit setup via API with env token. Rationale: Prevents accidental exposure.

Assumptions

1. User deactivation is soft-delete via deactivatedAt field. Hard delete cascades and destroys workspace data.
2. BetterAuth supports custom credential providers alongside OIDC.
3. Invitation flow uses link-based tokens (no email service required initially).
4. Break-glass auth is off by default, controlled by ENABLE_LOCAL_AUTH env var.
5. Migration script runs outside the API server as a standalone script.
6. Admin pages follow existing Settings page UI patterns (cards, tables, dialogs).