current_scope 0.5.0

data/app/views/current_scope/subjects/index.html.erb

@@ -0,0 +1,124 @@
+<h1>Subjects</h1>
+<p class="cs-lede">Everyone who can hold a role, with their one org-wide role and
+  any per-record scoped roles. Filter to find people; select several to grant a
+  scoped role in one go.</p>
+
+<div class="cs-toolbar">
+  <%= form_with url: subjects_path, method: :get, class: "cs-search", role: "search" do %>
+    <input type="search" name="q" value="<%= @query %>" class="cs-filter" data-cs-filter
+           placeholder="Search everyone by email or name…" aria-label="Search subjects">
+    <%= submit_tag "Search", name: nil, class: "cs-btn" %>
+    <% if @query.present? %><%= link_to "Clear", subjects_path, class: "cs-btn" %><% end %>
+  <% end %>
+  <span class="cs-spacer"></span>
+</div>
+<% if @query.present? %>
+  <p class="cs-hint">Showing matches for “<%= @query %>” across all subjects. Narrow the list below per page; selection applies to the current page.</p>
+<% else %>
+  <%# Always shown (not just on multi-page lists): the one input drives TWO
+      mechanisms — typing live-filters this page, Search queries every subject —
+      and nothing but this line says so. %>
+  <p class="cs-hint">Type to filter this page, or Search to find anyone by email or name across every subject.</p>
+<% end %>
+
+<div class="cs-bulk" data-cs-bulk hidden>
+  <strong><span data-cs-bulk-count>0</span> selected</strong>
+  <span class="cs-spacer"></span>
+  <%# Org-wide role for the selection. JS injects the checked subjects as
+      subject_gids[] on submit; blank role clears it for all. %>
+  <%# Setting REPLACES each subject's current org-wide role (blank clears it) —
+      as consequential as Remove, which confirms, so this does too. %>
+  <% bulk_prompt = "Change the org-wide role for the selected subjects? This replaces their current role." %>
+  <%= form_with url: role_assignments_path, method: :post, class: "cs-bulk-org",
+        data: { cs_bulk_org: true, cs_confirm: bulk_prompt, turbo_confirm: bulk_prompt } do %>
+    <%= select_tag :role_id, options_from_collection_for_select(@roles, :id, :name),
+          include_blank: "org role…", aria: { label: "Org-wide role for selected" } %>
+    <%= submit_tag "Set for selected", name: nil, class: "cs-btn" %>
+  <% end %>
+  <%= link_to "Grant scoped role…", "#", class: "cs-btn cs-btn-primary",
+        data: { cs_bulk_scoped: true, cs_bulk_url: new_scoped_role_assignment_path } %>
+  <button type="button" class="cs-btn" data-cs-bulk-clear>Clear</button>
+</div>
+
+<div class="cs-card cs-card--flush">
+<table class="cs-table" data-cs-filter-list>
+  <thead>
+    <tr>
+      <th class="cs-select-cell">
+        <input type="checkbox" data-cs-select-all aria-label="Select all subjects">
+      </th>
+      <th>Subject</th><th>Org-wide role</th><th>Scoped roles</th>
+    </tr>
+  </thead>
+  <tbody>
+    <% @subjects.each do |subject| %>
+      <%# Key by what the polymorphic association STORES (the base_class name),
+          not subject.class.name — an STI subject (AdminUser < User) is saved as
+          "User", and keying on the subclass name would show its roles as
+          "— none —" while the resolver happily enforces them. %>
+      <% key = [ subject.class.polymorphic_name, subject.id.to_s ] %>
+      <% label = current_scope_subject_label(subject) %>
+      <%# Filter against a precise text set — subject label, current org role, and
+          scoped roles/records — NOT the row's textContent: every row embeds a
+          <select> listing all role names, which would match every query. %>
+      <% org_role_name = @roles.find { |r| r.id == @assignments[key]&.role_id }&.name %>
+      <% filter_text = [ label, org_role_name,
+                         *(@scoped[key] || []).map { |sra|
+                           "#{sra.role.name} #{current_scope_holder_resource_label(sra)}"
+                         } ].compact.join(" ") %>
+      <tr data-cs-row data-cs-filter-text="<%= filter_text %>">
+        <td class="cs-select-cell">
+          <input type="checkbox" data-cs-select value="<%= subject.to_gid %>"
+                 aria-label="Select <%= label %>">
+        </td>
+        <td><%= label %></td>
+        <td>
+          <% set_prompt = "Change the org-wide role for #{label}? This replaces their current role." %>
+          <%= form_with url: role_assignments_path, method: :post,
+                data: { cs_confirm: set_prompt, turbo_confirm: set_prompt } do %>
+            <%= hidden_field_tag :subject_gid, subject.to_gid %>
+            <%= select_tag :role_id,
+                  options_from_collection_for_select(@roles, :id, :name, @assignments[key]&.role_id),
+                  include_blank: "— none —",
+                  aria: { label: "Org-wide role for #{label}" } %>
+            <%= submit_tag "Set", name: nil,
+                  aria: { label: "Set org-wide role for #{label}" } %>
+          <% end %>
+        </td>
+        <td>
+          <% (@scoped[key] || []).each do |sra| %>
+            <% resource_label = current_scope_holder_resource_label(sra) %>
+            <% orphaned = sra.orphaned_resource? %>
+            <span class="cs-chip cs-scoped-chip<%= ' cs-chip--inert' if orphaned %>" id="scoped_chip_<%= sra.id %>">
+              <span class="cs-chip-label">
+                <%= sra.role.name %> of <%= resource_label %>
+                <% if orphaned %><span class="cs-inert-badge">inert</span><% end %>
+              </span>
+              <% revoke_prompt = orphaned ?
+                    "Remove inert scoped grant (#{resource_label})?" :
+                    "Revoke #{sra.role.name} on #{resource_label}?" %>
+              <%= button_to "×", scoped_role_assignment_path(sra), method: :delete,
+                    class: "cs-chip-remove",
+                    id: "scoped_chip_revoke_#{sra.id}",
+                    title: (orphaned ? "Remove inert scoped grant" : "Revoke this scoped role"),
+                    form: { data: { cs_confirm: revoke_prompt } },
+                    aria: { label: (orphaned ? "Remove inert #{sra.role.name} grant on #{resource_label}" : "Revoke #{sra.role.name} on #{resource_label}") },
+                    data: { turbo_confirm: revoke_prompt } %>
+            </span>
+          <% end %>
+          <%= link_to "+ scoped role", new_scoped_role_assignment_path(subject_gid: subject.to_gid),
+                class: "cs-add-scoped" %>
+        </td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+</div>
+
+<p class="cs-filter-empty" data-cs-filter-empty hidden>No subjects on this page match your filter.</p>
+
+<nav class="cs-pagination" aria-label="Subjects pagination">
+  <% if @page > 1 %><%= link_to "← Previous", subjects_path(page: @page - 1, q: @query.presence) %><% end %>
+  <span>Page <%= @page %></span>
+  <% if @has_next_page %><%= link_to "Next →", subjects_path(page: @page + 1, q: @query.presence) %><% end %>
+</nav>

