@oceanum/oceanumlab 4.6.2 → 4.7.1

package/src/auth/tokens.ts

@@ -0,0 +1,104 @@
+import { Token } from '@lumino/coreutils';
+import { ISignal } from '@lumino/signaling';
+
+/**
+ * One Oceanum deployment (production or development).
+ */
+export interface IOceanumEnvironment {
+  /** Page hostnames served by this environment, e.g. `notebook.oceanum.io`. */
+  readonly hosts: readonly string[];
+  /** Auth0 tenant domain, e.g. `auth.oceanum.io`. */
+  readonly auth0Domain: string;
+  /** Auth0 SPA client id. */
+  readonly clientId: string;
+  /**
+   * The Oceanum apps domain, e.g. `oceanum.io`. The Oceanum nav builds its app, account,
+   * docs and sign-out URLs from it (`https://platform.oceanum.io/account`, ...).
+   */
+  readonly oceanumDomain: string;
+  /** Service base URLs for this environment. */
+  readonly urls: IOceanumServiceUrls;
+  /**
+   * Whether to check for an existing Oceanum.io session with a full-page redirect when the
+   * silent iframe check finds none. Only for a tenant on another site than the notebook
+   * (browsers that block third-party cookies hide the session from the iframe), and only where
+   * the site origin is an allowed callback URL.
+   */
+  readonly signInRedirect: boolean;
+}
+
+/** Service base URLs for an environment, without trailing slashes. */
+export interface IOceanumServiceUrls {
+  /** Datamesh gateway, e.g. `https://datamesh.oceanum.io`. */
+  readonly datamesh: string;
+  /** Spec store, e.g. `https://specs.oceanum.io`. */
+  readonly specs: string;
+  /** User management service (Auth0 user metadata), e.g. `https://manage.oceanum.io`. */
+  readonly manage: string;
+  /**
+   * Datamesh UI, e.g. `https://ui.datamesh.oceanum.io`, shown by oceanumlab's Datamesh panel.
+   * Optional: without it, Oceanum production applies.
+   */
+  readonly datameshUi?: string;
+  /**
+   * Oceanum AI backend, e.g. `https://ai.oceanum.io`, called by oceanumlab's AI chat.
+   * Optional: without it, Oceanum production applies.
+   */
+  readonly ai?: string;
+}
+
+export type ColorScheme = 'light' | 'dark' | 'auto';
+
+/** The signed-in user, from the Auth0 ID token claims. */
+export interface IOceanumUser {
+  readonly sub: string;
+  readonly email: string;
+  readonly name: string | null;
+  /** `https://oceanum.io/active_org`. */
+  readonly activeOrg: string | null;
+  /** `https://oceanum.io/color_scheme`. */
+  readonly colorScheme: ColorScheme | null;
+}
+
+/**
+ * Oceanum.io sign-in state, shared with other Oceanum Notebook extensions.
+ */
+export interface IOceanumAuth {
+  /** The environment for this page, or `null` if sign-in is not configured for this host. */
+  readonly environment: IOceanumEnvironment | null;
+  /** Service URLs for `environment`, or `null` when it is `null`. */
+  readonly urls: IOceanumServiceUrls | null;
+  /** Resolves once any login redirect has been handled and the session restored. */
+  readonly ready: Promise<void>;
+  /** The signed-in user, or `null`. */
+  readonly user: IOceanumUser | null;
+  /** Emits the new user (or `null`) on sign-in and sign-out. */
+  readonly userChanged: ISignal<IOceanumAuth, IOceanumUser | null>;
+  /** Emits the new access token (or `null`) whenever it changes, including refreshes. */
+  readonly tokenChanged: ISignal<IOceanumAuth, string | null>;
+  /**
+   * Start sign-in without leaving the page, so its kernels survive. Resolves once sign-in has
+   * started, not when it completes; watch `userChanged` for the result. Does nothing while a
+   * user is signed in.
+   */
+  signIn(): Promise<void>;
+  /** Sign out of Oceanum.io and clear the session. */
+  signOut(): Promise<void>;
+  /**
+   * A current access token, refreshed if it is near expiry, or `null` when signed out.
+   * Never cache the result: Auth0 access tokens are short-lived.
+   */
+  getAccessToken(): Promise<string | null>;
+}
+
+/**
+ * The sign-in contract. oceanumlab owns it and exports it from its package entry, because a
+ * Lumino token is matched by object identity: every extension that provides or consumes it
+ * has to import this one object, which JupyterLab arranges by sharing `@oceanum/oceanumlab`
+ * as a singleton module. On an ordinary JupyterLab oceanumlab's own device sign-in provides
+ * it; on notebook.oceanum.io the notebook's Oceanum widget extension does.
+ */
+export const IOceanumAuth = new Token<IOceanumAuth>(
+  '@oceanum/oceanumlab:IOceanumAuth',
+  'Oceanum.io sign-in state and Datamesh access tokens.'
+);

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,7 +91,14 @@ export class ChatRouter {
    */
   constructor(
     private _settings: ISettingRegistry.ISettings,
-    private _notebook: () => Promise<INotebookSnapshot | null>
+    private _commands: AuthCommands,
+    private _notebook: () => Promise<INotebookSnapshot | null>,
+    /**
+     * The Oceanum AI backend's address: the signed-in deployment's, or empty for the
+     * production default. Deployment configuration, not a setting -- a user-editable
+     * address is somewhere to send the user's credential.
+     */
+    private _backend: () => string = () => ''
   ) {}
 
   async route(
@@ -178,20 +193,28 @@ 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._backend());
 
     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 +231,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, where the deployment names none. */
 export const OCEANUM_AI_BACKEND_URL = 'https://ai.oceanum.io';
 
 /** URL of the Datamesh UI embedded in the Datamesh panel */

package/src/datameshUiUrl.ts

@@ -1,29 +1,22 @@
 /**
  * The Datamesh UI panel's address, and which messages may come from it.
  *
- * The address is a setting (`datameshUiUrl`), so a deployment can point the
- * panel at another Datamesh UI -- a dev one, say. 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`.
+ * The address comes from the deployment's sign-in environment, so a development
+ * deployment can point the panel at its own Datamesh UI. It is still written by a
+ * person in a config file, so anything that is not an http(s) URL falls back to the
+ * default 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. */
+/** The Datamesh UI address to use for a configured 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);
 }
 
 /**
  * The panel's iframe `src`: the Datamesh UI in embed mode, which hides the
- * Oceanum.io navigator. Any query the setting already has is kept.
+ * Oceanum.io navigator. Any query the address already has is kept.
  */
 export function datameshUiSrc(url: string | null | undefined): string {
   const src = validDatameshUiUrl(url);

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

package/src/index.ts

@@ -7,6 +7,7 @@ import {
 import { ICommandPalette, Notification } from '@jupyterlab/apputils';
 import { LabIcon } from '@jupyterlab/ui-components';
 import { find } from '@lumino/algorithm';
+import { Signal } from '@lumino/signaling';
 import { Widget } from '@lumino/widgets';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { IStateDB } from '@jupyterlab/statedb';
@@ -17,11 +18,18 @@ import { requestAPI } from './handler';
 import { ChatRouter, ChatRouterError, ChatMessage } from './chatRouter';
 import { reporterFor } from './progress';
 import { ConversationPin } from './conversationPin';
+import { deviceAuthPlugin } from './auth/plugin';
+import { IOceanumAuth } from './auth/tokens';
+
 import { snapshotFromIpynb, snapshotOf } from './notebookContext';
 import { notebookHost } from './notebookHost';
 import { KernelHandoff } from './kernelHandoff';
 import { runChatLoop, STOPPED } from './aiLoop';
-import { DATAMESH_UI_SERVICE, MAX_OBSERVE_ROUNDS } from './constants';
+import {
+  DATAMESH_UI_SERVICE,
+  MAX_OBSERVE_ROUNDS,
+  OCEANUM_AI_BACKEND_URL
+} from './constants';
 
 import '../style/index.css';
 
@@ -48,17 +56,30 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
     ISettingRegistry,
     IStateDB
   ],
+  // Optional so the panel still loads on a host with no Oceanum environment; the
+  // Notebooks tab then explains why it is empty instead of the panel failing to start.
+  optional: [IOceanumAuth],
   activate: (
     app: JupyterFrontEnd,
     palette: ICommandPalette,
     restorer: ILayoutRestorer,
     status: ILabStatus,
-    settingRegistry: ISettingRegistry
+    settingRegistry: ISettingRegistry,
+    stateDB: IStateDB,
+    auth: IOceanumAuth | null
   ) => {
     console.log('Oceanum datamesh connect extension is loaded');
 
-    // The `datameshUiUrl` setting; the default until the settings load.
-    let datameshUiUrl = DATAMESH_UI_SERVICE;
+    // Where the Datamesh UI and Oceanum AI live is the deployment's business, so it comes
+    // from the sign-in environment (the Jupyter server's configuration, or the notebook
+    // site's) and falls back to production. These were user settings until 4.7.1; a
+    // user-editable service address is somewhere to send the user's credential.
+    const datameshUiUrl = auth?.urls?.datameshUi ?? DATAMESH_UI_SERVICE;
+    const aiBackendUrl = auth?.urls?.ai ?? OCEANUM_AI_BACKEND_URL;
+    // The `datameshToken` setting for the AI chat; empty until the settings load.
+    let datameshTokenSetting = '';
+    // Tells the sidebar the settings above have changed.
+    const settingsChanged = new Signal<JupyterFrontEnd, void>(app);
 
     const findDatameshUI = (): DatameshUI | undefined =>
       find(
@@ -77,12 +98,8 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
         }).then(res => console.log(res));
       }
       window.injectToken = set.get('injectToken').user as boolean;
-      // An open Datamesh UI panel follows a change of address.
-      datameshUiUrl = set.get('datameshUiUrl').composite as string;
-      const datameshUI = findDatameshUI();
-      if (datameshUI) {
-        datameshUI.url = datameshUiUrl;
-      }
+      datameshTokenSetting = set.get('datameshToken').composite as string;
+      settingsChanged.emit();
     };
     //Try to get the datamesh token from the envars
 
