catalisa-biometrics 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cfbf89065beb0aa0cb605efab699bab5458db396c1e356df40195b8d52aed522
+  data.tar.gz: 23acfaded0c4209a537b34f31d2e4d85ce4d88d3d780ac7d193aeda44861c7a7
+SHA512:
+  metadata.gz: aa549767800b3f096b122c74f6528d0dcaaa250d8277ef16ef0f3ddb77e46355ce3197c8d9c89b837bf6e23d4c2e564b1e2bc4af2f27f23db97dfb9ee42ff5b7
+  data.tar.gz: b4029c5653c1104c4d02385841c2464d26830c533a93f3179c4e3dcd0e9624984ad58a464edecda4a193bea6579614255eaf6bad691e2e44c998303679d7a3f6

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Catalisa
+
+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,149 @@
+# catalisa-biometrics
+
+Ruby SDK for **Catalisa Biometrics** — liveness and face-match sessions, signed evidence and webhook verification.
+
+- Standard library only: `net/http`, `openssl`, `json`. Ruby **3.0+**
+- One typed error carrying the API's own code
+- Offline verification of the Ed25519 evidence signature
+
+```bash
+gem install catalisa-biometrics
+```
+
+## How the flow works
+
+1. **Your server** creates a session and receives `handoff.captureUrl`.
+2. The person opens that URL (browser tab, iframe or WebView) and does the challenge.
+3. The decision arrives **on your server** through the `biometrics.session.completed` webhook, or through `#session`.
+
+The capture page never reveals the result to the person in front of the camera — on purpose, so it cannot be used as a fraud oracle. Never decide anything from front-end events.
+
+## Quick start
+
+```ruby
+require "catalisa/biometrics"
+
+client = Catalisa::Biometrics::Client.new(api_key: ENV.fetch("CATALISA_API_KEY"))
+
+session = client.create_session(
+  flow: Catalisa::Biometrics::Flows::LIVENESS_ONLY,
+  purpose: "abertura de conta",
+  metadata: { orderId: "123" },
+)
+# send the person to session.dig("handoff", "captureUrl")
+
+envelope = client.session(session["sessionId"])
+# proceed when envelope["status"] == "APPROVED"
+```
+
+## API
+
+| Method | What it does |
+|---|---|
+| `create_session` | Opens a session; the envelope comes with `handoff` |
+| `session` | Reads the session, with decision, checks and evidence |
+| `sessions` | Lists sessions, newest first, with filters and pagination |
+| `cancel_session` | Closes a session that has not settled; the allowance slot comes back |
+| `evidence` | Signed evidence plus short-lived download links |
+| `verify_evidence_on_server` | Asks the API to check the signature |
+| `evidence_keys` | Published signing keys, retired ones included |
+| `Evidence.verify` | Checks the signature **offline**, without calling Catalisa |
+| `submit_capture` | Uploads a capture recorded by your own app |
+| `WebhookVerifier#verify` | Verifies a delivery and returns the parsed event |
+
+## Errors
+
+Every failure raises `Catalisa::Biometrics::Error` with the API's own code:
+
+```ruby
+begin
+  session = client.create_session(flow: "LIVENESS_ONLY", purpose: "kyc")
+rescue Catalisa::Biometrics::Error => e
+  if e.quota_exceeded?
+    # the customer's monthly allowance is gone (402); e.details has the numbers
+  elsif e.subaccount_suspended?
+    # suspended: nothing opens until it is reactivated
+  elsif e.transient?
+    # rate limit, server fault or network: worth trying again
+  end
+  warn "#{e.code}: #{e.message} (request #{e.request_id})"
+end
+```
+
+## Retries
+
+- **429** is retried for every method, honoring `Retry-After`: the rate limiter refuses before anything runs.
+- **5xx and network failures** are retried only for reads.
+- **Session creation is never retried** on those: the server does not deduplicate by `Idempotency-Key` yet, and a retry could open two sessions (and spend the allowance twice).
+
+## Webhooks
+
+The delivery is signed with the subscription's **private** key; you verify with the public one. Verify the **raw** bytes — parsing and re-serializing the JSON changes them and the signature will not match.
+
+```ruby
+verifier = Catalisa::Biometrics::WebhookVerifier.new(public_keys_by_key_id)
+
+post "/webhooks/biometrics" do
+  raw = request.body.read
+  begin
+    event = verifier.verify(request.env, raw)
+  rescue Catalisa::Biometrics::WebhookVerificationError
+    halt 400
+  end
+  # event["id"] is stable: use it for idempotency, a delivery can repeat
+  status 200 # answer fast; do the work afterwards
+end
+```
+
+It reads headers in whatever shape your stack hands them over, Rack's `HTTP_X_WEBHOOK_ID` included. The engine does not refuse old deliveries — the receiver does, with a five-minute tolerance by default.
+
+## Signed evidence
+
+```ruby
+keys = client.evidence_keys
+evidence = client.evidence(session_id)
+out = Catalisa::Biometrics::Evidence.verify(session_id, envelope["attempt"], evidence["bundleHash"], evidence["signature"], keys)
+# out[:valid] says whether this is the bundle Catalisa signed
+```
+
+The message is `sessionId|attempt|bundleHash|signedAt`, signed with Ed25519. Retired keys stay published, so evidence signed years ago still verifies.
+
+## Test environment
+
+An API key belongs to one world and says so on every session it opens:
+
+| | `test` (sandbox) | `live` |
+|---|---|---|
+| Engine | Simulated, deterministic | The real one configured for the account |
+| Result | Decided by the CPF ending in `subject_ref` | Decided by the engine |
+| Allowance | Not spent | Spent |
+| Billing | Never billed | Billed |
+| Visibility | A test key only reads test sessions; a live key only reads live ones | |
+
+A test key needs no engine configured, so you can integrate on day one. The envelope and the `session.completed` payload carry `environment`.
+
+Endings that drive the sandbox result: `…-25` (or any other) approves, `…-11` comes back inconclusive for human review, `…-55` asks for a second attempt and then approves, `…-66` fails as an engine error, `…-00`, `…-33` and `…-44` reject by face match, liveness and continuity.
+
+## Subaccounts
+
+With an organization key, pass `subaccount_id:` to act on behalf of a subaccount; with a subaccount key the scope is already bound. Envelopes and webhook payloads carry `subaccountId` (`nil` for organization sessions).
+
+## Custom capture
+
+`submit_capture` uploads a video your own app recorded, authenticating with the session's `captureToken` — the account key never leaves your server. Only `video/webm` and `video/mp4` are accepted, up to 16 MiB and 24 seconds.
+
+Prefer the hosted page when you can: it already runs the quality checks that keep a useless recording from spending an attempt.
+
+## Development
+
+```bash
+ruby -Ilib -Itest -e 'Dir.glob("test/*_test.rb").each { |f| require File.expand_path(f) }'
+```
+
+The tests share `vectors/vectors.json` with the Node, Python, Go, PHP and .NET SDKs — the same signatures, produced by the building block's own code.
+
+Releases go out through GitHub Actions with RubyGems trusted publishing: no API key is stored anywhere.
+
+## License
+
+MIT

