@oceanum/oceanumlab 4.6.2 → 4.7.1

package/src/__tests__/serverAuth.spec.ts

@@ -0,0 +1,277 @@
+import {
+  AuthRequest,
+  readServerAuthOption,
+  SERVER_AUTH_OPTION,
+  ServerAuth
+} from '../auth/serverAuth';
+import { IOceanumEnvironment } from '../auth/tokens';
+
+const OPTION = JSON.stringify({
+  auth0Domain: 'auth.oceanum.io',
+  clientId: 'a-client',
+  oceanumDomain: 'oceanum.io',
+  urls: {
+    datamesh: 'https://datamesh.oceanum.io/',
+    specs: 'https://specs.oceanum.io',
+    manage: 'https://manage.oceanum.io',
+    ai: 'https://ai.oceanum.io'
+  }
+});
+
+const ENVIRONMENT = readServerAuthOption(
+  OPTION,
+  'localhost'
+) as IOceanumEnvironment;
+
+const CLAIMS = { sub: 'auth0|abc', email: 'ada@example.org', name: 'Ada' };
+const PENDING = {
+  userCode: 'WXYZ-1234',
+  verificationUri: 'https://auth.oceanum.io/activate',
+  verificationUriComplete:
+    'https://auth.oceanum.io/activate?user_code=WXYZ-1234',
+  expiresIn: 900
+};
+
+const SIGNED_OUT = {
+  state: 'signedOut',
+  claims: null as unknown,
+  pending: null as unknown,
+  error: null as string | null
+};
+const WAITING = { ...SIGNED_OUT, state: 'pending', pending: PENDING };
+const SIGNED_IN = { ...SIGNED_OUT, state: 'signedIn', claims: CLAIMS };
+
+/** A Jupyter server whose answers can be changed as the test goes. */
+function server(initial: Record<string, unknown>) {
+  const calls: string[] = [];
+  const state = { status: initial, token: 'jwt-1' as string | null };
+  const request: AuthRequest = async (action, method) => {
+    calls.push(`${method} ${action}`);
+    if (action === 'token') {
+      const signedIn = state.status.state === 'signedIn';
+      return { ...state.status, accessToken: signedIn ? state.token : null };
+    }
+    return state.status;
+  };
+  return { calls, state, request };
+}
+
+const tick = (ms = 0): Promise<void> =>
+  new Promise(resolve => setTimeout(resolve, ms));
+
+async function until(check: () => void, timeout = 2000): Promise<void> {
+  const end = Date.now() + timeout;
+  for (;;) {
+    try {
+      check();
+      return;
+    } catch (err) {
+      if (Date.now() > end) {
+        throw err;
+      }
+    }
+    await tick(10);
+  }
+}
+
+describe('readServerAuthOption', () => {
+  it('reads the page option name the server publishes under', () => {
+    // oceanumlab/__init__.py writes this literal (SERVER_AUTH_OPTION there, pinned by its
+    // own test). Renaming either side alone would silently turn sign-in off everywhere.
+    expect(SERVER_AUTH_OPTION).toBe('oceanumServerAuth');
+  });
+
+  it('builds the environment, normalising URLs and dropping absent optional ones', () => {
+    expect(ENVIRONMENT.urls).toEqual({
+      datamesh: 'https://datamesh.oceanum.io',
+      specs: 'https://specs.oceanum.io',
+      manage: 'https://manage.oceanum.io',
+      ai: 'https://ai.oceanum.io'
+    });
+    // The device grant is indifferent to the page's address, so there is nothing to match.
+    expect(ENVIRONMENT.hosts).toEqual(['localhost']);
+  });
+
+  it('treats a missing or unusable option as no sign-in on offer', () => {
+    expect(readServerAuthOption(undefined, 'localhost')).toBeNull();
+    expect(readServerAuthOption('', 'localhost')).toBeNull();
+    expect(readServerAuthOption('not json', 'localhost')).toBeNull();
+    expect(readServerAuthOption('[]', 'localhost')).toBeNull();
+    const noSpecs = JSON.parse(OPTION);
+    delete noSpecs.urls.specs;
+    expect(
+      readServerAuthOption(JSON.stringify(noSpecs), 'localhost')
+    ).toBeNull();
+    const script = JSON.parse(OPTION);
+    script.urls.specs = 'javascript:alert(1)';
+    expect(
+      readServerAuthOption(JSON.stringify(script), 'localhost')
+    ).toBeNull();
+  });
+});
+
+describe('ServerAuth', () => {
+  it('is inert, and ready, when the server offers no sign-in', async () => {
+    const jupyter = server(SIGNED_OUT);
+    const auth = new ServerAuth({
+      environment: null,
+      request: jupyter.request
+    });
+
+    await auth.ready;
+    await auth.signIn();
+
+    expect(auth.user).toBeNull();
+    expect(await auth.getAccessToken()).toBeNull();
+    expect(jupyter.calls).toEqual([]);
+    auth.dispose();
+  });
+
+  it('finds a session the server already holds, before it says it is ready', async () => {
+    // A page reload, or a second tab: the server signed in earlier and still is.
+    const jupyter = server(SIGNED_IN);
+    const auth = new ServerAuth({
+      environment: ENVIRONMENT,
+      request: jupyter.request
+    });
+
+    await auth.ready;
+
+    expect(auth.user?.email).toBe('ada@example.org');
+    expect(await auth.getAccessToken()).toBe('jwt-1');
+    auth.dispose();
+  });
+
+  it('starts a sign-in, waits on the user, then reports the user and the token', async () => {
+    const jupyter = server(SIGNED_OUT);
+    const auth = new ServerAuth({
+      environment: ENVIRONMENT,
+      request: jupyter.request,
+      pendingPollMs: 10
+    });
+    await auth.ready;
+    const users: (string | null)[] = [];
+    const tokens: (string | null)[] = [];
+    auth.userChanged.connect((_, user) => users.push(user?.email ?? null));
+    auth.tokenChanged.connect((_, token) => tokens.push(token));
+
+    jupyter.state.status = WAITING;
+    await auth.signIn();
+    expect(auth.pending?.userCode).toBe('WXYZ-1234');
+    expect(auth.user).toBeNull();
+
+    // The user confirms the code in their browser; the server's next answer says so.
+    jupyter.state.status = SIGNED_IN;
+    await until(() => expect(auth.user?.email).toBe('ada@example.org'));
+
+    expect(auth.pending).toBeNull();
+    expect(users).toEqual(['ada@example.org']);
+    expect(tokens).toEqual(['jwt-1']);
+    auth.dispose();
+  });
+
+  it('passes on a refreshed token while signed in', async () => {
+    const jupyter = server(SIGNED_IN);
+    const auth = new ServerAuth({
+      environment: ENVIRONMENT,
+      request: jupyter.request,
+      tokenPollMs: 10
+    });
+    await auth.ready;
+    const tokens: (string | null)[] = [];
+    auth.tokenChanged.connect((_, token) => tokens.push(token));
+
+    jupyter.state.token = 'jwt-2';
+    await until(() => expect(tokens).toEqual(['jwt-2']));
+    auth.dispose();
+  });
+
+  it('signs out without calling it a session that ended', async () => {
+    const jupyter = server(SIGNED_IN);
+    const ended: string[] = [];
+    const auth = new ServerAuth({
+      environment: ENVIRONMENT,
+      request: jupyter.request,
+      onSessionEnded: message => ended.push(message)
+    });
+    await auth.ready;
+    const tokens: (string | null)[] = [];
+    auth.tokenChanged.connect((_, token) => tokens.push(token));
+
+    jupyter.state.status = SIGNED_OUT;
+    await auth.signOut();
+
+    expect(jupyter.calls).toContain('POST signout');
+    expect(auth.user).toBeNull();
+    expect(tokens).toEqual([null]);
+    expect(ended).toEqual([]);
+    auth.dispose();
+  });
+
+  it('says so when the server ends the session itself', async () => {
+    const jupyter = server(SIGNED_IN);
+    const ended: string[] = [];
+    const auth = new ServerAuth({
+      environment: ENVIRONMENT,
+      request: jupyter.request,
+      onSessionEnded: message => ended.push(message),
+      tokenPollMs: 10
+    });
+    await auth.ready;
+
+    // The refresh token was revoked: the server's next answer is signed out, with why.
+    jupyter.state.status = {
+      ...SIGNED_OUT,
+      error: 'Your Oceanum.io session has ended.'
+    };
+    await until(() => expect(auth.user).toBeNull());
+
+    expect(ended).toEqual(['Your Oceanum.io session has ended.']);
+    auth.dispose();
+  });
+
+  it('keeps the session when the Jupyter server is briefly unreachable', async () => {
+    const jupyter = server(SIGNED_IN);
+    let failing = false;
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+    const auth = new ServerAuth({
+      environment: ENVIRONMENT,
+      request: async (action, method) => {
+        if (failing) {
+          throw new Error('connection refused');
+        }
+        return jupyter.request(action, method);
+      }
+    });
+    await auth.ready;
+
+    failing = true;
+    await auth.refresh();
+
+    // One failed request is not a sign-out.
+    expect(auth.user?.email).toBe('ada@example.org');
+    auth.dispose();
+    warn.mockRestore();
+  });
+
+  it('cancels a sign-in that is waiting', async () => {
+    const jupyter = server(SIGNED_OUT);
+    const auth = new ServerAuth({
+      environment: ENVIRONMENT,
+      request: jupyter.request,
+      pendingPollMs: 10000
+    });
+    await auth.ready;
+    jupyter.state.status = WAITING;
+    await auth.signIn();
+
+    jupyter.state.status = SIGNED_OUT;
+    await auth.cancelSignIn();
+
+    expect(jupyter.calls).toContain('POST cancel');
+    expect(auth.pending).toBeNull();
+    auth.dispose();
+  });
+});

