@xemahq/ui-kernel 0.9.1 → 0.10.0

package/src/vista/surfaces/elicitation-transport.ts

@@ -3,8 +3,8 @@
 //
 // This module is the ONLY code that ever reads a captured field value out of
 // the form surface, and it does exactly one thing with it: put it in the body
-// of a `fetch` to the ABSOLUTE service URL carried by the (already validated)
-// surface payload, bearing the SUBJECT's own JWT.
+// of a `fetch` to an endpoint derived from the HOST-CONFIGURED trusted
+// elicitation-service base URL, bearing the SUBJECT's own JWT.
 //
 // Three properties make "the agent cannot receive the value" structural:
 //
@@ -15,15 +15,17 @@
 //   • the response is PROJECTED, not passed through: `toOutcome` constructs a
 //     fresh object with exactly three keys, so a service that echoed a secret
 //     back could still not leak one through this boundary;
-//   • the URL is absolute and comes from the payload validator, which rejects
-//     anything that is not `http(s)://…` — there is no host-relative path, so
-//     the request cannot be aimed at the app's own BFF or the chat transport.
+//   • the payload carries only an opaque ref. It has NO network authority. This
+//     module validates the host-configured base URL and derives the exact
+//     status/submit paths before a bearer token or field value reaches fetch.
 //
 // Errors carry the SERVICE's message verbatim (that is how the backend's hard
 // 400 on an empty credential form becomes readable UI copy) and never the
 // request body.
 // ═══════════════════════════════════════════════════════════════════════════
-import type { VistaFormOutcome } from '../vista-form-host';
+import { isValidVistaFormRef } from '../vista-payloads';
+
+import type { VistaFormOutcome } from '../vista-form-context';
 
 /** A non-2xx answer from the owning service, carrying its message verbatim. */
 export class VistaFormSubmitError extends Error {
@@ -36,6 +38,19 @@ export class VistaFormSubmitError extends Error {
   }
 }
 
