super_auth 0.4.0 → 0.7.0

data/lib/super_auth/rls.rb

@@ -3,12 +3,26 @@
 # ByCurrentUser filters queries at the ORM layer; RLS enforces the same rule
 # inside Postgres, so raw SQL, `unscoped`, and non-Ruby clients are subject
 # to it too — enforcing apps don't load this gem at all. Identity is
-# asserted per transaction by the super_auth_become() SQL function
-# (installed by `enable`): it sets transaction-local identity settings plus
-# a stamp of the current transaction id, and every policy requires a stamp
-# from the current transaction. Identity therefore cannot outlive its
-# transaction or leak across pooled connections — a query without a fresh
-# assertion sees no rows.
+# asserted per transaction by two SQL functions installed by `enable`:
+#
+#   super_auth_become(user_external_id, user_external_type, user_id)
+#     asserts a user's identity. Executable by PUBLIC.
+#   super_auth_system()
+#     asserts system context, which bypasses every policy. EXECUTE is
+#     revoked from PUBLIC; `grant_system(role)` hands it to the roles that
+#     may bypass.
+#
+# `enable` also grants every role SELECT on the gem's own tables, which the
+# policies and the user models read, so a runtime role needs privileges on
+# the application's tables and nothing else.
+#
+# Both set transaction-local identity settings plus a stamp of the current
+# transaction id, and every policy requires a stamp from the current
+# transaction. Identity therefore cannot outlive its transaction or leak
+# across pooled connections — a query without a fresh assertion sees no
+# rows. Both raise if the calling role is a superuser or has BYPASSRLS:
+# Postgres exempts those roles from every policy, so an identity assertion
+# from one would protect nothing while looking like it does.
 module SuperAuth
   module RLS
     POLICY = "super_auth".freeze
@@ -16,7 +30,7 @@ module SuperAuth
     class << self
       # Enable RLS on an app table with a policy mirroring ByCurrentUser:
       # type-level authorization rows (resource_external_id IS NULL) act as a
-      # wildcard, per-record rows match on id, and system users bypass.
+      # wildcard, per-record rows match on id, and system context bypasses.
       #
       # One deliberate divergence: INSERTs are also gated. The policy is
       # FOR ALL with no WITH CHECK, so Postgres reuses its USING expression
@@ -25,7 +39,8 @@ module SuperAuth
       # system context.
       def enable(table, resource_type:, db: SuperAuth.db)
         postgres!(db)
-        create_become_function(db)
+        create_functions(db)
+        grant_runtime_reads(db)
         t = db.literal(Sequel.identifier(table.to_s))
         db.run "ALTER TABLE #{t} ENABLE ROW LEVEL SECURITY"
         # FORCE: apply the policy even when the app connects as the table owner
@@ -54,9 +69,9 @@ module SuperAuth
         SQL
       end
 
-      # Drops the table's policy; the shared super_auth_become function is
-      # left in place (other tables may still be protected, and it is
-      # harmless on its own).
+      # Drops the table's policy; the shared functions are left in place
+      # (other tables may still be protected, and they are harmless on their
+      # own).
       def disable(table, db: SuperAuth.db)
         postgres!(db)
         t = db.literal(Sequel.identifier(table.to_s))
@@ -70,51 +85,166 @@ module SuperAuth
       # (BEGIN; SELECT super_auth_become(...); queries; COMMIT). Sequel and
       # ActiveRecord queries inside the block share the transaction's
       # connection, so the policies see the identity; it dies with the
-      # transaction. In nested calls the innermost assertion wins for the
-      # rest of the outer transaction.
-      def as(user, db: SuperAuth.db)
+      # transaction. A user whose `system?` is true asserts system context
+      # through super_auth_system() instead, which the connection's role
+      # must have been granted EXECUTE on.
+      #
+      # Inside an enclosing transaction (the caller's, or an outer `as`) it
+      # joins that transaction instead of opening one, and it puts the
+      # enclosing identity back when the block ends, however it ends: the
+      # innermost assertion wins inside the block and nothing else afterwards.
+      # This touches only the database settings; SuperAuth.as is the call that
+      # also sets SuperAuth.current_user.
+      #
+      # Transaction options pass through to Sequel's transaction. One matters
+      # for a wrapper that exists only to carry an identity:
+      #   auto_savepoint: true   every nested transaction becomes a savepoint
+      #                          (the ActiveRecord bridge turns this into
+      #                          joinable: false), so a save inside the block
+      #                          commits on its own and its after_commit hooks
+      #                          fire then, not at the end of the block.
+      # Whether a write survives the block raising is the caller's policy, not
+      # this wrapper's: rescue inside the block to keep it, or let the
+      # exception out to roll it back.
+      def as(user, db: SuperAuth.db, **transaction_options)
         postgres!(db)
