super_auth 0.8.0 → 0.9.0

data/USAGE.md

@@ -58,11 +58,11 @@ This creates an initializer at `config/initializers/super_auth.rb`. The SuperAut
 **Step 3.** Copy the SuperAuth migrations into your app and run them:
 
 ```bash
-rails railties:install:migrations
+rails super_auth:install:migrations   # the engine-scoped task; railties:install:migrations also works but copies every mounted engine's migrations
 rails db:migrate
 ```
 
-This creates the `super_auth_*` tables (users, groups, roles, permissions, resources, edges, authorizations) alongside your application's tables. The engine does not run its migrations by itself, so repeat both commands after upgrading to a version that ships a new one (0.8.0 adds migration 11, `parent_id` on resources).
+This creates the `super_auth_*` tables (users, groups, roles, permissions, resources, edges, authorizations) alongside your application's tables. The engine does not run its migrations by itself, so repeat both commands after upgrading to a version that ships a new one (0.8.0 added migration 11, `parent_id` on resources; 0.9.0 adds 12, two indexes, and 13, the resource tree guard). A table under Postgres row-level security also needs `SuperAuth::RLS.enable` re-run after a gem upgrade, since a policy already in the database does not change on its own — see "Keeping the policy current" in the README.
 
 **Step 4.** Set the current user in your controller:
 
@@ -95,6 +95,8 @@ Post.all                        # only posts the current user can access
 Post.where(published: true)     # scoped AND filtered by authorization
 ```
 
+A record that belongs to something can be reached through the column that says so, with no node per record: `super_auth parent: { column: :blog_id, resource_type: ["Blog::Member"] }` also admits every post whose `blog_id` the user holds a `Blog::Member` row for. See [Parent-record grants](#parent-record-grants-tenancy-from-a-column).
+
 **Step 6 (optional).** Mount the engine, which serves the graph editor. It has no
 authentication of its own, so mount it inside yours:
 
@@ -224,6 +226,8 @@ backend.ancestors_dataset.all        # => [Engineering, Company]
 company.descendants_dataset.all      # => [Engineering, Backend, Frontend]
 ```
 
+A node cannot be made its own parent or moved under one of its own descendants: the save fails validation (`parent_id is inside the node's own subtree, which would close a cycle`). A cycle would make every node in it an ancestor of every other, so a grant on any of them would reach all of their subtrees, and nothing would fail loudly. `compile!` refuses a table with a cycle in it too, naming the nodes, for writes that went around the model. The same holds for roles and resources.
+
 ### Roles (hierarchical)
 
 Roles work exactly like Groups -- they support the same nesting.
@@ -277,35 +281,51 @@ q3.parent                        # => reports
 
 The compiled row for `q3` carries `q3`'s own `external_type` and `external_id` whether the edge was drawn to `q3` or to `reports`: runtime reads the record a grant reaches and nothing about how it got there. There are no resource path columns in the compiled table; "granted through which container" is a question for the graph (`parent`, `children_dataset`) and the editor.
 
-#### Deprecated: type-level (wildcard) nodes
+#### Type-level grants
 
-A node with an `external_type` and no `external_id` is a type-level, or wildcard, node: at runtime it means every record of that type, present and future. `ByCurrentUser` skips per-record filtering when one matches, and the row-level security policy's `resource_external_id IS NULL OR` clause does the same in the database.
+A node with an `external_type` and no `external_id` is a type-level grant, or wildcard: at runtime it means every record of that type, present and future. `ByCurrentUser` skips per-record filtering when one matches, and the row-level security policy's type-level step does the same in the database. It is a supported, permanent primitive — "this principal may act on every record of this type" has no cheaper spelling, and a platform admin tier is made of them. One way they go wrong: a type string that resolves to no scoped model — the class was moved to a read-only base with a `Writable` subclass and the scope went with it, or the constant is gone — compiles rows that admit nobody. In Rails, `SuperAuth::ActiveRecord::Resource.dead_type_level_nodes` lists them.
 
 ```ruby
-# Deprecated: every Post, present and future
+# Every Post, present and future
 posts = SuperAuth::Resource.create(name: "posts", external_type: "Post")
 ```
 
-Wildcard nodes are deprecated as of 0.8.0 and still work: `compile!` warns once per compile naming the ones that exist (silence it with `SuperAuth.deprecator.silenced = true`, or in Rails through `config.active_support.deprecation`), and no removal version is promised. What `compile!` refuses, with a `SuperAuth::Error` naming the node ids, is a wildcard with a parent or children: nested in the tree it would reach every record of its type through its ancestors' grants. A wildcard stays at the root with no children, or gets an `external_id`.
+What a type-level node may not do is join the tree. `compile!` refuses, with a `SuperAuth::Error` naming the node ids, a type-level node with a parent or children: nested in the tree it would reach every record of its type through its ancestors' grants, and nodes beneath it could be reached only through a grant that already covers them. The subtree walk never descends from one either, so a granted type-level node compiles to its own `(type, NULL)` row and nothing else, on every path. A type-level node stays at the root with no children, or gets an `external_id`.
 
