super_auth 0.4.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d15415f81b29b08a690f0223fe01fd888177085f479adb902ab5103002e7292
-  data.tar.gz: 6bc43afccfc699cbf2f8d67c6af32226cfa8989f2e188bbe919835529b488a43
+  metadata.gz: ce52cd6a9867c21405fe203e87a765372b5b0febd49109286711c7e546c5118a
+  data.tar.gz: 1b67868c607adfa20b6832eb08e7bbf5ecaabe468a92a7ca4a8e408a8f3f2316
 SHA512:
-  metadata.gz: 8fc62a59a8291668b01d3a4a012422f764302534f5acc7be6d5954e2dfa4427cd69d7b5f81d65fb96a9be77f1c3c328ce4785071ba2310e7c2cbecf1c1174f9f
-  data.tar.gz: c5012e5e5fdebb90c46326ed8438e939b4c37562730aa33078eecc9dd74debb07c0154509c90549c4dbc783aa4f14e7d2353e63d814571e22e018f45439d3991
+  metadata.gz: '0582f16e103f0a1a00e7ac77edc49a3ba35f59cd0d0c98f4a98f1529c6452ca2adad7f1543df9251e923a8c805a0bce04a95c3fe17d8be86b02063b7b578b1a4'
+  data.tar.gz: f28dedeb421ee5ea689914429e5dac616f8f3a5efa99272b2e4aea2c715c5c880670936483bcb4cfe8f7e5344cff9c72a917296d6cbdb2a2d92213067a09ac29

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-07
+
+### Fixed
+
+- The editor's Groups and Roles boxes drew a flat list ordered by name and faked the hierarchy with indentation, so a child appeared nested under whichever unrelated node happened to sort directly above it — a group named `org:451ed5a8…` sorts between "Lawyers" and "Organizations" and was drawn under Lawyers, while its real parent rendered below its own child. Group grants flow to members of descendant groups, so "which parent does this hang under" is the question the editor is opened to answer, and it was answering it wrong. `/api/graph` now returns nested types ordered by ancestor name path, so each child follows its own parent with siblings alphabetical among themselves. Display only: no `parent_id` changes, and the client's `depthOf` is untouched. The order stays total for a broken tree — a dangling `parent_id` sorts as a root, and a parent cycle terminates rather than hanging the sort.
+
+### Added
+
+- `super_auth_resources.super_auth_label`, a nullable column holding the human name of the application record a resource node points at, so the editor can render "Gulf War presumptive" where it rendered `Claim#3a00b6fa-2998-41ba-953f-a3b0de1876b3`. The label is stored rather than resolved at render time for three reasons: the editor reads bare Sequel models with no association to the application, `super_auth-editor` serves the same UI against a bare `SUPER_AUTH_DATABASE_URL` with no application loaded at all, and RLS makes exactly the largest protected resource types unreadable without an asserted identity — a live lookup would return empty labels for those and full labels for everything else, which reads as data rather than as a missing permission. The column carries the prefix for the same reason the opt-in method does: `label` is a name applications want for themselves. Migration 10 in both `db/migrate/` and `db/migrate_activerecord/`.
+- `SuperAuth.label_for(record)` derives that name by convention rather than configuration: `super_auth_label` if the model defines it, then `name`, then `title`. Never `to_s` — the label sits where `Type#id` otherwise renders, and `#<Claim:0x000055…>` is worse than the id it would replace.
+- `SuperAuth::ActiveRecord::Resource` derives its label on save, so a host that already syncs resource nodes gets labels with no extra wiring, and `#refresh_label!` re-derives it after the application record is renamed, which does not write the node. A nil derivation never overwrites a stored label: RLS blanking the record, an `external_type` naming a class this process has not loaded, and a type-level row (`external_id IS NULL`) all derive nil, and none of them means the record has no name.
+- The editor renders the label in the slot that held `Type#id`, demoting `Type#id` to the tooltip, and falls back to today's rendering for a node without one. Its per-box filter now matches everything a row carries — name, label, `external_type` and `external_id` — so a pasted uuid finds its node, which it never did before: the filter only ever looked at `name`.
+- `rake super_auth:labels:backfill` labels existing rows and repairs drift. It asserts the system identity where RLS is installed, because the application tables it reads are the ones RLS protects — run without an identity it would derive nil for the rows that matter most and report success.
+
+A stored label is a snapshot. It drifts between the application record being renamed and the next `refresh_label!` or backfill, and that is the trade: a stale or missing label degrades to the `Type#id` the editor rendered before, never to something wrong. `super_auth_users.name` has always been a denormalized label of the same kind and never refreshes at all, so this is the existing idea finished rather than a new one.
+
+Users are out of scope: `super_auth_users.name` already carries a human name, so user nodes already read as "Jonathan Frias" in the editor. Groups, roles and permissions encode their application link in host-specific name conventions and are a separate job.
+
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- `SuperAuth::RLS.assert(user)` asserts the database identity in the transaction the caller already holds and opens nothing: the `SELECT super_auth_become(...)` half of the SQL contract, or `super_auth_system()` for a system user. For code that changes user mid-transaction or manages its own transaction; `SuperAuth.as` is now this plus a transaction plus restore.
+- `SuperAuth::RLS.installed?` reports whether `enable` has run on the database, so an application that degrades when RLS is absent no longer probes for the SQL functions by signature. A probe written against one signature returns false when the signature changes and turns row-level security off with a green suite, which is what a 0.4.0 probe does against 0.5.0.
+
+### Changed
+
+- `SuperAuth.as` assigns `SuperAuth.current_user` inside the transaction, after the database identity is asserted, so an application that hooks the writer to re-assert does so on the transaction's connection instead of once outside it and once in.
+
+### Removed
+
+- `on_error:` on `SuperAuth.as` and `SuperAuth::RLS.as`, added in 0.5.0. Whether a write survives the block raising is the caller's decision, not the identity wrapper's: rescue inside the block to keep it, let the exception out to roll it back. `as` has one control-flow path again.
+
+## [0.5.0] - 2026-09-07
+
+### Security
+
+- Row-level security: the system bypass is no longer a parameter of `super_auth_become()`. It moved to a separate function, `super_auth_system()`, whose `EXECUTE` privilege `enable` revokes from `PUBLIC`, so the right to bypass every policy is granted per role (`GRANT EXECUTE ON FUNCTION super_auth_system() TO <role>`) instead of coming with the right to assert an identity. `SuperAuth.as(user)` calls it for users whose `system?` is true. Both functions now raise if the calling role is a superuser or has `BYPASSRLS`, because Postgres exempts those roles from row security and the assertion would protect nothing. Breaking for clients that call the SQL directly: `super_auth_become(...)` takes three arguments and the four-argument overload is dropped on the next `enable`; roles that bypass need the grant above.
+
+### Added
+
+- A graph editor, Rails-free, shipped as a mountable Rack app (`SuperAuth::Editor`, `require "super_auth/editor"`) and a command (`super_auth-editor`) that serves it on loopback against `SUPER_AUTH_DATABASE_URL`, with `--migrate` and `--seed` as explicit, opt-in steps. Five boxes with client-side traversal, node and edge CRUD, and a Recompile button. It has no authentication of its own: mount it inside yours. Writes must be JSON, only the eight edge kinds the path strategies read can be created, and the command rejects foreign `Host` headers.
+- `SuperAuth::Authorization.compile!` for applications without ActiveRecord, and `POST /api/compile` in the editor. Runtime enforcement reads only the compiled table, so every graph edit is inert until it runs.
+
+### Fixed
+
+- `ByCurrentUser` now recognises a Sequel `SuperAuth::User` as an internal user and matches it on `user_id`, as the RLS policies already did; before, it was treated as an external object and silently saw nothing. Both layers share `SuperAuth.internal_user?`.
+
+### Removed
+
+- The d3 graph visualizer: `SuperAuth::GraphController`, its view, its JSON API (`/graph/data`, `/graph/authorize`, `/graph/orphaned`, `/graph/compile_authorizations`, and the `/graph/*` create and delete routes), `visualization.html`, and `VISUALIZATION.md`. `mount SuperAuth::Engine => "/super_auth"` now serves the graph editor at that path; it has no authentication of its own, so mount it inside yours. Anything that called the old JSON routes must move to the editor's API or to the models.
+
+### Changed
+
+- `SuperAuth.as(user)` now carries both identities: it sets `SuperAuth.current_user` (read by the `ByCurrentUser` scope) for the block as well as asserting the database identity (read by the RLS policies), and restores both on the way out, on return, on raise, and when nested. `SuperAuth::RLS.as` stays the pure SQL-contract wrapper and now restores the enclosing database identity when it is nested inside a transaction, so an inner block can no longer leave the outer one running as its user. Inside a transaction the caller opened, `as` joins it. One option replaces the wrapper an application used to need: `auto_savepoint: true` makes every nested transaction a savepoint (the ActiveRecord bridge turns it into `joinable: false`), so a save inside the block commits on its own and its `after_commit` hooks fire then. Other keyword options pass through to Sequel's `transaction`. Behaviour change: `SuperAuth.as(nil)` runs the block with `current_user = nil`, so apps with `missing_user_behavior = :raise` now raise on scoped queries inside an anonymous block instead of inheriting whatever the thread-local held before. Clients that probe for the identity function must look for `super_auth_become(text, text, text)`; the four-argument signature is gone (see Security above).
+- `SuperAuth::RLS.enable` grants `SELECT` on `super_auth_authorizations` and `super_auth_users` to `PUBLIC`, so a runtime role needs privileges on the application's tables and nothing else; `SuperAuth::RLS.grant_system(role)` hands out the bypass without hand-written SQL. `system?` on both user models is now a read-only lookup (`.system` still creates the row), so passing SuperAuth user records to `SuperAuth.as` never needs `INSERT`.
+
 ## [0.4.0] - 2026-09-02
 
 ### Security

