@oceanum/oceanumlab 4.7.0 → 4.7.2

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__/shareClient.spec.ts

@@ -0,0 +1,314 @@
+import type { INotebookContent } from '@jupyterlab/nbformat';
+
+import { SpecStoreClient, SpecStoreError } from '../share/client';
+import type { ISpecBody } from '../share/notebook';
+
+const ID = '6f1c1a52-4b8e-4c0f-9a57-1d2e3f4a5b6c';
+const SERVER_ID = '0b7d9f2e-1111-4a2b-8c3d-9e8f7a6b5c4d';
+
+const notebook: INotebookContent = {
+  nbformat: 4,
+  nbformat_minor: 5,
+  metadata: {},
+  cells: []
+};
+
+function record(id: string = ID) {
+  return {
+    id,
+    name: 'Waves',
+    description: null as string | null,
+    modified: '2026-09-12T10:00:00',
+    creator: 'a@example.com',
+    spec: notebook
+  };
+}
+
+function json(data: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => data
+  } as unknown as Response;
+}
+
+function noContent(): Response {
+  return {
+    ok: true,
+    status: 204,
+    json: async () => {
+      throw new Error('no body');
+    }
+  } as unknown as Response;
+}
+
+function setup(
+  response: () => Response | Promise<Response>,
+  token: string | null = 'tok'
+) {
+  const fetch = jest.fn(
+    async (_input: RequestInfo | URL, _init?: RequestInit) => response()
+  );
+  const client = new SpecStoreClient({
+    specsUrl: 'https://specs.example.com/',
+    getAccessToken: async () => token,
+    fetch: fetch as unknown as typeof globalThis.fetch
+  });
+  const call = (i = 0) => {
+    const [url, init] = fetch.mock.calls[i];
+    return {
+      url: String(url),
+      method: init?.method,
+      headers: (init?.headers ?? {}) as Record<string, string>,
+      body: init?.body === undefined ? undefined : JSON.parse(String(init.body))
+    };
+  };
+  return { client, fetch, call };
+}
+
+const body: ISpecBody = { name: 'Waves', description: null, spec: notebook };
+
+describe('SpecStoreClient', () => {
+  it('lists with the bearer token', async () => {
+    const { client, call } = setup(() => json([record()]));
+    const items = await client.list();
+    expect(items).toHaveLength(1);
+    expect(call()).toEqual({
+      url: 'https://specs.example.com/specs/notebook',
+      method: 'GET',
+      headers: { Authorization: 'Bearer tok' },
+      body: undefined
+    });
+  });
+
+  it('requires sign-in to list, without calling the server', async () => {
+    const { client, fetch } = setup(() => json([]), null);
+    await expect(client.list()).rejects.toMatchObject({ kind: 'signed-out' });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('gets a record anonymously when signed out', async () => {
+    const { client, call } = setup(() => json(record()), null);
+    const result = await client.get(ID);
+    expect(result.id).toBe(ID);
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    expect(call().headers).toEqual({});
+  });
+
+  it('refuses ids that are not UUIDs before building a URL', async () => {
+    const { client, fetch } = setup(() => json(record()));
+    await expect(client.get('../eidos')).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+    await expect(client.update('x/permissions', body)).rejects.toBeInstanceOf(
+      SpecStoreError
+    );
+    await expect(client.remove('x')).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('creates with a JSON body, never sends an id, and uses the server id', async () => {
+    const { client, call } = setup(() => json(record(SERVER_ID)));
+    const withId = { ...body, id: ID } as ISpecBody;
+    const result = await client.create(withId);
+    expect(result.id).toBe(SERVER_ID);
+    expect(call()).toEqual({
+      url: 'https://specs.example.com/specs/notebook',
+      method: 'POST',
+      headers: {
+        Authorization: 'Bearer tok',
+        'Content-Type': 'application/json'
+      },
+      body: { name: 'Waves', description: null, spec: notebook }
+    });
+  });
+
+  it('updates with PUT to the record URL', async () => {
+    const { client, call } = setup(() => json(record()));
+    await client.update(ID, body);
+    expect(call().method).toBe('PUT');
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    expect(call().body).toEqual(body);
+  });
+
+  it('patches only the fields it is given', async () => {
+    const { client, call } = setup(() => json(record()));
+    await client.patch(ID, { name: 'Renamed' });
+    expect(call()).toEqual({
+      url: `https://specs.example.com/specs/notebook/${ID}`,
+      method: 'PATCH',
+      headers: {
+        Authorization: 'Bearer tok',
+        'Content-Type': 'application/json'
+      },
+      body: { name: 'Renamed' }
+    });
+  });
+
+  it('refuses a patch that carries nothing, without calling the server', async () => {
+    // The store answers an empty patch with 400, and there is nothing to send.
+    const { client, fetch } = setup(() => json(record()));
+    await expect(client.patch(ID, {})).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it('renames with a single patch, leaving the notebook alone', async () => {
+    const { client, call, fetch } = setup(() => json(record()));
+    await client.rename(ID, 'Renamed');
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(call().method).toBe('PATCH');
+    expect(call().body).toEqual({ name: 'Renamed' });
+  });
+
+  it('renames by reading and putting back where the store has no PATCH', async () => {
+    // Production served no PATCH when this was written; a store without it answers 405.
+    const responses: Record<string, () => Response> = {
+      PATCH: () => json('Method Not Allowed', 405),
+      GET: () => json({ ...record(), description: 'Wave stats' }),
+      PUT: () => json(record())
+    };
+    const fetch = jest.fn(
+      async (_input: RequestInfo | URL, init?: RequestInit) =>
+        responses[init?.method ?? 'GET']()
+    );
+    const client = new SpecStoreClient({
+      specsUrl: 'https://specs.example.com',
+      getAccessToken: async () => 'tok',
+      fetch: fetch as unknown as typeof globalThis.fetch
+    });
+
+    await client.rename(ID, 'Renamed');
+
+    expect(fetch.mock.calls.map(([, init]) => init?.method)).toEqual([
+      'PATCH',
+      'GET',
+      'PUT'
+    ]);
+    const put = JSON.parse(String(fetch.mock.calls[2][1]?.body));
+    // The name changes; everything else goes back as it was read.
+    expect(put).toEqual({
+      name: 'Renamed',
+      description: 'Wave stats',
+      spec: notebook
+    });
+  });
+
+  it('does not fall back for a failure that is not a missing method', async () => {
+    const { client, fetch } = setup(() => json('Forbidden', 403));
+    await expect(client.rename(ID, 'Renamed')).rejects.toMatchObject({
+      kind: 'forbidden'
+    });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('deletes with DELETE to the record URL, and needs sign-in', async () => {
+    const { client, call } = setup(() => noContent());
+    await client.remove(ID);
+    expect(call().method).toBe('DELETE');
+    expect(call().url).toBe(`https://specs.example.com/specs/notebook/${ID}`);
+    expect(call().body).toBeUndefined();
+
+    const signedOut = setup(() => noContent(), null);
+    await expect(signedOut.client.remove(ID)).rejects.toMatchObject({
+      kind: 'signed-out'
+    });
+    expect(signedOut.fetch).not.toHaveBeenCalled();
+  });
+
+  it('posts permission grants', async () => {
+    const { client, call } = setup(() => json([]));
+    await client.addPermission(ID, {
+      type: 'user',
+      entity: 'b@example.com',
+      permission: 'write'
+    });
+    await client.addPermission(ID, {
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+    expect(call(0).url).toBe(
+      `https://specs.example.com/specs/notebook/${ID}/permissions`
+    );
+    expect(call(0).method).toBe('POST');
+    expect(call(0).body).toEqual({
+      type: 'user',
+      entity: 'b@example.com',
+      permission: 'write'
+    });
+    expect(call(1).body).toEqual({
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+  });
+
+  it('deletes a permission by repeating the exact grant', async () => {
+    const { client, call } = setup(() => json([]));
+    await client.removePermission(ID, {
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+    expect(call(0).url).toBe(
+      `https://specs.example.com/specs/notebook/${ID}/permissions`
+    );
+    expect(call(0).method).toBe('DELETE');
+    expect(call(0).body).toEqual({
+      type: 'public',
+      entity: '',
+      permission: 'read'
+    });
+  });
+
+  it.each([
+    [400, 'expired', 'Your Oceanum session has expired, sign in again.'],
+    [403, 'forbidden', /another organisation/],
+    [404, 'not-found', /no longer exists/],
+    [405, 'unsupported', /does not offer that operation/],
+    [413, 'too-large', /too large/],
+    [500, 'server', 'Oceanum.io returned an error (HTTP 500).']
+  ])('maps HTTP %i to %s', async (status, kind, message) => {
+    const { client } = setup(() => json('Forbidden', status as number));
+    const error = await client.get(ID).catch(e => e);
+    expect(error).toBeInstanceOf(SpecStoreError);
+    expect(error.kind).toBe(kind);
+    expect(error.status).toBe(status);
+    expect(error.message).toMatch(message as string | RegExp);
+  });
+
+  it('maps a network failure', async () => {
+    const { client } = setup(() =>
+      Promise.reject(new TypeError('Failed to fetch'))
+    );
+    await expect(client.create(body)).rejects.toMatchObject({
+      kind: 'network',
+      message: expect.stringMatching(/Could not reach Oceanum.io/)
+    });
+  });
+
+  it('rejects malformed responses', async () => {
+    const { client } = setup(() => json({ id: 'nope', name: 1 }));
+    await expect(client.get(ID)).rejects.toMatchObject({ kind: 'invalid' });
+    const list = setup(() => json({ detail: 'x' }));
+    await expect(list.client.list()).rejects.toMatchObject({
+      kind: 'invalid'
+    });
+  });
+
+  it('asks for a fresh token on every request', async () => {
+    const getAccessToken = jest.fn(async () => 'tok');
+    const client = new SpecStoreClient({
+      specsUrl: 'https://specs.example.com',
+      getAccessToken,
+      fetch: async () => json(record())
+    });
+    await client.get(ID);
+    await client.get(ID);
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+  });
+});