super_auth 0.3.3 → 0.7.0

data/config/routes.rb

@@ -1,73 +1,11 @@
+require "super_auth/editor"
+
+# The engine serves the graph editor at its mount point. Mount it inside your
+# own authentication: it has none of its own.
+#
+#   authenticate :admin do
+#     mount SuperAuth::Engine => "/super_auth"
+#   end
 SuperAuth::Engine.routes.draw do
-  # Main graph visualization interface
-  get '/', to: 'graph#index', as: :root
-  get '/graph', to: 'graph#index'
-
-  # Graph data API
-  get '/graph/data', to: 'graph#data'
-  get '/graph/orphaned', to: 'graph#orphaned'
-  post '/graph/compile_authorizations', to: 'graph#compile_authorizations'
-
-  # Authorization check
-  get '/graph/authorize', to: 'graph#authorize'
-
-  # Legacy visualization endpoint
-  get '/visualization', to: 'graph#visualization'
-
-  # CRUD operations for graph entities
-  scope :graph do
-    resources :users, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_user
-      end
-      member do
-        delete '/', action: :delete_user
-      end
-    end
-
-    resources :groups, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_group
-      end
-      member do
-        delete '/', action: :delete_group
-      end
-    end
-
-    resources :roles, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_role
-      end
-      member do
-        delete '/', action: :delete_role
-      end
-    end
-
-    resources :permissions, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_permission
-      end
-      member do
-        delete '/', action: :delete_permission
-      end
-    end
-
-    resources :graph_resources, only: [:create, :destroy], controller: 'graph', path: 'resources' do
-      collection do
-        post '/', action: :create_resource
-      end
-      member do
-        delete '/', action: :delete_resource
-      end
-    end
-
-    resources :edges, only: [:create, :destroy], controller: 'graph' do
-      collection do
-        post '/', action: :create_edge
-      end
-      member do
-        delete '/', action: :delete_edge
-      end
-    end
-  end
+  mount SuperAuth::Editor, at: "/"
 end

data/db/migrate/10_add_super_auth_label_to_resources.rb

@@ -0,0 +1,13 @@
+Sequel.migration do
+  up do
+    alter_table(:super_auth_resources) do
+      add_column :super_auth_label, String
+    end
+  end
+
+  down do
+    alter_table(:super_auth_resources) do
+      drop_column :super_auth_label
+    end
+  end
+end

data/db/migrate/1_users.rb

@@ -2,7 +2,7 @@ Sequel.migration do
   up do
     create_table(:super_auth_users) do
       primary_key :id
-      String :external_id # , null: false
+      column :external_id, SuperAuth.sequel_external_id_type # , null: false
       String :external_type # , null: false
       String :name
       DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP

data/db/migrate/5_resources.rb

@@ -3,7 +3,7 @@ Sequel.migration do
     create_table(:super_auth_resources) do
       primary_key :id
       String :name
-      String :external_id # , null: false
+      column :external_id, SuperAuth.sequel_external_id_type # , null: false
       String :external_type # , null: false
       DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
       DateTime :updated_at, null: false, default: Sequel::CURRENT_TIMESTAMP

data/db/migrate/7_authorization.rb

@@ -3,7 +3,7 @@ Sequel.migration do
     create_table(:super_auth_authorizations) do
       Integer :user_id, null: true
       String :user_name, null: true
-      String :user_external_id, null: true
+      column :user_external_id, SuperAuth.sequel_external_id_type, null: true
       String :user_external_type, null: true
       DateTime :user_created_at, null: true
       DateTime :user_updated_at, null: true
@@ -28,7 +28,7 @@ Sequel.migration do
       DateTime :permission_updated_at, null: true
       Integer :resource_id, null: true
       String :resource_name, null: true
-      String :resource_external_id, null: true
+      column :resource_external_id, SuperAuth.sequel_external_id_type, null: true
       String :resource_external_type, null: true
       DateTime :created_at, null: false, default: Sequel::CURRENT_TIMESTAMP
       DateTime :updated_at, null: false, default: Sequel::CURRENT_TIMESTAMP

data/db/migrate/8_add_indexes_to_edges.rb

