add_auth 0.2.1

data/lib/add_auth/configuration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module AddAuth
+  class Configuration
+    attr_accessor :challenge, :challenge_on,
+      :digest_secret, :eligible, :stylesheet, :css_classes, :mail_from, :base_url, :rate_limit_store, :trusted_recovery_address, :support_url
+    attr_writer :session_token_digest, :sign_in_token_digest
+
+    SessionOptions = Struct.new(:enabled, :lifetime, :idle_timeout, :legacy_bridge_until)
+    EmailOptions = Struct.new(:enabled, :token_lifetime, :same_browser)
+    StepUpOptions = Struct.new(:enabled, :purposes, :fresh_for, :strong_for)
+    PasskeyOptions = Struct.new(:enabled, :rp_id, :origins, :name, :anonymous_limit)
+    NotificationOptions = Struct.new(:enabled)
+    MaintenanceOptions = Struct.new(:batch_size, :session_retention, :email_retention, :notification_retention)
+    attr_accessor :passwords_enabled
+    attr_reader :maintenance, :notifications, :passkeys, :session, :email_link, :step_up, :challenge_when_unavailable
+
+    def initialize
+      @passwords_enabled = true
+      @session = SessionOptions.new(enabled: false, lifetime: 43_200, idle_timeout: 1800)
+      @email_link = EmailOptions.new(enabled: false, token_lifetime: 1200, same_browser: false)
+      @notifications = NotificationOptions.new(enabled: false)
+      @maintenance = MaintenanceOptions.new(batch_size: 100)
+      @passkeys = PasskeyOptions.new(enabled: false, origins: [], name: "Your account", anonymous_limit: 1000)
+      @trusted_recovery_address = ->(_user) {}
+      @step_up = StepUpOptions.new(enabled: false, purposes: {}, fresh_for: 600, strong_for: 300)
+      @eligible = ->(_user) { true } # Hosts supply their confirmed/locked/disabled policy here.
+      @stylesheet = "/add_auth.css"
+      @css_classes = {}
+      @challenge = Core::Challenge::Null.new
+      @challenge_on = []
+      @challenge_when_unavailable = :closed
+    end
+
+    def session_token_digest
+      @session_token_digest ||= default_digest("add_auth.session-token-digest.v1")
+    end
+
+    def sign_in_token_digest
+      @sign_in_token_digest ||= default_digest("add_auth.sign-in-token-digest.v1")
+    end
+
+    def challenge_when_unavailable=(policy)
+      value = policy.to_sym
+      raise ArgumentError, "challenge_when_unavailable must be :closed or :open" unless %i[closed open].include?(value)
+
+      @challenge_when_unavailable = value
+    rescue NoMethodError
+      raise ArgumentError, "challenge_when_unavailable must be :closed or :open"
+    end
+
+    private
+
+    def default_digest(salt)
+      unless digest_secret.respond_to?(:call)
+        raise AddAuth::Error, "configure digest_secret or inject a digest adapter outside a Rails app"
+      end
+      Core::Digest::Hmac.new(salt: salt, secret: digest_secret.call)
+    end
+  end
+end

