rls_multi_tenant 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e90e7f280c785aa09f9f643da2420a38423f888592a750d4587dcc961ede1de1
+  data.tar.gz: cb1ec28221f70d26bcf6444be404feccf6098417325921692f8c95ba4d945a3c
+SHA512:
+  metadata.gz: e28c40e201630a87955c890b4f417d43c0e7418674a6bf776d44cd4a39b28cb6c49b4873c6807e0e21247b8e120682a986e1bccf95cdc47d1be29f2b63c213c6
+  data.tar.gz: 986900e03f1234f1f19813f1680af7675861c35a437b64582512854bdc9f7d05828a78a6bf6755f656a2b05fa7e47447312c83d53796bea4929962f1ed18b70c

data/.rubocop.yml

@@ -0,0 +1,46 @@
+require:
+  - rubocop-rails
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'spec/tmp/**/*'
+    - 'tmp/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/rls_multi_tenant/generators/**/*'
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/DescribeMethod:
+  Enabled: false

data/README.md

@@ -0,0 +1,141 @@
+# RLS Multi-Tenant
+
+A Rails gem that provides PostgreSQL Row Level Security (RLS) based multi-tenancy for Rails applications.
+
+## Features
+
+- 🔒 **Row Level Security**: Automatic tenant isolation using PostgreSQL RLS
+- 🛡️ **Security Validation**: Prevents running with privileged database users
+- 🔄 **Context Switching**: Easy tenant context management
+- 📦 **Auto-inclusion**: Automatic model configuration
+- 🚀 **Generators**: Rails generators for quick setup
+- ⚙️ **Configurable**: Flexible configuration options
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rls_multi_tenant', path: 'gems/rls_multi_tenant'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+1. **Install the gem configuration:**
+   ```bash
+   rails generate rls_multi_tenant:install
+   ```
+
+2. **Configure environment variables:**
+   ```bash
+   POSTGRES_USER=your_admin_user # This is the user that will run the migrations
+   POSTGRES_PASSWORD=your_admin_user_password
+   POSTGRES_APP_USER=your_app_user # This is the user that will run the app
+   POSTGRES_APP_PASSWORD=your_password
+   ```
+
+3. **Run migrations:**
+   ```bash
+   rails db_as:admin[migrate] # Custom rake task to run migrations with admin privileges
+   ```
+
+## Usage
+
+### Basic Multi-Tenant Models
+
+Create a new model:
+```bash
+rails generate rls_multi_tenant:model User name email
+```
+
+Your models automatically include the `MultiTenant` concern:
+
+```ruby
+class User < ApplicationRecord
+  # Automatically includes MultiTenant concern
+  # include RlsMultiTenant::Concerns::MultiTenant
+end
+```
+
+### Tenant Context Switching
+
+```ruby
+# Create a new tenant
+tenant = Tenant.create!(name: "Tenant 1")
+```
+
+```ruby
+# Switch tenant context for a block
+Tenant.switch(tenant) do
+  User.create!(name: "User from Tenant 1", email: "user@example.com") # Automatically assigned to current tenant
+end
+
+# Switch tenant context permanently
+Tenant.switch!(tenant)
+User.create!(name: "User from Tenant 1", email: "user@example.com")
+Tenant.reset! # Reset context
+
+# Get current tenant
+current_tenant = Tenant.current
+```
+
+## Configuration
+
+Configure the gem in `config/initializers/rls_multi_tenant.rb`:
+
+```ruby
+RlsMultiTenant.configure do |config|
+  config.tenant_class_name = "Tenant"           # Your tenant model class
+  config.tenant_id_column = :tenant_id          # Tenant ID column name
+  config.app_user_env_var = "POSTGRES_APP_USER" # Environment variable for app user
+  config.enable_security_validation = true      # Enable security checks. This will check if the app user is set without superuser privileges.
+end
+```
+
+### Database Admin Task
+```bash
+# Run migrations with admin privileges (required because app user can't run migrations)
+rails db_as:admin[migrate]
+
+# Run seeds with admin privileges
+rails db_as:admin[seed]
+
+# Create database with admin privileges
+rails db_as:admin[create]
+```
+
+## Security Features
+
+The gem includes multiple security layers:
+
+1. **Environment Validation**: Ensures `POSTGRES_APP_USER` is set and not privileged
+2. **Database User Validation**: Checks that the database user doesn't have SUPERUSER privileges
+3. **RLS Policies**: Automatic tenant isolation at the database level
+
+## Requirements
+
+- Rails 7.0+
+- PostgreSQL 12+ (with UUID extension support)
+- Ruby 3.0+
+
+## UUID Support
+
+This gem uses UUIDs for the tenant model by default to ensure proper multi-tenant isolation. The `enable_uuid` migration must be run before creating tenant tables.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rls_multi_tenant/concerns/multi_tenant.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RlsMultiTenant
+  module Concerns
+    module MultiTenant
+      extend ActiveSupport::Concern
+
+      included do
+        belongs_to :tenant, class_name: RlsMultiTenant.tenant_class_name, foreign_key: RlsMultiTenant.tenant_id_column
+        
+        validates RlsMultiTenant.tenant_id_column, presence: true
+
+        before_validation :set_tenant_id
+
+        private
+
+        def set_tenant_id
+          current_tenant = RlsMultiTenant.tenant_class.current
+          if current_tenant && self.send(RlsMultiTenant.tenant_id_column).blank?
+            self.send("#{RlsMultiTenant.tenant_id_column}=", current_tenant.id)
+          end
+        end
+      end
+
+      class_methods do
+        private
+
+        def extract_tenant_id(tenant_or_id)
+          case tenant_or_id
+          when RlsMultiTenant.tenant_class
+            tenant_or_id.id
+          when String, Integer
+            tenant_or_id
+          else
+            raise ArgumentError, "Expected #{RlsMultiTenant.tenant_class_name} object or tenant_id, got #{tenant_or_id.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rls_multi_tenant/concerns/tenant_context.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RlsMultiTenant
+  module Concerns
+    module TenantContext
+      extend ActiveSupport::Concern
+
+      SET_TENANT_ID_SQL = 'SET rls.tenant_id = %s'.freeze
+      RESET_TENANT_ID_SQL = 'RESET rls.tenant_id'.freeze
+
+      class_methods do
+        # Switch tenant context for a block
+        def switch(tenant_or_id)
+          tenant_id = extract_tenant_id(tenant_or_id)
+          connection.execute format(SET_TENANT_ID_SQL, connection.quote(tenant_id))
+          yield
+        ensure
+          reset!
+        end
+
+        # Switch tenant context permanently (until reset)
+        def switch!(tenant_or_id)
+          tenant_id = extract_tenant_id(tenant_or_id)
+          connection.execute format(SET_TENANT_ID_SQL, connection.quote(tenant_id))
+        end
+
+        # Reset tenant context
+        def reset!
+          connection.execute RESET_TENANT_ID_SQL
+        end
+
+        # Get current tenant from context
+        def current
+          return nil unless connection.active?
+
+          result = connection.execute("SHOW rls.tenant_id")
+          tenant_id = result.first&.dig('rls.tenant_id')
+          
+          return nil if tenant_id.blank?
+          
+          RlsMultiTenant.tenant_class.find_by(id: tenant_id)
+        rescue ActiveRecord::StatementInvalid, PG::Error
+          nil
+        end
+
+        private
+
+        def extract_tenant_id(tenant_or_id)
+          case tenant_or_id
+          when RlsMultiTenant.tenant_class
+            tenant_or_id.id
+          when String, Integer
+            tenant_or_id
+          else
+            raise ArgumentError, "Expected #{RlsMultiTenant.tenant_class_name} object or tenant_id, got #{tenant_or_id.class}"
+          end
+        end
+      end
+
+      # Instance methods
+      def switch(tenant_or_id)
+        self.class.switch(tenant_or_id) { yield }
+      end
+
+      def switch!(tenant_or_id)
+        self.class.switch!(tenant_or_id)
+      end
+
+      def reset!
+        self.class.reset!
+      end
+    end
+  end
+end