@@ -1,5 +1,10 @@
 Sequel.migration do
+  # InnoDB already creates an index for every foreign key column, and will not
+  # drop one a constraint depends on, so on MySQL these indexes are redundant
+  # and their removal would fail. Skip them there.
   up do
+    next if [:mysql, :mysql2].include?(database_type)
+
     add_index :super_auth_edges, :user_id
     add_index :super_auth_edges, :group_id
     add_index :super_auth_edges, :role_id
@@ -8,6 +13,8 @@ Sequel.migration do
   end
 
   down do
+    next if [:mysql, :mysql2].include?(database_type)
+
     drop_index :super_auth_edges, :user_id
     drop_index :super_auth_edges, :group_id
     drop_index :super_auth_edges, :role_id

data/db/migrate_activerecord/20250101000001_create_super_auth_users.rb

@@ -1,7 +1,7 @@
 class CreateSuperAuthUsers < ActiveRecord::Migration[7.0]
   def change
     create_table :super_auth_users do |t|
-      t.string :external_id
+      t.column :external_id, SuperAuth.external_id_type
       t.string :external_type
       t.string :name
       t.timestamps default: -> { "CURRENT_TIMESTAMP" }

data/db/migrate_activerecord/20250101000005_create_super_auth_resources.rb

@@ -2,7 +2,7 @@ class CreateSuperAuthResources < ActiveRecord::Migration[7.0]
   def change
     create_table :super_auth_resources do |t|
       t.string :name
-      t.string :external_id
+      t.column :external_id, SuperAuth.external_id_type
       t.string :external_type
       t.timestamps default: -> { "CURRENT_TIMESTAMP" }
     end

data/db/migrate_activerecord/20250101000007_create_super_auth_authorizations.rb

@@ -3,7 +3,7 @@ class CreateSuperAuthAuthorizations < ActiveRecord::Migration[7.0]
     create_table :super_auth_authorizations do |t|
       t.integer :user_id
       t.string :user_name
-      t.string :user_external_id
+      t.column :user_external_id, SuperAuth.external_id_type
       t.string :user_external_type
       t.datetime :user_created_at
       t.datetime :user_updated_at
@@ -32,7 +32,7 @@ class CreateSuperAuthAuthorizations < ActiveRecord::Migration[7.0]
 
       t.integer :resource_id
       t.string :resource_name
-      t.string :resource_external_id
+      t.column :resource_external_id, SuperAuth.external_id_type
       t.string :resource_external_type
 
       t.timestamps default: -> { "CURRENT_TIMESTAMP" }

data/db/migrate_activerecord/20250101000010_add_super_auth_label_to_super_auth_resources.rb

@@ -0,0 +1,5 @@
+class AddSuperAuthLabelToSuperAuthResources < ActiveRecord::Migration[7.0]
+  def change
+    add_column :super_auth_resources, :super_auth_label, :string
+  end
+end

data/exe/super_auth-editor

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# Serves the super_auth graph editor on loopback. See `super_auth-editor --help`.
+require "super_auth/editor/cli"
+
+begin
+  SuperAuth::Editor::CLI.run(ARGV)
+rescue SuperAuth::Error => e
+  abort "super_auth-editor: #{e.message}"
+end

data/lib/generators/super_auth/install/templates/README

@@ -6,24 +6,29 @@ Next steps:
 
 1. Run migrations to create the database tables:
 
-   SuperAuth.install_migrations
+   rails db:migrate
 
-   You can run this in the Rails console or add it to a rake task.
+   (the engine adds its ActiveRecord migrations to your app)
 
-2. Mount the engine in config/routes.rb:
+2. Mount the engine in config/routes.rb, inside your own authentication.
+   It serves the graph editor, which has no authentication of its own:
 
-   mount SuperAuth::Engine => '/super_auth'
+   authenticate :admin do
+     mount SuperAuth::Engine => '/super_auth'
+   end
 
-3. (Optional) Load sample data to see the visualization in action:
+3. (Optional) Load sample data to have a graph to look at:
 
    rails runner "load File.join(SuperAuth::Engine.root, 'db/seeds/sample_data.rb')"
 
