touchque 5.0.0

data/lib/touchque/resources/identity.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # Touchque Login Management API (tq.identity): your customers' accounts, roles,
+    # business-customer organizations, apps, APIs, connections and the tenant itself,
+    # from your server with your workspace key. Bodies and queries are Hashes with the
+    # API's camelCase fields (symbol or string keys); answers are the API's JSON.
+    #
+    #   tq.identity.users.list(q: "ayse")
+    #   tq.identity.users.block(user_id, reason: "chargeback")
+    #   tq.identity.imports.start(users: [{ email: e, passwordHash: "$2b$10$..." }])
+    class Identity
+      attr_reader :users, :imports, :exports, :roles, :organizations, :clients, :apis, :connections, :custom_domains
+
+      def initialize(http)
+        @http = http
+        @users = IdentityUsers.new(http)
+        @imports = IdentityJobs.new(http, "imports")
+        @exports = IdentityJobs.new(http, "exports")
+        @roles = IdentityCrud.new(http, "/identity/roles", "roles")
+        @organizations = IdentityOrganizations.new(http)
+        @clients = IdentityClients.new(http)
+        @apis = IdentityCrud.new(http, "/identity/apis", "apis")
+        @connections = IdentityCrud.new(http, "/identity/connections", "connections")
+        @custom_domains = IdentityCrud.new(http, "/identity/custom-domains", "domains")
+      end
+
+      # The tenant (404 not_enabled until it is set up).
+      def get_tenant
+        @http.get("/identity/tenant")
+      end
+
+      # Turns Touchque Login on (slug, displayName) or changes its settings.
+      def update_tenant(body)
+        @http.put("/identity/tenant", body)
+      end
+
+      def rotate_signing_key
+        @http.post("/identity/tenant/signing-keys/rotate", {})
+      end
+
+      # The phone app the hosted pages tell customers to approve on ("Approve on the Acme app").
+      # nil: your brand name when the Mobile SDK is set up, else Touchque (approverApp in the tenant shows which).
+      def set_approver_app_name(name)
+        @http.put("/identity/tenant", { "branding" => { "approverAppName" => name } })
+      end
+
+      # Serve sign-in only on the primary custom domain: {slug}.login.touchque.com redirects page loads there and
+      # refuses other calls. Turning it on needs a verified primary domain with a working certificate.
+      def set_custom_domain_only(on)
+        @http.put("/identity/tenant", { "customDomainOnly" => on })
+      end
+
+      # Checks a verified custom domain's certificate at the sign-in edge now (certificate: pending | active | error).
+      def check_domain_certificate(domain_id)
+        @http.post("/identity/custom-domains/#{Util.seg(domain_id)}/check-certificate", {})
+      end
+
+      # The delivery log. Message text only in the local dev inbox.
+      def outbox(params = {})
+        @http.get("/identity/outbox", params)
+      end
+
+      # Wrong passwords, suspicious addresses, bot challenge, breached passwords, new-browser notices, the risk engine.
+      def get_attack_protection
+        @http.get("/identity/attack-protection")
+      end
+
+      # Partial; the bot challenge's secret is write-only.
+      def set_attack_protection(settings)
+        @http.put("/identity/attack-protection", settings)
+      end
+
+      # What attack protection caught lately.
+      def attack_events(params = {})
+        @http.get("/identity/attack-protection/events", params)
+      end
+
+      # The email and SMS providers; secrets never come back (secretsSet).
+      def get_delivery
+        @http.get("/identity/delivery")
+      end
+
+      # Your own provider: email smtp, ses, postmark, sendgrid; sms twilio, netgsm, e.g.
+      # { provider: "postmark", from: "login@acme.com", serverToken: "..." }. A secret left
+      # out keeps its stored value.
+      def set_delivery(channel, provider)
+        @http.put("/identity/delivery/#{Util.seg(channel)}", provider)
+      end
+
+      # Back to Touchque's transport.
+      def remove_delivery(channel)
+        @http.delete("/identity/delivery/#{Util.seg(channel)}")
+      end
+
+      # One test message through the provider in use.
+      def test_delivery(channel, to)
+        @http.post("/identity/delivery/#{Util.seg(channel)}/test", { "to" => to })
+      end
+    end
+
+    # List, get, create, update and delete for one kind of Touchque Login object.
+    class IdentityCrud
+      def initialize(http, base, list_key)
+        @http = http
+        @base = base
+        @list_key = list_key
+      end
+
+      def list(params = {})
+        @http.get(@base, params)[@list_key] || []
+      end
+
+      def get(id)
+        @http.get("#{@base}/#{Util.seg(id)}")
+      end
+
+      def create(body)
+        @http.post(@base, body)
+      end
+
+      def update(id, body)
+        @http.patch("#{@base}/#{Util.seg(id)}", body)
+      end
+
+      def delete(id)
+        @http.delete("#{@base}/#{Util.seg(id)}")
+      end
+    end
+
+    # Your customers' apps (OpenID Connect clients).
+    class IdentityClients < IdentityCrud
+      def initialize(http)
+        super(http, "/identity/clients", "clients")
+      end
+
+      # A new client secret: it is in the answer, this once.
+      def rotate_secret(client_id)
+        @http.post("#{@base}/#{Util.seg(client_id)}/rotate-secret", {})
+      end
+    end
+
+    # Business customers, their members and invitations.
+    class IdentityOrganizations < IdentityCrud
+      def initialize(http)
+        super(http, "/identity/organizations", "organizations")
+      end
+
+      def members(org_id)
+        @http.get("#{org(org_id)}/members")
+      end
+
+      def add_members(org_id, user_ids)
+        @http.post("#{org(org_id)}/members", { "userIds" => user_ids.to_a })
+      end
+
+      def remove_member(org_id, user_id)
+        @http.delete("#{org(org_id)}/members/#{Util.seg(user_id)}")
+      end
+
+      def set_connections(org_id, connections)
+        @http.put("#{org(org_id)}/connections", { "connections" => connections })
+      end
+
+      def invitations(org_id)
+        @http.get("#{org(org_id)}/invitations")
+      end
+
+      # The link opens the app's sign-in route (initiateLoginUri) with organization and invitation.
+      def invite(org_id, invitation)
+        @http.post("#{org(org_id)}/invitations", invitation)
+      end
+
+      def revoke_invitation(org_id, invitation_id)
+        @http.delete("#{org(org_id)}/invitations/#{Util.seg(invitation_id)}")
+      end
+
+      private
+
+      def org(org_id)
+        "#{@base}/#{Util.seg(org_id)}"
+      end
+    end
+
+    # Bulk user imports and exports, running in the background.
+    class IdentityJobs
+      def initialize(http, kind)
+        @http = http
+        @kind = kind
+      end
+
+      # Imports: { users: [...], upsert: true }; exports: { format: "csv" | "json" }.
+      def start(body)
+        @http.post("/identity/users-#{@kind}", body)
+      end
+
+      def get(job_id)
+        @http.get("/identity/users-#{@kind}/#{Util.seg(job_id)}")
+      end
+
+      # Exports: the finished file (CSV or JSON text).
+      def file(job_id)
+        @http.get_text("/identity/users-#{@kind}/#{Util.seg(job_id)}/file")
+      end
+
+      # Polls until the job is done or failed (or the timeout passes: the last state).
+      def wait(job_id, interval: 1.0, timeout: 600.0)
+        deadline = Time.now + timeout
+        loop do
+          job = get(job_id)
+          return job if job["status"] != "running" || Time.now > deadline
+
+          sleep interval
+        end
+      end
+    end
+
+    # A tenant's customer accounts.
+    class IdentityUsers
+      def initialize(http)
+        @http = http
+      end
+
+      # Query: q, blocked, emailVerified, connection, organization, limit, cursor.
+      def list(params = {})
+        @http.get("/identity/users", params)
+      end
+
+      def get(user_id)
+        @http.get(u(user_id))
+      end
+
+      # email and: password, passwordHash (bcrypt/argon2), customPasswordHash, emailVerified,
+      # name, givenName, familyName, phone, locale, userMetadata, appMetadata, sendVerificationEmail.
+      def create(user)
+        @http.post("/identity/users", user)
+      end
+
+      # Metadata is merged; a key set to nil is removed.
+      def update(user_id, changes)
+        @http.patch(u(user_id), changes)
+      end
+
+      # Erasure (KVKK/GDPR): the account and every workspace row that names it.
+      def delete(user_id)
+        @http.delete(u(user_id))
+      end
+
+      def block(user_id, reason: nil)
+        @http.post("#{u(user_id)}/block", Util.compact({ "reason" => reason }))
+      end
+
+      def unblock(user_id)
+        @http.post("#{u(user_id)}/unblock", {})
+      end
+
+      # Everything about the person (KVKK/GDPR access request); never hashes.
+      def export(user_id)
+        @http.get("#{u(user_id)}/export")
+      end
+
+      def sessions(user_id)
+        @http.get("#{u(user_id)}/sessions")
+      end
+
+      # Ends one of the user's sessions.
+      def end_session(user_id, session_id)
+        @http.delete("#{u(user_id)}/sessions/#{Util.seg(session_id)}")
+      end
+
+      def sign_out_everywhere(user_id)
+        @http.delete("#{u(user_id)}/sessions")
+      end
+
+      # Removes passkeys, unlinks the Touchque app, turns email codes off, signs out everywhere.
+      def reset_mfa(user_id)
+        @http.delete("#{u(user_id)}/mfa")
+      end
+
+      # Accounts at providers whose tokens the vault keeps for the user (connections with tokenVault on).
+      def connected_accounts(user_id)
+        @http.get("#{u(user_id)}/connected-accounts")
+      end
+
+      # Deletes the stored tokens: apps stop using the account for the user; signing in with it stays.
+      def disconnect_account(user_id, account_id)
+        @http.delete("#{u(user_id)}/connected-accounts/#{Util.seg(account_id)}")
+      end
+
+      def unlink_identity(user_id, identity_id, force: false)
+        @http.delete("#{u(user_id)}/identities/#{Util.seg(identity_id)}#{force ? "?force=true" : ""}")
+      end
+
+      def send_verification_email(user_id, return_to: nil)
+        @http.post("#{u(user_id)}/verification-email", Util.compact({ "returnTo" => return_to }))
+      end
+
+      # send_email: false: the link comes back for you to deliver.
+      def password_reset(user_id, send_email: true, ttl_sec: nil)
+        body = { "sendEmail" => send_email }
+        body["ttlSec"] = ttl_sec unless ttl_sec.nil?
+        @http.post("#{u(user_id)}/password-reset", body)
+      end
+
+      def roles(user_id)
+        @http.get("#{u(user_id)}/roles")
+      end
+
+      def add_roles(user_id, role_ids, organization_id: nil)
+        body = { "roleIds" => role_ids.to_a }
+        body["organizationId"] = organization_id unless organization_id.nil?
+        @http.post("#{u(user_id)}/roles", body)
+      end
+
+      def remove_role(user_id, role_id, organization_id: nil)
+        @http.delete("#{u(user_id)}/roles/#{Util.seg(role_id)}#{organization_id ? "?organizationId=#{Util.seg(organization_id)}" : ""}")
+      end
+
+      def logs(user_id, limit: nil)
+        @http.get("#{u(user_id)}/logs", { "limit" => limit })
+      end
+
+      private
+
+      def u(user_id)
+        "/identity/users/#{Util.seg(user_id)}"
+      end
+    end
+  end
+end

data/lib/touchque/resources/login.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # Setup secrets (the QR code the Touchque app scans) and a user's link status.
+    class Auth
+      def initialize(http)
+        @http = http
+      end
+
+      # A new setup secret: show +qrCodeDataUrl+ so the Touchque app links the phone.
+      # 409 when an unscanned or used secret exists (reset_secret issues a new one).
+      def generate_secret(external_username)
+        @http.post("/auth/generate-secret", { "externalUsername" => external_username })
+      end
+
+      def reset_secret(external_username)
+        @http.post("/auth/secret/reset", { "externalUsername" => external_username })
+      end
+
+      def validate_secret(secret)
+        @http.post("/auth/secret/validate", { "secret" => secret })
+      end
+
+      # A user's link status without sending a push: +used+ flips true and +deviceId+ is
+      # set once the app scans the secret. +device+ is the linked phone's self-reported
+      # posture (device trust), nil before a phone is linked. APIError 404 for an unknown user.
+      def get_user(external_username)
+        @http.get("/users/#{Util.seg(external_username)}")
+      end
+    end
+
+    # Push approvals on the user's phone: request, status, wait, use once, report fraud.
+    class Login
+      FRAUD_REASONS = %w[chargeback account_takeover social_engineering other].freeze
+
+      def initialize(http)
+        @http = http
+      end
+
+      # A push to the user's phone (returns at once).
+      #
+      # details: transaction context for the approval screen, {"Amount" => "250 EUR"} or
+      # [{label:, value:}], at most 8 lines (labels <= 40, values <= 120 characters). Build
+      # it from server-side state. browser_proof: the X-Touchque-Browser header (silent
+      # sign-ins), passed through untouched. context: for your Touchque Actions only.
+      # security_changes: {password:, mfa:, device:, email:, phone:} => Time / ISO 8601 /
+      # epoch ms, when each last changed in your system. destination: {kind:, value:, known:}
+      # where the action sends money (shown in full on the phone). locale: "tr" or "en".
+      def request(external_username, type: "LOGIN", reference_id: nil, client_ip: nil, user_agent: nil,
+                  require_biometric: false, require_number_match: false, details: nil, browser_proof: nil,
+                  context: nil, challenge_digits: nil, expires_in: nil, client_signals: nil,
+                  security_changes: nil, destination: nil, locale: nil, qr_pairing: nil, device_risk: nil, device_risk_request_id: nil, reply: nil)
+        body = { "externalUsername" => external_username, "type" => type || "LOGIN" }
+        # An empty reference is no reference (the API answers null for it).
+        body["referenceId"] = reference_id unless reference_id.to_s.empty?
+        body["clientIp"] = client_ip unless client_ip.nil?
+        body["userAgent"] = user_agent unless user_agent.nil?
+        body["requireBiometric"] = true if require_biometric
+        body["requireNumberMatch"] = true if require_number_match
+        body["challengeDigits"] = challenge_digits if [2, 3].include?(challenge_digits)
+        # How long the push waits for the person: 30 (default) to 300 seconds.
+        body["expiresIn"] = expires_in unless expires_in.nil?
+        # A browser pairing by QR code (qr_pairings), confirmed on the phone: only that phone is asked, once.
+        body["qrPairing"] = qr_pairing unless qr_pairing.to_s.empty?
+        # Ask the person to type back on the phone a sign-in code another service sent them:
+        # { kind: "code", key: Touchque::CodeReply.new_key["publicKey"], channel: "sms", target: "+**********26" }.
+        # status(id)["reply"]["ct"] holds only the ciphertext: Touchque::CodeReply.open opens it. Not with qr_pairing.
+        body["reply"] = Util.stringify(reply) if reply
+        body["clientSignals"] = client_signals if client_signals && !client_signals.empty?
+        # The page's device report from @touchque/web (deviceRisk.collect), when the workspace
+        # turned Device risk on: its signals only ever ask for more.
+        body["deviceRisk"] = device_risk unless device_risk.to_s.empty?
+        body["deviceRiskRequestId"] = device_risk_request_id unless device_risk_request_id.to_s.empty?
+        body["details"] = Util.stringify(details) if details && !details.empty?
+        body["browserProof"] = browser_proof if browser_proof && !browser_proof.empty?
+        body["context"] = Util.stringify(context) if context && !context.empty?
+        body["securityChanges"] = self.class.security_changes_body(security_changes) if security_changes && !security_changes.empty?
+        body["destination"] = Util.stringify(destination) if destination && !destination.empty?
+        body["locale"] = locale if locale && !locale.empty?
+        @http.post("/login/request", body)
+      end
+
+      # Times go out as ISO 8601 UTC; strings and epoch milliseconds as given.
+      def self.security_changes_body(changes)
+        changes.each_with_object({}) do |(kind, at), out|
+          next if at.nil?
+
+          out[kind.to_s] = at.respond_to?(:utc) ? at.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ") : at
+        end
+      end
+
+      # Where a request is now: PENDING, CONFIRMED, REJECTED or EXPIRED.
+      def status(request_id)
+        @http.get("/login/status/#{Util.seg(request_id)}")
+      end
+
+      # Asks the phone and polls until the user approves or rejects (every 0.4 s, up to
+      # +timeout+ seconds). With number matching the user picks a number on the phone:
+      # +on_challenge+ (or the block) gets {"requestId", "challengeCode", "expiresAt",
+      # "reasons", "caseCode"} right after the request exists and before any waiting.
+      # Show +challengeCode+ to the user now; the phone asks for it. An error it raises
+      # is logged and ignored.
+      #
+      # Raises PasskeyRequiredError (policy: no push was sent; step_up: tapped during a
+      # call), RejectedError, or TimeoutError.
+      def verify(external_username, type: "LOGIN", timeout: 30, poll_interval: 0.4, on_challenge: nil, **options, &block)
+        on_challenge ||= block
+        sent = request(external_username, type: type, **options)
+        request_id = sent["requestId"]
+        raise PasskeyRequiredError.new(request_id) if sent["requiresPasskey"]
+
+        if on_challenge
+          challenge = { "requestId" => request_id, "expiresAt" => sent["expiresAt"] }
+          %w[challengeCode reasons caseCode].each { |k| challenge[k] = sent[k] if sent[k] && !(sent[k].respond_to?(:empty?) && sent[k].empty?) }
+          begin
+            on_challenge.call(challenge)
+          rescue StandardError => e
+            # The caller's callback must not stop the wait.
+            Touchque.log :warn, "[Touchque] on_challenge failed: #{e.class}: #{e.message}"
+          end
+        end
+        wait(request_id, sent["challengeCode"], timeout, poll_interval)
+      end
+
+      # Waits for a request you already sent.
+      def wait_for_approval(request_id, timeout: 30, poll_interval: 0.4)
+        wait(request_id, nil, timeout, poll_interval)
+      end
+
+      # Approves a pending request with one of the user's recovery codes (no phone).
+      def approve_with_recovery_code(request_id, code)
+        @http.post("/login/recovery", { "requestId" => request_id, "code" => code })
+      end
+
+      # Uses an approved request exactly once. The first call on a CONFIRMED request wins
+      # atomically; every later call raises APIError with code +already_used+ (409).
+      def consume(request_id)
+        @http.post("/login/#{Util.seg(request_id)}/consume", {})
+      end
+
+      # Reports a request you later learned was fraud (a chargeback, a confirmed account
+      # takeover, a scam the user was talked into). The risk engine learns from it; the
+      # request's status does not change. A repeat answers "alreadyReported" => true.
+      def report_fraud(request_id, reason: nil, note: nil)
+        raise ConfigError, "report_fraud() needs the request id" if request_id.to_s.empty?
+
+        @http.post("/login/#{Util.seg(request_id)}/report-fraud", Util.compact({ "reason" => reason, "note" => note }))
+      end
+
+      private
+
+      def wait(request_id, challenge_code, timeout, interval)
+        deadline = Time.now + timeout
+        loop do
+          s = status(request_id)
+          case s["status"]
+          when "CONFIRMED"
+            return {
+              "approved" => true, "status" => "CONFIRMED", "requestId" => request_id,
+              "challengeCode" => challenge_code, "assurance" => s["assurance"], "confirmedVia" => s["confirmedVia"],
+              # Vishing Shield: approved during a call; critical actions wait for the phone to re-confirm.
+              "provisional" => s["provisional"] ? true : false
+            }
+          when "REJECTED" then raise RejectedError.new(request_id)
+          when "EXPIRED" then raise TimeoutError.new("Touchque: request '#{request_id}' expired before it was approved.", request_id)
+          end
+          # Vishing Shield: tapped during a call, the request now waits for a passkey in the browser.
+          raise PasskeyRequiredError.new(request_id, "step_up") if s["status"] == "PENDING" && s["requiresPasskey"]
+          if Time.now + interval > deadline
+            raise TimeoutError.new("Touchque: request '#{request_id}' was not approved within #{timeout}s. The user did not respond in time.", request_id)
+          end
+
+          sleep interval
+        end
+      end
+    end
+
+    # WebAuthn / FIDO2 (passkeys), the backend half: the ceremony runs in the browser
+    # (@touchque/web); your backend relays its JSON through these methods.
+    class WebAuthn
+      def initialize(http)
+        @http = http
+      end
+
+      # Registration step 1. +approval_request_id+: a PASSKEY_ENROLL request the user approved
+      # on their linked phone (403 enrollment_approval_required otherwise).
+      def register_options(external_username, discoverable: false, approval_request_id: nil)
+        body = { "externalUsername" => external_username }
+        body["discoverable"] = true if discoverable
+        body["approvalRequestId"] = approval_request_id if approval_request_id && !approval_request_id.empty?
+        @http.post("/webauthn/register/options", body)
+      end
+
+      def register_verify(external_username, response, label: nil)
+        body = { "externalUsername" => external_username, "response" => response }
+        body["label"] = label unless label.nil?
+        @http.post("/webauthn/register/verify", body)
+      end
+
+      # Second factor: options scoped to a pending request.
+      def authenticate_options(request_id)
+        @http.post("/webauthn/login/options", { "requestId" => request_id })
+      end
+
+      def authenticate_verify(request_id, response)
+        @http.post("/webauthn/login/verify", { "requestId" => request_id, "response" => response })
+      end
+
+      # Whether passkey sign-in (passwordlessLoginEnabled) is on for your workspace.
+      # Ask before your sign-in page shows its passkey button and passkey autofill:
+      # when it is off, primary_options answers 403 passwordless_login_disabled.
+      # { "enabled" => bool, "userVerification" => "required" | "preferred" | nil }.
+      def primary_availability
+        raw = @http.get("/webauthn/authenticate/primary/availability") || {}
+        enabled = raw["enabled"] == true
+        uv = raw["userVerification"]
+        { "enabled" => enabled, "userVerification" => enabled && %w[required preferred].include?(uv) ? uv : nil }
+      end
+
+      # Passwordless sign-in step 1; without a user, any passkey of your site (autofill).
+      def primary_options(external_username = nil)
+        @http.post("/webauthn/authenticate/primary/options", Util.compact({ "externalUsername" => external_username }))
+      end
+
+      def primary_verify(attempt_id, response)
+        @http.post("/webauthn/authenticate/primary/verify", { "attemptId" => attempt_id, "response" => response })
+      end
+
+      def list_credentials(external_username)
+        @http.get("/webauthn/credentials", { "externalUsername" => external_username })
+      end
+
+      # Scope the deletion to +external_username+ (recommended).
+      def delete_credential(credential_record_id, external_username: nil)
+        path = "/webauthn/credentials/#{Util.seg(credential_record_id)}"
+        path += "?externalUsername=#{Util.seg(external_username)}" if external_username
+        @http.delete(path)
+      end
+    end
+
+    # Offline Sign: QR challenge and typed-code approvals that work with the phone offline.
+    class Offline
+      ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+
+      def initialize(http)
+        @http = http
+      end
+
+      # An offline QR challenge. Always pass +request_id+ when the QR follows a push: a
+      # phone-side rejection then kills the QR, and number matching carries over.
+      def challenge(external_username, type: "LOGIN", details: nil, client_ip: nil, user_agent: nil,
+                    ttl_seconds: nil, include_qr_image: true, request_id: nil, require_number_match: false)
+        body = { "externalUsername" => external_username, "type" => type }
+        body["details"] = Util.stringify(details) unless details.nil?
+        body["clientIp"] = client_ip unless client_ip.nil?
+        body["userAgent"] = user_agent unless user_agent.nil?
+        body["ttlSeconds"] = ttl_seconds unless ttl_seconds.nil?
+        body["includeQrImage"] = false unless include_qr_image
+        body["requestId"] = request_id unless request_id.nil?
+        body["requireNumberMatch"] = true if require_number_match
+        @http.post("/offline/challenge", body)
+      end
+
+      # The 7-character code from the phone. Never raises for a wrong, expired or used code:
+      # check "approved"; "reason" is invalid_code, locked, expired, used, unknown_challenge,
+      # request_rejected, too_many_failures or device_not_enrolled.
+      def verify(challenge_id, code)
+        not_approved_as_result { @http.post("/offline/verify", { "challengeId" => challenge_id, "code" => code }) }
+      end
+
+      # The rolling time-based code. Refused for critical action types.
+      def verify_totp(external_username, code, type: "LOGIN", client_ip: nil, request_id: nil)
+        body = { "externalUsername" => external_username, "code" => code, "type" => type }
+        body["clientIp"] = client_ip unless client_ip.nil?
+        body["requestId"] = request_id unless request_id.nil?
+        not_approved_as_result { @http.post("/offline/totp/verify", body) }
+      end
+
+      # Salted, slow digests of each user's next codes, for checking typed codes while your
+      # server cannot reach Touchque. Check a code with Offline.match_totp_verifier.
+      def totp_verifiers(external_usernames, from_step: nil, steps: nil)
+        body = { "externalUsernames" => external_usernames.to_a }
+        body["fromStep"] = from_step unless from_step.nil?
+        body["steps"] = steps unless steps.nil?
+        @http.post("/offline/totp/verifiers", body)
+      end
+
+      # The step a typed code belongs to (the current one or one either side), or nil,
+      # without calling Touchque. Accept each step once.
+      def self.match_totp_verifier(verifiers, user, code, at: nil)
+        given = code.to_s.upcase.delete(" \t-")
+        return nil unless given.length == 7 && given.chars.all? { |c| ALPHABET.include?(c) }
+
+        step_seconds = verifiers["stepSeconds"].to_i
+        length = verifiers.dig("kdf", "length").to_i
+        return nil if step_seconds <= 0 || length <= 0
+
+        salt = Util.b64_decode(user["salt"])
+        digests = Util.b64_decode(user["digests"])
+        now = (at || Time.now).to_i / step_seconds
+        [now, now - 1, now + 1].each do |step|
+          next if step < user["fromStep"].to_i || step > verifiers["notAfterStep"].to_i
+
+          i = (step - user["fromStep"].to_i) * 2 * length
+          next if i + 2 * length > digests.bytesize
+
+          got = OpenSSL::KDF.pbkdf2_hmac(given, salt: salt + ":#{step}", iterations: verifiers.dig("kdf", "iterations").to_i, length: length, hash: "sha256")
+          return step if Util.secure_compare(digests.byteslice(i, length), got) || Util.secure_compare(digests.byteslice(i + length, length), got)
+        end
+        nil
+      end
+
+      private
+
+      def not_approved_as_result
+        yield
+      rescue APIError => e
+        raise if e.status >= 500
+
+        { "approved" => false, "reason" => e.reason || e.code || e.error, "attemptsLeft" => e.attempts_left }
+      end
+    end
+  end
+end