Module: EzLogsAgent::ActorValidator

Defined in:
lib/ez_logs_agent/actor_validator.rb

Overview

Validates and sanitizes actor data structures.

Actor schema: {

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 before being stored in event context.

Constant Summary collapse

VALID_KINDS =

Valid actor_kind values — keep in sync with the server’s Event enum and with ‘EzLogsAgent::UserAgentDetector` output. Anything outside this set is dropped on sanitize.

%w[human agent system hybrid].freeze

Class Method Summary collapse

Class Method Details

.sanitize(actor) ⇒ Hash?

Sanitize actor structure to ensure consistent format Returns nil for invalid actors

Parameters:

  • actor (Hash, nil) —

    Actor hash to sanitize

Returns:

  • (Hash, nil) —

    Sanitized actor or nil



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/ez_logs_agent/actor_validator.rb', line 48

def sanitize(actor)
  return nil unless valid?(actor)
  return nil if actor.nil?

  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

.valid?(actor) ⇒ Boolean

Check if an actor structure is valid

Parameters:

  • actor (Hash, nil) —

    Actor hash to validate

Returns:

  • (Boolean) —

    true if valid (including nil), false otherwise



30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/ez_logs_agent/actor_validator.rb', line 30

def valid?(actor)
  # nil actor is valid (means "unknown provenance")
  return true if actor.nil?

  # Must be a Hash
  return false unless actor.is_a?(Hash)

  # id is required
  id = actor[:id] || actor["id"]
  return false if id.nil? || id.to_s.empty?

  true
end