touchque 5.0.0

data/lib/touchque/resources/webhook.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Touchque
+  # Storage for webhook jtis already accepted. +check_and_set+ must atomically record
+  # the jti for +ttl_seconds+ and return true when it was NOT seen before. Use
+  # MemoryReplayCache in one process, or one over Redis (SET key 1 NX EX ttl) or your
+  # database when you run several (Puma clusters, several hosts).
+  class MemoryReplayCache
+    def initialize(max_entries: 100_000)
+      @max_entries = [max_entries, 2].max
+      @seen = {}
+      @lock = Mutex.new
+    end
+
+    def check_and_set(jti, ttl_seconds)
+      @lock.synchronize do
+        now = Time.now.to_f
+        return false if @seen[jti] && @seen[jti] > now
+
+        if @seen.size >= @max_entries
+          @seen.delete_if { |_, exp| exp <= now }
+          @seen.shift while @seen.size >= @max_entries
+        end
+        @seen[jti] = now + ttl_seconds
+        true
+      end
+    end
+  end
+
+  module Resources
+    # Webhook signature verification (signed with your API secret).
+    class Webhook
+      DEFAULT_TOLERANCE_SECONDS = 300
+
+      # "reason" values of a REJECTED login webhook. Treat a value you do not know as a rejection.
+      REASON_USER_REJECTED = "user_rejected"
+      # The user said "this wasn't me": 2FA is frozen.
+      REASON_USER_REPORTED_FRAUD = "user_reported_fraud"
+      # The user said someone on the phone told them to approve: 2FA is frozen; treat it as a takeover in progress.
+      REASON_USER_REPORTED_COACHED = "user_reported_coached"
+      # An AI agent's request: the user said no and blocked the agent from asking them again (no 2FA freeze).
+      REASON_USER_BLOCKED_AGENT = "user_blocked_agent"
+      REASON_RISK_REVERSED = "risk_reversed"
+      REASON_RISK_STEP_UP = "risk_step_up"
+      REASON_APPROVAL_SIGNATURE_INVALID = "approval_signature_invalid"
+      REASON_DEVICE_INTEGRITY_FAILED = "device_integrity_failed"
+      # Vishing Shield: approved during a call (or with the screen shared / remote-controlled), critical, no passkey.
+      REASON_VISHING_SUSPECTED = "vishing_suspected"
+      # Mirror Alarm: the sign-in page was not on your site (a real-time phishing proxy).
+      REASON_PHISHING_ORIGIN = "phishing_origin"
+
+      # "event" values of event webhooks. Ignore types you do not know.
+      EVENT_DEVICE_LINKED = "DEVICE_LINKED"
+      EVENT_DEVICE_UNLINKED = "DEVICE_UNLINKED"
+      EVENT_PASSKEY_REGISTERED = "PASSKEY_REGISTERED"
+      EVENT_PASSKEY_DELETED = "PASSKEY_DELETED"
+      # Device risk: an identification or a device_risk.check raised a signal that asks for more. Never a trait.
+      EVENT_DEVICE_RISK_SIGNAL = "DEVICE_RISK_SIGNAL"
+      # Device risk: an alert rule of the workspace went off.
+      EVENT_DEVICE_RISK_ALERT = "DEVICE_RISK_ALERT"
+      # After the call, the user confirmed a provisional approval was theirs: critical actions are allowed again.
+      EVENT_APPROVAL_RECONFIRMED = "APPROVAL_RECONFIRMED"
+      # The user took an approval back (reason COACHED or UNDO): end the session built on it.
+      EVENT_APPROVAL_REVOKED = "APPROVAL_REVOKED"
+      # Mobile SDK: send this push with your own keys (Mobile.push_from_webhook).
+      EVENT_MOBILE_PUSH = "MOBILE_PUSH"
+      EVENT_AGENT_CREATED = "AGENT_CREATED"
+      EVENT_AGENT_SUSPENDED = "AGENT_SUSPENDED"
+      EVENT_AGENT_RESUMED = "AGENT_RESUMED"
+      EVENT_AGENT_REVOKED = "AGENT_REVOKED"
+      EVENT_AGENT_KEY_ADDED = "AGENT_KEY_ADDED"
+      EVENT_AGENT_KEY_REMOVED = "AGENT_KEY_REMOVED"
+      # The kill switch stopped every AI agent of the workspace.
+      EVENT_AGENTS_PAUSED = "AGENTS_PAUSED"
+      EVENT_AGENTS_RESUMED = "AGENTS_RESUMED"
+      EVENT_AGENT_POLICY_CHANGED = "AGENT_POLICY_CHANGED"
+      EVENT_AGENT_WORKSPACE_POLICY_CHANGED = "AGENT_WORKSPACE_POLICY_CHANGED"
+      EVENT_AGENT_APPROVAL_REDEEMED = "AGENT_APPROVAL_REDEEMED"
+      # A person stopped an AI agent from asking them ("this wasn't me", coached, or three rejections).
+      EVENT_AGENT_BLOCKED_BY_PERSON = "AGENT_BLOCKED_BY_PERSON"
+      EVENT_AGENT_UNBLOCKED_FOR_PERSON = "AGENT_UNBLOCKED_FOR_PERSON"
+      # An AI agent sent the same request to the same person three times in 10 minutes.
+      EVENT_AGENT_LOOP_DETECTED = "AGENT_LOOP_DETECTED"
+      EVENT_AGENT_MANDATE_REQUESTED = "AGENT_MANDATE_REQUESTED"
+      EVENT_AGENT_MANDATE_REVOKED = "AGENT_MANDATE_REVOKED"
+      # An AI agent's text carried an instruction to the model or a link that carries data; the request was refused.
+      EVENT_AGENT_INJECTION_SUSPECTED = "AGENT_INJECTION_SUSPECTED"
+      # An approval came back sooner than a person can answer; it is never usable.
+      EVENT_AGENT_INHUMAN_APPROVAL = "AGENT_INHUMAN_APPROVAL"
+      # A new or renamed AI agent's name read like another agent's; it was refused.
+      EVENT_AGENT_LOOKALIKE_NAME = "AGENT_LOOKALIKE_NAME"
+      # Never Locked Out (tq.recovery): every step of a recovery, with "recoveryId" and "status".
+      # RECOVERY_COMPLETED is followed by DEVICE_LINKED ("via" => "recovery"); VETOED, EXPIRED
+      # and FAILED end it without a move.
+      EVENT_RECOVERY_STARTED = "RECOVERY_STARTED"
+      EVENT_RECOVERY_DEVICE_BOUND = "RECOVERY_DEVICE_BOUND"
+      # The vouchers' quorum was reached: the account moves at "coolOffUntil" unless vetoed.
+      EVENT_RECOVERY_COOLING = "RECOVERY_COOLING"
+      EVENT_RECOVERY_COMPLETED = "RECOVERY_COMPLETED"
+      EVENT_RECOVERY_VETOED = "RECOVERY_VETOED"
+      EVENT_RECOVERY_EXPIRED = "RECOVERY_EXPIRED"
+      EVENT_RECOVERY_FAILED = "RECOVERY_FAILED"
+      # Help desk (tq.assist): a session opened or ended, a check on the phone passed or failed
+      # ("outcome": wrong_number, not_me, coached, declined), approvals unfrozen after a check.
+      EVENT_ASSIST_OPENED = "ASSIST_OPENED"
+      EVENT_ASSIST_ENDED = "ASSIST_ENDED"
+      EVENT_ASSIST_CHECK_PASSED = "ASSIST_CHECK_PASSED"
+      EVENT_ASSIST_CHECK_FAILED = "ASSIST_CHECK_FAILED"
+      EVENT_ASSIST_UNFROZEN = "ASSIST_UNFROZEN"
+      # The person checked that the agent from IT is really working on their account.
+      EVENT_ASSIST_CLAIM_CONFIRMED = "ASSIST_CLAIM_CONFIRMED"
+      # Nobody from IT was working on the account when the person asked: someone is pretending to be IT.
+      EVENT_ASSIST_CLAIM_UNVERIFIED = "ASSIST_CLAIM_UNVERIFIED"
+
+      def initialize(api_secret)
+        @secret = api_secret
+      end
+
+      # Never shows the API secret (logs, consoles, error reporters).
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      # Verifies an incoming webhook and returns its payload.
+      #
+      # raw_body: the request body exactly as received. signature: the x-signature header
+      # (nil uses the "signature" field inside the body). tolerance_seconds: reject a
+      # callback whose signed timestamp is missing, invalid or further than this from now
+      # (0 disables it). replay_cache: a second delivery of the same jti raises
+      # WebhookReplayError (answer 200, don't run your side effects again).
+      def verify(raw_body, signature = nil, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, replay_cache: nil)
+        payload = Util.parse_json(raw_body.to_s)
+        raise WebhookSignatureError, "invalid JSON payload" unless payload.is_a?(Hash)
+
+        provided = signature.to_s.empty? ? payload["signature"] : signature
+        raise WebhookSignatureError, "no signature provided" unless provided.is_a?(String) && !provided.empty?
+
+        begin
+          canonical = self.class.canonicalize(raw_body.to_s)
+        rescue JSON::ParserError
+          raise WebhookSignatureError, "could not canonicalize the payload"
+        end
+        # Never put the expected signature in the error: it would be a signing oracle.
+        raise WebhookSignatureError, "invalid signature" unless Util.secure_compare(Util.hmac_hex(@secret, canonical), provided)
+
+        # Touchque always signs a timestamp: a missing or unparseable one fails closed.
+        if tolerance_seconds.positive?
+          at = Util.parse_time(payload["timestamp"])
+          raise WebhookSignatureError, "timestamp is missing or invalid" if at.nil?
+          raise WebhookSignatureError, "timestamp is outside the allowed window" if (Time.now.to_f - at).abs > tolerance_seconds
+        end
+
+        if replay_cache
+          jti = payload["jti"]
+          raise WebhookSignatureError, "jti is missing" unless jti.is_a?(String) && !jti.empty?
+          # Remember it for twice the window so it outlives any timestamp that could still pass.
+          raise WebhookReplayError.new(jti) unless replay_cache.check_and_set(jti, [tolerance_seconds * 2, 600].max)
+        end
+        payload
+      end
+
+      # The server's stableStringify: drop "signature", sort the TOP-LEVEL keys only (by
+      # UTF-16 code units, like JavaScript), keep each value's bytes (nested key order,
+      # number spelling); insignificant whitespace is removed.
+      def self.canonicalize(raw_body)
+        raise JSON::ParserError, "not an object" unless JSON.parse(raw_body).is_a?(Hash)
+
+        members = {}
+        Util.top_level_members(raw_body).each { |key, value| members[key] = value unless key == "signature" }
+        body = members.keys.sort_by { |k| k.encode("UTF-16BE").bytes }.map do |key|
+          "#{Util.js_string(key)}:#{Util.compact_json(members[key])}"
+        end
+        "{#{body.join(",")}}"
+      end
+    end
+  end
+end

