invoance 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 465e862ed29dc6dc0d5c4829472f739ddbaaace820845dd7c54bb6d9aabd77dc
+  data.tar.gz: 49e142ab37c383cd94b14aaa6f02a456e7a190bbdd961de45d9f4e215febe56c
+SHA512:
+  metadata.gz: 6e26cf457a2f054a6d027c30a2fcb3b6335b220431de8d4b67541c6be824287a934ddc5b4509017602fc2949240489c7760fd85b4b024b00bbe609c82e43c078
+  data.tar.gz: ca148fd01bef837bc515093332b3908866a6ce6ebbae7ba02cc97bb84ca33e0869655d128681895d767a2b339ce130d302c55cb21b6c024423aadf64814400a1

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-06
+
+### Added
+
+- Initial release of the official Ruby SDK for the Invoance compliance API.
+- `Invoance::Client` with resource accessors: `events`, `documents`,
+  `attestations`, `traces`, and `audit` (sub-resources `audit.events`,
+  `audit.orgs`, `audit.streams`, `audit.portal_sessions`, `audit.exports`).
+- Synchronous HTTP transport built on Ruby stdlib (`net/http`) with zero runtime
+  gem dependencies.
+- Full error hierarchy under `Invoance::Error` (`AuthenticationError`,
+  `ForbiddenError`, `NotFoundError`, `ValidationError`, `ConflictError`,
+  `QuotaExceededError`, `ServerError`, `NetworkError`, `TimeoutError`) with
+  status-code mapping and `Retry-After` parsing.
+- Client-side input validation for SHA-256 hex digests.
+- Offline audit-log verification: `invoance.audit/1` canonicalization
+  (`Invoance::AuditCanonical`) and Ed25519 signature verification
+  (`Invoance::AuditVerify`) using stdlib OpenSSL.
+- `attestations.verify_signature` and `attestations.verify_payload` for
+  client-side AI-attestation verification.
+- `Invoance::Resources.content_idempotency_key` for content-stable idempotency keys.
+- `Client#validate` for a non-raising API-key/connectivity probe.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Invoance, Inc.
+
+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,198 @@
+# Invoance Ruby SDK
+
+Official Ruby SDK for the [Invoance](https://invoance.com) compliance API —
+cryptographic proof infrastructure for events, documents, AI attestations,
+traces, and audit logs.
+
+- **Synchronous** — methods return values and raise exceptions on error.
+- **Zero runtime dependencies** — pure Ruby stdlib (`net/http`, `json`,
+  `openssl`, `digest`).
+- **Offline verification** — check Ed25519 signatures and recompute audit-log
+  canonical hashes without trusting the server.
+
+Requires **Ruby >= 3.0**.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "invoance"
+```
+
+Then:
+
+```console
+$ bundle install
+```
+
+Or install directly:
+
+```console
+$ gem install invoance
+```
+
+## Quick start
+
+```ruby
+require "invoance"
+
+# Reads INVOANCE_API_KEY and INVOANCE_BASE_URL from the environment.
+client = Invoance::Client.new
+
+# Or pass the key explicitly:
+client = Invoance::Client.new(api_key: "inv_live_abc123")
+
+# Ingest a compliance event
+event = client.events.ingest(
+  event_type: "user.login",
+  payload: { "user_id" => "u_42" }
+)
+puts event["event_id"]
+
+# Verify the API key / connectivity (never raises)
+result = client.validate
+raise "bad config: #{result["reason"]}" unless result["valid"]
+```
+
+Responses are plain Ruby `Hash`es with **string keys** matching the wire JSON
+exactly — no symbolization.
+
+## Configuration
+
+```ruby
+client = Invoance::Client.new(
+  api_key: "inv_live_...",             # or ENV["INVOANCE_API_KEY"]
+  base_url: "https://api.invoance.com", # or ENV["INVOANCE_BASE_URL"]
+  api_version: "v1",
+  timeout: 30,                          # seconds
+  idempotency_key: nil,                 # default for mutating requests
+  extra_headers: {}                     # merged into every request
+)
+```
+
+## Resources
+
+### Events
+
+```ruby
+client.events.ingest(event_type:, payload:, event_time: nil, trace_id: nil, idempotency_key: nil)
+client.events.list(page: nil, limit: nil, date_from: nil, date_to: nil, event_type: nil)
+client.events.get(event_id)
+client.events.verify(event_id, payload_hash: nil, payload: nil) # provide exactly one
+```
+
+### Documents
+
+```ruby
+client.documents.anchor(document_hash:, document_ref: nil, event_type: nil,
+                        original_bytes_b64: nil, metadata: nil, trace_id: nil,
+                        idempotency_key: nil)
+
+# Convenience: hash + base64 a file, then anchor.
+client.documents.anchor_file(file: "./invoice.pdf", document_ref: "Invoice #1042")
+# For raw bytes instead of a path:
+client.documents.anchor_file(file: bytes, is_path: false, document_ref: "blob")
+
+client.documents.list(...)
+client.documents.get(event_id)
+client.documents.get_original(event_id) # => raw binary String
+client.documents.verify(event_id, document_hash:)
+```
+
+### AI Attestations
+
+```ruby
+client.attestations.ingest(
+  type: "chat.completion",
+  input: { "prompt" => "..." },
+  output: { "text" => "..." },
+  model_provider: "openai",
+  model_name: "gpt-4o",
+  model_version: "2026-01",
+  subject: { user_id: "u_1", session_id: "s_9" } # optional
+)
+
+client.attestations.list(...)
+client.attestations.get(id)
+client.attestations.verify(id, content_hash:)
+client.attestations.get_raw(id) # => Hash
+
+# Client-side verification (no trust in the server):
+client.attestations.verify_payload(id, raw_json_string_or_hash)
+result = client.attestations.verify_signature(id)
+result["valid"] # => true/false
+```
+
+> **Note:** for `verify_payload`, pass the raw JSON string exactly as shown in
+> the dashboard's "Raw immutable record" viewer. Key order is preserved (not
+> sorted) because the backend hashes with struct field order.
+
+### Traces
+
+```ruby
+trace = client.traces.create(label: "Batch 2026-07")
+client.traces.list(status: "open")
+client.traces.get(trace_id, event_page: 1, event_limit: 50)
+client.traces.seal(trace_id)
+client.traces.proof(trace_id)         # => Hash
+client.traces.proof_pdf(trace_id)     # => raw binary PDF String
+client.traces.delete(trace_id)
+```
+
+### Audit Logs
+
+```ruby
+client.audit.orgs.create(organization_id: "org_1", name: "Acme")
+client.audit.events.ingest(
+  organization_id: "org_1",
+  action: "invoice.approved",
+  actor: { "type" => "user", "id" => "u_1" },
+  targets: [{ "type" => "invoice", "id" => "inv_9" }]
+)
+client.audit.events.list(organization_id: "org_1", limit: 100)
+client.audit.streams.create("org_1", url: "https://siem.example/hook")
+client.audit.portal_sessions.create(organization_id: "org_1", intent: "viewer")
+client.audit.exports.create(organization_id: "org_1", format: "csv")
+```
+
+Offline verify an audit event returned by the API:
+
+```ruby
+event = client.audit.events.get("evt_123")
+result = Invoance::AuditVerify.verify_audit_event(event)
+# => { "valid" => true, "reason" => nil, "payload_hash" => "...", "key_source" => "event" }
+
+# Pin against the tenant's registered key for a real tamper guarantee:
+Invoance::AuditVerify.verify_audit_event(event, public_key: registered_hex_key)
+```
+
+## Error handling
+
+Everything the SDK raises inherits from `Invoance::Error`:
+
+```ruby
+begin
+  client.events.ingest(event_type: "user.login", payload: {})
+rescue Invoance::QuotaExceededError => e
+  puts "rate limited, retry after #{e.retry_after_seconds}s"
+rescue Invoance::AuthenticationError
+  puts "check INVOANCE_API_KEY"
+rescue Invoance::Error => e
+  puts "Invoance error: #{e.message} (status #{e.status_code})"
+end
+```
+
+Every error exposes `status_code`, `error_code`, `body`,
+`retry_after_seconds`, and `request_context`.
+
+## Development
+
+```console
+$ bundle install
+$ bundle exec rspec
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/invoance/audit_canonical.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module Invoance
+  # `invoance.audit/1` canonical serializer (client-side).
+  #
+  # Reproduces the server's frozen canonicalization so an event's signature
+  # can be checked offline. Canonical bytes = build the signed object
+  # (signed fields present + non-nil, timestamps normalized, forced
+  # schema_id), strip nil members recursively, sort every object's keys
+  # deeply (alphabetical), emit compact UTF-8.
+  #
+  # NOTE: Ruby's JSON.generate produces compact output, does NOT escape
+  # forward slashes, and emits UTF-8 literally — matching Node's
+  # JSON.stringify.
+  module AuditCanonical
+    AUDIT_SCHEMA_ID = "invoance.audit/1"
+
+    SIGNED_FIELDS = %w[
+      org_id event_id seq ingested_at action occurred_at actor targets context metadata
+    ].freeze
+
+    REQUIRED_FIELDS = %w[
+      org_id event_id seq ingested_at action occurred_at actor targets
+    ].freeze
+
+    RFC3339 = /\A(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|z|[+-]\d{2}:\d{2})\z/.freeze
+
+    module_function
+
+    # RFC3339 -> the one canonical form: UTC, exactly 3 fractional digits, `Z`.
+    # Fractional seconds are TRUNCATED to millis (not rounded).
+    #
+    # @param value [String]
+    # @return [String]
+    def normalize_ts(value)
+      raise ArgumentError, "timestamp must be a string" unless value.is_a?(String)
+
+      m = RFC3339.match(value.strip)
+      raise ArgumentError, "invalid RFC3339 timestamp: #{value}" unless m
+
+      yr, mo, dy, hh, mi, ss, frac, off = m.captures
+      millis = ((frac || "") + "000")[0, 3].to_i
+
+      # Build UTC epoch (in milliseconds) manually — no rounding.
+      base = Time.utc(yr.to_i, mo.to_i, dy.to_i, hh.to_i, mi.to_i, ss.to_i)
+      epoch_ms = (base.to_i * 1000) + millis
+
+      unless off == "Z" || off == "z"
+        sign = off[0] == "+" ? 1 : -1
+        oh = off[1, 2].to_i
+        om = off[4, 2].to_i
+        epoch_ms -= sign * (oh * 3600 + om * 60) * 1000
+      end
+
+      secs, ms = epoch_ms.divmod(1000)
+      d = Time.at(secs).utc
+      format("%04d-%02d-%02dT%02d:%02d:%02d.%03dZ",
+             d.year, d.month, d.day, d.hour, d.min, d.sec, ms)
+    end
+
+    # @api private
+    def strip_nils(v)
+      case v
+      when Array
+        v.map { |x| strip_nils(x) }
+      when Hash
+        out = {}
+        v.each do |k, val|
+          next if val.nil?
+
+          out[k] = strip_nils(val)
+        end
+        out
+      else
+        v
+      end
+    end
+
+    # @api private
+    def sort_deep(v)
+      case v
+      when Array
+        v.map { |x| sort_deep(x) }
+      when Hash
+        v.keys.map(&:to_s).sort.each_with_object({}) do |k, out|
+          # Keys may be symbols or strings on the input; normalize lookup.
+          orig = v.key?(k) ? k : k.to_sym
+          out[k] = sort_deep(v[orig])
+        end
+      else
+        v
+      end
+    end
+
+    # @api private
+    def build_signed_object(event)
+      unless event.is_a?(Hash)
+        raise ArgumentError, "event must be a JSON object"
+      end
+
+      e = stringify_keys(event)
+      REQUIRED_FIELDS.each do |f|
+        if e[f].nil?
+          raise ArgumentError, "missing required field: #{f}"
+        end
+      end
+
+      out = {}
+      SIGNED_FIELDS.each do |f|
+        val = e[f]
+        next if val.nil?
+
+        out[f] = (f == "occurred_at" || f == "ingested_at") ? normalize_ts(val) : val
+      end
+      out["schema_id"] = AUDIT_SCHEMA_ID
+      out
+    end
+
+    # The canonical signed bytes for an audit event (binary String).
+    #
+    # @param event [Hash]
+    # @return [String] compact UTF-8 JSON
+    def canonical_audit_bytes(event)
+      signed = sort_deep(strip_nils(build_signed_object(event)))
+      JSON.generate(signed)
+    end
+
+    # payload_hash = SHA-256(canonical bytes), lowercase hex.
+    #
+    # @param canonical [String]
+    # @return [String]
+    def payload_hash_hex(canonical)
+      Digest::SHA256.hexdigest(canonical)
+    end
+
+    # @api private
+    def stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+    end
+  end
+end

data/lib/invoance/audit_verify.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+require_relative "audit_canonical"
+
+module Invoance
+  # Offline, client-side signature verification for audit events.
+  #
+  # Reconstructs the canonical signed bytes from an event returned by the API
+  # and checks the Ed25519 signature using stdlib OpenSSL (no external
+  # dependency, matching this SDK's zero-dependency design).
+  #
+  # Trust note: by default this verifies against the key embedded in the event
+  # (event["signing_public_key"]), which proves the payload is internally
+  # consistent with that key. For a real tamper guarantee, pass public_key =
+  # the tenant's registered key (the server pins it and never trusts the row's
+  # key).
+  #
+  # Ed25519 requires Ruby's OpenSSL to support Ed25519 (Ruby >= 3.0 with a
+  # modern OpenSSL). On older stacks the verify degrades to an invalid result
+  # with a descriptive reason rather than crashing. If you need to support
+  # such stacks, the `ed25519` gem is a drop-in alternative — but this SDK
+  # stays dependency-free.
+  module AuditVerify
+    # DER SPKI prefix for a raw 32-byte Ed25519 public key (RFC 8410).
+    SPKI_ED25519_PREFIX = ["302a300506032b6570032100"].pack("H*").freeze
+
+    module_function
+
+    # Ed25519-verify a raw message with a raw 32-byte public key.
+    # Returns true/false; never raises (OpenSSL errors → false).
+    #
+    # @param message [String] binary message bytes
+    # @param signature [String] binary signature bytes
+    # @param pubkey [String] raw 32-byte public key
+    # @return [Boolean]
+    def ed25519_verify(message, signature, pubkey)
+      der = SPKI_ED25519_PREFIX + pubkey.b
+      pkey = OpenSSL::PKey.read(der)
+      # nil digest for Ed25519 (single-shot, no separate hash).
+      pkey.verify(nil, signature.b, message.b)
+    rescue StandardError, OpenSSL::OpenSSLError
+      false
+    end
+
+    # Hex-decode a hex string into a binary String.
+    # @api private
+    def hex_to_bytes(hex)
+      [hex].pack("H*")
+    end
+
+    # Verify one audit event's signature offline.
+    #
+    # @param event [Hash] string-keyed event as returned by the API
+    # @param public_key [String, nil] hex-encoded pinned key to verify against
+    # @return [Hash] { "valid" =>, "reason" =>, "payload_hash" =>, "key_source" => }
+    def verify_audit_event(event, public_key: nil)
+      key_source = public_key.nil? ? "event" : "pinned"
+      e = stringify(event)
+
+      signed_input = {
+        "org_id" => e["org_id"],
+        "event_id" => (e["id"].nil? ? e["event_id"] : e["id"]),
+        "seq" => e["seq"],
+        "ingested_at" => e["ingested_at"],
+        "action" => e["action"],
+        "occurred_at" => e["occurred_at"],
+        "actor" => e["actor"],
+        "targets" => e["targets"]
+      }
+      signed_input["context"] = e["context"] unless e["context"].nil?
+      signed_input["metadata"] = e["metadata"] unless e["metadata"].nil?
+
+      begin
+        canonical = AuditCanonical.canonical_audit_bytes(signed_input)
+      rescue StandardError
+        return result(false, "canonicalization_failed", "", key_source)
+      end
+
+      recomputed = AuditCanonical.payload_hash_hex(canonical)
+      if !e["payload_hash"].nil? && e["payload_hash"] != recomputed
+        return result(false, "payload_hash_mismatch", recomputed, key_source)
+      end
+
+      key = public_key.nil? ? e["signing_public_key"] : public_key
+      return result(false, "no_public_key", recomputed, key_source) if key.nil? || key == ""
+
+      sig = e["signature"]
+      return result(false, "no_signature", recomputed, key_source) if sig.nil? || sig == ""
+
+      sig_bytes = sig.is_a?(String) ? hex_to_bytes(sig) : sig
+      key_bytes = key.is_a?(String) ? hex_to_bytes(key) : key
+      ok = ed25519_verify(canonical, sig_bytes, key_bytes)
+
+      if ok
+        result(true, nil, recomputed, key_source)
+      else
+        result(false, "signature_invalid", recomputed, key_source)
+      end
+    end
+
+    # @api private
+    def result(valid, reason, payload_hash, key_source)
+      {
+        "valid" => valid,
+        "reason" => reason,
+        "payload_hash" => payload_hash,
+        "key_source" => key_source
+      }
+    end
+
+    # @api private
+    def stringify(hash)
+      return {} unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+    end
+  end
+end

data/lib/invoance/client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "http"
+require_relative "errors"
+require_relative "resources/events"
+require_relative "resources/documents"
+require_relative "resources/attestations"
+require_relative "resources/traces"
+require_relative "resources/audit"
+
+module Invoance
+  # Top-level SDK client.
+  #
+  #   # Reads INVOANCE_API_KEY / INVOANCE_BASE_URL from env automatically
+  #   client = Invoance::Client.new
+  #
+  #   # Or pass explicitly to override
+  #   client = Invoance::Client.new(api_key: "inv_live_abc123")
+  #
+  #   event = client.events.ingest(event_type: "user.login", payload: { user_id: "u_42" })
+  class Client
+    attr_reader :events, :documents, :attestations, :traces, :audit
+
+    # @param api_key [String, nil]
+    # @param base_url [String, nil]
+    # @param api_version [String]
+    # @param timeout [Numeric] seconds
+    # @param idempotency_key [String, nil]
+    # @param extra_headers [Hash]
+    def initialize(api_key: nil, base_url: nil, api_version: "v1", timeout: 30,
+                   idempotency_key: nil, extra_headers: {})
+      @config = Config.new(
+        api_key: api_key,
+        base_url: base_url,
+        api_version: api_version,
+        timeout: timeout,
+        idempotency_key: idempotency_key,
+        extra_headers: extra_headers
+      )
+      @http = Http.new(@config)
+
+      @events = Resources::Events.new(@http)
+      @documents = Resources::Documents.new(@http)
+      @attestations = Resources::Attestations.new(@http)
+      @traces = Resources::Traces.new(@http)
+      @audit = Resources::Audit.new(@http)
+    end
+
+    # The resolved base URL in use.
+    # @return [String]
+    def base_url
+      @config.base_url
+    end
+
+    # Probe a cheap authenticated endpoint (GET /v1/events?limit=1) to
+    # confirm the API key works. NEVER raises.
+    #
+    # @return [Hash] { "valid" =>, "reason" =>, "base_url" => }
+    def validate
+      base = @config.base_url
+      begin
+        @events.list(limit: 1)
+        { "valid" => true, "reason" => nil, "base_url" => base }
+      rescue AuthenticationError
+        { "valid" => false,
+          "reason" => "Authentication failed — check INVOANCE_API_KEY",
+          "base_url" => base }
+      rescue ForbiddenError
+        { "valid" => true,
+          "reason" => "API key authenticated but lacks permission to list events",
+          "base_url" => base }
+      rescue QuotaExceededError
+        { "valid" => true,
+          "reason" => "API key authenticated but currently rate limited",
+          "base_url" => base }
+      rescue NetworkError, TimeoutError => e
+        { "valid" => false, "reason" => "Server unreachable: #{e.message}", "base_url" => base }
+      rescue Error => e
+        { "valid" => false, "reason" => e.message, "base_url" => base }
+      end
+    end
+  end
+end

data/lib/invoance/config.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Invoance
+  # Resolved, immutable SDK configuration.
+  #
+  # All fields are optional at the client boundary — when omitted the SDK
+  # reads from environment variables:
+  #
+  #   * INVOANCE_API_KEY  — API key (required)
+  #   * INVOANCE_BASE_URL — API host (defaults to https://api.invoance.com)
+  class Config
+    DEFAULT_BASE_URL = "https://api.invoance.com"
+    DEFAULT_TIMEOUT = 30
+    ENV_API_KEY = "INVOANCE_API_KEY"
+    ENV_BASE_URL = "INVOANCE_BASE_URL"
+
+    attr_reader :api_key, :base_url, :api_version, :timeout, :idempotency_key, :extra_headers
+
+    # @param api_key [String, nil]
+    # @param base_url [String, nil]
+    # @param api_version [String]
+    # @param timeout [Numeric] request timeout in seconds
+    # @param idempotency_key [String, nil] default idempotency key for mutating requests
+    # @param extra_headers [Hash] merged into every request
+    def initialize(api_key: nil, base_url: nil, api_version: "v1", timeout: DEFAULT_TIMEOUT,
+                   idempotency_key: nil, extra_headers: {})
+      resolved_key = api_key || ENV[ENV_API_KEY] || ""
+      if resolved_key.empty?
+        raise ArgumentError,
+              "api_key is required. Pass it explicitly or set the #{ENV_API_KEY} environment variable."
+      end
+
+      @api_key = resolved_key
+      @base_url = (base_url || ENV[ENV_BASE_URL] || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @api_version = (api_version || "v1").gsub(%r{\A/+|/+\z}, "")
+      @timeout = timeout || DEFAULT_TIMEOUT
+      @idempotency_key = idempotency_key
+      @extra_headers = extra_headers || {}
+    end
+  end
+end