package/src/__tests__/settingsSchema.spec.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+import { ISettingRegistry, SettingRegistry } from '@jupyterlab/settingregistry';
+
+const ID = '@oceanum/oceanumlab:datamesh-connect';
+const schema = JSON.parse(
+  readFileSync(join(__dirname, '../../schema/datamesh-connect.json'), 'utf8')
+) as ISettingRegistry.ISchema;
+
+/** A registry whose stored user settings for the plugin are `user`. */
+function registryWith(user: Record<string, unknown>): SettingRegistry {
+  const plugin: ISettingRegistry.IPlugin = {
+    id: ID,
+    data: { user: {}, composite: {} },
+    raw: JSON.stringify(user),
+    schema,
+    version: 'test'
+  };
+  const connector = {
+    fetch: async (): Promise<ISettingRegistry.IPlugin> => plugin,
+    list: async () => ({ ids: [ID], values: [plugin] }),
+    save: async (): Promise<void> => undefined,
+    remove: async (): Promise<void> => undefined
+  };
+  return new SettingRegistry({ connector: connector as any });
+}
+
+/**
+ * `datameshUiUrl` and `aiBackendUrl` were user settings until 4.7.1. They are deployment
+ * configuration now: a user-editable service address is somewhere to send the user's
+ * credential.
+ *
+ * Taking them out of the schema is not enough on its own, and would have been a breaking
+ * release. The schema is `additionalProperties: false`, the registry REJECTS a load whose
+ * stored settings fail validation, and these two keys are stored for every
+ * notebook.oceanum.io user: until this release that site wrote each environment's addresses
+ * into oceanumlab's settings. Every one of them would have lost the whole settings load --
+ * the Datamesh token with it.
+ */
+describe('the datamesh-connect settings schema', () => {
+  it('no longer offers the two service addresses as settings', () => {
+    expect(Object.keys(schema.properties ?? {})).toEqual([
+      'datameshToken',
+      'injectToken',
+      'autoRunCode',
+      'iterate'
+    ]);
+  });
+
+  it('still loads settings stored when they were', async () => {
+    const registry = registryWith({
+      datameshToken: 'a-token',
+      datameshUiUrl: 'https://ui.datamesh.oceanum.tech',
+      aiBackendUrl: 'https://ai.oceanum.tech'
+    });
+
+    const settings = await registry.load(ID);
+
+    expect(settings.get('datameshToken').composite).toBe('a-token');
+  });
+
+  it('stays strict about everything else', async () => {
+    // Tolerating those two must not turn into tolerating typos.
+    const warn = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+    const registry = registryWith({ datameshTokn: 'a-typo' });
+
+    await expect(registry.load(ID)).rejects.toBeDefined();
+    warn.mockRestore();
+  });
+});

