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
docs(aws-marketplace): rewrite the listing kit and provisioning for the EventBridge integration
nirholas985dfae42f5a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b43ecdb28..ba43e6995 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -42,6 +42,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Text to 3D gets its footer back, a retry button that knows when to open, and an honest name for the model that refined your prompt**: The /forge-spark page was driven end to end in a real browser. The closing note under the workspace was written as a page footer, and the site's old corner-credit styling for the 3D viewer pages had quietly claimed it: it was pulled out of the layout into a floating monospace strip that sat on top of the viewer on a desktop, and on a 320px phone it landed across the composer with its link to the full studio pushed off the edge of the screen entirely. That note is now ordinary page text, centered under the workspace where it belongs, and the real three.ws footer, with its full set of links, is on the page for the first time. When a generation fails there is now a Try again button inside the error itself, so recovery does not mean scrolling back to the top; when the generator answers that it is busy, the button counts down and opens exactly when a retry can actually get through. A stage that fails is marked in red instead of silently dropping back to grey, the wait now shows real elapsed seconds so a cold reconstruction lane no longer reads as a hang, and the first step is renamed to whatever model actually answered, because the prompt refiner is a chain of engines and Nemotron is only the first one it tries. (`/forge-spark`) `[fix, improvement]`- **The Agent-Forged Gallery says what actually went wrong, and its thumbnails stop fighting the link they sit in**: The gallery of 3D props that the platform's autonomous agents bought with real USDC was driven end to end in a real browser: a hundred live cards, the category chips, prompt search, all four sorts, and the loading, empty and error states at phone, tablet and desktop widths. The finding worth caring about was in the error state. When the feed failed with a server error rather than a dropped connection, the page still said only "Something went wrong", because the translation pass ran after the failed request and overwrote the specific reason the page had just written there. The reason now lives on its own line that translation leaves alone, so a failure tells you what it was and the Try again button next to it recovers the full gallery. Each prop's spinning preview had also been set up to drag-orbit under the link that wraps it, from an attribute written to do the exact opposite; the previews are now purely decorative and the whole tile is just a link to the 3D viewer. The category chips announced themselves to screen readers as tabs without being tabs, and never said which family the grid was filtered to; they are now a labelled group of toggle buttons that report their own state. Every control on the page (search box, sort, chips, the Preview and Download buttons, the thumbnail itself) now shows a focus ring when reached by keyboard, where the search box previously had its ring switched off entirely. A prop still waiting on its settlement no longer renders an empty price, and one whose model file is not written yet no longer offers a Preview and Download that lead nowhere. (`/forged`) `[fix, improvement]`- **The avatar SDK bundle we ship is now built from the code we deploy**: The <agent-3d> runtime that sites load from three.ws is a single bundled file, and the production build never rebuilt it. It was copied from whatever the build machine happened to have on disk, which could be days older than the code being deployed, so a fix to the avatar element could ship everywhere else on the site and quietly not reach the SDK. The deploy now rebuilds that bundle from the same commit as the rest of the release, every time. Nothing to change on your side: existing embeds keep working and simply pick up the current runtime. (`/avatar-sdk`) `[fix, sdk, infra]`+- **The AWS Marketplace integration is rebuilt for the rules AWS now enforces**: Subscribing to three.ws through AWS Marketplace would have failed on the first click, and nobody would have known why. AWS changed how a buyer is identified: for any product created since June 2026 it no longer sends the customer identifier our integration was built around, sends a license identifier instead, and delivers cancellation notices over a different channel entirely. The whole path is rebuilt on the new model, from the database up: subscriptions are keyed on the license AWS actually issues, lifecycle events arrive over the new channel with their own authentication, and a cancellation that could refer to more than one of a buyer's subscriptions now refuses to guess rather than cutting off access someone is still paying for. Signature checking also follows the algorithm the message declares instead of assuming one, so a genuine notice can no longer be thrown out as a forgery. Listing status is unchanged for now: the product still has to be created and reviewed on the AWS side, which is theirs to schedule, not ours. (`/docs/aws-marketplace`) `[fix, infra]`- **The Character Library counts its own characters, and fills the screen while it does**: The library page had been advertising 106 rigged characters since launch. There are 107 on the shelf today, and there will be more tomorrow, so the number is no longer typed into the headline, the page description or the share card: the page asks the library how many it has and prints the answer under the hero. The grid also stopped wasting a third of a desktop screen. A layout rule left the page shrink-to-fitting to about two thirds of the window, so a wide monitor showed three columns where five fit; it now uses the full width it was designed for. Every character card previously carried a hidden second tab stop that announced the same name as the card itself, which made keyboard browsing twice as long as it needed to be, and thumbnails could not be dragged out of alignment by an accidental swipe anymore because the preview no longer pretends to be an interactive 3D control. The search box has a visible focus ring again instead of a one pixel border shift, and when the library cannot be reached the page now says what actually went wrong rather than reverting to a generic sentence a moment later. (`/character-library`) `[fix, improvement]`- **The Characters gallery pages past the first screen, and stops fighting dark mode**: The character gallery at /characters was audited end to end in a real browser: loading the feed, both sort orders, search, Load more, following a card through to its character page, and the loading, empty and error states, at phone, tablet and desktop widths. The worst finding was that the Top sort was quietly broken. Sorting by most-chatted read the right first screen, but pressing Load more asked the server to continue from the wrong place, so the feed ended after eight characters out of more than two thousand. It now pages all the way through, in order. The page also ignored the site theme: it painted a fixed light-blue background under the dark header no matter what you had chosen, which is now fixed in both directions, and wallet addresses on the cards were nearly invisible on a light background everywhere they appear on the site. The gallery filled only a narrow strip down the middle of a desktop screen and now uses the full width, up to four cards across. If the feed failed to load you got one line of grey text and no way to retry; there is now a proper message with a Try again button, a failed Load more keeps the characters you already had, and searching for something with no matches offers to clear the search rather than leaving you at a dead end. Pressing Top while the first screen was still loading used to light up the button and change nothing, so you were left reading New results under a Top heading. The search box had no label for screen readers, the sort buttons never showed which was selected, and neither they nor Load more showed a focus outline for anyone navigating by keyboard. Keyboard users can also now skip the header and land in the gallery. Finally, the feed itself is several times faster to answer on a cold request, because it no longer counts every conversation of every published character just to show you twenty-four of them. (`/characters`) `[fix, improvement]`- **The coin-community lobby tells you which worlds people are actually standing in**: The front door at three.ws/play has been rebuilt around the question it exists to answer: which of these coin worlds is worth walking into right now. It opens with the claim and three live numbers (how many communities are listed, how many people are inside a world at this moment, and what those communities are worth together), and every one of them is measured rather than decorated: the headcount comes straight from the multiplayer matchmaker, and when that cannot be read the number is left out instead of guessed. Each card now carries its own live count, so a world with nine people in it says so, and the search field has grown into a full-width command bar with a / shortcut and a clear button. Above the grid there are four orderings that are real reorders of real fields: the live trending order, most people inside, biggest market cap, and newest launch; the headcount ordering stays switched off, and says why, while live counts are unavailable. Cards gained the details you actually pick a world on (how old the coin is, whether it launched in the last day, whether it is still on its bonding curve, and how loud its board is), and lost the badge that was true of almost every coin and therefore told you nothing. The avatar picker, which used to be a tall panel standing between you and the worlds, is now a single row showing the avatar you will be seen as and the name above your head, folded away for anyone who has already chosen and wide open for anyone who has not. A card whose artwork fails to load keeps the coin's initial instead of leaving a grey hole, the grid fades in in reading order, and the whole page holds together from a 390px phone to a desktop. (`/play`) `[improvement, feature]`@@ -49,6 +50,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **The Concierge page stops cutting itself off on a phone, and its install tabs work from the keyboard**: Three fixes to the Concierge landing page. On a narrow phone screen the whole page was being sized against the longest line of the install snippet, which pushed the column roughly twice as wide as the screen; because the site clips sideways overflow, the right-hand half of every headline, paragraph and button was simply cut off with no way to scroll to it. The column now fits the screen and the code snippet scrolls inside its own box, the way it already did on a laptop. The four install tabs (one tag, web component, npm, imperative) announced themselves to a screen reader as tabs but were not wired to the panels they open and ignored the arrow keys; they now move with Left, Right, Home and End, and each tab is properly tied to its snippet. Copy buttons also say which snippet they copy, and if the browser blocks the clipboard the snippet is selected for you so Ctrl+C still works. Finally, the passive "Have you tried" suggestion card could land on top of the live concierge demo in the corner; it now stacks clear of it. (`/concierge`) `[fix, improvement]`- **The Create page no longer black-screens when the sign-in check stalls, and a broken remix link no longer kills every button on it**: Three fixes to the front door for creating, plus a strip of your own avatars that was never once drawn. The page is meant to greet a returning creator with "Start from one of yours" and a row of the avatars they have already made, one click from remixing any of them. It read the library reply in the wrong shape, decided it had received nothing, and hid the row every single time, so nobody has ever seen it. It reads the reply correctly now and the row appears, with a real thumbnail for each avatar. The page opens behind a full-screen loading screen while it checks whether you are signed in; if that check got no answer at all (a stalled connection rather than a refused one) the screen stayed black forever and the page read as dead. It now hands the page back after a short wait and treats you as signed out, which costs at most one extra trip through sign-in. Separately, opening a remix link for an avatar that had been deleted or made private used to show a message for four seconds and then leave you on a page where not one of the eight creation cards did anything: the remix ran before the buttons were wired and gave up without wiring them. The cards are live first now, and a failed remix explains itself in a panel that stays put, with a button to try again and a button to move on. Also: the talking-avatar-video card now says "Coming soon" on the card itself instead of only dimming, answers the keyboard the same way it answers a mouse, and stops calling itself unavailable when the check simply could not reach us (it asks again when you click). A saved avatar whose thumbnail has been deleted falls back to a silhouette instead of a broken image. (`/create`) `[fix, improvement]`- **The listings page now records our NVIDIA Inception membership**: Anyone reading the listings and distribution page to see which programs back three.ws was getting an incomplete answer: the startup-programs table named Quicknode and Google Cloud but left NVIDIA Inception out entirely, even though the platform has been a member since July 2026 and every 3D generation lane runs on NVIDIA GPUs. The table now carries the NVIDIA row, saying what the membership is, what runs on the hardware behind it, and, as everywhere else on the site, that a startup program is not a partnership, an investment, or an endorsement. (`/docs/listings`) `[docs, fix]`+- **The listings page now tracks the AI platform directories, starting with OpenAI**: The listings and distribution page tracked cloud marketplaces, startup programs, and chain dApp directories, but had nothing for the directories the AI platforms run themselves, which is where an MCP server gets listed as something you can install rather than something you can read about. There is now an AI Platform Directories section, and it opens with the three OpenAI surfaces: the plugin directory shared by ChatGPT and Codex, the Showcase Gallery, and the Cookbook, each with its current status stated plainly rather than implied. The three.ws MCP server at three.ws/api/mcp already meets the plugin directory's gating requirement, and the section says so. (`/docs/listings`) `[docs]`- **The Money Flow Map stops cutting its own table off on a phone, and a refresh no longer blanks the map**: The map of who pays whom at three.ws/flow was driven end to end in a real browser: every window, every filter, the legend toggles, search, zoom, the wallet table and the loading, empty and error states, at phone, tablet and desktop widths. Two findings mattered. On a phone the page was quietly cutting itself in half: the "What the money bought" panel and the entire wallet table were laid out wider than the screen and then clipped away, with no way to scroll to them, so the text version of the graph (the part a screen reader and a keyboard actually use) was unreachable on mobile. The table now scrolls inside its own frame and nothing runs off the edge. Second, the page re-reads the chain every minute, and every one of those re-reads used to cover the drawn map with a loading spinner, so a live page flickered into looking broken once a minute. A background re-read now leaves the map alone and reports itself on the timestamp next to the controls, and if it fails, the graph you were reading stays on screen with the failure named there instead of being wiped for an error panel. Switching the time window still shows the loading state, because that genuinely replaces the topology, and it now cancels a read that is still in flight: a slow 90-day request could previously land after you had already switched to 7 days and draw a window you were not looking at, under a button that said something else. The rest is the polish an audit turns up: the table's own caption said "no wallets match the current filters" even in a quiet window where you had set no filters, and now tells those two situations apart; the empty state no longer offers a "Show 90 days" button while you are already on 90 days, and offers the next longer window instead; the clear-search cross stayed on screen after Clear filters had already emptied the box; and the canvas now resolves its colours once per frame rather than several times per line, which is what a four-hundred-route graph feels like on a laptop. (`/flow`) `[fix, improvement]`- **The Pole Club audio controls no longer fall off the edge of a small phone**: On a narrow phone the club's top bar ran out of room and simply cut off whatever did not fit, and the page cannot scroll sideways, so the mute button and the 8D audio toggle were gone with no way to reach them. The bar now gives up the parts that are only there to read (the tagline and the price and rail labels, all of which the panel's How it works section repeats) and keeps both controls at full size at every width, down to a 320px screen. (`/club`) `[fix]`- **The Pole Club leaderboard now ranks the dancers who are actually on the poles**: The club's leaderboard was reading names out of the payout registry instead of off the stage, so it listed four dancers under names matching none of the three at the poles, every one of them sitting at zero. It now names each dancer exactly as her pole card does, drops entries for dancers who are not in tonight's lineup and have never been tipped, and says what a quiet board actually means: the 24h and 1h views tell you the club has been quiet rather than claiming nobody has ever tipped, which was never true while the all-time board was full. Keyboard and screen-reader visitors get the rest of the pass: the page carries one real heading instead of five competing ones, Skip to stage now lands you on the stage, and the controls belonging to the walk-in (the agent picker, the Enter the club prompt) no longer sit invisibly in the tab order once you are inside the room. (`/club`) `[fix, improvement]`diff --git a/data/changelog.json b/data/changelog.jsonindex ce236892e..29844003b 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,25 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-08-17",+ "title": "The AWS Marketplace integration is rebuilt for the rules AWS now enforces",+ "summary": "Subscribing to three.ws through AWS Marketplace would have failed on the first click, and nobody would have known why. AWS changed how a buyer is identified: for any product created since June 2026 it no longer sends the customer identifier our integration was built around, sends a license identifier instead, and delivers cancellation notices over a different channel entirely. The whole path is rebuilt on the new model, from the database up: subscriptions are keyed on the license AWS actually issues, lifecycle events arrive over the new channel with their own authentication, and a cancellation that could refer to more than one of a buyer's subscriptions now refuses to guess rather than cutting off access someone is still paying for. Signature checking also follows the algorithm the message declares instead of assuming one, so a genuine notice can no longer be thrown out as a forgery. Listing status is unchanged for now: the product still has to be created and reviewed on the AWS side, which is theirs to schedule, not ours.",+ "tags": [+ "fix",+ "infra"+ ],+ "link": "/docs/aws-marketplace"+ },+ {+ "date": "2026-08-17",+ "title": "The listings page now tracks the AI platform directories, starting with OpenAI",+ "summary": "The listings and distribution page tracked cloud marketplaces, startup programs, and chain dApp directories, but had nothing for the directories the AI platforms run themselves, which is where an MCP server gets listed as something you can install rather than something you can read about. There is now an AI Platform Directories section, and it opens with the three OpenAI surfaces: the plugin directory shared by ChatGPT and Codex, the Showcase Gallery, and the Cookbook, each with its current status stated plainly rather than implied. The three.ws MCP server at three.ws/api/mcp already meets the plugin directory's gating requirement, and the section says so.",+ "tags": [+ "docs"+ ],+ "link": "/docs/listings"+ },{"date": "2026-08-17","title": "The listings page now records our NVIDIA Inception membership",diff --git a/docs/aws-marketplace-listing-kit.md b/docs/aws-marketplace-listing-kit.mdindex c88a89cd9..20f3eeb8c 100644--- a/docs/aws-marketplace-listing-kit.md+++ b/docs/aws-marketplace-listing-kit.md@@ -7,12 +7,13 @@ deployed — see [aws-marketplace.md](./aws-marketplace.md). This doc covers thelisting itself, which has not yet been created (the AMMP "AI agents & toolsproducts" page shows "No products to display").-> **BLOCKER, verified 2026-08-02: the integration in this repo cannot serve a new-> listing as written.** AWS stopped populating `CustomerIdentifier` for new SaaS-> integrations, and all 51 references across 7 files key on it. Read-> "Verified against AWS docs" and "Confirmed defects" at the bottom of this file-> before touching the listing. Do not create the product expecting the backend to-> work; it will fail the subscribe round-trip.+> **Backend blockers cleared 2026-08-17.** The four defects that would have failed+> the subscribe round-trip (identity keyed on the retired `CustomerIdentifier`,+> the orphan SNS topic pin, hardcoded SHA1 SNS verification, and the missing+> EventBridge transport) are fixed and covered by tests. The listing is now+> gated only on AWS-console work and Seller Operations review. The evidence+> behind each fix is in "Verified against AWS docs" and "Defects and their+> fixes" at the bottom of this file.- **Seller account:** three-ws @ 155407237916- **Delivery method:** API-based (SaaS fulfillment) — **not** container/Bedrock@@ -27,11 +28,10 @@ products" page shows "No products to display").current EULA ("offered free of charge through AWS Marketplace") and clears AWS reviewfastest (no tax/bank/dimension interview).-> Note: `docs/aws-marketplace.md` and the unused `AWS_MP_METERING_DIMENSION` /-> `AWS_MP_DEFAULT_RATE_LIMIT_PER_MINUTE` env references describe an earlier-> AWS-metered-billing plan. That is superseded: billing is x402-per-call, not AWS-metered.-> Reconcile `docs/aws-marketplace.md` so it stops promising per-call/per-agent-minute AWS-> billing.+> `AWS_MP_METERING_DIMENSION` and `AWS_MP_DEFAULT_RATE_LIMIT_PER_MINUTE` remain in+> the code for a future usage-priced listing. Both are inert while the dimension+> is unset, which is the correct state for a free listing. [aws-marketplace.md](./aws-marketplace.md)+> documents them as optional rather than as the billing model.---@@ -40,30 +40,38 @@ products" page shows "No products to display").This codespace has no AWS credentials, so these must be run on a machine withadmin creds on account 155407237916.-### 1. Provision the IAM user (the SNS half of the script is dead weight)+### 1. Provision the IAM user and the EventBridge relay```bash./scripts/aws-marketplace-provision.sh```-**The SNS topic this script creates is NOT the topic AMMP wants, and there is no-field in the SaaS wizard to paste it into.** AWS Marketplace creates and owns the-notification topics and hands you the ARN *during product creation*, in the form+It creates, idempotently:++- the IAM user `three-ws-marketplace` plus the four marketplace actions and an+ access key. `resolveCustomer()` in `api/_lib/aws-marketplace.js` calls+ `aws-marketplace:ResolveCustomer`; without those keys every subscribe redirect+ dies at `/aws-marketplace/error?reason=token_expired`.+- an EventBridge **connection** holding a generated shared secret, an **API+ destination** pointing at `https://three.ws/api/aws-marketplace/subscription`,+ an IAM role EventBridge assumes to invoke it, an SQS dead-letter queue, and a+ **rule** on the default event bus matching `source: aws.agreement-marketplace`.++The relay is required because lifecycle events for a new listing arrive on+EventBridge, which cannot POST to an external HTTPS endpoint directly. **The+seller never supplies an SNS topic ARN**, and there is no field in the SaaS+wizard for one: AWS creates and owns the notification topics and hands them over+on the product overview page *after* product creation, in the form`arn:aws:sns:us-east-1:<aws-owned-account>:aws-mp-subscription-notification-<PRODUCTCODE>`.-You subscribe to that topic afterwards; you never supply your own. Ignore the-script's `AWS_MP_SNS_TOPIC_ARN` output. See-[Amazon SNS notifications for SaaS products](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-notification.html).+See [Amazon SNS notifications for SaaS products](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-notification.html).-What the script is genuinely needed for is the IAM user: `resolveCustomer()` in-`api/_lib/aws-marketplace.js` calls `aws-marketplace:ResolveCustomer`, and without-those keys every subscribe redirect dies at `/aws-marketplace/error?reason=token_expired`.--Take `AWS_MP_ACCESS_KEY_ID`, `AWS_MP_SECRET_ACCESS_KEY`, and `AWS_MP_REGION` and set-them on the Cloud Run service (production env lives there, not Vercel):+Take `AWS_MP_ACCESS_KEY_ID`, `AWS_MP_SECRET_ACCESS_KEY`, `AWS_MP_REGION`, and+`AWS_MP_EVENT_SECRET` and set them on the Cloud Run service (production env lives+there, not Vercel):```bashgcloud run services update three-ws-api --region us-central1 \- --update-env-vars AWS_MP_ACCESS_KEY_ID=…,AWS_MP_SECRET_ACCESS_KEY=…,AWS_MP_REGION=…+ --update-env-vars AWS_MP_ACCESS_KEY_ID=…,AWS_MP_SECRET_ACCESS_KEY=…,AWS_MP_REGION=us-east-1,AWS_MP_EVENT_SECRET=…```(`--update-env-vars` merges. Never use `--set-env-vars` here: it replaces the entire@@ -71,6 +79,14 @@ env set and would wipe every other production variable.)`AWS_MP_PRODUCT_CODE` is assigned by AMMP after the product is created — add it last.+### 1b. Apply the schema migration++The Concurrent Agreements re-key ships as+`api/_lib/migrations/20260817120000_aws_marketplace_concurrent_agreements.sql`.+Preview with `npm run db:status`, then `npm run db:migrate` (which applies every+pending migration immediately, with no dry run). `npm run deploy:gcp:submit`+refuses to submit while it is pending, so this cannot be skipped by accident.+### 2. EULA: pick Standard Contract and skip this entirely (recommended)The AMMP wizard accepts either the **Standard Contract for AWS Marketplace (SCMP)**@@ -195,44 +211,47 @@ The free AWS subscription only grants the x402 access key.| AMMP field | Value ||---|---|| Fulfillment / SaaS URL (Registration URL) | `https://three.ws/api/aws-marketplace/register` |-| SNS notification topic ARN | Not a field you fill in. AWS hands you `aws-mp-subscription-notification-<PRODUCTCODE>` after the product is created; subscribe to it then. |+| SNS notification topic ARN | Not a field you fill in. AWS hands you the notification configuration on the product overview page after the product is created. || EULA | **Standard Contract (SCMP)**: recommended, zero setup. Custom EULA only if the S3 copy returns 200 (see prereq #2). || Post-subscribe redirect | `https://three.ws/aws-marketplace/welcome` (handled by register.js) |-Lifecycle events land on `POST /api/aws-marketplace/subscription` (SNS webhook —-already deployed; handles subscribe-success, unsubscribe-success, subscribe-fail,-entitlement-updated, and the SubscriptionConfirmation handshake).+Lifecycle events land on `POST /api/aws-marketplace/subscription`, which is+deployed and accepts both transports: EventBridge agreement/license events+relayed through the API destination (the path a new listing uses), and legacy+signed SNS notifications with the SubscriptionConfirmation handshake.---## Step sequence in AMMP-Nothing in steps 2-7 depends on the IAM keys, so if creds are slow to arrive, start-the wizard anyway and backfill the env vars before the round-trip test in step 9.+Nothing in steps 3-8 depends on the IAM keys, so if creds are slow to arrive, start+the wizard anyway and backfill the env vars before the round-trip test in step 10.-1. Run prereq #1; set `AWS_MP_ACCESS_KEY_ID`, `AWS_MP_SECRET_ACCESS_KEY`, and- `AWS_MP_REGION` on the Cloud Run service.-2. AMMP → **AI agents & tools products** → **Create AI agents & tools product**.-3. Delivery method: **API-based** (SaaS). (Until you finish the wizard the draft may+1. Run prereq #1; set `AWS_MP_ACCESS_KEY_ID`, `AWS_MP_SECRET_ACCESS_KEY`,+ `AWS_MP_REGION`, and `AWS_MP_EVENT_SECRET` on the Cloud Run service.+2. Run prereq #1b (`npm run db:status`, then `npm run db:migrate`) and deploy, so+ production is serving the re-keyed schema before any buyer can reach it.+3. AMMP → **AI agents & tools products** → **Create AI agents & tools product**.+4. Delivery method: **API-based** (SaaS). (Until you finish the wizard the draft mayappear under **SaaS products**, per AMMP's own note — that's expected.)-4. Fill product detail fields from the "Listing fields" section above; upload the logo.-5. Pricing: choose **Free**.-6. Fulfillment: paste the Registration URL from the table. There is no SNS field here.-7. EULA: select **Standard Contract**.-8. Save → AMMP assigns a **Product Code** and gives you the two `aws-mp-*` SNS topic- ARNs. Set `AWS_MP_PRODUCT_CODE` on the Cloud Run service. No rebuild is needed:- `gcloud run services update three-ws-api --region us-central1 --update-env-vars- AWS_MP_PRODUCT_CODE=…` cuts a new revision on its own.-9. Wire notifications per what the product overview page actually shows. For a new- listing expect **EventBridge**, not SNS (see Defect 4 below): create a rule on the- default event bus in seller account 155407237916 matching- `source: aws.agreement-marketplace`, with an API destination targeting- `https://three.ws/api/aws-marketplace/subscription`, and make that handler parse- EventBridge event JSON. Only if AWS also issues the legacy- `aws-mp-subscription-notification-<PRODUCTCODE>` topic, add an HTTPS subscription- to it as a secondary leg. Then run one end-to-end- subscribe → redirect → welcome → issue-key test while the product is **limited**.-10. Once the private round-trip works, **Request changes → Update visibility →+5. Fill product detail fields from the "Listing fields" section above; upload the logo.+6. Pricing: choose **Free**.+7. Fulfillment: paste the Registration URL from the table. There is no SNS field here.+8. EULA: select **Standard Contract**.+9. Save → AMMP assigns a **Product Code** and shows the notification configuration+ on the product overview page. Set `AWS_MP_PRODUCT_CODE` on the Cloud Run service.+ No rebuild is needed: `gcloud run services update three-ws-api --region+ us-central1 --update-env-vars AWS_MP_PRODUCT_CODE=…` cuts a new revision on its own.+10. Confirm the notification wiring against what that page actually shows. The+ EventBridge rule from prereq #1 already matches every+ `source: aws.agreement-marketplace` event, so a new listing needs nothing+ further. Only if AWS also issues the legacy+ `aws-mp-subscription-notification-<PRODUCTCODE>` topic, set+ `AWS_MP_SNS_TOPIC_ARN` to **that** ARN and add an HTTPS subscription to+ `https://three.ws/api/aws-marketplace/subscription` as a secondary leg. Then+ run one end-to-end subscribe → redirect → welcome → issue-key test from a test+ AWS account while the product is **limited**.+11. Once the private round-trip works, **Request changes → Update visibility →Public**. This one needs AWS Marketplace Seller Operations approval, so it is thestep with real calendar time on it. Everything before it is same-day.@@ -241,16 +260,34 @@ the wizard anyway and backfill the env vars before the round-trip test in step 9## What is and isn't doneDone (in repo, deployed):-- Registration URL, SNS webhook, key issuance, account linking endpoints.-- `aws_marketplace_customers` schema + x402 bridge.-- EULA HTML, S3 publish script, SNS/IAM provision script.+- Registration URL, lifecycle webhook (EventBridge + legacy SNS), key issuance,+ account linking endpoints.+- `aws_marketplace_customers` schema, re-keyed onto `LicenseArn` for Concurrent+ Agreements, plus the x402 bridge.+- EULA HTML, S3 publish script, IAM + EventBridge provision script.- Welcome onboarding page.+- Test coverage for the event mapping, the relay secret, the ambiguity guard, the+ metering call shape, and SNS SignatureVersion 1 and 2.Not done (requires AWS console / seller creds — cannot be done from this repo):- Running the provision + EULA-publish scripts (no AWS CLI/creds in codespace).-- Publishing the S3 EULA (currently 404 — never uploaded).+- Publishing the S3 EULA (currently 404, never uploaded; unnecessary if you pick+ the Standard Contract).- Creating the product in the AMMP wizard (manual web UI).- Obtaining and wiring `AWS_MP_PRODUCT_CODE`.+- The limited-visibility round-trip test and the public-visibility request.++## Calendar++There is no same-day path to a public AWS Marketplace URL. Plan against this:++| Day | Step | Owner |+|---|---|---|+| 1 | Prereqs 1 + 1b, deploy, create the product, save the draft | us |+| 1 | Product code lands, env var set, revision cuts | us |+| 1-2 | Limited-visibility round-trip test from a test AWS account | us |+| 2 | Request public visibility | us |+| +7-10 business days | Seller Operations review and publish | AWS |---@@ -314,36 +351,44 @@ and [saas-eventbridge-integration](https://docs.aws.amazon.com/marketplace/latesevents are delivered to the seller's **default event bus** in their own AWS accountwith `source: aws.agreement-marketplace`. Targets are AWS resources (Lambda, StepFunctions, API Gateway). An external HTTPS webhook needs an EventBridge rule plus an-API destination to relay to it. `api/aws-marketplace/subscription.js` is an SNS HTTPS-webhook and cannot be an EventBridge target as written.+API destination to relay to it. That relay is what+`scripts/aws-marketplace-provision.sh` now creates, and+`api/aws-marketplace/subscription.js` parses both envelope shapes.----## Confirmed defects (fix before the listing goes anywhere)--**Defect 1 (critical, listing-breaking): the identity model is keyed on a field AWS-no longer sends.** `resolveCustomer()` in `api/_lib/aws-marketplace.js` reads-`result.CustomerIdentifier` and discards `LicenseArn` entirely. `register.js` uses it-as the `ON CONFLICT` key. `subscription.js` returns 400 `missing_customer_identifier`-without it. 51 references across 7 files: `aws-marketplace.js`,-`aws-marketplace-bridge.js`, `x402-subscriptions.js`, `issue-key.js`, `register.js`,-`subscription.js`, `link.js`. On a new listing every subscribe dies at the first-insert. Fix: return and persist `LicenseArn` + `CustomerAWSAccountId`, key on those,-keep `customer_identifier` nullable for any legacy row.--**Defect 2 (critical, silent): the SNS topic guard rejects every real notification.**-`verifySnsMessage()` compares `msg.TopicArn` against `env.AWS_MP_SNS_TOPIC_ARN`. The-provision script emits the *self-created* topic ARN for that variable. Set it as the-old docs instructed and every genuine AWS notification fails the check and returns 403,-with the cause visible only in logs. Fix: set that var to the AWS-issued-`aws-mp-subscription-notification-<PRODUCTCODE>` ARN, or leave it unset (the guard is-skipped when empty) until the real ARN is known.--**Defect 3 (latent): SNS signature verification hardcodes SHA1.**-`verifySnsMessage()` always does `createVerify('SHA1')` and never reads-`msg.SignatureVersion`. AWS SNS SignatureVersion 2 signs with SHA256. On a-SignatureVersion 2 topic every message fails verification and returns 403. Fix: branch-on `msg.SignatureVersion` (`'2'` implies SHA256, otherwise SHA1).+## Defects and their fixes (all four closed 2026-08-17)++**Defect 1 (critical, listing-breaking): the identity model was keyed on a field AWS+no longer sends.** `resolveCustomer()` read `result.CustomerIdentifier` and discarded+`LicenseArn` entirely; `register.js` used it as the `ON CONFLICT` key; `subscription.js`+returned 400 `missing_customer_identifier` without it. On a new listing every subscribe+died at the first insert.++*Fixed:* `resolveCustomer()` returns `licenseArn` and `customerAWSAccountId` alongside+the legacy field. `api/_lib/aws-marketplace-store.js` is the single place that knows how+a buyer is identified, keying on `license_arn` (unique) with `agreement_id` as a+correlation key and `customer_identifier` kept nullable for a legacy row. Migration+`20260817120000_aws_marketplace_concurrent_agreements.sql` carries the schema, including+re-pointing the metering audit table's foreign key off the now-nullable column. The+browser handle became the row id, so no license ARN reaches a URL.++**Defect 2 (critical, silent): the SNS topic guard rejected every real notification.**+The old provision script emitted a *self-created* topic ARN for `AWS_MP_SNS_TOPIC_ARN`.+Set as the old docs instructed, every genuine AWS notification failed the pin and+returned 403, visible only in logs.++*Fixed:* the script no longer creates that topic, and both this file and+[aws-marketplace.md](./aws-marketplace.md) state that the variable takes the AWS-issued+`aws-mp-subscription-notification-<PRODUCTCODE>` ARN or nothing at all.++**Defect 3 (latent): SNS signature verification hardcoded SHA1.**+`verifySnsMessage()` always did `createVerify('SHA1')` and never read+`msg.SignatureVersion`, so every message from a SignatureVersion 2 topic (SHA256)+failed verification with an error that reads exactly like a forgery.++*Fixed:* the digest follows `msg.SignatureVersion`. Both versions are covered in+`tests/api/aws-marketplace-sns.test.js`, including a tampered version 2 message.**Defect 4 (critical, transport-level): the SNS webhook is the wrong transport for anew listing.** The [Concurrent Agreements upgrade guide](https://aws.amazon.com/blogs/awsmarketplace/complete-guide-to-upgrading-your-saas-product-to-aws-marketplace-concurrent-agreements/)@@ -355,9 +400,30 @@ of the seller AWS account** (155407237916), not on an HTTPS URL. Reachingresources: an EventBridge rule matching `source: aws.agreement-marketplace` plus anAPI destination (connection + auth) targeting our endpoint, and the endpoint mustparse EventBridge event JSON, not SNS envelopes. `subscription.js` as written-(SNS envelope parse, SNS signature verify, SubscribeURL handshake) never fires on a-new listing. Defects 2 and 3 (topic-ARN guard, SHA1) remain real but only matter for-the legacy SNS path; the primary fix is the EventBridge leg.-`scripts/aws-marketplace-provision.sh` should provision the rule + API destination-instead of the orphan SNS topic. Still verify against the product overview page at-creation time (`saas-create-product` says the EventBridge configuration appears there).+(SNS envelope parse, SNS signature verify, SubscribeURL handshake) would never have+fired on a new listing.++*Fixed:* `subscription.js` detects the envelope shape and routes to the right handler,+so the same URL serves either transport and a listing migrated between them needs no+code change. `parseMarketplaceEvent()` maps every documented detail-type onto the+action the listing takes, stripping the `- Manufacturer` / `- Proposer` role suffix+(we are both). `scripts/aws-marketplace-provision.sh` provisions the connection, API+destination, IAM role, dead-letter queue, and rule instead of the orphan SNS topic.++Two things the relay forced, both worth knowing:++- **The relay needs its own authentication.** An API destination delivery is an+ ordinary HTTPS POST with no AWS signature on it. The connection attaches+ `x-three-ws-marketplace-secret`, checked in constant time against+ `AWS_MP_EVENT_SECRET`; an unset secret refuses EventBridge deliveries outright.+ Without it, anyone who found the URL could revoke a paying buyer's key with a+ forged `Purchase Agreement Ended`.+- **An end event can be ambiguous, and guessing is worse than doing nothing.**+ Agreement events carry no license ARN, and under Concurrent Agreements one AWS+ account can hold several live agreements for the same product. When resolution+ falls back to the acceptor's account id and matches more than one row, the handler+ logs and revokes nothing. Retrying cannot add information, so it answers 200 rather+ than looping the relay into the dead-letter queue.++Still verify against the product overview page at creation time+(`saas-create-product` says the EventBridge configuration appears there).diff --git a/docs/aws-marketplace.md b/docs/aws-marketplace.mdindex aa7b82a14..073bf5e05 100644--- a/docs/aws-marketplace.md+++ b/docs/aws-marketplace.md@@ -2,7 +2,7 @@three.ws is a verified AWS Partner. The AWS Marketplace product is an API-based (SaaS) listing, and the AWS subscription is a **free front door**: subscribing links your AWS account to a three.ws account and issues an x402 access key. Actual usage is then paid per-call in USDC over the x402 / HTTP 402 protocol, the same as every other x402 endpoint. AWS Marketplace itself does not meter or bill usage.-> **Listing status (checked 2026-08-15): not yet public.** Every endpoint described below is built and deployed, but the product has not been created in the AWS Marketplace Management Portal, so there is nothing to subscribe to on the AWS side yet. The Marketplace credentials (`AWS_MP_*`) are correspondingly unset in production, so `POST /api/aws-marketplace/subscription` answers `503 not_configured` today. The remaining steps are AWS-console work and Seller Operations approval, tracked in [aws-marketplace-listing-kit.md](./aws-marketplace-listing-kit.md). Until then, use x402 directly: no AWS subscription is required to call `/api/x402/*`.+> **Listing status (checked 2026-08-17): not yet public.** The integration is built, deployed, and now conforms to the Concurrent Agreements requirements AWS made mandatory for new SaaS products on 2026-06-01, but the product has not been created in the AWS Marketplace Management Portal, so there is nothing to subscribe to on the AWS side yet. The Marketplace credentials (`AWS_MP_*`) are correspondingly unset in production, so `POST /api/aws-marketplace/subscription` answers `503 not_configured` today. The remaining steps are AWS-console work and Seller Operations approval, tracked in [aws-marketplace-listing-kit.md](./aws-marketplace-listing-kit.md). Until then, use x402 directly: no AWS subscription is required to call `/api/x402/*`.## Subscribing via AWS Marketplace@@ -10,7 +10,7 @@ This is the flow once the listing is public.1. Find the three.ws listing on [AWS Marketplace](https://aws.amazon.com/marketplace).2. Choose **Subscribe** — the AWS Marketplace subscription is free.-3. After confirming in AWS, you are redirected to `https://three.ws/aws-marketplace/welcome` to complete account setup.+3. Choose **Set up your account**. AWS POSTs a short-lived registration token to `https://three.ws/api/aws-marketplace/register`, which exchanges it for your license and redirects you to `https://three.ws/aws-marketplace/welcome`.4. If you already have a three.ws account, sign in and your AWS subscription is linked automatically.5. Once linked, the welcome page issues your x402 access key so you can start calling `/api/x402/*` immediately.@@ -18,50 +18,76 @@ This is the flow once the listing is public.The AWS Marketplace subscription is free: there are no AWS pricing dimensions, no contract, and no AWS-side metering. Usage is paid per-call in USDC via x402 (HTTP 402): every call returns a structured 402 challenge, your wallet or facilitator pays in USDC, and the request retries automatically. This is identical to how a non-AWS caller pays, so there is nothing to reconcile on your AWS invoice.+## How a buyer is identified++This matters if you are reading the code, because AWS changed the answer and the old answer is still all over the internet.++For a **new** SaaS integration, `ResolveCustomer` no longer populates `CustomerIdentifier`. It returns `LicenseArn` and `CustomerAWSAccountId`, and the license ARN is the per-grant identity ([ResolveCustomer API reference](https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_ResolveCustomer.html)). Under **Concurrent Agreements** one AWS account can hold several simultaneous agreements for the same product, so the buyer's AWS account id alone does not identify a subscription and is never used as a key.++The record in `aws_marketplace_customers` therefore carries all of `license_arn` (unique), `agreement_id`, `customer_aws_account_id`, and a nullable legacy `customer_identifier`. The handle passed to the browser on `/aws-marketplace/welcome?customer=…` is the row's own id, not the license ARN: a grant identifier does not belong in a URL that lands in browser history, referrer headers, and access logs.+## AWS account-The AWS Marketplace seller account for three.ws is `155407237916` (`us-east-1`), which hosts the Marketplace integration — the SNS subscription topic, the ResolveCustomer/entitlement bridge, and the EULA. The platform's own production runtime runs on Google Cloud Run (service `three-ws-api`, region `us-central1`); see [ops/gcp-production.md](./ops/gcp-production.md) for the hosting runbook.+The AWS Marketplace seller account for three.ws is `155407237916` (`us-east-1`), which hosts the Marketplace integration: the IAM user for the metering APIs, the EventBridge relay for lifecycle events, and the EULA. The platform's own production runtime runs on Google Cloud Run (service `three-ws-api`, region `us-central1`); see [ops/gcp-production.md](./ops/gcp-production.md) for the hosting runbook.-## For Developers: Marketplace Integration Endpoints+## For developers: Marketplace integration endpointsIf you are integrating three.ws programmatically after subscribing via AWS Marketplace, the relevant API endpoints are:| Endpoint | Purpose ||---|---|-| `POST /api/aws-marketplace/register` | Registration URL — receives the Marketplace token, resolves the customer, and starts onboarding |-| `POST /api/aws-marketplace/subscription` | SNS webhook — receives subscription lifecycle events from AWS |-| `POST /api/aws-marketplace/link` | Attaches your resolved AWS customer record to your signed-in three.ws account. Called by the welcome page; requires a session cookie. |+| `POST /api/aws-marketplace/register` | Registration URL. Receives the Marketplace token, resolves the license, and starts onboarding |+| `POST /api/aws-marketplace/subscription` | Lifecycle webhook. Receives EventBridge agreement/license events (and legacy SNS notifications) |+| `POST /api/aws-marketplace/link` | Attaches your resolved AWS subscription record to your signed-in three.ws account. Called by the welcome page; requires a session cookie. || `POST /api/aws-marketplace/issue-key` | Mints (or returns) the x402 API key for your linked subscription. The plaintext key is returned once, on first issue. |-`register` and `subscription` are called automatically by AWS during the subscription flow; you do not need to call them directly. `link` and `issue-key` are called by the welcome page on your behalf once you sign in.+`register` and `subscription` are called by AWS during and after the subscription flow; you do not call them directly. `link` and `issue-key` are called by the welcome page on your behalf once you sign in.-Both `link` and `issue-key` require an active session and refuse a subscription that belongs to someone else, so a given AWS customer record can only ever be attached to one three.ws account:+Both `link` and `issue-key` require an active session and refuse a subscription that belongs to someone else, so a given AWS subscription can only ever be attached to one three.ws account:| Status | Meaning ||---|---|| `401 unauthenticated` | No valid session cookie. Sign in, then retry. || `403 customer_linked_to_other_account` | This AWS subscription is already attached to a different three.ws account. |-| `404 customer_not_found` | The customer identifier is unknown. Re-open the setup link from AWS Marketplace. |+| `404 customer_not_found` | The subscription record is unknown. Re-open the setup link from AWS Marketplace. || `409 subscription_inactive` | The AWS subscription is cancelled or expired. Re-subscribe in AWS Marketplace first. |+## Lifecycle notifications++New listings receive lifecycle events on **Amazon EventBridge**, not SNS. AWS Marketplace delivers agreement and license events to the seller account's default event bus with `source: aws.agreement-marketplace`, and SNS does not carry the `LicenseArn` these events are keyed on. EventBridge cannot POST to an external HTTPS endpoint on its own, so an EventBridge rule targets an **API destination** that relays to `https://three.ws/api/aws-marketplace/subscription`. `scripts/aws-marketplace-provision.sh` creates the connection, destination, IAM role, dead-letter queue, and rule.++| Event | Effect |+|---|---|+| `Purchase Agreement Created` / `Amended` | Record the agreement; open a pending record if the buyer has not registered yet |+| `License Updated` | Attach the license ARN to the buyer's record |+| `Purchase Agreement Ended` | Revoke the x402 key and mark the record cancelled |+| `License Deprovisioned` | Revoke the x402 key and mark the record cancelled |++The webhook **refuses to guess**. If an end event only identifies the buyer's AWS account and that account holds more than one live agreement for the product, it logs the ambiguity and revokes nothing, because revoking the wrong one cuts off access a buyer is still paying for. Retrying cannot add information, so it answers `200` rather than looping the relay.++The legacy SNS transport is still accepted for an existing integration: `subscribe-success`, `unsubscribe-success`, `subscribe-fail`, and `entitlement-updated`, with full signature verification against the AWS-issued topic.+### Operator configurationThe integration reads its AWS credentials from the environment and ships inert without them: nothing fabricates an entitlement AWS did not grant.| Variable | Required | Purpose ||---|---|---|-| `AWS_MP_ACCESS_KEY_ID` | Yes | Credentials for ResolveCustomer, MeterUsage, and GetEntitlements. |+| `AWS_MP_ACCESS_KEY_ID` | Yes | Credentials for ResolveCustomer, BatchMeterUsage, and GetEntitlements. || `AWS_MP_SECRET_ACCESS_KEY` | Yes | Paired secret for the above. || `AWS_MP_PRODUCT_CODE` | Yes | Product code from the Marketplace listing. |-| `AWS_MP_SNS_TOPIC_ARN` | Yes, for the webhook | The Marketplace SNS topic. `POST /api/aws-marketplace/subscription` answers `503 not_configured` until it is set. |+| `AWS_MP_EVENT_SECRET` | Yes, for the webhook | Shared secret the EventBridge API destination attaches as `x-three-ws-marketplace-secret`. `POST /api/aws-marketplace/subscription` answers `503 not_configured` for EventBridge deliveries until it is set. |+| `AWS_MP_SNS_TOPIC_ARN` | Only for the legacy SNS leg | The AWS-issued `aws-mp-subscription-notification-<PRODUCTCODE>` topic. Never a self-created topic. || `AWS_MP_REGION` | No (default `us-east-1`) | Region for the Marketplace API clients. |-| `AWS_MP_METERING_DIMENSION` | No | Set for a usage-based listing to report MeterUsage per granted call. Leave unset for a contract listing. |+| `AWS_MP_METERING_DIMENSION` | No | Set for a usage-based listing to report BatchMeterUsage per granted call. Leave unset for a free or contract listing. || `AWS_MP_ENTITLEMENT_REQUIRED` | No | Set truthy on a contract listing to gate key issuance on a live GetEntitlements check. || `AWS_MP_DEFAULT_RATE_LIMIT_PER_MINUTE` | No (default `600`) | Rate limit stamped on issued keys. Override per offer with `AWS_MP_RATE_LIMIT_<OFFER_ID>`. |-**`AWS_MP_SNS_TOPIC_ARN` is not optional in practice.** A valid SNS signature only proves that some AWS account signed the message: anyone can create an SNS topic in their own account and have AWS sign a notification for it. The topic ARN is what binds the webhook to this listing, so without it a forged `subscribe-success` could mint a free API key and a forged `unsubscribe-success` could revoke a paying customer's. The handler therefore refuses delivery outright rather than trusting an unpinned topic. SNS retries with backoff, so notifications that arrive during a misconfiguration are redelivered once the variable is set.+**`AWS_MP_EVENT_SECRET` is what authenticates the EventBridge relay.** An API destination delivery is an ordinary HTTPS POST; the header the connection attaches is the only thing distinguishing it from an anonymous caller who found the URL. Without that check a forged `Purchase Agreement Ended` could revoke a paying buyer's key. The handler therefore refuses EventBridge deliveries outright while the secret is unset, and compares it in constant time when it is. EventBridge retries with backoff and dead-letters to SQS, so deliveries that arrive during a misconfiguration are recoverable.++**`AWS_MP_SNS_TOPIC_ARN` plays the same role for the legacy leg.** A valid SNS signature only proves that some AWS account signed the message: anyone can create an SNS topic in their own account and have AWS sign a notification for it. The topic ARN is what binds the webhook to this listing, so the handler refuses SNS delivery outright rather than trusting an unpinned topic. Signature verification follows the message's `SignatureVersion` (version 2 topics sign with SHA256, version 1 with SHA1).-If the registration URL is hit while the AWS credentials are missing, the customer is redirected to `/aws-marketplace/error?reason=not_configured` (not `token_expired`) and the missing variables are named in the server log.+If the registration URL is hit while the AWS credentials are missing, the customer is redirected to `/aws-marketplace/error?reason=not_configured` (not `token_expired`) and the missing variables are named in the server log. If AWS resolves the token but returns no usable identity at all, the redirect reason is `unresolved_customer` and no record is written: an unkeyed record would grant access we could never revoke.## Supportdiff --git a/docs/listings.md b/docs/listings.mdindex 9677bb979..4ac22073a 100644--- a/docs/listings.md+++ b/docs/listings.md@@ -12,7 +12,7 @@ Cloud marketplaces are the procurement flow enterprises use to acquire software| Cloud | Status | Links ||---|---|---|-| **AWS** Marketplace | Live | three.ws is an AWS Partner. Subscribe via AWS Marketplace to consolidate billing on your AWS account; subscriptions auto-issue an x402 API key via the marketplace entitlement service. See [aws-marketplace.md](./aws-marketplace.md). |+| **AWS** Marketplace | Integration ready, listing not yet created | three.ws is an AWS Partner and the SaaS integration is built, deployed, and conformant with the Concurrent Agreements requirements AWS made mandatory for new products on 2026-06-01. The product itself has not been created in the AWS Marketplace Management Portal yet, so there is nothing to subscribe to on the AWS side: use [x402](/docs/x402) directly in the meantime, which needs no AWS account. Once the listing is public, subscribing consolidates procurement on your AWS account and auto-issues an x402 API key. See [aws-marketplace.md](./aws-marketplace.md) and the [listing kit](./aws-marketplace-listing-kit.md). || **Alibaba Cloud** International Marketplace | Live | [Product listing](https://marketplace.alibabacloud.com/products/56724001/sgcmfw00036800.html) · [Storefront](https://marketplace.alibabacloud.com/store/3247293.html) · [Announcement](/blog/three-ws-on-alibaba-cloud-marketplace.html) · [Marketplace blog feature](https://marketplace.alibabacloud.com/doc/blog/detail/mplace-sgcmfw00036800.html) || **Google Cloud** Marketplace | Open to partnership | three.ws already runs its production stack on Google Cloud Run (`three-ws-api`, us-central1) — a natural fit for Vertex AI and GCP's global CDN. Reach out for co-listing, credits, and joint GTM. || **Microsoft Azure** Marketplace | On roadmap | Targeted alongside the AWS/Alibaba rollout. |@@ -43,6 +43,18 @@ Dappbay is BNB Chain's official dApp directory. The listing is about distributio---+## AI Platform Directories++The discovery surfaces owned by the AI platforms themselves, where an MCP server can be listed as an installable product rather than a documentation page.++| Directory | Status | Listing details |+|---|---|---|+| **OpenAI** Plugin Directory (ChatGPT + Codex) | Open to submission | The universal directory shared by ChatGPT and Codex since 2026-07-09, superseding the former App directory. three.ws already meets the gating requirement: a public OAuth 2.1 MCP server at `https://three.ws/api/mcp` ([mcp.md](./mcp.md)). Full submission kit, prerequisites, and rejection criteria: [openai-listing-channels.md](./openai-listing-channels.md). |+| **OpenAI** Showcase Gallery | Open to submission | Editorial feature on openai.com for apps, demos, and open-source projects built with OpenAI models, APIs, or Codex. Open web form, no repo gate. See [openai-listing-channels.md](./openai-listing-channels.md). |+| **OpenAI** Cookbook | Submitted, not merged | [PR #2874](https://github.com/openai/openai-cookbook/pull/2874) (a self-correcting 3D collectible pipeline using text-to-3D, function calling, and vision) has been open since 2026-07-21. Root-cause analysis and the revival steps are in [openai-listing-channels.md](./openai-listing-channels.md). |++---+## Media & Content Partners| Partner | Status | Links |diff --git a/docs/openai-listing-channels.md b/docs/openai-listing-channels.mdnew file mode 100644index 000000000..2556333f2--- /dev/null+++ b/docs/openai-listing-channels.md@@ -0,0 +1,139 @@+# OpenAI listing channels: every surface three.ws can be listed on++Every route to getting three.ws published on an OpenAI-owned surface, ranked by leverage, with the concrete blocker on each. Written 2026-08-17 after auditing the stalled Cookbook PR.++Related docs: [listings.md](./listings.md) (every listing across all vendors), [mcp.md](./mcp.md) (the hosted MCP server a plugin submission depends on), [nvidia-apps-catalog-listing.md](./nvidia-apps-catalog-listing.md) (the same kind of kit for NVIDIA).++---++## Summary: the Cookbook was the weakest of five channels, and we led with it++The Cookbook is a docs repo with no distribution guarantee. The **plugin directory** is a product listing inside ChatGPT and Codex with real installs. We have 37 MCP packages and a hosted OAuth 2.1 MCP server already shipping, which is the exact hard requirement most plugin submitters fail. That is the channel to lead with.++| Channel | Owner | Effort | What it gets us | Status |+|---|---|---|---|---|+| **Plugin directory** (ChatGPT + Codex) | OpenAI | Medium | A listed, installable product inside ChatGPT and Codex | Not submitted. We already meet the MCP prerequisite. |+| **Showcase Gallery** | OpenAI | Low | Editorial feature on openai.com | Not submitted. Open web form. |+| **Cookbook** | OpenAI | Done, then stalled | A docs page on cookbook.openai.com | PR [#2874](https://github.com/openai/openai-cookbook/pull/2874) open since 2026-07-21, currently unmergeable. |+| **Customer stories** | OpenAI | High | Case study on openai.com/stories | Sales-led. Needs usage numbers, not a form. |+| **Grove** | OpenAI | Low | $50k API credits, SF cohort | Wrong stage. Program is pre-idea to pre-seed. |++---++## 1. Plugin directory (the real opportunity)++On **2026-07-09 OpenAI migrated the App directory into the Plugin directory**, a single universal directory shared by ChatGPT and Codex. You publish once and appear in both. This replaced the app-submission flow OpenAI opened to third-party developers on 2025-12-17.++Docs: [developers.openai.com/plugins](https://developers.openai.com/plugins) · [submission guide](https://developers.openai.com/plugins/deploy/submission.md) · [MCP server review requirements](https://developers.openai.com/plugins/deploy/app-review.md) · [plugin guidelines](https://developers.openai.com/plugins/app-guidelines.md) · [submission errors](https://developers.openai.com/plugins/deploy/submission-errors.md)++### Why we are unusually well positioned++The gating requirement is a public, production MCP server. Most submitters have to build one. We already run it:++| Requirement | What we already have |+|---|---|+| Public MCP server | `https://three.ws/api/mcp`, Streamable HTTP, MCP `2025-06-18` ([mcp.md](./mcp.md)) |+| Auth | OAuth 2.1 end-user flow, with `api/mcp/.well-known/oauth-protected-resource` discovery already routed in `vercel.json` |+| Verified website | three.ws, live on Cloud Run behind the production LB |+| Privacy policy and terms | Live pages, already declared in `data/pages.json` |+| Well-scoped tools | 37 MCP packages under `packages/*-mcp`, plus `mcp-server/` and `mcp-bridge/` |+| Screenshots and UI | The avatar viewer and studio surfaces render inline already |++### Prerequisites before the form opens++1. **"Apps Management" write access** on the OpenAI Platform organization role. Without it the submission portal will not let you create a draft.+2. **Verified developer or business identity.** Every public submission requires it. Complete individual or business verification in organization settings first, because verification is its own review and will otherwise become the long pole.++### What the form asks for++Six sections: **Info** (name, short and long description, logo, category, URLs, publisher fields), **MCP** (server URL, authentication, domain verification, tool scanning), **Skills** (upload a bundle or import from the MCP server), **Prompts** (starter examples), **Testing**, **Global** (country availability). Plus release notes.++**The testing section is the one to budget for: at least five positive test cases and three negative ones.** Positive cases need a user prompt, expected behavior, result shape, and any required test data. Negative cases have to demonstrate an appropriate refusal or a safe fallback.++### Scoping decision: submit one plugin, not thirty-seven++The guidelines reject "overly generic single-word names unlinked to your brand" and reward apps that are "tightly scoped." Thirty-seven separate MCP servers submitted individually reads as directory spam and most would fail the tightly-scoped test on their own. Submit **one three.ws plugin whose tools are the text-to-3D and avatar pipeline**, which is the thing no one else in the directory does. The rest stay available as direct MCP connections documented in [mcp.md](./mcp.md).++### Known rejection reasons to design against++Trial or demo versions and incomplete functionality; missing or misleading tool annotations (`readOnlyHint`, `destructiveHint`, `openWorldHint` must be set and accurate); unauthorized third-party integrations or API circumvention; deceptive commerce, which includes digital goods, subscriptions, and upsells; unauthorized data collection. Content must suit users 13 to 17.++Two of those need real attention in our case. **Tool annotations** must be audited across the submitted server, because generation tools that spend credits are not `readOnlyHint`. And **deceptive commerce**: the x402 payment path has to be transparently disclosed, never presented as free and then charged.++### Review flow++Submit, OpenAI reviews, they approve, then **you** publish, then it appears in the directory. It does not go live on approval. OpenAI's own wording is that "review timelines may vary as OpenAI builds and scales the review process," so treat the date as unknown and do not build a launch announcement around a specific week.++---++## 2. Showcase Gallery (lowest effort, do it this week)++Form: [openai.com/form/showcase-submission/](https://openai.com/form/showcase-submission/)++OpenAI's Showcase Gallery takes submissions of apps, demos, and **open-source projects** built with OpenAI models, APIs, or Codex, to be featured as inspiration for the developer community. three.ws qualifies on all three counts: it is open source, it is a live app, and `api/chat.js`, `api/vision.js`, `api/concierge.js`, `api/agent-ask.js`, and the TTS lanes all call OpenAI in production.++It is a plain web form with no repo gate, no CODEOWNERS review, and no merge conflict to lose to. Curation is still OpenAI's call, but the cost of asking is fifteen minutes. There is no reason this was not submitted before the Cookbook PR.++---++## 3. Cookbook: PR #2874 is fixable, but it is not the channel to bet on++[PR #2874](https://github.com/openai/openai-cookbook/pull/2874), "Add example: build a self-correcting 3D collectible set with three.ws text-to-3D, function calling, and vision," opened 2026-07-21. 1,903 additions across a notebook, six images, an SVG diagram, `registry.yaml`, and `authors.yaml`.++### Why it never landed++Four independent reasons, and the first is decisive:++1. **It has merge conflicts right now.** GitHub reports the PR as `CONFLICTING` / `DIRTY`. Nobody can merge it in this state regardless of how much they like it. The conflicts are in `registry.yaml` and `authors.yaml`, the two shared metadata files that **every** Cookbook PR touches, so any PR left open for weeks conflicts by default. This was self-inflicted by waiting rather than rebasing.++2. **No OpenAI reviewer has ever formally reviewed it.** `reviewDecision` is `REVIEW_REQUIRED` with zero reviews. The repo's `.github/CODEOWNERS` is one line: `* @openai/developer-experience`. Every file needs Developer Experience team approval. That gate landed in PR #2920 on 2026-08-05, and a mandatory `docs-editor` review gate landed in PR #2862 on 2026-07-17, four days before we opened. We submitted into a review regime that had just tightened.++3. **The `docs-editor` gate was not visibly satisfied.** `AGENTS.md` requires running the repo's `docs-editor` skill on every changed notebook markdown cell before merge, and resolving or explicitly documenting all remaining P0 and P1 findings in the PR. The thread resolves the Codex bot's findings thoroughly, and the bot's final verdict was clean, but the Codex bot is not the `docs-editor` gate. A reviewer scanning for that checklist does not find it.++4. **The repo does not promise merges.** `CONTRIBUTING.md` says, verbatim: "Contributions are reviewed on a best-effort basis - we can't provide guarantees around when or if content contributions will be reviewed or merged." There are 165 open PRs and the oldest dates to 2024-07-06. Of the last 60 merges, 35 came from OpenAI staff accounts, and most of the external ones are affiliated partners shipping vendor integrations.++### To revive it++In order: rebase onto `main` and resolve `registry.yaml` and `authors.yaml` by hand, taking both sides; re-run `python .github/scripts/check_notebooks.py`; run the `docs-editor` skill over every markdown cell and post the P0/P1 resolution list as a comment so the gate is visibly met; then leave it alone.++**One thing to stop doing.** The thread contains repeated @-mentions of individual OpenAI staff, an "I guess this will just fade into the abyss" comment, asking `@codex` to merge the PR three times, and a signoff of "Well i tried. GGWP OpenAI." That is a permanent public record on OpenAI's repo attached to our project name, and it is now the most visible three.ws artifact in OpenAI's GitHub org. It does not read as a maintainer's problem, it reads as ours. Rebase, post one clean status comment, and let the work carry it.++---++## 4. Customer stories: real, but not a form++[openai.com/business/customer-stories/](https://openai.com/business/customer-stories/) and [openai.com/stories/](https://openai.com/stories/) are editorial, sales-led, and curated. There is no self-serve submission. The path is a relationship with OpenAI's go-to-market team, and the currency is usage numbers plus a named outcome. Park this until the plugin listing is live and producing install and call volume worth citing, then it becomes a natural follow-on ask rather than a cold one.++The nearest self-serve adjacent surface is the [OpenAI Developer Community](https://community.openai.com) "Use cases and examples" category. No gate, indexed by search, and legitimate to post a build writeup to.++---++## 5. Grove: wrong stage, note it and move on++[Apply to OpenAI Grove](https://openai.com/index/openai-grove/). Five-week program at OpenAI's SF HQ, roughly fifteen participants per cohort, $50k in API credits, in-person sessions in the first and last week. Cohort 2 ran 2026-01-22 to 2026-02-27.++Explicitly aimed at "technical talent at the very start of their company-building journey" and "pre-idea individuals." three.ws is a shipping production platform with cloud marketplace listings, which is past the target stage. Worth watching for a cohort-3 call in case the criteria widen, but it is not a listing channel and should not consume effort.++---++## Non-OpenAI registries that actually merge++Not OpenAI-owned, so they do not answer the original question, but they are where MCP discovery genuinely happens and unlike the Cookbook they merge in days:++| Registry | Scale | Notes |+|---|---|---|+| [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | 89.6k stars | The reference MCP server list. The single highest-traffic MCP index. |+| [hashgraph-online/awesome-codex-plugins](https://github.com/hashgraph-online/awesome-codex-plugins) | 818 stars | Curated Codex and ChatGPT plugin list. Directly downstream of the plugin directory. |+| mcp.so | ~20k servers | Self-registration. |+| smithery.ai, glama.ai/mcp | Large | Form or self-registration. |++---++## Order of operations++1. Submit the **Showcase Gallery** form. Lowest cost, no gate, do it first.+2. Start **developer or business identity verification** on the OpenAI Platform, because it is a review that blocks the plugin submission and nothing else depends on us.+3. Audit tool annotations and x402 payment disclosure on the MCP server we intend to submit, then write the five positive and three negative test cases.+4. Submit the **plugin**.+5. **Rebase #2874**, post one clean status comment, stop pinging.+6. List on the MCP registries above in parallel. They cost minutes and do not depend on any OpenAI review.diff --git a/pages/aws/index.html b/pages/aws/index.htmlindex ebe7058ad..71e2f36ab 100644--- a/pages/aws/index.html+++ b/pages/aws/index.html@@ -243,11 +243,11 @@<div class="endpoints"><div class="endpoint"><code>POST /api/aws-marketplace/register</code>- <div class="desc">Fulfillment URL. Exchanges <code>x-amzn-marketplace-token</code> for a stable customer identifier via ResolveCustomer.</div>+ <div class="desc">Fulfillment URL. Exchanges <code>x-amzn-marketplace-token</code> via ResolveCustomer for the buyer's <code>LicenseArn</code> and <code>CustomerAWSAccountId</code>, the identifiers AWS issues to new SaaS integrations.</div></div><div class="endpoint"><code>POST /api/aws-marketplace/subscription</code>- <div class="desc">SNS notification webhook. Verifies AWS signature against the signing cert and processes subscribe / unsubscribe lifecycle events.</div>+ <div class="desc">Lifecycle webhook. Handles EventBridge agreement and license events relayed through an API destination, and legacy SNS notifications verified against the AWS signing cert.</div></div><div class="endpoint"><code>POST /api/aws-marketplace/link</code>diff --git a/public/changelog.json b/public/changelog.jsonindex ee70e7f94..d6b6ee538 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-17T14:48:00.518Z",+ "generated_at": "2026-08-17T15:18:34.436Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -402,6 +402,17 @@"infra"]},+ {+ "date": "2026-08-17",+ "type": "update",+ "title": "The AWS Marketplace integration is rebuilt for the rules AWS now enforces",+ "summary": "Subscribing to three.ws through AWS Marketplace would have failed on the first click, and nobody would have known why. AWS changed how a buyer is identified: for any product created since June 2026 it no longer sends the customer identifier our integration was built around, sends a license identifier instead, and delivers cancellation notices over a different channel entirely. The whole path is rebuilt on the new model, from the database up: subscriptions are keyed on the license AWS actually issues, lifecycle events arrive over the new channel with their own authentication, and a cancellation that could refer to more than one of a buyer's subscriptions now refuses to guess rather than cutting off access someone is still paying for. Signature checking also follows the algorithm the message declares instead of assuming one, so a genuine notice can no longer be thrown out as a forgery. Listing status is unchanged for now: the product still has to be created and reviewed on the AWS side, which is theirs to schedule, not ours.",+ "link": "/docs/aws-marketplace",+ "tags": [+ "fix",+ "infra"+ ]+ },{"date": "2026-08-17","type": "update",@@ -479,6 +490,16 @@"fix"]},+ {+ "date": "2026-08-17",+ "type": "update",+ "title": "The listings page now tracks the AI platform directories, starting with OpenAI",+ "summary": "The listings and distribution page tracked cloud marketplaces, startup programs, and chain dApp directories, but had nothing for the directories the AI platforms run themselves, which is where an MCP server gets listed as something you can install rather than something you can read about. There is now an AI Platform Directories section, and it opens with the three OpenAI surfaces: the plugin directory shared by ChatGPT and Codex, the Showcase Gallery, and the Cookbook, each with its current status stated plainly rather than implied. The three.ws MCP server at three.ws/api/mcp already meets the plugin directory's gating requirement, and the section says so.",+ "link": "/docs/listings",+ "tags": [+ "docs"+ ]+ },{"date": "2026-08-17","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex a3635aef4..3c9364edb 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -294,6 +294,14 @@<category>fix</category><description>The <agent-3d> runtime that sites load from three.ws is a single bundled file, and the production build never rebuilt it. It was copied from whatever the build machine happened to have on disk, which could be days older than the code being deployed, so a fix to the avatar element could ship everywhere else on the site and quietly not reach the SDK. The deploy now rebuilds that bundle from the same commit as the rest of the release, every time. Nothing to change on your side: existing embeds keep working and simply pick up the current runtime.</description></item>+ <item>+ <title>The AWS Marketplace integration is rebuilt for the rules AWS now enforces</title>+ <link>https://three.ws/docs/aws-marketplace</link>+ <guid isPermaLink="false">2026-08-17:The AWS Marketplace integration is rebuilt for the rules AWS now enforces</guid>+ <pubDate>Mon, 17 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>Subscribing to three.ws through AWS Marketplace would have failed on the first click, and nobody would have known why. AWS changed how a buyer is identified: for any product created since June 2026 it no longer sends the customer identifier our integration was built around, sends a license identifier instead, and delivers cancellation notices over a different channel entirely. The whole path is rebuilt on the new model, from the database up: subscriptions are keyed on the license AWS actually issues, lifecycle events arrive over the new channel with their own authentication, and a cancellation that could refer to more than one of a buyer's subscriptions now refuses to guess rather than cutting off access someone is still paying for. Signature checking also follows the algorithm the message declares instead of assuming one, so a genuine notice can no longer be thrown out as a forgery. Listing status is unchanged for now: the product still has to be created and reviewed on the AWS side, which is theirs to schedule, not ours.</description>+ </item><item><title>The Character Library counts its own characters, and fills the screen while it does</title><link>https://three.ws/character-library</link>@@ -350,6 +358,14 @@<category>docs</category><description>Anyone reading the listings and distribution page to see which programs back three.ws was getting an incomplete answer: the startup-programs table named Quicknode and Google Cloud but left NVIDIA Inception out entirely, even though the platform has been a member since July 2026 and every 3D generation lane runs on NVIDIA GPUs. The table now carries the NVIDIA row, saying what the membership is, what runs on the hardware behind it, and, as everywhere else on the site, that a startup program is not a partnership, an investment, or an endorsement.</description></item>+ <item>+ <title>The listings page now tracks the AI platform directories, starting with OpenAI</title>+ <link>https://three.ws/docs/listings</link>+ <guid isPermaLink="false">2026-08-17:The listings page now tracks the AI platform directories, starting with OpenAI</guid>+ <pubDate>Mon, 17 Aug 2026 12:00:00 GMT</pubDate>+ <category>docs</category>+ <description>The listings and distribution page tracked cloud marketplaces, startup programs, and chain dApp directories, but had nothing for the directories the AI platforms run themselves, which is where an MCP server gets listed as something you can install rather than something you can read about. There is now an AI Platform Directories section, and it opens with the three OpenAI surfaces: the plugin directory shared by ChatGPT and Codex, the Showcase Gallery, and the Cookbook, each with its current status stated plainly rather than implied. The three.ws MCP server at three.ws/api/mcp already meets the plugin directory's gating requirement, and the section says so.</description>+ </item><item><title>The Money Flow Map stops cutting its own table off on a phone, and a refresh no longer blanks the map</title><link>https://three.ws/flow</link>diff --git a/public/features.json b/public/features.jsonindex ed841f951..9d2491c61 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-17T14:48:00.511Z",+ "generated_at": "2026-08-17T15:18:34.415Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/scripts/aws-marketplace-provision.sh b/scripts/aws-marketplace-provision.shindex 307468081..060a4d29c 100755--- a/scripts/aws-marketplace-provision.sh+++ b/scripts/aws-marketplace-provision.sh@@ -1,67 +1,68 @@#!/usr/bin/env bash-# Provision AWS resources required for the AWS Marketplace SaaS listing.+# Provision the AWS-side resources the three.ws AWS Marketplace SaaS listing needs.#-# Creates:-# 1. SNS topic `three-ws-marketplace-subscription` (us-east-1)-# 2. Topic policy allowing aws-marketplace.amazonaws.com to publish-# 3. IAM user `three-ws-marketplace` with the four marketplace actions-# 4. Access key pair for that user+# Creates, idempotently:+# 1. IAM user `three-ws-marketplace` + inline policy + access key+# (ResolveCustomer / BatchMeterUsage / MeterUsage / GetEntitlements)+# 2. An EventBridge connection holding the shared secret header+# 3. An EventBridge API destination pointing at the lifecycle webhook+# 4. An IAM role EventBridge assumes to invoke that destination+# 5. An SQS dead-letter queue for relays the webhook rejects+# 6. An EventBridge rule on the default bus matching+# `source: aws.agreement-marketplace`, targeting the API destination+#+# Why EventBridge and not SNS: AWS Marketplace made the Concurrent Agreements+# integration mandatory for new SaaS products on 2026-06-01. Lifecycle events for+# a new listing land on the seller account's DEFAULT event bus, and SNS does not+# carry the LicenseArn those events are keyed on. The seller never supplies an+# SNS topic ARN either. AWS creates and owns the notification topics and hands+# them over on the product overview page AFTER product creation. An earlier+# version of this script created a `three-ws-marketplace-subscription` topic that+# nothing consumed; this version does not recreate it. If a previous run left one+# on the account, delete it (`aws sns delete-topic`) so nobody mistakes it for+# the listing's real notification topic.+#+# EventBridge cannot POST to an external HTTPS endpoint on its own, which is why+# the rule targets an API destination. The destination's connection attaches the+# `x-three-ws-marketplace-secret` header, and the webhook refuses any delivery+# that does not carry it, and that header is the whole authentication story for+# relay, so treat the generated secret like a credential.## Prereqs:-# - aws CLI v2 configured with admin creds on the seller AWS account-# - jq installed+# - aws CLI v2 configured with admin creds on seller account 155407237916+# - jq and openssl installed#-# Outputs are printed at the end; paste them into:-# - AMMP product page (SNS Topic ARN)-# - Vercel project env vars (AWS_MP_ACCESS_KEY_ID, AWS_MP_SECRET_ACCESS_KEY)+# Env overrides:+# AWS_MP_EVENT_SECRET reuse an existing secret instead of generating one+# WEBHOOK_URL override the target endpoint (default https://three.ws/...)#-# Idempotent: re-running is safe — existing resources are reused, only new-# access keys are issued if the user has fewer than 2 active keys.+# Re-running is safe: existing resources are updated in place, and a new access+# key is only issued when the user has room for one (AWS allows 2).set -euo pipefailREGION="us-east-1"-TOPIC_NAME="three-ws-marketplace-subscription"USER_NAME="three-ws-marketplace"POLICY_NAME="three-ws-marketplace-policy"+CONNECTION_NAME="three-ws-marketplace-connection"+DESTINATION_NAME="three-ws-marketplace-webhook"+RULE_NAME="three-ws-marketplace-agreements"+ROLE_NAME="three-ws-marketplace-eventbridge"+DLQ_NAME="three-ws-marketplace-dlq"+SECRET_HEADER="x-three-ws-marketplace-secret"+WEBHOOK_URL="${WEBHOOK_URL:-https://three.ws/api/aws-marketplace/subscription}"++for tool in aws jq openssl; do+ command -v "$tool" >/dev/null 2>&1 || { echo "[!] $tool is required" >&2; exit 1; }+doneACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"echo "[*] Provisioning on AWS account $ACCOUNT_ID in $REGION"-# ─── 1. SNS topic ────────────────────────────────────────────────────────────-echo "[*] Creating SNS topic $TOPIC_NAME (idempotent)"-TOPIC_ARN="$(aws sns create-topic \- --name "$TOPIC_NAME" \- --region "$REGION" \- --query TopicArn \- --output text)"-echo " Topic ARN: $TOPIC_ARN"--# ─── 2. Topic policy: allow AWS Marketplace to publish ───────────────────────-echo "[*] Applying topic policy (allow aws-marketplace.amazonaws.com to publish)"-POLICY_JSON=$(cat <<EOF-{- "Version": "2012-10-17",- "Statement": [{- "Sid": "AllowMarketplacePublish",- "Effect": "Allow",- "Principal": { "Service": "aws-marketplace.amazonaws.com" },- "Action": "sns:Publish",- "Resource": "$TOPIC_ARN",- "Condition": {- "StringEquals": { "aws:SourceAccount": "$ACCOUNT_ID" }- }- }]-}-EOF-)-aws sns set-topic-attributes \- --topic-arn "$TOPIC_ARN" \- --attribute-name Policy \- --attribute-value "$POLICY_JSON" \- --region "$REGION" >/dev/null--# ─── 3. IAM user + policy ────────────────────────────────────────────────────+EVENT_SECRET="${AWS_MP_EVENT_SECRET:-$(openssl rand -hex 32)}"+SECRET_WAS_GENERATED=$([ -n "${AWS_MP_EVENT_SECRET:-}" ] && echo "no" || echo "yes")++# ─── 1. IAM user + policy ────────────────────────────────────────────────────echo "[*] Creating IAM user $USER_NAME (idempotent)"if ! aws iam get-user --user-name "$USER_NAME" >/dev/null 2>&1; thenaws iam create-user --user-name "$USER_NAME" >/dev/null@@ -85,7 +86,6 @@ aws iam put-user-policy \}]}'-# ─── 4. Access keys ──────────────────────────────────────────────────────────EXISTING_KEYS="$(aws iam list-access-keys --user-name "$USER_NAME" --query 'length(AccessKeyMetadata)' --output text)"if [ "$EXISTING_KEYS" -ge 2 ]; thenecho "[!] User already has $EXISTING_KEYS access keys (AWS limit is 2)."@@ -96,27 +96,182 @@ elseKEY_OUTPUT="$(aws iam create-access-key --user-name "$USER_NAME")"fi+# ─── 2. EventBridge connection (carries the shared secret) ───────────────────+echo "[*] Creating EventBridge connection $CONNECTION_NAME (idempotent)"+AUTH_PARAMS="$(jq -nc --arg name "$SECRET_HEADER" --arg value "$EVENT_SECRET" \+ '{ApiKeyAuthParameters: {ApiKeyName: $name, ApiKeyValue: $value}}')"++if aws events describe-connection --name "$CONNECTION_NAME" --region "$REGION" >/dev/null 2>&1; then+ CONNECTION_ARN="$(aws events update-connection \+ --name "$CONNECTION_NAME" \+ --authorization-type API_KEY \+ --auth-parameters "$AUTH_PARAMS" \+ --region "$REGION" \+ --query ConnectionArn --output text)"+else+ CONNECTION_ARN="$(aws events create-connection \+ --name "$CONNECTION_NAME" \+ --description "Shared secret header for the three.ws AWS Marketplace lifecycle webhook" \+ --authorization-type API_KEY \+ --auth-parameters "$AUTH_PARAMS" \+ --region "$REGION" \+ --query ConnectionArn --output text)"+fi+echo " Connection: $CONNECTION_ARN"++# A connection becomes usable only once its secret has been stored. Targeting an+# AUTHORIZING destination fails at put-targets, so wait it out rather than+# leaving the operator to re-run the script and wonder why.+echo "[*] Waiting for the connection to become AUTHORIZED"+for _ in $(seq 1 30); do+ STATE="$(aws events describe-connection --name "$CONNECTION_NAME" --region "$REGION" --query ConnectionState --output text)"+ [ "$STATE" = "AUTHORIZED" ] && break+ sleep 2+done+[ "$STATE" = "AUTHORIZED" ] || { echo "[!] Connection stuck in state $STATE" >&2; exit 1; }++# ─── 3. API destination ──────────────────────────────────────────────────────+echo "[*] Creating API destination $DESTINATION_NAME → $WEBHOOK_URL (idempotent)"+if aws events describe-api-destination --name "$DESTINATION_NAME" --region "$REGION" >/dev/null 2>&1; then+ DESTINATION_ARN="$(aws events update-api-destination \+ --name "$DESTINATION_NAME" \+ --connection-arn "$CONNECTION_ARN" \+ --invocation-endpoint "$WEBHOOK_URL" \+ --http-method POST \+ --invocation-rate-limit-per-second 20 \+ --region "$REGION" \+ --query ApiDestinationArn --output text)"+else+ DESTINATION_ARN="$(aws events create-api-destination \+ --name "$DESTINATION_NAME" \+ --description "three.ws AWS Marketplace agreement + license lifecycle webhook" \+ --connection-arn "$CONNECTION_ARN" \+ --invocation-endpoint "$WEBHOOK_URL" \+ --http-method POST \+ --invocation-rate-limit-per-second 20 \+ --region "$REGION" \+ --query ApiDestinationArn --output text)"+fi+echo " Destination: $DESTINATION_ARN"++# ─── 4. Dead-letter queue ────────────────────────────────────────────────────+# A lifecycle event that the webhook 5xxs is the one event we cannot afford to+# drop: it is the difference between a cancelled buyer losing access and keeping+# it. EventBridge retries, then discards, unless a DLQ is attached.+echo "[*] Creating dead-letter queue $DLQ_NAME (idempotent)"+DLQ_URL="$(aws sqs create-queue --queue-name "$DLQ_NAME" --region "$REGION" --query QueueUrl --output text)"+DLQ_ARN="$(aws sqs get-queue-attributes --queue-url "$DLQ_URL" --attribute-names QueueArn --region "$REGION" --query 'Attributes.QueueArn' --output text)"+aws sqs set-queue-attributes \+ --queue-url "$DLQ_URL" \+ --region "$REGION" \+ --attributes "$(jq -nc --arg arn "$DLQ_ARN" --arg account "$ACCOUNT_ID" '{+ Policy: ({+ Version: "2012-10-17",+ Statement: [{+ Sid: "AllowEventBridgeDeadLetter",+ Effect: "Allow",+ Principal: { Service: "events.amazonaws.com" },+ Action: "sqs:SendMessage",+ Resource: $arn,+ Condition: { StringEquals: { "aws:SourceAccount": $account } }+ }]+ } | tostring)+ }')" >/dev/null+echo " DLQ: $DLQ_ARN"++# ─── 5. IAM role EventBridge assumes to invoke the destination ───────────────+echo "[*] Creating IAM role $ROLE_NAME (idempotent)"+TRUST_POLICY="$(jq -nc --arg account "$ACCOUNT_ID" '{+ Version: "2012-10-17",+ Statement: [{+ Effect: "Allow",+ Principal: { Service: "events.amazonaws.com" },+ Action: "sts:AssumeRole",+ Condition: { StringEquals: { "aws:SourceAccount": $account } }+ }]+}')"+if aws iam get-role --role-name "$ROLE_NAME" >/dev/null 2>&1; then+ aws iam update-assume-role-policy --role-name "$ROLE_NAME" --policy-document "$TRUST_POLICY" >/dev/null+else+ aws iam create-role --role-name "$ROLE_NAME" --assume-role-policy-document "$TRUST_POLICY" >/dev/null+fi+ROLE_ARN="$(aws iam get-role --role-name "$ROLE_NAME" --query 'Role.Arn' --output text)"++aws iam put-role-policy \+ --role-name "$ROLE_NAME" \+ --policy-name "invoke-api-destination" \+ --policy-document "$(jq -nc --arg arn "$DESTINATION_ARN" '{+ Version: "2012-10-17",+ Statement: [{ Effect: "Allow", Action: "events:InvokeApiDestination", Resource: $arn }]+ }')"+echo " Role: $ROLE_ARN"++# ─── 6. Rule on the default bus ──────────────────────────────────────────────+# AWS Marketplace delivers agreement and license events to the DEFAULT bus of+# the seller account. The pattern matches the whole source rather than an+# enumerated detail-type list so a new event type AWS adds still reaches the+# webhook, which acknowledges anything it takes no action on.+echo "[*] Creating rule $RULE_NAME on the default event bus (idempotent)"+RULE_ARN="$(aws events put-rule \+ --name "$RULE_NAME" \+ --event-bus-name default \+ --description "Relay AWS Marketplace agreement + license events to three.ws" \+ --event-pattern '{"source":["aws.agreement-marketplace"]}' \+ --state ENABLED \+ --region "$REGION" \+ --query RuleArn --output text)"+echo " Rule: $RULE_ARN"++# IAM role propagation can lag rule creation by a few seconds; put-targets fails+# with a validation error rather than retrying on its own.+sleep 5+aws events put-targets \+ --rule "$RULE_NAME" \+ --event-bus-name default \+ --region "$REGION" \+ --targets "$(jq -nc --arg arn "$DESTINATION_ARN" --arg role "$ROLE_ARN" --arg dlq "$DLQ_ARN" '[{+ Id: "three-ws-webhook",+ Arn: $arn,+ RoleArn: $role,+ DeadLetterConfig: { Arn: $dlq },+ RetryPolicy: { MaximumRetryAttempts: 10, MaximumEventAgeInSeconds: 3600 }+ }]')" >/dev/null+echo ""echo "════════════════════════════════════════════════════════════════════════"-echo "DONE. Paste these values into Vercel env vars + AMMP."+echo "DONE. Set these on the Cloud Run service (production env lives there)."echo "════════════════════════════════════════════════════════════════════════"echo ""-echo "AWS_MP_SNS_TOPIC_ARN=$TOPIC_ARN"echo "AWS_MP_REGION=$REGION"+if [ "$SECRET_WAS_GENERATED" = "yes" ]; then+ echo "AWS_MP_EVENT_SECRET=$EVENT_SECRET"+ echo " ^ generated now and stored in the EventBridge connection. Save it."+else+ echo "AWS_MP_EVENT_SECRET=<unchanged; reused from the environment>"+fiif [ -n "$KEY_OUTPUT" ]; then- ACCESS_KEY_ID="$(echo "$KEY_OUTPUT" | jq -r .AccessKey.AccessKeyId)"- SECRET_ACCESS_KEY="$(echo "$KEY_OUTPUT" | jq -r .AccessKey.SecretAccessKey)"- echo "AWS_MP_ACCESS_KEY_ID=$ACCESS_KEY_ID"- echo "AWS_MP_SECRET_ACCESS_KEY=$SECRET_ACCESS_KEY"- echo ""- echo "[!] The secret access key is shown ONCE. Save it now."+ echo "AWS_MP_ACCESS_KEY_ID=$(echo "$KEY_OUTPUT" | jq -r .AccessKey.AccessKeyId)"+ echo "AWS_MP_SECRET_ACCESS_KEY=$(echo "$KEY_OUTPUT" | jq -r .AccessKey.SecretAccessKey)"+ echo " ^ the secret access key is shown ONCE. Save it now."fiecho ""-echo "AWS_MP_PRODUCT_CODE = <assigned by AMMP after product creation>"+echo "AWS_MP_PRODUCT_CODE = <assigned by AMMP after product creation, add it last>"+echo ""+echo "Apply with (--update-env-vars MERGES; --set-env-vars would wipe every other var):"+echo " gcloud run services update three-ws-api --region us-central1 \\"+echo " --update-env-vars AWS_MP_ACCESS_KEY_ID=…,AWS_MP_SECRET_ACCESS_KEY=…,AWS_MP_REGION=$REGION,AWS_MP_EVENT_SECRET=…"echo ""echo "Next steps:"-echo " 1. Set the env vars above in Vercel (production + preview)"-echo " 2. In AMMP → Products → SaaS → Create new SaaS product"-echo " 3. Paste the SNS Topic ARN into the product's notification topic field"-echo " 4. AMMP will assign the AWS_MP_PRODUCT_CODE — add it to Vercel"-echo " 5. Submit limited (private) listing for end-to-end test"+echo " 1. Set the env vars above on Cloud Run."+echo " 2. AMMP → AI agents & tools products → Create, delivery method API-based (SaaS)."+echo " Registration URL: https://three.ws/api/aws-marketplace/register"+echo " Pricing: Free. EULA: Standard Contract (SCMP)."+echo " 3. AMMP assigns the product code. Set AWS_MP_PRODUCT_CODE on Cloud Run."+echo " 4. Check the product overview page for the notification configuration AWS"+echo " issued. If it also lists a legacy aws-mp-subscription-notification-<code>"+echo " SNS topic, set AWS_MP_SNS_TOPIC_ARN to THAT ARN (never a self-created one)"+echo " and add an HTTPS subscription to $WEBHOOK_URL as a secondary leg."+echo " 5. Subscribe from a test account while the listing is limited, and confirm"+echo " the register → welcome → issue-key round trip."+echo " 6. Request changes → Update visibility → Public (AWS Seller Operations"+echo " review, 7-10 business days)."diff --git a/src/aws-marketplace-welcome.js b/src/aws-marketplace-welcome.jsindex 1489a08e7..63c6648e0 100644--- a/src/aws-marketplace-welcome.js+++ b/src/aws-marketplace-welcome.js@@ -1,7 +1,10 @@// AWS Marketplace post-registration welcome page.//// Receives: ?customer=<id>&trial=<0|1>[&signup=1]-// - customer — stable CustomerIdentifier from ResolveCustomer+// - customer : opaque handle for the marketplace subscription record. AWS+// stopped populating CustomerIdentifier for new SaaS+// integrations, so this is the aws_marketplace_customers row id;+// the API also accepts a legacy CustomerIdentifier.// - trial — "1" when the subscription is a free trial// - signup — "1" when the user has no three.ws account yet//@@ -20,6 +23,7 @@ const wantsSignup = p.get('signup') === '1';const ERROR_MESSAGES = {token_expired: 'The AWS Marketplace registration link has expired. Please return to AWS Marketplace and subscribe again.',not_configured: 'AWS Marketplace subscriptions are temporarily unavailable on three.ws. Your AWS subscription is unaffected. Please open this link again shortly, or contact support if it persists.',+ unresolved_customer: 'AWS did not return an identity for this subscription, so we could not set it up. Your AWS subscription is unaffected. Please contact support and we will activate it manually.',link_failed: 'We could not link your AWS subscription to your account. Please try signing in again or contact support.',// Error codes returned by /api/aws-marketplace/link, so a rejected link says// what to do about it instead of "contact support" for every cause.