data/lib/rls_multi_tenant/generators/install/install_generator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RlsMultiTenant
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install RLS Multi-tenant gem configuration and initial setup"
+
+      def create_initializer
+        template "rls_multi_tenant.rb", "config/initializers/rls_multi_tenant.rb"
+      end
+
+      def create_tenant_model
+        unless File.exist?(File.join(destination_root, "app/models/tenant.rb"))
+          template "tenant_model.rb", "app/models/tenant.rb"
+        else
+          say "Tenant model already exists, skipping creation", :yellow
+        end
+      end
+
+      def create_db_admin_task
+        unless File.exist?(File.join(destination_root, "lib/tasks/db_admin.rake"))
+          template "db_admin.rake", "lib/tasks/db_admin.rake"
+        else
+          say "Database admin task already exists, skipping creation", :yellow
+        end
+      end
+
+      def create_uuid_migration
+        unless Dir.glob(File.join(destination_root, "db/migrate/*_enable_uuid_extension.rb")).any?
+          create_migration_with_timestamp("enable_uuid", 1)
+        else
+          say "UUID extension migration already exists, skipping creation", :yellow
+        end
+      end
+
+      def create_app_user_migration
+        unless Dir.glob(File.join(destination_root, "db/migrate/*_create_app_user.rb")).any?
+          create_migration_with_timestamp("create_app_user", 2)
+        else
+          say "App user migration already exists, skipping creation", :yellow
+        end
+      end
+
+      def create_tenant_migration
+        unless Dir.glob(File.join(destination_root, "db/migrate/*_create_tenants.rb")).any?
+          create_migration_with_timestamp("create_tenant", 3)
+        else
+          say "Tenant migration already exists, skipping creation", :yellow
+        end
+      end
+
+      def show_instructions
+        say "\n" + "="*60, :green
+        say "RLS Multi-tenant gem installed successfully!", :green
+        say "="*60, :green
+        say "\nNext steps:", :yellow
+        say "1. Configure your environment variables:\n", :yellow
+        say "   POSTGRES_USER=your_admin_user # This is the user that will run the migrations", :yellow
+        say "   POSTGRES_PASSWORD=your_admin_user_password", :yellow
+        say "   POSTGRES_APP_USER=your_app_user # This is the user that will run the app", :yellow
+        say "   POSTGRES_APP_PASSWORD=your_app_user_password", :yellow
+        say "\n2. Make sure to use the POSTGRES_APP_USER in your database.yml.", :yellow
+        say "\n3. Run the migrations with admin privileges:\n", :yellow
+        say "   rails db_as:admin[migrate]", :yellow
+        say "   Note: We must use the admin user because the app user doesn't have migration privileges", :yellow
+        say "\n4. Use 'rails generate rls_multi_tenant:model' for new multi-tenant models", :yellow
+        say "="*60, :green
+      end
+
+      private
+
+      def create_migration_with_timestamp(migration_type, order)
+        base_timestamp = Time.current.strftime("%Y%m%d%H%M")
+        timestamp = "#{base_timestamp}#{sprintf('%02d', order)}"
+        
+        case migration_type
+        when "enable_uuid"
+          template "enable_uuid_extension.rb", "db/migrate/#{timestamp}_enable_uuid_extension.rb"
+        when "create_app_user"
+          template "create_app_user.rb", "db/migrate/#{timestamp}_create_app_user.rb"
+        when "create_tenant"
+          template "create_tenant.rb", "db/migrate/#{timestamp}_create_tenants.rb"
+        end
+      end
+    end
+  end
+end