data/lib/catalisa/biometrics/client.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module Catalisa
+  module Biometrics
+    DEFAULT_BASE_URL = "https://api.biometrics.catalisa.app/v1"
+
+    # Sandbox or production. A key belongs to one; a session keeps the one it was
+    # born in.
+    module Environments
+      TEST = "test"
+      LIVE = "live"
+    end
+
+    module Flows
+      ONBOARDING = "ONBOARDING"
+      AUTHENTICATION = "AUTHENTICATION"
+      ENROLLMENT = "ENROLLMENT"
+      LIVENESS_ONLY = "LIVENESS_ONLY"
+      DEDUP = "DEDUP"
+    end
+
+    module Statuses
+      SESSION_OPEN = "SESSION_OPEN"
+      PROCESSING = "PROCESSING"
+      APPROVED = "APPROVED"
+      REJECTED = "REJECTED"
+      INCONCLUSIVE = "INCONCLUSIVE"
+      RETRY_ALLOWED = "RETRY_ALLOWED"
+      EXPIRED = "EXPIRED"
+      CANCELLED = "CANCELLED"
+      ERROR = "ERROR"
+
+      TERMINAL = [APPROVED, REJECTED, INCONCLUSIVE, EXPIRED, CANCELLED].freeze
+
+      # The session has settled: nothing will change after this.
+      def self.terminal?(status) = TERMINAL.include?(status)
+    end
+
+    # Catalisa Biometrics client.
+    #
+    # The flow never trusts the browser:
+    #
+    #   1. your server creates a session and gets handoff.captureUrl;
+    #   2. the person opens that URL (tab, iframe or WebView) and does the challenge;
+    #   3. the decision reaches your server through the webhook, or through #session.
+    #
+    # The capture page never shows the result to the person in front of the
+    # camera, on purpose: it would be a fraud oracle. Never decide anything from
+    # front-end events.
+    class Client
+      # @param api_key [String] key from the console; a test key runs the sandbox
+      # @param access_token [String, nil] an IAM JWT instead of an API key
+      # @param subaccount_id [String, nil] act on behalf of a subaccount (organization key only)
+      # @param timeout [Numeric] seconds per attempt
+      # @param max_retries [Integer] reads and 429 only
+      # @param transport [#call, nil] ->(request) { { status:, headers:, body: } }, for tests
+      def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, access_token: nil, subaccount_id: nil,
+                     timeout: 30, max_retries: 2, transport: nil)
+        if (api_key.nil? || api_key.empty?) && (access_token.nil? || access_token.empty?)
+          raise ArgumentError, "Catalisa Biometrics: an API key (or an access token) is required"
+        end
+
+        @api_key = api_key
+        @access_token = access_token
+        @base_url = base_url.chomp("/")
+        @subaccount_id = subaccount_id
+        @timeout = timeout
+        @max_retries = max_retries
+        @transport = transport
+      end
+
+      # Opens a session. The answer carries handoff.captureUrl, where the person goes.
+      #
+      # Never retried on a 5xx or a network failure: the server does not
+      # deduplicate by Idempotency-Key yet, and a retry could open two sessions
+      # (and spend the allowance twice).
+      def create_session(flow:, purpose:, idempotency_key: nil, **fields)
+        headers = idempotency_key ? { "Idempotency-Key" => idempotency_key } : {}
+        body = { flow: flow, purpose: purpose }.merge(fields)
+
+        request(:post, "/sessions", body: body, headers: headers).fetch("data", {})
+      end
+
+      # Reads a session. One from another subaccount — or from the other
+      # environment — answers 404, on purpose: existence is not confirmed.
+      def session(session_id)
+        request(:get, "/sessions/#{escape(session_id)}", idempotent: true).fetch("data", {})
+      end
+
+      # Lists sessions, newest first.
+      def sessions(page: nil, page_size: nil, **filters)
+        query = {}
+        query["page[number]"] = page if page
+        query["page[size]"] = page_size if page_size
+        %i[status flow customer_id subject_cpf from to subaccount_id environment].each do |key|
+          value = filters[key]
+          next if value.nil? || value.to_s.empty?
+
+          query[camel(key)] = value
+        end
+
+        request(:get, "/sessions", query: query, idempotent: true)
+      end
+
+      # Closes a session that has not settled. The allowance slot comes back.
+      def cancel_session(session_id)
+        request(:post, "/sessions/#{escape(session_id)}/cancel").fetch("data", {})
+      end
+
+      # Signed evidence plus short-lived download links for the artifacts.
+      def evidence(session_id)
+        request(:get, "/sessions/#{escape(session_id)}/evidence", idempotent: true).fetch("data", {})
+      end
+
+      # Asks the API to check the evidence signature. Handy, but it trusts the
+      # same party that signed it: for an audit, verify offline with
+      # Catalisa::Biometrics::Evidence.verify.
+      def verify_evidence_on_server(session_id)
+        request(:get, "/sessions/#{escape(session_id)}/evidence/verify", idempotent: true).fetch("data", {})
+      end
+
+      # Published signing keys, retired ones included, so old evidence still verifies.
+      def evidence_keys
+        request(:get, "/evidence-keys", idempotent: true).fetch("data", [])
+      end
+
+      # Uploads a capture your own app recorded, authenticating with the session's
+      # capture token — the account key never leaves your server. Only video/webm
+      # and video/mp4 are accepted, up to 16 MiB and 24 seconds.
+      #
+      # Prefer the hosted page when you can: it already runs the quality checks
+      # that keep a useless recording from spending an attempt.
+      def submit_capture(session_id, capture_token, video:, video_mime: "video/webm",
+                         video_filename: "challenge.webm", telemetry: nil, channel: nil, captured_at: nil)
+        raise Error.new(status: 0, code: "UNAUTHORIZED", message: "a capture token is required") if capture_token.to_s.empty?
+        raise Error.new(status: 0, code: "VALIDATION", message: "the video is empty") if video.to_s.empty?
+
+        boundary = "----catalisa#{SecureRandom.hex(8)}"
+        parts = +"--#{boundary}\r\n"
+        parts << "Content-Disposition: form-data; name=\"video\"; filename=\"#{video_filename}\"\r\n"
+        parts << "Content-Type: #{video_mime}\r\n\r\n"
+        parts << video.dup.force_encoding(Encoding::BINARY)
+        parts << "\r\n"
+        { "telemetry" => telemetry && JSON.generate(telemetry), "channel" => channel, "capturedAt" => captured_at }
+          .each do |name, value|
+            next if value.nil?
+
+            parts << "--#{boundary}\r\nContent-Disposition: form-data; name=\"#{name}\"\r\n\r\n#{value}\r\n"
+          end
+        parts << "--#{boundary}--\r\n"
+
+        answer = send_request(
+          method: :post,
+          url: "#{@base_url}/sessions/#{escape(session_id)}/captures",
+          # The capture token authenticates on its own; the API key is not sent.
+          headers: {
+            "Accept" => "application/json",
+            "User-Agent" => user_agent,
+            "Authorization" => "Bearer #{capture_token}",
+            "Content-Type" => "multipart/form-data; boundary=#{boundary}",
+          },
+          body: parts,
+        )
+
+        decode(answer).fetch("data", {})
+      end
+
+      private
+
+      def user_agent = "catalisa-biometrics-ruby/#{VERSION}"
+
+      def escape(value) = URI.encode_www_form_component(value.to_s)
+
+      def camel(key)
+        head, *rest = key.to_s.split("_")
+        ([head] + rest.map(&:capitalize)).join
+      end
+
+      def request(method, path, query: {}, body: nil, headers: {}, idempotent: false)
+        url = "#{@base_url}#{path}"
+        url += "?#{URI.encode_www_form(query)}" unless query.empty?
+
+        request_headers = { "Accept" => "application/json", "User-Agent" => user_agent }.merge(headers)
+        if @access_token && !@access_token.empty?
+          request_headers["Authorization"] = "Bearer #{@access_token}"
+        else
+          request_headers["X-API-Key"] = @api_key
+        end
+        request_headers["X-Subaccount-Id"] = @subaccount_id if @subaccount_id && !@subaccount_id.empty?
+        payload = body && JSON.generate(body)
+        request_headers["Content-Type"] = "application/json" if payload
+
+        attempt = 0
+        begin
+          decode(send_request(method: method, url: url, headers: request_headers, body: payload))
+        rescue Error => e
+          # A 429 is always safe to retry: the rate limiter refuses before the
+          # handler runs, so nothing was done.
+          retryable = e.status == 429 || (idempotent && (e.status >= 500 || e.status.zero?))
+          raise unless retryable && attempt < @max_retries
+
+          sleep(backoff(attempt, e))
+          attempt += 1
+          retry
+        end
+      end
+
+      def backoff(attempt, error)
+        return [error.retry_after, 30].min if error.retry_after&.positive?
+
+        base = 0.5 * (2**attempt)
+        [base + rand * base * 0.25, 8.0].min
+      end
+
+      def decode(answer)
+        status = answer[:status]
+        raise Error.from_response(status, answer[:body], answer[:headers]) if status >= 400
+        return {} if answer[:body].to_s.empty?
+
+        JSON.parse(answer[:body])
+      rescue JSON::ParserError => e
+        raise Error.new(status: status, code: "INTERNAL", message: "unexpected answer: #{e.message}")
+      end
+
+      def send_request(method:, url:, headers:, body: nil)
+        return @transport.call(method: method, url: url, headers: headers, body: body) if @transport
+
+        uri = URI(url)
+        klass = { get: Net::HTTP::Get, post: Net::HTTP::Post, patch: Net::HTTP::Patch, delete: Net::HTTP::Delete }.fetch(method)
+        request = klass.new(uri, headers)
+        request.body = body if body
+
+        response = Net::HTTP.start(uri.host, uri.port,
+                                   use_ssl: uri.scheme == "https",
+                                   open_timeout: @timeout,
+                                   read_timeout: @timeout) { |http| http.request(request) }
+
+        { status: response.code.to_i, headers: response.each_header.to_h, body: response.body }
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise Error.new(status: 0, code: "TIMEOUT", message: "no answer within #{@timeout}s")
+      rescue SystemCallError, SocketError, OpenSSL::SSL::SSLError => e
+        raise Error.new(status: 0, code: "CONNECTION", message: "connection failed: #{e.message}")
+      end
+    end
+  end
+end

