@xemahq/ui-kernel 0.11.1 → 0.12.0

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

@@ -1,88 +0,0 @@
-/**
- * The frozen custom-UI frame wire contract — the HOST side of the ONLY channel
- * across the sandbox-frame boundary.
- *
- * Promoted from `app-forge-web` into the UI kernel (Canopy §8.3) so every plane
- * that renders untrusted, author-authored UI — App Forge's runtime views AND
- * the Vista `html` surface — speaks ONE protocol through ONE hardened frame.
- *
- * A compiled custom-UI chunk (self-mounting ESM, running inside a strict-CSP,
- * opaque-origin iframe) speaks exactly these four message `type`s at exactly
- * this protocol version. The chunk's self-mount wrapper is generated by the
- * app-function-broker from its OWN copy of these values
- * (`repos/xema-cultivars/biomes/platform/app-function-broker/api/src/compile/ui/custom-ui-frame-contract.ts`),
- * so the enum members and protocol number here MUST stay byte-for-byte
- * identical to that source of truth. Changing a value is a coordinated,
- * breaking wire change: bump the protocol on BOTH sides in lockstep.
- *
- * The chunk never touches host state directly — it announces readiness, the
- * host pushes props, the component asks the host to perform intents, and a
- * render throw is reported back. The host validates every inbound message
- * (source identity + protocol + closed `type` set) before acting.
- */
-
-/** The frozen protocol version stamped on every frame message. */
-export const CUSTOM_UI_FRAME_PROTOCOL = 1 as const;
-
-/**
- * The closed set of message `type`s exchanged across the frame boundary. The
- * string values are the wire contract and must never diverge from the broker's.
- *
- *  - {@link FrameReady}  frame → host: mounted, ready for props (no payload).
- *  - {@link HostProps}   host → frame: `{ props }`; repeatable to re-render.
- *  - {@link FrameIntent} frame → host: `{ intent }` — the host validates+performs.
- *  - {@link FrameError}  frame → host: `{ message }` — the render threw.
- */
-export enum CustomUiFrameMessageType {
-  FrameReady = 'xema.customui.frameReady',
-  HostProps = 'xema.customui.hostProps',
-  FrameIntent = 'xema.customui.frameIntent',
-  FrameError = 'xema.customui.frameError',
-}
-
-/** frame → host: emitted once on load. */
-export interface FrameReadyMessage {
-  readonly type: CustomUiFrameMessageType.FrameReady;
-  readonly protocol: typeof CUSTOM_UI_FRAME_PROTOCOL;
-}
-
-/** host → frame: the props to render the component with. */
-export interface HostPropsMessage {
-  readonly type: CustomUiFrameMessageType.HostProps;
-  readonly protocol: typeof CUSTOM_UI_FRAME_PROTOCOL;
-  readonly props: CustomUiComponentProps;
-}
-
-/** frame → host: the component asked the host to perform an action. */
-export interface FrameIntentMessage {
-  readonly type: CustomUiFrameMessageType.FrameIntent;
-  readonly protocol: typeof CUSTOM_UI_FRAME_PROTOCOL;
-  readonly intent: unknown;
-}
-
-/** frame → host: the component's render threw. */
-export interface FrameErrorMessage {
-  readonly type: CustomUiFrameMessageType.FrameError;
-  readonly protocol: typeof CUSTOM_UI_FRAME_PROTOCOL;
-  readonly message: string;
-}
-
-/**
- * The read-only props payload handed to a custom-UI component. It MUST be a
- * plain, structured-clone-serializable object — it crosses the frame boundary
- * via `postMessage`. The component also receives an injected `xemaEmit(intent)`
- * function (added inside the frame by the self-mount wrapper, NOT sent over the
- * wire), so this shape carries data only.
- */
-export type CustomUiComponentProps = Record<string, unknown>;
-
-/** Build the host→frame props message (single seam so the shape can't drift). */
-export function hostPropsMessage(
-  props: CustomUiComponentProps,
-): HostPropsMessage {
-  return {
-    type: CustomUiFrameMessageType.HostProps,
-    protocol: CUSTOM_UI_FRAME_PROTOCOL,
-    props,
-  };
-}

package/src/vista/html/custom-ui-intents.spec.ts

