didit-sdk 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4537c78240a3127727b1208e521b36f946950a9b6a168687ec9c95966834f5ee
+  data.tar.gz: 8946035f920824815b730d9903962b98e991a9540b8e4acacdb628a8b3a475a5
+SHA512:
+  metadata.gz: 62db2a22d9e118145679b32b4d6f82cfee433e46636296d43da9f374968222fcefa44a7b8d04a1ead2c43a8c97bc939f5686884b8a62e09c2a6e99fcda274e44
+  data.tar.gz: 2d7e3ad74748b9996661bdde816fee61e2fbb7265141518dedef948b9638c4725e2eb3fdbda5d658cec7293c5eaee69d506232e4b48a2eedeb2cc9cf946157cc

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [1.0.0](https://github.com/didit-protocol/sdk-ruby/compare/v0.1.0...v1.0.0) (2026-10-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* **spec:** the API spec sync changes the SDK surface (nullable fields, removed fields, account.organizations.list returns a page, the session decision response is the SessionDecision component).
+
+### Features
+
+* add bank.account_check (POST /v3/bank/account-check/) and bank_verifications on the decision ([de3a7b8](https://github.com/didit-protocol/sdk-ruby/commit/de3a7b85d29409df6e8a4eeef793c4fbe00a0904))
+* **spec:** sync API spec 2026-10-23 ([#4](https://github.com/didit-protocol/sdk-ruby/issues/4)) ([ce9061c](https://github.com/didit-protocol/sdk-ruby/commit/ce9061c3056274319f5ab9325dba5c8439cc048a))
+* **spec:** sync API spec 2026-10-27 ([#13](https://github.com/didit-protocol/sdk-ruby/issues/13)) ([a7ab2a9](https://github.com/didit-protocol/sdk-ruby/commit/a7ab2a9624d64dfda1c3fa2fb03cd93605523fee))
+
+
+### API Spec Updates
+
+* **spec:** sync API spec 2026-10-25 ([#8](https://github.com/didit-protocol/sdk-ruby/issues/8)) ([2e941a5](https://github.com/didit-protocol/sdk-ruby/commit/2e941a58a29b950f066e9d879f77342a715e9cae))
+* **spec:** sync API spec 2026-10-29 ([#15](https://github.com/didit-protocol/sdk-ruby/issues/15)) ([468dbfc](https://github.com/didit-protocol/sdk-ruby/commit/468dbfc3137c4a84021ce1f51a04c2a689b668bd))
+
+
+### Miscellaneous Chores
+
+* release 1.0.0 ([b183cb4](https://github.com/didit-protocol/sdk-ruby/commit/b183cb463fc00c66d15ab6403f2ecb79c58b49a5))

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Didit
+
+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,277 @@
+# Didit Ruby SDK
+
+The official [Didit](https://didit.me) Ruby library.
+Identity verification (KYC), business verification (KYB), AML screening, biometrics, transaction monitoring, Travel Rule and customer authentication, from your backend.
+
+> In development. Not released yet.
+
+- Every Didit server API: sessions, standalone checks, KYB, users and businesses, workflows, webhooks, cases, transactions, wallet screening, Travel Rule and account management.
+- Typed results with RBS signatures (checked with Steep), generated from the [OpenAPI contract](openapi/).
+- Webhook verification and Didit Authentication (OpenID Connect) token verification built in.
+- Standard library `net/http` with persistent connections, retries and timeouts. The only dependency is `jwt`, and only the Authentication module loads it.
+
+## Install
+
+```ruby
+# Gemfile
+gem "didit-sdk"
+```
+
+```sh
+gem install didit-sdk
+```
+
+```ruby
+require "didit"
+```
+
+Ruby 3.1 or newer (tested on 3.1, 3.2, 3.3, 3.4 and 4.0).
+
+## Quickstart
+
+Create a session, send the user to its URL, read the decision and verify the webhook Didit sends when it changes.
+
+```ruby
+require "didit"
+
+didit = Didit::Client.new # reads DIDIT_API_KEY
+
+session = didit.sessions.create(workflow_id: "your-workflow-id", vendor_data: "user-42")
+redirect_to session.url
+
+decision = didit.sessions.retrieve_decision(session.session_id)
+decision.status # => "Approved", "Declined", "In Review", ...
+decision.id_verifications&.first&.first_name
+
+# In your webhook endpoint (Rails), with the raw body:
+event = didit.webhooks.verify(request.raw_post, request.headers, ENV.fetch("DIDIT_WEBHOOK_SECRET"))
+case event
+in Didit::Webhooks::StatusUpdatedEvent(status: "Approved", session_id:) then approve(session_id)
+in Didit::Webhooks::StatusUpdatedEvent then nil
+in Didit::Webhooks::UnknownEvent then nil # a type this SDK version does not know yet
+else nil
+end
+```
+
+[`examples/quickstart.rb`](examples/quickstart.rb) runs the same steps. [`examples/`](examples/) also has standalone ID verification, AML screening, transaction screening, Travel Rule, Authentication, and webhook receivers for Rails, Sinatra and Rack.
+
+## Configuration
+
+```ruby
+didit = Didit::Client.new(
+  api_key: "...",              # default ENV["DIDIT_API_KEY"]
+  organization_id: "...",      # default ENV["DIDIT_ORGANIZATION_ID"]; needed by application-scoped methods
+  application_id: "...",       # default ENV["DIDIT_APPLICATION_ID"]; needed by application-scoped methods
+  base_url: "https://verification.didit.me",
+  account_base_url: "https://apx.didit.me/auth/v2",
+  timeout: 60,                 # seconds per attempt
+  max_retries: 2,
+  default_headers: {},
+  logger: nil,                 # any object with #debug; or DIDIT_LOG=debug for stderr
+  http_client: nil             # ->(uri) { Net::HTTP.new(...) } for proxies or a CA bundle
+)
+```
+
+- One client per process is the intended use. It is thread safe, keeps connections open per host, and a forked child never reuses its parent's connections.
+- `with_options` returns a copy with some options changed that shares the connections: `didit.with_options(timeout: 5, max_retries: 0)`.
+- Every method takes `request_options:` for one call: `{ timeout:, max_retries:, extra_headers:, extra_query:, extra_body: }`.
+- Application-scoped methods (all of `cases`, `networks`, `regulatory_reports`, `report_templates` and `business_sessions`, and some of `sessions`, `users`, `businesses` and `transactions`): the SDK fills `organization_id` and `application_id` from the client, and raises `Didit::ConfigurationError` before sending when either is missing.
+- The API key is sent only to `base_url`. It never appears in logs, error messages or error bodies.
+
+## Making calls
+
+Resources follow the API: `didit.sessions`, `didit.sessions.imports`, `didit.users`, `didit.transactions.rules`, `didit.cases.notes`, and so on.
+Ids in the URL are positional arguments; everything else is a keyword.
+
+```ruby
+didit.users.update("user-42", display_name: "Maria", metadata: { plan: "gold" })
+didit.sessions.update_status(session_id, new_status: "Declined", comment: nil) # nil sends JSON null
+```
+
+A keyword you leave out is not sent. Unknown or missing keywords raise `ArgumentError`, like any Ruby method.
+Nested objects are Hashes with the API's field names, as symbols or strings.
+
+Results are typed objects:
+
+```ruby
+session.session_id         # typed reader
+session[:session_id]       # any field, also ones this SDK version does not know yet
+session.to_h               # the JSON object with symbol keys
+session.created_at         # Time
+```
+
+`didit.with_raw_response` gives the HTTP response behind a result:
+
+```ruby
+raw = didit.with_raw_response.sessions.create(workflow_id: "...")
+raw.status      # => 201
+raw.request_id  # => "..."
+session = raw.parse
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `Didit::DiditError` | base of everything below |
+| `Didit::APIConnectionError` / `Didit::APITimeoutError` | no response |
+| `Didit::APIStatusError` | any non-2xx, with `status`, `body`, `headers`, `request_id` |
+| `BadRequestError` 400, `AuthenticationError` 401, `PermissionDeniedError` 403, `NotFoundError` 404, `ConflictError` 409, `UnprocessableEntityError` 422, `RateLimitError` 429, `InternalServerError` 5xx | subclasses of `APIStatusError` |
+| `Didit::APIResponseValidationError` | a 2xx that is not the documented content, or a pagination link that loops or leaves the API |
+| `Didit::WebhookVerificationError` | webhook verification failed, with a `reason` |
+| `Didit::TokenVerificationError` | an Authentication token failed verification, with a `reason` |
+| `Didit::ConfigurationError` | missing API key or ids, or an invalid argument, before anything is sent |
+
+```ruby
+begin
+  didit.sessions.retrieve_decision(session_id)
+rescue Didit::NotFoundError
+  # ...
+rescue Didit::APIStatusError => e
+  logger.warn("Didit #{e.status}: #{e.message}") # the message ends with the request id
+end
+```
+
+## Retries and timeouts
+
+Failed requests are retried up to `max_retries` times (default 2) with exponential backoff from 0.5 s, full jitter, capped at 8 s, honouring `Retry-After` (capped at 60 s).
+GET, HEAD, PUT and DELETE are retried on connection errors, timeouts, 408, 429 and 5xx.
+POST and PATCH are retried only on 429 and when the connection failed before the request was sent, never after it may have reached the server.
+
+## Pagination
+
+```ruby
+page = didit.sessions.list(limit: 50)
+page.total_count          # the API's count across pages
+page.each { |s| puts s.status } # this page
+page.next_page            # the next Didit::Page, or nil
+
+didit.sessions.list(limit: 50).auto_paging_each { |s| puts s.session_id } # every page, fetched as needed
+```
+
+## Files and binary responses
+
+Upload arguments take a `Pathname`, an `IO` (`File`, `StringIO`, ...), a `String` with the file's bytes, or a `Didit::FilePart` to set the file name and content type:
+
+```ruby
+didit.id_verification.verify(front_image: Pathname("passport.jpg"))
+didit.face_match.compare(user_image: File.open("selfie.jpg", "rb"), ref_image: Didit::FilePart.new(bytes, filename: "ref.png"))
+```
+
+Reports come back as bytes, or in chunks to a block:
+
+```ruby
+pdf = didit.sessions.generate_pdf(session_id)
+File.open("report.pdf", "wb") { |f| didit.sessions.generate_pdf(session_id) { |chunk| f.write(chunk) } }
+```
+
+## Webhooks
+
+```ruby
+event = Didit::Webhooks.verify(raw_body, headers, secret)            # or didit.webhooks.verify(...)
+event = Didit::Webhooks.verify(raw_body, headers, [new_secret, old_secret]) # during a rotation
+```
+
+- Pass the raw request body: `request.raw_post` in Rails, `request.body.read` after `request.body.rewind` in Sinatra (it may have read the body for its params), `env["rack.input"].read` in Rack. Headers can be a Hash in any case, a Rack env or Rails `request.headers`.
+- A delivery is accepted when `X-Signature` matches the body, `X-Signature-V2` matches its canonical JSON, or a `-Previous` variant matches (secret rotation). Timestamps older or newer than `tolerance:` (300 s) are rejected.
+- `verify_parsed(payload, headers, secret)` is for frameworks that only give you the parsed JSON; it can check `X-Signature-V2` only.
+- The deprecated `X-Signature-Simple` counts only with `allow_simple: true`; then `event.body_authenticated?` is false and you should re-fetch the record from the API.
+- Failures raise `Didit::WebhookVerificationError` with `reason`: `:missing_signature`, `:invalid_signature`, `:missing_timestamp`, `:timestamp_mismatch`, `:timestamp_out_of_tolerance` or `:invalid_payload`.
+- Events are typed: `StatusUpdatedEvent`, `DataUpdatedEvent`, `UserStatusUpdatedEvent`, `UserDataUpdatedEvent`, `BusinessStatusUpdatedEvent`, `BusinessDataUpdatedEvent`, `ActivityCreatedEvent`, `TransactionCreatedEvent`, `TransactionStatusUpdatedEvent`, `TravelRuleStatusUpdatedEvent`, `WorkflowComplianceChangedEvent`, `KybRegistrySearchResolvedEvent`, and `UnknownEvent` for anything else. Session events carry the typed `decision`.
+- `kyb.registry_search.resolved` callbacks arrive unsigned, so `verify` rejects them (with `:missing_signature`, or a timestamp reason when their timestamp fails the checks that come first). `Didit::Webhooks.parse_event(JSON.parse(body))` reads one without verifying it; treat it as untrusted and re-fetch the data from the API.
+
+See [`examples/webhooks/`](examples/webhooks/) for Rails, Sinatra and Rack receivers. In a Rails controller that inherits from `ActionController::Base`, skip CSRF protection for the webhook action.
+
+## Transactions and Travel Rule
+
+```ruby
+txn = didit.transactions.create(
+  transaction_id: "order-1001", transaction_category: "finance",
+  transaction_details: { direction: "outbound", amount: 1500, currency: "EUR", action_type: "withdrawal" },
+  subject: { entity_type: "individual", vendor_data: "user-42", full_name: "Maria Garcia" }
+)
+txn.status
+didit.transactions.rules.list
+didit.transactions.travel_rule.update_transfer(txn.txn_id, payment_txn_id: "0xabc...")
+didit.wallet_screening.screen(wallet_address: "0x...", blockchain: "ethereum")
+didit.travel_rule.list_vasps(search: "exchange")
+```
+
+Webhooks `transaction.created`, `transaction.status.updated` and `travel_rule.status.updated` arrive as typed events.
+
+## Authentication
+
+Didit Authentication gives your application an OpenID Connect issuer for your users. The `Didit::Authentication` module is for your backend: it verifies the tokens your frontend sends, exchanges codes, refreshes tokens, checks sessions and creates step-up verifications. It never uses the API key.
+
+```ruby
+auth = Didit::Authentication.new("https://acme.auth.didit.me", client_id: ENV["DIDIT_APPLICATION_ID"])
+# or Didit::Authentication.from_publishable_key("pk_live_...")
+
+claims = auth.verify_access_token(bearer_token)           # ES256, typ at+jwt, iss, exp/nbf/iat with 60 s leeway
+claims.sub
+claims.org&.role
+
+pkce = Didit::Authentication.create_pkce                  # redirect with pkce.code_challenge, state and nonce
+tokens = auth.exchange_code(params[:code], code_verifier: pkce.code_verifier, redirect_uri: callback_url)
+id = auth.verify_id_token(tokens.id_token, nonce: session[:nonce])
+tokens = auth.refresh(tokens.refresh_token)               # serialise refreshes per session: reusing one revokes it
+
+auth.get_session(access_token)                            # instant revocation check
+auth.revoke_session(access_token)
+step_up = auth.create_step_up(access_token, action: "payout", amount: "250.00", currency: "EUR", return_to: url)
+auth.retrieve_step_up(access_token, step_up.id).approved? # act only on status "approved"
+```
+
+Discovery and keys are fetched on first use and cached as the issuer's `Cache-Control` says; an unknown key id triggers at most one refetch per minute.
+Rejected tokens raise `Didit::TokenVerificationError` with a `reason` such as `:unsupported_algorithm`, `:invalid_issuer`, `:invalid_audience`, `:expired` or `:unknown_key`.
+
+## Account management
+
+The `didit.account` methods use the account API (`https://apx.didit.me/auth/v2`) and a Bearer token instead of the API key:
+
+```ruby
+login = didit.account.login(email: "you@example.com", password: "...")
+account = didit.with_options(account_token: login.access_token)
+account.account.organizations.list
+```
+
+## Debug logging
+
+`DIDIT_LOG=debug` prints one line per request to stderr: method, path, status, duration and request id. It never prints bodies, headers or query strings. Pass `logger:` to send the same lines to your logger.
+
+## Language notes
+
+Choices this SDK makes where [docs/DESIGN.md](docs/DESIGN.md) leaves the language idiom open:
+
+- **Arguments.** Ids in the path are positional; request fields are keywords. An omitted keyword is left out of the request and `nil` sends JSON `null`. `Didit::OMIT` leaves a keyword out explicitly, which helps when building calls conditionally. Keywords that are Ruby keywords (`retry:`, `case:`) work as usual.
+- **Names.** Methods and readers are snake_case. A field that would hide an `Object` method gets a trailing underscore (`method` is `method_`); camelCase fields read as snake_case (`firstName` is `first_name`). `model[:wireName]` always gives the raw value.
+- **Types.** Responses are `Didit::Model` subclasses under `Didit::Types`, loaded on first use. Readers convert on access and never raise: a value with an unexpected shape comes back as it is. Date-times are `Time`, dates are `Date`, numbers are `Float`, and string decimals stay strings. Models support `to_h`, `to_json`, `==` and pattern matching (`in {status: "Approved"}`).
+- **Open enums.** Known values are frozen string constants (`Didit::Types::SessionDecisionStatus::APPROVED`, plus `VALUES`); values the SDK does not know are returned unchanged.
+- **Signatures.** RBS signatures ship in `sig/` with the gem, so Steep users get typed calls and results. Readers of required fields are typed non-nil; if the API ever omits one, the reader returns nil.
+- **Pages.** `Didit::Page` is `Enumerable` over the current page. Use `total_count` for the API's `count` (because `Enumerable#count` counts this page), `next_url`, `previous_url`, `next_page` and `auto_paging_each`. A `next` link to another origin, or one already followed, raises `APIResponseValidationError`. Lists that page with `next_offset` (case action receipts and duplicates) return plain results.
+- **Errors.** Error names follow DESIGN. `APIResponseValidationError` (Python's name) covers 2xx responses that are not JSON and bad pagination links. Every check made before sending raises `ConfigurationError`, including invalid path ids (empty, `.` or `..`), uploads and request options. Verification `reason`s are Symbols.
+- **Timeouts.** `timeout` applies to each attempt's connect, write and read separately, as net/http does; there is no overall deadline.
+- **HTTP.** net/http with a small connection pool per origin. Redirects are never followed. Proxies come from the usual `http_proxy`/`https_proxy` variables, or from `http_client:`, a callable that returns a configured, not yet started `Net::HTTP` for a URI.
+- **Uploads.** Files are read into memory before sending, so a retry can resend them. Content types come from a fixed table of file extensions, not the host's MIME database.
+- **Deprecations.** Methods for operations removed from the API stay for one minor version and warn once through Ruby's `:deprecated` warning category (shown with `Warning[:deprecated] = true` or `ruby -W:deprecated`).
+- **Webhooks.** The canonical JSON is serialised by the SDK itself, because Ruby prints floats differently from Python (`1.0e-05` instead of `1e-05`). `event.verified_by` names the header that matched. `verify` and `verify_parsed` take a `now:` keyword for tests.
+- **Authentication.** The `jwt` gem checks the ES256 signature; the SDK checks everything else. `verify_id_token(token, nonce: nil)` requires a token without a nonce (the refresh case). A step-up's `method` field reads as `verification_method`. `clock:` (unix seconds) is for tests. The issuer is configured without a trailing slash; if its discovery document names it with one, tokens must carry that exact `iss`. A discovery document that names another issuer raises `ConfigurationError` and is fetched again only after a minute. Publishable keys are read with or without `=` padding.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md): generated versus hand-written code, `bundle exec rake generate`, tests, the daily spec sync and releases.
+
+## Versioning
+
+[Semantic versioning](https://semver.org). The SDK stays on 0.x until its first public release; while on 0.x, a breaking change bumps the minor version. Releases are cut by release-please and the changelog is generated.
+
+## Links
+
+- API reference and guides: https://docs.didit.me
+- Webhooks: https://docs.didit.me/integration/webhooks
+- Design contract shared by every Didit server SDK: [docs/DESIGN.md](docs/DESIGN.md)
+- Security: [SECURITY.md](SECURITY.md)
+
+## License
+
+MIT

data/lib/didit/authentication/base64_url.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Didit
+  class Authentication
+    # Unpadded base64url (RFC 4648 section 5) with strict decoding.
+    # @api private
+    module Base64Url
+      ALPHABET = /\A[A-Za-z0-9_-]*\z/
+
+      module_function
+
+      # @param bytes [String]
+      # @return [String]
+      def encode(bytes)
+        [bytes].pack("m0").tr("+/", "-_").delete("=")
+      end
+
+      # The bytes of canonical unpadded base64url, else nil: no padding, no
+      # characters outside the alphabet, no impossible length, no stray bits.
+      #
+      # @param text [String]
+      # @return [String, nil] binary
+      def decode(text)
+        text = text.b
+        return nil unless ALPHABET.match?(text) && text.length % 4 != 1
+
+        bytes = (text.tr("-_", "+/") + ("=" * (-text.length % 4))).unpack1("m0")
+        bytes if bytes.is_a?(String)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/didit/authentication/cache.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Didit
+  class Authentication
+    # The parts of +/.well-known/openid-configuration+ the SDK uses.
+    # @api private
+    class Discovery
+      # @return [String]
+      attr_reader :issuer
+      # @return [String]
+      attr_reader :token_endpoint
+      # @return [String]
+      attr_reader :jwks_uri
+      # @return [Hash] the document as the issuer sent it (frozen)
+      attr_reader :document
+
+      def initialize(issuer:, token_endpoint:, jwks_uri:, document:)
+        @issuer = issuer
+        @token_endpoint = token_endpoint
+        @jwks_uri = jwks_uri
+        @document = IssuerCache.deep_freeze(document)
+        freeze
+      end
+    end
+
+    # What is cached for one issuer, and when to fetch again (no I/O here).
+    #
+    # The discovery document and the key set are cached for the response's
+    # +Cache-Control: max-age+ less its +Age+ (Didit sends +public, max-age=300+),
+    # five minutes when the header is absent, a minute for +no-store+ and
+    # +no-cache+, and never less than a minute or more than a day. A token whose
+    # +kid+ is not in the cached key set triggers a refetch only when the last
+    # fetch, successful or failed, is at least a minute old. After a failed
+    # fetch, verification that needs the keys fails fast for a minute instead of
+    # fetching again for every token. A discovery document that names another
+    # issuer is refused, without fetching it again, for a minute.
+    #
+    # The caller holds a lock around fetches; reads of a fresh entry need none,
+    # because entries are replaced, never changed.
+    # @api private
+    class IssuerCache
+      DEFAULT_MAX_AGE = 300
+      MIN_MAX_AGE = 60
+      MAX_MAX_AGE = 86_400
+      REFETCH_INTERVAL = 60
+      NO_CACHE = %w[no-store no-cache].freeze
+
+      # A cached value and the clock reading it expires at.
+      class Entry
+        attr_reader :value, :expires_at
+
+        def initialize(value, expires_at)
+          @value = value
+          @expires_at = expires_at
+          freeze
+        end
+      end
+
+      class << self
+        # How long a discovery or JWKS response may be kept, in seconds.
+        #
+        # @param headers [Hash{String => String}] names in lower case
+        # @return [Integer]
+        def cache_seconds(headers)
+          max_age = max_age(headers.fetch("cache-control", ""))
+          return DEFAULT_MAX_AGE if max_age.nil?
+
+          age = Integer(headers.fetch("age", "").strip, 10, exception: false) || 0
+          (max_age - age).clamp(MIN_MAX_AGE, MAX_MAX_AGE)
+        end
+
+        # A deeply frozen copy of a parsed JSON value.
+        def deep_freeze(value)
+          case value
+          when Hash then value.to_h { |key, item| [key.dup.freeze, deep_freeze(item)] }.freeze
+          when Array then value.map { |item| deep_freeze(item) }.freeze
+          when String then value.dup.freeze
+          else value
+          end
+        end
+
+        private
+
+        # The max-age directive, 0 for no-store and no-cache, nil without either.
+        def max_age(cache_control)
+          # @type var max_age: Integer?
+          max_age = nil
+          cache_control.split(",").each do |directive|
+            name, value = directive.split("=", 2)
+            name = name.to_s.strip.downcase
+            return 0 if NO_CACHE.include?(name)
+
+            if name == "max-age"
+              seconds = Integer(value.to_s.strip.delete_prefix('"').delete_suffix('"'), 10, exception: false)
+              max_age = seconds if seconds
+            end
+          end
+          max_age
+        end
+      end
+
+      # @param clock [#call] returns the current time in seconds
+      def initialize(clock)
+        @clock = clock
+        @discovery = nil
+        @key_set = nil
+        @key_set_attempted_at = nil
+        @key_set_failed = false
+        @refused = nil
+      end
+
+      # The cached discovery document while it is fresh.
+      #
+      # @return [Discovery, nil]
+      def discovery
+        fresh(@discovery)
+      end
+
+      # @return [Discovery]
+      def store_discovery(discovery, headers)
+        @discovery = Entry.new(discovery, now + IssuerCache.cache_seconds(headers))
+        discovery
+      end
+
+      # Notes that the discovery document named another issuer, with the error message.
+      def discovery_refused(message)
+        @refused = Entry.new(message, now + REFETCH_INTERVAL)
+        nil
+      end
+
+      # The message of a discovery document refused less than a minute ago, else nil.
+      #
+      # @return [String, nil]
+      def refused_discovery
+        fresh(@refused)
+      end
+
+      # The cached key set while it is fresh.
+      #
+      # @return [KeySet, nil]
+      def key_set
+        fresh(@key_set)
+      end
+
+      # @return [KeySet]
+      def store_key_set(key_set, headers)
+        at = now
+        @key_set = Entry.new(key_set, at + IssuerCache.cache_seconds(headers))
+        @key_set_attempted_at = at
+        @key_set_failed = false
+        key_set
+      end
+
+      # Notes a fetch of the key set (or of the discovery document before it) that failed.
+      def key_set_fetch_failed
+        @key_set_attempted_at = now
+        @key_set_failed = true
+        nil
+      end
+
+      # No key set is fresh and the last fetch failed less than a minute ago.
+      def key_set_unavailable?
+        attempted_at = @key_set_attempted_at
+        return false unless @key_set_failed && attempted_at && key_set.nil?
+
+        now - attempted_at < REFETCH_INTERVAL
+      end
+
+      # The fresh key set when it has +kid+: the lock-free fast path.
+      #
+      # @return [KeySet, nil]
+      def key_set_with(kid)
+        current = key_set
+        current if current&.key?(kid)
+      end
+
+      # Whether verifying a token signed with +kid+ should fetch the key set: when
+      # none is fresh, or when +kid+ is unknown and the last fetch, successful or
+      # failed, was at least {REFETCH_INTERVAL} seconds ago. A nil +kid+ asks for
+      # any fresh key set. Check {#key_set_unavailable?} first.
+      def needs_key_set_fetch?(kid)
+        current = key_set
+        return true if current.nil?
+        return false if kid.nil? || current.key?(kid)
+
+        attempted_at = @key_set_attempted_at
+        attempted_at.nil? || now - attempted_at >= REFETCH_INTERVAL
+      end
+
+      private
+
+      def fresh(entry)
+        entry.value if entry && now < entry.expires_at
+      end
+
+      def now
+        @clock.call.to_f
+      end
+    end
+  end
+end