thevoidforge 21.0.11 → 21.0.13

package/dist/docs/patterns/multi-tenant.ts

@@ -0,0 +1,382 @@
+/**
+ * Pattern: Multi-Tenancy (Workspace/Organization Scoping)
+ *
+ * Key principles:
+ * - Every query is scoped to the tenant (workspace/org)
+ * - Tenant context is resolved once in middleware, passed downstream
+ * - Never trust client-provided tenant IDs — derive from session
+ * - Cross-tenant data access is impossible by default
+ * - Admin/superadmin access is explicit and audited
+ *
+ * Agents: Ahsoka (access control), Strange (service architecture), Kenobi (security)
+ *
+ * Framework adaptations:
+ *   Next.js: Middleware + headers, or context in server components
+ *   Django: Middleware + thread-local or django-tenants
+ *   Rails: ActsAsTenant gem, or Current.workspace pattern
+ *   Express: Middleware + req.workspace
+ *
+ * === Django Deep Dive (django-tenants) ===
+ *
+ *   # Schema-per-tenant: each org gets its own Postgres schema
+ *   # pip install django-tenants
+ *   # settings.py: DATABASE_ROUTERS, TENANT_MODEL, SHARED_APPS, TENANT_APPS
+ *
+ *   # Alternative: shared schema with org_id filtering
+ *   class TenantMiddleware:
+ *       def __call__(self, request):
+ *           request.org = get_org_from_subdomain(request)
+ *           return self.get_response(request)
+ *
+ *   # Every QuerySet filtered by org: Project.objects.filter(org=request.org)
+ *   # Custom manager: class TenantManager: def for_org(self, org): return self.filter(org=org)
+ *   # CRITICAL: never use .all() on tenant-scoped models — always .for_org(org)
+ *
+ * === FastAPI Deep Dive ===
+ *
+ *   # Depends() for tenant scoping — injected into every route
+ *   async def get_current_org(request: Request, user = Depends(get_current_user)):
+ *       org_id = request.headers.get("X-Org-Id") or user.default_org_id
+ *       org = await OrgService.get(org_id)
+ *       if not org or user.id not in org.member_ids:
+ *           raise HTTPException(403, "Not a member of this organization")
+ *       return org
+ *
+ *   @router.get("/projects")
+ *   async def list_projects(org = Depends(get_current_org), db = Depends(get_db)):
+ *       return await db.execute(select(Project).where(Project.org_id == org.id))
+ *
+ *   # Same principle: every query scoped by org. Never trust client-provided org_id
+ *   # without verifying membership.
+ */
+
+// --- Tenant resolution middleware ---
+
+import { NextRequest, NextResponse } from 'next/server'
+import { getSession } from '@/lib/auth'
+import { db } from '@/lib/db'
+
+export async function tenantMiddleware(req: NextRequest) {
+  const session = await getSession(req)
+  if (!session) {
+    return NextResponse.json(
+      { error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
+      { status: 401 }
+    )
+  }
+
+  // Extract workspace from URL (e.g., /api/workspaces/:id/projects)
+  const workspaceId = req.nextUrl.pathname.match(
+    /\/api\/workspaces\/([^/]+)/
+  )?.[1]
+
+  if (!workspaceId) {
+    return NextResponse.next()  // Not a workspace-scoped route
+  }
+
+  // Verify membership — NEVER trust the URL alone (Ahsoka — access control)
+  const membership = await db.workspaceMember.findUnique({
+    where: {
+      workspaceId_userId: {
+        workspaceId,
+        userId: session.userId,
+      },
+    },
+  })
+
+  if (!membership) {
+    // Return 404, not 403 — don't reveal workspace existence
+    return NextResponse.json(
+      { error: { code: 'NOT_FOUND', message: 'Not found' } },
+      { status: 404 }
+    )
+  }
+
+  // Pass tenant context downstream via headers
+  const response = NextResponse.next()
+  response.headers.set('x-workspace-id', workspaceId)
+  response.headers.set('x-workspace-role', membership.role)
+  return response
+}
+
+// --- Tenant-scoped service ---
+
+interface TenantContext {
+  workspaceId: string
+  userId: string
+  role: 'owner' | 'admin' | 'member' | 'viewer'
+}
+
+export const projectService = {
+  // Every query includes the tenant scope — no exceptions
+  async list(ctx: TenantContext) {
+    return db.project.findMany({
+      where: { workspaceId: ctx.workspaceId },  // Always scoped
+      orderBy: { createdAt: 'desc' },
+    })
+  },
+
+  async getById(ctx: TenantContext, projectId: string) {
+    const project = await db.project.findUnique({
+      where: { id: projectId },
+    })
+
+    // Double-check tenant scope — defense in depth (Kenobi)
+    if (!project || project.workspaceId !== ctx.workspaceId) {
+      throw new ApiError('NOT_FOUND', 'Project not found', 404)
+    }
+
+    return project
+  },
+
+  async create(ctx: TenantContext, input: { name: string }) {
+    // Role check — only owners, admins, and members can create
+    if (ctx.role === 'viewer') {
+      throw new ApiError('FORBIDDEN', 'Viewers cannot create projects', 403)
+    }
+
+    return db.project.create({
+      data: {
+        name: input.name,
+        workspaceId: ctx.workspaceId,
+        createdById: ctx.userId,
+      },
+    })
+  },
+
+  async delete(ctx: TenantContext, projectId: string) {
+    // Only owners and admins can delete
+    if (!['owner', 'admin'].includes(ctx.role)) {
+      throw new ApiError('FORBIDDEN', 'Insufficient permissions', 403)
+    }
+
+    const project = await this.getById(ctx, projectId)
+
+    await db.project.delete({ where: { id: project.id } })
+  },
+}
+
+// --- Route handler using tenant context ---
+
+import { NextRequest, NextResponse } from 'next/server'
+
+export async function GET(
+  req: NextRequest,
+  { params }: { params: { workspaceId: string } }
+) {
+  const ctx: TenantContext = {
+    workspaceId: req.headers.get('x-workspace-id')!,
+    userId: req.headers.get('x-user-id')!,
+    role: req.headers.get('x-workspace-role') as TenantContext['role'],
+  }
+
+  const projects = await projectService.list(ctx)
+  return NextResponse.json({ projects })
+}
+
+// --- Schema pattern (Prisma) ---
+/*
+model Workspace {
+  id        String   @id @default(cuid())
+  name      String
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  members  WorkspaceMember[]
+  projects Project[]
+}
+
+model WorkspaceMember {
+  workspaceId String
+  userId      String
+  role        WorkspaceRole @default(MEMBER)
+  joinedAt    DateTime      @default(now())
+
+  workspace Workspace @relation(fields: [workspaceId], references: [id])
+  user      User      @relation(fields: [userId], references: [id])
+
+  @@id([workspaceId, userId])
+  @@index([userId])  // Fast lookup: "which workspaces is this user in?"
+}
+
+enum WorkspaceRole {
+  OWNER
+  ADMIN
+  MEMBER
+  VIEWER
+}
+
+model Project {
+  id          String   @id @default(cuid())
+  name        String
+  workspaceId String   // Always scoped to workspace
+  createdById String
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  workspace Workspace @relation(fields: [workspaceId], references: [id])
+  createdBy User      @relation(fields: [createdById], references: [id])
+
+  @@index([workspaceId])  // All queries filter by workspace
+}
+*/
+
+// --- Composite primary keys for org-scoped tables ---
+// Tables with natural keys need UNIQUE(natural_key, org_id) to prevent
+// cross-tenant collisions. A widgetId might be unique within Org A but
+// Org B can independently create the same widgetId. Without a composite
+// constraint the second insert silently overwrites or fails.
+//
+// Prisma schema:
+/*
+model WidgetState {
+  id          String   @id @default(cuid())
+  widgetId    String                        // Natural key — unique per org, not globally
+  workspaceId String
+  state       Json
+  updatedAt   DateTime @updatedAt
+
+  workspace Workspace @relation(fields: [workspaceId], references: [id])
+
+  @@unique([widgetId, workspaceId])         // Prevents cross-tenant collision
+  @@index([workspaceId])                    // Tenant-scoped queries stay fast
+}
+*/
+//
+// Django equivalent:
+//   class Meta:
+//       constraints = [
+//           models.UniqueConstraint(fields=['widget_id', 'org'], name='unique_widget_per_org')
+//       ]
+//
+// Rails equivalent:
+//   add_index :widget_states, [:widget_id, :workspace_id], unique: true
+//
+// Rule: any column that acts as a "slug", "external_id", or "name" within
+// a tenant MUST have a composite unique constraint including the tenant FK.
+
+// --- Django equivalent ---
+/*
+# middleware.py
+class TenantMiddleware:
+    def __call__(self, request):
+        workspace_id = resolve_workspace_from_url(request.path)
+        if workspace_id:
+            membership = WorkspaceMember.objects.filter(
+                workspace_id=workspace_id, user=request.user
+            ).first()
+            if not membership:
+                return JsonResponse({'error': 'Not found'}, status=404)
+            request.workspace = membership.workspace
+            request.workspace_role = membership.role
+        return self.get_response(request)
+
+# services.py
+class ProjectService:
+    @staticmethod
+    def list(workspace):
+        return Project.objects.filter(workspace=workspace)
+
+    @staticmethod
+    def create(workspace, user, name):
+        return Project.objects.create(
+            workspace=workspace, created_by=user, name=name
+        )
+*/
+
+// --- Rails equivalent ---
+/*
+# app/controllers/concerns/tenant_scoped.rb
+module TenantScoped
+  extend ActiveSupport::Concern
+
+  before_action :set_workspace
+
+  private
+
+  def set_workspace
+    @workspace = current_user.workspaces.find_by(id: params[:workspace_id])
+    head :not_found unless @workspace
+    @membership = @workspace.memberships.find_by(user: current_user)
+  end
+
+  def authorize_role!(*roles)
+    head :forbidden unless roles.include?(@membership.role.to_sym)
+  end
+end
+*/
+
+// --- Per-tenant credential store ---
+// Encrypted API key storage — keys never leave the server in plaintext.
+// AES-256-GCM at rest, key derived from org-specific master key.
+// Write-only admin API: responses contain metadata only (provider, timestamps).
+
+interface TenantCredential {
+  orgId: string
+  provider: string           // e.g. 'stripe', 'openai', 'tiktok'
+  encryptedKey: Buffer       // AES-256-GCM ciphertext + IV + auth tag
+  verifiedAt: Date | null    // Last successful probe — null if never verified
+  revokedAt: Date | null     // Soft-delete: non-null means revoked
+}
+
+interface CredentialMetadata {
+  provider: string
+  createdAt: Date
+  verifiedAt: Date | null
+  isRevoked: boolean
+}
+
+class CredentialStore {
+  constructor(private readonly masterKeyProvider: (orgId: string) => Promise<Buffer>) {}
+
+  /** Store a new credential. Runs a verification probe before persisting. */
+  async store(orgId: string, provider: string, plainKey: string): Promise<void> {
+    await this.verifyProbe(provider, plainKey)           // Fail fast if key is invalid
+    const masterKey = await this.masterKeyProvider(orgId)
+    const encrypted = encryptAes256Gcm(plainKey, masterKey)
+    await db.tenantCredential.create({
+      data: { orgId, provider, encryptedKey: encrypted, verifiedAt: new Date() },
+    })
+  }
+
+  /** Decrypt for server-side use only — NEVER expose in an API response. */
+  async getDecrypted(orgId: string, provider: string): Promise<string> {
+    const cred = await this.findActiveCredential(orgId, provider)
+    const masterKey = await this.masterKeyProvider(orgId)
+    return decryptAes256Gcm(cred.encryptedKey, masterKey)
+  }
+
+  /** List credentials as metadata — no secrets returned. */
+  async listMetadata(orgId: string): Promise<CredentialMetadata[]> {
+    const creds = await db.tenantCredential.findMany({ where: { orgId } })
+    return creds.map(c => ({
+      provider: c.provider,
+      createdAt: c.createdAt,
+      verifiedAt: c.verifiedAt,
+      isRevoked: c.revokedAt !== null,
+    }))
+  }
+
+  /** Soft-revoke: marks revokedAt, old key ignored after grace period. */
+  async revoke(orgId: string, provider: string): Promise<void> {
+    await db.tenantCredential.updateMany({
+      where: { orgId, provider, revokedAt: null },
+      data: { revokedAt: new Date() },
+    })
+  }
+
+  private async findActiveCredential(orgId: string, provider: string) {
+    const cred = await db.tenantCredential.findFirst({
+      where: { orgId, provider, revokedAt: null },
+      orderBy: { createdAt: 'desc' },
+    })
+    if (!cred) throw new ApiError('NOT_FOUND', `No active credential for ${provider}`, 404)
+    return cred
+  }
+
+  /** Provider-specific liveness check before storing a key. */
+  private async verifyProbe(provider: string, key: string): Promise<void> {
+    // Each provider adapter exposes a lightweight health endpoint.
+    // Throws ApiError('INVALID_CREDENTIAL') if the key fails.
+  }
+}

package/dist/docs/patterns/oauth-token-lifecycle.ts

@@ -0,0 +1,223 @@
+/**
+ * Pattern: OAuth Token Lifecycle
+ *
+ * Key principles:
+ * - Refresh at 80% of TTL (not at expiry — prevents race conditions)
+ * - Multi-grant-type support (authorization_code, refresh_token)
+ * - Vault integration — tokens encrypted at rest in financial vault
+ * - Failure escalation: retry 3x → pause platform → alert → requires_reauth
+ * - Token stored as encrypted blob in vault, keyed by platform name
+ * - Session token (daemon) rotates every 24 hours (§9.19.15)
+ *
+ * Agents: Breeze (platform relations), Dockson (vault)
+ *
+ * PRD Reference: §9.5 (token refresh strategy), §9.18 (vault session), §9.19.15
+ */
+
+type AdPlatform = 'meta' | 'google' | 'tiktok' | 'linkedin' | 'twitter' | 'reddit';
+
+// ── Token Types ───────────────────────────────────────
+
+interface OAuthTokenSet {
+  platform: AdPlatform;
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: string;        // ISO 8601
+  tokenType: string;        // 'Bearer'
+  scopes: string[];
+  grantedAt: string;        // ISO 8601 — when the token was first obtained
+  lastRefreshedAt: string;  // ISO 8601 — when the token was last refreshed
+}
+
+type TokenHealth = 'healthy' | 'expiring_soon' | 'expired' | 'refresh_failed' | 'requires_reauth' | 'revoked';
+
+interface TokenStatus {
+  platform: AdPlatform;
+  health: TokenHealth;
+  expiresAt: string;
+  lastRefresh: string;
+  consecutiveFailures: number;
+  error?: string;
+}
+
+// ── Platform TTL Configuration ────────────────────────
+
+interface PlatformTokenConfig {
+  platform: AdPlatform;
+  accessTokenTtlHours: number;   // How long the access token lives
+  refreshTokenTtlDays: number;   // How long the refresh token lives (0 = never expires)
+  refreshEndpoint: string;
+  revokeEndpoint?: string;
+}
+
+const PLATFORM_CONFIGS: PlatformTokenConfig[] = [
+  { platform: 'meta',     accessTokenTtlHours: 1440, refreshTokenTtlDays: 0,  refreshEndpoint: 'https://graph.facebook.com/v19.0/oauth/access_token' },
+  { platform: 'google',   accessTokenTtlHours: 1,    refreshTokenTtlDays: 0,  refreshEndpoint: 'https://oauth2.googleapis.com/token' },
+  { platform: 'tiktok',   accessTokenTtlHours: 24,   refreshTokenTtlDays: 365, refreshEndpoint: 'https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/' },
+  { platform: 'linkedin', accessTokenTtlHours: 1440, refreshTokenTtlDays: 365, refreshEndpoint: 'https://www.linkedin.com/oauth/v2/accessToken' },
+  { platform: 'twitter',  accessTokenTtlHours: 0,    refreshTokenTtlDays: 0,  refreshEndpoint: '' }, // OAuth 1.0a — tokens don't expire
+  { platform: 'reddit',   accessTokenTtlHours: 1,    refreshTokenTtlDays: 0,  refreshEndpoint: 'https://www.reddit.com/api/v1/access_token' },
+];
+
+// ── Refresh Logic ─────────────────────────────────────
+
+const REFRESH_AT_TTL_PERCENT = 0.80; // Refresh at 80% of TTL
+const MAX_CONSECUTIVE_FAILURES = 3;
+
+/**
+ * Check if a token needs refresh.
+ * Returns true if the token is past 80% of its TTL.
+ */
+function needsRefresh(token: OAuthTokenSet): boolean {
+  const config = PLATFORM_CONFIGS.find(c => c.platform === token.platform);
+  if (!config || config.accessTokenTtlHours === 0) return false; // Never expires (Twitter OAuth 1.0a)
+
+  const expiresAt = new Date(token.expiresAt).getTime();
+  const lastRefresh = new Date(token.lastRefreshedAt).getTime();
+  const ttlMs = config.accessTokenTtlHours * 60 * 60 * 1000;
+  const refreshAt = lastRefresh + (ttlMs * REFRESH_AT_TTL_PERCENT);
+
+  return Date.now() >= refreshAt;
+}
+
+/**
+ * Determine the health status of a token.
+ */
+function getTokenHealth(token: OAuthTokenSet, failures: number): TokenHealth {
+  if (failures >= MAX_CONSECUTIVE_FAILURES) return 'requires_reauth';
+
+  const now = Date.now();
+  const expiresAt = new Date(token.expiresAt).getTime();
+
+  if (expiresAt < now) return 'expired';
+
+  const config = PLATFORM_CONFIGS.find(c => c.platform === token.platform);
+  if (!config || config.accessTokenTtlHours === 0) return 'healthy'; // Never expires
+
+  const ttlMs = config.accessTokenTtlHours * 60 * 60 * 1000;
+  const warningAt = expiresAt - (ttlMs * 0.2); // Warn at 80% consumed
+
+  if (now >= warningAt) return 'expiring_soon';
+  if (failures > 0) return 'refresh_failed';
+  return 'healthy';
+}
+
+// ── Failure Escalation (§9.5) ─────────────────────────
+
+interface RefreshResult {
+  success: boolean;
+  newTokens?: OAuthTokenSet;
+  error?: string;
+  requiresReauth?: boolean;
+}
+
+/**
+ * Handle a refresh failure. Implements the escalation:
+ * 1st failure: retry after 30s
+ * 2nd failure: retry after 60s
+ * 3rd failure: pause campaigns on this platform, set requires_reauth, alert
+ *
+ * The `invalid_grant` error means the refresh token itself is expired/revoked.
+ * This does NOT count toward the 3-failure pause trigger (§9.18) —
+ * it goes straight to requires_reauth.
+ */
+function handleRefreshFailure(
+  platform: AdPlatform,
+  error: string,
+  consecutiveFailures: number
+): { action: 'retry' | 'pause_and_alert' | 'reauth'; retryAfterMs?: number } {
+  // invalid_grant = refresh token revoked/expired — immediate reauth
+  if (error.includes('invalid_grant') || error.includes('revoked')) {
+    return { action: 'reauth' };
+  }
+
+  const newCount = consecutiveFailures + 1;
+  if (newCount >= MAX_CONSECUTIVE_FAILURES) {
+    return { action: 'pause_and_alert' };
+  }
+
+  // Exponential backoff: 30s, 60s
+  const retryAfterMs = 30000 * Math.pow(2, consecutiveFailures);
+  return { action: 'retry', retryAfterMs };
+}
+
+// ── Vault Integration ─────────────────────────────────
+// Tokens are stored in the financial vault, keyed by platform name.
+// The daemon reads them at startup and holds them in memory.
+// On refresh, the daemon writes the updated token back to the vault.
+
+const TOKEN_VAULT_KEY_PREFIX = 'growth/tokens/';
+
+function tokenVaultKey(platform: AdPlatform): string {
+  return TOKEN_VAULT_KEY_PREFIX + platform;
+}
+
+/**
+ * Serialize tokens for vault storage.
+ * The vault stores strings — tokens are JSON-serialized.
+ */
+function serializeTokens(tokens: OAuthTokenSet): string {
+  return JSON.stringify(tokens);
+}
+
+function deserializeTokens(data: string): OAuthTokenSet {
+  return JSON.parse(data) as OAuthTokenSet;
+}
+
+// ── Session Token Rotation (§9.19.15) ─────────────────
+// The daemon session token (heartbeat.token) rotates every 24 hours.
+// During rotation, accept both old and new tokens for 30-second grace period.
+
+const SESSION_TOKEN_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const SESSION_TOKEN_GRACE_MS = 30 * 1000; // 30 seconds
+
+interface SessionTokenState {
+  current: string;
+  previous?: string;
+  rotatedAt: number;
+  previousExpiresAt?: number;
+}
+
+function shouldRotateSessionToken(state: SessionTokenState): boolean {
+  return Date.now() - state.rotatedAt >= SESSION_TOKEN_TTL_MS;
+}
+
+function rotateSessionToken(state: SessionTokenState, newToken: string): SessionTokenState {
+  return {
+    current: newToken,
+    previous: state.current,
+    rotatedAt: Date.now(),
+    previousExpiresAt: Date.now() + SESSION_TOKEN_GRACE_MS,
+  };
+}
+
+function validateSessionToken(provided: string, state: SessionTokenState): boolean {
+  const { timingSafeEqual } = require('node:crypto');
+
+  // Check current token
+  if (provided.length === state.current.length) {
+    const a = Buffer.from(provided);
+    const b = Buffer.from(state.current);
+    if (timingSafeEqual(a, b)) return true;
+  }
+
+  // Check previous token during grace period
+  if (state.previous && state.previousExpiresAt && Date.now() < state.previousExpiresAt) {
+    if (provided.length === state.previous.length) {
+      const a = Buffer.from(provided);
+      const b = Buffer.from(state.previous);
+      if (timingSafeEqual(a, b)) return true;
+    }
+  }
+
+  return false;
+}
+
+export type { OAuthTokenSet, TokenHealth, TokenStatus, PlatformTokenConfig, RefreshResult, SessionTokenState };
+export {
+  PLATFORM_CONFIGS, REFRESH_AT_TTL_PERCENT, MAX_CONSECUTIVE_FAILURES,
+  needsRefresh, getTokenHealth, handleRefreshFailure,
+  tokenVaultKey, serializeTokens, deserializeTokens,
+  SESSION_TOKEN_TTL_MS, SESSION_TOKEN_GRACE_MS,
+  shouldRotateSessionToken, rotateSessionToken, validateSessionToken,
+};