@@ -1,135 +0,0 @@
-/**
- * Custom-UI intent parsing/dispatch — the frame asks, the host validates+
- * performs. Proves the closed set rejects unknown kinds and out-of-policy
- * (external) navigation targets, that a valid intent dispatches to its handler,
- * and that the two shipped intent SETS behave as their names promise: the
- * built-in navigate set parses+performs exactly one kind, and
- * `NO_CUSTOM_UI_INTENTS` grants a frame no authority at all.
- *
- * 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 { describe, expect, it, vi } from 'vitest';
-
-import {
-  createNavigateIntentSet,
-  CustomUiIntentKind,
-  NO_CUSTOM_UI_INTENTS,
-  parseCustomUiIntent,
-  performCustomUiIntent,
-  type CustomUiIntentHandlers,
-} from './custom-ui-intents';
-
-describe('parseCustomUiIntent', () => {
-  it('parses a valid host-relative navigate intent', () => {
-    expect(
-      parseCustomUiIntent({ kind: 'navigate', href: '/apps/x/page' }),
-    ).toEqual({ kind: CustomUiIntentKind.Navigate, href: '/apps/x/page' });
-  });
-
-  it('rejects an unknown intent kind', () => {
-    expect(parseCustomUiIntent({ kind: 'delete-everything' })).toBeNull();
-  });
-
-  it('rejects a navigate to an external (protocol-relative) URL', () => {
-    expect(
-      parseCustomUiIntent({ kind: 'navigate', href: '//evil.example.com' }),
-    ).toBeNull();
-  });
-
-  it('rejects a navigate to an absolute external URL', () => {
-    expect(
-      parseCustomUiIntent({ kind: 'navigate', href: 'https://evil.example' }),
-    ).toBeNull();
-  });
-
-  // Regression: a backslash normalises to a forward slash (WHATWG), so `/\host`
-  // is protocol-relative and resolves to a FOREIGN origin — the exact bypass a
-  // prefix-only check (`startsWith('/') && !startsWith('//')`) missed. The
-  // origin-resolution validator MUST reject every backslash form.
-  it('rejects a navigate whose backslash form resolves to a foreign origin', () => {
-    for (const href of [
-      '/\\evil.example.com',
-      '/\\\\evil.example.com',
-      '/\\/evil.example.com',
-      '\\/evil.example.com',
-    ]) {
-      expect(parseCustomUiIntent({ kind: 'navigate', href })).toBeNull();
-    }
-  });
-
-  it('rejects a navigate href containing whitespace or control chars', () => {
-    expect(
-      parseCustomUiIntent({ kind: 'navigate', href: '/ /evil' }),
-    ).toBeNull();
-    expect(parseCustomUiIntent({ kind: 'navigate', href: '/\tx' })).toBeNull();
-  });
-
-  it('rejects a navigate with a non-string href', () => {
-    expect(parseCustomUiIntent({ kind: 'navigate', href: 42 })).toBeNull();
-  });
-
-  it('rejects non-object payloads', () => {
-    expect(parseCustomUiIntent(null)).toBeNull();
-    expect(parseCustomUiIntent('navigate')).toBeNull();
-  });
-});
-
-describe('performCustomUiIntent', () => {
-  it('dispatches a navigate intent to the navigate handler', () => {
-    const navigate = vi.fn();
-    const handlers: CustomUiIntentHandlers = {
-      [CustomUiIntentKind.Navigate]: navigate,
-    };
-    performCustomUiIntent(
-      { kind: CustomUiIntentKind.Navigate, href: '/apps/x' },
-      handlers,
-    );
-    expect(navigate).toHaveBeenCalledWith({
-      kind: CustomUiIntentKind.Navigate,
-      href: '/apps/x',
-    });
-  });
-});
-
-describe('createNavigateIntentSet', () => {
-  it('parses and performs a host-relative navigate, and only that', () => {
-    const navigate = vi.fn();
-    const set = createNavigateIntentSet({
-      [CustomUiIntentKind.Navigate]: navigate,
-    });
-
-    const intent = set.parse({ kind: 'navigate', href: '/apps/x' });
-    expect(intent).toEqual({
-      kind: CustomUiIntentKind.Navigate,
-      href: '/apps/x',
-    });
-    if (intent === null) {
-      throw new Error('expected a parsed navigate intent');
-    }
-    set.perform(intent);
-    expect(navigate).toHaveBeenCalledWith({
-      kind: CustomUiIntentKind.Navigate,
-      href: '/apps/x',
-    });
-
-    // Anything outside the closed set is rejected by `parse` — never performed.
-    expect(set.parse({ kind: 'wipe-db' })).toBeNull();
-    expect(
-      set.parse({ kind: 'navigate', href: 'https://evil.example' }),
-    ).toBeNull();
-  });
-});
-
-describe('NO_CUSTOM_UI_INTENTS', () => {
-  it('grants the frame NO authority: every payload is rejected', () => {
-    for (const raw of [
-      { kind: 'navigate', href: '/apps/x' },
-      { kind: 'wipe-db' },
-      null,
-      'navigate',
-    ]) {
-      expect(NO_CUSTOM_UI_INTENTS.parse(raw)).toBeNull();
-    }
-  });
-});

package/src/vista/html/custom-ui-intents.ts

@@ -1,155 +0,0 @@
-/**
- * The intent plane of the custom-UI frame bridge — now PLUGGABLE.
- *
- * A component running inside the sandbox frame NEVER acts with the user's
- * authority. It posts an intent across the boundary; the host validates it
- * against a CLOSED set and performs it. An unrecognised or malformed intent is
- * rejected — never coerced, never silently dropped into a default action.
- *
- * Promoting this out of App Forge required one change and one only: WHICH
- * closed set applies is now supplied by the mounting surface
- * ({@link CustomUiIntentSet}) instead of being hard-wired. The security shape is
- * unchanged — a set is still a `parse` that returns `null` for anything outside
- * it, plus a `perform` that is exhaustive over it. There is no "accept any
- * intent" set and no free-form action strings.
- *
- * {@link createNavigateIntentSet} is the built-in set every host gets.
- */
-
-/**
- * A closed intent set: parse-or-reject, then perform. `parse` MUST be total and
- * MUST NOT throw — returning `null` is the ONLY way to reject, and the bridge
- * turns that into `ignored`.
- */
-export interface CustomUiIntentSet<TIntent> {
-  parse(raw: unknown): TIntent | null;
-  perform(intent: TIntent): void;
-}
-
-/** Closed set of intent kinds the built-in set understands. */
-export enum CustomUiIntentKind {
-  /** Navigate the host to an in-app path. */
-  Navigate = 'navigate',
-}
-
-/**
- * Navigate intent — the host routes to `href`. Constrained to a host-relative
- * path (leading `/`, no scheme, no protocol-relative `//`) so a frame can never
- * drive the host to an arbitrary external origin.
- */
-export interface NavigateIntent {
-  readonly kind: CustomUiIntentKind.Navigate;
-  readonly href: string;
-}
-
-/** The discriminated union of every intent the BUILT-IN set performs. */
-export type CustomUiIntent = NavigateIntent;
-
-/**
- * Typed handler set for the built-in intents. Exhaustive over
- * {@link CustomUiIntentKind} by construction — adding a kind forces adding a
- * handler here (a compile error otherwise), so no intent kind can ship without
- * a host-side performer.
- */
-export interface CustomUiIntentHandlers {
-  readonly [CustomUiIntentKind.Navigate]: (intent: NavigateIntent) => void;
-}
-
-/**
- * True for a same-origin, host-relative path — the only href a frame may request.
- *
- * A prefix check (`startsWith('/') && !startsWith('//')`) is NOT sufficient:
- * browsers (WHATWG URL) normalize a backslash to a forward slash for special
- * schemes, so `"/\\evil.com"` is protocol-relative and resolves to a FOREIGN
- * origin — a `router.push` of it hard-navigates the victim's top window off to
- * `evil.com` (open redirect / phishing). Author code runs inside the frame and
- * an authored app is viewed by OTHER users, so this is a real cross-user
- * surface. We therefore RESOLVE the href against the current origin and require
- * the resolved origin to be identical — the browser's own parser decides, so no
- * textual-prefix trick (`\`, control chars, whitespace, embedded scheme) can
- * slip a foreign origin past us. A relative href that cannot be parsed, or that
- * escapes the origin, is rejected.
- */
-function isHostRelativePath(href: string): boolean {
-  // Must be rooted at '/'.
-  if (!href.startsWith('/')) {
-    return false;
-  }
-  // A backslash is a protocol-relative/scheme trick after WHATWG normalisation
-  // ("/\\evil.com" -> //evil.com -> foreign origin); whitespace / control
-  // chars can also confuse the parser. Reject any before resolving.
-  if (href.includes('\\')) {
-    return false;
-  }
-  // eslint-disable-next-line no-control-regex
-  if (/[\u0000-\u0020\u007f]/.test(href)) {
-    return false;
-  }
-  let resolved: URL;
-  try {
-    resolved = new URL(href, window.location.origin);
-  } catch {
-    return false;
-  }
-  // The browser's parser is authoritative: the resolved origin MUST equal ours.
-  return resolved.origin === window.location.origin;
-}
-
-/**
- * Parse an untrusted intent payload (arrived from the sandbox frame) into a
- * typed {@link CustomUiIntent}, or `null` if it is not a recognized, valid
- * member of the closed set. Fail-safe: unknown `kind`, wrong payload shape, or
- * an out-of-policy value all return `null` — the caller rejects it.
- */
-export function parseCustomUiIntent(raw: unknown): CustomUiIntent | null {
-  if (raw === null || typeof raw !== 'object') {
-    return null;
-  }
-  const candidate = raw as { kind?: unknown; href?: unknown };
-  switch (candidate.kind) {
-    case CustomUiIntentKind.Navigate:
-      if (typeof candidate.href !== 'string') {
-        return null;
-      }
-      if (!isHostRelativePath(candidate.href)) {
-        return null;
-      }
-      return { kind: CustomUiIntentKind.Navigate, href: candidate.href };
-    default:
-      return null;
-  }
-}
-
-/**
- * Dispatch a parsed intent to its handler. Exhaustive `switch` over the closed
- * set — a new kind added to {@link CustomUiIntentKind} without a `case` here is
- * a compile error (the `never` guard), so the set can never be silently
- * under-served.
- */
-export function performCustomUiIntent(
-  intent: CustomUiIntent,
-  handlers: CustomUiIntentHandlers,
-): void {
-  handlers[CustomUiIntentKind.Navigate](intent);
-}
-
-/** The built-in intent set: host-relative navigation and nothing else. */
-export function createNavigateIntentSet(
-  handlers: CustomUiIntentHandlers,
-): CustomUiIntentSet<CustomUiIntent> {
-  return {
-    parse: parseCustomUiIntent,
-    perform: (intent) => performCustomUiIntent(intent, handlers),
-  };
-}
-
-/**
- * The EMPTY intent set — parses nothing, performs nothing. Mount a frame with
- * this when the rendered content must be strictly presentational (the Vista
- * `html` surface's static-document form). It is an explicit "this frame has no
- * authority", not an absent configuration.
- */
-export const NO_CUSTOM_UI_INTENTS: CustomUiIntentSet<never> = {
-  parse: () => null,
-  perform: () => undefined,
-};