data/lib/add_auth/core/access_policy.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    # Account policy survives feature toggles; disabling passkeys cannot restore
+    # weaker access to an account that explicitly adopted strict policy.
+    class AccessPolicy
+      def initialize(credentials:, passkeys_enabled:, email_enabled:, trusted_recovery_address:, password_enabled: true)
+        @credentials, @passkeys_enabled, @email_enabled = credentials, passkeys_enabled, email_enabled
+        @trusted_recovery_address = trusted_recovery_address
+        @password_enabled = password_enabled
+      end
+
+      def strict?(user) = user.respond_to?(:add_auth_strict) && user.add_auth_strict == true
+      def version(user) = user.respond_to?(:add_auth_policy_version) ? user.add_auth_policy_version : 0
+
+      def sign_in_allowed?(user, method)
+        return false if strict?(user) && method.to_sym != :passkey
+        case method.to_sym
+        when :password then @password_enabled && user.respond_to?(:password_digest) && user.password_digest.is_a?(String) && !user.password_digest.empty?
+        when :email_link then @email_enabled
+        when :passkey then @passkeys_enabled
+        else false
+        end
+      end
+
+      def methods_for(user)
+        StepUp::METHODS.select { |method| sign_in_allowed?(user, method) }
+      end
+
+      def recovery_address(user)
+        address = @trusted_recovery_address.call(user)
+        address if address.is_a?(String) && address.valid_encoding? && address.bytesize.between?(3, 254) && address == user.email_address
+      end
+
+      def recoverable?(user) = !strict?(user) && @email_enabled && !recovery_address(user).nil?
+      def fallback?(user) = !strict?(user) && (sign_in_allowed?(user, :password) || recoverable?(user))
+
+      def credential_current?(user:, id:)
+        credential = @credentials.call(id)
+        credential && credential.user_id == user.id && !credential.revoked_at
+      end
+
+      def session_allowed?(user, row)
+        return false if row.respond_to?(:authentication_policy_version) && row.authentication_policy_version != version(user)
+        if row.authenticated_with == "passkey"
+          return false unless row.authentication_uv && credential_current?(user: user, id: row.authentication_credential_id)
+        end
+        return true unless strict?(user)
+        (row.authenticated_with == "passkey" && row.authentication_uv) ||
+          (row.elevated_with == "passkey" && row.elevation_uv && credential_current?(user: user, id: row.elevation_credential_id))
+      end
+    end
+  end
+end

data/lib/add_auth/core/browser_binding.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module AddAuth
+  module Core
+    # A browser secret is transport state, never identity or stronger proof.
+    class BrowserBinding
+      def initialize(digest:)
+        @digest = digest
+      end
+
+      def generate = SecureRandom.urlsafe_base64(32)
+
+      def digest(secret)
+        @digest.digest("browser:#{secret}") if valid?(secret)
+      end
+
+      def matches?(stored, secret)
+        valid?(secret) && stored.is_a?(String) && @digest.matches?(stored, "browser:#{secret}")
+      end
+
+      def valid?(secret)
+        secret.is_a?(String) && secret.bytesize == 43 && secret.ascii_only? && /\A[A-Za-z0-9_-]{43}\z/.match?(secret)
+      end
+    end
+  end
+end

