thevoidforge 21.0.11 → 21.0.13

package/dist/docs/patterns/middleware.ts

@@ -0,0 +1,363 @@
+/**
+ * Pattern: Middleware (Auth + Request Logging)
+ *
+ * Key principles:
+ * - Auth middleware runs before route handlers
+ * - Request logging captures method, path, status, duration
+ * - Structured JSON logs with requestId for tracing
+ * - Never log sensitive data (passwords, tokens, PII)
+ * - Fail closed — if auth check errors, deny access
+ *
+ * Agents: Kenobi (security), Barton (error handling), L (monitoring)
+ *
+ * Framework adaptations:
+ *   Next.js: This file (middleware.ts in root, NextRequest/NextResponse)
+ *   Express: app.use(authMiddleware), app.use(requestLogger) — (err, req, res, next) for errors
+ *   Django: MIDDLEWARE list in settings.py, or decorators (@login_required, @permission_required)
+ *   Rails: before_action in controllers, Rack middleware for logging
+ *
+ * === Django Deep Dive ===
+ *
+ *   # app/middleware.py
+ *   import time, json, logging, uuid
+ *
+ *   class RequestLoggingMiddleware:
+ *       def __init__(self, get_response):
+ *           self.get_response = get_response
+ *       def __call__(self, request):
+ *           request.request_id = str(uuid.uuid4())
+ *           start = time.monotonic()
+ *           response = self.get_response(request)
+ *           duration = time.monotonic() - start
+ *           logging.info(json.dumps({
+ *               "request_id": request.request_id, "method": request.method,
+ *               "path": request.path, "status": response.status_code,
+ *               "duration_ms": round(duration * 1000),
+ *               "user_id": getattr(request.user, "id", None),
+ *           }))
+ *           return response
+ *
+ *   # settings.py: MIDDLEWARE = ['app.middleware.RequestLoggingMiddleware', ...]
+ *   # Order matters: logging before auth, auth before rate limiting
+ *   # @login_required is per-view — use for fine-grained control, not global middleware
+ *
+ * === FastAPI Deep Dive ===
+ *
+ *   from fastapi import Request
+ *   from starlette.middleware.base import BaseHTTPMiddleware
+ *   import time, uuid
+ *
+ *   class RequestLoggingMiddleware(BaseHTTPMiddleware):
+ *       async def dispatch(self, request: Request, call_next):
+ *           request.state.request_id = str(uuid.uuid4())
+ *           start = time.monotonic()
+ *           response = await call_next(request)
+ *           duration = time.monotonic() - start
+ *           # structured log here
+ *           return response
+ *
+ *   # app.add_middleware(RequestLoggingMiddleware)
+ *   # For auth: prefer Depends() over middleware — dependency injection is more testable
+ *   # For rate limiting: slowapi or custom Depends() with Redis
+ */
+
+import { NextRequest, NextResponse } from 'next/server'
+import { verifySessionToken } from '@/lib/auth'
+import { nanoid } from 'nanoid'
+
+// --- Auth middleware ---
+export async function authMiddleware(req: NextRequest) {
+  const token = req.cookies.get('session')?.value
+
+  if (!token) {
+    return NextResponse.json(
+      { error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
+      { status: 401 }
+    )
+  }
+
+  try {
+    // Fail closed — if verification throws, deny access (Kenobi)
+    const session = await verifySessionToken(token)
+
+    if (!session) {
+      return NextResponse.json(
+        { error: { code: 'UNAUTHORIZED', message: 'Invalid session' } },
+        { status: 401 }
+      )
+    }
+
+    // Attach session to request headers for downstream use
+    const response = NextResponse.next()
+    response.headers.set('x-user-id', session.userId)
+    response.headers.set('x-request-id', nanoid())
+    return response
+  } catch {
+    // Auth errors = deny, don't expose details
+    return NextResponse.json(
+      { error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
+      { status: 401 }
+    )
+  }
+}
+
+// --- Request logging middleware ---
+export function withRequestLogging(
+  handler: (req: NextRequest) => Promise<NextResponse>
+) {
+  return async (req: NextRequest): Promise<NextResponse> => {
+    const requestId = nanoid()
+    const start = Date.now()
+
+    // Add request ID for tracing
+    const url = new URL(req.url)
+
+    let response: NextResponse
+    let error: unknown = null
+
+    try {
+      response = await handler(req)
+    } catch (err) {
+      error = err
+      response = NextResponse.json(
+        { error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' } },
+        { status: 500 }
+      )
+    }
+
+    const duration = Date.now() - start
+
+    // Structured log — JSON, parseable, includes tracing context (L — monitoring)
+    const logEntry = {
+      requestId,
+      method: req.method,
+      path: url.pathname,
+      status: response.status,
+      duration,
+      userId: req.headers.get('x-user-id') || undefined,
+      // Never log: request body, auth tokens, cookies, PII (Padme — data protection)
+      ...(error instanceof Error && { error: error.message }),
+      ...(duration > 1000 && { slow: true }), // Flag slow requests
+    }
+
+    if (response.status >= 500) {
+      console.error(JSON.stringify(logEntry))
+    } else if (response.status >= 400) {
+      console.warn(JSON.stringify(logEntry))
+    } else {
+      console.log(JSON.stringify(logEntry))
+    }
+
+    // Attach request ID to response for client-side debugging
+    response.headers.set('x-request-id', requestId)
+    return response
+  }
+}
+
+// --- Rate limiting middleware ---
+// Simple in-memory rate limiter. Replace with Redis for multi-instance.
+const rateLimitMap = new Map<string, { count: number; resetAt: number }>()
+
+export function rateLimit(
+  req: NextRequest,
+  { limit = 60, windowMs = 60_000 }: { limit?: number; windowMs?: number } = {}
+): NextResponse | null {
+  // Rate limit by IP or user ID (Ahsoka — access control)
+  // IP extraction priority: cf-connecting-ip (Cloudflare, set at edge, cannot be spoofed by client)
+  // > x-real-ip (nginx) > x-forwarded-for first entry (client-spoofable) > fallback
+  const key =
+    req.headers.get('x-user-id') ||
+    req.headers.get('cf-connecting-ip') ||
+    req.headers.get('x-real-ip') ||
+    req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+    'unknown'
+  const now = Date.now()
+
+  const entry = rateLimitMap.get(key)
+
+  if (!entry || now > entry.resetAt) {
+    rateLimitMap.set(key, { count: 1, resetAt: now + windowMs })
+    return null // Allowed
+  }
+
+  entry.count++
+
+  if (entry.count > limit) {
+    return NextResponse.json(
+      { error: { code: 'RATE_LIMITED', message: 'Too many requests' } },
+      {
+        status: 429,
+        headers: {
+          'Retry-After': String(Math.ceil((entry.resetAt - now) / 1000)),
+        },
+      }
+    )
+  }
+
+  return null // Allowed
+}
+
+// =============================================================================
+// Cookie Authentication
+// =============================================================================
+
+/**
+ * 1. Setting HttpOnly Cookies on Login
+ *
+ * After successful authentication, set the JWT in an HttpOnly cookie.
+ * HttpOnly prevents XSS from reading the token. Secure ensures HTTPS only.
+ * SameSite=Lax blocks cross-site POST requests while allowing top-level navigation.
+ *
+ * === Express / Next.js API Route ===
+ *
+ *   // POST /api/auth/login
+ *   const token = await createSessionToken(user.id)
+ *   res.setHeader('Set-Cookie', [
+ *     `session=${token}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=${7 * 24 * 60 * 60}`,
+ *   ])
+ *   // Next.js App Router: use cookies() from 'next/headers'
+ *   //   cookies().set('session', token, {
+ *   //     httpOnly: true, secure: true, sameSite: 'lax',
+ *   //     path: '/', maxAge: 7 * 24 * 60 * 60,
+ *   //   })
+ *   res.json({ user: { id: user.id, email: user.email } })
+ *
+ * === Django / FastAPI ===
+ *
+ *   # Django view
+ *   response = JsonResponse({"user": {"id": user.id}})
+ *   response.set_cookie("session", token, httponly=True, secure=True,
+ *                        samesite="Lax", max_age=7 * 24 * 60 * 60)
+ *
+ *   # FastAPI endpoint
+ *   response = JSONResponse({"user": {"id": user.id}})
+ *   response.set_cookie("session", token, httponly=True, secure=True,
+ *                        samesite="lax", max_age=7 * 24 * 60 * 60)
+ */
+
+/**
+ * 2. Reading Cookies with Bearer Fallback
+ *
+ * Check cookie first (browser clients), then Authorization header (API clients).
+ * This lets the same endpoint serve both contexts without separate auth flows.
+ */
+export async function authMiddlewareWithCookieFallback(req: NextRequest) {
+  // Cookie takes priority — browser clients send this automatically
+  let token = req.cookies.get('session')?.value
+
+  // Bearer fallback — API clients, mobile apps, server-to-server
+  if (!token) {
+    const authHeader = req.headers.get('authorization')
+    if (authHeader?.startsWith('Bearer ')) {
+      token = authHeader.slice(7)
+    }
+  }
+
+  if (!token) {
+    return NextResponse.json(
+      { error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
+      { status: 401 }
+    )
+  }
+
+  try {
+    // Fail closed — same principle as authMiddleware (Kenobi)
+    const session = await verifySessionToken(token)
+    if (!session) {
+      return NextResponse.json(
+        { error: { code: 'UNAUTHORIZED', message: 'Invalid session' } },
+        { status: 401 }
+      )
+    }
+
+    const response = NextResponse.next()
+    response.headers.set('x-user-id', session.userId)
+    response.headers.set('x-request-id', nanoid())
+    return response
+  } catch {
+    return NextResponse.json(
+      { error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
+      { status: 401 }
+    )
+  }
+}
+
+/**
+ * 3. CSRF Protection via Custom Header
+ *
+ * SameSite=Lax already blocks cross-site POSTs, but defense-in-depth matters (Kenobi).
+ * Require X-Requested-With on all mutation endpoints. Browsers enforce CORS preflight
+ * on custom headers, so a cross-origin attacker cannot set this without server consent.
+ *
+ * === Django / FastAPI ===
+ *
+ *   # Django: use built-in CsrfViewMiddleware OR check custom header
+ *   class CSRFCustomHeaderMiddleware:
+ *       def __call__(self, request):
+ *           if request.method in ("POST", "PUT", "DELETE", "PATCH"):
+ *               if request.headers.get("X-Requested-With") != "XMLHttpRequest":
+ *                   return JsonResponse({"error": "CSRF check failed"}, status=403)
+ *           return self.get_response(request)
+ *
+ *   # FastAPI: use Depends() for the same check
+ *   async def require_csrf_header(request: Request):
+ *       if request.method in ("POST", "PUT", "DELETE", "PATCH"):
+ *           if request.headers.get("x-requested-with") != "XMLHttpRequest":
+ *               raise HTTPException(403, "CSRF check failed")
+ */
+const MUTATION_METHODS = new Set(['POST', 'PUT', 'DELETE', 'PATCH'])
+
+export function csrfProtection(req: NextRequest): NextResponse | null {
+  if (!MUTATION_METHODS.has(req.method)) {
+    return null // GET/HEAD/OPTIONS — no CSRF risk
+  }
+
+  // Cookie-based auth requires the custom header; Bearer tokens are not vulnerable
+  const hasCookie = req.cookies.has('session')
+  const hasCustomHeader = req.headers.get('x-requested-with') === 'XMLHttpRequest'
+
+  if (hasCookie && !hasCustomHeader) {
+    return NextResponse.json(
+      { error: { code: 'CSRF_FAILED', message: 'Missing X-Requested-With header' } },
+      { status: 403 }
+    )
+  }
+
+  return null // Allowed
+}
+
+/**
+ * 4. Frontend Fetch Configuration
+ *
+ * When using cookie auth, every fetch() call must include credentials: 'include'.
+ * Without it, the browser won't send or accept cookies on cross-origin requests.
+ * This typed wrapper enforces that and sets the CSRF header automatically.
+ */
+type ApiResponse<T> = { data: T } | { error: { code: string; message: string } }
+
+async function apiFetch<T>(
+  path: string,
+  options: RequestInit = {}
+): Promise<ApiResponse<T>> {
+  const response = await fetch(path, {
+    ...options,
+    credentials: 'include', // Required — sends cookies with every request
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Requested-With': 'XMLHttpRequest', // CSRF protection for cookie auth
+      ...options.headers,
+    },
+  })
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}))
+    return { error: body.error ?? { code: 'UNKNOWN', message: response.statusText } }
+  }
+
+  return { data: await response.json() }
+}
+
+// Usage:
+//   const result = await apiFetch<{ user: User }>('/api/users/me')
+//   if ('error' in result) { handleError(result.error) }
+//   else { renderUser(result.data.user) }

