@toon-protocol/views 0.2.0

package/dist/a2ui/validate.js

@@ -0,0 +1,117 @@
+/**
+ * The standard-catalog-only validation gate for branch 2 (A2UI, medium trust).
+ *
+ * This is the security boundary of the A2UI branch. Medium trust is reserved for
+ * renderers that stay ENTIRELY within the A2UI "Basic" standard catalog and
+ * carry no client-defined behavior. Anything else must be REFUSED here and
+ * dropped to branch 3 (the sandboxed mcp-ui path) — never rendered at medium
+ * trust against the client's own primitives.
+ *
+ * The gate returns a discriminated {@link A2uiGateResult}:
+ *   - `{ ok: true, surface, root }`            → render at medium trust, or
+ *   - `{ ok: false, fallback: 'mcp-ui', … }`   → drop to branch 3 (custom comp /
+ *                                                 behavior), or
+ *   - `{ ok: false, fallback: 'native', … }`   → unsupported A2UI version /
+ *                                                 unparseable; let the dispatch
+ *                                                 fall through (branch 1/4).
+ *
+ * The renderer NEVER renders a surface the gate refused.
+ */
+import { A2UI_BASIC_CATALOG_SET, SUPPORTED_A2UI_VERSIONS, } from './types.js';
+/**
+ * Keys on a component node that indicate client-defined *behavior* (actions,
+ * handlers, validators). Their presence drops the surface to branch 3 even if
+ * every component name is in the Basic catalog — medium trust never executes
+ * renderer-supplied behavior.
+ */
+const BEHAVIOR_KEYS = ['action', 'actions', 'onClick', 'onTap', 'onChange', 'handler', 'fn', 'function', 'validate', 'validator', 'script'];
+/** Read the `["a2ui", "<version>"]` tag value, or `undefined`. */
+export function readA2uiVersion(tags) {
+    const tag = tags.find((t) => t[0] === 'a2ui');
+    return tag?.[1];
+}
+/**
+ * Validate the A2UI renderer for branch 2.
+ *
+ * @param content   the `kind:31036` renderer `content` (the JSON `surfaceUpdate`)
+ * @param tags      the renderer event tags (read for the `a2ui` version tag)
+ * @returns a {@link A2uiGateResult} — pass (render) or refuse (fall back).
+ */
+export function validateA2uiRenderer(content, tags) {
+    // 1. Version negotiation — read `["a2ui", "<version>"]`. A missing tag is the
+    //    supported default (the `m` tag already selected A2UI). An *unsupported*
+    //    version falls through (branch 1/4) rather than dropping to mcp-ui.
+    const version = readA2uiVersion(tags);
+    if (version !== undefined && !SUPPORTED_A2UI_VERSIONS.has(version)) {
+        return {
+            ok: false,
+            fallback: 'native',
+            reason: 'unsupported-version',
+            detail: `unsupported A2UI version "${version}"`,
+        };
+    }
+    // 2. Parse the surfaceUpdate. Unparseable → fall through (branch 1/4).
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        return { ok: false, fallback: 'native', reason: 'unparseable-surface', detail: 'content is not valid JSON' };
+    }
+    // The surfaceUpdate may be the bare body or wrapped under `surfaceUpdate`.
+    const surface = unwrapSurface(parsed);
+    if (!surface || !Array.isArray(surface.components)) {
+        return { ok: false, fallback: 'native', reason: 'unparseable-surface', detail: 'no surfaceUpdate.components array' };
+    }
+    if (surface.components.length === 0) {
+        return { ok: false, fallback: 'native', reason: 'empty-surface', detail: 'surfaceUpdate has no components' };
+    }
+    // 3. Standard-catalog-only invariant. Any custom component name, or any node
+    //    carrying client-defined behavior, REFUSES → branch 3.
+    for (const node of surface.components) {
+        if (!node || typeof node !== 'object' || typeof node.component !== 'string') {
+            return { ok: false, fallback: 'native', reason: 'unparseable-surface', detail: 'malformed component node' };
+        }
+        if (!A2UI_BASIC_CATALOG_SET.has(node.component)) {
+            return {
+                ok: false,
+                fallback: 'mcp-ui',
+                reason: 'custom-component',
+                detail: `component "${node.component}" is not in the A2UI Basic catalog`,
+            };
+        }
+        for (const key of BEHAVIOR_KEYS) {
+            if (key in node && node[key] !== undefined) {
+                return {
+                    ok: false,
+                    fallback: 'mcp-ui',
+                    reason: 'custom-behavior',
+                    detail: `component "${node.id}" carries client-defined behavior "${key}"`,
+                };
+            }
+        }
+    }
+    // 4. Resolve the root: explicit `root`, else the conventional `id: "root"`,
+    //    else the first component.
+    const explicit = typeof surface.root === 'string' ? surface.root : undefined;
+    const rootId = explicit ??
+        (surface.components.find((c) => c.id === 'root')?.id) ??
+        surface.components[0]?.id;
+    if (!rootId || !surface.components.some((c) => c.id === rootId)) {
+        return { ok: false, fallback: 'native', reason: 'missing-root', detail: 'no resolvable root component' };
+    }
+    return { ok: true, surface, root: rootId };
+}
+/** Accept either a bare surface body or one wrapped under `surfaceUpdate`. */
+function unwrapSurface(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const obj = parsed;
+    const inner = obj['surfaceUpdate'];
+    if (inner && typeof inner === 'object')
+        return inner;
+    if (Array.isArray(obj['components']))
+        return obj;
+    return undefined;
+}
+//# sourceMappingURL=validate.js.map

