api_keys 0.5.1 → 0.7.0

data/app/controllers/api_keys/keys_controller.rb

@@ -3,9 +3,13 @@
 module ApiKeys
   # Controller for managing API keys belonging to the current owner.
   class KeysController < ApplicationController
+    ALREADY_SHOWN_ALERT = "This API key's token was already shown and cannot be shown again. " \
+                          "If you did not save it, revoke this key and create a new one."
+
     before_action :set_api_key, only: [:show, :edit, :update, :revoke]
+    helper ApiKeys::Helpers::ViewHelpers
     helper_method :key_types_feature_enabled?, :api_keys_allowed_restriction_kinds,
-                  :dashboard_scope_choices, :restriction_field_text
+                  :dashboard_scope_choices, :restriction_field_text, :api_keys_displayed_scopes
 
     # GET /keys
     def index
@@ -36,15 +40,24 @@ module ApiKeys
     # Shows the newly generated key's plaintext token ONCE.
     # This is not a standard show action, it's used transiently after creation.
     def show
-      # Key is set by set_api_key
-      # We need to retrieve the plaintext token stored temporarily
-      # after creation. This relies on how we handle creation.
-      # We'll likely store it in the session flash or pass it directly.
-      @plaintext_token = ApiKeys::TokenSession.retrieve_once(session, api_key: @api_key)
-      unless @plaintext_token
-        # If accessed directly without the token, redirect or show an error
-        redirect_to keys_path, alert: "API key token can only be shown once immediately after creation."
-      end
+      # Key is set by set_api_key. The plaintext token comes from the one-time
+      # session handoff written by create; it is released once, ever. This
+      # action opens no database transaction, so the durable claim commits
+      # before the token is rendered; keep it that way. A retrieval inside a
+      # transaction (for example a host around_action wrapping every request
+      # in one) is refused and the handoff kept, see ApiKeys::TokenSession.
+      retrieval = ApiKeys::TokenSession.retrieve_once_with_status(session, api_key: @api_key)
+      @plaintext_token = retrieval.token
+      return if @plaintext_token
+
+      # A replayed copy of the session, or a refresh after the token page,
+      # gets an explicit answer instead of the generic one.
+      alert = if retrieval.already_shown? || @api_key.token_shown?
+                ALREADY_SHOWN_ALERT
+              else
+                "API key token can only be shown once immediately after creation."
+              end
+      redirect_to keys_path, alert: alert
     end
 
     # GET /keys/new
@@ -59,12 +72,23 @@ module ApiKeys
       # re-checking every scope the owner had cleared.
       @submitted_scopes = submitted_params[:scopes]
 
