JWT Claims

if (payload.risk_score === undefined) {
  // Free plan, or a claim your plan does not include
}

{
  "sub": "SGVsbG8sIHdvcmxkIQ-keyId",
  "kid": "SGVsbG8sIHdvcmxkIQ-keyId",
  "iat": 1772107200,
  "exp": 1772110800,
  "iss": "app-attest-acme",
  "aud": "Acme",
  "team_id": "ABBM6U9RM5",
  "bundle_id": "com.acme.app",
  "risk_score": 12,
  "device_integrity": "high",
  "jailbreak_detected": false,
  "attestation_count": 47,
  "first_seen": 1764331200,
  "last_attestation": 1772107200,
  "permissions": ["basic", "payments", "transfers", "high_value", "admin"],
  "custom_claims": {
    "user_tier": "premium",
    "subscription": {
      "tier": "plus",
      "is_active": true,
      "environment": "production",
      "expires_at": 1774699200
    }
  }
}

{
  "sub": "SGVsbG8sIHdvcmxkIQ-keyId",
  "kid": "SGVsbG8sIHdvcmxkIQ-keyId",
  "iat": 1772107200,
  "exp": 1772110800,
  "iss": "app-attest-acme",
  "aud": "Acme",
  "team_id": "ABBM6U9RM5",
  "bundle_id": "com.acme.app",
  "custom_claims": {
    "environment": "production"
  }
}

npm install jose

import { createRemoteJWKSet, jwtVerify } from 'jose'

// Create once at module scope — it caches keys and refreshes on rotation.
const JWKS = createRemoteJWKSet(
  new URL('https://api.grantiva.io/.well-known/jwks.json')
)

// Per-organization. Decode a real token to read the exact values.
const ISSUER = 'app-attest-acme'
const AUDIENCE = 'Acme'

export async function verifyDeviceToken(token) {
  const { payload } = await jwtVerify(token, JWKS, {
    algorithms: ['RS256'],
    issuer: ISSUER,
    audience: AUDIENCE,
  })
  // jose already checked signature, exp, iss and aud.
  return payload
}

// Authorization decision from the signed risk score.
export function riskGate(payload, { highStakes = false } = {}) {
  const score = payload.risk_score

  if (score === undefined) {
    // Free plan, or a plan without risk scoring in the token.
    // Fall back to your own signals — do not treat "no score" as "safe".
    return highStakes ? 'step-up' : 'allow'
  }

  if (payload.jailbreak_detected) return 'deny'
  if (score > 75) return 'deny'
  if (score > 20) return highStakes ? 'step-up' : 'allow'

  // score <= 20. The token can still be up to an hour old.
  const ageSeconds = Math.floor(Date.now() / 1000) - payload.iat
  if (highStakes && ageSeconds > 300) return 'step-up'

  return 'allow'
}

// Express middleware
export async function requireAttestedDevice(req, res, next) {
  const token = req.headers.authorization?.replace(/^Bearer /, '')
  if (!token) return res.status(401).json({ error: 'missing device token' })

  let payload
  try {
    payload = await verifyDeviceToken(token)
  } catch {
    return res.status(401).json({ error: 'invalid or expired device token' })
  }

  const decision = riskGate(payload, { highStakes: false })
  if (decision === 'deny') {
    return res.status(403).json({ error: 'device blocked' })
  }

  req.device = { keyId: payload.sub, payload, decision }
  next()
}

pip install "PyJWT[crypto]"

import time
import jwt
from jwt import PyJWKClient

# Create once at import — it caches the key set.
jwks_client = PyJWKClient("https://api.grantiva.io/.well-known/jwks.json")

# Per-organization. Decode a real token to read the exact values.
ISSUER = "app-attest-acme"
AUDIENCE = "Acme"


def verify_device_token(token: str) -> dict:
    signing_key = jwks_client.get_signing_key_from_jwt(token)
    return jwt.decode(
        token,
        signing_key.key,
        algorithms=["RS256"],
        issuer=ISSUER,
        audience=AUDIENCE,
    )


def risk_gate(payload: dict, high_stakes: bool = False) -> str:
    score = payload.get("risk_score")  # absent on Free

    if score is None:
        # No signed score. Fall back to your own signals —
        # "no score" is not the same as "low risk".
        return "step-up" if high_stakes else "allow"

    if payload.get("jailbreak_detected"):
        return "deny"
    if score > 75:
        return "deny"
    if score > 20:
        return "step-up" if high_stakes else "allow"

    # score <= 20. The score was captured when the token was minted.
    if high_stakes and (int(time.time()) - payload["iat"]) > 300:
        return "step-up"

    return "allow"


# FastAPI dependency
from fastapi import Header, HTTPException


async def attested_device(authorization: str = Header(default="")) -> dict:
    token = authorization.removeprefix("Bearer ").strip()
    if not token:
        raise HTTPException(status_code=401, detail="missing device token")
    try:
        payload = verify_device_token(token)
    except jwt.PyJWTError:
        raise HTTPException(status_code=401, detail="invalid or expired device token")

    if risk_gate(payload) == "deny":
        raise HTTPException(status_code=403, detail="device blocked")

    return payload