dinie-sdk-sandbox 1.1.0

data/lib/dinie/runtime/token_manager.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require "base64"
+require "faraday"
+require "faraday/net_http_persistent"
+
+module Dinie
+  module Internal
+    # `TokenManager` — the OAuth2 *client_credentials* token cache (architecture §10, RB-T,
+    # `runtime-patterns.md` §4), porting `sdk-js` `src/runtime/token-manager.ts`. It acquires and
+    # transparently refreshes the Bearer token every request rides on, speaking RFC 6749:
+    #
+    #   POST {base_url}/auth/token
+    #   Authorization: Basic base64("{client_id}:{client_secret}")
+    #   Content-Type:  application/x-www-form-urlencoded
+    #   body:          grant_type=client_credentials
+    #   → 200 { access_token, token_type: "bearer", expires_in }
+    #
+    # Three behaviours make it one of the risky-core modules:
+    #
+    #   1. **Proactive refresh** — the cached token is treated as stale {REFRESH_MARGIN_SECONDS}
+    #      (300s) BEFORE its real expiry, so a live request never races the boundary.
+    #   2. **Concurrency lock** — a `Mutex` + `ConditionVariable` (+ an `@refreshing` flag)
+    #      serialize refreshes: N simultaneous `#access_token` callers trigger exactly ONE token
+    #      POST. The claim ("I will refresh") is made UNDER the mutex, so it is impossible for two
+    #      threads to both start a refresh; the losers park on the condition variable and, after a
+    #      **double-check** on wake, return the freshly-cached token. The POST itself runs OUTSIDE
+    #      the lock so a slow handshake never blocks the validity check.
+    #   3. **401 invalidation** — `#invalidate!` drops the cached token. The 401 one-shot re-auth
+    #      itself is orchestrated by {HttpClient} (story 003); this module only exposes the seam
+    #      (`#access_token` / `#invalidate!`) and never loops on requests itself.
+    #
+    # ── DI seam (architecture §10, RB15) ──
+    # This is the REAL token source {HttpClient} expects via its injected `token_manager:`
+    # (`auth_headers` calls `#access_token`; the 401 one-shot calls `#invalidate!`). {Dinie::Client}
+    # builds ONE `Faraday::Connection` and injects it into BOTH the HttpClient and this manager, so
+    # the token POST rides the SAME connection pool as every other request — and, once story 005
+    # mounts the logging middleware on that shared connection, the `Authorization: Basic` header
+    # (which carries the client secret) is redacted there. URLs are absolute, so the connection's
+    # `url_prefix` is irrelevant (mirrors {HttpClient}). A `connection:` is optional: standalone use
+    # (and most specs) lets the manager build its own.
+    #
+    # ── runtime ↔ generated boundary ──
+    # Lives in `runtime/`, imports only `errors` (for {Dinie::OAuthError}) + Faraday, and is NOT
+    # part of the public barrel: {Dinie::Client}/{HttpClient} construct it internally.
+    #
+    # The ClassLength cop is disabled below: the token lifecycle (validity check → claim → POST →
+    # parse → cache → wake) is one cohesive concurrency unit; splitting it would scatter the
+    # invariant (the refresh claim and the cache mutation must share one mutex).
+    class TokenManager # rubocop:disable Metrics/ClassLength
+      # Bare token-endpoint path, appended to the configured base URL (which already carries the
+      # `/api/v3` version prefix, so the full URL is `…/api/v3/auth/token`).
+      TOKEN_PATH = "/auth/token"
+      # Session-exchange endpoint path — step 2 of the two-step session-mode flow. POSTed with
+      # the cc-bearer in `Authorization: Bearer …` and `{ code }` JSON body.
+      SESSION_EXCHANGE_PATH = "/biometrics/session-exchange"
+      # Refresh the token this many SECONDS before its stated expiry (300s, `runtime-patterns.md`
+      # §4). The margin absorbs clock skew and in-flight latency so a live request never carries a
+      # token that expires mid-flight.
+      REFRESH_MARGIN_SECONDS = 300
+      # The fixed `application/x-www-form-urlencoded` body of the client_credentials grant.
+      GRANT_BODY = "grant_type=client_credentials"
+      # `Content-Type` of the token request.
+      FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
+      # OAuthError messages for a malformed token payload (kept as constants so the guard clauses
+      # stay on one line and read cleanly).
+      MISSING_ACCESS_TOKEN = 'OAuth2 token response was missing a valid "access_token".'
+      # {Dinie::OAuthError} message for a token payload missing a valid `expires_in`.
+      MISSING_EXPIRES_IN = 'OAuth2 token response was missing a valid "expires_in".'
+
+      # @param client_id [String] OAuth2 client id (the Basic-auth username)
+      # @param client_secret [String] OAuth2 client secret (the Basic-auth password)
+      # @param base_url [String, nil] API base URL incl. the version prefix (default
+      #   {HttpClient::DEFAULT_BASE_URL}); the bare {TOKEN_PATH} is appended to it
+      # @param connection [Faraday::Connection, nil] injected shared connection (pool-sharing seam);
+      #   `nil` builds a standalone one. Requests use absolute URLs, so `url_prefix` is irrelevant
+      # @param refresh_margin_seconds [Integer] proactive-refresh margin (default
+      #   {REFRESH_MARGIN_SECONDS}); parameterized for boundary tests
+      # @param adapter [Symbol, nil] Faraday adapter for the standalone connection (default
+      #   `:net_http_persistent`)
+      # @param clock [#call, nil] monotonic-ish "seconds now" source (tests inject a controllable
+      #   one to exercise the margin boundary); defaults to wall-clock seconds
+      # @param code [String, nil] session-mode authorization code (from the biometrics flow).
+      #   When present the manager operates in **session mode**: `#access_token` performs a
+      #   two-step exchange (cc-credentials → {SESSION_EXCHANGE_PATH}) exactly once. After the
+      #   session token expires, {Dinie::SessionTokenExpiredError} is raised — the code is
+      #   single-use and cannot be re-exchanged.
+      def initialize(client_id:, client_secret:, base_url: nil, connection: nil, # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+                     refresh_margin_seconds: REFRESH_MARGIN_SECONDS, adapter: nil, clock: nil, code: nil)
+        @client_id = client_id
+        @client_secret = client_secret
+        @base_url = (base_url || HttpClient::DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+        @refresh_margin_seconds = refresh_margin_seconds
+        @clock = clock || -> { ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) }
+        @connection = connection || build_connection(adapter)
+        @code = code
+        @exchanged = false
+
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @refreshing = false
+        @access_token = nil
+        @expires_at = nil
+      end
+
+      # Return a valid Bearer access token, acquiring or refreshing transparently.
+      #
+      # Fast path: a cached token still inside the margin is returned without a request. Otherwise
+      # the FIRST caller claims the refresh under the mutex and runs the POST outside it; concurrent
+      # callers park on the condition variable and, after a double-check on wake, return the
+      # freshly-cached token. Under N concurrent callers exactly ONE token POST occurs.
+      #
+      # @return [String] a valid OAuth2 access token
+      # @raise [Dinie::OAuthError] the token handshake failed (transport, non-2xx, or malformed body)
+      def access_token
+        @mutex.synchronize do
+          loop do
+            return @access_token if token_valid?
+            break unless @refreshing
+
+            # Another thread is already refreshing — park until it broadcasts, then re-check
+            # (double-check pattern): it may have populated the cache, or its refresh may have failed.
+            @condition.wait(@mutex)
+          end
+          @refreshing = true # claim the refresh (under the mutex — only one thread can win)
+        end
+
+        refresh_and_cache
+      end
+
+      # Drop the cached token so the next {#access_token} re-authenticates. Called by {HttpClient}
+      # on a 401 (the one-shot re-auth is orchestrated there). Takes the mutex so it never races a
+      # concurrent validity check.
+      #
+      # @return [void]
+      def invalidate!
+        @mutex.synchronize do
+          @access_token = nil
+          @expires_at = nil
+        end
+      end
+
+      private
+
+      # True when a token is cached and still outside the refresh margin. Only ever called under
+      # the mutex, so reading `@access_token`/`@expires_at` together is race-free.
+      def token_valid?
+        !@access_token.nil? && now < @expires_at - @refresh_margin_seconds
+      end
+
+      # Run the refresh OUTSIDE the mutex (the POST is I/O — holding the lock would block the
+      # validity check for every other caller). Whatever happens, the `ensure` clears the claim and
+      # wakes the parked threads, so a failed handshake never leaves a permanently-stuck lock: the
+      # next waiter re-checks, finds no token, and retries.
+      def refresh_and_cache # rubocop:disable Metrics/MethodLength
+        access_token, expires_at = fetch_token
+        @mutex.synchronize do
+          @access_token = access_token
+          @expires_at = expires_at
+        end
+        access_token
+      ensure
+        @mutex.synchronize do
+          @refreshing = false
+          @condition.broadcast
+        end
+      end
+
+      # Dispatch to partner mode or session mode. Partner mode (no `code`) performs the standard
+      # client_credentials POST and caches until the margin. Session mode performs the two-step
+      # exchange exactly once; subsequent stale-token paths raise {Dinie::SessionTokenExpiredError}.
+      def fetch_token
+        return fetch_partner_token unless @code
+        raise Dinie::SessionTokenExpiredError if @exchanged
+
+        fetch_session_token
+      end
+
+      # Session mode step: cc-credentials → SESSION_EXCHANGE_PATH. Returns
+      # `[customer_access_token, absolute_expiry_seconds]`. Sets `@exchanged` AFTER the POST
+      # succeeds so T9 (exchange failure) leaves `@exchanged = false` and the caller can see
+      # the typed API error (no phantom expiry on the next call).
+      def fetch_session_token
+        cc_token = fetch_client_credentials_token
+        access_token, expires_in = exchange(cc_token, @code)
+        @exchanged = true
+        [access_token, now + expires_in]
+      end
+
+      # Partner mode: a single client_credentials POST, returns
+      # `[access_token, absolute_expiry_seconds]`. The original `fetch_token` body, extracted
+      # so `fetch_token` stays a clean dispatcher.
+      def fetch_partner_token
+        response = request_token
+        raise Dinie::OAuthError, status_failure(response.status, body_detail(response)) unless success?(response.status)
+
+        access_token, expires_in = parse_token_response(response.body)
+        [access_token, now + expires_in]
+      end
+
+      # Step 1 of the session two-step: obtain a cc-bearer (used as the Authorization header
+      # on the subsequent exchange POST). Returns only the access_token string.
+      def fetch_client_credentials_token
+        response = request_token
+        raise Dinie::OAuthError, status_failure(response.status, body_detail(response)) unless success?(response.status)
+
+        access_token, = parse_token_response(response.body)
+        access_token
+      end
+
+      # Step 2 of the session two-step: POST SESSION_EXCHANGE_PATH with the cc-bearer and
+      # the authorization code. Returns `[customer_access_token, expires_in]`. Non-2xx raises
+      # the typed API error from {Dinie::Internal::Errors.from_response} (e.g. AuthError on 401).
+      def exchange(cc_token, code)
+        response = request_exchange(cc_token, code)
+        unless success?(response.status)
+          raise Dinie::Internal::Errors.from_response(
+            status: response.status, headers: response.headers.to_h, body: response.body
+          )
+        end
+
+        parse_exchange_response(response.body)
+      end
+
+      # One Faraday round-trip to SESSION_EXCHANGE_PATH. Absolute URL. Transport failures
+      # become {Dinie::OAuthError} (no server response to dispatch on).
+      def request_exchange(cc_token, code)
+        @connection.run_request(
+          :post,
+          exchange_url,
+          JSON.generate(code: code),
+          "authorization" => "Bearer #{cc_token}",
+          "content-type" => "application/json",
+          "accept" => "application/json"
+        )
+      rescue Faraday::Error => e
+        raise Dinie::OAuthError, "Session exchange request failed before a response was received: #{e.message}"
+      end
+
+      # Validate + extract the exchange response, returning `[access_token, expires_in]`.
+      # Raises {Dinie::OAuthError} on structural problems (shape, missing fields).
+      def parse_exchange_response(raw_body)
+        parsed = parse_json(raw_body)
+        raise Dinie::OAuthError, "Session exchange response was not a JSON object." unless parsed.is_a?(Hash)
+
+        access_token = parsed[:access_token]
+        expires_in = parsed[:expires_in]
+        raise Dinie::OAuthError, MISSING_ACCESS_TOKEN unless valid_access_token?(access_token)
+        raise Dinie::OAuthError, MISSING_EXPIRES_IN unless valid_expires_in?(expires_in)
+
+        [access_token, expires_in]
+      end
+
+      def exchange_url
+        "#{@base_url}#{SESSION_EXCHANGE_PATH}"
+      end
+
+      # One Faraday round-trip to the token endpoint. Absolute URL ⇒ the connection's `url_prefix`
+      # is irrelevant. A transport failure (DNS, refused, timeout) becomes {Dinie::OAuthError}.
+      def request_token
+        @connection.run_request(:post, token_url, GRANT_BODY, token_request_headers)
+      rescue Faraday::Error => e
+        raise Dinie::OAuthError, "OAuth2 token request failed before a response was received: #{e.message}"
+      end
+
+      # Validate + extract the wire payload, returning `[access_token, expires_in]`. `token_type` is
+      # intentionally ignored: {HttpClient} always sends `Authorization: Bearer …`, so the wire
+      # value is informational. Any shape problem raises {Dinie::OAuthError}.
+      def parse_token_response(raw_body)
+        parsed = parse_json(raw_body)
+        raise Dinie::OAuthError, "OAuth2 token response was not a JSON object." unless parsed.is_a?(Hash)
+
+        access_token = parsed[:access_token]
+        expires_in = parsed[:expires_in]
+        raise Dinie::OAuthError, MISSING_ACCESS_TOKEN unless valid_access_token?(access_token)
+        raise Dinie::OAuthError, MISSING_EXPIRES_IN unless valid_expires_in?(expires_in)
+
+        [access_token, expires_in]
+      end
+
+      def parse_json(raw_body)
+        JSON.parse(raw_body.to_s, symbolize_names: true)
+      rescue JSON::ParserError
+        raise Dinie::OAuthError, "OAuth2 token response body was not valid JSON."
+      end
+
+      def valid_access_token?(value)
+        value.is_a?(String) && !value.empty?
+      end
+
+      def valid_expires_in?(value)
+        value.is_a?(Numeric) && value.positive?
+      end
+
+      def token_request_headers
+        {
+          "authorization" => "Basic #{basic_credentials}",
+          "content-type" => FORM_CONTENT_TYPE,
+          "accept" => "application/json"
+        }
+      end
+
+      # Base64 (RFC 4648) of `client_id:client_secret`, no line breaks (HTTP Basic).
+      def basic_credentials
+        Base64.strict_encode64("#{@client_id}:#{@client_secret}")
+      end
+
+      def token_url
+        "#{@base_url}#{TOKEN_PATH}"
+      end
+
+      def success?(status)
+        (200..299).cover?(status)
+      end
+
+      # Best-effort body text for a non-2xx failure message (never raises).
+      def body_detail(response)
+        response.body.to_s.strip
+      rescue StandardError
+        ""
+      end
+
+      def status_failure(status, detail)
+        suffix = detail.empty? ? "" : ": #{detail}"
+        "OAuth2 token request failed with status #{status}#{suffix}"
+      end
+
+      def now
+        @clock.call
+      end
+
+      # Standalone fallback connection (production injects the shared one from {Dinie::Client}).
+      # No logger seam here: the canonical, logged connection is the Client's shared one.
+      def build_connection(adapter)
+        Faraday.new(url: @base_url) do |faraday|
+          faraday.adapter(adapter || :net_http_persistent)
+        end
+      end
+    end
+  end
+end

data/lib/dinie/runtime/webhooks.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+require_relative "errors"
+
+module Dinie
+  # `Dinie::Webhooks.extract` — webhook verification + per-type deserialization, a module-function
+  # (RB11, architecture §8, §18.2). Implements the Standard Webhooks v1 contract Dinie inherited:
+  #
+  #     signed_payload = "{webhook-id}.{webhook-timestamp}.{body}"
+  #     expected       = base64(HMAC-SHA256(decode_secret(secret), signed_payload))
+  #     header         = "v1,<sig1> v1,<sig2>"   # space-separated, rotation-capable
+  #
+  # `extract` does verification AND deserialization in one call: it reads the three `webhook-*`
+  # headers (case-insensitive, symbol/string), enforces a bidirectional timestamp window (replay
+  # guard), decodes the secret (`whsec_` → base64), HMAC-SHA256s the signed payload, and compares —
+  # in CONSTANT time via {OpenSSL.secure_compare} — against every `v1,<sig>` in the header. Any
+  # match → {Dinie::Events::DESERIALIZERS}`[type]` hydrates the snake-native body into the typed
+  # {Dinie::Events} member; an unknown `type` → {Dinie::UnknownWebhookEventError}; no match →
+  # {Dinie::WebhookSignatureError}. It NEVER returns an unverified event (security by behavior — the
+  # name `extract` returns the event, not a boolean).
+  #
+  # Both `secret` and the signature header accept multiple values, so secret rotation works from
+  # either side. Verification needs no OAuth credentials, hence a module-function (not a client
+  # method). Mirrors `sdk-js` `src/runtime/webhooks.ts` (@ `19c9bca`), in Ruby (`openssl` stdlib;
+  # base64 via `String#unpack1("m")` / `Array#pack("m0")` — no extra dependency).
+  #
+  # ── runtime ↔ generated boundary (controlled inverse import — openapi-SoT, §4) ──
+  # The general rule is "runtime/ never imports generated/". `webhooks.rb` is one of two declared
+  # exceptions (the other is `http.rb → ERROR_REGISTRY`). The webhook event catalog's SoT is
+  # `openapi.yaml` (`webhooks:`), so the typed members AND the {Dinie::Events::DESERIALIZERS} table
+  # live in `generated/events/`. This module references the table at call time; the barrel
+  # (`lib/dinie.rb`) loads `generated/events` before any call. The reference is the forcing-function:
+  # an event not in openapi is not in `generated/events`, not in the table, so `extract` raises
+  # {Dinie::UnknownWebhookEventError} — forcing the contract conversation.
+  #
+  # ── Header normalization (deferred decision §21.5 — RESOLVED: case-insensitive + symbol/string) ──
+  # Standard Webhooks headers are lowercase dashed (`webhook-id`). Inbound frameworks vary in
+  # capitalization, so the lookup is case-insensitive and accepts both String and Symbol keys. The
+  # partner passes a Hash keyed by the `webhook-*` names; framework env normalization (Rack's
+  # `HTTP_WEBHOOK_ID`) is the partner's responsibility (a framework adapter is out of scope, §1):
+  #
+  #   # Rails:   Dinie::Webhooks.extract(headers: request.headers.to_h, body: request.raw_post, secret:)
+  #   # Sinatra: Dinie::Webhooks.extract(headers: { "webhook-id" => request.env["HTTP_WEBHOOK_ID"],
+  #   #            "webhook-timestamp" => request.env["HTTP_WEBHOOK_TIMESTAMP"],
+  #   #            "webhook-signature" => request.env["HTTP_WEBHOOK_SIGNATURE"] }, body: request.body.read, secret:)
+  #   # Rack:    headers = env.select { |k, _| k.start_with?("HTTP_") }
+  #   #            .transform_keys { |k| k.delete_prefix("HTTP_").downcase.tr("_", "-") }
+  module Webhooks
+    # Default replay tolerance, in seconds (5 minutes), applied in both directions.
+    DEFAULT_TOLERANCE_SECONDS = 300
+    # Secrets carrying this prefix are base64-encoded; the remainder is decoded before HMAC.
+    WHSEC_PREFIX = "whsec_"
+    # Only `v1` signature tokens are honored.
+    SIGNATURE_VERSION = "v1"
+
+    module_function
+
+    # Verify a Standard Webhooks v1 payload and return the deserialized, typed event — a
+    # {Dinie::Events} member straight from openapi (`generated/events/`), hydrated per type so the
+    # snake-native surface is honest. It NEVER returns an unverified event.
+    #
+    # @param headers [Hash] inbound HTTP headers (case-insensitive lookup of the `webhook-*` trio)
+    # @param body [String] the RAW request body, exactly as received, BEFORE `JSON.parse`
+    # @param secret [String, Array<String>] signing secret(s); `whsec_`-prefixed → base64. An Array
+    #   tries each secret (rotation)
+    # @param tolerance_seconds [Integer] replay window in seconds, applied in both directions
+    # @return [Dinie::Events::WebhookEventBase] the verified, typed event member
+    # @raise [Dinie::WebhookTimestampError] the timestamp header is missing, malformed, or outside
+    #   the tolerance window (too old OR too far in the future)
+    # @raise [Dinie::WebhookSignatureError] a required header is missing, no usable secret was
+    #   supplied, or no signature in the header matched
+    # @raise [Dinie::UnknownWebhookEventError] the signature verified but the payload's `type` is
+    #   not in the openapi event catalog
+    def extract(headers:, body:, secret:, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS)
+      webhook_id = required_header(headers, "webhook-id", Dinie::WebhookSignatureError)
+      timestamp = required_header(headers, "webhook-timestamp", Dinie::WebhookTimestampError)
+      signature = required_header(headers, "webhook-signature", Dinie::WebhookSignatureError)
+
+      verify_timestamp!(timestamp, tolerance_seconds)
+      verify_signature!(signed_payload(webhook_id, timestamp, body), secret, signature)
+      deserialize_verified_event(body)
+    end
+
+    # @api private
+    # Build the byte-faithful signed payload `"{id}.{timestamp}.{body}"` (binary-concatenated so a
+    # non-UTF-8 body never raises an encoding error).
+    def signed_payload(webhook_id, timestamp, body)
+      "#{webhook_id}.#{timestamp}.".b + body.to_s.b
+    end
+
+    # @api private
+    # Fetch a required header or raise `error_class`. Missing and empty both fail.
+    def required_header(headers, name, error_class)
+      value = lookup_header(headers, name)
+      return value unless value.nil? || value == ""
+
+      raise error_class, "Missing required webhook header: #{name}."
+    end
+
+    # @api private
+    # Case-insensitive, symbol/string single-value header lookup (§21.5). A list value (rare) yields
+    # its first element.
+    def lookup_header(headers, name)
+      value = fetch_header(headers, name)
+      value.is_a?(Array) ? value.first : value
+    end
+
+    # @api private
+    def fetch_header(headers, name)
+      return headers[name] if headers.key?(name)
+      return headers[name.to_sym] if headers.key?(name.to_sym)
+
+      target = name.downcase
+      headers.each { |key, value| return value if key.to_s.downcase == target }
+      nil
+    end
+
+    # @api private
+    # Enforce the bidirectional replay window: reject a malformed, too-old, or too-far-future
+    # timestamp.
+    def verify_timestamp!(timestamp, tolerance_seconds)
+      seconds = Integer(timestamp.to_s.strip, 10, exception: false)
+      raise Dinie::WebhookTimestampError, "Invalid webhook timestamp: #{timestamp.inspect}." if seconds.nil?
+
+      skew = Time.now.to_i - seconds
+      raise Dinie::WebhookTimestampError, "Webhook timestamp is too old." if skew > tolerance_seconds
+      return unless skew < -tolerance_seconds
+
+      raise Dinie::WebhookTimestampError, "Webhook timestamp is too far in the future."
+    end
+
+    # @api private
+    # Raise unless any (secret, signature) pair matches (constant-time, multi-sig rotation).
+    def verify_signature!(payload, secret, signature_header)
+      secrets = normalize_secrets(secret)
+      raise Dinie::WebhookSignatureError, "No webhook secret provided." if secrets.empty?
+      return if signatures_match?(payload, secrets, parse_signature_header(signature_header))
+
+      raise Dinie::WebhookSignatureError,
+            "No matching webhook signature found; the payload may have been tampered with."
+    end
+
+    # @api private
+    def normalize_secrets(secret)
+      Array(secret).select { |candidate| candidate.is_a?(String) && !candidate.empty? }
+    end
+
+    # @api private
+    # Split the `webhook-signature` header into decoded `v1` signatures. Space-separated
+    # `v1,<base64>` tokens; non-`v1` and malformed tokens are dropped.
+    def parse_signature_header(header)
+      header.split.filter_map do |token|
+        version, separator, value = token.partition(",")
+        next if separator.empty? || value.empty? || version != SIGNATURE_VERSION
+
+        value.unpack1("m")
+      end
+    end
+
+    # @api private
+    # True when any (secret, signature) pair matches. {OpenSSL.secure_compare} is constant-time and
+    # safe on unequal-length inputs (it digests both first), so no length guard is needed.
+    def signatures_match?(payload, secrets, provided_signatures)
+      secrets.any? do |secret|
+        expected = OpenSSL::HMAC.digest("SHA256", decode_secret(secret), payload)
+        provided_signatures.any? { |candidate| OpenSSL.secure_compare(candidate, expected) }
+      end
+    end
+
+    # @api private
+    # `whsec_`-prefixed secrets are base64; everything else is treated as raw bytes.
+    def decode_secret(secret)
+      return secret.delete_prefix(WHSEC_PREFIX).unpack1("m") if secret.start_with?(WHSEC_PREFIX)
+
+      secret.b
+    end
+
+    # @api private
+    # Deserialize a VERIFIED body per type (reached only after a signature matched, so the bytes are
+    # authentic). Dispatch is table-driven through {Dinie::Events::DESERIALIZERS}; a `type` absent
+    # from the catalog raises {Dinie::UnknownWebhookEventError} (forces the contract conversation).
+    def deserialize_verified_event(body)
+      raw = JSON.parse(body, symbolize_names: true)
+      event_type = raw[:type]
+      deserializer = event_type.is_a?(String) ? Dinie::Events::DESERIALIZERS[event_type] : nil
+      raise Dinie::UnknownWebhookEventError, event_type.to_s if deserializer.nil?
+
+      deserializer.call(raw)
+    end
+  end
+end

data/lib/dinie/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Dinie
+  # The gem version (semver). Surfaced in the `User-Agent` (`Dinie-SDK-Ruby/<VERSION>`) and the
+  # `X-Dinie-Sdk-Version` header. Generator-sourced in V0.5.
+  VERSION = "1.1.0"
+end

data/lib/dinie.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Curated public barrel — the single entry point consumers load via `require "dinie"`.
+#
+# It uses explicit `require_relative`s (no Zeitwerk — RB16) so load order is deterministic
+# for the generated error/event registries. This mirrors `src/index.ts` in `sdk-js`:
+# the runtime is required first (hand-written mechanism), then the generated indexes.
+#
+# At bootstrap only `version` exists. The runtime and generated layers land in later
+# stories; their requires stay as commented TODOs so the smoke suite is green before
+# those files exist. Uncomment each line in the story that introduces the file.
+
+require_relative "dinie/version"
+
+# --- generated api_version constant (required before runtime so http.rb can read it) ---
+require_relative "dinie/generated/api_version"
+
+# --- runtime (hand-written — CODEOWNER humans — stories 002–005) ---------------
+require_relative "dinie/runtime/model"
+require_relative "dinie/runtime/errors"
+require_relative "dinie/runtime/request_options"
+require_relative "dinie/runtime/idempotency"
+require_relative "dinie/runtime/rate_limit"
+require_relative "dinie/runtime/retry"
+require_relative "dinie/runtime/http"
+require_relative "dinie/runtime/token_manager"
+require_relative "dinie/runtime/logger"
+require_relative "dinie/runtime/paginator"
+require_relative "dinie/runtime/multipart"
+require_relative "dinie/runtime/webhooks"
+
+# --- generated (hand-authored V0.3 — CODEOWNER bot — stories 006–011) ----------
+require_relative "dinie/generated/errors/registry"
+require_relative "dinie/generated/types"
+require_relative "dinie/generated/events"
+require_relative "dinie/generated/resources"
+require_relative "dinie/generated/client"

data/sig/_external/faraday.rbs

@@ -0,0 +1,44 @@
+# Vendored minimal Faraday stub (architecture §5.2, story 013 / §21.3).
+#
+# Faraday + net-http-persistent ship no bundled RBS and are not in `rbs collection` at a usable
+# fidelity, so this stub declares only the Faraday surface the SDK references — entry points return
+# `untyped`, so every downstream Faraday interaction (connection, request env, response) type-checks
+# permissively without inventing precise third-party signatures. This is the documented seam that
+# keeps `steep check` informative in v1 (the `# §21.3 decision` in the Steepfile): replace it with a
+# real upstream Faraday RBS to promote the gate to blocking.
+#
+# Scope: only what `lib/dinie/runtime/{http,token_manager,logger,multipart}.rb` touch as Faraday
+# constants. Everything else flows through `untyped`.
+
+module Faraday
+  # `Faraday.new(url:) { |conn| ... }` — returns an untyped connection so `conn.request` /
+  # `conn.use` / `conn.adapter` / `conn.run_request` all resolve permissively.
+  def self.new: (*untyped, **untyped) ?{ (untyped) -> void } -> untyped
+
+  # Base for the custom logging middleware (`Internal::Middleware::Logging < Faraday::Middleware`).
+  class Middleware
+    def initialize: (untyped app) -> void
+    def call: (untyped env) -> untyped
+  end
+
+  # Transport error hierarchy the retry loop rescues + classifies.
+  class Error < StandardError
+  end
+
+  class TimeoutError < Error
+  end
+
+  class ConnectionFailed < Error
+  end
+
+  # Multipart parts the KYC upload wrapper builds / type-checks against.
+  module Multipart
+    class FilePart
+      def initialize: (*untyped) -> void
+    end
+
+    class ParamPart
+      def initialize: (*untyped) -> void
+    end
+  end
+end

data/sig/dinie/generated/client.rbs

@@ -0,0 +1,45 @@
+# `Dinie::Client` — the SDK entry point (architecture §2 RB1, §3.2, §10). Mirrors
+# `lib/dinie/generated/client.rb`. Owns a connection pool + an OAuth2 token cache; construct once.
+
+module Dinie
+  # Per-call options accepted by every resource method: a normalized `RequestOptions` or a plain
+  # Hash (`{ timeout:, idempotency_key:, headers:, max_retries: }`). The methods default it to `{}`.
+  type request_opts = Dinie::Internal::RequestOptions | Hash[Symbol, untyped]
+
+  class Client
+    DEFAULT_TIMEOUT_SECONDS: Integer
+    DEFAULT_MAX_RETRIES: Integer
+
+    def initialize: (?client_id: String?, ?client_secret: String?, ?base_url: String?, ?timeout: Numeric, ?max_retries: Integer, ?idempotency: bool, ?log_level: Symbol, ?logger: untyped, ?adapter: Symbol?, ?token_manager: Dinie::Internal::TokenManager?, ?connection: untyped) -> void
+
+    # The customers resource.
+    def customers: () -> Dinie::Resources::Customers
+
+    # The credit-offers resource.
+    def credit_offers: () -> Dinie::Resources::CreditOffers
+
+    # The loans resource.
+    def loans: () -> Dinie::Resources::Loans
+
+    # The banks resource (flat `Array<Bank>` list).
+    def banks: () -> Dinie::Resources::Banks
+
+    # The credentials resource.
+    def credentials: () -> Dinie::Resources::Credentials
+
+    # The webhook-endpoints resource.
+    def webhook_endpoints: () -> Dinie::Resources::WebhookEndpoints
+
+    # The latest rate-limit snapshot; `nil` before the first call.
+    def rate_limit: () -> Dinie::RateLimit?
+
+    # Clone the client with merged config, sharing the same TokenManager + connection.
+    def with_options: (**untyped overrides) -> Dinie::Client
+
+    private
+
+    def build_token_manager: (String? client_id, String? client_secret) -> Dinie::Internal::TokenManager
+    def build_connection: (log_level: Symbol, logger: untyped, adapter: Symbol?) -> untyped
+    def first_present: (*untyped candidates) -> untyped
+  end
+end