@oceanum/oceanumlab 4.6.2 → 4.7.0

package/src/__tests__/chatRouter.spec.ts

@@ -1,9 +1,33 @@
+import type { AuthCommands } from '../aiBackend';
 import { ChatRouter } from '../chatRouter';
 import type { INotebookSnapshot } from '../notebookContext';
 
-const settings = {
-  get: () => ({ composite: 'a-token' })
-} as unknown as ConstructorParameters<typeof ChatRouter>[0];
+/** Settings holding `values`; a key not given has no value. */
+const settingsWith = (values: Record<string, unknown>) =>
+  ({
+    get: (key: string) => ({ composite: values[key] })
+  }) as unknown as ConstructorParameters<typeof ChatRouter>[0];
+
+const settings = settingsWith({ datameshToken: 'a-token' });
+
+/**
+ * A host with these commands, each answering with what its function returns.
+ * `enabled` and `visible` are what the registry's queries answer, which is how
+ * the sign-in state is read without running anything.
+ */
+const hostCommands = (
+  commands: Record<string, () => unknown>,
+  { enabled = [] as string[], visible = [] as string[] } = {}
+) =>
+  ({
+    hasCommand: jest.fn((id: string) => id in commands),
+    execute: jest.fn(async (id: string) => commands[id]()),
+    isEnabled: jest.fn((id: string) => enabled.includes(id)),
+    isVisible: jest.fn((id: string) => visible.includes(id))
+  }) as AuthCommands & { execute: jest.Mock };
+
+/** Plain JupyterLab: no Oceanum.io sign-in to lend. */
+const noSignIn = hostCommands({});
 
 const snapshot = (
   cells: INotebookSnapshot['cells'],
@@ -12,6 +36,7 @@ const snapshot = (
 
 let sent: Record<string, unknown> | undefined;
 let sentHeaders: Record<string, string> | undefined;
+let sentUrl: string | undefined;
 
 interface IRequestInit {
   body: string;
@@ -22,9 +47,10 @@ interface IRequestInit {
 /** Answer every request with what `response` builds from it. */
 function answering(response: (init: IRequestInit) => unknown): void {
   (globalThis as any).fetch = jest.fn(
-    async (_url: string, init: IRequestInit) => {
+    async (url: string, init: IRequestInit) => {
       sent = JSON.parse(init.body);
       sentHeaders = init.headers;
+      sentUrl = url;
       return response(init);
     }
   );
@@ -33,6 +59,7 @@ function answering(response: (init: IRequestInit) => unknown): void {
 beforeEach(() => {
   sent = undefined;
   sentHeaders = undefined;
+  sentUrl = undefined;
   answering(() => ({
     ok: true,
     status: 200,
@@ -82,7 +109,7 @@ function streamed(frames: string[], signal?: AbortSignal, hang = false) {
 
 describe('ChatRouter: the notebook sent with a request', () => {
   it('is the conversation notebook, code and markdown', async () => {
-    const router = new ChatRouter(settings, async () =>
+    const router = new ChatRouter(settings, noSignIn, async () =>
       snapshot([
         { kind: 'code', source: 'x = 1' },
         { kind: 'markdown', source: '## Notes' },
@@ -100,7 +127,7 @@ describe('ChatRouter: the notebook sent with a request', () => {
   });
 
   it('carries the selected cell of that notebook, which a code answer may replace', async () => {
-    const router = new ChatRouter(settings, async () =>
+    const router = new ChatRouter(settings, noSignIn, async () =>
       snapshot([{ kind: 'code', source: 'df.head()' }], {
         source: 'df.head()',
         isCode: true
@@ -115,7 +142,7 @@ describe('ChatRouter: the notebook sent with a request', () => {
 
   it('asks for the notebook on every request, so it follows the conversation', async () => {
     let current = snapshot([{ kind: 'code', source: 'a = 1' }]);
-    const router = new ChatRouter(settings, async () => current);
+    const router = new ChatRouter(settings, noSignIn, async () => current);
 
     await router.route('one');
     expect(sent?.notebookCells).toEqual(['a = 1']);
@@ -126,7 +153,7 @@ describe('ChatRouter: the notebook sent with a request', () => {
   });
 
   it('sends no notebook when there is none', async () => {
-    const router = new ChatRouter(settings, async () => null);
+    const router = new ChatRouter(settings, noSignIn, async () => null);
 
     await router.route('hello');
 
@@ -138,7 +165,7 @@ describe('ChatRouter: the notebook sent with a request', () => {
   it('still sends the question when the notebook cannot be read', async () => {
     // Context is best-effort; a notebook that could not be read must not
     // cost the user the answer.
-    const router = new ChatRouter(settings, async () => {
+    const router = new ChatRouter(settings, noSignIn, async () => {
       throw new Error('could not read');
     });
 
@@ -154,7 +181,7 @@ describe('ChatRouter: the streamed answer', () => {
 
   it('asks for the stream only when someone is listening', async () => {
     // Without a listener the request is byte-identical to what it always was.
-    const router = new ChatRouter(settings, noNotebook);
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
 
     await router.route('hello');
     expect(sentHeaders?.Accept).toBeUndefined();
@@ -179,7 +206,7 @@ describe('ChatRouter: the streamed answer', () => {
       ])
     );
     const progress: unknown[] = [];
-    const router = new ChatRouter(settings, noNotebook);
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
 
     const result = await router.route('find waves', [], undefined, p =>
       progress.push(p)
@@ -197,7 +224,7 @@ describe('ChatRouter: the streamed answer', () => {
 
   it('reads JSON when the server answers with JSON anyway', async () => {
     // An older backend, or a proxy that buffered the stream away.
-    const router = new ChatRouter(settings, noNotebook);
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
 
     const result = await router.route('hello', [], undefined, () => undefined);
 
@@ -216,7 +243,7 @@ describe('ChatRouter: the streamed answer', () => {
         })
       ])
     );
-    const router = new ChatRouter(settings, noNotebook);
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
 
     await expect(
       router.route('hi', [], undefined, () => undefined)
@@ -230,7 +257,7 @@ describe('ChatRouter: the streamed answer', () => {
   it('fails a stream that ends without its answer', async () => {
     // A dropped connection: a failure, not a shorter answer.
     answering(() => streamed([frame('status', { phase: 'generating' })]));
-    const router = new ChatRouter(settings, noNotebook);
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
 
     await expect(
       router.route('hi', [], undefined, () => undefined)
@@ -261,7 +288,7 @@ describe('ChatRouter: the streamed answer', () => {
         })
       }
     }));
-    const router = new ChatRouter(settings, noNotebook);
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
 
     await expect(
       router.route('hi', [], undefined, () => undefined)
@@ -280,7 +307,7 @@ describe('ChatRouter: the streamed answer', () => {
       ])
     );
     const progress: unknown[] = [];
-    const router = new ChatRouter(settings, noNotebook);
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
 
     const response = await router.observe(
       'hi',
@@ -301,7 +328,7 @@ describe('ChatRouter: the streamed answer', () => {
       streamed([frame('status', { phase: 'generating' })], init.signal, true)
     );
     const progress: unknown[] = [];
-    const router = new ChatRouter(settings, noNotebook);
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
 
     const pending = router.route('hi', [], controller.signal, p =>
       progress.push(p)
@@ -313,3 +340,218 @@ describe('ChatRouter: the streamed answer', () => {
     expect(progress).toEqual([{ phase: 'generating' }]);
   });
 });
+
+describe('ChatRouter: where a request goes, and what it is signed with', () => {
+  const noNotebook = async (): Promise<null> => null;
+  /** Oceanum Notebook with sign-in configured, and someone signed in. */
+  const signedIn = (token: () => unknown) =>
+    hostCommands(
+      {
+        'oceanum-auth:access-token': token,
+        'oceanum-auth:sign-in': () => undefined,
+        'oceanum-auth:sign-out': () => undefined
+      },
+      {
+        enabled: ['oceanum-auth:sign-in'],
+        visible: ['oceanum-auth:sign-out']
+      }
+    );
+
+  it('sends a pasted token as X-Datamesh-Token to the default backend', async () => {
+    const router = new ChatRouter(settings, noSignIn, noNotebook);
+
+    await router.route('hello');
+
+    expect(sentUrl).toBe('https://ai.oceanum.io/api/chat');
+    expect(sentHeaders?.['X-Datamesh-Token']).toBe('a-token');
+    expect(sentHeaders?.Authorization).toBeUndefined();
+  });
+
+  it('prefers a pasted token over the sign-in, without asking for it', async () => {
+    // An explicit token is the user's choice, as it is in the kernel.
+    const host = signedIn(() => 'a-jwt');
+    const router = new ChatRouter(settings, host, noNotebook);
+
+    await router.route('hello');
+
+    expect(sentHeaders?.['X-Datamesh-Token']).toBe('a-token');
+    expect(sentHeaders?.Authorization).toBeUndefined();
+    expect(host.execute).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['no', undefined],
+    ['an empty', ''],
+    ['a blank', '   ']
+  ])(
+    'uses the sign-in as a bearer token with %s pasted token',
+    async (_, token) => {
+      const router = new ChatRouter(
+        settingsWith({ datameshToken: token }),
+        signedIn(() => 'a-jwt'),
+        noNotebook
+      );
+
+      await router.route('hello');
+
+      expect(sentHeaders?.Authorization).toBe('Bearer a-jwt');
+      expect(sentHeaders?.['X-Datamesh-Token']).toBeUndefined();
+    }
+  );
+
+  it('asks for the sign-in on every request, so a refreshed token is used', async () => {
+    let token = 'first-jwt';
+    const router = new ChatRouter(
+      settingsWith({}),
+      signedIn(() => token),
+      noNotebook
+    );
+
+    await router.route('one');
+    expect(sentHeaders?.Authorization).toBe('Bearer first-jwt');
+
+    token = 'second-jwt';
+    await router.observe('two', [], []);
+    expect(sentHeaders?.Authorization).toBe('Bearer second-jwt');
+  });
+
+  it('sends to the configured address, without a double slash', async () => {
+    const router = new ChatRouter(
+      settingsWith({
+        datameshToken: 'a-token',
+        aiBackendUrl: ' https://ai.oceanum.tech/ '
+      }),
+      noSignIn,
+      noNotebook
+    );
+
+    await router.route('hello');
+    expect(sentUrl).toBe('https://ai.oceanum.tech/api/chat');
+
+    await router.observe('hello', [], []);
+    expect(sentUrl).toBe('https://ai.oceanum.tech/api/chat/observe');
+  });
+
+  it('sends to the default for an invalid address', async () => {
+    const router = new ChatRouter(
+      settingsWith({
+        datameshToken: 'a-token',
+        aiBackendUrl: 'javascript:alert(1)'
+      }),
+      noSignIn,
+      noNotebook
+    );
+
+    await router.route('hello');
+
+    expect(sentUrl).toBe('https://ai.oceanum.io/api/chat');
+  });
+
+  it('asks the user to sign in when the host can sign in and nobody has', async () => {
+    const router = new ChatRouter(
+      settingsWith({}),
+      signedIn(() => null),
+      noNotebook
+    );
+
+    await expect(router.route('hello')).rejects.toMatchObject({
+      name: 'ChatRouterError',
+      message: expect.stringContaining('Sign in to Oceanum.io')
+    });
+    expect((globalThis as any).fetch).not.toHaveBeenCalled();
+  });
+
+  it('asks for a Datamesh token when the host has no sign-in', async () => {
+    const router = new ChatRouter(settingsWith({}), noSignIn, noNotebook);
+
+    await expect(router.route('hello')).rejects.toThrow(
+      'Datamesh token not configured. Set your token in Settings → Oceanum.io.'
+    );
+    expect((globalThis as any).fetch).not.toHaveBeenCalled();
+  });
+
+  it('asks for a Datamesh token where the site has sign-in disabled', async () => {
+    // The command is there, but the site has no Oceanum.io environment, so
+    // telling the user to sign in would be telling them to do the impossible.
+    const router = new ChatRouter(
+      settingsWith({}),
+      hostCommands({
+        'oceanum-auth:access-token': () => null,
+        'oceanum-auth:sign-in': () => undefined
+      }),
+      noNotebook
+    );
+
+    await expect(router.route('hello')).rejects.toThrow(
+      'Datamesh token not configured. Set your token in Settings → Oceanum.io.'
+    );
+  });
+
+  it.each([
+    ['rejects', () => Promise.reject(new Error('no'))],
+    ['answers with something other than a string', () => ({ token: 'x' })]
+  ])('counts a sign-in command that %s as signed out', async (_, answer) => {
+    const router = new ChatRouter(
+      settingsWith({}),
+      signedIn(answer),
+      noNotebook
+    );
+
+    await expect(router.route('hello')).rejects.toThrow(
+      'Sign in to Oceanum.io'
+    );
+    expect((globalThis as any).fetch).not.toHaveBeenCalled();
+  });
+
+  it('says the sign-in was refused on a 401 with the sign-in', async () => {
+    answering(() => ({ ok: false, status: 401 }));
+    const router = new ChatRouter(
+      settingsWith({}),
+      signedIn(() => 'a-jwt'),
+      noNotebook
+    );
+
+    await expect(router.route('hello')).rejects.toMatchObject({
+      message:
+        'Your Oceanum.io sign-in was not accepted. Sign in to Oceanum.io again.',
+      statusCode: 401
+    });
+  });
+
+  it('says the token was refused on a 401 with a pasted token', async () => {
+    answering(() => ({ ok: false, status: 401 }));
+
+    await expect(
+      new ChatRouter(settings, noSignIn, noNotebook).route('hello')
+    ).rejects.toMatchObject({
+      message: 'Invalid or expired Datamesh token.',
+      statusCode: 401
+    });
+    // Where the host can sign in, the pasted token is what stands in the way.
+    await expect(
+      new ChatRouter(
+        settings,
+        signedIn(() => 'a-jwt'),
+        noNotebook
+      ).route('hello')
+    ).rejects.toThrow('clear it to use your Oceanum.io sign-in');
+  });
+
+  it('names the configured address when it cannot be reached', async () => {
+    (globalThis as any).fetch = jest.fn(async () => {
+      throw new TypeError('Failed to fetch');
+    });
+    const router = new ChatRouter(
+      settingsWith({
+        datameshToken: 'a-token',
+        aiBackendUrl: 'http://localhost:8000/'
+      }),
+      noSignIn,
+      noNotebook
+    );
+
+    await expect(router.route('hello')).rejects.toThrow(
+      'Could not reach Oceanum AI backend at http://localhost:8000. Is it running?'
+    );
+  });
+});

package/src/aiBackend.ts

@@ -0,0 +1,150 @@
+/**
+ * Where the Oceanum AI backend is, and what a request to it is signed with.
+ *
+ * The backend accepts either a Datamesh token (`X-Datamesh-Token`) or an
+ * Oceanum.io access token (`Authorization: Bearer`). A token pasted into the
+ * settings is explicit, so it wins; otherwise a host that signs users in to
+ * Oceanum.io -- Oceanum Notebook -- lends its sign-in through its commands.
+ * Plain JupyterLab has no such commands and needs the pasted token.
+ *
+ * Whether the user is signed in, or can sign in, is read with the registry's
+ * queries (`isVisible`, `isEnabled`), never by running a command: every
+ * `execute` emits `commandExecuted`, which closes JupyterLab's command palette.
+ * The access-token command is run only when a token is actually needed.
+ */
+import type { CommandRegistry } from '@lumino/commands';
+import { OCEANUM_AI_BACKEND_URL } from './constants';
+import { validHttpUrl } from './httpUrl';
+
+/**
+ * The host's command answering with the current Oceanum.io access token (a
+ * JWT), or null when signed out. The token is cached and refreshed by the
+ * host, so it is asked for on every use rather than kept.
+ */
+export const ACCESS_TOKEN_COMMAND = 'oceanum-auth:access-token';
+
+/**
+ * The host's command that starts signing in to Oceanum.io. Enabled only where
+ * sign-in is configured for the site.
+ */
+export const SIGN_IN_COMMAND = 'oceanum-auth:sign-in';
+
+/** The host's command that signs out. Visible only while signed in. */
+export const SIGN_OUT_COMMAND = 'oceanum-auth:sign-out';
+
+/** The part of the command registry the sign-in is reached through. */
+export type AuthCommands = Pick<
+  CommandRegistry,
+  'hasCommand' | 'execute' | 'isEnabled' | 'isVisible'
+>;
+
+export type AiCredentialSource = 'datamesh-token' | 'sign-in';
+
+export interface IAiCredential {
+  /** Which credential it is: the 401 message differs. */
+  source: AiCredentialSource;
+  headers: Record<string, string>;
+}
+
+/**
+ * The backend address for an `aiBackendUrl` setting value, without a trailing
+ * slash so a path can be appended. An invalid value falls back to the default.
+ */
+export function aiBackendUrl(value: string | null | undefined): string {
+  const url = validHttpUrl(value, OCEANUM_AI_BACKEND_URL);
+  return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+}
+
+/** A `datameshToken` setting value, trimmed; '' when there is none. */
+export function pastedToken(datameshToken: unknown): string {
+  return typeof datameshToken === 'string' ? datameshToken.trim() : '';
+}
+
+/**
+ * Asks a query of the host's command, treating a missing command, or a query
+ * that throws, as false. Queries never emit `commandExecuted`.
+ */
+function query(
+  commands: AuthCommands,
+  id: string,
+  which: 'isEnabled' | 'isVisible'
+): boolean {
+  try {
+    return commands.hasCommand(id) && commands[which](id);
+  } catch {
+    return false;
+  }
+}
+
+/** Whether the host can sign the user in to Oceanum.io on this site. */
+export function canSignIn(commands: AuthCommands): boolean {
+  return query(commands, SIGN_IN_COMMAND, 'isEnabled');
+}
+
+/** Whether the host says the user is signed in to Oceanum.io. */
+export function isSignedIn(commands: AuthCommands): boolean {
+  return query(commands, SIGN_OUT_COMMAND, 'isVisible');
+}
+
+/**
+ * Which credential a request would carry, without fetching it: runs no
+ * command, so it is safe to ask whenever something changes.
+ */
+export function aiCredentialSource(
+  datameshToken: unknown,
+  commands: AuthCommands
+): AiCredentialSource | null {
+  if (pastedToken(datameshToken)) {
+    return 'datamesh-token';
+  }
+  if (commands.hasCommand(ACCESS_TOKEN_COMMAND) && isSignedIn(commands)) {
+    return 'sign-in';
+  }
+  return null;
+}
+
+/**
+ * Asks the host for its Oceanum.io access token; null without the command.
+ * This runs a command: call it only when a token is needed for a request.
+ */
+export function signInToken(commands: AuthCommands): () => Promise<unknown> {
+  return async () =>
+    commands.hasCommand(ACCESS_TOKEN_COMMAND)
+      ? commands.execute(ACCESS_TOKEN_COMMAND)
+      : null;
+}
+
+/**
+ * The credential for a request: the pasted Datamesh token if there is one,
+ * otherwise the host's sign-in, otherwise null.
+ *
+ * @param datameshToken The `datameshToken` setting value.
+ * @param getSignInToken Asked only without a pasted token. Anything but a
+ *   non-empty string -- including a rejection -- counts as signed out.
+ */
+export async function resolveAiCredential(
+  datameshToken: unknown,
+  getSignInToken: () => Promise<unknown>
+): Promise<IAiCredential | null> {
+  const pasted = pastedToken(datameshToken);
+  if (pasted) {
+    return {
+      source: 'datamesh-token',
+      headers: { 'X-Datamesh-Token': pasted }
+    };
+  }
+  let token: unknown;
+  try {
+    token = await getSignInToken();
+  } catch {
+    return null;
+  }
+  const signedIn = typeof token === 'string' ? token.trim() : '';
+  if (!signedIn) {
+    return null;
+  }
+  return {
+    source: 'sign-in',
+    headers: { Authorization: `Bearer ${signedIn}` }
+  };
+}

package/src/chatRouter.ts

@@ -1,5 +1,11 @@
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
-import { OCEANUM_AI_BACKEND_URL } from './constants';
+import {
+  aiBackendUrl,
+  canSignIn,
+  resolveAiCredential,
+  signInToken,
+  type AuthCommands
+} from './aiBackend';
 import type { Progress } from './progress';
 import { readSse } from './sse';
 import type { ObservedRun } from './notebookRun';
@@ -76,6 +82,8 @@ function asOceanumResponse(data: unknown): OceanumResponse {
 
 export class ChatRouter {
   /**
+   * @param _commands Where the host's Oceanum.io sign-in is asked for, when
+   *   there is no pasted Datamesh token.
    * @param _notebook What the conversation's notebook holds -- the one its
    *   answers are placed in -- or null if there is nothing to send. Asked on
    *   every request, so it follows the conversation rather than whichever tab
@@ -83,6 +91,7 @@ export class ChatRouter {
    */
   constructor(
     private _settings: ISettingRegistry.ISettings,
+    private _commands: AuthCommands,
     private _notebook: () => Promise<INotebookSnapshot | null>
   ) {}
 
@@ -178,20 +187,30 @@ export class ChatRouter {
     signal?: AbortSignal,
     onProgress?: (progress: Progress) => void
   ): Promise<unknown> {
-    const token = this._settings.get('datameshToken').composite as string;
-    if (!token) {
+    // Resolved per request, not once: the sign-in token refreshes, and the
+    // user can sign in, sign out or paste a token between two requests.
+    const credential = await resolveAiCredential(
+      this._settings.get('datameshToken').composite,
+      signInToken(this._commands)
+    );
+    if (!credential) {
       throw new ChatRouterError(
-        'Datamesh token not configured. Set your token in Settings → Oceanum.io.'
+        canSignIn(this._commands)
+          ? 'Not signed in. Sign in to Oceanum.io to use Oceanum AI, or set a Datamesh token in Settings → Oceanum.io.'
+          : 'Datamesh token not configured. Set your token in Settings → Oceanum.io.'
       );
     }
+    const backend = aiBackendUrl(
+      this._settings.get('aiBackendUrl').composite as string
+    );
 
     let response: Response;
     try {
-      response = await fetch(`${OCEANUM_AI_BACKEND_URL}${path}`, {
+      response = await fetch(`${backend}${path}`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
-          'X-Datamesh-Token': token,
+          ...credential.headers,
           // Ask for the streamed form only when someone is listening. The
           // server requires the media type to be NAMED -- a wildcard never
           // selects it -- so omitting this is what keeps the plain JSON path
@@ -208,12 +227,21 @@ export class ChatRouter {
         throw err;
       }
       throw new ChatRouterError(
-        `Could not reach Oceanum AI backend at ${OCEANUM_AI_BACKEND_URL}. Is it running?`
+        `Could not reach Oceanum AI backend at ${backend}. Is it running?`
       );
     }
 
     if (response.status === 401) {
-      throw new ChatRouterError('Invalid or expired Datamesh token.', 401);
+      let message = 'Invalid or expired Datamesh token.';
+      if (credential.source === 'sign-in') {
+        message =
+          'Your Oceanum.io sign-in was not accepted. Sign in to Oceanum.io again.';
+      } else if (canSignIn(this._commands)) {
+        // A pasted token wins over the sign-in, so say how to fall back to it.
+        message +=
+          ' Update it, or clear it to use your Oceanum.io sign-in, in Settings → Oceanum.io.';
+      }
+      throw new ChatRouterError(message, 401);
     }
 
     if (!response.ok) {

package/src/constants.ts

@@ -3,7 +3,7 @@
  * These values are compiled into the extension.
  */
 
-/** URL of the Oceanum AI backend service */
+/** Default URL of the Oceanum AI backend service (the `aiBackendUrl` setting) */
 export const OCEANUM_AI_BACKEND_URL = 'https://ai.oceanum.io';
 
 /** URL of the Datamesh UI embedded in the Datamesh panel */

package/src/datameshUiUrl.ts

@@ -7,18 +7,11 @@
  * rather than ending up in an iframe's `src`.
  */
 import { DATAMESH_UI_SERVICE } from './constants';
+import { validHttpUrl } from './httpUrl';
 
 /** The Datamesh UI address to use for a `datameshUiUrl` setting value. */
 export function validDatameshUiUrl(url: string | null | undefined): URL {
-  try {
-    const parsed = new URL((url ?? '').trim());
-    if (parsed.protocol === 'https:' || parsed.protocol === 'http:') {
-      return parsed;
-    }
-  } catch {
-    // Empty or not a URL: the default below.
-  }
-  return new URL(DATAMESH_UI_SERVICE);
+  return validHttpUrl(url, DATAMESH_UI_SERVICE);
 }
 
 /**

package/src/httpUrl.ts

@@ -0,0 +1,23 @@
+/**
+ * An address typed into a setting, checked before anything uses it.
+ *
+ * A setting is typed in by hand, so anything that is not an http(s) URL falls
+ * back to the default rather than ending up in an iframe's `src` or a
+ * request's address.
+ */
+
+/** `value` as an http(s) URL, or `fallback` when it is empty or not one. */
+export function validHttpUrl(
+  value: string | null | undefined,
+  fallback: string
+): URL {
+  try {
+    const parsed = new URL((value ?? '').trim());
+    if (parsed.protocol === 'https:' || parsed.protocol === 'http:') {
+      return parsed;
+    }
+  } catch {
+    // Empty or not a URL: the default below.
+  }
+  return new URL(fallback);
+}