+      # A `scopes: :ceiling` type is authorized by its live permissions, so
+      # the form offers no scopes for it and any submitted (cleared boxes, or
+      # a crafted request) are ignored. The key stores the type's current
+      # ceiling as its metadata.
+      type_config = requested_key_type_config(submitted_params[:key_type])
+      scopes = if ApiKeys::ApiKey.scopes_follow_ceiling_for?(type_config)
+                 type_config[:permissions].map(&:to_s)
+               else
+                 submitted_params[:scopes]
+               end
+
       # Use the HasApiKeys helper method to create the key
       begin
         # create_api_key! now returns the ApiKey instance
         @api_key = current_api_keys_owner.create_api_key!(
           name: submitted_params[:name],
-          scopes: submitted_params[:scopes],
+          scopes: scopes,
           expires_at: parse_expiration(submitted_params[:expires_at_preset]),
           key_type: submitted_params[:key_type].presence,
           # The model normalizes these raw strings; no parser needed here.
@@ -105,12 +129,20 @@ module ApiKeys
     # PATCH/PUT /keys/:id
     def update
       attributes = api_key_update_params
-      if attributes.key?(:scopes)
-        attributes[:scopes] = scopes_after_editing_offered_choices(attributes[:scopes])
-      elsif held_scopes_within_ceiling != Array(@api_key.scopes)
-        # No scope boxes were shown, but the key still holds a scope its type
-        # no longer allows; without dropping it no edit could ever be saved.
-        attributes[:scopes] = held_scopes_within_ceiling
+      if @api_key.scopes_follow_ceiling?
+        # The type's live ceiling authorizes this key and its stored scopes are
+        # metadata. The form offers no scope boxes for it, so any submitted
+        # scopes (the sentinel, or a crafted request) are ignored, and held
+        # scopes outside a narrowed ceiling are kept: the model lets such a key
+        # save as long as its scopes are not written.
+        attributes.delete(:scopes)
+      else
+        # The form speaks only for the scopes it offered (see
+        # ApiKey#scopes_after_form_edit). Without a scopes parameter (no boxes
+        # were shown) it still drops held scopes the current ceiling excludes,
+        # or no edit of such a key could ever be saved.
+        edited = @api_key.scopes_after_form_edit(offered: dashboard_scope_choices, checked: attributes[:scopes])
+        attributes[:scopes] = edited if attributes.key?(:scopes) || edited != Array(@api_key.scopes)
       end
       skip_untouched_restriction_fields!(attributes)
 
@@ -176,35 +208,6 @@ module ApiKeys
       Array(current_api_keys_owner.class.api_keys_settings.dig(:default_scopes))
     end
 
-    # The edit form can only speak for the scopes it showed. Checked choices
-    # are granted and unchecked ones removed; any other scope the key holds
-    # (for example one granted programmatically, or a type permission outside
-    # the owner's defaults) is kept, in its current order. A submitted value
-    # that was never offered is ignored.
-    #
-    # A held scope outside the key's current ceiling is dropped, whether
-    # offered or not: authentication already denies it, so no access changes,
-    # and keeping it would make every save of the key (a rename, or tightening
-    # a non-revocable key's origins) fail the ceiling validation. A newly
-    # checked scope outside the ceiling is kept, so validation reports it.
-    #
-    # @param submitted [Array<String>] Checked boxes, sentinel already stripped.
-    # @return [Array<String>]
-    def scopes_after_editing_offered_choices(submitted)
-      offered = dashboard_scope_choices
-      held = Array(@api_key.scopes)
-      kept = held_scopes_within_ceiling.select { |scope| !offered.include?(scope) || submitted.include?(scope) }
-      added = offered.select { |scope| submitted.include?(scope) && !held.include?(scope) }
-      kept + added
-    end
-
-    # The key's scopes without those its current ceiling excludes.
-    #
-    # @return [Array<String>]
-    def held_scopes_within_ceiling
-      Array(@api_key.scopes).select { |scope| @api_key.scope_within_ceiling?(scope) }
-    end
-
     # The text the form puts in a restriction field. Usable entries appear as
     # they are stored; anything else a stored policy holds (null, false, a
     # number, a blank string) is shown as JSON, so the owner can see it.
@@ -295,6 +298,30 @@ module ApiKeys
       end.uniq
     end
 
+    # The permissions a key actually has, for display. A `scopes: :ceiling` key
+    # is authorized by its type's live ceiling, so showing the list it stored
+    # at creation would misstate what it can do.
+    #
+    # @param api_key [ApiKeys::ApiKey]
+    # @return [Array<String>]
+    def api_keys_displayed_scopes(api_key)
+      return Array(api_key.key_type_config[:permissions]).map(&:to_s) if api_key.scopes_follow_ceiling?
+
+      api_key.scopes.is_a?(Array) ? api_key.scopes : []
+    end
+
+    # The configuration of the key type a create request resolves to, the way
+    # create_api_key! resolves it (the submitted type, else the default), or
+    # nil when there is none or it is unknown.
+    #
+    # @return [Hash, nil]
+    def requested_key_type_config(key_type_param)
+      type_name = key_type_param.presence || ApiKeys.configuration.default_key_type
+      return nil if type_name.blank?
+
+      (ApiKeys.configuration.key_types || {}).find { |name, _settings| name.to_s == type_name.to_s }&.last
+    end
+
     # Check if key types feature is enabled
     def key_types_feature_enabled?
       ApiKeys.configuration.key_types.present? && ApiKeys.configuration.key_types.any?

data/app/views/api_keys/keys/_form.html.erb

@@ -33,7 +33,11 @@
           <% if config[:permissions] != :all %>
             <small class="api-keys-form-help">
               <strong><%= type.to_s.humanize %>:</strong>
-              Limited to <%= config[:permissions]&.join(", ") || "no" %> permissions
+              <% if ApiKeys::ApiKey.scopes_follow_ceiling_for?(config) %>
+                Always has exactly the <%= config[:permissions].join(", ") %> permissions
+              <% else %>
+                Limited to <%= config[:permissions]&.join(", ") || "no" %> permissions
+              <% end %>
               <% unless config.fetch(:revocable, true) %>
                 <em>(cannot be revoked)</em>
               <% end %>
@@ -65,10 +69,13 @@
     </div>
 
     <%# The offered scopes are the owner's default scopes. The controller reads %>
-    <%# the same list (dashboard_scope_choices) when it saves the form. %>
+    <%# the same list (dashboard_scope_choices) when it saves the form. A key type %>
+    <%# with `scopes: :ceiling` has no scopes to choose: the script below hides and %>
+    <%# disables these boxes and shows that type's live permissions instead, and %>
+    <%# the controller ignores scopes submitted for it. %>
     <% @available_scopes = dashboard_scope_choices %>
     <% if @available_scopes.present? %>
-      <div>
+      <%= tag.div data: { api_keys_scope_choices: "" }, hidden: api_key.scopes_follow_ceiling? do %>
         <%= form.label :scopes, "Permissions" %>
         <%# Browsers omit unchecked boxes, so clearing every box would send no scopes %>
         <%# parameter at all and the key would silently get the defaults. This empty %>
@@ -91,7 +98,21 @@
             <%= form.label "scopes_#{scope.parameterize}", class: "form-check-label" do %><code><%= scope %></code><% end %>
           </div>
         <% end %>
-      </div>
+      <% end %>
+    <% end %>
+
+    <% ApiKeys.configuration.key_types.to_h.each do |type, config| %>
+      <% next unless ApiKeys::ApiKey.scopes_follow_ceiling_for?(config) %>
+      <%= tag.div class: "api-keys-ceiling-scopes", data: { api_keys_ceiling_contract: type.to_s },
+                  hidden: api_key.key_type.to_s != type.to_s do %>
+        <p><strong>Permissions</strong></p>
+        <% config[:permissions].each do |scope| %>
+          <kbd class="tag is-small"><%= scope %></kbd>
+        <% end %>
+        <small class="api-keys-form-help">
+          <%= type.to_s.humanize %> keys always have exactly these permissions, and follow the key type when it changes.
+        </small>
+      <% end %>
     <% end %>
 
     <%= render "api_keys/keys/restriction_fields", form: form, api_key: api_key %>
@@ -105,18 +126,31 @@
       <%= form.text_field :name %>
     </div>
 
-    <%# The edit form offers the owner's default scopes and edits only those: %>
-    <%# saving keeps every other scope the key holds, except scopes its type no %>
-    <%# longer allows (see the controller's scopes_after_editing_offered_choices). %>
+    <%# A `scopes: :ceiling` key is authorized by its type's live permissions and %>
+    <%# its stored scopes are metadata, so the form shows the live ceiling and %>
+    <%# offers nothing to edit; the controller ignores scopes submitted for it. %>
+    <%# Any other key gets the owner's default scopes as boxes, and a save edits %>
+    <%# only those: it keeps every other scope the key holds, except scopes its %>
+    <%# type no longer allows (ApiKey#scopes_after_form_edit). %>
     <% @available_scopes = dashboard_scope_choices %>
-    <% dropped_scopes = Array(api_key.scopes).reject { |scope| api_key.scope_within_ceiling?(scope) } %>
+    <% dropped_scopes = api_key.scopes_follow_ceiling? ? [] : Array(api_key.scopes).reject { |scope| api_key.scope_within_ceiling?(scope) } %>
     <% if dropped_scopes.any? %>
       <small class="api-keys-form-help">
         <%= safe_join(dropped_scopes.map { |scope| content_tag(:code, scope) }, ", ") %>
         <%= dropped_scopes.one? ? "is" : "are" %> no longer allowed for this key and will be removed when you save.
       </small>
     <% end %>
-    <% if @available_scopes.present? %>
+    <% if api_key.scopes_follow_ceiling? %>
+      <div class="api-keys-ceiling-scopes">
+        <p><strong>Permissions / Scopes</strong></p>
+        <% api_keys_displayed_scopes(api_key).each do |scope| %>
+          <kbd class="tag is-small"><%= scope %></kbd>
+        <% end %>
+        <small class="api-keys-form-help">
+          Permissions follow the <%= api_key.key_type.humanize.downcase %> key type and update automatically when it changes.
+        </small>
+      </div>
+    <% elsif @available_scopes.present? %>
       <div>
         <%= form.label :scopes, "Permissions / Scopes" %>
         <%# Empty sentinel: clearing every box must remove every offered scope, not keep the old ones. %>
@@ -165,7 +199,8 @@
   <% key_type_policies = ApiKeys.configuration.key_types.to_h do |type, config| %>
     <% [type.to_s, {
       restrictions: ApiKeys::ApiKey.restriction_kinds_for(config).map(&:to_s),
-      expirable: ApiKeys::ApiKey.revocable_for(config)
+      expirable: ApiKeys::ApiKey.revocable_for(config),
+      ceiling: ApiKeys::ApiKey.scopes_follow_ceiling_for?(config)
     }] %>
   <% end %>
   <script nonce="<%= content_security_policy_nonce %>">
@@ -189,6 +224,17 @@
           container.hidden = !enabled;
           container.querySelectorAll("input, select, textarea").forEach((input) => { input.disabled = !enabled; });
         });
