#259 Implement Platform Tenant (_platform) for super admin access

## Overview Implement a special '_platform' tenant that serves as the administrative domain for platform-level operations. Users with roles in this tenant can perform cross-tenant platform operations (like managing customer tenants). ## Design Decisions ### Core Architecture - Special tenant ID: `_platform` (underscore prefix = system tenant) - Reuses existing RBAC infrastructure (auth library, middleware, audit logging) - Platform admins authenticate normally via OAuth, but have additional roles in `_platform` tenant - `_platform` is hidden from user-facing tenant lists ### Platform Roles (auth library groups) - `platform_owner`: Full platform control (can add other platform admins) - `platform_admin`: Manage tenants, view platform metrics, impersonate tenants - `platform_support`: Read-only access to tenant info for support ### Platform Permissions - `manage_tenants`: Create, update, deactivate, delete tenants - `view_all_tenants`: List all tenants with metadata - `manage_platform_admins`: Add/remove platform admins - `view_platform_metrics`: View cross-tenant analytics - `impersonate_tenant`: Access tenant data as platform admin (for support/debugging) ## Implementation Tasks ### 1. Database Setup - Add `_platform` to `tenant_client_keys` table with auto-generated client_key - Add `is_system_tenant` column to identify system tenants (optional) ### 2. Auth Library Setup - Create roles and permissions for `_platform` tenant using auth library API - Use existing `get_auth_for_tenant(conn, '_platform')` pattern ### 3. RBAC Middleware - Add `@require_platform_permission(permission)` decorator - Check if user has role in `_platform` tenant for platform operations - Works alongside existing tenant-scoped `@require_permission` ### 4. Bootstrap CLI - `hwe platform init`: Create _platform tenant and roles/permissions - `hwe platform add-admin --email X --role platform_owner`: Add platform admin - Environment variable `PLATFORM_OWNER_EMAIL` for initial bootstrap ### 5. Hide System Tenants - Update `GET /api/v1/tenants` to exclude tenants starting with `_` - System tenants only visible via platform admin APIs ### 6. Tenant Impersonation Platform admins can impersonate any customer tenant for support/debugging: #### API Endpoint ``` POST /api/v1/platform/impersonate Authorization: Bearer <platform_admin_jwt> { "target_tenant_id": "customer_tenant" } Response: { "impersonation_token": "<jwt_with_target_tenant>", "expires_at": "2025-12-04T20:00:00Z", "original_user": "admin@platform.com", "target_tenant": "customer_tenant" } ``` #### Security Controls - Requires `impersonate_tenant` permission in `_platform` tenant - Impersonation JWT contains special claims: `impersonated: true`, `original_email`, `original_tenant` - Short expiration (1 hour max) - All actions with impersonation token are audit logged with original user identity - Cannot impersonate `_platform` tenant itself #### Audit Trail Every API call with impersonation token logs: - Original platform admin email - Target tenant being accessed - Action performed - Timestamp ## Security Considerations - Platform admins can ONLY access customer data via explicit impersonation - All platform operations are audit logged via auth library - Impersonation requires explicit permission and comprehensive logging - OAuth login already verifies user has at least one tenant role before issuing JWT - Impersonation tokens are clearly marked and short-lived ## Dependencies - Auth library (already integrated) - Vault access for secrets - Existing RBAC middleware ## Blocks - Issue #258: Implement super admin tenant management APIs (needs this first)