super_auth 0.3.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a2db33b2e48f7e542d54f3b5cef127f51c09fe19896b4ec6644a65ffa424c91
-  data.tar.gz: 87a7b993edea7bab1ca6c3298805f17e62ce0cd8b67de9114167cdb868316d7d
+  metadata.gz: ce52cd6a9867c21405fe203e87a765372b5b0febd49109286711c7e546c5118a
+  data.tar.gz: 1b67868c607adfa20b6832eb08e7bbf5ecaabe468a92a7ca4a8e408a8f3f2316
 SHA512:
-  metadata.gz: 62f14629c43e5dae082d3884803dae6559a91c58118479fc1fc6e4496dec27036c35cf8011e859b16f0e5a30d9c977244d2c39d005936a015796ddd1845b87ee
-  data.tar.gz: ee2cfaa0d1d3d4b8e3ba56130bc47cdbcb491982fac339bcde956a555b267dc8b39c82da284427f4b7e0baeb6382a5532766135d96922ecd1170079a0333c2f5
+  metadata.gz: '0582f16e103f0a1a00e7ac77edc49a3ba35f59cd0d0c98f4a98f1529c6452ca2adad7f1543df9251e923a8c805a0bce04a95c3fe17d8be86b02063b7b578b1a4'
+  data.tar.gz: f28dedeb421ee5ea689914429e5dac616f8f3a5efa99272b2e4aea2c715c5c880670936483bcb4cfe8f7e5344cff9c72a917296d6cbdb2a2d92213067a09ac29

data/CHANGELOG.md

@@ -1,5 +1,83 @@
 ## [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
+
+- Fix: path strategy 1 (users <-> groups <-> roles <-> permissions <-> resources) granted every role held by any group to the members of every group that held a role. `SuperAuth::Edge.users_groups_roles_permissions_resources` built one set of all role-holding groups and one set of all group-held roles and cross-joined them with nothing correlating a group to its own role. The role lookup is now joined through the member's own group ancestry, so a role attached to one group never reaches members of an unrelated group. Affects `SuperAuth::Edge.authorizations` and anything compiled from it (`SuperAuth::ActiveRecord::Authorization.compile!`); recompile authorizations after upgrading.
+
+### Added
+
+- Postgres row-level security enforcement (`SuperAuth::RLS`, `rails g super_auth:rls Model ...`). Identity is anchored to the transaction by the `super_auth_become()` SQL function, exposed in Ruby as `SuperAuth.as(user) { ... }`, so non-Ruby clients get the same enforcement.
+- Permission-gated subclass loading: a `ByCurrentUser` subclass is its own resource type, so privileged methods can live on a subclass whose access must be granted explicitly. A grant on the base class does not flow down.
+- `SuperAuth.external_id_type` types the external id columns at install time instead of casting at query time.
+
+### Changed
+
+- Relicensed from MIT to GPL-2.0.
+- Path strategies 1, 2 and 3 join group ancestry and role subtrees on integer pairs from two new recursive CTEs (`Group.ancestor_pairs`, `Role.descendant_pairs`) instead of LIKE-matching ids inside the comma-separated path strings, which no planner can index. Output is unchanged. On a 10,000-user graph the full `authorizations` union went from 10.4 s to 2.5 s on Postgres 16; on MySQL 8 a 500-user graph went from 9.9 s to 0.08 s, and on SQLite strategy 1 alone went from over 400 s to 0.01 s.
+
+### Fixed
+
+- MySQL 8 support. `SuperAuth::Edge.authorizations` raised "Illegal mix of collations for operation 'UNION'" whenever the connection collation differed from the table collation, which it does under ActiveRecord's defaults, so `compile!` could never run on MySQL. The recursive tree CTEs typed their path columns from the anchor row, so any `group_path` or `role_path` over 11 characters, or name path over 255, failed with "Data too long". Migration 8 no longer adds edge indexes on MySQL, where InnoDB already indexes foreign keys and refuses to drop them, which had broken `uninstall_migrations`. CI now runs the suite against real MySQL instead of silently falling back to SQLite.
+
 ## [0.3.3] - 2026-04-29
 
 - Fix: detect PostgreSQL/SQLite/Mysql2 adapter subclasses (e.g. PostGIS, Makara) when bootstrapping the Sequel connection from ActiveRecord. Previously only the exact stock adapter classes were recognized, leaving `SuperAuth.db` unset for apps using a subclassed adapter.

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.3.3)
+    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

