Acceptance policies, TPM classes & assurance tiers

Every enrolled device is classified into one root-of-trust class, derived from its hardware key's certificate (the EK cert issuer + the TCG manufacturer identifier) or, for mobile, from the platform attestation. Classes roll up into groups you author policy against:

Tokens carry the device's class as tpm_class (kebab-cased, e.g. hardware-discrete-infineon), so you can branch on it in your own code even when the policy accepted it.

You don't have to author anything. Select a built-in by name from the dashboard, pin it to an API key, or name it per-call as the policy argument to rh.verify(). The appraisal is run against it server→server, so the verdict you get back already reflects it.

Need something between the built-ins? Register a named policy (you get back a UUID you reference afterwards; the policy lives server-side, you don't ship a rule blob in every request). The coarse form is a few fields:

// Authorization: Bearer rh_sk_live_…   (Owner role)
{
  "name": "My app — accept hardware + Nitro",
  "description": "Hardware and firmware TPMs everywhere; AWS NitroTPM for our CI runners.",
  "acceptedClassGroups": ["hardware", "firmware-tpm", "mobile-hardware"],
  "acceptedSpecificClasses": ["cloud-vtpm-aws-nitro"],
  "unacceptedBehavior": "reject",          // "reject" | "warn"
  "requireCloudCrossValidation": true,
  "minAcr": "urn:rootherald:device:high",
  "minimumEarStatus": "affirming",
  "mode": "strict"
}
// → 201 Created (PolicyDetail):
// {
//   "id": "8f3a…",
//   "name": "My app — accept hardware + Nitro",
//   "isBuiltIn": false,
//   "version": 1,
//   "acceptedClassGroups": ["hardware", "firmware-tpm", "mobile-hardware"],
//   "acceptedSpecificClasses": ["cloud-vtpm-aws-nitro"],
//   "unacceptedBehavior": "reject",
//   "requireCloudCrossValidation": true,
//   "minAcr": "urn:rootherald:device:high",
//   "mode": "strict"
// }

acceptedClassGroups takes group names (hardware, cloud-vtpm, …); acceptedSpecificClasses pins individual vendor classes (e.g. cloud-vtpm-aws-nitro). Anything outside the accepted set is governed by unacceptedBehavior: "warn" lets out-of-set devices through with a warn verdict and a degraded trustworthiness vector (useful for shadow-banning or review queues), while "reject" blocks them outright.

A separate axis from TPM class. The acr value says what the authenticationachieved. Root Herald treats a requested tier as a hard requirement: if it can't be satisfied, the attestation does not issue a token at that tier, never a silently-weaker result. A policy may also impose an ACR floor (minAcr).

Higher tiers subsume lower ones. The acr claim in the issued token is the single tier that was actually satisfied, never the preference list, never a partial match.

If your policy accepts a cloud-vtpm class and requireCloudCrossValidationis on (the default), the device must additionally submit cloud-provider instance-identity evidence so the verifier can bind "this virtual TPM" to "this specific instance, in this account": the defence against relaying a vTPM attestation from a different instance.

The cloud evidence is bundled into the opaque blob the dumb client collects. Your server submits it with rh.verify() (naming a cloud-cross-validating policy) and reads the resulting device verdict returned directly.

cloudEvidence: {
  provider: "aws",
  nitroAttestationDocument: body.nitroDoc,        // CBOR/COSE, from the Nitro hypervisor
  ec2InstanceIdentityDocument: body.iid,          // from IMDSv2
  ec2InstanceIdentitySignature: body.iidSig,
  getInstanceTpmEkPubResult: body.ekPub,          // from the EC2 GetInstanceTpmEkPub API
}

Azure (provider: "azure", IMDS attested document) and GCP (provider: "gcp", GCE instance identity token) follow the same pattern. The verifier checks the cloud doc chains to that cloud's root, the EK matches what was enrolled, and the instance/account/region are what you expect.

For server/workload attestation generally, also consider cloud-native primitives (AWS Nitro Enclaves attestation documents, SPIFFE/SPIRE, cloud workload identity). A hardware TPM is the wrong tool for "is this container the workload I expect?". Root Herald is strongest for endpoint devices.