-Under Postgres row-level security a wildcard remains the only way to authorize INSERT this release. The policy is `FOR ALL` with `USING` reused as `WITH CHECK`, and a per-record row can only match an id that has already been registered and compiled. A container is not a replacement for it there: it loses INSERT, it needs a node saved and a full recompile for every new record, and saving that node needs a role that can write the gem's tables, which `enable` grants `SELECT` on only. The successor is a grant on a parent record (`SuperAuth::RLS.enable(:documents, resource_type: "Document", parent: { column: :folder_id, resource_type: "Folder" })`, with a `ByCurrentUser` mirror), planned for the next release.
+Two finders, because the nil id is easy to reach by accident: `SuperAuth::Resource.wildcards` is the type-level nodes, and `SuperAuth::Resource.record("Post", post.id)` is the node for one record, which raises `SuperAuth::Error` on a nil id rather than answering with the type-level node — a helper called with an unset foreign key would otherwise grant, revoke or label the grant that covers every Post.
 
-##### Migrating a wildcard to a container
+Destroying a node takes its compiled rows and its edges with it, in the same transaction. Children are left where they are (the foreign key refuses to orphan them), and rows compiled *through* the node for its descendants last until the next compile, as after any other revocation.
 
-Where the type is not under row-level security, or INSERT is not needed, a wildcard becomes a container plus one node per record. Move the edges off the wildcard before destroying it, so the grants survive, then compile. `Post` is a `super_auth` model, so its default scope hides every row from a process with no current user — the loop reads through `unscoped`; where RLS is installed the database enforces the same rule, so the work runs as the system user:
+#### Parent-record grants (tenancy from a column)
 
-```ruby
-wildcard = SuperAuth::Resource.where(external_type: "Post", external_id: nil).first
+A record that belongs to something — a post to a blog, a claim to an organization — can be reached through the column that says so, with no node per record and nothing to recompile when a record is created or moves. Declare the column and the types whose rows admit through it on the model (and, on Postgres, on the policy), then grant the parent's node as usual:
 
-migrate = proc do
-  container = SuperAuth::Resource.create(name: "posts")            # untyped: a container
-  Post.unscoped.find_each do |post|                                  # ByCurrentUser hides every row without a current user
-    SuperAuth::Resource.create(name: post.title, external_type: "Post", external_id: post.id, parent: container)
-  end
-  SuperAuth::Edge.where(resource_id: wildcard.id).update(resource_id: container.id)  # update_all on the ActiveRecord twin
-  wildcard.destroy
+```ruby
+class Post < ApplicationRecord
+  super_auth parent: { column: :blog_id, resource_type: ["Blog::Member"] }
 end
 
+# One node per blog, of a capability type nobody else is granted; grant it, compile
+blog_node = SuperAuth::Resource.create(name: blog.title, external_type: "Blog::Member", external_id: blog.id)
+SuperAuth::Edge.create(user: alice, resource: blog_node)
+SuperAuth::ActiveRecord::Authorization.compile!
+
+Post.where(blog_id: blog.id)   # alice sees every post of the blog, present and future
+```
+
+The steps are OR'd: a per-record grant on one post still admits it, with or without a `blog_id`, and a type-level `Post` grant still admits everything. A type-level `Blog::Member` row admits nothing (a column holds an id; NULL equals none), and parents do not chain. The parent type is a capability type nobody else is granted — `Blog::Member`, never bare `Blog`, whose per-record node any grant on the blog reaches — and the list under the column names every tier that may touch the row at all, because the database policy must never be narrower than any tier's ORM scope. The full contract, the Postgres side, and the platform-only subclass that must declare no parent are in the README ("Postgres Row-Level Security" and "Permission-Gated Models").
+
+##### Moving tenancy from per-record nodes to a parent column
+
+A table that has been carrying one node per record per member — a post node for every blog member — can drop those rows for the column. Never delete per-record nodes wholesale: a node with a direct user->resource edge (an owner, a reader granted one record) is that user's only path, and `blog_id` says nothing about them. The rule is that a per-record node may go only when no user->resource edge points at it and no child sits under it; on Postgres, `SuperAuth::RLS.coverage(:posts)` reports what the change does before it is made — `widening` (records the parent step admits that no per-record row did), `loss` (what a type-level holder would lose), `null_parent` (records no parent grant can reach), `orphaned_rows`, and `deletable_nodes`, the rule above as a sample. Over the whole table the rule is one query, and `destroy` purges each node's compiled rows and edges as it goes. Where RLS is installed the work runs as the system user, since the policy hides the rows from a process with no identity:
+
+```ruby
+deletable = SuperAuth::Resource.where(external_type: "Post").exclude(external_id: nil).
+  exclude(id: SuperAuth::Edge.exclude(user_id: nil).exclude(resource_id: nil).select(:resource_id)).
+  exclude(id: SuperAuth::Resource.exclude(parent_id: nil).select(:parent_id))
+
+migrate = proc { deletable.each(&:destroy) }
+
 if SuperAuth::RLS.installed?
   SuperAuth.as(SuperAuth::User.system, &migrate)
 else