@@ -2,50 +2,241 @@
 
 [![Build Status](https://github.com/JonathanFrias/super_auth/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/JonathanFrias/super_auth/actions)
 
-Super auth is turn-key authorization gem that makes unauthorized access unrepresentable. **Stop writing tests for authorization with confidence**
+Super auth is a turn-key authorization engine that makes unauthorized access unrepresentable — enforced in your database, so the same rules protect every client, in any language, that touches your data. **Stop writing authorization tests; enforce access with confidence.**
 
-The intent is to use with ruby applications, as well as centralize authorization for multiple applications. If you look at the [OWASP top vulnerabilty](https://owasp.org/Top10/A01_2021-Broken_Access_Control/), broken
-access control is the NUMBER 1 most common security risk in modern applications today. super_auth provides a authentication strategy that allows you to completely de-risk your application, solving this issue once confidently.
+The intent is to centralize authorization for one application or many, in any language. If you look at the [OWASP top vulnerability](https://owasp.org/Top10/A01_2021-Broken_Access_Control/), broken
+access control is the NUMBER 1 most common security risk in modern applications today. super_auth provides an authorization model that lets you de-risk your application, solving this issue once, confidently.
 
 
 ## Installation
 
+SuperAuth enforces authorization in the database, so any language can participate. The reference client is the Ruby gem:
+
     gem "super_auth"
 
+## Supported databases
+
+PostgreSQL 13+, MySQL 8.0+, and SQLite 3.44+. The group and role trees are recursive
+CTEs and the path columns use `concat()`, which sets those floors. CI runs the full
+suite against each of the three. Row-level security is Postgres only.
 
 ## Docs
 
 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
+
+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.
+
+```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
+```
+
+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).
+
+> ⚠️ **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.
+
+In Rails the engine serves it. Mount the engine inside your own authentication:
 
-SuperAuth includes an interactive graph visualization tool to help you understand and debug your authorization rules!
+```ruby
+# config/routes.rb
+authenticate :admin do                          # Devise; or a constraints block
+  mount SuperAuth::Engine => "/super_auth"
+end
+```
 
-![SuperAuth Visualization](https://img.shields.io/badge/Visualization-Interactive-brightgreen)
+Or mount the app itself anywhere: `require "super_auth/editor"` and
+`mount SuperAuth::Editor => "/wherever"`, again inside your authentication.
 
-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
+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
+```
+
+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)
+
+The `ByCurrentUser` scope enforces authorization at the ORM layer. On Postgres you can
+additionally enforce the same rules inside the database itself, so raw SQL, `unscoped`,
+background jobs, and any other client on the same database are subject to them too —
+unauthorized rows become invisible at the connection level. Enforcement is pure SQL:
+participating apps don't load this gem, or Ruby, at all. The gem's role is
+administrative — define the graph, compile authorizations, enable the policies — which
+is what makes super_auth usable as a central authorization service for apps in any
+language.
+
+### The contract (any language)
+
+Identity is asserted per transaction by calling the `super_auth_become` function that
+`SuperAuth::RLS.enable` installs:
+
+```sql
+BEGIN;
+SELECT super_auth_become(user_external_id => '42', user_external_type => 'AppUser');
+-- run normal queries; rows the user isn't authorized for don't exist --
+COMMIT;  -- identity dies with the transaction; there is nothing to clear
+```
 
-**Quick Start:**
+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
+every policy requires a stamp from the current transaction. Outside a transaction the
+settings have already reverted, and identity smuggled in as session settings carries a
+dead transaction's stamp — either way queries return no rows and writes are rejected.
+Misuse fails closed, and the scheme works unchanged behind transaction-pooling proxies
+like pgbouncer, because a transaction is exactly what they keep on one server
+connection.
+
+### Setup (Rails)
+
+**1. Match column types to your primary keys — before your first migration.**
+The policies compare `super_auth_authorizations.resource_external_id` directly
+against your tables' pks with no casting, so the columns must share a type:
+
+```ruby
+# config/initializers/super_auth.rb
+SuperAuth.setup do |config|
+  config.external_id_type = :bigint   # Rails' default pk type; use :uuid, :string, ... to match yours
+end
+```
+
+If super_auth is already migrated with the wrong type, alter the four external id
+columns (`super_auth_users.external_id`, `super_auth_resources.external_id`,
+`super_auth_authorizations.user_external_id`, `super_auth_authorizations.resource_external_id`)
+in a migration of your own.
+
+**2. Enable RLS on the tables you want protected:**
 
 ```bash
-# 1. Generate initializer
-rails generate super_auth:install
+rails generate super_auth:rls Document Invoice
+rails db:migrate
+```
 
-# 2. Mount the engine in config/routes.rb
-mount SuperAuth::Engine => '/super_auth'
+This creates one migration calling `SuperAuth::RLS.enable(:documents, resource_type: "Document")`
+per model — you can also call that directly for tables outside Rails. `resource_type`
+must match the `resource_external_type` used in your authorization rows (the model's
+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`); 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;
+```
 
-# 3. Load sample data (optional)
-rails runner "load File.join(SuperAuth::Engine.root, 'db/seeds/sample_data.rb')"
+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
 ```
 
-Then visit: `http://localhost:3000/super_auth/visualization`
+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*
+> to the policies — it does **not** constrain a superuser. So if your app connects to
+> 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. `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.
 
-See [VISUALIZATION.md](VISUALIZATION.md) for complete documentation.
+**4. Wrap work in an identity assertion.** In Ruby:
+
+```ruby
+SuperAuth.as(current_user) do
+  # every query in here is enforced by the database
+end
+```
+
+`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. 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
+
+- Queries with no identity asserted see nothing, and writes are rejected — fail
+  closed, by design. A client that has never heard of super_auth cannot accidentally
+  reach protected rows.
+- Creating rows requires a type-level authorization for that resource type (or system
+  context): the policy is `FOR ALL` with no `WITH CHECK`, so Postgres reuses its
+  `USING` expression as the implicit `WITH CHECK` for INSERTs and UPDATEs.
+- The transaction stamp calls `pg_current_xact_id()`, which assigns a real transaction
+  id even to read-only transactions — one extra xid per protected transaction.
+  Negligible for almost everyone; revisit with a virtual-xid variant only if
+  transaction id churn ever matters at extreme read volume.
+- One `external_id_type` covers the whole install, so every protected table across
+  every participating app needs the same pk type.
+- Postgres 13+ only (`pg_current_xact_id`). On other databases `SuperAuth::RLS`
+  raises, and the ORM scope remains the enforcement layer.
 
 ## Configuration
 
@@ -55,12 +246,18 @@ SuperAuth.setup do |config|
   # Raise an error when a query runs without a current user set.
   # Default is :none (returns empty results silently).
   config.missing_user_behavior = :raise
+
+  # Column type for external id columns, applied when the migrations run. Set
+  # it to your application's primary key type (:bigint, :uuid, :string, ...) so
+  # authorization comparisons are natively typed. Default is :string.
+  config.external_id_type = :bigint
 end
 ```
 
 | Option | Values | Default | Description |
 |--------|--------|---------|-------------|
 | `missing_user_behavior` | `:none`, `:raise` | `:none` | Controls what happens when `SuperAuth.current_user` is blank. `:none` returns an empty result set. `:raise` raises `SuperAuth::Error`. |
+| `external_id_type` | `:string`, `:bigint`, `:uuid`, ... | `:string` | Column type for the external id columns, applied when the migrations run. Set it to your application's primary key type so every comparison against your tables' pks is natively typed — no casting anywhere. |
 
 ## Usage
 
@@ -75,6 +272,9 @@ SuperAuth is a rules engine engine that works on 5 different authorization conce
 The basis for how this works is that the rules engine is trying to match a user with a resource to determine access.
 The engine determines if it can find an authorization route betewen a user and a resource. It does so by looking at users, groups, roles, permissions.
 
+                          +---+           +---+
+                          |   |           |   |      (Group nests within Group,
+                          |   v           |   v       Role nests within Role)
                          +-------+       +------+
                          | Group |<----->| Role |
                          +-------+\    / +------+
@@ -92,7 +292,9 @@ The engine determines if it can find an authorization route betewen a user and a
 
 
 The lines between the boxes are called [edges](https://en.wikipedia.org/wiki/Glossary_of_graph_theory#edge).
-Note that `Group` and `Role` trees.
+The self-loops on `Group` and `Role` mean each nests within itself: a `Group` can contain
+child `Group`s and a `Role` can contain child `Role`s, recursively. Grants on a parent
+flow to every descendant — which is why `Group` and `Role` are described as *trees*.
 
 In general the super_auth has 5 different pathing strategies to search for access.
 
@@ -210,6 +412,68 @@ Since the path is stored with the record, it trivial to audit access permissions
 
 TODO: Write usage instructions here
 
+## Permission-Gated Models
+
+Every class is authorized by its own name — nothing is derived, and a grant on one class never flows to another. That makes a subclass the natural home for privileged methods: it shares the base class's table and rows, but loading it requires its own, explicitly approved grant. If you can't load the object, you can't call its methods.
+
+```ruby
+class Resource < ApplicationRecord
+  super_auth
+  # Loadable by users granted the "Resource" resource type.
+
+  class ResourceRestartPermission < Resource
+    # Loadable ONLY by users granted "Resource::ResourceRestartPermission".
+    def restart!
+      # dangerous restart operation
+    end
+  end
+end
+```
+
+Approve access to the subclass the same way as any other resource — register it by its class name and draw edges to it:
+
+```ruby
+restartable = SuperAuth::Resource.create(
+  name: "restartable servers",
+  external_type: "Resource::ResourceRestartPermission"
+)
+restart = SuperAuth::Permission.create(name: "restart")
+SuperAuth::Edge.create(user: sa_user, permission: restart)
+SuperAuth::Edge.create(permission: restart, resource: restartable)
+SuperAuth::ActiveRecord::Authorization.compile!
+
+Resource.find(id)                            # needs a "Resource" grant
+Resource::ResourceRestartPermission.find(id) # needs its own explicit approval
+```
+
+Grants are per class in both directions: a `"Resource"` grant does not unlock the subclass, and a `"Resource::ResourceRestartPermission"` grant does not unlock the base class.
+
+## Row-Level Security for permission-gated models
+
+For defense in depth on Postgres (13+), enable a policy on the table. It is keyed by a single resource type — the base class's name — and enforces *row visibility* using the same [contract described above](#postgres-row-level-security-optional):
+
+```ruby
+SuperAuth::RLS.enable(:resources, resource_type: "Resource")
+```
+
+`enable` turns on `ROW LEVEL SECURITY` (with `FORCE`, so the table owner is covered too) and installs a policy that derives visibility from `super_auth_authorizations`. Identity is asserted **per transaction, not per connection**: wrap the work in `SuperAuth.as`, which opens a transaction and calls `super_auth_become` for you (see the contract above). Every query inside is filtered, and the identity dies with the transaction:
+
+```ruby
+SuperAuth.as(current_user) do
+  SuperAuth.db[:resources].all   # only rows current_user holds a grant on
+end
+# outside the block there is no asserted identity, so the policy matches nothing
+```
+
+Works with `SuperAuth::User` records (matched by `user_id`) or your own user objects (matched by `user_external_id` / `user_external_type`); type-level wildcard grants (`resource_external_id IS NULL`) and the system user behave exactly as they do in the ActiveRecord scope. `SuperAuth::RLS.disable(:resources)` removes the policy.
+
+Because a policy sees only the table, not which Ruby class issued the query, row-level security enforces access to the **base** resource type: a `"Resource"` grant makes the row visible in the database, but the policy cannot distinguish the `"Resource::ResourceRestartPermission"` subclass. Per-class (capability) enforcement therefore stays with the ORM scope — the database is the row-visibility backstop, the client gates the capability.
+
+Notes:
+
+- With no `SuperAuth.as` assertion in effect, the policy matches nothing (deny by default) and writes are rejected — fail closed.
+- Postgres superusers and `BYPASSRLS` roles bypass row-level security entirely — run your application as a regular role (see the setup guide above).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -222,4 +486,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/Jonath
 
 ## License
 
-The gem is available as open source under the terms of the [GPL](https://www.gnu.org/licenses/quick-guide-gplv3.html).
+The gem is available as open source under the terms of the [GPL v2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html).

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)
 
@@ -436,6 +440,29 @@ SuperAuth.current_user = SuperAuth::User.system
 Post.all  # Returns all posts
 ```
 
+### Permission-gated subclasses
+
+Every class is authorized by its own name, so privileged methods belong on a subclass: it shares the base class's table and rows, but loading it requires its own explicitly approved grant — access never flows between base and subclass in either direction:
+
+```ruby
+class Post < ApplicationRecord
+  super_auth
+
+  class PostPublishPermission < Post
+    def publish!
+      update!(published: true)
+    end
+  end
+end
+
+Post.find(id)                        # needs a "Post" grant
+Post::PostPublishPermission.find(id) # needs a "Post::PostPublishPermission" grant
+```
+
+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`).
+
 ### Linking to your app's models
 
 Connect SuperAuth entities to your ActiveRecord models via `external_id` and `external_type`:
@@ -510,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:
@@ -616,4 +641,4 @@ auths = SuperAuth::Edge.authorizations.all
 
 ## License
 
-SuperAuth is available as open source under the [GPL License](https://www.gnu.org/licenses/quick-guide-gplv3.html).
+SuperAuth is available as open source under the [GPL v2 License](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html).