didww-otp_verification 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 95cc4c0b5d246e12eeb76854405106c8ef277a4790dbbfee8620f6984a6074a8
+  data.tar.gz: 5d157aba75750f9b9a605b1d114dfdd289dbc9ea949b3d1d2a0a5636da12c0a9
+SHA512:
+  metadata.gz: fa0921c7b444d6efaba56f12c050d68b408c98f956a21fd3656c3672eabc8c73415a8d3fb5e16bc9c32f7bbcfca930856d5cc1c80fabc0f98a758e40bfb22d59
+  data.tar.gz: aa033d4b455850aa7ed1c5a79861bfb35a303fd8e677387ebf1d77be9ccb78468cbb5bcc4d7fe1438995a3277faa2eae67c07d689068aa5fa531bd54627cab62

data/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+Notable changes to the DIDWW OTP Verification Ruby SDK.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html): from 1.0.0 onwards a breaking change
+to the public surface requires a major version.
+
+## [1.0.0] — 2026-09
+
+First public release.
+
+### Added
+
+- **Every verification endpoint, addressable two ways.** `start_verification`,
+  `report_verification` and `get_verification` take a verification id;
+  `report_verification_by_number` and `get_verification_by_number` take a phone number in E.164
+  with the leading `+` optional, for when the id was never persisted. The number is
+  percent-encoded into its path segment, so a leading `+` survives a proxy that would otherwise
+  decode it to a space. "Latest" means the active verification when there is one, and otherwise
+  the most recent finished attempt — so an outcome that was missed can still be read.
+
+- **All three authentication modes**, selectable per client or globally. `:basic` sends
+  `Basic base64(key:secret)`. `:public` sends `Application <key>` and uses no secret, for
+  applications whose callback URL authorises each start. `:application` signs every request with
+  HMAC-SHA256 and adds an `x-timestamp` header; signing is automatic and is installed as the last
+  Faraday middleware, so the signature always covers the exact bytes that go on the wire — after
+  any middleware the caller added. A secret that is not valid URL-safe base64 fails at
+  construction rather than on the first request.
+
+- **The API's coded error envelope as typed exceptions.** A non-2xx response raises under
+  `DIDWW::OTPVerification::Error`: `UnauthorizedError` (401), `BalanceInsufficientError` (402),
+  `NotFoundError` (404), `ValidationError` (400/422) and `ServerError` (5xx); any other status
+  — a 403 or a 429 from a proxy, say — raises the `APIError` base class rather than going
+  unnoticed. Each carries `#errors`, an array of `ErrorItem`s with a stable `#code` and a fixed
+  human `#detail`, plus `#code` and `#codes` shortcuts. One response can carry several errors,
+  so `#codes` is the reliable one.
+
+- **Verification outcomes as data, not exceptions.** A failed, expired or denied verification is
+  a successful HTTP call: `Verification#status`, `#error_code` and `#error_detail` say what
+  happened, and `#finished?` is the signal to stop polling. Statuses and codes are plain strings
+  and an open set, so new ones ship without an SDK release.
+
+- **Inbound callback signature verification.** `CallbackVerifier` checks the signature DIDWW
+  sends with a `verification_request` callback, enforcing a configurable 5-minute timestamp
+  window against replays and comparing in constant time. Requiring
+  `didww/otp_verification/callback_verifier` on its own loads no HTTP client at all, so a
+  service that only receives callbacks never pays the cost of loading Faraday. (The gem still
+  declares Faraday as a runtime dependency, so it is installed either way.)
+
+- **A Rails helper for the same.** `RailsCallbackVerifier` reads every signed field off an
+  `ActionDispatch::Request`, using `raw_post` so the received bytes are what get verified. It
+  lives in `didww/otp_verification/rails`, which is deliberately not auto-required — Rails is
+  never a runtime dependency of this gem.
+
+- **Per-delivery-method options, passed through verbatim.** `sms:` carries `languages` and
+  `app_hash`, `callout:` carries `languages`; each travels under the key the API names the method
+  by, and only the block matching `delivery_method` is read. The response block comes back the
+  same way and is readable via `#sms_template`, `#sms_language`, `#sms_interception_timeout`,
+  `#sms_app_hash` and `#callout_language`, or `#sms`/`#callout` for the whole thing. Naming no
+  field inside a block individually means a field the API gains needs no release here, and a
+  method that gains a block gains one keyword rather than a new call shape.
+
+- **The language the server actually chose.** `#sms_language` and `#callout_language` report the
+  tag the message was rendered in or the announcement is played in — the first requested tag that
+  matched, otherwise the `en-US` fallback — so a fallback is detected rather than guessed at. The
+  templates and the recordings are separate catalogues, so a tag honoured on `sms` can still fall
+  back on `callout`.
+
+- **Configuration with no global-only settings.** Credentials, environment, auth mode, Faraday
+  adapter and a Faraday customization block can all be set globally through
+  `DIDWW::OTPVerification.configure` and overridden per `Client` — which is what a multi-tenant
+  host needs. `register_env` adds environments beyond the published production and sandbox.
+
+### Notes
+
+- Requires Ruby 3.1 or newer. Faraday is the only runtime HTTP dependency.
+- The SDK does not auto-retry. If you add `faraday-retry`, exclude `POST` (it would
+  double-charge) and `PATCH` (each report counts against the three-attempt limit).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DIDWW
+
+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,409 @@
+# DIDWW OTP Verification Ruby SDK
+
+Ruby client for the [DIDWW OTP Verification API](https://verification.didww.com)
+(`/api/v1`). Wraps all verification endpoints (address a verification by id or
+by phone number), all three auth modes, and inbound callback signature
+verification.
+
+📖 [API documentation](https://doc.didww.com/otp-verification/index.html)
+
+## Installation
+
+```ruby
+gem "didww-otp_verification"
+```
+
+## Quick start
+
+```ruby
+require "didww/otp_verification"
+
+client = DIDWW::OTPVerification::Client.new(
+  key:    "your-app-key",
+  secret: "your-app-secret"
+)
+
+verification = client.start_verification(
+  destination:     "+4915112345678",
+  delivery_method: "sms",                 # "sms" | "callout"
+  sms:             {languages: ["en-US"]} # optional, see below
+)
+verification.id       # => "0f9c8b7a-..."
+verification.status   # => "pending"
+verification.pending? # => true
+verification.to_h     # => raw response data Hash with string keys
+
+# Report the code the user entered (counts as an attempt; max 3, expires in 2 min)
+result = client.report_verification(
+  verification.id, delivery_method: "sms", code: "1234"
+)
+result.verified? # => true/false
+
+# Poll status
+client.get_verification(verification.id)
+```
+
+Both delivery methods are reported the same way: `code:` carries what the user
+entered, whether they read it off a message or heard it in a call.
+
+### Per-method options
+
+Options that apply to one delivery method only go in a keyword named after that
+method and travel verbatim, so the call above goes on the wire as:
+
+```json
+{ "data": { "destination": "+4915112345678", "delivery_method": "sms",
+            "sms": { "languages": ["en-US"] } } }
+```
+
+`sms:` and `callout:` are the keywords today, one per delivery method. The API
+reads only the block matching `delivery_method` and ignores the others.
+
+#### `sms:`
+
+| Field       | Description                                                                                                                                                                   |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `languages` | Preferred template languages as BCP 47 tags, most preferred first. Matched exactly, so the region subtag is required — `"pl"` does not match `pl-PL`. Unmatched tags fall back to `en-US`. |
+| `app_hash`  | Android SMS Retriever hash: exactly 11 characters of `[A-Za-z0-9+/]`. The delivered message is then prefixed with `<#> ` and the hash appended as its last token, so the handset can auto-fill the code. Omit it on every other platform. |
+
+`app_hash` is here because a Ruby backend often starts the verification on behalf
+of an Android app — the hash identifies that app, so only the app can compute it.
+
+```ruby
+client.start_verification(
+  destination: "+4915112345678", delivery_method: "sms",
+  sms: {languages: ["en-US"], app_hash: "A1b2C3d4E5f"}
+)
+```
+
+#### `callout:`
+
+| Field       | Description                                                                                                                                                                   |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `languages` | Preferred announcement languages — the same tags, order and matching rules as the `sms:` ones, so the same list is valid for either method. It is not shared between them, though: each method reads only its own block, so the list goes under `callout:` here and under `sms:` there. The catalogues are separate too, so a tag that has a message template but no recording is accepted and falls back to `en-US`. |
+
+```ruby
+client.start_verification(
+  destination: "+4915112345678", delivery_method: "callout",
+  callout: {languages: ["de-DE", "en-US"]}
+)
+```
+
+The SDK names no field inside a block individually — the block travels verbatim,
+so a field the API adds to either one needs no release here and works the day the
+API ships it. The cost of that is no typo protection: an unrecognized option is
+ignored rather than rejected, and a misspelled key returns `201` with the
+defaults applied, not an error.
+
+### Reading a method block back
+
+The response carries the block for the method that was used, readable field by
+field or as a whole:
+
+```ruby
+v.sms_template             # => "Your code is {{CODE}}"
+v.sms_language             # => "en-US"
+v.sms_interception_timeout # => 120
+v.sms_app_hash             # => "A1b2C3d4E5f", or nil if none was stored
+v.sms                      # => the raw block, or nil on a callout verification
+
+v.callout_language         # => "de-DE"
+v.callout                  # => the raw block, or nil on an sms verification
+```
+
+`sms_language` and `callout_language` are the tag the **server** chose — the
+first requested language it had a template (or a recording) for, otherwise the
+`en-US` fallback — never an echo of what was asked for. Comparing one against the
+list that was sent is how a fallback is detected rather than guessed at, and
+because the two catalogues are separate, a tag honoured on `sms` can still fall
+back on `callout`.
+
+`sms_interception_timeout` is how many seconds a client should keep an on-device
+SMS listener armed. It is a fixed budget, not a countdown, and **not** a deadline
+for the verification — manual entry keeps working until `expires_at`.
+`sms_app_hash` is echoed back only when one was stored, so it reflects what was
+persisted rather than what was requested.
+
+### Address by phone number
+
+Every report/fetch call has a `_by_number` variant that targets the latest
+verification for a phone number (E.164, leading `+` optional) instead of an id:
+
+```ruby
+client.get_verification_by_number("+4915112345678")
+client.report_verification_by_number(
+  "+4915112345678", delivery_method: "sms", code: "1234"
+)
+```
+
+Numbers are matched on their digits, so any formatting works. "Latest" is the
+active verification when there is one, otherwise the most recent finished
+attempt — so you can still read an outcome you missed. A `404` means the number
+has no verification at all.
+
+## Sandbox environment
+
+The SDK targets production by default. To hit the sandbox, pass `env: :sandbox`:
+
+```ruby
+client = DIDWW::OTPVerification::Client.new(
+  key:    "your-app-key",
+  secret: "your-app-secret",
+  env:    :sandbox
+)
+```
+
+Or set it as a global default:
+
+```ruby
+DIDWW::OTPVerification.configure do |c|
+  c.env = :sandbox
+end
+```
+
+## Configuration
+
+Set global defaults; every field is overridable per `Client`.
+
+```ruby
+DIDWW::OTPVerification.configure do |c|
+  c.key       = ENV["DIDWW_OTP_KEY"]
+  c.secret    = ENV["DIDWW_OTP_SECRET"]
+  c.auth_mode = :basic                      # :basic (default) | :public | :application
+
+  # Register extra environments (a local dev server, a private mock, ...)
+  c.register_env(:local, "http://localhost:3000")
+
+  # Customize every Faraday connection (proxy, logging, timeouts, adapter)
+  c.faraday do |conn|
+    conn.options.timeout = 10
+    conn.response :logger
+  end
+end
+
+DIDWW::OTPVerification::Client.new  # picks up the globals
+```
+
+### Per-request credentials / config
+
+Nothing is global-only. Pass anything straight to `Client.new` — ideal for
+multi-tenant apps:
+
+```ruby
+DIDWW::OTPVerification::Client.new(
+  key: tenant.key, secret: tenant.secret,
+  base_url: "https://custom.host",          # wins over env
+  adapter: :typhoeus                         # any Faraday adapter
+) { |conn| conn.proxy = "http://proxy:3128" }
+```
+
+## Auth modes
+
+| Mode               | Header                                          | Secret   | Notes                              |
+| ------------------ | ----------------------------------------------- | -------- | ---------------------------------- |
+| `:basic` (default) | `Basic base64(key:secret)`                      | required | Documented, simplest               |
+| `:public`          | `Application <key>`                             | not used | Requires a callback URL on the app |
+| `:application`     | `Application <key>:<signature>` + `x-timestamp` | required | HMAC-SHA256 signed                 |
+
+Set the mode per `Client` via `auth_mode:`, or globally via
+`c.auth_mode` in `configure`.
+
+### `:basic` (default)
+
+Sends `Basic base64(key:secret)`. Requires both `key` and `secret`.
+
+```ruby
+client = DIDWW::OTPVerification::Client.new(
+  key:    "your-app-key",
+  secret: "your-app-secret",
+  auth_mode: :basic          # optional — this is the default
+)
+```
+
+### `:public`
+
+Sends `Application <key>`. No secret is used; the app must have a callback URL
+configured so DIDWW can deliver results.
+
+```ruby
+client = DIDWW::OTPVerification::Client.new(
+  key:       "your-app-key",
+  auth_mode: :public
+)
+```
+
+### `:application`
+
+Sends `Application <key>:<signature>` plus an `x-timestamp` header. The `secret`
+is the URL-safe base64 signing key and is required. Signing is applied
+automatically; the signature is computed over the exact request bytes.
+
+```ruby
+client = DIDWW::OTPVerification::Client.new(
+  key:       "your-app-key",
+  secret:    "your-app-secret",
+  auth_mode: :application
+)
+```
+
+## Verifying inbound callbacks
+
+DIDWW sends signed `verification_request` callbacks to your server using the
+same HMAC scheme. The verifier has no HTTP-client dependency. The callback
+request payload is documented at
+[Request from DIDWW](https://doc.didww.com/otp-verification/callbacks.html#request-from-didww).
+
+```ruby
+verifier = DIDWW::OTPVerification::CallbackVerifier.new(secret: app_secret)
+
+key, signature = DIDWW::OTPVerification::CallbackVerifier
+                 .parse_authorization(request.headers["Authorization"])
+
+ok = verifier.valid?(
+  method:       request.request_method,   # "POST"
+  path:         request.path,             # your callback URL's path
+  content_type: request.content_type,
+  body:         request.raw_post,         # RAW body bytes — do not re-serialize
+  timestamp:    request.headers["x-timestamp"],
+  signature:    signature
+)
+
+render json: { action: ok ? "allow" : "deny" }
+```
+
+The verifier also enforces a 5-minute timestamp window (configurable via
+`tolerance:`) to reject replays.
+
+### Rails
+
+`RailsCallbackVerifier` pulls every signed field off an `ActionDispatch`
+request for you. It lives in a separate file that is **not** auto-required —
+Rails is an optional runtime dependency — so require it explicitly:
+
+```ruby
+require "didww/otp_verification/rails"
+```
+
+Controller:
+
+```ruby
+class DidwwCallbacksController < ActionController::API
+  before_action :verify_didww_signature
+
+  # Signature is already verified here — decide allow/deny from your own
+  # logic and the callback params.
+  def create
+    # some custom logic to decide whether to allow or deny the verification request
+    allow = expected_destination? params.dig(:data, :destination)
+
+    render json: { action: allow ? "allow" : "deny" }
+  end
+
+  private
+
+  def verify_didww_signature
+    verifier = DIDWW::OTPVerification::RailsCallbackVerifier.new(
+      secret: ENV["DIDWW_OTP_SECRET"]
+    )
+    head(:unauthorized) unless verifier.valid?(request)
+  end
+end
+```
+
+Routes (`config/routes.rb`) — the path must match the callback URL registered
+on your app, since it is part of the signed payload:
+
+```ruby
+post "/callbacks/didww", to: "didww_callbacks#create"
+```
+
+## Verification outcomes
+
+Every 2xx response carries the verification's `status`. One that ended badly also
+carries `error_code` (switch on it) and `error_detail` (display it). These are
+**not** exceptions — a failed or denied verification is a successful HTTP call.
+
+| `status`   | Terminal | `error_code`                                                                                 |
+| ---------- | -------- | -------------------------------------------------------------------------------------------- |
+| `pending`  | no       | `nil` — on its way, or awaiting a report                                                       |
+| `verified` | yes      | `nil`                                                                                          |
+| `failed`   | yes      | `too_many_attempts`, `dispatch_failed`, `stale_dispatch`, `superseded`, `application_deleted`   |
+| `expired`  | yes      | `expired` — past the 2-minute window                                                           |
+| `denied`   | yes      | `denied_by_callback`, `denied_missing_callback_url`, `denied_invalid_callback_response`         |
+
+`superseded` means a newer `start_verification` for the same number retired this
+one — only the newest verification per number stays active.
+
+```ruby
+v = client.get_verification(id)
+
+if v.finished?  # verified / failed / expired / denied — stop polling
+  case v.error_code
+  when nil                 then grant_access
+  when "too_many_attempts" then lock_out
+  when "expired"           then offer_resend
+  else logger.warn("verification #{v.id}: #{v.error_detail}")
+  end
+end
+```
+
+Statuses and codes are plain strings and an open set — new ones ship without an
+SDK release, so always keep a default branch and treat the
+[API documentation](https://doc.didww.com/otp-verification/index.html) as the
+authoritative list.
+
+## Errors
+
+Non-2xx responses raise a typed error under `DIDWW::OTPVerification::Error`:
+
+| Class                      | Status    | Typical code                          |
+| -------------------------- | --------- | ------------------------------------- |
+| `UnauthorizedError`        | 401       | `unauthorized`                        |
+| `BalanceInsufficientError` | 402       | `balance_insufficient`                |
+| `NotFoundError`            | 404       | `not_found`                           |
+| `ValidationError`          | 400 / 422 | `parameter_missing` / per-field codes |
+| `ServerError`              | 5xx       | `internal_error`                      |
+
+Every error carries the API's coded envelope: `#errors` is an array of
+`ErrorItem`s (`#code`, `#detail`), and `#code`/`#codes` are shortcuts to the
+stable, machine-readable slugs. Switch on `code`; the human `detail` is fixed per
+code and only for display. One response can carry several errors — check `#codes`
+rather than `#code`, which only returns the first.
+
+Every status the API produces carries this envelope. `#errors` is empty only when
+a response has no JSON body at all — e.g. a 502 from a proxy in front of it.
+
+```ruby
+begin
+  client.start_verification(destination: "", delivery_method: "sms")
+rescue DIDWW::OTPVerification::ValidationError => e
+  e.status            # => 422
+  e.code              # => "destination_blank"
+  e.codes             # => ["destination_blank"]
+  e.errors.first.code # => "destination_blank"
+  e.message           # => every error's detail, joined by ", "
+end
+```
+
+## Retries
+
+The SDK does **not** auto-retry. If you add `faraday-retry`, exclude `POST`
+(double-charges) and `PATCH` (each report counts against the 3-attempt limit).
+
+## Development
+
+Development is pinned to the Ruby in `.ruby-version`; the gem itself supports
+3.1+.
+
+```sh
+bundle install
+bundle exec rake spec         # core gem specs (no Rails)
+bundle exec rake spec:rails   # Rails integration suite (spec-rails/)
+```
+
+The signing implementation is pinned to the server's own test vectors in
+`spec/didww/otp_verification/signer_spec.rb`.
+
+Rails is a **dev-only** dependency: it is exercised solely by the `spec-rails/`
+suite and is never a runtime dependency of the gem. The core specs under
+`spec/` never load Rails.

data/lib/didww/otp_verification/callback_verifier.rb

@@ -0,0 +1,72 @@
+require "time"
+require "openssl"
+
+# Required directly by callback-only services; cannot assume the entry point.
+require_relative "util"
+require_relative "signer"
+
+module DIDWW
+  module OTPVerification
+    # Verifies the signature of an inbound verification-request callback that
+    # DIDWW sends to your server. Uses the same HMAC scheme as outbound signing,
+    # where PATH is the path of *your* callback URL.
+    #
+    # Has no Faraday dependency on purpose: a service that only receives
+    # callbacks should not need the HTTP client.
+    #
+    #   verifier = DIDWW::OTPVerification::CallbackVerifier.new(secret: app_secret)
+    #   key, signature = DIDWW::OTPVerification::CallbackVerifier.parse_authorization(auth_header)
+    #   verifier.valid?(
+    #     method: "POST", path: "/callbacks/didww",
+    #     content_type: "application/json", body: raw_body,
+    #     timestamp: request.headers["x-timestamp"], signature: signature
+    #   )
+    class CallbackVerifier
+      # @param tolerance [Integer] max allowed clock skew, in seconds (server uses 5 minutes).
+      def initialize(secret:, tolerance: 300, clock: -> { Time.now.to_i })
+        @signer = Signer.new(secret)
+        @tolerance = tolerance
+        @clock = clock
+      end
+
+      # Splits an "Application <key>:<signature>" header into [key, signature].
+      # Returns [nil, nil] if the header is missing or not in that form.
+      def self.parse_authorization(header)
+        return [nil, nil] if header.nil?
+
+        scheme, credentials = header.split(" ", 2)
+        return [nil, nil] unless scheme == "Application" && credentials
+
+        key, signature = credentials.split(":", 2)
+        [key, signature]
+      end
+
+      # @return [Boolean] true when both the timestamp is fresh and the
+      #   signature matches (constant-time comparison).
+      def valid?(method:, path:, content_type:, body:, timestamp:, signature:)
+        return false if Util.blank?(signature)
+        return false unless fresh?(timestamp)
+
+        expected = @signer.sign(
+          method:, path:, content_type:, body:, timestamp: timestamp
+        )
+        secure_compare(expected, signature)
+      end
+
+      private
+
+      def fresh?(timestamp)
+        return false if Util.blank?(timestamp)
+
+        (@clock.call - timestamp.to_i).abs <= @tolerance
+      end
+
+      # Constant-time string comparison via the audited stdlib implementation.
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        OpenSSL.fixed_length_secure_compare(a, b)
+      end
+    end
+  end
+end

data/lib/didww/otp_verification/client.rb

@@ -0,0 +1,196 @@
+require "faraday"
+require "base64"
+require "erb"
+
+module DIDWW
+  module OTPVerification
+    # The API client. All three verification endpoints hang off an instance.
+    #
+    #   client = DIDWW::OTPVerification::Client.new(
+    #     key: "app-uuid", secret: "app-secret", env: :sandbox
+    #   )
+    #   verification = client.start_verification(
+    #     destination: "+4915112345678", delivery_method: "sms"
+    #   )
+    #   client.report_verification(verification.id, delivery_method: "sms", code: "1234")
+    #   client.get_verification(verification.id)
+    #
+    # The +*_by_number+ variants address the latest verification for a phone
+    # number instead of an id.
+    #
+    # Unspecified arguments fall back to DIDWW::OTPVerification.configuration.
+    class Client
+      API_PREFIX = "/api/v1".freeze
+
+      attr_reader :key, :auth_mode, :base_url
+
+      # @param base_url [String, nil] explicit base URL; wins over +env+.
+      # @param env [Symbol, nil] a registered environment name.
+      # @param auth_mode [Symbol] :basic (default), :public, or :application.
+      # @param adapter [Symbol, Array, nil] a Faraday adapter override.
+      # @yield [conn] optional per-client Faraday customization.
+      def initialize(key: nil, secret: nil, env: nil, base_url: nil,
+        auth_mode: nil, adapter: nil, &faraday_block)
+        config = OTPVerification.configuration
+        @key = key || config.key
+        @secret = secret || config.secret
+        @auth_mode = (auth_mode || config.auth_mode).to_sym
+        @base_url = base_url || config.base_url_for(env || config.env)
+        @adapter = adapter || config.adapter
+        @faraday_block = faraday_block || config.faraday
+        validate!
+      end
+
+      # POST /api/v1/verifications
+      #
+      # Options specific to one delivery method go in a keyword named after it,
+      # e.g. <tt>sms: { languages: ["en-US"] }</tt> or
+      # <tt>callout: { languages: ["de-DE"] }</tt>, and travel verbatim. The API
+      # reads only the block matching +delivery_method+ and ignores the others.
+      # An unrecognized option is ignored rather than rejected, so a typo there
+      # fails silently. Methods with no options of their own take no keyword.
+      def start_verification(destination:, delivery_method:, sms: nil, callout: nil)
+        data = {destination:, delivery_method:}
+        data[:sms] = sms unless sms.nil?
+        data[:callout] = callout unless callout.nil?
+        request(:post, "#{API_PREFIX}/verifications", data)
+      end
+
+      # PATCH /api/v1/verifications/:id. Reports the +code+ the user entered;
+      # every delivery method is reported the same way. NB: reporting counts as
+      # an attempt (max 3), so never auto-retry this call.
+      def report_verification(id, delivery_method:, code:)
+        request(:patch, "#{API_PREFIX}/verifications/#{id}", {delivery_method:, code:})
+      end
+
+      # GET /api/v1/verifications/:id
+      def get_verification(id)
+        handle(connection.get("#{API_PREFIX}/verifications/#{id}"))
+      end
+
+      # PATCH /api/v1/verifications/by_number/:number. Reports against the latest
+      # verification for +number+ (E.164, leading + optional). Same attempt
+      # caveat as #report_verification: never auto-retry.
+      def report_verification_by_number(number, delivery_method:, code:)
+        request(:patch, "#{API_PREFIX}/verifications/by_number/#{encode(number)}",
+          {delivery_method:, code:})
+      end
+
+      # GET /api/v1/verifications/by_number/:number. +number+ is E.164 with an
+      # optional leading +.
+      def get_verification_by_number(number)
+        handle(connection.get("#{API_PREFIX}/verifications/by_number/#{encode(number)}"))
+      end
+
+      private
+
+      # Percent-encode a value for use as a single URL path segment. Notably
+      # turns a leading "+" into "%2B" so it survives proxies that would
+      # otherwise decode "+" to a space in the path.
+      def encode(segment)
+        ERB::Util.url_encode(segment.to_s)
+      end
+
+      def request(method, path, data)
+        handle(connection.public_send(method, path, {data: data}))
+      end
+
+      def handle(response)
+        body = response.body
+
+        if response.success?
+          unless body.is_a?(Hash)
+            raise APIError.new(
+              "unexpected response body",
+              status: response.status,
+              response: response
+            )
+          end
+          return Verification.new(body["data"])
+        end
+
+        errors = parse_errors(body)
+        raise error_class(response.status).new(
+          status: response.status,
+          errors: errors,
+          response: response
+        )
+      end
+
+      # Map the {"errors": [{"code", "detail"}]} envelope to ErrorItem objects.
+      # Tolerates a plain-string element by exposing it as the +detail+.
+      def parse_errors(body)
+        return [] unless body.is_a?(Hash)
+
+        Array(body["errors"]).map do |item|
+          if item.is_a?(Hash)
+            ErrorItem.new(item["code"], item["detail"])
+          else
+            ErrorItem.new(nil, item.to_s)
+          end
+        end
+      end
+
+      def error_class(status)
+        case status
+        when 401 then UnauthorizedError
+        when 402 then BalanceInsufficientError
+        when 404 then NotFoundError
+        when 400, 422 then ValidationError
+        when 500..599 then ServerError
+        else APIError
+        end
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: @base_url) do |conn|
+          conn.request :json
+          conn.response :json, content_type: /\bjson$/
+          @faraday_block&.call(conn)
+          # Auth (signing) must be installed last so it sees the final request
+          # bytes/headers/path, after any user middleware from @faraday_block.
+          apply_auth(conn)
+          conn.adapter(*Array(@adapter || Faraday.default_adapter))
+        end
+      end
+
+      def apply_auth(conn)
+        case @auth_mode
+        when :basic
+          conn.request :authorization, :basic, @key, @secret
+        when :public
+          conn.headers["Authorization"] = "Application #{@key}"
+        when :application
+          conn.use Middleware::Signature, key: @key, secret: @secret
+        end
+      end
+
+      def validate!
+        unless AUTH_MODES.include?(@auth_mode)
+          raise ConfigurationError,
+            "unknown auth_mode #{@auth_mode.inspect}; expected one of #{AUTH_MODES.inspect}"
+        end
+        raise ConfigurationError, "key is required" if Util.blank?(@key)
+        if secret_required? && Util.blank?(@secret)
+          raise ConfigurationError, "secret is required for #{@auth_mode} auth mode"
+        end
+
+        validate_signing_secret! if @auth_mode == :application
+      end
+
+      def secret_required?
+        @auth_mode == :basic || @auth_mode == :application
+      end
+
+      # The application secret is the URL-safe base64 signing key; decode it now
+      # so a malformed secret fails fast here instead of raising an untyped
+      # ArgumentError from Signer on the first request.
+      def validate_signing_secret!
+        Base64.urlsafe_decode64(@secret)
+      rescue ArgumentError
+        raise ConfigurationError,
+          "secret is not valid URL-safe base64 for #{@auth_mode} auth mode"
+      end
+    end
+  end
+end

data/lib/didww/otp_verification/configuration.rb

@@ -0,0 +1,52 @@
+require_relative "errors"
+
+module DIDWW
+  module OTPVerification
+    # Global defaults for Client. Every field can be overridden per-Client at
+    # construction time.
+    class Configuration
+      # The environments the API publishes. Add more with #register_env.
+      DEFAULT_ENVS = {
+        production: "https://verification.didww.com",
+        sandbox: "https://verification-sandbox.didww.com"
+      }.freeze
+
+      attr_accessor :key, :secret, :env, :auth_mode, :adapter
+
+      def initialize
+        @envs = DEFAULT_ENVS.dup
+        @env = :production
+        @auth_mode = :basic
+        @key = nil
+        @secret = nil
+        @adapter = nil
+        @faraday_block = nil
+      end
+
+      # Register a named environment, e.g. a local dev server:
+      #   config.register_env(:local, "http://localhost:3000")
+      def register_env(name, base_url)
+        @envs[name.to_sym] = base_url
+      end
+
+      # @return [String] base URL for a registered environment.
+      # @raise [ConfigurationError] if the environment is unknown.
+      def base_url_for(env)
+        @envs.fetch(env.to_sym) do
+          raise ConfigurationError,
+            "unknown env #{env.inspect}; registered: #{@envs.keys.inspect}"
+        end
+      end
+
+      # Register a block to customize every Faraday connection (proxy, logging,
+      # timeouts, custom adapter, etc). Runs after the built-in request/response
+      # middleware but before auth signing, so application-mode signatures are
+      # always computed over the final request bytes.
+      #   config.faraday { |conn| conn.response :logger }
+      def faraday(&block)
+        @faraday_block = block if block
+        @faraday_block
+      end
+    end
+  end
+end

data/lib/didww/otp_verification/errors.rb

@@ -0,0 +1,54 @@
+module DIDWW
+  module OTPVerification
+    # Base class for every error raised by this SDK.
+    class Error < StandardError; end
+
+    # Raised when the client is misconfigured (missing key/secret, unknown env, etc).
+    class ConfigurationError < Error; end
+
+    # A single coded error from the API's error envelope
+    # +{ "errors": [ { "code", "detail" } ] }+. +code+ is a stable,
+    # machine-readable slug (switch on it); +detail+ is its fixed human text.
+    ErrorItem = Struct.new(:code, :detail) do
+      def to_s = detail || code || ""
+    end
+
+    # Raised when the API responds with a non-2xx status. Subclasses map to
+    # specific HTTP statuses. Every documented status carries the coded error
+    # envelope; +errors+ is empty only when a response has no (or a non-JSON)
+    # body, e.g. an error produced by a proxy in front of the API.
+    class APIError < Error
+      # @return [Array<ErrorItem>] coded errors from the response body.
+      attr_reader :status, :errors, :response
+
+      def initialize(message = nil, status:, errors: [], response: nil)
+        @status = status
+        @errors = errors
+        @response = response
+        details = errors.map(&:detail).compact
+        super(message || (details.empty? ? "HTTP #{status}" : details.join(", ")))
+      end
+
+      # @return [String, nil] machine-readable code of the first error.
+      def code = errors.first&.code
+
+      # @return [Array<String>] machine-readable codes of every error.
+      def codes = errors.map(&:code)
+    end
+
+    # 401 Unauthorized (+unauthorized+ code).
+    class UnauthorizedError < APIError; end
+
+    # 402 Payment Required (+balance_insufficient+ code).
+    class BalanceInsufficientError < APIError; end
+
+    # 404 Not Found.
+    class NotFoundError < APIError; end
+
+    # 400 Bad Request / 422 Unprocessable Content (validation errors in +errors+).
+    class ValidationError < APIError; end
+
+    # 5xx Server Error (+internal_error+ code).
+    class ServerError < APIError; end
+  end
+end

data/lib/didww/otp_verification/middleware/signature.rb

@@ -0,0 +1,37 @@
+require "faraday"
+
+module DIDWW
+  module OTPVerification
+    module Middleware
+      # Faraday request middleware that signs the outgoing request using the
+      # +application+ auth scheme. It MUST run after the request body has been
+      # serialized (i.e. after +conn.request :json+) so that CONTENT-MD5 is
+      # computed over the exact bytes that go on the wire.
+      #
+      # Injects:
+      #   Authorization: Application <key>:<signature>
+      #   x-timestamp:   <unix-seconds>
+      class Signature < Faraday::Middleware
+        def initialize(app, key:, secret:, clock: -> { Time.now.to_i })
+          super(app)
+          @key = key
+          @signer = Signer.new(secret)
+          @clock = clock
+        end
+
+        def on_request(env)
+          timestamp = @clock.call.to_s
+          signature = @signer.sign(
+            method: env.method,
+            path: env.url.path,
+            content_type: env.request_headers["Content-Type"].to_s,
+            body: env.body.to_s,
+            timestamp: timestamp
+          )
+          env.request_headers["Authorization"] = "Application #{@key}:#{signature}"
+          env.request_headers["x-timestamp"] = timestamp
+        end
+      end
+    end
+  end
+end

data/lib/didww/otp_verification/rails.rb

@@ -0,0 +1,55 @@
+require_relative "callback_verifier"
+
+module DIDWW
+  module OTPVerification
+    # Rails glue for verifying inbound callback signatures straight from an
+    # ActionDispatch request.
+    #
+    # NOT auto-required by "didww/otp_verification" on purpose: Rails is an
+    # optional runtime dependency, so services that don't run Rails pay nothing.
+    # Require it explicitly where you need it:
+    #
+    #   require "didww/otp_verification/rails"
+    #
+    #   class DidwwCallbacksController < ActionController::API
+    #     before_action :verify_didww_signature
+    #
+    #     def create
+    #       # signature already verified; decide allow/deny from params
+    #       render json: { action: allowed?(params) ? "allow" : "deny" }
+    #     end
+    #
+    #     private
+    #
+    #     def verify_didww_signature
+    #       verifier = DIDWW::OTPVerification::RailsCallbackVerifier.new(secret: app_secret)
+    #       head(:unauthorized) unless verifier.valid?(request)
+    #     end
+    #   end
+    class RailsCallbackVerifier
+      # Same options as CallbackVerifier.
+      def initialize(secret:, tolerance: 300, clock: -> { Time.now.to_i })
+        @verifier = CallbackVerifier.new(secret: secret, tolerance: tolerance, clock: clock)
+      end
+
+      # Pulls every signed field off the ActionDispatch::Request and verifies it.
+      # Uses request.raw_post so the exact received bytes are signed — never
+      # re-serialize the parsed params.
+      #
+      # @param request [ActionDispatch::Request]
+      # @return [Boolean]
+      def valid?(request)
+        _key, signature = CallbackVerifier.parse_authorization(request.headers["Authorization"])
+
+        @verifier.valid?(
+          method: request.request_method,
+          path: request.path,
+          content_type: request.content_type,
+          body: request.raw_post,
+          timestamp: request.headers["x-timestamp"],
+          signature: signature
+        )
+      end
+    end
+  end
+end

data/lib/didww/otp_verification/signer.rb

@@ -0,0 +1,59 @@
+require "openssl"
+require "digest"
+require "base64"
+
+require_relative "errors"
+require_relative "util"
+
+module DIDWW
+  module OTPVerification
+    # HMAC-SHA256 request signer for the +application+ auth mode.
+    #
+    # The signing key is the application +secret+ decoded from URL-safe base64.
+    # The string to sign is 5 lines joined by "\n":
+    #
+    #   <HTTP-METHOD>
+    #   <CONTENT-MD5>            # Base64(MD5(body)), empty string when no body
+    #   <CONTENT-TYPE>
+    #   x-timestamp:<TIMESTAMP>
+    #   <PATH>
+    #
+    # The signature is Base64(HMAC-SHA256(key, string_to_sign)).
+    class Signer
+      def initialize(secret)
+        raise ConfigurationError, "secret is required for signing" if Util.blank?(secret)
+
+        @key = Base64.urlsafe_decode64(secret)
+      end
+
+      # @return [String] the base64-encoded signature.
+      def sign(method:, path:, content_type:, body:, timestamp:)
+        digest = OpenSSL::HMAC.digest(
+          "SHA256",
+          @key,
+          string_to_sign(method:, path:, content_type:, body:, timestamp:)
+        )
+        Base64.strict_encode64(digest)
+      end
+
+      # @return [String] the canonical string that gets signed. Exposed for
+      #   debugging / cross-checking against the server implementation.
+      def string_to_sign(method:, path:, content_type:, body:, timestamp:)
+        content_md5 =
+          if body.nil? || body.empty?
+            ""
+          else
+            Base64.strict_encode64(Digest::MD5.digest(body))
+          end
+
+        [
+          method.to_s.upcase,
+          content_md5,
+          content_type.to_s,
+          "x-timestamp:#{timestamp}",
+          path
+        ].join("\n")
+      end
+    end
+  end
+end

data/lib/didww/otp_verification/util.rb

@@ -0,0 +1,13 @@
+module DIDWW
+  module OTPVerification
+    # Small internal helpers shared across the SDK.
+    module Util
+      module_function
+
+      # @return [Boolean] true when +value+ is nil or an empty string.
+      def blank?(value)
+        value.nil? || value.to_s.empty?
+      end
+    end
+  end
+end

data/lib/didww/otp_verification/verification.rb

@@ -0,0 +1,85 @@
+require "time"
+require "bigdecimal"
+
+module DIDWW
+  module OTPVerification
+    # Thin value object wrapping the +data+ envelope returned by every
+    # verification endpoint. Statuses and error codes are an open set, so the
+    # predicates below are conveniences, not an exhaustive enum.
+    #
+    # +error_code+/+error_detail+ say why a verification ended badly; both are
+    # nil while pending and when verified. They are unrelated to the errors on
+    # an APIError, which is raised instead of returning a Verification.
+    class Verification
+      attr_reader :id, :destination, :delivery_method, :fee, :status,
+        :error_code, :error_detail, :expires_at, :sms, :callout, :raw
+
+      def initialize(data)
+        data ||= {}
+        @raw = data
+        @id = data["id"]
+        @destination = data["destination"]
+        @delivery_method = data["delivery_method"]
+        @fee = data["fee"] ? BigDecimal(data["fee"]) : nil
+        @status = data["status"]
+        @error_code = data["error_code"]
+        @error_detail = data["error_detail"]
+        @expires_at = data["expires_at"] ? Time.parse(data["expires_at"]) : nil
+        @sms = data["sms"]
+        @callout = data["callout"]
+      end
+
+      # @return [Hash] the raw +data+ envelope this object was built from.
+      def to_h
+        @raw
+      end
+
+      # @return [String, nil] SMS template, only present for the +sms+ method.
+      def sms_template
+        @sms && @sms["template"]
+      end
+
+      # The tag the server chose for the message: the first requested language
+      # it had a template for, or the +en-US+ fallback. It is a choice, never an
+      # echo, so comparing it against what was asked for is how a fallback is
+      # detected rather than guessed at.
+      #
+      # @return [String, nil] BCP 47 tag, only present for the +sms+ method.
+      def sms_language
+        @sms && @sms["language"]
+      end
+
+      # @return [Integer, nil] seconds to keep an SMS listener armed. Not a
+      #   deadline: manual entry stays live until +expires_at+.
+      def sms_interception_timeout
+        @sms && @sms["interception_timeout"]
+      end
+
+      # @return [String, nil] SMS Retriever hash, echoed back only when one was
+      #   stored on this verification.
+      def sms_app_hash
+        @sms && @sms["app_hash"]
+      end
+
+      # The tag the announcement is played in: the first requested language the
+      # server had a recording for, or the +en-US+ fallback. The recordings are
+      # a different catalogue from the SMS templates, so a tag honoured on +sms+
+      # can still fall back here.
+      #
+      # @return [String, nil] BCP 47 tag, only present for the +callout+ method.
+      def callout_language
+        @callout && @callout["language"]
+      end
+
+      def pending? = status == "pending"
+      def verified? = status == "verified"
+      def failed? = status == "failed"
+      def expired? = status == "expired"
+      def denied? = status == "denied"
+
+      # @return [Boolean] true once the verification reached a terminal status
+      #   (successfully or not) — stop polling.
+      def finished? = verified? || failed? || expired? || denied?
+    end
+  end
+end

data/lib/didww/otp_verification/version.rb

@@ -0,0 +1,5 @@
+module DIDWW
+  module OTPVerification
+    VERSION = "1.0.0"
+  end
+end

data/lib/didww/otp_verification.rb

@@ -0,0 +1,39 @@
+require "faraday"
+
+require_relative "otp_verification/version"
+require_relative "otp_verification/errors"
+require_relative "otp_verification/util"
+require_relative "otp_verification/configuration"
+require_relative "otp_verification/signer"
+require_relative "otp_verification/middleware/signature"
+require_relative "otp_verification/verification"
+require_relative "otp_verification/callback_verifier"
+require_relative "otp_verification/client"
+
+module DIDWW
+  module OTPVerification
+    AUTH_MODES = %i[basic public application].freeze
+
+    class << self
+      # Global configuration singleton. Used as defaults by Client.
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      #   DIDWW::OTPVerification.configure do |c|
+      #     c.env = :sandbox
+      #     c.key = ENV["DIDWW_OTP_KEY"]
+      #     c.secret = ENV["DIDWW_OTP_SECRET"]
+      #   end
+      def configure
+        yield configuration
+        configuration
+      end
+
+      # Mainly for tests.
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: didww-otp_verification
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- DIDWW
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Client for the DIDWW OTP verification API with basic, public and HMAC-signed
+  (application) auth, plus inbound callback signature verification.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/didww/otp_verification.rb
+- lib/didww/otp_verification/callback_verifier.rb
+- lib/didww/otp_verification/client.rb
+- lib/didww/otp_verification/configuration.rb
+- lib/didww/otp_verification/errors.rb
+- lib/didww/otp_verification/middleware/signature.rb
+- lib/didww/otp_verification/rails.rb
+- lib/didww/otp_verification/signer.rb
+- lib/didww/otp_verification/util.rb
+- lib/didww/otp_verification/verification.rb
+- lib/didww/otp_verification/version.rb
+homepage: https://github.com/didww/didww-verification-ruby-sdk
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/didww/didww-verification-ruby-sdk
+  changelog_uri: https://github.com/didww/didww-verification-ruby-sdk/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby SDK for the DIDWW OTP Verification API
+test_files: []