@xemahq/ui-kernel 0.9.0 → 0.9.2

package/src/vista/surfaces/UrlSurface.tsx

@@ -0,0 +1,40 @@
+/**
+ * `SurfaceKind.Url` — a live external URL inside mock browser chrome.
+ *
+ * The chrome (traffic lights + address bar + reload) is `UrlPreviewChrome`,
+ * lifted out of the thin session workspace; the device bezel is the shared
+ * `PreviewDeviceFrame`. The frame itself is `sandbox="allow-scripts
+ * allow-forms"` and NEVER `allow-same-origin`: a previewed app runs in its own
+ * opaque origin and cannot reach the host's DOM, cookies or tokens.
+ */
+
+import { PreviewDeviceFrame } from '../../ui/primitives/preview-device-frame';
+import { UrlPreviewChrome } from '../../ui/primitives/url-preview-chrome';
+
+import type { VistaUrlPayload } from '../vista-payloads';
+import type { ReactElement } from 'react';
+
+export function UrlSurface({
+  url,
+  device = 'desktop',
+  reloadNonce,
+}: Readonly<VistaUrlPayload>): ReactElement {
+  return (
+    <UrlPreviewChrome url={url}>
+      <PreviewDeviceFrame device={device}>
+        <iframe
+          // Remounting on a nonce change is how a reload is requested without
+          // reaching into the frame (which we cannot do: it is cross-origin).
+          key={`${url}::${device}::${reloadNonce ?? 0}`}
+          title={`Preview of ${url}`}
+          src={url}
+          // NEVER add allow-same-origin — it would dissolve the origin boundary
+          // between the previewed app and the host.
+          sandbox="allow-scripts allow-forms"
+          loading="lazy"
+          style={{ height: '100%', width: '100%', border: 0 }}
+        />
+      </PreviewDeviceFrame>
+    </UrlPreviewChrome>
+  );
+}

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

@@ -0,0 +1,129 @@
+/**
+ * The binary-bodied first-party surfaces: `image`, `media`, `pdf`.
+ *
+ * Each accepts an already-resolved `url` OR a workspace `path` resolved through
+ * the host {@link VistaFileSource}.
+ *
+ * SECURITY — `pdf`: the bytes are frequently UNTRUSTED (user uploads,
+ * agent-produced artifacts). The PDF is painted onto a `<canvas>` by pdf.js
+ * (the shared `PdfPreview`) — NO iframe, NO script execution — never embedded
+ * in the browser's own viewer. `PdfPreview` is lazy-imported so pdf.js
+ * (~1.9 MB) stays out of any bundle that never opens a PDF; that dynamic import
+ * is the whole point of the `@xemahq/ui-kernel/pdf` subpath.
+ */
+import { Suspense, lazy, type ReactElement, type ReactNode } from 'react';
+
+import { VistaFileUrl } from '../vista-file-source';
+
+import type { VistaBlobPayload } from '../vista-payloads';
+
+const PdfPreview = lazy(() =>
+  import('../../pdf').then((m) => ({ default: m.PdfPreview })),
+);
+
+/** Render from an inline url, or resolve the path first. */
+function BlobBody({
+  payload,
+  render,
+}: Readonly<{
+  payload: VistaBlobPayload;
+  render: (url: string) => ReactNode;
+}>): ReactElement {
+  if (payload.url !== undefined) return <>{render(payload.url)}</>;
+  // `validateBlobPayload` guarantees exactly one of url/path.
+  return <VistaFileUrl path={payload.path as string} render={render} />;
+}
+
+export function ImageSurface(payload: VistaBlobPayload): ReactElement {
+  return (
+    <BlobBody
+      payload={payload}
+      render={(url) => (
+        <div
+          style={{
+            height: '100%',
+            display: 'grid',
+            placeItems: 'center',
+            padding: 16,
+            overflow: 'auto',
+          }}
+        >
+          <img
+            src={url}
+            alt={payload.alt ?? 'Preview'}
+            style={{ maxWidth: '100%', maxHeight: '100%', objectFit: 'contain' }}
+          />
+        </div>
+      )}
+    />
+  );
+}
+
+export function PdfSurface(payload: VistaBlobPayload): ReactElement {
+  return (
+    <BlobBody
+      payload={payload}
+      render={(url) => (
+        <Suspense
+          fallback={
+            <div
+              style={{
+                height: '100%',
+                display: 'grid',
+                placeItems: 'center',
+                fontSize: 12.5,
+                color: 'hsl(var(--ink-4))',
+              }}
+            >
+              Loading viewer…
+            </div>
+          }
+        >
+          <PdfPreview
+            url={url}
+            title={payload.alt ?? 'PDF preview'}
+            className="h-full w-full"
+          />
+        </Suspense>
+      )}
+    />
+  );
+}
+
+/**
+ * `media` — audio or video, chosen by `contentType`. The type is REQUIRED by the
+ * payload validator for this kind (see the registration): guessing between an
+ * `<audio>` and a `<video>` element from a URL would be a heuristic that fails
+ * on extension-less URLs.
+ */
+export function MediaSurface(payload: VistaBlobPayload): ReactElement {
+  const isAudio = (payload.contentType ?? '').startsWith('audio/');
+  return (
+    <BlobBody
+      payload={payload}
+      render={(url) => (
+        <div
+          style={{
+            height: '100%',
+            display: 'grid',
+            placeItems: 'center',
+            padding: 16,
+            background: 'hsl(var(--paper-sunk))',
+          }}
+        >
+          {isAudio ? (
+            // eslint-disable-next-line jsx-a11y/media-has-caption
+            <audio src={url} controls style={{ width: '100%', maxWidth: 520 }} />
+          ) : (
+            // eslint-disable-next-line jsx-a11y/media-has-caption
+            <video
+              src={url}
+              controls
+              style={{ maxWidth: '100%', maxHeight: '100%' }}
+            />
+          )}
+        </div>
+      )}
+    />
+  );
+}

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

