@ggui-ai/protocol 0.1.0-rc.1

package/dist/validation/contract-validator.d.ts

@@ -0,0 +1,244 @@
+import type { PropsSpec, StreamSpec, ActionSpec, ContextSpec, JsonSchema, JsonObject, DataContract } from '../types/data-contract';
+import type { ActionEnvelope } from '../types/events';
+import type { CompiledContractValidators } from '../integrations/mcp-apps';
+import type { ValidateFunction } from './ajv-runtime';
+export type { ValidateFunction } from './ajv-runtime';
+import { type ReservedChannelValidator } from './reserved-channels';
+export interface ContractViolation extends JsonObject {
+    field: string;
+    message: string;
+    expected?: string;
+    received?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    violations: ContractViolation[];
+}
+/**
+ * Synthesize a {@link PropsSpec} into the single object-node JSON
+ * Schema the runtime validates `props` against — `{type:'object',
+ * properties:{…entry.schema…}, required:[…entry.required…]}`.
+ * Closed-shape (`additionalProperties:false` at every depth) is NOT
+ * injected here — the Ajv compile step ({@link compileForValidation} /
+ * {@link compileValidatorModule}) does that, so this returns the raw
+ * pre-injection wrapper.
+ *
+ * Shared by {@link validatePropsData} (server-side runtime check) and
+ * {@link compileContractValidators} (push-time standalone emission) so
+ * the precompiled in-iframe validator enforces byte-identical
+ * semantics to the runtime validator — one synthesis, no drift.
+ */
+export declare function buildPropsWrapperSchema(spec: PropsSpec): JsonSchema;
+/**
+ * Validate runtime props data against a PropsSpec contract.
+ *
+ * Synthesizes the propsSpec into a single JSON Schema object node
+ * — `{type:'object', properties: {…spec.properties[name].schema…},
+ * required: [...names where entry.required], additionalProperties:
+ * false}` — and validates `props` against it via the shared Ajv
+ * runtime. The closed-shape injector recurses into every nested
+ * object so the bidirectional contract (every declared key
+ * validated, every data key declared) holds at any depth.
+ *
+ * Load-bearing for `ggui_update kind:'merge'` (RFC 7396): a patch
+ * adding a key absent from `propsSpec.properties` would silently
+ * land on the stack item without this gate. Same rule applies to
+ * the `done`-vs-declared-`completed` class of bug inside array
+ * items — Ajv rejects with the exact path (`todos[0].done`).
+ */
+export declare function validatePropsData(props: Record<string, unknown>, spec: PropsSpec, precompiled?: ValidateFunction): ValidationResult;
+/**
+ * Validate a stream delivery's payload against the channel's declared
+ * schema on a {@link StreamSpec}.
+ *
+ * Signature takes the channel name + payload explicitly — matching
+ * the {@link StreamEnvelope} wire shape (where channel is a first-
+ * class envelope field, not a field nested inside the payload).
+ *
+ * Checks:
+ *  - `channelName` is declared in `spec` (a flat `Record<channelName,
+ *    StreamChannelEntry>` post-2026-04-22 flatten) — undeclared
+ *    channels reject with `'Unknown stream channel'` in the
+ *    violation message.
+ *  - `payload` conforms to `spec[channelName].schema` when
+ *    that schema declares a `type`.
+ *
+ * Reserved-channel handling (injection pattern):
+ *
+ *   Known reserved channels (see {@link isKnownReservedChannel}) are
+ *   server-owned and bypass the streamSpec path entirely — agents
+ *   never declare them. Their payloads are validated through the
+ *   TWO-TIER validator lookup:
+ *
+ *     1. `extraReservedValidators` — optional, caller-provided. Primary
+ *        consumer: a hosting implementation composing the A2UI
+ *        validator for `_ggui:preview`. Consulted FIRST so callers can
+ *        override or extend built-ins.
+ *     2. `BUILTIN_RESERVED_VALIDATORS` — protocol-owned, always active.
+ *        Ships the {@link validateContractErrorPayload} for
+ *        `_ggui:contract-error`.
+ *     3. Fall-through: if no validator is registered for the known
+ *        reserved channel, return `{valid: true}`. Preserves backward
+ *        compatibility for any future reserved channel the runtime
+ *        adds before its validator is authored.
+ *
+ *   Without this structure, a `_ggui:preview` emission into a session
+ *   whose active stack item carries ANY user streamSpec would
+ *   synthesize a false "Unknown channel" violation, blocking the
+ *   provisional preview runtime. Symmetric with the client-side
+ *   handling in `GguiSession`.
+ *
+ * Crucially narrow by design — the known-reserved path is a CLOSED
+ * SET, not a prefix check. A typo inside the reserved namespace
+ * (e.g. `_ggui:preveiw`) is NOT recognized, falls through to the
+ * normal unknown-channel rejection, and surfaces the bug at its
+ * emission site instead of turning into a silent no-op delivery.
+ *
+ * Does NOT validate channel semantics (mode / replay / complete) —
+ * those are declarations, not shape constraints. See
+ * `resolveStreamChannel` for semantics lookup.
+ */
+export declare function validateStreamData(channelName: string, payload: unknown, spec: StreamSpec, extraReservedValidators?: ReadonlyMap<string, ReservedChannelValidator>, precompiledChannels?: ReadonlyMap<string, ValidateFunction>): ValidationResult;
+/**
+ * Validate a contextSpec slot value against the spec's declared
+ * schema. Symmetric with {@link validateStreamData} /
+ * {@link validateActionData}: the iframe-runtime observer uses this
+ * to gate Provider values BEFORE posting `ui/update-model-context`
+ * envelopes (per the contextSpec design-lock — Q4 schema check).
+ *
+ * Checks:
+ *   - `slotName` is declared in `spec` — undeclared slots reject with
+ *     `'Unknown context slot'`.
+ *   - `value` conforms to `spec[slotName].schema` when that schema
+ *     declares a `type`.
+ *
+ * Mirrors `validateActionData`'s posture: the runtime that calls this
+ * decides whether to surface the failure (dev-only `console.warn`,
+ * drop silently in production) — the validator is a pure shape gate.
+ */
+export declare function validateContextData(slotName: string, value: unknown, spec: ContextSpec, precompiledSlots?: ReadonlyMap<string, ValidateFunction>): ValidationResult;
+/**
+ * Validate an inbound user-action payload against the session's ActionSpec.
+ *
+ * Symmetric with {@link validatePropsData} / {@link validateStreamData}, but for
+ * live-channel INBOUND user → core traffic. Enforces the action contract at the
+ * wire boundary BEFORE the event is buffered or forwarded to an agent.
+ *
+ * Input shape mirrors `ActionEventValue` from `events.ts`:
+ *   `{ action: string, data?: JsonValue, tool?: string }`
+ *
+ * Checks:
+ * - `action` is a non-empty string
+ * - `action` is declared in `spec` (a flat `Record<actionName,
+ *   ActionEntry>` post-2026-04-22 flatten)
+ * - If the declared action has a `schema`, `data` matches it
+ *
+ * Actions without a declared schema are void-payload (fire-and-forget) — a
+ * present-but-unexpected `data` is tolerated to stay forward-compatible with
+ * clients that attach UI metadata the contract doesn't model. Contracts that
+ * want strict emptiness should declare `schema: { type: 'null' }`.
+ */
+export declare function validateActionData(value: unknown, spec: ActionSpec, precompiledActions?: ReadonlyMap<string, ValidateFunction>): ValidationResult;
+/**
+ * Validate an inbound {@link ActionEnvelope} against the target stack
+ * item's {@link ActionSpec}. Payload-contract layer of live-channel
+ * inbound enforcement — the allowlist gate (`assertEventAllowed` in
+ * `@ggui-ai/mcp-server-handlers`) is a separate concern that runs
+ * first.
+ *
+ * Semantics:
+ *   - `envelope.type !== 'data:submit'` → `{valid: true, violations: []}`.
+ *     Only action submissions carry payload contract today; other
+ *     event types (lifecycle, interaction, error) have no schema
+ *     enforcement on this layer.
+ *   - `spec === undefined` → `{valid: true, violations: []}`. Stack
+ *     items without an actionSpec have no contract; legacy pushes keep
+ *     flowing.
+ *   - Otherwise `envelope.payload` is validated against `spec` via
+ *     {@link validateActionData}. Same rules, same output shape.
+ *
+ * This helper does NOT enforce allowlist, session binding, or stack
+ * routing — those are ingress-plumbing concerns. Pure payload-shape
+ * check; returns `ValidationResult` rather than throwing so callers
+ * can decide whether to surface as a wire error, log, etc.
+ */
+export declare function validateActionEnvelope(envelope: ActionEnvelope, spec: ActionSpec | undefined, precompiledActions?: ReadonlyMap<string, ValidateFunction>): ValidationResult;
+/**
+ * Compile a contract's runtime-validated sub-schemas into standalone,
+ * eval-free ESM validator modules — the producer half of the
+ * precompiled-validator channel
+ * ({@link CompiledContractValidators} on `GguiBootstrapMeta`).
+ *
+ * The renderer iframe runs under a strict CSP with no `'unsafe-eval'`,
+ * so it cannot call `ajv.compile()` (which builds validators via
+ * `new Function`). Compilation therefore happens server-side at push
+ * time — where the contract schema is fixed and codegen is legal — and
+ * the iframe loads each emitted module via a `blob:` dynamic import.
+ *
+ * One module per runtime-validated surface, matching the four runtime
+ * validators in this file exactly (no second contract model):
+ *
+ *   - `props`   — the synthesized object wrapper from
+ *     {@link buildPropsWrapperSchema}, as {@link validatePropsData}
+ *     validates `props`.
+ *   - `actions` — per-action `entry.schema`, as {@link validateActionData}
+ *     validates `data`. Void actions (no `schema`) contribute no entry.
+ *   - `streams` — per-channel `entry.schema`, as {@link validateStreamData}
+ *     validates `payload`.
+ *   - `context` — per-slot `entry.schema`, as {@link validateContextData}
+ *     validates `value`.
+ *
+ * Returns `undefined` when the contract declares no runtime-validated
+ * schema at all — the bootstrap projection then omits the field.
+ */
+export declare function compileContractValidators(specs: {
+    readonly propsSpec?: PropsSpec;
+    readonly actionSpec?: ActionSpec;
+    readonly streamSpec?: StreamSpec;
+    readonly contextSpec?: ContextSpec;
+}): CompiledContractValidators | undefined;
+/**
+ * Format violations into a human-readable error message for the target agent.
+ */
+export declare function formatViolations(violations: ContractViolation[]): string;
+/**
+ * Validate the contract structure itself — catches malformed contract
+ * before they're persisted and used to validate runtime data.
+ *
+ * Checks:
+ * - PropsSpec properties have valid schemas (type or oneOf/anyOf defined)
+ * - Array schemas have items defined (otherwise element validation is impossible)
+ * - Object schemas with required fields reference existing properties
+ * - StreamSpec channels have schemas defined (reserved-prefix names rejected)
+ * - ActionSpec actions have schemas defined
+ * - ContextSpec slots: identifier-shape keys, no reserved keys
+ *   (`__proto__`/`constructor`/`prototype`), schema present, default
+ *   satisfies schema, debounceMs is a non-negative integer, no key
+ *   collision with propsSpec, and `deriveContextDefault` yields a
+ *   non-undefined initial value (see `validateContextStructure`).
+ * - Cross-reference invariants (`actionSpec.nextStep`,
+ *   `streamSpec.source.tool` resolve to `agentCapabilities.tools[*]`).
+ * - Name invariants (no collision across actionSpec / streamSpec /
+ *   contextSpec; no `_ggui:` reserved-prefix keys).
+ * - Schema-compat invariants (`actionSpec[*].schema` ⊆
+ *   `tool.inputSchema`; `streamSpec[*].schema` ⊇ `tool.outputSchema`).
+ */
+export declare function validateContractStructure(contract: DataContract): ValidationResult;
+export declare class ContractViolationError extends Error {
+    readonly violations: ContractViolation[];
+    readonly tool: 'ggui_push' | 'ggui_update' | 'ggui_emit' | 'ggui_event';
+    readonly hint: string;
+    constructor(opts: {
+        tool: 'ggui_push' | 'ggui_update' | 'ggui_emit' | 'ggui_event';
+        violations: ContractViolation[];
+        hint?: string;
+    });
+    /** Structured payload for MCP error response `data` field. */
+    toErrorData(): {
+        error: 'contract_violation';
+        tool: string;
+        violations: ContractViolation[];
+        hint: string;
+    };
+}
+//# sourceMappingURL=contract-validator.d.ts.map

package/dist/validation/contract-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-validator.d.ts","sourceRoot":"","sources":["../../src/validation/contract-validator.ts"],"names":[],"mappings":"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"}