feat(#351): Implement RLS context interceptor (fix SEC-API-4)

Implements Row-Level Security (RLS) context propagation via NestJS interceptor and AsyncLocalStorage. Core Implementation: - RlsContextInterceptor sets PostgreSQL session variables (app.current_user_id, app.current_workspace_id) within transaction boundaries - Uses SET LOCAL for transaction-scoped variables, preventing connection pool leakage - AsyncLocalStorage propagates transaction-scoped Prisma client to services - Graceful handling of unauthenticated routes - 30-second transaction timeout with 10-second max wait Security Features: - Error sanitization prevents information disclosure to clients - TransactionClient type provides compile-time safety, prevents invalid method calls - Defense-in-depth security layer for RLS policy enforcement Quality Rails Compliance: - Fixed 154 lint errors in llm-usage module (package-level enforcement) - Added proper TypeScript typing for Prisma operations - Resolved all type safety violations Test Coverage: - 19 tests (7 provider + 9 interceptor + 3 integration) - 95.75% overall coverage (100% statements on implementation files) - All tests passing, zero lint errors Documentation: - Comprehensive RLS-CONTEXT-USAGE.md with examples and migration guide Files Created: - apps/api/src/common/interceptors/rls-context.interceptor.ts - apps/api/src/common/interceptors/rls-context.interceptor.spec.ts - apps/api/src/common/interceptors/rls-context.integration.spec.ts - apps/api/src/prisma/rls-context.provider.ts - apps/api/src/prisma/rls-context.provider.spec.ts - apps/api/src/prisma/RLS-CONTEXT-USAGE.md Fixes #351 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 12:25:50 -06:00
parent e20aea99b9
commit 93d403807b
9 changed files with 1107 additions and 46 deletions
--- a/apps/api/src/prisma/RLS-CONTEXT-USAGE.md
+++ b/apps/api/src/prisma/RLS-CONTEXT-USAGE.md
@@ -0,0 +1,186 @@
+# RLS Context Usage Guide
+
+This guide explains how to use the RLS (Row-Level Security) context system in services.
+
+## Overview
+
+The RLS context system automatically sets PostgreSQL session variables for authenticated requests:
+
+- `app.current_user_id` - Set from the authenticated user
+- `app.current_workspace_id` - Set from the workspace context (if present)
+
+These session variables enable PostgreSQL RLS policies to automatically filter queries based on user permissions.
+
+## How It Works
+
+1. **RlsContextInterceptor** runs after AuthGuard and WorkspaceGuard
+2. It wraps the request in a Prisma transaction (30s timeout, 10s max wait for connection)
+3. Inside the transaction, it executes `SET LOCAL` to set session variables
+4. The transaction client is propagated via AsyncLocalStorage
+5. Services access it using `getRlsClient()`
+
+### Transaction Timeout
+
+The interceptor configures a 30-second transaction timeout and 10-second max wait for connection acquisition. This supports:
+
+- File uploads
+- Complex queries with joins
+- Bulk operations
+- Report generation
+
+If you need longer-running operations, consider moving them to background jobs instead of synchronous HTTP requests.
+
+## Usage in Services
+
+### Basic Pattern
+
+```typescript
+import { Injectable } from "@nestjs/common";
+import { PrismaService } from "../prisma/prisma.service";
+import { getRlsClient } from "../prisma/rls-context.provider";
+
+@Injectable()
+export class TasksService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async findAll(workspaceId: string) {
+    // Use RLS client if available, otherwise fall back to standard client
+    const client = getRlsClient() ?? this.prisma;
+
+    // This query is automatically filtered by RLS policies
+    return client.task.findMany({
+      where: { workspaceId },
+    });
+  }
+}
+```
+
+### Why Use This Pattern?
+
+**With RLS context:**
+
+- Queries are automatically filtered by user/workspace permissions
+- Defense in depth: Even if application logic fails, database RLS enforces security
+- No need to manually add `where` clauses for user/workspace filtering
+
+**Fallback to standard client:**
+
+- Supports unauthenticated routes (public endpoints)
+- Supports system operations that need full database access
+- Graceful degradation if RLS context isn't set
+
+### Advanced: Explicit Transaction Control
+
+For operations that need multiple queries in a single transaction:
+
+```typescript
+async createWithRelations(workspaceId: string, data: CreateTaskDto) {
+  const client = getRlsClient() ?? this.prisma;
+
+  // If using RLS client, we're already in a transaction
+  // If not, we need to create one
+  if (getRlsClient()) {
+    // Already in a transaction with RLS context
+    return this.performCreate(client, data);
+  } else {
+    // Need to manually wrap in transaction
+    return this.prisma.$transaction(async (tx) => {
+      return this.performCreate(tx, data);
+    });
+  }
+}
+
+private async performCreate(client: PrismaClient, data: CreateTaskDto) {
+  const task = await client.task.create({ data });
+  await client.activity.create({
+    data: {
+      type: "TASK_CREATED",
+      taskId: task.id,
+    },
+  });
+  return task;
+}
+```
+
+## Unauthenticated Routes
+
+For public endpoints (no AuthGuard), `getRlsClient()` returns `undefined`:
+
+```typescript
+@Get("public/stats")
+async getPublicStats() {
+  // No RLS context - uses standard Prisma client
+  const client = getRlsClient() ?? this.prisma;
+
+  // This query has NO RLS filtering (public data)
+  return client.task.count();
+}
+```
+
+## Testing
+
+When testing services, you can mock the RLS context:
+
+```typescript
+import { vi } from "vitest";
+import * as rlsContext from "../prisma/rls-context.provider";
+
+describe("TasksService", () => {
+  it("should use RLS client when available", () => {
+    const mockClient = {} as PrismaClient;
+    vi.spyOn(rlsContext, "getRlsClient").mockReturnValue(mockClient);
+
+    // Service will use mockClient instead of prisma
+  });
+});
+```
+
+## Security Considerations
+
+1. **Always use the pattern**: `getRlsClient() ?? this.prisma`
+2. **Don't bypass RLS** unless absolutely necessary (e.g., system operations)
+3. **Trust the interceptor**: It sets context automatically - no manual setup needed
+4. **Test with and without RLS**: Ensure services work in both contexts
+
+## Architecture
+
+```
+Request → AuthGuard → WorkspaceGuard → RlsContextInterceptor → Service
+                                              ↓
+                                        Prisma.$transaction
+                                              ↓
+                                    SET LOCAL app.current_user_id
+                                    SET LOCAL app.current_workspace_id
+                                              ↓
+                                        AsyncLocalStorage
+                                              ↓
+                                    Service (getRlsClient())
+```
+
+## Related Files
+
+- `/apps/api/src/common/interceptors/rls-context.interceptor.ts` - Main interceptor
+- `/apps/api/src/prisma/rls-context.provider.ts` - AsyncLocalStorage provider
+- `/apps/api/src/lib/db-context.ts` - Legacy RLS utilities (reference only)
+- `/apps/api/src/prisma/prisma.service.ts` - Prisma service with RLS helpers
+
+## Migration from Legacy Pattern
+
+If you're migrating from the legacy `withUserContext()` pattern:
+
+**Before:**
+
+```typescript
+return withUserContext(userId, async (tx) => {
+  return tx.task.findMany({ where: { workspaceId } });
+});
+```
+
+**After:**
+
+```typescript
+const client = getRlsClient() ?? this.prisma;
+return client.task.findMany({ where: { workspaceId } });
+```
+
+The interceptor handles transaction management automatically, so you no longer need to wrap every query.
--- a/apps/api/src/prisma/rls-context.provider.spec.ts
+++ b/apps/api/src/prisma/rls-context.provider.spec.ts
@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { getRlsClient, runWithRlsClient, type TransactionClient } from "./rls-context.provider";
+
+describe("RlsContextProvider", () => {
+  let mockPrismaClient: TransactionClient;
+
+  beforeEach(() => {
+    // Create a mock transaction client (excludes $connect, $disconnect, etc.)
+    mockPrismaClient = {
+      $executeRaw: vi.fn(),
+    } as unknown as TransactionClient;
+  });
+
+  describe("getRlsClient", () => {
+    it("should return undefined when no RLS context is set", () => {
+      const client = getRlsClient();
+      expect(client).toBeUndefined();
+    });
+
+    it("should return the RLS client when context is set", () => {
+      runWithRlsClient(mockPrismaClient, () => {
+        const client = getRlsClient();
+        expect(client).toBe(mockPrismaClient);
+      });
+    });
+
+    it("should return undefined after context is cleared", () => {
+      runWithRlsClient(mockPrismaClient, () => {
+        const client = getRlsClient();
+        expect(client).toBe(mockPrismaClient);
+      });
+
+      // After runWithRlsClient completes, context should be cleared
+      const client = getRlsClient();
+      expect(client).toBeUndefined();
+    });
+  });
+
+  describe("runWithRlsClient", () => {
+    it("should execute callback with RLS client available", () => {
+      const callback = vi.fn(() => {
+        const client = getRlsClient();
+        expect(client).toBe(mockPrismaClient);
+      });
+
+      runWithRlsClient(mockPrismaClient, callback);
+
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it("should clear context after callback completes", () => {
+      runWithRlsClient(mockPrismaClient, () => {
+        // Context is set here
+      });
+
+      // Context should be cleared after execution
+      const client = getRlsClient();
+      expect(client).toBeUndefined();
+    });
+
+    it("should clear context even if callback throws", () => {
+      const error = new Error("Test error");
+
+      expect(() => {
+        runWithRlsClient(mockPrismaClient, () => {
+          throw error;
+        });
+      }).toThrow(error);
+
+      // Context should still be cleared
+      const client = getRlsClient();
+      expect(client).toBeUndefined();
+    });
+
+    it("should support nested contexts", () => {
+      const outerClient = mockPrismaClient;
+      const innerClient = {
+        $executeRaw: vi.fn(),
+      } as unknown as TransactionClient;
+
+      runWithRlsClient(outerClient, () => {
+        expect(getRlsClient()).toBe(outerClient);
+
+        runWithRlsClient(innerClient, () => {
+          expect(getRlsClient()).toBe(innerClient);
+        });
+
+        // Should restore outer context
+        expect(getRlsClient()).toBe(outerClient);
+      });
+
+      // Should clear completely after outer context ends
+      expect(getRlsClient()).toBeUndefined();
+    });
+  });
+});
--- a/apps/api/src/prisma/rls-context.provider.ts
+++ b/apps/api/src/prisma/rls-context.provider.ts
@@ -0,0 +1,82 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { PrismaClient } from "@prisma/client";
+
+/**
+ * Transaction-safe Prisma client type that excludes methods not available on transaction clients.
+ * This prevents services from accidentally calling $connect, $disconnect, $transaction, etc.
+ * on a transaction client, which would cause runtime errors.
+ */
+export type TransactionClient = Omit<
+  PrismaClient,
+  "$connect" | "$disconnect" | "$transaction" | "$on" | "$use"
+>;
+
+/**
+ * AsyncLocalStorage for propagating RLS-scoped Prisma client through the call chain.
+ * This allows the RlsContextInterceptor to set a transaction-scoped client that
+ * services can access via getRlsClient() without explicit dependency injection.
+ *
+ * The RLS client is a Prisma transaction client that has SET LOCAL app.current_user_id
+ * and app.current_workspace_id executed, enabling Row-Level Security policies.
+ *
+ * @see docs/design/credential-security.md for RLS architecture
+ */
+const rlsContext = new AsyncLocalStorage<TransactionClient>();
+
+/**
+ * Gets the current RLS-scoped Prisma client from AsyncLocalStorage.
+ * Returns undefined if no RLS context is set (e.g., unauthenticated routes).
+ *
+ * Services should use this pattern:
+ * ```typescript
+ * const client = getRlsClient() ?? this.prisma;
+ * ```
+ *
+ * This ensures they use the RLS-scoped client when available (for authenticated
+ * requests) and fall back to the standard client otherwise.
+ *
+ * @returns The RLS-scoped Prisma transaction client, or undefined
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class TasksService {
+ *   constructor(private readonly prisma: PrismaService) {}
+ *
+ *   async findAll() {
+ *     const client = getRlsClient() ?? this.prisma;
+ *     return client.task.findMany(); // Automatically filtered by RLS
+ *   }
+ * }
+ * ```
+ */
+export function getRlsClient(): TransactionClient | undefined {
+  return rlsContext.getStore();
+}
+
+/**
+ * Executes a function with an RLS-scoped Prisma client available via getRlsClient().
+ * The client is propagated through the call chain using AsyncLocalStorage and is
+ * automatically cleared after the function completes.
+ *
+ * This is used by RlsContextInterceptor to wrap request handlers.
+ *
+ * @param client - The RLS-scoped Prisma transaction client
+ * @param fn - The function to execute with RLS context
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * await prisma.$transaction(async (tx) => {
+ *   await tx.$executeRaw`SET LOCAL app.current_user_id = ${userId}`;
+ *
+ *   return runWithRlsClient(tx, async () => {
+ *     // getRlsClient() now returns tx
+ *     return handler();
+ *   });
+ * });
+ * ```
+ */
+export function runWithRlsClient<T>(client: TransactionClient, fn: () => T): T {
+  return rlsContext.run(client, fn);
+}