data/Gemfile

@@ -15,4 +15,9 @@ group :development, :test do
   gem "activerecord"
   gem "sequel-activerecord_connection"
   gem "after_commit_everywhere"
+  # Rack::MockRequest and Rack::Lint for the editor specs, and a server for
+  # exe/super_auth-editor. The gem itself depends on none of them.
+  gem "rack"
+  gem "rackup"
+  gem "webrick"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    super_auth (0.4.0)
+    super_auth (0.7.0)
       sequel
 
 GEM
@@ -54,6 +54,9 @@ GEM
       coderay (~> 1.1)
       method_source (~> 1.0)
       reline (>= 0.6.0)
+    rack (3.2.7)
+    rackup (2.3.1)
+      rack (>= 3)
     rake (13.3.1)
     reline (0.6.3)
       io-console (~> 0.5)
@@ -82,6 +85,7 @@ GEM
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     uri (1.1.1)
+    webrick (1.9.2)
     zeitwerk (2.7.5)
 
 PLATFORMS
@@ -96,12 +100,15 @@ DEPENDENCIES
   mysql2
   pg
   pry
+  rack
+  rackup
   rake (~> 13.0)
   rspec (~> 3.0)
   sequel
   sequel-activerecord_connection
   sqlite3
   super_auth!
+  webrick
   zeitwerk (~> 2.6)
 
 BUNDLED WITH

