@xemahq/ui-kernel 0.11.0 → 0.11.2

package/src/vista/html/CustomUiFrame.spec.tsx

@@ -1,127 +0,0 @@
-/**
- * CustomUiFrame — the executes-author-code security surface.
- *
- * Asserts the opaque-origin posture on the rendered iframe: sandbox is
- * `allow-scripts` with NO `allow-same-origin`, the srcdoc pins the server SRI
- * hash as the CSP script-src, and the chunk bytes are the inline module script.
- * The static-document form is asserted too: same containment, `script-src
- * 'none'`, so an authored `<script>` can never run.
- *
- * The final block MUTATION-tests the sandbox invariant IN ISOLATION: it proves
- * the suite goes RED if `allow-same-origin` is ever added to the sandbox token
- * (which would dissolve the origin boundary), independent of the CSP-hash
- * mutation proof in `custom-ui-srcdoc.spec.ts`.
- *
- * Migrated from `app-forge-web` when the frame was promoted into the UI kernel;
- * runs under the host-web vitest mirror (this package carries no vitest dep).
- */
-import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it, vi } from 'vitest';
-
-import {
-  createNavigateIntentSet,
-  CustomUiIntentKind,
-  NO_CUSTOM_UI_INTENTS,
-} from './custom-ui-intents';
-import { CustomUiFrame } from './CustomUiFrame';
-
-const INTEGRITY = 'sha384-AbC123def456Ghi789jklMnoPqr';
-const COMPILED = 'export default function C(){return null}';
-// The style import is a HOST concern (the kernel defaults to its own reset) —
-// this test is about the security surface, so it pins a trivial stylesheet.
-const STYLE_CSS = ':root{--x:1}';
-
-function parseIframe(markup: string): Element {
-  const doc = new DOMParser().parseFromString(markup, 'text/html');
-  const iframe = doc.querySelector('iframe');
-  if (!iframe) {
-    throw new Error('no iframe rendered');
-  }
-  return iframe;
-}
-
-function renderFrame() {
-  return parseIframe(
-    renderToStaticMarkup(
-      <CustomUiFrame
-        content={{ compiledOutput: COMPILED, integrity: INTEGRITY }}
-        componentProps={{ records: [] }}
-        intents={createNavigateIntentSet({
-          [CustomUiIntentKind.Navigate]: vi.fn(),
-        })}
-        styleCss={STYLE_CSS}
-        title="Test custom view"
-      />,
-    ),
-  );
-}
-
-function renderDocumentFrame(document: string) {
-  return parseIframe(
-    renderToStaticMarkup(
-      <CustomUiFrame
-        content={{ document }}
-        intents={NO_CUSTOM_UI_INTENTS}
-        styleCss={STYLE_CSS}
-        title="Test static document"
-      />,
-    ),
-  );
-}
-
-describe('CustomUiFrame security posture', () => {
-  it('renders an opaque-origin sandbox: allow-scripts, NO allow-same-origin', () => {
-    const iframe = renderFrame();
-    expect(iframe.getAttribute('sandbox')).toBe('allow-scripts');
-    expect(iframe.getAttribute('sandbox')).not.toContain('allow-same-origin');
-  });
-
-  it('pins the server integrity as the CSP script-src in the srcdoc', () => {
-    const srcdoc = renderFrame().getAttribute('srcdoc') ?? '';
-    expect(srcdoc).toContain(`script-src '${INTEGRITY}'`);
-    expect(srcdoc).toContain(`default-src 'none'`);
-  });
-
-  it('inlines the chunk bytes as the one module script', () => {
-    const srcdoc = renderFrame().getAttribute('srcdoc') ?? '';
-    expect(srcdoc).toContain(`<script type="module">${COMPILED}</script>`);
-    expect(srcdoc).toContain('<div id="root"></div>');
-  });
-
-  // ── MUTATION TEST (sandbox invariant, isolated) ────────────────────────────
-  // Prove the assertion is load-bearing: if the component were changed to
-  // `sandbox="allow-scripts allow-same-origin"`, THIS exact assertion fails.
-  it('MUTATION: adding allow-same-origin to the sandbox token is caught', () => {
-    const sandbox = renderFrame().getAttribute('sandbox') ?? '';
-    // Exact-match pin: any extra token (e.g. allow-same-origin) breaks equality.
-    expect(sandbox).toBe('allow-scripts');
-    // And the explicit negative guard the mutation would trip.
-    const mutated = 'allow-scripts allow-same-origin';
-    expect(sandbox).not.toBe(mutated);
-  });
-});
-
-describe('CustomUiFrame static-document form', () => {
-  it("renders an untrusted document with script-src 'none' in the same sandbox", () => {
-    const iframe = renderDocumentFrame('<h1>Report</h1>');
-    expect(iframe.getAttribute('sandbox')).toBe('allow-scripts');
-    const srcdoc = iframe.getAttribute('srcdoc') ?? '';
-    expect(srcdoc).toContain(`script-src 'none'`);
-    expect(srcdoc).toContain(`default-src 'none'`);
-    expect(srcdoc).toContain('<h1>Report</h1>');
-  });
-
-  it('renders a visible notice (no iframe) when the document cannot be built safely', () => {
-    const markup = renderToStaticMarkup(
-      <CustomUiFrame
-        content={{ document: '<p>x</p></script><script>alert(1)</script>' }}
-        intents={NO_CUSTOM_UI_INTENTS}
-        styleCss={STYLE_CSS}
-        title="Unsafe document"
-      />,
-    );
-    expect(markup).toContain('role="alert"');
-    expect(markup).toContain('could not be prepared safely');
-    expect(markup).not.toContain('<iframe');
-  });
-});