data/lib/rls_multi_tenant/generators/install/templates/create_app_user.rb

@@ -0,0 +1,33 @@
+class CreateAppUser < ActiveRecord::Migration[<%= Rails.version.to_f %>]
+  def up
+    app_user = ENV['<%= RlsMultiTenant.app_user_env_var %>']
+    app_password = ENV['POSTGRES_APP_PASSWORD']
+
+    # Create user with RLS privileges in PostgreSQL
+    execute <<-SQL
+      DO $$
+      BEGIN
+        IF NOT EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '#{app_user}') THEN
+          CREATE ROLE #{app_user} WITH LOGIN PASSWORD '#{app_password}';
+        END IF;
+      END
+      $$;
+    SQL
+
+    # Grant basic permissions to the user
+    execute "GRANT CONNECT ON DATABASE #{ActiveRecord::Base.connection.current_database} TO #{app_user};"
+    execute "GRANT USAGE ON SCHEMA public TO #{app_user};"
+    execute "GRANT CREATE ON SCHEMA public TO #{app_user};"
+  end
+
+  def down
+    app_user = ENV['<%= RlsMultiTenant.app_user_env_var %>']
+    
+    # Revoke permissions
+    execute "REVOKE ALL ON SCHEMA public FROM #{app_user};"
+    execute "REVOKE CONNECT ON DATABASE #{ActiveRecord::Base.connection.current_database} FROM #{app_user};"
+    
+    # Drop user
+    execute "DROP ROLE IF EXISTS #{app_user};"
+  end
+end

data/lib/rls_multi_tenant/generators/install/templates/create_tenant.rb

