api_keys 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a6a1c6dfefaad9dff55f1ccf08e4564fe510e1ca2355a8a42b1e0a39044d346
-  data.tar.gz: ec7ee25c565277dfd6f5ea00edf6908114d8950163d0c3f0cdeca5f754e41723
+  metadata.gz: 3183ee0be98a005fd2fc318937f9f8aeb6d8a6c0528a0b75d7234e55cde80480
+  data.tar.gz: 67080c1cddf08ee647657c8845a9332c61279249d8c9765ea0ad6fda4e4961a3
 SHA512:
-  metadata.gz: fa7545cb53f513946904cf6a2ae623429627af0e1831c1d4c789f294f0db636d6d98aeebce54892b1b7d6bbbee399d11c782122ed875d57e5d38f83d1de10a43
-  data.tar.gz: 3721750d661a77af6086e72b7f6afd4a47deb4c6e8f7535836a5fbed6ed45f1e2506d1a97fd96b02729ea2746df63c2c9997839e3de4535dec41020dd65bf139
+  metadata.gz: ff1adbe9b462443d7f278013030780bfc99ec2ef5acb6a814966a3530950147069bf33cc79d3d35ae8f6af8f76bf43b3a9a42d9692e22f9757df3c172b186535
+  data.tar.gz: 6f3f9febcd26069d345739d6268c8bcd4acce174ccdd2c24f915c8cfabf5404c2aa708e3538219ad8be30c8392d633101a6f1e52d7b099e123bf01474511859e

data/CHANGELOG.md