data/lib/touchque/safe_approval.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Touchque
+  # Safe Guard approvals, checked without trusting Touchque. The approver's phone decodes the
+  # raw Safe transaction itself and signs, with a P-256 key only its biometrics unlock, a
+  # 105-byte approval that TouchqueSafeGuard checks on chain:
+  #
+  #   index (1) | expiresAt (8) | displayDigest (32) | r (32) | s (32)
+  #
+  # over the SHA-256 of the 149-byte message
+  #
+  #   "TQG1" | purpose (1) | chainId (32) | guard (20) | Safe (20) | subject (32) | expiresAt (8) | displayDigest (32)
+  #
+  # where subject is the Safe transaction hash (EIP-712, purpose 1 "approve") or, for a change
+  # the guard schedules, the governance hash (purpose 2 "schedule"). verify makes the guard's
+  # check off chain: both hashes are computed here from the raw fields, so a co-signer (or your
+  # own server) refuses an approval of anything else, whoever relayed it.
+  #
+  # A target is { "chainId", "safe", "guard", "tx" => { "to", "value", "data", "operation",
+  # "safeTxGas", "baseGas", "gasPrice", "gasToken", "refundReceiver", "nonce" } } (string or
+  # symbol keys); integers as Integer or decimal strings.
+  module SafeApproval
+    MAGIC = "TQG1".b
+    PURPOSES = { "approve" => 1, "schedule" => 2 }.freeze
+    # The guard (MAX_APPROVAL_TTL) refuses an approval valid for longer than a day.
+    MAX_APPROVAL_TTL = 86_400
+    # OpenZeppelin P256 (the guard) refuses s above N/2.
+    HALF_N = 0x7fffffff800000007fffffffffffffffde737d56d38bcf4279dce5617e3192a8
+    MAX_UINT256 = (1 << 256) - 1
+    MAX_UINT64 = (1 << 64) - 1
+    ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
+    # SubjectPublicKeyInfo prefix of an uncompressed P-256 point.
+    SPKI_P256 = ["3059301306072a8648ce3d020106082a8648ce3d030107034200"].pack("H*")
+    MASK = (1 << 64) - 1
+    RC = %w[
+      0000000000000001 0000000000008082 800000000000808a 8000000080008000 000000000000808b 0000000080000001
+      8000000080008081 8000000000008009 000000000000008a 0000000000000088 0000000080008009 000000008000000a
+      000000008000808b 800000000000008b 8000000000008089 8000000000008003 8000000000008002 8000000000000080
+      000000000000800a 800000008000000a 8000000080008081 8000000000008080 0000000080000001 8000000080008008
+    ].map { |h| h.to_i(16) }.freeze
+    # Rotation of lane x + 5y.
+    ROT = [0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14].freeze
+
+    module_function
+
+    # The Safe transaction hash (EIP-712, domain = chainId + the Safe): what the owners sign and
+    # an ordinary approval covers.
+    def safe_tx_hash(target)
+      t = parse(target)
+      domain = keccak256(TYPE_HASHES[:domain] + t[:chain_id] + t[:safe])
+      struct = keccak256(
+        TYPE_HASHES[:safe_tx] + t[:to] + t[:value] + keccak256(t[:data]) + t[:operation] + t[:safe_tx_gas] +
+        t[:base_gas] + t[:gas_price] + t[:gas_token] + t[:refund_receiver] + t[:nonce]
+      )
+      hex(keccak256("\x19\x01".b + domain + struct))
+    end
+
+    # What the guard schedules a governance change under: the change itself, without the nonce
+    # or gas fields.
+    def governance_hash(target)
+      t = parse(target)
+      hex(keccak256(TYPE_HASHES[:governance] + t[:chain_id] + t[:safe] + t[:to] + t[:value] + keccak256(t[:data]) + t[:operation]))
+    end
+
+    # The 149-byte message the phone signs (its SHA-256 is what the guard verifies), as 0x hex.
+    # +purpose+ is "approve" or "schedule"; +expires_at+ Unix seconds.
+    def message(purpose:, chain_id:, guard:, safe:, subject:, expires_at:, display_digest:)
+      code = PURPOSES[purpose.to_s] or raise ConfigError, "SafeApproval: purpose is \"approve\" or \"schedule\""
+      hex(
+        MAGIC + code.chr + uint(chain_id, "chainId", MAX_UINT64) + address(guard, "guard")[12, 20] + address(safe, "safe")[12, 20] +
+        bytes(subject, "subject", 32) + uint(expires_at, "expiresAt", MAX_UINT64)[24, 8] + bytes(display_digest, "displayDigest", 32)
+      )
+    end
+
+    # SHA-256 of the rows as "label\x1Fvalue" joined by "\x1E" (UTF-8), as 0x hex: the digest an
+    # approval carries. Rows are { "label", "value" } (string or symbol keys).
+    def display_digest(rows)
+      canonical = rows.map { |r| "#{field(r, "label")}\u001F#{field(r, "value")}" }.join("\u001E")
+      "0x#{OpenSSL::Digest::SHA256.hexdigest(canonical.encode("UTF-8"))}"
+    end
+
+    # Checks a phone's Safe Guard approval the way TouchqueSafeGuard does, without trusting the
+    # server that relayed it: the Safe and governance hashes come from +target+, the key from
+    # the guard's approver list on chain ("x || y", 128 hex characters, or { "x", "y" }).
+    # +purpose+: what you are about to use the approval for, "approve" (the default: run this
+    # very Safe transaction) or "schedule" (start this governance change's waiting time). A
+    # schedule approval covers no nonce or gas fields, so it is accepted only when you name
+    # "schedule". +approver_index+: the approval must name it.
+    # +display_digest+ or +rows+: from your own decoding, the rows the phone must have shown.
+    # +now+: a Time or Unix seconds.
+    #
+    # Returns { "valid", "reason", "purpose", "approverIndex", "expiresAt", "displayDigest",
+    # "safeTxHash", "governanceHash" }; "reason" is nil when valid, else approval_malformed,
+    # public_key_invalid, approver_index_mismatch, approval_expired, rows_differ, high_s or
+    # signature_invalid. Raises ConfigError only when +target+ is not a Safe transaction.
+    #
+    #   status = tq.safe_guard.status(request_id)
+    #   check = Touchque::SafeApproval.verify(my_tx, status["safeTx"]["approval"], approver_key_from_chain, approver_index: 0)
+    #   raise "approval refused: #{check["reason"]}" unless check["valid"]
+    def verify(target, approval, public_key, purpose: nil, approver_index: nil, display_digest: nil, rows: nil, now: nil)
+      t = parse(target)
+      hashes = { "safeTxHash" => safe_tx_hash(target), "governanceHash" => governance_hash(target) }
+      parsed = { "approverIndex" => nil, "expiresAt" => nil, "displayDigest" => nil }
+      refuse = ->(reason) { { "valid" => false, "reason" => reason, "purpose" => nil }.merge(parsed, hashes) }
+      return refuse.call("approval_malformed") unless approval.is_a?(String) && approval.match?(/\A(0x)?[0-9a-fA-F]{210}\z/)
+
+      b = [strip0x(approval)].pack("H*")
+      expires_at = b[1, 8].unpack1("Q>")
+      parsed = { "approverIndex" => b.getbyte(0), "expiresAt" => expires_at, "displayDigest" => hex(b[9, 32]) }
+      key = ec_key(public_key)
+      return refuse.call("public_key_invalid") if key.nil?
+      return refuse.call("approver_index_mismatch") if !approver_index.nil? && approver_index != parsed["approverIndex"]
+
+      seconds = now.nil? ? Time.now.to_i : now.to_i
+      return refuse.call("approval_expired") if expires_at < seconds || expires_at > seconds + MAX_APPROVAL_TTL
+
+      expected = display_digest || (rows && SafeApproval.display_digest(rows))
+      return refuse.call("rows_differ") if expected && "0x#{strip0x(expected.downcase)}" != parsed["displayDigest"]
+
+      r = b[41, 32].unpack1("H*").to_i(16)
+      s = b[73, 32].unpack1("H*").to_i(16)
+      return refuse.call("high_s") if s > HALF_N
+
+      der = OpenSSL::ASN1::Sequence([OpenSSL::ASN1::Integer(OpenSSL::BN.new(r)), OpenSSL::ASN1::Integer(OpenSSL::BN.new(s))]).to_der
+      # Never falls back to "schedule": that one is valid at any nonce.
+      p = (purpose || "approve").to_s
+      msg = message(
+        purpose: p, chain_id: t[:chain_id].unpack1("H*").to_i(16), guard: hex(t[:guard][12, 20]), safe: hex(t[:safe][12, 20]),
+        subject: p == "approve" ? hashes["safeTxHash"] : hashes["governanceHash"], expires_at: expires_at, display_digest: parsed["displayDigest"]
+      )
+      ok = begin
+        key.verify("SHA256", der, [strip0x(msg)].pack("H*"))
+      rescue OpenSSL::PKey::PKeyError
+        false
+      end
+      return refuse.call("signature_invalid") unless ok
+
+      { "valid" => true, "reason" => nil, "purpose" => p }.merge(parsed, hashes)
+    end
+
+    # The owners' Safe signatures with the approvals appended (approvals by index | count |
+    # "TQG1"): the signatures argument of execTransaction for an ordinary transaction.
+    def with_approvals(owner_signatures, approvals)
+      items = approval_bytes(approvals)
+      hex(bytes(owner_signatures, "ownerSignatures") + items.join + items.size.chr + MAGIC)
+    end
+
+    # The call data of guard.schedule(safe, governanceHash, approvals), which starts a
+    # governance change's waiting time.
+    def schedule_call(safe, governance_hash, approvals)
+      joined = approval_bytes(approvals).join
+      hex(
+        TYPE_HASHES[:schedule][0, 4] + address(safe, "safe") + bytes(governance_hash, "governanceHash", 32) + uint(96, "offset", MAX_UINT256) +
+        uint(joined.bytesize, "length", MAX_UINT256) + joined + ("\0".b * ((32 - (joined.bytesize % 32)) % 32))
+      )
+    end
+
+    # ── Keccak-256 (the Ethereum hash: Keccak padding, not SHA3-256) ──
+
+    def rotl(value, n)
+      n.zero? ? value : (((value << n) | (value >> (64 - n))) & MASK)
+    end
+
+    def keccak_f(a)
+      RC.each do |rc|
+        c = (0...5).map { |x| a[x] ^ a[x + 5] ^ a[x + 10] ^ a[x + 15] ^ a[x + 20] }
+        5.times do |x|
+          d = c[(x + 4) % 5] ^ rotl(c[(x + 1) % 5], 1)
+          0.step(20, 5) { |y| a[x + y] ^= d }
+        end
+        b = Array.new(25, 0)
+        5.times { |x| 5.times { |y| b[y + (5 * (((2 * x) + (3 * y)) % 5))] = rotl(a[x + (5 * y)], ROT[x + (5 * y)]) } }
+        0.step(20, 5) { |y| 5.times { |x| a[x + y] = b[x + y] ^ (~b[((x + 1) % 5) + y] & b[((x + 2) % 5) + y] & MASK) } }
+        a[0] ^= rc
+      end
+      a
+    end
+
+    def keccak256(data)
+      rate = 136
+      padded = data.b + ("\0".b * (rate - (data.bytesize % rate)))
+      padded.setbyte(data.bytesize, padded.getbyte(data.bytesize) ^ 0x01)
+      padded.setbyte(padded.bytesize - 1, padded.getbyte(padded.bytesize - 1) ^ 0x80)
+      a = Array.new(25, 0)
+      (0...padded.bytesize).step(rate) do |off|
+        padded[off, rate].unpack("Q<17").each_with_index { |lane, k| a[k] ^= lane }
+        keccak_f(a)
+      end
+      a[0, 4].pack("Q<4")
+    end
+
+    TYPE_HASHES = {
+      domain: keccak256("EIP712Domain(uint256 chainId,address verifyingContract)"),
+      safe_tx: keccak256("SafeTx(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,address gasToken,address refundReceiver,uint256 nonce)"),
+      # The guard contract hashes this exact string, so it keeps its original spelling.
+      governance: keccak256("TouchQueGovernance(uint256 chainId,address safe,address to,uint256 value,bytes32 dataHash,uint8 operation)"),
+      schedule: keccak256("schedule(address,bytes32,bytes)")
+    }.freeze
+
+    # ── Field parsing: the partner's own data, so a wrong field raises ──
+
+    def field(hash, key)
+      hash.key?(key) ? hash[key] : hash[key.to_sym]
+    end
+
+    def parse(target)
+      tx = target.is_a?(Hash) ? field(target, "tx") : nil
+      raise ConfigError, "SafeApproval: pass { \"chainId\", \"safe\", \"guard\", \"tx\" => { \"to\", \"value\", \"data\", \"operation\", ..., \"nonce\" } }" unless tx.is_a?(Hash)
+
+      operation = field(tx, "operation") || 0
+      raise ConfigError, "SafeApproval: tx.operation must be 0 (call) or 1 (delegatecall)" unless [0, 1].include?(operation)
+
+      {
+        chain_id: uint(field(target, "chainId"), "chainId", MAX_UINT64),
+        safe: address(field(target, "safe"), "safe"),
+        guard: address(field(target, "guard"), "guard"),
+        to: address(field(tx, "to"), "tx.to"),
+        value: uint(field(tx, "value") || 0, "tx.value", MAX_UINT256),
+        data: bytes(field(tx, "data") || "0x", "tx.data"),
+        operation: uint(operation, "tx.operation", 1),
+        safe_tx_gas: uint(field(tx, "safeTxGas") || 0, "tx.safeTxGas", MAX_UINT256),
+        base_gas: uint(field(tx, "baseGas") || 0, "tx.baseGas", MAX_UINT256),
+        gas_price: uint(field(tx, "gasPrice") || 0, "tx.gasPrice", MAX_UINT256),
+        gas_token: address(field(tx, "gasToken") || ZERO_ADDRESS, "tx.gasToken"),
+        refund_receiver: address(field(tx, "refundReceiver") || ZERO_ADDRESS, "tx.refundReceiver"),
+        nonce: uint(field(tx, "nonce"), "tx.nonce", MAX_UINT256)
+      }
+    end
+
+    # A non-negative integer (Integer or decimal string) as a 32-byte word.
+    def uint(value, name, max)
+      v = if value.is_a?(Integer) then value
+          elsif value.is_a?(String) && value.match?(/\A(0|[1-9][0-9]*)\z/) then value.to_i
+          end
+      raise ConfigError, "SafeApproval: #{name} must be a non-negative integer (a decimal string for large values)" if v.nil? || v.negative? || v > max
+
+      [v.to_s(16).rjust(64, "0")].pack("H*")
+    end
+
+    def address(value, name)
+      raise ConfigError, "SafeApproval: #{name} must be an address (0x and 40 hex characters)" unless value.is_a?(String) && value.match?(/\A0x[0-9a-fA-F]{40}\z/)
+
+      ("\0".b * 12) + [value[2..]].pack("H*")
+    end
+
+    def bytes(value, name, size = nil)
+      unless value.is_a?(String) && value.match?(/\A0x(?:[0-9a-fA-F]{2})*\z/) && (size.nil? || value.length == 2 + (2 * size))
+        raise ConfigError, "SafeApproval: #{name} must be 0x-prefixed hex#{size ? " of #{size} bytes" : ""}"
+      end
+
+      [value[2..]].pack("H*")
+    end
+
+    def approval_bytes(approvals)
+      list = Array(approvals)
+      raise ConfigError, "SafeApproval: pass 1 to 255 approvals" unless list.size.between?(1, 255)
+
+      list.each_with_index.map { |a, i| bytes(a.to_s.start_with?("0x") ? a : "0x#{a}", "approvals[#{i}]", 105) }.sort_by.with_index { |a, i| [a.getbyte(0), i] }
+    end
+
+    def ec_key(key)
+      xy = key.is_a?(Hash) ? strip0x(field(key, "x").to_s) + strip0x(field(key, "y").to_s) : strip0x(key.to_s)
+      return nil unless xy.match?(/\A[0-9a-fA-F]{128}\z/)
+
+      ec = OpenSSL::PKey.read(SPKI_P256 + ["04#{xy}"].pack("H*"))
+      ec.public_key.on_curve? ? ec : nil
+    rescue OpenSSL::PKey::PKeyError, OpenSSL::PKey::EC::Point::Error
+      nil
+    end
+
+    def strip0x(text)
+      text.start_with?("0x") ? text[2..] : text
+    end
+
+    def hex(data)
+      "0x#{data.unpack1("H*")}"
+    end
+
+    private_class_method :rotl, :keccak_f, :keccak256, :field, :parse, :uint, :address, :bytes, :approval_bytes, :ec_key, :strip0x, :hex
+  end
+end