data/lib/add_auth/core/challenge/base.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    module Challenge
+      # The adapter contract every challenge provider implements. See
+      # docs/authentication-gem-plan.md section 9 for the full design,
+      # including the decision that matters most here: #verify returns a
+      # result with a real `unavailable?` state, distinct from `rejected?`.
+      # A provider outage and a failed human challenge are different events
+      # and most integrations in the wild conflate them -- either locking out
+      # every user during an outage, or waving everyone through. The host
+      # chooses which way to fail via `Configuration#challenge_when_unavailable`.
+      #
+      # Concrete adapters (Turnstile, reCAPTCHA) use only Ruby's standard
+      # library and are loaded with Core. A host opts in with
+      # `bin/rails g add_auth:challenge turnstile`, which generates the
+      # initializer stanza and route; no provider call happens until the host
+      # supplies keys and includes the action in `challenge_on`.
+      class Base
+        Verification = Data.define(:status, :reason) do
+          def initialize(status:, reason: nil)
+            unless %i[success rejected unavailable].include?(status)
+              raise ArgumentError, "unknown challenge status"
+            end
+            super
+          end
+
+          def success? = status == :success
+          def rejected? = status == :rejected
+          def unavailable? = status == :unavailable
+        end
+
+        def site_key
+          raise NotImplementedError, "#{self.class} must implement #site_key"
+        end
+
+        def script_url
+          raise NotImplementedError, "#{self.class} must implement #script_url"
+        end
+
+        def stimulus_controller
+          raise NotImplementedError, "#{self.class} must implement #stimulus_controller"
+        end
+
+        # @param token [String, nil] the provider's response token from the form.
+        # @param remote_ip [String, nil]
+        # @param action [Symbol] one of Configuration#challenge_on's entries;
+        #   used to bind the token to the form it was minted for.
+        # @return [Verification]
+        def verify(token:, remote_ip:, action:)
+          raise NotImplementedError, "#{self.class} must implement #verify"
+        end
+
+        def inspect = "#<#{self.class} [FILTERED]>"
+        attr_reader :allowed_hostnames
+
+        private
+
+        def require_value(value, name, max_bytes:)
+          unless value.is_a?(String) && value.valid_encoding? && value.bytesize.between?(1, max_bytes)
+            raise ArgumentError, "challenge #{name} must be present"
+          end
+          value.dup.freeze
+        end
+
+        def normalize_hostnames(hostnames)
+          values = hostnames.is_a?(String) ? hostnames.split(",") : Array(hostnames)
+          values.map { |hostname| hostname.to_s.strip.downcase }.reject(&:empty?).uniq.freeze
+        end
+
+        def normalize_action(action)
+          value = action.to_s
+          raise ArgumentError, "challenge action must be present" unless value.match?(/\A[a-zA-Z0-9._:-]{1,64}\z/)
+          value
+        end
+
+        def hostname_allowed?(hostname)
+          hostname.is_a?(String) && !hostname.empty? &&
+            (@allowed_hostnames.empty? || @allowed_hostnames.include?(hostname.downcase))
+        end
+
+        def response_failure(payload)
+          return unavailable(:verification_service) unless [true, false].include?(payload["success"])
+          return if payload["success"] == true
+          errors = payload["error-codes"]
+          valid_errors = errors.nil? || (errors.is_a?(Array) && errors.all? { |value| value.is_a?(String) })
+          return unavailable(:verification_service) unless valid_errors
+          service_errors = %w[internal-error missing-input-secret invalid-input-secret bad-request]
+          return unavailable(:verification_service) if (Array(errors) & service_errors).any?
+          rejected(:challenge_rejected)
+        end
+
+        def success = Verification.new(status: :success)
+        def rejected(reason) = Verification.new(status: :rejected, reason:)
+        def unavailable(reason) = Verification.new(status: :unavailable, reason:)
+      end
+    end
+  end
+end

