current_scope 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db5a9b846aa990e7a570fcecda8ed17155e1dda547d2378cae7f50c24222f600
-  data.tar.gz: 8c7a489b449e685e5690a764d154d7c9b9f2fcac014f6d11f2cef6456d1ecc26
+  metadata.gz: cb3cfaf17408e822d2ce269223bed45714e97dad48d68ad68826cb398c39434f
+  data.tar.gz: 20729feebd795748b0898e62d4934b1ca3ed490ee585fcf911ad37d5d500e2a5
 SHA512:
-  metadata.gz: 2240d706b073404c057a1f28fbb0548ff1a8e9b596164d4ecf6fe2d787c3beee789537e4b5742e0034965a23cc7385eecc9eb604ed99cb3a73121d959a39087d
-  data.tar.gz: 6e1d6254c026ccce754eeae54ae160f94880ee4e410589d2f4ee6511a01aebf0a94e797b6b2eb075358f8f6b1681b10778c41f44488a2694349aace5e7f24dc7
+  metadata.gz: 7b6ede764a4924731f2a92c118dd0a2c018de8a808ddbd8d9010eacd862e0e57e972dcf3fe56a4337b239e052039dc0e022a1ef0bd7113c1fa1835e5d4c55f7a
+  data.tar.gz: 9b8823b93863c93d01eecb46a2773ad7fa3dd7fe0b9908f9a5f50137492ffb7ad4a10cbddc8207aaab0f4ed4ba27f572d5624b8687da6069878abff6465838e3

data/README.md