data/lib/touchque/security_events.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Touchque
+  # A refused Security Event Token (Shared Signals). +error+ is the RFC 8935 error
+  # to answer with (HTTP 400 {"err": error}): invalid_request, invalid_key,
+  # invalid_issuer or invalid_audience; temporarily_unavailable when the issuer's
+  # keys could not be read (answer 503: the transmitter tries again).
+  class SecurityEventError < Error
+    attr_reader :error
+
+    def initialize(error, message)
+      @error = error
+      super(message)
+    end
+  end
+
+  # Shared Signals (OpenID Shared Signals Framework 1.0): Security Event Tokens
+  # (SETs, RFC 8417) an identity provider sends when something happens to a
+  # person's account after sign-in: CAEP session-revoked, credential-change,
+  # device-compliance-change; RISC account-disabled, credential-compromise.
+  # Touchque SSO sends them for an organization's members to the receivers its
+  # admin adds (Organization > Continuous access). Your app ends the person's
+  # sessions or asks them to sign in again.
+  #
+  # Push delivery (RFC 8935), the SET is the request body (application/secevent+jwt):
+  #
+  #   VERIFIER = Touchque::SecurityEventVerifier.new(issuer: "https://sso.touchque.com", audience: "https://app.example.com")
+  #   post "/ssf" do
+  #     event = VERIFIER.verify(request.body.read)
+  #     end_sessions_of(event["subject"]["email"]) if event["name"] == "session-revoked"
+  #     status 202
+  #   rescue Touchque::SecurityEventError => e
+  #     halt 400, { err: e.error, description: e.message }.to_json
+  #   end
+  #
+  # Poll delivery (RFC 8936): Touchque::SecurityEvents.poll(url:, token:, ack: [...]).
+  #
+  # A SET does not expire: it says what happened. Keep the jtis you handled and
+  # skip a repeat.
+  module SecurityEvents
+    # The event types Touchque sends, by their short name.
+    TYPES = {
+      "session-revoked" => "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
+      "credential-change" => "https://schemas.openid.net/secevent/caep/event-type/credential-change",
+      "device-compliance-change" => "https://schemas.openid.net/secevent/caep/event-type/device-compliance-change",
+      "account-disabled" => "https://schemas.openid.net/secevent/risc/event-type/account-disabled",
+      "credential-compromise" => "https://schemas.openid.net/secevent/risc/event-type/credential-compromise",
+      "verification" => "https://schemas.openid.net/secevent/ssf/event-type/verification",
+      "stream-updated" => "https://schemas.openid.net/secevent/ssf/event-type/stream-updated"
+    }.freeze
+    NAMESPACE = %r{\Ahttps://schemas\.openid\.net/secevent/(caep|risc|ssf)/event-type/([a-z0-9-]+)\z}.freeze
+
+    module_function
+
+    # One poll: acknowledges what you handled and returns { "sets" => { jti => token }, "more_available" => bool }.
+    def poll(url:, token:, ack: nil, set_errs: nil, max_events: nil, return_immediately: nil)
+      raise ConfigError, "#{url} must be an https URL" unless CrossAppAccess.safe_url?(url)
+      raise ConfigError, "poll needs the stream's token" if token.to_s.empty?
+
+      body = {}
+      body["ack"] = ack unless ack.nil?
+      body["setErrs"] = set_errs unless set_errs.nil?
+      body["maxEvents"] = max_events unless max_events.nil?
+      body["returnImmediately"] = return_immediately unless return_immediately.nil?
+      headers = { "Content-Type" => "application/json", "Accept" => "application/json", "Authorization" => "Bearer #{token}" }
+      status, text, = Transport.call("POST", url, headers: headers, body: JSON.generate(body), timeout: 30)
+      data = Util.parse_json(text)
+      data = {} unless data.is_a?(Hash)
+      raise SecurityEventError.new((data["error"] || "server_error").to_s, "#{url} answered #{status}") unless status == 200
+
+      { "sets" => data["sets"].is_a?(Hash) ? data["sets"] : {}, "more_available" => data["moreAvailable"] == true }
+    end
+  end
+
+  # Checks a SET: signature (RS256, the issuer's keys), typ, issuer, audience, one event.
+  class SecurityEventVerifier
+    def initialize(issuer:, audience:, jwks_uri: nil, jwks: nil, clock_skew: 300, fetch: nil)
+      raise ConfigError, "SecurityEventVerifier needs issuer (the transmitter) and audience (your stream's aud)" if issuer.to_s.empty? || audience.to_s.empty?
+
+      @issuer = issuer
+      @audience = audience
+      @jwks_uri = jwks_uri
+      @skew = clock_skew
+      @fetch = fetch || CrossAppAccess.method(:get_json)
+      @pinned = !jwks.nil?
+      @keys = {}
+      @keys_at = 0
+      @tried_at = 0
+      @lock = Mutex.new
+      set_keys(jwks) if jwks
+    end
+
+    # The SET, checked: { "jti", "issuer", "audience" (list), "issued_at", "txn" (Touchque's case code),
+    # "subject" (sub_id), "type" (URI), "name" (short name, or nil), "claims" (the event's own) },
+    # or SecurityEventError.
+    def verify(token)
+      bad = ->(message) { SecurityEventError.new("invalid_request", message) }
+      parts = JWS.split(token.to_s.strip)
+      raise bad.call("not a JWT") unless parts
+
+      head, c, input, sig = parts
+      raise bad.call("not a Security Event Token (typ secevent+jwt)") unless head["typ"].to_s.downcase == "secevent+jwt"
+      raise SecurityEventError.new("invalid_key", "unsupported signature") unless head["alg"] == "RS256" && head["kid"].is_a?(String)
+
+      key = begin
+        key_for(head["kid"])
+      rescue StandardError => e
+        raise SecurityEventError.new("temporarily_unavailable", "the transmitter's keys could not be read: #{e.message}")
+      end
+      raise SecurityEventError.new("invalid_key", "signature does not verify") unless key && JWS.verify("RS256", key, input, sig)
+      raise SecurityEventError.new("invalid_issuer", "another issuer") unless c["iss"] == @issuer
+
+      audience = (c["aud"].is_a?(Array) ? c["aud"] : [c["aud"]]).select { |a| a.is_a?(String) }
+      raise SecurityEventError.new("invalid_audience", "not for this receiver") unless audience.include?(@audience)
+      raise bad.call("jti and iat are required") unless c["jti"].is_a?(String) && c["iat"].is_a?(Integer)
+      raise bad.call("issued in the future") if c["iat"] - @skew > Util.now
+
+      events = c["events"]
+      raise bad.call("a SET carries exactly one event") unless events.is_a?(Hash) && events.length == 1
+
+      type, claims = events.first
+      m = SecurityEvents::NAMESPACE.match(type)
+      {
+        "jti" => c["jti"], "issuer" => c["iss"], "audience" => audience, "issued_at" => c["iat"],
+        "txn" => c["txn"].is_a?(String) ? c["txn"] : nil, "subject" => c["sub_id"].is_a?(Hash) ? c["sub_id"] : {},
+        "type" => type, "name" => m ? m[2] : nil, "claims" => claims.is_a?(Hash) ? claims : {}
+      }
+    end
+
+    private
+
+    def set_keys(jwks)
+      @keys = (jwks["keys"] || []).each_with_object({}) { |k, h| h[k["kid"]] = k if k["kid"] }
+      @keys_at = Util.now
+    end
+
+    def load_keys
+      unless @jwks_uri
+        meta = @fetch.call("#{@issuer.chomp("/")}/.well-known/ssf-configuration")
+        raise "the transmitter's metadata does not match its issuer" unless meta["issuer"] == @issuer && meta["jwks_uri"].is_a?(String)
+
+        @jwks_uri = meta["jwks_uri"]
+      end
+      raise "#{@jwks_uri} must be an https URL" unless CrossAppAccess.safe_url?(@jwks_uri)
+
+      set_keys(@fetch.call(@jwks_uri))
+    end
+
+    def key_for(kid)
+      return @keys[kid] if @pinned
+
+      @lock.synchronize do
+        load_keys if @keys_at.zero? || Util.now - @keys_at > 3600
+        if !@keys.key?(kid) && Util.now - @tried_at > 300
+          @tried_at = Util.now
+          load_keys
+        end
+        @keys[kid]
+      end
+    end
+  end
+end