-4. Start your Rails server and visit:
+4. Start your Rails server and open the editor:
 
-   http://localhost:3000/super_auth/visualization
+   http://localhost:3000/super_auth
 
-For more information, see:
-- VISUALIZATION.md for full documentation
-- README.md for usage examples
+   Edits change the graph; runtime access comes from the compiled table,
+   so press Recompile (or run SuperAuth::ActiveRecord::Authorization.compile!)
+   after editing.
+
+For more information, see README.md ("Graph editor") and USAGE.md.
 
 ===============================================================================

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

@@ -2,8 +2,19 @@
 # The SuperAuth Railtie automatically connects to your database and loads all
 # models on boot. Use this file for any additional configuration.
 #
-# SuperAuth.setup do |config|
-#   # Raise an error when a query runs without a current user set.
-#   # Default is :none (returns empty results silently).
-#   # config.missing_user_behavior = :raise
-# end
+SuperAuth.setup do |config|
+  # Column type for external id columns, created when the migrations run.
+  # Match your application's primary key type (:bigint, :uuid, :string, ...)
+  # so comparisons against your tables' pks are natively typed. Rails
+  # defaults to bigint pks. Must be set before running super_auth migrations.
+  config.external_id_type = :bigint
+
+  # Raise an error when a query runs without a current user set.
+  # Default is :none (returns empty results silently).
+  # config.missing_user_behavior = :raise
+
+  # Postgres row-level security: enable it per table with
+  #   rails generate super_auth:rls Model ...
+  # then wrap request work in SuperAuth.as(current_user) { ... } wherever
+  # database-level enforcement should apply.
+end

data/lib/generators/super_auth/rls/rls_generator.rb

@@ -0,0 +1,22 @@
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module SuperAuth
+  module Generators
+    class RlsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      # The model class names typed on the command line, verbatim:
+      # `rails g super_auth:rls Document Invoice` => ["Document", "Invoice"]
+      argument :model_names, type: :array, banner: "Model Model ..."
+
+      desc "Creates a migration enabling Postgres row-level security for the given models"
+
+      def create_migration_file
+        migration_template 'migration.rb.erb', 'db/migrate/enable_super_auth_rls.rb'
+      end
+    end
+  end
+end

data/lib/generators/super_auth/rls/templates/migration.rb.erb

@@ -0,0 +1,15 @@
+class EnableSuperAuthRls < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def up
+<% model_names.each do |model| -%>
+    SuperAuth::RLS.enable(:<%= model.tableize.tr('/', '_') %>, resource_type: "<%= model.camelize %>")
+<% end -%>
+    # Roles allowed to bypass the policies (migrations, seeds, admin jobs):
+    # SuperAuth::RLS.grant_system(:app_admin)
+  end
+
+  def down
+<% model_names.each do |model| -%>
+    SuperAuth::RLS.disable(:<%= model.tableize.tr('/', '_') %>)
+<% end -%>
+  end
+end

data/lib/super_auth/active_record/by_current_user.rb

@@ -1,4 +1,24 @@
 module SuperAuth::ActiveRecord::ByCurrentUser
+  # Records are filtered to those the current user holds an authorization for,
+  # keyed by the querying class's name. Because a subclass is its own resource
+  # type, privileged methods can be placed on a subclass whose access must be
+  # approved explicitly — a grant on the base class does not flow down:
+  #
+  #   class Resource < ApplicationRecord
+  #     super_auth
+  #
+  #     class ResourceRestartPermission < Resource
+  #       def restart!
+  #         # dangerous restart operation
+  #       end
+  #     end
+  #   end
+  #
+  # Resource::ResourceRestartPermission shares the base class's table and rows,
+  # but loading it requires an authorization whose resource_external_type is
+  # "Resource::ResourceRestartPermission" (edges to a SuperAuth::Resource
+  # registered with that external_type). If you can't load the object, you
+  # can't call the method.
   def self.included(base)
     base.send(:default_scope, **{all_queries: true}) do
       if SuperAuth.current_user.blank?
@@ -10,7 +30,7 @@ module SuperAuth::ActiveRecord::ByCurrentUser
         self
       else
         user_where =