@@ -127,8 +144,17 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
       openDatameshUI: openDatameshUI,
       datameshUiUrl: () => datameshUiUrl,
       datameshUiFrame: () => findDatameshUI()?.frame ?? null,
+      datameshToken: () => datameshTokenSetting,
+      aiBackendUrl: () => aiBackendUrl,
+      settingsChanged,
       commands: app.commands,
-      getCurrentWidget
+      getCurrentWidget,
+      auth
+      // No `openStoredNotebook`: nothing can open a spec store record by id yet.
+      // share-oceanum has `oceanum-share:open`, but it takes no arguments — it opens
+      // its own picker — so there is nothing to hand an id to. Opening arrives with
+      // the drive in OCE-182, where the contents API makes it the ordinary path.
+      // Until then the list reads rather than offering a click that does nothing.
     });
     datameshConnectWidget.id = 'datamesh-connect';
     datameshConnectWidget.title.icon = oceanumIcon;
@@ -136,8 +162,30 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
 
     restorer.add(datameshConnectWidget, 'datamesh-connect');
 
+    // The layout restorer restores the widget's place in the shell, not fields on it,
+    // so the chosen tab is kept here. Restoring is best effort: a missing or unreadable
+    // entry just leaves the default.
+    const TAB_STATE_KEY = `${PLUGIN_ID}:tab`;
+    void stateDB
+      .fetch(TAB_STATE_KEY)
+      .then(value => {
+        if (typeof value === 'string') {
+          datameshConnectWidget.selectTab(value);
+        }
+      })
+      .catch((): void => undefined);
+    datameshConnectWidget.tabChanged.connect((_, id) => {
+      void stateDB.save(TAB_STATE_KEY, id);
+    });
+
     // Rank has been chosen somewhat arbitrarily to give priority to the running
     // sessions widget in the sidebar.