-        internal_id = external_id = external_type = nil
-        system = user.respond_to?(:system?) && !!user.system?
-        if user && internal_user?(user)
-          internal_id = user.id.to_s
-        elsif user
-          external_id = user.id.to_s
-          external_type = user.class.name
+        # Outside a transaction the settings die at COMMIT and there is nothing
+        # to restore; inside one, the enclosing identity must survive the block.
+        enclosing = db.in_transaction? ? identity(db) : nil
+        db.transaction(**transaction_options) do
+          assert(user, db: db)
+          begin
+            yield
+          ensure
+            restore(enclosing, db) if enclosing
+          end
         end
-        db.transaction do
-          db.get(Sequel.function(:super_auth_become, external_id, external_type, internal_id, system))
-          yield
+      end
+
+      # Assert `user`'s identity in the transaction the caller already holds,
+      # without opening one: the SELECT super_auth_become(...) half of the
+      # contract, or super_auth_system() for a user whose `system?` is true.
+      # For re-asserting mid-transaction, and for code that manages its own
+      # transaction and only needs the identity in it. Outside a transaction
+      # the settings die with the statement, so it protects nothing there.
+      def assert(user, db: SuperAuth.db)
+        postgres!(db)
+        if user.respond_to?(:system?) && user.system?
+          db.get(Sequel.function(:super_auth_system))
+        else
+          db.get(Sequel.function(:super_auth_become, *become_args(user)))
         end
       end
 
+      # Whether `enable` has run on this database: both identity functions
+      # exist with their current signatures. One query per call, so a hot
+      # path memoises it. False on a non-Postgres database, where RLS cannot
+      # be installed.
+      def installed?(db: SuperAuth.db)
+        return false unless db.database_type == :postgres
+        db.get(Sequel.lit("to_regprocedure('super_auth_become(text,text,text)') IS NOT NULL AND to_regprocedure('super_auth_system()') IS NOT NULL"))
+      end
+
+      # Allow `role` to assert system context: SuperAuth.as with a user whose
+      # system? is true, or SELECT super_auth_system() directly. enable revokes
+      # this from PUBLIC; grant it to the roles that run migrations, seeds and
+      # admin jobs, and to nothing else.
+      def grant_system(role, db: SuperAuth.db)
+        postgres!(db)
+        db.run "GRANT EXECUTE ON FUNCTION super_auth_system() TO #{db.literal(Sequel.identifier(role.to_s))}"
+      end
+
       private
 
-      # One shared function per database; clients assert identity by calling
-      # it inside their transaction. CREATE OR REPLACE keeps enable
-      # idempotent.
-      def create_become_function(db)
+      # What any runtime role needs on the gem's own tables: the policies read
+      # super_auth_authorizations as the querying role, and the user models'
+      # system? reads super_auth_users. Granting PUBLIC makes enable the only
+      # setup step; a deployment that wants these tables private can REVOKE
+      # from PUBLIC and grant per role.
+      def grant_runtime_reads(db)
+        db.run "GRANT SELECT ON super_auth_authorizations, super_auth_users TO PUBLIC"
+      end
+
+      # Refuses an identity assertion from a role Postgres exempts from row
+      # security: the policies would apply to nobody while everything looked
+      # enforced. Checks the effective role, so a superuser session that has
+      # SET ROLE to an application role passes.
+      SUPERUSER_GUARD = <<~SQL.freeze
+        IF (SELECT rolsuper OR rolbypassrls FROM pg_roles WHERE rolname = current_user) THEN
+          RAISE EXCEPTION 'super_auth: role % is a superuser or has BYPASSRLS, so row-level security does not apply to it and asserting an identity would protect nothing. Connect as a regular role.', current_user
+            USING ERRCODE = 'invalid_authorization_specification';
+        END IF;
+      SQL
+
+      # Two shared functions per database; clients assert identity by calling
+      # one of them inside their transaction. CREATE OR REPLACE keeps enable
+      # idempotent. The pre-0.5 four-argument super_auth_become carried the
+      # system bypass as its last parameter; a REPLACE with a different
+      # signature would leave that overload in place, so it is dropped.
+      def create_functions(db)
+        db.run "DROP FUNCTION IF EXISTS super_auth_become(text, text, text, boolean)"
         db.run <<~SQL
           CREATE OR REPLACE FUNCTION super_auth_become(
             user_external_id text DEFAULT NULL,
             user_external_type text DEFAULT NULL,
-            user_id text DEFAULT NULL,
-            system boolean DEFAULT false
+            user_id text DEFAULT NULL
           ) RETURNS void LANGUAGE plpgsql AS $$
           BEGIN
