How attestation works
The whole mechanism, end to end, with the engineering detail included. The short version lives on how it works; this is the one that names the components.
Your app collects a sealed proof from the device's chip
Virtually every modern laptop and phone has a small security chip built in: a TPM on Windows and Linux, a Secure Enclave on Apple hardware. The SDK asks that chip for a fresh, sealed proof that the request is coming from a specific, real, physical machine — not a script, not a rented cloud server. That act, the device cryptographically proving what it is, is what attestation means.
This is the only work that happens on the user's device, and it is hands-off. The client holds none of Root Herald's keys and makes no decision. It hands the sealed proof back to your app, tied to the action you care about — signup, claim, vote, game-launch, or your own label — and your app forwards it to your server.
// Collect a fresh, sealed proof from the device's security chip,
// bound to a one-time challenge from your server. The client
// consults no key and renders no verdict.
char* evidence = nullptr;
RootHeraldClient_CollectEvidence(nonce, &evidence);
// Hand the opaque `evidence` blob to your backend to check (step 5).
RootHeraldClient_FreeEvidence(evidence);
// On the web, the extension collects the same opaque proof; your
// backend checks it with @rootherald/node (see step 5).The chip signs a one-time challenge
Before it trusts anything, your server hands the device a one-time challenge (a nonce), and the chip signs that exact value. This is what keeps the proof fresh: a proof captured yesterday, or copied off another machine, carries the wrong challenge and is thrown out. You get a proof made for this request, not a recording someone can replay.
Windows and Linux ship today. Mobile and macOS are coming: Hardware Key Attestation on Android, App Attest on iOS, and the Secure Enclave on macOS at a reduced assurance level.
On Windows and Linux the SDK talks to a local native host over the extension's native-messaging API. The host issues a TPM2_Quote over PCRs 0–7 under the server nonce, reads the EK public key and certificate off the chip, and pulls any missing intermediate certificates from the Windows TPM store, Intel PTT NV handles, or the AMD fTPM AIA endpoint as needed.
We confirm the proof came from genuine hardware
A software fake can call itself anything, but it cannot forge a real chip manufacturer's signature. We trace the proof back to the manufacturer that made the chip and confirm that manufacturer is on our trust anchor list. This is the line between a genuine device and a rented cloud server or emulator pretending to be one.
If a piece of the chain is genuinely unreachable for a moment we retry; if it doesn't trace back to a trusted manufacturer we reject outright and never retry.
EkCertificateValidator walks the EK certificate chain. When intermediates are missing, AiaChaser follows AIA URLs up to 16 levels deep, backed by a Postgres and in-memory cache with stale-while-revalidate, and the chain must terminate at one of our pinned manufacturer roots. ChainFailureKind separates operational failures (EkChainFetchFailed, retry-eligible) from cryptographic ones (EkNotTrusted, EkKeyMismatch, never retried).
We check it against your rules
A policy is your rule for how strict to be: accept real hardware only, or allow cloud devices too. Different products draw that line in different places, so you pick the rule and we enforce it on every check.
Five built-ins cover most needs — strict-hardware, strict-hardware-permissive-mobile, cloud-permissive, enterprise-managed-only and dev — or you can author your own. When you choose to allow cloud devices we don't take their word for it: the proof is bound to a specific cloud instance and anything that doesn't match is rejected.
PolicyResolver picks the policy by three-rung resolution: per-call → per-session → per-project default → strict-hardware fallback. For cloud-permissive policies the cross-validators run here — NitroTPM plus EC2 instance identity, Azure IMDS-attested data, and the GCP instance-identity JWT each bind the cloud vTPM to one specific instance. A mismatch rejects with the audit event cloud_cross_validation_failed.
You get a pass, warn, or fail — plus an anonymous device id
Your server makes one server-to-server call and gets back a verdict: a pass / warn / fail answer plus an anonymous per-device id. There is no token to store and no state to keep. The id is stable per chip for you but cannot be correlated to any other company, so you learn “is this the same device as last time?” with no tracking cookie and no personal data.
const rh = new RootHerald({ secretKey: process.env.RH_SECRET_KEY }); // rh_sk_…
const { challengeId, nonce } = await rh.issueChallenge(); // relay nonce to client
const verdict = await rh.verify(evidence, { // check it server→server
challengeId,
policy: "rootherald:builtin:strict-hardware",
});
// verdict ≈ AttestationVerdict
{
"acr": "urn:rootherald:device:high",
"device": {
"ueid": "2f9c8a14…", // stable per-company device id (no PII)
"verdict": "pass", // pass | warn | fail
"earStatus": "affirming", // affirming | warning | contraindicated
"attestationType": "tpm20",
"secureBootVerified": true,
"trustworthinessVector": { "hardware": 2, "configuration": 2 }
}
}