+    //
+    // Oceanum Notebook wants this panel first instead, but that is a property of that
+    // distribution rather than of the extension: in a plain JupyterLab the file browser
+    // is the primary navigation surface and displacing it would be a regression. A
+    // distribution moves it with JupyterLab's own shell user-layout settings, keyed on
+    // this widget's id, rather than this extension hard-coding one host's preference.
     app.shell.add(datameshConnectWidget, 'left', { rank: 900 });
 
     app.commands.addCommand('datamesh-ui:open', {
@@ -157,10 +205,12 @@ export const oceanum_ai_extension: JupyterFrontEndPlugin<void> = {
   id: '@oceanum/oceanumlab:ai-chat',
   autoStart: true,
   requires: [INotebookTracker, ISettingRegistry],
+  optional: [IOceanumAuth],
   activate: (
     app: JupyterFrontEnd,
     notebookTracker: INotebookTracker,
-    settingRegistry: ISettingRegistry
+    settingRegistry: ISettingRegistry,
+    auth: IOceanumAuth | null
   ) => {
     console.log('Oceanum AI chat extension is loaded');
 
@@ -180,26 +230,31 @@ export const oceanum_ai_extension: JupyterFrontEndPlugin<void> = {
         // The panel the current request read its selected cell from, if the
         // notebook was open: a code answer may replace that cell only there.
         let readFrom: NotebookPanel | null = null;
-        const router = new ChatRouter(settings, async () => {
-          const open = await pin.current();
-          readFrom = open;
-          if (open) {
-            return snapshotOf(open.content);
-          }
-          const path = pin.path();
-          if (!path) {
-            return null;
-          }
-          try {
-            const file = await app.serviceManager.contents.get(path, {
-              content: true
-            });
-            return snapshotFromIpynb(file.content);
-          } catch {
-            // Gone: an answer's cells will go into a new notebook instead.
-            return null;
-          }
-        });
+        const router = new ChatRouter(
+          settings,
+          app.commands,
+          async () => {
+            const open = await pin.current();
+            readFrom = open;
+            if (open) {
+              return snapshotOf(open.content);
+            }
+            const path = pin.path();
+            if (!path) {
+              return null;
+            }
+            try {
+              const file = await app.serviceManager.contents.get(path, {
+                content: true
+              });
+              return snapshotFromIpynb(file.content);
+            } catch {
+              // Gone: an answer's cells will go into a new notebook instead.
+              return null;
+            }
+          },
+          () => auth?.urls?.ai ?? ''
+        );
         // Asked only when an answer has blocks to place: brings the
         // conversation's notebook to the front, opening it again if closed.
         const handoff = new KernelHandoff(
@@ -335,4 +390,15 @@ export const oceanum_ai_extension: JupyterFrontEndPlugin<void> = {
   }
 };
 
-export default [datamesh_connect_extension, oceanum_ai_extension];
+/**
+ * The sign-in contract, exported so another extension can provide or consume it: a Lumino
+ * token is matched by object identity, so everyone has to import this one object, and
+ * JupyterLab shares `@oceanum/oceanumlab` between extensions as a singleton module.
+ */
+export * from './auth/tokens';
+
+export default [
+  deviceAuthPlugin,
+  datamesh_connect_extension,
+  oceanum_ai_extension
+];

package/src/specStore.ts

@@ -0,0 +1,82 @@
+/**
+ * Reading the Oceanum spec store's `notebook` records.
+ *
+ * Deliberately small: only what the Stored notebooks tab needs. oceanum-notebook's
+ * share-oceanum package has a fuller client (create, update, permissions), and when
+ * sharing moves here the two should become one rather than sitting side by side.
+ */
+
+/** A spec store list entry. The list omits the notebook body. */
+export interface ISpecSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  /** Set when the record is created and never updated, so this is a creation time. */
+  modified: string;
+  /** Null unless the caller created the record: the store hides other creators. */
+  creator: string | null;
+}
+
+function isSummary(value: unknown): value is ISpecSummary {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.id === 'string' &&
+    typeof v.name === 'string' &&
+    typeof v.modified === 'string'
+  );
+}
+
+/**
+ * Every notebook the signed-in user may read: their own and those shared with them.
+ *
+ * The store answers an unauthenticated caller with an empty list rather than an error,
+ * so a missing token is indistinguishable from an empty account — callers should check
+ * they are signed in before showing "no notebooks".
+ */
+export async function listNotebooks(
+  specsUrl: string,
+  token: string,
+  fetcher: typeof fetch = fetch
+): Promise<ISpecSummary[]> {
+  const url = `${specsUrl.replace(/\/+$/, '')}/specs/notebook`;
+  const response = await fetcher(url, {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  if (!response.ok) {
+    // The store answers a bad or expired token with 400, and 403 both for no access
+    // and for a record that does not exist.
+    throw new Error(`Oceanum.io returned HTTP ${response.status}.`);
+  }
+  const data = await response.json();
+  if (!Array.isArray(data)) {
+    throw new Error('Oceanum.io returned an unexpected response.');
+  }
+  return data.filter(isSummary);
+}
+
+/**
+ * Split a listing into the caller's own notebooks and the rest, newest first.
+ *
+ * The store only sends `creator` on records the caller created, so anything else it
+ * returns is shared with them — directly, or because it is public. Addresses are
+ * compared case-insensitively: the store matches entities as case-sensitive globs, so
+ * the two sides can differ in case.
+ */
+export function partitionNotebooks(
+  items: readonly ISpecSummary[],
+  email: string | null
+): { mine: ISpecSummary[]; shared: ISpecSummary[] } {
+  const me = email?.toLowerCase() ?? null;
+  const sorted = [...items].sort((a, b) =>
+    b.modified.localeCompare(a.modified)
+  );
+  const isMine = (item: ISpecSummary): boolean =>
+    me !== null && item.creator?.toLowerCase() === me;
+  return {
+    mine: sorted.filter(isMine),
+    shared: sorted.filter(item => !isMine(item))
+  };
+}