+            #{SUPERUSER_GUARD}
             PERFORM set_config('super_auth.user_id',            COALESCE(user_id, ''), true),
                     set_config('super_auth.user_external_id',   COALESCE(user_external_id, ''), true),
                     set_config('super_auth.user_external_type', COALESCE(user_external_type, ''), true),
-                    set_config('super_auth.system',             CASE WHEN system THEN 'true' ELSE '' END, true),
+                    set_config('super_auth.system',             '', true),
+                    set_config('super_auth.xid',                pg_current_xact_id()::text, true);
+          END
+          $$;
+        SQL
+        db.run <<~SQL
+          CREATE OR REPLACE FUNCTION super_auth_system() RETURNS void LANGUAGE plpgsql AS $$
+          BEGIN
+            #{SUPERUSER_GUARD}
+            PERFORM set_config('super_auth.user_id',            '', true),
+                    set_config('super_auth.user_external_id',   '', true),
+                    set_config('super_auth.user_external_type', '', true),
+                    set_config('super_auth.system',             'true', true),
                     set_config('super_auth.xid',                pg_current_xact_id()::text, true);
           END
           $$;
         SQL
+        # Bypass is opt-in per role: GRANT EXECUTE ON FUNCTION super_auth_system() TO <role>.
+        db.run "REVOKE EXECUTE ON FUNCTION super_auth_system() FROM PUBLIC"
+      end
+
+      # super_auth_become's three arguments for `user`: a SuperAuth user
+      # record goes by user_id, any other object by id and class name, nil by
+      # nothing, an identity no authorization matches.
+      def become_args(user)
+        if user.nil?
+          [nil, nil, nil]
+        elsif SuperAuth.internal_user?(user)
+          [nil, nil, user.id.to_s]
+        else
+          [user.id.to_s, user.class.name, nil]
+        end
+      end
+
+      # The five transaction-local settings the policies read, in one order.
+      SETTINGS = %w[
+        super_auth.user_id super_auth.user_external_id super_auth.user_external_type
+        super_auth.system super_auth.xid
+      ].freeze
+
+      def identity(db)
+        db.dataset.get(SETTINGS.each_with_index.map { |name, i| Sequel.function(:current_setting, name, true).as(:"s#{i}") })
       end
 
-      def internal_user?(user)
-        (defined?(SuperAuth::ActiveRecord::User) && user.is_a?(SuperAuth::ActiveRecord::User)) ||
-          (defined?(SuperAuth::User) && user.is_a?(SuperAuth::User))
+      # Writes the settings back directly: the values were read from this same
+      # transaction, so the stamp is still the current one, and no role is
+      # granted anything it could not already set.
+      def restore(values, db)
+        db.dataset.get(SETTINGS.zip(values).each_with_index.map { |(name, value), i| Sequel.function(:set_config, name, value.to_s, true).as(:"s#{i}") })
+      rescue Sequel::DatabaseError
+        # The block aborted the transaction; its rollback discards the settings.
       end
 
       def postgres!(db)

data/lib/super_auth/user.rb

@@ -2,7 +2,9 @@ class SuperAuth::User < Sequel::Model(:super_auth_users)
   one_to_many :edges
   one_to_many :resources
 
