developers
Verify a signed intent in ~15 lines.
No SDK required. Any language with an ed25519 library and an HTTP client can verify a customer handle envelope. Below: minimal working examples in shell, Node, Go, and Python.
The wire format
An intent envelope is a JSON object. It travels in the request body or the
X-Handle-Intent header (base64url of the JSON).
{
"from": "/u/aclay",
"intent": "refund.request",
"scope": ["read:orders","write:refunds(self)"],
"body": { "order": "HC-orders-2026-04812" },
"issued": "2026-06-28T14:02:11Z",
"expires": "2026-06-28T15:02:11Z",
"nonce": "01HXR7Z1M6...4V",
"sig": "ed25519:7af3…c01b"
}
Curl — smoke test
# 1. fetch handle's public keys (JWKS-shaped)
curl -s https://username.md/u/aclay/.well-known/keys
# 2. POST a signed intent to your endpoint
curl -X POST https://api.example.com/refunds \
-H "Content-Type: application/json" \
-H "X-Handle-Intent: $(cat intent.json | base64)" \
-d @body.json
Node — 15-line verify
import { verify } from "@noble/ed25519";
async function verifyIntent(env) {
const jwks = await fetch(
`https://username.md${env.from}/.well-known/keys`
).then(r => r.json());
const key = jwks.keys.find(k => k.use === "sig");
const msg = canonicalize({ ...env, sig: undefined });
const ok = await verify(
hex(env.sig.split(":")[1]), utf8(msg), b64u(key.x)
);
if (!ok) throw new Error("bad signature");
if (Date.parse(env.expires) < Date.now()) throw new Error("expired");
return env;
}
Go — sidecar verify
import (
"crypto/ed25519"
"encoding/json"
"net/http"
"time"
)
func verifyIntent(env Envelope) error {
jwks, _ := fetchJWKS(env.From)
pub := ed25519.PublicKey(jwks.Sig())
msg, _ := canonicalize(env)
if !ed25519.Verify(pub, msg, env.Sig()) {
return errors.New("bad signature")
}
if time.Now().After(env.Expires) {
return errors.New("expired")
}
return nil
}
Python — inline verify
from nacl.signing import VerifyKey
import httpx, json, datetime as dt
def verify_intent(env):
jwks = httpx.get(f"https://username.md{env['from']}/.well-known/keys").json()
pub = VerifyKey(bytes.fromhex(jwks["keys"][0]["x"]))
msg = json.dumps({k:v for k,v in env.items() if k!="sig"}, sort_keys=True).encode()
pub.verify(msg, bytes.fromhex(env["sig"].split(":")[1]))
assert dt.datetime.fromisoformat(env["expires"]) > dt.datetime.utcnow()
return env
Reference services
Sidecar
verifyd
Tiny Go verify service. Runs at :8081, exposes POST /verify. Suitable
for ForwardAuth in Traefik or ext_authz in Envoy.
Library
@aboutus/verify
Zero-dep Node package (planned). Two functions: verifyIntent(env) and
Express.middleware().