rootherald
The server→server Background-Check client for Ruby 3.1+. Mint a challenge, appraise the client's opaque evidence with your rh_sk_ secret key, and get the verdict back directly. Depends only on faraday.
This SDK is implemented but not yet published to its package registry. Until it ships, collect an opaque evidence blob on the device and appraise it server-side with @rootherald/node (or any available server SDK). The API shown below is the planned surface and may change before release.
How it works
Your keyless client collects an opaque evidence blob and hands it to your backend. Your backend uses RootHerald::BackgroundCheck, authenticated with its rh_sk_ secret, to mint a nonce (issue_challenge) and submit the evidence for appraisal (verify). The verdict is computed by Root Herald and returned to your backend — it never travels through the client, which holds no key.
Install
gem "rootherald"bundle install
# or, without bundler:
gem install rootheraldConstruct the client
The initializer validates the key — anything not starting with rh_sk_ raises ArgumentError.
require "rootherald"
rh = RootHerald::BackgroundCheck.new(secret_key: ENV.fetch("RH_SECRET_KEY")) # rh_sk_…Mint a challenge
# Relay challenge.nonce to your client; it quotes over it and returns an
# opaque evidence blob to your backend.
challenge = rh.issue_challengeVerify the evidence
verify returns an AttestResult whose .verdict is a symbol (:allow / :warn / :deny), plus .device (the raw device hash) and advisory-only cohort accessors. Only protocol/auth/quota problems raise — a failing device does not.
# 'evidence' is the opaque blob your client collected, passed through verbatim.
result = rh.verify(evidence, challenge_id: challenge.challenge_id,
policy: "rootherald:builtin:strict-hardware")
return head(:forbidden) unless result.verdict == RootHerald::Verdict::ALLOW
# result.device is the raw device hash (camelCase keys from the wire).
device_id = result.device["ueid"]A runnable Rails demo that calls the client from a controller ships in the SDK repo under samples/rails-demo. Instantiate RootHerald::BackgroundCheck in an initializer and call issue_challenge / verify from your controller actions.