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(guards): register the iOS app, MCP catalog and SRI pin checks, with proofs

nirholas86c067764375
diff --git a/data/guards.json b/data/guards.json
index 896b7aa1f..73301b650 100644
--- a/data/guards.json
+++ b/data/guards.json
@@ -1251,6 +1251,27 @@
"reason": "Drives a real Chromium against the running voice loop with a synthesized microphone stream. The behaviours under test (a wake word firing, playback stopping on barge-in, a capture track actually ending) only exist at runtime, so there is no static fixture that could stand in for them."
}
},
+ {
+ "id": "check-ios-app",
+ "script": "scripts/check-ios-app.mjs",
+ "npm": "check:ios-app",
+ "title": "The iOS app's native half still agrees with the web half",
+ "protects": "The iOS share extension is a real, embedded target with every file it needs, every target ships one MARKETING_VERSION, the app and the extension join the same App Group, the .glb type the activation rule names is the one the app imports, and the Swift plugin, quick actions and scene delegate still match the routes and calls the site makes.",
+ "why": "Nothing on a Linux build machine can compile Swift, and the iOS app is two halves that only meet on a phone. Every failure this catches is a name that changed on one side and not the other, and every one is silent on device: a quick action that opens nothing, a share extension that never appears in the share sheet, a plugin call that rejects. App Store Connect also refuses an upload whose extension version differs from the app's. Green means the halves agree; it does not mean the Swift compiles.",
+ "stages": [
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "The share extension loses the Swift file that hands a shared model to the app.",
+ "violation": {
+ "delete": [
+ "ios/native/App/ShareExtension/ShareViewController.swift"
+ ]
+ },
+ "expect": "ShareViewController.swift is missing"
+ }
+ },
{
"id": "check-ios-icons",
"script": "ios/scripts/make-icons.mjs",
@@ -1293,6 +1314,28 @@
"expect": "DRIFT"
}
},
+ {
+ "id": "check-mcp-catalog",
+ "script": "scripts/check-mcp-catalog.mjs",
+ "npm": "check:mcp-catalog",
+ "title": "The connectable MCP server catalog is valid",
+ "protects": "data/mcp-catalog.json, the vetted list of external MCP servers an agent owner can connect on /integrations/mcp, parses and passes the same validateCatalog() the API runs at request time, with no tier glob listed under two tiers of one entry.",
+ "why": "The API validates the catalog when /api/integrations/mcp is called, so a malformed entry is not a build error, it is a 500 on the integrations page for every owner. A glob listed under two tiers is quieter still: first match wins, so the second tier silently never applies. Running the runtime validator offline moves both failures to build time.",
+ "stages": [
+ "prebuild",
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "A catalog file that is no longer valid JSON.",
+ "violation": {
+ "write": {
+ "data/mcp-catalog.json": "{ \"servers\": [ guard proof\n"
+ }
+ },
+ "expect": "is not valid JSON"
+ }
+ },
{
"id": "check-merge-conflicts",
"script": "scripts/check-merge-conflicts.mjs",
@@ -1474,6 +1517,27 @@
"expect": "id_ed25519"
}
},
+ {
+ "id": "check-sri-pins",
+ "script": "scripts/check-sri-pins.mjs",
+ "npm": "check:sri-pins",
+ "title": "Documented embed SRI pins match the release ledger",
+ "protects": "Every <agent-3d> script tag in the docs, specs, blog, examples, skills and package READMEs that pins a released version with an integrity hash carries the hash data/agent-3d-releases.json recorded for that release, and pins only versions that were actually released. `--fix` rewrites stale hashes from the ledger.",
+ "why": "An embedder copies the snippet from our docs. A pin whose hash disagrees with the bytes we serve makes the browser refuse the script, so the avatar never appears on their page and nothing on our side errors. On 2026-10-01 rebuilding a released version on every deploy broke every published pin at once. check-dist runs the same check on every deploy build; this entry point is the one to run while editing docs, and the one that repairs them.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "A doc snippet pinning a released version to a hash that is not the released one.",
+ "violation": {
+ "write": {
+ "docs/guard-proof-sri-pin.md": "# Proof fixture\n\n<script type=\"module\" src=\"https://three.ws/agent-3d/1.5.2/agent-3d.js\" integrity=\"sha384-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\" crossorigin=\"anonymous\"></script>\n"
+ }
+ },
+ "expect": "browsers will refuse it"
+ }
+ },
{
"id": "check-tdz-bootstrap",
"script": "scripts/check-tdz-bootstrap.mjs",
diff --git a/docs/guards.md b/docs/guards.md
index fec512c1f..128ab7c0d 100644
--- a/docs/guards.md
+++ b/docs/guards.md
@@ -115,6 +115,7 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| Python worker dependencies | `npm run audit:deps` | No pinned Python dependency in `workers/`, `services/` or `packages/` carries a known vulnerability in the OSV database. Needs network, so it runs on demand rather than in the gate. |
| iOS app icon | `npm run check:ios-icons` | The committed iOS icon and launch images are exactly what the current brand mark produces, and the icon carries no alpha channel. |
| macOS app icon | `npm run check:macos-icon` | The ten committed Mac icon sizes and their Contents.json are exactly what the current brand mark produces. |
+| iOS app native layer | `npm run check:ios-app` | The iOS share extension is a real, embedded target with every file it needs, every target ships one `MARKETING_VERSION`, the app and the extension join the same App Group, and the Swift plugin, quick actions and scene delegate still match the routes and calls the site makes. Green means the halves agree, not that the Swift compiles. |
| Apple glance widget | `npm run check:apple-widget` | Both Xcode projects that build the Agent glance widget are consistent, every shared Swift source belongs to the targets that need it, and the Swift client still agrees with `api/glance/mine.js` on the endpoint, the headers, the states, the sizes and the token shape. |
| Windows glance widget | `npm run check:windows-widget` | The widgets member in `vite.config.js`, the glance service worker, the two glance endpoints and the Adaptive Card all agree: every field the board requires is present, the declared icons and screenshots exist at the sizes claimed, the worker handles all six board lifecycle events and registers the advertised refresh, and the card expands in the board's own templating engine with no unbound expressions and no dead button targets. |
| Windows glance widget, as deployed | `npm run check:windows-widget:live` | The same contract against what an origin is really serving: the manifest it declares, the worker bytes it returns, the picker assets it serves, and whether the Adaptive Card the board would fetch expands in that engine when bound with the deployed worker's own payload builder. Everything above it passes on a commit that has not shipped, which is how production served a card that drew nothing while this tree was green. Needs network, so it runs on demand, after a deploy. |
@@ -131,6 +132,8 @@ Run `npm run audit:guards` to print the current count and per-stage breakdown. T
| The `[hidden]` guard | `npm run audit:hidden-guard` | Every page resolves the CSS that makes `hidden` actually hide. |
| Site link integrity | `npm run audit:links` | Every navigable target resolves to a real route or file. |
| On-page SEO | `npm run audit:seo` | Across the pages we ask Google to index: no duplicate title or description, every canonical self-referential, no sitemap entry answering noindex or a non-200, and structured data that parses. Reads a live origin, so `--base` points it at a preview. |
+| MCP connection catalog | `npm run check:mcp-catalog` | `data/mcp-catalog.json`, the external MCP servers an owner can connect on `/integrations/mcp`, passes the same validator the API runs at request time, so a malformed entry fails the build instead of 500ing the integrations page. |
+| Embed SRI pins | `npm run check:sri-pins` | Every documented `<agent-3d>` script tag that pins a released version carries the integrity hash the release ledger recorded for it, so a copied snippet is never refused by the browser. `--fix` rewrites stale hashes. `check:dist` runs the same check on every deploy build. |
| Awesome list freshness | `npm run check:awesome` | `awesome/README.md` and `public/awesome.json` still match `data/awesome.json`, the source both are generated from. |
| Prompt library freshness | `npm run check:prompt-library` | `public/prompts.json` and `public/prompts.txt` still match `data/prompt-library.json`, and every prompt in that source is well formed: unique id, known category and setup tier, balanced `<placeholder>` brackets, and links that resolve to real routes. |
| Awesome list link health | `npm run awesome:links` | Every url in the Awesome 3D Agents list still answers, and none is listed twice. Manual on purpose: it calls a hundred-odd third-party hosts, and it tells a bot-filter 403 apart from a dead link. |
diff --git a/public/guards.json b/public/guards.json
index 896b7aa1f..73301b650 100644
--- a/public/guards.json
+++ b/public/guards.json
@@ -1251,6 +1251,27 @@
"reason": "Drives a real Chromium against the running voice loop with a synthesized microphone stream. The behaviours under test (a wake word firing, playback stopping on barge-in, a capture track actually ending) only exist at runtime, so there is no static fixture that could stand in for them."
}
},
+ {
+ "id": "check-ios-app",
+ "script": "scripts/check-ios-app.mjs",
+ "npm": "check:ios-app",
+ "title": "The iOS app's native half still agrees with the web half",
+ "protects": "The iOS share extension is a real, embedded target with every file it needs, every target ships one MARKETING_VERSION, the app and the extension join the same App Group, the .glb type the activation rule names is the one the app imports, and the Swift plugin, quick actions and scene delegate still match the routes and calls the site makes.",
+ "why": "Nothing on a Linux build machine can compile Swift, and the iOS app is two halves that only meet on a phone. Every failure this catches is a name that changed on one side and not the other, and every one is silent on device: a quick action that opens nothing, a share extension that never appears in the share sheet, a plugin call that rejects. App Store Connect also refuses an upload whose extension version differs from the app's. Green means the halves agree; it does not mean the Swift compiles.",
+ "stages": [
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "The share extension loses the Swift file that hands a shared model to the app.",
+ "violation": {
+ "delete": [
+ "ios/native/App/ShareExtension/ShareViewController.swift"
+ ]
+ },
+ "expect": "ShareViewController.swift is missing"
+ }
+ },
{
"id": "check-ios-icons",
"script": "ios/scripts/make-icons.mjs",
@@ -1293,6 +1314,28 @@
"expect": "DRIFT"
}
},
+ {
+ "id": "check-mcp-catalog",
+ "script": "scripts/check-mcp-catalog.mjs",
+ "npm": "check:mcp-catalog",
+ "title": "The connectable MCP server catalog is valid",
+ "protects": "data/mcp-catalog.json, the vetted list of external MCP servers an agent owner can connect on /integrations/mcp, parses and passes the same validateCatalog() the API runs at request time, with no tier glob listed under two tiers of one entry.",
+ "why": "The API validates the catalog when /api/integrations/mcp is called, so a malformed entry is not a build error, it is a 500 on the integrations page for every owner. A glob listed under two tiers is quieter still: first match wins, so the second tier silently never applies. Running the runtime validator offline moves both failures to build time.",
+ "stages": [
+ "prebuild",
+ "gate"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "A catalog file that is no longer valid JSON.",
+ "violation": {
+ "write": {
+ "data/mcp-catalog.json": "{ \"servers\": [ guard proof\n"
+ }
+ },
+ "expect": "is not valid JSON"
+ }
+ },
{
"id": "check-merge-conflicts",
"script": "scripts/check-merge-conflicts.mjs",
@@ -1474,6 +1517,27 @@
"expect": "id_ed25519"
}
},
+ {
+ "id": "check-sri-pins",
+ "script": "scripts/check-sri-pins.mjs",
+ "npm": "check:sri-pins",
+ "title": "Documented embed SRI pins match the release ledger",
+ "protects": "Every <agent-3d> script tag in the docs, specs, blog, examples, skills and package READMEs that pins a released version with an integrity hash carries the hash data/agent-3d-releases.json recorded for that release, and pins only versions that were actually released. `--fix` rewrites stale hashes from the ledger.",
+ "why": "An embedder copies the snippet from our docs. A pin whose hash disagrees with the bytes we serve makes the browser refuse the script, so the avatar never appears on their page and nothing on our side errors. On 2026-10-01 rebuilding a released version on every deploy broke every published pin at once. check-dist runs the same check on every deploy build; this entry point is the one to run while editing docs, and the one that repairs them.",
+ "stages": [
+ "manual"
+ ],
+ "needs": "none",
+ "proof": {
+ "summary": "A doc snippet pinning a released version to a hash that is not the released one.",
+ "violation": {
+ "write": {
+ "docs/guard-proof-sri-pin.md": "# Proof fixture\n\n<script type=\"module\" src=\"https://three.ws/agent-3d/1.5.2/agent-3d.js\" integrity=\"sha384-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\" crossorigin=\"anonymous\"></script>\n"
+ }
+ },
+ "expect": "browsers will refuse it"
+ }
+ },
{
"id": "check-tdz-bootstrap",
"script": "scripts/check-tdz-bootstrap.mjs",
diff --git a/scripts/check-ios-app.mjs b/scripts/check-ios-app.mjs
index 860369dc4..f2ae5e4d0 100644
--- a/scripts/check-ios-app.mjs
+++ b/scripts/check-ios-app.mjs
@@ -24,10 +24,20 @@ import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const read = (rel) => readFileSync(join(REPO, rel), 'utf8');
const problems = [];
-const fail = (msg) => problems.push(msg);
+const fail = (msg) => {
+ if (!problems.includes(msg)) problems.push(msg);
+};
+// A missing file is a finding, not a crash: report it and let every other
+// check still run, so one deletion does not hide the rest of the report.
+const read = (rel) => {
+ if (!existsSync(join(REPO, rel))) {
+ fail(`${rel} is missing`);
+ return '';
+ }
+ return readFileSync(join(REPO, rel), 'utf8');
+};
let checks = 0;
const pass = (msg) => {
checks++;