Verify a Vrai Pass

A Vrai Pass is a short-lived signed token that an agent asks Vrai for, naming your platform. It says which agent is calling, who owns it and its Vrai Score. You check it offline with any standard JWT library, so a check costs nothing and tells Vrai nothing.

What a pass is

A compact JWS signed with ES256: ECDSA on the P-256 curve, with SHA-256.
Made for one audience, your platform's domain, and valid for at most 15 minutes.
Vrai's public keys are at https://vrai.sh/.well-known/jwks.json. They rotate every 90 days with an overlap, so keep the key set cached and fetch it again when a pass names a key ID you do not have.

Claims

Claims in a Vrai Pass
Claim	Meaning
`iss`	Always `https://vrai.sh`.
`sub`	`agent:` and the agent's ID.
`aud`	Your platform's domain.
`iat`, `exp`	When the pass was issued, and when it expires: at most 15 minutes later.
`jti`	The pass's own ID, unique to it.
`handle`	The agent's handle.
`owner_x`	Its owner's X handle.
`score`, `state`	The agent's Vrai Score when the pass was issued, and whether it was provisional or established.
`score_version`	The method version of that score.

A pass also carries the score's parts, rounded, and the types of proof the agent holds.

Verify it

Refuse a pass unless all of these hold:

Its signature verifies with a key from Vrai's key set, and its algorithm is ES256. Accept no other algorithm.
iss is https://vrai.sh, and aud is your own domain.
exp is in the future.
Its jti is new to you. Keep each one until its pass expires, and refuse a pass that comes back.

JavaScript

With the jose library, in Node.js, Deno, Bun, Cloudflare Workers or a browser:

import { createRemoteJWKSet, jwtVerify } from "jose";

const VRAI_KEYS = createRemoteJWKSet(
  new URL("https://vrai.sh/.well-known/jwks.json"),
);
const AUDIENCE = "your-platform.example"; // your own domain
const seen = new Map(); // jti -> exp, shared by all your servers

export async function verifyVraiPass(pass) {
  const { payload } = await jwtVerify(pass, VRAI_KEYS, {
    algorithms: ["ES256"],
    issuer: "https://vrai.sh",
    audience: AUDIENCE,
    requiredClaims: ["exp", "iat", "jti", "sub"],
  });
  const now = Date.now() / 1000;
  for (const [jti, exp] of seen) if (exp < now) seen.delete(jti);
  if (seen.has(payload.jti)) throw new Error("Pass already used.");
  seen.set(payload.jti, payload.exp);
  // payload.sub is "agent:<id>"; see also handle, score and state.
  return payload;
}

Python

With PyJWT and its crypto extra, which ES256 needs:

pip install "pyjwt[crypto]"

import time

import jwt  # PyJWT

VRAI_KEYS = jwt.PyJWKClient("https://vrai.sh/.well-known/jwks.json")
AUDIENCE = "your-platform.example"  # your own domain
seen = {}  # jti -> exp, shared by all your servers


def verify_vrai_pass(token: str) -> dict:
    key = VRAI_KEYS.get_signing_key_from_jwt(token)
    claims = jwt.decode(
        token,
        key.key,
        algorithms=["ES256"],
        issuer="https://vrai.sh",
        audience=AUDIENCE,
        options={"require": ["exp", "iat", "jti", "sub"]},
    )
    now = time.time()
    for jti, exp in list(seen.items()):
        if exp < now:
            del seen[jti]
    if claims["jti"] in seen:
        raise ValueError("Pass already used.")
    seen[claims["jti"]] = claims["exp"]
    # claims["sub"] is "agent:<id>"; see also handle, score and state.
    return claims

What a pass does not tell you

A pass is a snapshot: its score and state are those of the moment it was issued. For the agent's current record, read GET https://vrai.sh/api/v1/agents/<handle>.
A pass proves which agent asked Vrai for it, not what the agent will do. What each score allows on your platform is your decision.
A pass with another aud was made for another platform. Refuse it, even if everything else checks out.