package/dist/a2ui/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/a2ui/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,sBAAsB,EACtB,uBAAuB,GAExB,MAAM,YAAY,CAAC;AAoCpB;;;;;GAKG;AACH,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;AAE5I,kEAAkE;AAClE,MAAM,UAAU,eAAe,CAAC,IAAgB;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC;IAC9C,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,IAAgB;IACpE,8EAA8E;IAC9E,6EAA6E;IAC7E,wEAAwE;IACxE,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACnE,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,qBAAqB;YAC7B,MAAM,EAAE,6BAA6B,OAAO,GAAG;SAChD,CAAC;IACJ,CAAC;IAED,uEAAuE;IACvE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAC;IAC/G,CAAC;IAED,2EAA2E;IAC3E,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,EAAE,mCAAmC,EAAE,CAAC;IACvH,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,iCAAiC,EAAE,CAAC;IAC/G,CAAC;IAED,6EAA6E;IAC7E,2DAA2D;IAC3D,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACtC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YAC5E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;QAC9G,CAAC;QACD,IAAI,CAAC,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAChD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,QAAQ,EAAE,QAAQ;gBAClB,MAAM,EAAE,kBAAkB;gBAC1B,MAAM,EAAE,cAAc,IAAI,CAAC,SAAS,oCAAoC;aACzE,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,IAAI,GAAG,IAAI,IAAI,IAAK,IAAgC,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;gBACxE,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,QAAQ,EAAE,QAAQ;oBAClB,MAAM,EAAE,iBAAiB;oBACzB,MAAM,EAAE,cAAc,IAAI,CAAC,EAAE,sCAAsC,GAAG,GAAG;iBAC1E,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,+BAA+B;IAC/B,MAAM,QAAQ,GAAG,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7E,MAAM,MAAM,GACV,QAAQ;QACR,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC;QACrD,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC;QAChE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;IAC3G,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC7C,CAAC;AAED,8EAA8E;AAC9E,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,MAAM,KAAK,GAAG,GAAG,CAAC,eAAe,CAAC,CAAC;IACnC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAA0B,CAAC;IAC1E,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAAE,OAAO,GAAmC,CAAC;IACjF,OAAO,SAAS,CAAC;AACnB,CAAC"}