@@ -314,8 +334,6 @@ end
 SuperAuth::Authorization.compile!   # SuperAuth::ActiveRecord::Authorization.compile! in Rails
 ```
 
-Under row-level security this loses INSERT on `posts` until the parent-record grant exists, and a `Post` created afterwards needs its own node and a recompile before anyone sees it.
-
 ## Drawing Edges
 
 Edges are the core of SuperAuth. Each edge connects exactly two entities.
@@ -522,7 +540,9 @@ Approve the subclass like any other resource — register a `SuperAuth::Resource
 
 The resource tree is containment, not inheritance. A row compiled through a container copies the descendant node's own `external_type`, which is why the rule above survives nesting — but a `"Post::PostPublishPermission"` node registered *under* the `"Post"` node is a descendant of it and receives every grant on `"Post"`. Register capability nodes as siblings of their base-class nodes, or in a container beside them, never as their children.
 
-For database-side enforcement of the same rules see "Postgres Row-Level Security" in the README (`SuperAuth::RLS.enable` — visibility is derived automatically from `SuperAuth.current_user`).
+A subclass inherits a `parent:` declaration and is still keyed on its own name; re-declaring on the subclass replaces its parents alone, on the one inherited scope. A subclass that exists to be *narrower* than the record's owner — actions even the owner may not take — declares no parent, ever: `Claim::Admin` keyed on `Organization::Admin` "for symmetry" would hand every organization admin those actions on their own organization's claims. The README's "Permission-Gated Models" shows `Claim::Admin` (platform-only, no parent) and `Organization::Admin` (a per-organization node, a legitimate parent type) side by side, because the names collide and the meanings are opposite.
+
+For database-side enforcement of the same rules see "Postgres Row-Level Security" in the README (`SuperAuth::RLS.enable` takes the same `resource_type:` and `parent:`, and lists every class that scopes the table and every tier's parent type, since the policy must never be narrower than any tier's ORM scope).
 
 ### Linking to your app's models
 
@@ -536,15 +556,25 @@ sa_user = SuperAuth::User.create(
   external_type: "User"
 )
 
-# Link a SuperAuth resource to one Post
+# Link a SuperAuth resource to one Post, in a container beside its siblings
+reports = SuperAuth::Resource.create(name: "reports")
 sa_resource = SuperAuth::Resource.create(
   name: post.title,
   external_type: "Post",
-  external_id: post.id
+  external_id: post.id,
+  parent: reports
 )
+SuperAuth::Resource.record("Post", post.id)    # finds it again; raises on a nil id rather than
+                                                # answering with the type-level "Post" node
+
+# Or reach posts through the blog they belong to, with no node per post
+class Post < ApplicationRecord
+  super_auth parent: { column: :blog_id, resource_type: ["Blog::Member"] }
+end
+SuperAuth::Resource.create(name: blog.title, external_type: "Blog::Member", external_id: blog.id)
 ```
 
-When `super_auth` is included in a model, the default scope matches the current user's `id` and class name against `external_id` / `external_type` in the authorizations table. This means your application user objects work directly -- no need to convert to SuperAuth users in the controller. On the resource side it matches the record's class name and `id` against `resource_external_type` / `resource_external_id`; a node with the type and no id matches every record of the type, the deprecated wildcard shape described under [Resources](#resources-hierarchical).
+When `super_auth` is included in a model, the default scope matches the current user's `id` and class name against `external_id` / `external_type` in the authorizations table. This means your application user objects work directly -- no need to convert to SuperAuth users in the controller. On the resource side it matches the record's class name and `id` against `resource_external_type` / `resource_external_id`; a node with the type and no id matches every record of the type, the type-level grant described under [Resources](#resources-hierarchical); and each `parent:` column is matched against the rows of its own types, so a `Blog::Member` row for blog 3 admits every post whose `blog_id` is 3.
 
 ### ActiveRecord models
 
@@ -597,6 +627,18 @@ deployers = SuperAuth::Edge.authorizations.all.select { |a|
 deployers.map { |a| a[:user_name] }.uniq
 ```
 