@@ -1,3 +1,63 @@
+## [Unreleased]
+
+## [0.4.0] - 2026-08-09
+
+This security-focused release hardens authentication, authorization, credential handling, the self-serve dashboard, background jobs, configuration, dependencies, CI, and the release supply chain. Upgrading is strongly recommended. Existing installations must apply the authentication lookup migration before deploying this version.
+
+### Security
+
+- Make token caching a non-authoritative ID lookup hint: every hit reloads current database state and cryptographically re-verifies the presented token, so revocation, expiration, scope changes, and cache poisoning fail closed.
+- Replace token-derived SHA1 cache identifiers with SHA256 and prevent plaintext tokens, digests, stored public tokens, request objects, and authentication result objects from leaking through gem logs, inspection, serialization, errors, or async callback arguments.
+- Bound token sizes, bcrypt input length, bcrypt cost, and bcrypt candidate work; add an indexed prefix/last-four/algorithm lookup for existing installations.
+- Bound historical-prefix discovery and fall back to an indexed last-four lookup so cache poisoning or unusually many retired prefixes cannot create unbounded request work or strand valid bcrypt keys.
+- Serialize all quota checks and inserts by locking the owner row, including direct Active Record creation paths.
+- Enforce immutable authentication identity fields, supported digest formats, bounded scopes/metadata/identifiers/session payloads, runtime permission ceilings, configured key types, and fail-closed environment isolation.
+- Require every newly created key to have a configured type once key-types mode is enabled; existing untyped legacy keys remain compatible.
+- Require explicit finite permissions and `revocable: false` for intentionally stored public tokens.
+- Fail closed when dashboard owner authentication is missing or ineffective; bind one-time session tokens to their created key; reject malformed create/update payloads; scope every dashboard lookup to the current owner; and add no-store, anti-framing, referrer, MIME-sniffing, and permissions headers.
+- Apply an enforcing nonce-based dashboard Content Security Policy and remove inline handlers, un-nonced scripts, third-party assets, and inline style attributes from credential-bearing views.
+- Enforce HTTPS authentication by default in production, disable query-string credentials in the demo, and remove third-party code from pages that handle tokens.
+- Pin GitHub Actions to immutable commits and add dependency auditing, Brakeman, CodeQL, dependency review, and Dependabot configuration.
+- Remove the unused Claude Code workflow and its third-party CI/OIDC surface.
+- Encrypt one-time secret-token handoffs inside the Rails session with an application-derived AES-256-GCM key, bind them to the created key, expire them after ten minutes, and delete them on first retrieval. Legacy in-flight plaintext handoffs remain readable for upgrade continuity but are never newly written.
+
+### Reliability
+
+- Execute authentication callbacks exactly once with serializable, credential-free context hashes.
+- Resolve job queues dynamically, prevent out-of-order/future jobs from corrupting usage timestamps, and keep request counters atomic.
+- Validate security-sensitive global and per-owner configuration early and store permission policy as defensive frozen copies.
+- Ensure each appraisal excludes the next Rails line's prereleases; Rails 7.2 uses its upstream-compatible Minitest 5 while Rails 8/default suites remain on Minitest 6.
+- Return `403 Forbidden` when a valid key lacks a required scope while retaining `401 Unauthorized` for missing or invalid credentials.
+- Honor the public `parent_controller` configuration (with a backward-compatible internal Engine fallback), cascade owner deletion across non-revocable keys, and debounce `last_used_at` jobs for one minute by default when exact request counting is disabled.
+- Remove redundant single-column polymorphic-owner indexes from new-install migrations and exclude development-only metadata from built gems.
+- Resolve every finding recorded in [issue #12](https://github.com/rameerez/api_keys/issues/12) through a code fix, test, explicit bounded design, or superseding hardening control.
+
+### Upgrade notes
+
+- Existing installations should run `rails generate api_keys:add_authentication_index` and `rails db:migrate` before deploying this version.
+- Invalid expiration presets now raise `ArgumentError` instead of silently creating a key without expiration.
+- Authentication identity fields (`token_digest`, algorithm, prefix, last four, owner, key type, and environment) can no longer be changed through normal Active Record updates after creation.
+- Typed keys with blank or retired environments now fail closed. Repair any such legacy rows before deployment; untyped legacy keys are unaffected.
+- When `key_types` is configured, new keys must pass `key_type:` or use a configured `default_key_type`; this does not invalidate existing untyped keys.
+- Authentication callbacks now execute asynchronously exactly once with small, credential-free context hashes instead of request, result, or model objects. Update callback consumers and ensure the application has a durable Active Job backend where delivery matters.
+- Production authentication now requires HTTPS by default and fails closed when a request appears insecure. Verify TLS termination and trusted proxy forwarding before deployment.
+- Scope and permission policy is enforced at creation, update, and authentication time. Malformed scopes and scopes above a configured ceiling are rejected; blank scopes deny access whenever a scope policy is enabled.
+- Reassess every permission ceiling configured with `public: true`. The gem validates that public tokens are non-revocable and finitely scoped, but only the host application can determine whether each named permission is safe for an untrusted client.
+- The actively security-tested matrix is Ruby 3.3, 3.4, and 4.0 with Rails 7.2, 8.0, and 8.1. The gemspec continues to permit Ruby 3.1+ for compatibility, but older runtimes are outside the documented security-support matrix.
+- Missing-scope responses now use HTTP 403 instead of 401. Clients that branch on the previous status should update.
+- New one-time token handoffs are encrypted and expire after ten minutes. Custom integrations must use `ApiKeys::TokenSession` rather than reading its internal session payload directly.
+- `last_used_at` updates are debounced for one minute by default when `track_requests_count` is false. Set `stats_update_interval = 0` for per-request timestamps; enabling exact request counting necessarily enqueues a stats job for every successful authentication.
+- Deleting an owner now removes all associated API-key rows, including non-revocable types. Direct user-level `revoke!`, `destroy`, and `destroy!` protections remain unchanged.
+
+## [0.3.0] - 2026-02-09
+
+- Add Stripe-style key types and environments (publishable/secret keys with test/live isolation)
+- Add public key token storage for non-revocable publishable keys
+- Add headless helpers for custom dashboard integrations
+- Add usage analytics scopes for admin dashboards
+- Fix PostgreSQL FOR UPDATE with COUNT aggregate error
+- Fix blank scopes bypass in key_types mode: empty scopes no longer grant unrestricted access when permission ceilings are configured
+
 ## [0.2.1] - 2025-08-04
 
 - Fix SecurityController callback reference from :authenticate_api_keys_user! to :authenticate_api_keys_owner!