usesmileid 12.1.0 → 13.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 896bc049c137997c9de0181582b1bb2564e96fbba5bbbac64b640363e7f472b2
-  data.tar.gz: 7f8bda781a38427a40550e95af93dc0286523b2b41e30a0cc37ef482b6752b8b
+  metadata.gz: f64d6fd177105edbffe5bceac374c675140d49a0da20d8e56041ae156429dda3
+  data.tar.gz: 810132bb74281566a6957f2ae76dd647d0e685f1423a71db26780dbf9351076f
 SHA512:
-  metadata.gz: e0e6772c8b7f6466b8807943dbda2cc72e8e52564ffe745faf9b9bc5cb2623dd43ecae662fab88974ecb98ae780fd713cacc11014bd23157e458b10c5709f17f
-  data.tar.gz: 94a7ac44229e2d2e43c722a2113a72d589db9a8242ca5f4ec7b1febd7828f35841d15fe1183c713bd91468e45d569f1403a6f392d7f96b13d82e8f00a6ee7fc8
+  metadata.gz: 856a7d6b04e054b1084d21dd35822274c2f0fcced663944ad01b6c6446df160e1f58237a5686c9f0824bd64e6cdf9de32b9b131fd1db68d4f34287998a9da0f4
+  data.tar.gz: 306285d436a657d8bbafe633b101cebb9f5e6e955b2fe60029d6ff08e3cc0c5665fb58edfa78037323f7f23563897012e4fff02fd7b2d6810cb01c5b2f6bb427

data/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [13.0.0] - 2026-11-09
+
+Version 12.2.0 was never published. Its changes are in this release, which is a major version because it breaks the 12.1.0 API.
+
+### Breaking changes
+
+- `biometric.authenticate` no longer takes `use_enrolled_image:`. Use `biometric_kyc.verify(use_enrolled_image: true, user_id: ...)` instead.
+- `biometric.authenticate` now requires `selfie_image:` and `liveness_images:`. Pass both on every call.
+- `SmileID::TokenManager` has been removed. The client now mints a token for each request, so you do not need to manage tokens.
+
+### Changed
+
+- Each request mints its own token, bound to that request's `user_id` and product, instead of reusing one cached token. A 401 is no longer retried with a refreshed token.
+- A `user_id` that is empty or padded with whitespace raises `ValidationError` before any request is sent.
+- `biometric.authenticate` takes `selfie_image:` and `liveness_images:` as required keywords.
+
+### Added
+
+- `biometric_kyc.verify(use_enrolled_image: true, user_id: ...)` verifies against the user's enrolled selfie; the grant is bound into the job's token and the selfie and liveness images may be omitted.
+
+### Removed
+
+- `use_enrolled_image` from `biometric.authenticate`; selfie and liveness images are now always required.
+
 ## [12.1.0] - 2026-10-01
 
 ### Added
@@ -41,6 +65,7 @@ First public release.
 - Typed errors under `SmileID::Errors`, keyed on HTTP status.
 - Bank codes, supported ID types and supported documents lookups.
 
-[Unreleased]: https://github.com/smileidentity/smileid-sdk-ruby/compare/v12.1.0...HEAD
+[Unreleased]: https://github.com/smileidentity/smileid-sdk-ruby/compare/v13.0.0...HEAD
+[13.0.0]: https://github.com/smileidentity/smileid-sdk-ruby/compare/v12.1.0...v13.0.0
 [12.1.0]: https://github.com/smileidentity/smileid-sdk-ruby/compare/v12.0.0...v12.1.0
 [12.0.0]: https://github.com/smileidentity/smileid-sdk-ruby/releases/tag/v12.0.0

data/README.md