package/src/__tests__/specStore.spec.ts

@@ -0,0 +1,126 @@
+import { ISpecSummary, listNotebooks, partitionNotebooks } from '../specStore';
+
+function summary(overrides: Partial<ISpecSummary> = {}): ISpecSummary {
+  return {
+    id: 'nb-1',
+    name: 'Wave analysis',
+    description: null,
+    modified: '2026-05-17T12:00:00',
+    creator: null,
+    ...overrides
+  };
+}
+
+function response(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body
+  } as unknown as Response;
+}
+
+describe('listNotebooks', () => {
+  it('asks the notebook spec type with the token as a bearer credential', async () => {
+    const calls: [string, RequestInit | undefined][] = [];
+    const fetcher = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      return response([]);
+    }) as unknown as typeof fetch;
+
+    await listNotebooks('https://specs.example.com', 'jwt', fetcher);
+
+    expect(calls[0][0]).toBe('https://specs.example.com/specs/notebook');
+    expect((calls[0][1]?.headers as Record<string, string>).Authorization).toBe(
+      'Bearer jwt'
+    );
+  });
+
+  it('tolerates a trailing slash on the service url', async () => {
+    const calls: string[] = [];
+    const fetcher = (async (url: string) => {
+      calls.push(url);
+      return response([]);
+    }) as unknown as typeof fetch;
+
+    await listNotebooks('https://specs.example.com//', 'jwt', fetcher);
+
+    expect(calls[0]).toBe('https://specs.example.com/specs/notebook');
+  });
+
+  it('reports the status rather than returning an empty list', async () => {
+    // The store answers a bad or expired token with 400, so silently returning []
+    // would look exactly like an account with no notebooks.
+    const fetcher = (async () =>
+      response({ detail: 'bad' }, 400)) as unknown as typeof fetch;
+    await expect(
+      listNotebooks('https://specs.example.com', 'jwt', fetcher)
+    ).rejects.toThrow('HTTP 400');
+  });
+
+  it('rejects a body that is not a list', async () => {
+    const fetcher = (async () =>
+      response({ detail: 'nope' })) as unknown as typeof fetch;
+    await expect(
+      listNotebooks('https://specs.example.com', 'jwt', fetcher)
+    ).rejects.toThrow('unexpected response');
+  });
+
+  it('drops entries that are not summaries rather than rendering undefined', async () => {
+    const fetcher = (async () =>
+      response([
+        summary({ id: 'good' }),
+        { id: 'bad' },
+        null
+      ])) as unknown as typeof fetch;
+    const items = await listNotebooks(
+      'https://specs.example.com',
+      'jwt',
+      fetcher
+    );
+    expect(items.map(item => item.id)).toEqual(['good']);
+  });
+});
+
+describe('partitionNotebooks', () => {
+  it('splits the caller own records from the rest', () => {
+    const mine = summary({ id: 'mine', creator: 'dave@oceanum.science' });
+    const theirs = summary({ id: 'theirs', creator: null });
+    const { mine: own, shared } = partitionNotebooks(
+      [mine, theirs],
+      'dave@oceanum.science'
+    );
+    expect(own.map(i => i.id)).toEqual(['mine']);
+    expect(shared.map(i => i.id)).toEqual(['theirs']);
+  });
+
+  it('compares addresses case-insensitively', () => {
+    // The store matches entities as case-sensitive globs, so the claim and the stored
+    // creator can differ in case for the same person.
+    const { mine } = partitionNotebooks(
+      [summary({ creator: 'Dave@Oceanum.Science' })],
+      'dave@oceanum.science'
+    );
+    expect(mine).toHaveLength(1);
+  });
+
+  it('treats everything as shared when nobody is signed in', () => {
+    const { mine, shared } = partitionNotebooks(
+      [summary({ creator: null }), summary({ id: 'b', creator: 'a@b.com' })],
+      null
+    );
+    expect(mine).toEqual([]);
+    expect(shared).toHaveLength(2);
+  });
+
+  it('orders each group newest first without mutating the input', () => {
+    const input = [
+      summary({ id: 'old', modified: '2026-01-01T00:00:00' }),
+      summary({ id: 'new', modified: '2026-05-17T00:00:00' })
+    ];
+    expect(partitionNotebooks(input, null).shared.map(i => i.id)).toEqual([
+      'new',
+      'old'
+    ]);
+    expect(input.map(i => i.id)).toEqual(['old', 'new']);
+  });
+});

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