@xemahq/ui-kernel 0.9.1 → 0.10.0

package/src/vista/surfaces/FormSurface.tsx

@@ -13,25 +13,45 @@
  *   • the values live in this component's `useState`; the single reader is
  *     `submitElicitationFields`, which takes them as a parameter and returns an
  *     outcome — the values are not reachable from any return or any throw;
- *   • the POST target is an ABSOLUTE service URL (`validateFormPayload` rejects
- *     a relative one), so the request cannot be aimed at the host's own BFF or
- *     the chat transport;
+ *   • the payload has NO URL authority. The exact endpoints are derived from
+ *     the trusted elicitation API base URL supplied by `VistaFormHost`;
  *   • secret fields are DECLARED (`spec.isSecret`) and render write-only; the
  *     surface holds no cache and no read path repopulates them.
  *
  * Nothing here is provider-aware. Whether the flow is a field form or an OAuth
  * handoff is decided by the payload the owning service produced.
  */
-import { AlertTriangle, CheckCircle2, ExternalLink, Loader2, ShieldCheck } from 'lucide-react';
-import { useCallback, useEffect, useState, type ReactElement, type ReactNode } from 'react';
+import {
+  AlertTriangle,
+  CheckCircle2,
+  ExternalLink,
+  Loader2,
+  ShieldCheck,
+} from 'lucide-react';
+import {
+  useCallback,
+  useEffect,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
 
-import { readElicitationStatus, submitElicitationFields, VistaFormSubmitError } from './elicitation-transport';
+import {
+  readElicitationStatus,
+  resolveTrustedElicitationEndpoints,
+  resolveTrustedElicitationLaunchUrl,
+  submitElicitationFields,
+  VistaFormSubmitError,
+} from './elicitation-transport';
 import { SchemaForm } from '../../ui/capture/schema-form';
 import { captureValuesToStringMap } from '../../ui/capture/submit-values';
 import { useSchemaValidation } from '../../ui/capture/use-schema-validation';
 import { cn } from '../../ui/cn';
 import { Button } from '../../ui/primitives/button';
-import { useVistaFormHost, type VistaFormOutcome } from '../vista-form-host';
+import {
+  useVistaFormHost,
+  type VistaFormOutcome,
+} from '../vista-form-context';
 
 import type { CaptureValues } from '../../ui/capture/field-spec';
 import type { VistaFormPayload } from '../vista-payloads';
@@ -51,6 +71,29 @@ export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
   const [showFieldErrors, setShowFieldErrors] = useState(false);
   const [outcome, setOutcome] = useState<VistaFormOutcome | null>(null);
   const { errors, isValid } = useSchemaValidation(payload.fields, values);
+  let transportConfigurationError: string | null = null;
+  let launchUrl: string | undefined;
+  if (host !== null) {
+    try {
+      // Validate the trust anchor before retrieving a bearer token or accepting
+      // a submit action. The transport repeats this check at the fetch boundary.
+      resolveTrustedElicitationEndpoints(
+        host.elicitationApiBaseUrl,
+        payload.ref,
+      );
+      if (payload.launch !== undefined) {
+        launchUrl = resolveTrustedElicitationLaunchUrl(
+          host.elicitationApiBaseUrl,
+          payload.launch.path,
+        );
+      }
+    } catch (error) {
+      transportConfigurationError =
+        error instanceof Error
+          ? error.message
+          : 'The trusted elicitation service is not configured safely.';
+    }
+  }
 
   const settle = useCallback(
     (next: VistaFormOutcome): void => {
@@ -85,14 +128,14 @@ export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
       .getAccessToken()
       .then((accessToken) =>
         submitElicitationFields({
-          submitUrl: payload.submitUrl,
+          apiBaseUrl: host.elicitationApiBaseUrl,
           ref: payload.ref,
           accessToken,
           fields: captureValuesToStringMap(payload.fields, values),
         }),
       )
       .then(settle, failed);
-  }, [host, isValid, payload.fields, payload.ref, payload.submitUrl, settle, failed, values]);
+  }, [host, isValid, payload.fields, payload.ref, settle, failed, values]);
 
   const handleCheckStatus = useCallback((): void => {
     if (host === null) return;
@@ -101,17 +144,23 @@ export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
     void host
       .getAccessToken()
       .then((accessToken) =>
-        readElicitationStatus({ statusUrl: payload.statusUrl, ref: payload.ref, accessToken }),
+        readElicitationStatus({
+          apiBaseUrl: host.elicitationApiBaseUrl,
+          ref: payload.ref,
+          accessToken,
+        }),
       )
       .then((next) => {
         if (next === null) {
-          setServiceError('Not completed yet — finish the steps in the other window, then check again.');
+          setServiceError(
+            'Not completed yet — finish the steps in the other window, then check again.',
+          );
           setPhase(FormPhase.Editing);
           return;
         }
         settle(next);
       }, failed);
-  }, [host, payload.ref, payload.statusUrl, settle, failed]);
+  }, [host, payload.ref, settle, failed]);
 
   // The consent/install window is a separate browsing context, so the only
   // signal this tab gets is the user returning to it. Re-checking on focus is
