Part of AAuth. Live at whoami.aauth.dev.
A reference resource server demonstrating AAuth identity claim release. Agents present an agent_token, receive a resource_token pointing at their Person Server, and come back with an auth_token that unlocks the caller's identity claims.
Drive the full flow in the AAuth Playground — it handles agent signing, the PS interaction, and consent. Pick the whoami tab after bootstrapping an agent.
| URL | Description |
|---|---|
| / | Identity claims endpoint (signed requests only) |
| /.well-known/aauth-resource.json | Resource metadata with scope_descriptions |
| /.well-known/jwks.json | Public signing key (Ed25519) |
Every request to GET / must carry an RFC 9421 HTTP Message Signature whose Signature-Key is a JWT. What happens next depends on the JWT typ:
The resource returns 401 with an Accept-Signature header telling the agent which components to sign and that it expects a JWT-keyed signature.
The resource verifies the agent token against the agent server's JWKS, reads the ps claim, fetches the PS metadata for its issuer, and mints a short-lived resource_token (aa-resource+jwt) audienced to that PS. The token carries the requested scopes and the agent's JWK thumbprint.
The response is 401 with an AAuth-Requirement header containing the resource token. The agent takes it to its PS and exchanges it for an auth_token.
The resource verifies the auth token against the issuer's JWKS, checks aud, exp, and that whoami is in scope, then returns a JSON body containing the identity claims (everything except JWT infrastructure claims like iss, aud, exp, cnf, etc.).
The whoami scope is always included on the resource token. Additional identity scopes can be requested via the ?scope= query parameter and are passed through on resource_token.scope. The supported set combines standard OIDC scopes with Hellō identity attributes:
openid profile name nickname given_name family_name preferred_username
picture email phone ethereum discord twitter github gitlab bio banner
recovery mastodon instagram verified_name existing_name existing_username
tenant_sub org groups roles
Example: GET /?scope=email%20picture
- Cloudflare Workers with Hono
- Stateless — no KV or other storage
- @hellocoop/httpsig for RFC 9421 HTTP Message Signatures
- Ed25519 signing keys
npm install
npm run dev # local dev server
npx tsc --noEmit # type check
bash scripts/test.sh # smoke tests against production
bash scripts/test.sh http://localhost:8787 # smoke tests against local devCloudflare Workers Builds auto-deploys on push to main. To set up from scratch:
npm run generate-key
# copy the output, then:
npx wrangler secret put SIGNING_KEY
npx wrangler deployPlease read CODE_OF_CONDUCT.md before participating.
