beskar 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 025703c477080d31ed167a7012be2cd390d3d73b2447b61624bffd3243f1aa6b
-  data.tar.gz: a056e8c20364351e9f96734836991be7949a92b279dfba05a6b327dad0b3d823
+  metadata.gz: d9899541c9baa5b2c2a0ac7106dba36f9fff668962e5b70e11d34efa483a7d76
+  data.tar.gz: 6f7e9d0f5f725ea486974958a517ec32a725e5a2723efa7bb5e8738e794b39ca
 SHA512:
-  metadata.gz: 1a70b96954525ebdf9867fcc1656b5313e111a0fd6c4e2e31f111d3d8c9320a156f5d29ed582ee06c5d418f26c7c04601147d749c7825747b601ae1975855211
-  data.tar.gz: 6523638cd97d91b78779f5fd8cf6276e5d07c39f3ba87ec342abae007ffed99dd505adf346917ed3601be0085d81ff247c874feed92effe27b34e94d523ab7c5
+  metadata.gz: 6f79580e66cc3c2e777d10b65fb14e4e7bc6bc7ea2abb86763cea85b059f439867a2a8167f41896bbed907b6d8cfdcbf9ca00407407cc22881ac42ea69e09b63
+  data.tar.gz: 1cede8ef21ba6c4a3704cac25b055e42719c543fdfdefd10916e56576f0b18f644723ac73528979a20a4a0c489d8178b656d38cf8d0bc072f1d2d1c901354ebe

data/CHANGELOG.md

@@ -2,10 +2,172 @@
 
 All notable changes to Beskar will be documented in this file.
 
