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/vanity/drops — sealed wallet drops (end-to-end-encrypted crypto gifting).
//
// A "drop" is a pre-funded Solana wallet handed to a recipient as an E2E-encrypted
// gift, claimable by link / QR / 3D agent. The wallet secret is ECIES-sealed so
// neither the operator, the database, a log, nor anyone but the holder of the
// matching X25519 key can open it. Funding is real on-chain (SOL / USDC / $THREE).
// The create step is x402-paid. Claims are exactly-once; expired unclaimed drops
// are reclaimed by the sender on-chain.
//
// GET ?view=config → assets, networks, funding availability, limits
// GET ?view=get&id=<id> → one drop (public view; no secret, no envelope)
// GET ?view=stats → funded / claimed / reclaimed counts
// GET ?view=mine&senderTag=<tag> → a sender's drops (to reclaim)
// GET ?view=balance&id=<id> → live on-chain balance of the drop address
//
// POST ?action=create (x402 PAID) → grind (optional vanity) + seal + fund + persist.
// body: { asset, amount, sealMode:'direct'|'claim-time', recipientPubKey?,
// claimTokenHash? (claim-time), prefix?, suffix?, ignoreCase?,
// format?, expiryHours, message?, theme?, senderLabel?, reclaimAddress?,
// senderTag?, irlPinId?, roomId? }
// POST ?action=claim → present the one-time claim token, atomically
// claim, and receive the SEALED envelope to open client-side.
// body: { id, claimToken (claim-time mode), claimRecipientPubKey? }
// POST ?action=reveal → direct-seal mode: fetch the sealed envelope
// (useless without the recipient's private key) for client-side open.
// body: { id }
// POST ?action=reclaim → sender sweeps an EXPIRED, unclaimed drop's
// funds back on-chain (atomic, exactly-once). body: { id } — funds always
// return to the reclaimAddress recorded at create time (never a body value).
//
// Money + key safety (see sealed-drop-store.js + sealed-drop-funding.js +
// src/solana/vanity/drop-protocol.js):
// • The plaintext drop secret NEVER appears in a response, a log, or an
// unsealed store field. It is sealed (ECIES) for delivery and held only as an
// AES-256-GCM ciphertext at rest for the reclaim-sweep path.
// • Funding is confirmed on-chain BEFORE the drop is persisted as claimable.
// • A drop is claimed EXACTLY ONCE (atomic CAS, idempotent on the claim token)
// OR reclaimed by the sender after expiry — never both.
// • $THREE is the only coin featured as *a coin*; SOL/USDC are runtime rails.
import { wrap, cors, error, json, readJson, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import {
NETWORK_BASE_MAINNET,
NETWORK_SOLANA_MAINNET,
send402,
verifyPayment,
settlePayment,
encodePaymentResponseHeader,
permit2VariantOf,
solanaSelfPayOnly,
resolveResourceUrl,
buildBazaarSchema,
} from '../_lib/x402-spec.js';
import { env } from '../_lib/env.js';
import {
PAYMENT_IDENTIFIER,
checkCache,
extractIdFromHeader,
hashPaymentProof,
hashRequestPayload,
paymentIdentifierExtension,
storeResponse,
writeCachedResponse,
writeConflict,
} from '../_lib/x402/payment-identifier-server.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import {
sealToRecipient,
parseX25519Key,
SEALED_ENVELOPE_SCHEME,
} from '../../src/solana/vanity/sealed-envelope.js';
import {
grindVanityNode,
validatePattern,
MAX_SERVER_PATTERN_LENGTH,
} from '../../src/solana/vanity/grinder-node.js';
import { grindVanityMnemonic, MAX_MNEMONIC_PATTERN_LENGTH } from '../../src/solana/vanity/mnemonic-grinder.js';
import { STRENGTH_WORD_COUNTS, DEFAULT_STRENGTH } from '../../src/solana/vanity/mnemonic.js';
import {
DROP_PROTOCOL_VERSION,
deriveDropId,
hashClaimToken,
timingSafeHexEqual,
isValidDropId,
normalizeAsset,
SEAL_MODES,
} from '../../src/solana/vanity/drop-protocol.js';
import {
createDrop,
activateDrop,
voidDrop,
getDrop,
getDropRecord,
claimDrop,
markReclaimable,
recordClaimDelivery,
listBySender,
dropStats,
isTransientDrop,
} from '../_lib/sealed-drop-store.js';
import {
fundingConfigured,
fundingWalletAddress,
fundDropAddress,
readDropBalance,
sweepReclaim,
amountToAtomics,
atomicsToAmount,
} from '../_lib/sealed-drop-funding.js';
import { encryptSecret, decryptSecret } from '../_lib/secret-box.js';
import { randomBytes as nobleRandomBytes, bytesToHex } from '@noble/hashes/utils';
import bs58 from 'bs58';
import { Keypair } from '@solana/web3.js';
const ROUTE = '/api/vanity/drops';
const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const PUBLIC_ORIGIN = env.APP_ORIGIN || 'https://three.ws';
const MIN_EXPIRY_HOURS = 1;
const MAX_EXPIRY_HOURS = 24 * 90; // 90 days
const DEFAULT_EXPIRY_HOURS = 24 * 7; // a week
const READ_CACHE = 'public, max-age=10, s-maxage=30, stale-while-revalidate=120';
// Curate the themes the share card + claim page render. Coin-agnostic visuals.
const THEMES = new Set(['default', 'birthday', 'congrats', 'thanks', 'welcome', 'tip']);
// Flat x402 create FEE (USDC atomics, 6dp). This is the platform charge for the
// create operation — independent of the funding amount, which the platform moves
// from its own funding wallet (a gift the creator arranges out-of-band or via the
// funding wallet top-up). Vanity grinding adds nothing extra at ≤3 chars.
const CREATE_FEE_ATOMICS = 50_000; // $0.05
// ── x402 challenge ────────────────────────────────────────────────────────────
export function buildRequirements(resourceUrl, priceAtomics) {
const amount = String(priceAtomics);
const out = [];
if (env.X402_PAY_TO_BASE && env.X402_ASSET_ADDRESS_BASE) {
const eip3009 = {
scheme: 'exact',
network: NETWORK_BASE_MAINNET,
amount,
payTo: env.X402_PAY_TO_BASE,
asset: env.X402_ASSET_ADDRESS_BASE,
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USD Coin', version: '2', decimals: 6 },
};
out.push(eip3009);
const permit2 = permit2VariantOf(eip3009);
if (permit2) out.push(permit2);
}
if (env.X402_PAY_TO_SOLANA && env.X402_ASSET_MINT_SOLANA && (env.X402_FEE_PAYER_SOLANA || solanaSelfPayOnly())) {
out.push({
scheme: 'exact',
network: NETWORK_SOLANA_MAINNET,
amount,
payTo: env.X402_PAY_TO_SOLANA,
asset: env.X402_ASSET_MINT_SOLANA,
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USDC', decimals: 6, ...(solanaSelfPayOnly() ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }) },
});
}
return out;
}
const CREATE_DESCRIPTION =
'three.ws Sealed Wallet Drops — mint a pre-funded Solana wallet and deliver it as an ' +
'end-to-end-encrypted gift, claimable by link / QR / 3D agent. The wallet secret is ' +
'ECIES-sealed (x25519-hkdf-sha256-aes256gcm) so neither three.ws, our database, nor ' +
'anyone but the recipient can open it. Fund it with SOL, USDC, or $THREE (real on-chain ' +
'transfer, confirmed before the drop goes live). Optional vanity prefix/suffix. Two seal ' +
'modes: direct (seal to a known X25519 recipient key) or claim-time (a bearer link whose ' +
'fragment carries the claim key the server never sees). Exactly-once claim; expired drops ' +
'reclaim to the sender. Pay the flat create fee in USDC on Base or Solana mainnet.';
const CREATE_INPUT_EXAMPLE = {
asset: 'SOL', amount: '0.01', sealMode: 'claim-time',
prefix: 'gift', expiryHours: '168', message: 'Happy birthday!', theme: 'birthday',
senderLabel: 'Alex', reclaimAddress: '<Base58 Solana address>',
};
const CREATE_INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['asset', 'amount', 'sealMode'],
properties: {
asset: { type: 'string', enum: ['SOL', 'USDC', 'THREE'], description: 'Funding asset. $THREE is the platform coin; SOL/USDC are rails.' },
amount: { type: 'string', description: 'Funding amount as a decimal (e.g. "0.01"). Moved on-chain into the drop wallet.' },
sealMode: { type: 'string', enum: ['direct', 'claim-time'], description: 'direct = seal to recipientPubKey now; claim-time = bearer link, the server mints a claim key and returns its secret once (you embed it in the link fragment).' },
recipientPubKey: { type: 'string', description: 'direct mode: the recipient X25519 public key the secret is sealed to.' },
prefix: { type: 'string', description: 'Optional Base58 vanity prefix (≤3 chars combined).' },
suffix: { type: 'string', description: 'Optional Base58 vanity suffix (≤3 chars combined).' },
ignoreCase: { type: 'string', enum: ['0', '1', 'true', 'false'] },
format: { type: 'string', enum: ['keypair', 'mnemonic'], description: 'mnemonic delivers an importable seed phrase (≤2 vanity chars).' },
expiryHours: { type: 'string', description: 'Hours until the drop expires + becomes reclaimable. 1–2160, default 168.' },
message: { type: 'string', description: 'Optional gift message (≤280 chars).' },
theme: { type: 'string', description: 'Optional card theme: default|birthday|congrats|thanks|welcome|tip.' },
senderLabel: { type: 'string', description: 'Optional public "from" label (≤40 chars).' },
reclaimAddress: { type: 'string', description: 'Solana address the funds reclaim to if the drop expires unclaimed.' },
senderTag: { type: 'string', description: 'Optional opaque tag to list your drops later (non-PII).' },
irlPinId: { type: 'string', description: 'Optional IRL pin id this drop is attached to (3D-agent handoff).' },
roomId: { type: 'string', description: 'Optional room id a 3D agent hands the drop out in.' },
},
};
const CREATE_OUTPUT_EXAMPLE = {
created: true,
drop: {
id: 'a1b2c3d4e5f607182930a1b2',
address: 'giftEXAMPLE1111111111111111111111111111111',
asset: 'SOL', amount: '0.01', sealMode: 'claim-time', status: 'funded',
expiresAt: 1750172800000, theme: 'birthday',
},
funding: { confirmed: true, tx: '<funding tx>', explorerUrl: 'https://solscan.io/tx/...' },
claimUrl: 'https://three.ws/drop/a1b2c3d4e5f607182930a1b2',
qrUrl: 'https://three.ws/api/vanity/drops?view=qr&id=a1b2c3d4e5f607182930a1b2',
ogUrl: 'https://three.ws/api/og/sealed-drop?id=a1b2c3d4e5f607182930a1b2',
};
const CREATE_OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['created', 'drop'],
properties: {
created: { type: 'boolean' },
drop: { type: 'object' },
funding: { type: 'object' },
claimUrl: { type: 'string', format: 'uri' },
qrUrl: { type: 'string', format: 'uri' },
ogUrl: { type: 'string', format: 'uri' },
},
};
const CREATE_BAZAAR = {
discoverable: true,
info: {
input: { type: 'http', method: 'POST', body: CREATE_INPUT_EXAMPLE, bodyType: 'json' },
output: { type: 'json', example: CREATE_OUTPUT_EXAMPLE },
},
schema: buildBazaarSchema({
method: 'POST', bodyType: 'json', bodySchema: CREATE_INPUT_SCHEMA, outputSchema: CREATE_OUTPUT_SCHEMA,
}),
};
function bad(message, code) {
return Object.assign(new Error(message), { status: 400, code: code || 'validation_error' });
}
function activeNetworks() {
const nets = [];
if (env.X402_PAY_TO_BASE && env.X402_ASSET_ADDRESS_BASE) nets.push('base');
if (env.X402_PAY_TO_SOLANA && env.X402_ASSET_MINT_SOLANA && (env.X402_FEE_PAYER_SOLANA || solanaSelfPayOnly())) nets.push('solana');
return nets;
}
// ── parse + validate a create request body ────────────────────────────────────
function parseCreate(body) {
const asset = normalizeAsset(body?.asset);
const amount = String(body?.amount ?? '').trim();
if (!amount) throw bad('amount is required (decimal, e.g. "0.01")');
const atomics = amountToAtomics(amount, asset); // validates shape/decimals
const sealMode = String(body?.sealMode || '').trim();
if (!SEAL_MODES.includes(sealMode)) {
throw bad(`sealMode must be one of ${SEAL_MODES.join(', ')}`, 'invalid_seal_mode');
}
// In direct mode the sender supplies the recipient's X25519 public key. In
// claim-time mode the server mints the claim key itself (returned once in the
// response, embedded by the creator in the link fragment) — no client input.
let recipientPubKey = null;
if (sealMode === 'direct') {
recipientPubKey = String(body?.recipientPubKey || '').trim();
if (!recipientPubKey) throw bad('direct seal mode requires recipientPubKey (X25519 public key)', 'recipient_required');
recipientPubKey = bs58.encode(parseX25519Key(recipientPubKey, 'recipientPubKey')); // validate + canonicalize
}
// Optional vanity pattern.
const prefix = typeof body?.prefix === 'string' ? body.prefix.trim() : '';
const suffix = typeof body?.suffix === 'string' ? body.suffix.trim() : '';
const ignoreCase = body?.ignoreCase === '1' || body?.ignoreCase === 'true' || body?.ignoreCase === true;
const format = String(body?.format || 'keypair').toLowerCase();
if (format !== 'keypair' && format !== 'mnemonic') throw bad('format must be keypair or mnemonic', 'invalid_format');
let strength = DEFAULT_STRENGTH;
if (body?.strength != null && body?.strength !== '') {
strength = Number(body.strength);
if (!STRENGTH_WORD_COUNTS[strength]) throw bad('strength must be 128 or 256', 'invalid_strength');
}
for (const [label, pat] of [['prefix', prefix], ['suffix', suffix]]) {
if (!pat) continue;
const v = validatePattern(pat);
if (!v.valid) throw bad(`invalid ${label}: ${v.errors.join('; ')}`);
}
const maxLen = format === 'mnemonic' ? MAX_MNEMONIC_PATTERN_LENGTH : MAX_SERVER_PATTERN_LENGTH;
if (prefix.length + suffix.length > maxLen) {
throw Object.assign(new Error(`combined vanity pattern exceeds the ${format} server limit of ${maxLen} chars`), { status: 400, code: 'pattern_too_long' });
}
let expiryHours = Number(body?.expiryHours);
if (!Number.isFinite(expiryHours) || expiryHours <= 0) expiryHours = DEFAULT_EXPIRY_HOURS;
expiryHours = Math.max(MIN_EXPIRY_HOURS, Math.min(MAX_EXPIRY_HOURS, expiryHours));
const message = String(body?.message || '').trim().slice(0, 280) || null;
const theme = THEMES.has(String(body?.theme || '').trim()) ? String(body.theme).trim() : 'default';
const senderLabel = String(body?.senderLabel || '').trim().slice(0, 40) || null;
const reclaimAddress = String(body?.reclaimAddress || '').trim();
if (reclaimAddress && !BASE58_RE.test(reclaimAddress)) throw bad('reclaimAddress must be a Base58 Solana address');
const senderTag = sanitizeTag(body?.senderTag);
const irlPinId = String(body?.irlPinId || '').trim().slice(0, 64) || null;
const roomId = String(body?.roomId || '').trim().slice(0, 64) || null;
return {
asset, amount, atomics, sealMode, recipientPubKey,
prefix, suffix, ignoreCase, format, strength,
expiryHours, message, theme, senderLabel, reclaimAddress: reclaimAddress || null,
senderTag, irlPinId, roomId,
};
}
// Every public path reads drops through here. A pending or voided record is a
// create that never completed (its fee never settled), so it is not a drop at
// all: it answers 404 exactly like an id that was never minted, and its sealed
// envelope stays unreachable.
async function getLiveDropRecord(id) {
const record = await getDropRecord(id);
return isTransientDrop(record) ? null : record;
}
function sanitizeTag(raw) {
const s = String(raw || '').trim();
if (!s) return null;
return s.replace(/[^A-Za-z0-9_.:-]/g, '').slice(0, 64) || null;
}
// Grind (or generate) the drop wallet. Returns { address, secretBundle, vanity }.
// secretBundle is the JSON that gets BOTH sealed (for delivery) and encrypted at
// rest (for reclaim). The plaintext never leaves this function.
function generateDropWallet({ prefix, suffix, ignoreCase, format, strength }) {
const wantsVanity = prefix || suffix;
if (format === 'mnemonic') {
const r = grindVanityMnemonic({ prefix, suffix, ignoreCase, strength, timeBudgetMs: 45_000 });
return {
address: r.publicKey,
vanity: wantsVanity ? { prefix: prefix || null, suffix: suffix || null, ignoreCase } : null,
secretBundle: {
format: 'mnemonic',
mnemonic: r.mnemonic,
wordCount: r.wordCount,
derivationPath: r.derivationPath,
secretKeyBase58: bs58.encode(r.secretKey),
secretKey: Array.from(r.secretKey),
},
secretKeyBytes: r.secretKey,
};
}
if (wantsVanity) {
const r = grindVanityNode({ prefix, suffix, ignoreCase, timeBudgetMs: 45_000 });
return {
address: r.publicKey,
vanity: { prefix: prefix || null, suffix: suffix || null, ignoreCase },
secretBundle: { format: 'keypair', secretKeyBase58: bs58.encode(r.secretKey), secretKey: Array.from(r.secretKey) },
secretKeyBytes: r.secretKey,
};
}
// No vanity pattern → a plain fresh keypair (free of grind time).
const kp = Keypair.generate();
return {
address: kp.publicKey.toBase58(),
vanity: null,
secretBundle: { format: 'keypair', secretKeyBase58: bs58.encode(kp.secretKey), secretKey: Array.from(kp.secretKey) },
secretKeyBytes: kp.secretKey,
};
}
// Undo a create whose fee failed to settle after the drop wallet was already
// funded on-chain: sweep the funds back to the wallet that sent them, then void
// the record so it can never be claimed, revealed, or swept as a live drop.
// Returns a sentence to append to the caller's error, so the requester learns
// what happened to the money either way. Never throws: the void is what makes the
// drop unclaimable, and it must happen even when the sweep does not.
async function rollbackFunding({ record, secretKey, reason }) {
const back = fundingWalletAddress();
let note = '';
if (back) {
try {
await sweepReclaim({ record: { ...record, status: 'reclaimed' }, dropSecretKey: secretKey, toAddress: back });
note = ' and its funding was returned';
} catch (sweepErr) {
console.error('[vanity/drops] rollback sweep failed', record.id, sweepErr?.message || sweepErr);
note = ` (funding sweep failed: ${sweepErr?.message || 'unknown error'}; drop ${record.id} is voided and its funds are recoverable by the operator)`;
}
}
await voidDrop({ id: record.id, reason }).catch(() => {});
return note;
}
// ── POST: create (x402-paid → grind → seal → fund → persist) ─────────────────
async function handleCreate(req, res) {
let body;
try {
body = await readJson(req);
} catch (err) {
return error(res, err.status || 400, 'validation_error', err.message || 'invalid JSON body');
}
let parsed;
try {
parsed = parseCreate(body);
} catch (err) {
return error(res, err.status || 400, err.code || 'validation_error', err.message);
}
// Without a funding wallet the platform can't fund or reclaim — refuse before
// charging the create fee.
if (!fundingConfigured()) {
return error(res, 503, 'funding_unconfigured', 'the drop funding wallet is not configured — drops are temporarily unavailable');
}
const resourceUrl = resolveResourceUrl(req, ROUTE);
const requirements = buildRequirements(resourceUrl, CREATE_FEE_ATOMICS);
if (!requirements.length) {
return error(res, 503, 'payment_unconfigured', 'no x402 network is configured (X402_PAY_TO_*)');
}
const service = withService({
serviceName: 'three.ws Sealed Wallet Drops',
tags: ['solana', 'vanity', 'gift', 'sealed', 'e2e', 'x402', 'drop'],
});
const challenge = {
resourceUrl,
accepts: requirements,
description: CREATE_DESCRIPTION,
bazaar: CREATE_BAZAAR,
extensions: { [PAYMENT_IDENTIFIER]: paymentIdentifierExtension(false) },
serviceName: service.serviceName,
tags: service.tags,
iconUrl: service.iconUrl,
};
const paymentHeader = req.headers['x-payment'] || req.headers['payment-signature'];
if (!paymentHeader) return await send402(res, challenge);
// Only requests carrying a payment proof reach the facilitator /verify round-trip,
// so gate exactly here with the shared critical x402-verify limiters (per-IP +
// global) — the same amplification protection paidEndpoint() applies, which this
// hand-rolled handler would otherwise skip.
const vIp = await limits.x402VerifyIp(clientIp(req));
if (!vIp.success) return rateLimited(res, vIp);
const vGlobal = await limits.x402VerifyGlobal();
if (!vGlobal.success) return rateLimited(res, vGlobal);
// Idempotency: a retried create with the same payment proof returns the same
// stored drop instead of grinding + funding twice.
const clientPaymentId = extractIdFromHeader(paymentHeader);
const payloadHash = hashRequestPayload({ method: 'POST', url: req.url, body: JSON.stringify(body) });
const paymentHash = hashPaymentProof(paymentHeader);
const paymentId = clientPaymentId || (paymentHash ? `proof:${paymentHash}` : null);
if (paymentId) {
const lookup = await checkCache({ route: ROUTE, paymentId, payloadHash, paymentHash });
if (lookup.kind === 'hit') return writeCachedResponse(res, lookup.entry);
if (lookup.kind === 'conflict') {
return writeConflict(res, { route: ROUTE, attemptedHash: lookup.attemptedHash, existingHash: lookup.existingHash, reason: lookup.reason });
}
}
let verified;
try {
verified = await verifyPayment({ paymentHeader, requirements });
} catch (err) {
if (err.status === 402) return await send402(res, { ...challenge, error: err.message });
return error(res, err.status || 502, err.code || 'verify_failed', err.message);
}
// Grind + seal + fund AFTER verify but BEFORE settle, so any failure (bad
// pattern, RPC outage, insufficient funding balance) aborts with the fee
// unsettled — the buyer is never charged for a drop that didn't get funded.
let wallet;
try {
wallet = generateDropWallet(parsed);
} catch (err) {
return error(res, err.status || 500, err.code || 'grind_failed', err.message);
}
// Seal the secret bundle for delivery (operator-blind).
// • direct mode: seal to the recipient's known X25519 public key.
// • claim-time mode: generate a throwaway claim keypair, seal to its PUBLIC
// key, hand the SECRET back to the creator exactly once (it goes into the
// link fragment #k=…, never stored). The server then derives + stores only
// the one-way claimTokenHash from that secret and discards the secret, so
// it can verify a claimant's possession without being able to open the
// wallet. (A client-sent claimTokenHash is ignored in this mode — the
// claim key is server-generated, so the canonical hash is the server's.)
let sealRecipientPub;
let claimSecretForSender = null; // returned ONCE to the creator in claim-time mode
if (parsed.sealMode === 'direct') {
sealRecipientPub = parsed.recipientPubKey;
} else {
const claimSecret = nobleRandomBytes(32);
const { x25519 } = await import('@noble/curves/ed25519.js');
sealRecipientPub = bs58.encode(x25519.getPublicKey(claimSecret));
claimSecretForSender = bs58.encode(claimSecret);
parsed._claimSecretBytes = claimSecret;
}
let sealedSecret;
try {
sealedSecret = await sealToRecipient(JSON.stringify(wallet.secretBundle), sealRecipientPub);
} catch (err) {
return error(res, err.status || 500, err.code || 'seal_failed', err.message);
}
// Encrypt the SAME plaintext at rest ONLY for the reclaim-sweep path (so the
// platform can refund an expired, unclaimed drop). This never weakens the
// recipient's E2E guarantee — the claim path always delivers the sealed
// envelope the recipient opens with their own key.
let encryptedAtRest;
try {
encryptedAtRest = await encryptSecret(JSON.stringify(wallet.secretBundle));
} catch (err) {
return error(res, err.status || 500, err.code || 'encrypt_failed', err.message);
}
// Derive the drop id + (claim-time) the canonical claim token hash.
const nonce = bytesToHex(nobleRandomBytes(16));
const id = deriveDropId({ address: wallet.address, nonce, sealMode: parsed.sealMode });
let storedClaimTokenHash = null;
if (parsed.sealMode === 'claim-time') {
const { deriveClaimToken } = await import('../../src/solana/vanity/drop-protocol.js');
const claimToken = deriveClaimToken(id, parsed._claimSecretBytes);
storedClaimTokenHash = hashClaimToken(claimToken);
// Wipe the claim secret from our memory now that the hash + sealed envelope
// exist; only the creator (in the response) retains it.
parsed._claimSecretBytes.fill(0);
}
// Fund the drop wallet on-chain. Confirmed before we persist a claimable record.
let funding;
try {
funding = await fundDropAddress({ toAddress: wallet.address, asset: parsed.asset, atomics: parsed.atomics });
} catch (err) {
return error(res, err.status || 502, err.code || 'funding_failed', `on-chain funding failed: ${err.message}`);
}
const now = Date.now();
const record = {
id,
protocol: DROP_PROTOCOL_VERSION,
address: wallet.address,
vanity: wallet.vanity,
asset: parsed.asset,
amount: parsed.amount,
amountAtomics: parsed.atomics.toString(),
network: 'solana',
sealMode: parsed.sealMode,
recipient: parsed.sealMode === 'direct' ? parsed.recipientPubKey : null,
claimTokenHash: storedClaimTokenHash, // claim-time only; one-way
sealedSecret, // ECIES envelope — opaque, addressed to recipient/claim key
encryptedAtRest, // AES-256-GCM ciphertext for the reclaim sweep ONLY
message: parsed.message,
theme: parsed.theme,
senderLabel: parsed.senderLabel,
reclaimAddress: parsed.reclaimAddress,
senderTag: parsed.senderTag,
irlPinId: parsed.irlPinId,
roomId: parsed.roomId,
fundingTx: funding.fundingTx,
fundingConfirmed: true,
escrowPayer: verified.payer || null,
createdAt: now,
expiresAt: now + parsed.expiryHours * 3600_000,
// Persisted as pending: recorded and id-reserved, but in no index and
// refused by claim/reveal/reclaim until the create fee actually settles.
// Otherwise a settle failure would leave a real, platform-funded wallet that
// a direct-mode recipient could still reveal and drain for free.
status: 'escrow_pending',
};
try {
await createDrop(record);
} catch (err) {
return error(res, err.status || 500, err.code || 'store_failed', err.message);
}
let settled;
try {
settled = await settlePayment({ verified });
} catch (err) {
// The fee never landed, but the drop wallet is already funded on-chain. Undo
// that: sweep the funds back to the wallet they came from (we still hold the
// freshly-ground key in memory) and void the record.
const rollback = await rollbackFunding({ record, secretKey: wallet.secretKeyBytes, reason: `create fee settle failed: ${err.message}` });
return error(res, err.status || 502, err.code || 'settle_failed', `${err.message}. No drop was created${rollback}`);
}
// Fee collected: publish the drop (status funded + indexed) in one step.
const activation = await activateDrop({ id, escrowTx: settled.transaction }).catch(() => 'error');
if (activation !== 'live') {
return error(res, 502, 'activation_failed', `your create fee settled (tx ${settled.transaction || 'unknown'}) but the drop could not be published; contact support with drop id ${id}`, {
dropId: id,
escrowTx: settled.transaction || null,
});
}
const claimUrl = `${PUBLIC_ORIGIN}/drop/${id}`;
const body200 = JSON.stringify({
created: true,
drop: await getDrop(id),
funding: {
confirmed: true,
tx: funding.fundingTx,
explorerUrl: `https://solscan.io/tx/${funding.fundingTx}`,
},
// In claim-time mode this is the bearer secret the creator embeds in the
// link fragment (#k=…). Returned ONCE; the server discards it. In direct
// mode it is null (the recipient already holds their private key).
claimSecret: claimSecretForSender,
claimUrl: claimSecretForSender ? `${claimUrl}#k=${claimSecretForSender}` : claimUrl,
shareUrl: claimUrl,
qrUrl: `${PUBLIC_ORIGIN}/api/vanity/drops?view=qr&id=${id}`,
ogUrl: `${PUBLIC_ORIGIN}/api/og/sealed-drop?id=${id}`,
escrow: { funded: true, txHash: settled.transaction || null, payer: settled.payer || verified.payer || null },
notice: claimSecretForSender
? 'The claim link contains the ONLY key that opens this wallet. Share the full link (with #k=…) with the recipient. Anyone who has the full link can claim it once.'
: 'Sealed to the recipient X25519 key. Only they can open it — three.ws cannot.',
});
const contentType = 'application/json; charset=utf-8';
res.setHeader('x-payment-response', encodePaymentResponseHeader(settled));
res.setHeader('cache-control', 'no-store');
res.setHeader('content-type', contentType);
res.statusCode = 201;
res.end(body200);
if (paymentId) {
await storeResponse({ route: ROUTE, paymentId, payloadHash, paymentHash, status: 201, body: body200, contentType, paymentResponseHeader: encodePaymentResponseHeader(settled) });
}
}
// ── POST: claim (present claim token → atomic claim → release sealed envelope) ─
async function handleClaim(req, res) {
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
let body;
try {
body = await readJson(req);
} catch (err) {
return error(res, err.status || 400, 'validation_error', err.message || 'invalid JSON body');
}
const id = String(body?.id || '').trim();
if (!isValidDropId(id)) return error(res, 400, 'validation_error', 'id must be a 24-char hex drop id');
const record = await getLiveDropRecord(id);
if (!record) return error(res, 404, 'not_found', 'no drop with that id');
if (record.status !== 'funded') {
return json(res, 409, {
claimed: false,
status: record.status,
reason: record.status === 'claimed' ? 'this drop was already claimed' : `this drop is ${record.status}`,
});
}
if (record.expiresAt && Date.now() > record.expiresAt) {
return json(res, 409, { claimed: false, status: 'expired', reason: 'this drop expired before it was claimed — the sender can reclaim it' });
}
// Authorize the claim.
let claimerTag;
if (record.sealMode === 'claim-time') {
const claimToken = String(body?.claimToken || '').trim().toLowerCase();
if (!/^[0-9a-f]{64}$/.test(claimToken)) {
return error(res, 400, 'claim_token_required', 'claimToken (64-char hex) is required to claim this bearer drop');
}
const presentedHash = hashClaimToken(claimToken);
if (!timingSafeHexEqual(presentedHash, record.claimTokenHash || '')) {
return error(res, 403, 'wrong_claim_token', 'this claim token does not match the drop — you need the original claim link');
}
// The claimerTag dedups idempotent retries of the SAME winning claim.
claimerTag = presentedHash;
} else {
// direct mode: anyone may fetch the envelope; it's useless without the
// recipient's private key. The claim simply marks the gift "opened". The
// claimerTag is a constant so an idempotent re-claim returns the envelope.
claimerTag = 'direct';
}
const claimRecipient = String(body?.claimRecipientPubKey || '').trim().slice(0, 64) || '';
// Atomic single-claim CAS.
let outcome;
try {
outcome = await claimDrop({ id, claimerTag, claimRecipient });
} catch (err) {
return error(res, err.status || 500, err.code || 'claim_failed', err.message);
}
if (outcome === 'missing') return error(res, 404, 'not_found', 'drop disappeared during claim');
if (outcome === 'closed') {
const fresh = await getDrop(id);
return json(res, 409, { claimed: false, status: fresh?.status || 'closed', reason: 'drop closed/expired during claim' });
}
if (outcome === 'lost') {
return json(res, 409, { claimed: false, status: 'claimed', reason: 'this drop was already claimed by someone else' });
}
// outcome === 'won' (first claim, or an idempotent re-claim with the same
// token). Release the SEALED envelope for client-side opening. The plaintext
// secret NEVER appears here — only the ECIES ciphertext.
if (claimRecipient) {
await recordClaimDelivery({ id, claimRecipient }).catch(() => {});
}
const fresh = await getDrop(id);
return json(res, 200, {
claimed: true,
status: 'claimed',
id,
address: record.address,
asset: record.asset,
amount: record.amount,
sealMode: record.sealMode,
recipient: record.recipient || null,
sealedSecret: record.sealedSecret,
sealedScheme: SEALED_ENVELOPE_SCHEME,
message: record.message || null,
theme: record.theme || 'default',
senderLabel: record.senderLabel || null,
explorerUrl: `https://solscan.io/account/${record.address}`,
drop: fresh,
notice: record.sealMode === 'claim-time'
? 'Open this envelope in your browser with the claim key from your link (#k=…). three.ws never saw that key.'
: 'Open this envelope in your browser with your X25519 private key. three.ws never held it.',
}, { 'cache-control': 'no-store' });
}
// ── POST: reveal (direct-seal: fetch the sealed envelope without claiming) ────
async function handleReveal(req, res) {
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
let body;
try {
body = await readJson(req);
} catch (err) {
return error(res, err.status || 400, 'validation_error', err.message || 'invalid JSON body');
}
const id = String(body?.id || '').trim();
if (!isValidDropId(id)) return error(res, 400, 'validation_error', 'id must be a 24-char hex drop id');
const record = await getLiveDropRecord(id);
if (!record) return error(res, 404, 'not_found', 'no drop with that id');
if (record.sealMode !== 'direct') {
return error(res, 409, 'wrong_mode', 'reveal is for direct-seal drops; bearer drops claim with their claim token');
}
// The envelope is ECIES ciphertext addressed to record.recipient — returning
// it leaks nothing without the recipient's private key. The open is client-side.
return json(res, 200, {
revealed: true,
id,
address: record.address,
asset: record.asset,
amount: record.amount,
recipient: record.recipient,
sealedSecret: record.sealedSecret,
sealedScheme: SEALED_ENVELOPE_SCHEME,
message: record.message || null,
theme: record.theme || 'default',
senderLabel: record.senderLabel || null,
status: record.status,
explorerUrl: `https://solscan.io/account/${record.address}`,
notice: 'Open this envelope client-side with your X25519 private key (openSealed). three.ws cannot — it never held your key.',
}, { 'cache-control': 'no-store' });
}
// ── POST: reclaim (sender sweeps an expired, unclaimed drop on-chain) ──────────
async function handleReclaim(req, res) {
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
let body;
try {
body = await readJson(req);
} catch (err) {
return error(res, err.status || 400, 'validation_error', err.message || 'invalid JSON body');
}
const id = String(body?.id || '').trim();
if (!isValidDropId(id)) return error(res, 400, 'validation_error', 'id must be a 24-char hex drop id');
const record = await getLiveDropRecord(id);
if (!record) return error(res, 404, 'not_found', 'no drop with that id');
// Atomic funded→reclaimed CAS, only for EXPIRED drops. Mutually exclusive with
// claim — a claimed drop can never be reclaimed.
const eligibility = await markReclaimable(id);
if (eligibility === 'missing') return error(res, 404, 'not_found', 'drop disappeared');
if (eligibility === 'ineligible') {
const fresh = await getDrop(id);
const why = fresh?.status === 'claimed'
? 'this drop was already claimed — nothing to reclaim'
: 'this drop has not expired yet';
return json(res, 409, { reclaimed: false, status: fresh?.status, reason: why });
}
// Reclaim destination is BOUND to the address recorded when the drop was
// created — never a value supplied in this (unauthenticated) request. A drop id
// leaks through share links / OG cards, so trusting a body-supplied address
// would let anyone who sees an id sweep the funded drop wallet to themselves.
const refundTo = record.reclaimAddress;
if (!refundTo || !BASE58_RE.test(refundTo)) {
return error(res, 409, 'no_reclaim_address', 'this drop was created without a reclaim address; a self-service reclaim requires one set at create time');
}
// Reconstruct the drop wallet's key from the at-rest ciphertext ONLY to sign
// the sweep. Never returned, never logged.
let dropSecretKey;
try {
const bundle = JSON.parse(await decryptSecret(record.encryptedAtRest));
dropSecretKey = Uint8Array.from(bundle.secretKey);
} catch (err) {
return error(res, 500, 'reclaim_key_error', 'could not reconstruct the drop key for the sweep');
}
let sweep;
try {
sweep = await sweepReclaim({ record: { ...record, status: 'reclaimed' }, dropSecretKey, toAddress: refundTo });
} catch (err) {
return json(res, 502, { reclaimed: false, status: 'reclaimed', reason: `reclaim sweep failed: ${err.message}. Retry to complete the reclaim.`, retryable: true });
} finally {
dropSecretKey?.fill?.(0);
}
return json(res, 200, {
reclaimed: true,
id,
asset: record.asset,
amount: record.amount,
reclaimTx: sweep.reclaimTx,
alreadyReclaimed: sweep.alreadyReclaimed,
reclaimAddress: refundTo,
explorerUrl: sweep.reclaimTx === 'empty' ? null : `https://solscan.io/tx/${sweep.reclaimTx}`,
notice: sweep.reclaimTx === 'empty' ? 'The drop wallet was already empty; nothing to sweep.' : 'Funds swept back to your reclaim address.',
}, { 'cache-control': 'no-store' });
}
// ── GET handlers ──────────────────────────────────────────────────────────────
async function handleGet(req, res, url) {
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const view = (url.searchParams.get('view') || 'config').toLowerCase();
if (view === 'config') {
return json(res, 200, {
fundingConfigured: fundingConfigured(),
assets: ['SOL', 'USDC', 'THREE'],
networks: activeNetworks(),
createFeeAtomics: CREATE_FEE_ATOMICS,
createFeeUsd: (CREATE_FEE_ATOMICS / 1e6).toFixed(2),
expiry: { minHours: MIN_EXPIRY_HOURS, maxHours: MAX_EXPIRY_HOURS, defaultHours: DEFAULT_EXPIRY_HOURS },
themes: [...THEMES],
sealModes: SEAL_MODES,
protocol: DROP_PROTOCOL_VERSION,
sealedScheme: SEALED_ENVELOPE_SCHEME,
}, { 'cache-control': READ_CACHE });
}
if (view === 'get') {
const id = (url.searchParams.get('id') || '').trim();
if (!isValidDropId(id)) return error(res, 400, 'validation_error', 'id must be a 24-char hex drop id');
const record = await getLiveDropRecord(id);
if (!record) return error(res, 404, 'not_found', 'no drop with that id');
// Public view + a claimable flag so the page knows which path to render,
// WITHOUT exposing the envelope or token hash.
const pub = await getDrop(id);
const expired = record.expiresAt && Date.now() > record.expiresAt && record.status === 'funded';
return json(res, 200, {
drop: pub,
claimable: record.status === 'funded' && !expired,
expired,
sealMode: record.sealMode,
}, { 'cache-control': 'no-store' });
}
if (view === 'balance') {
const id = (url.searchParams.get('id') || '').trim();
if (!isValidDropId(id)) return error(res, 400, 'validation_error', 'id must be a 24-char hex drop id');
const record = await getLiveDropRecord(id);
if (!record) return error(res, 404, 'not_found', 'no drop with that id');
const { atomics } = await readDropBalance({ address: record.address, asset: record.asset });
return json(res, 200, {
id,
address: record.address,
asset: record.asset,
atomics,
amount: atomics != null ? atomicsToAmount(atomics, record.asset) : null,
explorerUrl: `https://solscan.io/account/${record.address}`,
}, { 'cache-control': 'no-store' });
}
if (view === 'stats') {
return json(res, 200, await dropStats(), { 'cache-control': READ_CACHE });
}
if (view === 'mine') {
const tag = sanitizeTag(url.searchParams.get('senderTag'));
if (!tag) return error(res, 400, 'validation_error', 'senderTag is required');
const drops = await listBySender(tag, Number(url.searchParams.get('limit')) || 50);
return json(res, 200, { drops, count: drops.length }, { 'cache-control': 'no-store' });
}
if (view === 'qr') {
const id = (url.searchParams.get('id') || '').trim();
if (!isValidDropId(id)) return error(res, 400, 'validation_error', 'id must be a 24-char hex drop id');
const record = await getLiveDropRecord(id);
if (!record) return error(res, 404, 'not_found', 'no drop with that id');
// The QR encodes the share URL (no fragment — the fragment claim key never
// goes server-side, so the QR shown server-side is the share landing only;
// the page re-renders a QR WITH the fragment client-side for the holder).
const target = `${PUBLIC_ORIGIN}/drop/${id}`;
try {
const QRCode = (await import('qrcode')).default;
const svg = await QRCode.toString(target, { type: 'svg', margin: 1, width: 320, color: { dark: '#000000', light: '#ffffff' } });
res.setHeader('content-type', 'image/svg+xml; charset=utf-8');
res.setHeader('cache-control', 'public, max-age=3600, s-maxage=86400');
res.statusCode = 200;
return res.end(svg);
} catch (err) {
return error(res, 500, 'qr_failed', 'could not render QR');
}
}
return error(res, 400, 'unknown_view', 'view must be config, get, balance, stats, mine, or qr');
}
// ── dispatch ──────────────────────────────────────────────────────────────────
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
const url = new URL(req.url, `http://${req.headers.host || 'three.ws'}`);
if (req.method === 'GET') return handleGet(req, res, url);
if (req.method === 'POST') {
const action = (url.searchParams.get('action') || 'create').toLowerCase();
if (action === 'create') return handleCreate(req, res);
if (action === 'claim') return handleClaim(req, res);
if (action === 'reveal') return handleReveal(req, res);
if (action === 'reclaim') return handleReclaim(req, res);
return error(res, 400, 'unknown_action', 'action must be create, claim, reveal, or reclaim');
}
res.setHeader('allow', 'GET, POST, OPTIONS');
return error(res, 405, 'method_not_allowed', 'use GET or POST');
});