data/README.md

@@ -25,34 +25,58 @@ suite against each of the three. Row-level security is Postgres only.
 How `super_auth` stacks up against other authentication strategies:
 [Do you really understand Authorization](https://dev.to/jonathanfrias/do-you-really-understand-authorization-1o5d)
 
-## Graph Visualization
+## Graph editor
 
-SuperAuth includes an interactive graph visualization tool to help you understand and debug your authorization rules!
+A Rails-free editor for the authorization graph: five boxes (groups, roles, users,
+permissions, resources); click any record to trace what it can reach and what reaches
+it; connect two records to draw an edge; delete records and edges; recompile. It ships
+in the gem as a Rack app and a command.
 
-![SuperAuth Visualization](https://img.shields.io/badge/Visualization-Interactive-brightgreen)
-
-See the complete authorization graph with:
-- Color-coded nodes (Users, Groups, Roles, Permissions, Resources)
-- Interactive path finding
-- Real-time authorization queries
-- Example scenarios from the README
+```bash
+gem install super_auth rackup webrick        # any Rack server works; puma too
+SUPER_AUTH_DATABASE_URL=postgres://user:password@localhost/app_development super_auth-editor
+```
 
-**Quick Start:**
+Then open http://127.0.0.1:4666. Options: `--host` (default `127.0.0.1`), `--port`
+(default `4666`), `--migrate` (run the gem's Sequel migrations first, for a database that
+has none), `--seed` (replace the whole graph with a sample company, destructive).
 
-```bash
-# 1. Generate initializer
-rails generate super_auth:install
+> ⚠️ **The editor has no authentication.** Anyone who can reach it can rewrite the graph.
+> The command binds to loopback and rejects requests whose `Host` header is not
+> localhost. When you mount the app in your own server, put your own authentication in
+> front of it, as below.
 
-# 2. Mount the engine in config/routes.rb
-mount SuperAuth::Engine => '/super_auth'
+In Rails the engine serves it. Mount the engine inside your own authentication:
 
-# 3. Load sample data (optional)
-rails runner "load File.join(SuperAuth::Engine.root, 'db/seeds/sample_data.rb')"
+```ruby
+# config/routes.rb
+authenticate :admin do                          # Devise; or a constraints block
+  mount SuperAuth::Engine => "/super_auth"
+end
 ```
 
-Then visit: `http://localhost:3000/super_auth/visualization`
+Or mount the app itself anywhere: `require "super_auth/editor"` and
+`mount SuperAuth::Editor => "/wherever"`, again inside your authentication.
+
+Mount it in any Rack app:
+
+```ruby
+# config.ru
+SuperAuth.db = Sequel.connect(ENV.fetch("SUPER_AUTH_DATABASE_URL"))
+SuperAuth.load
+map "/super_auth/editor" do
+  use Rack::Auth::Basic { |user, password| user == "admin" && password == ENV.fetch("EDITOR_PASSWORD") }
+  run SuperAuth::Editor
+end
+```
 
-See [VISUALIZATION.md](VISUALIZATION.md) for complete documentation.
+Edits change the graph, not runtime access: `ByCurrentUser` and the row-level security
+policies read the compiled `super_auth_authorizations` table. The strip at the top shows
+that table's row count, and **Recompile** runs `SuperAuth::Authorization.compile!`
+(`POST /api/compile`). The API is small and JSON: `GET /api/graph`,
+`POST /api/nodes/:type`, `DELETE /api/nodes/:type/:id`, `POST /api/edges`,
+`DELETE /api/edges/:id`, `POST /api/compile`. Writes must be `application/json`, and
+the editor only creates edges of the eight kinds the path strategies read.
 
 ## Postgres Row-Level Security (optional)
 
@@ -77,8 +101,24 @@ SELECT super_auth_become(user_external_id => '42', user_external_type => 'AppUse
 COMMIT;  -- identity dies with the transaction; there is nothing to clear
 ```
 
-For a user managed inside super_auth, pass `user_id => '7'` instead; `system => true`
-bypasses the policies (migrations, seeds, admin jobs).
+For a user managed inside super_auth, pass `user_id => '7'` instead.
+
+System context, which bypasses the policies (migrations, seeds, admin jobs), is a
+separate function, so the right to bypass is granted per role rather than coming with
+the right to assert an identity:
+
+```sql
+BEGIN;
+SELECT super_auth_system();
+-- every protected row is visible and writable --
+COMMIT;
+```
+
+`enable` revokes `EXECUTE` on `super_auth_system()` from `PUBLIC`; a role without an
+explicit grant (`SuperAuth::RLS.grant_system(role)`) gets `permission denied`. Both
+functions raise if the calling role is a superuser or has `BYPASSRLS`: Postgres exempts
+those roles from every policy, so the assertion would protect nothing while looking
+like it does.
 
 The assertion is anchored to the calling transaction: `super_auth_become` sets
 transaction-local identity settings plus a stamp of the current transaction id, and
@@ -121,16 +161,28 @@ class name when you use the AR integration).
 
 **3. Connect as a role RLS applies to.** Superusers and `BYPASSRLS` roles skip
 policies entirely, so the app must not connect as one (owning the tables is fine —
-the policies use `FORCE ROW LEVEL SECURITY`). The role needs `SELECT` on
-`super_auth_authorizations`, which the policies read; `EXECUTE` on
-`super_auth_become` is granted to `PUBLIC` by default, so no extra grant is needed:
+the policies use `FORCE ROW LEVEL SECURITY`); both identity functions refuse such a
+role outright. `enable` grants every role what it needs on the gem's own tables
+(`SELECT` on `super_auth_authorizations` and `super_auth_users`; `super_auth_become`
+is executable by `PUBLIC`), so a runtime role needs privileges on your tables and
+nothing else:
 
 ```sql
 CREATE ROLE app_runtime LOGIN PASSWORD '...';
 GRANT SELECT, INSERT, UPDATE, DELETE ON documents, invoices TO app_runtime;
-GRANT SELECT ON super_auth_authorizations TO app_runtime;
 ```
 
+The right to bypass the policies is separate. Grant it, from a migration or a
+console, only to the roles that run migrations, seeds and admin jobs:
+
+```ruby
+SuperAuth::RLS.grant_system(:app_admin)  # GRANT EXECUTE ON FUNCTION super_auth_system() TO app_admin
+```
+
+To keep the gem's tables readable only by specific roles instead, `REVOKE SELECT ON
+super_auth_authorizations, super_auth_users FROM PUBLIC` and grant per role; the
+policies run as the querying role, so it must keep that `SELECT`.
+
 > ⚠️ **This is the one step that, if skipped, silently disables all protection.**
 > PostgreSQL *always* lets **superusers** and roles with the **`BYPASSRLS`** attribute
 > bypass row-level security. `FORCE ROW LEVEL SECURITY` only subjects the table *owner*
@@ -138,8 +190,9 @@ GRANT SELECT ON super_auth_authorizations TO app_runtime;
 > Postgres as a superuser (the default in many local setups and some managed hosts), the
 > policies apply to nobody and every row stays visible, while everything *looks* like it
 > is working. Always connect as a dedicated non-superuser, non-`BYPASSRLS` role such as
-> `app_runtime` above. SuperAuth's language-specific clients check this on startup and
-> warn you when the connection is able to bypass RLS.
+> `app_runtime` above. `super_auth_become()` and `super_auth_system()` refuse to run for
+> such a role, so a misconfigured connection fails on its first identity assertion
+> instead of silently seeing everything.
 
 **4. Wrap work in an identity assertion.** In Ruby:
 
@@ -149,11 +202,24 @@ SuperAuth.as(current_user) do
 end
 ```
 
-`SuperAuth.as` opens a transaction and calls `super_auth_become` for you — use it in
-an `around_action` (or around a job) to cover a whole request. Non-Ruby apps use the
-SQL contract directly. Each policy checks `super_auth_authorizations` with the same
+`SuperAuth.as` sets `SuperAuth.current_user` for the block as well, so the
+`ByCurrentUser` scope and the policies agree, and restores both on the way out, nested
+calls included. It opens a transaction and calls `super_auth_become` for you, or joins
+the transaction you are already in — use it in an `around_action` (or around a job) to
+cover a whole request. `auto_savepoint: true` makes every nested transaction a
+savepoint (ActiveRecord's `joinable: false`), so each save inside commits on its own
+and its `after_commit` hooks fire then; other keyword options pass through to Sequel's
+`transaction`. Whether a write survives the block raising is up to you: rescue inside
+the block to keep it. Where there is no block to wrap, a transaction you already
+manage or a change of user mid-request, `SuperAuth::RLS.assert(user)` asserts the
+identity in the current transaction and nothing else, and `SuperAuth::RLS.installed?`
+reports whether `enable` has run, so no application needs to know the SQL functions'
+signatures. Non-Ruby apps use the SQL contract directly. Each policy checks `super_auth_authorizations` with the same
 semantics as `ByCurrentUser`: type-level authorizations (`resource_external_id IS NULL`)
-act as a wildcard, per-record authorizations match on id, `system?` users bypass.
+act as a wildcard, per-record authorizations match on id. Any object with an `id`
+works as the user, including SuperAuth's own user records. For a user whose `system?`
+is true, `SuperAuth.as` calls `super_auth_system()` instead, so the connection's role
+must have been given the bypass with `SuperAuth::RLS.grant_system`.
 
 ### Notes
 

data/USAGE.md

@@ -95,14 +95,18 @@ Post.all                        # only posts the current user can access
 Post.where(published: true)     # scoped AND filtered by authorization
 ```
 
-**Step 6 (optional).** Mount the visualization engine:
+**Step 6 (optional).** Mount the engine, which serves the graph editor. It has no
+authentication of its own, so mount it inside yours:
 
 ```ruby
 # config/routes.rb
-mount SuperAuth::Engine => '/super_auth'
+authenticate :admin do                 # Devise; or a constraints block
+  mount SuperAuth::Engine => '/super_auth'
+end
 ```
 
-Then visit `http://localhost:3000/super_auth/visualization` to see your authorization graph.
+Then open `http://localhost:3000/super_auth` to edit the graph. Edits take effect at
+runtime after **Recompile** (or `SuperAuth::ActiveRecord::Authorization.compile!`).
 
 ### Standalone Setup (without Rails)
 
@@ -533,25 +537,23 @@ deployers.map { |a| a[:user_name] }.uniq
 
 ## Visualization
 
-SuperAuth includes an interactive graph visualization UI. After mounting the engine:
+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.
 
-```ruby
-# config/routes.rb
-mount SuperAuth::Engine => '/super_auth'
-```
+- Rails: mount the engine inside your own authentication (Step 6 above) and open
+  `http://localhost:3000/super_auth`.
+- Anywhere else: `super_auth-editor` serves it on loopback against
+  `SUPER_AUTH_DATABASE_URL`, or `require "super_auth/editor"` and mount
+  `SuperAuth::Editor` in any Rack app, inside your authentication.
 
-Load sample data (optional):
+Load sample data (optional, Rails):
 
 ```bash
 rails runner "load File.join(SuperAuth::Engine.root, 'db/seeds/sample_data.rb')"
 ```
 
-Visit `http://localhost:3000/super_auth/visualization` to see:
-
-- Color-coded nodes for each entity type
-- Interactive path finding
-- Real-time authorization queries
-
 ## Full Example
 
 Here's a complete example modeling a company with departments, roles, and resources:

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_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/rls/templates/migration.rb.erb

@@ -3,6 +3,8 @@ class EnableSuperAuthRls < ActiveRecord::Migration[<%= ActiveRecord::Migration.c
 <% 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

data/lib/super_auth/active_record/by_current_user.rb

@@ -30,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 }

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