@oceanum/oceanumlab 4.7.0 → 4.7.1

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

@@ -47,7 +47,7 @@ export interface IAiCredential {
 }
 
 /**
- * The backend address for an `aiBackendUrl` setting value, without a trailing
+ * 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 {

package/src/auth/accountWidget.ts

@@ -0,0 +1,113 @@
+import { CommandRegistry } from '@lumino/commands';
+import { Menu, Widget } from '@lumino/widgets';
+
+import { IPendingSignIn, ServerAuth } from './serverAuth';
+
+export const CommandIDs = {
+  signIn: 'oceanum-auth:sign-in',
+  signOut: 'oceanum-auth:sign-out',
+  account: 'oceanum-auth:account',
+  /**
+   * For other parts of oceanumlab and other extensions, such as the AI chat: resolves to
+   * the current access token, or `null` when signed out. Never rejects.
+   */
+  accessToken: 'oceanum-auth:access-token'
+} as const;
+
+/**
+ * The top-bar account control: "Sign in" when signed out, the user's email with a sign-out
+ * menu when signed in.
+ */
+export class AccountWidget extends Widget {
+  constructor(auth: ServerAuth, commands: CommandRegistry) {
+    super({ node: document.createElement('button') });
+    this._auth = auth;
+    this._commands = commands;
+    this._menu = new Menu({ commands });
+    this._menu.addItem({ command: CommandIDs.account });
+    this._menu.addItem({ type: 'separator' });
+    this._menu.addItem({ command: CommandIDs.signOut });
+    // The application shell refuses widgets without an id.
+    this.id = 'oceanum-account';
+    this.addClass('oc-Account');
+    this.node.setAttribute('type', 'button');
+    this.node.addEventListener('click', this._onClick);
+    auth.userChanged.connect(this._render, this);
+    auth.stateChanged.connect(this._render, this);
+    void auth.ready.then(() => this._render());
+    this._render();
+  }
+
+  dispose(): void {
+    if (this.isDisposed) {
+      return;
+    }
+    this.node.removeEventListener('click', this._onClick);
+    this._menu.dispose();
+    super.dispose();
+  }
+
+  private _onClick = (): void => {
+    if (!this._auth.user) {
+      void this._commands.execute(CommandIDs.signIn);
+      return;
+    }
+    const rect = this.node.getBoundingClientRect();
+    this._menu.open(rect.left, rect.bottom);
+  };
+
+  private _render(): void {
+    const user = this._auth.user;
+    const waiting = !user && this._auth.pending !== null;
+    this.node.textContent = user
+      ? user.email
+      : waiting
+        ? 'Signing in to Oceanum.io…'
+        : 'Sign in to Oceanum.io';
+    this.node.title = user
+      ? `Signed in to Oceanum.io as ${user.email}`
+      : 'Sign in to Oceanum.io';
+    this.toggleClass('oc-mod-signedIn', user !== null);
+  }
+
+  private _auth: ServerAuth;
+  private _commands: CommandRegistry;
+  private _menu: Menu;
+}
+
+/**
+ * What the sign-in dialog shows: the code to confirm, and a link to the page that confirms
+ * it. A real link rather than `window.open`, which a popup blocker stops once there has
+ * been an `await` between the click and the call -- and there always has, because the code
+ * comes from the server.
+ */
+export class SignInBody extends Widget {
+  constructor(pending: IPendingSignIn) {
+    super();
+    this.addClass('oc-SignIn');
+
+    const intro = document.createElement('p');
+    intro.textContent =
+      'Open the Oceanum.io sign-in page, and check that it shows this code:';
+
+    const code = document.createElement('div');
+    code.className = 'oc-SignIn-code';
+    code.textContent = pending.userCode;
+
+    const link = document.createElement('a');
+    link.className = 'oc-SignIn-link jp-mod-styled jp-mod-accept';
+    link.href = pending.verificationUriComplete;
+    link.target = '_blank';
+    link.rel = 'noopener noreferrer';
+    link.textContent = 'Open the sign-in page';
+
+    const note = document.createElement('p');
+    note.className = 'oc-SignIn-note';
+    const minutes = Math.max(1, Math.round(pending.expiresIn / 60));
+    note.textContent =
+      `This closes by itself once you have signed in. The code lasts ${minutes} ` +
+      `minute${minutes === 1 ? '' : 's'}. Only confirm a code you asked for yourself.`;
+
+    this.node.append(intro, code, link, note);
+  }
+}

package/src/auth/claims.ts

@@ -0,0 +1,30 @@
+import { ColorScheme, IOceanumUser } from './tokens';
+
+const CLAIM = 'https://oceanum.io/';
+const COLOR_SCHEMES: readonly ColorScheme[] = ['light', 'dark', 'auto'];
+
+/** Build the user from Auth0 ID token claims; `null` if the claims lack an identity. */
+export function userFromClaims(
+  claims: Record<string, unknown> | null | undefined
+): IOceanumUser | null {
+  if (!claims) {
+    return null;
+  }
+  const str = (value: unknown): string | null =>
+    typeof value === 'string' && value.length > 0 ? value : null;
+  const sub = str(claims.sub);
+  const email = str(claims.email) ?? str(claims[`${CLAIM}email`]);
+  if (!sub || !email) {
+    return null;
+  }
+  const scheme = claims[`${CLAIM}color_scheme`];
+  return {
+    sub,
+    email,
+    name: str(claims.name),
+    activeOrg: str(claims[`${CLAIM}active_org`]),
+    colorScheme: COLOR_SCHEMES.includes(scheme as ColorScheme)
+      ? (scheme as ColorScheme)
+      : null
+  };
+}

