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.

43.4 KB
Raw Blame
/**
 * Permissions API dispatcher
 * --------------------------
 * POST /api/permissions/grant
 * GET  /api/permissions/list
 * GET  /api/permissions/metadata
 * POST /api/permissions/redeem
 * POST /api/permissions/revoke
 * GET  /api/permissions/verify
 *
 * Routed by the filesystem resolver in server/index.mjs: the trailing path
 * segment lands in req.query.action.
 */

import { createHash } from 'node:crypto';
import { z } from 'zod';
import { ethers, Wallet, Contract, Interface, isAddress } from 'ethers';
import { evmFallbackProvider } from '../_lib/evm/rpc.js';

import { sql } from '../_lib/db.js';
import { runLocked } from '../_lib/locked-sql.js';
import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';
import { cors, json, method, readJson, wrap, error, rateLimited, reportServerError } from '../_lib/http.js';
import { requireCsrf } from '../_lib/csrf.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { parse } from '../_lib/validate.js';
import { env } from '../_lib/env.js';
import { recordEvent } from '../_lib/usage.js';
import { SERVER_CHAIN_META } from '../_lib/onchain.js';
import {
	DELEGATION_MANAGER_DEPLOYMENTS,
	DELEGATION_MANAGER_ABI,
	EIP712_DOMAIN,
	DELEGATION_TYPES,
} from '../../src/erc7710/abi.js';
import {
	isDelegationValid,
	redeemDelegation,
	PermissionError,
} from '../../src/permissions/toolkit.js';

export default wrap(async (req, res) => {
	const action = req.query?.action;

	switch (action) {
		case 'grant':
			return handleGrant(req, res);
		case 'list':
			return handleList(req, res);
		case 'metadata':
			return handleMetadata(req, res);
		case 'redeem':
			return handleRedeem(req, res);
		case 'revoke':
			return handleRevoke(req, res);
		case 'verify':
			return handleVerify(req, res);
		default:
			return error(res, 404, 'not_found', 'unknown permissions action');
	}
});

// ── grant ──────────────────────────────────────────────────────────────────

const ROOT_AUTHORITY = '0x0000000000000000000000000000000000000000000000000000000000000000';

const hexAddr = z.string().regex(/^0x[0-9a-fA-F]{40}$/, 'must be a 20-byte hex address');
const hexBytes = z.string().regex(/^0x([0-9a-fA-F]{2})*$/, 'must be 0x-prefixed hex bytes');
const hexBytes32 = z.string().regex(/^0x[0-9a-fA-F]{64}$/, 'must be a 32-byte hex value');

const caveatSchema = z.object({
	enforcer: hexAddr,
	terms: hexBytes.default('0x'),
	args: hexBytes.default('0x'),
});

const delegationSchema = z.object({
	delegator: hexAddr,
	delegate: hexAddr,
	authority: hexBytes32.optional(),
	caveats: z.array(caveatSchema).default([]),
	salt: z.union([
		z
			.string()
			.regex(/^(0x[0-9a-fA-F]+|\d+)$/, 'salt must be a decimal or 0x-prefixed hex integer'),
		z.number().int().nonnegative(),
	]),
	signature: hexBytes,
	hash: hexBytes32,
});

const scopeSchema = z.object({
	token: z.string().min(1),
	maxAmount: z.string().min(1),
	period: z.enum(['daily', 'weekly', 'once']),
	targets: z.array(hexAddr).min(1),
	expiry: z.number().int().positive(),
});

const grantBodySchema = z.object({
	agentId: z.string().uuid(),
	chainId: z.number().int().positive(),
	delegation: delegationSchema,
	scope: scopeSchema,
});

