@ggui-ai/protocol 0.1.0-rc.1

package/dist/validation/ui-security.js

@@ -0,0 +1,138 @@
+// packages/protocol/src/validation/ui-security.ts
+//
+// Shared UI security validation — single source of truth for dangerous
+// patterns and UI classification. Used by:
+//   - core/src/tools/validation.ts (generator pipeline)
+//   - core/src/validation/ui-compiler.ts (CLI compiler)
+//   - cloud/amplify/functions/rest-api/cli-api/ui-register-handler.ts (register endpoint)
+//
+// This module is PUBLIC (@ggui-ai/protocol) — keep it dependency-free.
+/**
+ * Patterns that are NEVER allowed in sandboxed UI components.
+ * These are security-critical — changes here affect every validation consumer.
+ */
+export const DANGEROUS_PATTERNS = [
+    {
+        pattern: /\beval\s*\(/,
+        name: 'eval()',
+        suggestion: 'Remove eval() - it allows arbitrary code execution. Use proper data handling instead.',
+    },
+    {
+        pattern: /\bFunction\s*\(/,
+        name: 'Function constructor',
+        suggestion: 'Remove Function() constructor - it allows arbitrary code execution.',
+    },
+    {
+        pattern: /\binnerHTML\s*=/,
+        name: 'innerHTML',
+        suggestion: 'Use React components instead of innerHTML to prevent XSS vulnerabilities.',
+    },
+    {
+        pattern: /\bdangerouslySetInnerHTML\b/,
+        name: 'dangerouslySetInnerHTML',
+        suggestion: 'Avoid dangerouslySetInnerHTML - use React components for rendering.',
+    },
+    {
+        pattern: /\bdocument\.\w+/,
+        name: 'document access',
+        suggestion: 'Do not access document directly - use React refs and state instead.',
+    },
+    {
+        pattern: /\bwindow\.(?!__GGUI)/,
+        name: 'window access',
+        suggestion: 'Do not access window directly - use React patterns instead.',
+    },
+    {
+        pattern: /\blocalStorage\b/,
+        name: 'localStorage',
+        suggestion: 'Do not use localStorage - pass data through props and onSubmit.',
+    },
+    {
+        pattern: /\bsessionStorage\b/,
+        name: 'sessionStorage',
+        suggestion: 'Do not use sessionStorage - pass data through props and onSubmit.',
+    },
+    {
+        pattern: /\bfetch\s*\(/,
+        name: 'fetch()',
+        suggestion: 'Do not make network requests - use adapters and onSubmit for data operations.',
+    },
+    {
+        pattern: /\bXMLHttpRequest\b/,
+        name: 'XMLHttpRequest',
+        suggestion: 'Do not make network requests - use adapters and onSubmit for data operations.',
+    },
+    {
+        pattern: /\bimport\s*\(/,
+        name: 'dynamic import',
+        suggestion: 'Do not use dynamic imports - all dependencies must be static imports.',
+    },
+    {
+        pattern: /<script\b/i,
+        name: 'script tag',
+        suggestion: 'Do not include script tags - use React components only.',
+    },
+    {
+        pattern: /\bnew\s+WebSocket\b/,
+        name: 'WebSocket',
+        suggestion: 'Do not create WebSocket connections - communication is handled by ggui.',
+    },
+    {
+        pattern: /\bnavigator\./,
+        name: 'navigator access',
+        suggestion: 'Do not access navigator - use React patterns for user interactions.',
+    },
+    {
+        pattern: /\blocation\./,
+        name: 'location access',
+        suggestion: 'Do not access location - routing is handled externally.',
+    },
+    {
+        pattern: /\bhistory\./,
+        name: 'history access',
+        suggestion: 'Do not access history - navigation is handled externally.',
+    },
+];
+// ── UI Classification ───────────────────────────────────────────────
+/** Import prefixes that indicate a fullstack UI (requires client bundle). */
+export const FULLSTACK_IMPORT_PREFIXES = [
+    '@ggui-ai/wire',
+    '@ggui-ai/react',
+    '@app/components',
+];
+/**
+ * Classify a component as sandboxed or fullstack based on its imports.
+ *
+ * - **sandboxed**: Pure React + @ggui-ai/design primitives. Portable, publishable.
+ * - **fullstack**: Uses @ggui-ai/wire, @ggui-ai/react, or @app/components. Private.
+ *
+ * Works on both source (.tsx) and compiled (.js) code.
+ */
+export function classifyUi(code) {
+    const importRegex = /(?:from|require\()\s*['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = importRegex.exec(code)) !== null) {
+        const src = match[1];
+        if (FULLSTACK_IMPORT_PREFIXES.some((prefix) => src === prefix || src.startsWith(prefix + '/'))) {
+            return 'fullstack';
+        }
+    }
+    return 'sandboxed';
+}
+/**
+ * Check code for dangerous patterns.
+ * Works on both source and compiled code.
+ */
+export function checkSecurity(code) {
+    const violations = [];
+    for (const { pattern, name, suggestion } of DANGEROUS_PATTERNS) {
+        // Reset lastIndex for global regexes
+        const re = new RegExp(pattern.source, pattern.flags);
+        const match = re.exec(code);
+        if (match) {
+            const line = code.substring(0, match.index).split('\n').length;
+            violations.push({ name, suggestion, line });
+        }
+    }
+    return { safe: violations.length === 0, violations };
+}

package/dist/validation/zod-to-json-schema.d.ts

@@ -0,0 +1,63 @@
+/**
+ * zod → {@link JsonSchema} conversion, normalized to the shape our
+ * {@link isSchemaSubset} algorithm accepts.
+ *
+ * **Why zod's built-in vs. the `zod-to-json-schema` package.** That
+ * library only understands zod v3 internals — passing a zod v4 schema
+ * yields an empty `{$schema}` document. The protocol package is on
+ * zod v4, which ships its own built-in `z.toJSONSchema()` helper that
+ * produces correct JSON Schema output for every construct we care
+ * about. The wrapper below normalizes the v4 output — draft-2020-12
+ * by default, plus a small handful of zod-specific quirks — onto the
+ * {@link JsonSchema} shape the subset algorithm consumes.
+ *
+ * **Normalizations applied.**
+ *
+ *   1. Strip the top-level `$schema` URI. Our {@link JsonSchema} does
+ *      not carry it, and the subset algorithm's "unsupported
+ *      constructs" flagging would treat unknown top-level keys as
+ *      surprises. `$schema` is metadata, not structure.
+ *   2. Preserve draft-2020-12 `additionalProperties: {}` (zod emits
+ *      this for `.passthrough()`) as `additionalProperties: {}` —
+ *      the subset algorithm treats the empty-schema case as a
+ *      structured-but-unconstrained extras slot. Callers that want
+ *      "strictly true" must convert explicitly.
+ *   3. Leave `anyOf` / `const` / `enum` shapes intact. The subset
+ *      algorithm flags them as P1/P2 deferred constructs — the
+ *      caller receives an honest `unsupported` violation rather
+ *      than a silent pass.
+ *   4. `z.any()` / `z.unknown()` produce an empty schema (no keys).
+ *      The subset algorithm treats an empty schema as a wildcard
+ *      (matches `isSchemaSubset(..., {type: 'string'})` as
+ *      compatible), which mirrors JSON Schema semantics.
+ *
+ * **Intended call sites.**
+ *
+ *   - Push-time + blueprint-registration schema-compat checks in
+ *     `@ggui-ai/mcp-server`: a mount-registered tool handler exposes
+ *     its `inputSchema` as a {@link ZodRawShape}; wrapping it in
+ *     `z.object(shape)` and converting gives the JsonSchema that
+ *     pairs against the declared `actionSpec[name].schema`.
+ *   - Ad-hoc authoring tools (e.g. console panels) that need a
+ *     human-readable JSON shape for a zod definition.
+ *
+ * @see ./schema-subset.ts
+ */
+import { type ZodRawShape, type ZodType } from 'zod';
+import type { JsonSchema } from '../types/data-contract.js';
+/**
+ * Convert a zod schema (or raw shape) to a {@link JsonSchema} suitable
+ * for the subset algorithm.
+ *
+ * - Pass a `ZodType` to convert it directly.
+ * - Pass a {@link ZodRawShape} (the raw `{ key: ZodType, ... }` map
+ *   shape {@link SharedHandler.inputSchema} carries) to have it
+ *   wrapped in `z.object(...)` before conversion.
+ *
+ * Never throws on legitimate input. If zod's native emitter returns
+ * a non-object (it shouldn't for any supported construct), we coerce
+ * to an empty schema `{}` so downstream comparison treats it as
+ * unconstrained.
+ */
+export declare function zodToJsonSchema(input: ZodType | ZodRawShape): JsonSchema;
+//# sourceMappingURL=zod-to-json-schema.d.ts.map

package/dist/validation/zod-to-json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-json-schema.d.ts","sourceRoot":"","sources":["../../src/validation/zod-to-json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,EAAK,KAAK,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,UAAU,CAQxE"}

package/dist/validation/zod-to-json-schema.js

@@ -0,0 +1,126 @@
+/**
+ * zod → {@link JsonSchema} conversion, normalized to the shape our
+ * {@link isSchemaSubset} algorithm accepts.
+ *
+ * **Why zod's built-in vs. the `zod-to-json-schema` package.** That
+ * library only understands zod v3 internals — passing a zod v4 schema
+ * yields an empty `{$schema}` document. The protocol package is on
+ * zod v4, which ships its own built-in `z.toJSONSchema()` helper that
+ * produces correct JSON Schema output for every construct we care
+ * about. The wrapper below normalizes the v4 output — draft-2020-12
+ * by default, plus a small handful of zod-specific quirks — onto the
+ * {@link JsonSchema} shape the subset algorithm consumes.
+ *
+ * **Normalizations applied.**
+ *
+ *   1. Strip the top-level `$schema` URI. Our {@link JsonSchema} does
+ *      not carry it, and the subset algorithm's "unsupported
+ *      constructs" flagging would treat unknown top-level keys as
+ *      surprises. `$schema` is metadata, not structure.
+ *   2. Preserve draft-2020-12 `additionalProperties: {}` (zod emits
+ *      this for `.passthrough()`) as `additionalProperties: {}` —
+ *      the subset algorithm treats the empty-schema case as a
+ *      structured-but-unconstrained extras slot. Callers that want
+ *      "strictly true" must convert explicitly.
+ *   3. Leave `anyOf` / `const` / `enum` shapes intact. The subset
+ *      algorithm flags them as P1/P2 deferred constructs — the
+ *      caller receives an honest `unsupported` violation rather
+ *      than a silent pass.
+ *   4. `z.any()` / `z.unknown()` produce an empty schema (no keys).
+ *      The subset algorithm treats an empty schema as a wildcard
+ *      (matches `isSchemaSubset(..., {type: 'string'})` as
+ *      compatible), which mirrors JSON Schema semantics.
+ *
+ * **Intended call sites.**
+ *
+ *   - Push-time + blueprint-registration schema-compat checks in
+ *     `@ggui-ai/mcp-server`: a mount-registered tool handler exposes
+ *     its `inputSchema` as a {@link ZodRawShape}; wrapping it in
+ *     `z.object(shape)` and converting gives the JsonSchema that
+ *     pairs against the declared `actionSpec[name].schema`.
+ *   - Ad-hoc authoring tools (e.g. console panels) that need a
+ *     human-readable JSON shape for a zod definition.
+ *
+ * @see ./schema-subset.ts
+ */
+import { z } from 'zod';
+/**
+ * Convert a zod schema (or raw shape) to a {@link JsonSchema} suitable
+ * for the subset algorithm.
+ *
+ * - Pass a `ZodType` to convert it directly.
+ * - Pass a {@link ZodRawShape} (the raw `{ key: ZodType, ... }` map
+ *   shape {@link SharedHandler.inputSchema} carries) to have it
+ *   wrapped in `z.object(...)` before conversion.
+ *
+ * Never throws on legitimate input. If zod's native emitter returns
+ * a non-object (it shouldn't for any supported construct), we coerce
+ * to an empty schema `{}` so downstream comparison treats it as
+ * unconstrained.
+ */
+export function zodToJsonSchema(input) {
+    const schema = isZodType(input) ? input : z.object(input);
+    // zod v4's native emitter returns a plain JSON-Schema-shaped object.
+    // `z.toJSONSchema` is typed as `unknown` when narrowed by our
+    // JsonSchema; cast + normalize.
+    const raw = z.toJSONSchema(schema);
+    if (raw === null || typeof raw !== 'object')
+        return {};
+    return normalize(raw);
+}
+/**
+ * Strip zod / draft-2020-12 quirks the subset algorithm doesn't
+ * consume, recursively. Does NOT strip unsupported constructs
+ * (oneOf/anyOf/enum/const/$ref/allOf) — those surface as explicit
+ * `unsupported` violations from the subset algorithm, which is what
+ * we want.
+ */
+function normalize(value) {
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        if (key === '$schema')
+            continue;
+        if (key === 'properties' && v !== null && typeof v === 'object') {
+            const props = {};
+            for (const [pkey, pval] of Object.entries(v)) {
+                props[pkey] = normalize(pval);
+            }
+            out[key] = props;
+            continue;
+        }
+        if (key === 'additionalProperties') {
+            if (typeof v === 'boolean') {
+                out[key] = v;
+            }
+            else {
+                out[key] = normalize(v);
+            }
+            continue;
+        }
+        if (key === 'items') {
+            out[key] = normalize(v);
+            continue;
+        }
+        out[key] = normalize(v);
+    }
+    return out;
+}
+/**
+ * Discriminator between `ZodType` and `ZodRawShape`. Zod v4 schemas
+ * carry a `_def` field (via the internal def bag). A raw shape is a
+ * plain object with string keys mapping to ZodType instances. We
+ * check for the presence of a ZodType marker to distinguish; absence
+ * means treat as raw shape.
+ */
+function isZodType(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    // Every zod v4 schema has `parse` and `_def`. A raw shape — a plain
+    // object of ZodType values — does not.
+    const bag = value;
+    return typeof bag['parse'] === 'function' && '_def' in bag;
+}