super_auth 0.7.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.
+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:
 
@@ -134,7 +136,7 @@ SuperAuth models authorization as a graph with 5 entity types:
 | **Group**      | Organizational units (teams, departments, etc) | Yes (nested)  |
 | **Role**       | Job titles or permission sets                  | Yes (nested)  |
 | **Permission** | Actions (read, write, deploy, etc)             | No            |
-| **Resource**   | Things being protected (files, APIs, records)  | No            |
+| **Resource**   | Things being protected (files, APIs, records)  | Yes (nested)  |
 
 **Edges** are connections drawn between any two entities. SuperAuth traverses the graph to find all valid paths from a User to a Resource. If a path exists, access is granted.
 
@@ -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.
@@ -245,20 +249,89 @@ write_perm  = SuperAuth::Permission.create(name: "write")
 deploy_perm = SuperAuth::Permission.create(name: "deploy")
 ```
 
-### Resources
+### Resources (hierarchical)
 
-Resources represent what you are protecting. They can link to your app's models.
+Resources represent what you are protecting. A node with neither `external_type` nor `external_id` is a container; a node with both points at one record of your application. Resources nest like groups and roles, and a grant on a node reaches the node and every node under it, so the usual shape is a container per folder, project, tenant or whatever your application nests records under, with the records registered beneath it.
 
 ```ruby
-# Named resource
+# A named resource with nothing behind it
 staging = SuperAuth::Resource.create(name: "staging")
 
-# Linked to an ActiveRecord model
-posts = SuperAuth::Resource.create(
-  name: "posts",
-  external_id: nil,
-  external_type: "Post"
+# A container, and a record of your app registered under it
+reports = SuperAuth::Resource.create(name: "reports")
+q3 = SuperAuth::Resource.create(
+  name: "Q3 report",
+  external_type: "Post",
+  external_id: post.id,
+  parent: reports
 )
+
+# A grant on the container reaches q3, and every node registered under
+# reports later, as of the next compile!
+SuperAuth::Edge.create(permission: read_perm, resource: reports)
+```
+
+Navigate the tree the same way as groups:
+
+```ruby
+SuperAuth::Resource.roots        # nodes with no parent
+reports.children_dataset.all     # => [q3]
+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.
+
+#### Type-level grants
+
+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
+# Every Post, present and future
+posts = SuperAuth::Resource.create(name: "posts", external_type: "Post")
+```
+
+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`.
+
+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.
+
+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.
+
+#### Parent-record grants (tenancy from a column)
+
+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:
+
+```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
+  SuperAuth.db.transaction(&migrate)
+end
+SuperAuth::Authorization.compile!   # SuperAuth::ActiveRecord::Authorization.compile! in Rails
 ```
 
 ## Drawing Edges
@@ -311,6 +384,8 @@ SuperAuth automatically evaluates 5 pathing strategies and unions the results. Y
 
 When groups or roles are nested, SuperAuth considers the full tree. If you assign a user to a parent group, they can access resources through roles attached to that group *and all its descendants*.
 
+Resources nest too, at the other end of the path: a grant on a container reaches every node registered under it (see [Resources](#resources-hierarchical)).
+
 ```ruby
 # Bethany is in Company (the root group)
 SuperAuth::Edge.create(user: bethany, group: company)
@@ -349,6 +424,8 @@ auth[:resource_id]      # Integer
 auth[:resource_name]    # "staging"
 ```
 
+`resource_id` and `resource_name` are the node the grant reaches: a row compiled through a container names the descendant, not the container, and there is no resource path column (see [Resources](#resources-hierarchical)).
+
 ### Filter by user
 
 ```ruby
@@ -461,7 +538,11 @@ Post::PostPublishPermission.find(id) # needs a "Post::PostPublishPermission" gra
 
 Approve the subclass like any other resource — register a `SuperAuth::Resource` with `external_type: "Post::PostPublishPermission"` and draw edges to it, then recompile with `SuperAuth::ActiveRecord::Authorization.compile!`.
 
-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`).
+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.
+
+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
 
@@ -475,14 +556,25 @@ sa_user = SuperAuth::User.create(
   external_type: "User"
 )
 
-# Link a SuperAuth resource to your app's Post model
+# 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: "posts",
-  external_type: "Post"
+  name: post.title,
+  external_type: "Post",
+  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.
+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
 
@@ -535,12 +627,26 @@ 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,
-permissions, resources); click any record to trace what it can reach and what reaches
-it, connect records to draw edges, delete records and edges, and recompile. See the
-README's "Graph editor" section for the full description.
+permissions, resources), drawing groups, roles and resources as trees; click any record
+to trace what it can reach and what reaches it, connect records to draw edges, create
+records (including a resource container under a chosen parent), delete records and
+edges, and recompile. The editor makes containers; your application registers records
+under them. See the README's "Graph editor" section for the full description.
 
 - Rails: mount the engine inside your own authentication (Step 6 above) and open
   `http://localhost:3000/super_auth`.
@@ -577,8 +683,8 @@ write  = SuperAuth::Permission.create(name: "write")
 deploy = SuperAuth::Permission.create(name: "deploy")
 
 # Resources
-api       = SuperAuth::Resource.create(name: "api", external_type: "API")
-dashboard = SuperAuth::Resource.create(name: "dashboard", external_type: "Dashboard")
+api       = SuperAuth::Resource.create(name: "api")
+dashboard = SuperAuth::Resource.create(name: "dashboard")
 prod_db   = SuperAuth::Resource.create(name: "production_db")
 
 # Users

data/db/migrate/11_add_parent_id_to_resources.rb

@@ -0,0 +1,32 @@
+Sequel.migration do
+  # Resources nest like groups and roles (2_groups.rb): same integer type as
+  # the pk, deferrable only where supported. The index is skipped on MySQL
+  # for the reason in 8_add_indexes_to_edges.rb — InnoDB indexes the foreign
+  # key column itself and will not drop that index while the constraint
+  # stands. Both branches compute database_type before alter_table: inside
+  # the block self is the generator.
+  up do
+    is_postgres = database_type == :postgres
+    is_mysql = [:mysql, :mysql2].include?(database_type)
+
+    alter_table(:super_auth_resources) do
+      if is_postgres
+        add_foreign_key :parent_id, :super_auth_resources, deferrable: true, type: :integer
+      else
+        add_foreign_key :parent_id, :super_auth_resources, type: :integer
+      end
+      add_index :parent_id unless is_mysql
+    end
+  end
+
+  # drop_foreign_key drops the constraint and then the column; MySQL refuses
+  # to drop a column a constraint still depends on.
+  down do
+    is_mysql = [:mysql, :mysql2].include?(database_type)
+
+    alter_table(:super_auth_resources) do
+      drop_index :parent_id unless is_mysql
+      drop_foreign_key :parent_id
+    end
+  end
+end

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/20250101000011_add_parent_id_to_super_auth_resources.rb

@@ -0,0 +1,9 @@
+class AddParentIdToSuperAuthResources < ActiveRecord::Migration[7.0]
+  # Mirrors db/migrate/11_add_parent_id_to_resources.rb. No index on MySQL:
+  # InnoDB indexes the foreign key column itself.
+  def change
+    add_column :super_auth_resources, :parent_id, :bigint
+    add_foreign_key :super_auth_resources, :super_auth_resources, column: :parent_id
+    add_index :super_auth_resources, :parent_id unless connection.adapter_name.match?(/mysql|trilogy/i)
+  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