touchque 5.0.0

data/lib/touchque/resources/actions.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # Action types (LOGIN, SEND_MONEY...): what a user is asked to approve. Define them
+    # from code at start-up instead of clicking them into the dashboard.
+    class ActionTypes
+      # The Second Thought questions an action type can ask (at most two).
+      SECOND_THOUGHT_QUESTIONS = %w[someone_guiding safe_account remote_access asked_for_code support_call
+                                    met_online promised_return know_recipient sim_in_hand].freeze
+
+      def initialize(http)
+        @http = http
+      end
+
+      # Creates the action type, or updates its name, description, critical flag and
+      # Second Thought questions ({questions: [...], locale: "tr" | "en"}; questions: []
+      # turns them off; nil keeps what the dashboard has). Never re-enables a type an
+      # admin disabled.
+      def define(type, name: nil, description: nil, critical: nil, second_thought: nil)
+        body = { "type" => type, "name" => name || type }
+        body["description"] = description unless description.nil?
+        body["critical"] = critical unless critical.nil?
+        body["secondThought"] = Util.stringify(second_thought) unless second_thought.nil?
+        @http.post("/action-types", body)
+      end
+
+      def list
+        @http.get("/action-types")
+      end
+    end
+
+    # Touchque Actions: your own code at points of the approval pipeline (before the push
+    # is sent, the silent sign-in decision, after an approval, fraud reports, device and
+    # recovery events). Touchque runs it in a sandbox; this resource deploys, tests,
+    # replays and observes it.
+    #
+    #   tq.actions.deploy("night-alert", trigger: "approval.decided",
+    #                     template: { id: "alert", params: { channel: "slack", when: { countries: ["TR"] } } })
+    #
+    # Action code itself is JavaScript (exports.onExecute = async (event, api) => {...}),
+    # whatever language your server is written in.
+    class Actions
+      SLUG = /\A[a-z0-9][a-z0-9-]{1,62}\z/.freeze
+      TEMPLATE = /\A[a-z_]{1,64}\z/.freeze
+
+      attr_reader :secrets
+
+      def initialize(http)
+        @http = http
+        @secrets = ActionSecrets.new(http)
+      end
+
+      # Creates the Action or adds a version and makes it live (idempotent). A version
+      # asking for a loosening capability (skip_number_match, override_block,
+      # allow_silent) waits for an admin's phone approval: then "deployed" is false and
+      # "approval" => {"required" => true}.
+      def deploy(slug, trigger: nil, code: nil, template: nil, name: nil, secrets: nil, allowed_hosts: nil,
+                 capabilities: nil, on_failure: nil, order: nil, enabled: nil, activate: nil)
+        path = slug_path(slug)
+        raise ConfigError, "actions.deploy() needs code or template" if code.nil? && template.nil?
+
+        body = draft(trigger: trigger, code: code, template: template, secrets: secrets, allowed_hosts: allowed_hosts, capabilities: capabilities)
+        body["name"] = name unless name.nil?
+        body["onFailure"] = on_failure unless on_failure.nil?
+        body["order"] = order unless order.nil?
+        body["enabled"] = enabled unless enabled.nil?
+        body["activate"] = activate unless activate.nil?
+        @http.put(path, body)
+      end
+
+      def list
+        @http.get("/actions")["actions"] || []
+      end
+
+      # The Action, the active version's code and its versions.
+      def get(slug)
+        @http.get(slug_path(slug))
+      end
+
+      def version(slug, number)
+        @http.get("#{slug_path(slug)}/versions/#{Integer(number)}")
+      end
+
+      # Rename, turn on or off, reorder, change on_failure.
+      def update(slug, name: nil, enabled: nil, order: nil, on_failure: nil)
+        body = { "name" => name, "enabled" => enabled, "order" => order, "onFailure" => on_failure }.reject { |_, v| v.nil? }
+        res = @http.patch(slug_path(slug), body)
+        res["action"] || res
+      end
+
+      def delete(slug)
+        @http.delete(slug_path(slug))
+      end
+
+      # Back to +version+, or to the newest runnable version before the active one.
+      def rollback(slug, version: nil)
+        @http.post("#{slug_path(slug)}/rollback", version.nil? ? {} : { "version" => version })
+      end
+
+      # Runs a draft (or the deployed Action +slug+) once on a recorded event, your own
+      # event or the trigger's sample. Sends nothing.
+      def test(trigger: nil, code: nil, template: nil, slug: nil, secrets: nil, allowed_hosts: nil, capabilities: nil,
+               event_id: nil, event: nil, network: nil)
+        body = draft(trigger: trigger, code: code, template: template, slug: slug, secrets: secrets, allowed_hosts: allowed_hosts, capabilities: capabilities)
+        body["eventId"] = event_id unless event_id.nil?
+        body["event"] = Util.stringify(event) unless event.nil?
+        body["network"] = network unless network.nil?
+        @http.post("/actions/test", body)
+      end
+
+      # Replays a draft against recent real decisions: how many it would have changed
+      # ("changed", "transitions" such as "push→number_match" => 12), notifications,
+      # errors and timing. +replaces+: the deployed Action it would replace.
+      def dry_run(trigger: nil, code: nil, template: nil, slug: nil, secrets: nil, allowed_hosts: nil, capabilities: nil,
+                  replaces: nil, on_failure: nil, limit: nil, since: nil)
+        body = draft(trigger: trigger, code: code, template: template, slug: slug, secrets: secrets, allowed_hosts: allowed_hosts, capabilities: capabilities)
+        body["replaces"] = replaces unless replaces.nil?
+        body["onFailure"] = on_failure unless on_failure.nil?
+        body["limit"] = limit unless limit.nil?
+        body["since"] = since.respond_to?(:iso8601) ? since.iso8601 : since unless since.nil?
+        @http.post("/actions/dry-run", body)
+      end
+
+      # Recorded events (newest first, kept 30 days); use an id with test(event_id:).
+      def events(trigger: nil, limit: nil)
+        @http.get("/actions/events", { "trigger" => trigger, "limit" => limit })["events"] || []
+      end
+
+      # Live runs: decision, notifications, console output, errors.
+      def logs(slug, limit: nil, before: nil)
+        before = before.iso8601 if before.respond_to?(:iso8601)
+        @http.get("#{slug_path(slug)}/logs", { "limit" => limit, "before" => before })["logs"] || []
+      end
+
+      # +window+: 1h, 24h (default), 7d or 30d.
+      def metrics(slug, window: nil)
+        @http.get("#{slug_path(slug)}/metrics", { "window" => window })
+      end
+
+      # Every trigger with its decisions, capabilities, notification types and a sample event.
+      def triggers
+        @http.get("/actions/triggers")
+      end
+
+      def templates
+        @http.get("/actions/templates")["templates"] || []
+      end
+
+      # A template as plain code (to read, or to start a code Action from).
+      def render_template(id, trigger, params = {})
+        raise ConfigError, "Unknown template id" unless id.to_s.match?(TEMPLATE)
+
+        @http.post("/actions/templates/#{id}/render", { "trigger" => trigger, "params" => Util.stringify(params || {}) })
+      end
+
+      private
+
+      def slug_path(slug)
+        raise ConfigError, "An Action slug is 2-63 lowercase letters, digits or - (e.g. \"night-alert\")" unless slug.to_s.match?(SLUG)
+
+        "/actions/#{slug}"
+      end
+
+      def draft(trigger: nil, code: nil, template: nil, slug: nil, secrets: nil, allowed_hosts: nil, capabilities: nil)
+        body = {}
+        body["trigger"] = trigger unless trigger.nil?
+        body["slug"] = slug unless slug.nil?
+        body["code"] = code unless code.nil?
+        body["template"] = Util.stringify(template) unless template.nil?
+        body["secrets"] = secrets unless secrets.nil?
+        body["allowedHosts"] = allowed_hosts unless allowed_hosts.nil?
+        body["capabilities"] = capabilities unless capabilities.nil?
+        body
+      end
+    end
+
+    # Secrets your Actions read (event.secrets.NAME) or notify with. A value is encrypted
+    # and never readable again through the API.
+    class ActionSecrets
+      NAME = /\A[A-Z][A-Z0-9_]{0,63}\z/.freeze
+
+      def initialize(http)
+        @http = http
+      end
+
+      def set(name, value)
+        path = path(name)
+        raise ConfigError, "A secret value is a non-empty string" if value.to_s.empty?
+
+        @http.put(path, { "value" => value })
+      end
+
+      # Names only.
+      def list
+        @http.get("/actions/secrets")["secrets"] || []
+      end
+
+      def delete(name)
+        @http.delete(path(name))
+      end
+
+      private
+
+      def path(name)
+        raise ConfigError, "A secret name is capital letters, digits or _ (e.g. SLACK_WEBHOOK_URL)" unless name.to_s.match?(NAME)
+
+        "/actions/secrets/#{name}"
+      end
+    end
+  end
+end

