Offline Token Verification

The Key Endpoint

GET https://shield.edge.network/.well-known/jwks.json

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "…",
      "kid": "a1b2c3d4e5f60718",
      "alg": "EdDSA",
      "use": "sig"
    }
  ]
}

Cache the key set for up to an hour. If you encounter a token with an unknown kid header, refetch once — that's how key rotation propagates.

Verifying a Token

Any JWT library that supports EdDSA works. With jose in Node:

import { createRemoteJWKSet, jwtVerify } from 'jose'

const JWKS = createRemoteJWKSet(
  new URL('https://shield.edge.network/.well-known/jwks.json')
)

async function verifyOffline(token, sitekey) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: 'edge-shield',
    subject: sitekey, // REQUIRED — binds the token to YOUR widget
  })
  return {
    score: payload.score,      // 1–100 humanity score
    hostname: payload.hn,      // hostname the widget ran on
    agent: payload.agt || null // verified agent domain, if declared
  }
}

Your verification must check, in order:

1. The signature, against a JWKS key matching the token's kid
2. iss equals edge-shield
3. sub equals your sitekey — without this check, a token minted for any Shield widget anywhere would pass
4. exp — tokens live 5 minutes
5. Optionally, that hn is one of your hostnames

The claims you get back:

{
  "iss": "edge-shield",
  "sub": "es_...",              // the widget's sitekey
  "jti": "b3f9…",               // unique token id (replay ledger key)
  "iat": 1785459151,
  "exp": 1785459451,            // 5-minute lifetime
  "score": 92,                  // 1–100 humanity score
  "hn": "example.com",          // hostname the widget ran on
  "agt": "crawler.example",     // optional: verified agent domain
  "agm": "web-bot-auth"         // optional: agent verification method
}

The Trade-Off: No Single-Use Guarantee

The one thing offline verification cannot give you is replay protection. The ledger of spent tokens lives on Shield's servers, so only siteverify guarantees that a token verifies exactly once. Verified offline, the same token is valid for its full 5-minute lifetime, as many times as it's presented.

You can narrow the replay window further by rejecting tokens whose iat is older than your form could plausibly take to submit — 60 seconds is a common choice.