-        if SuperAuth.current_user.is_a?(SuperAuth::ActiveRecord::User)
+        if SuperAuth.internal_user?(SuperAuth.current_user)
           { user_id: SuperAuth.current_user.id }
         else
           { user_external_id: SuperAuth.current_user.id, user_external_type: SuperAuth.current_user.class.name }
@@ -26,7 +46,10 @@ module SuperAuth::ActiveRecord::ByCurrentUser
         if type_level.exists?
           self
         else
-          # Per-record authorization: filter to specific records the user can access.
+          # Per-record authorization: filter to specific records the user can
+          # access. No type handling here: the external id columns are created
+          # with the app's pk type (SuperAuth.external_id_type at install
+          # time), so the comparison is natively typed.
           where(
             id: SuperAuth::ActiveRecord::Authorization
                 .where(**user_where, resource_external_type: resource_type)
@@ -36,7 +59,4 @@ module SuperAuth::ActiveRecord::ByCurrentUser
       end
     end
   end
-
-  module ClassMethods
-  end
 end

data/lib/super_auth/active_record/resource.rb

@@ -1,4 +1,45 @@
 class SuperAuth::ActiveRecord::Resource < ActiveRecord::Base
   self.table_name = 'super_auth_resources'
   belongs_to :external, polymorphic: true, optional: true
+
+  # `super_auth_label` is a stored snapshot of the application record's human
+  # name, so the editor can render "Gulf War presumptive" instead of
+  # Claim#3a00b6fa and `super_auth-editor` can do it against a bare
+  # SUPER_AUTH_DATABASE_URL with no application loaded. It carries the prefix
+  # for the same reason the opt-in method on the host's model does: `label` is
+  # a name applications want for themselves.
+  #
+  # Deriving it here means a host that already syncs its resources gets labels
+  # with no extra wiring; renames still need refresh_label!, since they do not
+  # write this row.
+  before_save :set_label, if: :external_id?
+
+  # Re-derive the label after the application record is renamed. Hosts call it
+  # from whatever already syncs the node; super_auth:labels:backfill calls it
+  # for every row.
+  def refresh_label!
+    derived = derived_label
+    update_column(:super_auth_label, derived) unless derived.nil?
+  end
+
+  private
+
+  def set_label
+    derived = derived_label
+    self.super_auth_label = derived unless derived.nil?
+  end
+
+  # ponytail: a nil derivation never overwrites a stored label, in either
+  # path, and never fails the save. Three things derive nil and none of them
+  # means "this record has no name": RLS makes the application record
+  # unreadable without an asserted identity, external_type is a plain string
+  # that can name a class this process has not loaded, and type-level rows
+  # (external_id IS NULL) have no record to name at all. Writing nil for any
+  # of them would turn "this label is stale" into data, which is the failure
+  # this column exists to avoid.
+  def derived_label
+    SuperAuth.label_for(external)
+  rescue NameError
+    nil
+  end
 end

data/lib/super_auth/active_record/user.rb

@@ -5,7 +5,9 @@ class SuperAuth::ActiveRecord::User < ActiveRecord::Base
 
   def model_name = ActiveModel::Name.new(:user)
 
-  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.find_by(name: "system") == self
   def self.system = find_or_create_by(name: "system")
 
   has_many :edges, class_name: 'SuperAuth::ActiveRecord::Edge'

data/lib/super_auth/authorization.rb

@@ -1,2 +1,14 @@
 class SuperAuth::Authorization < Sequel::Model(:super_auth_authorizations)
+  # Clears and repopulates the compiled table from the current graph, inside
+  # one transaction, and returns the row count. Row by row, like
+  # SuperAuth::ActiveRecord::Authorization.compile!; a single INSERT ... SELECT
+  # is a separate change. Runtime enforcement (ByCurrentUser, the RLS policies)
+  # reads only this table, so every edit to the graph is inert until this runs.
+  def self.compile!
+    db.transaction do
+      dataset.delete
+      SuperAuth::Edge.authorizations.each { |row| dataset.insert(row) }
+      dataset.count
+    end
+  end
 end