rls-guard

RLS Guard

A powerful CLI tool for managing PostgreSQL Row Level Security (RLS) policies as code using TypeScript.

Features

• 🔒 Declarative RLS policies - Define your security policies in TypeScript using a fluent API
• 🚀 Easy deployment - Deploy policies to your PostgreSQL database with a single command
• 🔍 Dry-run support - Preview SQL commands before executing them
• 🎯 Type-safe configuration - Full TypeScript support with intellisense and type checking
• 🏗️ Built-in helpers - Common RLS patterns like user isolation, tenant separation, and role-based access
• 🔧 Cross-platform - Works on macOS, Linux, and Windows

Installation

Install globally via npm:

npm install -g rls-guard

Quick Start

• Initialize a new configuration:

  rls-guard init
  

• Configure your database and policies in rls.config.ts:

  import { config, currentUserId, tenantId, publicAccess } from 'rls-guard/lib/rls-config';
  
  const rlsConfig = config()
    .database(db => db
      .connectionUrl("postgresql://user:pass@localhost:5432/mydb")
    )
    
    // Users can only see their own records
    .addPolicy(p => p
      .name("user_isolation")
      .onTable("users")
      .forCommand("SELECT")
      .withExpression(currentUserId())
      .forRoles("authenticated_user")
    )
    
    // Admin users have full access
    .addPolicy(p => p
      .name("admin_full_access")
      .onTable("users")
      .forCommand("ALL")
      .withExpression(publicAccess())
      .forRoles("admin")
    );
  
  export default rlsConfig;
  

• Deploy your policies:

  # Preview changes
  rls-guard deploy --dry-run
  
  # Apply to database
  rls-guard deploy
  

Configuration

Database Connection

Connect using a connection URL:

.database(db => db
  .connectionUrl("postgresql://user:pass@localhost:5432/mydb?sslmode=disable")
)

Or individual parameters:

.database(db => db
  .host("localhost")
  .port(5432)
  .database("mydb")
  .username("user")
  .password("pass")
  .ssl(false)
)

Policy Types

Permissive policies (default) - Allow access when conditions are met:

.addPolicy(p => p
  .name("user_data_access")
  .onTable("user_data")
  .forCommand("SELECT")
  .withExpression(currentUserId())
  .forRoles("user")
  .asPermissive()  // This is the default
)

Restrictive policies - Block access unless conditions are met:

.addPolicy(p => p
  .name("sensitive_data_restriction")
  .onTable("sensitive_data")
  .forCommand("SELECT")
  .withExpression("false")  // Block by default
  .forRoles("public")
  .asRestrictive()
)

Built-in Helper Functions

• currentUserId(column?) - Match current user ID
• tenantId(column?) - Multi-tenant isolation
• recentData(column, days) - Time-based access
• ownerOnly(userCol, ownerCol) - Owner-based access
• roleCheck(role) - Role-based conditions
• publicAccess() - Always allow (returns true)
• noAccess() - Always deny (returns false)

Commands

rls-guard init

Create a new rls.config.ts file with example policies.

rls-guard pull [options]

Extract existing RLS policies from your PostgreSQL database and generate a configuration file.

Options:

• --connection <url> - Database connection string (or set DATABASE_URL env var)
• --output, -o <file> - Output file path (default: rls.config.ts)
• --tables, -t <tables> - Comma-separated list of tables to extract
• --format, -f <format> - Output format: typescript or json (default: typescript)
• --comments, -c - Add explanatory comments to generated config
• --no-mask - Don't mask sensitive connection info in output

Example:

# Extract all policies to TypeScript config
rls-guard pull --connection "postgresql://user:pass@localhost:5432/mydb"

# Extract specific tables with comments
rls-guard pull --tables "users,posts" --comments --output policies.config.ts

# Generate JSON format
rls-guard pull --format json --output policies.json

rls-guard deploy [options]

Deploy RLS policies to your PostgreSQL database.

Options:

• --dry-run - Show SQL commands without executing them
• --config, -c <path> - Path to config file (default: rls.config.ts)

rls-guard version

Show the current version.

Requirements

• Node.js 12+
• PostgreSQL 9.5+ (RLS support)
• TypeScript configuration file

Testing

RLS Guard includes comprehensive test suites:

# Run unit and basic integration tests
npm test

# Run database integration tests (requires PostgreSQL)
npm run test:db

# Set up test database with Docker
npm run test:db-setup

# Run full test suite with Docker database  
npm run test:full

See TESTING.md for detailed testing documentation.

Contributing

We welcome contributions! RLS Guard is an open-source project that benefits from community involvement.

🗺️ Feature Roadmap

Check out our Feature Roadmap to see planned features and improvements. Pick any item that interests you!

🚀 Quick Start for Contributors

• Fork the repository on GitHub
• Clone your fork locally
• Install dependencies: npm install
• Submit a pull request with a clear description

🎯 Ways to Contribute

• 🐛 Report bugs - Found an issue? Let us know!
• 💡 Suggest features - Ideas for improvements are welcome
• 📚 Improve docs - Help make RLS Guard easier to use
• 🧪 Add tests - Help us maintain quality
• ⚡ Performance - Optimize queries and connections
• 🎨 UX improvements - Better CLI output and error messages

📋 Development Areas

• CLI enhancements and better error handling
• Additional PostgreSQL features and cloud provider support
• IDE integrations (VS Code extension, auto-completion)
• Policy templates and testing frameworks
• CI/CD integrations and monitoring tools

See the complete roadmap for detailed feature plans and development priorities.

License

MIT License