@xemahq/ui-kernel 0.9.0 → 0.9.1

package/src/vista/VistaPanel.tsx

@@ -0,0 +1,155 @@
+/**
+ * `VistaPanel` — the ONE tabbed render plane.
+ *
+ * It replaces the three hand-rolled tab strips the frontend carried (the thin
+ * session workspace, the Design-System-Builder preview, and App Forge's
+ * preview): tab chrome is {@link OverflowTabs} (auto-collapsing "More…" instead
+ * of a horizontal-scroll strip, active + pinned always visible), tab STATE is
+ * {@link useVistaTabs}, and the body is whatever the Vista surface registry
+ * resolves the active {@link VistaTab} to.
+ *
+ * The panel is presentation only: it never fetches, never authorises, and never
+ * decides what a kind means. Resolution follows the three-layer guarantee —
+ * a registered renderer wins, else the generic schema-driven renderer the
+ * catalogue sync installed, else {@link SurfaceFallbackCard} with a typed
+ * reason. It never throws and never blanks.
+ */
+import { type ReactElement, type ReactNode } from 'react';
+
+import { surfaceKindIcon } from './surface-icons';
+import { vistaSurfaceRegistry } from './surface-registry';
+import { SurfaceFallbackCard } from './SurfaceFallbackCard';
+import { cn } from '../ui/cn';
+import { OverflowTabs, type OverflowTab } from '../ui/primitives/overflow-tabs';
+
+import type { VistaTab } from './vista-model';
+
+export interface VistaPanelProps {
+  /** Every open tab, in display order (pinned first). */
+  readonly tabs: readonly VistaTab[];
+  /** The focused tab, or `null` when the panel holds no tabs. */
+  readonly activeTabId: string | null;
+  readonly onActivate: (tabId: string) => void;
+  /**
+   * Close handler. Omit for a panel whose tabs are all host-owned; pinned tabs
+   * never render a close affordance regardless.
+   */
+  readonly onClose?: (tabId: string) => void;
+  /** Optional action rendered at the right edge of the tab bar. */
+  readonly tabBarAction?: ReactNode;
+  /**
+   * Tab ids to mark with the strip's attention dot — "this tab changed while
+   * you were looking elsewhere". The panel does not decide what "changed"
+   * means; the owner does.
+   */
+  readonly indicatorTabIds?: readonly string[];
+  /** Rendered when there are no tabs at all. */
+  readonly emptyState?: ReactNode;
+  readonly className?: string;
+}
+
+export function VistaPanel({
+  tabs,
+  activeTabId,
+  onActivate,
+  onClose,
+  tabBarAction,
+  indicatorTabIds,
+  emptyState,
+  className,
+}: VistaPanelProps): ReactElement {
+  const active = tabs.find((t) => t.tabId === activeTabId) ?? null;
+  return (
+    <div
+      className={cn(
+        'flex h-full min-h-0 min-w-0 flex-1 flex-col overflow-hidden',
+        className,
+      )}
+    >
+      <VistaTabBar
+        tabs={tabs}
+        activeTabId={activeTabId}
+        onActivate={onActivate}
+        {...(onClose ? { onClose } : {})}
+        {...(tabBarAction === undefined ? {} : { tabBarAction })}
+        {...(indicatorTabIds === undefined ? {} : { indicatorTabIds })}
+      />
+      <div className="min-h-0 flex-1 overflow-hidden">
+        {active === null ? (
+          <>{emptyState ?? null}</>
+        ) : (
+          <VistaSurfaceBody tab={active} />
+        )}
+      </div>
+    </div>
+  );
+}
+
+export type VistaTabBarProps = Omit<
+  VistaPanelProps,
+  'emptyState' | 'className'
+> & { readonly className?: string };
+
+/**
+ * The tab STRIP alone. Exported so a surface whose chrome interleaves other
+ * controls between the tabs and the body (the Design-System-Builder's browser
+ * chrome puts a URL + action row there) composes the SAME strip instead of
+ * hand-rolling a second one. `VistaPanel` is just this plus
+ * {@link VistaSurfaceBody}.
+ */
+export function VistaTabBar({
+  tabs,
+  activeTabId,
+  onActivate,
+  onClose,
+  tabBarAction,
+  indicatorTabIds,
+  className,
+}: VistaTabBarProps): ReactElement {
+  const overflowTabs: OverflowTab[] = tabs.map((tab) => {
+    const entry: {
+      value: string;
+      label: string;
+      pinned?: boolean;
+      indicator?: boolean;
+      icon?: OverflowTab['icon'];
+    } = { value: tab.tabId, label: tab.title };
+    if (tab.pinned === true) entry.pinned = true;
+    if (indicatorTabIds?.includes(tab.tabId) === true) entry.indicator = true;
+    const icon = surfaceKindIcon(tab.kind);
+    if (icon !== undefined) entry.icon = icon;
+    return entry;
+  });
+  return (
+    <div className={cn('flex shrink-0 items-end gap-2 px-2', className)}>
+      <div className="min-w-0 flex-1">
+        <OverflowTabs
+          tabs={overflowTabs}
+          value={activeTabId ?? ''}
+          onChange={onActivate}
+          {...(onClose ? { onClose } : {})}
+        />
+      </div>
+      {tabBarAction}
+    </div>
+  );
+}
+
+/**
+ * Resolve ONE tab through the registry and draw it. Split out so the resolution
+ * decision (and therefore the fallback reason) is inspectable in isolation.
+ */
+export function VistaSurfaceBody({
+  tab,
+}: Readonly<{ tab: VistaTab }>): ReactElement {
+  const resolution = vistaSurfaceRegistry.resolve(tab);
+  if (resolution.matched) return resolution.rendered;
+  return (
+    <SurfaceFallbackCard
+      kind={resolution.kind}
+      reason={resolution.reason}
+      payload={tab.payload}
+      title={tab.title}
+    />
+  );
+}

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;