@@ -137,6 +186,19 @@ export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
     );
   }
 
+  if (transportConfigurationError !== null) {
+    return (
+      <Shell heading={payload.heading} purpose={payload.purpose}>
+        <Notice
+          tone="error"
+          title="The secure service is not configured safely"
+        >
+          {transportConfigurationError}
+        </Notice>
+      </Shell>
+    );
+  }
+
   if (phase === FormPhase.Settled && outcome !== null) {
     return (
       <Shell heading={payload.heading} purpose={payload.purpose}>
@@ -146,7 +208,10 @@ export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
             <p className="text-body-1 font-medium text-ink">Submitted.</p>
             <p className="text-caption text-ink-3">
               The value went straight to the service and was never shown to the
-              agent{outcome.connectionId === null ? '.' : `. Connection ${outcome.connectionId} is ready.`}
+              agent
+              {outcome.connectionId === null
+                ? '.'
+                : `. Connection ${outcome.connectionId} is ready.`}
             </p>
           </div>
         </div>
@@ -166,7 +231,9 @@ export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
           <div className="flex flex-wrap items-center gap-2">
             <Button
               onClick={() => {
-                globalThis.open(payload.launch?.url, '_blank', 'noopener,noreferrer');
+                // `launchUrl` was derived from the host trust anchor above; the
+                // payload contributes only a validated same-origin path.
+                globalThis.open(launchUrl, '_blank', 'noopener,noreferrer');
               }}
               className="gap-1.5"
               disabled={working}
@@ -174,7 +241,11 @@ export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
               <ExternalLink className="h-4 w-4" />
               {payload.launch.label}
             </Button>
-            <Button variant="outline" onClick={handleCheckStatus} disabled={working}>
+            <Button
+              variant="outline"
+              onClick={handleCheckStatus}
+              disabled={working}
+            >
               {working && <Loader2 className="mr-1 h-4 w-4 animate-spin" />}
               I&apos;ve finished — check
             </Button>
@@ -184,8 +255,8 @@ export function FormSurface(payload: Readonly<VistaFormPayload>): ReactElement {
         <>
           {payload.fields.length === 0 && (
             <Notice tone="warn" title="No form fields were declared">
-              This connector declares no onboarding form. Submitting will ask the
-              service, which is the authority on whether that is allowed.
+              This connector declares no onboarding form. Submitting will ask
+              the service, which is the authority on whether that is allowed.
             </Notice>
           )}
           <SchemaForm
@@ -217,16 +288,25 @@ function Shell({
   heading,
   purpose,
   children,
-}: Readonly<{ heading?: string; purpose: string; children: ReactNode }>): ReactElement {
+}: Readonly<{
+  heading?: string;
+  purpose: string;
+  children: ReactNode;
+}>): ReactElement {
   return (
     <div className="h-full overflow-auto">
       <div className="mx-auto max-w-2xl space-y-4 p-6">
         <div className="space-y-1">
-          <h2 className="text-subtitle font-semibold text-ink">{heading ?? 'Secure request'}</h2>
-          {purpose.length > 0 && <p className="text-body-1 text-ink-2">{purpose}</p>}
+          <h2 className="text-subtitle font-semibold text-ink">
+            {heading ?? 'Secure request'}
+          </h2>
+          {purpose.length > 0 && (
+            <p className="text-body-1 text-ink-2">{purpose}</p>
+          )}
           <p className="flex items-center gap-1.5 text-caption text-ink-3">
             <ShieldCheck className="h-3.5 w-3.5" />
-            Sent straight to the service with your own sign-in. The agent never sees what you type.
+            Sent straight to the service with your own sign-in. The agent never
+            sees what you type.
           </p>
         </div>
         {children}
@@ -239,23 +319,42 @@ function Notice({
   tone,
   title,
   children,
-}: Readonly<{ tone: 'error' | 'warn'; title: string; children: ReactNode }>): ReactElement {
+}: Readonly<{
+  tone: 'error' | 'warn';
+  title: string;
+  children: ReactNode;
+}>): ReactElement {
   return (
     <div
       role="alert"
       className={cn(
         'flex items-start gap-2 rounded-md border p-3',
-        tone === 'error' ? 'border-destructive/40 bg-destructive/10' : 'border-rule bg-paper-elev',
+        tone === 'error'
+          ? 'border-destructive/40 bg-destructive/10'
+          : 'border-rule bg-paper-elev',
       )}
     >
       <AlertTriangle
-        className={cn('mt-0.5 h-4 w-4 shrink-0', tone === 'error' ? 'text-destructive' : 'text-ink-3')}
+        className={cn(
+          'mt-0.5 h-4 w-4 shrink-0',
+          tone === 'error' ? 'text-destructive' : 'text-ink-3',
+        )}
       />
       <div className="space-y-0.5">
-        <p className={cn('text-body-1 font-medium', tone === 'error' ? 'text-destructive' : 'text-ink')}>
+        <p
+          className={cn(
+            'text-body-1 font-medium',
+            tone === 'error' ? 'text-destructive' : 'text-ink',
+          )}
+        >
           {title}
         </p>
-        <p className={cn('text-body-1', tone === 'error' ? 'text-destructive/90' : 'text-ink-3')}>
+        <p
+          className={cn(
+            'text-body-1',
+            tone === 'error' ? 'text-destructive/90' : 'text-ink-3',
+          )}
+        >
           {children}
         </p>
       </div>

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

@@ -12,11 +12,15 @@ 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';
@@ -39,14 +43,128 @@ afterEach(() => {
   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' } }),
+      jsonResponse(201, {
+        data: { submitted: true, ref: 'ref-1', connectionId: 'conn-9' },
+      }),
     );
 
     await submitElicitationFields({
-      submitUrl: SUBMIT_URL,
+      apiBaseUrl: API_BASE_URL,
       ref: 'ref-1',
       accessToken: 'user-jwt',
       fields: { apiKey: SECRET },
@@ -57,8 +175,11 @@ describe('submitElicitationFields', () => {
     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');
+    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 () => {
@@ -76,26 +197,36 @@ describe('submitElicitationFields', () => {
     );
 
     const outcome = await submitElicitationFields({
-      submitUrl: SUBMIT_URL,
+      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(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' } }),
+      jsonResponse(201, {
+        data: { submitted: true, ref: 'ref-1', connectionId: 'conn-9' },
+      }),
     );
 
     await submitElicitationFields({
-      submitUrl: SUBMIT_URL,
+      apiBaseUrl: API_BASE_URL,
       ref: 'ref-1',
       accessToken: 'user-jwt',
       fields: { baseUrl: 'https://acme.example.com', apiKey: SECRET },
@@ -108,10 +239,25 @@ describe('submitElicitationFields', () => {
   });
 
   it('accepts a flat (un-enveloped) response body', async () => {
-    stubFetch(jsonResponse(200, { submitted: true, ref: 'ref-1', connectionId: 'conn-2' }));
+    stubFetch(
+      jsonResponse(200, {
+        submitted: true,
+        ref: 'ref-1',
+        connectionId: 'conn-2',
+      }),
+    );
     await expect(
-      submitElicitationFields({ submitUrl: SUBMIT_URL, ref: 'ref-1', accessToken: 't', fields: {} }),
-    ).resolves.toEqual({ submitted: true, ref: 'ref-1', connectionId: 'conn-2' });
+      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 () => {
@@ -126,7 +272,7 @@ describe('submitElicitationFields', () => {
 
     // An empty field schema submits an empty map; the SERVICE is the authority.
     const promise = submitElicitationFields({
-      submitUrl: SUBMIT_URL,
+      apiBaseUrl: API_BASE_URL,
       ref: 'ref-1',
       accessToken: 'user-jwt',
       fields: {},
@@ -139,35 +285,67 @@ describe('submitElicitationFields', () => {
   it('refuses a 2xx that does not report the elicitation as submitted', async () => {
     stubFetch(jsonResponse(200, { data: { ref: 'ref-1' } }));
     await expect(
-      submitElicitationFields({ submitUrl: SUBMIT_URL, ref: 'ref-1', accessToken: 't', fields: {} }),
+      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 } }));
+    stubFetch(
+      jsonResponse(200, {
+        data: { ref: 'ref-1', status: 'pending', connectionId: null },
+      }),
+    );
     await expect(
-      readElicitationStatus({ statusUrl: STATUS_URL, ref: 'ref-1', accessToken: 't' }),
+      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' } }),
+      jsonResponse(200, {
+        data: { ref: 'ref-1', status: 'submitted', connectionId: 'conn-3' },
+      }),
     );
     await expect(
-      readElicitationStatus({ statusUrl: STATUS_URL, ref: 'ref-1', accessToken: 't' }),
-    ).resolves.toEqual({ submitted: true, ref: 'ref-1', connectionId: 'conn-3' });
+      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({ statusUrl: STATUS_URL, ref: 'ref-1', accessToken: 'user-jwt' });
+    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.headers as Record<string, string>).Authorization).toBe('Bearer user-jwt');
+    expect(init.redirect).toBe('error');
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      'Bearer user-jwt',
+    );
   });
 });
 
@@ -175,11 +353,15 @@ 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');
+    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(null, 503)).toBe(
+      'The service rejected the submission (HTTP 503).',
+    );
     expect(extractServiceMessage({ message: '' }, 500)).toBe(
       'The service rejected the submission (HTTP 500).',
     );