@xemahq/ui-kernel 0.8.0 → 0.9.1

package/src/vista/form-payload.spec.ts

@@ -0,0 +1,93 @@
+/**
+ * Guards `validateFormPayload` — the structural half of "the value never
+ * reaches the agent".
+ *
+ * The validator is what makes the submit target un-aimable at the host's own
+ * origin (where the BFF / chat transport lives): only an ABSOLUTE `http(s)`
+ * URL is accepted, and a rejected payload draws the typed fallback card rather
+ * than a form.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { CaptureFieldType } from '../ui/capture/field-spec';
+
+import { validateFormPayload } from './vista-payloads';
+
+const BASE = {
+  ref: 'ref-1',
+  purpose: 'Connect Acme so I can read your tickets.',
+  submitUrl: 'https://connector-gateway.example.test/credential-elicitations/ref-1/submit',
+  statusUrl: 'https://connector-gateway.example.test/credential-elicitations/ref-1',
+  fields: [
+    {
+      key: 'apiKey',
+      label: 'API key',
+      type: CaptureFieldType.String,
+      required: true,
+      isSecret: true,
+      transform: 'trim',
+    },
+    { key: 'baseUrl', label: 'Base URL', type: CaptureFieldType.Url, required: true, isSecret: false },
+  ],
+};
+
+describe('validateFormPayload', () => {
+  it('accepts a well-formed field-mode payload and preserves declared secrecy', () => {
+    const payload = validateFormPayload(BASE);
+    expect(payload).not.toBeNull();
+    expect(payload?.fields).toHaveLength(2);
+    expect(payload?.fields[0]?.isSecret).toBe(true);
+    expect(payload?.fields[1]?.isSecret).toBe(false);
+    expect(payload?.fields[0]?.transform).toBe('trim');
+  });
+
+  it('REJECTS a host-relative submit URL — it could only hit the app itself', () => {
+    expect(validateFormPayload({ ...BASE, submitUrl: '/credential-elicitations/ref-1/submit' })).toBeNull();
+    expect(validateFormPayload({ ...BASE, submitUrl: '//evil.example/x' })).toBeNull();
+    expect(validateFormPayload({ ...BASE, submitUrl: 'javascript:alert(1)' })).toBeNull();
+    expect(validateFormPayload({ ...BASE, statusUrl: '/credential-elicitations/ref-1' })).toBeNull();
+  });
+
+  it('accepts an EMPTY field schema — the service is the authority, not the client', () => {
+    const payload = validateFormPayload({ ...BASE, fields: [] });
+    expect(payload).not.toBeNull();
+    expect(payload?.fields).toEqual([]);
+  });
+
+  it('rejects a malformed field spec rather than half-rendering it', () => {
+    expect(validateFormPayload({ ...BASE, fields: [{ key: 'a', label: 'A', type: 'nope' }] })).toBeNull();
+    expect(validateFormPayload({ ...BASE, fields: [{ key: 'a', label: 'A' }] })).toBeNull();
+    expect(
+      validateFormPayload({
+        ...BASE,
+        fields: [{ key: 'a', label: 'A', type: CaptureFieldType.String, isSecret: 'yes' }],
+      }),
+    ).toBeNull();
+    expect(validateFormPayload({ ...BASE, fields: {} })).toBeNull();
+  });
+
+  it('accepts a launch (oauth2 / app_install) payload with an absolute URL', () => {
+    const payload = validateFormPayload({
+      ...BASE,
+      fields: [],
+      launch: { url: 'https://acme.example.test/oauth/authorize?x=1', label: 'Continue to Acme', hint: 'h' },
+    });
+    expect(payload?.launch).toEqual({
+      url: 'https://acme.example.test/oauth/authorize?x=1',
+      label: 'Continue to Acme',
+      hint: 'h',
+    });
+  });
+
+  it('rejects a launch with a relative URL or no label', () => {
+    expect(validateFormPayload({ ...BASE, launch: { url: '/authorize', label: 'Go' } })).toBeNull();
+    expect(
+      validateFormPayload({ ...BASE, launch: { url: 'https://acme.example.test/a', label: '' } }),
+    ).toBeNull();
+  });
+
+  it('rejects a missing ref', () => {
+    expect(validateFormPayload({ ...BASE, ref: '' })).toBeNull();
+    expect(validateFormPayload({ ...BASE, ref: undefined })).toBeNull();
+  });
+});

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

@@ -0,0 +1,125 @@
+/**
+ * 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

@@ -0,0 +1,204 @@
+/**
+ * `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

@@ -0,0 +1,191 @@
+/**
+ * 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,
+    });
+  });
+});