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>

apps/api/src/llm-usage/llm-usage.controller.ts

@@ -1,6 +1,7 @@
 import { Controller, Get, Param, Query } from "@nestjs/common";
+import type { LlmUsageLog } from "@prisma/client";
 import { LlmUsageService } from "./llm-usage.service";
-import type { UsageAnalyticsQueryDto } from "./dto";
+import type { UsageAnalyticsQueryDto, UsageAnalyticsResponseDto } from "./dto";
 
 /**
  * LLM Usage Controller
@@ -20,8 +21,10 @@ export class LlmUsageController {
    * @returns Aggregated usage analytics
    */
   @Get("analytics")
-  async getAnalytics(@Query() query: UsageAnalyticsQueryDto) {
-    const data = await this.llmUsageService.getUsageAnalytics(query);
+  async getAnalytics(
+    @Query() query: UsageAnalyticsQueryDto
+  ): Promise<{ data: UsageAnalyticsResponseDto }> {
+    const data: UsageAnalyticsResponseDto = await this.llmUsageService.getUsageAnalytics(query);
     return { data };
   }
 
@@ -32,8 +35,10 @@ export class LlmUsageController {
    * @returns Array of usage logs
    */
   @Get("by-workspace/:workspaceId")
-  async getUsageByWorkspace(@Param("workspaceId") workspaceId: string) {
-    const data = await this.llmUsageService.getUsageByWorkspace(workspaceId);
+  async getUsageByWorkspace(
+    @Param("workspaceId") workspaceId: string
+  ): Promise<{ data: LlmUsageLog[] }> {
+    const data: LlmUsageLog[] = await this.llmUsageService.getUsageByWorkspace(workspaceId);
     return { data };
   }
 
@@ -48,8 +53,11 @@ export class LlmUsageController {
   async getUsageByProvider(
     @Param("workspaceId") workspaceId: string,
     @Param("provider") provider: string
-  ) {
-    const data = await this.llmUsageService.getUsageByProvider(workspaceId, provider);
+  ): Promise<{ data: LlmUsageLog[] }> {
+    const data: LlmUsageLog[] = await this.llmUsageService.getUsageByProvider(
+      workspaceId,
+      provider
+    );
     return { data };
   }
 
@@ -61,8 +69,11 @@ export class LlmUsageController {
    * @returns Array of usage logs
    */
   @Get("by-workspace/:workspaceId/model/:model")
-  async getUsageByModel(@Param("workspaceId") workspaceId: string, @Param("model") model: string) {
-    const data = await this.llmUsageService.getUsageByModel(workspaceId, model);
+  async getUsageByModel(
+    @Param("workspaceId") workspaceId: string,
+    @Param("model") model: string
+  ): Promise<{ data: LlmUsageLog[] }> {
+    const data: LlmUsageLog[] = await this.llmUsageService.getUsageByModel(workspaceId, model);
     return { data };
   }
 }

apps/api/src/llm-usage/llm-usage.service.ts

@@ -1,4 +1,5 @@
 import { Injectable, Logger } from "@nestjs/common";
+import type { LlmUsageLog, Prisma } from "@prisma/client";
 import { PrismaService } from "../prisma/prisma.service";
 import type {
   TrackUsageDto,
@@ -28,12 +29,12 @@ export class LlmUsageService {
    * @param dto - Usage tracking data
    * @returns The created usage log entry
    */
-  async trackUsage(dto: TrackUsageDto) {
+  async trackUsage(dto: TrackUsageDto): Promise<LlmUsageLog> {
     this.logger.debug(
       `Tracking usage: ${dto.provider}/${dto.model} - ${String(dto.totalTokens)} tokens`
     );
 
-    return this.prisma.llmUsageLog.create({
+    return await this.prisma.llmUsageLog.create({
       data: dto,
     });
   }
@@ -46,7 +47,7 @@ export class LlmUsageService {
    * @returns Aggregated usage analytics
    */
   async getUsageAnalytics(query: UsageAnalyticsQueryDto): Promise<UsageAnalyticsResponseDto> {
-    const where: Record<string, unknown> = {};
+    const where: Prisma.LlmUsageLogWhereInput = {};
 
     if (query.workspaceId) {
       where.workspaceId = query.workspaceId;
@@ -63,43 +64,59 @@ export class LlmUsageService {
     if (query.startDate || query.endDate) {
       where.createdAt = {};
       if (query.startDate) {
-        (where.createdAt as Record<string, Date>).gte = new Date(query.startDate);
+        where.createdAt.gte = new Date(query.startDate);
       }
       if (query.endDate) {
-        (where.createdAt as Record<string, Date>).lte = new Date(query.endDate);
+        where.createdAt.lte = new Date(query.endDate);
       }
     }
 
-    const usageLogs = await this.prisma.llmUsageLog.findMany({ where });
+    const usageLogs: LlmUsageLog[] = await this.prisma.llmUsageLog.findMany({ where });
 
     // Aggregate totals
-    const totalCalls = usageLogs.length;
-    const totalPromptTokens = usageLogs.reduce((sum, log) => sum + log.promptTokens, 0);
-    const totalCompletionTokens = usageLogs.reduce((sum, log) => sum + log.completionTokens, 0);
-    const totalTokens = usageLogs.reduce((sum, log) => sum + log.totalTokens, 0);
-    const totalCostCents = usageLogs.reduce((sum, log) => sum + (log.costCents ?? 0), 0);
+    const totalCalls: number = usageLogs.length;
+    const totalPromptTokens: number = usageLogs.reduce(
+      (sum: number, log: LlmUsageLog) => sum + log.promptTokens,
+      0
+    );
+    const totalCompletionTokens: number = usageLogs.reduce(
+      (sum: number, log: LlmUsageLog) => sum + log.completionTokens,
+      0
+    );
+    const totalTokens: number = usageLogs.reduce(
+      (sum: number, log: LlmUsageLog) => sum + log.totalTokens,
+      0
+    );
+    const totalCostCents: number = usageLogs.reduce(
+      (sum: number, log: LlmUsageLog) => sum + (log.costCents ?? 0),
+      0
+    );
 
-    const durations = usageLogs.map((log) => log.durationMs).filter((d): d is number => d !== null);
-    const averageDurationMs =
-      durations.length > 0 ? durations.reduce((sum, d) => sum + d, 0) / durations.length : 0;
+    const durations: number[] = usageLogs
+      .map((log: LlmUsageLog) => log.durationMs)
+      .filter((d): d is number => d !== null);
+    const averageDurationMs: number =
+      durations.length > 0
+        ? durations.reduce((sum: number, d: number) => sum + d, 0) / durations.length
+        : 0;
 
     // Group by provider
     const byProviderMap = new Map<string, ProviderUsageDto>();
     for (const log of usageLogs) {
-      const existing = byProviderMap.get(log.provider);
+      const existing: ProviderUsageDto | undefined = byProviderMap.get(log.provider);
       if (existing) {
         existing.calls += 1;
         existing.promptTokens += log.promptTokens;
         existing.completionTokens += log.completionTokens;
         existing.totalTokens += log.totalTokens;
         existing.costCents += log.costCents ?? 0;
-        if (log.durationMs) {
-          const count = existing.calls === 1 ? 1 : existing.calls - 1;
+        if (log.durationMs !== null) {
+          const count: number = existing.calls === 1 ? 1 : existing.calls - 1;
           existing.averageDurationMs =
             (existing.averageDurationMs * (count - 1) + log.durationMs) / count;
         }
       } else {
-        byProviderMap.set(log.provider, {
+        const newProvider: ProviderUsageDto = {
           provider: log.provider,
           calls: 1,
           promptTokens: log.promptTokens,
@@ -107,27 +124,28 @@ export class LlmUsageService {
           totalTokens: log.totalTokens,
           costCents: log.costCents ?? 0,
           averageDurationMs: log.durationMs ?? 0,
-        });
+        };
+        byProviderMap.set(log.provider, newProvider);
       }
     }
 
     // Group by model
     const byModelMap = new Map<string, ModelUsageDto>();
     for (const log of usageLogs) {
-      const existing = byModelMap.get(log.model);
+      const existing: ModelUsageDto | undefined = byModelMap.get(log.model);
       if (existing) {
         existing.calls += 1;
         existing.promptTokens += log.promptTokens;
         existing.completionTokens += log.completionTokens;
         existing.totalTokens += log.totalTokens;
         existing.costCents += log.costCents ?? 0;
-        if (log.durationMs) {
-          const count = existing.calls === 1 ? 1 : existing.calls - 1;
+        if (log.durationMs !== null) {
+          const count: number = existing.calls === 1 ? 1 : existing.calls - 1;
           existing.averageDurationMs =
             (existing.averageDurationMs * (count - 1) + log.durationMs) / count;
         }
       } else {
-        byModelMap.set(log.model, {
+        const newModel: ModelUsageDto = {
           model: log.model,
           calls: 1,
           promptTokens: log.promptTokens,
@@ -135,28 +153,29 @@ export class LlmUsageService {
           totalTokens: log.totalTokens,
           costCents: log.costCents ?? 0,
           averageDurationMs: log.durationMs ?? 0,
-        });
+        };
+        byModelMap.set(log.model, newModel);
       }
     }
 
     // Group by task type
     const byTaskTypeMap = new Map<string, TaskTypeUsageDto>();
     for (const log of usageLogs) {
-      const taskType = log.taskType ?? "unknown";
-      const existing = byTaskTypeMap.get(taskType);
+      const taskType: string = log.taskType ?? "unknown";
+      const existing: TaskTypeUsageDto | undefined = byTaskTypeMap.get(taskType);
       if (existing) {
         existing.calls += 1;
         existing.promptTokens += log.promptTokens;
         existing.completionTokens += log.completionTokens;
         existing.totalTokens += log.totalTokens;
         existing.costCents += log.costCents ?? 0;
-        if (log.durationMs) {
-          const count = existing.calls === 1 ? 1 : existing.calls - 1;
+        if (log.durationMs !== null) {
+          const count: number = existing.calls === 1 ? 1 : existing.calls - 1;
           existing.averageDurationMs =
             (existing.averageDurationMs * (count - 1) + log.durationMs) / count;
         }
       } else {
-        byTaskTypeMap.set(taskType, {
+        const newTaskType: TaskTypeUsageDto = {
           taskType,
           calls: 1,
           promptTokens: log.promptTokens,
@@ -164,11 +183,12 @@ export class LlmUsageService {
           totalTokens: log.totalTokens,
           costCents: log.costCents ?? 0,
           averageDurationMs: log.durationMs ?? 0,
-        });
+        };
+        byTaskTypeMap.set(taskType, newTaskType);
       }
     }
 
-    return {
+    const response: UsageAnalyticsResponseDto = {
       totalCalls,
       totalPromptTokens,
       totalCompletionTokens,
@@ -179,6 +199,8 @@ export class LlmUsageService {
       byModel: Array.from(byModelMap.values()),
       byTaskType: Array.from(byTaskTypeMap.values()),
     };
+
+    return response;
   }
 
   /**
@@ -187,8 +209,8 @@ export class LlmUsageService {
    * @param workspaceId - Workspace UUID
    * @returns Array of usage logs
    */
-  async getUsageByWorkspace(workspaceId: string) {
-    return this.prisma.llmUsageLog.findMany({
+  async getUsageByWorkspace(workspaceId: string): Promise<LlmUsageLog[]> {
+    return await this.prisma.llmUsageLog.findMany({
       where: { workspaceId },
       orderBy: { createdAt: "desc" },
     });
@@ -201,8 +223,8 @@ export class LlmUsageService {
    * @param provider - Provider name
    * @returns Array of usage logs
    */
-  async getUsageByProvider(workspaceId: string, provider: string) {
-    return this.prisma.llmUsageLog.findMany({
+  async getUsageByProvider(workspaceId: string, provider: string): Promise<LlmUsageLog[]> {
+    return await this.prisma.llmUsageLog.findMany({
       where: { workspaceId, provider },
       orderBy: { createdAt: "desc" },
     });
@@ -215,8 +237,8 @@ export class LlmUsageService {
    * @param model - Model name
    * @returns Array of usage logs
    */
-  async getUsageByModel(workspaceId: string, model: string) {
-    return this.prisma.llmUsageLog.findMany({
+  async getUsageByModel(workspaceId: string, model: string): Promise<LlmUsageLog[]> {
+    return await this.prisma.llmUsageLog.findMany({
       where: { workspaceId, model },
       orderBy: { createdAt: "desc" },
     });