async function handleGrant(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req, res);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	if (!(await requireCsrf(req, res, user.id))) return;

	const rl = await limits.permissionsGrant(user.id);
	if (!rl.success) return rateLimited(res, rl);

	const raw = await readJson(req);
	const parsed = grantBodySchema.safeParse(raw);
	if (!parsed.success) {
		const msg = parsed.error.issues
			.map((i) => `${i.path.join('.') || 'body'}: ${i.message}`)
			.join('; ');
		return error(res, 400, 'validation_error', msg);
	}
	const { agentId, chainId, delegation, scope } = parsed.data;

	// chainId must be a supported DelegationManager deployment
	if (!(chainId in DELEGATION_MANAGER_DEPLOYMENTS)) {
		return error(res, 400, 'chain_not_supported', `chainId ${chainId} is not supported`);
	}

	// Owner gate: agent must exist and belong to the authenticated user
	const [agent] = await sql`
		select id, user_id from agent_identities
		where id = ${agentId} and deleted_at is null
		limit 1
	`;
	if (!agent) return error(res, 404, 'not_found', 'agent not found');
	if (agent.user_id !== user.id) return error(res, 403, 'not_owner', 'you do not own this agent');

	// Wallet linkage: delegation.delegator must be a wallet linked to the authenticated user
	const delegatorLower = delegation.delegator.toLowerCase();
	const [linkedWallet] = await sql`
		select address from user_wallets
		where user_id = ${user.id} and address = ${delegatorLower}
		limit 1
	`;
	if (!linkedWallet) {
		return error(
			res,
			409,
			'wallet_not_linked',
			'delegation.delegator is not linked to your account',
		);
	}

	// Signature verification — two steps:
	// 1. Re-derive the EIP-712 hash from delegation fields and compare with delegation.hash
	//    (prevents chain-hop replay: different contract address → different hash).
	// 2. Recover the signer from the signature and verify it matches delegation.delegator.
	const managerAddr = DELEGATION_MANAGER_DEPLOYMENTS[chainId];
	const eip712Domain = EIP712_DOMAIN({ chainId, verifyingContract: managerAddr });
	let derivedHash;
	try {
		const structValue = {
			delegate: delegation.delegate,
			delegator: delegation.delegator,
			authority: delegation.authority || ROOT_AUTHORITY,
			caveats: delegation.caveats.map((c) => ({
				enforcer: c.enforcer,
				terms: c.terms,
				args: c.args,
			})),
			salt: BigInt(delegation.salt),
		};

		derivedHash = ethers.TypedDataEncoder.hash(eip712Domain, DELEGATION_TYPES, structValue);

		if (derivedHash.toLowerCase() !== delegation.hash.toLowerCase()) {
			return error(
				res,
				400,
				'hash_mismatch',
				'delegation.hash does not match the delegation fields',
			);
		}

		const recovered = ethers.verifyTypedData(
			eip712Domain,
			DELEGATION_TYPES,
			structValue,
			delegation.signature,
		);
		if (recovered.toLowerCase() !== delegatorLower) {
			return error(
				res,
				400,
				'signature_invalid',
				'signature does not match delegation.delegator',
			);
		}
	} catch (err) {
		if (err instanceof PermissionError) {
			return error(res, 400, err.code || 'signature_invalid', err.message);
		}
		return error(res, 400, 'signature_invalid', err.message || 'invalid delegation signature');
	}

	// On-chain revocation check (isDelegationValid from task 04)
	const rpcUrl = SERVER_CHAIN_META[chainId]?.rpc;
	const validity = await isDelegationValid({ hash: delegation.hash, chainId, rpcUrl }).catch(
		(err) => {
			if (err instanceof PermissionError) return { valid: false, reason: err.code };
			console.warn('[grant] isDelegationValid error', err?.message);
			return { valid: true }; // RPC unavailable; proceed and rely on indexer for revocation
		},
	);
	if (!validity.valid) {
		return error(
			res,
			400,
			validity.reason || 'signature_invalid',
			'delegation is not valid on-chain',
		);
	}

	// Scope sanity checks
	const nowSec = Math.floor(Date.now() / 1000);
	if (scope.expiry <= nowSec + 60) {
		return error(
			res,
			400,
			'validation_error',
			'scope.expiry must be at least 60 seconds in the future',
		);
	}
	if (scope.expiry > nowSec + 365 * 24 * 3600) {
		return error(res, 400, 'validation_error', 'scope.expiry must be within 365 days');
	}
	let maxAmountBig;
	try {
		maxAmountBig = BigInt(scope.maxAmount);
	} catch {
		return error(res, 400, 'validation_error', 'scope.maxAmount must be a numeric string');
	}
	if (maxAmountBig <= 0n) {
		return error(res, 400, 'validation_error', 'scope.maxAmount must be positive');
	}
	let targets;
	try {
		targets = scope.targets.map((t) => ethers.getAddress(t));
	} catch {
		return error(res, 400, 'validation_error', 'scope.targets contains an invalid address');
	}

	const delegationHash = derivedHash;
	const expiresAt = new Date(scope.expiry * 1000).toISOString();
	const delegatorAddr = ethers.getAddress(delegation.delegator);
	const delegateAddr = ethers.getAddress(delegation.delegate);

	const delegationJson = {
		delegator: delegation.delegator,
		delegate: delegation.delegate,
		authority: delegation.authority || ROOT_AUTHORITY,
		caveats: delegation.caveats,
		salt: String(delegation.salt),
		// signature stored as part of the envelope; not logged separately
		signature: delegation.signature,
		hash: delegationHash,
	};
	const scopeJson = { ...scope, targets };

	// Persist — delegation_hash is UNIQUE; on conflict return 409
	const rows = await sql`
		insert into agent_delegations (
			agent_id, chain_id, delegator_address, delegate_address,
			delegation_hash, delegation_json, scope, expires_at
		)
		values (
			${agentId},
			${chainId},
			${delegatorAddr.toLowerCase()},
			${delegateAddr.toLowerCase()},
			${delegationHash},
			${JSON.stringify(delegationJson)}::jsonb,
			${JSON.stringify(scopeJson)}::jsonb,
			${expiresAt}
		)
		on conflict (delegation_hash) do nothing
		returning id
	`;

	if (!rows || rows.length === 0) {
		const [existing] = await sql`
			select id from agent_delegations where delegation_hash = ${delegationHash} limit 1
		`;
		return error(res, 409, 'duplicate_delegation', 'this delegation has already been granted', {
			id: existing?.id,
		});
	}

	const { id } = rows[0];

	recordEvent({ userId: user.id, agentId, kind: 'permissions.grant' });

	return json(res, 200, { ok: true, id, delegationHash, expiresAt });
}

// ── list ───────────────────────────────────────────────────────────────────

const LIST_PUBLIC_CACHE = 'public, max-age=30, s-maxage=60';
const VALID_STATUSES = new Set(['active', 'revoked', 'expired', 'all']);

