feat(web-dashboard): ChatKit UI Integration

packages/api/AUTH_INTEGRATION.md

@@ -1,213 +0,0 @@
-# Backend Auth Integration Guide for Frontend Team
-
-## Overview
-
-The TaskFlow API uses JWT/JWKS authentication against the Better Auth SSO. This document explains how auth works so you can verify your frontend implementation aligns correctly.
-
----
-
-## Auth Flow
-
-```
-┌──────────┐     ┌──────────┐     ┌──────────┐
-│ Frontend │     │   SSO    │     │ Backend  │
-│  (Next)  │     │ (Better  │     │ (FastAPI)│
-│          │     │   Auth)  │     │          │
-└────┬─────┘     └────┬─────┘     └────┬─────┘
-     │                │                │
-     │ 1. OAuth PKCE  │                │
-     │ ──────────────>│                │
-     │                │                │
-     │ 2. JWT Token   │                │
-     │ <──────────────│                │
-     │                │                │
-     │ 3. API Request │                │
-     │ ───────────────────────────────>│
-     │ Authorization: Bearer <JWT>     │
-     │                │                │
-     │                │ 4. Fetch JWKS  │
-     │                │ <──────────────│
-     │                │   (cached 1hr) │
-     │                │                │
-     │                │ 5. Return keys │
-     │                │ ──────────────>│
-     │                │                │
-     │ 6. Response    │                │
-     │ <───────────────────────────────│
-     │                │                │
-```
-
----
-
-## What Backend Expects
-
-### Authorization Header
-
-Every API request (except `/health` and `/`) must include:
-
-```
-Authorization: Bearer <JWT_TOKEN>
-```
-
-### JWT Requirements
-
-The JWT must be signed with **RS256** algorithm and contain:
-
-| Claim | Required | Description |
-|-------|----------|-------------|
-| `sub` | Yes | User ID (used as `user.id` in backend) |
-| `email` | Yes | User email |
-| `name` | No | Display name |
-| `role` | No | `"user"` or `"admin"` (defaults to `"user"`) |
-| `tenant_id` | No | Primary organization ID |
-| `kid` | Yes (header) | Key ID matching a key in JWKS |
-
-### JWKS Endpoint
-
-Backend fetches public keys from:
-```
-{SSO_URL}/api/auth/jwks
-```
-
-For local development with SSO at `http://localhost:3001`:
-```
-http://localhost:3001/api/auth/jwks
-```
-
----
-
-## Error Responses
-
-### 401 Unauthorized
-
-**Missing or invalid token:**
-```json
-{
-  "error": "Invalid JWT: <reason>",
-  "status_code": 401
-}
-```
-
-**Key not found (kid mismatch):**
-```json
-{
-  "error": "Token signing key not found in JWKS",
-  "status_code": 401
-}
-```
-
-### 503 Service Unavailable
-
-**SSO unreachable (no cached keys):**
-```json
-{
-  "error": "Authentication service unavailable: <details>",
-  "status_code": 503
-}
-```
-
----
-
-## Frontend Checklist
-
-Please verify your implementation:
-
-- [ ] **Token Storage**: JWT stored securely (httpOnly cookie or secure storage)
-- [ ] **Authorization Header**: Every API call includes `Authorization: Bearer <token>`
-- [ ] **Token Refresh**: Handle token expiration and refresh before it expires
-- [ ] **PKCE Flow**: Using OAuth2 PKCE (not implicit flow)
-- [ ] **JWT Claims**: Token includes `sub`, `email`, and `kid` in header
-- [ ] **Error Handling**: Handle 401 by redirecting to login or refreshing token
-- [ ] **SSO URL**: Configured to same SSO as backend (`SSO_URL` env var)
-
----
-
-## Debug Logging (Backend)
-
-I've added debug logging to help troubleshoot auth issues. When testing, check backend logs for:
-
-```
-[AUTH] Fetching JWKS from http://localhost:3001/api/auth/jwks
-[AUTH] JWKS fetched successfully: 2 keys
-[AUTH] JWT header - kid: abc123, alg: RS256
-[AUTH] JWT verified - sub: user-123, email: user@example.com
-[AUTH] Authenticated user: CurrentUser(id='user-123', email='user@example.com')
-```
-
-**If auth fails, logs will show:**
-- JWKS fetch errors (SSO connection issues)
-- Key ID mismatches (shows expected vs available kids)
-- JWT verification errors (expired, malformed, bad signature)
-
-To enable verbose logging, set `DEBUG=true` or `LOG_LEVEL=DEBUG` in backend `.env`.
-
----
-
-## Dev Mode (Local Testing Without SSO)
-
-For local development without SSO running, backend supports dev mode:
-
-```env
-DEV_MODE=true
-DEV_USER_ID=dev-user-123
-DEV_USER_EMAIL=dev@localhost
-DEV_USER_NAME=Dev User
-```
-
-In dev mode, any `Authorization: Bearer <anything>` header is accepted and returns the dev user. This is **only for local development** - never enable in production.
-
----
-
-## Example: Fetch with Auth (Frontend)
-
-```typescript
-// Example using fetch
-const response = await fetch('http://localhost:8000/api/projects', {
-  headers: {
-    'Authorization': `Bearer ${accessToken}`,
-    'Content-Type': 'application/json',
-  },
-});
-
-if (response.status === 401) {
-  // Token expired or invalid - refresh or redirect to login
-  await refreshToken();
-  // Retry request...
-}
-```
-
-```typescript
-// Example with axios interceptor
-axios.interceptors.request.use((config) => {
-  const token = getAccessToken();
-  if (token) {
-    config.headers.Authorization = `Bearer ${token}`;
-  }
-  return config;
-});
-
-axios.interceptors.response.use(
-  (response) => response,
-  async (error) => {
-    if (error.response?.status === 401) {
-      await refreshToken();
-      return axios.request(error.config);
-    }
-    return Promise.reject(error);
-  }
-);
-```
-
----
-
-## Questions?
-
-If you see auth failures, please share:
-1. The error response from backend
-2. Backend logs (with DEBUG=true)
-3. JWT token (you can decode at jwt.io - don't share in public channels)
-
-We can debug together to identify if the issue is:
-- Token generation (SSO/frontend)
-- Token transmission (frontend)
-- Token verification (backend)

specs/005-chatkit-ui/checklists/requirements.md

@@ -0,0 +1,75 @@
+# Requirements Checklist: 005-chatkit-ui
+
+**Generated**: 2025-12-07
+**Spec Version**: 1.0
+**Status**: VALIDATED
+
+---
+
+## Content Quality
+
+- [x] No implementation details (frameworks, APIs, code structure)
+- [x] Written for stakeholders, not just developers
+- [x] User-focused language throughout
+- [x] Clear problem statement in executive summary
+- [x] No [NEEDS CLARIFICATION] markers remaining
+
+---
+
+## Requirement Completeness
+
+- [x] All requirements are testable (Given/When/Then format)
+- [x] All requirements are measurable (specific metrics in success criteria)
+- [x] All requirements are technology-agnostic
+- [x] Each functional requirement has unique ID (FR-XXX)
+- [x] Requirements cover positive and negative cases
+
+---
+
+## User Scenarios
+
+- [x] User stories prioritized (P1, P2, P3)
+- [x] Each story independently testable
+- [x] Acceptance scenarios use Given/When/Then format
+- [x] Edge cases documented
+- [x] Error scenarios included
+
+---
+
+## Feature Readiness
+
+- [x] Success criteria are measurable
+- [x] Constraints clearly stated
+- [x] Non-goals explicitly listed
+- [x] Assumptions documented
+- [x] Dependencies identified
+- [x] Key entities defined
+
+---
+
+## Constitutional Compliance (TaskFlow)
+
+- [x] Audit: Chat interactions will create audit entries via backend
+- [x] Agent Parity: Chat provides human equivalent to MCP agent interface
+- [x] Recursive Tasks: Can create subtasks via natural language
+- [x] Spec-Driven: This spec created before implementation
+- [x] Phase Continuity: Uses existing API contracts and data models
+
+---
+
+## Validation Summary
+
+| Category | Pass | Fail | Total |
+|----------|------|------|-------|
+| Content Quality | 5 | 0 | 5 |
+| Requirement Completeness | 5 | 0 | 5 |
+| User Scenarios | 5 | 0 | 5 |
+| Feature Readiness | 6 | 0 | 6 |
+| Constitutional Compliance | 5 | 0 | 5 |
+| **TOTAL** | **26** | **0** | **26** |
+
+---
+
+## Verdict: READY
+
+Specification is complete and ready for planning phase (`/sp.plan`).