-  def system? = self.class.system == self
+  # A read: runtime roles only get SELECT on this table. `.system` creates
+  # the row when missing and belongs to migrations, seeds and consoles.
+  def system? = self.class.first(name: "system") == self
   def self.system = find_or_create(name: "system")
 
   dataset_module do

data/lib/super_auth/version.rb

@@ -1,3 +1,3 @@
 module SuperAuth
-  VERSION = "0.4.0"
+  VERSION = "0.7.0"
 end

data/lib/super_auth.rb

@@ -42,6 +42,23 @@ module SuperAuth
     external_id_type == :string ? String : external_id_type
   end
 
+  # The human name of the application record behind a node, by convention
+  # rather than configuration: a model says it explicitly with
+  # `super_auth_label`, otherwise `name` then `title` are tried, and a model
+  # with none of them has no label. This is also the name of the column the
+  # derivation is stored in, since `label` is a name applications want for
+  # themselves. Deliberately never `to_s` — the label sits where the editor
+  # otherwise renders `Type#id`, and "#<Claim:0x000055…>" is worse than the id
+  # it would replace.
+  def self.label_for(record)
+    %i[super_auth_label name title].each do |method|
+      next unless record.respond_to?(method)
+      value = record.public_send(method)
+      return value.to_s unless value.nil? || value.to_s.empty?
+    end
+    nil
+  end
+
   def self.load
     require "super_auth/authorization"
     require "super_auth/edge"
@@ -95,11 +112,31 @@ module SuperAuth
     raise Error, "Failed to uninstall migrations: #{e.message}"
   end
 
-  # Run the block with `user`'s identity asserted inside a database
-  # transaction, so RLS policies (see SuperAuth::RLS) enforce authorization
-  # for every query in the block. Postgres only.
-  def self.as(user, db: SuperAuth.db, &block)
-    SuperAuth::RLS.as(user, db: db, &block)
+  # Run the block as `user` in both layers: SuperAuth.current_user, which the
+  # ByCurrentUser scope reads, and the database identity the RLS policies read
+  # (see SuperAuth::RLS.as). Both are restored on the way out, whether the
+  # block returns, raises, or was nested inside another `as`. Passing nil runs
+  # the block with no user in either layer. Postgres only, since the database
+  # half is. Keyword options (auto_savepoint:, ...) go to SuperAuth::RLS.as.
+  # current_user is assigned inside the transaction, after the database
+  # identity, so an application that hooks the writer to re-assert does so on
+  # the connection that holds the transaction.
+  def self.as(user, db: SuperAuth.db, **options)
+    previous = current_user
+    SuperAuth::RLS.as(user, db: db, **options) do
+      self.current_user = user
+      yield
+    end
+  ensure
+    self.current_user = previous
+  end
+
+  # Both user models are internal: their id is the user_id that the policies
+  # and ByCurrentUser match on. Anything else is an application object,
+  # matched by id and class name.
+  def self.internal_user?(user)
+    (defined?(SuperAuth::ActiveRecord::User) && user.is_a?(SuperAuth::ActiveRecord::User)) ||
+      (defined?(SuperAuth::User) && user.is_a?(SuperAuth::User))
   end
 
   def self.current_user=(user)

data/lib/tasks/super_auth_tasks.rake

@@ -6,6 +6,34 @@ namespace :super_auth do
     puts "Done"
   end
 
+  namespace :labels do
+    desc "Re-derive super_auth_resources.super_auth_label from the application records"
+    task backfill: :environment do
+      SuperAuth.load
+      backfill = lambda do
+        changed = 0
+        SuperAuth::ActiveRecord::Resource.where.not(external_id: nil).find_each do |resource|
+          before = resource.super_auth_label
+          resource.refresh_label!
+          changed += 1 if resource.super_auth_label != before
+        end
+        changed
+      end
+
+      # The application tables this reads are the ones RLS protects, so a run
+      # with no identity derives nil for exactly the rows that matter most and
+      # then reports success. Assert the system identity where RLS is
+      # installed; where it is not, there is nothing to assert.
+      changed =
+        if SuperAuth::RLS.installed?
+          SuperAuth.as(SuperAuth::ActiveRecord::User.system) { backfill.call }
+        else
+          backfill.call
+        end
+      puts "Labelled #{changed} resources"
+    end
+  end
+
   task :rollback => :environment do
     raise "You must define SUPER_AUTH_DATABASE_URL in your environment for this to work" if ENV['SUPER_AUTH_DATABASE_URL'].nil? || ENV['SUPER_AUTH_DATABASE_URL'].empty?
     SuperAuth.uninstall_migrations

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: super_auth
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jonathan Frias
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -40,7 +40,8 @@ dependencies:
 description: Simple, yet super powerful authorization for you application
 email:
 - jonathan@gofrias.com
