optiaudit-rails 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ee00e821c324db9b3aba699c39e04eff9b471b1d1dfd5779deae13c6b2f293
-  data.tar.gz: cc49b0ca5595307c1461067dc06467a1f056c998b8e795a35beb29510aeb44d7
+  metadata.gz: 2da47ba93a09717845045e65800eebf3f280a2261402a2bb7f7bf7a2db72a7a2
+  data.tar.gz: a5c6b63dfdba71cfaf7843f3ba0daedffbd1e5d76834cb4a74bb4174ace02ac7
 SHA512:
-  metadata.gz: 3b50e99331b77e089addca33877bf5ba22c38b7f37f3303fb911593382c48200b74b36eaeb321ace3baa748e1a47ac9f5c7c622e98609656f6b067d54bb38e10
-  data.tar.gz: 8559093f201881f42ab2482949b5128c9778f095e0e394fa74187df8b1d6ff48120d8a0093b4032f03feefd47a24d3fbc76552a5bd103f839dac1f301cf032a9
+  metadata.gz: 6578b9531cbdefe3dcb5c05268d6ebaf9c6bc45c6d7773df090cd2822f325d910f76edad3b5b367752845439b1cb924a3c5f6a0546c8ec41076c7cccb2e1709b
+  data.tar.gz: eae50f9a7632ca5a6087292e9b3d2e3c99faffa37619a3e1d86dff713c027ae22243b71de72d6ba18e05689ded14c5ca380ddfe86e85c8433ce72960628a37b3

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-22
+
+Correcciones de la verificación del README contra OptiAudit real, con la 0.1.0 publicada.
+
+### Fixed
+
+- **IP falsificada.** Cuando `Client-IP` y `X-Forwarded-For` no coinciden (`IpSpoofAttackError`), la 0.1.0 mandaba `request.ip`, que es el valor que eligió el cliente. Ahora el evento sale sin `ip_address`, con un warning.
+- **`ip_address` inválido** pasado a mano: OptiAudit lo acepta con 202 y después su worker pierde el evento sin avisar. Ahora la gema lo omite.
+- **`client_timestamp` que no es ISO 8601** pasado a mano: OptiAudit rechazaba el evento con 400. Ahora se reemplaza por la hora actual, con un warning.
+
+### Changed
+
+- README: con el adaptador `:thread`, OptiAudit pisa el `metadata.request_id` de cada evento con el id del POST del batch. El spoofing de IP ocurre en Rails 5.2 a 7.0, y en Rails 5.2 con log `info` es Rails, no la gema, el que responde 500.
+
 ## [0.1.0] - 2026-10-22
 
 Primera versión: el equivalente para Rails de `@theoptimalpartner/nestjs-optiaudit` 0.1.8 (SC25-2703).