@@ -0,0 +1,369 @@
+/**
+ * Guards the secure-elicitation transport — the ONE place a captured field
+ * value is read out of the `form` surface.
+ *
+ * These are the load-bearing proofs of Canopy §8.4: the value goes browser →
+ * service and the only thing that comes back out is `{ submitted, ref,
+ * connectionId }`. Runs under the host-web vitest mirror (this package carries
+ * no vitest dep).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  extractServiceMessage,
+  readElicitationStatus,
+  resolveTrustedElicitationEndpoints,
+  resolveTrustedElicitationLaunchUrl,
+  submitElicitationFields,
+  VistaFormSubmitError,
+  VistaFormTransportConfigError,
+} from './elicitation-transport';
+
+const SERVICE_ORIGIN = 'https://connector-gateway.example.test';
+const API_BASE_URL = `${SERVICE_ORIGIN}/credential-elicitations`;
+const SUBMIT_URL = `${SERVICE_ORIGIN}/credential-elicitations/ref-1/submit`;
+const STATUS_URL = `${SERVICE_ORIGIN}/credential-elicitations/ref-1`;
+const SECRET = 'sk-live-DO-NOT-LEAK';
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function stubFetch(response: Response): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn().mockResolvedValue(response);
+  vi.stubGlobal('fetch', fetchMock);
+  return fetchMock;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('trusted elicitation endpoint resolution', () => {
+  it('derives exact status and submit paths from the host trust anchor', () => {
+    expect(resolveTrustedElicitationEndpoints(API_BASE_URL, 'ref-1')).toEqual({
+      statusUrl: STATUS_URL,
+      submitUrl: SUBMIT_URL,
+    });
+  });
+
+  it.each([
+    ['relative', '/credential-elicitations'],
+    ['network-path', '//evil.example/credential-elicitations'],
+    ['scheme confusion', 'javascript:https://trusted.example'],
+    [
+      'authority confusion',
+      'https://trusted.example@evil.example/credential-elicitations',
+    ],
+    [
+      'query',
+      'https://trusted.example/credential-elicitations?next=https://evil.example',
+    ],
+    [
+      'fragment',
+      'https://trusted.example/credential-elicitations#https://evil.example',
+    ],
+    [
+      'path traversal',
+      'https://trusted.example/credential-elicitations/../evil',
+    ],
+    [
+      'encoded path traversal',
+      'https://trusted.example/credential-elicitations/%2e%2e/evil',
+    ],
+  ])('rejects %s base URL input', (_label, apiBaseUrl) => {
+    expect(() =>
+      resolveTrustedElicitationEndpoints(apiBaseUrl, 'ref-1'),
+    ).toThrow(VistaFormTransportConfigError);
+  });
+
+  it('requires HTTPS for a non-local service', () => {
+    expect(() =>
+      resolveTrustedElicitationEndpoints(
+        'http://api.example.test/credential-elicitations',
+        'ref-1',
+        'http://host.example.test:8080',
+      ),
+    ).toThrow(/Insecure elicitation HTTP/);
+  });
+
+  it('permits explicit loopback and same-host HTTP development', () => {
+    expect(
+      resolveTrustedElicitationEndpoints(
+        'http://localhost:3010/credential-elicitations',
+        'ref-1',
+        'http://localhost:8080',
+      ).statusUrl,
+    ).toBe('http://localhost:3010/credential-elicitations/ref-1');
+    expect(
+      resolveTrustedElicitationEndpoints(
+        'http://192.168.1.20:3010/credential-elicitations',
+        'ref-1',
+        'http://192.168.1.20:8080',
+      ).statusUrl,
+    ).toBe('http://192.168.1.20:3010/credential-elicitations/ref-1');
+  });
+
+  it.each(['.', '..', '../steal', 'a/b', '%2e%2e', 'réf'])(
+    'rejects unsafe ref %s before URL construction',
+    (ref) => {
+      expect(() =>
+        resolveTrustedElicitationEndpoints(API_BASE_URL, ref),
+      ).toThrow(VistaFormTransportConfigError);
+    },
+  );
+
+  it('keeps launch paths on the trusted origin and rejects authority/traversal', () => {
+    expect(
+      resolveTrustedElicitationLaunchUrl(
+        API_BASE_URL,
+        '/oauth/acme/authorize?flow=1',
+      ),
+    ).toBe(`${SERVICE_ORIGIN}/oauth/acme/authorize?flow=1`);
+
+    for (const path of [
+      'https://evil.example/steal',
+      '//evil.example/steal',
+      '/oauth/../steal',
+      '/oauth/%2e%2e/steal',
+      '/oauth\\..\\steal',
+      '/oauth/start#https://evil.example',
+    ]) {
+      expect(() =>
+        resolveTrustedElicitationLaunchUrl(API_BASE_URL, path),
+      ).toThrow(VistaFormTransportConfigError);
+    }
+  });
+
+  it('does not call fetch when the trusted base or ref is invalid', async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    await expect(
+      submitElicitationFields({
+        apiBaseUrl:
+          'https://trusted.example@evil.example/credential-elicitations',
+        ref: '../steal',
+        accessToken: 'user-jwt',
+        fields: { apiKey: SECRET },
+      }),
+    ).rejects.toBeInstanceOf(VistaFormTransportConfigError);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('submitElicitationFields', () => {
+  it('POSTs to the SERVICE origin directly — not a host-relative path', async () => {
+    const fetchMock = stubFetch(
+      jsonResponse(201, {
+        data: { submitted: true, ref: 'ref-1', connectionId: 'conn-9' },
+      }),
+    );
+
+    await submitElicitationFields({
+      apiBaseUrl: API_BASE_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+      fields: { apiKey: SECRET },
+    });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(SUBMIT_URL);
+    expect(new URL(url).origin).toBe(SERVICE_ORIGIN);
+    expect(init.method).toBe('POST');
+    expect(init.redirect).toBe('error');
+    // The SUBJECT's own bearer — not a service token, not the agent's.
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      'Bearer user-jwt',
+    );
+  });
+
+  it('never hands a secret back to the caller, even when the service echoes it', async () => {
+    stubFetch(
+      jsonResponse(201, {
+        data: {
+          submitted: true,
+          ref: 'ref-1',
+          connectionId: 'conn-9',
+          // A hostile / careless service echoing the submission back.
+          fields: { apiKey: SECRET },
+          credentials: { apiKey: SECRET },
+        },
+      }),
+    );
+
+    const outcome = await submitElicitationFields({
+      apiBaseUrl: API_BASE_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+      fields: { apiKey: SECRET },
+    });
+
+    // The outcome is a FRESH object with exactly three keys.
+    expect(Object.keys(outcome).sort()).toEqual([
+      'connectionId',
+      'ref',
+      'submitted',
+    ]);
+    expect(outcome).toEqual({
+      submitted: true,
+      ref: 'ref-1',
+      connectionId: 'conn-9',
+    });
+    expect(JSON.stringify(outcome)).not.toContain(SECRET);
+    expect(JSON.stringify(outcome)).not.toContain('apiKey');
+  });
+
+  it('round-trips a NON-secret field to the service body', async () => {
+    const fetchMock = stubFetch(
+      jsonResponse(201, {
+        data: { submitted: true, ref: 'ref-1', connectionId: 'conn-9' },
+      }),
+    );
+
+    await submitElicitationFields({
+      apiBaseUrl: API_BASE_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+      fields: { baseUrl: 'https://acme.example.com', apiKey: SECRET },
+    });
+
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).toEqual({
+      fields: { baseUrl: 'https://acme.example.com', apiKey: SECRET },
+    });
+  });
+
+  it('accepts a flat (un-enveloped) response body', async () => {
+    stubFetch(
+      jsonResponse(200, {
+        submitted: true,
+        ref: 'ref-1',
+        connectionId: 'conn-2',
+      }),
+    );
+    await expect(
+      submitElicitationFields({
+        apiBaseUrl: API_BASE_URL,
+        ref: 'ref-1',
+        accessToken: 't',
+        fields: {},
+      }),
+    ).resolves.toEqual({
+      submitted: true,
+      ref: 'ref-1',
+      connectionId: 'conn-2',
+    });
+  });
+
+  it("surfaces the backend's empty-schema 400 as a usable message", async () => {
+    stubFetch(
+      jsonResponse(400, {
+        statusCode: 400,
+        message:
+          'No credential form is declared for a connection to "ACME" — there is nothing to validate ' +
+          'the submitted values against, so they cannot be stored.',
+      }),
+    );
+
+    // An empty field schema submits an empty map; the SERVICE is the authority.
+    const promise = submitElicitationFields({
+      apiBaseUrl: API_BASE_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+      fields: {},
+    });
+
+    await expect(promise).rejects.toBeInstanceOf(VistaFormSubmitError);
+    await expect(promise).rejects.toThrow(/No credential form is declared/);
+  });
+
+  it('refuses a 2xx that does not report the elicitation as submitted', async () => {
+    stubFetch(jsonResponse(200, { data: { ref: 'ref-1' } }));
+    await expect(
+      submitElicitationFields({
+        apiBaseUrl: API_BASE_URL,
+        ref: 'ref-1',
+        accessToken: 't',
+        fields: {},
+      }),
+    ).rejects.toThrow(/did not report the elicitation as submitted/);
+  });
+});
+
+describe('readElicitationStatus', () => {
+  it('returns null while pending — an explicit "not yet", never a guess', async () => {
+    stubFetch(
+      jsonResponse(200, {
+        data: { ref: 'ref-1', status: 'pending', connectionId: null },
+      }),
+    );
+    await expect(
+      readElicitationStatus({
+        apiBaseUrl: API_BASE_URL,
+        ref: 'ref-1',
+        accessToken: 't',
+      }),
+    ).resolves.toBeNull();
+  });
+
+  it('settles on the service-reported submitted status', async () => {
+    stubFetch(
+      jsonResponse(200, {
+        data: { ref: 'ref-1', status: 'submitted', connectionId: 'conn-3' },
+      }),
+    );
+    await expect(
+      readElicitationStatus({
+        apiBaseUrl: API_BASE_URL,
+        ref: 'ref-1',
+        accessToken: 't',
+      }),
+    ).resolves.toEqual({
+      submitted: true,
+      ref: 'ref-1',
+      connectionId: 'conn-3',
+    });
+  });
+
+  it('GETs the service origin with the subject bearer', async () => {
+    const fetchMock = stubFetch(
+      jsonResponse(200, { data: { ref: 'ref-1', status: 'pending' } }),
+    );
+    await readElicitationStatus({
+      apiBaseUrl: API_BASE_URL,
+      ref: 'ref-1',
+      accessToken: 'user-jwt',
+    });
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(new URL(url).origin).toBe(SERVICE_ORIGIN);
+    expect(init.method).toBe('GET');
+    expect(init.redirect).toBe('error');
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      'Bearer user-jwt',
+    );
+  });
+});
+
+describe('extractServiceMessage', () => {
+  it('reads a string message, a message array, and a nested error message', () => {
+    expect(extractServiceMessage({ message: 'nope' }, 400)).toBe('nope');
+    expect(extractServiceMessage({ message: ['a', 'b'] }, 400)).toBe('a b');
+    expect(extractServiceMessage({ error: { message: 'deep' } }, 400)).toBe(
+      'deep',
+    );
+  });
+
+  it('never yields an empty string', () => {
+    expect(extractServiceMessage(null, 503)).toBe(
+      'The service rejected the submission (HTTP 503).',
+    );
+    expect(extractServiceMessage({ message: '' }, 500)).toBe(
+      'The service rejected the submission (HTTP 500).',
+    );
+  });
+});