data/lib/add_auth/core/challenge/http.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "timeout"
+
+module AddAuth
+  module Core
+    module Challenge
+      # Small, dependency-free HTTP boundary shared by provider adapters. It
+      # deliberately returns protocol states instead of raising provider errors
+      # into an authentication request. A provider outage and a malformed
+      # response are both unavailable; an invalid user token is rejected.
+      class Http
+        Response = Data.define(:status, :payload)
+
+        DEFAULT_OPEN_TIMEOUT = 3
+        DEFAULT_READ_TIMEOUT = 3
+        MAX_TOKEN_BYTES = 2048
+        MAX_RESPONSE_BYTES = 16_384
+        TOTAL_TIMEOUT = 10
+
+        def initialize(endpoint:, secret_key:, transport: nil, allowed_hosts: nil,
+          open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+          @allowed_hosts = allowed_hosts&.map { |host| host.to_s.downcase }&.freeze
+          @endpoint = validate_endpoint(endpoint)
+          @secret_key = validate_secret(secret_key)
+          @transport = transport || method(:request)
+          @open_timeout = bounded_timeout(open_timeout, "open_timeout")
+          @read_timeout = bounded_timeout(read_timeout, "read_timeout")
+        end
+
+        def call(token:, remote_ip: nil)
+          return Response.new(status: :rejected, payload: nil) unless valid_token?(token)
+
+          parameters = {"secret" => @secret_key, "response" => token}
+          parameters["remoteip"] = remote_ip if remote_ip.is_a?(String) && !remote_ip.empty?
+          raw = @transport.call(uri: @endpoint, params: parameters)
+          status, body = extract(raw)
+          return Response.new(status: :unavailable, payload: nil) unless status.between?(200, 299)
+
+          return Response.new(status: :unavailable, payload: nil) if body.bytesize > MAX_RESPONSE_BYTES
+          payload = JSON.parse(body, max_nesting: 10)
+          return Response.new(status: :unavailable, payload: nil) unless payload.is_a?(Hash)
+
+          Response.new(status: :ok, payload: payload)
+        rescue JSON::ParserError, TypeError, ArgumentError
+          Response.new(status: :unavailable, payload: nil)
+        rescue
+          # Network, TLS and provider client failures must not disclose
+          # endpoint details or secret material to the authentication caller.
+          Response.new(status: :unavailable, payload: nil)
+        end
+
+        def inspect = "#<AddAuth::Core::Challenge::Http [FILTERED]>"
+
+        private
+
+        def validate_endpoint(endpoint)
+          uri = URI.parse(endpoint.to_s)
+          unless uri.is_a?(URI::HTTPS) && uri.host && uri.userinfo.nil? && uri.query.nil? && uri.fragment.nil?
+            raise ArgumentError, "challenge endpoint must be HTTPS"
+          end
+          if @allowed_hosts && !@allowed_hosts.include?(uri.host.downcase)
+            raise ArgumentError, "challenge endpoint host is not allowed"
+          end
+          uri
+        rescue URI::InvalidURIError
+          raise ArgumentError, "challenge endpoint must be a valid HTTPS URL"
+        end
+
+        def validate_secret(secret)
+          value = secret.to_s
+          raise ArgumentError, "challenge secret_key must be present" if value.empty? || value.bytesize > 512
+
+          value
+        end
+
+        def bounded_timeout(value, name)
+          number = Float(value)
+          raise ArgumentError, "#{name} must be between 0.1 and 30 seconds" unless number.between?(0.1, 30)
+
+          number
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "#{name} must be between 0.1 and 30 seconds"
+        end
+
+        def valid_token?(token)
+          token.is_a?(String) && token.valid_encoding? && token.bytesize.between?(1, MAX_TOKEN_BYTES)
+        end
+
+        def extract(raw)
+          if raw.respond_to?(:code) && raw.respond_to?(:body)
+            [Integer(raw.code), raw.body.to_s]
+          elsif raw.is_a?(Array) && raw.size == 2
+            [Integer(raw.fetch(0)), raw.fetch(1).to_s]
+          else
+            raise TypeError, "invalid challenge transport response"
+          end
+        end
+
+        def request(uri:, params:)
+          client = Net::HTTP.new(uri.host, uri.port)
+          client.use_ssl = true
+          client.open_timeout = @open_timeout
+          client.read_timeout = @read_timeout
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request.set_form_data(params)
+          client.write_timeout = @read_timeout
+          client.max_retries = 0
+          Timeout.timeout(TOTAL_TIMEOUT) do
+            result = nil
+            client.start do |http|
+              http.request(request) do |response|
+                body = +""
+                response.read_body do |chunk|
+                  raise IOError, "challenge response too large" if body.bytesize + chunk.bytesize > MAX_RESPONSE_BYTES
+                  body << chunk
+                end
+                result = [response.code.to_i, body]
+              end
+            end
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/challenge/null.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    module Challenge
+      # The default adapter: no challenge configured, every verification
+      # succeeds, and the view helper renders nothing. This is what makes
+      # `add_auth_challenge_tag` safe to leave in a generated view whether or
+      # not the host has configured Turnstile/reCAPTCHA (section 9).
+      class Null < Base
+        def site_key = nil
+        def script_url = nil
+        def stimulus_controller = nil
+
+        def verify(token:, remote_ip:, action:)
+          success
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/challenge/recaptcha.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "add_auth/core/challenge/http"
+
+module AddAuth
+  module Core
+    module Challenge
+      # Google reCAPTCHA Siteverify adapter for both v2 checkbox and v3 score
+      # keys. v2 deliberately ignores action/score fields because Google does
+      # not make the v3 contract available for that mode.
+      class Recaptcha < Base
+        ENDPOINT = "https://www.google.com/recaptcha/api/siteverify"
+        SCRIPT_URL = "https://www.google.com/recaptcha/api.js"
+
+        def initialize(site_key:, secret_key:, version: :v3, allowed_hostnames: [], minimum_score: 0.5,
+          expected_action: nil, transport: nil, endpoint: ENDPOINT,
+          open_timeout: Http::DEFAULT_OPEN_TIMEOUT, read_timeout: Http::DEFAULT_READ_TIMEOUT)
+          @site_key = require_value(site_key, "site_key", max_bytes: 512)
+          @version = normalize_version(version)
+          @allowed_hostnames = normalize_hostnames(allowed_hostnames)
+          @minimum_score = normalize_score(minimum_score)
+          @expected_action = expected_action.nil? ? nil : normalize_action(expected_action)
+          @http = Http.new(endpoint: endpoint, secret_key: secret_key, allowed_hosts: ["www.google.com"], transport: transport,
+            open_timeout: open_timeout, read_timeout: read_timeout)
+        end
+
+        attr_reader :site_key, :version, :minimum_score, :expected_action
+
+        def script_url = "#{SCRIPT_URL}?render=#{(@version == :v3) ? URI.encode_www_form_component(site_key) : "explicit"}"
+        def stimulus_controller = "add_auth--challenge-recaptcha"
+
+        def verify(token:, remote_ip:, action:)
+          response = @http.call(token: token, remote_ip: remote_ip)
+          return rejected(:invalid_token) if response.status == :rejected
+          return unavailable(:verification_service) unless response.status == :ok
+
+          payload = response.payload
+          failure = response_failure(payload)
+          return failure if failure
+          return rejected(:challenge_rejected) unless hostname_allowed?(payload["hostname"])
+          return success if @version == :v2
+
+          expected = @expected_action || normalize_action(action)
+          return rejected(:challenge_rejected) unless payload["action"] == expected
+          return rejected(:challenge_rejected) unless score_at_least?(payload["score"])
+
+          success
+        end
+
+        private
+
+        def normalize_version(version)
+          value = version.to_sym
+          raise ArgumentError, "reCAPTCHA version must be :v2 or :v3" unless %i[v2 v3].include?(value)
+
+          value
+        rescue NoMethodError
+          raise ArgumentError, "reCAPTCHA version must be :v2 or :v3"
+        end
+
+        def normalize_score(score)
+          value = Float(score)
+          raise ArgumentError, "minimum_score must be between 0 and 1" unless value.between?(0, 1)
+
+          value
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "minimum_score must be between 0 and 1"
+        end
+
+        def score_at_least?(score)
+          score.is_a?(Numeric) && score.finite? && score.between?(@minimum_score, 1)
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/challenge/test.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    module Challenge
+      # Deterministic adapter for specs. Install the desired mode in test setup
+      # and restore the previous configuration after each example. This exercises
+      # Core outcomes without coupling host tests to provider HTTP stubs.
+      class Test < Base
+        def initialize(mode: :success)
+          @mode = mode
+        end
+
+        attr_accessor :mode
+
+        def site_key = "test-site-key"
+        def script_url = nil
+        def stimulus_controller = "add_auth--challenge-test"
+
+        def verify(token:, remote_ip:, action:)
+          case @mode
+          when :success then success
+          when :rejected then rejected(:challenge_rejected)
+          when :unavailable then unavailable(:verification_service)
+          else
+            raise ArgumentError, "unknown Test challenge mode: #{@mode.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/challenge/turnstile.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "add_auth/core/challenge/http"
+
+module AddAuth
+  module Core
+    module Challenge
+      # Cloudflare Turnstile's server-side Siteverify adapter. The browser
+      # widget is optional and host-rendered; this class owns the security
+      # decision made from Cloudflare's response.
+      class Turnstile < Base
+        ENDPOINT = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
+        SCRIPT_URL = "https://challenges.cloudflare.com/turnstile/v0/api.js"
+
+        def initialize(site_key:, secret_key:, allowed_hostnames: [], transport: nil,
+          endpoint: ENDPOINT, open_timeout: Http::DEFAULT_OPEN_TIMEOUT,
+          read_timeout: Http::DEFAULT_READ_TIMEOUT)
+          @site_key = require_value(site_key, "site_key", max_bytes: 512)
+          @allowed_hostnames = normalize_hostnames(allowed_hostnames)
+          @http = Http.new(endpoint: endpoint, secret_key: secret_key, allowed_hosts: ["challenges.cloudflare.com"], transport: transport,
+            open_timeout: open_timeout, read_timeout: read_timeout)
+        end
+
+        attr_reader :site_key
+
+        def script_url = "#{SCRIPT_URL}?render=explicit"
+        def stimulus_controller = "add_auth--challenge-turnstile"
+
+        def verify(token:, remote_ip:, action:)
+          expected_action = normalize_action(action)
+          response = @http.call(token: token, remote_ip: remote_ip)
+          return rejected(:invalid_token) if response.status == :rejected
+          return unavailable(:verification_service) unless response.status == :ok
+
+          payload = response.payload
+          failure = response_failure(payload)
+          return failure if failure
+          return rejected(:challenge_rejected) unless payload["action"] == expected_action
+          return rejected(:challenge_rejected) unless hostname_allowed?(payload["hostname"])
+
+          success
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/delivery.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    # Shared leased-delivery state machine. The including strategy supplies
+    # rejection(user, record) and delivery_details(user, record); the store owns
+    # locking and persistence. Transport always runs after this lock returns.
+    module Delivery
+      def claim_delivery(digest:)
+        @store.with_token(digest: digest) do |user, record|
+          next if rejection(user, record) || record.delivery_payload.nil? || record.delivered_at ||
+            (record.delivery_lease_until && record.delivery_lease_until > @clock.now)
+          details = delivery_details(user, record)
+          next unless details
+          key = @random.hex(16)
+          @store.lease(record: record, key: key, until_time: @clock.now + 300)
+          details.merge(lease: key)
+        end
+      end
+
+      def delivery_failed(digest:, lease: nil)
+        @store.with_token(digest: digest) do |user, record|
+          next if lease && record && record.delivery_lease_key != lease
+          @store.revoke(record: record, at: @clock.now) unless rejection(user, record)
+        end
+        nil
+      end
+
+      def delivery_succeeded(digest:, lease:)
+        finish_delivery(digest: digest, lease: lease, outcome: :delivered)
+      end
+
+      def finish_delivery(digest:, lease:, outcome:)
+        raise ArgumentError, "unsupported delivery outcome" unless %i[delivered cancelled].include?(outcome)
+        return false unless lease.is_a?(String) && !lease.empty?
+        @store.with_token(digest: digest) do |_user, record|
+          next false unless record && record.delivery_lease_key == lease
+          if outcome == :delivered
+            @store.delivered(record: record, at: @clock.now)
+          else
+            @store.revoke(record: record, at: @clock.now)
+            @store.lease(record: record, key: nil, until_time: nil)
+          end
+          true
+        end
+      end
+
+      def delivery_retry(digest:, lease:)
+        @store.with_token(digest: digest) do |_user, record|
+          @store.lease(record: record, key: nil, until_time: nil) if record && record.delivery_lease_key == lease
+        end
+      end
+    end
+  end
+end

data/lib/add_auth/core/digest/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AddAuth
+  module Core
+    module Digest
+      # The adapter contract every token/session digest implementation
+      # satisfies. See docs/authentication-gem-plan.md section 2's
+      # "Pluggable cryptography" subsection: unlike the Challenge adapter,
+      # there is no credible reason to swap this for a *security* property --
+      # the reason to override it is organizational (a host mandated to run
+      # OpenSSL in FIPS mode, or to route HMAC operations through an HSM).
+      # Any object responding to #digest and #matches? satisfies this
+      # contract; Base exists to document it and to fail loudly if a
+      # concrete adapter forgets a method, the same role Challenge::Base
+      # plays for challenge providers.
+      class Base
+        # @param token [String] the raw, high-entropy secret (a session
+        #   token, a sign-in token) as presented by the client.
+        # @return [String] an opaque digest safe to store at rest.
+        def digest(token)
+          raise NotImplementedError, "#{self.class} must implement #digest"
+        end
+
+        # @param digest [String, nil] the stored digest to compare against.
+        # @param token [String, nil] the raw token presented by the client.
+        # @return [Boolean] true only for a byte-exact match of the digest
+        #   the same token would produce, compared in constant time.
+        def matches?(digest, token)
+          raise NotImplementedError, "#{self.class} must implement #matches?"
+        end
+      end
+    end
+  end
+end