icdev 0.0.3__py3-none-any.whl

tools/forge_studio/enterprise/whitelabel_engine.py

@@ -0,0 +1,887 @@
+# CUI // SP-CTI
+"""White-label engine — full theme customization, custom domains, email templates,
+and login page branding for Forge Studio tenants.
+
+Extends the tenant_manager branding system with:
+- Complete CSS theme engine (colors, fonts, spacing, shadows, component styles)
+- Custom domain mapping
+- Email template customization (welcome, reset_password, invite)
+- Custom login page generation
+- Legal page configuration (privacy, terms, support)
+- Feature flags (hide_powered_by, custom_favicon, custom_404)
+- Comprehensive branding injection into ejected apps
+
+Architecture decision: D-FS-P6-3 — White-label extends tenant_manager branding
+with full theme engine, custom domains, email templates, and login page customization.
+
+CLI: python tools/forge_studio/enterprise/whitelabel_engine.py --configure --tenant-id "..." --json
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from tools.forge_studio.audit import log_forge_event
+
+logger = logging.getLogger("forge_studio.enterprise.whitelabel")
+
+# ---------------------------------------------------------------------------
+# Default theme
+# ---------------------------------------------------------------------------
+
+DEFAULT_THEME: Dict[str, Any] = {
+    "colors": {
+        "primary": "#6366f1",
+        "secondary": "#8b5cf6",
+        "accent": "#06b6d4",
+        "background": "#0f172a",
+        "surface": "#1e293b",
+        "text": "#f8fafc",
+        "text_muted": "#94a3b8",
+        "success": "#22c55e",
+        "warning": "#f59e0b",
+        "error": "#ef4444",
+    },
+    "fonts": {
+        "heading": "Inter, system-ui, sans-serif",
+        "body": "Inter, system-ui, sans-serif",
+        "mono": "JetBrains Mono, Fira Code, monospace",
+    },
+    "spacing": {
+        "unit": "0.25rem",
+        "page_padding": "2rem",
+        "card_padding": "1.5rem",
+        "input_padding": "0.75rem 1rem",
+    },
+    "border_radius": {
+        "small": "0.25rem",
+        "medium": "0.5rem",
+        "large": "0.75rem",
+        "full": "9999px",
+    },
+    "shadows": {
+        "small": "0 1px 2px rgba(0,0,0,0.05)",
+        "medium": "0 4px 6px -1px rgba(0,0,0,0.1)",
+        "large": "0 10px 15px -3px rgba(0,0,0,0.1)",
+    },
+    "header_style": {
+        "height": "64px",
+        "background": "var(--fs-surface)",
+        "border_bottom": "1px solid rgba(255,255,255,0.1)",
+    },
+    "sidebar_style": {
+        "width": "260px",
+        "background": "var(--fs-surface)",
+        "border_right": "1px solid rgba(255,255,255,0.1)",
+    },
+}
+
+DEFAULT_LEGAL: Dict[str, Any] = {
+    "privacy_url": "",
+    "terms_url": "",
+    "support_url": "",
+    "company_name": "",
+    "copyright_text": "",
+}
+
+DEFAULT_EMAIL_TEMPLATES: Dict[str, Any] = {
+    "welcome": {
+        "subject": "Welcome to {{app_title}}",
+        "body_html": "<h1>Welcome, {{user_name}}!</h1><p>Your account is ready.</p>",
+    },
+    "reset_password": {
+        "subject": "Reset your {{app_title}} password",
+        "body_html": "<h1>Password Reset</h1><p>Click <a href='{{reset_url}}'>here</a> to reset.</p>",
+    },
+    "invite": {
+        "subject": "You've been invited to {{app_title}}",
+        "body_html": "<h1>You're Invited</h1><p>{{inviter_name}} invited you. <a href='{{invite_url}}'>Join now</a>.</p>",
+    },
+}
+
+DEFAULT_FEATURE_FLAGS: Dict[str, Any] = {
+    "hide_powered_by": False,
+    "custom_favicon": False,
+    "custom_404": False,
+}
+
+# ---------------------------------------------------------------------------
+# DB schema
+# ---------------------------------------------------------------------------
+
+WHITELABEL_SCHEMA = """
+CREATE TABLE IF NOT EXISTS forge_studio_whitelabel_configs (
+    id TEXT PRIMARY KEY,
+    tenant_id TEXT NOT NULL UNIQUE,
+    custom_domain TEXT,
+    custom_login_html TEXT,
+    email_from_name TEXT,
+    email_from_address TEXT,
+    email_templates_json TEXT,
+    theme_json TEXT NOT NULL,
+    legal_json TEXT,
+    feature_flags_json TEXT,
+    generated_css TEXT,
+    status TEXT DEFAULT 'active' CHECK(status IN ('active','disabled','archived')),
+    classification TEXT DEFAULT 'CUI // SP-CTI',
+    created_at TEXT NOT NULL,
+    updated_at TEXT
+);
+"""
+
+
+def ensure_whitelabel_tables():
+    """Create white-label tables if they don't exist."""
+    from tools.db.storage import get_connection
+
+    with get_connection() as conn:
+        for stmt in WHITELABEL_SCHEMA.split(";"):
+            s = stmt.strip()
+            if s and not s.startswith("--"):
+                conn.execute(s)
+
+    logger.info("Forge Studio whitelabel tables ensured")
+
+
+# ---------------------------------------------------------------------------
+# Theme CSS compiler
+# ---------------------------------------------------------------------------
+
+def compile_theme_css(theme_dict: Dict[str, Any]) -> str:
+    """Generate CSS custom properties and component overrides from a theme dict.
+
+    Produces:
+    - :root CSS custom properties (--fs-primary, --fs-secondary, etc.)
+    - Component-level style overrides (buttons, cards, inputs, sidebar, header)
+
+    Args:
+        theme_dict: Theme configuration following DEFAULT_THEME structure.
+
+    Returns:
+        Complete CSS string ready for injection.
+    """
+    theme = {**DEFAULT_THEME}
+    # Deep merge top-level keys
+    for key in theme:
+        if key in theme_dict and isinstance(theme[key], dict):
+            theme[key] = {**theme[key], **theme_dict[key]}
+        elif key in theme_dict:
+            theme[key] = theme_dict[key]
+
+    colors = theme.get("colors", {})
+    fonts = theme.get("fonts", {})
+    spacing = theme.get("spacing", {})
+    radius = theme.get("border_radius", {})
+    shadows = theme.get("shadows", {})
+    header = theme.get("header_style", {})
+    sidebar = theme.get("sidebar_style", {})
+
+    css_parts = []
+
+    # --- Root custom properties ---
+    css_parts.append(""":root {
+  /* Colors */
+  --fs-primary: %(primary)s;
+  --fs-secondary: %(secondary)s;
+  --fs-accent: %(accent)s;
+  --fs-bg: %(background)s;
+  --fs-surface: %(surface)s;
+  --fs-text: %(text)s;
+  --fs-text-muted: %(text_muted)s;
+  --fs-success: %(success)s;
+  --fs-warning: %(warning)s;
+  --fs-error: %(error)s;
+
+  /* Fonts */
+  --fs-font-heading: %(font_heading)s;
+  --fs-font-body: %(font_body)s;
+  --fs-font-mono: %(font_mono)s;
+
+  /* Spacing */
+  --fs-spacing-unit: %(spacing_unit)s;
+  --fs-page-padding: %(page_padding)s;
+  --fs-card-padding: %(card_padding)s;
+  --fs-input-padding: %(input_padding)s;
+
+  /* Border radius */
+  --fs-radius-sm: %(radius_small)s;
+  --fs-radius: %(radius_medium)s;
+  --fs-radius-lg: %(radius_large)s;
+  --fs-radius-full: %(radius_full)s;
+
+  /* Shadows */
+  --fs-shadow-sm: %(shadow_small)s;
+  --fs-shadow: %(shadow_medium)s;
+  --fs-shadow-lg: %(shadow_large)s;
+}""" % {
+        "primary": colors.get("primary", "#6366f1"),
+        "secondary": colors.get("secondary", "#8b5cf6"),
+        "accent": colors.get("accent", "#06b6d4"),
+        "background": colors.get("background", "#0f172a"),
+        "surface": colors.get("surface", "#1e293b"),
+        "text": colors.get("text", "#f8fafc"),
+        "text_muted": colors.get("text_muted", "#94a3b8"),
+        "success": colors.get("success", "#22c55e"),
+        "warning": colors.get("warning", "#f59e0b"),
+        "error": colors.get("error", "#ef4444"),
+        "font_heading": fonts.get("heading", "Inter, system-ui, sans-serif"),
+        "font_body": fonts.get("body", "Inter, system-ui, sans-serif"),
+        "font_mono": fonts.get("mono", "JetBrains Mono, Fira Code, monospace"),
+        "spacing_unit": spacing.get("unit", "0.25rem"),
+        "page_padding": spacing.get("page_padding", "2rem"),
+        "card_padding": spacing.get("card_padding", "1.5rem"),
+        "input_padding": spacing.get("input_padding", "0.75rem 1rem"),
+        "radius_small": radius.get("small", "0.25rem"),
+        "radius_medium": radius.get("medium", "0.5rem"),
+        "radius_large": radius.get("large", "0.75rem"),
+        "radius_full": radius.get("full", "9999px"),
+        "shadow_small": shadows.get("small", "0 1px 2px rgba(0,0,0,0.05)"),
+        "shadow_medium": shadows.get("medium", "0 4px 6px -1px rgba(0,0,0,0.1)"),
+        "shadow_large": shadows.get("large", "0 10px 15px -3px rgba(0,0,0,0.1)"),
+    })
+
+    # --- Component overrides: buttons ---
+    css_parts.append("""
+/* Button styles */
+.fs-btn, .btn-primary, [data-fs-btn] {
+  background: var(--fs-primary);
+  color: var(--fs-text);
+  font-family: var(--fs-font-body);
+  border-radius: var(--fs-radius);
+  padding: 0.625rem 1.25rem;
+  border: none;
+  cursor: pointer;
+  box-shadow: var(--fs-shadow-sm);
+  transition: background 0.2s, box-shadow 0.2s;
+}
+.fs-btn:hover, .btn-primary:hover, [data-fs-btn]:hover {
+  background: var(--fs-secondary);
+  box-shadow: var(--fs-shadow);
+}""")
+
+    # --- Component overrides: cards ---
+    css_parts.append("""
+/* Card styles */
+.fs-card, .card, [data-fs-card] {
+  background: var(--fs-surface);
+  border-radius: var(--fs-radius-lg);
+  padding: var(--fs-card-padding);
+  box-shadow: var(--fs-shadow);
+  color: var(--fs-text);
+}""")
+
+    # --- Component overrides: inputs ---
+    css_parts.append("""
+/* Input styles */
+.fs-input, input[type="text"], input[type="email"], input[type="password"],
+textarea, select, [data-fs-input] {
+  background: var(--fs-bg);
+  color: var(--fs-text);
+  border: 1px solid var(--fs-surface);
+  border-radius: var(--fs-radius);
+  padding: var(--fs-input-padding);
+  font-family: var(--fs-font-body);
+  transition: border-color 0.2s;
+}
+.fs-input:focus, input:focus, textarea:focus, select:focus {
+  border-color: var(--fs-primary);
+  outline: none;
+}""")
+
+    # --- Component overrides: sidebar ---
+    sidebar_width = sidebar.get("width", "260px")
+    sidebar_bg = sidebar.get("background", "var(--fs-surface)")
+    sidebar_border = sidebar.get("border_right", "1px solid rgba(255,255,255,0.1)")
+    css_parts.append("""
+/* Sidebar styles */
+.fs-sidebar, [data-fs-sidebar] {
+  width: %s;
+  background: %s;
+  border-right: %s;
+  color: var(--fs-text);
+}""" % (sidebar_width, sidebar_bg, sidebar_border))
+
+    # --- Component overrides: header ---
+    header_height = header.get("height", "64px")
+    header_bg = header.get("background", "var(--fs-surface)")
+    header_border = header.get("border_bottom", "1px solid rgba(255,255,255,0.1)")
+    css_parts.append("""
+/* Header styles */
+.fs-header, [data-fs-header] {
+  height: %s;
+  background: %s;
+  border-bottom: %s;
+  color: var(--fs-text);
+  display: flex;
+  align-items: center;
+  padding: 0 var(--fs-page-padding);
+}""" % (header_height, header_bg, header_border))
+
+    # --- Base body ---
+    css_parts.append("""
+/* Base body */
+body {
+  background: var(--fs-bg);
+  color: var(--fs-text);
+  font-family: var(--fs-font-body);
+  margin: 0;
+  padding: 0;
+}
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--fs-font-heading);
+}
+code, pre {
+  font-family: var(--fs-font-mono);
+}""")
+
+    return "\n".join(css_parts)
+
+
+# ---------------------------------------------------------------------------
+# White-label CRUD
+# ---------------------------------------------------------------------------
+
+def configure_whitelabel(
+    tenant_id: str,
+    config_dict: Dict[str, Any],
+    project_id: str = "",
+) -> Dict[str, Any]:
+    """Configure or update white-label settings for a tenant.
+
+    Args:
+        tenant_id: Tenant identifier (must exist in forge_studio_tenants).
+        config_dict: Configuration with optional keys:
+            - custom_domain: str
+            - custom_login_html: str
+            - email_from_name: str
+            - email_from_address: str
+            - email_templates: dict (welcome, reset_password, invite)
+            - theme: dict (colors, fonts, spacing, border_radius, shadows, etc.)
+            - legal: dict (privacy_url, terms_url, support_url, company_name, copyright_text)
+            - feature_flags: dict (hide_powered_by, custom_favicon, custom_404)
+        project_id: Project context for audit trail.
+
+    Returns:
+        {status, config_id, config}
+    """
+    from tools.db.storage import get_connection
+
+    now = datetime.now(timezone.utc).isoformat()
+
+    # Merge theme with defaults
+    theme = {**DEFAULT_THEME}
+    if "theme" in config_dict and isinstance(config_dict["theme"], dict):
+        for key in theme:
+            if key in config_dict["theme"] and isinstance(theme[key], dict):
+                theme[key] = {**theme[key], **config_dict["theme"][key]}
+            elif key in config_dict["theme"]:
+                theme[key] = config_dict["theme"][key]
+
+    # Merge other configs
+    legal = {**DEFAULT_LEGAL, **(config_dict.get("legal") or {})}
+    email_templates = {**DEFAULT_EMAIL_TEMPLATES, **(config_dict.get("email_templates") or {})}
+    feature_flags = {**DEFAULT_FEATURE_FLAGS, **(config_dict.get("feature_flags") or {})}
+
+    # Compile CSS from theme
+    generated_css = compile_theme_css(theme)
+
+    # Check for existing config
+    with get_connection() as conn:
+        existing = conn.execute(
+            "SELECT id FROM forge_studio_whitelabel_configs WHERE tenant_id = ?",
+            (tenant_id,),
+        ).fetchone()
+
+    if existing:
+        config_id = existing[0]
+        with get_connection() as conn:
+            conn.execute(
+                "UPDATE forge_studio_whitelabel_configs SET "
+                "custom_domain = ?, custom_login_html = ?, email_from_name = ?, "
+                "email_from_address = ?, email_templates_json = ?, theme_json = ?, "
+                "legal_json = ?, feature_flags_json = ?, generated_css = ?, "
+                "status = ?, updated_at = ? "
+                "WHERE id = ?",
+                (
+                    config_dict.get("custom_domain", ""),
+                    config_dict.get("custom_login_html", ""),
+                    config_dict.get("email_from_name", ""),
+                    config_dict.get("email_from_address", ""),
+                    json.dumps(email_templates),
+                    json.dumps(theme),
+                    json.dumps(legal),
+                    json.dumps(feature_flags),
+                    generated_css,
+                    "active",
+                    now,
+                    config_id,
+                ),
+            )
+    else:
+        config_id = f"wl-{uuid.uuid4().hex[:12]}"
+        with get_connection() as conn:
+            conn.execute(
+                "INSERT INTO forge_studio_whitelabel_configs "
+                "(id, tenant_id, custom_domain, custom_login_html, email_from_name, "
+                "email_from_address, email_templates_json, theme_json, legal_json, "
+                "feature_flags_json, generated_css, status, classification, "
+                "created_at, updated_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    config_id, tenant_id,
+                    config_dict.get("custom_domain", ""),
+                    config_dict.get("custom_login_html", ""),
+                    config_dict.get("email_from_name", ""),
+                    config_dict.get("email_from_address", ""),
+                    json.dumps(email_templates),
+                    json.dumps(theme),
+                    json.dumps(legal),
+                    json.dumps(feature_flags),
+                    generated_css,
+                    "active",
+                    "CUI // SP-CTI",
+                    now, now,
+                ),
+            )
+
+    config = {
+        "id": config_id,
+        "tenant_id": tenant_id,
+        "custom_domain": config_dict.get("custom_domain", ""),
+        "theme": theme,
+        "legal": legal,
+        "email_templates": email_templates,
+        "feature_flags": feature_flags,
+        "status": "active",
+        "created_at": now,
+    }
+
+    log_forge_event("forge_studio_whitelabel_configured", {
+        "config_id": config_id,
+        "tenant_id": tenant_id,
+        "custom_domain": config_dict.get("custom_domain", ""),
+        "feature_flags": feature_flags,
+    }, project_id=project_id)
+
+    return {"status": "success", "config_id": config_id, "config": config}
+
+
+def get_whitelabel_config(tenant_id: str) -> Optional[Dict[str, Any]]:
+    """Get white-label configuration for a tenant.
+
+    Args:
+        tenant_id: Tenant identifier.
+
+    Returns:
+        Config dict or None if not configured.
+    """
+    from tools.db.storage import get_connection
+
+    with get_connection() as conn:
+        row = conn.execute(
+            "SELECT id, tenant_id, custom_domain, custom_login_html, "
+            "email_from_name, email_from_address, email_templates_json, "
+            "theme_json, legal_json, feature_flags_json, generated_css, "
+            "status, created_at, updated_at "
+            "FROM forge_studio_whitelabel_configs WHERE tenant_id = ?",
+            (tenant_id,),
+        ).fetchone()
+
+    if not row:
+        return None
+
+    return {
+        "id": row[0],
+        "tenant_id": row[1],
+        "custom_domain": row[2],
+        "custom_login_html": row[3],
+        "email_from_name": row[4],
+        "email_from_address": row[5],
+        "email_templates": json.loads(row[6]) if row[6] else DEFAULT_EMAIL_TEMPLATES,
+        "theme": json.loads(row[7]) if row[7] else DEFAULT_THEME,
+        "legal": json.loads(row[8]) if row[8] else DEFAULT_LEGAL,
+        "feature_flags": json.loads(row[9]) if row[9] else DEFAULT_FEATURE_FLAGS,
+        "generated_css": row[10] or "",
+        "status": row[11],
+        "created_at": row[12],
+        "updated_at": row[13],
+    }
+
+
+def list_whitelabel_configs() -> List[Dict[str, Any]]:
+    """List all white-label configurations.
+
+    Returns:
+        List of config summary dicts.
+    """
+    from tools.db.storage import get_connection
+
+    with get_connection() as conn:
+        rows = conn.execute(
+            "SELECT id, tenant_id, custom_domain, status, created_at, updated_at "
+            "FROM forge_studio_whitelabel_configs ORDER BY created_at DESC",
+        ).fetchall()
+
+    return [
+        {
+            "id": r[0], "tenant_id": r[1], "custom_domain": r[2],
+            "status": r[3], "created_at": r[4], "updated_at": r[5],
+        }
+        for r in rows
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Login page generator
+# ---------------------------------------------------------------------------
+
+def generate_login_page(tenant_id: str) -> str:
+    """Generate a branded login page HTML for a tenant.
+
+    Uses the tenant's white-label theme, logo, and company name.
+    Falls back to defaults if no white-label config exists.
+
+    Args:
+        tenant_id: Tenant identifier.
+
+    Returns:
+        Complete HTML string for the login page.
+    """
+    from tools.forge_studio.tenant_manager import get_tenant
+
+    config = get_whitelabel_config(tenant_id)
+    tenant = get_tenant(tenant_id)
+
+    # If tenant has custom login HTML, use that directly
+    if config and config.get("custom_login_html"):
+        return config["custom_login_html"]
+
+    # Build from theme
+    theme = config.get("theme", DEFAULT_THEME) if config else DEFAULT_THEME
+    legal = config.get("legal", DEFAULT_LEGAL) if config else DEFAULT_LEGAL
+    css = config.get("generated_css", "") if config else compile_theme_css(DEFAULT_THEME)
+
+    branding = tenant.get("branding", {}) if tenant else {}
+    app_title = branding.get("app_title", "") or (tenant.get("name", "Application") if tenant else "Application")
+    logo_url = branding.get("logo_url", "")
+    company_name = legal.get("company_name", "") or app_title
+    copyright_text = legal.get("copyright_text", "") or f"&copy; {company_name}"
+    privacy_url = legal.get("privacy_url", "")
+    terms_url = legal.get("terms_url", "")
+
+    logo_html = f'<img src="{logo_url}" alt="{app_title}" class="login-logo" />' if logo_url else ""
+
+    legal_links = []
+    if privacy_url:
+        legal_links.append(f'<a href="{privacy_url}">Privacy Policy</a>')
+    if terms_url:
+        legal_links.append(f'<a href="{terms_url}">Terms of Service</a>')
+    legal_html = " &middot; ".join(legal_links) if legal_links else ""
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Sign In &mdash; {app_title}</title>
+  <style>
+{css}
+
+.login-container {{
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--fs-bg);
+  padding: 2rem;
+}}
+.login-card {{
+  background: var(--fs-surface);
+  border-radius: var(--fs-radius-lg);
+  padding: 2.5rem;
+  width: 100%;
+  max-width: 420px;
+  box-shadow: var(--fs-shadow-lg);
+}}
+.login-logo {{
+  max-height: 48px;
+  margin-bottom: 1.5rem;
+}}
+.login-title {{
+  font-family: var(--fs-font-heading);
+  font-size: 1.5rem;
+  color: var(--fs-text);
+  margin: 0 0 0.5rem;
+}}
+.login-subtitle {{
+  color: var(--fs-text-muted);
+  margin: 0 0 2rem;
+  font-size: 0.875rem;
+}}
+.login-field {{
+  margin-bottom: 1.25rem;
+}}
+.login-field label {{
+  display: block;
+  color: var(--fs-text-muted);
+  font-size: 0.8125rem;
+  margin-bottom: 0.375rem;
+}}
+.login-field input {{
+  width: 100%;
+  box-sizing: border-box;
+}}
+.login-btn {{
+  width: 100%;
+  padding: 0.75rem;
+  font-size: 1rem;
+  font-weight: 600;
+  margin-top: 0.5rem;
+}}
+.login-footer {{
+  text-align: center;
+  margin-top: 2rem;
+  color: var(--fs-text-muted);
+  font-size: 0.75rem;
+}}
+.login-footer a {{
+  color: var(--fs-accent);
+  text-decoration: none;
+}}
+  </style>
+</head>
+<body>
+  <div class="login-container">
+    <div class="login-card">
+      {logo_html}
+      <h1 class="login-title">Sign in to {app_title}</h1>
+      <p class="login-subtitle">Enter your credentials to continue</p>
+      <form method="POST" action="/auth/login">
+        <div class="login-field">
+          <label for="email">Email</label>
+          <input type="email" id="email" name="email" placeholder="you@example.com" required />
+        </div>
+        <div class="login-field">
+          <label for="password">Password</label>
+          <input type="password" id="password" name="password" placeholder="Your password" required />
+        </div>
+        <button type="submit" class="fs-btn login-btn">Sign In</button>
+      </form>
+      <div class="login-footer">
+        <p>{copyright_text}</p>
+        {f'<p>{legal_html}</p>' if legal_html else ''}
+      </div>
+    </div>
+  </div>
+</body>
+</html>"""
+
+
+# ---------------------------------------------------------------------------
+# Eject injection (comprehensive)
+# ---------------------------------------------------------------------------
+
+def inject_whitelabel_into_eject(
+    tenant_id: str,
+    output_dir: str,
+) -> Dict[str, Any]:
+    """Inject comprehensive white-label branding into an ejected app directory.
+
+    Writes:
+    - globals.css with full theme CSS
+    - Custom favicon placeholder
+    - Legal pages (privacy.html, terms.html)
+    - manifest.json updates
+    - Login page
+
+    Args:
+        tenant_id: Tenant identifier.
+        output_dir: Ejected app root directory.
+
+    Returns:
+        {status, files_written: [list of paths]}
+    """
+    from tools.forge_studio.tenant_manager import get_tenant
+
+    config = get_whitelabel_config(tenant_id)
+    tenant = get_tenant(tenant_id)
+
+    if not config:
+        return {"status": "skipped", "reason": "No whitelabel config", "files_written": []}
+
+    theme = config.get("theme", DEFAULT_THEME)
+    legal = config.get("legal", DEFAULT_LEGAL)
+    feature_flags = config.get("feature_flags", DEFAULT_FEATURE_FLAGS)
+    branding = tenant.get("branding", {}) if tenant else {}
+    app_title = branding.get("app_title", "") or (tenant.get("name", "Application") if tenant else "Application")
+
+    files_written = []
+
+    # Ensure output dirs
+    os.makedirs(os.path.join(output_dir, "public"), exist_ok=True)
+    os.makedirs(os.path.join(output_dir, "app"), exist_ok=True)
+
+    # 1. globals.css — full theme
+    css_path = os.path.join(output_dir, "app", "globals.css")
+    generated_css = config.get("generated_css", "") or compile_theme_css(theme)
+    existing_css = ""
+    if os.path.exists(css_path):
+        with open(css_path, "r", encoding="utf-8") as f:
+            existing_css = f.read()
+    with open(css_path, "w", encoding="utf-8") as f:
+        f.write(f"/* White-label theme — auto-generated */\n{generated_css}\n\n{existing_css}")
+    files_written.append(css_path)
+
+    # 2. Favicon placeholder
+    if feature_flags.get("custom_favicon"):
+        favicon_path = os.path.join(output_dir, "public", "favicon.ico")
+        if not os.path.exists(favicon_path):
+            # Write a minimal placeholder — tenant replaces with real file
+            with open(favicon_path, "wb") as f:
+                f.write(b"")  # Empty placeholder
+            files_written.append(favicon_path)
+
+    # 3. Legal pages
+    company_name = legal.get("company_name", "") or app_title
+    privacy_url = legal.get("privacy_url", "")
+    terms_url = legal.get("terms_url", "")
+
+    if privacy_url or legal.get("company_name"):
+        privacy_path = os.path.join(output_dir, "public", "privacy.html")
+        with open(privacy_path, "w", encoding="utf-8") as f:
+            f.write(f"""<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><title>Privacy Policy — {app_title}</title></head>
+<body>
+<h1>Privacy Policy</h1>
+<p>{company_name} privacy policy.</p>
+{f'<p>Full policy: <a href="{privacy_url}">{privacy_url}</a></p>' if privacy_url else ''}
+<p class="classification">CUI // SP-CTI</p>
+</body>
+</html>""")
+        files_written.append(privacy_path)
+
+    if terms_url or legal.get("company_name"):
+        terms_path = os.path.join(output_dir, "public", "terms.html")
+        with open(terms_path, "w", encoding="utf-8") as f:
+            f.write(f"""<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="UTF-8"><title>Terms of Service — {app_title}</title></head>
+<body>
+<h1>Terms of Service</h1>
+<p>{company_name} terms of service.</p>
+{f'<p>Full terms: <a href="{terms_url}">{terms_url}</a></p>' if terms_url else ''}
+<p class="classification">CUI // SP-CTI</p>
+</body>
+</html>""")
+        files_written.append(terms_path)
+
+    # 4. manifest.json
+    manifest_path = os.path.join(output_dir, "public", "manifest.json")
+    manifest = {
+        "name": app_title,
+        "short_name": app_title[:12],
+        "start_url": "/",
+        "display": "standalone",
+        "background_color": theme.get("colors", {}).get("background", "#0f172a"),
+        "theme_color": theme.get("colors", {}).get("primary", "#6366f1"),
+    }
+    with open(manifest_path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2)
+    files_written.append(manifest_path)
+
+    # 5. Login page
+    login_path = os.path.join(output_dir, "public", "login.html")
+    login_html = generate_login_page(tenant_id)
+    with open(login_path, "w", encoding="utf-8") as f:
+        f.write(login_html)
+    files_written.append(login_path)
+
+    return {"status": "success", "files_written": files_written}
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    import argparse
+    import sys
+
+    parser = argparse.ArgumentParser(description="Forge Studio White-Label Engine")
+    parser.add_argument("--configure", action="store_true", help="Configure white-label for a tenant")
+    parser.add_argument("--get", action="store_true", help="Get white-label config for a tenant")
+    parser.add_argument("--list", action="store_true", help="List all white-label configs")
+    parser.add_argument("--login-page", action="store_true", help="Generate login page HTML")
+    parser.add_argument("--inject", type=str, default="", help="Inject whitelabel into eject output dir")
+    parser.add_argument("--compile-css", action="store_true", help="Compile theme CSS from defaults")
+    parser.add_argument("--tenant-id", type=str, default="", help="Tenant ID")
+    parser.add_argument("--domain", type=str, default="", help="Custom domain")
+    parser.add_argument("--theme-file", type=str, default="", help="Path to theme JSON file")
+    parser.add_argument("--legal-file", type=str, default="", help="Path to legal JSON file")
+    parser.add_argument("--project-id", type=str, default="", help="Project ID for audit")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    args = parser.parse_args()
+
+    ensure_whitelabel_tables()
+
+    if args.configure:
+        if not args.tenant_id:
+            print(json.dumps({"status": "error", "error": "--tenant-id required"}))
+            sys.exit(1)
+        config_dict: Dict[str, Any] = {}
+        if args.domain:
+            config_dict["custom_domain"] = args.domain
+        if args.theme_file and os.path.exists(args.theme_file):
+            with open(args.theme_file, "r", encoding="utf-8") as f:
+                config_dict["theme"] = json.load(f)
+        if args.legal_file and os.path.exists(args.legal_file):
+            with open(args.legal_file, "r", encoding="utf-8") as f:
+                config_dict["legal"] = json.load(f)
+        result = configure_whitelabel(
+            tenant_id=args.tenant_id,
+            config_dict=config_dict,
+            project_id=args.project_id,
+        )
+    elif args.get:
+        if not args.tenant_id:
+            print(json.dumps({"status": "error", "error": "--tenant-id required"}))
+            sys.exit(1)
+        result = get_whitelabel_config(args.tenant_id) or {"status": "not_found"}
+    elif args.list:
+        result = list_whitelabel_configs()
+    elif args.login_page:
+        if not args.tenant_id:
+            print(json.dumps({"status": "error", "error": "--tenant-id required"}))
+            sys.exit(1)
+        html = generate_login_page(args.tenant_id)
+        if args.json:
+            result = {"status": "success", "html_length": len(html), "html": html}
+        else:
+            print(html)
+            sys.exit(0)
+    elif args.inject:
+        if not args.tenant_id:
+            print(json.dumps({"status": "error", "error": "--tenant-id required"}))
+            sys.exit(1)
+        result = inject_whitelabel_into_eject(args.tenant_id, args.inject)
+    elif args.compile_css:
+        css = compile_theme_css(DEFAULT_THEME)
+        if args.json:
+            result = {"status": "success", "css_length": len(css), "css": css}
+        else:
+            print(css)
+            sys.exit(0)
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+    print(json.dumps(result, indent=2, default=str))
+
+
+if __name__ == "__main__":
+    main()