Skip to content
Verification spec · EdDSA + RFC 8785 JCS · Schema 1.4.0

Verify a passport without us

Every passport carries an Ed25519 signature and is hashed into a daily Merkle root we publish. Both verify offline. This page is the spec and a working implementation.

Two checks, two different questions

Signature

Did Agenstry issue this exact document? An EdDSA signature over the RFC 8785 canonicalisation of the passport. Any edit — one flipped byte in one signal — breaks it.

Inclusion proof

Did Agenstry say it on that date? A Merkle path from this passport to a daily root published before now. We cannot back-date a friendlier passport, because that day's root is already out.

You want both: a signature alone would let us re-sign history; a proof alone wouldn't bind the content to us.

The three public inputs

curl -s https://agenstry.com/api/v1/passport/example.com        > passport.json
curl -s https://agenstry.com/api/v1/passport/example.com/proof  > proof.json
curl -s https://agenstry.com/.well-known/jwks.json              > jwks.json

The JWKS holds the signing key, selected by the passport's key_id. Retired keys stay published, so archived passports keep verifying.

Check 1 — the signature

The signature is a detached compact JWS (header..signature, empty payload segment — the payload is the document you're holding). The signed bytes are the JCS canonicalisation of the passport with the signature key removed, and nothing else removed: key_id, signed_at and the whole verification block are inside the signature, so nobody can repoint jwks_url at a key they control.

import base64, json
from cryptography.hazmat.primitives.asymmetric import ed25519

def jcs(obj):  # RFC 8785, sufficient for the value types a passport holds
    return json.dumps(obj, sort_keys=True, separators=(",", ":"),
                      ensure_ascii=False).encode()

def b64d(s): return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
def b64e(b): return base64.urlsafe_b64encode(b).rstrip(b"=").decode()

passport = json.load(open("passport.json"))
jwks     = json.load(open("jwks.json"))

header_b64, _, sig_b64 = passport["signature"].split(".")
header = json.loads(b64d(header_b64))
assert header["alg"] == "EdDSA"
assert header["typ"] == "agenstry-passport+jws"   # not a badge or card signature

jwk = next(k for k in jwks["keys"]
           if k["kid"] == header["kid"] and k["kty"] == "OKP")
key = ed25519.Ed25519PublicKey.from_public_bytes(b64d(jwk["x"]))

payload = {k: v for k, v in passport.items() if k != "signature"}
key.verify(b64d(sig_b64), f"{header_b64}.{b64e(jcs(payload))}".encode())
print("signature OK —", header["kid"])

Check 2 — the inclusion proof

The leaf commits to verification.content_digest: a SHA-256 over the JCS form of just schema_version, subject, signals and summary. It excludes issued_at and signed_at (change on every fetch), our issuer URLs, and history/tier (differ between free and paid views). One leaf means one agent's trust state on one day.

import hashlib

def sha256(b): return hashlib.sha256(b).digest()

proof  = json.load(open("proof.json"))["proof"]
subset = {k: passport[k] for k in
          ("schema_version", "subject", "signals", "summary") if k in passport}
digest = "sha256:" + hashlib.sha256(jcs(subset)).hexdigest()
assert digest == proof["content_digest"], "this proof is about a different document"

# Leaf: sha256("passport" \0 domain \0 digest)
domain = passport["subject"]["domain"]
node = sha256(("passport\0" + domain + "\0" + digest).encode())
assert node.hex() == proof["leaf"]

# Walk up to the passports sub-root. An odd node carries up unchanged,
# so a level with no sibling emits no step.
for step in proof["audit_path"]:
    sib = bytes.fromhex(step["hash"])
    node = sha256(node + sib) if step["position"] == "right" else sha256(sib + node)
assert node.hex() == proof["passports_sub_root"]

# Rebuild the day's root from the sub-roots, in the published order.
def merkle_root(leaves):
    layer = list(leaves)
    while len(layer) > 1:
        layer = [sha256(layer[i] + layer[i+1]) if i+1 < len(layer) else layer[i]
                 for i in range(0, len(layer), 2)]
    return layer[0].hex()

values = {**proof["sibling_sub_roots"], "passports": node.hex()}
nodes  = [sha256(f"{label}:".encode() + values[label].encode())
          for label in proof["sub_root_order"]]
assert merkle_root(nodes) == proof["merkle_root"]
print("anchored in the root published for", proof["date"])

Cross-check proof.merkle_root against the root listed on /transparency for that date. If they agree, the passport was in a tree we published.

Signed but not yet anchored

Anchoring runs once per UTC day, the morning after the day closes. A newer passport is signed but not yet in a root: verification.inclusion_proof_available says so, and the proof endpoint returns not_anchored. An agent indexed today is first provable tomorrow.

An inclusion proof attests to the trust state as measured when that day's tree was built, not to a live document.

Ready-made verifier

The repository ships scripts/verify_passport_offline.py, the code above with argument parsing (standard library plus cryptography). Exit code 0 means every requested check passed.

python verify_passport_offline.py \
    --passport passport.json --proof proof.json --jwks jwks.json

SIGNATURE  PASS  signed by agenstry-passport-ed25519-1
INCLUSION  PASS  anchored in the root published for 2026-08-05

There is also POST https://agenstry.com/api/v1/passport/verify, which returns the same verdict. That still means trusting us; the offline path doesn't.

Key rotation

When we rotate, the new key signs new passports and the retired public key stays in the JWKS indefinitely, so passports signed under it keep verifying.