data/app/views/layouts/current_scope/application.html.erb

@@ -0,0 +1,56 @@
+<% cs_theme = %w[light dark].include?(cookies[:current_scope_theme]) ? cookies[:current_scope_theme] : nil %>
+<% active = controller_name %>
+<!DOCTYPE html>
+<html lang="en"<%= " data-cs-theme=\"#{cs_theme}\"".html_safe if cs_theme %>>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>CurrentScope</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag "current_scope/application", media: "all" %>
+  <%= javascript_include_tag "current_scope/application", defer: true %>
+</head>
+<body>
+  <%# WCAG 2.4.1: every page repeats the sidebar + topbar before its content —
+      keyboard users get a bypass. Visually hidden until focused. %>
+  <a class="cs-skip-link" href="#cs-main-content">Skip to content</a>
+  <div class="cs-shell">
+    <aside class="cs-sidebar">
+      <div class="cs-brand"><span class="cs-brand-mark" aria-hidden="true"></span> CurrentScope</div>
+      <nav class="cs-nav" aria-label="Management">
+        <%= link_to "Roles", current_scope.roles_path,
+              "aria-current": ("page" if active == "roles") %>
+        <%= link_to "Subjects", current_scope.subjects_path,
+              "aria-current": ("page" if %w[subjects scoped_role_assignments].include?(active)) %>
+        <%= link_to "Events", current_scope.events_path,
+              "aria-current": ("page" if active == "events") %>
+      </nav>
+      <div class="cs-sidebar-foot">Authorization console</div>
+    </aside>
+
+    <div class="cs-main">
+      <div class="cs-topbar">
+        <span class="cs-topbar-title">Authorization</span>
+        <span class="cs-topbar-spacer"></span>
+        <span class="cs-badge">full access</span>
+        <button type="button" class="cs-theme-toggle" data-cs-theme-toggle
+                aria-label="Toggle dark mode" aria-pressed="<%= cs_theme == "dark" %>">
+          <span class="cs-icon-light" aria-hidden="true">☾</span>
+          <span class="cs-icon-dark" aria-hidden="true">☀</span>
+        </button>
+      </div>
+
+      <% if notice.present? %><p class="cs-flash cs-flash--notice" role="status"><%= notice %></p><% end %>
+      <% if alert.present? %><p class="cs-flash cs-flash--alert" role="alert"><%= alert %></p><% end %>
+
+      <main class="cs-content" id="cs-main-content" tabindex="-1">
+        <%= yield %>
+      </main>
+    </div>
+  </div>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,13 @@
+CurrentScope::Engine.routes.draw do
+  root to: "roles#index"
+
+  resources :roles, except: :show do
+    member { get :members }
+  end
+  resources :subjects, only: :index
+  resources :events, only: :index
+  # create is subject-keyed (no id); destroy removes one assignment by id (the
+  # members page's cleanup path for an orphan whose subject was deleted).
+  resources :role_assignments, only: [ :create, :destroy ]
+  resources :scoped_role_assignments, only: [ :new, :create, :destroy ]
+end