data/lib/catalisa/biometrics/errors.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Catalisa
+  module Biometrics
+    # Every failed call raises this. The API answers
+    # `{"error":"<code>","message":"...","details":{...}}`, so #code is the API's
+    # own word for what happened — branch on it, never on the message.
+    class Error < StandardError
+      # HTTP status, or 0 when the request never reached the API.
+      attr_reader :status
+
+      # API error code (VALIDATION, NOT_FOUND, QUOTA_EXCEEDED…), or
+      # TIMEOUT/CONNECTION when the request did not complete.
+      attr_reader :code
+
+      # Whatever the API attached: the offending fields, the quota numbers.
+      attr_reader :details
+
+      # `x-request-id`, when the API sends one — quote it in a support ticket.
+      attr_reader :request_id
+
+      # `Retry-After` in seconds, on a 429.
+      attr_reader :retry_after
+
+      def initialize(status:, code:, message:, details: {}, request_id: nil, retry_after: nil)
+        super(message)
+        @status = status
+        @code = code
+        @details = details
+        @request_id = request_id
+        @retry_after = retry_after
+      end
+
+      # The customer's monthly allowance is gone. A test key never gets here.
+      def quota_exceeded? = code == "QUOTA_EXCEEDED"
+
+      # The subaccount is suspended: nothing opens until it is reactivated.
+      def subaccount_suspended? = code == "SUBACCOUNT_SUSPENDED"
+
+      # Worth trying again by itself: rate limit, server fault or network.
+      def transient? = status == 429 || status >= 500 || status.zero?
+
+      # Builds the error from what the API answered. A body that is not the
+      # expected envelope — an HTML page from a proxy, say — still yields a usable
+      # code, taken from the status.
+      def self.from_response(status, body, headers)
+        parsed = begin
+          body.to_s.empty? ? nil : JSON.parse(body)
+        rescue JSON::ParserError
+          nil
+        end
+
+        code = code_for(status)
+        message = ""
+        details = {}
+
+        if parsed.is_a?(Hash)
+          code = parsed["error"] if parsed["error"].is_a?(String) && !parsed["error"].empty?
+          message = parsed["message"] if parsed["message"].is_a?(String)
+          if parsed["details"].is_a?(Hash)
+            details = parsed["details"]
+            # The machine-readable code lives inside details on the cases that
+            # carry numbers with them (quota, suspension).
+            code = details["code"] if details["code"].is_a?(String) && !details["code"].empty?
+          end
+        end
+        message = message_for(status) if message.empty?
+
+        new(
+          status: status,
+          code: code,
+          message: message,
+          details: details,
+          request_id: headers["x-request-id"],
+          retry_after: headers["retry-after"]&.to_i,
+        )
+      end
+
+      def self.code_for(status)
+        case status
+        when 400, 415 then "VALIDATION"
+        when 401 then "UNAUTHORIZED"
+        when 402 then "QUOTA_EXCEEDED"
+        when 403 then "FORBIDDEN"
+        when 404 then "NOT_FOUND"
+        when 409 then "CONFLICT"
+        when 413 then "PAYLOAD_TOO_LARGE"
+        when 429 then "RATE_LIMITED"
+        when 500.. then "INTERNAL"
+        else "ERROR"
+        end
+      end
+      private_class_method :code_for
+
+      def self.message_for(status)
+        case status
+        when 401 then "API key missing, wrong or revoked"
+        when 402 then "monthly allowance exhausted"
+        when 403 then "this key may not do that"
+        when 404 then "not found in this scope"
+        when 429 then "too many requests"
+        when 500.. then "the API failed"
+        else "request failed with status #{status}"
+        end
+      end
+      private_class_method :message_for
+    end
+
+    # A webhook delivery that failed verification. Answer 400 and do not process
+    # the body.
+    class WebhookVerificationError < StandardError
+      # Which check failed: :missing_headers, :invalid_signature,
+      # :timestamp_out_of_tolerance, :unknown_key_id, :unsupported_signature_version.
+      attr_reader :failure
+
+      def initialize(failure, message)
+        super(message)
+        @failure = failure
+      end
+    end
+  end
+end

