beskar 0.0.2 → 0.2.0

data/docs/guides/authentication.md

@@ -0,0 +1,213 @@
+# Authentication admission and account locks
+
+Authentication enforcement is independent of audit persistence. Disabling
+`security_tracking`, or a failed optional audit write, does not turn off rate
+limits or risk-based locking. A request-local attempt ID correlates the decision
+with any audit records that were successfully written.
+
+## Dashboard access
+
+The initializer generated by `bin/rails generate beskar:install` contains complete
+dashboard examples for Rails built-in authentication and Devise. Uncomment one
+example's three callbacks: `authenticate_admin`, `authorize_admin`, and
+`audit_actor`. Adapt the example's `admin?` and `beskar_permissions` methods to
+your application; neither Rails nor Devise provides those role/permission methods.
+
+Beskar's dashboard controller inherits from `ActionController::Base`, not your
+application controller. Your host's `Authentication` concern does not run there,
+so `Current.session`, `Current.user`, or `current_user` cannot be assumed available.
+The Rails example resolves `::Session` using `cookies.signed[:session_id]`, checks
+`SessionRevocation.native_session_allowed?`, and shares the resolved user between
+the three callbacks through a controller instance variable. It requires the
+Rails-native model integration below. Adapt the lookup if your host changed the
+generated cookie or session model.
+
+If the session guard raises `NoMethodError` for `beskar_access_allowed?`, add
+`include Beskar::Models::SecurityTrackableAuthenticable` to the host user model.
+The similarly named `Beskar::Models::SecurityTrackable` concern is Devise-specific
+and does not supply this method. Keep the revocation check in place so locked
+accounts cannot access the dashboard through an existing session.
+
+Devise uses Warden and does not require a Rails-native `Session` model. Its example
+uses `request.env['warden'].authenticate(scope: :user)` to resume a session or run
+configured strategies, then `.user(scope: :user)` to read that identity in the
+permission and audit callbacks. The scope identifies a Devise mapping, not a role;
+use `:admin` only for an app with that mapping. See the
+[Warden authentication API](https://github.com/wardencommunity/warden/blob/master/lib/warden/proxy.rb).
+
+Authentication alone does not grant dashboard permissions. `authorize_admin`
+must return `true` for each allowed operation (`read`, `manage_bans`, `export`,
+`read_audit`). Writes and exports additionally require a trusted `audit_actor`;
+see [Audit lifecycle](audit-lifecycle.md).
+
+## Devise
+
+Include `Beskar::Models::SecurityTrackable` on each protected model. The engine
+wraps Devise's database-password strategy: it identifies the target account and
+reserves IP/account (and opt-in global) capacity **before password verification**. This includes
+Devise HTTP Basic password authentication. Unknown accounts receive hashed,
+normalized identity keys; password values are not used as counter keys.
+
+The Warden outcome hook reuses the same admission instead of counting twice.
+Protected-page visits without credentials and session fetches do not manufacture
+failed logins. Devise scope aliases are resolved through `Devise.mappings`.
+
+Risk-based Devise locking requires `:lockable`. A confirmed lock always rejects
+the current attempt; `immediate_signout` defaults true and legacy false no longer
+bypasses a lock. Normal persisted `locked_at` changes rotate a durable account
+generation, invalidating all existing Devise sessions and remember-me cookies.
+Unlock never restores an older generation. This includes Devise's own lockable
+locks and manual model updates, not bulk SQL bypasses. Unrelated accounts/scopes
+remain signed in. Generation reads bypass Active Record's query cache.
+
+**Upgrade:** the new session/remember-cookie salt format signs out existing
+Devise clients once. Drain old workers; mixed versions cannot safely enforce the
+new credentials. All authentication models and state must use one writer pool.
+
+Devise owns its own `unlock_strategy` and `unlock_in`. Beskar's `auto_unlock_time`
+does **not** override Devise's class-level unlock policy. Configure it in Devise.
+Standard custom Warden strategies now reserve IP capacity before `_run!`
+verification; invalid tokens count. The account is charged once when an opaque
+strategy identifies it. Warden `set_user` is guarded even with
+`run_callbacks: false`, covering OAuth-style manual sign-in and stateless Warden.
+Session fetch checks locks without counting a login. A custom strategy overriding
+Warden's dispatcher, model serialization, or credential verifier needs its own
+review. Beskar cannot revoke a host bearer token that omits the generation check.
+See [Security hardening and rollout](../operations/security-hardening.md) for API and WebSocket adapters.
+
+## Rails-native authentication: required integration
+
+The old logging-only controller calls are insufficient. Upgrade the login
+controller to reserve admission before `authenticate_by`, then guard session
+creation:
+
+```ruby
+class User < ApplicationRecord
+  has_secure_password
+  has_many :sessions, dependent: :destroy
+  normalizes :email_address, with: ->(email) { email.strip.downcase }
+  include Beskar::Models::SecurityTrackableAuthenticable
+end
+
+class SessionsController < ApplicationController
+  include Authentication
+  include Beskar::Controllers::SecurityTracking
+
+  allow_unauthenticated_access only: %i[new create]
+  before_action -> { admit_authentication_attempt(User, :user) }, only: :create
+
+  def create
+    if (user = User.authenticate_by(params.permit(:email_address, :password)))
+      return unless complete_authentication(user) { start_new_session_for(user) }
+      redirect_to after_authentication_url
+    else
+      track_authentication_failure(User, :user)
+      redirect_to new_session_path, alert: "Try another email address or password."
+    end
+  end
+end
+```
+
+For custom identity fields, pass an explicit identity-only hash through
+`admit_authentication_attempt(User, :user, credentials: {...})`. Match the identity
+lookup used by your authentication code. Never include passwords in that hash.
+
+The session-creation block runs in a retryable database transaction; restrict it
+to session creation and response-cookie assignment, not external notifications or
+other non-idempotent external actions. Users, sessions, and Beskar state must use
+the same writer connection pool for these transactions to be atomic. Sharded or
+cross-database authentication models need a separately designed adapter.
+
+Existing-session readers must also honor the persistent lock. In Rails'
+`Authentication` concern, adapt `resume_session` along these lines:
+
+```ruby
+def resume_session
+  Current.session ||= find_session_by_cookie
+  if Current.session && !Beskar::Services::SessionRevocation.native_session_allowed?(Current.session, request: request)
+    Current.session = nil
+    cookies.delete(:session_id)
+  end
+  Current.session
+end
+```
+
+The dummy application contains the exercised integration. Include the check on
+every other path that resumes a native session (including custom API or websocket
+authentication). In-flight requests cannot be retroactively canceled by a lock.
+
+Native locks use `beskar_security_states`; no lock columns on the user table are
+required. The default strategy selects native locking for native models. A lock
+revokes all database sessions, never compares their IDs to the unrelated Rack
+session ID, and serializes with guarded new-session creation. If a host session
+destruction callback fails or aborts, the persistent lock remains authoritative,
+access is denied by the reader guard, and physical cleanup failure is logged.
+That lock becomes manual-only so expiry cannot reactivate old sessions. Explicit
+unlock retries cleanup and only clears the lock if every session was removed.
+
+`auto_unlock_time` controls native lock duration. Set it to `nil` for manual-only
+unlocking. To explicitly unlock:
+
+```ruby
+Beskar::Services::AccountLocker.new(user, risk_score: 0).unlock!
+```
+
+Native lock rows retain their deadline inside their data; periodic expired-state
+cleanup does not erase manual locks. Account-lifecycle cleanup remains separate.
+
+## Policy and failure boundaries
+
+- Monitor mode and whitelisted IPs suppress Beskar automatic account locks,
+  sign-outs, and emergency password resets. Observed authentication counters do
+  not consume enforced global/account capacity.
+- Devise's own failed-attempt Lockable policy and host Rails rate limiters are
+  independent. Beskar does not disable those host policies in monitor mode.
+- Admission denials return HTTP 429 with a retry deadline. Native lock denials
+  return HTTP 403. Required authentication-state or enforced risk-assessment
+  failures reject authentication with HTTP 503. Optional audit/enrichment failures
+  are logged and do not reject an otherwise allowed attempt.
+- Direct model tracking methods preserve their optional `SecurityEvent` return
+  contract; that return is **not** an admission decision. Native controllers should
+  use `complete_authentication`, not infer authorization from whether an event
+  saved. `track_authentication_success` now returns a boolean for custom callers;
+  ignoring it is unsafe and does not provide the concurrent session guard.
+
+## Audit and recovery
+
+Known failed targets are associated with their user record for account-history
+analysis. Rejected admissions/sessions use `authentication_blocked`, not
+`login_success`. `metadata["authentication"]` records the attempt ID, scope,
+admission outcome, and actual lock result. Lock events reference that same attempt
+ID; the login audit row may not yet exist or may be disabled.
+
+Deleting an account retains its linked events unchanged, including the original
+`user_type` and `user_id`. This is not anonymization; no event expiry or automatic
+purge is added. See [Audit lifecycle](audit-lifecycle.md) for retention, missing-user
+presentation, and the separate required journal for dashboard ban changes.
+
+Authentication context no longer stores Rack session IDs. Referrers are restricted
+to HTTP(S), with credentials, queries, and fragments removed. Other WAF/export
+privacy findings are still tracked separately; this is not a complete audit-data
+redaction policy.
+
+Emergency reset remains opt-in. Thresholds count confirmed account-lock evidence,
+not strings containing a false travel/device flag or duplicate success events.
+Password invalidation, session revocation, and the mandatory recovery audit commit
+together; failure rolls them back. `require_manual_unlock: true` removes the native
+automatic-unlock deadline. Notification hooks run after all enclosing transactions
+commit.
+
+Account-lock and native emergency-reset notifications now use opt-in post-commit
+Action Mailer jobs. The three notification flags default to false; configure a
+sender, HTTPS recovery entry page, and any security-team recipients before enabling
+them. See [Notifications and recovery](notifications-and-recovery.md) for retries,
+legacy hook overrides, delivery/privacy limits, and the tested native recovery
+handoff. A successful password reset does not bypass a Beskar manual lock. Real
+production delivery and host-specific recovery verification remain necessary.
+Normalized risk evidence and removal of unsafe automatic trust discounts are
+documented in [Risk scoring](risk-scoring.md).
+
+See [Configuration](configuration.md) for validated lock strategies and the
+optional host-owned, post-commit analysis hook. The old `:custom` placeholder is
+rejected; use a supported strategy or explicit `:none`. No built-in background
+analyzer is supplied; analysis and notification delivery are separate job paths.

data/docs/guides/configuration.md

@@ -0,0 +1,182 @@
+# Configuration and supported capabilities
+
+Beskar validates configuration during Rails startup, after main autoloader setup
+and host `after_initialize` callbacks registered by configuration files. Invalid settings raise
+`Beskar::Configuration::Error` and stop boot. Errors identify known setting paths
+without interpolating supplied values or unknown keys.
+
+## Changes and defaults
+
+Prefer `Beskar.configure` in `config/initializers/beskar.rb`:
+
+```ruby
+Beskar.configure do |config|
+  config.monitor_only = true
+  config.rate_limiting = {ip_attempts: {limit: 20}}
+end
+```
+
+Whole-section assignment overlays **library defaults**, including nested defaults.
+The example keeps the default IP period and account/global limits. It also resets
+any previous customizations in that section. To retain existing customizations,
+edit individual entries inside the configure block:
+
+```ruby
+Beskar.configure do |config|
+  config.rate_limiting[:ip_attempts][:limit] = 20
+end
+```
+
+`configure` copies the current settings, yields the copy, validates it, and
+publishes another copy. A raised exception or validation failure leaves the
+active configuration unchanged. Retaining the block's nested hashes/arrays does
+not provide a reference to the published values. Proc callbacks and classes
+remain trusted host objects; their behavior is not sandboxed or deep-copied.
+
+Configuration is sealed after startup validation. Direct/nested mutation and
+wholesale replacement are then rejected. Prefer initializer changes plus a
+coordinated restart. Runtime `Beskar.configure(actor:, reason:, request_id:)`
+requires an explicit `authorize_configuration` grant, validates a detached copy,
+and records a mandatory filtered before/after journal before publishing it.
+Missing authorization, invalid settings, open database transactions, or failed
+journaling cannot publish. Publication is serialized within the Ruby process.
+This is not a distributed configuration store or a per-request snapshot; runtime
+changes affect only this process. The journal records authorized publication
+intent, not proof every worker adopted it. A process crash after journaling can
+prevent publication. Boot/deployment edits and changes inside trusted callback
+implementations must be audited by the host deployment/source-control workflow.
+See [Security hardening and rollout](../operations/security-hardening.md) for the complete contract.
+
+During initialization, `configure` defers resolution of named host jobs until the
+final startup check, when `app/jobs` can be autoloaded. Runtime `configure` and an
+explicit `validate!` resolve enabled jobs immediately.
+
+## What is validated
+
+- Known symbol-keyed section schemas; unknown, misspelled, string, and removed
+  keys are rejected. Partial section assignments fill missing defaults; deleting
+  required entries in place is invalid.
+- Actual booleans, not strings such as `"false"`; dashboard authorization and
+  `audit_actor` callbacks must each be a Proc or nil. Nil authorization denies all
+  dashboard access; nil `audit_actor` permits authenticated reads but rejects writes.
+  Validation does not execute callbacks, grant access, or verify their decisions.
+- Finite positive windows, cache lifetimes, decay half-lives, block durations,
+  and thresholds; integer attempt/history/emergency counts. Authentication risk
+  thresholds must be between 0 and 100. Native `auto_unlock_time` and WAF
+  `permanent_block_after` accept nil for manual-only unlock/no permanent escalation.
+- Valid IP/CIDR whitelist strings; WAF exception policies, nonempty block-duration
+  arrays, regexp exclusions, and method/category names.
+- Supported lock strategies and geolocation providers; configured authentication
+  scope-name syntax. MaxMind requires an existing readable database path.
+- An explicit Active Job subclass when automatic analysis is active.
+- Sender/recipient mailbox syntax and an explicit HTTPS recovery entry page when
+  user notifications are enabled; a nonempty recipient list for enabled team alerts.
+
+Validation does not query application tables or `Rails.cache`. Any Rails.cache
+backend remains supported; coordinated enforcement still uses the database
+contract in [State storage](../operations/state-storage.md). Validation does not prove host
+model/adapter readiness, MaxMind file integrity, queue availability, or production
+database correctness. Runtime enrichment failure handling remains separate.
+
+## Supported capabilities
+
+| Area | Contract |
+| --- | --- |
+| Account locks | `:devise_lockable`, `:rails_auth`, or explicit `:none`. The placeholder `:custom` and unknown values are rejected. Host adapter requirements remain in [Authentication](authentication.md). |
+| Geolocation | `:mock` or `:maxmind`. IP2Location and unknown providers are rejected, including by direct service construction. Mock results do not supply geographic risk evidence. |
+| Background analysis | Off by default. A host-owned Active Job can opt into the post-commit hook below; no built-in analyzer is supplied. |
+| Administration API | No versioned API; authenticated dashboard resource exports remain available. |
+| Administrative history | Dashboard ban changes require a trusted `audit_actor` and per-request `audit_reason`, with mandatory transactional history. See [Audit lifecycle](audit-lifecycle.md) for configuration and the new migration. |
+| Notifications/recovery delivery | Opt-in Action Mailer notices for account locks and native emergency resets, with post-commit jobs and bounded retries. Explicit sender/recovery/team configuration is required. The host still owns password-reset/unlock flows; see [Notifications and recovery](notifications-and-recovery.md). |
+
+Unsupported lock strategies also raise when read at runtime. With risk enforcement
+enabled, authentication rejects this misconfiguration with 503 rather than
+silently skipping the lock; both supported authentication paths are regression
+tested. `:none` deliberately disables locking and is not a custom adapter hook.
+
+## Optional host background analysis
+
+Provide a host job and explicitly enable it. Prefer a class-name string so each
+invocation resolves the current Rails-autoloaded class:
+
+```ruby
+# app/jobs/security_review_job.rb
+class SecurityReviewJob < ApplicationJob
+  def perform(user_type:, user_id:, event_type:)
+    # Restrict supported identities explicitly; adapt for your host models.
+    return unless user_type == "User" && event_type == "login_success"
+    user = User.find_by(id: user_id)
+    return unless user
+
+    suspicious = user.suspicious_login_pattern?
+    Rails.logger.info("Security review user_id=#{user.id} suspicious=#{suspicious}")
+  end
+end
+
+# config/initializers/beskar.rb
+Beskar.configure do |config|
+  config.security_tracking[:analysis_job] = "SecurityReviewJob"
+  config.security_tracking[:auto_analyze_patterns] = true
+end
+```
+
+Automatic invocation occurs on the successful-login tracking path after an
+admitted attempt, with successful-login tracking enabled. It is optional analysis,
+not asynchronous authentication enforcement. A failed optional audit write does
+not by itself prevent invocation. The arguments contain only the model's base
+class name, user ID, and `"login_success"`; no email, credential, session, raw
+request context, or audit-event ID is passed. IDs still identify users and require
+appropriate queue access/retention policy.
+
+Monitor-only and whitelisted observations can invoke the hook too. Arguments do
+not contain the policy mode; host jobs must not infer permission to lock, revoke,
+or reset an account from receiving a job. Keep this hook read-only enrichment;
+final admission and applicable policy remain synchronous.
+
+Enqueueing waits for all enclosing Active Record transactions to commit. An outer
+rollback or rolled-back savepoint cancels its callback. With no open transaction,
+enqueueing runs immediately. Preparation errors, queue exceptions, and aborted
+enqueue attempts are logged without raw exception messages and do not undo a
+committed login/update or change admission.
+
+This is **not a transactional outbox**: a process crash between commit and enqueue
+can lose analysis. Backends/retries may duplicate work. Hosts own queue selection,
+workers, retry/idempotence policy, and any eventual delivery. The local tests use
+real database commits/rollbacks and the Active Job test adapter, not a production
+worker or durable delivery service. The public `analyze_suspicious_patterns_async`
+helper is also callable directly, but is not an admission/authorization check.
+
+## Upgrade notes
+
+- Configure `authorize_admin(request, permission)` separately from authentication;
+  missing permissions deny dashboard access. Grants are `:read`, `:manage_bans`,
+  `:export`, and `:read_audit`. Exports now require actor/reason/history as well.
+- Global login limits and request-wide authentication-quota blocking default off.
+  Explicitly opting in restores their distributed-denial/shared-NAT tradeoffs.
+- A real lock always rejects the login and invalidates prior Devise credentials;
+  `immediate_signout: false` is a deprecated compatibility value, not a bypass.
+
+- Dashboard mutations now require a server-derived `audit_actor` callback and
+  `audit_reason`. Deploy the administrative-action migration before new workers;
+  see [Audit lifecycle](audit-lifecycle.md). Missing actor configuration returns
+  503 for writes, without disabling authenticated reads.
+- Lock/user-reset/team notification flags now default to false. Their old true
+  defaults were log-only placeholders. Explicitly configure delivery before
+  enabling them; see [Notifications and recovery](notifications-and-recovery.md).
+- Automatic analysis now defaults to false. Enabling it requires `analysis_job`;
+  the former silent discovery of a nonexistent `Beskar::SecurityAnalysisJob` is
+  removed. Adapt any existing custom job to the explicit keyword contract above.
+- Replace `:custom`/IP2Location configuration with a supported capability; these
+  placeholders no longer silently do nothing.
+- Remove obsolete `waf[:block_threshold]` and `waf[:monitor_only]`. Use cumulative
+  `waf[:score_threshold]` and top-level `monitor_only`, respectively. A violation
+  count is not interchangeable with a cumulative score.
+- MaxMind configuration with a missing/unreadable path now stops startup. Supply
+  a readable database or explicitly choose `:mock` without geographic risk evidence.
+- Review partial section assignments for the default-overlay behavior above.
+  The sixth batch required no new migration; the eighth batch adds the history table.
+
+The Ruby 4.0.6 regressions exercise invalid/valid application boots, host job
+autoloading, rejected configure-block publication, real commit/rollback behavior,
+and optional queue failures. Production workers, actual class reloading, MaxMind
+database reload/load behavior, and host-specific adapter readiness remain unverified.

data/docs/guides/dashboard-and-search.md

@@ -0,0 +1,251 @@
+# Dashboard and search contract
+
+Reporting/search behavior introduced in the fifth repair batch, which required
+no new migration. The eighth batch adds a history table and required actor/reason
+for dashboard writes; see [Audit lifecycle](audit-lifecycle.md).
+See [Audit data and WAF](audit-and-waf.md) for capture, redaction, export paging,
+and privacy limitations, and [Repair status](../audits/repair-status.md) for open work.
+
+## One set of reporting bands
+
+`Beskar::RiskLevel` supplies model predicates/scopes, dashboard counts, event
+filters (including exports), badges, labels, colors, and filter option text:
+
+| Band | Event score | Badge |
+| --- | --- | --- |
+| Low | 0–29 | success |
+| Medium | 30–69 | warning |
+| High | 70–89 | danger |
+| Critical | 90–100 | critical |
+
+The model's existing high/critical boundaries of 70 and 90 are authoritative.
+`high_risk` and the dashboard's High Risk Events total include critical events;
+the `risk_level=high` filter selects only 70–89. This distinguishes a minimum
+threat threshold from an exclusive histogram bucket.
+
+Invalid/missing/out-of-range scores are unknown, not critical. They receive a
+neutral badge and are excluded from score-band counts, while still counting as
+events in overall totals. Fractional aggregate scores use the same boundaries:
+69.9 remains medium, 89.9 remains high.
+
+These are reporting bands, not a change to scoring weights, configured account
+lock thresholds, WAF severity points, or cumulative WAF ban thresholds.
+Older dashboard thresholds of 61/86 and the conflicting boundary at 30 are
+removed. Review saved filters/report consumers that relied on those old ranges.
+
+## Statistics and user presentation
+
+Overview event totals and failed-login counts reuse one grouped event-type
+query. Risk-band and high/critical counts reuse one grouped score query. The
+selected statistics period has both a lower bound and a current-time upper
+bound, excluding future-dated records. The recent-activity list remains the
+latest ten events across periods, as its own section describes.
+
+These separate queries are not a transactional snapshot: concurrent writes can
+still change results between queries. Grouped counts reduce repeated queries
+but do not remove the cost of scanning a large selected period.
+
+Ban details compute count, average, maximum, first seen, and last seen from all
+events for that IP. The table still shows only the latest 20. Related-event
+tables preload their user associations; lists with equal timestamps use IDs
+as a descending tie-breaker. Pagination remains offset-based for HTML lists;
+exports retain their separate descending-ID cursor contract.
+
+Associated user labels support both Devise `email` and native `email_address`.
+The same bounded, filtered presentation is used by dashboard/event/ban views
+and exports. Native associated email addresses honor both `email_address` and
+the common `email` filter name; this does not rewrite the host user record.
+Attempted-email and metadata fields retain their own audit-key filtering
+contract. Configure a broad `:email` filter to cover those email-bearing keys.
+Where no address is available, views use an attempted email or user-ID fallback.
+
+## Search semantics and database support
+
+Event index and both export formats use `Services::EventSearch`:
+
+- General search covers IP, User-Agent, attempted email, event type, and a text
+  representation of metadata on all three database families below.
+- The email filter checks the attempted-email column, falling back only when
+  that column is null to the top-level `metadata.attempted_email` value.
+  Unrelated metadata prose and the user's current email are not email matches.
+- Terms are bounded to 256 characters, lowercased for ASCII-insensitive matching,
+  and passed as SQL values. Percent, underscore, and the chosen escape character
+  (`!`) are literal text, not user-controlled LIKE wildcards.
+- Missing/empty/non-text search values do not add a filter. Non-ASCII case folding,
+  collation behavior, and serialized-JSON escaping remain database-dependent.
+
+JSON cannot be handled as an ordinary string column everywhere. PostgreSQL
+extracts legacy email text with `->>`; SQLite uses `json_extract`; MySQL uses
+`JSON_EXTRACT` plus `JSON_UNQUOTE`, preserving JSON-null behavior. The centralized
+expressions follow the respective primary references:
+[PostgreSQL JSON operators](https://www.postgresql.org/docs/current/functions-json.html),
+[SQLite JSON functions](https://www.sqlite.org/json1.html), and
+[MySQL JSON search functions](https://dev.mysql.com/doc/refman/8.4/en/json-search-functions.html).
+
+General metadata search uses a TEXT cast on PostgreSQL/SQLite and a CHAR cast on
+MySQL (Mysql2/Trilogy), instead of applying LIKE directly to a JSON column.
+This is text search, not a structured JSON query language or a full-text index.
+
+SQLite execution, request/export integration, literal-wildcard handling, and
+PostgreSQL/MySQL SQL generation are tested locally. No live PostgreSQL/MySQL
+server, production collation matrix, query plan, or throughput benchmark has
+been exercised by this batch. Other adapters have no implemented legacy-email
+extractor and fail explicitly when that filter is used.
+
+Search operates on stored values, before read-time model filtering. It can
+therefore match sensitive legacy values that are hidden when rendered, revealing
+record membership to an authorized administrator. Read-time redaction is not
+historical erasure; remediate legacy storage separately if that inference is
+unacceptable. Searches over newly redacted values cannot recover the original.
+Leading-substring and JSON-text search can still be expensive despite paging.
+
+## Public routes and remaining work
+
+Removed the unimplemented `/beskar/api/v1/*` routes and their route helpers.
+They previously pointed to missing controllers. Supported read exports remain
+`/beskar/security_events/export.csv|json` and
+`/beskar/banned_ips/export.csv|json`, behind dashboard authorization.
+There is no versioned programmatic administration API.
+
+The fifth batch verified rendered HTML and controllers. Batch nine additionally
+exercises the forms in Chromium as described below. Administrative lifecycle and
+opt-in notifications have their own contracts in [Audit lifecycle](audit-lifecycle.md)
+and [Notifications and recovery](notifications-and-recovery.md).
+
+## Ban forms and timezones
+
+New/edit expiry fields are explicitly **UTC**, independent of browser timezone and
+the host application's `Time.zone`. A timezone-free dashboard value such as
+`2030-11-03T01:30` means 01:30 UTC, not a DST-dependent local wall time. Scripted
+dashboard requests may also supply ISO 8601 timestamps with `Z` or a numeric
+`+HH:MM`/`-HH:MM` offset. These are normalized to the identified UTC instant.
+The parser accepts valid calendar dates with four-digit positive years, hours
+0–23, optional seconds, and up to six fractional digits. Malformed dates, overflow
+times, leap seconds, non-string shapes, and excessive precision return 422 rather
+than normalizing to another date or silently selecting a default.
+
+HTML datetime controls use millisecond precision. Edit forms mark that precision
+with `expiry_precision=milliseconds`; submitting the unchanged displayed instant
+preserves existing database microseconds. Scripted requests without that form
+marker retain their explicit precision. This is not optimistic locking against
+stale form edits. Report timestamps outside these inputs continue to use their
+existing Rails/application-zone presentation; they are not reinterpreted as UTC
+wall-clock input.
+
+Creation presets are computed on the server, once: a positive integer number of
+seconds, capped at 90 days. An explicit custom expiry takes precedence; absent/empty
+duration and custom expiry use 24 hours. Invalid supplied presets and unknown ban
+types return 422. Permanent creation ignores temporary duration/expiry values.
+This restriction applies to dashboard creation/the manager, not a new global ban
+duration cap. Direct `BannedIp.ban!` and administrative extension contracts remain
+separate. Valid custom dates can be in the past, permitting an explicit expiry;
+the database does not silently advance them.
+
+Quick edit buttons add elapsed UTC hours to the later of the displayed expiry or
+the browser's current time; they never convert a UTC string through the browser's
+local timezone. They only edit the field until the operator submits. Switching a
+permanent ban to temporary requires an expiry; JavaScript suggests 24 hours if the
+field is empty. Switching to permanent disables temporary controls, and server
+normalization clears expiry. Presets are not converted to client-clock timestamps
+on submission. Create-form validation retries retain the selected duration rather
+than turning it into a stale custom expiry. Existing custom reasons remain selectable,
+and blank-expiry validation renders without a secondary view error.
+
+## Script policy and native navigation
+
+One layout behavior script carries the host-generated nonce. Inline `onclick`,
+`onchange`, and submission handlers are removed from the dashboard. Delegated
+listeners are installed once per document; initial load and restored pages refresh
+the control state without adding duplicate handlers. Validation errors and notices
+are no longer automatically removed after five seconds.
+
+The engine does not loosen the host's CSP. Hosts enforcing script CSP must provide
+a nonce generator and allow that nonce in `script-src`, for example:
+
+```ruby
+# Host CSP configuration: merge with your existing policy, do not discard it.
+config.content_security_policy_nonce_generator = ->(_) { SecureRandom.base64(24) }
+config.content_security_policy_nonce_directives = %w[script-src style-src]
+```
+
+Local tests enforce `script-src 'self' 'nonce-…'`, `script-src-attr 'none'`, and no
+script `unsafe-inline` or `unsafe-eval`. The layout's style block also receives a
+nonce, but the existing views still contain **inline style attributes**. Tests
+explicitly allow `style-src-attr 'unsafe-inline'`; hosts forbidding those attributes
+will not get the intended styling. This is script-policy compatibility, not full
+strict-style CSP support. Moving the remaining styles into classes/assets remains
+open; hosts should not weaken script policy to accommodate dashboard controls.
+
+The dashboard body explicitly opts out of Turbo Drive (`data-turbo="false"`).
+Links and forms use native navigation even when the host has loaded Turbo. The
+handwritten method-link/form synthesizer is removed; Rails forms carry their own
+CSRF token and `_method` where needed. Beskar does not require Rails UJS, Turbo,
+an import map, or a JavaScript bundler for its dashboard. Mutation redirects use
+the existing Rails redirect flow; no new client-side submission protocol is added.
+
+With JavaScript disabled or the behavior script blocked, normal new/edit/review
+forms still work. Temporary fields and bulk controls remain available; server
+authorization, reasons, validation, and CSRF remain mandatory. Quick edit buttons,
+preview, selection helpers, automatic page-size submission, and bulk confirmation
+dialogs are enhancements. A visible page-size submit button works without scripts.
+Changing page size preserves filters, drops the old page number, and avoids duplicate
+hidden `per_page` inputs. Row unban actions still require a separate review form;
+bulk confirmation dialogs require JavaScript.
+
+## Browser verification and remaining limits
+
+Browser tests use the standard [Rails system-test integration](https://api.rubyonrails.org/v8.0/classes/ActionDispatch/SystemTestCase.html)
+with Capybara and Selenium, installed only in the development project's test bundle.
+Turbo Rails is a test-only dependency used to load the real host library, not a new
+runtime dependency of Beskar. Run separately from the ordinary suite:
+
+```sh
+mise exec -- env PARALLEL_WORKERS=1 bin/rails test test/system/dashboard_test.rb
+```
+
+Use an installed Chrome/Chromium and matching ChromeDriver. Optional
+`BESKAR_BROWSER_BINARY` and `BESKAR_BROWSER_DRIVER` select their paths; otherwise the
+harness discovers local binaries/driver, with Selenium's usual fallback when no
+driver is installed. `BESKAR_BROWSER_LOG` enables verbose ChromeDriver logs at the
+specified path, appended across tests. Each test gets a fresh browser process.
+The tests do not use a production account, copy the project runtime, or disable
+Chromium's sandbox. Failed startup does not trigger another browser launch for
+screenshots or teardown.
+
+Coverage includes UTC edits with multiple browser zones and DST-boundary dates,
+microsecond preservation, server-relative presets with a skewed browser clock,
+permanent/temporary toggles, persistent validation feedback/retry, bulk clear/cancel/
+confirm, page-size filters, actual Turbo-loaded navigation, back navigation, no
+duplicate audit operations, and JavaScript-disabled create/review/delete with real
+CSRF protection. Browser console checks reject script/CSP errors (excluding a
+missing favicon and the deliberately tested validation response's HTTP 422).
+Screenshot inspection supplemented functional checks.
+
+Native form submissions now wait for the destination URL before checking the
+success notice. Scoped notice checks also wait for same-URL redirects, such as
+bulk unban. This avoids reading the outgoing document during navigation: in
+[CI run 35353219531](https://github.com/AuditBadger-com/beskar/actions/runs/35353219531),
+ChromeDriver 153 reported `Node with given id does not belong to the document`
+while the update itself succeeded. A delayed-submit regression with matching
+text in the outgoing page fails without the destination wait and passes with it.
+The export test similarly waits for the export URL before checking the response.
+With Chrome/ChromeDriver 153.0.8010.52 and mise Ruby 4.0.7, all 11 browser tests
+(118 assertions) pass with seeds `42702`, `101`, `202`, `303`, and `20260918`.
+
+CI includes a separate Ubuntu 24.04 browser job with a
+[matching Chrome/driver setup](https://github.com/browser-actions/setup-chrome)
+and system dependencies. A per-binary AppArmor rule permits the downloaded
+Chrome to use its sandbox without disabling global user-namespace restrictions.
+Startup is verified by the Selenium suite itself. The standalone `--dump-dom`
+preflight hung with Chrome for Testing 153.0.8010.52, reproduced locally even
+though all ten browser tests passed with that exact browser/driver pair.
+The `browser-diagnostics` artifact retains verbose driver logs (including Chrome
+startup diagnostics) and failure screenshots for three days. Browser startup now
+passes in hosted CI; the navigation-synchronization repair still needs hosted
+confirmation. Other browsers, full strict-style CSP,
+mobile/accessibility review, arbitrary host layouts/authentication integrations,
+Turbo Frames/Streams, and transactional stale-form protection remain unverified
+or out of scope for this batch. No new database migration is required for batch
+nine; the preceding administrative-history migration and actor configuration still
+apply. Update scripted callers that previously relied on local-zone timestamps or
+loosely parsed duration strings before deploying.