+**"Why can Alice see this post?"** — once a model declares `parent:`, the compiled table alone no longer answers this: a row is admitted by a compiled row naming a *different* record (the blog), so the answer is a join through the posts table, and `explain` is that join:
+
+```ruby
+SuperAuth.current_user = alice
+Post.super_auth_explain(post)
+# => [{ step: :blog_id, user_external_id: 42, user_external_type: "User",
+#       resource_external_type: "Blog::Member", resource_external_id: 3, ... }]
+# steps: :type_level, :id, or a parent column; [{ step: :system }] for the system user
+```
+
+On Postgres `SuperAuth::RLS.explain(:posts, post.id)` answers the same for the identity asserted on the connection, with no model loaded.
+
 ## Visualization
 
 The graph editor shows the whole graph as five boxes (groups, roles, users,
@@ -695,7 +737,6 @@ auths = SuperAuth::Edge.authorizations.all
 | `SuperAuth.current_user`        | Get the current user                                 |
 | `SuperAuth.install_migrations`  | Create all `super_auth_*` tables                     |
 | `SuperAuth.uninstall_migrations`| Drop all `super_auth_*` tables                       |
-| `SuperAuth.deprecator`          | Where deprecation warnings go; `silenced = true` quiets them |
 
 ### Environment Variables
 

data/db/migrate/12_add_resource_indexes.rb

@@ -0,0 +1,116 @@
+Sequel.migration do
+  # Four lookups that ran as sequence scans. Two are the host's own work
+  # around a record: the compiled table by the resource a row names, and the
+  # resources table by the record a node points at, which every finder for a
+  # record's node runs. The first leads on the id, not the type: a host's
+  # per-record compile is keyed by record, and one record carries several
+  # nodes of different types (Claim and Claim::Writable for one claim), so the
+  # hot slice is "every row for these ids, whatever their type" — id-only by
+  # construction, and a type-leading index can only scan and filter it.
+  #
+  # The other two are the policy's own, and they are Postgres only, since the
+  # policy is and an expression index is not portable. Every step of the
+  # policy matches the asserted identity by casting the column —
+  # a.user_external_id::text and a.user_id::text, cast on the column because
+  # casting the setting would turn a malformed identity into an error inside
+  # every query — and a cast on a column defeats a plain btree unless it is a
+  # no-op. So idx_sa_auth_by_current_user (migration 9) serves the external
+  # half only where SuperAuth.external_id_type is a text type, and nothing has
+  # ever indexed user_id at all. On a uuid or bigint host that is one full
+  # pass over super_auth_authorizations per half per step, once per statement
+  # on every protected table. These two index the expressions the policy
+  # actually writes, so each half seeks instead.
+  #
+  # The internal half is built on every Postgres host: user_id is int4 in
+  # every install (migration 7), int4->text is CoerceViaIO, and `holdings`
+  # emits both identity halves for every step whatever kind of identity is
+  # asserted, so an install that only ever asserts an external user pays for
+  # this one too. The external half is built only where the column's
+  # catalogue type is neither varchar nor text: varchar->text is a
+  # RelabelType, so on the default :string install migration 9's plain btree
+  # already answers the cast as a seek and this index is pure duplication —
+  # 47 MB beside migration 9's 39 MB, and roughly +580 ms per 200,000 rows
+  # written at compile. The catalogue is asked rather than
+  # SuperAuth.external_id_type, because the column is what the policy casts
+  # and a host may have altered it since; a column the query cannot find gets
+  # the index, since the failure that matters is not having one.
+  #
+  # The write cost of the pair is approximate — a 200,000-row compile insert
+  # against a 999,973-row uuid table, individual runs 920-2619 ms: two
+  # indexes 1158 ms (~173k rows/s, 20 MB), four 2538 ms (~79k rows/s, 45 MB),
+  # so about +7 s and +25 MB per 1,000,000 rows compiled.
+  #
+  # CONCURRENTLY on Postgres, which is why the whole migration runs outside a
+  # transaction. A host large enough to need these cannot take an ACCESS
+  # EXCLUSIVE lock on super_auth_authorizations: it sits on the read path of
+  # every statement on every protected table, so a plain CREATE INDEX stalls
+  # the application for the length of the build. The price is that a failed
+  # build leaves an INVALID index behind, holding the name and used by no
+  # planner; re-running the migration is the repair, because the check below
+  # drops an index of one of these names that Postgres marks invalid and
+  # builds it again. That is the one case where a name a host may own is not
+  # left alone, and it costs the host nothing: an invalid index answers no
+  # query, and nothing can take its name while it stands. MySQL 8 builds an
+  # index online by default and SQLite is irrelevant at this scale, so both
+  # keep a plain add_index.
+  no_transaction
+
+  up do
+    is_postgres = database_type == :postgres
+    concurrent = is_postgres ? { concurrently: true } : {}
+
+    # True when the name is taken and the migration should leave it alone. On
+    # Postgres the catalogue is the right question rather than the table's
+    # index list: an index name is unique per schema, so a name taken on any
+    # table blocks this one, and Sequel's `indexes` reports neither an
+    # invalid index nor an index on an expression.
+    taken = lambda do |table, name|
+      next indexes(table).key?(name) unless is_postgres
+
+      row = fetch("SELECT i.indisvalid FROM pg_index i WHERE i.indexrelid = to_regclass(?)", name.to_s).first
+      next false unless row
+      next true if row[:indisvalid]
+
+      run "DROP INDEX CONCURRENTLY IF EXISTS #{literal(Sequel.identifier(name.to_s))}"
+      false
+    end
+
+    unless taken.call(:super_auth_authorizations, :idx_sa_auth_by_resource)
+      add_index :super_auth_authorizations, [:resource_external_id, :resource_external_type],
+        name: :idx_sa_auth_by_resource, **concurrent
+    end
+    unless taken.call(:super_auth_resources, :idx_sa_resources_by_external)
+      add_index :super_auth_resources, [:external_type, :external_id],
+        name: :idx_sa_resources_by_external, **concurrent
+    end
+
+    next unless is_postgres
+
+    unless taken.call(:super_auth_authorizations, :idx_sa_auth_by_internal_user_text)
+      add_index :super_auth_authorizations,
+        [Sequel.lit("(user_id::text)"), :resource_external_type, :resource_external_id],
+        name: :idx_sa_auth_by_internal_user_text, concurrently: true
+    end
+
+    row = fetch(<<~SQL).first
+      SELECT t.typname FROM pg_attribute a JOIN pg_type t ON t.oid = a.atttypid
+      WHERE a.attrelid = to_regclass('super_auth_authorizations')
+        AND a.attname = 'user_external_id' AND a.attnum > 0 AND NOT a.attisdropped
+    SQL
+    external_is_text = row && %w[varchar text].include?(row[:typname])
+
+    unless external_is_text || taken.call(:super_auth_authorizations, :idx_sa_auth_by_current_user_text)
+      add_index :super_auth_authorizations,
+        [Sequel.lit("(user_external_id::text)"), :user_external_type, :resource_external_type, :resource_external_id],
+        name: :idx_sa_auth_by_current_user_text, concurrently: true
+    end
+  end
+
+  # No down: up skipped an index a host already owned under the same name,
+  # and a migration cannot tell afterwards which of the two it created, so a
+  # rollback that dropped by name would take a host's own index with it. An
+  # index left behind costs nothing; a lost one costs a sequence scan on a
+  # hot path. The tables' own drop removes them on a full uninstall.
+  down do
+  end
+end

data/db/migrate/13_add_resource_tree_guard.rb

@@ -0,0 +1,28 @@
+Sequel.migration do
+  # A parent_id cycle in super_auth_resources is a security defect, not
+  # untidiness: every node in a cycle is an ancestor of every other, so a
+  # grant on any of them reaches all of their subtrees, and the walks
+  # terminate on a cycle (UNION), so nothing fails loudly. The models refuse
+  # the shape (SuperAuth::Nestable validate) and compile! refuses to run on it
+  # (assert_acyclic!). This trigger is the third line, for writes that go
+  # around both — a raw UPDATE, a data migration, another language — and
+  # refuses them at the row, with the same two rules: a node is not its own
+  # parent, and its new parent is not inside its own subtree. The walk goes
+  # UP from the new parent with UNION, so a cycle already in the table that
+  # does not include the row terminates instead of looping.
+  #
+  # Postgres only. SQLite and MySQL both have triggers, each in a dialect of
+  # its own with its own limits on what a trigger body may do, and the model
+  # and compile guards already hold there; a second and third implementation
+  # of the same check is not worth what it costs to carry. On those two this
+  # migration does nothing, and says so here rather than in a gap in the
+  # numbering. The SQL lives in SuperAuth::TreeGuard, which a host also calls
+  # from its test setup: db/schema.rb cannot carry a trigger.
+  up do
+    SuperAuth::TreeGuard.install(db: self)
+  end
+
+  down do
+    SuperAuth::TreeGuard.remove(db: self)
+  end
+end

data/db/migrate_activerecord/20250101000001_create_super_auth_users.rb

@@ -4,7 +4,13 @@ class CreateSuperAuthUsers < ActiveRecord::Migration[7.0]
       t.column :external_id, SuperAuth.external_id_type
       t.string :external_type
       t.string :name
-      t.timestamps default: -> { "CURRENT_TIMESTAMP" }
+      # precision: nil so MySQL emits datetime, not datetime(6): MySQL 8
+      # refuses a datetime(6) whose default does not name the same
+      # precision ("Invalid default value for created_at"), which stopped
+      # the chain at migration 1 and made the gem uninstallable there. It
+      # also matches the Sequel twin, whose DateTime is datetime on MySQL;
+      # on Postgres and SQLite it changes nothing.
+      t.timestamps precision: nil, default: -> { "CURRENT_TIMESTAMP" }
     end
   end
 end

data/db/migrate_activerecord/20250101000002_create_super_auth_groups.rb

@@ -3,7 +3,13 @@ class CreateSuperAuthGroups < ActiveRecord::Migration[7.0]
     create_table :super_auth_groups do |t|
       t.string :name, null: false
       t.bigint :parent_id
-      t.timestamps default: -> { "CURRENT_TIMESTAMP" }
+      # precision: nil so MySQL emits datetime, not datetime(6): MySQL 8
+      # refuses a datetime(6) whose default does not name the same
+      # precision ("Invalid default value for created_at"), which stopped
+      # the chain at migration 1 and made the gem uninstallable there. It
+      # also matches the Sequel twin, whose DateTime is datetime on MySQL;
+      # on Postgres and SQLite it changes nothing.
+      t.timestamps precision: nil, default: -> { "CURRENT_TIMESTAMP" }
     end
 
     add_foreign_key :super_auth_groups, :super_auth_groups, column: :parent_id

data/db/migrate_activerecord/20250101000003_create_super_auth_permissions.rb

@@ -2,7 +2,13 @@ class CreateSuperAuthPermissions < ActiveRecord::Migration[7.0]
   def change
     create_table :super_auth_permissions do |t|
       t.string :name, null: false
-      t.timestamps default: -> { "CURRENT_TIMESTAMP" }
+      # precision: nil so MySQL emits datetime, not datetime(6): MySQL 8
+      # refuses a datetime(6) whose default does not name the same
+      # precision ("Invalid default value for created_at"), which stopped
+      # the chain at migration 1 and made the gem uninstallable there. It
+      # also matches the Sequel twin, whose DateTime is datetime on MySQL;
+      # on Postgres and SQLite it changes nothing.
+      t.timestamps precision: nil, default: -> { "CURRENT_TIMESTAMP" }
     end
   end
 end

data/db/migrate_activerecord/20250101000004_create_super_auth_roles.rb

@@ -3,7 +3,13 @@ class CreateSuperAuthRoles < ActiveRecord::Migration[7.0]
     create_table :super_auth_roles do |t|
       t.string :name, null: false
       t.bigint :parent_id
-      t.timestamps default: -> { "CURRENT_TIMESTAMP" }
+      # precision: nil so MySQL emits datetime, not datetime(6): MySQL 8
+      # refuses a datetime(6) whose default does not name the same
+      # precision ("Invalid default value for created_at"), which stopped
+      # the chain at migration 1 and made the gem uninstallable there. It
+      # also matches the Sequel twin, whose DateTime is datetime on MySQL;
+      # on Postgres and SQLite it changes nothing.
+      t.timestamps precision: nil, default: -> { "CURRENT_TIMESTAMP" }
     end
 
     add_foreign_key :super_auth_roles, :super_auth_roles, column: :parent_id

data/db/migrate_activerecord/20250101000005_create_super_auth_resources.rb

@@ -4,7 +4,13 @@ class CreateSuperAuthResources < ActiveRecord::Migration[7.0]
       t.string :name
       t.column :external_id, SuperAuth.external_id_type
       t.string :external_type
-      t.timestamps default: -> { "CURRENT_TIMESTAMP" }
+      # precision: nil so MySQL emits datetime, not datetime(6): MySQL 8
+      # refuses a datetime(6) whose default does not name the same
+      # precision ("Invalid default value for created_at"), which stopped
+      # the chain at migration 1 and made the gem uninstallable there. It
+      # also matches the Sequel twin, whose DateTime is datetime on MySQL;
+      # on Postgres and SQLite it changes nothing.
+      t.timestamps precision: nil, default: -> { "CURRENT_TIMESTAMP" }
     end
   end
 end

data/db/migrate_activerecord/20250101000006_create_super_auth_edges.rb

@@ -6,7 +6,13 @@ class CreateSuperAuthEdges < ActiveRecord::Migration[7.0]
       t.references :permission, foreign_key: { to_table: :super_auth_permissions }, null: true
       t.references :role, foreign_key: { to_table: :super_auth_roles }, null: true
       t.references :resource, foreign_key: { to_table: :super_auth_resources }, null: true
-      t.timestamps default: -> { "CURRENT_TIMESTAMP" }
+      # precision: nil so MySQL emits datetime, not datetime(6): MySQL 8
+      # refuses a datetime(6) whose default does not name the same
+      # precision ("Invalid default value for created_at"), which stopped
+      # the chain at migration 1 and made the gem uninstallable there. It
+      # also matches the Sequel twin, whose DateTime is datetime on MySQL;
+      # on Postgres and SQLite it changes nothing.
+      t.timestamps precision: nil, default: -> { "CURRENT_TIMESTAMP" }
     end
   end
 end

data/db/migrate_activerecord/20250101000007_create_super_auth_authorizations.rb

@@ -35,7 +35,13 @@ class CreateSuperAuthAuthorizations < ActiveRecord::Migration[7.0]
       t.column :resource_external_id, SuperAuth.external_id_type
       t.string :resource_external_type
 
-      t.timestamps default: -> { "CURRENT_TIMESTAMP" }
+      # precision: nil so MySQL emits datetime, not datetime(6): MySQL 8
+      # refuses a datetime(6) whose default does not name the same
+      # precision ("Invalid default value for created_at"), which stopped
+      # the chain at migration 1 and made the gem uninstallable there. It
+      # also matches the Sequel twin, whose DateTime is datetime on MySQL;
+      # on Postgres and SQLite it changes nothing.
+      t.timestamps precision: nil, default: -> { "CURRENT_TIMESTAMP" }
     end
   end
 end

data/db/migrate_activerecord/20250101000012_add_super_auth_resource_indexes.rb

@@ -0,0 +1,89 @@
+class AddSuperAuthResourceIndexes < ActiveRecord::Migration[7.0]
+  # Mirrors db/migrate/12_add_resource_indexes.rb, which says why: the
+  # compiled table by the resource a row names (id first — a per-record
+  # compile slices by ids across several node types), the resources table by
+  # the record a node points at, and, on Postgres only, the two expressions
+  # the policy's identity halves compare (user_external_id::text and
+  # user_id::text), which no plain btree can serve on a uuid or bigint host.
+  # The user_id half is built on every Postgres host, because `holdings`
+  # emits both identity halves for every step whatever kind of identity is
+  # asserted; the user_external_id half is built only where that column's
+  # catalogue type is neither varchar nor text, since varchar->text is a
+  # RelabelType and migration 9's plain btree already answers the cast as a
+  # seek there — a duplicate index of 47 MB and roughly +580 ms per 200,000
+  # rows written at compile. The catalogue is asked rather than
+  # SuperAuth.external_id_type, because the column is what the policy casts.
+  # Approximate write cost of the pair, on a uuid host: a 200,000-row compile
+  # insert goes from 1158 ms with two indexes to 2538 ms with four, about
+  # +7 s and +25 MB per 1,000,000 rows compiled.
+  #
+  # CONCURRENTLY on Postgres, so this migration runs outside a transaction:
+  # super_auth_authorizations is on the read path of every statement on every
+  # protected table, and a plain CREATE INDEX holds ACCESS EXCLUSIVE on it for
+  # the length of the build. A failed build leaves an INVALID index holding
+  # the name; re-running the migration is the repair, since the check below
+  # drops an invalid index of one of these names and builds it again. MySQL 8
+  # builds an index online by default and SQLite is irrelevant at this scale,
+  # so both keep a plain add_index.
+  disable_ddl_transaction!
+
+  def up
+    postgres = connection.adapter_name.match?(/postgres/i)
+    concurrent = postgres ? { algorithm: :concurrently } : {}
+
+    unless taken?(:super_auth_authorizations, :idx_sa_auth_by_resource, postgres)
+      add_index :super_auth_authorizations, [:resource_external_id, :resource_external_type],
+        name: :idx_sa_auth_by_resource, **concurrent
+    end
+    unless taken?(:super_auth_resources, :idx_sa_resources_by_external, postgres)
+      add_index :super_auth_resources, [:external_type, :external_id],
+        name: :idx_sa_resources_by_external, **concurrent
+    end
+
+    return unless postgres
+
+    unless taken?(:super_auth_authorizations, :idx_sa_auth_by_internal_user_text, postgres)
+      add_index :super_auth_authorizations,
+        "(user_id::text), resource_external_type, resource_external_id",
+        name: :idx_sa_auth_by_internal_user_text, algorithm: :concurrently
+    end
+
+    typname = connection.select_value(<<~SQL)
+      SELECT t.typname FROM pg_attribute a JOIN pg_type t ON t.oid = a.atttypid
+      WHERE a.attrelid = to_regclass('super_auth_authorizations')
+        AND a.attname = 'user_external_id' AND a.attnum > 0 AND NOT a.attisdropped
+    SQL
+    return if %w[varchar text].include?(typname)
+
+    unless taken?(:super_auth_authorizations, :idx_sa_auth_by_current_user_text, postgres)
+      add_index :super_auth_authorizations,
+        "(user_external_id::text), user_external_type, resource_external_type, resource_external_id",
+        name: :idx_sa_auth_by_current_user_text, algorithm: :concurrently
+    end
+  end
+
+  # No down, for the reason in the Sequel twin: up skipped an index the host
+  # already owned under the same name, and a rollback dropping by name would
+  # take it with it.
+  def down
+  end
+
+  private
+
+  # True when the name is taken and this migration should leave it alone. On
+  # Postgres the catalogue answers it: an index name is unique per schema, and
+  # index_name_exists? reports neither an invalid index nor one on an
+  # expression. An invalid index — what a failed CREATE INDEX CONCURRENTLY
+  # leaves — is dropped rather than kept, since it answers no query and no
+  # other index can take its name while it stands.
+  def taken?(table, name, postgres)
+    return connection.index_name_exists?(table, name) unless postgres
+
+    valid = connection.select_value("SELECT i.indisvalid FROM pg_index i WHERE i.indexrelid = to_regclass(#{connection.quote(name.to_s)})")
+    return false if valid.nil?
+    return true if ActiveRecord::Type::Boolean.new.cast(valid)
+
+    connection.execute("DROP INDEX CONCURRENTLY IF EXISTS #{connection.quote_table_name(name.to_s)}")
+    false
+  end
+end

data/db/migrate_activerecord/20250101000013_add_resource_tree_guard_to_super_auth_resources.rb

@@ -0,0 +1,15 @@
+class AddResourceTreeGuardToSuperAuthResources < ActiveRecord::Migration[7.0]
+  # Mirrors db/migrate/13_add_resource_tree_guard.rb, which says why: a
+  # parent_id cycle silently widens grants, the models and compile! refuse
+  # it, and this trigger refuses it for writes that go around them. Postgres
+  # only; a no-op elsewhere. The SQL lives in SuperAuth::TreeGuard so a host
+  # can install it from its test setup as well: db/schema.rb cannot carry a
+  # trigger, so a test database built from it has none.
+  def up
+    SuperAuth::TreeGuard.install(db: SuperAuth.db)
+  end
+
+  def down
+    SuperAuth::TreeGuard.remove(db: SuperAuth.db)
+  end
+end

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

@@ -6,11 +6,13 @@ Next steps:
 
 1. Copy the engine's migrations into your app and run them:
 
-   rails railties:install:migrations
+   rails super_auth:install:migrations
    rails db:migrate
 
    (the engine does not run its migrations by itself; repeat both after an
-   upgrade that ships a new one)
+   upgrade that ships a new one, and re-run SuperAuth::RLS.enable for any
+   table under row-level security, since a policy already in the database
+   does not change with the gem — SuperAuth::RLS.stale lists the ones behind)
 
 2. Mount the engine in config/routes.rb, inside your own authentication.
    It serves the graph editor, which has no authentication of its own:

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

