beskar 0.1.0 → 0.2.1

data/db/migrate/20260910000001_create_beskar_security_states.rb

@@ -0,0 +1,14 @@
+class CreateBeskarSecurityStates < ActiveRecord::Migration[8.0]
+  def change
+    create_table :beskar_security_states do |t|
+      t.string :key, null: false
+      t.json :data, null: false, default: -> { "('{}')" }
+      t.datetime :expires_at
+      t.integer :lock_version, null: false, default: 0
+      t.timestamps
+    end
+    add_index :beskar_security_states, :key, unique: true
+    add_index :beskar_security_states, :expires_at
+    add_index :beskar_security_events, [:user_type, :user_id, :event_type, :created_at], name: "index_beskar_events_on_user_event_time"
+  end
+end

data/db/migrate/20260911000001_create_beskar_administrative_actions.rb

@@ -0,0 +1,22 @@
+class CreateBeskarAdministrativeActions < ActiveRecord::Migration[8.0]
+  def change
+    create_table :beskar_administrative_actions do |t|
+      t.string :actor, null: false, limit: 200
+      t.string :action, null: false
+      t.bigint :target_id, null: false
+      t.string :operation_id, null: false, limit: 36
+      t.string :request_id, null: false, limit: 200
+      t.text :reason, null: false
+      # MySQL requires JSON defaults to be expressions, even for literals.
+      t.json :before_state, null: false, default: -> { "('{}')" }
+      t.json :after_state, null: false, default: -> { "('{}')" }
+      t.datetime :created_at, null: false
+    end
+    # No user/ban foreign key or cascading association: the action must survive
+    # deletion of its live target. Retention is a separate, explicit operation.
+    add_index :beskar_administrative_actions, [:operation_id, :target_id], unique: true,
+      name: "index_beskar_actions_on_operation_target"
+    add_index :beskar_administrative_actions, [:target_id, :id]
+    add_index :beskar_administrative_actions, :created_at
+  end
+end

data/db/migrate/20260911000002_expand_administrative_action_targets.rb

@@ -0,0 +1,6 @@
+class ExpandAdministrativeActionTargets < ActiveRecord::Migration[8.0]
+  def change
+    add_column :beskar_administrative_actions, :target_type, :string, null: false, default: "BannedIp"
+    change_column_null :beskar_administrative_actions, :target_id, true
+  end
+end

data/docs/README.md

@@ -0,0 +1,73 @@
+# Beskar documentation
+
+Start with the current guides and operational contracts below. The original
+review and archived overview describe earlier code; they are not current setup
+instructions. [Repair status](audits/repair-status.md) distinguishes verified
+changes from open findings and production validation still required.
+
+## Start here
+
+- **Installing or integrating:** follow the [project README](../README.md#installation),
+  then read [configuration](guides/configuration.md),
+  [authentication](guides/authentication.md), and [state storage](operations/state-storage.md).
+- **Upgrading an existing installation:** use the
+  [security hardening and rollout checklist](operations/security-hardening.md#rollout).
+- **Working on repairs:** consult [repair status](audits/repair-status.md) and the
+  [original findings](audits/project-review.md) before selecting work.
+
+## Guides
+
+- [Configuration](guides/configuration.md) — validation, supported capabilities,
+  defaults, and audited runtime changes.
+- [Authentication](guides/authentication.md) — Devise/Warden admission, native
+  session integration, account locks, and revocation boundaries.
+- [Risk scoring](guides/risk-scoring.md) — factors, geographic evidence, and
+  heuristic limitations.
+- [Audit data and WAF](guides/audit-and-waf.md) — filtering, exports, scanner
+  matching, requested-path evidence, and privacy boundaries.
+- [Audit lifecycle](guides/audit-lifecycle.md) — unchanged event retention,
+  administrative permissions, actor/reason history, and migrations.
+- [Dashboard and search](guides/dashboard-and-search.md) — reporting, search,
+  routes, forms, timezones, and browser/CSP behavior.
+- [Notifications and recovery](guides/notifications-and-recovery.md) — opt-in
+  delivery jobs and host-owned recovery flows.
+
+## Operations
+
+- [State storage](operations/state-storage.md) — database authority, cache
+  independence, concurrency, rate limits, cleanup, and rollout.
+- [Monitor-only mode](operations/monitor-only-mode.md) — observation behavior and
+  the transition to enforcement.
+- [Security hardening](operations/security-hardening.md) — authentication
+  coverage, deployment requirements, availability tradeoffs, and validation gates.
+
+## Audits and repair tracking
+
+- [Repair status](audits/repair-status.md) — completed batches, test evidence,
+  unresolved findings, and next verification gates.
+- [Original project review](audits/project-review.md) — the September 2026
+  diagnostic baseline and F01–F26 findings; preserved as historical evidence.
+
+## Research and historical reference
+
+- [Rust performance assessment](research/rust-performance-assessment.md) — a
+  measured investigation and proposal, not an implemented feature or performance
+  guarantee.
+- [Archived project overview](archive/project-documentation.md) — the
+  pre-remediation architecture and examples; do not use it as current guidance.
+- [Changelog](../CHANGELOG.md) — historical release notes.
+
+## Maintaining these docs
+
+Keep `README.md` and `CHANGELOG.md` at the repository root. Put current feature
+guides in `guides/`, deployment/runtime contracts in `operations/`, findings and
+progress in `audits/`, proposals in `research/`, and superseded references in
+`archive/`. Use lowercase, hyphenated filenames and relative Markdown links.
+Source paths mentioned in prose are relative to the repository root.
+
+Add new documents to this index. The gem includes `docs/**/*.md`; link/index and
+packaging regressions run with:
+
+```sh
+mise exec -- env PARALLEL_WORKERS=1 bin/rails test test/documentation_test.rb
+```