+
+        // A scopes: :ceiling type has no scopes to choose: hide and disable the
+        // boxes (so none are submitted) and show that type's live permissions.
+        const ceiling = Boolean(policy && policy.ceiling);
+        form.querySelectorAll("[data-api-keys-scope-choices]").forEach((container) => {
+          container.hidden = ceiling;
+          container.querySelectorAll("input, select, textarea").forEach((input) => { input.disabled = ceiling; });
+        });
+        form.querySelectorAll("[data-api-keys-ceiling-contract]").forEach((container) => {
+          container.hidden = !(ceiling && container.dataset.apiKeysCeilingContract === keyType.value);
+        });
       };
 
       keyType.addEventListener("change", updatePolicyFields);

data/app/views/api_keys/keys/_key_row.html.erb

@@ -40,11 +40,13 @@
     <% else %>
       <em>Never used</em>
     <% end %>
+    <%= render partial: 'api_keys/keys/refusal_notice', locals: { key: key, compact: true } %>
   </td>
 
   <td class="api-keys-cell-scopes">
-    <% if key.scopes.present? %>
-      <% key.scopes.each do |scope| %>
+    <% displayed_scopes = api_keys_displayed_scopes(key) %>
+    <% if displayed_scopes.present? %>
+      <% displayed_scopes.each do |scope| %>
         <kbd class="api-keys-scope-tag tag is-small"><%= scope %></kbd>
       <% end %>
     <% else %>