@@ -0,0 +1,20 @@
+class CreateTenants < ActiveRecord::Migration[<%= Rails.version.to_f %>]
+  def change
+    create_table :tenants, id: :uuid do |t|
+      t.string :name, null: false
+
+      t.timestamps
+    end
+
+    add_index :tenants, :name, unique: true
+
+    reversible do |dir|
+      dir.up do
+        execute "GRANT SELECT, INSERT, UPDATE, DELETE ON tenants TO #{ENV['<%= RlsMultiTenant.app_user_env_var %>']}"
+      end
+      dir.down do
+        execute "REVOKE SELECT, INSERT, UPDATE, DELETE ON tenants FROM #{ENV['<%= RlsMultiTenant.app_user_env_var %>']}"
+      end
+    end
+  end
+end

data/lib/rls_multi_tenant/generators/install/templates/db_admin.rake

@@ -0,0 +1,27 @@
+namespace :db_as do
+  desc "Run a db: task with admin privileges. Usage: `rails db_as:admin[migrate]`"
+  task :admin, [:sub_task] do |t, args|
+    sub_task = args[:sub_task]
+
+    # Check if a sub-task was provided
+    if sub_task.nil? || !Rake::Task.task_defined?("db:#{sub_task}")
+      puts "Usage: rails db_as:admin[sub_task]"
+      puts "Valid sub-tasks: #{Rake.application.tasks.map(&:name).select { |name| name.start_with?("db:") }.map { |name| name.split(':', 2).last }.uniq.sort.join(', ')}"
+      exit
+    end
+
+    database_url = "postgresql://#{ENV['POSTGRES_USER']}:#{ENV['POSTGRES_PASSWORD']}@#{ENV['POSTGRES_HOST']}:5432/#{ENV['POSTGRES_DB']}"
+
+    # Set the DATABASE_URL with admin user details.
+    ENV['DATABASE_URL'] = database_url
+    ENV['CACHE_DATABASE_URL'] = "#{database_url}_cache"
+    ENV['QUEUE_DATABASE_URL'] = "#{database_url}_queue"
+    ENV['CABLE_DATABASE_URL'] = "#{database_url}_cable"
+    
+    # Set a flag to indicate we're running with admin privileges
+    ENV['RLS_MULTI_TENANT_ADMIN_MODE'] = 'true'
+
+    puts "Executing db:#{sub_task} with admin privileges..."
+    Rake::Task["db:#{sub_task}"].invoke
+  end
+end

data/lib/rls_multi_tenant/generators/install/templates/enable_rls.rb

@@ -0,0 +1,27 @@
+class EnableRlsFor<%= table_name.camelize %> < ActiveRecord::Migration[<%= Rails.version.to_f %>]
+  def change
+    reversible do |dir|
+      dir.up do
+        # Enable Row Level Security
+        execute 'ALTER TABLE <%= table_name %> ENABLE ROW LEVEL SECURITY'
+        
+        # Create RLS policy
+        execute "CREATE POLICY <%= table_name %>_app_user ON <%= table_name %> TO #{ENV['<%= RlsMultiTenant.app_user_env_var %>']} USING (<%= RlsMultiTenant.tenant_id_column %> = NULLIF(current_setting('rls.tenant_id', TRUE), '')::uuid)"
+        
+        # Grant permissions
+        execute "GRANT SELECT, INSERT, UPDATE, DELETE ON <%= table_name %> TO #{ENV['<%= RlsMultiTenant.app_user_env_var %>']}"
+      end
+      
+      dir.down do
+        # Revoke permissions
+        execute "REVOKE SELECT, INSERT, UPDATE, DELETE ON <%= table_name %> FROM #{ENV['<%= RlsMultiTenant.app_user_env_var %>']}"
+        
+        # Drop policy
+        execute "DROP POLICY <%= table_name %>_app_user ON <%= table_name %>"
+        
+        # Disable RLS
+        execute "ALTER TABLE <%= table_name %> DISABLE ROW LEVEL SECURITY"
+      end
+    end
+  end
+end

data/lib/rls_multi_tenant/generators/install/templates/enable_uuid_extension.rb

@@ -0,0 +1,5 @@
+class EnableUuidExtension < ActiveRecord::Migration[<%= Rails.version.to_f %>]
+  def change
+    enable_extension 'uuid-ossp'
+  end
+end

data/lib/rls_multi_tenant/generators/install/templates/rls_multi_tenant.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+RlsMultiTenant.configure do |config|
+  # Configure the tenant model class name
+  config.tenant_class_name = "Tenant"
+  
+  # Configure the tenant ID column name
+  config.tenant_id_column = :tenant_id
+  
+  # Configure the environment variable for the app user
+  config.app_user_env_var = "POSTGRES_APP_USER"
+  
+  # Enable/disable security validation
+  config.enable_security_validation = true
+end