async function handleList(req, res) {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;

	if (req.method !== 'GET') {
		res.setHeader('allow', 'GET, OPTIONS');
		return error(res, 405, 'method_not_allowed', 'method not allowed');
	}

	const rl = await limits.read(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url = new URL(req.url, 'http://x');
	const agentId = url.searchParams.get('agentId') || null;
	const delegator = url.searchParams.get('delegator') || null;

	if (!agentId && !delegator) {
		return error(res, 400, 'missing_filter', 'agentId or delegator query param is required');
	}

	const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
	if (agentId && !UUID_RE.test(agentId)) {
		return error(res, 400, 'invalid_id', 'agentId must be a valid UUID');
	}

	const statusParam = url.searchParams.get('status') || 'active';
	if (!VALID_STATUSES.has(statusParam)) {
		return error(
			res,
			400,
			'validation_error',
			'status must be active, revoked, expired, or all',
		);
	}

	const chainIdParam = url.searchParams.get('chainId');
	const chainId = chainIdParam ? parseInt(chainIdParam, 10) : null;
	if (chainIdParam && (Number.isNaN(chainId) || chainId <= 0)) {
		return error(res, 400, 'validation_error', 'chainId must be a positive integer');
	}

	// Reject non-numeric paging here: an unparsed NaN reaches Postgres as `LIMIT
	// NaN::int` and surfaces as a 500 db_error, which reads like an outage for what
	// is plain caller error.
	const rawLimit = url.searchParams.get('limit');
	const rawOffset = url.searchParams.get('offset');
	if (rawLimit !== null && !/^\d+$/.test(rawLimit)) {
		return error(res, 400, 'validation_error', 'limit must be a non-negative integer');
	}
	if (rawOffset !== null && !/^\d+$/.test(rawOffset)) {
		return error(res, 400, 'validation_error', 'offset must be a non-negative integer');
	}
	const limitParam = Math.min(200, Math.max(1, parseInt(rawLimit || '50', 10)));
	const offset = Math.max(0, parseInt(rawOffset || '0', 10));

	// agentId-only path: public, no auth required, published agents only
	if (agentId && !delegator) {
		let rows;
		try {
			rows = await sql`
				SELECT
					id, chain_id, delegator_address, delegate_address, delegation_hash,
					scope, status, expires_at, created_at, last_redeemed_at, redemption_count
				FROM agent_delegations
				WHERE agent_id = ${agentId}
				  AND EXISTS (
					SELECT 1 FROM agent_identities ai
					WHERE ai.id = agent_delegations.agent_id AND ai.deleted_at IS NULL AND ai.is_published = true
				  )
				  AND (${statusParam} = 'all' OR status = ${statusParam})
				  AND (${chainId}::integer IS NULL OR chain_id = ${chainId}::integer)
				ORDER BY created_at DESC
				LIMIT ${limitParam}::int OFFSET ${offset}::int
			`;
		} catch (err) {
			console.error('[permissions/list] public query failed', err?.code, err?.message || err);
			return error(res, 500, 'db_error', 'Failed to list delegations');
		}

		const delegations = rows.map(toListPublicShape);
		const body = { ok: true, delegations };
		if (rows.length === limitParam) body.nextOffset = offset + limitParam;

		return json(res, 200, body, { 'cache-control': LIST_PUBLIC_CACHE });
	}

	// delegator path (or both provided): session required
	const session = await getSessionUser(req, res);
	const bearer = session ? null : await authenticateBearer(extractBearer(req));
	if (!session && !bearer) {
		return error(res, 401, 'unauthorized', 'sign in required to list delegations by delegator');
	}
	const userId = session?.id ?? bearer?.userId;

	// Verify the session user owns this delegator address
	const targetDelegator = delegator || null;
	if (targetDelegator) {
		let wallet;
		try {
			[wallet] = await sql`
				SELECT 1 FROM user_wallets
				WHERE user_id = ${userId}
				  AND lower(address) = lower(${targetDelegator})
				LIMIT 1
			`;
		} catch (err) {
			console.error(
				'[permissions/list] wallet ownership query failed',
				err?.code,
				err?.message || err,
			);
			return error(res, 500, 'db_error', 'Failed to list delegations');
		}
		if (!wallet) {
			return error(
				res,
				403,
				'forbidden',
				'delegator address does not belong to your account',
			);
		}
	}

	const whereAgentId = agentId;
	let rows;
	try {
		rows = await sql`
			SELECT
				id, chain_id, delegator_address, delegate_address, delegation_hash,
				delegation_json, scope, status, expires_at, created_at, last_redeemed_at, redemption_count
			FROM agent_delegations
			WHERE (${whereAgentId}::uuid IS NULL OR agent_id = ${whereAgentId}::uuid)
			  AND (${targetDelegator}::text IS NULL OR lower(delegator_address) = lower(${targetDelegator}::text))
			  AND (${statusParam} = 'all' OR status = ${statusParam})
			  AND (${chainId}::integer IS NULL OR chain_id = ${chainId}::integer)
			ORDER BY created_at DESC
			LIMIT ${limitParam}::int OFFSET ${offset}::int
		`;
	} catch (err) {
		console.error('[permissions/list] auth query failed', err?.code, err?.message || err);
		return error(res, 500, 'db_error', 'Failed to list delegations');
	}

	const delegations = rows.map(toListAuthShape);
	const body = { ok: true, delegations };
	if (rows.length === limitParam) body.nextOffset = offset + limitParam;

	return json(res, 200, body);
}

function toListPublicShape(row) {
	return {
		id: row.id,
		chainId: row.chain_id,
		delegator: row.delegator_address,
		delegate: row.delegate_address,
		delegationHash: row.delegation_hash,
		scope: row.scope,
		status: row.status,
		expiresAt: row.expires_at,
		createdAt: row.created_at,
		lastRedeemedAt: row.last_redeemed_at,
		redemptionCount: row.redemption_count,
	};
}

function toListAuthShape(row) {
	return {
		...toListPublicShape(row),
		delegationJson: row.delegation_json,
	};
}

// ── metadata ───────────────────────────────────────────────────────────────

function metadataCorsHeaders(res) {
	res.setHeader('access-control-allow-origin', '*');
	res.setHeader('access-control-allow-methods', 'GET, OPTIONS');
	res.setHeader('access-control-allow-headers', 'content-type');
	res.setHeader('access-control-max-age', '86400');
}

async function handleMetadata(req, res) {
	if (req.method === 'OPTIONS') {
		metadataCorsHeaders(res);
		res.statusCode = 204;
		res.end();
		return;
	}

	metadataCorsHeaders(res);

	if (req.method !== 'GET') {
		res.setHeader('allow', 'GET, OPTIONS');
		return error(res, 405, 'method_not_allowed', 'method not allowed');
	}

	const rl = await limits.read(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url = new URL(req.url, 'http://x');
	const agentId = url.searchParams.get('agentId');
	if (!agentId) return error(res, 400, 'missing_param', 'agentId is required');

	const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
	if (!UUID_RE.test(agentId)) {
		return error(res, 400, 'invalid_id', 'agentId must be a valid UUID');
	}

	const chainIdParam = url.searchParams.get('chainId');
	const chainId = chainIdParam ? parseInt(chainIdParam, 10) : null;
	if (chainIdParam && (Number.isNaN(chainId) || chainId <= 0)) {
		return error(res, 400, 'validation_error', 'chainId must be a positive integer');
	}

	// Public endpoint: an unpublished agent's delegations (wallet addresses, scope)
	// stay private to their owner, so it reads as not found here.
	const [agent] = await sql`
		SELECT id FROM agent_identities
		WHERE id = ${agentId} AND deleted_at IS NULL AND is_published = true
		LIMIT 1
	`;
	if (!agent) {
		return json(res, 404, { ok: false, error: 'agent_not_found' });
	}

	const rows = await sql`
		SELECT
			chain_id, delegator_address, delegate_address, delegation_hash,
			delegation_json, scope, expires_at, created_at, revoked_at
		FROM agent_delegations
		WHERE agent_id = ${agentId}
		  AND status = 'active'
		  AND (${chainId}::integer IS NULL OR chain_id = ${chainId}::integer)
		ORDER BY expires_at DESC
	`;

	const delegations = rows.map((r) => ({
		chainId: r.chain_id,
		delegator: r.delegator_address,
		delegate: r.delegate_address,
		hash: r.delegation_hash,
		scope: r.scope,
		expiresAt: r.expires_at,
		createdAt: r.created_at,
		envelope: r.delegation_json,
	}));

	// delegationManager: use the filtered chain if provided, otherwise first delegation's chain
	const resolveChain = chainId ?? rows[0]?.chain_id ?? null;
	const delegationManager = resolveChain
		? (DELEGATION_MANAGER_DEPLOYMENTS[resolveChain] ?? null)
		: null;

	// Last-Modified: max of created_at and revoked_at across returned rows
	let lastModified = null;
	for (const r of rows) {
		const candidates = [r.created_at, r.revoked_at].filter(Boolean);
		for (const d of candidates) {
			if (!lastModified || d > lastModified) lastModified = d;
		}
	}

	const body = {
		ok: true,
		agentId,
		spec: 'erc-7715/0.1',
		delegationManager,
		delegations,
	};

	const bodyStr = JSON.stringify(body);
	const etag = `"${createHash('sha256').update(bodyStr).digest('hex').slice(0, 32)}"`;

	res.setHeader('cache-control', 'public, max-age=60, s-maxage=300, stale-while-revalidate=600');
	res.setHeader('etag', etag);
	if (lastModified) res.setHeader('last-modified', new Date(lastModified).toUTCString());

	// ETag short-circuit
	if (req.headers['if-none-match'] === etag) {
		res.statusCode = 304;
		res.end();
		return;
	}

	res.statusCode = 200;
	res.setHeader('content-type', 'application/json; charset=utf-8');
	res.end(bodyStr);
}

// ── redeem ─────────────────────────────────────────────────────────────────

// Idempotency cache (in-memory, 10-minute TTL)
const idempotencyCache = new Map();
const IDEMPOTENCY_TTL_MS = 10 * 60 * 1000;

function idempotencyGet(key) {
	const entry = idempotencyCache.get(key);
	if (!entry) return null;
	if (Date.now() > entry.expiresAt) {
		idempotencyCache.delete(key);
		return null;
	}
	return entry.result;
}

function idempotencySet(key, result) {
	// Purge expired entries opportunistically.
	const now = Date.now();
	for (const [k, v] of idempotencyCache) {
		if (now > v.expiresAt) idempotencyCache.delete(k);
	}
	idempotencyCache.set(key, { result, expiresAt: now + IDEMPOTENCY_TTL_MS });
}

const hexData = z.string().regex(/^0x[0-9a-fA-F]*$/, 'must be 0x-prefixed hex');
const weiValue = z.string().regex(/^\d+$/, 'value must be a decimal integer string');

const callSchema = z.object({
	to: z.string().refine((v) => isAddress(v), 'to must be a valid EIP-55 address'),
	value: weiValue.default('0'),
	data: hexData.default('0x'),
});

const redeemBodySchema = z.object({
	id: z.string().uuid(),
	calls: z.array(callSchema).min(1).max(4),
});

// ERC-20 selector helpers
const TRANSFER_SELECTOR = '0xa9059cbb';
const TRANSFER_FROM_SELECTOR = '0x23b872dd';

// Decode token amount from ERC-20 transfer/transferFrom calldata.
// Param slots (0-indexed) start at hex[8 + n*64]. Returns null if unrecognised.
function decodeErc20AmountFixed(data) {
	if (!data || data.length < 10) return null;
	const hex = data.startsWith('0x') ? data.slice(2) : data;
	const sel = '0x' + hex.slice(0, 8).toLowerCase();
	try {
		if (sel === TRANSFER_SELECTOR && hex.length >= 8 + 64 + 64) {
			// slot 1 (0-indexed) = amount
			return BigInt('0x' + hex.slice(8 + 64, 8 + 64 + 64));
		}
		if (sel === TRANSFER_FROM_SELECTOR && hex.length >= 8 + 64 + 64 + 64) {
			// slot 2 (0-indexed) = amount
			return BigInt('0x' + hex.slice(8 + 64 + 64, 8 + 64 + 64 + 64));
		}
	} catch {
		return null;
	}
	return null;
}

function periodStart(period) {
	const now = new Date();
	if (period === 'daily') {
		return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
	}
	if (period === 'weekly') {
		const day = now.getUTCDay(); // 0=Sun
		const diff = day === 0 ? -6 : 1 - day; // back to Monday
		const monday = new Date(now);
		monday.setUTCDate(now.getUTCDate() + diff);
		monday.setUTCHours(0, 0, 0, 0);
		return monday;
	}
	// 'once' or unknown: entire history counts
	return new Date(0);
}

async function handleRedeem(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS' })) return;
	if (!method(req, res, ['POST'])) return;

	// Feature flag — 503 when disabled
	if (!env.PERMISSIONS_RELAYER_ENABLED) {
		return error(res, 503, 'feature_disabled', 'relayer not enabled on this deployment');
	}

	// Rate limit — strict bucket since each request costs gas
	const ip = clientIp(req);
	const rl = await limits.strict(ip);
	if (!rl.success) return rateLimited(res, rl);

	// Auth — agent bearer only (no user sessions on this machine endpoint)
	const token = extractBearer(req);
	const bearer = await authenticateBearer(token);
	if (!bearer) return error(res, 401, 'unauthorized', 'valid bearer token required');
	if (!hasScope(bearer.scope, 'permissions:redeem')) {
		return error(
			res,
			403,
			'insufficient_scope',
			"token must include 'permissions:redeem' scope",
		);
	}

	// Idempotency-Key check (before parsing body — key is in header)
	const idempotencyKey = req.headers['idempotency-key'] || null;

	// Parse body
	let body;
	try {
		body = parse(redeemBodySchema, await readJson(req));
	} catch (err) {
		return error(res, err.status || 400, err.code || 'validation_error', err.message);
	}
	const { id, calls } = body;

	// Idempotency-Key early return. The cache key carries the bearer principal
	// because this lookup runs before the ownership gate below: keyed on the
	// delegation id alone, a principal who does not own the delegation could
	// replay someone else's (id, key) pair and be handed their txHash and
	// receipt. Scoping to the principal makes a retry idempotent only for the
	// caller who made the original call.
	const idempotencyScope = idempotencyKey ? `${bearer.userId}:${id}:${idempotencyKey}` : null;
	if (idempotencyScope) {
		const cached = idempotencyGet(idempotencyScope);
		if (cached) return json(res, 200, cached);
	}

	// Load delegation row
	const [row] = await sql`
		SELECT id, agent_id, chain_id, delegation_hash, delegation_json, scope,
		       status, expires_at, redemption_count, last_redeemed_at
		FROM agent_delegations
		WHERE id = ${id}
		LIMIT 1
	`;
	if (!row) return error(res, 404, 'delegation_not_found', 'delegation not found');

	// Ownership binding: the bearer principal must own the agent this delegation
	// belongs to. Without this, any token carrying the `permissions:redeem` scope
	// could force redemption of ANY delegation by id (enumerating UUIDs) — spending
	// the platform relayer's gas and triggering transfers the delegator didn't
	// initiate. Mirror the owner gate used by the grant path.
	const [owner] = await sql`
		SELECT user_id FROM agent_identities
		WHERE id = ${row.agent_id} AND deleted_at IS NULL
		LIMIT 1
	`;
	if (!owner || owner.user_id !== bearer.userId) {
		// 404 (not 403) so a caller can't probe which delegation ids exist.
		return error(res, 404, 'delegation_not_found', 'delegation not found');
	}

	// Check status
	if (row.status === 'revoked') {
		return error(res, 409, 'delegation_revoked', 'delegation has been revoked');
	}

	// Check expiry; auto-flip status if expired
	const now = new Date();
	if (new Date(row.expires_at) <= now) {
		// Side-effect: mark as expired without blocking
		sql`UPDATE agent_delegations SET status = 'expired' WHERE id = ${id}`.catch(() => {});
		return error(res, 409, 'delegation_expired', 'delegation has expired');
	}

	if (row.status !== 'active') {
		return error(res, 409, 'delegation_expired', `delegation status is '${row.status}'`);
	}

	const scope = row.scope;
	const chainId = row.chain_id;

	// The relayer redeems through the chain's DelegationManager, so a row on a
	// chain with no deployment can never settle. Grant, revoke, and verify all
	// gate on this map; redeem used to reach `redeemDelegation`, have
	// `managerAddress()` throw, and report it as a 502 rpc_error: a chain
	// support gap dressed up as a provider outage. Checked here, before the
	// spend reservation, so there is nothing to release.
	if (!DELEGATION_MANAGER_DEPLOYMENTS[chainId]) {
		return error(
			res,
			409,
			'chain_not_supported',
			`no DelegationManager deployment for chainId ${chainId}`,
		);
	}

	// ── Server-side scope checks (cheap, prevent paying gas on doomed tx) ────

	// 1. Target allow-list
	const allowedTargets = new Set((scope.targets || []).map((t) => t.toLowerCase()));
	for (const call of calls) {
		if (!allowedTargets.has(call.to.toLowerCase())) {
			return error(
				res,
				403,
				'target_not_allowed',
				`call target ${call.to} is not in scope.targets`,
			);
		}
	}

	// 2. Native ETH: reject non-zero value if token is ERC-20
	const isNative = scope.token === 'native';
	if (!isNative) {
		for (const call of calls) {
			if (BigInt(call.value) > 0n) {
				return error(
					res,
					403,
					'scope_exceeded',
					'non-zero ETH value not allowed for ERC-20 scoped delegation',
				);
			}
		}
	}

	// 3. Amount cap. Compute this request's spend, then reserve it atomically.
	const maxAmount = BigInt(scope.maxAmount || '0');
	const pStart = periodStart(scope.period || 'daily');

	let requestAmount = 0n;
	if (isNative) {
		requestAmount = calls.reduce((s, c) => s + BigInt(c.value), 0n);
	} else {
		for (const call of calls) {
			const decoded = decodeErc20AmountFixed(call.data);
			if (decoded === null) {
				return error(
					res,
					403,
					'scope_exceeded',
					`call to ${call.to} does not look like an ERC-20 transfer or transferFrom`,
				);
			}
			requestAmount += decoded;
		}
	}

	// Atomically reserve this spend against the period cap. Reading the period
	// history and then writing the usage_event only AFTER the on-chain submit left
	// a TOCTOU window: concurrent redeems for the same delegation all read the same
	// historical total, all pass the cap, and all submit — collectively exceeding
	// scope.maxAmount. The advisory xact lock (keyed on the delegation id)
	// serializes redeems for one delegation, and the INSERT…SELECT only materializes
	// the reservation row when history + this request stays within the cap, so the
	// check and the reserve are one atomic statement. Finalized to 'ok' with the tx
	// hash after submit, or deleted if the submit never lands. 'failed' rows are
	// excluded from the period sum so a released reservation frees its budget.
	const reserveMeta = JSON.stringify({ delegation_id: id, chain_id: chainId, amount: requestAmount.toString() });
	const reserveRows = await runLocked([id], sql`
		WITH spent AS (
			SELECT trunc(COALESCE(SUM((meta->>'amount')::numeric), 0)) AS s
			FROM usage_events
			WHERE kind = 'permissions.redeem'
			  AND status <> 'failed'
			  AND meta->>'delegation_id' = ${id}
			  AND created_at >= ${pStart.toISOString()}
		)
		INSERT INTO usage_events (user_id, api_key_id, agent_id, kind, status, meta)
		SELECT ${bearer.userId}, ${bearer.apiKeyId ?? null}, ${row.agent_id},
		       'permissions.redeem', 'pending', ${reserveMeta}::jsonb
		FROM spent
		WHERE spent.s + ${requestAmount.toString()}::numeric <= ${maxAmount.toString()}::numeric
		RETURNING id, (SELECT trunc(s)::text FROM spent) AS spent_before
	`);
	if (!reserveRows.length) {
		// Re-read for an accurate error body (outside the lock is fine).
		const [h] = await sql`
			SELECT trunc(COALESCE(SUM((meta->>'amount')::numeric), 0))::text AS spent
			FROM usage_events
			WHERE kind = 'permissions.redeem' AND status <> 'failed'
			  AND meta->>'delegation_id' = ${id} AND created_at >= ${pStart.toISOString()}
		`;
		return error(
			res,
			403,
			'scope_exceeded',
			isNative
				? 'ETH spend would exceed scope.maxAmount for this period'
				: 'token spend would exceed scope.maxAmount for this period',
			{
				maxAmount: scope.maxAmount,
				periodSpent: h?.spent ?? '0',
				requested: requestAmount.toString(),
			},
		);
	}
	const spendReservationId = reserveRows[0].id;

	// Every exit from here on must release the reservation, or a request that never
	// reached the chain keeps consuming the delegation's period budget forever
	// ('pending' rows count toward the cap; only 'failed' is excluded).
	const releaseReservation = () =>
		sql`UPDATE usage_events SET status = 'failed' WHERE id = ${spendReservationId}`.catch(
			(err) => console.error('[permissions/redeem] reservation release failed', err?.message),
		);

	// ── Build signer ───────────────────────────────────────────────────────
	// evmFallbackProvider owns endpoint resolution for every chain: an explicit
	// RPC_URL_<chainId> override first, then Alchemy, then the curated public
	// endpoints, with sequential failover across all of them. This handler used
	// to carry its own hand-copied one-endpoint-per-chain table and 502 on any
	// chain missing from it, which would have failed the next DelegationManager
	// deployment on a chain the shared layer can already reach.
	let signer;
	try {
		const provider = await evmFallbackProvider(chainId);
		// AGENT_RELAYER_KEY is never logged — only use it to construct the Wallet
		signer = new Wallet(env.AGENT_RELAYER_KEY, provider);
	} catch (err) {
		await releaseReservation();
		// `no RPC endpoint for chain N` is a deployment gap, not a code fault:
		// report it as an upstream failure the operator can fix with RPC_URL_<id>
		// rather than as a generic internal error.
		if (/no RPC endpoint/i.test(err?.message || '')) {
			return error(
				res,
				502,
				'rpc_error',
				`no RPC endpoint available for chain ${chainId} (set RPC_URL_${chainId})`,
			);
		}
		return error(res, 500, 'internal_error', 'failed to initialise relayer signer');
	}

	// ── Submit on-chain ────────────────────────────────────────────────────
	let txHash, receipt;
	try {
		({ txHash, receipt } = await redeemDelegation({
			delegation: row.delegation_json,
			delegationHash: row.delegation_hash,
			calls,
			signer,
			chainId,
		}));
	} catch (err) {
		// The on-chain submit never landed — release the reservation so it stops
		// counting toward the period cap (mark 'failed', excluded from the sum).
		await releaseReservation();
		if (err instanceof PermissionError && err.code === 'delegation_revoked') {
			// Auto-sync status in DB
			sql`UPDATE agent_delegations SET status = 'revoked' WHERE id = ${id}`.catch(() => {});
			return error(res, 409, 'delegation_revoked', err.message);
		}
		// RPC or provider error
		console.error('[permissions/redeem] on-chain error', err?.code, err?.message);
		return error(res, 502, 'rpc_error', err?.message || 'on-chain call failed');
	}

	// ── Update DB ──────────────────────────────────────────────────────────
	await sql`
		UPDATE agent_delegations
		SET redemption_count = redemption_count + 1,
		    last_redeemed_at = NOW()
		WHERE id = ${id}
	`;

	// Finalize the reservation written before submit: flip 'pending' → 'ok' and
	// attach the on-chain outcome. The amount already counts toward the period cap
	// (reserved atomically under the advisory lock), so this only records the result.
	await sql`
		UPDATE usage_events
		SET status = 'ok',
		    meta = meta || ${JSON.stringify({ tx_hash: txHash, gas_used: receipt.gasUsed })}::jsonb
		WHERE id = ${spendReservationId}
	`.catch((err) => console.error('[permissions/redeem] finalize failed', err?.message));

	const result = { ok: true, txHash, receipt };

	if (idempotencyScope) {
		idempotencySet(idempotencyScope, result);
	}

	return json(res, 200, result);
}

// ── revoke ─────────────────────────────────────────────────────────────────

const revokeBodySchema = z.object({
	id: z.string().uuid(),
	txHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/, 'must be a 66-char 0x-prefixed hex string'),
});

const revokeIface = new Interface(DELEGATION_MANAGER_ABI);
const _revokeEvent = revokeIface.getEvent('DisabledDelegation');
if (!_revokeEvent)
	throw new Error(
		'DisabledDelegation event not found in DELEGATION_MANAGER_ABI — check src/erc7710/abi.js',
	);
const DISABLED_TOPIC = _revokeEvent.topicHash;

const RPC_TIMEOUT_MS = 5000;

function withTimeout(promise, ms) {
	return new Promise((resolve, reject) => {
		const t = setTimeout(() => reject(new Error(`rpc timeout after ${ms}ms`)), ms);
		Promise.resolve(promise).then(
			(v) => {
				clearTimeout(t);
				resolve(v);
			},
			(e) => {
				clearTimeout(t);
				reject(e);
			},
		);
	});
}

async function handleRevoke(req, res) {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req, res);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	if (!(await requireCsrf(req, res, user.id))) return;

	const rl = await limits.permissionsRevoke(user.id);
	if (!rl.success) return rateLimited(res, rl);

	const raw = await readJson(req);
	const parsed = revokeBodySchema.safeParse(raw);
	if (!parsed.success) {
		const msg = parsed.error.issues
			.map((i) => `${i.path.join('.') || 'body'}: ${i.message}`)
			.join('; ');
		return error(res, 400, 'validation_error', msg);
	}
	const { id, txHash } = parsed.data;

	// Lookup delegation + agent owner in one join
	const [row] = await sql`
		SELECT d.*, a.user_id AS agent_owner_user_id
		FROM agent_delegations d
		JOIN agent_identities a ON a.id = d.agent_id AND a.deleted_at IS NULL
		WHERE d.id = ${id}
		LIMIT 1
	`;
	if (!row) return error(res, 404, 'delegation_not_found', 'delegation not found');

	// Authorization: agent owner OR the delegator wallet linked to this user
	const isAgentOwner = row.agent_owner_user_id === user.id;
	let isDelegator = false;
	if (!isAgentOwner) {
		const [wallet] = await sql`
			SELECT address FROM user_wallets
			WHERE user_id = ${user.id} AND address = ${row.delegator_address}
			LIMIT 1
		`;
		isDelegator = !!wallet;
	}
	if (!isAgentOwner && !isDelegator) {
		return error(res, 403, 'forbidden', 'you are not authorized to revoke this delegation');
	}

	// Build a read-only provider for the delegation's chain
	const chainMeta = SERVER_CHAIN_META[row.chain_id];
	if (!chainMeta) {
		return error(res, 400, 'chain_not_supported', `chainId ${row.chain_id} is not supported`);
	}
	const managerAddr = DELEGATION_MANAGER_DEPLOYMENTS[row.chain_id];
	if (!managerAddr) {
		return error(
			res,
			400,
			'chain_not_supported',
			`no DelegationManager for chainId ${row.chain_id}`,
		);
	}

	const provider = await evmFallbackProvider(row.chain_id, { primaryUrl: chainMeta.rpc });

	// Fetch receipt (up to 3 attempts with short back-off for propagation lag)
	let receipt = null;
	for (let attempt = 0; attempt < 3 && !receipt; attempt++) {
		if (attempt > 0) await new Promise((r) => setTimeout(r, 800));
		receipt = await withTimeout(provider.getTransactionReceipt(txHash), RPC_TIMEOUT_MS).catch(
			() => null,
		);
	}
	if (!receipt) return error(res, 400, 'tx_not_found', 'transaction receipt not found');

	if (receipt.status === 0) {
		return error(res, 400, 'tx_reverted', 'transaction was reverted on-chain');
	}

	// Decode DisabledDelegation event: (bytes32 indexed delegationHash, address indexed delegator, address indexed delegate, ...)
	// topics[0] = event sig, topics[1] = delegationHash, topics[2] = delegator, topics[3] = delegate
	const disabledLog = receipt.logs.find((log) => log.topics[0] === DISABLED_TOPIC);
	if (!disabledLog) {
		return error(res, 400, 'tx_mismatch', 'transaction contains no DisabledDelegation event');
	}

	const loggedHash = disabledLog.topics[1]; // bytes32 indexed — raw topic IS the value
	if (loggedHash.toLowerCase() !== row.delegation_hash.toLowerCase()) {
		return error(res, 400, 'tx_mismatch', 'transaction revoked a different delegation hash');
	}

	// Second confirmation: call disabledDelegations(hash) on-chain
	const manager = new Contract(managerAddr, DELEGATION_MANAGER_ABI, provider);
	const isDisabled = await withTimeout(
		manager.disabledDelegations(row.delegation_hash),
		RPC_TIMEOUT_MS,
	).catch(() => null);
	if (!isDisabled) {
		return error(
			res,
			400,
			'not_yet_disabled',
			'delegation is not yet marked disabled on-chain',
		);
	}

	// Flip status active → revoked; 0 rows = already revoked / never active
	const updated = await sql`
		UPDATE agent_delegations
		SET status = 'revoked', revoked_at = NOW(), tx_hash_revoke = ${txHash}
		WHERE id = ${id} AND status = 'active'
		RETURNING revoked_at
	`;
	if (!updated || updated.length === 0) {
		const [current] = await sql`SELECT status FROM agent_delegations WHERE id = ${id} LIMIT 1`;
		const currentStatus = current?.status ?? 'unknown';
		return error(
			res,
			409,
			'already_revoked',
			`delegation cannot be revoked (current status: ${currentStatus})`,
		);
	}

	const revokedAt = updated[0].revoked_at;

	recordEvent({ userId: user.id, agentId: row.agent_id, kind: 'permissions.revoke' });

	return json(res, 200, { ok: true, status: 'revoked', revokedAt });
}