package/dist/docs/patterns/mobile-screen.tsx

@@ -0,0 +1,139 @@
+/**
+ * Pattern: React Native Screen with All States
+ *
+ * Key principles:
+ * - Every screen handles: loading, empty, error, and success states (same as web component.tsx)
+ * - Safe area insets respected — content never under the notch or home indicator
+ * - Navigation follows platform conventions (back swipe iOS, hardware back Android)
+ * - Touch targets minimum 44pt (iOS) / 48dp (Android)
+ * - Keyboard avoidance on all forms
+ * - Supports Dynamic Type / system font scaling
+ * - Reduced motion respected via useReducedMotion()
+ *
+ * Agents: Legolas (code), Samwise-Mobile (a11y), Bilbo (copy), Gimli (performance)
+ *
+ * Framework adaptations:
+ *   React Native: This file
+ *   Flutter: Same 4-state pattern with StatefulWidget, SafeArea, MediaQuery
+ *   SwiftUI: NavigationStack, .safeAreaInset, @Environment(\.dynamicTypeSize)
+ *
+ * The framework changes, the principle doesn't:
+ * EVERY screen handles loading, empty, error, and success. Safe area is non-negotiable.
+ */
+
+import React from 'react'
+import {
+  View,
+  Text,
+  FlatList,
+  TouchableOpacity,
+  ActivityIndicator,
+  RefreshControl,
+  StyleSheet,
+  Platform,
+  AccessibilityInfo,
+} from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+import { useNavigation } from '@react-navigation/native'
+
+// --- Types ---
+interface Project {
+  id: string
+  name: string
+  description: string | null
+}
+
+interface ProjectListScreenProps {
+  projects: Project[]
+  isLoading: boolean
+  error: string | null
+  onRefresh: () => void
+  onDelete: (id: string) => void
+}
+
+export function ProjectListScreen({
+  projects,
+  isLoading,
+  error,
+  onRefresh,
+  onDelete,
+}: ProjectListScreenProps) {
+  const insets = useSafeAreaInsets()
+  const navigation = useNavigation()
+
+  // Loading state — full-screen spinner with a11y announcement
+  if (isLoading && projects.length === 0) {
+    return (
+      <View style={[styles.center, { paddingTop: insets.top }]} accessibilityRole="progressbar">
+        <ActivityIndicator size="large" />
+        <Text style={styles.loadingText} accessibilityLiveRegion="polite">
+          Loading projects...
+        </Text>
+      </View>
+    )
+  }
+
+  // Error state — actionable, not just "something went wrong"
+  if (error) {
+    return (
+      <View style={[styles.center, { paddingTop: insets.top }]} accessibilityRole="alert">
+        <Text style={styles.errorTitle}>Couldn't load your projects</Text>
+        <Text style={styles.errorMessage}>{error}</Text>
+        <TouchableOpacity
+          onPress={onRefresh}
+          style={styles.retryButton}
+          accessibilityRole="button"
+          accessibilityLabel="Retry loading projects"
+        >
+          <Text style={styles.retryText}>Try Again</Text>
+        </TouchableOpacity>
+      </View>
+    )
+  }
+
+  // Empty state — guide the user
+  if (projects.length === 0) {
+    return (
+      <View style={[styles.center, { paddingTop: insets.top }]}>
+        <Text style={styles.emptyTitle}>No projects yet</Text>
+        <Text style={styles.emptyMessage}>Create your first project to get started.</Text>
+      </View>
+    )
+  }
+
+  // Success state — pull-to-refresh list
+  return (
+    <FlatList
+      data={projects}
+      keyExtractor={(item) => item.id}
+      contentContainerStyle={{ paddingTop: insets.top, paddingBottom: insets.bottom }}
+      refreshControl={<RefreshControl refreshing={isLoading} onRefresh={onRefresh} />}
+      renderItem={({ item }) => (
+        <TouchableOpacity
+          style={styles.card}
+          onPress={() => navigation.navigate('ProjectDetail', { id: item.id })}
+          accessibilityRole="button"
+          accessibilityLabel={`Open ${item.name}`}
+          // Touch target: minimum 44pt height enforced by card padding
+        >
+          <Text style={styles.cardTitle}>{item.name}</Text>
+          {item.description && <Text style={styles.cardDescription}>{item.description}</Text>}
+        </TouchableOpacity>
+      )}
+    />
+  )
+}
+
+const styles = StyleSheet.create({
+  center: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: 24 },
+  loadingText: { marginTop: 12, fontSize: 16, color: '#666' },
+  errorTitle: { fontSize: 18, fontWeight: '600', color: '#dc2626' },
+  errorMessage: { marginTop: 4, fontSize: 14, color: '#dc2626', textAlign: 'center' },
+  retryButton: { marginTop: 16, paddingHorizontal: 20, paddingVertical: 12, backgroundColor: '#dc2626', borderRadius: 8 },
+  retryText: { color: '#fff', fontWeight: '600' },
+  emptyTitle: { fontSize: 18, fontWeight: '600', color: '#111' },
+  emptyMessage: { marginTop: 4, fontSize: 14, color: '#666' },
+  card: { padding: 16, borderBottomWidth: StyleSheet.hairlineWidth, borderColor: '#e5e7eb', minHeight: 44 },
+  cardTitle: { fontSize: 16, fontWeight: '600', color: '#111' },
+  cardDescription: { marginTop: 4, fontSize: 14, color: '#666' },
+})