package/src/vista/html/custom-ui-srcdoc.spec.ts

@@ -1,151 +0,0 @@
-/**
- * Custom-UI srcdoc / CSP builder — the security invariant lives HERE.
- *
- * These assertions pin the strict-CSP posture that makes running author- and
- * agent-authored content safe, on BOTH forms the frame renders: the compiled,
- * SRI-pinned chunk (`script-src '<hash>'`) and the untrusted static document
- * (`script-src 'none'`). The mutation blocks prove the invariants IN ISOLATION:
- * the suite goes RED if the CSP `script-src` hash is dropped or loosened (e.g.
- * to `'unsafe-inline'` / a wildcard), or if the static-document policy ever
- * grew a script source.
- *
- * Migrated verbatim 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 { describe, expect, it } from 'vitest';
-
-import {
-  buildCustomUiFrameCsp,
-  buildCustomUiSrcDoc,
-  buildUntrustedHtmlFrameCsp,
-  buildUntrustedHtmlSrcDoc,
-  CustomUiSrcDocError,
-} from './custom-ui-srcdoc';
-
-const INTEGRITY = 'sha384-AbC123+/def456Ghi789jklMnoPqr==';
-const COMPILED = 'export default function C(){return null}';
-
-describe('buildCustomUiFrameCsp', () => {
-  it('emits the exact airtight directive string, pinning the server hash', () => {
-    expect(buildCustomUiFrameCsp(INTEGRITY)).toBe(
-      `default-src 'none'; script-src '${INTEGRITY}'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'`,
-    );
-  });
-
-  it('script-src carries the server integrity token verbatim', () => {
-    expect(buildCustomUiFrameCsp(INTEGRITY)).toContain(
-      `script-src '${INTEGRITY}'`,
-    );
-  });
-
-  it('never grants scripts unsafe-inline or a wildcard', () => {
-    const csp = buildCustomUiFrameCsp(INTEGRITY);
-    expect(csp).not.toContain("script-src 'unsafe-inline'");
-    expect(csp).not.toContain('script-src *');
-    expect(csp).toContain(`default-src 'none'`);
-  });
-});
-
-describe('buildCustomUiSrcDoc', () => {
-  const srcDoc = buildCustomUiSrcDoc({
-    compiledOutput: COMPILED,
-    integrity: INTEGRITY,
-    styleCss: ':root{--x:1}',
-  });
-
-  it('embeds the pinned CSP as a meta http-equiv', () => {
-    expect(srcDoc).toContain(
-      `<meta http-equiv="Content-Security-Policy" content="${buildCustomUiFrameCsp(
-        INTEGRITY,
-      )}" />`,
-    );
-  });
-
-  it('inlines the chunk verbatim as the one module script (hash must match)', () => {
-    expect(srcDoc).toContain(`<script type="module">${COMPILED}</script>`);
-  });
-
-  it('carries the #root mount point the self-mount wrapper renders into', () => {
-    expect(srcDoc).toContain('<div id="root"></div>');
-  });
-
-  it('inlines the design-system style (style-src unsafe-inline)', () => {
-    expect(srcDoc).toContain('<style>:root{--x:1}</style>');
-  });
-
-  it('refuses a chunk containing a literal </script (would truncate the module)', () => {
-    expect(() =>
-      buildCustomUiSrcDoc({
-        compiledOutput: 'const x = "a</script><script>alert(1)</script>";',
-        integrity: INTEGRITY,
-        styleCss: '',
-      }),
-    ).toThrow(CustomUiSrcDocError);
-  });
-
-  // ── MUTATION TEST (security invariant, isolated) ───────────────────────────
-  // A loosened policy that drops the hash pin must FAIL these assertions. This
-  // proves the guard is load-bearing: remove/loosen the script-src hash and the
-  // suite goes red.
-  it('MUTATION: dropping the script-src hash makes the CSP invalid — caught', () => {
-    const loosened = `default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'`;
-    // The real builder must NOT equal the loosened (hash-dropped) policy…
-    expect(buildCustomUiFrameCsp(INTEGRITY)).not.toBe(loosened);
-    // …and the real policy MUST pin the exact hash the loosened one dropped.
-    expect(buildCustomUiFrameCsp(INTEGRITY)).toContain(
-      `script-src '${INTEGRITY}'`,
-    );
-  });
-});
-
-describe('buildUntrustedHtmlFrameCsp', () => {
-  it('emits the same airtight policy with script-src none', () => {
-    expect(buildUntrustedHtmlFrameCsp()).toBe(
-      `default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'`,
-    );
-  });
-});
-
-describe('buildUntrustedHtmlSrcDoc', () => {
-  const DOCUMENT = '<h1>Report</h1><p>Static, agent-authored markup.</p>';
-  const srcDoc = buildUntrustedHtmlSrcDoc({
-    document: DOCUMENT,
-    styleCss: ':root{--x:1}',
-  });
-
-  it("pins script-src 'none' — an authored <script> can NEVER execute", () => {
-    expect(srcDoc).toContain(
-      `<meta http-equiv="Content-Security-Policy" content="${buildUntrustedHtmlFrameCsp()}" />`,
-    );
-    expect(srcDoc).toContain(`script-src 'none'`);
-    // No script source of any kind may be granted on the static path.
-    expect(srcDoc).not.toContain("script-src 'unsafe-inline'");
-    expect(srcDoc).not.toContain('script-src *');
-    expect(srcDoc).not.toContain('script-src sha384-');
-    expect(srcDoc).toContain(`default-src 'none'`);
-    expect(srcDoc).toContain(`base-uri 'none'`);
-    expect(srcDoc).toContain(`form-action 'none'`);
-  });
-
-  it('emits the document verbatim with the inlined styles', () => {
-    expect(srcDoc).toContain('<style>:root{--x:1}</style>');
-    expect(srcDoc).toContain(DOCUMENT);
-  });
-
-  it('refuses a document containing a literal </script (fail-closed)', () => {
-    expect(() =>
-      buildUntrustedHtmlSrcDoc({
-        document: '<p>ok</p></script><script>alert(1)</script>',
-        styleCss: '',
-      }),
-    ).toThrow(CustomUiSrcDocError);
-  });
-
-  // ── MUTATION TEST (static-document invariant, isolated) ────────────────────
-  it('MUTATION: granting the static document any script source is caught', () => {
-    const loosened = `default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'`;
-    expect(buildUntrustedHtmlFrameCsp()).not.toBe(loosened);
-    expect(buildUntrustedHtmlFrameCsp()).toContain(`script-src 'none'`);
-  });
-});