usesmileid 12.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b3aa92d6b398bde9e998a5e5b128c688a94ac72331b7f5be584df7008286458
+  data.tar.gz: f44668a9c23b92c59708176ba20153ef729b3f840431a3fd2fd32fab8121efa4
+SHA512:
+  metadata.gz: 2f3017edcda29325e2b49d5a6824d20f6c649538044e840f2a6b08aea08d44d65fa9e8e07c821544519181726d9a3fa3853ee796c6216808c18169f094d65a5e
+  data.tar.gz: 146f765cb0b59e9aa473718c614ae3287fd94e064e51bca8f546755c09e1b3f4f60c22816c538041aeb01750c1728da2b9b3b3c65d0238edbe74a3a88106b289

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- Renamed the gem from `smile-identity-core` to `smileid`. The require path
+  (`require "smileid"`) and the `SmileID` module are unchanged.
+- Set the version to 12.0.0, aligning the server SDKs with the V12 mobile
+  SDKs.
+- `base_url` must now be an absolute https URL with no query or fragment,
+  validated at construction. There is no allow-insecure option.
+- `default_callback_url` (at construction) and per-request `callback_url`
+  values (entry operations and replay) must be https; insecure values raise
+  a validation error before any request is sent.
+- `job_id` and `user_id` path parameters are URL-encoded as single path
+  segments before interpolation.
+- Multipart filenames and content types are sanitized against header
+  injection on every input path, including caller-supplied content types.
+  Filenames have control characters stripped and quotes encoded; content
+  types must be a valid media type.
+
+### Added
+
+- `SmileID::Errors::UnexpectedResponseError`, raised when a 2xx success
+  response body is not the expected JSON object.
+
+### Added
+
+- Full V3 API coverage: enhanced KYC, document verification, enhanced document
+  verification, biometric KYC, biometric enrollment, authentication and compare,
+  verification status with a `wait_until_complete` polling helper, callback
+  replay, fraud reporting (with `flag_fraud` / `clear_fraud` wrappers), and the
+  four services endpoints.
+- Internal JWT authentication with a thread-safe cache and a single automatic
+  refresh on 401.
+- Typed error hierarchy under `SmileID::Errors`, covering both API error body
+  shapes.
+- Automatic retries with exponential backoff and `Retry-After` support for
+  idempotent calls only.
+- Consent builder and client-side validation for user details and fraud
+  reports.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Smile Identity Limited
+
+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,320 @@
+# usesmileid
+
+[![Gem Version](https://img.shields.io/gem/v/usesmileid.svg)](https://rubygems.org/gems/usesmileid)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Smile ID server-side SDK for Ruby, covering the V3 APIs.
+
+The SDK handles authentication, request serialization, retries and typed errors so you can call Smile ID from Ruby with plain method calls. You never handle tokens yourself.
+
+Requires Ruby 3.0 or later.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "usesmileid"
+```
+
+Or install it directly:
+
+```bash
+gem install usesmileid
+```
+
+## Getting started
+
+Construct one client with your partner id and API key. The client is thread-safe and can be shared across your application.
+
+```ruby
+require "usesmileid"
+
+smile = SmileID::Client.new(
+  partner_id: "1234",
+  api_key: ENV.fetch("SMILE_API_KEY"),
+  environment: :sandbox,                              # default
+  default_callback_url: "https://app.example.com/cb"  # optional
+)
+```
+
+Partner ids are displayed zero-padded (for example 002) but must be passed without leading zeros (2).
+
+Authentication is internal: the SDK fetches a short-lived token from the API, caches it until just before expiry, and refreshes it once automatically if a request returns 401. You never see or pass a token.
+
+### Environment selection
+
+The client uses the sandbox by default. Set `environment: :production` to go live. Only `:sandbox` and `:production` are named.
+
+| Environment | Base URL |
+|---|---|
+| `:sandbox` (default) | `https://testapi.smileidentity.com` |
+| `:production` | `https://api.smileidentity.com` |
+
+Any other host needs an explicit `base_url:`, which wins over `environment`:
+
+```ruby
+smile = SmileID::Client.new(
+  partner_id: "2",
+  api_key: ENV.fetch("SMILE_API_KEY"),
+  base_url: "https://your-environment.example.com"
+)
+```
+
+A custom `base_url` must be an absolute https URL with no query string or fragment. There is deliberately no way to use plain http. Callback URLs (`default_callback_url` and any per-request `callback_url`) must also be https; an insecure callback raises a validation error before any request is sent.
+
+Non-production environments match test identities on given names + last name + email; an unrecognised identity resolves to `block`.
+
+### Other client options
+
+| Option | Default | Purpose |
+|---|---|---|
+| `timeout` | 30 | Per-request timeout in seconds. Every method also accepts a per-call `timeout:` override. |
+| `max_retries` | 2 | Retries for idempotent calls only (status and services reads, and the internal token fetch). Job submissions are never retried automatically. |
+| `http_client` | SDK default | Inject your own `Faraday::Connection` for testing or proxies. |
+
+## Shared inputs
+
+All verification submissions need consent and user details.
+
+```ruby
+consent = SmileID::Consent.granted(
+  granted_at: Time.now.utc,
+  notice_language: "EN",
+  notice_privacy_policy_url: "https://example.com/privacy"
+)
+
+user_details = {
+  given_names: "John",
+  last_name: "Doe",
+  email: "john@example.com"   # at least one of email / phone_number is required
+}
+```
+
+Image inputs accept a file path (`"selfie.jpg"`), raw bytes, an IO object, or a hash such as `{ path: "front.png", content_type: "image/png" }`.
+
+## Methods
+
+### Enhanced KYC
+
+```ruby
+accepted = smile.enhanced_kyc.verify(
+  country: "NG",
+  id_type: "NIN",
+  id_number: "12345678901",
+  user_details: user_details,
+  consent: consent,
+  user_id: "user_01h8x9y2z3a4b5c6d7e8f9g0h1"  # optional
+)
+accepted.job_id     # => "job_..."
+accepted.accepted?  # => true
+```
+
+### Document verification
+
+```ruby
+accepted = smile.documents.verify(
+  selfie_image: "selfie.jpg",
+  liveness_images: ["live1.jpg", "live2.jpg", "live3.jpg",
+                    "live4.jpg", "live5.jpg", "live6.jpg"],
+  document: "doc_front.jpg",
+  document_back: "doc_back.jpg",  # optional
+  country: "NG",
+  user_details: user_details,
+  consent: consent
+)
+```
+
+### Enhanced document verification
+
+Same shape as document verification, but `id_type` is required.
+
+```ruby
+accepted = smile.documents.verify_enhanced(
+  id_type: "PASSPORT",
+  selfie_image: "selfie.jpg",
+  liveness_images: ["live1.jpg", "live2.jpg", "live3.jpg",
+                    "live4.jpg", "live5.jpg", "live6.jpg"],
+  document: "doc_front.jpg",
+  country: "NG",
+  user_details: user_details,
+  consent: consent
+)
+```
+
+### Biometric KYC
+
+```ruby
+accepted = smile.biometric_kyc.verify(
+  selfie_image: "selfie.jpg",
+  liveness_images: ["live1.jpg", "live2.jpg", "live3.jpg",
+                    "live4.jpg", "live5.jpg", "live6.jpg"],
+  country: "NG",
+  id_type: "NIN",
+  id_number: "12345678901",
+  user_details: user_details,
+  consent: consent
+)
+```
+
+### Biometric enrollment
+
+```ruby
+accepted = smile.biometric.enroll(
+  selfie_image: "selfie.jpg",
+  liveness_images: ["live1.jpg", "live2.jpg", "live3.jpg",
+                    "live4.jpg", "live5.jpg", "live6.jpg"],
+  user_details: user_details,
+  consent: consent,
+  user_id: "user-42"  # optional partner-provided id
+)
+```
+
+### Biometric authentication
+
+`user_id` is required and must match an enrolled user. Images are required unless you set `use_enrolled_image: true`.
+
+```ruby
+accepted = smile.biometric.authenticate(
+  user_id: "user-42",
+  selfie_image: "selfie.jpg",
+  liveness_images: ["live1.jpg", "live2.jpg", "live3.jpg",
+                    "live4.jpg", "live5.jpg", "live6.jpg"],
+  user_details: user_details,
+  consent: consent
+)
+```
+
+### Biometric compare
+
+```ruby
+accepted = smile.biometric.compare(
+  selfie_image: "selfie.jpg",
+  comparison_image: "id_photo.jpg",
+  comparison_image_type: "ID_PHOTO",  # DOCUMENT | ID_PHOTO | PORTRAIT
+  user_details: user_details,
+  consent: consent
+)
+```
+
+### Check a verification's status
+
+```ruby
+status = smile.verifications.retrieve("job_01h8x9y2z3a4b5c6d7e8f9g0h1")
+status.status      # "processing", "not_found", or the decision: "clear", "block", "attention", "error"
+status.complete?   # true when terminal, i.e. neither processing nor not_found
+status.message     # e.g. "Job completed"
+```
+
+A job the API does not know yet returns a status of `not_found` rather than raising an error, so you can poll safely right after submission.
+
+### Wait for a verification to complete
+
+```ruby
+status = smile.verifications.wait_until_complete(
+  "job_01h8x9y2z3a4b5c6d7e8f9g0h1",
+  interval: 2,   # seconds between polls (default 2)
+  timeout: 60    # give up after this many seconds (default 60)
+)
+```
+
+Polling stops as soon as the job reaches a terminal decision (`clear`, `block`, `attention` or `error`). Raises `SmileID::Errors::TimeoutError` if the job does not complete in time. Pass `treat_not_found_as_pending: false` to return immediately when the job is unknown instead of polling on.
+
+### Replay a callback
+
+```ruby
+smile.verifications.replay(
+  "job_01h8x9y2z3a4b5c6d7e8f9g0h1",
+  callback_url: "https://app.example.com/cb"  # optional override
+)
+```
+
+Replaying a job that is still processing raises `SmileID::Errors::ConflictError`.
+
+### Report user fraud
+
+```ruby
+smile.users.report_fraud(
+  "user-42",
+  is_fraud: true,
+  reason: "ACCOUNT_TAKEOVER",
+  reported_by: "risk@example.com"
+)
+```
+
+Or use the convenience wrappers:
+
+```ruby
+smile.users.flag_fraud("user-42", reason: "ACCOUNT_TAKEOVER", reported_by: "risk@example.com")
+smile.users.clear_fraud("user-42", notes: "Cleared after review", reported_by: "risk@example.com")
+```
+
+When flagging, `reason` is required (and `notes` too if the reason is `OTHER`). When clearing, `notes` is required.
+
+### Services
+
+Bank codes, supported ID types and supported documents need no authentication.
+
+```ruby
+smile.services.bank_codes(country: "NG").bank_codes
+# => [{ "code" => "044", "country" => "NG", "name" => "Access Bank" }, ...]
+
+smile.services.supported_id_types(country: "NG").id_types
+# => [{ "country" => "NG", "type" => "BVN", "label" => ..., "regex" => ..., ... }, ...]
+
+smile.services.supported_documents(country_code: "NG").valid_documents
+# => [{ "country" => { "code" => "NG", ... }, "id_types" => [...] }, ...]
+
+smile.services.id_status(country: "NG", id_type: "BVN")
+# => #<IdStatusResponse last_known_status="online" last_hour_success_rate="95%" ...>
+```
+
+## Error handling
+
+Every API failure raises a typed error under `SmileID::Errors`, keyed on the HTTP status:
+
+| Error | Raised on |
+|---|---|
+| `InvalidRequestError` | 400, 415, and failed client-side validation (`ValidationError` subclass) |
+| `AuthenticationError` | 401 after one automatic token refresh |
+| `PaymentRequiredError` | 402 — insufficient wallet balance |
+| `PermissionError` | 403 |
+| `NotFoundError` | 404 (except `verifications.retrieve`, which returns a `not_found` status) |
+| `ConflictError` | 409 — for example replaying a job that is still processing |
+| `PayloadTooLargeError` | 413 |
+| `RateLimitError` | 429 |
+| `APIError` | any 5xx |
+| `ConnectionError` | network failure or timeout with no HTTP response |
+| `TimeoutError` | `wait_until_complete` deadline passed (no HTTP response) |
+| `UnexpectedResponseError` | a 2xx response whose body is not the expected JSON object, for example proxy interference |
+
+Each error exposes `status_code`, `status`, `message`, `code`, `request_id` and `raw_body`.
+
+```ruby
+begin
+  smile.enhanced_kyc.verify(...)
+rescue SmileID::Errors::PaymentRequiredError => e
+  e.status_code  # 402
+  e.message      # "Insufficient wallet balance."
+rescue SmileID::Errors::SmileIDError => e
+  # catch-all for anything the API raised
+end
+```
+
+## Telemetry
+
+The SDK sends three telemetry headers on every request: `SmileID-Source-SDK` (`ruby`), `SmileID-Source-SDK-Version` and a `User-Agent` identifying the SDK and Ruby version. These identify the SDK for observability. They are never used for authentication and carry no personal data.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec     # unit tests, fully offline
+bundle exec rubocop
+```
+
+The end-to-end sandbox test runs only when `SMILE_PARTNER_ID` and `SMILE_API_KEY` are set in the environment; otherwise it skips. Set `SMILE_BASE_URL` to run it against a host other than the sandbox.
+
+## Contributing
+
+See [SECURITY.md](SECURITY.md) for how to report a security issue.

data/lib/usesmileid/client/auth.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'json'
+
+module SmileID
+  # Internal JWT lifecycle (spec section 2.3, 2A). Partners never see the token.
+  #
+  # The cache is thread-safe: concurrent calls do not stampede the token
+  # endpoint. The token is cached until its JWT `exp` claim minus a 60s skew; a
+  # token whose expiry cannot be decoded is treated as single-use (refreshed on
+  # the next call, and always on a 401).
+  class TokenManager
+    EXPIRY_SKEW = 60
+
+    def initialize(config, transport)
+      @config = config
+      @transport = transport
+      @mutex = Mutex.new
+      @cached = nil
+    end
+
+    # Return a valid token, fetching one if the cache is empty or expired.
+    def token
+      @mutex.synchronize do
+        return @cached[:jwt] if valid?
+
+        fetch
+      end
+    end
+
+    # Force a refresh (used after a 401). Fetches a new token unconditionally.
+    def force_refresh
+      @mutex.synchronize do
+        @cached = nil
+        fetch
+      end
+    end
+
+    private
+
+    def valid?
+      @cached && Time.now < @cached[:expires_at]
+    end
+
+    def fetch
+      response = @transport.send_request(
+        method: :post,
+        url: "#{@config.base_url}/v3/token",
+        headers: Telemetry.headers.merge(
+          'smileid-partner-id' => @config.partner_id,
+          'smileid-api-key' => @config.api_key
+        ),
+        query: {},
+        body: nil,
+        retryable: true
+      )
+
+      unless response.status == 200
+        raise Errors.from_response(
+          status_code: response.status,
+          body: response.json,
+          raw_body: response.raw_body,
+          headers: response.headers
+        )
+      end
+
+      jwt = response.json && response.json['token']
+      raise Errors::AuthenticationError.new('token endpoint returned no token') if jwt.nil?
+
+      @cached = { jwt: jwt, expires_at: expires_at(jwt) }
+      jwt
+    end
+
+    def expires_at(jwt)
+      exp = decode_exp(jwt)
+      exp ? Time.at(exp) - EXPIRY_SKEW : Time.now
+    end
+
+    # Decode the `exp` claim from a JWT without verifying the signature. Returns
+    # nil when the token cannot be decoded.
+    def decode_exp(jwt)
+      payload_segment = jwt.to_s.split('.')[1]
+      return nil if payload_segment.nil?
+
+      payload = JSON.parse(Base64.urlsafe_decode64(pad(payload_segment)))
+      exp = payload['exp']
+      exp.is_a?(Numeric) ? exp : nil
+    rescue ArgumentError, JSON::ParserError
+      nil
+    end
+
+    def pad(segment)
+      remainder = segment.length % 4
+      remainder.zero? ? segment : segment + ('=' * (4 - remainder))
+    end
+  end
+end

data/lib/usesmileid/client/client.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'json'
+
+module SmileID
+  # The Smile ID client (spec section 2.1, 4). Construct once, then call
+  # resource verbs, e.g. client.enhanced_kyc.verify(...).
+  class Client
+    attr_reader :config
+
+    def initialize(partner_id:, api_key:, environment: :sandbox,
+                   default_callback_url: nil, base_url: nil, timeout: Config::DEFAULT_TIMEOUT,
+                   max_retries: Config::DEFAULT_MAX_RETRIES, http_client: nil)
+      @config = Config.new(
+        partner_id: partner_id, api_key: api_key, environment: environment,
+        default_callback_url: default_callback_url,
+        base_url: base_url, timeout: timeout, max_retries: max_retries, http_client: http_client
+      )
+      @transport = Transport.new(@config)
+      @token_manager = TokenManager.new(@config, @transport)
+    end
+
+    def enhanced_kyc
+      @enhanced_kyc ||= Resources::EnhancedKyc.new(self)
+    end
+
+    def documents
+      @documents ||= Resources::Documents.new(self)
+    end
+
+    def biometric_kyc
+      @biometric_kyc ||= Resources::BiometricKyc.new(self)
+    end
+
+    def biometric
+      @biometric ||= Resources::Biometric.new(self)
+    end
+
+    def verifications
+      @verifications ||= Resources::Verifications.new(self)
+    end
+
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+
+    def services
+      @services ||= Resources::Services.new(self)
+    end
+
+    # Execute an operation end to end: build the request, attach auth and
+    # telemetry, sign if configured, send it, refresh-on-401 once, and either
+    # return the response or raise a typed error (spec section 2A, 7).
+    #
+    # @return [SmileID::Response] on a success status for the operation.
+    def call(op_key, form: nil, path_params: {}, query: {}, user_id_header: nil, timeout: nil)
+      op = Generated::Operations.fetch(op_key)
+      url = @config.base_url + interpolate(op.path, path_params)
+      content_type, body = serialize(op, form)
+      refreshed = false
+
+      loop do
+        headers = build_headers(op, content_type, user_id_header)
+        response = @transport.send_request(
+          method: op.http_method, url: url, headers: headers, query: query || {},
+          body: body, retryable: op.idempotent, timeout: timeout
+        )
+
+        if response.status == 401 && op.authenticated && !refreshed
+          @token_manager.force_refresh
+          refreshed = true
+          next
+        end
+
+        return handle(op, response)
+      end
+    end
+
+    private
+
+    # Multipart bodies only; an op with an optional body (replay) sends no
+    # body at all when there are no fields.
+    def serialize(op, form)
+      return [nil, nil] unless op.body_kind == :multipart
+      return [nil, nil] if form.nil? || form.empty?
+
+      Helpers::Multipart.build(form)
+    end
+
+    def build_headers(op, content_type, user_id_header)
+      headers = Telemetry.headers
+      headers['Content-Type'] = content_type if content_type
+      headers['SmileID-Token'] = @token_manager.token if op.authenticated
+      headers['SmileID-Partner-ID'] = @config.partner_id if op.partner_id_header
+      headers['User-ID'] = user_id_header if user_id_header
+      headers
+    end
+
+    def handle(op, response)
+      if op.success_statuses.include?(response.status)
+        return response if response.json.is_a?(Hash)
+
+        raise Errors::UnexpectedResponseError.new(
+          'expected a JSON object response body',
+          status_code: response.status,
+          request_id: Errors.request_id_from(response.headers),
+          raw_body: response.raw_body
+        )
+      end
+
+      raise Errors.from_response(
+        status_code: response.status,
+        body: response.json,
+        raw_body: response.raw_body,
+        headers: response.headers
+      )
+    end
+
+    def interpolate(path, path_params)
+      path.gsub(/\{(\w+)\}/) do
+        key = Regexp.last_match(1)
+        value = path_params[key] || path_params[key.to_sym]
+        raise ArgumentError, "missing path parameter: #{key}" if value.nil?
+
+        ERB::Util.url_encode(value.to_s)
+      end
+    end
+  end
+end