stack/apps/api/src/prisma/RLS-CONTEXT-USAGE.md

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

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:

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:

@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:

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:

return withUserContext(userId, async (tx) => {
  return tx.task.findMany({ where: { workspaceId } });
});

After:

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.