ez_logs_agent 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3edfe639cbf53d13c7b902ae2795687878c6898affaac8cd1b2d4610d9e357ae
-  data.tar.gz: ceef7660ed54a8693e8090d03acae9bdc524b4c6993c810f2fda5507a0e691e3
+  metadata.gz: 452e5fb397336daeaccc2f5738be03545e5bd318243f30755d5e5205d1c9d2f6
+  data.tar.gz: 22b04cd9a432fef3006ffb33c4322c188e0d9bb4914fb07487f1a135ada3877c
 SHA512:
-  metadata.gz: db1c93abdea22ac379936498fee9c9d873f676741e704267898890ad83324dd0f2b26cc0e0c12a0713f6e8ed4b1e0f7535baab8650b17b088c666a45947a18b8
-  data.tar.gz: 50d06b7f6035e01032f4d6066ed9477304851d7273ad25c352719c66be5e6f1ba0f641aad8e8710df754f4bed6b8e205524ae424037af16756af7f9f8297778b
+  metadata.gz: 345f3c6929cf6b88bb6d909c6ada301907ccb2aee852957f8da0b278852033978d5116f6ecd67358b33c50921c4fd82e0c65d2cfa1ebb7304d4b9387f8138617
+  data.tar.gz: b412f7a99fbc624541062f0fc8ab148576f48350fc0c72636938360d7cc6c17974382b6bcb47800224e315666bd91f992fdb6b4d4218f54efb16c06b2140f08a

data/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.6] — 2026-05-24
+
+### Added
+- Optional `actor.principal` sub-field (`{ id:, label? }`) on the wire,
+  carrying the human a `kind: "agent"` or `kind: "hybrid"` actor is
+  acting on behalf of. Drops silently if malformed; existing callers
+  unaffected. Lets the server narrate agent actions as
+  "Claude updated employee, on behalf of Razvan" instead of
+  attributing the change to either party alone.
+
+### Internal
+- Dropped a stray gemspec bump to `sidekiq ~> 8.1` that landed via an
+  auto-merged dependabot PR without re-resolving `Gemfile.lock`. Dev
+  deps are back in sync with the lockfile (`rails ~> 7.0`,
+  `sqlite3 ~> 1.6`, `sidekiq ~> 7.0`); no runtime change for customers.
+
+## [0.1.5] — 2026-05-17 — security release
+
+### Security
+- `DatabaseCapturer` no longer captures columns the host app declared
+  `encrypts :foo` on. Rails 7+ decrypts attributes in memory before
+  `saved_changes` fires, so without this guard the plaintext of every
+  encrypted column was landing on the wire and in the EZLogs UI on
+  every create / update. The new policy is declarative: at capture
+  time we read `record.class.encrypted_attributes` (Rails 7+) and drop
+  every name in that set, regardless of column name. If the host app
+  encrypted it, we never capture it. Upgrade is strongly recommended
+  for any deployment whose models use `encrypts`. Customers running
+  0.1.4 or earlier should also scrub historical events for the
+  affected column names — the data leaked in the past will stay in
+  the event store until masked.
+- `SENSITIVE_PATTERNS` (the secondary name-based denylist) now also
+  matches `private_key`, `public_key`, `signing_key`, `pem`, `cipher`,
+  `nonce`, `salt`, `digest`, `signature`, `hmac`. Belt-and-suspenders
+  for columns that carry sensitive material but weren't declared
+  `encrypts` (legacy code, manual hashing, externally-generated
+  material).
+
 ## [0.1.4] — 2026-05-17
 
 ### Fixed

data/lib/ez_logs_agent/actor_validator.rb

@@ -5,9 +5,15 @@ module EzLogsAgent
   #
   # Actor schema:
   # {
-  #   id: String,               # REQUIRED, stable identifier
-  #   label: String | nil,      # optional, human-readable display
-  #   kind: String | nil        # optional, one of human|agent|system|hybrid
+  #   id: String,                       # REQUIRED, stable identifier
+  #   label: String | nil,              # optional, human-readable display
+  #   kind: String | nil,               # optional, one of human|agent|system|hybrid
+  #   principal: { id:, label? } | nil  # optional, only meaningful when
+  #                                     # kind == "hybrid": the human who
+  #                                     # authorized the agent. Drives the
+  #                                     # "Claude updated employee, on
+  #                                     # behalf of Razvan" framing on the
+  #                                     # server's AiExplainer.
   # }
   #
   # This module ensures actors conform to the expected structure
@@ -46,13 +52,36 @@ module EzLogsAgent
         id = actor[:id] || actor["id"]
         label = actor[:label] || actor["label"]
         kind = actor[:kind] || actor["kind"]
+        principal = actor[:principal] || actor["principal"]
 
         result = { id: id.to_s }
         result[:label] = label.to_s if label
         result[:kind] = kind.to_s if kind && VALID_KINDS.include?(kind.to_s)
+        sanitized_principal = sanitize_principal(principal)
+        result[:principal] = sanitized_principal if sanitized_principal
 
         result
       end
+
+      private
+
+      # Sanitize the optional principal sub-structure. Reuses the same
+      # "id required, label optional" shape as the top-level actor — but
+      # principals are always human, so no `kind` field. Returns nil if
+      # the principal is missing or malformed (we drop silently rather
+      # than rejecting the whole actor; principal is purely advisory).
+      def sanitize_principal(principal)
+        return nil if principal.nil?
+        return nil unless principal.is_a?(Hash)
+
+        id = principal[:id] || principal["id"]
+        return nil if id.nil? || id.to_s.empty?
+
+        result = { id: id.to_s }
+        label = principal[:label] || principal["label"]
+        result[:label] = label.to_s if label
+        result
+      end
     end
   end
 end