data/lib/rls_multi_tenant/generators/install/templates/tenant_model.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class Tenant < ApplicationRecord
+  include RlsMultiTenant::Concerns::TenantContext
+
+  validates :name, presence: true
+end

data/lib/rls_multi_tenant/generators/migration/migration_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RlsMultiTenant
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      argument :migration_type, type: :string, desc: "Type of migration to generate"
+
+      desc "Generate RLS Multi-tenant migrations"
+
+      def create_migration
+        case migration_type
+        when "create_tenant"
+          create_tenant_migration
+        when "create_app_user"
+          create_app_user_migration
+        when "enable_rls"
+          create_enable_rls_migration
+        when "enable_uuid"
+          create_enable_uuid_migration
+        else
+          say "Unknown migration type: #{migration_type}", :red
+          say "Available types: create_tenant, create_app_user, enable_rls, enable_uuid", :yellow
+        end
+      end
+
+      private
+
+      def create_app_user_migration
+        timestamp = Time.current.strftime("%Y%m%d%H%M%S")
+        template "create_app_user.rb", "db/migrate/#{timestamp}_create_app_user.rb"
+      end
+
+      def create_enable_rls_migration
+        timestamp = Time.current.strftime("%Y%m%d%H%M%S")
+        template "enable_rls.rb", "db/migrate/#{timestamp}_enable_rls_for_#{table_name}.rb"
+      end
+
+      def create_tenant_migration
+        timestamp = Time.current.strftime("%Y%m%d%H%M%S")
+        template "create_tenant.rb", "db/migrate/#{timestamp}_create_tenant.rb"
+      end
+
+      def create_enable_uuid_migration
+        timestamp = Time.current.strftime("%Y%m%d%H%M%S")
+        template "enable_uuid_extension.rb", "db/migrate/#{timestamp}_enable_uuid_extension.rb"
+      end
+
+      def table_name
+        @table_name ||= ask("Enter table name for RLS:")
+      end
+    end
+  end
+end

data/lib/rls_multi_tenant/generators/migration/templates/create_app_user.rb

@@ -0,0 +1,33 @@
+class CreateAppUser < ActiveRecord::Migration[<%= Rails.version.to_f %>]
+  def up
+    app_user = ENV['<%= RlsMultiTenant.app_user_env_var %>']
+    app_password = ENV['POSTGRES_APP_PASSWORD']
+
+    # Create user with RLS privileges in PostgreSQL
+    execute <<-SQL
+      DO $$
+      BEGIN
+        IF NOT EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = '#{app_user}') THEN
+          CREATE ROLE #{app_user} WITH LOGIN PASSWORD '#{app_password}';
+        END IF;
+      END
+      $$;
+    SQL
+
+    # Grant basic permissions to the user
+    execute "GRANT CONNECT ON DATABASE #{ActiveRecord::Base.connection.current_database} TO #{app_user};"
+    execute "GRANT USAGE ON SCHEMA public TO #{app_user};"
+    execute "GRANT CREATE ON SCHEMA public TO #{app_user};"
+  end
+
+  def down
+    app_user = ENV['<%= RlsMultiTenant.app_user_env_var %>']
+    
+    # Revoke permissions
+    execute "REVOKE ALL ON SCHEMA public FROM #{app_user};"
+    execute "REVOKE CONNECT ON DATABASE #{ActiveRecord::Base.connection.current_database} FROM #{app_user};"
+    
+    # Drop user
+    execute "DROP ROLE IF EXISTS #{app_user};"
+  end
+end

data/lib/rls_multi_tenant/generators/migration/templates/create_tenant.rb

@@ -0,0 +1,20 @@
+class CreateTenants < ActiveRecord::Migration[<%= Rails.version.to_f %>]
+  def change
+    create_table :tenants, id: :uuid do |t|
+      t.string :name, null: false
+
+      t.timestamps
+    end
+
+    add_index :tenants, :name, unique: true
+
+    reversible do |dir|
+      dir.up do
+        execute "GRANT SELECT, INSERT, UPDATE, DELETE ON tenants TO #{ENV['<%= RlsMultiTenant.app_user_env_var %>']}"
+      end
+      dir.down do
+        execute "REVOKE SELECT, INSERT, UPDATE, DELETE ON tenants FROM #{ENV['<%= RlsMultiTenant.app_user_env_var %>']}"
+      end
+    end
+  end
+end