Skip to content

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.

8.5 KB
Raw Blame
/**
 * @three-ws/sdk — Permissions module
 *
 * ERC-7710 scoped delegation client for three.ws.
 *
 * Quick start:
 *   import { PermissionsClient } from '@three-ws/sdk/permissions';
 *   const client = new PermissionsClient({ baseUrl: 'https://three.ws/' });
 *   const { delegations } = await client.getMetadata(agentId);
 */

const DEFAULT_BASE = 'https://three.ws/';

/**
 * Typed error class for permission operations.
 * The `code` property maps to canonical error codes from PERMISSIONS_SPEC.md §8.
 *
 * Codes: delegation_expired | delegation_revoked | scope_exceeded | target_not_allowed
 *        | delegation_not_found | signature_invalid | chain_not_supported | rate_limited
 */
export class PermissionError extends Error {
	/**
	 * @param {string} code    Canonical error code from the spec
	 * @param {string} message Human-readable description
	 */
	constructor(code, message) {
		super(message);
		this.code = code;
		this.name = 'PermissionError';
	}
}

/**
 * HTTP client for the three.ws permissions API.
 *
 * Methods `grant` and `revoke` require a browser-connected ethers v6 Signer and will
 * throw `PermissionError('browser_only', ...)` when called in a Node.js environment.
 */
export class PermissionsClient {
	/**
	 * @param {object} [opts]
	 * @param {string} [opts.baseUrl]  API base URL (default: https://three.ws/)
	 * @param {string} [opts.bearer]  Bearer token for authenticated endpoints (redeem, private list)
	 */
	constructor({ baseUrl = DEFAULT_BASE, bearer } = {}) {
		this._base = baseUrl.replace(/\/$/, '');
		this._bearer = bearer ?? null;
	}

	/** @returns {Record<string, string>} */
	_headers() {
		const h = { 'Content-Type': 'application/json' };
		if (this._bearer) h['Authorization'] = `Bearer ${this._bearer}`;
		return h;
	}

	/**
	 * @param {string} url
	 * @param {RequestInit} [opts]
	 * @returns {Promise<any>}
	 */
	async _request(url, opts = {}) {
		const res = await fetch(url, { ...opts, headers: this._headers() });
		const body = await res.json();
		if (!body.ok) {
			throw new PermissionError(
				body.error ?? 'unknown_error',
				body.message ?? body.error ?? 'Request failed',
			);
		}
		return body;
	}

	/**
	 * List delegations for an agent or delegator.
	 *
	 * Public path (agentId only) returns active delegations without auth.
	 * Private path (delegator) requires a bearer token or session.
	 *
	 * @param {{ agentId?: string; delegator?: string; status?: string }} [params]
	 * @returns {Promise<DelegationPublic[]>}
	 */
	async listDelegations({ agentId, delegator, status } = {}) {
		const url = new URL(`${this._base}/api/permissions/list`);
		if (agentId) url.searchParams.set('agentId', agentId);
		if (delegator) url.searchParams.set('delegator', delegator);
		if (status) url.searchParams.set('status', status);
		const data = await this._request(url.toString());
		return data.delegations ?? [];
	}

	/**
	 * Fetch public permissions metadata for an agent.
	 * Returns the spec version and the agent's active delegations.
	 *
	 * @param {string} agentId
	 * @returns {Promise<{ spec: string; delegations: DelegationPublic[] }>}
	 */
	async getMetadata(agentId) {
		const url = `${this._base}/api/permissions/metadata?agentId=${encodeURIComponent(agentId)}`;
		const data = await this._request(url);
		return { spec: data.spec, delegations: data.delegations ?? [] };
	}