data/lib/touchque/resources/agents.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # AI agents as identities of their own: register an agent with its PUBLIC key, give
+    # it an accountable owner and the action types it may ask approvals for, suspend,
+    # revoke or stop every agent at once. The agent itself never gets your API key: it
+    # signs in with its own key (Touchque::Agent).
+    #
+    #   keys = Touchque::AgentKeys.generate                     # where the agent runs
+    #   agent = tq.agents.create("Invoice bot", ["PAY_INVOICE"], public_key: keys["publicJwk"])
+    class Agents
+      attr_reader :vault
+
+      def initialize(http)
+        @http = http
+        @vault = AgentVault.new(http)
+        @jwks = nil
+        @jwks_at = 0
+        @audience = nil
+        @lock = Mutex.new
+      end
+
+      # Uses an agent's approval exactly once, right before you execute: checks the
+      # expectation against the token first (nothing is used on a mismatch), then
+      # Touchque checks the token and marks it used, and the answer is checked again.
+      def redeem_approval(token, user: nil, type: nil, authorization_details: nil)
+        expect = { user: user, type: type, authorization_details: authorization_details }
+        ApprovalToken.assert_matches!(ApprovalToken.decode(token)["claims"], **expect)
+        approval = @http.post("/agents/approvals/redeem", { "token" => token })["approval"] || {}
+        ApprovalToken.assert_matches!({ "sub" => approval["externalUsername"], "type" => approval["type"],
+                                        "authorization_details" => approval["authorizationDetails"] }, **expect)
+        approval
+      end
+
+      # The aud of this workspace's approval tokens (touchque:workspace:<id>), from
+      # GET /agents/approval-audience; asked once, then kept.
+      def approval_audience
+        @lock.synchronize do
+          unless @audience
+            audience = (@http.get("/agents/approval-audience") || {})["audience"]
+            raise ApprovalMismatchError, "Touchque did not name this workspace's approval audience" if !audience.is_a?(String) || audience.empty?
+
+            @audience = audience
+          end
+          @audience
+        end
+      end
+
+      # Verifies an approval token offline (Touchque's published keys, expiry, aud, the
+      # expectation). aud must be this workspace's: audience defaults to approval_audience,
+      # and a token without aud or for another workspace is refused. It does not make
+      # the token single-use: redeem_approval does.
+      def verify_approval_token(token, audience: nil, user: nil, type: nil, authorization_details: nil)
+        audience = approval_audience if audience.nil? || audience.to_s.empty?
+        expect = { audience: audience, user: user, type: type, authorization_details: authorization_details }
+        ApprovalToken.verify_with(token, jwks(false), **expect)
+      rescue ApprovalMismatchError => e
+        raise unless e.message.include?("unknown key")
+
+        ApprovalToken.verify_with(token, jwks(true), **expect)
+      end
+
+      # Registers an agent (needs the agents:write scope). owner_email: the accountable
+      # member (default the API key's creator; the agent stops when they leave).
+      def create(name, allowed_types, public_key: nil, public_keys: nil, description: nil, owner_email: nil, platform: nil, review_in_days: nil)
+        body = { "name" => name, "allowedTypes" => allowed_types.to_a }
+        body["description"] = description unless description.nil?
+        body["ownerEmail"] = owner_email unless owner_email.nil?
+        body["platform"] = platform unless platform.nil?
+        body["reviewInDays"] = review_in_days unless review_in_days.nil?
+        body["publicKey"] = public_only(public_key) unless public_key.nil?
+        body["publicKeys"] = public_keys.map { |k| public_only(k) } unless public_keys.nil?
+        @http.post("/agents", body)["agent"]
+      end
+
+      # {"agents" => [...], "killSwitch" => {...}}.
+      def list(status: nil)
+        @http.get("/agents", { "status" => status })
+      end
+
+      def get(agent_id)
+        @http.get(path(agent_id))["agent"]
+      end
+
+      # Changes, hands over (owner_email) or renews (review_in_days) an agent.
+      def update(agent_id, name: nil, description: nil, owner_email: nil, platform: nil, allowed_types: nil, review_in_days: nil)
+        body = { "name" => name, "description" => description, "ownerEmail" => owner_email, "platform" => platform,
+                 "allowedTypes" => allowed_types, "reviewInDays" => review_in_days }.reject { |_, v| v.nil? }
+        @http.patch(path(agent_id), body)["agent"]
+      end
+
+      # Adds a key (rotation: add the new one, move the agent to it, then remove the old one).
+      def add_key(agent_id, public_key)
+        @http.post("#{path(agent_id)}/keys", { "publicKey" => public_only(public_key) })["agent"]
+      end
+
+      # Removes a key; tokens the agent got with it stop at once.
+      def remove_key(agent_id, kid)
+        @http.delete("#{path(agent_id)}/keys/#{Util.seg(kid)}")["agent"]
+      end
+
+      # Stops an agent at once (its tokens too) until resumed.
+      def suspend(agent_id, reason: nil)
+        @http.post("#{path(agent_id)}/suspend", Util.compact({ "reason" => reason }))["agent"]
+      end
+
+      def resume(agent_id)
+        @http.post("#{path(agent_id)}/resume", {})["agent"]
+      end
+
+      # Revokes an agent for good (the record stays for the audit trail).
+      def revoke(agent_id)
+        @http.delete(path(agent_id))["agent"]
+      end
+
+      # Sets the agent's budgets, amounts, recipients and background rule (a full
+      # replacement): requestsPer10Min, requestsPerUserPer10Min, amountPerRequest /
+      # amountPerDay ({"TRY" => "1000.00"}), background (non_critical | never),
+      # newRecipients (ask | deny), recipientAllowlist, fourEyes, requirePasskeyAbove
+      # ({"TRY" => "10000.00"}: over it the person approves with a passkey on your page,
+      # never on the phone or with a mandate).
+      def set_policy(agent_id, policy)
+        @http.put("#{path(agent_id)}/policy", { "policy" => Util.stringify(policy) })["agent"]
+      end
+
+      # The workspace's agent events for a SIEM, oldest first: { "events", "next", "hasMore" }.
+      # Keep "next" and pass it as +after+; the first call reads from +since+ (ISO 8601;
+      # default the last 24 hours).
+      def list_events(after: nil, since: nil, limit: nil)
+        query = { "after" => after, "since" => since, "limit" => limit }.compact
+        @http.get("/agents/events", query.empty? ? nil : query)
+      end
+
+      # The workspace's policy: every agent's floor (an agent's own policy can only make it stricter).
+      def workspace_policy
+        @http.get("/agents/workspace-policy")["policy"]
+      end
+
+      # The name every other Touchque SDK uses (getWorkspacePolicy); workspace_policy stays.
+      alias get_workspace_policy workspace_policy
+
+      # Sets the workspace's policy (a full replacement; a field left out sets no floor).
+      def set_workspace_policy(policy)
+        @http.put("/agents/workspace-policy", { "policy" => Util.stringify(policy) })["policy"]
+      end
+
+      # The people who stopped this agent asking them (reason not_me, coached or rejections).
+      def list_blocks(agent_id)
+        @http.get("#{path(agent_id)}/blocks")["blocks"] || []
+      end
+
+      # Lets the agent ask this person again (check with them first).
+      def lift_block(agent_id, user)
+        @http.delete("#{path(agent_id)}/blocks/#{Util.seg(user)}")
+        nil
+      end
+
+      # An agent's mandates, optionally one person's.
+      def list_mandates(agent_id, user: nil)
+        @http.get("#{path(agent_id)}/mandates", { "externalUsername" => user })["mandates"] || []
+      end
+
+      # Ends an agent's mandate at once.
+      def revoke_mandate(agent_id, mandate_id)
+        @http.post("#{path(agent_id)}/mandates/#{Util.seg(mandate_id)}/revoke", {})
+      end
+
+      # Stops (true) or restarts (false) every agent of the workspace at once.
+      def set_kill_switch(engaged, reason: nil)
+        body = { "engaged" => engaged }
+        body["reason"] = reason if reason
+        @http.put("/agents/kill-switch", body)["killSwitch"]
+      end
+
+      private
+
+      def path(agent_id)
+        "/agents/#{Util.seg(agent_id)}"
+      end
+
+      # Refuses a private key before it leaves this process.
+      def public_only(jwk)
+        jwk = Util.stringify(jwk)
+        if jwk.key?("d")
+          raise ConfigError, "Pass the agent's PUBLIC key: this one has private parts (d). The private key must stay where the agent runs."
+        end
+
+        jwk
+      end
+
+      def jwks(force)
+        @lock.synchronize do
+          if force || @jwks.nil? || Util.now - @jwks_at > 300
+            @jwks = @http.get("/agents/jwks.json")
+            @jwks_at = Util.now
+          end
+          @jwks
+        end
+      end
+    end
+
+    # The token vault for your agents (tq.agents.vault): after your own OAuth flow with a
+    # person, deposit their tokens; Touchque keeps them sealed and refreshes them, and the
+    # agents a connection names get a short-lived access token
+    # (Touchque::Agent#get_connection_token), never the refresh token.
+    class AgentVault
+      def initialize(http)
+        @http = http
+      end
+
+      def list_connections
+        @http.get("/agents/vault/connections")["connections"] || []
+      end
+
+      # Adds or replaces a connection; client_secret is kept when left out of a replacement.
+      # provider: google, microsoft, github, facebook, linkedin, x or oidc.
+      def put_connection(name, provider:, client_id:, client_secret: nil, tenant: nil, issuer: nil, agent_ids: nil)
+        body = { "provider" => provider, "clientId" => client_id }
+        body.merge!(Util.compact({ "clientSecret" => client_secret, "tenant" => tenant, "issuer" => issuer }))
+        body["agentIds"] = agent_ids.to_a unless agent_ids.nil?
+        @http.put("/agents/vault/connections/#{Util.seg(name)}", body)["connection"]
+      end
+
+      # Removes it, and every person's tokens kept for it.
+      def remove_connection(name)
+        @http.delete("/agents/vault/connections/#{Util.seg(name)}")
+      end
+
+      # Keeps a person's tokens (replacing earlier ones) after your own OAuth flow with them.
+      def deposit(connection, user, access_token:, refresh_token: nil, expires_in: nil, scope: nil)
+        body = { "accessToken" => access_token }
+        body["refreshToken"] = refresh_token unless refresh_token.nil?
+        body["expiresIn"] = expires_in unless expires_in.nil?
+        body["scope"] = scope unless scope.nil?
+        @http.put("/agents/vault/accounts/#{Util.seg(connection)}/#{Util.seg(user)}", body)["account"]
+      end
+
+      # A person's accounts in the vault (never a token).
+      def list_accounts(user)
+        @http.get("/agents/vault/accounts", { "externalUsername" => user })["accounts"] || []
+      end
+
+      # Deletes a person's tokens: agents get nothing more for them there.
+      def remove_account(connection, user)
+        @http.delete("/agents/vault/accounts/#{Util.seg(connection)}/#{Util.seg(user)}")
+        nil
+      end
+    end
+  end
+end