@@ -40,7 +40,7 @@ smile = SmileID::Client.new(
 
 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.
+Authentication is internal: before each request the SDK fetches a short-lived token from the API. A job's token is bound to that job's product and, when the job names one, its user; other calls get a token with neither. A 401 raises `AuthenticationError` without a retry. You never see or pass a token.
 
 ### Environment selection
 
@@ -177,6 +177,20 @@ accepted = smile.biometric_kyc.verify(
 )
 ```
 
+To verify against a user's enrolled selfie instead of a fresh capture, set `use_enrolled_image: true` and pass the enrolled `user_id`; the selfie and liveness images may then be omitted.
+
+```ruby
+accepted = smile.biometric_kyc.verify(
+  use_enrolled_image: true,
+  user_id: "user-42",
+  country: "NG",
+  id_type: "NIN",
+  id_number: "12345678901",
+  user_details: user_details,
+  consent: consent
+)
+```
+
 ### Biometric enrollment
 
 ```ruby
@@ -192,7 +206,7 @@ accepted = smile.biometric.enroll(
 
 ### Biometric authentication
 
-`user_id` is required and must match an enrolled user. Images are required unless you set `use_enrolled_image: true`.
+`user_id` is required and must match an enrolled user. The selfie and liveness images are always required.
 
 ```ruby
 accepted = smile.biometric.authenticate(
@@ -296,7 +310,7 @@ Every API failure raises a typed error under `SmileID::Errors`, keyed on the HTT
 | Error | Raised on |
 |---|---|
 | `InvalidRequestError` | 400, 415, and failed client-side validation (`ValidationError` subclass) |
-| `AuthenticationError` | 401 after one automatic token refresh |
+| `AuthenticationError` | 401 |
 | `PaymentRequiredError` | 402 — insufficient wallet balance |
 | `PermissionError` | 403 |
 | `NotFoundError` | 404 (except `verifications.retrieve`, which returns a `not_found` status) |

data/lib/usesmileid/client/client.rb

@@ -7,6 +7,19 @@ 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
+    # Mirrors the API authorizer: a token bound to a product is accepted only on
+    # that product's endpoint. Paths absent here mint a token with no claims.
+    PRODUCT_BY_PATH = {
+      '/v3/enhanced_kyc' => 'enhanced_kyc',
+      '/v3/document_verification' => 'document_verification',
+      '/v3/enhanced_document_verification' => 'enhanced_document_verification',
+      '/v3/residency_document_verification' => 'residency_document_verification',
+      '/v3/biometric_kyc' => 'biometric_kyc',
+      '/v3/registration' => 'smart_selfie_registration',
+      '/v3/authentication' => 'smart_selfie_authentication',
+      '/v3/compare' => 'smart_selfie_compare'
+    }.freeze
+
     attr_reader :config
 
     def initialize(partner_id:, api_key:, environment: :sandbox,
@@ -18,7 +31,6 @@ module SmileID
         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
@@ -49,32 +61,25 @@ module SmileID
       @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).
+    # Execute an operation end to end: mint its token, build the request, attach
+    # auth and telemetry, send it, and either return the response or raise a
+    # typed error (spec section 2A, 7). Every authenticated call mints its own
+    # token; retries of an idempotent call reuse it.
     #
     # @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)
+    def call(op_key, form: nil, path_params: {}, query: {}, user_id_header: nil, timeout: nil,
+             use_enrolled_image: false)
       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
-        )
+      token = mint_token(op, form, user_id_header, use_enrolled_image, timeout) if op.authenticated
 
-        if response.status == 401 && op.authenticated && !refreshed
-          @token_manager.force_refresh
-          refreshed = true
-          next
-        end
-
-        return handle(op, response)
-      end
+      headers = build_headers(op, content_type, user_id_header, token)
+      response = @transport.send_request(
+        method: op.http_method, url: url, headers: headers, query: query || {},
+        body: body, retryable: op.idempotent, timeout: timeout
+      )
+      handle(op, response)
     end
 
     private
@@ -88,15 +93,86 @@ module SmileID
       Helpers::Multipart.build(form)
     end
 
-    def build_headers(op, content_type, user_id_header)
+    def build_headers(op, content_type, user_id_header, token)
       headers = Telemetry.headers
       headers['Content-Type'] = content_type if content_type
-      headers['SmileID-Token'] = @token_manager.token if op.authenticated
+      headers['SmileID-Token'] = token if token
       headers['SmileID-Partner-ID'] = @config.partner_id if op.partner_id_header
       headers['User-ID'] = user_id_header if user_id_header
       headers
     end
 
+    # The token is bound to this one request's user and product. A grant
+    # (use_enrolled_image) authorises a captureless job for one user, so it must
+    # never reach another call's token.
+    def mint_token(op, form, user_id_header, use_enrolled_image, timeout)
+      product = PRODUCT_BY_PATH[op.path]
+      user_id = job_user_id(form, user_id_header) if product
+      if use_enrolled_image && user_id.nil?
+        raise Errors::ValidationError.new('user_id is required when use_enrolled_image is true')
+      end
+
+      claims = { 'user_id' => user_id, 'product' => product,
+                 'use_enrolled_image' => (true if use_enrolled_image) }.compact
+      request_token(claims, timeout)
+    end
+
+    def request_token(claims, timeout)
+      content_type, body = Helpers::Multipart.build(claims) unless claims.empty?
+      response = @transport.send_request(
+        method: :post,
+        url: "#{@config.base_url}/v3/token",
+        headers: token_headers(content_type),
+        body: body,
+        retryable: true,
+        timeout: timeout
+      )
+
+      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']
+      if jwt.nil? || jwt.to_s.empty?
+        raise Errors::UnexpectedResponseError.new(
+          'token endpoint returned no token',
+          status_code: response.status,
+          request_id: Errors.request_id_from(response.headers),
+          raw_body: response.raw_body
+        )
+      end
+
+      jwt
+    end
+
+    # The API trims the User-ID header but not the token's user_id claim, so a
+    # padded id would mint a token for a different user than the job names.
+    def job_user_id(form, user_id_header)
+      user_id = user_id_header.nil? ? form && form['user_id'] : user_id_header
+      return nil if user_id.nil?
+
+      text = user_id.to_s
+      if text.empty? || text != text.strip
+        raise Errors::ValidationError.new('user_id must not be empty or padded with whitespace')
+      end
+
+      user_id
+    end
+
+    def token_headers(content_type)
+      headers = Telemetry.headers.merge(
+        'smileid-partner-id' => @config.partner_id,
+        'smileid-api-key' => @config.api_key
+      )
+      headers['Content-Type'] = content_type if content_type
+      headers
+    end
+
     def handle(op, response)
       if op.success_statuses.include?(response.status)
         return response if response.json.is_a?(Hash)

data/lib/usesmileid/client/resources.rb

@@ -29,6 +29,13 @@ module SmileID
         callback_url || @client.config.default_callback_url
       end
 
+      def require_images!(selfie_image, liveness_images, condition = nil)
+        return unless selfie_image.nil? || liveness_images.nil? || Array(liveness_images).empty?
+
+        message = ['selfie_image and liveness_images are required', condition].compact.join(' ')
+        raise Errors::ValidationError.new(message)
+      end
+
       def accepted(response)
         Generated::Models::AcceptedResponse.from(response.json)
       end
@@ -133,9 +140,24 @@ module SmileID
 
     # POST /v3/biometric_kyc
     class BiometricKyc < Base
-      def verify(selfie_image:, liveness_images:, consent:, country:, id_type:, id_number:,
-                 user_details:, callback_url: nil, sandbox_result: nil,
+      # With use_enrolled_image: true the job verifies against user_id's enrolled
+      # selfie, so the images may be omitted. The grant is bound into this job's
+      # token, never sent in the body.
+      def verify(consent:, country:, id_type:, id_number:, user_details:,
+                 selfie_image: nil, liveness_images: nil, use_enrolled_image: false,
+                 callback_url: nil, sandbox_result: nil,
                  partner_params: nil, metadata: nil, user_id: nil, timeout: nil)
+        unless [true, false].include?(use_enrolled_image)
+          raise Errors::ValidationError.new('use_enrolled_image must be true or false')
+        end
+
+        if use_enrolled_image
+          if user_id.to_s.strip.empty?
+            raise Errors::ValidationError.new('user_id is required when use_enrolled_image is true')
+          end
+        else
+          require_images!(selfie_image, liveness_images, 'unless use_enrolled_image is true')
+        end
         form = {
           'country' => country,
           'id_type' => id_type,
@@ -149,7 +171,8 @@ module SmileID
           'partner_params' => partner_params,
           'metadata' => metadata
         }.compact
-        accepted(@client.call(:biometric_kyc, form: form, user_id_header: user_id, timeout: timeout))
+        accepted(@client.call(:biometric_kyc, form: form, user_id_header: user_id, timeout: timeout,
+                                              use_enrolled_image: use_enrolled_image))
       end
     end
 
@@ -173,17 +196,16 @@ module SmileID
       end
 
       # user_id goes in the BODY here (required), not the User-ID header.
-      def authenticate(user_id:, consent:, user_details:, selfie_image: nil, liveness_images: nil,
-                       use_enrolled_image: nil, callback_url: nil, sandbox_result: nil,
+      def authenticate(user_id:, consent:, user_details:, selfie_image:, liveness_images:,
+                       callback_url: nil, sandbox_result: nil,
                        partner_params: nil, metadata: nil, timeout: nil)
-        require_images!(use_enrolled_image, selfie_image, liveness_images)
+        require_images!(selfie_image, liveness_images)
         form = {
           'user_id' => user_id,
           'selfie_image' => selfie_image,
           'liveness_images' => liveness_images,
           'user_details' => coerce_user_details(user_details),
           'consent' => coerce_consent(consent),
-          'use_enrolled_image' => use_enrolled_image,
           'callback_url' => resolve_callback(callback_url),
           'sandbox_result' => sandbox_result,
           'partner_params' => partner_params,
@@ -212,17 +234,6 @@ module SmileID
         }.compact
         accepted(@client.call(:compare, form: form, timeout: timeout))
       end
-
-      private
-
-      def require_images!(use_enrolled_image, selfie_image, liveness_images)
-        return if use_enrolled_image == true
-        return unless selfie_image.nil? || liveness_images.nil? || Array(liveness_images).empty?
-
-        raise Errors::ValidationError.new(
-          'selfie_image and liveness_images are required unless use_enrolled_image is true'
-        )
-      end
     end
 
     # GET /v3/status, POST /v3/replay, plus the wait_until_complete poll helper.

data/lib/usesmileid/client/transport.rb

@@ -36,7 +36,7 @@ module SmileID
   # The single HTTP transport (spec section 2.2, 2.6). Builds the Faraday
   # request, sends it, retries idempotent operations on transient failures
   # honouring Retry-After, and normalizes the response. It does not touch auth;
-  # the client injects tokens and handles the refresh-on-401 dance.
+  # the client mints and injects tokens.
   class Transport
     RETRY_STATUSES = [408, 429, 500, 502, 503, 504].freeze
     BACKOFF_BASE = 0.5

data/lib/usesmileid/errors.rb

@@ -39,7 +39,7 @@ module SmileID
     # Raised before send when a local validation rule fails (spec section 5.1, 6.11).
     class ValidationError < InvalidRequestError; end
 
-    # 401 — token missing, invalid, or expired after a single refresh attempt.
+    # 401 — token missing, invalid or expired.
     class AuthenticationError < SmileIDError; end
 
     # 402 — insufficient wallet balance.

data/lib/usesmileid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SmileID
-  VERSION = '12.1.0'
+  VERSION = '13.0.0'
 end

data/lib/usesmileid.rb

@@ -9,7 +9,6 @@ require 'usesmileid/helpers/user_details'
 require 'usesmileid/helpers/multipart'
 require 'usesmileid/client/config'
 require 'usesmileid/client/transport'
-require 'usesmileid/client/auth'
 require 'usesmileid/client/resources'
 require 'usesmileid/client/client'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: usesmileid
 version: !ruby/object:Gem::Version
-  version: 12.1.0
+  version: 13.0.0
 platform: ruby
 authors:
 - Smile Identity
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-11-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -49,7 +49,6 @@ files:
 - LICENSE
 - README.md
 - lib/usesmileid.rb
-- lib/usesmileid/client/auth.rb
 - lib/usesmileid/client/client.rb
 - lib/usesmileid/client/config.rb
 - lib/usesmileid/client/resources.rb

data/lib/usesmileid/client/auth.rb

@@ -1,98 +0,0 @@
-# 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