verisec 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c85f0ebd658b3105c5e3041d1d116cfcb7c14ca9068b132b8d2dae719f5fcbd
+  data.tar.gz: dc91184d659c12f7e5ca5f74e60298ff8b657265cdb653b0f8e9411e456c543e
+SHA512:
+  metadata.gz: 2b62de646665e9d210879253e8dd90ff7d565c5c39f04653d2c7a75eba41d1b7069cb47949c306818848a7a211117415485182e9fad991368feb0cd3289159d1
+  data.tar.gz: 239269dd7710269d5d8eac6af99fb2e841fd7849f3366c262705143b6631d7b91856becce9b42995df57f3116f2eb69b8539c4f77dbca2ffe4b64822b1e1e8bc

data/README.md

@@ -0,0 +1,211 @@
+# VeriSec Ruby SDK
+
+The official Ruby library for the VeriSec API: identity (KYC) and Financial checks. Every API is a method, images
+come straight from files, retries never run a charged call twice, live keys are exchanged for tokens for you, and
+webhook deliveries are verified.
+
+```ruby
+# Gemfile
+gem "verisec"
+```
+
+Ruby 3.0 or later. No runtime dependencies (net/http, json and openssl from the standard library).
+
+## Configure
+
+```ruby
+require "verisec"
+
+client = VeriSec::Client.new(api_key: ENV["VERISEC_API_KEY"]) # sk_test_… or ak_live_…
+```
+
+Create keys in the console under **API Keys**. A test key (`sk_test_…`) is used as it is. A live key (`ak_live_…`)
+also needs the client id and secret issued with it; the library exchanges them for a short-lived token, shares it
+between threads and renews it before it expires:
+
+```ruby
+client = VeriSec::Client.new(
+  api_key: ENV["VERISEC_API_KEY"],             # ak_live_…
+  client_id: ENV["VERISEC_CLIENT_ID"],
+  client_secret: ENV["VERISEC_CLIENT_SECRET"]
+)
+```
+
+Every option falls back to the environment (`VERISEC_API_KEY`, `VERISEC_CLIENT_ID`, `VERISEC_CLIENT_SECRET`,
+`VERISEC_BASE_URL`), so `VeriSec::Client.new` alone works too. Options: `base_url:` (default
+`https://verisec.mmose.me`), `timeout:` in seconds per attempt (default 300: a deep cheque read can take up to about
+250 s), `max_retries:` (default 2). A client can be shared between threads.
+
+## KYC: pass images as files
+
+Every API is a method, grouped the way the API groups them: `client.face`, `client.liveness`, `client.documents`,
+`client.mrz`, `client.screening`, `client.phone.otp`, … Method names are the API's operation names in snake_case
+(`photo.bestFrame` is `client.photo.best_frame`, `age.verifyLive` is `client.age.verify_live`); the full list with
+prices is in `spec/README.md`, and each method's documentation lists its fields and price.
+
+```ruby
+result = client.face.verify(image1: "selfie.jpg", image2: "id-photo.jpg", threshold: 0.8)
+result.match       # => true
+result.similarity  # => 0.998
+
+doc = client.documents.read(image_front: "id-front.jpg", image_back: Pathname("id-back.jpg"))
+
+# bytes you already hold
+result = client.face.verify(image1: VeriSec::Image.bytes(upload.read), image2: "id-photo.jpg")
+
+# lists take the images themselves; the index and ids are filled in for you
+match = client.face.match(images: ["selfie.jpg", "passport.jpg"])
+search = client.face.search(probe: "selfie.jpg", gallery: ["a.jpg", { image: "b.jpg", id: "employee-42" }])
+
+screening = client.screening.sanctions(name: "Jane Example")
+```
+
+An image can be a path (`String` or `Pathname`), an open `IO` (`File`, `StringIO`, an uploaded file),
+`VeriSec::Image.bytes(bytes)`, a `data:` URI, base64 you already have, or a binary String of raw bytes (what
+`File.binread` returns). The library sends plain base64, the way the API takes it. Anything else raises a
+`VeriSec::VeriSecError` naming the field (`image1: not a file that exists, a data: URI or base64.`) before anything
+is sent. Your parameters are never modified.
+
+Field names are exactly the API's, which uses both `detectAll` and `image_front`: write them as the method's
+documentation spells them (`client.face.analyze(image: "a.jpg", onlyCentralFace: true)`); they are sent unchanged.
+
+## Results
+
+A KYC call returns the answer's `data`; a Financial call the object. Read fields as methods or with `[]`:
+
+```ruby
+result.match                          # => true
+result[:similarity]                   # => 0.998
+result.metadata.ctx.userIp            # nested objects are wrapped too
+result.dig("compared", 0, "roi")      # => [182, 241, 173, 220]
+result.to_h                           # the plain Hash, exactly the JSON the API sent
+```
+
+Each answer type is a class (`VeriSec::Types::FaceVerify`, `VeriSec::Types::BinRecord`, …). A field the type defines
+but the answer left out reads as `nil`; a name it does not have raises `NoMethodError`, so typos don't pass silently.
+Fields the API adds later are still readable.
+
+The response is on `last_response`:
+
+```ruby
+result.last_response.request_id   # => "req_…" (quote it when you contact support)
+result.last_response.warnings     # => [] (KYC: notes about the result that are not errors)
+result.last_response.latency_ms   # => 412 (KYC: how long the check took on the server)
+result.last_response.status       # => 200
+result.last_response.headers      # => {"content-type" => "application/json", …}
+```
+
+**Open results.** The engines' full answers (face analyze and match, document read, liveness, MRZ read, IP and
+sanctions screening, proof of address, the contact dossier, …) have no fixed fields: read them as a Hash.
+
+```ruby
+screening = client.screening.sanctions(name: "Jane Example")
+screening.keys                     # => ["query", "summary", "results"]
+screening["summary"]               # or screening.dig("results", 0), screening.to_h
+screening.last_response.request_id
+```
+
+## Financial: cheques, cards, banks, BIN
+
+```ruby
+cheque = client.cheques.read(image: "cheque.jpg")                     # a path, Pathname or IO
+line = client.cheques.micr_line(image: VeriSec::FileInput.new(bytes, filename: "cheque.jpg"), format: "e13b")
+card = client.cards.check(number: "4242 4242 4242 4242", expiry: "09/29")
+bin = client.bin.lookup("424242")
+bank = client.banks.lookup(name: "Harbor Point Bank", country: "US")
+
+cheque.vision.payee     # Financial answers are objects with an `object` type ("cheque_read")
+bin.network             # => "Visa"
+```
+
+Images are uploaded as `multipart/form-data` with `X-VeriSec-Source: sdk`, so the console files them under "SDK".
+
+## One call's options
+
+```ruby
+client.cheques.read(image: "cheque.jpg", request_options: { timeout: 600, max_retries: 0, headers: { "X-Trace" => "t1" } })
+```
+
+## Credits
+
+Each call costs its API's price in credits, charged only when it succeeds. Refused calls (no credits, no permission,
+rate limited) and calls that could not run are free.
+
+## Errors
+
+```ruby
+begin
+  client.face.verify(image1: "selfie.jpg", image2: "id-photo.jpg")
+rescue VeriSec::InsufficientCreditsError
+  warn "Top up credits in the console (nothing was charged)."
+rescue VeriSec::InvalidRequestError => e
+  warn "#{e.code} #{e.param}: #{e.message}"   # e.g. parameter_unknown, image_unreadable
+rescue VeriSec::RateLimitError => e
+  warn "Wait #{e.retry_after} s."
+rescue VeriSec::APIError => e
+  warn "#{e.status} #{e.code} #{e.request_id}"
+rescue VeriSec::APIConnectionError => e
+  warn e.message                              # says whether the call may have run
+end
+```
+
+| Class | When |
+|---|---|
+| `VeriSec::InvalidRequestError` | 400, 413, 415, 422: a field is missing or not valid, the file is too large or not an image |
+| `VeriSec::AuthenticationError` | 401: no key, or the key or token is not valid |
+| `VeriSec::InsufficientCreditsError` | 402: not enough credits, or the key's spend cap (nothing charged) |
+| `VeriSec::PermissionError` | 403: the key may not call this API |
+| `VeriSec::NotFoundError` | 404 |
+| `VeriSec::RateLimitError` | 429 (with `retry_after`) |
+| `VeriSec::APIServerError` | 5xx: the check could not run (nothing charged) |
+| `VeriSec::APIConnectionError` | no answer; `VeriSec::APITimeoutError` (a subclass) when it took too long |
+
+All of them inherit from `VeriSec::VeriSecError` (also `VeriSec::Error`), with `status`, `code`, `message`, `param`,
+`request_id` and `headers`.
+
+## Retries
+
+The library retries rate limits (429), server errors (5xx) and connections that never opened (refused, DNS, network
+unreachable, connect timeout), up to `max_retries` times with backoff (`Retry-After` wins): none of those were charged.
+It never sends a call again after a timeout or a connection that dropped once the request was sent, because the
+check may already have run and been charged; you get an `APITimeoutError` / `APIConnectionError` saying so.
+
+## Webhooks
+
+Deliveries are signed as Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`). Pass the raw
+body, the headers (a Hash in any spelling, or the Rack env) and your endpoint's signing secret (`whsec_…`):
+
+```ruby
+post "/webhooks/verisec" do
+  event = VeriSec::Webhook.construct_event(request.body.read, request.env, ENV["VERISEC_WEBHOOK_SECRET"])
+  case event.type
+  when "verification.completed" then handle(event.data)
+  end
+  status 200
+rescue VeriSec::SignatureVerificationError
+  halt 400
+end
+```
+
+`VeriSec::Webhook.verify_signature` returns true or false, `verify_signature!` raises, and
+`generate_test_headers(payload, secret)` signs a payload for your own tests. The tolerance for the timestamp is 300 s
+(`tolerance:` changes it). `client.webhooks` is the same module.
+
+## Types
+
+`sig/` holds RBS signatures for everything: each method's keyword arguments with their types, and each answer type's
+readers, for Steep or your editor.
+
+## Development
+
+```sh
+bundle config set --local path vendor/bundle
+bundle install
+ruby script/generate    # after the spec changes: lib/verisec/generated and sig/generated, from ../spec/openapi.json
+bundle exec rake test   # unit tests, then integration tests against ../test-server on port 4026
+```
+
+The resources (`lib/verisec/generated/resources.rb`), the answer types (`lib/verisec/generated/types.rb`) and their
+signatures are generated from the spec; adding an operation needs only a re-run. The integration tests start the
+shared test server (`node ../test-server/server.mjs --port 4026`), call every operation through the library, and stop
+it when they end.

data/examples/quickstart.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Quickstart: three real calls.
+#
+#   VERISEC_API_KEY=sk_test_… ruby -Ilib examples/quickstart.rb selfie.jpg id-photo.jpg
+#
+# Against the local test server:
+#
+#   node ../test-server/server.mjs --port 4026 &
+#   VERISEC_BASE_URL=http://127.0.0.1:4026 VERISEC_API_KEY=sk_test_demo ruby -Ilib examples/quickstart.rb a.png b.png
+
+require "verisec"
+
+client = VeriSec::Client.new # the key (and VERISEC_BASE_URL, if set) from the environment
+
+# MRZ parse: the machine-readable lines of a passport, checked digit by digit
+mrz = client.mrz.parse(
+  lines: ["P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<", "L898902C36UTO7408122F1204159ZE184226B<<<<<10"]
+)
+puts "MRZ: #{mrz.format}, valid #{mrz.valid}, #{mrz.parsed.surname} #{mrz.parsed.given_name}"
+
+# BIN lookup: a card's network and issuer from its first digits
+bin = client.bin.lookup("424242")
+puts "BIN: #{bin.network} #{bin.type}, issued by #{bin.issuer} (#{bin.country})"
+
+# Face verify: are the two photos the same person?
+selfie, id_photo = ARGV
+if selfie && id_photo
+  result = client.face.verify(image1: selfie, image2: id_photo)
+  puts "Same person: #{result.match}, similarity #{result.similarity.round(3)}, " \
+       "request #{result.last_response.request_id}"
+end

data/lib/verisec/auth.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # How requests are authenticated: a sandbox secret key as it is, or live
+  # credentials exchanged for a short-lived token.
+  #
+  # @api private
+  module Auth
+    # Sandbox: the secret key (`sk_test_…`) is the bearer token.
+    class SecretKey
+      def initialize(key)
+        @key = key
+      end
+
+      # @return [String]
+      def token
+        @key
+      end
+
+      # A rejected secret key stays rejected.
+      #
+      # @return [Boolean] false: fetching again can't help
+      def invalidate(_token)
+        false
+      end
+
+      def inspect
+        "#<#{self.class.name} #{Util.redact(@key)}>"
+      end
+    end
+
+    # Live: an `ak_live_` API key with its client id and secret, exchanged at
+    # POST /v2/oauth/token for a bearer token. The token is cached until 60
+    # seconds before it expires; threads share one exchange.
+    class ClientCredentials
+      # Seconds before expiry at which the token is renewed.
+      REFRESH_MARGIN = 60
+      # Token lifetime assumed when the answer doesn't say.
+      DEFAULT_LIFETIME = 3600
+
+      # @param clock [#call] monotonic seconds
+      # @yieldreturn [Hash] the token endpoint's answer (`access_token`, `expires_in`)
+      def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, &exchange)
+        @exchange = exchange
+        @clock = clock
+        @mutex = Mutex.new
+        @cached = nil
+      end
+
+      # @return [String] a valid access token, exchanging credentials when needed
+      def token
+        cached = @cached
+        return cached[:token] if fresh?(cached)
+
+        @mutex.synchronize do
+          cached = @cached
+          return cached[:token] if fresh?(cached)
+
+          answer = @exchange.call
+          access_token = answer.is_a?(Hash) ? answer["access_token"] : nil
+          raise Error, "The token endpoint returned no access_token." unless access_token.is_a?(String) && !access_token.empty?
+
+          lifetime = answer["expires_in"].is_a?(Numeric) ? answer["expires_in"] : DEFAULT_LIFETIME
+          @cached = { token: access_token, expires_at: @clock.call + [lifetime - REFRESH_MARGIN, 0].max }
+          access_token
+        end
+      end
+
+      # Forgets a token the API rejected, so the next request exchanges again.
+      # A token another thread already replaced is left alone.
+      #
+      # @return [Boolean] true: a fresh token can help
+      def invalidate(rejected)
+        @mutex.synchronize { @cached = nil if @cached.nil? || @cached[:token] == rejected }
+        true
+      end
+
+      def inspect
+        "#<#{self.class.name} cached=#{!@cached.nil?}>"
+      end
+
+      private
+
+      def fresh?(cached)
+        !cached.nil? && @clock.call < cached[:expires_at]
+      end
+    end
+  end
+end

data/lib/verisec/client.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # A client for the VeriSec API, KYC and Financial.
+  #
+  #   client = VeriSec::Client.new(api_key: ENV["VERISEC_API_KEY"]) # sk_test_…
+  #
+  #   result = client.face.verify(image1: "selfie.jpg", image2: VeriSec::Image.bytes(id_photo))
+  #   result.match                      # => true
+  #   result.last_response.request_id   # => "req_…"
+  #
+  #   client.cheques.micr_line(image: "cheque.jpg", format: "e13b")
+  #   client.bin.lookup("424242")
+  #
+  # Every API is a method, grouped the way the API groups them (`client.face`,
+  # `client.documents`, `client.phone.otp`, `client.cheques`, …), named after
+  # its operationId in snake_case (`cheques.micrLine` is `client.cheques.micr_line`).
+  # Parameters are keyword arguments under the API's own field names (it mixes
+  # `detectAll` and `image_front`; they are sent exactly as written), plus
+  # `request_options: { timeout:, max_retries:, headers: }` to change one call.
+  # A KYC call returns the envelope's `data`; a Financial call the object.
+  #
+  # A client holds no per-request state, so one can be shared between threads.
+  class Client
+    # @param api_key [String, nil] a test key (`sk_test_…`) or a live API key
+    #   (`ak_live_…`). Defaults to `ENV["VERISEC_API_KEY"]`.
+    # @param client_id [String, nil] live keys only: the client id issued with
+    #   the key. Defaults to `ENV["VERISEC_CLIENT_ID"]`.
+    # @param client_secret [String, nil] live keys only: the client secret
+    #   issued with the key. Defaults to `ENV["VERISEC_CLIENT_SECRET"]`.
+    # @param base_url [String, nil] defaults to `ENV["VERISEC_BASE_URL"]`, then
+    #   https://verisec.mmose.me
+    # @param timeout [Numeric, nil] seconds per attempt, for each read or write
+    #   (opening the connection waits at most 30 s of it); default 300, since a
+    #   deep cheque read can take up to about 250 s
+    # @param max_retries [Integer, nil] retries after the first attempt, only
+    #   where nothing was charged (a connection that never opened, a 429, a
+    #   5xx); default 2
+    # @raise [VeriSec::VeriSecError] when there is no API key, or a live key
+    #   comes without its client id and secret
+    def initialize(api_key: nil, client_id: nil, client_secret: nil, base_url: nil, timeout: nil, max_retries: nil)
+      @transport = Transport.new(
+        api_key: api_key, client_id: client_id, client_secret: client_secret, base_url: base_url,
+        timeout: timeout, max_retries: max_retries
+      )
+      build_resources
+    end
+
+    # Verify and parse webhook deliveries:
+    # `client.webhooks.construct_event(payload, headers, secret)`.
+    #
+    # @return [Module] {VeriSec::Webhook}
+    def webhooks
+      Webhook
+    end
+
+    # @return [String] where requests go
+    def base_url
+      @transport.base_url
+    end
+
+    # @return [Numeric] seconds per attempt
+    def timeout
+      @transport.timeout
+    end
+
+    # @return [Integer] retries after the first attempt
+    def max_retries
+      @transport.max_retries
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect}>"
+    end
+  end
+end

data/lib/verisec/errors.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # Base class of every error this library raises.
+  #
+  # The API fields ({#status}, {#code}, {#param}, {#request_id}) are set when
+  # the API answered with an error ({APIError}) and nil otherwise, so they can
+  # be read on any VeriSecError without checking its class first.
+  #
+  #   begin
+  #     client.face.verify(image1: "selfie.jpg", image2: "id-photo.jpg")
+  #   rescue VeriSec::InsufficientCreditsError
+  #     # top up credits in the console; nothing was charged
+  #   rescue VeriSec::InvalidRequestError => e
+  #     warn "#{e.code} #{e.param}: #{e.message}"
+  #   rescue VeriSec::VeriSecError => e
+  #     warn "#{e.class}: #{e.message} (request #{e.request_id})"
+  #   end
+  class VeriSecError < StandardError
+    # @return [Integer, nil] the HTTP status code
+    attr_reader :status
+    # @return [String, nil] the machine-readable reason, e.g. "invalid_input", "insufficient_credits"
+    attr_reader :code
+    # @return [String, nil] the request field the error is about, in the API's spelling ("images[0].data")
+    attr_reader :param
+    # @return [String, nil] the request id; quote it when you contact support
+    attr_reader :request_id
+
+    # @return [Hash{String => String}] the response headers (lower-case names); empty without a response
+    def headers
+      @headers || {}
+    end
+  end
+
+  # The short name: `rescue VeriSec::Error` catches everything this library raises.
+  Error = VeriSecError
+
+  # The API answered with an error status (or a 2xx KYC answer with `ok: false`).
+  # Rescue a subclass to handle one kind.
+  class APIError < VeriSecError
+    # @param message [String, nil] the API's message
+    # @param status [Integer] the HTTP status
+    # @param code [String, nil]
+    # @param param [String, nil]
+    # @param request_id [String, nil]
+    # @param headers [Hash{String => String}] lower-case names
+    def initialize(message = nil, status: nil, code: nil, param: nil, request_id: nil, headers: {})
+      super(message || "VeriSec API request failed with status #{status}")
+      @status = status
+      @code = code
+      @param = param
+      @request_id = request_id
+      @headers = headers
+    end
+
+    # The right subclass for a failed answer.
+    #
+    # @api private
+    # @param status [Integer] the HTTP status
+    # @param body [Hash] what {Util.error_body} read from the answer: `code`, `message`, `param`
+    # @param headers [Hash{String => String}] the response headers, lower-case names
+    # @param request_id [String, nil]
+    # @return [APIError]
+    def self.from(status, body, headers, request_id)
+      class_for(status).new(
+        body[:message], status: status, code: body[:code], param: body[:param], request_id: request_id, headers: headers
+      )
+    end
+
+    # @api private
+    def self.class_for(status)
+      case status
+      when 401 then AuthenticationError
+      when 402 then InsufficientCreditsError
+      when 403 then PermissionError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      else status >= 500 ? APIServerError : InvalidRequestError
+      end
+    end
+    private_class_method :class_for
+  end
+
+  # 400, 413, 415, 422 (and any other 4xx without its own class): a field is
+  # missing or not valid, or the file is too large or not an image. See {#code}
+  # and {#param}.
+  class InvalidRequestError < APIError; end
+
+  # 401: no API key, or the key (or a live token) is not valid, expired or revoked.
+  class AuthenticationError < APIError; end
+
+  # 402: not enough credits, or the key reached its spend cap. Nothing was charged.
+  class InsufficientCreditsError < APIError; end
+
+  # 403: the key may not call this API (permission, environment or IP allow-list).
+  class PermissionError < APIError; end
+
+  # 404: nothing was found (or no such route).
+  class NotFoundError < APIError; end
+
+  # 429: too many requests for this key. Nothing was charged. The library
+  # already waited and retried; this is what was left.
+  class RateLimitError < APIError
+    # @return [Integer, Float, nil] seconds to wait, from the Retry-After header
+    def retry_after
+      Util.parse_seconds(headers["retry-after"])
+    end
+  end
+
+  # 5xx: the check could not run. Nothing was charged; it is safe to try again.
+  class APIServerError < APIError; end
+
+  # The request got no answer: the connection could not be opened, or it dropped
+  # after the request was sent (then the call may have run, and been charged, on
+  # the server, which is why the library does not send it again). The original
+  # exception is available as {#cause}.
+  class APIConnectionError < VeriSecError; end
+
+  # No answer within the timeout. The call may still have run (and been charged)
+  # on the server, so the library does not send it again.
+  class APITimeoutError < APIConnectionError; end
+
+  # A webhook signature did not verify, or its timestamp is outside the tolerance.
+  class SignatureVerificationError < VeriSecError; end
+end

data/lib/verisec/file_input.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module VeriSec
+  # A file to upload: its bytes, a file name and a media type. The Financial
+  # reads (cheques, cards) send it as `multipart/form-data` under `image`.
+  #
+  # You rarely build one yourself: `image:` also takes a path (a String or a
+  # Pathname) or an open IO (File, StringIO, Tempfile, an uploaded file), and
+  # the library wraps it. Use it to send bytes you already have, or to name them:
+  #
+  #   client.cheques.read(image: VeriSec::FileInput.new(bytes, filename: "cheque.jpg"))
+  class FileInput
+    # The file name used when none is known.
+    DEFAULT_FILENAME = "image"
+
+    # Media types by file extension, used when the bytes don't say.
+    EXTENSION_TYPES = {
+      ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg", ".png" => "image/png", ".bmp" => "image/bmp",
+      ".webp" => "image/webp", ".gif" => "image/gif", ".tif" => "image/tiff", ".tiff" => "image/tiff"
+    }.freeze
+
+    # Guesses an image's media type from its first bytes.
+    #
+    # @param bytes [String]
+    # @return [String, nil]
+    def self.sniff(bytes)
+      head = bytes.byteslice(0, 12).to_s.b
+      if head.start_with?("\xFF\xD8".b) then "image/jpeg"
+      elsif head.start_with?("\x89PNG".b) then "image/png"
+      elsif head.start_with?("BM".b) then "image/bmp"
+      elsif head.start_with?("RIFF".b) && head.byteslice(8, 4) == "WEBP".b then "image/webp"
+      elsif head.start_with?("GIF8".b) then "image/gif"
+      end
+    end
+
+    # Reads a file from disk now, so a missing file fails before any request.
+    #
+    # @param path [String, Pathname]
+    # @param content_type [String, nil]
+    # @return [FileInput]
+    # @raise [VeriSecError] when the file can't be read
+    def self.from_path(path, content_type: nil, field: "image")
+      path = path.to_path if path.respond_to?(:to_path)
+      new(File.binread(path), filename: File.basename(path), content_type: content_type)
+    rescue SystemCallError, IOError, ArgumentError, EncodingError => e
+      raise VeriSecError, "#{field}: cannot read #{Util.shorten(path)} (#{Util.reason(e)})"
+    end
+
+    # Wraps anything an upload accepts: a FileInput, a path (String or
+    # Pathname), an IO, a {VeriSec::Image}, or a String of raw bytes in binary
+    # encoding (what `File.binread` returns).
+    #
+    # @api private
+    # @param value [FileInput, String, Pathname, IO, Image]
+    # @param field [String] the field's name, for errors
+    # @return [FileInput]
+    # @raise [VeriSecError] for a file that can't be read, or anything else
+    def self.wrap(value, field = "image")
+      case value
+      when FileInput then value
+      when Image then new(value.data)
+      when String
+        bytes = value.encoding == Encoding::BINARY && !value.ascii_only?
+        bytes ? new(value) : from_path(value, field: field)
+      when Pathname then from_path(value, field: field)
+      else
+        return new(value) if value.respond_to?(:read)
+        return from_path(value, field: field) if value.respond_to?(:to_path)
+
+        raise VeriSecError, "#{field}: expected a file path, an IO or a VeriSec::FileInput, not " \
+                            "#{value.nil? ? 'nil' : value.class}."
+      end
+    end
+
+    # @param data [String, IO] the bytes, or an IO to read them from (read once,
+    #   from its current position)
+    # @param filename [String, nil] the name sent with the upload; an IO's own
+    #   name (its path, or `original_filename`) is used when left out
+    # @param content_type [String, nil] the media type; guessed from the bytes,
+    #   then from the file name, when left out
+    def initialize(data, filename: nil, content_type: nil)
+      unless data.is_a?(String) || data.respond_to?(:read)
+        raise TypeError, "VeriSec::FileInput needs a String of bytes or an IO, not #{data.class}"
+      end
+
+      @data = data
+      @filename = filename.nil? ? self.class.send(:name_of, data) : File.basename(filename.to_s)
+      @content_type = content_type
+    end
+
+    # @return [String] the file name sent with the upload
+    def filename
+      @filename || DEFAULT_FILENAME
+    end
+
+    # @return [String] the file's bytes (binary)
+    def bytes
+      @bytes ||= begin
+        raw = @data.is_a?(String) ? @data : @data.read
+        raw.to_s.b.freeze
+      end
+    end
+
+    # @return [String] the media type
+    def content_type
+      @content_type ||= self.class.sniff(bytes) ||
+                        EXTENSION_TYPES[File.extname(filename).downcase] ||
+                        "application/octet-stream"
+    end
+
+    def inspect
+      "#<#{self.class.name} filename=#{filename.inspect} content_type=#{content_type.inspect} bytes=#{bytes.bytesize}>"
+    end
+
+    # The file name an IO carries: an uploaded file's original name, or its path.
+    def self.name_of(data)
+      return nil if data.is_a?(String)
+
+      name = data.original_filename if data.respond_to?(:original_filename)
+      name ||= data.path if data.respond_to?(:path) && data.path.is_a?(String)
+      name ? File.basename(name) : nil
+    end
+    private_class_method :name_of
+  end
+end