data/db/migrate/20260710000001_create_current_scope_tables.rb

@@ -0,0 +1,31 @@
+class CreateCurrentScopeTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :current_scope_roles do |t|
+      t.string :name, null: false, index: { unique: true }
+      t.boolean :full_access, null: false, default: false
+      t.timestamps
+    end
+
+    create_table :current_scope_role_permissions do |t|
+      t.references :role, null: false, foreign_key: { to_table: :current_scope_roles }
+      t.string :permission_key, null: false
+      t.index [ :role_id, :permission_key ], unique: true
+    end
+
+    create_table :current_scope_role_assignments do |t|
+      t.references :subject, polymorphic: true, null: false,
+                   index: { unique: true, name: "index_current_scope_one_role_per_subject" }
+      t.references :role, null: false, foreign_key: { to_table: :current_scope_roles }
+      t.timestamps
+    end
+
+    create_table :current_scope_scoped_role_assignments do |t|
+      t.references :subject, polymorphic: true, null: false
+      t.references :role, null: false, foreign_key: { to_table: :current_scope_roles }
+      t.references :resource, polymorphic: true, null: false
+      t.timestamps
+      t.index [ :subject_type, :subject_id, :resource_type, :resource_id, :role_id ],
+              unique: true, name: "index_current_scope_unique_scoped_assignment"
+    end
+  end
+end

data/db/migrate/20260710000002_create_current_scope_events.rb

@@ -0,0 +1,32 @@
+class CreateCurrentScopeEvents < ActiveRecord::Migration[7.1]
+  # Append-only authorization event ledger. This migration ships to arbitrary
+  # hosts and is NEVER renamed after release, so the schema shape is FROZEN.
+  #
+  # NORMATIVE target mapping (mirrored in the Event model header):
+  #   - assignment events (org_role.*, scoped_role.*): target = the GRANTEE
+  #     (the subject being granted). The role/resource ride in `details`.
+  #   - role.* events: target = the role itself.
+  def change
+    create_table :current_scope_events do |t|
+      t.string :event, null: false         # namespaced past-tense name (role.created, permission.granted, ...)
+      t.string :actor, null: false         # GlobalID of the REAL actor (never nil: record! raises first)
+      t.string :subject, null: false       # GlobalID of the effective subject; ALWAYS set (== actor unless impersonating)
+      t.string :target, null: false        # GlobalID of the thing acted on (see normative mapping above)
+      t.string :target_label, null: false  # denormalized human label so history survives target deletion
+      # json (NOT jsonb): an opaque, append-only payload the engine never
+      # queries, so it needs no index/operator support — and plain json is the
+      # portable type across SQLite / PostgreSQL / MySQL.
+      t.json :details
+      t.string :request_id                 # correlation-only, not evidence (client-suppliable via X-Request-Id)
+      # created_at only — declared explicitly, NOT via t.timestamps. There is
+      # deliberately no updated_at: its absence documents append-only intent.
+      t.datetime :created_at, null: false
+
+      # Append-only + host-side retention => unbounded growth, so unindexed
+      # scans are forever. Newest-first reads use order(id: :desc) (append-only
+      # => id order == commit order), so no created_at index is needed.
+      t.index :target
+      t.index :actor
+    end
+  end
+end