data/app/views/api_keys/keys/_refusal_notice.html.erb

@@ -0,0 +1,24 @@
+<%# Refused-but-identified traffic for one key: requests that presented this key's %>
+<%# real token and were refused by a policy. Renders nothing until one is recorded, %>
+<%# and nothing on installations without the refusal stats columns. %>
+<%# Locals: key (required), compact (optional, for the key list) %>
+
+<% refused_at = key.last_refused_at %>
+<% if refused_at %>
+  <% reason = api_key_refusal_reason(key) %>
+  <% still_refused = key.last_used_at.nil? || refused_at > key.last_used_at %>
+  <% if local_assigns[:compact] %>
+    <small class="api-keys-refusal-text" title="<%= refused_at.utc.strftime('%Y-%m-%d %H:%M:%S UTC') %>">
+      Refused <%= time_ago_in_words(refused_at) %> ago: <%= reason %>
+    </small>
+  <% else %>
+    <p class="api-keys-refusal-notice" role="status">
+      <strong><%= still_refused ? "Requests are arriving but refused" : "Some requests were refused" %>:</strong>
+      last at <time datetime="<%= refused_at.utc.iso8601 %>"><%= refused_at.utc.strftime("%Y-%m-%d %H:%M:%S UTC") %></time>
+      (<%= time_ago_in_words(refused_at) %> ago), because <%= reason %>.
+      <% if ApiKeys.configuration.track_requests_count && key.refusals_count.positive? %>
+        <%= pluralize(key.refusals_count, "refusal") %> recorded so far.
+      <% end %>
+    </p>
+  <% end %>
+<% end %>

data/app/views/api_keys/keys/_show_token.html.erb

@@ -35,16 +35,13 @@
   </div>
 
 
-  <% if api_key.scopes.present? %>
+  <% displayed_scopes = api_keys_displayed_scopes(api_key) %>
+  <% if displayed_scopes.present? %>
     <div class="api-keys-token-scopes">
       <p><strong>Permissions</strong></p>
 
-      <% if api_key.scopes.present? %>
-        <% api_key.scopes.each do |scope| %>
-          <kbd class="tag is-small"><%= scope %></kbd>
-        <% end %>
-      <% else %>
-        &mdash;
+      <% displayed_scopes.each do |scope| %>
+        <kbd class="tag is-small"><%= scope %></kbd>
       <% end %>
     </div>
   <% end %>

data/app/views/api_keys/keys/edit.html.erb

@@ -1,5 +1,7 @@
 <div class="col-5">
   <h2>Edit API Key: <%= @api_key.name.presence || @api_key.masked_token %></h2>
 
+  <%= render 'refusal_notice', key: @api_key %>
+
   <%= render 'form', api_key: @api_key %> 
 </div>

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