package/src/vista/html/CustomUiFrame.tsx

@@ -1,206 +0,0 @@
-/**
- * `CustomUiFrame` — the reusable, security-hardened renderer for untrusted UI.
- * It runs author-/agent-authored content inside an OPAQUE-ORIGIN sandbox iframe
- * and bridges it to the host over the frozen `postMessage` contract.
- *
- * Promoted from `app-forge-web` into the UI kernel (Canopy §8.3) so App Forge's
- * runtime views and the Vista `html` surface share ONE hardened frame. The
- * intent set is now supplied by the mounting surface
- * ({@link CustomUiIntentSet}); everything below is carried over verbatim.
- *
- * Security posture (NON-NEGOTIABLE — this renders untrusted content):
- *   • sandbox="allow-scripts" and NO allow-same-origin → the frame runs in a
- *     unique opaque origin and cannot reach host DOM, cookies, localStorage or
- *     tokens.
- *   • srcdoc with a `<meta>` CSP that pins the chunk's server SRI hash as the
- *     sole script-src (or `'none'` for a static document) and sets default-src
- *     'none' → no network, only the exact pinned bytes execute. See
- *     {@link buildCustomUiSrcDoc} / {@link buildUntrustedHtmlSrcDoc}.
- *   • Every inbound message is validated by {@link classifyFrameMessage}
- *     (source-window identity + protocol + closed type set) before the host
- *     acts. Intents are validated against a closed set and performed by the
- *     host — the frame never acts with the user's authority.
- *
- * The host pushes read-only props on `frameReady` (and re-pushes when they
- * change), performs validated intents, and surfaces a render error the frame
- * reports — never a blank frame.
- */
-import { AlertTriangle } from 'lucide-react';
-import { useEffect, useMemo, useRef, useState, type ReactElement } from 'react';
-
-import { classifyFrameMessage } from './custom-ui-frame-bridge';
-import {
-  hostPropsMessage,
-  type CustomUiComponentProps,
-} from './custom-ui-frame-contract';
-import { type CustomUiIntentSet } from './custom-ui-intents';
-import {
-  CUSTOM_UI_FRAME_RESET_CSS,
-  buildCustomUiSrcDoc,
-  buildUntrustedHtmlSrcDoc,
-} from './custom-ui-srcdoc';
-import { cn } from '../../ui/cn';
-
-/** What the frame renders. Exactly one of the two forms. */
-export type CustomUiFrameContent =
-  | {
-      /** A server-compiled, SRI-pinned, self-mounting ESM chunk. */
-      readonly compiledOutput: string;
-      /** Server SRI/CSP token (`sha384-<base64>`) pinning the chunk bytes. */
-      readonly integrity: string;
-    }
-  | {
-      /** An untrusted HTML document. Rendered with `script-src 'none'`. */
-      readonly document: string;
-    };
-
-export interface CustomUiFrameProps<TIntent> {
-  /** The content to render. */
-  readonly content: CustomUiFrameContent;
-  /** Read-only, serializable props handed to a compiled component. */
-  readonly componentProps?: CustomUiComponentProps;
-  /** The CLOSED intent set this frame may exercise against the host. */
-  readonly intents: CustomUiIntentSet<TIntent>;
-  /**
-   * CSS inlined into the frame (the frame cannot fetch a stylesheet — its CSP
-   * is `default-src 'none'`). Defaults to {@link CUSTOM_UI_FRAME_RESET_CSS};
-   * hosts prepend it to their own design-token CSS.
-   */
-  readonly styleCss?: string;
-  /** Accessible title for the iframe. */
-  readonly title: string;
-  readonly className?: string;
-}
-
-const EMPTY_PROPS: CustomUiComponentProps = {};
-
-export function CustomUiFrame<TIntent>({
-  content,
-  componentProps = EMPTY_PROPS,
-  intents,
-  styleCss = CUSTOM_UI_FRAME_RESET_CSS,
-  title,
-  className,
-}: CustomUiFrameProps<TIntent>): ReactElement {
-  const iframeRef = useRef<HTMLIFrameElement | null>(null);
-  const [frameError, setFrameError] = useState<string | null>(null);
-
-  // Latest props/intent set, read by the message listener without
-  // re-subscribing (the listener is attached once; a props re-render is handled
-  // by a dedicated effect below).
-  const propsRef = useRef(componentProps);
-  propsRef.current = componentProps;
-  const intentsRef = useRef(intents);
-  intentsRef.current = intents;
-  const readyRef = useRef(false);
-
-  // The srcdoc is a pure function of the content identity + inlined styles — it
-  // does NOT depend on props (props flow over postMessage, not by re-mounting
-  // the frame). Recomputing only on content change avoids reloading the frame
-  // on every prop update.
-  // The builders throw on content that would truncate the inline module (a
-  // `</script`-bearing body) — surface it as a visible error rather than
-  // white-screening. `null` srcDoc ⇒ render the notice, no iframe.
-  const isCompiled = 'compiledOutput' in content;
-  const compiledOutput = isCompiled ? content.compiledOutput : null;
-  const integrity = isCompiled ? content.integrity : null;
-  const document = isCompiled ? null : content.document;
-  const srcDoc = useMemo<string | null>(() => {
-    try {
-      return compiledOutput !== null && integrity !== null
-        ? buildCustomUiSrcDoc({ compiledOutput, integrity, styleCss })
-        : buildUntrustedHtmlSrcDoc({ document: document ?? '', styleCss });
-    } catch {
-      return null;
-    }
-  }, [compiledOutput, integrity, document, styleCss]);
-
-  // Fresh content is a fresh frame lifecycle — reset ready + error state.
-  useEffect(() => {
-    readyRef.current = false;
-    setFrameError(null);
-  }, [srcDoc]);
-
-  useEffect(() => {
-    function onMessage(event: MessageEvent): void {
-      const frameWindow = iframeRef.current?.contentWindow ?? null;
-      const classified = classifyFrameMessage(
-        event,
-        frameWindow,
-        intentsRef.current.parse,
-      );
-      switch (classified.kind) {
-        case 'ready':
-          readyRef.current = true;
-          setFrameError(null);
-          frameWindow?.postMessage(hostPropsMessage(propsRef.current), '*');
-          return;
-        case 'intent':
-          intentsRef.current.perform(classified.intent);
-          return;
-        case 'error':
-          setFrameError(classified.message);
-          return;
-        case 'ignored':
-          return;
-      }
-    }
-    window.addEventListener('message', onMessage);
-    return () => window.removeEventListener('message', onMessage);
-  }, []);
-
-  // Re-push props to an already-ready frame when they change (repeatable
-  // re-render, per the HostProps contract). Before ready, the frameReady
-  // handler above pushes the current props — so no update is lost.
-  useEffect(() => {
-    if (!readyRef.current) {
-      return;
-    }
-    iframeRef.current?.contentWindow?.postMessage(
-      hostPropsMessage(componentProps),
-      '*',
-    );
-  }, [componentProps]);
-
-  if (srcDoc === null) {
-    return (
-      <div className={className}>
-        <div
-          role="alert"
-          className="flex items-start gap-2 rounded border border-destructive/40 bg-destructive/5 p-3 text-sm text-destructive"
-        >
-          <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
-          <span>
-            This custom view could not be prepared safely and was not rendered.
-          </span>
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <div className={cn('flex h-full min-h-0 flex-col', className)}>
-      {frameError !== null ? (
-        <div
-          role="alert"
-          className="mb-2 flex items-start gap-2 rounded border border-destructive/40 bg-destructive/5 p-3 text-sm text-destructive"
-        >
-          <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
-          <span>This custom view failed to render: {frameError}</span>
-        </div>
-      ) : null}
-      <iframe
-        ref={iframeRef}
-        title={title}
-        // OPAQUE ORIGIN: allow-scripts ONLY. Adding allow-same-origin would
-        // dissolve the origin boundary and give author code access to host
-        // cookies/DOM/tokens — never add it.
-        sandbox="allow-scripts"
-        srcDoc={srcDoc}
-        className="min-h-[24rem] w-full flex-1 rounded border border-rule bg-paper"
-      />
-    </div>
-  );
-}
-
-export default CustomUiFrame;

package/src/vista/html/custom-ui-frame-bridge.spec.ts

@@ -1,191 +0,0 @@
-/**
- * The host-side inbound-message classifier — the security gate for every
- * message the host acts on. Proves it REJECTS a wrong-source message, a
- * wrong-protocol message, an unknown type, and a well-formed envelope carrying
- * an unknown intent; and that it correctly classifies frameReady / a valid
- * intent / a render error. Also proves frameReady is answered with a hostProps
- * message (via the paired builder), and that a frame mounted with the EMPTY
- * intent set can never get an intent performed.
- *
- * Migrated from `app-forge-web` when the frame was promoted into the UI kernel
- * (the intent parser is now an argument instead of a hard-wired import — every
- * gate is otherwise unchanged); runs under the host-web vitest mirror.
- */
-import { describe, expect, it } from 'vitest';
-
-import { classifyFrameMessage } from './custom-ui-frame-bridge';
-import {
-  CUSTOM_UI_FRAME_PROTOCOL,
-  CustomUiFrameMessageType,
-  hostPropsMessage,
-} from './custom-ui-frame-contract';
-import {
-  CustomUiIntentKind,
-  NO_CUSTOM_UI_INTENTS,
-  parseCustomUiIntent,
-} from './custom-ui-intents';
-
-// A stand-in for the iframe's contentWindow — identity is all the gate checks.
-const FRAME_WINDOW = { name: 'frame' } as unknown as Window;
-const OTHER_WINDOW = { name: 'other' } as unknown as Window;
-
-function evt(
-  data: unknown,
-  source: Window | null,
-): Pick<MessageEvent, 'source' | 'data'> {
-  return { data, source };
-}
-
-describe('classifyFrameMessage', () => {
-  it('classifies a valid frameReady', () => {
-    const result = classifyFrameMessage(
-      evt(
-        {
-          type: CustomUiFrameMessageType.FrameReady,
-          protocol: CUSTOM_UI_FRAME_PROTOCOL,
-        },
-        FRAME_WINDOW,
-      ),
-      FRAME_WINDOW,
-      parseCustomUiIntent,
-    );
-    expect(result).toEqual({ kind: 'ready' });
-  });
-
-  it('classifies a valid frameIntent into a typed intent', () => {
-    const result = classifyFrameMessage(
-      evt(
-        {
-          type: CustomUiFrameMessageType.FrameIntent,
-          protocol: CUSTOM_UI_FRAME_PROTOCOL,
-          intent: { kind: 'navigate', href: '/apps/x/page' },
-        },
-        FRAME_WINDOW,
-      ),
-      FRAME_WINDOW,
-      parseCustomUiIntent,
-    );
-    expect(result).toEqual({
-      kind: 'intent',
-      intent: { kind: CustomUiIntentKind.Navigate, href: '/apps/x/page' },
-    });
-  });
-
-  it('classifies a frameError, surfacing the message', () => {
-    const result = classifyFrameMessage(
-      evt(
-        {
-          type: CustomUiFrameMessageType.FrameError,
-          protocol: CUSTOM_UI_FRAME_PROTOCOL,
-          message: 'boom',
-        },
-        FRAME_WINDOW,
-      ),
-      FRAME_WINDOW,
-      parseCustomUiIntent,
-    );
-    expect(result).toEqual({ kind: 'error', message: 'boom' });
-  });
-
-  it('REJECTS a message from the wrong source window', () => {
-    const result = classifyFrameMessage(
-      evt(
-        {
-          type: CustomUiFrameMessageType.FrameReady,
-          protocol: CUSTOM_UI_FRAME_PROTOCOL,
-        },
-        OTHER_WINDOW,
-      ),
-      FRAME_WINDOW,
-      parseCustomUiIntent,
-    );
-    expect(result).toEqual({ kind: 'ignored' });
-  });
-
-  it('REJECTS a message with the wrong protocol', () => {
-    const result = classifyFrameMessage(
-      evt(
-        { type: CustomUiFrameMessageType.FrameReady, protocol: 999 },
-        FRAME_WINDOW,
-      ),
-      FRAME_WINDOW,
-      parseCustomUiIntent,
-    );
-    expect(result).toEqual({ kind: 'ignored' });
-  });
-
-  it('REJECTS an unknown message type', () => {
-    const result = classifyFrameMessage(
-      evt(
-        {
-          type: 'xema.customui.somethingElse',
-          protocol: CUSTOM_UI_FRAME_PROTOCOL,
-        },
-        FRAME_WINDOW,
-      ),
-      FRAME_WINDOW,
-      parseCustomUiIntent,
-    );
-    expect(result).toEqual({ kind: 'ignored' });
-  });
-
-  it('REJECTS a well-formed envelope carrying an unknown intent', () => {
-    const result = classifyFrameMessage(
-      evt(
-        {
-          type: CustomUiFrameMessageType.FrameIntent,
-          protocol: CUSTOM_UI_FRAME_PROTOCOL,
-          intent: { kind: 'wipe-db' },
-        },
-        FRAME_WINDOW,
-      ),
-      FRAME_WINDOW,
-      parseCustomUiIntent,
-    );
-    expect(result).toEqual({ kind: 'ignored' });
-  });
-
-  it('REJECTS when no frame window is mounted yet', () => {
-    const result = classifyFrameMessage(
-      evt(
-        {
-          type: CustomUiFrameMessageType.FrameReady,
-          protocol: CUSTOM_UI_FRAME_PROTOCOL,
-        },
-        FRAME_WINDOW,
-      ),
-      null,
-      parseCustomUiIntent,
-    );
-    expect(result).toEqual({ kind: 'ignored' });
-  });
-
-  // The intent set is now supplied by the mounting surface — a frame mounted
-  // with the EMPTY set has no authority, so even a perfectly-formed navigate
-  // envelope is ignored.
-  it('REJECTS every intent when mounted with the EMPTY intent set', () => {
-    const result = classifyFrameMessage(
-      evt(
-        {
-          type: CustomUiFrameMessageType.FrameIntent,
-          protocol: CUSTOM_UI_FRAME_PROTOCOL,
-          intent: { kind: 'navigate', href: '/apps/x/page' },
-        },
-        FRAME_WINDOW,
-      ),
-      FRAME_WINDOW,
-      NO_CUSTOM_UI_INTENTS.parse,
-    );
-    expect(result).toEqual({ kind: 'ignored' });
-  });
-
-  it('answers frameReady with a hostProps message (paired builder)', () => {
-    const props = { records: [{ id: 'r1' }] };
-    const message = hostPropsMessage(props);
-    expect(message).toEqual({
-      type: CustomUiFrameMessageType.HostProps,
-      protocol: CUSTOM_UI_FRAME_PROTOCOL,
-      props,
-    });
-  });
-});

package/src/vista/html/custom-ui-frame-bridge.ts

@@ -1,98 +0,0 @@
-/**
- * The host-side inbound-message classifier for the sandbox-frame bridge.
- *
- * Every `message` event the host window receives while a frame is mounted
- * passes through {@link classifyFrameMessage}. It enforces the security gate
- * BEFORE the host acts on anything:
- *
- *   1. SOURCE IDENTITY — `event.source` must be the frame's own
- *      `contentWindow`. We compare the window identity, NOT `event.origin`: an
- *      opaque-origin sandbox frame (no `allow-same-origin`) reports its origin
- *      as the string `"null"`, so origin is useless as an allow-check. Window
- *      identity is unforgeable across the boundary.
- *   2. PROTOCOL — `event.data.protocol` must equal the pinned protocol version.
- *   3. TYPE — `event.data.type` must be a member of the closed
- *      {@link CustomUiFrameMessageType} set.
- *
- * Anything failing any gate is classified `ignored` and the host does nothing.
- * A valid message is narrowed to a typed, discriminated result the caller acts
- * on. The intent payload is parsed against the mounting surface's CLOSED intent
- * set here too, so a frame that posts a well-formed envelope but an
- * unknown/invalid intent is still `ignored` — never performed.
- *
- * Promoted from `app-forge-web` into the UI kernel (Canopy §8.3). The only
- * change is that the intent set is a parameter instead of a hard-wired import;
- * every gate is carried over verbatim.
- */
-import {
-  CUSTOM_UI_FRAME_PROTOCOL,
-  CustomUiFrameMessageType,
-} from './custom-ui-frame-contract';
-
-/** The typed outcome of classifying one inbound frame message. */
-export type ClassifiedFrameMessage<TIntent> =
-  | { readonly kind: 'ready' }
-  | { readonly kind: 'intent'; readonly intent: TIntent }
-  | { readonly kind: 'error'; readonly message: string }
-  | { readonly kind: 'ignored' };
-
-const IGNORED: ClassifiedFrameMessage<never> = { kind: 'ignored' };
-
-/**
- * Classify an inbound `message` event from a sandbox frame. `frameWindow` is the
- * mounted iframe's `contentWindow` (may be `null` before mount); `parseIntent`
- * is the mounting surface's closed-set parser (returns `null` to reject).
- * Returns a typed result; every rejection path returns `ignored` (fail-safe —
- * the host performs nothing on a message it cannot fully validate).
- */
-export function classifyFrameMessage<TIntent>(
-  event: Pick<MessageEvent, 'source' | 'data'>,
-  frameWindow: Window | null,
-  parseIntent: (raw: unknown) => TIntent | null,
-): ClassifiedFrameMessage<TIntent> {
-  // Gate 1: source identity. Reject if we have no frame yet or the message did
-  // not come from THIS frame's window.
-  if (frameWindow === null || event.source !== frameWindow) {
-    return IGNORED;
-  }
-
-  const data = event.data;
-  if (data === null || typeof data !== 'object') {
-    return IGNORED;
-  }
-  const envelope = data as {
-    protocol?: unknown;
-    type?: unknown;
-    intent?: unknown;
-    message?: unknown;
-  };
-
-  // Gate 2: protocol version.
-  if (envelope.protocol !== CUSTOM_UI_FRAME_PROTOCOL) {
-    return IGNORED;
-  }
-
-  // Gate 3: closed message-type set.
-  switch (envelope.type) {
-    case CustomUiFrameMessageType.FrameReady:
-      return { kind: 'ready' };
-    case CustomUiFrameMessageType.FrameIntent: {
-      const intent = parseIntent(envelope.intent);
-      // A valid envelope carrying an unknown/invalid intent is rejected, not
-      // performed.
-      return intent === null ? IGNORED : { kind: 'intent', intent };
-    }
-    case CustomUiFrameMessageType.FrameError:
-      return {
-        kind: 'error',
-        message:
-          typeof envelope.message === 'string'
-            ? envelope.message
-            : 'The custom view failed to render.',
-      };
-    default:
-      // Includes HostProps (host→frame only, never inbound) and any unknown
-      // string — ignored.
-      return IGNORED;
-  }
-}