Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Persona Hub
Overview
Persona Hub is three.ws's cross-app sign-in: a user creates and stores their three.ws avatar once, then any tenant site embedding the <three-ws-signin> widget can request a short-lived JWT that bears the user's avatar URL. three.ws itself issues the token — from a popup served on three.ws, against the user's session cookie — and tenants verify it server-side, either offline against the published JWKS (when the deployment is running in ES256 mode) or by calling the public /api/auth/persona/verify endpoint. ES256 is the preferred algorithm because the public key is published at /.well-known/jwks.json and tenants can verify without a network round-trip.
The pattern is one avatar, many sites — redesigned around three.ws's own auth stack.
How it works
tenant site three.ws (popup) three.ws backend
│ │ │
1. ├── <three-ws-signin> ───────┤ │
│ button clicked │ │
│ │ │
2. ├── window.open() ──────────►│ /persona/authorize.html │
│ │ (consent screen) │
│ │ │
3. │ │ GET /api/auth/persona/me ───►│
│ │ ◄────────── user + avatars │
│ │ │
4. │ │ user picks avatar, clicks │
│ │ "Authorize" │
│ │ │
5. │ │ POST /api/auth/persona/issue►│
│ │ body { tenant_origin, │
│ │ avatar_id } │
│ │ ◄──── { token, avatar } │
│ │ │
6. │◄── postMessage ────────────┤ closes popup │
│ { token, avatar } │ │
│ │ │
7. ├── (optional) verify │ │
│ GET /api/auth/persona/verify?token=…&audience=… ──────►│
│ ◄────────────── { sub, avatar, exp } │
The cookie carrying the user's three.ws session is __Host-sid — locked to the exact host. The popup runs on three.ws so the consent screen can read it; the tenant never sees it. Cross-site avatar sharing happens entirely via the postMessage-delivered JWT.
Embedding the widget
<script src="https://three.ws/persona/widget.js" defer></script>
<three-ws-signin
client-origin="https://coolgame.three.ws"
label="Sign in with three.ws">
</three-ws-signin>
Listen for the result:
const el = document.querySelector('three-ws-signin');
el.addEventListener('three-ws:authorized', (e) => {
const { token, avatar, expires_in } = e.detail;
// avatar: { id, url, thumbnail_url, name }
// token: 24h JWT — verify server-side before trusting
});
el.addEventListener('three-ws:cancelled', () => {
// user closed the popup or hit Cancel
});
Programmatic API
const result = await window.ThreeWsPersona.signIn({
clientOrigin: 'https://coolgame.three.ws',
});
// result.token, result.avatar
Key generation
Run scripts/generate-persona-key.mjs once per deployment to produce an ES256 (P-256) keypair:
node scripts/generate-persona-key.mjs
# or pin a custom key id:
node scripts/generate-persona-key.mjs --kid=persona-2026-05
The script writes nothing to disk. It prints a copy-pasteable block to stdout:
PERSONA_JWKS_KID=persona-2026-05-20
PERSONA_JWKS_PRIVATE_KEY_PEM="-----BEGIN PRIVATE KEY-----\nMIGH…\n-----END PRIVATE KEY-----"
# Optional — derived from private key if omitted:
# PERSONA_JWKS_PUBLIC_KEY_PEM="-----BEGIN PUBLIC KEY-----\nMFkw…\n-----END PUBLIC KEY-----"
followed by the public JWK that /.well-known/jwks.json will publish once the env vars take effect. Three env vars are involved:
| Variable | Required | Purpose |
|---|---|---|
PERSONA_JWKS_PRIVATE_KEY_PEM |
yes (to enable ES256) | PKCS8 PEM with \n escaped. The server signs persona tokens with this key. Without it, the server falls back to HS256. |
PERSONA_JWKS_KID |
no (defaults to persona-es256-1) |
Key id published in the JWK and embedded in the JWT header so tenants can pick the right key after rotation. |
PERSONA_JWKS_PUBLIC_KEY_PEM |
no | SPKI PEM. If omitted, the public JWK is derived from the private key at runtime. Set this only if you want to publish a different public key (rare). |
Paste the block into the deployment's environment (the Cloud Run service config for production, .env.local for dev), redeploy, and confirm the new key is live with:
curl https://three.ws/.well-known/jwks.json
The response should contain one entry under keys whose kid matches PERSONA_JWKS_KID. The private key must never leave the server — it is the sole signer for every persona token issued by this deployment.
Issuing a token
POST /api/auth/persona/issue — defined in api/auth/persona/[action].js (handleIssue).
| Method | POST |
| Auth | three.ws session: a valid __Host-sid cookie sent with credentials: 'include' |
| Body | { "tenant_origin": "<https origin>", "avatar_id"?: "<uuid>" } |
| Success | 200 with { token, expires_in, avatar, tenant_origin, alg } |
| Errors | 401 unauthorized — no session. 400 invalid_request — tenant_origin is not a three.ws subdomain or localhost. 404 no_avatar — user has no avatar yet. |
tenant_origin must be a bare origin (no path, no query, no fragment), https://*.three.ws or https://three.ws, or — for dev — http://localhost[:port] / http://127.0.0.1[:port]. Anything else is rejected with 400 invalid_request. The validator is validateTenantOrigin() in api/auth/persona/[action].js; add a subdomain by editing that function.
When avatar_id is omitted, the user's most recently created avatar is used. Pass avatar_id from the consent UI's picker to bind a specific avatar to the token.
curl
The endpoint requires a real session, so this only succeeds when the caller is signed in to three.ws (the cookie value below is illustrative — copy yours from the browser's devtools after signing in):
curl -sS -X POST https://three.ws/api/auth/persona/issue \
-H 'content-type: application/json' \
-H 'cookie: __Host-sid=<your session cookie value>' \
--data '{"tenant_origin":"https://coolgame.three.ws"}'
Without a session you get 401 unauthorized:
{ "error": "unauthorized", "error_description": "sign in to three.ws first" }
A successful response looks like:
{
"token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InBlcnNvbmEtMjAyNi0wNS0yMCIsInR5cCI6IkpXVCJ9…",
"expires_in": 86400,
"avatar": {
"id": "a-1",
"name": "My Avatar",
"url": "https://three.ws/cdn/u/<user>/avatar.glb",
"thumbnail_url": "https://three.ws/cdn/u/<user>/avatar.png"
},
"tenant_origin": "https://coolgame.three.ws",
"alg": "ES256"
}
alg reflects the signing mode this deployment is currently in (ES256 when a persona keypair is configured, HS256 otherwise — see ES256 vs HS256 fallback).
fetch (from the consent popup)
const res = await fetch('/api/auth/persona/issue', {
method: 'POST',
credentials: 'include', // sends __Host-sid
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
tenant_origin: 'https://coolgame.three.ws',
avatar_id: 'a-1', // optional — defaults to newest
}),
});
if (!res.ok) {
const { error, error_description } = await res.json();
throw new Error(`${error}: ${error_description}`);
}
const { token, avatar, expires_in, alg } = await res.json();
Decoded JWT claims
The base64url payload of the issued token decodes to:
{
"scope": "persona:read avatar:read",
"token_use": "persona",
"avatar": {
"id": "a-1",
"name": "My Avatar",
"url": "https://three.ws/cdn/u/<user>/avatar.glb",
"thumbnail_url": "https://three.ws/cdn/u/<user>/avatar.png"
},
"iss": "https://three.ws",
"sub": "<three.ws user id>",
"aud": "https://coolgame.three.ws",
"iat": 1747699200,
"exp": 1747785600,
"jti": "<16-byte random hex>"
}
Header:
{ "alg": "ES256", "kid": "persona-2026-05-20", "typ": "JWT" }
alg is ES256 in ES mode and HS256 in fallback. kid is PERSONA_JWKS_KID in ES mode and JWT_KID (defaults to k1) in fallback. Both modes set the same payload claims — the only thing that changes is how the signature is produced and verified.
Verifying a token (tenant side)
A persona token must always be verified before the tenant trusts any claim on it. There are two paths:
- Offline against the JWKS (
ES256only). The tenant fetches https://three.ws/.well-known/jwks.json once, caches it, and verifies the signature locally. - Online against the verify endpoint (works for both
ES256andHS256). The tenant callsGET /api/auth/persona/verify?token=…&audience=…and trusts the response.
Use path 1 in production when ES256 is active — it's free, cache-friendly, and doesn't depend on three.ws being reachable on the verify path. Use path 2 as a universal fallback.
Node.js (offline, JWKS) — recommended
import { jwtVerify, createRemoteJWKSet } from 'jose';
// createRemoteJWKSet fetches the JWKS once and caches it in memory.
// The cache invalidates on `kid` miss so key rotation is automatic.
const JWKS = createRemoteJWKSet(
new URL('https://three.ws/.well-known/jwks.json'),
);
export async function verifyPersonaToken(token, tenantOrigin) {
const { payload } = await jwtVerify(token, JWKS, {
issuer: 'https://three.ws',
audience: tenantOrigin, // must match what you embedded with
algorithms: ['ES256'],
});
// payload.sub — three.ws user id (stable across sessions)
// payload.avatar — { id, name, url, thumbnail_url }
// payload.scope — "persona:read avatar:read"
// payload.exp — unix timestamp
return payload;
}
Install jose (npm install jose) — that's the only dependency. The JWKS handle is reusable across requests; do not construct a new one per call.
Browser (offline, JWKS via ESM CDN)
<script type="module">
import { jwtVerify, createRemoteJWKSet } from 'https://esm.sh/jose@5';
const JWKS = createRemoteJWKSet(
new URL('https://three.ws/.well-known/jwks.json'),
);
async function verify(token, tenantOrigin) {
const { payload } = await jwtVerify(token, JWKS, {
issuer: 'https://three.ws',
audience: tenantOrigin,
algorithms: ['ES256'],
});
return payload;
}
// example wiring against the widget
document.querySelector('three-ws-signin')
.addEventListener('three-ws:authorized', async (e) => {
const claims = await verify(e.detail.token, 'https://coolgame.three.ws');
console.log('signed in as', claims.sub, claims.avatar);
});
</script>
If you bundle (Vite / webpack / esbuild), drop the CDN URL and import from jose directly — same API. Browser-side verification is only safe for UI hints — anything privileged on the tenant must still re-verify on the tenant's server. The browser cannot keep an audience binding honest if the calling page is compromised.
Online verify (works for ES256 and HS256)
const url = new URL('https://three.ws/api/auth/persona/verify');
url.searchParams.set('token', token);
url.searchParams.set('audience', 'https://coolgame.three.ws');
const res = await fetch(url);
if (!res.ok) {
const { error, error_description } = await res.json();
throw new Error(`${error}: ${error_description}`);
}
const claims = await res.json();
// claims: { ok, sub, aud, scope, exp, avatar }
The verify endpoint applies the same checks as jose.jwtVerify — signature, issuer (https://three.ws), audience match, expiry — and additionally rejects tokens whose token_use claim is not "persona".
ES256 vs HS256 fallback
The signing algorithm is decided at issue time by api/auth/persona/[action].js:158-161:
const es = await esKeys(); // null if PERSONA_JWKS_PRIVATE_KEY_PEM is unset
const alg = es ? 'ES256' : 'HS256';
const kid = es ? es.kid : env.JWT_KID;
const signingKey = es ? es.privateKey : hsKey();
- ES256 (preferred). Active when
PERSONA_JWKS_PRIVATE_KEY_PEMis set. The server signs with the EC P-256 private key; the public key is published at/.well-known/jwks.jsonso tenants verify offline. - HS256 (fallback). Active when
PERSONA_JWKS_PRIVATE_KEY_PEMis unset. The server signs with theJWT_SECRETHMAC secret./.well-known/jwks.jsonreturns{"keys": []}and includes a diagnostic headerx-three-ws-status: no PERSONA_JWKS_PRIVATE_KEY_PEM configured; persona tokens are HS256, verify via /api/auth/persona/verify.
Verification accepts both algorithms in either order — the /verify endpoint tries ES256 first and falls back to HS256 — so tokens minted just before a key rollover keep working until they expire. The alg field in the issue response tells the client which mode was used; tenants do not need to branch on it (the offline path simply requires ES256).
What tenants should do in an HS256 deployment. Skip JWKS entirely — the HMAC secret cannot be published, so offline verification is impossible. Always call GET /api/auth/persona/verify?token=…&audience=… from your server. If a tenant's runtime requires offline verification (e.g. an edge worker that must not call out to three.ws on the hot path), file an issue against the deployment owner to install a persona keypair before launch.
Tokens in practice
- TTL. 24 hours (
PERSONA_TTL_SEC = 60 * 60 * 24,api/auth/persona/[action].js:42). Tenants that need a longer-lived session must mint their own session from the persona token'ssubafter verifying — do not extend the persona JWT itself. - Rotation. Generate a new keypair with
node scripts/generate-persona-key.mjs, deploy with a newPERSONA_JWKS_KID, and the JWKS publishes the new key. Old tokens continue to verify against/api/auth/persona/verifywhile they live; once the longest possible token TTL has elapsed (24h), no token in the wild still references the oldkid. The deployment can serve both old and new keys side by side by adding extra entries to thekeysarray — the current handler emits a single key but the verifier accepts any matchingkidfrom the published set. - Revocation. There is no revocation list. Defense is the short TTL: 24 hours. If a token must be invalidated sooner, the tenant should treat its own server-issued session as the source of truth and invalidate that. If a private key is leaked, rotate
PERSONA_JWKS_PRIVATE_KEY_PEMandPERSONA_JWKS_KID; verification of any token signed with the old key will fail as soon as the old JWK is removed from the published set.
Troubleshooting
| Symptom | What to check |
|---|---|
jwks_uri unreachable (browser console / fetch failure) |
Confirm https://three.ws/.well-known/jwks.json returns 200. If it returns {"keys":[]} and the response carries x-three-ws-status: …HS256…, the deployment is in HS256 fallback — offline verification cannot work, switch to the /api/auth/persona/verify path. |
JWKSNoMatchingKey / kid not found |
The token was signed with a key the JWKS no longer publishes (key was rotated and the old entry removed). Either redeploy with the old key added back to the published set, or have the user re-authorize so a fresh token is minted under the current kid. |
alg mismatch from jwtVerify |
The token's alg header doesn't match algorithms: ['ES256']. If the issue response returned alg: "HS256", the deployment is in fallback — call /api/auth/persona/verify instead. Never pass algorithms: ['HS256'] to a remote-JWKS verifier; HS256 is symmetric and the secret cannot be published. |
JWTClaimValidationFailed: "aud" claim check failed |
The audience you passed to jwtVerify (or to /verify) doesn't match the token's aud. Audience is the exact tenant_origin used at issue time — case-sensitive, no trailing slash. |
JWTExpired: "exp" claim timestamp check failed |
Token is older than 24 h. Have the user re-authorize through the widget. There is no refresh endpoint — persona tokens are not refreshable by design. |
invalid_token: token is not a persona token from /verify |
The token validates cryptographically but its token_use claim is not "persona". Tokens issued by the main three.ws auth stack are not accepted on this endpoint. |
400 invalid_request on /issue with tenant_origin must be a https three.ws subdomain or localhost dev origin |
The origin contains a path / query / fragment, is not https, or is not a three.ws subdomain. Pass a bare origin like https://coolgame.three.ws. Add a new subdomain by editing validateTenantOrigin() in api/auth/persona/[action].js. |
Allowed tenant origins
/api/auth/persona/issue accepts these origins for tenant_origin:
https://three.wshttps://<anything>.three.wshttp://localhost[:port]andhttp://127.0.0.1[:port](dev only)
Other origins return 400 invalid_request. This is the chokepoint that prevents arbitrary sites from minting tokens claiming any user's three.ws avatar.
Endpoint reference
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/auth/persona/me |
GET |
three.ws session | Lists the user's avatars for the consent UI. |
/api/auth/persona/issue |
POST |
three.ws session | Mints a 24h persona JWT for { tenant_origin, avatar_id }. |
/api/auth/persona/verify |
GET |
none | Verifies a token's signature, issuer, audience, expiry, and token_use. |
| /.well-known/jwks.json | GET |
none | Publishes the active persona public key (empty array in HS256 fallback). |
JWT claims:
| Claim | Value |
|---|---|
iss |
https://three.ws (the deployment's PUBLIC_APP_ORIGIN) |
sub |
three.ws user id |
aud |
tenant origin (validated against the issued audience on verify) |
scope |
persona:read avatar:read |
token_use |
persona |
avatar |
{ id, name, url, thumbnail_url } |
iat / exp |
issued at / expires at (24h TTL) |
jti |
unique token id (16 random bytes) |
Threat model notes
- Origin spoofing. The popup posts back only to the
tenant_originit was opened with. The browser enforces this via the second argument topostMessage, so a malicious script on another tab cannot receive the token. - Replay between tenants. Each token's
audis bound to the issuing tenant.verifyrequires the caller to supply the audience — if a token issued forcoolgame.three.wsis replayed againstevilgame.three.ws, verification fails. - State CSRF. The widget generates a per-popup
statenonce; the popup echoes it back in the postMessage payload. The widget rejects messages whosestatedoesn't match. - Token theft via XSS on tenant. A compromised tenant could leak tokens, but the blast radius is limited to that user's avatar URL (already publicly fetchable in most flows) plus their three.ws user id. No write scopes are granted by a persona token.