@@ -23,5 +37,6 @@ Primera versión: el equivalente para Rails de `@theoptimalpartner/nestjs-optiau
 - **`Optiaudit::Testing`** para que las apps verifiquen sus eventos en tests sin HTTP.
 - Compatibilidad probada en CI: Ruby 2.7 + Rails 5.2 + Sidekiq 6.3, Ruby 3.0 + Rails 6.1 + Sidekiq 6.5 y Ruby 3.2 + Rails 7.0 + Sidekiq 7.2.
 
-[Unreleased]: https://bitbucket.org/RoutingUC/optiaudit-rails/branches/compare/main%0Dv0.1.0
+[Unreleased]: https://bitbucket.org/RoutingUC/optiaudit-rails/branches/compare/main%0Dv0.1.1
+[0.1.1]: https://bitbucket.org/RoutingUC/optiaudit-rails/src/v0.1.1/
 [0.1.0]: https://bitbucket.org/RoutingUC/optiaudit-rails/src/v0.1.0/

data/README.md

@@ -166,7 +166,7 @@ Request data, also filled in by `optiaudit_track`:
 | `ip_address` | `request.remote_ip` (see below) |
 | `user_agent` | `request.user_agent` |
 | `session_id` | SHA-256 of the session id. The raw id is a credential and never leaves the app. Only sent when the action already loaded the session. |
-| `metadata.request_id` | `request.request_id` (`X-Request-ID`), also sent as the `X-Request-ID` header to OptiAudit |
+| `metadata.request_id` | `request.request_id` (`X-Request-ID`), also sent as the `X-Request-ID` header to OptiAudit. With the `:thread` adapter OptiAudit replaces it with the id of the batch request (see [Delivery](#delivery)). |
 | `metadata.module` | the module given to the macro |
 
 ## Client IP Resolution
@@ -179,15 +179,18 @@ rule as the NestJS package since `v0.1.8`: values a client injects on the left a
 If your proxies use public addresses (a CDN in front of the load balancer), add them to
 `config.action_dispatch.trusted_proxies`, or `remote_ip` will return the proxy.
 
-In Rails 5.2, `remote_ip` raises `IpSpoofAttackError` when `Client-IP` and `X-Forwarded-For` disagree.
-The gem then logs a warning and uses `request.ip`, so the event is still sent and the request is not affected.
+When `Client-IP` and `X-Forwarded-For` disagree, `remote_ip` raises `IpSpoofAttackError` (Rails 5.2 to 7.0).
+The gem logs a warning and sends the event without `ip_address`: the other sources of the IP, like
+`request.ip`, return a value the client chose. The gem never raises, but Rails itself may: in Rails 5.2
+the request logger calls `remote_ip` at log level `info`, so with those headers the request fails with
+500 before reaching the controller, with or without this gem.
 
 ## Delivery
 
 | Adapter | When | How |
 |---------|------|-----|
 | `:sidekiq` | Default when Sidekiq is loaded | One job per event in the `optiaudit` queue. Survives deploys. Retried with Sidekiq's backoff (5 times by default) on 5xx, 429, timeouts and connection errors. Other 4xx are dropped with a warning: retrying would not fix them. |
-| `:thread` | Default without Sidekiq | In-memory buffer sent to `POST /events/batch` (up to 100 events) every 5 seconds or when full, from a background thread. Works with forking servers (Puma, Unicorn): each process starts its own thread. Pending events are flushed at exit. Events still in memory are lost if the process is killed, and failed batches are not retried. |
+| `:thread` | Default without Sidekiq | In-memory buffer sent to `POST /events/batch` (up to 100 events) every 5 seconds or when full, from a background thread. Works with forking servers (Puma, Unicorn): each process starts its own thread. Pending events are flushed at exit. Events still in memory are lost if the process is killed, and failed batches are not retried. OptiAudit sets `metadata.request_id` of every event in a batch to the id of the batch request, so the request id of each event is lost. |
 | `:inline` | Console, scripts, debugging | Synchronous `POST /events` in the caller's thread. Adds up to `timeout` seconds to a request. |
 
 Sidekiq jobs receive the event as a hash of string keys and JSON values, so they work with Sidekiq 7's
@@ -271,11 +274,11 @@ Fields accepted by `Optiaudit.track` and `optiaudit_track`, with the limits of O
 | `resource_type` | string | Truncated to 100. |
 | `resource_id` | string | Truncated to 100. |
 | `resource_path` | string | Truncated to 500. |
-| `ip_address` | string | Truncated to 45. |
+| `ip_address` | string | IPv4 or IPv6. Omitted if it is not an IP (OptiAudit would accept it and then lose the event). |
 | `user_agent` | string | |
 | `session_id` | string | Truncated to 255. `optiaudit_track` sends a SHA-256. |
 | `metadata` | hash | Free-form. Converted to JSON types. |
-| `client_timestamp` | Time or ISO 8601 string | Default: when `track` is called, not when the event is sent. |
+| `client_timestamp` | Time or ISO 8601 string | Default: when `track` is called, not when the event is sent. A string that is not ISO 8601 is replaced by the current time, with a warning. |
 
 OptiAudit rejects the whole event when one field is invalid, and in a batch, the whole batch. That is why
 the gem truncates or omits fields instead of sending them as they are.
@@ -289,7 +292,9 @@ the gem truncates or omits fields instead of sending them as they are.
 | No actor | Event not sent |
 | Action raised or response 4xx/5xx | Event not sent |
 | Unknown `event_type` | Event not sent, logs warning |
-| Invalid `actor_email` / `organization_id` | Field omitted, event sent |
+| Invalid `actor_email` / `organization_id` / `ip_address` | Field omitted, event sent |
+| Invalid `client_timestamp` | Replaced by the current time, logs warning, event sent |
+| `Client-IP` and `X-Forwarded-For` disagree (IP spoofing) | Event sent without `ip_address`, logs warning |
 | HTTP 5xx, 429, timeout (3s), connection error | Logs warning, doesn't raise. Sidekiq retries. |
 | HTTP 4xx (other) | Logs warning, doesn't raise, no retry |
 | HTTP 207 on a batch | Logs warning with the rejected events |
@@ -312,7 +317,18 @@ To try the gem end to end against a real OptiAudit (e.g. development), `examples
 OPTIAUDIT_URL=https://... OPTIAUDIT_WRITE_KEY=oat-... bundle exec ruby examples/smoke.rb
 ```
 
-Releases are published to rubygems.org from Bitbucket Pipelines with the manual `custom: publish` pipeline.
+## Releasing
+
+The gem is owned by the `routinguc` account on rubygems.org and requires MFA (`rubygems_mfa_required`),
+so every push asks for a one-time password and releases are published by hand, not from CI:
+
+1. Update `lib/optiaudit/version.rb` and `CHANGELOG.md`, commit and wait for the CI matrix to pass.
+2. Tag the release: `git tag v<version> && git push origin v<version>`.
+3. Build and push with an API key that has the "Push rubygem" scope (rubygems.org → Settings → API keys):
+   ```bash
+   gem build optiaudit-rails.gemspec
+   GEM_HOST_API_KEY=<api-key> gem push optiaudit-rails-<version>.gem   # asks for the OTP
+   ```
 
 ## License
 

data/lib/optiaudit/event.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "ipaddr"
 require "json"
 require "time"
 
@@ -9,8 +10,9 @@ module Optiaudit
   # OptiAudit validates every field and rejects the whole event (and, in a batch,
   # the whole batch) when one is invalid. So instead of sending something that
   # will come back as 400/422, fields are fixed here: strings are truncated to
-  # the API limits, an invalid actor_email is omitted and a non-integer
-  # organization_id is omitted.
+  # the API limits; an invalid actor_email or ip_address and a non-integer
+  # organization_id are omitted; an invalid client_timestamp becomes the
+  # current time.
   module Event
     # Limits from OptiAudit's CreateEventDto.
     MAX_LENGTHS = {
@@ -59,6 +61,7 @@ module Optiaudit
       end
       event["actor_type"] ||= DEFAULT_ACTOR_TYPE
       event.delete("actor_email") unless email?(event["actor_email"])
+      event.delete("ip_address") unless ip?(event["ip_address"])
 
       organization_id = integer(params["organization_id"])
       event["organization_id"] = organization_id if organization_id
@@ -99,6 +102,17 @@ module Optiaudit
       labels.size >= 2 && labels.all? { |label| label.match?(DOMAIN_LABEL) } && labels.last.match?(TOP_LEVEL_DOMAIN)
     end
 
+    # OptiAudit stores it in an INET column: anything else is accepted by the
+    # API and then lost by its worker.
+    def ip?(value)
+      return false if value.nil?
+
+      IPAddr.new(value)
+      true
+    rescue IPAddr::Error
+      false
+    end
+
     def integer(value)
       return value if value.is_a?(Integer)
 
@@ -107,10 +121,25 @@ module Optiaudit
 
     def timestamp(value)
       case value
-      when nil then Time.now.utc.iso8601(3)
+      when nil then current_timestamp
       when Time, DateTime then value.to_time.utc.iso8601(3)
-      else value.to_s
+      else
+        return value.to_s if iso8601?(value.to_s)
+
+        Optiaudit.log_warning("client_timestamp #{value.to_s.inspect} is not ISO 8601, using the current time")
+        current_timestamp
       end
     end
+
+    def iso8601?(value)
+      Time.iso8601(value)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    def current_timestamp
+      Time.now.utc.iso8601(3)
+    end
   end
 end

data/lib/optiaudit/request_data.rb

@@ -17,13 +17,14 @@ module Optiaudit
     end
 
     # remote_ip skips trusted proxies (private ranges by default), so behind a
-    # load balancer it returns the client's public IP. In Rails 5.2 it raises
-    # when Client-IP and X-Forwarded-For disagree.
+    # load balancer it returns the client's public IP. It raises when
+    # Client-IP and X-Forwarded-For disagree; then the IP is omitted: the
+    # alternatives (request.ip) return a value the client chose.
     def client_ip(request)
       request.remote_ip
     rescue ActionDispatch::RemoteIp::IpSpoofAttackError => e
-      Optiaudit.log_warning("remote_ip rejected (#{e.message}), using request.ip")
-      request.ip
+      Optiaudit.log_warning("remote_ip rejected (#{e.message}), event sent without ip_address")
+      nil
     end
 
     # Hashed: the raw session id is a credential and never leaves the app.

data/lib/optiaudit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Optiaudit
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: optiaudit-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - The Optimal Partner