// ── verify ─────────────────────────────────────────────────────────────────

const HASH_RE = /^0x[0-9a-fA-F]{64}$/;
const CACHE_VALID = 'public, max-age=30, s-maxage=60';
const CACHE_INVALID = 'public, max-age=300, s-maxage=600';

async function handleVerify(req, res) {
	res.setHeader('access-control-allow-origin', '*');
	res.setHeader('access-control-allow-methods', 'GET, OPTIONS');
	res.setHeader('access-control-allow-headers', 'content-type');
	res.setHeader('access-control-max-age', '86400');
	if (req.method === 'OPTIONS') {
		res.statusCode = 204;
		res.end();
		return;
	}

	if (req.method !== 'GET') {
		res.setHeader('allow', 'GET, OPTIONS');
		return error(res, 405, 'method_not_allowed', 'method not allowed');
	}

	const rl = await limits.read(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url = new URL(req.url, 'http://x');
	const hash = url.searchParams.get('hash');
	const chainIdRaw = url.searchParams.get('chainId');

	if (!hash) return error(res, 400, 'validation_error', 'hash query param is required');
	if (!HASH_RE.test(hash))
		return error(res, 400, 'validation_error', 'hash must be 0x + 64 hex chars');
	if (!chainIdRaw) return error(res, 400, 'validation_error', 'chainId query param is required');

	const chainId = parseInt(chainIdRaw, 10);
	if (Number.isNaN(chainId) || chainId <= 0)
		return error(res, 400, 'validation_error', 'chainId must be a positive integer');
	if (!DELEGATION_MANAGER_DEPLOYMENTS[chainId])
		return error(res, 400, 'validation_error', `chainId ${chainId} is not supported`);

	const checkedAt = new Date().toISOString();

	const [row] = await sql`
		SELECT status, expires_at
		FROM agent_delegations
		WHERE delegation_hash = ${hash} AND chain_id = ${chainId}
		LIMIT 1
	`;

	if (row?.status === 'revoked') {
		return verifyRespond(
			res,
			{ ok: true, valid: false, reason: 'delegation_revoked', checkedAt, chainId, hash },
			CACHE_INVALID,
		);
	}

	if (row?.status === 'expired' || (row?.expires_at && new Date(row.expires_at) <= new Date())) {
		return verifyRespond(
			res,
			{ ok: true, valid: false, reason: 'delegation_expired', checkedAt, chainId, hash },
			CACHE_INVALID,
		);
	}

	// On-chain check — 5 s timeout
	let disabled;
	try {
		disabled = await verifyWithTimeout(verifyCheckDisabled(hash, chainId), 5000);
	} catch (err) {
		// Route through the boundary: ref + Sentry capture + deduped ops alert.
		// The internal RPC error string stays server-side; the client sees only a
		// stable code plus the ref it can quote to support.
		const ref = reportServerError(err, { code: 'rpc_error', status: 502, context: { check: 'verifyCheckDisabled' } });
		res.statusCode = 502;
		res.setHeader('content-type', 'application/json; charset=utf-8');
		res.setHeader('cache-control', 'no-store');
		res.end(
			JSON.stringify({
				ok: false,
				error: 'rpc_error',
				error_description: 'on-chain verification failed',
				ref,
			}),
		);
		return;
	}

	if (disabled) {
		// Self-heal: if DB still tracks it as active, flip to revoked without blocking the response.
		if (row?.status === 'active') {
			queueMicrotask(() => {
				sql`
					UPDATE agent_delegations
					SET status = 'revoked', revoked_at = NOW()
					WHERE delegation_hash = ${hash} AND status = 'active'
				`.catch((e) => console.error('[verify] self-heal failed', e));
			});
		}
		return verifyRespond(
			res,
			{ ok: true, valid: false, reason: 'delegation_revoked', checkedAt, chainId, hash },
			CACHE_INVALID,
		);
	}

	const body = { ok: true, valid: true, checkedAt, chainId, hash };
	if (!row) body.reason = 'unknown_to_platform';
	return verifyRespond(res, body, CACHE_VALID);
}

async function verifyCheckDisabled(hash, chainId) {
	const provider = await evmFallbackProvider(chainId);
	const manager = new Contract(
		DELEGATION_MANAGER_DEPLOYMENTS[chainId],
		DELEGATION_MANAGER_ABI,
		provider,
	);
	// The on-chain method is `disabledDelegations(bytes32)`; that is the only name
	// DELEGATION_MANAGER_ABI declares, so calling anything else here resolves to
	// undefined on the Contract and turns every verify into a 502.
	return manager.disabledDelegations(hash);
}

function verifyWithTimeout(promise, ms) {
	return Promise.race([
		promise,
		new Promise((_, reject) =>
			setTimeout(() => reject(new Error(`RPC timeout after ${ms}ms`)), ms),
		),
	]);
}

function verifyRespond(res, body, cacheControl) {
	const str = JSON.stringify(body);
	const etag = `"${createHash('sha256').update(str).digest('hex').slice(0, 16)}"`;
	res.statusCode = 200;
	res.setHeader('content-type', 'application/json; charset=utf-8');
	res.setHeader('cache-control', cacheControl);
	res.setHeader('etag', etag);
	res.end(str);
}