Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

fix(media-cors): answer the preflight the media routes advertise instead of 404ing it

nirholasef568deac070
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 216bc9755..e98b39d2a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,9 +8,11 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **A knock now holds the money until you actually get a reply**: Paying to reach someone used to send your money the instant the payment cleared, which meant an owner could take every knock and answer none, and you had no way to get it back. A new Solana program makes the payment conditional: it sits in a vault that only the knock itself controls, and exactly three things can happen to it. The owner answers inside the reply window and gets paid, the owner declines and you are refunded in full with no fee taken, or the window closes and anyone at all can trigger your refund. There is no admin key that can move a knock that is parked, the fee is capped at 10% in the program itself, and the fee you agreed to when you knocked cannot be raised on money that is already in escrow. Your message never touches the chain: only a fingerprint of it is stored, so either side can later prove what was sent without publishing it. Ten invariants covering every one of those promises run against the real compiled program on every test run. `[feature, security]`
- **Agent wallets can pay three.ws on X Layer again**: Buying agents that pay for a 3D generation on X Layer sign their payment with a wallet that carries an on-chain delegation, which is how every OKX agent wallet is built. Our checker judged those signatures with a contract call that answers a different question, so it turned away correct, fully funded payments and quoted the price a second time instead of doing the work. Payments are now checked the same way the stablecoin itself checks them, so a signed authorization that the network would honour is one we accept. `[fix]`
+- **Cross-origin 3D loads no longer break on a header your site never sent**: Embedding a three.ws avatar on your own site loads the model straight from us, and the site answers every origin. One case still failed: if your loader attached any extra header (a trace id, an auth token, anything a browser does not treat as standard), the browser first asked us for permission and we answered with a 404 page, so the model never loaded. That request is now answered properly, and the answer echoes exactly the headers you asked about. Alongside it, the media docs now spell out the three ways to read a model file and which one to pick: files under three.ws load directly, generated assets load directly from three.ws/cdn, and the /api/glb proxy is there for a URL whose host you cannot identify. (`/docs/media-api`) `[fix, docs]`
- **Knock somebody's door and get your money back if they never answer**: Paying to reach a stranger has meant paying first and hoping. The money left your wallet the moment the payment cleared, and if the person never replied, that was that. Doors can now take escrowed knocks instead: your payment sits in a vault on Solana that the recipient cannot touch until they actually answer you. If they answer, they are paid. If they decline, you get everything back and are charged nothing, because reading something and passing on it is not a service. And if they simply never respond before the window they set, anyone at all can trigger the refund and every cent comes back to you, so it does not depend on you remembering to chase it. three.ws holds no key that can move that money, and neither does anyone else. Door owners can turn the lane on in their knock settings and choose how long they get to reply, from an hour to a month. (`/docs/knock`) `[feature, security]`
- **The 3D services we sell to other agents quote one clear price, however they are asked**: Our four paid 3D generation services on the OKX.AI agent marketplace answer every caller with a price quote before any work happens. Two flaws in that quote are fixed. A request that arrived with no body and no content type was turned away with a formatting complaint instead of a price, and that is exactly how the marketplace's own compatibility check asks, so the check saw four services that looked like they had no payment set up at all. Separately, a request that named no specific tool got a quote listing the same payment network twice at two different prices, one of them wrong. Every unpaid request now receives a single unambiguous quote at the service's listed price, on each payment network it accepts. `[fix]`
- **The IBM partnership demos arm wherever the page is opened**: The live demo pages loaded their own payment script across the network by full address, so on any address other than the main site (a preview, a local run, a copy published on a partner domain) the browser refused it and the paid demos never armed. Each page now loads the copy it ships with. The publish-once page IBM hosts got the opposite fix: every file it pulls now carries our full address, so its language switcher no longer looks for a file on the host's own domain and comes back empty. (`/ibm/hello`) `[fix]`
+- **When the payment wallets run thin, the money now reaches the right one first**: three.ws pays its own on-chain fees from a funding wallet that tops up every engine below its floor. It ranked those engines purely by the size of their shortfall, so a top-up went to whichever wallet was missing the most, and the small wallet that pays the fee on every single payment could sit under its cutoff while the rail stayed shut. The payment wallets are now funded first, so a modest top-up restores settlement instead of a large one being required to reach it by accident. Two related repairs land with it: a wallet holding stablecoins but too little native currency to open the account a swap pays out into is now told exactly how much it is short, instead of retrying the same impossible conversion every half hour, and previewing the rebalancer with a dry run no longer executes real swaps. `[fix, infra]`
## 2026-09-03
diff --git a/ISSUES.md b/ISSUES.md
index efaac2c59..0826ff3d3 100644
--- a/ISSUES.md
+++ b/ISSUES.md
@@ -183,35 +183,53 @@ here; the code-quality items from that pass are not production issues.
9. **Live R2 CORS does not match `scripts/set-r2-cors.mjs`** (owner action:
one credential). CONFIRMED by measurement, not inference, and RE-CONFIRMED
- unchanged on 2026-09-02: `node scripts/set-r2-cors.mjs --probe` reads the
+ unchanged on 2026-09-04: `node scripts/set-r2-cors.mjs --probe` reads the
enforced policy from outside and exits 1 on this bucket. The probe needs no
credentials of any kind (it discovers the public host from a live listing
endpoint and the upload host from the auth-free `/api/forge-upload`), so
anyone can re-check this in one command.
+ Measured again 2026-09-04, every row from raw `curl` as well as the probe:
+
| Surface | Result |
|---|---|
- | Site edge, `three.ws/avatars/*.glb`, foreign origin | PASS, `access-control-allow-origin: *`. Not affected. |
- | Public bucket host `pub-*.r2.dev`, foreign origin GET/HEAD | FAIL. Body returns `200`, but with no `access-control-allow-origin`, so the browser discards it. Allowlisted origins DO get their origin echoed, which is how the live read rule is known to still be the old allowlist rather than the world-open `*`. |
- | Presigned `PUT` preflight on the S3 endpoint | Mixed. `204` for `three.ws`, `*.vercel.app`, `localhost:3000`; `403` for `www.three.ws`, `*.app.github.dev`, `localhost:5173`. |
+ | Site edge, `three.ws/avatars/*.glb`, foreign origin | PASS, `access-control-allow-origin: *` with `access-control-allow-methods: GET, HEAD, OPTIONS`. Not affected. |
+ | Site edge, first-party `three.ws/cdn/<key>`, foreign origin | PASS, `access-control-allow-origin: *`. Serves the same bucket objects, so it is a working route around the row below for any caller that has the object key. |
+ | Public bucket host `pub-*.r2.dev`, foreign origin GET/HEAD | FAIL. Body returns `200`, but with no `access-control-allow-origin`, so the browser discards it. Allowlisted origins DO get their origin echoed (`Vary: Origin`), which is how the live read rule is known to still be the old allowlist rather than the world-open `*`. Its `OPTIONS` preflight is a bare `403`. |
+ | Presigned `PUT` preflight on the S3 endpoint | Mixed, unchanged. `204` for `three.ws`, `*.vercel.app` (wildcard confirmed with a synthetic subdomain), `localhost:3000`; `403` for `www.three.ws`, `*.app.github.dev`, `localhost:5173`. |
The live policy is one allowlist rule serving both reads and writes
(`GET, PUT, HEAD, POST, DELETE`), predating the script's split into a
world-open `public-read` rule plus an origin-locked `browser-upload` rule.
Impact: user-generated avatars resolve to `pub-*.r2.dev` via
`publicUrl()` in [api/_lib/r2.js](api/_lib/r2.js), so third-party embeds
- reading those GLBs directly get a CORS failure. The `/api/glb` proxy is
- the working mitigation and stays correct after the fix; the docs now say
- which host needs it (docs/media-api.md, both embed tutorials).
+ reading those GLBs directly get a CORS failure. Two first-party paths are
+ the working mitigation and both stay correct after the fix: `/cdn/<key>`
+ (same bytes, CDN-cached, cheapest when the caller has the object key) and
+ the `/api/glb` proxy (for a URL of unknown host). The docs say which path
+ applies where (docs/media-api.md, docs/character-library.md, both embed
+ tutorials).
+
+ Fixed on the way past, 2026-09-04: the site edge advertised
+ `access-control-allow-methods: GET, HEAD, OPTIONS` on the media routes but
+ answered `OPTIONS` with the 404 page, because the filesystem phase of
+ [server/index.mjs](server/index.mjs) serves GET/HEAD only. A simple
+ cross-origin GET was unaffected (it sends no preflight), but any fetch
+ carrying a non-safelisted header was blocked. Those routes now answer the
+ preflight `204` from the headers the route already collected
+ (tests/server-media-cors-preflight.test.js). Ships with the next deploy.
Blocked on one credential, not on code. The only R2 token reachable from
this machine (`S3_*` in `.env`, identical to the Cloud Run service env,
bucket `chatty-storage`) is object-scoped and gets `403 AccessDenied` on
Get/PutBucketCors. Secret Manager holds no R2 or Cloudflare admin token
- (checked 2026-08-01 with working gcloud auth). As of 2026-09-02 this
- machine holds no R2 token at all and its gcloud session has expired, which
- changes nothing: the probe above still measures the live policy without
- credentials, and applying the fix still needs the admin token below.
+ (re-checked 2026-09-04: the project's only matching secret is
+ `s3-secret-access-key`, and the `three-ws-api` service carries no
+ `CLOUDFLARE_*` or `R2_*` variable, so the Cloudflare REST API is not an
+ alternative route in either). As of 2026-09-04 this machine's own `.env`
+ and `.env.local` hold no R2 token at all, which changes nothing: the probe
+ above still measures the live policy without credentials, and applying the
+ fix still needs the admin token below.
Owner: mint an "Admin Read & Write" R2 token scoped to the bucket (the
script prints the exact steps; its `--get` path explains this instead
of crashing), drop it in `.env.local` as `R2_ACCESS_KEY_ID`/`R2_SECRET_ACCESS_KEY`,
diff --git a/data/changelog.json b/data/changelog.json
index cf49f9dca..c50098815 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,16 @@
{
"$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-09-04",
+ "title": "Cross-origin 3D loads no longer break on a header your site never sent",
+ "summary": "Embedding a three.ws avatar on your own site loads the model straight from us, and the site answers every origin. One case still failed: if your loader attached any extra header (a trace id, an auth token, anything a browser does not treat as standard), the browser first asked us for permission and we answered with a 404 page, so the model never loaded. That request is now answered properly, and the answer echoes exactly the headers you asked about. Alongside it, the media docs now spell out the three ways to read a model file and which one to pick: files under three.ws load directly, generated assets load directly from three.ws/cdn, and the /api/glb proxy is there for a URL whose host you cannot identify.",
+ "tags": [
+ "fix",
+ "docs"
+ ],
+ "link": "/docs/media-api"
+ },
{
"date": "2026-09-04",
"title": "Knock somebody's door and get your money back if they never answer",
@@ -26408,6 +26418,15 @@
"tags": [
"fix"
]
+ },
+ {
+ "date": "2026-09-04",
+ "title": "When the payment wallets run thin, the money now reaches the right one first",
+ "summary": "three.ws pays its own on-chain fees from a funding wallet that tops up every engine below its floor. It ranked those engines purely by the size of their shortfall, so a top-up went to whichever wallet was missing the most, and the small wallet that pays the fee on every single payment could sit under its cutoff while the rail stayed shut. The payment wallets are now funded first, so a modest top-up restores settlement instead of a large one being required to reach it by accident. Two related repairs land with it: a wallet holding stablecoins but too little native currency to open the account a swap pays out into is now told exactly how much it is short, instead of retrying the same impossible conversion every half hour, and previewing the rebalancer with a dry run no longer executes real swaps.",
+ "tags": [
+ "fix",
+ "infra"
+ ]
}
]
}
diff --git a/docs/character-library.md b/docs/character-library.md
index 66a7bf624..319b85be3 100644
--- a/docs/character-library.md
+++ b/docs/character-library.md
@@ -109,7 +109,7 @@ The gallery and API are read-only consumers of a manifest built by a local pipel
3. `scripts/fetch-mixamo-avatar-thumbnails.mjs` stages the PNG thumbnails.
4. `scripts/build-mixamo-avatar-library.mjs` reads `public/avatars/mixamo/catalog.json`, merges the extra CC0 characters from `public/avatars/extra/characters.json`, and PUTs `avatars/library/manifest.json` to R2 (`--dry-run` prints without uploading).
-R2 CORS is configured by `scripts/set-r2-cors.mjs` so browsers can GET the GLBs cross-origin. The live bucket policy is an origin allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`) that predates the world-open read rule now in that script, so a GLB loaded straight from the CDN on any other origin fails with no `access-control-allow-origin` header. Measure the live policy with `node scripts/set-r2-cors.mjs --probe`; until it is corrected, embeds on third-party origins should route the GLB through [`/api/glb`](./media-api.md#same-origin-glb-proxy), as [the embed tutorial](./tutorials/character-library-to-embed.md) does.
+R2 CORS is configured by `scripts/set-r2-cors.mjs` so browsers can GET the GLBs cross-origin. The live bucket policy is an origin allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`) that predates the world-open read rule now in that script, so a GLB loaded straight from the bucket host on any other origin fails with no `access-control-allow-origin` header (re-measured 2026-09-04). Measure the live policy yourself with `node scripts/set-r2-cors.mjs --probe`, which needs no credentials. Until the bucket is corrected, embeds on third-party origins should load the GLB from a first-party path instead: [`/cdn/<key>`](./media-api.md#how-bucket-objects-are-served-cdnkey) when you have the object key, or [`/api/glb`](./media-api.md#same-origin-glb-proxy) when all you have is the manifest URL, as [the embed tutorial](./tutorials/character-library-to-embed.md) does.
## Related
diff --git a/docs/media-api.md b/docs/media-api.md
index b59c26edc..b35de821e 100644
--- a/docs/media-api.md
+++ b/docs/media-api.md
@@ -250,26 +250,36 @@ If `draco=1` comes back `500 transcode_failed` with `draco.createCompressedPrimi
### When you need it, and when you do not
It depends entirely on which host serves the `.glb`, not on which origin you
-are loading from. Measured 2026-08-01:
+are loading from. Re-measured 2026-09-04, unchanged since 2026-08-01:
| Source host | Cross-origin fetch | Use the proxy? |
|---|---|---|
| `https://three.ws/...` (built-in library avatars, `/avatars/*`, anything under the site) | `access-control-allow-origin: *` on every origin | No. Fetch it directly. |
-| `https://pub-*.r2.dev/...` (the media bucket: user-generated avatars, forge output, character-library GLBs, the target of `/api/avatar/render`'s `302`) | Header only for origins on the bucket allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`). Every other origin gets no header and the fetch dies. | Yes. |
+| `https://three.ws/cdn/<key>` (the same bucket objects, served first-party) | `access-control-allow-origin: *` on every origin | No. Fetch it directly, and prefer this over the proxy. |
+| `https://pub-*.r2.dev/...` (the media bucket's own host: user-generated avatars, forge output, character-library GLBs, the target of `/api/avatar/render`'s `302`) | Header only for origins on the bucket allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`). Every other origin gets a `200` with no `access-control-allow-origin`, so the browser discards the bytes. | Yes, or rewrite the URL to `/cdn/<key>`. |
So a `<model-viewer>` embed on a partner site, a Jupyter/Colab notebook, a
Codespaces preview, or a Vite dev server on `localhost:5173` can read
-`three.ws` URLs directly but needs the proxy for bucket URLs. If you cannot
-tell which one an API handed you, the proxy is always safe: passing it a
-`three.ws` URL costs one extra hop on a cold CDN cache and nothing after.
+`three.ws` URLs directly but needs the proxy for `pub-*.r2.dev` URLs.
+
+Two ways out of a bucket URL, and they are not equivalent:
+
+- **[`/cdn/<key>`](#how-bucket-objects-are-served-cdnkey)** is the cheaper one
+ when you have the object key (everything after the bucket host). Same bytes,
+ first-party, CORS-open, and CDN-cached for 30 days at the edge.
+- **`/api/glb?src=<url>`** is the one to reach for when all you have is a URL
+ someone handed you, including a URL on a host that is not ours at all. It is
+ always safe: passing it a `three.ws` URL costs one extra hop on a cold CDN
+ cache and nothing after.
The bucket allowlist is the deliberate part for uploads (presigned `PUT`s stay
origin-locked) and an accident for reads, which are meant to be world-open.
`scripts/set-r2-cors.mjs` holds the corrected policy and
-`node scripts/set-r2-cors.mjs --probe` measures what is live; see
-[`scripts/README.md`](../scripts/README.md). Even once reads are world-open,
-this proxy stays the right answer for callers that want one URL shape and no
-dependency on a third-party host's headers.
+`node scripts/set-r2-cors.mjs --probe` measures what is live from any machine,
+with no bucket credentials; see [`scripts/README.md`](../scripts/README.md).
+Even once reads are world-open, both first-party paths stay the right answer for
+callers that want one URL shape and no dependency on a third-party host's
+headers.
Safe by construction: upstream objects are already public and keyless, and
the fetch runs through the SSRF-hardened fetcher (scheme allowlist, DNS
diff --git a/docs/tutorials/character-library-to-embed.md b/docs/tutorials/character-library-to-embed.md
index 038343516..8d49c6fcc 100644
--- a/docs/tutorials/character-library-to-embed.md
+++ b/docs/tutorials/character-library-to-embed.md
@@ -313,7 +313,7 @@ Then use that URL in the element:
Safe by construction: the upstream objects are already public and keyless, and the proxy fetch runs through an SSRF-hardened client (scheme allowlist, DNS pinning, private-address blocklist, redirect re-validation, 30 MB cap, 20 second timeout). It is a CORS shim, not an open proxy. The response is cached immutably, so the proxy costs one hop on a cold cache and nothing after.
-One exception worth knowing, so you do not reach for the proxy reflexively: this applies to the `pub-*.r2.dev` CDN host, which is where every manifest GLB lives. Files served from `three.ws` itself (`https://three.ws/avatars/cesium-man.glb` and the rest of the built-in set) already answer every origin with `access-control-allow-origin: *`, measured 2026-08-01. Those load directly, no proxy. Check the host in the URL, not the symptom.
+One exception worth knowing, so you do not reach for the proxy reflexively: this applies to the `pub-*.r2.dev` bucket host, which is where every manifest GLB lives. Files served from `three.ws` itself (`https://three.ws/avatars/cesium-man.glb` and the rest of the built-in set) already answer every origin with `access-control-allow-origin: *`, re-measured 2026-09-04. So does `https://three.ws/cdn/<key>`, which serves the very same bucket objects first-party. Those load directly, no proxy. Check the host in the URL, not the symptom.
Use the proxied URL from the start and you never have a localhost-only success to unlearn. The same shim is what makes these GLBs loadable in a Jupyter or Colab notebook and on a dev server running on a non-standard port.
diff --git a/docs/tutorials/render-avatar-images.md b/docs/tutorials/render-avatar-images.md
index e27202349..b09397b80 100644
--- a/docs/tutorials/render-avatar-images.md
+++ b/docs/tutorials/render-avatar-images.md
@@ -455,7 +455,8 @@ Sometimes an image is not enough and you want the actual interactive model. Load
Two hosts, two answers (measured 2026-08-01):
- **`https://three.ws/...`**, which is where the built-in library avatars live (`/avatars/selfie-girl.glb` and friends), answers every origin with `access-control-allow-origin: *`. Load these directly. No proxy needed.
-- **`https://pub-*.r2.dev/...`**, the media CDN behind every avatar you or your users generated, answers only origins on its allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`). From `https://your-site.com`, from Jupyter, or from a Vite server on `localhost:5173`, a direct load fails with a CORS error and an empty canvas. That is the URL `/api/avatar/render` redirects to and the URL the avatar APIs return for user avatars.
+- **`https://pub-*.r2.dev/...`**, the media bucket's own host, behind every avatar you or your users generated, answers only origins on its allowlist (`three.ws`, `*.vercel.app`, `localhost:3000`; re-measured 2026-09-04). From `https://your-site.com`, from Jupyter, or from a Vite server on `localhost:5173`, a direct load fails with a CORS error and an empty canvas. That is the URL `/api/avatar/render` redirects to and the URL the avatar APIs return for user avatars.
+- **`https://three.ws/cdn/<key>`** serves those same bucket objects first-party, with `access-control-allow-origin: *` on every origin. If you have the object key (everything after the bucket host), this loads directly and needs nothing below.
`GET /api/glb?src=<url>` exists for the second case. It streams any public GLB back with `access-control-allow-origin: *`, and it is harmless on the first, so if you cannot tell which host a URL points at, use it. The example below proxies a `three.ws` URL that would also load directly, because it is the pattern that keeps working when you swap in a generated avatar:
diff --git a/prompts/finish/backlog-PROGRESS.md b/prompts/finish/backlog-PROGRESS.md
index 77e9be3e5..27c9a72b3 100644
--- a/prompts/finish/backlog-PROGRESS.md
+++ b/prompts/finish/backlog-PROGRESS.md
@@ -1396,3 +1396,183 @@ The one definition-of-done line not met to the letter: the two healthz reads are
apart rather than an hour. Both are an order of magnitude under the threshold and the sensor
itself scores the subsystem `ok`, so the line's intent holds; noted here rather than papered
over. Retired the order file and dropped its row from the index in the same commit.
+
+## 2026-09-04: 07 bnb-testnet-deploys (re-verified again; still one human faucet claim, and nothing else)
+
+Measured, all against the current tree rather than carried forward from the 2026-09-02 entry:
+
+- `forge script script/DeployWorldMoves.s.sol:DeployWorldMoves --rpc-url https://data-seed-prebsc-1-s1.bnbchain.org:8545 --sender 0x1C49...3871`
+ simulates green: 566,068 gas at 0.1 gwei = 0.0000566068 BNB.
+- `forge script script/DeployGreenfieldVault.s.sol:DeployGreenfieldVault` against the same live
+ chain-97 RPC simulates green against the real testnet PermissionHub / CrossChain / ObjectHub:
+ 1,711,362 gas = 0.0001711362 BNB. Both numbers are identical to the two previous re-reads.
+- `forge test`: 19/19 WorldMoves, 41/41 GreenfieldVault.
+- `cast balance 0x1C4918894dfA5eE11cfF9629B458b5169Cfa3871` is **0** on three independent
+ chain-97 lanes (`data-seed-prebsc-1-s1`, `bsc-testnet.drpc.org`,
+ `bsc-testnet-rpc.publicnode.com`), each confirmed to answer chainId 97 first.
+- `node scripts/bnb-testnet-deploy-prove.mjs` (preflight, signs nothing) renders the spend table
+ and stops on the unfunded deployer, as designed.
+- `curl -s 'https://three.ws/api/bnb/world-config?network=testnet'` returns
+ `address: null, deployed: false` to an anonymous caller. `WORLD_MOVES_ADDRESS_TESTNET` is
+ confirmed absent from the `three-ws-api` service env.
+
+Did:
+
+- Re-proved the whole `--broadcast` path end to end against a local `anvil --chain-id 97`,
+ running the real `scripts/bnb-testnet-deploy-prove.mjs --broadcast` (not a hand-assembled
+ sequence), so a funded run will not be the first execution of this code. Both contracts
+ deployed, then 1 `join`, 3 `move`, 1 `leave` mined through the real
+ `api/_lib/bnb/world-moves.js` sender, decoded live by `src/bnb/world-presence-reader.js`
+ (1 Joined, 3 Moved, 1 Left), `createGhostTracker` at 1 ghost before the leave and 0 after.
+ Local addresses deliberately not recorded: they are anvil-local.
+- Re-checked the faucet blocker from scratch across four claim paths instead of citing the
+ earlier finding. All four are human-gated: the official `testnet.bnbchain.org/faucet-smart`
+ serves its HTML page at the `/api/v1/faucet` path rather than a claim API; ghostchain.io and
+ faucet.zalalena.com both load Cloudflare Turnstile / hCaptcha; tokentool.bitbond.com needs a
+ wallet connect plus a completed third-party profile. No agent path exists.
+- Corrected one stale fact the index carried: `gcloud` is authenticated in this workspace again
+ (the 2026-09-01 snapshot recorded it dead), so the post-deploy `--update-env-vars` step needs
+ no further unblocking.
+- Updated `contracts/DEPLOYMENTS.md` with the 2026-09-04 re-verification in both the WorldMoves
+ and GreenfieldVault sections.
+
+Left, and it is the same single line it has been since 2026-07-08: **fund**
+`0x1C4918894dfA5eE11cfF9629B458b5169Cfa3871` **with tBNB** at
+https://www.bnbchain.org/en/testnet-faucet (the owner, because the faucet is captcha-gated).
+0.000227743 BNB covers both deploys; any faucet drip is far more than enough. After funding,
+one command finishes the order end to end:
+
+```
+node scripts/bnb-testnet-deploy-prove.mjs --broadcast
+```
+
+which deploys both contracts, proves the live sender / reader / ghost paths against what it just
+deployed, and prints the exact `--update-env-vars` line for `WORLD_MOVES_ADDRESS_TESTNET`.
+The work-order file stays on disk: this is a partial, not a close.
+
+## 2026-09-04: 05 R2 bucket CORS (re-measured, edge preflight fixed, still one credential short)
+
+Measured, all three surfaces, from raw `curl` as well as
+`node scripts/set-r2-cors.mjs --probe` (which exits 1 and needs no credentials):
+
+| Surface | Result |
+|---|---|
+| 1. Public bucket host `pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev`, GET from `https://example.org` | FAIL. `200`, no `access-control-allow-origin`. Allowlisted origins get their own origin echoed with `Vary: Origin`. `OPTIONS` on it is a bare `403`. |
+| 2. Presigned `PUT` preflight on `chatty-storage.<account>.r2.cloudflarestorage.com` | MIXED, identical to 2026-08-01. `204` for `three.ws`, `3d-agent.vercel.app`, a synthetic `*.vercel.app` subdomain, `localhost:3000`; `403` for `www.three.ws`, `*.app.github.dev`, `localhost:5173`, `example.org`. |
+| 3. Site edge `three.ws/avatars/cesium-man.glb` | PASS on GET/HEAD from any origin (`access-control-allow-origin: *`). Its advertised `OPTIONS` preflight answered `404`. |
+| Bonus, first-party `three.ws/cdn/<key>` | PASS from any origin. Same bucket bytes, CDN-cached, so it routes around row 1 for any caller holding the object key. |
+
+So the live bucket is still one allowlist rule serving both reads and writes.
+Item confirmed again, not closed.
+
+Did: fixed row 3's preflight in [server/index.mjs](../../server/index.mjs). The
+media routes in `vercel.json` advertise `access-control-allow-methods: GET, HEAD,
+OPTIONS`, but the filesystem phase serves GET/HEAD only, so `OPTIONS` fell
+through to the 404 page and any cross-origin fetch carrying a non-safelisted
+header was blocked even though the GET is world-open. Those routes now answer
+`204` from the headers the route already collected, echoing
+`access-control-request-headers` and `no-store` so a shared cache cannot hold one
+preflight for a different header set; `/api/` paths still reach their own
+handlers. Covered by `tests/server-media-cors-preflight.test.js` (5 tests).
+Refreshed the measured claims and dates in `docs/media-api.md`,
+`docs/character-library.md` and both embed tutorials, and added `/cdn/<key>` to
+the "which path do I use" guidance beside `/api/glb` (the proxy stays, and stays
+the right advice for a URL whose host you cannot identify). ISSUES.md item 9
+carries the 2026-09-04 table. Changelog entry added; `npm run audit:docs` clean.
+
+The two cleanups this order asked for were already done on 2026-08-01 and were
+verified still true rather than redone: `scripts/set-r2-cors.mjs` names
+`.env.local` and `scripts/read-service-env.mjs` and explicitly warns off
+`vercel env pull`, and the `/api/glb` docs already said which host needs it.
+
+Left: applying the bucket policy, and only that. Re-checked the credential
+situation from scratch on 2026-09-04, and it is worse than 2026-08-01, not
+better: this machine's `.env` holds three unrelated vars and `.env.local` holds
+only `DATABASE_URL`, the `three-ws-api` service carries no `R2_*` or
+`CLOUDFLARE_*` variable at all (`node scripts/read-service-env.mjs --names`), and
+the project's only matching Secret Manager entry is `s3-secret-access-key`, the
+object-scoped key. There is therefore no S3 admin path and no Cloudflare REST API
+path either. Owner: mint an "Admin Read & Write" R2 token scoped to
+`chatty-storage`, put it in `.env.local` as `R2_ACCESS_KEY_ID` /
+`R2_SECRET_ACCESS_KEY`, run `node scripts/set-r2-cors.mjs`, confirm with
+`--probe` (it should print "Live policy matches POLICY in this script").
+
+One alternative the owner may prefer, noted and deliberately NOT taken here:
+`S3_PUBLIC_DOMAIN` on the Cloud Run service is the `pub-*.r2.dev` host, and
+`publicUrl()` in [api/_lib/r2.js](../../api/_lib/r2.js) builds every public media
+URL from it. Pointing it at `https://three.ws/cdn` would make every emitted URL
+first-party and world-readable in one config change, with no R2 token. It is not
+free: it re-points every media URL the platform hands out, and
+`keyFromPublicUrl()` would stop resolving the r2.dev URLs already stored in
+columns like `preview_image_url`, so deletion paths would need a migration or a
+dual-prefix match first. That is an architecture decision, not a CORS fix, so it
+is the owner's call.
+
+## 2026-09-04: 01 x402 settle runway
+Measured, all of it live:
+- `curl -s https://three.ws/api/version` → `c2148462e`, revision `three-ws-api-00412-s7l`,
+ built 2026-09-03 19:16 UTC. 25 commits behind `main`.
+- `curl -s https://three.ws/api/healthz` → **HTTP 500**, so the DoD's settle-rate line
+ cannot be read at all right now. Cause, from
+ `gcloud logging read '... "healthz"' --freshness=1h`:
+ `Cannot find module '/app/services/home-relay/src/token.js' imported from
+ /app/api/_lib/home/relay.js` on every request. Already fixed in the tree by
+ `d668ceece` (.gcloudignore never re-included `services/`); that commit is NOT in the
+ running revision, so healthz recovers on the next deploy. Not this order's bug, but it
+ gates this order's verification.
+- `curl -s https://three.ws/api/x402/runway-lab` → sponsor `Wwwu…T3WwW` 0.001508 SOL,
+ spendable 0; ring payer `X4o2…stML` 0.001253 SOL; **982 of 1003 paid attempts in 24 h
+ refused, every one of them `cause: floor`, example
+ `fee_wallet_below_floor:1253408<2000000`**. That lamport figure is the RING PAYER's,
+ not the sponsor's: the ring runs self-pay, so `decoded.feePayer` is the payer and it is
+ the payer's floor that is shutting the rail. `fee_runway_exhausted` no longer appears in
+ the 24 h refusal book at all.
+- `POST /api/cron/treasury-topup?dry=1` → `master_deficit_sol` 0.308492 (non-zero, so
+ lever 1 is doing its job), `spendable_sol` 0, `plan: []`, `reclaim.reclaimedSol` 0,
+ `agent_reclaim`: 110 wallets `at_or_below_floor`, 2 `failed` at stage `recover`
+ (Atlas #22 0.0684 SOL, Echo #22 0.0545 SOL, both `secret_undecryptable`, the retired
+ key from `docs/ops/wallet-key-migration.md`). Nothing reclaimable exists.
+- Secret Manager has exactly one version of `wallet-encryption-key` (created 2026-09-02)
+ and no `WALLET_ENCRYPTION_KEY_PREVIOUS` on the service, so the 0.49 SOL sealed under the
+ retired key stays sealed. Re-confirmed rather than re-litigated.
+
+Found and fixed three defects that decide whether owner capital actually restores the rail:
+
+1. **A thin top-up funded the wrong wallet.** `planTopUps` ordered targets by absolute
+ deficit only. Production's two targets are the relayer/treasury bundle (deficit 0.983
+ SOL) and the ring payer (deficit 0.179 SOL), so simulating the real planner against the
+ real balances shows an owner sending 0.1, 0.2 or 0.5 SOL putting **all** of it in the
+ bundle and leaving the payer at 0.001253 SOL, still under its 0.002 hard floor: the
+ settle rate would not have moved until roughly 1 SOL landed. The x402 sponsor and payer
+ specs now carry `settleCritical: true` (`api/_lib/solana-signers.js`), `treasury-topup`
+ merges the flag across specs sharing a pubkey, and `planTopUps` funds settle-critical
+ wallets first. Same simulation after the change: 0.1 SOL goes to the payer and clears
+ its floor.
+2. **`?dry=1` on `economy-rebalance` executed live swaps.** Its only non-signing path was
+ being disarmed, and production is armed, so previewing it here built, signed and
+ submitted a real swap (it died in simulation, so nothing moved and no signature
+ landed). It now honors `?dry=1` the way `treasury-topup` always has.
+3. **The rebalancer re-planned a swap that cannot execute, every 30 minutes.** The ring
+ payer holds 4.18 USDC and 1,253,408 lamports; a `usdc->sol` swap must fund the
+ 1,855,569-lamport rent for the wSOL account it creates (verified on chain: the payer
+ has no wSOL account, `getMinimumBalanceForRentExemption(165)` = 1,855,569), so every
+ run died inside the ATA `CreateIdempotent` with system error `0x1` under a truncated
+ `failed`. `planRebalance` now skips with `below_swap_rent:1253408<1870569`, waived when
+ a wSOL account already exists. This is why the payer cannot self-rescue from its own
+ USDC float: it is ~0.0006 SOL short of being able to spend the 4.18 USDC it holds.
+
+Did: the three fixes above plus five tests (`tests/economy-master.test.js`,
+`tests/economy-rebalance.test.js`), the skip-reason split
+(`master_insufficient_spendable` vs `run_cap_reached`, which had made an empty master read
+as a cap to raise), `docs/economy-master.md` (guard table, skip-reason table, dry-run
+section, invariant 4), and a `data/changelog.json` entry. `npm run gate` green.
+
+Left, and all of it is the owner's:
+- **Capital.** Send SOL to the economy master `WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW`
+ and nowhere else. 0.1 SOL now reaches the ring payer first and restarts settlement;
+ 2 SOL clears the fleet's 1.47 SOL deficit with real runway. Stop-and-ask gate 1.
+- **The deploy.** All three fixes, and the healthz 500 fix `d668ceece`, are in the tree and
+ absent from revision 00412. Until it ships, funding the master still hits the old
+ ordering.
+- DoD lines 1 to 3 stay open behind those two. Lines 4 to 6 (recurrence guard + test,
+ changelog, this log) are done. The prompt file stays on disk.
diff --git a/public/changelog.json b/public/changelog.json
index 6b5827b10..1520f754b 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-04T02:00:38.891Z",
+ "generated_at": "2026-09-04T06:25:16.108Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -27,6 +27,17 @@
"fix"
]
},
+ {
+ "date": "2026-09-04",
+ "type": "update",
+ "title": "Cross-origin 3D loads no longer break on a header your site never sent",
+ "summary": "Embedding a three.ws avatar on your own site loads the model straight from us, and the site answers every origin. One case still failed: if your loader attached any extra header (a trace id, an auth token, anything a browser does not treat as standard), the browser first asked us for permission and we answered with a 404 page, so the model never loaded. That request is now answered properly, and the answer echoes exactly the headers you asked about. Alongside it, the media docs now spell out the three ways to read a model file and which one to pick: files under three.ws load directly, generated assets load directly from three.ws/cdn, and the /api/glb proxy is there for a URL whose host you cannot identify.",
+ "link": "/docs/media-api",
+ "tags": [
+ "fix",
+ "docs"
+ ]
+ },
{
"date": "2026-09-04",
"type": "update",
@@ -58,6 +69,17 @@
"fix"
]
},
+ {
+ "date": "2026-09-04",
+ "type": "update",
+ "title": "When the payment wallets run thin, the money now reaches the right one first",
+ "summary": "three.ws pays its own on-chain fees from a funding wallet that tops up every engine below its floor. It ranked those engines purely by the size of their shortfall, so a top-up went to whichever wallet was missing the most, and the small wallet that pays the fee on every single payment could sit under its cutoff while the rail stayed shut. The payment wallets are now funded first, so a modest top-up restores settlement instead of a large one being required to reach it by accident. Two related repairs land with it: a wallet holding stablecoins but too little native currency to open the account a swap pays out into is now told exactly how much it is short, instead of retrying the same impossible conversion every half hour, and previewing the rebalancer with a dry run no longer executes real swaps.",
+ "link": null,
+ "tags": [
+ "fix",
+ "infra"
+ ]
+ },
{
"date": "2026-09-03",
"type": "launch",
diff --git a/public/changelog.xml b/public/changelog.xml
index 5e30c208d..d05b4c7d1 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -22,6 +22,14 @@
<category>fix</category>
<description>Buying agents that pay for a 3D generation on X Layer sign their payment with a wallet that carries an on-chain delegation, which is how every OKX agent wallet is built. Our checker judged those signatures with a contract call that answers a different question, so it turned away correct, fully funded payments and quoted the price a second time instead of doing the work. Payments are now checked the same way the stablecoin itself checks them, so a signed authorization that the network would honour is one we accept.</description>
</item>
+ <item>
+ <title>Cross-origin 3D loads no longer break on a header your site never sent</title>
+ <link>https://three.ws/docs/media-api</link>
+ <guid isPermaLink="false">2026-09-04:Cross-origin 3D loads no longer break on a header your site never sent</guid>
+ <pubDate>Fri, 04 Sep 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>Embedding a three.ws avatar on your own site loads the model straight from us, and the site answers every origin. One case still failed: if your loader attached any extra header (a trace id, an auth token, anything a browser does not treat as standard), the browser first asked us for permission and we answered with a 404 page, so the model never loaded. That request is now answered properly, and the answer echoes exactly the headers you asked about. Alongside it, the media docs now spell out the three ways to read a model file and which one to pick: files under three.ws load directly, generated assets load directly from three.ws/cdn, and the /api/glb proxy is there for a URL whose host you cannot identify.</description>
+ </item>
<item>
<title>Knock somebody's door and get your money back if they never answer</title>
<link>https://three.ws/docs/knock</link>
@@ -46,6 +54,14 @@
<category>fix</category>
<description>The live demo pages loaded their own payment script across the network by full address, so on any address other than the main site (a preview, a local run, a copy published on a partner domain) the browser refused it and the paid demos never armed. Each page now loads the copy it ships with. The publish-once page IBM hosts got the opposite fix: every file it pulls now carries our full address, so its language switcher no longer looks for a file on the host's own domain and comes back empty.</description>
</item>
+ <item>
+ <title>When the payment wallets run thin, the money now reaches the right one first</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-09-04:When the payment wallets run thin, the money now reaches the right one first</guid>
+ <pubDate>Fri, 04 Sep 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>three.ws pays its own on-chain fees from a funding wallet that tops up every engine below its floor. It ranked those engines purely by the size of their shortfall, so a top-up went to whichever wallet was missing the most, and the small wallet that pays the fee on every single payment could sit under its cutoff while the rail stayed shut. The payment wallets are now funded first, so a modest top-up restores settlement instead of a large one being required to reach it by accident. Two related repairs land with it: a wallet holding stablecoins but too little native currency to open the account a swap pays out into is now told exactly how much it is short, instead of retrying the same impossible conversion every half hour, and previewing the rebalancer with a dry run no longer executes real swaps.</description>
+ </item>
<item>
<title>Docs · Connect a home that is only on your network</title>
<link>https://three.ws/docs/home-relay</link>
diff --git a/public/features.json b/public/features.json
index 165c18142..10c973c4b 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-04T02:00:38.878Z",
+ "generated_at": "2026-09-04T06:25:16.026Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
diff --git a/server/index.mjs b/server/index.mjs
index 18ee584ce..48479dbb5 100644
--- a/server/index.mjs
+++ b/server/index.mjs
@@ -417,6 +417,36 @@ app.use(async (req, res) => {
}
}
+ // CORS preflight for the static media routes. Those rules advertise
+ // `access-control-allow-methods: GET, HEAD, OPTIONS`, but the filesystem
+ // phase below only serves GET/HEAD, so an OPTIONS request fell through to
+ // the 404 and every cross-origin fetch carrying a non-safelisted header
+ // (a GLTFLoader with setRequestHeader, a fetch with an auth or tracing
+ // header) was blocked by the browser even though the GET itself is
+ // world-open. Answer the preflight from the headers the route already
+ // collected. /api/ paths are excluded: their handlers own their own CORS.
+ if (
+ req.method === 'OPTIONS' &&
+ !currentPath.startsWith('/api/') &&
+ collected['access-control-allow-methods']
+ ) {
+ const requested = req.headers['access-control-request-headers'];
+ res
+ .status(204)
+ .set(collected)
+ .set({
+ 'access-control-allow-headers': requested || '*',
+ 'access-control-max-age': '86400',
+ // The route's own long cache-control belongs to the asset, not to
+ // this negotiation: a shared cache holding one preflight would
+ // answer it for a different requested-header set.
+ 'cache-control': 'no-store',
+ vary: 'Origin, Access-Control-Request-Headers',
+ })
+ .end();
+ return;
+ }
+
// Functions phase: anything routed under /api/ is a serverless handler.
if (currentPath.startsWith('/api/')) {
// Vercel parity: a handler behind a dest rewrite sees the dest's query
diff --git a/tests/server-media-cors-preflight.test.js b/tests/server-media-cors-preflight.test.js
new file mode 100644
index 000000000..233b4ce1c
--- /dev/null
+++ b/tests/server-media-cors-preflight.test.js
@@ -0,0 +1,77 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { startTestServer } from './helpers/test-server.js';
+
+// The static media routes in vercel.json advertise
+// `access-control-allow-methods: GET, HEAD, OPTIONS` so third-party sites can
+// load our GLBs, animations, and the agent-3d bundle. The filesystem phase of
+// server/index.mjs only serves GET/HEAD, so the OPTIONS request those headers
+// invite fell through to the 404 page. A simple cross-origin GET still worked
+// (no preflight is sent for one), but any fetch carrying a non-safelisted
+// header preflighted, got a 404, and was blocked by the browser: the advertised
+// contract and the served one disagreed.
+//
+// Measured 2026-09-04 against production, before the fix:
+// OPTIONS https://three.ws/avatars/cesium-man.glb -> HTTP/2 404 (with ACAO: *)
+
+let BASE;
+let server;
+
+beforeAll(async () => {
+ server = await startTestServer();
+ BASE = server.base;
+}, 30000);
+
+afterAll(() => {
+ server?.close();
+});
+
+const preflight = (path, headers = {}) =>
+ fetch(`${BASE}${path}`, {
+ method: 'OPTIONS',
+ headers: {
+ origin: 'https://example.org',
+ 'access-control-request-method': 'GET',
+ ...headers,
+ },
+ redirect: 'manual',
+ });
+
+describe('cross-origin preflight on the public media routes', () => {
+ it('answers 204 with the route's own CORS headers', async () => {
+ const res = await preflight('/avatars/cesium-man.glb');
+ expect(res.status).toBe(204);
+ expect(res.headers.get('access-control-allow-origin')).toBe('*');
+ expect(res.headers.get('access-control-allow-methods')).toMatch(/OPTIONS/);
+ });
+
+ it('echoes the requested headers so a non-safelisted header passes', async () => {
+ const res = await preflight('/animations/idle.glb', {
+ 'access-control-request-headers': 'x-trace-id',
+ });
+ expect(res.status).toBe(204);
+ expect(res.headers.get('access-control-allow-headers')).toBe('x-trace-id');
+ expect(res.headers.get('vary') || '').toMatch(/Access-Control-Request-Headers/i);
+ });
+
+ it('never lets a shared cache hold one preflight for another header set', async () => {
+ const res = await preflight('/avatars/cesium-man.glb', {
+ 'access-control-request-headers': 'x-trace-id',
+ });
+ expect(res.headers.get('cache-control')).toBe('no-store');
+ });
+
+ it('leaves /api/ preflights to their own handlers', async () => {
+ // api/healthz.js answers its own preflight via api/_lib/cors.js, so this
+ // branch must not intercept it. The tell is the media branch's signature:
+ // it always sets `cache-control: no-store` and varies on the requested
+ // headers, and the handler sets neither.
+ const res = await preflight('/api/healthz', { 'access-control-request-headers': 'x-trace-id' });
+ expect(res.headers.get('cache-control')).not.toBe('no-store');
+ expect(res.headers.get('vary') || '').not.toMatch(/Access-Control-Request-Headers/i);
+ });
+
+ it('does not turn an unrouted path into a 204', async () => {
+ const res = await preflight('/definitely-not-a-real-page-xyz');
+ expect(res.status).toBe(404);
+ });
+});