@oceanum/oceanumlab 4.6.1 → 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/__tests__/datameshUiUrl.spec.ts

@@ -0,0 +1,154 @@
+import schema from '../../schema/datamesh-connect.json';
+import { DATAMESH_UI_SERVICE } from '../constants';
+import {
+  datameshUiSrc,
+  isDatameshUiMessage,
+  validDatameshUiUrl
+} from '../datameshUiUrl';
+
+describe('validDatameshUiUrl', () => {
+  it('is the default the settings schema offers', () => {
+    expect(schema.properties.datameshUiUrl.default).toBe(DATAMESH_UI_SERVICE);
+  });
+
+  it('takes an http(s) address as it is', () => {
+    expect(validDatameshUiUrl('https://ui.datamesh.oceanum.tech').href).toBe(
+      'https://ui.datamesh.oceanum.tech/'
+    );
+    expect(validDatameshUiUrl('http://localhost:3000').href).toBe(
+      'http://localhost:3000/'
+    );
+  });
+
+  it.each([
+    ['empty', ''],
+    ['blank', '   '],
+    ['missing', undefined],
+    ['null', null],
+    ['not a URL', 'not a url'],
+    ['a relative path', '/datamesh'],
+    ['a javascript: URL', 'javascript:alert(1)'],
+    ['a data: URL', 'data:text/html,<script>alert(1)</script>'],
+    ['a file: URL', 'file:///etc/passwd']
+  ])('falls back to the default for %s', (_, url) => {
+    expect(validDatameshUiUrl(url).href).toBe(`${DATAMESH_UI_SERVICE}/`);
+  });
+});
+
+describe('datameshUiSrc', () => {
+  it('opens the default Datamesh UI in embed mode', () => {
+    expect(datameshUiSrc(DATAMESH_UI_SERVICE)).toBe(
+      'https://ui.datamesh.oceanum.io/?embed=1'
+    );
+  });
+
+  it('keeps the query and fragment a custom address already has', () => {
+    const src = new URL(
+      datameshUiSrc('https://ui.datamesh.oceanum.tech/app?workspace=abc#top')
+    );
+
+    expect(src.origin).toBe('https://ui.datamesh.oceanum.tech');
+    expect(src.pathname).toBe('/app');
+    expect(src.searchParams.get('workspace')).toBe('abc');
+    expect(src.searchParams.get('embed')).toBe('1');
+    expect(src.hash).toBe('#top');
+  });
+
+  it('does not add embed twice', () => {
+    const src = new URL(
+      datameshUiSrc('https://ui.datamesh.oceanum.io?embed=0')
+    );
+
+    expect(src.searchParams.getAll('embed')).toEqual(['1']);
+  });
+
+  it('opens the default for an invalid address', () => {
+    expect(datameshUiSrc('not a url')).toBe(
+      'https://ui.datamesh.oceanum.io/?embed=1'
+    );
+  });
+
+  it('never puts a javascript: URL in the iframe', () => {
+    expect(datameshUiSrc('javascript:alert(1)')).toBe(
+      'https://ui.datamesh.oceanum.io/?embed=1'
+    );
+  });
+});
+
+describe('isDatameshUiMessage', () => {
+  const frame = {} as Window;
+  const other = {} as Window;
+
+  it('accepts a message from the panel at the configured origin', () => {
+    expect(
+      isDatameshUiMessage(
+        { origin: 'https://ui.datamesh.oceanum.io', source: frame },
+        DATAMESH_UI_SERVICE,
+        frame
+      )
+    ).toBe(true);
+  });
+
+  it('compares origins, not whole addresses', () => {
+    expect(
+      isDatameshUiMessage(
+        { origin: 'https://ui.datamesh.oceanum.tech', source: frame },
+        'https://ui.datamesh.oceanum.tech/app?workspace=abc',
+        frame
+      )
+    ).toBe(true);
+  });
+
+  it.each([
+    ['another site', 'https://evil.example'],
+    ['the production UI when a dev one is configured', DATAMESH_UI_SERVICE],
+    ['another port', 'https://ui.datamesh.oceanum.tech:8443'],
+    ['plain http', 'http://ui.datamesh.oceanum.tech'],
+    ['an opaque origin', 'null']
+  ])('rejects a message from %s', (_, origin) => {
+    expect(
+      isDatameshUiMessage(
+        { origin, source: frame },
+        'https://ui.datamesh.oceanum.tech',
+        frame
+      )
+    ).toBe(false);
+  });
+
+  it('checks the origin against the default for an invalid setting', () => {
+    expect(
+      isDatameshUiMessage(
+        { origin: 'https://ui.datamesh.oceanum.io', source: frame },
+        'javascript:alert(1)',
+        frame
+      )
+    ).toBe(true);
+    expect(
+      isDatameshUiMessage(
+        { origin: 'null', source: frame },
+        'javascript:alert(1)',
+        frame
+      )
+    ).toBe(false);
+  });
+
+  it('rejects the right origin from another window', () => {
+    expect(
+      isDatameshUiMessage(
+        { origin: 'https://ui.datamesh.oceanum.io', source: other },
+        DATAMESH_UI_SERVICE,
+        frame
+      )
+    ).toBe(false);
+  });
+
+  it('rejects every message while the panel is closed', () => {
+    expect(
+      isDatameshUiMessage(
+        { origin: 'https://ui.datamesh.oceanum.io', source: null },
+        DATAMESH_UI_SERVICE,
+        null
+      )
+    ).toBe(false);
+  });
+});

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}` }
+  };
+}