@aphexcms/cms-core 0.1.0 → 0.1.3

package/src/auth/MULTI_TENANCY_PLAN.md

@@ -1,1183 +0,0 @@
-# Multi-Tenancy Implementation Plan
-
-**Goal**: Transform Aphex CMS from single-tenant to multi-tenant, enabling agencies to manage multiple client organizations with complete data isolation.
-
----
-
-## ⚠️ Important: Soft Multi-Tenancy
-
-**This implementation uses "soft multi-tenancy" (shared database with row-level filtering), NOT "true multi-tenancy" (database-per-tenant).**
-
-### What This Means:
-
-- ✅ All organizations share the same database and compute resources
-- ✅ Data isolation is enforced at the **application level** via `organizationId` filtering
-- ✅ Suitable for 90% of use cases (agencies, freelancers, small-to-medium businesses)
-- ❌ NOT suitable for enterprises requiring database-level isolation or dedicated infrastructure
-- ❌ Noisy neighbor effects possible (one org's heavy queries can slow others)
-- ❌ Cannot guarantee data residency (all data in same database/region)
-
-### When to Upgrade to True Multi-Tenancy:
-
-- Enterprise clients with compliance requirements (GDPR, HIPAA)
-- Organizations requiring guaranteed SLAs and dedicated resources
-- High-security environments requiring database-level isolation
-- Clients willing to pay 10-40x more for dedicated infrastructure
-
-See [Enterprise Multi-Tenancy Considerations](#enterprise-multi-tenancy-considerations) for future evolution paths.
-
----
-
-## Overview
-
-### Key Principles
-
-- ✅ **Separate Organizations** - Each client gets their own isolated workspace
-- ✅ **Super Admin Pattern** - First/designated users can create organizations
-- ✅ **Many-to-Many** - Users can belong to multiple organizations with different roles
-- ✅ **Active Organization** - Users work in one organization at a time (switchable)
-- ✅ **Role-Based Access** - Owner > Admin > Editor > Viewer per organization
-- ✅ **Complete Isolation** - Documents/assets are scoped by organization
-- ✅ **Don't Touch Better Auth** - All extensions go in CMS tables
-
-### Architecture
-
-```
-Better Auth (App Layer)          CMS Core (Package Layer)
-├── user (authentication)        ├── cms_organizations
-├── session                      ├── cms_organization_members
-└── apikey                       ├── cms_invitations
-                                 ├── cms_user_sessions
-                                 ├── cms_documents (+ organizationId)
-                                 └── cms_assets (+ organizationId)
-```
-
----
-
-## Phase 1: Database Schema
-
-### New Tables
-
-#### 1. Organizations
-
-```typescript
-cms_organizations {
-  id: uuid PRIMARY KEY;
-  name: varchar(200) NOT NULL;           // "Client A", "Agency Internal"
-  slug: varchar(100) UNIQUE NOT NULL;    // "client-a", "agency-internal"
-  metadata: jsonb;                        // { logo, theme, website, settings }
-  createdBy: text NOT NULL;               // User ID (super admin who created it)
-  createdAt: timestamp;
-  updatedAt: timestamp;
-}
-```
-
-**Purpose**: Store organization (client/project) data with branding/settings.
-
-#### 2. Organization Members (Many-to-Many)
-
-```typescript
-cms_organization_members {
-  id: uuid PRIMARY KEY;
-  organizationId: uuid NOT NULL → cms_organizations(id) CASCADE;
-  userId: text NOT NULL;                  // References Better Auth user
-  role: enum('owner', 'admin', 'editor', 'viewer') NOT NULL;
-  preferences: jsonb;                     // Org-specific user preferences
-  invitedBy: text;                        // User ID who invited this member
-  createdAt: timestamp;
-  updatedAt: timestamp;
-
-  UNIQUE(organizationId, userId);         // One role per user per org
-}
-```
-
-**Purpose**: Junction table linking users to organizations with roles.
-
-#### 3. Invitations
-
-```typescript
-cms_invitations {
-  id: uuid PRIMARY KEY;
-  organizationId: uuid NOT NULL → cms_organizations(id) CASCADE;
-  email: varchar(255) NOT NULL;
-  role: enum('owner', 'admin', 'editor', 'viewer') NOT NULL;
-  token: text UNIQUE NOT NULL;            // Crypto-random token (32 bytes)
-  invitedBy: text NOT NULL;               // User ID of inviter
-  expiresAt: timestamp NOT NULL;          // Default: now() + 7 days
-  acceptedAt: timestamp;                  // Null until accepted
-  createdAt: timestamp;
-
-  UNIQUE(organizationId, email);          // Can't invite same email twice
-}
-```
-
-**Purpose**: Pending invitations with secure tokens.
-
-#### 4. User Sessions (Active Organization Tracking)
-
-```typescript
-cms_user_sessions {
-  userId: text PRIMARY KEY;               // References Better Auth user
-  activeOrganizationId: uuid → cms_organizations(id);
-  updatedAt: timestamp;
-}
-```
-
-**Purpose**: Track which organization user is currently working in.
-
-### Modified Tables
-
-#### 5. Documents (Add Organization Scoping)
-
-```typescript
-cms_documents {
-  // ... existing fields
-  organizationId: uuid NOT NULL → cms_organizations(id) CASCADE;  // NEW
-}
-```
-
-#### 6. Assets (Add Organization Scoping)
-
-```typescript
-cms_assets {
-  // ... existing fields
-  organizationId: uuid NOT NULL → cms_organizations(id) CASCADE;  // NEW
-}
-```
-
-### Keep Existing Tables
-
-#### 7. User Profiles (Keep for Global Preferences)
-
-```typescript
-cms_user_profiles {
-  userId: text PRIMARY KEY;
-  preferences: jsonb;  // Global preferences (theme, language)
-  createdAt: timestamp;
-  updatedAt: timestamp;
-}
-```
-
-**Note**: This stores global user preferences. Organization-specific preferences go in `cms_organization_members`.
-
----
-
-## Phase 2: Core Types & Interfaces
-
-### New Types
-
-**Location**: `packages/cms-core/src/types/`
-
-```typescript
-// types/organization.ts
-export interface Organization {
-	id: string;
-	name: string;
-	slug: string;
-	metadata?: {
-		logo?: string;
-		theme?: { primaryColor: string; fontFamily: string; logoUrl: string };
-		website?: string;
-		settings?: Record<string, any>;
-	};
-	createdBy: string;
-	createdAt: Date;
-	updatedAt: Date;
-}
-
-export interface OrganizationMember {
-	id: string;
-	organizationId: string;
-	userId: string;
-	role: 'owner' | 'admin' | 'editor' | 'viewer';
-	preferences?: Record<string, any>;
-	invitedBy?: string;
-	createdAt: Date;
-	updatedAt: Date;
-}
-
-export interface OrganizationMembership {
-	organization: Organization; // Full org data
-	member: OrganizationMember; // Membership record
-}
-
-export interface Invitation {
-	id: string;
-	organizationId: string;
-	email: string;
-	role: 'owner' | 'admin' | 'editor' | 'viewer';
-	token: string;
-	invitedBy: string;
-	expiresAt: Date;
-	acceptedAt?: Date;
-	createdAt: Date;
-}
-```
-
-### Updated Types
-
-```typescript
-// types/user.ts (UPDATED)
-export interface CMSUser extends AuthUser {
-	// Super admin flag
-	isSuperAdmin: boolean;
-
-	// Current active organization (what they're working in now)
-	activeOrganization?: {
-		id: string;
-		name: string;
-		role: 'owner' | 'admin' | 'editor' | 'viewer';
-	};
-
-	// All organizations user belongs to (for switcher)
-	organizations?: OrganizationMembership[];
-
-	// Global preferences
-	preferences?: Record<string, any>;
-}
-
-// types/auth.ts (UPDATED)
-export interface SessionAuth {
-	type: 'session';
-	user: CMSUser; // Now includes org context
-	session: {
-		id: string;
-		expiresAt: Date;
-	};
-}
-
-export interface ApiKeyAuth {
-	type: 'api_key';
-	keyId: string;
-	name: string;
-	permissions: ('read' | 'write')[];
-	organizationId: string; // NEW: All API keys are org-scoped
-	createdBy?: string;
-	lastUsedAt?: Date;
-}
-```
-
-### New Adapter Interface
-
-```typescript
-// db/interfaces/organization.ts
-export interface OrganizationAdapter {
-	// Organization CRUD
-	createOrganization(data: CreateOrganizationData): Promise<Organization>;
-	findOrganizationById(id: string): Promise<Organization | null>;
-	findOrganizationBySlug(slug: string): Promise<Organization | null>;
-	updateOrganization(id: string, data: UpdateOrganizationData): Promise<Organization>;
-	deleteOrganization(id: string): Promise<boolean>;
-
-	// Member management
-	addMember(data: AddMemberData): Promise<OrganizationMember>;
-	removeMember(organizationId: string, userId: string): Promise<boolean>;
-	updateMemberRole(
-		organizationId: string,
-		userId: string,
-		role: string
-	): Promise<OrganizationMember>;
-	findUserMembership(userId: string, organizationId: string): Promise<OrganizationMember | null>;
-	findUserOrganizations(userId: string): Promise<OrganizationMembership[]>;
-	findOrganizationMembers(organizationId: string): Promise<OrganizationMember[]>;
-
-	// Invitation management
-	createInvitation(data: CreateInvitationData): Promise<Invitation>;
-	findInvitationByToken(token: string): Promise<Invitation | null>;
-	findOrganizationInvitations(organizationId: string): Promise<Invitation[]>;
-	acceptInvitation(token: string, userId: string): Promise<OrganizationMember>;
-	deleteInvitation(id: string): Promise<boolean>;
-	cleanupExpiredInvitations(): Promise<number>;
-
-	// User session management
-	updateUserSession(userId: string, organizationId: string): Promise<void>;
-	findUserSession(userId: string): Promise<{ activeOrganizationId: string } | null>;
-}
-```
-
-### Updated Adapter Interfaces
-
-```typescript
-// DocumentAdapter - Add organizationId parameter
-interface DocumentAdapter {
-	list(organizationId: string, filters?: DocumentFilters): Promise<Document[]>;
-	create(organizationId: string, data: CreateDocumentData): Promise<Document>;
-	update(organizationId: string, id: string, data: UpdateDocumentData): Promise<Document>;
-	delete(organizationId: string, id: string): Promise<boolean>;
-	// ... all methods need organizationId
-}
-
-// AssetAdapter - Add organizationId parameter
-interface AssetAdapter {
-	list(organizationId: string, filters?: AssetFilters): Promise<Asset[]>;
-	create(organizationId: string, data: CreateAssetData): Promise<Asset>;
-	delete(organizationId: string, id: string): Promise<boolean>;
-	// ... all methods need organizationId
-}
-```
-
----
-
-## Phase 3: Auth Service Updates
-
-### Super Admin Detection
-
-**Don't modify Better Auth `user` table**. Use one of these approaches:
-
-**Option 1: Environment Variable (Recommended)**
-
-```typescript
-// apps/studio/src/lib/server/auth/service.ts
-const SUPER_ADMIN_EMAILS = process.env.SUPER_ADMIN_EMAILS?.split(',') || [];
-
-async function isSuperAdmin(email: string): boolean {
-	return SUPER_ADMIN_EMAILS.includes(email);
-}
-```
-
-**Option 2: Separate CMS Table**
-
-```typescript
-// Create cms_super_admins table
-cms_super_admins {
-  userId: text PRIMARY KEY;
-  createdAt: timestamp;
-}
-```
-
-### Enrich authService.getSession()
-
-**Location**: `apps/studio/src/lib/server/auth/service.ts`
-
-```typescript
-async getSession(request: Request, db: DatabaseAdapter): Promise<SessionAuth | null> {
-  // 1. Get Better Auth session (authentication)
-  const session = await auth.api.getSession({ headers: request.headers });
-  if (!session) return null;
-
-  // 2. Check super admin status
-  const isSuperAdmin = SUPER_ADMIN_EMAILS.includes(session.user.email);
-
-  // 3. Get active organization from cms_user_sessions
-  const userSession = await db.findUserSession(session.user.id);
-  const activeOrgId = userSession?.activeOrganizationId;
-
-  // 4. If activeOrgId exists, get membership details
-  let activeOrganization;
-  if (activeOrgId) {
-    const membership = await db.findUserMembership(session.user.id, activeOrgId);
-    if (membership) {
-      activeOrganization = {
-        id: membership.organization.id,
-        name: membership.organization.name,
-        role: membership.member.role
-      };
-    }
-  }
-
-  // 5. Get all user organizations (for switcher)
-  const organizations = await db.findUserOrganizations(session.user.id);
-
-  // 6. Get global preferences (from cms_user_profiles)
-  const userProfile = await db.findUserProfileById(session.user.id);
-
-  // 7. Build enriched CMSUser
-  const cmsUser: CMSUser = {
-    id: session.user.id,
-    email: session.user.email,
-    name: session.user.name,
-    image: session.user.image,
-    isSuperAdmin,
-    activeOrganization,
-    organizations,
-    preferences: userProfile?.preferences || {}
-  };
-
-  return {
-    type: 'session',
-    user: cmsUser,
-    session: {
-      id: session.session.id,
-      expiresAt: session.session.expiresAt
-    }
-  };
-}
-```
-
----
-
-## Phase 4: API Endpoints
-
-### Organization Management
-
-```typescript
-POST   /api/organizations              // Create org (super admin only)
-GET    /api/organizations              // List user's organizations
-GET    /api/organizations/:id          // Get org details
-PATCH  /api/organizations/:id          // Update org (owner only)
-DELETE /api/organizations/:id          // Delete org (owner only)
-POST   /api/auth/switch-organization   // Switch active org
-
-// Super admin only
-GET    /api/admin/organizations        // List all orgs
-GET    /api/admin/organizations/:id/stats  // Org stats
-```
-
-### Member Management
-
-```typescript
-GET    /api/organizations/:id/members           // List members
-PATCH  /api/organizations/:id/members/:userId   // Update member role
-DELETE /api/organizations/:id/members/:userId   // Remove member
-```
-
-### Invitation System
-
-```typescript
-// Create invitation (owner/admin only)
-POST   /api/organizations/:id/invitations
-{
-  email: "user@example.com",
-  role: "editor",
-  expiresInDays: 7  // Optional, default 7
-}
-// Returns: { id, token, inviteLink: "/invite/token" }
-
-// List pending invitations (owner/admin only)
-GET    /api/organizations/:id/invitations
-
-// Cancel invitation (owner/admin only)
-DELETE /api/invitations/:id
-
-// Smart redirect (no UI, just logic)
-GET    /invite/:token
-// If authenticated → auto-accept and redirect
-// If not authenticated → redirect to login/signup with ?invite=token
-```
-
-### Updated Endpoints
-
-```typescript
-// All now automatically scoped by activeOrganizationId
-GET    /api/documents
-POST   /api/documents
-GET    /api/assets
-POST   /api/assets
-
-// API keys now require organizationId
-POST   /api/auth/api-keys
-{
-  name: "Production Key",
-  permissions: ["read", "write"],
-  organizationId: "org-123"  // REQUIRED
-}
-```
-
----
-
-## Phase 5: Invitation Flow
-
-### Complete Flow (Corrected)
-
-```
-1. Owner/Admin creates invitation
-   ↓
-2. Email sent to user with /invite/token link
-   ↓
-3. User clicks link → GET /invite/:token
-   ↓
-4. Route checks authentication:
-
-   If authenticated:
-     → Auto-accept invitation
-     → Redirect to /admin (in new org)
-
-   If NOT authenticated:
-     → Check if user exists (by email)
-
-     If user exists:
-       → Redirect to /login?invite=token
-
-     If user doesn't exist:
-       → Redirect to /signup?invite=token
-   ↓
-5. After login/signup:
-   → Check for ?invite= param
-   → Auto-accept invitation
-   → Redirect to /admin (in new org)
-```
-
-### Implementation
-
-```typescript
-// apps/studio/src/routes/invite/[token]/+page.server.ts
-export const load: PageServerLoad = async ({ params, locals }) => {
-	const { token } = params;
-
-	// Get invitation
-	const invitation = await db.findInvitationByToken(token);
-	if (!invitation) throw error(404, 'Invitation not found');
-	if (invitation.expiresAt < new Date()) throw error(410, 'Invitation expired');
-	if (invitation.acceptedAt) throw error(410, 'Invitation already accepted');
-
-	// Check if user is authenticated
-	const auth = locals.auth;
-
-	if (auth && auth.type === 'session') {
-		// User is logged in → auto-accept
-		await db.acceptInvitation(token, auth.user.id);
-
-		// Set as active organization
-		await db.updateUserSession(auth.user.id, invitation.organizationId);
-
-		throw redirect(302, '/admin');
-	} else {
-		// User not logged in → redirect to login/signup
-		// Check if user exists
-		const userExists = await checkUserExists(invitation.email);
-
-		if (userExists) {
-			throw redirect(302, `/login?invite=${token}`);
-		} else {
-			throw redirect(302, `/signup?invite=${token}`);
-		}
-	}
-};
-```
-
-```typescript
-// Update login/signup to handle invite param
-// apps/studio/src/routes/login/+page.server.ts (or form action)
-export const actions = {
-	default: async ({ request, locals, url }) => {
-		// ... perform login
-
-		// Check for invite token
-		const inviteToken = url.searchParams.get('invite');
-		if (inviteToken) {
-			await db.acceptInvitation(inviteToken, userId);
-			await db.updateUserSession(userId, invitation.organizationId);
-		}
-
-		throw redirect(302, '/admin');
-	}
-};
-```
-
-### Email Integration
-
-```typescript
-// Send invitation email (use Resend, SendGrid, etc.)
-const invitation = await db.createInvitation({
-	organizationId: org.id,
-	email: 'user@example.com',
-	role: 'editor',
-	invitedBy: currentUser.id,
-	expiresInDays: 7
-});
-
-await emailService.send({
-	to: invitation.email,
-	subject: `You've been invited to ${org.name}`,
-	template: 'invitation',
-	data: {
-		orgName: org.name,
-		inviterName: currentUser.name,
-		role: invitation.role,
-		inviteLink: `https://yourdomain.com/invite/${invitation.token}`,
-		expiresAt: invitation.expiresAt
-	}
-});
-```
-
----
-
-## Phase 6: Frontend Components
-
-### Organization Switcher
-
-```svelte
-<!-- apps/studio/src/lib/components/OrganizationSwitcher.svelte -->
-<script lang="ts">
-	import { page } from '$app/stores';
-
-	let user = $derived($page.data.auth?.user);
-	let activeOrg = $derived(user?.activeOrganization);
-	let organizations = $derived(user?.organizations || []);
-	let isSuperAdmin = $derived(user?.isSuperAdmin || false);
-
-	async function switchOrganization(orgId: string) {
-		await fetch('/api/auth/switch-organization', {
-			method: 'POST',
-			headers: { 'Content-Type': 'application/json' },
-			body: JSON.stringify({ organizationId: orgId })
-		});
-		window.location.reload();
-	}
-</script>
-
-{#if isSuperAdmin}
-	<span class="badge">Super Admin</span>
-{/if}
-
-<select value={activeOrg?.id} onchange={(e) => switchOrganization(e.currentTarget.value)}>
-	{#if !activeOrg}
-		<option value="">Select Organization</option>
-	{/if}
-	{#each organizations as { organization, member }}
-		<option value={organization.id}>
-			{organization.name} ({member.role})
-		</option>
-	{/each}
-</select>
-
-{#if isSuperAdmin}
-	<a href="/admin/organizations/new">+ Create Organization</a>
-{/if}
-```
-
-### Key UI Updates
-
-- **Header/Sidebar**: Show active organization and switcher
-- **Organization Settings**: Only visible to owners/admins
-- **Invite Members Form**: Only visible to owners/admins
-- **Pending Invitations List**: Show in members page
-- **Login/Signup Pages**: Handle `?invite=` parameter
-- **No Accept Invite Page**: `/invite/:token` is just a smart redirect
-
----
-
-## Phase 7: Public Content & Landing Pages
-
-### Organization-Based Routing
-
-Each organization can have landing pages with custom branding:
-
-**Option A: Subdomain**
-
-```
-https://client-a.yourdomain.com/product-launch
-https://client-b.yourdomain.com/services
-```
-
-**Option B: Path**
-
-```
-https://yourdomain.com/client-a/product-launch
-https://yourdomain.com/client-b/services
-```
-
-### Implementation
-
-```typescript
-// Landing pages are just documents scoped by organizationId
-await db.createDocument(clientAOrgId, {
-  schemaType: 'landingPage',
-  data: {
-    title: 'Product Launch',
-    slug: 'product-launch',
-    hero: { ... },
-    sections: [ ... ],
-    status: 'published'
-  }
-});
-
-// Route resolves org from subdomain/path
-const org = await db.findOrganizationBySlug(subdomain);
-const pages = await db.findDocuments(org.id, {
-  schemaType: 'landingPage',
-  filters: { 'data.slug': pageSlug, 'data.status': 'published' }
-});
-
-// Apply org theme from metadata
-const theme = org.metadata?.theme || defaultTheme;
-```
-
----
-
-## Phase 8: Migration Strategy
-
-### Step 1: Add Schema
-
-```sql
--- Add new tables
-CREATE TABLE cms_organizations (...);
-CREATE TABLE cms_organization_members (...);
-CREATE TABLE cms_invitations (...);
-CREATE TABLE cms_user_sessions (...);
-
--- Add organizationId to existing tables
-ALTER TABLE cms_documents ADD COLUMN organization_id UUID;
-ALTER TABLE cms_assets ADD COLUMN organization_id UUID;
-```
-
-### Step 2: Migrate Data
-
-```sql
--- Create default organization
-INSERT INTO cms_organizations (id, name, slug, created_by)
-VALUES (
-  gen_random_uuid(),
-  'Default Organization',
-  'default',
-  (SELECT id FROM user WHERE email = 'admin@example.com')
-);
-
--- Migrate user profiles to organization members
-INSERT INTO cms_organization_members (organization_id, user_id, role)
-SELECT
-  (SELECT id FROM cms_organizations WHERE slug = 'default'),
-  user_id,
-  'editor'  -- Default role
-FROM cms_user_profiles;
-
--- Assign all documents to default org
-UPDATE cms_documents
-SET organization_id = (SELECT id FROM cms_organizations WHERE slug = 'default');
-
--- Assign all assets to default org
-UPDATE cms_assets
-SET organization_id = (SELECT id FROM cms_organizations WHERE slug = 'default');
-```
-
-### Step 3: Deploy Code
-
-- Update adapters
-- Update auth service
-- Update UI
-
-### Step 4: Make organizationId NOT NULL
-
-```sql
-ALTER TABLE cms_documents ALTER COLUMN organization_id SET NOT NULL;
-ALTER TABLE cms_assets ALTER COLUMN organization_id SET NOT NULL;
-```
-
----
-
-## Key Architecture Decisions
-
-### ✅ What We're Doing
-
-1. **Don't Modify Better Auth Tables**
-   - Store super admin list in env var or separate table
-   - Store active org in `cms_user_sessions` (not `session` table)
-
-2. **Keep User Profiles Table**
-   - For global user preferences (theme, language)
-   - Organization-specific preferences go in `cms_organization_members`
-
-3. **Many-to-Many User-Organization**
-   - Users can belong to multiple organizations
-   - Different role in each organization
-   - One active organization at a time
-
-4. **Smart Invite Flow**
-   - No separate "accept invite" page
-   - `/invite/:token` auto-redirects to login/signup
-   - Auto-accept after authentication
-
-5. **Organization Scoping**
-   - All documents/assets require `organizationId`
-   - API keys are organization-scoped
-   - Complete data isolation
-
-### ❌ What We're NOT Doing
-
-1. **Not modifying Better Auth schema** - All extensions in CMS tables
-2. **Not adding fine-grained permissions yet** - Start with role-based access
-3. **Not implementing datasets yet** - Can add later (dev/staging/prod)
-4. **Not using Better Auth hooks for sync** - Using lazy sync in authService
-
----
-
-## Summary Checklist
-
-- [ ] Phase 1: Create database schema (4 new tables, 2 modified)
-- [ ] Phase 2: Define types and interfaces
-- [ ] Phase 3: Implement OrganizationAdapter (PostgreSQL)
-- [ ] Phase 4: Update DocumentAdapter and AssetAdapter signatures
-- [ ] Phase 5: Update authService.getSession() to enrich with org data
-- [ ] Phase 6: Create organization management endpoints
-- [ ] Phase 7: Implement invitation system (create, accept, email)
-- [ ] Phase 8: Build organization switcher UI
-- [ ] Phase 9: Update login/signup to handle invite params
-- [ ] Phase 10: Add organization settings pages
-- [ ] Phase 11: Test multi-tenancy isolation
-- [ ] Phase 12: Run migration on existing data
-- [ ] Phase 13: (Optional) Add landing page routing
-- [ ] Phase 14: (Optional) Set up email service for invitations
-
----
-
-**Estimated Time**: 2-3 weeks for core multi-tenancy (Phases 1-12)
-
-**Next Steps**: Start with Phase 1 (Database Schema) - create the migration file.
-
----
-
-## Best Practices & Guardrails for Soft Multi-Tenancy
-
-Since this implementation uses soft multi-tenancy (shared database), it's critical to have proper guardrails to prevent data leaks and noisy neighbor issues.
-
-### ✅ Current Safeguards in This Plan
-
-#### 1. **Database-Level Constraints**
-
-```sql
--- Foreign key ensures organizationId is valid
-ALTER TABLE cms_documents
-  ADD CONSTRAINT fk_documents_organization
-  FOREIGN KEY (organization_id)
-  REFERENCES cms_organizations(id)
-  ON DELETE CASCADE;
-
--- NOT NULL prevents missing organizationId
-ALTER TABLE cms_documents
-  ALTER COLUMN organization_id SET NOT NULL;
-
--- Index for fast filtering (prevents slow queries)
-CREATE INDEX idx_documents_organization ON cms_documents(organization_id);
-CREATE INDEX idx_assets_organization ON cms_assets(organization_id);
-```
-
-**Why**: These constraints ensure you CANNOT create documents without an organization, and queries filter efficiently.
-
-#### 2. **Adapter-Level Enforcement**
-
-```typescript
-// ALL adapter methods REQUIRE organizationId parameter
-interface DocumentAdapter {
-  // ✅ Good: organizationId required
-  list(organizationId: string, filters?: Filters): Promise<Document[]>;
-
-  // ❌ Bad: organizationId optional or missing
-  list(filters?: Filters): Promise<Document[]>;
-}
-
-// Implementation ensures filtering
-async list(organizationId: string, filters) {
-  return await db.select()
-    .from(documents)
-    .where(eq(documents.organizationId, organizationId)); // ALWAYS filtered
-}
-```
-
-**Why**: Makes it impossible to forget filtering by organizationId - it's a required parameter.
-
-#### 3. **Auth Hook Enforcement**
-
-```typescript
-// Auth hook sets organizationId in event.locals
-if (auth.type === 'session') {
-	if (!auth.user.activeOrganization) {
-		// ✅ No org selected → block access
-		throw redirect(302, '/select-organization');
-	}
-	event.locals.organizationId = auth.user.activeOrganization.id;
-}
-
-// API routes use locals.organizationId
-const orgId = locals.organizationId; // Set by auth hook
-const docs = await db.findDocuments(orgId, filters);
-```
-
-**Why**: Centralized enforcement - organizationId is set once in middleware, used everywhere.
-
-#### 4. **Type Safety**
-
-```typescript
-// TypeScript ensures organizationId is provided
-const docs = await db.findDocuments(orgId, { schemaType: 'post' });
-//                                   ^^^^^ Required, won't compile without it
-```
-
-**Why**: Compile-time safety prevents accidental cross-org queries.
-
----
-
-### ⚠️ Recommended Additional Safeguards
-
-#### 1. **Row-Level Security (RLS) - Database Level** (HIGHLY RECOMMENDED)
-
-Add PostgreSQL Row-Level Security as a backup:
-
-```sql
--- Enable RLS on tables
-ALTER TABLE cms_documents ENABLE ROW LEVEL SECURITY;
-ALTER TABLE cms_assets ENABLE ROW LEVEL SECURITY;
-
--- Create policy: users can only see their org's data
-CREATE POLICY documents_org_isolation ON cms_documents
-  USING (organization_id = current_setting('app.current_organization_id')::uuid);
-
-CREATE POLICY assets_org_isolation ON cms_assets
-  USING (organization_id = current_setting('app.current_organization_id')::uuid);
-
--- Set org context per request
-SET app.current_organization_id = 'org-123';
-SELECT * FROM cms_documents; -- Only sees org-123's documents
-```
-
-**Implementation**:
-
-```typescript
-// In adapter, set session variable before querying
-async list(organizationId: string, filters) {
-  // Set RLS context
-  await db.execute(sql`SET app.current_organization_id = ${organizationId}`);
-
-  // Even if we forget WHERE clause, RLS protects us
-  return await db.select().from(documents);
-}
-```
-
-**Benefit**: Even if application code has a bug, database-level RLS prevents cross-org access.
-
----
-
-#### 2. **Query Timeouts** (Prevent Noisy Neighbor)
-
-```typescript
-// Set statement timeout per request
-async executeQuery(orgId: string, query: SQL) {
-  await db.execute(sql`SET statement_timeout = '30s'`); // Kill after 30s
-
-  try {
-    return await db.execute(query);
-  } catch (error) {
-    if (error.code === '57014') { // Query timeout
-      throw new Error('Query took too long - please optimize your filters');
-    }
-    throw error;
-  }
-}
-```
-
-**Benefit**: Prevents one org's bad query from locking the database.
-
----
-
-#### 3. **Connection Pool Limits Per Organization**
-
-```typescript
-// Track active connections per org
-const orgConnectionCount = new Map<string, number>();
-
-async function getConnection(orgId: string) {
-	const current = orgConnectionCount.get(orgId) || 0;
-
-	// Limit to 5 concurrent connections per org
-	if (current >= 5) {
-		throw new Error('Too many concurrent requests - please try again');
-	}
-
-	orgConnectionCount.set(orgId, current + 1);
-
-	const conn = await pool.connect();
-
-	conn.on('release', () => {
-		orgConnectionCount.set(orgId, (orgConnectionCount.get(orgId) || 1) - 1);
-	});
-
-	return conn;
-}
-```
-
-**Benefit**: Prevents one org from exhausting the connection pool.
-
----
-
-#### 4. **API Rate Limiting** ✅ Already Handled by Better Auth
-
-**Current Implementation:**
-
-```typescript
-// apps/studio/src/lib/server/auth/better-auth/instance.ts
-plugins: [
-	apiKey({
-		apiKeyHeaders: ['x-api-key'],
-		rateLimit: {
-			enabled: true,
-			timeWindow: 1000 * 60 * 60 * 24, // 24 hours (adjustable)
-			maxRequests: 10000 // 10k requests/day (adjustable)
-		},
-		enableMetadata: true
-	})
-];
-```
-
-**Benefit**:
-
-- ✅ API keys already rate-limited (10k requests/day by default)
-- ✅ Configurable per deployment (adjust timeWindow and maxRequests)
-- ✅ Handled by Better Auth (automatic enforcement)
-- ✅ Prevents API abuse without additional infrastructure
-- ✅ No Redis/Upstash needed for basic rate limiting
-
-**Note**: This is per-key rate limiting. Each API key is limited independently. For organization-level aggregated limits (e.g., "Org A gets 100k requests/day across all keys"), you'd need custom rate limiting, but per-key limits are sufficient for most use cases.
-
----
-
-#### 5. **Monitoring & Alerting Per Organization**
-
-```typescript
-// Track query performance per org
-async function executeQuery(orgId: string, query: SQL) {
-	const start = Date.now();
-
-	try {
-		const result = await db.execute(query);
-		const duration = Date.now() - start;
-
-		// Log slow queries
-		if (duration > 1000) {
-			console.warn(`[Org ${orgId}] Slow query (${duration}ms):`, query);
-
-			// Alert if consistently slow
-			await metrics.increment('slow_queries', { organizationId: orgId });
-		}
-
-		return result;
-	} catch (error) {
-		// Track errors per org
-		await metrics.increment('query_errors', { organizationId: orgId });
-		throw error;
-	}
-}
-```
-
-**Benefit**: Identify problematic organizations before they affect others.
-
----
-
-#### 6. **Audit Logging**
-
-```typescript
-// Log all data access
-cms_audit_logs {
-  id: uuid;
-  organizationId: uuid;
-  userId: text;
-  action: enum('read', 'create', 'update', 'delete');
-  resourceType: string; // 'document', 'asset'
-  resourceId: uuid;
-  timestamp: timestamp;
-}
-
-// In adapter
-async create(orgId: string, data: CreateDocumentData) {
-  const doc = await db.insert(documents).values({
-    ...data,
-    organizationId: orgId
-  });
-
-  // Audit log
-  await db.insert(auditLogs).values({
-    organizationId: orgId,
-    userId: currentUser.id,
-    action: 'create',
-    resourceType: 'document',
-    resourceId: doc.id,
-    timestamp: new Date()
-  });
-
-  return doc;
-}
-```
-
-**Benefit**: Track and investigate any cross-org access attempts.
-
----
-
-#### 7. **Regular Security Audits**
-
-```typescript
-// Automated check: Find documents without organizationId (shouldn't exist)
-async function auditOrganizationIsolation() {
-	const orphanedDocs = await db.select().from(documents).where(isNull(documents.organizationId));
-
-	if (orphanedDocs.length > 0) {
-		console.error(`SECURITY ALERT: ${orphanedDocs.length} documents without organizationId!`);
-		// Alert admin
-	}
-
-	// Check for cross-org references
-	const invalidRefs = await db.execute(sql`
-    SELECT d.id, d.organization_id, a.organization_id as asset_org_id
-    FROM cms_documents d
-    JOIN cms_assets a ON d.data->>'imageId' = a.id::text
-    WHERE d.organization_id != a.organization_id
-  `);
-
-	if (invalidRefs.length > 0) {
-		console.error(`SECURITY ALERT: ${invalidRefs.length} cross-org references!`);
-	}
-}
-
-// Run daily
-setInterval(auditOrganizationIsolation, 24 * 60 * 60 * 1000);
-```
-
-**Benefit**: Catch isolation bugs early before they become security issues.
-
----
-
-### ✅ Summary: Is This Plan Following Best Practices?
-
-**YES**, the current plan has good safeguards:
-
-| Safeguard                             | Status          | Notes                                    |
-| ------------------------------------- | --------------- | ---------------------------------------- |
-| **Required organizationId parameter** | ✅ Built-in     | Adapter interface enforces it            |
-| **Database foreign keys**             | ✅ Built-in     | Prevents invalid organizationId          |
-| **NOT NULL constraints**              | ✅ Built-in     | Prevents missing organizationId          |
-| **API key rate limiting**             | ✅ Built-in     | Better Auth plugin (10k/day, adjustable) |
-| **Indexes on organizationId**         | ⚠️ Add this     | Ensure fast queries (performance)        |
-| **Row-Level Security (RLS)**          | ❌ Not included | HIGHLY RECOMMENDED to add                |
-| **Query timeouts**                    | ❌ Not included | Recommended for production               |
-| **Connection pool limits**            | ❌ Not included | Recommended for scale                    |
-| **Audit logging**                     | ❌ Not included | Recommended for compliance               |
-
-### Recommendations:
-
-**Must Have (Before Production)**:
-
-1. ✅ Add database indexes on `organizationId` columns
-2. ✅ Implement Row-Level Security (RLS) in PostgreSQL
-3. ✅ Add query timeouts
-
-**Should Have (For Scale)**: 4. ✅ Add connection pool limits per organization 5. ✅ Set up monitoring per organization 6. ✅ Consider session-based rate limiting (for UI users, not API keys)
-
-**Nice to Have (For Enterprise)**: 7. ✅ Audit logging 8. ✅ Automated security audits 9. ✅ Backup/restore per organization 10. ✅ Organization-level aggregated rate limits (across all API keys)
-
----
-
-## Enterprise Multi-Tenancy Considerations
-
-For clients requiring true database isolation, consider these evolution paths:
-
-### **Tier 2: Schema-per-Tenant** (Intermediate)
-
-- Each org gets a PostgreSQL schema (same database, isolated tables)
-- Better isolation than row-level filtering
-- Still shares compute resources
-- ~4x price increase
-
-### **Tier 3: Database-per-Tenant** (Advanced)
-
-- Each org gets a separate database (different DBs, same server)
-- Complete database isolation
-- Independent backups/restores
-- Can support data residency requirements
-- ~10x price increase
-
-### **Tier 4: Fully Isolated** (Enterprise)
-
-- Each org gets dedicated compute + database + storage
-- No noisy neighbor effects
-- Custom SLAs and scaling
-- Suitable for Fortune 500 clients
-- ~40x+ price increase
-
-**Implementation Note**: Current architecture supports gradual migration - start with soft multi-tenancy, upgrade specific orgs to higher tiers as needed.