	/**
	 * Grant a scoped ERC-7710 delegation to an agent. **Browser only.**
	 *
	 * Flow: build unsigned delegation → EIP-712 sign via signer → POST /api/permissions/grant.
	 *
	 * The `delegate` param is the agent's smart account address (obtained from the agent manifest
	 * or from `getMetadata`). The signer must be the human owner (delegator) wallet.
	 *
	 * @param {{
	 *   agentId: string;
	 *   chainId: number;
	 *   preset: ScopePreset;
	 *   delegate: string;
	 *   signer: import('ethers').Signer;
	 * }} params
	 * @returns {Promise<{ id: string; delegationHash: string }>}
	 * @throws {PermissionError} 'browser_only' when called in Node.js
	 */
	async grant({ agentId, chainId, preset, delegate, signer }) {
		if (typeof window === 'undefined') {
			throw new PermissionError(
				'browser_only',
				'grant() requires a browser environment with a wallet — not available in Node.js',
			);
		}
		// Dynamic import keeps ethers + toolkit out of the Node.js bundle.
		const { encodeScopedDelegation, signDelegation } = await import(
			'./permissions/toolkit.js'
		);
		const { CAVEAT_ENFORCERS, encodeCaveats } = await import('./erc7710/abi.js');

		const delegatorAddr = await signer.getAddress();
		const expiry = Math.floor(Date.now() / 1000) + preset.expiryDays * 86400;

		const allowedTargetsTerms = await encodeCaveats(
			preset.targets.map((t) => ({ enforcer: t, terms: '0x', args: '0x' })),
		);
		const caveats = [
			{
				enforcer: CAVEAT_ENFORCERS.AllowedTargetsEnforcer[chainId],
				terms: allowedTargetsTerms,
				args: '0x',
			},
			{
				enforcer: CAVEAT_ENFORCERS.ERC20LimitEnforcer[chainId],
				terms: preset.maxAmount,
				args: '0x',
			},
			{
				enforcer: CAVEAT_ENFORCERS.TimestampEnforcer[chainId],
				terms: String(expiry),
				args: '0x',
			},
		];

		const unsigned = encodeScopedDelegation({
			delegator: delegatorAddr,
			delegate,
			caveats,
			expiry,
			chainId,
		});
		const signed = await signDelegation(unsigned, signer);

		const data = await this._request(`${this._base}/api/permissions/grant`, {
			method: 'POST',
			body: JSON.stringify({
				agentId,
				chainId,
				delegation: signed,
				scope: {
					token: preset.token,
					maxAmount: preset.maxAmount,
					period: preset.period,
					targets: preset.targets,
					expiryDays: preset.expiryDays,
				},
			}),
		});
		return { id: data.id, delegationHash: data.delegationHash };
	}

	/**
	 * Redeem a delegation to execute on-chain calls. Requires a bearer token.
	 *
	 * The redemption is executed server-side via a relayer. The bearer token must
	 * carry a scope that includes permission to redeem on behalf of the agent.
	 *
	 * @param {{ id: string; calls: Array<{ to: string; value?: string; data: string }> }} params
	 * @returns {Promise<{ txHash: string }>}
	 */
	async redeem({ id, calls }) {
		const data = await this._request(`${this._base}/api/permissions/redeem`, {
			method: 'POST',
			body: JSON.stringify({ id, calls }),
		});
		return { txHash: data.txHash };
	}

	/**
	 * Revoke a delegation on-chain and mirror the revocation to the server. **Browser only.**
	 *
	 * Flow: send `DelegationManager.disableDelegation(delegationHash)` tx via signer
	 *       → POST /api/permissions/revoke with the resulting tx hash.
	 *
	 * Obtain `delegationHash` from the `DelegationPublic` returned by `listDelegations`
	 * or `getMetadata` before calling this method.
	 *
	 * @param {{ id: string; delegationHash: string; signer: import('ethers').Signer }} params
	 * @returns {Promise<{ status: 'revoked'; txHash: string }>}
	 * @throws {PermissionError} 'browser_only' when called in Node.js
	 * @throws {PermissionError} 'chain_not_supported' if no DelegationManager for the signer's chain
	 */
	async revoke({ id, delegationHash, signer }) {
		if (typeof window === 'undefined') {
			throw new PermissionError(
				'browser_only',
				'revoke() requires a browser environment with a wallet — not available in Node.js',
			);
		}
		const { Contract } = await import('ethers');
		const { DELEGATION_MANAGER_ABI, DELEGATION_MANAGER_DEPLOYMENTS } = await import(
			'./erc7710/abi.js'
		);
		const network = await signer.provider.getNetwork();
		const managerAddr = DELEGATION_MANAGER_DEPLOYMENTS[Number(network.chainId)];
		if (!managerAddr) {
			throw new PermissionError(
				'chain_not_supported',
				`no DelegationManager for chain ${network.chainId}`,
			);
		}
		const dm = new Contract(managerAddr, DELEGATION_MANAGER_ABI, signer);
		const tx = await dm.disableDelegation(delegationHash);
		await tx.wait();
		await this._request(`${this._base}/api/permissions/revoke`, {
			method: 'POST',
			body: JSON.stringify({ id, txHash: tx.hash }),
		});
		return { status: 'revoked', txHash: tx.hash };
	}

	/**
	 * Verify that a delegation hash is valid on-chain.
	 * Makes a real-time read from the DelegationManager contract.
	 *
	 * @param {string} hash     Delegation hash (keccak256, hex-encoded)
	 * @param {number} chainId  Chain ID where the delegation was created
	 * @returns {Promise<{ valid: boolean; reason?: string }>}
	 */
	async verify(hash, chainId) {
		const url = `${this._base}/api/permissions/verify?hash=${encodeURIComponent(hash)}&chainId=${chainId}`;
		const data = await this._request(url);
		return data.reason !== undefined
			? { valid: data.valid, reason: data.reason }
			: { valid: data.valid };
	}
}