@@ -198,6 +198,12 @@
     [hidden] { display: none !important; }
     .api-keys-form-errors { color: var(--api-keys-danger-color); }
     .api-keys-form-help { display: block; color: var(--color-darkGrey, #666); }
+    .api-keys-refusal-notice {
+      padding: 0.8em 1em;
+      border-left: 4px solid var(--api-keys-warning-color);
+      background-color: var(--bg-secondary-color, #f9f9f9);
+    }
+    .api-keys-refusal-text { display: block; color: var(--api-keys-danger-color); }
     .api-keys-empty-state { text-align: center; padding: 2em; }
     .api-keys-expired-text { color: var(--api-keys-status-expired-color); }
     .api-keys-token-panel { padding: 1em; margin: 1em 0; border-radius: 4px; }

data/docs/reviews/2026-10-18-0-6-0/01-astra-review-of-0-6-0.md

@@ -0,0 +1,36 @@
+# Security review of the 0.6.0 branch (Codex Astra, 2026-10-18, at 720e401, PR #66)
+
+Scope: `git diff origin/main..720e401` on the 0.5.1 main: ceiling-authoritative scopes (#28), refused-traffic stats (#38), the durable one-time handoff (`token_shown_at`), `ApiKey#scopes_after_form_edit`, migrations and docs, read-only, under the 0.5.0 threat model. Verdict: BLOCK on the durable handoff claim being undone by a host transaction that rolls back after the plaintext was released; four should-fixes (creation form still offers scope boxes for ceiling types; stats debouncing does not bound pending jobs; the retrieval result's inspect printed the token; reconciliation did not recheck revocation inside the lock) and two nits. All were applied in the next commits; see the disposition at the end.
+
+## Blocking
+
+- **The durable handoff can be rolled back after releasing the token.** The claim uses the caller’s database connection without ensuring its transaction has committed, and retrieval immediately returns the plaintext. Calling retrieval inside a transaction that subsequently rolls back restores `token_shown_at = NULL`. Verified in memory with `NullStore`: retrieval → rollback → copied-session replay returned the same token twice. A host controller wrapping display in a transaction can therefore violate the advertised guarantee. Fail closed inside an existing transaction, or ensure consumption commits independently before releasing plaintext. The unconditional durability claims must also be corrected. [api_key.rb:601](lib/api_keys/models/api_key.rb:601), [token_session.rb:167](lib/api_keys/helpers/token_session.rb:167), [README.md:514](README.md:514)
+
+## Should fix
+
+- **The creation form still offers ineffective scope checkboxes for ceiling types.** Only the persisted-key form suppresses them; the creation form always offers owner scopes, and its JavaScript handles restrictions and expiration only. An owner can clear every permission yet create a key authorized for the entire ceiling. Hide/disable those controls and display the live contract when selecting a ceiling type. Recommending `scopes: :ceiling` for publishable keys is appropriate under the initializer’s stated “users do not pick scopes” condition, but this form contradicts that condition. [_form.html.erb:73](app/views/api_keys/keys/_form.html.erb:73), [_form.html.erb:182](app/views/api_keys/keys/_form.html.erb:182), [initializer.rb:156](lib/generators/api_keys/templates/initializer.rb:156)
+
+- **Refusal debouncing does not bound pending jobs.** It checks only the persisted timestamp; enqueueing reserves nothing. With counting disabled and a one-minute interval, 100 requests carrying a revoked token queued 100 refusal jobs before worker execution. Prefix/last-four knowledge alone cannot stamp a key: verification checks the full token, and forged requests queued no stats jobs. Document the pending-job limitation and consider atomic enqueue deduplication; successful-use debouncing has the same limitation. [authentication.rb:172](lib/api_keys/authentication.rb:172), [authenticator.rb:260](lib/api_keys/services/authenticator.rb:260), [CHANGELOG.md:24](CHANGELOG.md:24)
+
+- **The new retrieval result exposes plaintext through inspection.** `Retrieval` inherits `Struct#inspect`/`to_s`, which includes its token on successful retrieval. Verified directly. Add credential-redacting inspection, consistent with the existing authentication result. The `already_shown` result itself correctly contains no token. [token_session.rb:83](lib/api_keys/helpers/token_session.rb:83), [authenticator.rb:46](lib/api_keys/services/authenticator.rb:46)
+
+- **Reconciliation does not recheck revocation after locking.** Selection filters `revoked_at: nil`, but a revocation between selection and `with_lock` is ignored after the row reloads. Verified that such a key still gains scopes and contributes to the changed count. Recheck eligibility inside the lock. This does not reactivate the key, but violates the documented exclusion of revoked keys. [api_key.rb:649](lib/api_keys/models/api_key.rb:649), [README.md:1312](README.md:1312)
+
+## Nits
+
+- The general statement that empty scopes grant nothing on typed keys needs an explicit ceiling-type exception. Ceiling keys intentionally receive their live permissions even with `scopes: []`. [README.md:889](README.md:889), [api_key.rb:388](lib/api_keys/models/api_key.rb:388)
+- The gem still identifies itself as `0.5.1`; bump it before publishing 0.6.0. The new runtime files are tracked and included by the gemspec. [version.rb:4](lib/api_keys/version.rb:4), [api_keys.gemspec:29](api_keys.gemspec:29)
+
+## Missing tests
+
+- **Committed, independent-connection handoff races and rollback replay.** The concurrent tests pin all threads to one SQLite connection and explicitly roll the transaction back afterward. They do not establish durability or independent-connection behavior across SQLite, PostgreSQL, and MySQL. Add those races with `NullStore`, followed by replay after commit/cache loss, plus the rollback regression above. [token_session_test.rb:40](test/helpers/token_session_test.rb:40)
+- **Refusal bursts before worker execution.** Current debounce coverage pre-populates `last_refused_at`; it misses pending-job amplification. Also exercise the forged-prefix/last-four refusal test with bcrypt, since the current test uses the default hashing configuration. [refusal_stats_test.rb:204](test/refusal_stats_test.rb:204), [refusal_stats_test.rb:176](test/refusal_stats_test.rb:176)
+
+VERDICT: BLOCK
+
+0.6.0 should not be published with its current unconditional durable-handoff guarantee: transaction rollback demonstrably permits a second release. Resolve that blocker and add the regression coverage before release. This review covered the full diff and used isolated in-memory checks without repository changes; the full suite was not run. Both requested GitHub issue fetches failed, and the two referenced `.cursor/rules` files were absent, so those sources could not be reviewed.
+## Disposition (lead)
+
+Applied in the six commits that followed (3a9b044 to 45afec4): the handoff claim is not trusted inside an open transaction (with a real cache the marker carries the guarantee; with none the token is withheld as `:inside_transaction`, nothing is recorded and the handoff stays for a retry outside the transaction; the dashboard opens no transaction; README, SECURITY.md and CHANGELOG corrected; the rollback replay tests and an 8-thread independent-connection race on a file-backed SQLite database); the creation form hides and disables scope boxes for a ceiling type and create ignores submitted scopes for it; success and refusal enqueues are deduplicated per key and kind with an atomic cache write when a real cache exists, documented otherwise; the retrieval result redacts the token in every representation; reconciliation rechecks revocation and type inside the lock; the README names the ceiling-type exception. Not available here: PostgreSQL and MySQL races (SQLite only). The version bump is the release step.
+
+Superseded in round 2: a retrieval inside an open transaction is now refused whatever the cache (a process-local cache could not stop another process after a rollback), and the README no longer says the dashboard always retrieves outside transactions, since its controller inherits the host's.

data/docs/reviews/2026-10-18-0-6-0/02-astra-re-review-of-0-6-0.md

@@ -0,0 +1,34 @@
+# Re-review of the 0.6.0 fixes, round 2 (Codex Astra, 2026-10-18, at fe28e9c, PR #66)
+
+Scope: `git diff 720e401..fe28e9c`, the six fixes answering review 01, read-only. Verdict: BLOCK on the handoff still releasing the plaintext inside a transaction whenever any non-NullStore cache was present (a process-local MemoryStore included), plus two should-fixes on the enqueue deduplication (a cache write answering nil treated as an existing reservation; a false `perform_later` not releasing the reservation) and docs nits. All applied in the five commits that followed (ab89492 to 497879e): retrieval inside any open Active Record transaction on the ApiKey pool is refused whatever the cache; suppression only on a confirmed reservation; release on a false enqueue; Solid Cache qualified in the stats section; the listed tests added. See 03.
+
+## Blocking
+
+- **Durable handoff: partially fixed, still open.** NullStore retrieval inside an Active Record transaction now withholds plaintext and preserves the handoff; the rollback tests genuinely exercise that scenario. But any non-NullStore cache enables release before commit—including process-local `MemoryStore`. After rollback, another process can release the token again without any cache flush. The new cache-loss test explicitly expects two releases. Documenting this limitation does not implement the requested fail-closed or independently committed consumption. Withhold inside transactions regardless of cache, or commit consumption independently. [token_session.rb:312](lib/api_keys/helpers/token_session.rb:312), [token_session.rb:395](lib/api_keys/helpers/token_session.rb:395), [token_session_test.rb:351](test/helpers/token_session_test.rb:351), [token_session_test.rb:420](test/helpers/token_session_test.rb:420)
+
+## Should fix
+
+- **Enqueue deduplication: partially closed, with a new failure mode.** Reservations address pending bursts when the cache supports atomic conditional writes. However, nil/false writes are treated as existing reservations, suppressing statistics even when nothing was reserved. Only exceptions trigger fallback. The failing-cache test raises `IOError`, so it misses this case; locally inspected RedisCacheStore returns nil for handled write failures. Check reservation presence before suppressing, and enqueue when reservation status is unavailable. [authentication.rb:234](lib/api_keys/authentication.rb:234), [refusal_stats_test.rb:289](test/refusal_stats_test.rb:289), [redis_cache_store.rb:397](rails source)
+
+- **Failed enqueues can retain reservations.** Both paths release only on exceptions, ignoring `perform_later` returning false. Active Job can return false after an enqueue error, suppressing subsequent attempts until expiration. The new tests cover raised exceptions only. [authentication.rb:160](lib/api_keys/authentication.rb:160), [authentication.rb:191](lib/api_keys/authentication.rb:191), [refusal_stats_test.rb:310](test/refusal_stats_test.rb:310), [enqueuing.rb:82](rails source)
+
+- **Creation form: closed in the inspected implementation.** JavaScript hides/disables scope controls and displays the selected ceiling. Server-side creation replaces submitted scopes with that ceiling, resolving omitted types through the configured default. Tests genuinely POST cleared, narrower, excessive, and ordinary-type scopes. No new authorization defect found; the rendering test does not execute selection changes. [keys_controller.rb:78](app/controllers/api_keys/keys_controller.rb:78), [keys_controller.rb:317](app/controllers/api_keys/keys_controller.rb:317), [_form.html.erb:230](app/views/api_keys/keys/_form.html.erb:230), [keys_controller_test.rb:774](test/controllers/keys_controller_test.rb:774)
+
+- **Retrieval inspection: closed.** Inspection, string conversion, pretty-printing, and JSON redact plaintext. The test obtains a successful retrieval and exercises those representations, including nested inspection. No new defect found in this change. [token_session.rb:111](lib/api_keys/helpers/token_session.rb:111), [token_session_test.rb:733](test/helpers/token_session_test.rb:733)
+
+- **Reconcile eligibility: closed.** Revocation and type are rechecked after the locked reload. The test performs a real database update after selection but before locking, leaving the selected object stale; it verifies unchanged scopes and exclusion from the count. This is a valid controlled interleaving, though not another connection. No new defect found. [api_key.rb:650](lib/api_keys/models/api_key.rb:650), [reconcile_scopes_test.rb:13](test/reconcile_scopes_test.rb:13), [reconcile_scopes_test.rb:48](test/reconcile_scopes_test.rb:48)
+
+## Nits
+
+- **Empty-scope wording: closed. Version bump: outstanding.** The ceiling exception is explicit; the gem still identifies as `0.5.1`. [README.md:890](README.md:890), [version.rb:4](lib/api_keys/version.rb:4)
+- **Documentation still overstates guarantees.** “The dashboard always” retrieves outside transactions is unsupported because its controller inherits the host controller. The stats section also promises atomic deduplication with Solid Cache while the handoff section describes its non-atomic absent-entry behavior. Qualify both, and update the filed disposition accordingly. [README.md:514](README.md:514), [application_controller.rb:10](app/controllers/api_keys/application_controller.rb:10), [README.md:1162](README.md:1162), [README.md:520](README.md:520), [review trace:34](docs/reviews/2026-10-18-0-6-0/01-astra-review-of-0-6-0.md:34)
+
+## Missing tests
+
+- **Handoff coverage improved materially, but remains SQLite-only.** The file-backed test uses autocommit pool connections, NullStore, and post-race replay against the committed marker. Its gate precedes checkout, so it does not guarantee distinct simultaneous connections; it also accepts any nil-producing loser. Add a barrier after checkout, assert loser statuses, and cover PostgreSQL/MySQL. [token_session_test.rb:71](test/helpers/token_session_test.rb:71), [token_session_test.rb:318](test/helpers/token_session_test.rb:318)
+- **Transaction-check boundaries remain untested.** It correctly checks the ApiKey pool, avoiding unrelated-pool false positives; lazy transactions and savepoints legitimately count. Its boundary is Active Record’s transaction manager: raw SQL `BEGIN` is not detected. Add separate-pool and nested-transaction coverage, and document that boundary. [token_session.rb:299](lib/api_keys/helpers/token_session.rb:299), [database_statements.rb:398](rails source)
+- **Original burst and bcrypt gaps: closed by meaningful scenarios.** Bursts enqueue before workers execute; bcrypt forgery preserves prefix/last-four while changing the secret. Still missing: non-raising cache/enqueue failures, browser type-switch execution, default-ceiling POST with omitted scopes/type, and reconciliation after retyping. [refusal_stats_test.rb:192](test/refusal_stats_test.rb:192), [refusal_stats_test.rb:239](test/refusal_stats_test.rb:239), [keys_controller_test.rb:774](test/controllers/keys_controller_test.rb:774), [reconcile_scopes_test.rb:48](test/reconcile_scopes_test.rb:48)
+
+VERDICT: BLOCK
+
+0.6.0 is not ready to publish: transactional token release remains replayable, and enqueue deduplication introduces silent statistics loss on non-raising failures. The form, redaction, reconciliation, and empty-scope fixes close their original findings. I read the entire delta through `fe28e9c` and checked every touched area; this was a static review, with no tests executed or repository changes. Both requested `.cursor/rules` files remain absent.

data/docs/reviews/2026-10-18-0-6-0/03-sol-re-check-of-0-6-0.md

@@ -0,0 +1,41 @@
+# Re-check of the 0.6.0 fixes, round 3 (Codex Sol, 2026-10-18, at 497879e, PR #66)
+
+Scope: `git diff fe28e9c..497879e`, the answer to review 02, read-only. Verdict: PASS; the two small items (a README sentence that still said every retrieval attempt uses the handoff up; two transaction-boundary tests that did not create the state they named) were applied in the next commit. Open by nature of the environment: PostgreSQL and MySQL races, and a browser test of switching the key type.
+
+## Blocking
+
+- **Durable handoff: closed for Active Record transactions.** The guard checks the **ApiKey pool’s current connection**, before either consumption write, regardless of cache. An unconsumed handoff returns `:inside_transaction` and is restored; a previously committed claim returns `:already_shown` and stays removed. Commit, rollback, cache replacement and cache-flush tests meaningfully exercise those paths. Cache replacement simulates another process; it does not launch one. [token_session.rb:186](lib/api_keys/helpers/token_session.rb:186), [token_session.rb:286](lib/api_keys/helpers/token_session.rb:286), [token_session_test.rb:353](test/helpers/token_session_test.rb:353), [token_session_test.rb:382](test/helpers/token_session_test.rb:382), [token_session_test.rb:499](test/helpers/token_session_test.rb:499)
+
+- **Compatibility boundary: verified.** Without the column, or without a named key, transaction refusal is bypassed and the cache-only behavior remains. The unmigrated transaction test genuinely drops the column. Raw SQL `BEGIN` remains undetected; its test actually releases plaintext and then rolls back the claim. That limitation is now explicit. [token_session.rb:302](lib/api_keys/helpers/token_session.rb:302), [token_session_test.rb:484](test/helpers/token_session_test.rb:484), [token_session_test.rb:514](test/helpers/token_session_test.rb:514), [README.md:517](README.md:517)
+
+## Should fix
+
+- **Non-raising cache-write failures: closed.** Suppression requires both `written == false` and a present reservation. Nil, absent entries and exceptions enqueue. The added tests exercise nil writes, false writes without storage, and failing existence checks through both successful and refused authentication. Existing burst tests exercise genuine suppression before workers run. [authentication.rb:243](lib/api_keys/authentication.rb:243), [refusal_stats_test.rb:239](test/refusal_stats_test.rb:239), [refusal_stats_test.rb:303](test/refusal_stats_test.rb:303)
+
+- **False enqueue results: closed with a working cache.** Both paths release reservations on false results and exceptions. The four-call expectation genuinely requires another attempt for each kind after its first false result. Cleanup remains best effort: a failed cache deletion can retain the reservation until expiry, because false deletion results are ignored and exceptions swallowed. The enqueue failure itself is logged. [authentication.rb:162](lib/api_keys/authentication.rb:162), [authentication.rb:198](lib/api_keys/authentication.rb:198), [authentication.rb:262](lib/api_keys/authentication.rb:262), [refusal_stats_test.rb:359](test/refusal_stats_test.rb:359)
+
+- **Creation form: remains closed.** Server-side creation resolves the default type and replaces submitted ceiling scopes. The new test genuinely POSTs with **both type and scopes omitted**, then with omitted type and crafted scopes. [keys_controller.rb:79](app/controllers/api_keys/keys_controller.rb:79), [keys_controller_test.rb:826](test/controllers/keys_controller_test.rb:826)
+
+- **Retrieval inspection: remains closed.** The test obtains plaintext successfully before checking string, inspection, nested inspection, pretty-print and JSON representations. [token_session_test.rb:782](test/helpers/token_session_test.rb:782)
+
+- **Reconciliation eligibility: remains closed.** The new retyping test updates the database after selection and before `with_lock` reloads the stale object, then checks unchanged scopes and exclusion from the count. This is a meaningful controlled interleaving on one connection. [reconcile_scopes_test.rb:13](test/reconcile_scopes_test.rb:13), [reconcile_scopes_test.rb:62](test/reconcile_scopes_test.rb:62), [api_key.rb:650](lib/api_keys/models/api_key.rb:650)
+
+## Nits
+
+- **Solid Cache documentation: closed.** The stats section now distinguishes conditional writes from atomic absent-entry reservation and explicitly permits simultaneous extra jobs on Solid Cache/PostgreSQL. Cache failures still intentionally permit one job per request before timestamp persistence. [README.md:1162](README.md:1162), [CHANGELOG.md:26](CHANGELOG.md:26)
+
+- **Transaction documentation: substantially closed.** README, SECURITY and CHANGELOG acknowledge host controller transactions and raw SQL boundaries; the filed disposition explicitly supersedes the earlier cache-dependent answer. One remaining inconsistency: “Any retrieval attempt uses the handoff up” contradicts the new retry-preserving status. Qualify it. [README.md:489](README.md:489), [SECURITY.md:49](SECURITY.md:49), [CHANGELOG.md:29](CHANGELOG.md:29), [review trace:36](docs/reviews/2026-10-18-0-6-0/01-astra-review-of-0-6-0.md:36)
+
+- **Empty-scope wording: closed. Version bump: outstanding.** The ceiling exception remains explicit; the runtime version remains `0.5.1`. [README.md:890](README.md:890), [version.rb:4](lib/api_keys/version.rb:4)
+
+## Missing tests
+
+- **SQLite races: closed; PostgreSQL/MySQL coverage remains open.** Both races now hold distinct autocommit connections before opening the barrier and require exactly one `:retrieved` plus seven `:already_shown` results. The NullStore race also checks committed state and later replay. [token_session_test.rb:46](test/helpers/token_session_test.rb:46), [token_session_test.rb:77](test/helpers/token_session_test.rb:77), [token_session_test.rb:309](test/helpers/token_session_test.rb:309)
+
+- **Transaction boundaries: partially closed.** Separate-pool and raw-SQL scenarios are real. However, the “non-joinable inner transaction” joins the existing joinable transaction because it omits `requires_new: true`. Also, on the inspected Rails 8.1.4 source, the untouched outer transaction lets the `requires_new` case use `RestartParentTransaction`, so it does not establish a physical savepoint. Add a real non-joinable transaction and dirty the outer transaction before testing a savepoint. The implementation’s `transaction_open?` check itself covers these states. [token_session_test.rb:433](test/helpers/token_session_test.rb:433), [token_session_test.rb:461](test/helpers/token_session_test.rb:461), [token_session_test.rb:465](test/helpers/token_session_test.rb:465), [database_statements.rb:372](rails source), [transaction.rb:538](rails source)
+
+- **Original burst/bcrypt gaps: remain closed. Browser type switching: still unexecuted.** The rendering test inspects markup/configuration and server-rendered defaults; it never executes the change listener. [refusal_stats_test.rb:192](test/refusal_stats_test.rb:192), [refusal_stats_test.rb:239](test/refusal_stats_test.rb:239), [keys_controller_test.rb:774](test/controllers/keys_controller_test.rb:774)
+
+VERDICT: PASS
+
+The round-2 release blockers are closed under the documented Active Record transaction boundary. I found no new blocking defect across the complete five-commit delta. The remaining documentation and coverage gaps are nonblocking; bump the version before publishing 0.6.0. This was a static review: no tests executed or repository changes made. Both requested `.cursor/rules` files remain absent.