@@ -3,6 +3,27 @@
 [![Gem Version](https://img.shields.io/gem/v/current_scope)](https://rubygems.org/gems/current_scope)
 [![CI](https://github.com/davidteren/current_scope/actions/workflows/ci.yml/badge.svg)](https://github.com/davidteren/current_scope/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](MIT-LICENSE)
+[![Website](https://img.shields.io/badge/website-davidteren.github.io%2Fcurrent__scope-4d7cfe)](https://davidteren.github.io/current_scope/)
+[![Status: not production-ready](https://img.shields.io/badge/status-not%20production--ready-e8590c)](https://github.com/davidteren/current_scope/issues)
+
+> ## ⚠️ Not production-ready
+>
+> There are some known issues which are currently being worked on. **This is not
+> production-ready**, but it is ready for experimentation and spiking, or
+> whatever people want to do with it — just not yet for production.
+>
+> This is an **authorization** library, so the bar is different: a bug here is a
+> user seeing or doing something they shouldn't. The open work is tracked in the
+> [issue tracker](https://github.com/davidteren/current_scope/issues), and
+> several items are security-relevant — permission keys that can be dropped
+> silently, advisory checks that don't consult the catalog, and gaps in the
+> separation-of-duties veto. Each is being worked through with a written plan and
+> an adversarial review pass.
+>
+> Kick the tyres, build a spike, tell us what breaks. Don't put it in front of
+> real users yet.
+
+**Website:** [davidteren.github.io/current_scope](https://davidteren.github.io/current_scope/) — overview, the resolver, and quickstart at a glance.
 
 **Authorization as data you edit in a UI, not rules you hardcode and redeploy —
 with one ambient context that makes `allowed_to?` work identically in
@@ -92,14 +113,91 @@ class SessionsController < ApplicationController
 end
 ```
 
+### Retrofitting an app that already has users
+
+> **Retrofitting a real app?** There's a full guide:
+> [Adopting CurrentScope in an existing app](docs/guides/adopting-in-an-existing-app.md)
+> — callback ordering vs. your authentication, the Devise recipe, the
+> `skip_before_action` fail-open trap, hybrid HTML+API grants, and a rollout
+> ladder. The short version is below.
+
+
+The gate is fail-closed, so the line you just added denies **everything** until
+grants exist. On a greenfield app that's invisible — you seed the Owner role and
+move on. On an app that already has controllers and traffic, it means your suite
+goes red and your users get 403s the moment you deploy, and the only way to
+discover what you should have granted is to break it and read the wreckage.
+
+Don't cut over blind. Run in report mode first:
+
+```ruby
+CurrentScope.configure do |config|
+  config.enforcement = :report   # :enforce (default) | :report
+end
+```
+
+The gate now logs what it *would* have denied and lets the request through,
+recording each one to the ledger. Exercise the app, or just run your suite —
+then read the gaps back out:
+
+```bash
+bin/rails current_scope:report
+```
+
+```
+Would-be denials — grant these to stop them (most-denied first):
+
+  Ada Lovelace — currently Member
+      412x  reports#index
+       38x  reports#export
+  Grace Hopper
+        7x  reports#approve
+
+Total: 457 would-be denials across 2 subject(s).
+```
+
+That *is* your grant-seeding work, in the shape of the role grid you need to
+build: every subject who'd have been refused, what they were missing, and how
+badly. Seed the roles it names, watch the list empty out, then flip to
+`:enforce`. Each step is one line back, and nobody gets a 403 while you learn.
+
+The rows are ordinary ledger events, so query them directly if you want
+something the task doesn't show:
+
+```ruby
+CurrentScope::Event.where(event: "access.would_deny").pluck(:subject, :details)
+# => [["gid://app/User/7", {"permission" => "reports#index", "reason" => "no_grant"}], ...]
+```
+
+**Report mode is an adoption ramp, not an off switch — don't run production on
+it.** It relaxes exactly one denial: *nobody has granted this yet*. Everything
+else still refuses:
+
+| Still enforced in `:report` | Why it can't be relaxed |
+|---|---|
+| Separation-of-duties veto | Lifting it lets an initiator really approve their own record — a fraud action executed, not a role gap surfaced. |
+| SoD actions the veto *couldn't* run on | If an SoD action is gated without a record, the veto has no initiator to measure and is skipped — so the refusal that comes back says "not granted", not "SoD approved". Report mode won't speak for a rule nobody asked, and still refuses. (`config.warn_on_nil_sod_record` surfaces the misconfiguration behind it.) |
+| The management console | It's where grants are made. An observation flag that opened it would be a privilege escalation. |
+| Impersonation read-only gate | Runs before the permission check and answers to its own rule. |
+
+The response carries `X-Current-Scope-Reason: would_deny` on anything report mode
+let through, so you can spot them in an integration test or a proxy log without
+reading the ledger.
+
 **Assumption #1: every controller descends from a `Guard`'d base.** An action on
 a controller that never includes `Guard` (an API base, a hand-rolled
-`ActionController::Base`) is silently ungated. To catch that in dev/test, include
-the optional `CurrentScope::GatingTripwire` on the base you want verified — it
-raises after any action that didn't run the gate, and carries its own
-`current_scope_skip_tripwire!` marker for genuinely-public actions (you can't use
-`skip_before_action :current_scope_check!` on a controller that never defined
-that callback — it raises at class load):
+`ActionController::Base`) is silently ungated — though no longer invisibly: the
+permission grid badges any controller **provably** ungated ("gate not run"),
+and `bin/rails current_scope:ungated` prints the same inventory as a command.
+To catch it at runtime, include the optional `CurrentScope::GatingTripwire` on
+the base you want verified — it fires after any action that didn't run the
+gate: **raising in dev/test, or logging once per `controller#action` under
+`config.gating_tripwire = :warn` (the default outside dev/test; once per
+process per site — a concurrent first hit can rarely emit a duplicate line)**, so a
+production host can inventory its ungated surface without 500ing. It carries
+its own `current_scope_skip_tripwire!` marker for genuinely-public actions (you
+can't use `skip_before_action :current_scope_check!` on a controller that never
+defined that callback — it raises at class load):
 
 ```ruby
 class ApiController < ActionController::Base
@@ -109,7 +207,10 @@ end
 ```
 
 It's an `after_action`, so it can't see an action that renders from a
-`before_action` (halted chain) — a strong aid, not total coverage.
+`before_action` (halted chain) — a strong aid, not total coverage. The grid
+badge and the `ungated` task mark only what the callback chain *proves*: a
+conditional skip (`only:`/`except:`) renders unmarked and is exactly what
+`:warn` exists to catch.
 
 Bootstrap the first admin (the management UI needs a full-access subject to
 enter, so the first grant can't happen in the UI). One command:
@@ -180,12 +281,74 @@ query that drifts:
 def index
   @projects = scope_for(Project).order(created_at: :desc).page(params[:page])
 end
+
+private
+
+# A collection-only controller declares BOTH hooks. current_scope_record = nil
+# is what tells the gate "this action has no record" (a scoped grant can then
+# open it); WITHOUT it the gate assumes nothing and current_scope_model is
+# inert — the grant never opens the gate. current_scope_model then names the
+# TYPE, so the grant opens the record-less gate only for Projects. (A
+# controller with member actions already has current_scope_record; it just
+# adds current_scope_model.)
+def current_scope_record = nil
+def current_scope_model = Project
 ```
 
 - **full-access or an org-wide grant** of the key → every record (`Project.all`).
 - **scoped grants** → only the specific records that role was granted on.
 - **no grant** (or no subject) → empty, fail-closed like the gate.
 
+The gate agrees. A collection action like `#index` has no record to name, so it
+asks a record-less question, bound to the type the controller declares
+(`current_scope_model`, above). For a **collection read**
+(`config.collection_read_actions`, `index` by default) the gate asks
+`scope_for` itself: the subject reaches the list exactly when it would show
+them records — scoped `full_access` grants included — and the two halves
+cannot disagree, because they are one query. Any other record-less key needs a
+scoped grant whose role ticks it explicitly; `scope_for` then narrows the list
+to the records they were actually granted. A grant on a `Report` never opens a
+`Projects` gate — the type is what binds them. **No org-wide grant is needed to
+reach a scoped index** (and reaching for one would defeat the purpose — an
+org-wide grant means "see everything", so `scope_for` would return
+`Project.all`). The same holds for the class form,
+`allowed_to?(:index, Project)`, which carries the type as its argument, so a
+view helper and the gate never disagree. A controller that does **not** declare
+`current_scope_model` fails the record-less gate closed for scoped grants (the
+denial carries `X-Current-Scope-Reason: model_undeclared`, and a dev nudge
+names the one-line fix). A declaration that returns something other than a
+concrete ActiveRecord class — `"Report"` for `Report`, say — also fails
+closed, labelled `model_invalid`, with a nudge naming the value the hook
+returned.
+
+> **The gate admits; `scope_for` narrows. Both halves are yours to wire.** The
+> gate only decides *whether* `#index` runs — it cannot filter a list you build
+> with `Project.all`. If a scoped role ticks a collection key and that action
+> doesn't call `scope_for`, the subject reaches the action and sees everything
+> it queries. Gate a collection action for scoped roles only alongside a
+> `scope_for` list.
+
+Off the read list the rule is uniform: a scoped role that ticks `create` or a
+bulk key opens *those* collection gates too, exactly as an org-wide grant of
+the same key already does. Tick a collection key on a scoped role only when
+you mean it — there is no record filter on `create`.
+
+A scoped **`full_access`** role follows the read/write split: it opens the
+listed reads of its record's type — the gate derives from which records the
+grant actually holds, so "Owner of Project #7" reaches the project index and
+sees Project #7 — and nothing else record-less. A full_access role satisfies
+*every* key, so honoring it in a record-less check that answers with a bare
+boolean would make one scoped grant a pass on every `#create` in the app; the
+read gates are safe precisely because their answer comes from the list. Two
+consequences worth knowing: a grant whose record is absent from the model's
+default scope — destroyed, soft-deleted, or scoped out by a tenant
+`default_scope` — opens nothing (an empty list is a 403, not an empty page),
+and the declared
+`current_scope_model` is **trusted like the record hook** — a wrong
+declaration opens that controller's listed reads to full_access holders of the
+declared type, so review the declaration the way you review
+`current_scope_record`.
+
 It returns a chainable `ActiveRecord::Relation`, so `.where`/`.order`/`.page`
 compose normally. `permission:` defaults to the model's `index` key and accepts
 a bare action or a full key (`scope_for(Report, permission: :approve)`).
@@ -264,9 +427,10 @@ to exempt a record type, or trim `config.sod_actions`.
 > on an SoD member action, the veto is *skipped* — an org-wide-granted subject
 > (including the initiator) passes. `nil` is legitimate for collection actions,
 > so the resolver can't tell the two apart and won't raise. Returning the record
-> on member actions is therefore the load-bearing control. As a dev/test aid,
-> set `config.warn_on_nil_sod_record = true` to log a nudge whenever an allowed
-> SoD action was gated with a nil record.
+> on member actions is therefore the load-bearing control. **In development and
+> test the gate logs a nudge** whenever an allowed SoD action was gated with no
+> record (`config.warn_on_nil_sod_record`, on by default there, off in
+> production) — see [Dev diagnostics](#dev-diagnostics).
 
 With `sod_actions` empty (the default), the veto step is a no-op and the
 resolver is simply `full_access → org-wide role → scoped role → deny`. No model
@@ -308,6 +472,17 @@ re-checked live at decision time:
 2. the record's host hook `current_scope_sod_bypassed?` returns true, **and**
 3. the record's **initiator** holds the bypass permission (`bypass_sod`).
 
+**Where the cell is.** Break-glass is the one permission that isn't an action
+you can route, so the role grid gets it injected rather than derived: with
+`allow_sod_bypass` on, every controller that routes an action listed in
+`sod_actions` grows a `bypass_sod` column, blank elsewhere. Tick it on the row
+for that resource and the role can break the glass — the supported way to build
+a "trusted admin may self-approve" role **without** `full_access`, which would
+grant it implicitly along with everything else and defeat the point of a scoped
+trusted approver. Turn `allow_sod_bypass` off and the column disappears and the
+key stops being grantable: grantability follows the catalog, and the catalog
+follows the flag.
+
 Holding `bypass_sod` on a flagged, self-initiated record **is** the
 authorization for the SoD action — the bypass grants the action, it doesn't
 merely lift the veto and then re-check for a separate `approve` grant.
@@ -354,19 +529,128 @@ and `sod_identity` — are grouped in their own block and covered under
 `sod_identity` is only observable once a mutation is allowed past the read-only
 gate.
 
+**`config.enforcement`** — `:enforce` (default) | `:report`. What the gate does
+with a denial. `:enforce` means a denial is a 403; it is the only production
+posture. `:report` logs a *missing grant* and lets the request through instead,
+recording it as `access.would_deny` — the adoption ramp for retrofitting an
+existing app, covered in [Retrofitting an app that already has
+users](#retrofitting-an-app-that-already-has-users). It relaxes nothing else: the
+SoD veto and the management console are untouched by it. An unknown value raises
+at boot rather than being silently treated as one of the two — believing you're
+enforcing when you aren't is the worst way to be wrong about this setting.
+
+**`config.collection_read_actions`** — `["index"]` by default. The record-less
+actions whose gate derives its answer from the scoped list, so a scoped
+`full_access` grant opens exactly the collections that would show its records
+(gate and list agree by construction — the #65 fix). Set `[]` to restore the
+pre-#65 behavior, where explicit ticks still open type-bound record-less gates
+but scoped `full_access` opens none (the whole record-less family is new in
+this release — no released version had either posture). A full key
+(`"reports#index"`) raises at assignment (the list is action-segment matched,
+app-wide), and a canonical mutating name (`create`/`update`/`destroy`) logs a
+loud warning.
+**List-narrowing reads only:** never name a mutating action here — that would
+hand a scoped full_access holder the action on every record of the type off a
+grant on one record. Custom read actions (`export`, `search`) are the intended
+additions. Members normalize to strings on assignment, so `%i[index]` works.
+
 The **audit ledger** is controlled by `config.audit` — tri-state
 `false | true | :strict`. `false` records nothing; `true` (the default) records
 every authorization change and degrades gracefully (skip + warn once) if the
 events table isn't migrated; `:strict` **raises** on a missing events table so
 an audit-mandatory app never commits an unaudited change (the mutation rolls
-back). `config.warn_on_nil_sod_record` (default off) is a dev/test aid — see the
-[Separation of duties](#separation-of-duties-opt-in) note.
+back).
+
+> **Note on the `!`:** despite the bang, `Event.record!` only guarantees
+> raise-on-failure under `:strict` (and for a missing actor). In the default
+> `true` mode a missing events table is a warn-once no-op, and under `false`
+> every call silently returns `nil` — so a mutation-wrapping transaction does
+> **not** roll back on a failed audit write unless you opt into `:strict`.
+
+### Dev diagnostics
+
+Three things this engine gets wrong **silently**, and silently in the bad
+direction: what went wrong looks exactly like what going right looks like. Each
+one now says so in the log.
+
+| Flag | Fires when | Why you'd never notice otherwise |
+|---|---|---|
+| `warn_on_nil_sod_record` | An SoD action was **allowed** while the gate had no record, so the veto was skipped | A veto that never ran looks identical to a veto that passed |
+| `warn_on_inert_scoped_grant` | Denied `no_grant`, the subject **holds a scoped grant** that would satisfy it, and the controller declares no `current_scope_record` | The 403 is byte-identical to "never granted", so you go audit the grants — which are fine — instead of the controller, which isn't |
+| `warn_on_cross_controller_derivation` | Short-form `allowed_to?(:show, record)` derived a **different key** than the gate on this controller enforces | If you meant this controller's gate, the view and the gate disagree — and the symptom (a link that 403s, or a hidden one that works) shows up nowhere near the cause |
+
+All three are **log-only** — no decision, exception, header, or audit row changes
+because of them, in any environment — and all three default **on in development
+and test, off in production**:
+
+```ruby
+config.warn_on_nil_sod_record = Rails.env.local?              # the defaults;
+config.warn_on_inert_scoped_grant = Rails.env.local?          # override either
+config.warn_on_cross_controller_derivation = Rails.env.local? # way
+```
+
+The last one is a **hint, not an accusation**, and says so: asking about a
+different resource than the current controller handles derives a different key
+too, and that is correct and common. Nothing at the call site distinguishes the
+two, so it warns **once per site** and names both readings. The first two are
+unambiguous.
+
+The default is the point. These catch mistakes you make while *writing* the app,
+which is exactly when dev/test is where you are — and a diagnostic that ships off
+is one the people who need it never find. `warn_on_nil_sod_record` has worked
+since v0.1 and defaulted off, which is how it helped nobody.
+
+A fourth setting is a **mode, not a flag** — the opt-in `GatingTripwire`
+already speaks; the question is how:
 
-Two loud-by-design behaviors: a controller excluded from the catalog can't be
+```ruby
+config.gating_tripwire = Rails.env.local? ? :raise : :warn   # the default
+```
+
+`:raise` (dev/test) makes CI go red on an ungated action; `:warn` (elsewhere)
+logs each ungated `controller#action` once, so a production host that included
+the mixin gets an inventory instead of 500s. There is no `:off` — not including
+the mixin is off.
+
+Three loud-by-design behaviors. A controller excluded from the catalog can't be
 granted, so gating it is a misconfiguration — Guard raises and tells you to
-either stop excluding it or `skip_before_action :current_scope_check!`. And a
+either stop excluding it or `skip_before_action :current_scope_check!`. A
 `user_method` that the controller doesn't respond to raises instead of
-silently turning every request into a 403.
+silently turning every request into a 403. And **granting a permission key that
+isn't in the catalog makes the role invalid**, naming the key:
+
+```ruby
+role.permission_keys = %w[reports#aprove]   # typo
+role.save   # => false
+role.errors[:permission_keys]
+# => ["not in the permission catalog: reports#aprove — check for typos, or use
+#     assign_permission_keys(..., scrub: true) to drop stale keys deliberately"]
+```
+
+A grant that vanishes is the worst kind of bug this library can have: the role
+looks right in the UI, the save succeeds, and the denial arrives later as an
+unexplained 403. So a key the app doesn't route is an error, not a shrug — that
+covers typos, programmatic grants of unrouted keys, and the never-routed
+break-glass permission (which stays ungrantable; see #21).
+
+There is one legitimate reason to drop a key silently: a controller was removed,
+so a role still holds keys that no longer route. That is named at the call site
+rather than assumed:
+
+```ruby
+role.assign_permission_keys(keys, scrub: true)   # stale keys dropped, no error
+role.save!
+role.permission_keys_change[:rejected]           # => ["gone#index"] — log it if you want
+```
+
+The diff is computed on save, so read it after. `scrub:` takes literal `true`
+and nothing else — a stray truthy value must not be able to turn the strict
+path off.
+
+`scrub:` is deliberately not reachable from `permission_keys=`, so form params
+and strong-params flows always take the strict path. The role editor is
+unaffected: its grid is built from routed actions, so everything it submits is
+already in the catalog, and a stale key is cleaned up transparently on save.
 
 ### Impersonation (act-as)
 
@@ -480,9 +764,24 @@ class ImpersonationsController < ApplicationController
 end
 ```
 
-Denials carry a machine-readable reason (`:sod_veto`, `:no_grant`,
-`:impersonation_gate`) on `AccessDenied#reason`, surfaced on the response as the
-`X-Current-Scope-Reason` header.
+Denials carry a machine-readable reason on `AccessDenied#reason`, surfaced on
+the response as the `X-Current-Scope-Reason` header:
+
+| Reason | Means |
+|---|---|
+| `sod_veto` | the record's initiator can't perform a separation-of-duties action on it |
+| `no_grant` | nothing granted the permission — the default deny |
+| `model_undeclared` | a record-less deny that a scoped grant would have opened, had the controller declared `current_scope_model` |
+| `model_invalid` | `current_scope_model` was declared but returned something other than a concrete ActiveRecord class |
+| `impersonation_gate` | a mutation while impersonating, which is read-only |
+| `not_full_access` | the management UI, which only full-access subjects enter |
+
+Every denial routes through one method, so a refusal can't reach a client
+without its reason. A **host** denial is a bodyless `403` — the reason header is
+the signal, and the gem won't render into your app's response contract. The
+engine's own management UI is the exception: it renders a short page saying a
+full-access role is required, because the person reading that one is an admin
+looking at a browser.
 
 **View/gate disagreement is by design.** `allowed_to?` is HTTP-ignorant: it
 still returns `true` for a permission the subject genuinely holds, even though

data/app/assets/javascripts/current_scope/application.js

@@ -79,6 +79,10 @@ document.addEventListener("DOMContentLoaded", function () {
   // hint and disable the preserve inputs so they don't force the old subset back.
   function releasePartial(box) {
     box.indeterminate = false;
+    // The attribute is what CSS keys on (dashed outline; the marked-row hatch)
+    // — leaving it set keeps partial styling on a cell the user just cleared,
+    // even though no keys will be submitted. (#79 review)
+    box.removeAttribute("data-cs-partial");
     var cell = box.closest("td");
     if (!cell) return;
     cell.querySelectorAll("[data-cs-preserve]").forEach(function (h) { h.disabled = true; });

data/app/assets/stylesheets/current_scope/application.css

@@ -132,6 +132,27 @@ a:hover { color: var(--cs-accent-strong); }
 
 :focus-visible { outline: 2px solid var(--cs-accent); outline-offset: 2px; border-radius: 3px; }
 
+/* Bypass block (WCAG 2.4.1): off-canvas until keyboard focus lands on it,
+ * then a small accent pill in the top-left, above the sticky sidebar. */
+.cs-skip-link {
+  position: absolute;
+  top: 0.5rem;
+  left: 0.5rem;
+  z-index: 10;
+  padding: 0.5rem 0.875rem;
+  background: var(--cs-accent);
+  color: var(--cs-on-accent);
+  border-radius: 6px;
+  font-weight: 600;
+  text-decoration: none;
+  transform: translateY(calc(-100% - 1rem));
+}
+.cs-skip-link:focus { transform: none; }
+
+/* The skip-link target: focusable for the jump, but never shows a ring of
+ * its own — the content it reveals is the feedback. */
+#cs-main-content:focus-visible { outline: none; }
+
 /* ---- Shell ------------------------------------------------------------ *
  * A left sidebar (wordmark + section nav) and a scrollable main column with
  * a sticky topbar. The dense grid lives inside main.
@@ -357,6 +378,17 @@ a:hover { color: var(--cs-accent-strong); }
   box-shadow: var(--cs-shadow);
 }
 .cs-card:not(.cs-card--flush) > * { padding-inline: 1.125rem; }
+
+/* The engine's front-door 403 — rendered standalone, without the console shell
+   (a sidebar of links this subject can't open would read as "you're in" and
+   then refuse every click). Only the centring is new; the surface, type and
+   theme tokens come from .cs-card and the base rules above. */
+.cs-denied {
+  max-width: 46rem;
+  margin: 12vh auto 0;
+  padding-block: 1.5rem;
+}
+.cs-denied p { margin: 0 0 0.75rem; max-width: 68ch; }
 /* Flush cards hold data tables. Let them scroll horizontally inside the card so
    a wide table never overflows the page. On a wide screen the table fills the
    card (base width:100%) and scoped-role chips wrap in their own cell — all
@@ -498,6 +530,73 @@ a:hover { color: var(--cs-accent-strong); }
 .cs-grid td:has(input[data-cs-partial="true"]) { background: var(--cs-accent-wash); }
 .cs-grid input[data-cs-partial="true"] { outline: 2px dashed var(--cs-accent); outline-offset: 1px; }
 
+/* UNGATED (provable): the gate never runs on this controller, so its granted
+   routed actions are inert. The badge is advisory — marking is not disabling
+   (KTD-8/R5): nothing grayed, nothing disabled. It sits under the controller
+   name in the sticky header, wrapping normally inside the nowrap column. */
+.cs-ungated-badge {
+  display: block;
+  max-width: 19rem;
+  margin-top: 0.25rem;
+  padding: 0.25rem 0.4375rem;
+  border: 1px solid var(--cs-danger-line);
+  border-radius: var(--cs-radius-sm);
+  background: var(--cs-danger-wash);
+  color: var(--cs-ink);
+  font-family: var(--cs-font);
+  font-size: 0.6875rem;
+  font-weight: 400;
+  line-height: 1.45;
+  white-space: normal;
+}
+.cs-ungated-badge strong {
+  color: var(--cs-danger);
+  font-weight: 650;
+  letter-spacing: 0.03em;
+  text-transform: uppercase;
+}
+.cs-ungated-badge code { font-family: var(--cs-mono); }
+
+/* A checked (or partial) cell in a marked row must not read as a live grant:
+   swap the cobalt wash for a muted hatch. CSS-only, keyed on the badge — the
+   cell markup is untouched. The break-glass cell (.cs-cell-bypass) is excluded
+   on purpose (KTD-9): that grant IS live on a marked row, so it keeps the real
+   granted wash from the rule above. */
+.cs-grid tbody tr:has(.cs-ungated-badge) td:not(.cs-cell-bypass):has(input:checked),
+.cs-grid tbody tr:has(.cs-ungated-badge) td:not(.cs-cell-bypass):has(input[data-cs-partial="true"]) {
+  background: repeating-linear-gradient(-45deg,
+      var(--cs-surface-2) 0 4px, var(--cs-bg) 4px 8px);
+}
+
+/* UNINSPECTABLE: the controller raised while loading, so the gate state is
+   unknown — a distinct third voice, deliberately not the danger badge (no
+   claim about gating is being made) and not silence (unmarked reads as
+   "checked, and gated" under the hint's rules). */
+.cs-uninspectable-note {
+  display: block;
+  max-width: 19rem;
+  margin-top: 0.25rem;
+  padding: 0.25rem 0.4375rem;
+  border: 1px dashed var(--cs-line-strong);
+  border-radius: var(--cs-radius-sm);
+  background: var(--cs-surface-2);
+  color: var(--cs-muted);
+  font-family: var(--cs-font);
+  font-size: 0.6875rem;
+  line-height: 1.45;
+  white-space: normal;
+}
+
+/* The per-cell exemption note on a marked row's break-glass cell. */
+.cs-bypass-exempt {
+  display: block;
+  margin-top: 0.125rem;
+  font-size: 0.625rem;
+  line-height: 1.3;
+  color: var(--cs-muted);
+  white-space: nowrap;
+}
+
 /* Checkboxes / radios use the accent. */
 input[type="checkbox"], input[type="radio"] {
   accent-color: var(--cs-accent);

data/app/controllers/current_scope/application_controller.rb

@@ -21,8 +21,46 @@ module CurrentScope
 
     private
 
+    # Raises rather than rendering, so the engine's front door lands in the same
+    # current_scope_denied path as every other denial and gets the reason header
+    # for free. It used to `head :forbidden` here — the one denial in the gem
+    # that sat outside that machinery, and so the one with no reason and no body
+    # (#23). MutationGuard's rescue_from catches this from a before_action.
+    #
+    # Who is denied is unchanged: the full_access? check is byte-for-byte what
+    # it was. Only how the refusal is surfaced changed.
     def require_full_access!
-      head :forbidden unless CurrentScope.resolver.full_access?(CurrentScope::Current.user)
+      return if CurrentScope.resolver.full_access?(CurrentScope::Current.user)
+
+      raise CurrentScope::AccessDenied.new(
+        "#{controller_path}##{action_name}", reason: :not_full_access
+      )
+    end
+
+    # The engine's UI is the one place a rendered denial belongs: the admin is
+    # looking at a browser, and "blank page" is not an answer to "why can't I get
+    # in?". Overrides ONLY the body — the reason header is still written by
+    # current_scope_denied, which stays the single place that knows about it.
+    #
+    # ONLY for :not_full_access. This concern rescues EVERY AccessDenied raised
+    # in this controller, and the other one that fires here is the impersonation
+    # gate — whose subject usually DOES have full access and is refused for an
+    # entirely different reason. Telling them they need a full-access role is a
+    # confidently wrong answer, which is worse than the blank page this fix
+    # replaces. Every other reason falls through to the bodyless default, i.e.
+    # exactly what it did before this change.
+    #
+    # HTML only: the page is a full HTML document, so a client that asked for
+    # anything else gets the bodyless 403 rather than markup under a content
+    # type it did not ask for.
+    #
+    # layout: false — the console layout is a sidebar of links to areas this
+    # subject cannot open. Offering them reads as "you're in" and then refuses
+    # every click.
+    def current_scope_render_denied(reason = nil)
+      return super unless reason == :not_full_access && request.format.html?
+
+      render "current_scope/shared/access_denied", status: :forbidden, layout: false
     end
 
     def subject_class

data/app/controllers/current_scope/role_assignments_controller.rb

@@ -69,14 +69,15 @@ module CurrentScope
     end
 
     # Returns true when a role was actually cleared, false when there was nothing
-    # to clear (so the caller's count stays accurate).
+    # to clear (so the caller's count stays accurate). Atomicity comes from
+    # create's outer bulk transaction — only called from inside it. (No inner
+    # transaction: without requires_new it would be a bare yield, and it isn't
+    # wanted — a failure anywhere rolls back the whole batch by design.)
     def clear_org_role(subject, assignment, prior_role)
       return false unless assignment.persisted? # nothing to clear ⇒ no event
 
-      RoleAssignment.transaction do
-        assignment.destroy!
-        Event.record!(event: "org_role.removed", target: subject, details: { role: prior_role.name })
-      end
+      assignment.destroy!
+      Event.record!(event: "org_role.removed", target: subject, details: { role: prior_role.name })
       true
     end
 
@@ -88,16 +89,15 @@ module CurrentScope
       new_role = Role.find(params.expect(:role_id))
       changed = prior_role.nil? || prior_role.id != new_role.id
 
-      RoleAssignment.transaction do
-        assignment.update!(role: new_role)
-        if prior_role.nil?
-          Event.record!(event: "org_role.assigned", target: subject, details: { role: new_role.name })
-        elsif prior_role.id != new_role.id
-          Event.record!(event: "org_role.changed", target: subject,
-                        details: { from: prior_role.name, to: new_role.name })
-        end
-        # same role re-set ⇒ no change ⇒ no event
+      # Atomicity comes from create's outer bulk transaction (see clear_org_role).
+      assignment.update!(role: new_role)
+      if prior_role.nil?
+        Event.record!(event: "org_role.assigned", target: subject, details: { role: new_role.name })
+      elsif prior_role.id != new_role.id
+        Event.record!(event: "org_role.changed", target: subject,
+                      details: { from: prior_role.name, to: new_role.name })
       end
+      # same role re-set ⇒ no change ⇒ no event
       changed
     end
   end