@@ -13,8 +13,11 @@ SuperAuth.setup do |config|
   # Default is :none (returns empty results silently).
   # config.missing_user_behavior = :raise
 
-  # Postgres row-level security: enable it per table with
+  # Wrap request work in SuperAuth.as(current_user) { ... } — in an
+  # around_action, and around jobs — so the ByCurrentUser scope has a user.
+  #
+  # Postgres row-level security is optional and off until you ask for it:
   #   rails generate super_auth:rls Model ...
-  # then wrap request work in SuperAuth.as(current_user) { ... } wherever
-  # database-level enforcement should apply.
+  # Once that migration has run, the same SuperAuth.as call also asserts the
+  # identity the policies read, so turning it on costs no application change.
 end

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

@@ -2,6 +2,8 @@ class EnableSuperAuthRls < ActiveRecord::Migration[<%= ActiveRecord::Migration.c
   def up
 <% model_names.each do |model| -%>
     SuperAuth::RLS.enable(:<%= model.tableize.tr('/', '_') %>, resource_type: "<%= model.camelize %>")
+    # Tenancy, not capability: a parent grant admits every row whose column holds a granted record's id, so list every type that may touch the row at all and let the ORM decide who writes.
+    #   parent: { column: :organization_id, resource_type: ["Organization::Member"] }
 <% end -%>
     # Roles allowed to bypass the policies (migrations, seeds, admin jobs):
     # SuperAuth::RLS.grant_system(:app_admin)

data/lib/super_auth/active_record/authorization.rb

@@ -8,20 +8,24 @@ class SuperAuth::ActiveRecord::Authorization < ActiveRecord::Base
       from("(#{SuperAuth::Edge.authorizations.sql}) as super_auth_authorizations".squish)
     end
 
-    # Clears and repopulates the authorizations table from the current graph.
-    # The wildcard guard runs before the delete, so a refused compile leaves
-    # the previous rows in place; the deprecation notice follows the commit.
+    # Clears and repopulates the authorizations table from the current graph
+    # with one INSERT ... SELECT on this connection, and returns the row
+    # count; see SuperAuth::Authorization.compile!. The guards run before the
+    # delete, so a refused compile leaves the previous rows in place.
     def compile!
       transaction do
         # Sequel runs on this transaction's connection (sequel-activerecord_connection),
         # so the JIT switch lands in it; see SuperAuth::Authorization.compile!.
         SuperAuth.db.run "SET LOCAL jit = off" if SuperAuth.db.database_type == :postgres
-        SuperAuth::Resource.assert_compilable!
+        SuperAuth::Authorization.assert_compilable!
         delete_all
-        from_graph.each { |auth| create!(auth.attributes.except("id")) }
+        connection.execute(
+          SuperAuth.db[:super_auth_authorizations].insert_sql(
+            SuperAuth::Edge::AUTHORIZATION_COLUMNS, SuperAuth::Authorization.compile_source
+          )
+        )
+        count
       end
-      SuperAuth::Resource.warn_deprecated_wildcards
-      count
     end
   end
 end