package/src/auth/plugin.ts

@@ -0,0 +1,155 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { Dialog, ICommandPalette, Notification } from '@jupyterlab/apputils';
+import { PageConfig, URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+
+import { AccountWidget, CommandIDs, SignInBody } from './accountWidget';
+import {
+  AuthRequest,
+  readServerAuthOption,
+  SERVER_AUTH_OPTION,
+  ServerAuth
+} from './serverAuth';
+import { IOceanumAuth } from './tokens';
+
+/**
+ * The id other deployments disable. notebook.oceanum.io provides IOceanumAuth from its own
+ * Oceanum widget extension, and Lumino lets a second provider silently replace the first
+ * rather than refusing it, so that site lists this id under `disabledExtensions`.
+ */
+export const DEVICE_AUTH_PLUGIN_ID = '@oceanum/oceanumlab:device-auth';
+
+function serverRequest(settings: ServerConnection.ISettings): AuthRequest {
+  return async (action, method) => {
+    const url = URLExt.join(settings.baseUrl, 'oceanum', 'auth', action);
+    const response = await ServerConnection.makeRequest(
+      url,
+      { method },
+      settings
+    );
+    if (!response.ok) {
+      throw new ServerConnection.ResponseError(response);
+    }
+    return response.json();
+  };
+}
+
+/** Show the code and the link until the sign-in completes, fails, or is cancelled. */
+async function showSignIn(auth: ServerAuth): Promise<void> {
+  const pending = auth.pending;
+  if (!pending) {
+    return;
+  }
+  const dialog = new Dialog({
+    title: 'Sign in to Oceanum.io',
+    body: new SignInBody(pending),
+    buttons: [Dialog.cancelButton()]
+  });
+  const closeWhenSettled = (): void => {
+    if (auth.pending === null) {
+      dialog.reject();
+    }
+  };
+  auth.stateChanged.connect(closeWhenSettled);
+  auth.userChanged.connect(closeWhenSettled);
+  try {
+    await dialog.launch();
+  } finally {
+    auth.stateChanged.disconnect(closeWhenSettled);
+    auth.userChanged.disconnect(closeWhenSettled);
+  }
+  if (auth.pending) {
+    // Still waiting, so it was the user who closed it.
+    await auth.cancelSignIn();
+  } else if (!auth.user && auth.error) {
+    Notification.warning(`Oceanum.io sign-in did not complete: ${auth.error}`, {
+      autoClose: false
+    });
+  }
+}
+
+export const deviceAuthPlugin: JupyterFrontEndPlugin<IOceanumAuth> = {
+  id: DEVICE_AUTH_PLUGIN_ID,
+  description:
+    'Oceanum.io sign-in by device code, run by the Jupyter server extension.',
+  autoStart: true,
+  provides: IOceanumAuth,
+  optional: [ICommandPalette],
+  activate: (
+    app: JupyterFrontEnd,
+    palette: ICommandPalette | null
+  ): IOceanumAuth => {
+    const environment = readServerAuthOption(
+      PageConfig.getOption(SERVER_AUTH_OPTION),
+      window.location.hostname
+    );
+    const auth = new ServerAuth({
+      environment,
+      request: serverRequest(app.serviceManager.serverSettings),
+      onSessionEnded: message =>
+        Notification.warning(message, { autoClose: false })
+    });
+    if (!environment) {
+      // The server offers no sign-in (`c.OceanumLab.sign_in = "off"`), or there is no
+      // oceanumlab server extension at all. Consumers see an auth with no environment and
+      // say sign-in is not configured; nothing is added to the top bar.
+      return auth;
+    }
+
+    document.addEventListener('visibilitychange', () => {
+      if (document.visibilityState === 'visible') {
+        void auth.refresh();
+      }
+    });
+
+    const { commands } = app;
+    let dialogOpen = false;
+    commands.addCommand(CommandIDs.signIn, {
+      label: 'Sign in to Oceanum.io',
+      isVisible: () => !auth.user,
+      execute: async () => {
+        await auth.signIn();
+        if (auth.pending && !dialogOpen) {
+          dialogOpen = true;
+          try {
+            await showSignIn(auth);
+          } finally {
+            dialogOpen = false;
+          }
+        } else if (!auth.user && !auth.pending && auth.error) {
+          Notification.warning(
+            `Oceanum.io sign-in could not start: ${auth.error}`,
+            { autoClose: false }
+          );
+        }
+      }
+    });
+    commands.addCommand(CommandIDs.signOut, {
+      label: 'Sign out of Oceanum.io',
+      isVisible: () => auth.user !== null,
+      execute: () => auth.signOut()
+    });
+    commands.addCommand(CommandIDs.account, {
+      label: () =>
+        auth.user ? `Signed in as ${auth.user.email}` : 'Not signed in',
+      isEnabled: () => false,
+      execute: () => undefined
+    });
+    commands.addCommand(CommandIDs.accessToken, {
+      label: 'Oceanum.io access token',
+      isVisible: () => false,
+      execute: () => auth.getAccessToken().catch((): null => null)
+    });
+    auth.userChanged.connect(() => commands.notifyCommandChanged());
+
+    if (palette) {
+      palette.addItem({ command: CommandIDs.signIn, category: 'Oceanum' });
+      palette.addItem({ command: CommandIDs.signOut, category: 'Oceanum' });
+    }
+    app.shell.add(new AccountWidget(auth, commands), 'top', { rank: 1000 });
+    return auth;
+  }
+};