+The entries below include historical behavior. For the current contract and
+upgrade requirements, use the [documentation index](docs/README.md) and
+[repair status](docs/audits/repair-status.md).
+
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## Unreleased
+
+## 0.2.1 - 2026-11-04
+
+Bug fixes for monitor mode and requests without a client address, plus
+requested-path evidence for WAF threats in the dashboard.
+
+### Changed
+
+- WAF events and ban metadata now retain `waf_analysis.request_path`: the
+  requested path with its original percent encoding, limited to 1,024 characters.
+  Queries and fragments are removed and host `request_path` filters apply. Event
+  and ban details show it beside the matched rules, and the events list has a
+  Requested Path column. Records created before this release show "Not recorded".
+- The dashboard overview labels top threat IPs as "in the selected period".
+
+### Fixed
+
+- Monitor mode and whitelisted addresses no longer deny a login when one request
+  sets a second user on a scope. Each user is recorded as a login of its own.
+  Enforcement still denies it as `identity_changed`.
+- A request with no usable client address no longer raises
+  `IPAddr::InvalidAddressError` in the middleware. `RequestContext.ip` returns nil,
+  and the middleware passes the request to the application without ban or WAF
+  checks. A login from such a request succeeds without an audit row. Logins
+  through non-password Warden strategies (such as OAuth) from such a request also
+  reach authentication; rate limiting with no applicable tier is now an allowed
+  no-op instead of raising `ArgumentError`.
+
+## 0.2.0 - 2026-09-21
+
+Security hardening, coordinated enforcement, and auditable administration.
+This release includes breaking changes for 0.1.0 installations; read the
+[rollout checklist](docs/operations/security-hardening.md#rollout) before upgrading.
+
+### Breaking changes
+
+- Security state is now coordinated through the database, independently of the
+  `Rails.cache` backend. Apply the new state and administrative-history migrations
+  before starting upgraded workers. Users, sessions, and security state must share
+  the writer connection pool; old cache counters are not imported.
+- Dashboard authentication no longer grants administrative permissions by itself.
+  Configure `authorize_admin` separately for `:read`, `:manage_bans`, `:export`,
+  and `:read_audit`. Ban mutations and exports require a trusted `audit_actor`,
+  a reason, and successfully recorded administrative history.
+- Configuration is validated and sealed at startup. Invalid or unsupported
+  settings stop boot; direct runtime mutation is rejected. Runtime changes through
+  `Beskar.configure` require separate authorization, actor/reason/request context,
+  and an audit record. Runtime publication remains process-local.
+- Global authentication budgets and request-wide blocking for exhausted IP login
+  quotas now default off. Opt in with `global_attempts[:enabled]` and
+  `ip_attempts[:block_requests]` under `rate_limiting` if those policies are needed.
+  Notifications and automatic pattern analysis also default off and require
+  explicit host configuration when enabled.
+- Monitor-only mode records observations in separate state without automatically
+  creating IP bans, locking accounts, or resetting passwords. Review bans created
+  by older monitor-mode versions before enabling enforcement; existing bans are
+  not automatically removed.
+- Devise session and remember-cookie salts now include a durable revocation
+  generation, causing a one-time sign-out of existing credentials. Confirmed locks
+  revoke prior credentials regardless of `immediate_signout`; unlocking does not
+  restore them. Risk-based locking itself remains opt-in.
+- Rails-native authentication must use the admission, session-creation, and
+  session-resumption guards. OAuth, custom tokens, API controllers, and Action Cable
+  require the appropriate host integration; they are not automatically protected
+  merely by mounting the engine.
+- Deleting an account retains its security events unchanged, including their
+  original account identifiers. Security events and administrative history reject
+  ordinary model-level rewrites/deletes. This is not anonymization or protection
+  against privileged SQL/bulk updates; hosts still own retention policy.
+- Exports are bounded to 1,000 rows per cursor page and use filtered fields and
+  CSV formula-injection defenses. Scripted consumers must supply an audit reason
+  on every page and accommodate the revised export contract.
+
+### Added
+
+- Framework-neutral authentication admission, API and Action Cable session guards,
+  explicit session revocation, and persistent Rails-native account locks with
+  automatic or manual-only unlock policies.
+- An append-only administrative journal and read-only history dashboard for ban
+  changes, export preparation, and authorized runtime configuration changes, with
+  actor, reason, request/operation correlation, and filtered before/after state.
+- Opt-in post-commit notification delivery jobs with bounded retries, plus an
+  explicit host-job contract for background analysis. Password recovery remains
+  owned by the host application or Devise; no built-in analyzer or recovery-token
+  issuer is supplied.
+- Organized, gem-packaged guides and operational contracts under `docs/`, including
+  authentication coverage, deployment requirements, and remaining limitations.
+- Complete dashboard initializer examples for Rails built-in authentication and
+  Devise, including permission checks and audit identity. The Rails example checks
+  the signed session cookie and session revocation, with explicit instructions to
+  include `SecurityTrackableAuthenticable` in the host user model. Installation
+  guidance explains Devise's Warden scopes and the dashboard controller context.
+
+### Security and fixes
+
+- Enforce Devise password/HTTP Basic admission before credential verification;
+  coordinate IP/account limits and backoff across workers without double-counting
+  outcomes. Required enforcement-state failures deny access while optional audit
+  failures do not undo authentication decisions.
+- Honor monitor/whitelist policy for automatic enforcement and isolate observation
+  counters. Whitelisted attempts do not consume enforced global capacity.
+- Fix lost updates in rate-limit/WAF state, concurrent ban extensions, and mixed
+  administrative/automatic changes. MySQL locking reads prevent stale transaction
+  snapshots from overwriting ban updates or missing sessions during revocation;
+  native cleanup also ignores stale loaded associations and preserves callbacks.
+- Read ban decisions from the authoritative database, preserve permanent bans
+  during cleanup, normalize individual IP addresses, and reject invalid durations.
+  Administrative extensions no longer fabricate additional violations.
+- Retain security events after account deletion, tolerate missing accounts in
+  dashboards/exports, and make bulk administrative changes and their history
+  transactional. Failed or aborted persistence no longer reports success.
+- Bound and filter audit metadata, headers, identities, and error logging; use
+  Rails-resolved client IPs and consistent Rack 3 headers and retry deadlines.
+- Correct timestamped geographic risk history, impossible-travel calculations,
+  provider/cache isolation, and shared decision/audit evidence. Mock geography
+  cannot supply geographic risk evidence; repeated IP use and unlocks no longer
+  grant implicit trust discounts.
+- Narrow WAF exception scoring to relevant evidence by default, improve path
+  canonicalization and exclusions, and prevent duplicate charges for one request.
+- Fix dashboard reporting/search/pagination, UTC and DST-sensitive ban editing,
+  unchanged microsecond expiry preservation, persistent validation messages, and
+  nonce-based scripts. Native forms retain CSRF protection and work with JavaScript
+  disabled or host Turbo loaded.
+- Fix migration installation, MySQL JSON defaults and foreign-key types, Ruby 4
+  test dependencies, Chrome sandbox setup, and browser navigation synchronization.
+  CI covers Ruby 3.4/4.0, SQLite, PostgreSQL, MySQL, and Chromium system tests.
+
+### Removed
+
+- Nonfunctional versioned API routes and their helpers. Dashboard resource exports
+  remain available behind their dedicated permissions.
+- Claims of support for unimplemented capabilities: general SQL injection/XSS
+  filtering, JavaScript challenges, honeypots, and a built-in automatic pattern
+  analyzer. Unsupported custom lock strategies and geolocation providers are
+  rejected rather than silently accepted.
+
+### Upgrading from 0.1.0
+
+1. Copy and apply all engine migrations with `bin/rails beskar:install:migrations`
+   and `bin/rails db:migrate`, including the administrative-action target expansion.
+2. Configure administrative permissions, actor resolution, and reasons; review
+   [configuration](docs/guides/configuration.md) and
+   [audit lifecycle](docs/guides/audit-lifecycle.md) for the changed contracts.
+3. Adopt the [authentication guards](docs/guides/authentication.md), review all
+   credential entry points, and plan the one-time Devise sign-out. Legacy custom
+   tokens without a revocation generation must be rejected or reissued.
+4. Drain old workers and restart from the same reviewed configuration. Review
+   legacy bans and risk evidence in monitor mode before enforcing, and schedule
+   `bin/rails beskar:cleanup_security_state` to reclaim expired enforcement state.
+   This task does not purge audit events or account-lifetime revocation generations.
+5. Validate host recovery/delivery, shared-NAT behavior, and database load/failure
+   handling in staging. Cache independence does not remove database availability
+   requirements or establish production capacity guarantees.
+
+## 0.1.0 - 2025-11-25
+
+Historical notes carried forward from the 0.1.0 release. In particular, the
+monitor-mode ban creation described below is superseded by 0.2.0.
 
 ### ⚠️ BREAKING CHANGES
 
@@ -14,7 +176,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Use `config.monitor_only = true/false` at the configuration root level instead
   - The method `Beskar.configuration.waf_monitor_only?` has been **removed**
   - Use `Beskar.configuration.monitor_only?` instead
-  - See [BREAKING_CHANGES.md](BREAKING_CHANGES.md) for detailed migration guide
+  - See [Current upgrade guidance](docs/operations/security-hardening.md) for detailed migration guide
 
 - **Dashboard authentication now required in all environments**
   - Previous behavior: Dashboard allowed access in development/test without authentication
@@ -46,7 +208,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Configurable authentication via `config.authenticate_admin` proc
   - Rails 7+ compatible with built-in CSRF protection
   - Install generator for easy setup (`rails generate beskar:install`)
-  - Full documentation in [DASHBOARD.md](DASHBOARD.md)
+  - Full documentation in [Current dashboard guide](docs/guides/dashboard-and-search.md)
 - **WAF Rails Exception Detection** - Enhanced security through Rails exception analysis
   - Detects `ActionController::UnknownFormat` exceptions (e.g., `/users/1.exe`) as potential scanning attempts
   - Detects `ActionDispatch::RemoteIp::IpSpoofAttackError` as critical IP spoofing attacks
@@ -104,10 +266,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Documentation
 
 - Updated README with new configuration structure
-- Enhanced MONITOR_ONLY_MODE.md with examples of querying ban records
+- Enhanced docs/operations/monitor-only-mode.md with examples of querying ban records
 - Added migration guide in BREAKING_CHANGES.md
-- Created PROJECT_DOCUMENTATION.md for development reference
-- Updated PROJECT_DOCUMENTATION.md with comprehensive dashboard authentication section
+- Created docs/archive/project-documentation.md for development reference
+- Updated docs/archive/project-documentation.md with comprehensive dashboard authentication section
   - Documented authentication flow and architecture
   - Added configuration examples and design principles
   - Included test coverage details
@@ -117,27 +279,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Clear warnings about development-only bypass patterns
 
 
-### Versioning Policy
+## Versioning policy
 
-- **Major version (X.0.0)**: Breaking changes that require code changes
-- **Minor version (0.X.0)**: New features, backward compatible
-- **Patch version (0.0.X)**: Bug fixes and minor improvements
+- Before 1.0, minor releases (0.X.0) may include explicitly documented breaking changes.
+- Patch releases (0.X.Y) contain backward-compatible fixes.
+- From 1.0 onward, breaking changes require a major version increment.
 
-### Upgrade Guide
+## Upgrade guide
 
 When upgrading between versions with breaking changes:
 
-1. Read the [BREAKING_CHANGES.md](BREAKING_CHANGES.md) file
+1. Read the [Current upgrade guidance](docs/operations/security-hardening.md) file
 2. Update your configuration according to the migration guide
 3. Run any new migrations: `rails db:migrate`
 4. Test in development/staging before deploying to production
 5. Start with `monitor_only = true` to verify behavior
 
-### Support
-
-- GitHub Issues: https://github.com/humadroid-io/beskar/issues
-- Documentation: https://humadroid.io/beskar
-
----
+## Support
 
-[Unreleased]: https://github.com/humadroid-io/beskar/compare/v0.0.2...HEAD
+- [GitHub issues](https://github.com/AuditBadger-com/beskar/issues)
+- [Documentation](docs/README.md)