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
// Fulfillment webhooks: authenticity first, then idempotency, then ordering.
//
// Every serious fulfillment provider retries deliveries. A replayed webhook
// that appends a second timeline row, or drives the state machine a second
// time, turns an ordinary retry into a corrupted order. The ledger insert on
// print_webhook_deliveries is the lock that prevents it, and this file pins
// the three properties the endpoint depends on:
//
// 1. An unverified delivery is refused BEFORE the body is parsed.
// 2. The claim happens before the payload is interpreted, so even a delivery
// we end up not applying is recorded and cannot be replayed.
// 3. A duplicate answers 200 (a 4xx makes a provider retry forever) and
// applies nothing.
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { createHmac } from 'node:crypto';
const SECRET = 'test-hmac-secret-not-a-real-credential';
// A ledger with the real unique constraint, so "claimed twice" behaves the way
// Postgres does rather than the way a stub might.
const ledger = new Set();
const claimWebhookDelivery = vi.fn(async ({ provider, deliveryId }) => {
const key = `${provider}:${deliveryId}`;
if (ledger.has(key)) return { fresh: false };
ledger.add(key);
return { fresh: true };
});
const markWebhookApplied = vi.fn(async () => {});
const releaseWebhookDelivery = vi.fn(async ({ provider, deliveryId }) => {
ledger.delete(`${provider}:${deliveryId}`);
});
const getOrderByProviderId = vi.fn(async () => ORDER);
vi.mock('../api/_lib/print/fulfillment-queries.js', () => ({
claimWebhookDelivery,
markWebhookApplied,
releaseWebhookDelivery,
getOrderByProviderId,
printStoreEnabled: () => true,
ADAPTER_DRIVABLE_STATUSES: ['submitted', 'printing', 'quality_check', 'shipped', 'delivered', 'canceled', 'rejected'],
OPEN_PROVIDER_STATUSES: ['submitted', 'printing', 'quality_check', 'shipped'],
}));
// The timeline the endpoint is not allowed to duplicate.
const timeline = [];
const applyProviderEvent = vi.fn(async ({ order, event }) => {
timeline.push({ status: event.status, note: event.note });
return { applied: true, order: { ...order, status: event.status }, reason: '' };
});
vi.mock('../api/_lib/print/fulfillment.js', () => ({
applyProviderEvent,
submitOrder: vi.fn(),
reconcileOrder: vi.fn(),
cancelWithProvider: vi.fn(),
FulfillmentError: class FulfillmentError extends Error {},
}));
const ORDER = {
id: '00000000-0000-4000-8000-000000000002',
status: 'printing',
provider: 'partner-cn',
provider_order_id: 'p-42',
};
const handler = (await import('../api/print/webhook/[provider].js')).default;
function mockRes() {
return {
statusCode: 200,
_headers: {},
_body: '',
setHeader(k, v) { this._headers[k.toLowerCase()] = v; },
getHeader(k) { return this._headers[k.toLowerCase()]; },
end(b) { this._body = b || ''; },
get headersSent() { return false; },
get writableEnded() { return false; },
get json() { try { return JSON.parse(this._body); } catch { return null; } },
};
}
const sign = (body, secret = SECRET) => createHmac('sha256', secret).update(body, 'utf8').digest('hex');
async function deliver(body, { provider = 'partner-cn', headers = {}, signed = true } = {}) {
const raw = typeof body === 'string' ? body : JSON.stringify(body);
const res = mockRes();
await handler(
{
method: 'POST',
url: `/api/print/webhook/${provider}`,
query: { provider },
headers: {
host: 'three.ws',
'content-type': 'application/json',
...(signed ? { 'x-print-signature': `sha256=${sign(raw)}` } : {}),
...headers,
},
rawBody: Buffer.from(raw),
},
res,
);
return res;
}
beforeEach(() => {
vi.clearAllMocks();
ledger.clear();
timeline.length = 0;
process.env.PRINT_PARTNER_CN_URL = 'https://partner.invalid/api';
process.env.PRINT_PARTNER_CN_KEY = SECRET;
getOrderByProviderId.mockResolvedValue(ORDER);
});
describe('a replayed delivery is applied exactly once', () => {
const PAYLOAD = { id: 'p-42', state: 'shipped', tracking_number: '1Z999', carrier: 'UPS' };
it('applies the first delivery and appends one timeline entry', async () => {
const res = await deliver(PAYLOAD);
expect(res.statusCode).toBe(200);
expect(res.json).toMatchObject({ ok: true, applied: true, status: 'shipped' });
expect(timeline).toHaveLength(1);
});
it('answers 200 duplicate on the replay and appends nothing', async () => {
await deliver(PAYLOAD);
const replay = await deliver(PAYLOAD);
expect(replay.statusCode).toBe(200);
expect(replay.json).toMatchObject({ ok: true, duplicate: true, applied: false });
expect(applyProviderEvent).toHaveBeenCalledTimes(1);
expect(timeline).toHaveLength(1);
});
it('stays at one even after five retries', async () => {
for (let i = 0; i < 5; i += 1) await deliver(PAYLOAD);
expect(timeline).toHaveLength(1);
});
it('treats a genuinely different event as a new delivery', async () => {
await deliver(PAYLOAD);
await deliver({ ...PAYLOAD, state: 'delivered' });
expect(timeline.map((e) => e.status)).toEqual(['shipped', 'delivered']);
});
it('honours the provider delivery id over the payload hash when they send one', async () => {
// Same delivery id, different body: their id is authoritative, so this is
// still one event.
await deliver(PAYLOAD, { headers: { 'x-print-delivery': 'dlv_7' } });
const replay = await deliver({ ...PAYLOAD, note: 'resent with a note' }, { headers: { 'x-print-delivery': 'dlv_7' } });
expect(replay.json.duplicate).toBe(true);
expect(timeline).toHaveLength(1);
});
});
describe('a failed apply releases the claim so the provider retry re-runs it', () => {
it('applies on the retry after the first apply threw', async () => {
const PAYLOAD = { id: 'p-42', state: 'shipped' };
applyProviderEvent.mockRejectedValueOnce(new Error('db write failed'));
const first = await deliver(PAYLOAD, { headers: { 'x-print-delivery': 'dlv_9' } });
expect(first.statusCode).toBeGreaterThanOrEqual(500);
const retry = await deliver(PAYLOAD, { headers: { 'x-print-delivery': 'dlv_9' } });
expect(retry.statusCode).toBe(200);
expect(retry.json.duplicate).toBeUndefined();
expect(retry.json.applied).toBe(true);
expect(timeline).toHaveLength(1);
});
});
describe('the unsigned delivery header cannot launder a replay', () => {
it('treats a signed body replayed under a fresh x-print-delivery as a duplicate', async () => {
const PAYLOAD = { id: 'p-42', state: 'shipped' };
await deliver(PAYLOAD, { headers: { 'x-print-delivery': 'dlv_1' } });
const replay = await deliver(PAYLOAD, { headers: { 'x-print-delivery': 'dlv_attacker_2' } });
expect(replay.json.duplicate).toBe(true);
expect(timeline).toHaveLength(1);
});
});
describe('authenticity is settled before anything else happens', () => {
it('refuses an unsigned delivery with 401', async () => {
const res = await deliver({ id: 'p-42', state: 'shipped' }, { signed: false });
expect(res.statusCode).toBe(401);
});
it('refuses a forged signature and never claims a ledger row', async () => {
const res = await deliver({ id: 'p-42', state: 'shipped' }, { headers: { 'x-print-signature': 'sha256=deadbeef' } });
expect(res.statusCode).toBe(401);
expect(claimWebhookDelivery).not.toHaveBeenCalled();
expect(applyProviderEvent).not.toHaveBeenCalled();
});
it('refuses a body altered in flight', async () => {
const raw = JSON.stringify({ id: 'p-42', state: 'printing' });
const res = mockRes();
await handler(
{
method: 'POST',
url: '/api/print/webhook/partner-cn',
query: { provider: 'partner-cn' },
headers: { host: 'three.ws', 'content-type': 'application/json', 'x-print-signature': sign(raw) },
rawBody: Buffer.from(raw.replace('printing', 'shipped!')),
},
res,
);
expect(res.statusCode).toBe(401);
});
it('404s a provider with no configured adapter, offering nothing to probe', async () => {
const res = await deliver({ id: 'x' }, { provider: 'not-a-lane' });
expect(res.statusCode).toBe(404);
});
it('refuses a delivery to the manual lane, which has no webhook by design', async () => {
const res = await deliver({ id: 'x' }, { provider: 'manual' });
expect(res.statusCode).toBe(401);
expect(res.json.error_description).toMatch(/no webhook/);
});
it('rejects a non-POST', async () => {
const res = mockRes();
await handler({ method: 'GET', url: '/api/print/webhook/partner-cn', query: { provider: 'partner-cn' }, headers: {} }, res);
expect(res.statusCode).toBe(405);
});
});
describe('a verified delivery we cannot apply is still recorded', () => {
it('claims the delivery before parsing, so malformed JSON cannot be replayed', async () => {
const res = await deliver('{not json');
expect(res.statusCode).toBe(400);
expect(claimWebhookDelivery).toHaveBeenCalledTimes(1);
});
it('answers 200 for an unknown order so the provider stops retrying', async () => {
getOrderByProviderId.mockResolvedValue(null);
const res = await deliver({ id: 'p-does-not-exist', state: 'shipped' });
expect(res.statusCode).toBe(200);
expect(res.json).toMatchObject({ applied: false, reason: 'no matching order' });
});
it('reports applied:false when the state machine refuses the move', async () => {
applyProviderEvent.mockResolvedValue({ applied: false, order: ORDER, reason: 'a print order cannot go from printing to quoted' });
const res = await deliver({ id: 'p-42', state: 'shipped' });
expect(res.statusCode).toBe(200);
expect(res.json).toMatchObject({ applied: false, status: 'printing' });
expect(res.json.reason).toMatch(/cannot go from/);
});
it('makes a provider retry when the database is unavailable', async () => {
vi.resetModules();
vi.doMock('../api/_lib/print/fulfillment-queries.js', () => ({
claimWebhookDelivery,
markWebhookApplied,
getOrderByProviderId,
printStoreEnabled: () => false,
ADAPTER_DRIVABLE_STATUSES: ['shipped'],
OPEN_PROVIDER_STATUSES: ['shipped'],
}));
const fresh = (await import('../api/print/webhook/[provider].js')).default;
const raw = JSON.stringify({ id: 'p-42', state: 'shipped' });
const res = mockRes();
await fresh(
{
method: 'POST',
url: '/api/print/webhook/partner-cn',
query: { provider: 'partner-cn' },
headers: { host: 'three.ws', 'content-type': 'application/json', 'x-print-signature': sign(raw) },
rawBody: Buffer.from(raw),
},
res,
);
expect(res.statusCode).toBe(503);
});
});