data/lib/touchque/resources/device_risk.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Touchque
+  module Resources
+    # Device risk (a paid add-on, off until your workspace turns it on): a visitor ID for
+    # every browser on your sign-up, password-reset, sign-in or approval page. The page
+    # identifies with @touchque/web (deviceRisk.identify({ siteKey, purpose }) gives
+    # { visitorId, requestId, confidence }) and sends you the requestId. Never trust the
+    # page's copy: read the identification here (get_event) or check it for an account
+    # (check). Touchque keeps keyed hashes only, with a key of your workspace alone, and its
+    # risk engine decides.
+    #
+    # Every signal only ever asks for more: "stepUp" means an extra check on this page (an
+    # emailed code, a passkey, a number-matched approval), never a refusal. For sign-ins,
+    # pass the requestId to login.request / risk.check as device_risk_request_id: instead.
+    # Collect it only on these pages and name it in your privacy notice.
+    #
+    # With the script tag (device.js), the form arrives with touchque_request_id:
+    #
+    #   r = tq.device_risk.check(params[:touchque_request_id], event: "sign_in", external_username: email)
+    #
+    # Pass it as it came. Missing, empty, made up or expired, it is still a verdict
+    # ("report" missing, unknown, expired; the signal device_identification_missing), never an
+    # exception: a page without the tag, or with it blocked, only gets the visitor a step-up.
+    class DeviceRisk
+      # The pages a device report may come from.
+      EVENTS = %w[sign_in sign_up password_reset approval].freeze
+      # What the page had sent: ok, replayed, or no usable identification.
+      REPORTS = %w[ok replayed missing unknown expired invalid].freeze
+      REQUEST_ID = /\Adre_[A-Za-z0-9_-]{22}\z/
+
+      def initialize(http)
+        @http = http
+      end
+
+      # Reads an answer, failing toward asking: "stepUp" is true unless it says exactly
+      # false; junk signals are dropped.
+      def self.parse_check(raw)
+        body = raw.is_a?(Hash) ? raw : {}
+        signals = (body["signals"].is_a?(Array) ? body["signals"] : []).filter_map do |s|
+          next unless s.is_a?(Hash) && s["code"].is_a?(String)
+
+          item = { "code" => s["code"], "text" => s["text"].is_a?(String) ? s["text"] : "",
+                   "strength" => %w[passkey none].include?(s["strength"]) ? s["strength"] : "number_match" }
+          item["enforced"] = s["enforced"] if [true, false].include?(s["enforced"])
+          item["evidence"] = s["evidence"] if s["evidence"].is_a?(Hash)
+          item
+        end
+        out = {
+          "report" => REPORTS.include?(body["report"]) ? body["report"] : "invalid",
+          "requestId" => body["requestId"].is_a?(String) ? body["requestId"] : nil,
+          "visitorId" => body["visitorId"].is_a?(String) ? body["visitorId"] : nil,
+          "confidence" => body["confidence"].is_a?(Numeric) ? body["confidence"] : nil,
+          "visitor" => body["visitor"].is_a?(Hash) ? body["visitor"] : nil,
+          "counts" => body["counts"].is_a?(Hash) ? body["counts"] : nil,
+          # The address (never coordinates), the visitor's counts, one answer to "a bot?" (detected | suspected | not_detected).
+          "network" => body["network"].is_a?(Hash) ? body["network"] : nil,
+          "velocity" => body["velocity"].is_a?(Hash) ? body["velocity"] : nil,
+          "bot" => body["bot"].is_a?(Hash) ? body["bot"] : nil,
+          "signals" => signals,
+          "stepUp" => body["stepUp"] != false,
+          "wouldStepUp" => body["wouldStepUp"] == true,
+          "requires" => %w[number_match passkey].include?(body["requires"]) ? body["requires"] : "none",
+          "mode" => body["mode"] == "enforce" ? "enforce" : "shadow",
+          # The engine's state for this check; "unavailable" when the risk engine could not be reached and the verdict is a safe default.
+          "engine" => body["engine"].is_a?(String) ? body["engine"] : nil
+        }
+        out["caseCode"] = body["caseCode"] if body["caseCode"].is_a?(String)
+        out
+      end
+
+      # Checks the page's identification for an account: binds it (one account per
+      # identification, 15 minutes) and asks the risk engine. Pass the form field as it came:
+      # nil, empty or made up is still a verdict ("report" missing, unknown), never an
+      # exception. 409 device_risk_off until your workspace turns Device risk on.
+      # device_risk: instead of request_id, the page's report (deviceRisk.collect).
+      #
+      #   r = tq.device_risk.check(params[:touchque_request_id], event: "sign_up", external_username: email, client_ip: request.remote_ip)
+      #   ask_for_email_code if r["stepUp"]   # never refuse on it alone
+      def check(request_id = nil, event: "sign_in", external_username: nil, client_ip: nil, device_risk: nil)
+        raise ConfigError, "device_risk.check(): event must be one of #{EVENTS.join(", ")}" unless EVENTS.include?(event)
+
+        body = {}
+        if request_id.is_a?(String) && !request_id.empty?
+          body["requestId"] = request_id[0, 64]
+        elsif !device_risk.to_s.empty?
+          body["deviceRisk"] = device_risk
+        end
+        body["event"] = event
+        body["externalUsername"] = external_username unless external_username.to_s.empty?
+        body["clientIp"] = client_ip unless client_ip.to_s.empty?
+        self.class.parse_check(@http.post("/device-risk/check", body))
+      end
+
+      SEARCH_FILTERS = { from: "from", to: "to", signal: "signal", kind: "kind", origin: "origin", ip: "ip", account: "account",
+                         visitor_id: "visitorId", request_id: "requestId", cursor: "cursor" }.freeze
+
+      # Your workspace's identifications, newest first, one page at a time
+      # (GET /device-risk/events): a date range (from:/to: YYYY-MM-DD or ISO times; 7 days by
+      # default, at most 90, within your retention) and any of the filters. ip: is an address
+      # or a CIDR range and is never returned. Pass "nextCursor" back as cursor: until it is
+      # nil; do not page by moving the dates. A search that would read too much is a 422
+      # search_too_broad: narrow the range or add a filter.
+      # { "events" => [...], "nextCursor" => String | nil, "from" => String, "to" => String }.
+      def search_events(step_up: nil, limit: nil, **filters)
+        unknown = filters.keys - SEARCH_FILTERS.keys
+        raise ConfigError, "device_risk.search_events() does not know #{unknown.join(', ')}" unless unknown.empty?
+        raise ConfigError, "device_risk.search_events() limit must be 1 to 100" unless limit.nil? || (limit.is_a?(Integer) && limit.between?(1, 100))
+
+        params = {}
+        filters.each { |k, v| params[SEARCH_FILTERS[k]] = v if v.is_a?(String) && !v.empty? }
+        params["stepUp"] = step_up ? "true" : "false" if [true, false].include?(step_up)
+        params["limit"] = limit.to_s if limit
+        raw = @http.get("/device-risk/events", params) || {}
+        cursor = raw["nextCursor"]
+        { "events" => raw["events"].is_a?(Array) ? raw["events"] : [],
+          "nextCursor" => cursor.is_a?(String) && !cursor.empty? ? cursor : nil,
+          "from" => raw["from"].to_s, "to" => raw["to"].to_s }
+      end
+
+      # The trusted identification behind a request_id: the visitor, how sure, what the page
+      # showed, the risk engine's verdict. Read-only.
+      def get_event(request_id)
+        raise ConfigError, "device_risk.get_event() needs a request_id (dre_...)" unless request_id.is_a?(String) && REQUEST_ID.match?(request_id)
+
+        @http.get("/device-risk/events/#{request_id}")
+      end
+    end
+  end
+end