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(audit): remove false dynamic routes and record production findings

nirholase735759bb0c2
diff --git a/docs/issue-resolution-2026-09-15.md b/docs/issue-resolution-2026-09-15.md
new file mode 100644
index 000000000..0005d7262
--- /dev/null
+++ b/docs/issue-resolution-2026-09-15.md
@@ -0,0 +1,74 @@
+# GitHub issue resolution record: 2026-09-15
+
+This record captures the repository and production audit requested against the
+open [three.ws issue tracker](https://github.com/nirholas/three.ws/issues).
+Credentials and secret values are intentionally never recorded in source,
+logs, issue comments, or build artifacts.
+
+## Completed
+
+- Issues [#110](https://github.com/nirholas/three.ws/issues/110),
+ [#111](https://github.com/nirholas/three.ws/issues/111), and
+ [#115](https://github.com/nirholas/three.ws/issues/115) were resolved by the
+ universal rig-convention work merged in PR #212.
+- The contributor thank-you page and README/community credits were merged in
+ [PR #219](https://github.com/nirholas/three.ws/pull/219). The page combines
+ the live GitHub contributor list with explicit credit for high-impact issue
+ reports, including Victoria Ali's object-storage report in #164.
+- Issue [#113](https://github.com/nirholas/three.ws/issues/113) is resolved by
+ a dedicated bow clip generated from committed project-authored keyframes.
+ It is reproducible through `npm run build:animations`, has 53 canonical
+ tracks, is torso-led and anchored according to `signatures.json`, and was
+ visually checked from front and side on the CZ reference avatar.
+
+## Production resolution: issue #164
+
+Issue [#164](https://github.com/nirholas/three.ws/issues/164) was closed after
+the production credential was rotated on 2026-09-15. The replacement secret
+was added as a new `s3-secret-access-key` Secret Manager version; the matching
+access-key ID was updated with Cloud Run's merge-only `--update-env-vars`
+semantics. No credential value was written to the repository, issue tracker, or
+deployment output.
+
+The resulting `three-ws-api` revision reached Ready and served 100% of traffic.
+`/api/healthz` then reported `object_storage: ok` with a successful signed read.
+A non-uploading `POST /api/forge-upload` probe reached normal content-type
+validation (`400 invalid_content_type`) rather than the former storage guard
+(`503 storage_unavailable`). This proves credential signing and application
+wiring recovered; a real browser upload remains the recommended end-to-end CORS
+check.
+
+Future rotations must use a newly issued Cloudflare R2 Secret Access Key. Store
+it without a trailing newline and never place it directly on a shell command
+line:
+
+```bash
+gcloud secrets versions add s3-secret-access-key \
+ --project aerial-vehicle-466722-p5 \
+ --data-file=-
+
+gcloud run services update three-ws-api \
+ --project aerial-vehicle-466722-p5 \
+ --region us-central1 \
+ --update-secrets S3_SECRET_ACCESS_KEY=s3-secret-access-key:latest
+```
+
+Verify the new revision before closing a future storage incident:
+
+```bash
+curl -s https://three.ws/api/healthz \
+ | jq '.subsystems.subsystems[] | select(.name=="object_storage")'
+```
+
+Then complete one real Forge photo upload. A healthy signed-read probe alone
+does not prove browser CORS behavior end to end.
+
+## Verification performed
+
+- Dedicated bow generator reproduced its committed artifact byte-for-byte.
+- Front/side filmstrip: 100% canonical-track coverage, grounded 1.8-second bow.
+- Animation manifest, registry, and measured motion signatures rebuilt.
+- Focused slot, registry, playback, and motion audits run before commit.
+- Production deep sweep run against Google Cloud Run; transient rollout probe
+ timeouts were rechecked against the ready revision and `/api/version` and
+ `/api/healthz` both responded afterward.
diff --git a/docs/ops/site-health-audit-2026-09-15.md b/docs/ops/site-health-audit-2026-09-15.md
new file mode 100644
index 000000000..dc8d51eb8
--- /dev/null
+++ b/docs/ops/site-health-audit-2026-09-15.md
@@ -0,0 +1,73 @@
+# Production site health audit: 2026-09-15
+
+This record captures the production audit requested on 2026-09-15, the fixes
+shipped from it, and the work that still depends on an external provider or an
+account balance. It deliberately contains no credentials, private keys, access
+tokens, wallet secrets, or complete private endpoint values.
+
+## Scope and method
+
+- Ran the Cloud Run deep triage sweep over the production fleet, including
+ health, revision, TLS, public pages, logs, scheduled jobs, migrations, wallet
+ readiness, Forge, LLM providers, object storage, and x402 settlement.
+- Drove Chromium against all 908 selected public and dynamically discovered
+ HTML routes in both desktop and mobile viewports. The audit records browser
+ exceptions, console errors, failed requests, HTTP failures, layout overflow,
+ accessibility basics, and dead controls.
+- Rechecked every initially failing route/viewport pair in isolation. This is
+ necessary because a full two-viewport WebGL crawl can exhaust a shared
+ renderer and turn healthy pages into false navigation or network failures.
+- Performed focused live checks against the affected API endpoints and asset
+ URLs. Authenticated-only flows were not considered cleared by the anonymous
+ browser pass.
+
+The initial browser report is retained outside Git under
+`reports/page-audit-2026-09-15T07-23-53-110Z.{json,md}`. Reports are ignored by
+design because they contain volatile production data and screenshots.
+
+## Findings and resolution
+
+| Area | Evidence | Resolution |
+| --- | --- | --- |
+| Cloud Run fleet | Health endpoint, TLS, public pages, revision readiness, schedulers, and migrations were healthy. | No fleet or schema change required. |
+| R2 object storage | Production used the correct account endpoint and bucket, but authenticated storage calls rejected the deployed key pair. Several historical showcase thumbnails also resolve to missing objects. | Added the new secret as a Secret Manager version and updated only the access-key environment variable with `--update-env-vars`. Future writes use the repaired credentials. Showcase images now pass through `/api/img`, which provides gateway retry and a valid deterministic fallback for missing historical objects. |
+| Auto-rig demo | `/demos/agents/auto-rig.html` threw before boot because its bare `three` imports had no import map. | Added a pinned Three.js import map for core and addons. |
+| Deploy preview | The bundled avatar is Meshopt-compressed; model-viewer 4.0 could parse it before attaching its decoder and emitted a hard exception. | Upgraded the hosted model-viewer runtime to 4.3.1, whose loader waits for the bundled Meshopt decoder. |
+| Voice state gallery | The browser audit treated the gallery's intentionally rendered ERROR example as a live failure banner. | Added a narrowly scoped `data-audit-intentional-error` annotation and taught the auditor to ignore only annotated example content. |
+| Solana price pages | `$THREE` curve calls returned 502 during the loaded sweep. Both affected pages passed an isolated rerun. | Classified as transient RPC-lane exhaustion, not a deterministic frontend failure. Provider reliability remains monitored by deep triage. |
+| Agent and metadata deep links | Seeded dynamic links included deleted/missing agent records and an unavailable Arweave metadata document. | Retained as upstream/data-lifecycle findings; the route shells render their designed not-found/degraded states. No replacement data was invented. |
+| Agent Galaxy | `/api/galaxy` returned `watsonx_unavailable`. | Requires valid watsonx credentials to construct real embeddings. The API correctly refuses to fabricate a galaxy. |
+| Coin Clash | `/api/clash/state` returned `cc_unconfigured`. | Requires a CoinCommunities read API key. The page already stops polling and renders a designed unavailable state. |
+| Forge and LLM lanes | The deep sweep found low Forge success and unavailable LLM providers. | Provider credentials/capacity must be restored; no mock generation lane was introduced. |
+| x402 settlement and sniper fleet | Settlement was not succeeding, the Solana fee payer was below its operating floor, and four sniper wallets were starved. The treasury-topup dry run produced an empty transfer plan: the master had no spendable SOL, no spare USDC, and two otherwise funded agent wallets had undecryptable secrets. | Requires an explicitly approved funding action plus recovery or rotation of the two unreadable wallet secrets. The empty plan was not applied and no funds were moved during this audit. |
+| OKX bot and alerts | The OKX bot's AI credential was rejected; production Telegram push alerts were disabled. | Requires valid provider credentials and an alerts chat configuration. |
+
+## Coverage notes
+
+The crawler found 115 linked HTML routes absent from `data/pages.json`, plus
+1,770 additional URLs excluded by dynamic-family sampling limits. Most are
+content instances (agent, avatar, market, category, profile, and protocol URLs),
+not separate static surfaces. The canonical route families remain the right
+manifest unit; instance sampling should be expanded only where it adds a new
+template or failure mode.
+
+The loaded audit initially recorded 100 errors, 232 warnings, and 5,188
+informational findings. Those totals include 57 route/viewport pairs that the
+first process could not reverify before its browser recycle cap, so they are not
+a release verdict. A second concurrency-one isolation pass was used for final
+classification. The large majority of WebGL and navigation errors disappeared
+when isolated.
+
+## Operating and security follow-up
+
+- Rotate every GitHub, Cloudflare, R2, npm, and other credential that was pasted
+ into a chat or terminal transcript, even if it was not committed. Treat chat
+ exposure as credential exposure.
+- Keep R2 credentials in Secret Manager. Never add them to `.env`, shell
+ history, reports, documentation, or Git.
+- Restore watsonx, CoinCommunities, OKX AI, and Telegram alert credentials using
+ Secret Manager references, then rerun `npm run triage:gcp -- --json --deep
+ --since 6h`.
+- Funding the fee payer or sniper wallets is an irreversible money-moving action
+ and must be separately confirmed with the exact wallets, amounts, token, and
+ network before execution.
diff --git a/scripts/lib/audit-routes.mjs b/scripts/lib/audit-routes.mjs
index d4c300f10..f1bf55684 100644
--- a/scripts/lib/audit-routes.mjs
+++ b/scripts/lib/audit-routes.mjs
@@ -112,7 +112,6 @@ export async function seedDynamicRoutes(ctx, baseUrl) {
const onchain = items.find((i) => i.agentId && i.chainId);
if (onchain) {
routes.push(`/a/${onchain.chainId}/${onchain.agentId}`);
- routes.push(`/agent/${onchain.chainId}:${onchain.agentId}`);
}
}
} catch {
diff --git a/tests/audit-routes.test.js b/tests/audit-routes.test.js
index 0e248c509..5ead18dfe 100644
--- a/tests/audit-routes.test.js
+++ b/tests/audit-routes.test.js
@@ -14,7 +14,7 @@ import { readFileSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
-import { AUTHED_ROUTES, isHtmlRoute } from '../scripts/lib/audit-routes.mjs';
+import { AUTHED_ROUTES, isHtmlRoute, seedDynamicRoutes } from '../scripts/lib/audit-routes.mjs';
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const routeTable = JSON.parse(readFileSync(resolve(ROOT, 'vercel.json'), 'utf8')).routes;
@@ -65,3 +65,22 @@ describe('AUTHED_ROUTES', () => {
}
});
});
+
+describe('seedDynamicRoutes', () => {
+ it('uses an on-chain explore result only with the on-chain viewer route', async () => {
+ const ctx = {
+ request: {
+ get: async () => ({
+ ok: () => true,
+ json: async () => ({ items: [{ chainId: 8453, agentId: 87073 }] }),
+ }),
+ },
+ };
+ const routes = await seedDynamicRoutes(ctx, 'https://three.ws');
+ expect(routes).toEqual(['/a/8453/87073']);
+ // /agent/:id is the internal UUID editor route. Feeding it an ERC-8004
+ // chain/id pair deterministically creates two API 404s and a fake audit
+ // failure for an agent that was never addressable there.
+ expect(routes.some((route) => route.startsWith('/agent/'))).toBe(false);
+ });
+});
diff --git a/tests/site-audit-regressions.test.js b/tests/site-audit-regressions.test.js
new file mode 100644
index 000000000..a2b315445
--- /dev/null
+++ b/tests/site-audit-regressions.test.js
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const source = (path) => readFileSync(resolve(process.cwd(), path), 'utf8');
+
+describe('production page-audit regressions', () => {
+ it('gives the standalone auto-rig demo resolvable Three.js imports', () => {
+ const html = source('public/demos/agents/auto-rig.html');
+ expect(html).toContain('<script type="importmap">');
+ expect(html).toContain('"three": "https://esm.sh/[email protected]"');
+ expect(html).toContain('"three/addons/": "https://esm.sh/[email protected]/examples/jsm/"');
+ });
+
+ it('loads the Meshopt-ready model-viewer release in the deploy preview', () => {
+ const js = source('src/erc8004/register-ui.js');
+ expect(js).toContain('/model-viewer/4.3.1/model-viewer.min.js');
+ expect(js).not.toContain('/model-viewer/4.0.0/model-viewer.min.js');
+ });
+
+ it('marks only the intentional voice error preview as audit documentation', () => {
+ const voice = source('src/voice-home.js');
+ const audit = source('scripts/page-audit.mjs');
+ expect(voice).toContain("if (state === STATES.ERROR) wrap.dataset.auditIntentionalError = ''");
+ expect(audit).toContain('[data-audit-intentional-error]');
+ });
+
+ it('routes showcase registry images through the resilient image proxy', () => {
+ const js = source('src/erc8004/showcase.js');
+ expect(js).toContain("import { proxiedImageURL } from '../ipfs.js'");
+ expect(js).toContain('proxiedImageURL(a.image');
+ });
+});