data/db/migrate/20260714000001_add_description_to_current_scope_roles.rb

@@ -0,0 +1,5 @@
+class AddDescriptionToCurrentScopeRoles < ActiveRecord::Migration[7.1]
+  def change
+    add_column :current_scope_roles, :description, :text
+  end
+end

data/db/migrate/20260805000001_widen_current_scope_polymorphic_ids.rb

@@ -0,0 +1,165 @@
+# #151. `subject_id` and `resource_id` were integer columns, so a host whose
+# models use UUID (or any non-numeric) primary keys had those ids cast by
+# String#to_i on write: "7f00aaaa-…" and "7f00bbbb-…" both stored as 7. Two
+# subjects became one identity and one inherited the other's roles.
+#
+# Widening to string supports BOTH shapes with no configuration to get wrong: an
+# integer key stores as "1", a UUID stores whole. Equality is the only comparison
+# these columns ever see (the resolver never orders or ranges on them), so string
+# storage costs nothing but index width.
+#
+# COLLATION IS FORCED BINARY ON MYSQL. Its default (utf8mb4_0900_ai_ci) is case
+# AND accent insensitive, so "ABC" and "abc" — or "jose" and "josé" — compare
+# equal. A grant to one would then match the other, which is #151 all over again
+# with a different mechanism. A record's primary key is an identifier, not prose;
+# it must compare byte for byte. PostgreSQL and SQLite already do.
+#
+# LENGTH IS BOUNDED AT 64 ON PURPOSE. These columns sit in a five-column unique
+# index, and MySQL caps an index at 3072 bytes; four unbounded varchar(255)
+# columns at utf8mb4 exceed that and the table will not create at all. 64 holds a
+# UUID (36), a ULID (26), and any integer key with room to spare.
+#
+# THIS MIGRATION CANNOT REPAIR ALREADY-COLLAPSED ROWS. Once "7f00aaaa-…" was
+# written as 7 the original value is gone. A host that ran 0.2 to 0.4 with
+# non-integer keys must re-grant those roles; UPGRADING.md carries the audit
+# query that lists them.
+# Bracketed [7.1] like every other migration this engine ships. The bracket pins
+# generation-time schema defaults, not the gem's minimum Rails, and the three
+# existing migrations all use it — a mechanical bump to match the Rails floor is
+# exactly what this repo's readiness plan says not to do.
+class WidenCurrentScopePolymorphicIds < ActiveRecord::Migration[7.1]
+  KEY_LIMIT = 64
+  # utf8mb4_bin is binary but PAD SPACE, so it still compares "abc" equal to
+  # "abc " — a trailing space would make two keys one identity, the same
+  # escalation the case-folding fix closed. utf8mb4_0900_bin is binary AND NO
+  # PAD (MySQL 8.0.17+). Prefer it; fall back where the server is older, since a
+  # case-sensitive comparison is still far better than the ai_ci default.
+  PREFERRED_COLLATION = "utf8mb4_0900_bin".freeze
+  FALLBACK_COLLATION = "utf8mb4_bin".freeze
+
+  COLUMNS = {
+    current_scope_role_assignments: [ :subject_id ],
+    current_scope_scoped_role_assignments: [ :subject_id, :resource_id ]
+  }.freeze
+
+  # The TYPE columns pair with the id in every grant predicate and in the unique
+  # index, so folding them is the same escalation by another column: on MySQL's
+  # default collation a grant on `Foo#5` would match a check for `FOO#5`. They are
+  # already varchar; only the collation changes, and only on MySQL.
+  TYPE_COLUMNS = {
+    current_scope_role_assignments: [ :subject_type ],
+    current_scope_scoped_role_assignments: [ :subject_type, :resource_type ]
+  }.freeze
+
+  def up
+    COLUMNS.each do |table, columns|
+      columns.each { |column| refuse_if_any_key_too_long(table, column) }
+    end
+    COLUMNS.each do |table, columns|
+      columns.each { |column| widen(table, column) }
+    end
+    return unless mysql?
+
+    TYPE_COLUMNS.each do |table, columns|
+      columns.each { |column| binary_collate(table, column) }
+    end
+  end
+
+  # Deliberately irreversible. Going back to integer would silently truncate
+  # every UUID it now holds — the exact data loss this migration exists to stop.
+  def down
+    raise ActiveRecord::IrreversibleMigration,
+          "Narrowing subject_id/resource_id back to integer would truncate any " \
+          "non-integer key stored since the upgrade (#151). Restore from a backup " \
+          "if you need the previous schema."
+  end
+
+  private
+
+  def mysql? = connection.adapter_name.match?(/mysql|trilogy|maria/i)
+
+  # Asked once per run, not per column: it is a catalog query.
+  def binary_collation
+    @binary_collation ||=
+      if connection.select_value(
+        "SELECT 1 FROM information_schema.collations " \
+        "WHERE collation_name = #{connection.quote(PREFERRED_COLLATION)}"
+      )
+        PREFERRED_COLLATION
+      else
+        FALLBACK_COLLATION
+      end
+  end
+
+  # Look BEFORE narrowing. Coming from the integer column this migration was
+  # written for, nothing can be too long — but a host arriving from a wider
+  # string column is a different story, and MySQL outside strict mode truncates
+  # silently rather than refusing. A truncated key names the wrong record, which
+  # is the whole of #151. Stop with the count and the column named, so the
+  # operator decides, rather than discovering it afterwards.
+  def refuse_if_any_key_too_long(table, column)
+    existing = connection.columns(table).find { |c| c.name == column.to_s }
+    return if existing.nil? || !existing.type.in?([ :string, :text ])
+
+    quoted = "#{connection.quote_table_name(table)}.#{connection.quote_column_name(column)}"
+    # CHAR_LENGTH on MySQL, where LENGTH counts BYTES and would refuse a
+    # perfectly short key that happens to be multi-byte. SQLite has no
+    # CHAR_LENGTH at all, and its LENGTH already counts characters; so does
+    # PostgreSQL's.
+    length_fn = mysql? ? "CHAR_LENGTH" : "LENGTH"
+    too_long = connection.select_value(
+      "SELECT COUNT(*) FROM #{connection.quote_table_name(table)} " \
+      "WHERE #{length_fn}(#{quoted}) > #{KEY_LIMIT}"
+    ).to_i
+    return if too_long.zero?
+
+    raise ActiveRecord::IrreversibleMigration,
+          "#{table}.#{column} holds #{too_long} value(s) longer than #{KEY_LIMIT} characters. " \
+          "Narrowing the column would truncate them, and a truncated key names the WRONG " \
+          "record (#151). Shorten or remove those grants first."
+  end
+
+  def already_correct?(table, column)
+    existing = connection.columns(table).find { |c| c.name == column.to_s }
+    return false if existing.nil?
+    return false unless existing.type == :string && existing.limit == KEY_LIMIT && !existing.null
+
+    !mysql? || existing.collation == binary_collation
+  end
+
+  # Collation only — the type columns are already the right type and width.
+  def binary_collate(table, column)
+    existing = connection.columns(table).find { |c| c.name == column.to_s }
+    return if existing.nil? || existing.collation == binary_collation
+
+    change_column table, column, :string, limit: existing.limit,
+                  null: false, collation: binary_collation
+  end
+
+  def widen(table, column)
+    # Idempotent, but NOT satisfied by type and width alone: a database built from
+    # schema.rb already has varchar(64) while carrying the server's default
+    # collation, which on MySQL is case-insensitive. Skipping there would leave the
+    # #151 collision live on every freshly-loaded schema.
+    return if already_correct?(table, column)
+
+    if connection.adapter_name.match?(/postg/i)
+      # Postgres will not cast integer to varchar implicitly in ALTER COLUMN; it
+      # needs USING. change_column does not emit one, so write it directly.
+      connection.execute(<<~SQL.squish)
+        ALTER TABLE #{connection.quote_table_name(table)}
+        ALTER COLUMN #{connection.quote_column_name(column)} TYPE character varying(#{KEY_LIMIT})
+        USING #{connection.quote_column_name(column)}::character varying
+      SQL
+    elsif mysql?
+      change_column table, column, :string, limit: KEY_LIMIT,
+                    null: false, collation: binary_collation
+      return
+    else
+      # SQLite rebuilds the table and compares BINARY by default.
+      change_column table, column, :string, limit: KEY_LIMIT
+    end
+
+    change_column_null table, column, false
+  end
+end