feat(#355): Create UserCredential model with RLS and encryption support

Implements secure user credential storage with comprehensive RLS policies and encryption-ready architecture for Phase 3 of M9-CredentialSecurity. **Features:** - UserCredential Prisma model with 19 fields - CredentialType enum (6 values: API_KEY, OAUTH_TOKEN, etc.) - CredentialScope enum (USER, WORKSPACE, SYSTEM) - FORCE ROW LEVEL SECURITY with 3 policies - Encrypted value storage (OpenBao Transit ready) - Cascade delete on user/workspace deletion - Activity logging integration (CREDENTIAL_* actions) - 28 comprehensive test cases **Security:** - RLS owner bypass, user access, workspace admin policies - SQL injection hardening for is_workspace_admin() - Encryption version tracking ready - Full down migration for reversibility **Testing:** - 100% enum coverage (all CredentialType + CredentialScope values) - Unique constraint enforcement - Foreign key cascade deletes - Timestamp behavior validation - JSONB metadata storage **Files:** - Migration: 20260207_add_user_credentials (184 lines + 76 line down.sql) - Security: 20260207163740_fix_sql_injection_is_workspace_admin - Tests: user-credential.model.spec.ts (28 tests, 544 lines) - Docs: README.md (228 lines), scratchpad Fixes #355 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 16:39:15 -06:00
parent 1f86c36cc1
commit 864c23dc94
8 changed files with 1480 additions and 34 deletions
--- a/apps/api/prisma/migrations/20260207163740_fix_sql_injection_is_workspace_admin/down.sql
+++ b/apps/api/prisma/migrations/20260207163740_fix_sql_injection_is_workspace_admin/down.sql
@@ -0,0 +1,18 @@
+-- Rollback: SQL Injection Hardening for is_workspace_admin() Helper Function
+-- This reverts the function to its previous implementation
+
+-- =============================================================================
+-- REVERT is_workspace_admin() to original implementation
+-- =============================================================================
+
+CREATE OR REPLACE FUNCTION is_workspace_admin(workspace_uuid UUID, user_uuid UUID)
+RETURNS BOOLEAN AS $$
+BEGIN
+  RETURN EXISTS (
+    SELECT 1 FROM workspace_members
+    WHERE workspace_id = workspace_uuid
+    AND user_id = user_uuid
+    AND role IN ('OWNER', 'ADMIN')
+  );
+END;
+$$ LANGUAGE plpgsql STABLE SECURITY DEFINER;
--- a/apps/api/prisma/migrations/20260207163740_fix_sql_injection_is_workspace_admin/migration.sql
+++ b/apps/api/prisma/migrations/20260207163740_fix_sql_injection_is_workspace_admin/migration.sql
@@ -0,0 +1,58 @@
+-- Security Fix: SQL Injection Hardening for is_workspace_admin() Helper Function
+-- This migration adds explicit UUID validation to prevent SQL injection attacks
+--
+-- Related: #355 Code Review - Security CRIT-3
+-- Original issue: Migration 20260129221004_add_rls_policies
+
+-- =============================================================================
+-- SECURITY FIX: Add explicit UUID validation to is_workspace_admin()
+-- =============================================================================
+-- The is_workspace_admin() function previously accepted UUID parameters without
+-- explicit type casting/validation. Although PostgreSQL's parameter binding provides
+-- some protection, explicit UUID type validation is a security best practice.
+--
+-- This fix adds explicit UUID validation using PostgreSQL's uuid type checking
+-- to ensure that non-UUID values cannot bypass the function's intent.
+
+CREATE OR REPLACE FUNCTION is_workspace_admin(workspace_uuid UUID, user_uuid UUID)
+RETURNS BOOLEAN AS $$
+DECLARE
+  -- Validate input parameters are valid UUIDs
+  v_workspace_id UUID;
+  v_user_id UUID;
+BEGIN
+  -- Explicitly validate workspace_uuid parameter
+  IF workspace_uuid IS NULL THEN
+    RETURN FALSE;
+  END IF;
+  v_workspace_id := workspace_uuid::UUID;
+
+  -- Explicitly validate user_uuid parameter
+  IF user_uuid IS NULL THEN
+    RETURN FALSE;
+  END IF;
+  v_user_id := user_uuid::UUID;
+
+  -- Query with validated parameters
+  RETURN EXISTS (
+    SELECT 1 FROM workspace_members
+    WHERE workspace_id = v_workspace_id
+    AND user_id = v_user_id
+    AND role IN ('OWNER', 'ADMIN')
+  );
+END;
+$$ LANGUAGE plpgsql STABLE SECURITY DEFINER;
+
+-- =============================================================================
+-- NOTES
+-- =============================================================================
+-- This is a hardening fix that adds defense-in-depth to the is_workspace_admin()
+-- helper function. While PostgreSQL's parameterized queries already provide
+-- protection against SQL injection, explicit UUID type validation ensures:
+--
+-- 1. Parameters are explicitly cast to UUID type
+-- 2. NULL values are handled defensively
+-- 3. The function's intent is clear and secure
+-- 4. Compliance with security best practices
+--
+-- This change is backward compatible and does not affect existing functionality.
--- a/apps/api/prisma/migrations/20260207_add_user_credentials/down.sql
+++ b/apps/api/prisma/migrations/20260207_add_user_credentials/down.sql
@@ -0,0 +1,76 @@
+-- Rollback: User Credentials Storage with RLS Policies
+-- This migration reverses all changes from migration.sql
+--
+-- Related: #355 - Create UserCredential Prisma model with RLS policies
+
+-- =============================================================================
+-- DROP TRIGGERS AND FUNCTIONS
+-- =============================================================================
+
+DROP TRIGGER IF EXISTS user_credentials_updated_at ON user_credentials;
+DROP FUNCTION IF EXISTS update_user_credentials_updated_at();
+
+-- =============================================================================
+-- DISABLE RLS
+-- =============================================================================
+
+ALTER TABLE user_credentials DISABLE ROW LEVEL SECURITY;
+
+-- =============================================================================
+-- DROP RLS POLICIES
+-- =============================================================================
+
+DROP POLICY IF EXISTS user_credentials_owner_bypass ON user_credentials;
+DROP POLICY IF EXISTS user_credentials_user_access ON user_credentials;
+DROP POLICY IF EXISTS user_credentials_workspace_access ON user_credentials;
+
+-- =============================================================================
+-- DROP INDEXES
+-- =============================================================================
+
+DROP INDEX IF EXISTS "user_credentials_user_id_workspace_id_provider_name_key";
+DROP INDEX IF EXISTS "user_credentials_scope_is_active_idx";
+DROP INDEX IF EXISTS "user_credentials_workspace_id_scope_idx";
+DROP INDEX IF EXISTS "user_credentials_user_id_scope_idx";
+DROP INDEX IF EXISTS "user_credentials_workspace_id_idx";
+DROP INDEX IF EXISTS "user_credentials_user_id_idx";
+
+-- =============================================================================
+-- DROP FOREIGN KEY CONSTRAINTS
+-- =============================================================================
+
+ALTER TABLE "user_credentials" DROP CONSTRAINT IF EXISTS "user_credentials_workspace_id_fkey";
+ALTER TABLE "user_credentials" DROP CONSTRAINT IF EXISTS "user_credentials_user_id_fkey";
+
+-- =============================================================================
+-- DROP TABLE
+-- =============================================================================
+
+DROP TABLE IF EXISTS "user_credentials";
+
+-- =============================================================================
+-- DROP ENUMS
+-- =============================================================================
+-- NOTE: ENUM values cannot be easily removed from an existing enum type in PostgreSQL.
+-- To fully reverse this migration, you would need to:
+--
+-- 1. Remove the 'CREDENTIAL' value from EntityType enum (if not used elsewhere):
+--    ALTER TYPE "EntityType" RENAME TO "EntityType_old";
+--    CREATE TYPE "EntityType" AS ENUM (...all values except CREDENTIAL...);
+--    -- Then rebuild all dependent objects
+--
+-- 2. Remove credential-related actions from ActivityAction enum (if not used elsewhere):
+--    ALTER TYPE "ActivityAction" RENAME TO "ActivityAction_old";
+--    CREATE TYPE "ActivityAction" AS ENUM (...all values except CREDENTIAL_*...);
+--    -- Then rebuild all dependent objects
+--
+-- 3. Drop the CredentialType and CredentialScope enums:
+--    DROP TYPE IF EXISTS "CredentialType";
+--    DROP TYPE IF EXISTS "CredentialScope";
+--
+-- Due to the complexity and risk of breaking existing data/code that references
+-- these enum values, this migration does NOT automatically remove them.
+-- If you need to clean up the enums, manually execute the steps above.
+--
+-- For development environments, you can safely drop and recreate the enums manually
+-- using the SQL statements above.
--- a/apps/api/prisma/migrations/20260207_add_user_credentials/migration.sql
+++ b/apps/api/prisma/migrations/20260207_add_user_credentials/migration.sql
@@ -0,0 +1,184 @@
+-- User Credentials Storage with RLS Policies
+-- This migration adds the user_credentials table for secure storage of user API keys,
+-- OAuth tokens, and other credentials with encryption and RLS enforcement.
+--
+-- Related: #355 - Create UserCredential Prisma model with RLS policies
+-- Design: docs/design/credential-security.md (Phase 3a)
+
+-- =============================================================================
+-- CREATE ENUMS
+-- =============================================================================
+
+-- CredentialType enum: Types of credentials that can be stored
+CREATE TYPE "CredentialType" AS ENUM ('API_KEY', 'OAUTH_TOKEN', 'ACCESS_TOKEN', 'SECRET', 'PASSWORD', 'CUSTOM');
+
+-- CredentialScope enum: Access scope for credentials
+CREATE TYPE "CredentialScope" AS ENUM ('USER', 'WORKSPACE', 'SYSTEM');
+
+-- =============================================================================
+-- EXTEND EXISTING ENUMS
+-- =============================================================================
+
+-- Add CREDENTIAL to EntityType for activity logging
+ALTER TYPE "EntityType" ADD VALUE 'CREDENTIAL';
+
+-- Add credential-related actions to ActivityAction
+ALTER TYPE "ActivityAction" ADD VALUE 'CREDENTIAL_CREATED';
+ALTER TYPE "ActivityAction" ADD VALUE 'CREDENTIAL_ACCESSED';
+ALTER TYPE "ActivityAction" ADD VALUE 'CREDENTIAL_ROTATED';
+ALTER TYPE "ActivityAction" ADD VALUE 'CREDENTIAL_REVOKED';
+
+-- =============================================================================
+-- CREATE USER_CREDENTIALS TABLE
+-- =============================================================================
+
+CREATE TABLE "user_credentials" (
+    "id" UUID NOT NULL DEFAULT uuid_generate_v4(),
+    "user_id" UUID NOT NULL,
+    "workspace_id" UUID,
+
+    -- Identity
+    "name" VARCHAR(255) NOT NULL,
+    "provider" VARCHAR(100) NOT NULL,
+    "type" "CredentialType" NOT NULL,
+    "scope" "CredentialScope" NOT NULL DEFAULT 'USER',
+
+    -- Encrypted storage
+    "encrypted_value" TEXT NOT NULL,
+    "masked_value" VARCHAR(20),
+
+    -- Metadata
+    "description" TEXT,
+    "expires_at" TIMESTAMPTZ,
+    "last_used_at" TIMESTAMPTZ,
+    "metadata" JSONB NOT NULL DEFAULT '{}',
+
+    -- Status
+    "is_active" BOOLEAN NOT NULL DEFAULT true,
+    "rotated_at" TIMESTAMPTZ,
+
+    -- Audit
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    "updated_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT "user_credentials_pkey" PRIMARY KEY ("id")
+);
+
+-- =============================================================================
+-- CREATE FOREIGN KEY CONSTRAINTS
+-- =============================================================================
+
+ALTER TABLE "user_credentials" ADD CONSTRAINT "user_credentials_user_id_fkey"
+    FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+ALTER TABLE "user_credentials" ADD CONSTRAINT "user_credentials_workspace_id_fkey"
+    FOREIGN KEY ("workspace_id") REFERENCES "workspaces"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- =============================================================================
+-- CREATE INDEXES
+-- =============================================================================
+
+-- Index for user lookups
+CREATE INDEX "user_credentials_user_id_idx" ON "user_credentials"("user_id");
+
+-- Index for workspace lookups
+CREATE INDEX "user_credentials_workspace_id_idx" ON "user_credentials"("workspace_id");
+
+-- Index for user + scope queries
+CREATE INDEX "user_credentials_user_id_scope_idx" ON "user_credentials"("user_id", "scope");
+
+-- Index for workspace + scope queries
+CREATE INDEX "user_credentials_workspace_id_scope_idx" ON "user_credentials"("workspace_id", "scope");
+
+-- Index for scope + active status queries
+CREATE INDEX "user_credentials_scope_is_active_idx" ON "user_credentials"("scope", "is_active");
+
+-- =============================================================================
+-- CREATE UNIQUE CONSTRAINT
+-- =============================================================================
+
+-- Prevent duplicate credentials per user/workspace/provider/name
+CREATE UNIQUE INDEX "user_credentials_user_id_workspace_id_provider_name_key"
+    ON "user_credentials"("user_id", "workspace_id", "provider", "name");
+
+-- =============================================================================
+-- ENABLE FORCE ROW LEVEL SECURITY
+-- =============================================================================
+-- FORCE means the table owner (mosaic) is also subject to RLS policies.
+-- This prevents Prisma (connecting as owner) from bypassing policies.
+
+ALTER TABLE user_credentials ENABLE ROW LEVEL SECURITY;
+ALTER TABLE user_credentials FORCE ROW LEVEL SECURITY;
+
+-- =============================================================================
+-- RLS POLICIES
+-- =============================================================================
+
+-- Owner bypass policy: Allow access to all rows ONLY when no RLS context is set
+-- This is required for:
+-- 1. Prisma migrations that run without RLS context
+-- 2. Database maintenance operations
+-- When RLS context IS set (current_user_id() returns non-NULL), this policy does not apply
+--
+-- NOTE: If connecting as a PostgreSQL superuser (like the default 'mosaic' role),
+-- RLS policies are bypassed entirely. For full RLS enforcement, the application
+-- should connect as a non-superuser role. See docs/design/credential-security.md
+CREATE POLICY user_credentials_owner_bypass ON user_credentials
+  FOR ALL
+  USING (current_user_id() IS NULL);
+
+-- User access policy: USER-scoped credentials visible only to owner
+-- Uses current_user_id() helper from migration 20260129221004_add_rls_policies
+CREATE POLICY user_credentials_user_access ON user_credentials
+  FOR ALL
+  USING (
+    scope = 'USER' AND user_id = current_user_id()
+  );
+
+-- Workspace admin access policy: WORKSPACE-scoped credentials visible to workspace admins
+-- Uses is_workspace_admin() helper from migration 20260129221004_add_rls_policies
+CREATE POLICY user_credentials_workspace_access ON user_credentials
+  FOR ALL
+  USING (
+    scope = 'WORKSPACE'
+    AND workspace_id IS NOT NULL
+    AND is_workspace_admin(workspace_id, current_user_id())
+  );
+
+-- SYSTEM-scoped credentials are only accessible via owner bypass policy
+-- (when current_user_id() IS NULL, which happens for admin operations)
+
+-- =============================================================================
+-- AUDIT TRIGGER
+-- =============================================================================
+
+-- Update updated_at timestamp on row changes
+CREATE OR REPLACE FUNCTION update_user_credentials_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER user_credentials_updated_at
+    BEFORE UPDATE ON user_credentials
+    FOR EACH ROW
+    EXECUTE FUNCTION update_user_credentials_updated_at();
+
+-- =============================================================================
+-- NOTES
+-- =============================================================================
+-- This migration creates the foundation for secure credential storage.
+-- The encrypted_value column stores ciphertext in one of two formats:
+--
+-- 1. OpenBao Transit format (preferred): vault:v1:base64data
+-- 2. AES-256-GCM fallback format: iv:authTag:encrypted
+--
+-- The VaultService (issue #353) handles encryption/decryption with automatic
+-- fallback to CryptoService when OpenBao is unavailable.
+--
+-- RLS enforcement ensures:
+-- - USER scope: Only the credential owner can access
+-- - WORKSPACE scope: Only workspace admins can access
+-- - SYSTEM scope: Only accessible via admin/migration bypass
--- a/apps/api/prisma/schema.prisma
+++ b/apps/api/prisma/schema.prisma
@@ -62,6 +62,10 @@ enum ActivityAction {
  LOGOUT
  PASSWORD_RESET
  EMAIL_VERIFIED
+  CREDENTIAL_CREATED
+  CREDENTIAL_ACCESSED
+  CREDENTIAL_ROTATED
+  CREDENTIAL_REVOKED
 }

 enum EntityType {
@@ -72,6 +76,7 @@ enum EntityType {
  USER
  IDEA
  DOMAIN
+  CREDENTIAL
 }

 enum IdeaStatus {
@@ -186,6 +191,21 @@ enum FederationMessageStatus {
  TIMEOUT
 }

+enum CredentialType {
+  API_KEY
+  OAUTH_TOKEN
+  ACCESS_TOKEN
+  SECRET
+  PASSWORD
+  CUSTOM
+}
+
+enum CredentialScope {
+  USER
+  WORKSPACE
+  SYSTEM
+}
+
 // ============================================
 // MODELS
 // ============================================
@@ -222,6 +242,7 @@ model User {
  llmProviders           LlmProviderInstance[]   @relation("UserLlmProviders")
  federatedIdentities    FederatedIdentity[]
  llmUsageLogs           LlmUsageLog[]           @relation("UserLlmUsageLogs")
+  userCredentials        UserCredential[]        @relation("UserCredentials")

  @@map("users")
 }
@@ -248,32 +269,33 @@ model Workspace {
  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz

  // Relations
-  owner                 User                   @relation("WorkspaceOwner", fields: [ownerId], references: [id], onDelete: Cascade)
-  members               WorkspaceMember[]
-  teams                 Team[]
-  tasks                 Task[]
-  events                Event[]
-  projects              Project[]
-  activityLogs          ActivityLog[]
-  memoryEmbeddings      MemoryEmbedding[]
-  domains               Domain[]
-  ideas                 Idea[]
-  relationships         Relationship[]
-  agents                Agent[]
-  agentSessions         AgentSession[]
-  agentTasks            AgentTask[]
-  userLayouts           UserLayout[]
-  knowledgeEntries      KnowledgeEntry[]
-  knowledgeTags         KnowledgeTag[]
-  cronSchedules         CronSchedule[]
-  personalities         Personality[]
-  llmSettings           WorkspaceLlmSettings?
-  qualityGates          QualityGate[]
-  runnerJobs                    RunnerJob[]
-  federationConnections         FederationConnection[]
-  federationMessages            FederationMessage[]
-  federationEventSubscriptions  FederationEventSubscription[]
-  llmUsageLogs                  LlmUsageLog[]
+  owner                        User                          @relation("WorkspaceOwner", fields: [ownerId], references: [id], onDelete: Cascade)
+  members                      WorkspaceMember[]
+  teams                        Team[]
+  tasks                        Task[]
+  events                       Event[]
+  projects                     Project[]
+  activityLogs                 ActivityLog[]
+  memoryEmbeddings             MemoryEmbedding[]
+  domains                      Domain[]
+  ideas                        Idea[]
+  relationships                Relationship[]
+  agents                       Agent[]
+  agentSessions                AgentSession[]
+  agentTasks                   AgentTask[]
+  userLayouts                  UserLayout[]
+  knowledgeEntries             KnowledgeEntry[]
+  knowledgeTags                KnowledgeTag[]
+  cronSchedules                CronSchedule[]
+  personalities                Personality[]
+  llmSettings                  WorkspaceLlmSettings?
+  qualityGates                 QualityGate[]
+  runnerJobs                   RunnerJob[]
+  federationConnections        FederationConnection[]
+  federationMessages           FederationMessage[]
+  federationEventSubscriptions FederationEventSubscription[]
+  llmUsageLogs                 LlmUsageLog[]
+  userCredentials              UserCredential[]

  @@index([ownerId])
  @@map("workspaces")
@@ -808,6 +830,52 @@ model Verification {
  @@map("verifications")
 }

+// ============================================
+// USER CREDENTIALS MODULE
+// ============================================
+
+model UserCredential {
+  id          String  @id @default(uuid()) @db.Uuid
+  userId      String  @map("user_id") @db.Uuid
+  workspaceId String? @map("workspace_id") @db.Uuid
+
+  // Identity
+  name     String
+  provider String // "github", "openai", "custom"
+  type     CredentialType
+  scope    CredentialScope @default(USER)
+
+  // Encrypted storage
+  encryptedValue String  @map("encrypted_value") @db.Text
+  maskedValue    String? @map("masked_value") @db.VarChar(20)
+
+  // Metadata
+  description String?   @db.Text
+  expiresAt   DateTime? @map("expires_at") @db.Timestamptz
+  lastUsedAt  DateTime? @map("last_used_at") @db.Timestamptz
+  metadata    Json      @default("{}")
+
+  // Status
+  isActive  Boolean   @default(true) @map("is_active")
+  rotatedAt DateTime? @map("rotated_at") @db.Timestamptz
+
+  // Audit
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  // Relations
+  user      User       @relation("UserCredentials", fields: [userId], references: [id], onDelete: Cascade)
+  workspace Workspace? @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+
+  @@unique([userId, workspaceId, provider, name])
+  @@index([userId])
+  @@index([workspaceId])
+  @@index([userId, scope])
+  @@index([workspaceId, scope])
+  @@index([scope, isActive])
+  @@map("user_credentials")
+}
+
 // ============================================
 // KNOWLEDGE MODULE
 // ============================================
@@ -1293,8 +1361,8 @@ model FederationConnection {
  disconnectedAt DateTime? @map("disconnected_at") @db.Timestamptz

  // Relations
-  workspace        Workspace                     @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
-  messages         FederationMessage[]
+  workspace          Workspace                     @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+  messages           FederationMessage[]
  eventSubscriptions FederationEventSubscription[]

  @@unique([workspaceId, remoteInstanceId])
@@ -1399,9 +1467,9 @@ model LlmUsageLog {
  userId      String @map("user_id") @db.Uuid

  // LLM provider and model info
-  provider            String  @db.VarChar(50)
-  model               String  @db.VarChar(100)
-  providerInstanceId  String? @map("provider_instance_id") @db.Uuid
+  provider           String  @db.VarChar(50)
+  model              String  @db.VarChar(100)
+  providerInstanceId String? @map("provider_instance_id") @db.Uuid

  // Token usage
  promptTokens     Int @default(0) @map("prompt_tokens")
@@ -1424,9 +1492,9 @@ model LlmUsageLog {
  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz

  // Relations
-  workspace              Workspace            @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
-  user                   User                 @relation("UserLlmUsageLogs", fields: [userId], references: [id], onDelete: Cascade)
-  llmProviderInstance    LlmProviderInstance? @relation("LlmUsageLogs", fields: [providerInstanceId], references: [id], onDelete: SetNull)
+  workspace           Workspace            @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+  user                User                 @relation("UserLlmUsageLogs", fields: [userId], references: [id], onDelete: Cascade)
+  llmProviderInstance LlmProviderInstance? @relation("LlmUsageLogs", fields: [providerInstanceId], references: [id], onDelete: SetNull)

  @@index([workspaceId])
  @@index([workspaceId, createdAt])