data/lib/ez_logs_agent/capturers/database_capturer.rb

@@ -60,7 +60,16 @@ module EzLogsAgent
       # Previously we filtered them out, but this loses important context.
       # FOREIGN_KEY_PATTERN = /_id\z/  # Removed January 2026
 
-      # Patterns for sensitive data to ignore
+      # Patterns for sensitive data to ignore.
+      #
+      # The first source of truth is `record.class.encrypted_attributes`
+      # (Rails 7+ `encrypts :foo` declaration) — see encrypted_attribute?.
+      # If the host app encrypted it, we never capture it.
+      #
+      # This list is the secondary defense: column names that frequently
+      # carry sensitive material even when the host app didn't declare
+      # `encrypts` (legacy code, manual hashing, externally-generated
+      # material). Matching is substring + case-insensitive.
       SENSITIVE_PATTERNS = %w[
         password
         token
@@ -70,6 +79,16 @@ module EzLogsAgent
         ssn
         social_security
         encrypted
+        private_key
+        public_key
+        signing_key
+        pem
+        cipher
+        nonce
+        salt
+        digest
+        signature
+        hmac
       ].freeze
 
 
@@ -276,8 +295,9 @@ module EzLogsAgent
           changes = model.saved_changes
           return nil if changes.nil? || changes.empty?
 
-          # Find meaningful changes
-          meaningful_changes = filter_meaningful_changes(changes)
+          # Find meaningful changes (excludes encrypted columns + sensitive
+          # name patterns — see meaningful_attribute? / encrypted_attribute?)
+          meaningful_changes = filter_meaningful_changes(changes, model)
           return nil if meaningful_changes.empty?
 
           # Build context with all meaningful changes
@@ -305,7 +325,7 @@ module EzLogsAgent
 
           # Filter to meaningful, non-nil scalar attributes
           meaningful_attrs = attributes.select do |attribute, value|
-            meaningful_attribute?(attribute) &&
+            meaningful_attribute?(attribute, model) &&
               scalar?(value) &&
               !value.nil?
           end
@@ -324,20 +344,27 @@ module EzLogsAgent
         # Filters changes to only meaningful business attributes
         #
         # @param changes [Hash] The saved_changes hash
+        # @param model [ActiveRecord::Base] The model instance (used to
+        #   consult `record.class.encrypted_attributes` so columns declared
+        #   `encrypts :foo` are never captured, regardless of their name).
         # @return [Array<Array>] Array of [attribute, [from, to]] pairs
-        def filter_meaningful_changes(changes)
+        def filter_meaningful_changes(changes, model)
           changes.select do |attribute, (from, to)|
-            meaningful_attribute?(attribute) &&
+            meaningful_attribute?(attribute, model) &&
               scalar_values?(from, to) &&
               values_actually_changed?(from, to)
           end.to_a
         end
 
-        # Checks if an attribute is meaningful (not technical/ignored)
+        # Checks if an attribute is meaningful (not technical/ignored).
         #
         # @param attribute [String] The attribute name
+        # @param model [ActiveRecord::Base, nil] The model instance — when
+        #   supplied, columns declared `encrypts :foo` on the model class
+        #   are dropped regardless of name. Authoritative drop: if the host
+        #   app encrypted the column, we never capture it.
         # @return [Boolean]
-        def meaningful_attribute?(attribute)
+        def meaningful_attribute?(attribute, model = nil)
           attr_str = attribute.to_s
 
           # Skip explicitly ignored attributes
@@ -347,13 +374,41 @@ module EzLogsAgent
           # relationship changes (e.g., assigned_to_id changing from user A to user B)
           # Previously filtered via FOREIGN_KEY_PATTERN - removed January 2026
 
-          # Skip sensitive data
+          # Authoritative: drop anything the host app declared `encrypts` on.
+          # Rails decrypts at the attribute layer before saved_changes fires,
+          # so without this check the plaintext would land on the wire.
+          return false if model && encrypted_attribute?(attr_str, model)
+
+          # Skip name-pattern-sensitive data (legacy / non-encrypts paths).
           return false if sensitive_attribute?(attr_str)
 
           true
         end
 
-        # Checks if attribute name contains sensitive patterns
+        # Checks whether the host app declared `encrypts :<attribute>` on
+        # this model's class. Available since Rails 7.0 via
+        # ActiveRecord::Encryption::EncryptableRecord#encrypted_attributes.
+        #
+        # Safe across host Rails versions: returns false if the API isn't
+        # present (older Rails, non-AR records).
+        #
+        # @param attribute [String] The attribute name (already to_s'd)
+        # @param model [ActiveRecord::Base] The model instance
+        # @return [Boolean]
+        def encrypted_attribute?(attribute, model)
+          klass = model.class
+          return false unless klass.respond_to?(:encrypted_attributes)
+
+          encrypted = klass.encrypted_attributes
+          return false if encrypted.nil? || encrypted.empty?
+
+          encrypted.map(&:to_s).include?(attribute)
+        rescue StandardError
+          false
+        end
+
+        # Checks if attribute name contains sensitive patterns.
+        # Secondary check — see SENSITIVE_PATTERNS comment.
         #
         # @param attribute [String] The attribute name
         # @return [Boolean]

data/lib/ez_logs_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EzLogsAgent
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ez_logs_agent
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - dezsirazvan
 bindir: bin
 cert_chain: []
-date: 2026-05-16 00:00:00.000000000 Z
+date: 2026-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: request_store