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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// /api/x402/did — dual-mode DID endpoint.
//
// GET → /.well-known/did.json — W3C DID Document for the x402 Offer & Receipt
// signing key (USE-17). Free. Verifiers resolve our `kid` back to a
// public key here when checking EIP-712 / JWS signatures on offers and
// receipts. Per spec §4.5.1 the resolved key is "authorized to sign for
// the service identified by the payload's resourceUrl", so listing the
// signer address (eip712) or public JWK (jws) here is the binding
// between our HTTPS origin and the signing material. Routed via
// vercel.json: /.well-known/did.json → /api/x402/did.
//
// POST → DID Verification Canary (USE-069). Paid $0.001 USDC. Resolves our
// published DID document over the real public route an external
// verifier would hit, validates it is a structurally correct W3C DID
// document with our x402 service binding, and measures end-to-end
// resolution latency. The verdict ({ verified, latency_ms }) is the
// actionable signal: a malformed/unreachable document means any
// counterparty verifying our offer/receipt signatures fails silently,
// and a slow resolver degrades their settlement path. The autonomous
// loop pays this canary on a schedule and records the verdict to
// x402_autonomous_log so the status surface flags a broken or slow DID
// subsystem before a partner does. Body:
// { "did": "did:three:canary", "mode": "verify" }
//
// When no issuer is configured the GET path returns 404 — there's nothing to
// publish — and the POST canary truthfully reports verified:false (not_configured).
import { cors, json, error, readBody as readRawBody } from '../_lib/http.js';
import { env } from '../_lib/env.js';
import { getIssuer } from '../_lib/x402/offer-receipt-issuer.js';
import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';
import { buildBazaarSchema } from '../_lib/x402-spec.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { installAccessControl } from '../_lib/x402/access-control.js';
import { sql } from '../_lib/db.js';
import { priceFor } from '../_lib/x402-prices.js';
const ROUTE = '/api/x402/did';
// W3C DID Core v1 context — a conformant DID document MUST list it first.
const DID_V1_CONTEXT = 'https://www.w3.org/ns/did/v1';
// The canary fails the latency leg above this. A DID document resolution that
// external verifiers experience should be well under a second; 1500ms leaves
// generous headroom for a cold serverless route + TLS while still catching a
// genuinely degraded resolver.
const MAX_LATENCY_MS = 1500;
// Resolve the origin we publish the DID document on. APP_ORIGIN is always a
// valid absolute origin (env normalizes it); SERVER_DOMAIN is the bare host.
function publicOrigin() {
return env.APP_ORIGIN || (env.SERVER_DOMAIN ? `https://${env.SERVER_DOMAIN}` : 'https://three.ws');
}
// Build the W3C DID Document from the configured offer-receipt issuer. Returns
// null when no signing key is configured (caller emits 404). Shared by the GET
// publisher and — indirectly, via the public route — the POST canary, so both
// always agree on the document shape.
export async function buildDidDocument() {
const built = await getIssuer();
if (!built) return null;
const domain = env.SERVER_DOMAIN;
const id = `did:web:${domain}`;
const verificationMethod = [];
if (built.format === 'eip712') {
// did:pkh authorization for EIP-712 verifiers. The recovered signer
// address from any EIP-712 signature MUST match the address embedded in
// this entry's blockchainAccountId for the offer/receipt to be accepted
// as originating from this resource server.
verificationMethod.push({
id: built.kid,
type: 'EcdsaSecp256k1RecoveryMethod2020',
controller: id,
blockchainAccountId: `eip155:1:${built.signerAddress}`,
});
} else if (built.format === 'jws' && built.publicKey) {
verificationMethod.push({
id: built.kid,
type: 'JsonWebKey2020',
controller: id,
publicKeyJwk: {
...built.publicKey.jwk,
alg: built.publicKey.alg,
},
});
}
return {
'@context': [
DID_V1_CONTEXT,
'https://w3id.org/security/suites/jws-2020/v1',
'https://w3id.org/security/suites/secp256k1recovery-2020/v1',
],
id,
verificationMethod,
// The same key authorizes both offer and receipt signing — assertionMethod
// is the W3C term that maps cleanly onto "this key signs claims about the
// service". authentication is included so DID-aware clients can also use
// the key for SIWX-style flows if we wire them up later.
assertionMethod: [built.kid],
authentication: [built.kid],
service: [
{
id: `${id}#x402`,
type: 'x402PaymentService',
serviceEndpoint: env.APP_ORIGIN,
},
],
};
}
// Structural validation of a resolved DID document against the subset of W3C
// DID Core our verifiers depend on, plus our x402 service binding. Returns a
// per-check breakdown so the canary's signal pinpoints what regressed.
export function validateDidDocument(doc) {
const ctx = doc && doc['@context'];
const ctxList = Array.isArray(ctx) ? ctx : ctx ? [ctx] : [];
const vm = Array.isArray(doc?.verificationMethod) ? doc.verificationMethod : [];
const assertion = Array.isArray(doc?.assertionMethod) ? doc.assertionMethod : [];
const services = Array.isArray(doc?.service) ? doc.service : [];
const vmIds = new Set(vm.map((m) => m && m.id).filter(Boolean));
const checks = {
is_object: !!doc && typeof doc === 'object' && !Array.isArray(doc),
has_did_context: ctxList.includes(DID_V1_CONTEXT),
has_did_id: typeof doc?.id === 'string' && /^did:/.test(doc.id),
// Every verification method must carry the triple verifiers key off of.
has_verification_method:
vm.length > 0 &&
vm.every((m) => m && typeof m.id === 'string' && typeof m.type === 'string' && typeof m.controller === 'string'),
// assertionMethod must reference a real verification method (string ref or
// embedded object) — the binding that authorizes the key to sign claims.
assertion_resolves:
assertion.length > 0 &&
assertion.some((a) => (typeof a === 'string' ? vmIds.has(a) : !!a && vmIds.has(a.id))),
// Our specific binding: the x402 payment service entry verifiers look for.
has_x402_service: services.some(
(s) => s && s.type === 'x402PaymentService' && typeof s.serviceEndpoint === 'string',
),
};
checks.valid = Object.values(checks).every(Boolean);
return checks;
}
// ── GET: publish the DID document (free) ─────────────────────────────────────
async function handleDidDocument(req, res) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
let doc;
try {
doc = await buildDidDocument();
} catch (err) {
console.error('[x402/did] issuer error:', err?.message);
return error(res, 500, 'issuer_misconfigured', 'signing key configuration error');
}
if (!doc) {
return error(
res,
404,
'not_configured',
'no offer-receipt signing key is configured for this deployment',
);
}
json(res, 200, doc, {
'content-type': 'application/did+json; charset=utf-8',
'cache-control': 'public, max-age=300',
});
}
// ── POST: DID Verification Canary (paid $0.001 USDC) ─────────────────────────
const DESCRIPTION =
'DID Verification Canary — pay $0.001 USDC to resolve three.ws\'s published ' +
'W3C DID document over its real public route, structurally validate it, and ' +
'measure end-to-end resolution latency. Returns { verified, latency_ms } plus ' +
'a per-check breakdown. verified=false when the document is unreachable, ' +
'malformed, or slower than 1500ms — the same failure an external x402 verifier ' +
'would hit resolving our offer/receipt signing key.';
const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
properties: {
did: {
type: 'string',
description: 'DID to verify (echoed for round-trip confirmation).',
default: 'did:three:canary',
},
mode: {
type: 'string',
enum: ['verify'],
description: 'Operation. Only "verify" is supported.',
default: 'verify',
},
},
};
const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['verified', 'latency_ms', 'did', 'mode', 'ts'],
properties: {
verified: { type: 'boolean' },
latency_ms: { type: 'integer' },
did: { type: 'string' },
mode: { type: 'string' },
resolved_did: { type: ['string', 'null'] },
http_status: { type: 'integer' },
within_latency: { type: 'boolean' },
malformed: { type: 'boolean' },
configured: { type: 'boolean' },
checks: { type: 'object' },
ts: { type: 'string', format: 'date-time' },
},
};
const BAZAAR = {
description: DESCRIPTION,
useCases: ['DID resolution health', 'offer/receipt signing-key verification', 'identity canary'],
input: { type: 'json', example: { did: 'did:three:canary', mode: 'verify' }, schema: INPUT_SCHEMA },
output: {
type: 'json',
example: {
verified: true,
latency_ms: 142,
did: 'did:three:canary',
mode: 'verify',
resolved_did: 'did:web:three.ws',
http_status: 200,
within_latency: true,
malformed: false,
configured: true,
checks: {
is_object: true,
has_did_context: true,
has_did_id: true,
has_verification_method: true,
assertion_resolves: true,
has_x402_service: true,
valid: true,
},
ts: '2026-06-27T10:00:00Z',
},
},
schema: buildBazaarSchema({ method: 'POST', bodySchema: INPUT_SCHEMA, outputSchema: OUTPUT_SCHEMA }),
};
async function readBody(req) {
// req.body is pre-parsed by Vercel; fall back to manual stream read for
// edge / test environments that hand a raw IncomingMessage.
if (req.body && typeof req.body === 'object') return req.body;
try {
const chunks = [await readRawBody(req, 1_000_000)];
const raw = Buffer.concat(chunks).toString('utf8');
return raw ? JSON.parse(raw) : {};
} catch {
return {};
}
}
// Turn one resolution attempt into the canary verdict. Pure (no I/O), so the
// verdict logic is unit-testable without a live resolver, same pattern as
// validateDidDocument above.
//
// `configured` answers "is a DID document published here", which only a real
// HTTP answer can settle: 404 proves no document, any other status proves one
// is being served. A transport failure (http_status 0: DNS, TLS, timeout)
// proves neither, so it reports false rather than claiming a document we never
// saw. `fetch_error` distinguishes that case from a genuine 404.
export function summarizeResolution({ httpStatus, doc, latency_ms, did, fetchError = null }) {
const checks = validateDidDocument(doc);
const configured = httpStatus > 0 && httpStatus !== 404;
const malformed = httpStatus !== 200 || !checks.valid;
const within_latency = latency_ms <= MAX_LATENCY_MS;
return {
verified: !malformed && within_latency,
latency_ms,
did,
mode: 'verify',
resolved_did: typeof doc?.id === 'string' ? doc.id : null,
http_status: httpStatus,
within_latency,
malformed,
configured,
checks,
...(fetchError ? { fetch_error: fetchError } : {}),
ts: new Date().toISOString(),
};
}
async function runVerify({ did }) {
const url = `${publicOrigin()}/.well-known/did.json`;
const t0 = Date.now();
let httpStatus = 0;
let doc = null;
let fetchError = null;
try {
const r = await fetch(url, {
headers: { accept: 'application/did+json, application/json', 'user-agent': 'threews-did-canary/1.0' },
signal: AbortSignal.timeout(5000),
});
httpStatus = r.status;
const text = await r.text();
try { doc = JSON.parse(text); } catch { doc = null; }
} catch (err) {
fetchError = err?.message || 'fetch_failed';
}
return summarizeResolution({ httpStatus, doc, latency_ms: Date.now() - t0, did, fetchError });
}
// Sweep the N most recently created agent identities and check each for
// resolvable key material. An agent without wallet_address has no cryptographic
// material to build a DID from — it cannot sign claims or be verified by
// counterparties. failed_count > 0 is the alert signal.
async function runSweep({ limit }) {
const rows = await sql`
SELECT id, wallet_address, created_at
FROM agent_identities
WHERE deleted_at IS NULL
ORDER BY created_at DESC
LIMIT ${limit}
`;
const dids = rows.map((r) => {
const resolvable = typeof r.wallet_address === 'string' && r.wallet_address.length > 0;
const did = resolvable
? `did:pkh:solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:${r.wallet_address}`
: `did:web:three.ws/agents/${r.id}`;
return {
did,
agent_id: r.id,
resolvable,
wallet_address: r.wallet_address || null,
created_at: r.created_at ? new Date(r.created_at).toISOString() : null,
};
});
const count = dids.length;
const resolvable_count = dids.filter((d) => d.resolvable).length;
const failed_count = count - resolvable_count;
return {
mode: 'sweep',
count,
resolvable_count,
failed_count,
dids,
ts: new Date().toISOString(),
};
}
const verifyCanary = paidEndpoint({
route: ROUTE,
method: 'POST',
priceAtomics: priceFor('did_verify', '1000'), // $0.001 USDC
networks: ['solana', 'base'],
description: DESCRIPTION,
bazaar: BAZAAR,
service: withService({
serviceName: 'three.ws DID Health',
tags: ['did', 'identity', 'health', 'verification', 'registry', 'x402'],
}),
accessControl: installAccessControl({ requiredScope: 'x402:bypass' }),
async handler({ req }) {
const body = await readBody(req);
const did = typeof body.did === 'string' && body.did.trim() ? body.did.trim().slice(0, 200) : 'did:three:canary';
const mode = typeof body.mode === 'string' && body.mode.trim() ? body.mode.trim().slice(0, 32) : 'verify';
const limit = Math.min(Math.max(Number(body.limit || 10), 1), 50);
if (mode === 'sweep') return runSweep({ limit });
return runVerify({ did });
},
});
// ── Dispatch by method ───────────────────────────────────────────────────────
// Only the two documented verbs are served. Anything else used to fall through
// to the GET publisher, so a PUT or DELETE answered with the DID document,
// which reads to a client (and to any cache in front of us) as if the write
// succeeded. 405 says plainly that the resource is read-or-pay only.
export default function handler(req, res) {
if (req.method === 'POST') return verifyCanary(req, res);
if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') {
return handleDidDocument(req, res);
}
if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
return error(res, 405, 'method_not_allowed', 'use GET for the DID document or POST for the verification canary');
}