package/dist/docs/patterns/mobile-service.ts

@@ -0,0 +1,167 @@
+/**
+ * Pattern: Offline-First Mobile Service
+ *
+ * Key principles:
+ * - Local-first: reads always hit local storage (SQLite/MMKV), writes queue for sync
+ * - Optimistic UI: user sees the change immediately, sync happens in background
+ * - Conflict resolution: last-write-wins with timestamp, or manual merge for critical data
+ * - Network-aware: queue syncs when connection is available, pauses when offline
+ * - Retry with backoff: failed syncs retry 3x with exponential backoff, then queue for later
+ *
+ * Agents: Stark (service logic), Thor (sync queue), Barton (error handling)
+ *
+ * Framework adaptations:
+ *   React Native: This file (SQLite via expo-sqlite or react-native-sqlite-storage, NetInfo)
+ *   Flutter: sqflite + connectivity_plus, same pattern with Dart async
+ *   SwiftUI: SwiftData or Core Data + NWPathMonitor, same pattern with async/await
+ *
+ * The framework changes, the principle doesn't:
+ * EVERY offline-capable service has: local store, sync queue, conflict resolution, retry.
+ */
+
+// --- Types ---
+interface SyncQueueItem {
+  id: string
+  action: 'create' | 'update' | 'delete'
+  entity: string
+  payload: Record<string, unknown>
+  timestamp: number
+  retries: number
+}
+
+interface SyncResult {
+  success: boolean
+  serverVersion?: Record<string, unknown>
+  conflict?: boolean
+}
+
+// --- Local Storage Layer ---
+// In a real implementation, this would use expo-sqlite, WatermelonDB, or MMKV
+
+class LocalStore {
+  /** Read from local SQLite — always available, even offline */
+  async get<T>(entity: string, id: string): Promise<T | null> {
+    // SELECT * FROM {entity} WHERE id = ? — local DB
+    return null as T | null // placeholder
+  }
+
+  /** Write to local SQLite + queue for sync */
+  async set<T extends { id: string }>(entity: string, item: T): Promise<void> {
+    // INSERT OR REPLACE INTO {entity} — local DB
+    // Then queue the sync
+    await SyncQueue.enqueue({
+      id: item.id,
+      action: 'update',
+      entity,
+      payload: item as Record<string, unknown>,
+      timestamp: Date.now(),
+      retries: 0,
+    })
+  }
+
+  /** Delete locally + queue for sync */
+  async delete(entity: string, id: string): Promise<void> {
+    // DELETE FROM {entity} WHERE id = ? — local DB
+    await SyncQueue.enqueue({
+      id,
+      action: 'delete',
+      entity,
+      payload: {},
+      timestamp: Date.now(),
+      retries: 0,
+    })
+  }
+
+  /** List all items of an entity — local only, instant */
+  async list<T>(entity: string): Promise<T[]> {
+    // SELECT * FROM {entity} — local DB
+    return [] as T[]
+  }
+}
+
+// --- Sync Queue ---
+// Persisted to SQLite so it survives app restarts
+
+class SyncQueue {
+  static async enqueue(item: SyncQueueItem): Promise<void> {
+    // INSERT INTO sync_queue — persisted locally
+  }
+
+  static async processQueue(apiClient: ApiClient): Promise<void> {
+    // 1. Read all pending items from sync_queue
+    // 2. For each item:
+    //    a. Send to server via apiClient
+    //    b. If success: remove from queue
+    //    c. If conflict: resolve (last-write-wins or flag for user)
+    //    d. If network error: increment retries, backoff
+    //    e. If retries > 3: move to dead letter (show user "sync failed" badge)
+  }
+
+  static async getPendingCount(): Promise<number> {
+    // SELECT COUNT(*) FROM sync_queue — for UI badge
+    return 0
+  }
+}
+
+// --- Network-Aware Sync Manager ---
+
+class SyncManager {
+  private intervalId: ReturnType<typeof setInterval> | null = null
+
+  /** Start periodic sync — call on app launch */
+  start(apiClient: ApiClient): void {
+    // Check connectivity, process queue if online
+    // Re-check every 30 seconds
+    this.intervalId = setInterval(() => {
+      // if (NetInfo.isConnected) SyncQueue.processQueue(apiClient)
+    }, 30_000)
+  }
+
+  /** Stop sync — call on app background or logout */
+  stop(): void {
+    if (this.intervalId) clearInterval(this.intervalId)
+  }
+
+  /** Force sync — call on pull-to-refresh */
+  async forceSync(apiClient: ApiClient): Promise<void> {
+    await SyncQueue.processQueue(apiClient)
+  }
+}
+
+// --- Conflict Resolution ---
+
+function resolveConflict(local: SyncQueueItem, server: Record<string, unknown>): 'keep-local' | 'keep-server' {
+  // Last-write-wins: compare timestamps
+  const serverTimestamp = (server as { updatedAt?: number }).updatedAt ?? 0
+  return local.timestamp > serverTimestamp ? 'keep-local' : 'keep-server'
+
+  // For critical data (financial, medical), prefer 'flag-for-user' instead of auto-resolve
+}
+
+// --- API Client (placeholder) ---
+
+interface ApiClient {
+  sync(item: SyncQueueItem): Promise<SyncResult>
+}
+
+// --- Usage ---
+// const store = new LocalStore()
+// const syncManager = new SyncManager()
+//
+// // On app launch:
+// syncManager.start(apiClient)
+//
+// // Read (always local — instant, works offline):
+// const projects = await store.list<Project>('projects')
+//
+// // Write (local + queue sync — optimistic, works offline):
+// await store.set('projects', { id: '1', name: 'New Project' })
+//
+// // Pull to refresh (force sync):
+// await syncManager.forceSync(apiClient)
+//
+// // Show sync badge:
+// const pending = await SyncQueue.getPendingCount()
+// if (pending > 0) showBadge(`${pending} changes pending sync`)
+
+export { LocalStore, SyncQueue, SyncManager, resolveConflict }