data/lib/catalisa/biometrics/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Catalisa
+  module Biometrics
+    VERSION = "0.1.0"
+  end
+end

data/lib/catalisa/biometrics/webhooks.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "time"
+
+module Catalisa
+  module Biometrics
+    # Verification of Catalisa Webhooks Engine deliveries:
+    #
+    #   message   = x-webhook-id + "\n" + x-webhook-timestamp + "\n" + raw body
+    #   signature = RSA-SHA256 (PKCS#1 v1.5), base64, in x-webhook-signature as "v1=<base64>"
+    #   key       = the subscription's PUBLIC key, chosen by x-webhook-key-id
+    #
+    # The signature is asymmetric: there is no shared secret to leak. The engine
+    # does not refuse old deliveries — the receiver enforces the time tolerance,
+    # or a captured delivery could be replayed forever.
+    class WebhookVerifier
+      MESSAGES = {
+        missing_headers: "missing x-webhook-id, x-webhook-timestamp, x-webhook-key-id or x-webhook-signature",
+        timestamp_invalid: "x-webhook-timestamp is not an ISO 8601 date",
+        timestamp_out_of_tolerance: "delivery is outside the time tolerance (possible replay)",
+        unknown_key_id: "no public key for this x-webhook-key-id",
+        unsupported_signature_version: "unsupported signature version (expected v1=)",
+        invalid_signature: "invalid signature",
+      }.freeze
+
+      # @param public_keys [Hash{String=>String}] keyId => PEM. Keep a retired key
+      #   here while deliveries signed with it may still arrive.
+      # @param tolerance [Integer] seconds; 0 disables the check (not recommended)
+      # @param now [Proc] reference clock, for tests
+      def initialize(public_keys, tolerance: 300, now: -> { Time.now })
+        @public_keys = public_keys
+        @tolerance = tolerance
+        @now = now
+      end
+
+      # Verifies a delivery and returns the parsed event.
+      #
+      # Pass the RAW body — the bytes as they arrived. Decoding and re-encoding
+      # the JSON changes them, and the signature will not match.
+      #
+      # @param headers [Hash] however your stack hands them over: Rack's
+      #   HTTP_X_WEBHOOK_ID, a framework's x-webhook-id, arrays included
+      def verify(headers, raw_body)
+        id = header(headers, "x-webhook-id")
+        timestamp = header(headers, "x-webhook-timestamp")
+        key_id = header(headers, "x-webhook-key-id")
+        signature = header(headers, "x-webhook-signature")
+
+        fail_with(:missing_headers) if [id, timestamp, key_id, signature].any? { |v| v.nil? || v.empty? }
+
+        sent_at = begin
+          Time.iso8601(timestamp)
+        rescue ArgumentError
+          fail_with(:timestamp_invalid)
+        end
+        fail_with(:timestamp_out_of_tolerance) if @tolerance.positive? && (@now.call - sent_at).abs > @tolerance
+        fail_with(:unsupported_signature_version) unless signature.start_with?("v1=")
+
+        pem = @public_keys[key_id]
+        fail_with(:unknown_key_id) if pem.nil?
+
+        raw = Base64.strict_decode64(signature[3..]) rescue fail_with(:invalid_signature)
+        key = begin
+          OpenSSL::PKey::RSA.new(pem)
+        rescue OpenSSL::PKey::RSAError
+          fail_with(:unknown_key_id)
+        end
+
+        message = "#{id}\n#{timestamp}\n#{raw_body}"
+        fail_with(:invalid_signature) unless key.verify(OpenSSL::Digest.new("SHA256"), raw, message)
+
+        begin
+          JSON.parse(raw_body)
+        rescue JSON::ParserError => e
+          fail_with(:invalid_signature, "the signed body is not valid JSON: #{e.message}")
+        end
+      end
+
+      private
+
+      def header(headers, name)
+        headers.each do |key, value|
+          normalized = key.to_s.downcase.tr("_", "-")
+          normalized = normalized.delete_prefix("http-")
+          next unless normalized == name
+
+          found = value.is_a?(Array) ? value.first : value
+          return found.nil? || found.to_s.empty? ? nil : found.to_s
+        end
+        nil
+      end
+
+      def fail_with(failure, message = nil)
+        raise WebhookVerificationError.new(failure, message || MESSAGES.fetch(failure))
+      end
+    end
+
+    # OFFLINE verification of the signed evidence, without calling Catalisa:
+    #
+    #   message   = "{sessionId}|{attempt}|{bundleHash}|{signedAt}"
+    #   signature = Ed25519 (RFC 8032), base64
+    #   key       = GET /evidence-keys, by the signature's keyId
+    #
+    # This is what lets a third party — an auditor, a court — confirm years later
+    # that the bundle is the one Catalisa signed.
+    module Evidence
+      module_function
+
+      # The exact string that was signed.
+      def message(session_id, attempt, bundle_hash, signed_at)
+        "#{session_id}|#{attempt}|#{bundle_hash}|#{signed_at}"
+      end
+
+      # @return [Hash] valid:, key_id:, unknown_key:, retired_at:
+      def verify(session_id, attempt, bundle_hash, signature, keys)
+        key_id = signature["keyId"] || signature[:keyId]
+        key = keys.find { |k| (k["keyId"] || k[:keyId]) == key_id }
+        return { valid: false, key_id: key_id, unknown_key: true, retired_at: nil } if key.nil?
+
+        retired_at = key["retiredAt"] || key[:retiredAt]
+        out = { valid: false, key_id: key_id, unknown_key: false, retired_at: retired_at }
+        return out unless (signature["alg"] || signature[:alg]) == "Ed25519"
+
+        raw = Base64.strict_decode64((signature["value"] || signature[:value]).to_s) rescue (return out)
+        public_key = begin
+          OpenSSL::PKey.read(key["publicKeyPem"] || key[:publicKeyPem])
+        rescue OpenSSL::PKey::PKeyError
+          return out
+        end
+        # Ed25519 signs the message itself, with no separate digest step: hence the
+        # nil digest. Not verify_raw — that one answers false for Ed25519 instead
+        # of raising, which is a quiet way to reject every valid receipt.
+        signed = message(session_id, attempt, bundle_hash, signature["signedAt"] || signature[:signedAt])
+        out[:valid] = public_key.verify(nil, raw, signed)
+
+        out
+      rescue OpenSSL::PKey::PKeyError
+        out
+      end
+    end
+  end
+end