+/** Invalid trusted-host transport configuration or unsafe path input. */
+export class VistaFormTransportConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'VistaFormTransportConfigError';
+  }
+}
+
+export interface TrustedElicitationEndpoints {
+  readonly statusUrl: string;
+  readonly submitUrl: string;
+}
+
 type UnknownRecord = Readonly<Record<string, unknown>>;
 
 function asRecord(value: unknown): UnknownRecord | null {
@@ -69,7 +84,9 @@ export function extractServiceMessage(body: unknown, status: number): string {
       : (record.message ?? asRecord(record.error)?.message ?? record.error);
   if (typeof candidate === 'string' && candidate.length > 0) return candidate;
   if (Array.isArray(candidate)) {
-    const joined = candidate.filter((m): m is string => typeof m === 'string').join(' ');
+    const joined = candidate
+      .filter((m): m is string => typeof m === 'string')
+      .join(' ');
     if (joined.length > 0) return joined;
   }
   if (typeof body === 'string' && body.length > 0) return body;
@@ -108,7 +125,10 @@ function toOutcome(body: unknown, ref: string): VistaFormOutcome | null {
 }
 
 /** The `Authorization`/`Content-Type` pair every request here carries. */
-function authHeaders(accessToken: string, json: boolean): Record<string, string> {
+function authHeaders(
+  accessToken: string,
+  json: boolean,
+): Record<string, string> {
   const headers: Record<string, string> = {
     Authorization: `Bearer ${accessToken}`,
     Accept: 'application/json',
@@ -117,6 +137,146 @@ function authHeaders(accessToken: string, json: boolean): Record<string, string>
   return headers;
 }
 
+function browserOrigin(): string | undefined {
+  return typeof globalThis.location === 'undefined'
+    ? undefined
+    : globalThis.location.origin;
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return (
+    hostname === 'localhost' ||
+    hostname.endsWith('.localhost') ||
+    hostname === '127.0.0.1' ||
+    hostname === '[::1]'
+  );
+}
+
+/**
+ * Parse the host's deploy-time trust anchor. It must be a canonical absolute
+ * HTTP(S) URL without credentials/query/fragment. HTTPS is mandatory except
+ * for loopback or same-host HTTP when the page itself is also served over HTTP.
+ */
+function trustedApiBaseUrl(
+  raw: string,
+  activeBrowserOrigin: string | undefined,
+): URL {
+  if (raw.length === 0 || raw.trim() !== raw) {
+    throw new VistaFormTransportConfigError(
+      'The trusted elicitation API base URL is empty or contains whitespace.',
+    );
+  }
+
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new VistaFormTransportConfigError(
+      'The trusted elicitation API base URL must be absolute.',
+    );
+  }
+
+  if (
+    (url.protocol !== 'https:' && url.protocol !== 'http:') ||
+    url.username.length > 0 ||
+    url.password.length > 0 ||
+    url.search.length > 0 ||
+    url.hash.length > 0
+  ) {
+    throw new VistaFormTransportConfigError(
+      'The trusted elicitation API base URL must use HTTP(S) and contain no credentials, query, or fragment.',
+    );
+  }
+
+  const canonicalPath =
+    url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+  const canonical = `${url.origin}${canonicalPath}`;
+  const suppliedWithoutOneTrailingSlash = raw.endsWith('/')
+    ? raw.slice(0, -1)
+    : raw;
+  if (suppliedWithoutOneTrailingSlash !== canonical) {
+    throw new VistaFormTransportConfigError(
+      'The trusted elicitation API base URL must be canonical and contain no traversal or ambiguous path.',
+    );
+  }
+
+  if (url.protocol === 'http:' && !isLoopbackHostname(url.hostname)) {
+    let page: URL | null = null;
+    if (activeBrowserOrigin !== undefined) {
+      try {
+        page = new URL(activeBrowserOrigin);
+      } catch {
+        page = null;
+      }
+    }
+    if (
+      page === null ||
+      page.protocol !== 'http:' ||
+      page.hostname !== url.hostname
+    ) {
+      throw new VistaFormTransportConfigError(
+        'Insecure elicitation HTTP is allowed only on loopback or the same host as an HTTP development page.',
+      );
+    }
+  }
+
+  return new URL(canonical);
+}
+
+/**
+ * Derive the only two authenticated endpoints from trusted host configuration
+ * plus one opaque path segment. Calling this directly remains safe even if a
+ * caller bypasses the surface-payload validator.
+ */
+export function resolveTrustedElicitationEndpoints(
+  apiBaseUrl: string,
+  ref: string,
+  activeBrowserOrigin: string | undefined = browserOrigin(),
+): TrustedElicitationEndpoints {
+  if (!isValidVistaFormRef(ref)) {
+    throw new VistaFormTransportConfigError(
+      'The elicitation reference is not a valid opaque base64url path segment.',
+    );
+  }
+  const base = trustedApiBaseUrl(apiBaseUrl, activeBrowserOrigin)
+    .toString()
+    .replace(/\/$/, '');
+  const statusUrl = `${base}/${ref}`;
+  return { statusUrl, submitUrl: `${statusUrl}/submit` };
+}
+
+/**
+ * Resolve an unauthenticated launch path under the SAME trusted service origin.
+ * Absolute/network-path URLs and dot-segment traversal fail closed.
+ */
+export function resolveTrustedElicitationLaunchUrl(
+  apiBaseUrl: string,
+  path: string,
+  activeBrowserOrigin: string | undefined = browserOrigin(),
+): string {
+  const base = trustedApiBaseUrl(apiBaseUrl, activeBrowserOrigin);
+  if (
+    !path.startsWith('/') ||
+    path.startsWith('//') ||
+    path.includes('\\') ||
+    path.includes('#')
+  ) {
+    throw new VistaFormTransportConfigError(
+      'The elicitation launch target must be a root-relative service path.',
+    );
+  }
+  const resolved = new URL(path, `${base.origin}/`);
+  if (
+    resolved.origin !== base.origin ||
+    `${resolved.pathname}${resolved.search}` !== path
+  ) {
+    throw new VistaFormTransportConfigError(
+      'The elicitation launch path contains traversal or an ambiguous encoding.',
+    );
+  }
+  return resolved.toString();
+}
+
 /**
  * POST the captured fields to the owning service.
  *
@@ -125,20 +285,30 @@ function authHeaders(accessToken: string, json: boolean): Record<string, string>
  * user reads.
  */
 export async function submitElicitationFields(args: {
-  readonly submitUrl: string;
+  readonly apiBaseUrl: string;
   readonly ref: string;
   readonly accessToken: string;
   readonly fields: Readonly<Record<string, string>>;
 }): Promise<VistaFormOutcome> {
-  const response = await fetch(args.submitUrl, {
+  const { submitUrl } = resolveTrustedElicitationEndpoints(
+    args.apiBaseUrl,
+    args.ref,
+  );
+  const response = await fetch(submitUrl, {
     method: 'POST',
     headers: authHeaders(args.accessToken, true),
     body: JSON.stringify({ fields: args.fields }),
     credentials: 'omit',
+    // A 307/308 could otherwise replay the credential body to a different
+    // origin. Authenticated elicitation endpoints must never redirect.
+    redirect: 'error',
   });
   const body = await readBody(response);
   if (!response.ok) {
-    throw new VistaFormSubmitError(response.status, extractServiceMessage(body, response.status));
+    throw new VistaFormSubmitError(
+      response.status,
+      extractServiceMessage(body, response.status),
+    );
   }
   const outcome = toOutcome(body, args.ref);
   if (outcome === null) {
@@ -158,18 +328,26 @@ export async function submitElicitationFields(args: {
  * Returns `null` while still pending — an explicit "not yet", never a guess.
  */
 export async function readElicitationStatus(args: {
-  readonly statusUrl: string;
+  readonly apiBaseUrl: string;
   readonly ref: string;
   readonly accessToken: string;
 }): Promise<VistaFormOutcome | null> {
-  const response = await fetch(args.statusUrl, {
+  const { statusUrl } = resolveTrustedElicitationEndpoints(
+    args.apiBaseUrl,
+    args.ref,
+  );
+  const response = await fetch(statusUrl, {
     method: 'GET',
     headers: authHeaders(args.accessToken, false),
     credentials: 'omit',
+    redirect: 'error',
   });
   const body = await readBody(response);
   if (!response.ok) {
-    throw new VistaFormSubmitError(response.status, extractServiceMessage(body, response.status));
+    throw new VistaFormSubmitError(
+      response.status,
+      extractServiceMessage(body, response.status),
+    );
   }
   return toOutcome(body, args.ref);
 }

package/src/vista/surfaces/file-surface-utils.ts

@@ -0,0 +1,62 @@
+import type { VistaFileEntry } from '../vista-payloads';
+
+interface FileExtMeta {
+  readonly color: string;
+  readonly tag: string;
+}
+
+const EXT_META: Readonly<Record<string, FileExtMeta>> = {
+  ts: { color: 'hsl(var(--info))', tag: 'TS' },
+  tsx: { color: 'hsl(var(--info))', tag: 'TSX' },
+  js: { color: 'hsl(var(--warning))', tag: 'JS' },
+  jsx: { color: 'hsl(var(--warning))', tag: 'JSX' },
+  json: { color: 'hsl(var(--ink-3))', tag: 'JSON' },
+  md: { color: 'hsl(var(--p-people))', tag: 'MD' },
+  css: { color: 'hsl(var(--p-sales))', tag: 'CSS' },
+  html: { color: 'hsl(var(--p-sales))', tag: 'HTML' },
+  yaml: { color: 'hsl(var(--ink-3))', tag: 'YAML' },
+  yml: { color: 'hsl(var(--ink-3))', tag: 'YAML' },
+};
+
+export function fileExtMeta(name: string): FileExtMeta {
+  if (/\.test\.[tj]sx?$/.test(name) || /\.spec\.[tj]sx?$/.test(name)) {
+    return { color: 'hsl(var(--success))', tag: 'TEST' };
+  }
+  const ext = name.split('.').pop() ?? '';
+  return (
+    EXT_META[ext] ?? {
+      color: 'hsl(var(--ink-4))',
+      tag: (ext || 'FILE').toUpperCase().slice(0, 4),
+    }
+  );
+}
+
+export interface VistaFileGroup {
+  readonly dir: string;
+  readonly files: readonly VistaFileEntry[];
+}
+
+function compareDirs(a: string, b: string): number {
+  if (a === '') return -1;
+  if (b === '') return 1;
+  return a.localeCompare(b);
+}
+
+export function groupFilesByFolder(
+  files: readonly VistaFileEntry[],
+): VistaFileGroup[] {
+  const groups = new Map<string, VistaFileEntry[]>();
+  for (const file of files) {
+    const slash = file.path.lastIndexOf('/');
+    const dir = slash < 0 ? '' : file.path.slice(0, slash);
+    const bucket = groups.get(dir);
+    if (bucket) bucket.push(file);
+    else groups.set(dir, [file]);
+  }
+  return [...groups.keys()].sort(compareDirs).map((dir) => ({
+    dir,
+    files: [...(groups.get(dir) ?? [])].sort((a, b) =>
+      a.path.localeCompare(b.path),
+    ),
+  }));
+}

package/src/vista/surfaces/index.ts

@@ -0,0 +1,24 @@
+import './register-surfaces';
+
+export { ChartSurface } from './ChartSurface';
+export { FilesSurface } from './FilesSurface';
+export {
+  fileExtMeta,
+  groupFilesByFolder,
+  type VistaFileGroup,
+} from './file-surface-utils';
+export { FormSurface } from './FormSurface';
+export {
+  extractServiceMessage,
+  readElicitationStatus,
+  resolveTrustedElicitationEndpoints,
+  resolveTrustedElicitationLaunchUrl,
+  submitElicitationFields,
+  VistaFormSubmitError,
+  VistaFormTransportConfigError,
+} from './elicitation-transport';
+export { HtmlSurface } from './HtmlSurface';
+export { TableSurface } from './TableSurface';
+export { UrlSurface } from './UrlSurface';
+export { CodeSurface, DiffSurface, JsonSurface } from './text-surfaces';
+export { ImageSurface, MediaSurface, PdfSurface } from './blob-surfaces';

package/src/vista/surfaces/{index.tsx → register-surfaces.tsx}

@@ -29,11 +29,7 @@
  */
 import { SurfaceKind } from '@xemahq/kernel-contracts/surface';
 
-import {
-  ImageSurface,
-  MediaSurface,
-  PdfSurface,
-} from './blob-surfaces';
+import { ImageSurface, MediaSurface, PdfSurface } from './blob-surfaces';
 import { ChartSurface } from './ChartSurface';
 import { FilesSurface } from './FilesSurface';
 import { FormSurface } from './FormSurface';
@@ -139,19 +135,3 @@ vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Form, {
   validate: validateFormPayload,
   render: (payload) => <FormSurface {...payload} />,
 });
-
-export { ChartSurface } from './ChartSurface';
-export { FilesSurface, fileExtMeta, groupFilesByFolder } from './FilesSurface';
-export { FormSurface } from './FormSurface';
-export {
-  submitElicitationFields,
-  readElicitationStatus,
-  extractServiceMessage,
-  VistaFormSubmitError,
-} from './elicitation-transport';
-export { HtmlSurface } from './HtmlSurface';
-export { TableSurface } from './TableSurface';
-export { UrlSurface } from './UrlSurface';
-export { CodeSurface, DiffSurface, JsonSurface } from './text-surfaces';
-export { ImageSurface, MediaSurface, PdfSurface } from './blob-surfaces';
-export type { VistaFileGroup } from './FilesSurface';

package/src/vista/surfaces/text-surfaces.tsx

@@ -9,7 +9,7 @@
  * `plain` tab kind was collapsed into it; one kind, one renderer, no alias).
  */
 
-import { useVistaCodeRenderer } from '../vista-code-renderer';
+import { useVistaCodeRenderer } from '../vista-code-renderer-context';
 import { VistaFileText } from '../vista-file-source';
 
 import type { VistaTextPayload } from '../vista-payloads';

package/src/vista/vista-code-renderer-context.ts

@@ -0,0 +1,16 @@
+import { createContext, useContext } from 'react';
+
+import type { ReactNode } from 'react';
+
+export type VistaCodeRenderer = (args: {
+  readonly content: string;
+  readonly path?: string;
+  readonly language?: string;
+}) => ReactNode;
+
+export const VistaCodeRendererContext =
+  createContext<VistaCodeRenderer | null>(null);
+
+export function useVistaCodeRenderer(): VistaCodeRenderer | null {
+  return useContext(VistaCodeRendererContext);
+}

package/src/vista/vista-code-renderer.tsx

@@ -14,20 +14,13 @@
  * the intended rendering. Neither is an error path.
  */
 import {
-  createContext,
-  useContext,
   type ReactElement,
   type ReactNode,
 } from 'react';
-
-/** Draw a code body. `path` is present for a file-backed surface. */
-export type VistaCodeRenderer = (args: {
-  readonly content: string;
-  readonly path?: string;
-  readonly language?: string;
-}) => ReactNode;
-
-const VistaCodeRendererContext = createContext<VistaCodeRenderer | null>(null);
+import {
+  VistaCodeRendererContext,
+  type VistaCodeRenderer,
+} from './vista-code-renderer-context';
 
 export function VistaCodeRendererProvider({
   renderer,
@@ -39,8 +32,3 @@ export function VistaCodeRendererProvider({
     </VistaCodeRendererContext.Provider>
   );
 }
-
-/** The host's code renderer, or `null` for the built-in mono pane. */
-export function useVistaCodeRenderer(): VistaCodeRenderer | null {
-  return useContext(VistaCodeRendererContext);
-}

package/src/vista/vista-file-context.ts

@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react';
+
+export interface VistaFileSource {
+  readText(path: string): Promise<string>;
+  resolveUrl(path: string): Promise<string>;
+  readonly revision?: string | number;
+}
+
+export const VistaFileSourceContext =
+  createContext<VistaFileSource | null>(null);
+
+export function useVistaFileSource(): VistaFileSource | null {
+  return useContext(VistaFileSourceContext);
+}

package/src/vista/vista-file-source.tsx

@@ -13,34 +13,16 @@
  * "content unavailable".
  */
 import {
-  createContext,
-  useContext,
   useEffect,
   useState,
   type ReactElement,
   type ReactNode,
 } from 'react';
-
-/** Host-supplied byte access for path-backed surfaces. */
-export interface VistaFileSource {
-  /** Read a workspace-relative path as text. Rejects on failure. */
-  readText(path: string): Promise<string>;
-  /**
-   * Resolve a workspace-relative path to a fetchable URL (`blob:`, `data:`, or
-   * a durable `https:` URL) for binary surfaces. Rejects on failure.
-   *
-   * The host owns the lifetime of anything it creates (e.g. revoking an object
-   * URL); the surface only reads.
-   */
-  resolveUrl(path: string): Promise<string>;
-  /**
-   * Opaque revision token. Change it to make every mounted path-backed surface
-   * re-read (the host bumps it on a workspace file-change event).
-   */
-  readonly revision?: string | number;
-}
-
-const VistaFileSourceContext = createContext<VistaFileSource | null>(null);
+import {
+  VistaFileSourceContext,
+  useVistaFileSource,
+  type VistaFileSource,
+} from './vista-file-context';
 
 export function VistaFileSourceProvider({
   source,
@@ -53,11 +35,6 @@ export function VistaFileSourceProvider({
   );
 }
 
-/** The active file source, or `null` when no provider is mounted. */
-export function useVistaFileSource(): VistaFileSource | null {
-  return useContext(VistaFileSourceContext);
-}
-
 /** Async load state for a path-backed surface. */
 type LoadState =
   | { readonly status: 'loading' }

package/src/vista/vista-form-context.ts

@@ -0,0 +1,20 @@
+import { createContext, useContext } from 'react';
+
+export interface VistaFormOutcome {
+  readonly submitted: true;
+  readonly ref: string;
+  readonly connectionId: string | null;
+}
+
+export interface VistaFormHost {
+  readonly elicitationApiBaseUrl: string;
+  getAccessToken(): Promise<string>;
+  onOutcome(outcome: VistaFormOutcome): void;
+}
+
+export const VistaFormHostContext =
+  createContext<VistaFormHost | null>(null);
+
+export function useVistaFormHost(): VistaFormHost | null {
+  return useContext(VistaFormHostContext);
+}

package/src/vista/vista-form-host.tsx

@@ -18,16 +18,22 @@
  *   2. `getAccessToken` returns the SUBJECT's token. The host binds it to the
  *      logged-in user's session; it is never a service token and never the
  *      agent's token, so the service authorizes the human, not the model.
- *   3. The surface's transport posts to an ABSOLUTE service URL taken from the
- *      validated payload (see `validateFormPayload`, which rejects a relative
- *      URL). There is no host-relative path, so it cannot be pointed at the
- *      app's own BFF/chat transport.
+ *   3. `elicitationApiBaseUrl` is supplied by trusted host configuration, never
+ *      by the agent-controlled payload. The kernel validates its scheme and
+ *      canonical authority/path before deriving the status/submit endpoints.
  *
  * There is deliberately NO default host: a `form` surface mounted without a
  * provider renders a visible refusal and cannot submit. Fail-closed — a form
  * that silently posts nowhere would be worse than one that says it cannot.
  */
-import { createContext, useContext, type ReactElement, type ReactNode } from 'react';
+import {
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  VistaFormHostContext,
+  type VistaFormHost,
+} from './vista-form-context';
 
 /**
  * Everything a settled elicitation reports. Closed, scalar-only, and
@@ -35,32 +41,6 @@ import { createContext, useContext, type ReactElement, type ReactNode } from 're
  * persistence layer behind it has no column able to hold a field value, and
  * neither does this type.
  */
-export interface VistaFormOutcome {
-  /** Always `true`: an unsettled elicitation produces no outcome at all. */
-  readonly submitted: true;
-  /** The elicitation reference the agent polls. Opaque, non-secret. */
-  readonly ref: string;
-  /** The connection the submission provisioned, when the service reported one. */
-  readonly connectionId: string | null;
-}
-
-/** Host-supplied capabilities for the `form` surface. */
-export interface VistaFormHost {
-  /**
-   * The SUBJECT's own access token. Called once per request so a refreshed
-   * token is picked up without remounting the surface.
-   */
-  getAccessToken(): Promise<string>;
-  /**
-   * Called exactly once when the elicitation settles. The host relays this to
-   * whatever needs to know (cache invalidation, the agent session). By type it
-   * can carry nothing but the outcome.
-   */
-  onOutcome(outcome: VistaFormOutcome): void;
-}
-
-const VistaFormHostContext = createContext<VistaFormHost | null>(null);
-
 export function VistaFormHostProvider({
   host,
   children,
@@ -71,8 +51,3 @@ export function VistaFormHostProvider({
     </VistaFormHostContext.Provider>
   );
 }
-
-/** The active form host, or `null` when no provider is mounted. */
-export function useVistaFormHost(): VistaFormHost | null {
-  return useContext(VistaFormHostContext);
-}

package/src/vista/vista-open-context.tsx

@@ -12,18 +12,13 @@
  * silently does nothing.
  */
 import {
-  createContext,
-  useContext,
   type ReactElement,
   type ReactNode,
 } from 'react';
-
-import type { VistaTab } from './vista-model';
-
-/** Open (or replace) a tab and focus it. Mirrors `VistaTabsController.open`. */
-export type VistaOpenFn = (surface: VistaTab) => string;
-
-const VistaOpenContext = createContext<VistaOpenFn | null>(null);
+import {
+  VistaOpenContext,
+  type VistaOpenFn,
+} from './vista-open-state';
 
 export function VistaOpenProvider({
   open,
@@ -35,8 +30,3 @@ export function VistaOpenProvider({
     </VistaOpenContext.Provider>
   );
 }
-
-/** The panel's `open`, or `null` when no panel is mounted above. */
-export function useVistaOpen(): VistaOpenFn | null {
-  return useContext(VistaOpenContext);
-}

package/src/vista/vista-open-state.ts

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+
+import type { VistaTab } from './vista-model';
+
+export type VistaOpenFn = (surface: VistaTab) => string;
+
+export const VistaOpenContext = createContext<VistaOpenFn | null>(null);
+
+export function useVistaOpen(): VistaOpenFn | null {
+  return useContext(VistaOpenContext);
+}