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
// AWS Marketplace integration helpers.
//
// Covers the integration points for a SaaS listing under the Concurrent
// Agreements requirements AWS made mandatory for new products on 2026-06-01:
// 1. resolveCustomer : exchange a registration token for the buyer's
// LicenseArn + CustomerAWSAccountId
// 2. meterUsage : report consumption (BatchMeterUsage, keyed on
// LicenseArn) for a usage-priced listing
// 3. getEntitlements : check entitlements for a contract listing
// 4. verifySnsMessage : validate a legacy SNS lifecycle notification
// 5. parseMarketplaceEvent : normalize an EventBridge agreement/license event
// 6. verifyEventSecret : authenticate the EventBridge API destination
//
// Why both notification transports: AWS still documents the SNS subscription
// topic for existing integrations, but new products receive agreement and
// license lifecycle events on the seller account's default EventBridge bus
// instead, and SNS never carries a LicenseArn. The webhook accepts either
// envelope so the listing works whichever one AWS wires up for it.
import {
MarketplaceMeteringClient,
ResolveCustomerCommand,
MeterUsageCommand,
BatchMeterUsageCommand,
} from '@aws-sdk/client-marketplace-metering';
import {
MarketplaceEntitlementServiceClient,
GetEntitlementsCommand,
} from '@aws-sdk/client-marketplace-entitlement-service';
import { createVerify, createPublicKey, timingSafeEqual } from 'node:crypto';
import { env } from './env.js';
import { fetchUpstream } from './upstream-fetch.js';
function credentials() {
return {
accessKeyId: env.AWS_MP_ACCESS_KEY_ID,
secretAccessKey: env.AWS_MP_SECRET_ACCESS_KEY,
};
}
function meteringClient() {
return new MarketplaceMeteringClient({
region: env.AWS_MP_REGION,
credentials: credentials(),
});
}
function entitlementClient() {
return new MarketplaceEntitlementServiceClient({
region: env.AWS_MP_REGION,
credentials: credentials(),
});
}
/**
* Exchange the registration token (from the POST body of the registration URL)
* for the buyer's identity.
*
* For a NEW SaaS integration AWS leaves `CustomerIdentifier` empty and returns
* `LicenseArn` + `CustomerAWSAccountId` instead, so all four fields are surfaced
* and the caller keys on whichever it got. Our listing has never been created,
* which makes it a new integration by definition; the legacy field is carried
* only so a pre-existing row can still be matched.
*
* Returns { customerIdentifier, licenseArn, customerAWSAccountId, productCode }.
* Throws on an invalid or expired token.
*/
export async function resolveCustomer(registrationToken) {
const client = meteringClient();
const result = await client.send(
new ResolveCustomerCommand({ RegistrationToken: registrationToken }),
);
return {
customerIdentifier: result.CustomerIdentifier || null,
licenseArn: result.LicenseArn || null,
customerAWSAccountId: result.CustomerAWSAccountId || null,
productCode: result.ProductCode,
};
}
/**
* Report metered usage to AWS Marketplace for billing.
*
* New integrations meter through BatchMeterUsage with `LicenseArn` +
* `CustomerAWSAccountId` per record; `MeterUsage` with a `CustomerIdentifier` is
* the legacy shape and is only used when that is genuinely all we hold for the
* buyer. Returns the metering record id, or null when AWS accepted the batch
* without issuing one.
*
* @param {object} params
* @param {string} [params.licenseArn] from resolveCustomer (new integrations)
* @param {string} [params.customerAWSAccountId] from resolveCustomer (new integrations)
* @param {string} [params.customerIdentifier] legacy integrations only
* @param {string} params.dimension usage dimension defined in the seller portal
* @param {number} params.quantity units consumed
* @param {Date} [params.timestamp] defaults to now
*/
export async function meterUsage({
licenseArn,
customerAWSAccountId,
customerIdentifier,
dimension,
quantity,
timestamp,
}) {
const client = meteringClient();
const when = timestamp ?? new Date();
if (licenseArn || customerAWSAccountId) {
const result = await client.send(
new BatchMeterUsageCommand({
ProductCode: env.AWS_MP_PRODUCT_CODE,
UsageRecords: [
{
Timestamp: when,
Dimension: dimension,
Quantity: quantity,
...(licenseArn ? { LicenseArn: licenseArn } : {}),
...(customerAWSAccountId ? { CustomerAWSAccountId: customerAWSAccountId } : {}),
},
],
}),
);
const [record] = result.Results ?? [];
if (record && record.Status && record.Status !== 'Success') {
throw new Error(`BatchMeterUsage rejected the record: ${record.Status}`);
}
return record?.MeteringRecordId ?? null;
}
if (!customerIdentifier) {
throw new Error('meterUsage: need LicenseArn/CustomerAWSAccountId (new integrations) or CustomerIdentifier (legacy)');
}
const result = await client.send(
new MeterUsageCommand({
ProductCode: env.AWS_MP_PRODUCT_CODE,
UsageDimension: dimension,
UsageQuantity: quantity,
Timestamp: when,
CustomerIdentifier: customerIdentifier,
}),
);
return result.MeteringRecordId ?? null;
}
/**
* Check entitlements for a buyer (contract-based products).
*
* Filters on CUSTOMER_AWS_ACCOUNT_ID, which is the filter new integrations must
* use; CUSTOMER_IDENTIFIER remains only for a legacy row that has nothing else.
* Returns the list of entitlement objects.
*/
export async function getEntitlements({ customerAWSAccountId, customerIdentifier }) {
const filter = customerAWSAccountId
? { CUSTOMER_AWS_ACCOUNT_ID: [customerAWSAccountId] }
: { CUSTOMER_IDENTIFIER: [customerIdentifier] };
if (!customerAWSAccountId && !customerIdentifier) {
throw new Error('getEntitlements: need CustomerAWSAccountId or CustomerIdentifier');
}
const client = entitlementClient();
const result = await client.send(
new GetEntitlementsCommand({
ProductCode: env.AWS_MP_PRODUCT_CODE,
Filter: filter,
}),
);
return result.Entitlements ?? [];
}
/**
* True when the AWS Marketplace integration has the credentials + product code
* it needs to call AWS. Read directly from process.env so it never throws the
* way the `req()`-backed env getters do when unconfigured — that's what lets the
* whole path ship INERT (like the fee module) instead of erroring.
*/
export function awsMarketplaceConfigured() {
return Boolean(
process.env.AWS_MP_ACCESS_KEY_ID &&
process.env.AWS_MP_SECRET_ACCESS_KEY &&
process.env.AWS_MP_PRODUCT_CODE,
);
}
/**
* Resolve whether a customer is currently ENTITLED, via a real GetEntitlements
* call — filtering out expired entitlements. Inert (entitled:null) when AWS is
* not configured, so a deployment without AWS creds degrades open and never
* fakes an entitlement AWS didn't grant. Throttling / network errors surface as
* a typed, retryable error the caller turns into an actionable boundary state.
*
* @returns {Promise<{ configured: boolean, entitled: boolean|null, entitlements: object[] }>}
*/
export async function customerEntitlement({ customerAWSAccountId, customerIdentifier }) {
if (!awsMarketplaceConfigured()) return { configured: false, entitled: null, entitlements: [] };
if (!customerAWSAccountId && !customerIdentifier) {
return { configured: true, entitled: null, entitlements: [] };
}
try {
const entitlements = await getEntitlements({ customerAWSAccountId, customerIdentifier });
const now = Date.now();
const active = entitlements.filter(
(e) => !e.ExpirationDate || new Date(e.ExpirationDate).getTime() > now,
);
return { configured: true, entitled: active.length > 0, entitlements: active };
} catch (err) {
const e = new Error(`aws_entitlement_check_failed: ${err?.name || ''} ${err?.message || ''}`.trim());
e.code = 'aws_entitlement_unavailable';
e.retryable = err?.name === 'ThrottlingException' || err?.name === 'InternalServiceErrorException';
throw e;
}
}
// ── SNS signature verification ────────────────────────────────────────────────
// AWS signs every SNS message with a private key and includes the cert URL.
// We download the cert once (cached per URL), build the canonical string, and
// verify the signature so we know the notification genuinely came from AWS.
const certCache = new Map();
/**
* Assert that a URL taken from an SNS payload is an AWS-hosted HTTPS endpoint
* before anything dereferences it. Both places that follow such a URL (the
* signing certificate and the SubscribeURL handshake) go through this, so a
* payload can never steer an outbound request at a host of its choosing.
* Also turns a missing/garbage URL into this same refusal instead of a
* TypeError from the URL constructor.
*
* @param {unknown} value the URL as it appeared in the payload
* @param {string} label what the URL is, for the thrown message
* @returns {URL} the parsed, trusted URL
*/
export function assertAwsHttpsUrl(value, label) {
let parsed;
try {
parsed = new URL(String(value));
} catch {
throw new Error(`Untrusted ${label}: ${value}`);
}
// The SNS service endpoint itself, never any `*.amazonaws.com` host: that
// suffix also covers S3 buckets and API Gateway stages anyone can create,
// which let a forger host their own signing certificate (and so sign any
// message they liked) or bounce this request through a redirect.
if (parsed.protocol !== 'https:' || !SNS_HOST_RE.test(parsed.hostname) || parsed.username || parsed.password) {
throw new Error(`Untrusted ${label}: ${value}`);
}
return parsed;
}
const SNS_HOST_RE = /^sns\.[a-z0-9-]+\.amazonaws\.com(\.cn)?$/;
// AWS publishes every SNS signing certificate under this file name.
const SNS_CERT_PATH_RE = /^\/SimpleNotificationService-[A-Za-z0-9]+\.pem$/;
async function fetchCert(url) {
if (certCache.has(url)) return certCache.get(url);
// Only trust certificates served by the SNS endpoint itself, at AWS's
// certificate path, and never follow a redirect off it.
const parsed = assertAwsHttpsUrl(url, 'SNS signing cert URL');
if (!SNS_CERT_PATH_RE.test(parsed.pathname) || parsed.search) {
throw new Error(`Untrusted SNS signing cert URL: ${url}`);
}
// The PEM is cached per URL above, so this is paid once per cert rotation.
const res = await fetchUpstream(url, { redirect: 'error' }, { name: 'aws-sns-cert', timeoutMs: 8_000, attempts: 3, okWhen: () => true });
if (!res.ok) throw new Error(`Failed to fetch SNS cert: ${res.status}`);
const pem = await res.text();
certCache.set(url, pem);
return pem;
}
// Fields included in the signature string differ by message type.
const NOTIFICATION_FIELDS = ['Message', 'MessageId', 'Subject', 'Timestamp', 'TopicArn', 'Type'];
const SUBSCRIPTION_FIELDS = ['Message', 'MessageId', 'SubscribeURL', 'Timestamp', 'Token', 'TopicArn', 'Type'];
function buildSignatureString(msg) {
const fields =
msg.Type === 'Notification' ? NOTIFICATION_FIELDS : SUBSCRIPTION_FIELDS;
return fields
.filter((k) => msg[k] !== undefined)
.map((k) => `${k}\n${msg[k]}\n`)
.join('');
}
/**
* Verify that a parsed SNS message object was genuinely signed by AWS.
* Throws if verification fails; returns void on success.
*
* SignatureVersion selects the digest: version 1 topics sign with SHA1, and
* version 2 topics (which AWS now recommends, and which a topic can be switched
* to at any time) sign with SHA256. Hardcoding SHA1 rejects every message from
* a version 2 topic with a signature failure that reads like an attack.
*/
export async function verifySnsMessage(msg) {
const expectedTopicArn = env.AWS_MP_SNS_TOPIC_ARN;
if (expectedTopicArn && msg.TopicArn !== expectedTopicArn) {
throw new Error(`SNS TopicArn mismatch: got ${msg.TopicArn}`);
}
const digest = String(msg.SignatureVersion) === '2' ? 'SHA256' : 'SHA1';
const pem = await fetchCert(msg.SigningCertURL);
const pubKey = createPublicKey(pem);
const verifier = createVerify(digest);
verifier.update(buildSignatureString(msg));
const valid = verifier.verify(pubKey, msg.Signature, 'base64');
if (!valid) throw new Error('SNS signature verification failed');
}
// ── EventBridge agreement + license events ───────────────────────────────────
// New SaaS products receive lifecycle notifications as EventBridge events on the
// seller account's default bus, not on an SNS topic. EventBridge cannot call an
// external HTTPS endpoint directly, so a rule relays them through an API
// destination, whose connection attaches a shared secret header. That header is
// the only thing standing between this endpoint and an anonymous caller who
// wants to revoke a buyer's access, so an unset secret refuses delivery outright
// rather than trusting the payload.
export const AGREEMENT_EVENT_SOURCE = 'aws.agreement-marketplace';
/** Header the EventBridge API destination connection attaches. */
export const EVENT_SECRET_HEADER = 'x-three-ws-marketplace-secret';
/**
* Constant-time comparison of the request's shared secret against the configured
* one. Returns a reason string on failure, or null when the request is trusted.
*/
export function verifyEventSecret(req) {
const expected = env.AWS_MP_EVENT_SECRET;
if (!expected) return 'not_configured';
const presented = req.headers?.[EVENT_SECRET_HEADER];
if (typeof presented !== 'string' || presented.length === 0) return 'missing_secret';
const a = Buffer.from(presented, 'utf8');
const b = Buffer.from(expected, 'utf8');
if (a.length !== b.length) return 'bad_secret';
return timingSafeEqual(a, b) ? null : 'bad_secret';
}
/** True when the parsed body looks like an EventBridge envelope rather than SNS. */
export function isEventBridgeEnvelope(body) {
return Boolean(body && typeof body === 'object' && typeof body['detail-type'] === 'string' && body.source);
}
/**
* Normalize an AWS Marketplace EventBridge event into the fields the webhook
* acts on. Returns null for an event from another source.
*
* `kind` is one of:
* agreement-created a new/renewed/amended agreement; grant access
* agreement-ended expired, cancelled, or terminated; revoke access
* license-updated the buyer's license was provisioned or changed
* license-deprovisioned the buyer's license ended; revoke access
* ignored a marketplace event this listing takes no action on
*
* Manufacturer and proposer variants of the agreement events are identical for
* our purposes (we are both), so the role suffix is stripped.
*/
export function parseMarketplaceEvent(event) {
if (!event || event.source !== AGREEMENT_EVENT_SOURCE) return null;
const detailType = String(event['detail-type'] || '');
const base = detailType.replace(/\s+-\s+(Manufacturer|Proposer|Acceptor)$/, '').trim();
const detail = event.detail || {};
const common = {
detailType,
agreementId: detail.agreement?.id ?? null,
agreementStatus: detail.agreement?.status ?? null,
acceptorAccountId: detail.acceptor?.accountId ?? detail.agreement?.acceptorId ?? null,
offerId: detail.offer?.id ?? detail.agreement?.offerId ?? null,
productCode: detail.product?.code ?? null,
licenseArn: detail.license?.arn ?? null,
};
switch (base) {
case 'Purchase Agreement Created':
case 'Purchase Agreement Amended':
return { kind: 'agreement-created', ...common };
case 'Purchase Agreement Ended':
return { kind: 'agreement-ended', ...common };
case 'License Updated':
return { kind: 'license-updated', ...common };
case 'License Deprovisioned':
return { kind: 'license-deprovisioned', ...common };
default:
return { kind: 'ignored', ...common };
}
}