data/lib/catalisa/biometrics.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "biometrics/version"
+require_relative "biometrics/errors"
+require_relative "biometrics/client"
+require_relative "biometrics/webhooks"
+
+# Catalisa Biometrics: liveness and face-match sessions, signed evidence and
+# webhook verification. Standard library only.
+module Catalisa
+  module Biometrics
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: catalisa-biometrics
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Catalisa
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-20 00:00:00.000000000 Z
+dependencies: []
+description: 'Ruby client for Catalisa Biometrics: opens verification sessions, reads
+  the decision with its score and threshold, verifies the signed receipt offline and
+  the webhook signature. Standard library only.'
+email:
+- contato@catalisa.app
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/catalisa/biometrics.rb
+- lib/catalisa/biometrics/client.rb
+- lib/catalisa/biometrics/errors.rb
+- lib/catalisa/biometrics/version.rb
+- lib/catalisa/biometrics/webhooks.rb
+homepage: https://docs.catalisa.app
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/catalisaio/catalisa-biometrics-sdk/tree/main/packages/ruby
+  bug_tracker_uri: https://github.com/catalisaio/catalisa-biometrics-sdk/issues
+  documentation_uri: https://docs.catalisa.app/blocks/biometrics/
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Catalisa Biometrics SDK — liveness and face-match sessions, signed evidence
+  and webhook verification
+test_files: []