ui-syncup 0.3.13 → 0.4.0-beta.2

package/docs/feature-architectures/RESOURCE_LIMITS.md

@@ -0,0 +1,69 @@
+# Resource Limits & Quotas
+
+## 1. Role Model
+
+### A. Team-level roles
+#### Management Roles
+- **TEAM_OWNER**: Access team settings, manage members/settings, delete team.
+- **TEAM_ADMIN**: Manage members, projects, integrations. Cannot delete team.
+
+#### Operational Roles
+- **TEAM_EDITOR**: Create/manage issues and annotations. Assigned to content creators.
+- **TEAM_MEMBER**: View projects and comment.
+- **TEAM_VIEWER**: Read-only access.
+
+### B. Project-level roles
+- **PROJECT_OWNER**: Full project control.
+- **PROJECT_EDITOR**: Create/manage issues.
+- **PROJECT_DEVELOPER**: Update issue status and comment.
+- **PROJECT_VIEWER**: Read-only.
+
+## 2. Resource Quotas
+
+To ensure system stability and fair usage in self-hosted environments, we define resource quotas. These are configured via environment variables.
+
+### Default Limits (Instance Level)
+All teams on the instance share the same limits.
+
+- **Members**: Configured via `MAX_MEMBERS_PER_TEAM` (default: unlimited)
+- **Projects**: Configured via `MAX_PROJECTS_PER_TEAM` (default: 100)
+- **Issues**: Configured via `MAX_ISSUES_PER_TEAM` (default: unlimited)
+- **Storage**: Configured via `MAX_STORAGE_PER_TEAM_MB` (default: 10,000)
+
+### Configuration (Env Vars)
+
+These values are read at runtime.
+
+```bash
+# .env
+MAX_MEMBERS_PER_TEAM="50"
+MAX_PROJECTS_PER_TEAM="25"
+MAX_ISSUES_PER_TEAM="1000"
+MAX_STORAGE_PER_TEAM_MB="5000"
+```
+
+## 3. Enforcement
+
+Enforcement logic resides in `server/limits/` (formerly entitlements).
+
+```typescript
+// src/server/limits/index.ts
+import { QUOTAS } from '@/config/quotas'
+
+export async function ensureCanCreateProject(teamId: string) {
+  const usage = await getUsageForTeam(teamId)
+  if (QUOTAS.projects !== "unlimited" && usage.projects >= QUOTAS.projects) {
+    throw new Error("LIMIT_PROJECTS_REACHED")
+  }
+}
+```
+
+## 4. Workflows
+
+Workflows are defined in `src/config/workflows.ts`.
+
+## 5. Naming Conventions
+
+- **TEAM_…** for team-level
+- **PROJECT_…** for project-level
+- API Routes: `/api/team/members`, `/api/projects`, `/api/issues`

package/docs/feature-architectures/SECURITY.md

