auditea 0.1.0.beta.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 308c6d6709fed09f200bcfc60829af1b7bd470a018691f456576818ccadc87ee
+  data.tar.gz: 27a669b879d0d864d427359bae7c01daf27e2a2d492e45ed73b492136d659196
+SHA512:
+  metadata.gz: 18517d6f3b825b1f1c97daab0bce3d6da97f68b157d87fb6c6aa302d0b6d79e1e202a682d4c427824df2ae71e7a7f51004124b8cc5ee7246d4d898e0e78cdc06
+  data.tar.gz: c8faa401027af8fadaa8f565994a875c047bed3840722ef101673c7a4565e554965e13e7f1d9b313bd9245499ffb02110145650ade188891278ec06e5aa87d6d

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0.beta.1 (unreleased)
+
+- Initial SDK: capture, structured logs, Rails request/exception observation, ActiveJob failures
+- EVENT_CONTRACT_V1 transport with HTTPS/loopback policy, status classification, byte limits, batch index results
+- Process-aware async queue, flush waits for in-flight work, privacy.redacted_fields
+- Manual smoke script: `examples/manual_capture.rb`

data/DESIGN.md

@@ -0,0 +1,48 @@
+# AUD-P009 / HR01 Design notes
+
+Issue: https://github.com/reznis/auditea-ruby/issues/1
+PR: https://github.com/reznis/auditea-ruby/pull/2
+
+## Authority
+
+- Wire contract: AudiTea vNext `EVENT_CONTRACT_V1`
+- Legacy SDK: design input, not a blind port
+
+## HR01 transport foundations
+
+- HTTPS required; HTTP only for localhost / 127.0.0.1 / ::1
+- Explicit status classification (201/200/409/422/401/413/415/3xx/429/5xx)
+- No redirect following; Authorization never forwarded elsewhere
+- Injectable sleeper/random for bounded exponential backoff + jitter
+- Client-side 128 KiB / 1 MiB / 100-event limits with byte-aware batch splitting
+- Batch results mapped by `index`; accepted/duplicate siblings not retried
+- Process PID ownership for pre-fork safety
+- `flush` waits for buffer empty **and** in-flight delivery
+- `privacy.redacted_fields` records filtered paths
+- ActiveJob final-failure → `job.failed` without job arguments
+
+## Legacy classification (summary)
+
+| Capability | Class |
+|---|---|
+| Explicit capture / track API | KEEP CONCEPT + PORT |
+| Actor / Target helpers | REFACTOR (no email-by-default) |
+| Configuration + Railtie | PORT (observe opt-in) |
+| HTTP Bearer + retries | REFACTOR |
+| Fail-open | KEEP CONCEPT + PORT |
+| Client `event_id` | KEEP CONCEPT + PORT |
+| Client `contract_version` / tenancy fields | DROP / REJECT (vNext conflict) |
+| Request context middleware | PORT + REFACTOR (no session_id) |
+| Rails auto observe | REFACTOR (single subscriber; requests opt-in) |
+| ActionMappingConfig YAML dictionary | REFERENCE ONLY → server taxonomy |
+| Privacy filter | KEEP CONCEPT + REFACTOR (all egress + redacted_fields) |
+| Exception capture | REFACTOR (fixed frames) |
+| Security surface | KEEP CONCEPT (deferred beyond beta.1 core) |
+| `Thread.new` per event | REWRITE → bounded queue |
+| `AUDITEA_DEBUG` full payload logs | DROP |
+| Auto Rails.logger forward | DROP for beta.1; adapter boundary reserved |
+
+## Compatibility
+
+- Ruby >= 3.2, including current Ruby 4.0.x (CI: 3.2, 3.3, 3.4, 4.0.6)
+- Rails 7.2 and Rails 8.1 gemfiles under `gemfiles/`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AudiTea contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,117 @@
+# auditea
+
+Ruby / Rails SDK for [AudiTea](https://github.com/reznis/AudiTea) event collection.
+
+Version: **0.1.0.beta.1**
+
+Captures durable technical and business evidence. AudiTea **server** owns taxonomy, dictionary, human labels, and reinterpretation.
+
+## Install (after RubyGems beta publication)
+
+```ruby
+# Gemfile
+gem "auditea", "0.1.0.beta.1"
+```
+
+```bash
+bundle install
+```
+
+### Contributor / pre-release fallback
+
+```ruby
+gem "auditea", github: "reznis/auditea-ruby", branch: "main"
+```
+
+Prefer the RubyGems artifact for ordinary TEST deployments once published.
+
+## Configure
+
+```ruby
+# config/initializers/auditea.rb
+Auditea.configure do |config|
+  config.endpoint = ENV.fetch("AUDITEA_ENDPOINT", "https://app.auditea.com")
+  config.source_token = ENV.fetch("AUDITEA_SOURCE_TOKEN") # at_src_<public_id>_<secret>
+  config.capture_requests = true   # opt-in Rails request observation
+  config.capture_exceptions = true
+  config.release = ENV["RELEASE"]
+end
+```
+
+Environment variables: `AUDITEA_ENDPOINT`, `AUDITEA_SOURCE_TOKEN` (or `AUDITEA_API_KEY`), `AUDITEA_CAPTURE_REQUESTS`, `AUDITEA_CAPTURE_EXCEPTIONS`, `AUDITEA_ASYNC`, `AUDITEA_RELEASE`.
+
+## Capture APIs
+
+```ruby
+Auditea.capture(
+  "project.approved",
+  actor: { type: "user", id: current_user.id },
+  target: { type: "Project", id: project.id },
+  evidence: { business: { from_status: "draft", to_status: "approved" } }
+)
+
+Auditea.log(:info, "Export finished", context: { export_id: export.id })
+```
+
+Wire format follows AudiTea **EVENT_CONTRACT_V1**:
+
+- Bearer Source credential authentication
+- No client `contract_version`
+- No client tenancy/scope fields (`workspace_id`, `environment`, …)
+- Extensible `evidence` / `context` / `provenance` / `metadata` bags
+
+## Rails
+
+The Railtie installs:
+
+- request context middleware (path **without** query string, request_id, method)
+- optional `process_action` observation → `network.request.completed`
+- optional exception observation → `exception.raised`
+
+Structural evidence is preserved so the server can later distinguish routes such as `/researchers/projects/18` vs `/bcer/1/projects/18` without SDK redeploy.
+
+### Structured logs
+
+Use `Auditea.log` explicitly.
+
+**Automatic `Rails.logger` forwarding is intentionally disabled in beta.1** (`Auditea::Instrumentation::LoggerAdapter`).
+
+## Transport
+
+- Sync or single-worker async queue (not one thread per event)
+- HTTPS required (HTTP allowed only for localhost / 127.0.0.1 / ::1)
+- Single events → `POST /api/v1/events`
+- Batches → `POST /api/v1/event_batches` with per-index result handling
+- Client-side 128 KiB / 1 MiB / 100-event limits
+- Retries with injectable exponential backoff+jitter on 5xx / 429 / network
+- Process-aware queue for pre-fork servers
+- Fail-open by default (`raise_errors: false`)
+
+## Manual smoke (local AudiTea)
+
+```bash
+AUDITEA_ENDPOINT=http://localhost:3000 \
+AUDITEA_SOURCE_TOKEN=at_src_... \
+bundle exec ruby examples/manual_capture.rb
+```
+
+Never commit a real token. The script prints a minimal safe result only.
+
+## License
+
+MIT. See `LICENSE`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+gem build auditea.gemspec
+
+# Rails compatibility (optional local)
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle exec rspec
+BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle exec rspec
+```

data/RELEASE.md

@@ -0,0 +1,43 @@
+# Release: auditea 0.1.0.beta.1
+
+## Preconditions (blockers)
+
+1. Independent human review of the PR
+2. Merge to `main`
+3. Exact-head CI green on merge commit
+4. License approved: **MIT**
+5. RubyGems MFA / owner account for `reznis` with push rights
+6. OTP / API key for `gem push` stored outside the repository (never commit secrets)
+
+## Build
+
+```bash
+git checkout main
+git pull
+bundle install
+bundle exec rspec
+gem build auditea.gemspec
+# => auditea-0.1.0.beta.1.gem
+```
+
+## Publish
+
+Publish only from reviewed `main` after its exact-head CI is green:
+
+```bash
+gem push auditea-0.1.0.beta.1.gem
+```
+
+Optional GitHub Actions: use `rubygems/configure-rubygems-credentials` with a repository secret `RUBYGEMS_API_KEY` — never commit the secret.
+
+## Verify
+
+```bash
+gem install auditea -v 0.1.0.beta.1 --pre
+```
+
+Then install in Semiweb TEST via:
+
+```ruby
+gem "auditea", "0.1.0.beta.1"
+```

data/auditea.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "lib/auditea/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "auditea"
+  spec.version = Auditea::VERSION
+  spec.authors = ["AudiTea"]
+  spec.email = ["opensource@auditea.app"]
+
+  spec.summary = "Ruby/Rails SDK for AudiTea event collection"
+  spec.description =
+    "Capture business events, Rails request evidence, exceptions, and structured logs " \
+    "for AudiTea /api/v1."
+  spec.homepage = "https://github.com/reznis/auditea-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/reznis/auditea-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/reznis/auditea-ruby/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.files = Dir[
+    "lib/**/*",
+    "examples/**/*",
+    "CHANGELOG.md",
+    "README.md",
+    "DESIGN.md",
+    "RELEASE.md",
+    "LICENSE*",
+    "auditea.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+end

data/examples/manual_capture.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Manual smoke against a local AudiTea server. Never commit tokens.
+#
+# Usage:
+#   AUDITEA_ENDPOINT=http://localhost:3000 \
+#   AUDITEA_SOURCE_TOKEN=at_src_... \
+#   bundle exec ruby examples/manual_capture.rb
+
+require "bundler/setup"
+require "auditea"
+
+endpoint = ENV.fetch("AUDITEA_ENDPOINT")
+token = ENV.fetch("AUDITEA_SOURCE_TOKEN")
+
+Auditea.configure do |config|
+  config.endpoint = endpoint
+  config.source_token = token
+  config.async = false
+  config.raise_errors = true
+  config.logger = Logger.new($stdout)
+end
+
+result = Auditea.capture(
+  "sdk.manual_smoke",
+  category: "debug",
+  severity: "info",
+  evidence: {
+    "smoke" => {
+      "script" => "examples/manual_capture.rb",
+      "note" => "manual capture from auditea-ruby"
+    }
+  },
+  metadata: {
+    "sdk_event_kind" => "manual_smoke"
+  }
+)
+
+Auditea.flush(timeout: 5)
+
+safe = {
+  ok: result[:ok],
+  event_id: result[:event_id],
+  outcome: result[:outcome],
+  status: result[:status],
+  queued: result[:queued],
+  reason: result[:reason]
+}.compact
+
+puts "auditea manual_capture result=#{safe.inspect}"

data/lib/auditea/actor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Auditea
+  module Actor
+    module_function
+
+    # No email-by-default (REWRITE of legacy Actor.from_user PII default).
+    def from_user(user, type: nil)
+      return nil unless user
+
+      {
+        "type" => type || user.class&.name,
+        "id" => safe(user, :id) || safe(user, :to_param)
+      }.compact
+    end
+
+    def safe(object, method_name)
+      return nil unless object.respond_to?(method_name)
+
+      value = object.public_send(method_name)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?) ? nil : value.to_s
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/auditea/client.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Auditea
+  class Client
+    def initialize(configuration = nil, http: nil, queue: nil)
+      @configuration = configuration
+      @injected_http = http
+      @injected_queue = queue
+      rebuild!
+    end
+
+    def configuration
+      @configuration || Auditea.configuration
+    end
+
+    def enqueue(event)
+      queue.enqueue(event)
+    end
+
+    def flush(timeout: 5)
+      queue.flush(timeout: timeout)
+    end
+
+    def shutdown
+      queue.shutdown
+    end
+
+    def reset!
+      shutdown
+      rebuild!
+    end
+
+    private
+
+    def queue
+      @queue || rebuild!
+    end
+
+    def rebuild!
+      cfg = configuration
+      @http = @injected_http || Transport::Http.new(cfg)
+      @queue = @injected_queue || Transport::Queue.new(cfg, http: @http)
+      @queue
+    end
+  end
+end

data/lib/auditea/configuration.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Auditea
+  class Configuration
+    DEFAULT_ENDPOINT = "https://app.auditea.com"
+    DEFAULT_BATCH_SIZE = 50
+    DEFAULT_FLUSH_INTERVAL = 2.0
+    DEFAULT_QUEUE_CAPACITY = 1_000
+    DEFAULT_TIMEOUT = 3.0
+    DEFAULT_OPEN_TIMEOUT = 2.0
+    DEFAULT_WRITE_TIMEOUT = 3.0
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_MESSAGE_MAX = 8_192
+    DEFAULT_NESTING_MAX = 16
+    LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+
+    attr_accessor :endpoint, :source_token, :enabled, :async, :raise_errors,
+                  :batch_size, :flush_interval, :queue_capacity, :timeout,
+                  :open_timeout, :write_timeout, :max_retries, :logger, :release, :sdk_name,
+                  :capture_requests, :capture_exceptions, :capture_request_params,
+                  :capture_active_job, :message_max_bytes, :nesting_max_depth
+
+    def initialize
+      @endpoint = ENV.fetch("AUDITEA_ENDPOINT", DEFAULT_ENDPOINT)
+      @source_token = ENV["AUDITEA_SOURCE_TOKEN"] || ENV.fetch("AUDITEA_API_KEY", nil)
+      @enabled = truthy?(ENV.fetch("AUDITEA_ENABLED", "true"))
+      @async = truthy?(ENV.fetch("AUDITEA_ASYNC", "true"))
+      @raise_errors = truthy?(ENV.fetch("AUDITEA_RAISE_ERRORS", "false"))
+      @batch_size = integer_env("AUDITEA_BATCH_SIZE", DEFAULT_BATCH_SIZE)
+      @flush_interval = float_env("AUDITEA_FLUSH_INTERVAL", DEFAULT_FLUSH_INTERVAL)
+      @queue_capacity = integer_env("AUDITEA_QUEUE_CAPACITY", DEFAULT_QUEUE_CAPACITY)
+      @timeout = float_env("AUDITEA_TIMEOUT", DEFAULT_TIMEOUT)
+      @open_timeout = float_env("AUDITEA_OPEN_TIMEOUT", DEFAULT_OPEN_TIMEOUT)
+      @write_timeout = float_env("AUDITEA_WRITE_TIMEOUT", DEFAULT_WRITE_TIMEOUT)
+      @max_retries = integer_env("AUDITEA_MAX_RETRIES", DEFAULT_MAX_RETRIES)
+      @logger = default_logger
+      @release = ENV["AUDITEA_RELEASE"] || ENV["RELEASE"] || ENV.fetch("HEROKU_RELEASE_VERSION", nil)
+      @sdk_name = "auditea-ruby"
+      @capture_requests = truthy?(ENV.fetch("AUDITEA_CAPTURE_REQUESTS", "false"))
+      @capture_exceptions = truthy?(ENV.fetch("AUDITEA_CAPTURE_EXCEPTIONS", "true"))
+      @capture_request_params = truthy?(ENV.fetch("AUDITEA_CAPTURE_REQUEST_PARAMS", "false"))
+      @capture_active_job = truthy?(ENV.fetch("AUDITEA_CAPTURE_ACTIVE_JOB", "true"))
+      @message_max_bytes = integer_env("AUDITEA_MESSAGE_MAX_BYTES", DEFAULT_MESSAGE_MAX)
+      @nesting_max_depth = integer_env("AUDITEA_NESTING_MAX_DEPTH", DEFAULT_NESTING_MAX)
+    end
+
+    def enabled?
+      !!@enabled
+    end
+
+    def async?
+      !!@async
+    end
+
+    def configured?
+      source_token.to_s.strip != "" && endpoint.to_s.strip != ""
+    end
+
+    def validate!
+      raise ConfigurationError, "endpoint must be HTTPS (or HTTP to localhost/127.0.0.1/::1)" unless valid_endpoint?
+      raise ConfigurationError, "batch_size must be 1..100" unless batch_size.between?(1, 100)
+      raise ConfigurationError, "queue_capacity must be >= 1" unless queue_capacity >= 1
+
+      true
+    end
+
+    def events_url
+      join_path("/api/v1/events")
+    end
+
+    def event_batches_url
+      join_path("/api/v1/event_batches")
+    end
+
+    def valid_endpoint?
+      uri = URI.parse(endpoint.to_s)
+      host = normalize_host(uri.host)
+      return false if host.empty?
+
+      case uri
+      when URI::HTTPS
+        true
+      when URI::HTTP
+        LOOPBACK_HOSTS.include?(host)
+      else
+        false
+      end
+    rescue URI::InvalidURIError
+      false
+    end
+
+    private
+
+    def normalize_host(host)
+      host.to_s.downcase.delete_prefix("[").delete_suffix("]")
+    end
+
+    def join_path(path)
+      base = endpoint.to_s.sub(%r{/\z}, "")
+      "#{base}#{path}"
+    end
+
+    def default_logger
+      return Rails.logger if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Logger.new($stdout)
+    end
+
+    def truthy?(value)
+      %w[1 true yes on].include?(value.to_s.strip.downcase)
+    end
+
+    def integer_env(name, default)
+      Integer(ENV.fetch(name, default))
+    rescue ArgumentError, TypeError
+      default
+    end
+
+    def float_env(name, default)
+      Float(ENV.fetch(name, default))
+    rescue ArgumentError, TypeError
+      default
+    end
+  end
+end

data/lib/auditea/current_context.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Auditea
+  # Request-scoped enrichment bag. Stored without session_id / cookies / credentials.
+  module CurrentContext
+    class << self
+      def store
+        Thread.current[:auditea_current_context] ||= {}
+      end
+
+      def clear!
+        Thread.current[:auditea_current_context] = {}
+      end
+
+      def set(attrs)
+        store.merge!(stringify(attrs))
+      end
+
+      def to_h
+        store.dup
+      end
+
+      private
+
+      def stringify(attrs)
+        attrs.each_with_object({}) do |(key, value), memo|
+          next if value.nil?
+
+          memo[key.to_s] = value.is_a?(Hash) ? stringify(value) : value
+        end
+      end
+    end
+  end
+end

data/lib/auditea/event_builder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Auditea
+  module EventBuilder
+    ACTION_FORMAT = /\A[a-z][a-z0-9_.]{0,126}\z/
+
+    module_function
+
+    def build(action:, category: nil, severity: nil, actor: nil, target: nil,
+              context: nil, evidence: nil, provenance: nil, metadata: nil,
+              privacy: nil, occurred_at: nil, event_id: nil)
+      action_key = action.to_s
+      raise ArgumentError, "invalid action: #{action_key.inspect}" unless action_key.match?(ACTION_FORMAT)
+
+      event = {
+        "event_id" => presence(event_id) || SecureRandom.uuid,
+        "occurred_at" => format_time(occurred_at || Time.now.utc),
+        "action" => action_key
+      }
+
+      event["category"] = category.to_s if presence(category)
+      event["severity"] = severity.to_s if presence(severity)
+      event["actor"] = stringify_keys(actor) if actor
+      event["target"] = stringify_keys(target) if target
+
+      merged_context = merge_context(context)
+      event["context"] = merged_context if merged_context
+
+      event["evidence"] = stringify_keys(evidence) if evidence
+      event["provenance"] = merge_provenance(provenance)
+      event["metadata"] = stringify_keys(metadata) if metadata
+      event["privacy"] = stringify_keys(privacy) if privacy
+
+      # Never include contract_version or tenancy/scope selectors (server-owned).
+      event
+    end
+
+    def merge_context(context)
+      base = CurrentContext.to_h
+      extra = stringify_keys(context || {})
+      merged = base.merge(extra)
+      merged.empty? ? nil : merged
+    end
+
+    def merge_provenance(provenance)
+      base = {
+        "sdk" => Auditea.configuration.sdk_name,
+        "sdk_version" => VERSION,
+        "runtime" => "ruby",
+        "ruby_version" => RUBY_VERSION
+      }
+      release = Auditea.configuration.release
+      base["release"] = release if presence(release)
+      base["rails_version"] = Rails.version if defined?(Rails) && Rails.respond_to?(:version)
+      base.merge(stringify_keys(provenance || {}))
+    end
+
+    def format_time(time)
+      time = Time.parse(time.to_s) unless time.respond_to?(:utc)
+      time.utc.iso8601
+    end
+
+    def stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), memo| memo[k.to_s] = stringify_keys(v) }
+      when Array
+        value.map { |v| stringify_keys(v) }
+      else
+        value
+      end
+    end
+
+    def presence(value)
+      return nil if value.nil?
+      return nil if value.respond_to?(:empty?) && value.empty?
+
+      value
+    end
+  end
+end