-executables: []
+executables:
+- super_auth-editor
 extensions: []
 extra_rdoc_files: []
 files:
@@ -53,10 +54,8 @@ files:
 - README.md
 - Rakefile
 - USAGE.md
-- VISUALIZATION.md
-- app/controllers/super_auth/graph_controller.rb
-- app/views/super_auth/graph/index.html.erb
 - config/routes.rb
+- db/migrate/10_add_super_auth_label_to_resources.rb
 - db/migrate/1_users.rb
 - db/migrate/2_groups.rb
 - db/migrate/3_permissions.rb
@@ -74,7 +73,9 @@ files:
 - db/migrate_activerecord/20250101000006_create_super_auth_edges.rb
 - db/migrate_activerecord/20250101000007_create_super_auth_authorizations.rb
 - db/migrate_activerecord/20250101000009_add_by_current_user_index_to_super_auth_authorizations.rb
+- db/migrate_activerecord/20250101000010_add_super_auth_label_to_super_auth_resources.rb
 - db/seeds/sample_data.rb
+- exe/super_auth-editor
 - lib/basic_loader.rb
 - lib/generators/super_auth/install/install_generator.rb
 - lib/generators/super_auth/install/templates/README
@@ -93,6 +94,10 @@ files:
 - lib/super_auth/active_record/user.rb
 - lib/super_auth/authorization.rb
 - lib/super_auth/edge.rb
+- lib/super_auth/editor.rb
+- lib/super_auth/editor/cli.rb
+- lib/super_auth/editor/index.html
+- lib/super_auth/editor/seed.rb
 - lib/super_auth/group.rb
 - lib/super_auth/nestable.rb
 - lib/super_auth/permission.rb
@@ -103,8 +108,6 @@ files:
 - lib/super_auth/user.rb
 - lib/super_auth/version.rb
 - lib/tasks/super_auth_tasks.rake
-- super_auth.gemspec
-- visualization.html
 homepage: https://github.com/JonathanFrias/super_auth
 licenses:
 - GPL-2.0

data/VISUALIZATION.md

@@ -1,58 +0,0 @@
-# SuperAuth Graph Visualization
-
-SuperAuth includes an interactive graph visualization tool that helps you understand and debug your authorization rules.
-
-## Setup
-
-### 1. Run the Installer
-
-Generate the initializer and install migrations:
-
-```bash
-rails generate super_auth:install
-```
-
-This will:
-- Create `config/initializers/super_auth.rb`
-- Install SuperAuth database migrations
-- Show you the next steps
-
-### 2. Mount the Engine
-
-Add the following to your `config/routes.rb`:
-
-```ruby
-Rails.application.routes.draw do
-  mount SuperAuth::Engine => '/super_auth'
-
-  # Your other routes...
-end
-```
-
-## Features
-
-### Interactive Graph
-
-- **Nodes**: Color-coded by type (Users, Groups, Roles, Permissions, Resources)
-- **Edges**: Solid lines for authorization relationships, dashed for hierarchy
-- **Zoom & Pan**: Navigate large graphs easily
-- **Click nodes**: View node details
-
-### Authorization Query
-
-1. Select a user from the dropdown
-2. Select a resource from the dropdown
-3. Click "Find Authorization Paths"
-4. View all paths that grant access
-5. See the first path highlighted on the graph
-
-### Statistics Panel
-
-Real-time counts of:
-- Users
-- Groups (with hierarchical relationships)
-- Roles (with hierarchical relationships)
-- Permissions
-- Resources
-- Authorization edges
-