@@ -0,0 +1,284 @@
+# Security Configuration
+
+This document describes the security headers and CORS configuration implemented in UI SyncUp.
+
+## Overview
+
+The application implements multiple layers of security controls:
+
+1. **Content Security Policy (CSP)** - Controls which resources can be loaded
+2. **CORS (Cross-Origin Resource Sharing)** - Controls which origins can access the API
+3. **Security Headers** - Additional browser security features
+4. **HSTS (HTTP Strict Transport Security)** - Forces HTTPS in production
+
+## Implementation
+
+### Architecture
+
+Security headers are configured in three places:
+
+1. **`next.config.ts`** - Global headers applied to all routes
+2. **`src/proxy.ts`** - Dynamic headers and CORS preflight handling
+3. **`src/lib/cors.ts`** - CORS utilities for API routes
+4. **`src/lib/security-headers.ts`** - Centralized security header definitions
+
+### Content Security Policy (CSP)
+
+CSP restricts which resources the browser can load, preventing XSS and data injection attacks.
+
+**Configured Directives:**
+
+```typescript
+{
+  'default-src': ["'self'"],
+  'script-src': ["'self'", "'unsafe-inline'", "'unsafe-eval'" /* dev only */],
+  'style-src': ["'self'", "'unsafe-inline'"],
+  'img-src': ["'self'", 'data:', 'https:', 'blob:'],
+  'font-src': ["'self'", 'data:'],
+  'connect-src': [
+    "'self'",
+    'https://*.supabase.co',
+    'https://*.r2.cloudflarestorage.com',
+    'https://accounts.google.com',
+    'http://localhost:*' /* dev only */,
+    'ws://localhost:*' /* dev only */
+  ],
+  'frame-ancestors': ["'none'"],
+  'base-uri': ["'self'"],
+  'form-action': ["'self'"],
+  'upgrade-insecure-requests': true /* production only */
+}
+```
+
+**External Services Allowed:**
+
+- **Supabase** (`*.supabase.co`) - Database and authentication
+- **Cloudflare R2** (`*.r2.cloudflarestorage.com`) - Object storage
+- **Google OAuth** (`accounts.google.com`) - Authentication
+
+**Modifying CSP:**
+
+To add a new external service:
+
+1. Edit `src/lib/security-headers.ts`
+2. Add the domain to the appropriate directive in `getCSPDirectives()`
+3. Test in development and preview environments before deploying to production
+
+```typescript
+// Example: Adding a new analytics service
+'connect-src': [
+  "'self'",
+  'https://*.supabase.co',
+  'https://*.r2.cloudflarestorage.com',
+  'https://accounts.google.com',
+  'https://analytics.example.com', // New service
+  // ...
+]
+```
+
+### CORS Configuration
+
+CORS controls which origins can make requests to the API.
+
+**Allowed Origins:**
+
+- **Production**: `NEXT_PUBLIC_APP_URL` environment variable
+- **Preview**: `*.vercel.app` wildcard
+- **Development**: `localhost:3000`, `localhost:3001`
+
+**CORS Headers:**
+
+```typescript
+{
+  'Access-Control-Allow-Credentials': 'true',
+  'Access-Control-Allow-Origin': '<origin>',
+  'Access-Control-Allow-Methods': 'GET,POST,PUT,PATCH,DELETE,OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With',
+  'Access-Control-Max-Age': '86400' // 24 hours
+}
+```
+
+**Using CORS in API Routes:**
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { withCors } from '@/lib/cors';
+
+export async function GET(request: NextRequest) {
+  const origin = request.headers.get('origin');
+  
+  const response = NextResponse.json({ data: 'example' });
+  
+  // Apply CORS headers
+  return withCors(response, origin);
+}
+```
+
+**Preflight Requests:**
+
+OPTIONS requests are automatically handled by `src/proxy.ts`. The proxy:
+
+1. Checks if the origin is allowed
+2. Returns appropriate CORS headers
+3. Returns 204 No Content status
+
+### Security Headers
+
+Additional security headers are applied to all responses:
+
+| Header | Value | Purpose |
+|--------|-------|---------|
+| `X-Frame-Options` | `DENY` | Prevents clickjacking by blocking iframe embedding |
+| `X-Content-Type-Options` | `nosniff` | Prevents MIME type sniffing |
+| `X-XSS-Protection` | `1; mode=block` | Enables browser XSS protection |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` | Controls referrer information |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` | Disables unnecessary browser features |
+| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains; preload` | Forces HTTPS (production only) |
+
+### HSTS (HTTP Strict Transport Security)
+
+HSTS forces browsers to use HTTPS for all requests.
+
+**Configuration:**
+
+- **Enabled**: Production only
+- **Max Age**: 31536000 seconds (1 year)
+- **Include Subdomains**: Yes
+- **Preload**: Yes (eligible for browser preload lists)
+
+**Important Notes:**
+
+- HSTS is only applied in production to avoid issues in local development
+- Once enabled, browsers will refuse to connect over HTTP
+- The preload flag makes the site eligible for browser HSTS preload lists
+
+## Testing
+
+### Local Testing
+
+1. Start the development server:
+   ```bash
+   bun dev
+   ```
+
+2. Check headers in browser DevTools:
+   - Open Network tab
+   - Reload the page
+   - Click on any request
+   - View Response Headers
+
+3. Verify CSP:
+   - Check Console for CSP violations
+   - All external resources should load without errors
+
+### Preview Environment Testing
+
+1. Deploy to a preview branch
+2. Test with different origins:
+   ```bash
+   # Should succeed (same origin)
+   curl -H "Origin: https://preview-xyz.vercel.app" \
+        https://preview-xyz.vercel.app/api/health
+   
+   # Should fail (different origin)
+   curl -H "Origin: https://evil.com" \
+        https://preview-xyz.vercel.app/api/health
+   ```
+
+3. Verify CSP allows all required external services
+
+### Production Testing
+
+1. After deployment, verify headers:
+   ```bash
+   curl -I https://ui-syncup.com
+   ```
+
+2. Check for:
+   - All security headers present
+   - HSTS header included
+   - CSP header includes all required domains
+
+3. Test CORS:
+   ```bash
+   # Preflight request
+   curl -X OPTIONS \
+        -H "Origin: https://ui-syncup.com" \
+        -H "Access-Control-Request-Method: POST" \
+        https://ui-syncup.com/api/health
+   ```
+
+## Security Checklist
+
+### Before Deploying
+
+- [ ] All external services are listed in CSP `connect-src`
+- [ ] CORS origins are correctly configured for the environment
+- [ ] No sensitive data in CSP or CORS configuration
+- [ ] HSTS is enabled for production
+- [ ] Security headers are applied to all routes
+
+### After Deploying
+
+- [ ] Verify all security headers are present
+- [ ] Test CORS with allowed and disallowed origins
+- [ ] Check browser console for CSP violations
+- [ ] Verify external services (Supabase, R2, Google) work correctly
+- [ ] Test API routes with different HTTP methods
+
+### Regular Maintenance
+
+- [ ] Review CSP violations in production logs
+- [ ] Update CSP when adding new external services
+- [ ] Rotate CORS origins when domains change
+- [ ] Monitor security header compliance with tools like [securityheaders.com](https://securityheaders.com)
+
+## Troubleshooting
+
+### CSP Violations
+
+**Symptom**: Console errors like "Refused to load..."
+
+**Solution**:
+1. Identify the blocked resource in the error message
+2. Add the domain to the appropriate CSP directive
+3. Test in development before deploying
+
+### CORS Errors
+
+**Symptom**: "CORS policy: No 'Access-Control-Allow-Origin' header"
+
+**Solution**:
+1. Check if the origin is in the allowed list
+2. Verify `NEXT_PUBLIC_APP_URL` is set correctly
+3. For preview deployments, ensure `*.vercel.app` is allowed
+
+### HSTS Issues
+
+**Symptom**: Browser refuses HTTP connections
+
+**Solution**:
+1. HSTS is production-only, shouldn't affect development
+2. Clear browser HSTS cache: `chrome://net-internals/#hsts`
+3. Verify `NODE_ENV` is set correctly
+
+### External Service Blocked
+
+**Symptom**: Supabase, R2, or Google OAuth not working
+
+**Solution**:
+1. Check CSP `connect-src` includes the service domain
+2. Verify environment variables are set correctly
+3. Check browser console for specific CSP violations
+
+## References
+
+- [MDN: Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+- [MDN: CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
+- [OWASP: Secure Headers Project](https://owasp.org/www-project-secure-headers/)
+- [Next.js: Security Headers](https://nextjs.org/docs/app/api-reference/next-config-js/headers)
+
+## Related Documentation
+
+- [Deployment Guide](./DEPLOYMENT.md) - Environment configuration
+- [Local Development](./LOCAL_DEVELOPMENT.md) - Development setup

package/docs/feature-architectures/WORKSPACES.md

@@ -0,0 +1,278 @@
+# Workspace Architecture
+
+UI SyncUp uses a **Workspace** model to organize users, projects, and resources. This document describes the workspace architecture and configuration options.
+
+## Overview
+
+A **Workspace** is the top-level organizational unit in UI SyncUp. It contains:
+- **Members** with assigned roles
+- **Projects** for organizing issues and annotations
+- **Settings** for workspace-level configuration
+
+```
+Instance
+├── Workspace(s)
+│   ├── Members (with roles)
+│   ├── Projects
+│   │   ├── Issues
+│   │   └── Annotations
+│   └── Settings
+```
+
+---
+
+## Workspace Modes
+
+UI SyncUp supports two operational modes controlled by the `MULTI_WORKSPACE_MODE` environment variable:
+
+### Single-Workspace Mode (Default)
+
+```bash
+MULTI_WORKSPACE_MODE=false  # or not set
+```
+
+**Behavior:**
+- One workspace is auto-created during initial setup
+- Admin names the workspace during setup wizard
+- Workspace switcher is hidden in the UI
+- All users belong to the single workspace
+- Simplified onboarding (no "create workspace" choice)
+- Ideal for small teams, agencies, and single-org self-hosting
+
+**UI Changes in Single Mode:**
+| Component | Multi-Workspace | Single-Workspace |
+|-----------|-----------------|------------------|
+| Sidebar workspace switcher | Visible | Hidden |
+| "Create new workspace" button | Visible | Hidden |
+| Workspace settings navigation | "Workspace Settings" | "Settings" |
+| Onboarding flow | Choice: create/join | Direct to dashboard |
+
+### Multi-Workspace Mode
+
+```bash
+MULTI_WORKSPACE_MODE=true
+```
+
+**Behavior:**
+- Users can create multiple workspaces
+- Users can be members of multiple workspaces
+- Workspace switcher is visible
+- Full workspace management UI available
+- Ideal for agencies, enterprises, or SaaS deployments
+
+---
+
+## Data Model
+
+### Workspace Entity
+
+```typescript
+interface Workspace {
+  id: string;           // UUID
+  name: string;         // Display name (2-50 chars)
+  slug: string;         // URL-safe identifier
+  description?: string; // Optional description
+  image?: string;       // Optional logo URL
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt?: Date;     // Soft delete support
+}
+```
+
+### Database Schema
+
+```sql
+CREATE TABLE workspaces (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(50) NOT NULL,
+  slug VARCHAR(100) NOT NULL UNIQUE,
+  description TEXT,
+  image TEXT,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  deleted_at TIMESTAMP WITH TIME ZONE
+);
+
+CREATE INDEX workspaces_slug_idx ON workspaces(slug);
+```
+
+> **Note:** The current codebase uses `teams` table. A migration will rename this to `workspaces` as part of the workspace refactor.
+
+---
+
+## Workspace Roles
+
+Workspace roles follow a **two-tier hierarchy**:
+
+### Management Roles (Workspace Settings Access)
+
+| Role | Description |
+|------|-------------|
+| **WORKSPACE_OWNER** | Full control over workspace and members. Can delete workspace and transfer ownership. |
+| **WORKSPACE_ADMIN** | Manage members, projects, integrations. Cannot delete workspace or transfer ownership. |
+
+### Operational Roles (Content Access)
+
+| Role | Level | Description |
+|------|-------|-------------|
+| **WORKSPACE_EDITOR** | 3 | Create and manage issues and annotations. |
+| **WORKSPACE_MEMBER** | 2 | View projects and comment on issues. |
+| **WORKSPACE_VIEWER** | 1 | View-only access to projects and issues. |
+
+### Role Assignment
+
+Users have **one management role** (optional) + **one operational role** (required):
+
+- `WORKSPACE_OWNER` + `WORKSPACE_EDITOR` → Owner who creates content
+- `WORKSPACE_OWNER` + `WORKSPACE_MEMBER` → Owner who only manages
+- `WORKSPACE_ADMIN` + `WORKSPACE_VIEWER` → Admin with read-only content access
+- `WORKSPACE_EDITOR` (no management role) → Content creator
+- `WORKSPACE_MEMBER` (no management role) → Collaborator
+
+---
+
+## Workspace Mode Detection
+
+The system detects workspace mode at runtime:
+
+```typescript
+// src/config/workspace.ts
+export const WORKSPACE_CONFIG = {
+  multiWorkspaceMode: process.env.MULTI_WORKSPACE_MODE === 'true',
+};
+
+export function isMultiWorkspaceMode(): boolean {
+  return WORKSPACE_CONFIG.multiWorkspaceMode;
+}
+```
+
+### Mode-Dependent Behavior
+
+| Feature | Check Function |
+|---------|----------------|
+| Show workspace switcher | `isMultiWorkspaceMode()` |
+| Allow workspace creation | `isMultiWorkspaceMode()` |
+| Show "Create workspace" in onboarding | `isMultiWorkspaceMode()` |
+| Require workspace selection on login | `isMultiWorkspaceMode() && userHasMultipleWorkspaces` |
+
+---
+
+## API Endpoints
+
+### Workspace Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/workspaces` | List user's workspaces |
+| `POST` | `/api/workspaces` | Create new workspace |
+| `GET` | `/api/workspaces/:id` | Get workspace details |
+| `PATCH` | `/api/workspaces/:id` | Update workspace |
+| `DELETE` | `/api/workspaces/:id` | Soft delete workspace |
+| `POST` | `/api/workspaces/:id/switch` | Switch active workspace |
+
+### Workspace Members
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/workspaces/:id/members` | List workspace members |
+| `POST` | `/api/workspaces/:id/members` | Add member |
+| `PATCH` | `/api/workspaces/:id/members/:userId` | Update member role |
+| `DELETE` | `/api/workspaces/:id/members/:userId` | Remove member |
+
+---
+
+## Setup Wizard Integration
+
+### Single-Workspace Mode Setup
+
+During initial setup in single-workspace mode:
+
+1. **Service Health Check** - Verify database connection
+2. **Create Admin Account** - First user becomes admin
+3. **Configure Instance** - Set instance name and URL
+4. **Create Workspace** - Name the default workspace (required)
+5. **Optional Sample Data** - Create demo project
+
+The workspace created in step 4 becomes the permanent workspace for this instance.
+
+### Multi-Workspace Mode Setup
+
+Same as single-workspace, but after setup:
+- Users can create additional workspaces
+- Workspace switcher appears in sidebar
+- New users choose: "Create workspace" or "Join with invite"
+
+---
+
+## Migration Strategy
+
+The transition from "Teams" to "Workspaces" will be semantic only:
+
+### Phase 1: Documentation & Types (Current)
+- Update all documentation to use "Workspace" terminology
+- Update TypeScript types and interfaces
+- Update UI text and labels
+
+### Phase 2: Database Migration (Future)
+- Rename `teams` table to `workspaces`
+- Rename `team_members` table to `workspace_members`
+- Update foreign keys and indexes
+
+### Phase 3: API Routes (Future)
+- Create new `/api/workspaces/*` routes
+- Deprecate `/api/teams/*` routes with redirect
+- Update client API calls
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MULTI_WORKSPACE_MODE` | `false` | Enable multi-workspace features |
+
+---
+
+## UI Components
+
+### Workspace Switcher (Multi-Mode Only)
+
+Located in the sidebar, allows users to:
+- See current workspace name and logo
+- Switch between workspaces
+- Create new workspace (if enabled)
+
+### Workspace Settings
+
+Accessible via workspace dropdown or settings navigation:
+- General settings (name, description, image)
+- Member management
+- Role assignments
+- Danger zone (delete workspace)
+
+---
+
+## Best Practices
+
+### Single-Workspace Deployments
+- Set `MULTI_WORKSPACE_MODE=false` (or leave unset)
+- Choose a descriptive workspace name during setup
+- All users will automatically be part of this workspace
+
+### Multi-Workspace Deployments
+- Set `MULTI_WORKSPACE_MODE=true`
+- Consider naming conventions for workspaces
+- Use workspace-based access control for department separation
+
+### Self-Hosting
+- Single-workspace mode is recommended for most self-hosted instances
+- Keeps the UI clean and reduces cognitive load
+- Can enable multi-workspace later if needed
+
+---
+
+## Related Documentation
+
+- [RBAC Documentation](./RBAC.md) - Role-based access control
+- [Resource Limits](./RESOURCE_LIMITS.md) - Quotas and limits
+- [Onboarding Specification](/.ai/specs/refactor-onboarding/requirements.md) - Setup wizard details