@oceanum/oceanumlab 4.6.2 → 4.7.1

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

package/src/auth/serverAuth.ts

@@ -0,0 +1,341 @@
+/**
+ * Oceanum.io sign-in on an ordinary JupyterLab, where the Jupyter server runs the OAuth
+ * device grant (oceanumlab/auth.py) and this only reflects its state.
+ *
+ * A browser sign-in cannot work here. Popup, redirect and the silent iframe check all send
+ * the page's own origin to Auth0 as the callback, Auth0 only accepts addresses registered in
+ * advance, and it cannot wildcard a port or an arbitrary host -- so everywhere but Oceanum's
+ * own sites the answer is "Callback URL mismatch". The device grant has no callback: the
+ * user opens a link and confirms a code, and the server collects the tokens.
+ *
+ * The refresh token and the device code never reach this page. It is handed short-lived
+ * access tokens only.
+ */
+import { PromiseDelegate } from '@lumino/coreutils';
+import { IDisposable } from '@lumino/disposable';
+import { ISignal, Signal } from '@lumino/signaling';
+
+import { userFromClaims } from './claims';
+import {
+  IOceanumAuth,
+  IOceanumEnvironment,
+  IOceanumServiceUrls,
+  IOceanumUser
+} from './tokens';
+
+/**
+ * The page option the server extension publishes when it runs the device sign-in. Must
+ * match SERVER_AUTH_OPTION in oceanumlab/__init__.py.
+ */
+export const SERVER_AUTH_OPTION = 'oceanumServerAuth';
+
+/** A sign-in waiting on the user: the code to confirm, and where to confirm it. */
+export interface IPendingSignIn {
+  readonly userCode: string;
+  readonly verificationUri: string;
+  /** The verification page with the code already filled in. */
+  readonly verificationUriComplete: string;
+  /** Seconds until the code lapses. */
+  readonly expiresIn: number;
+}
+
+interface IServerStatus {
+  state: 'signedOut' | 'pending' | 'signedIn';
+  claims: Record<string, unknown> | null;
+  pending: IPendingSignIn | null;
+  error: string | null;
+  accessToken?: string | null;
+}
+
+/** One exchange with the server extension's `/oceanum/auth/<action>` handler. */
+export type AuthRequest = (
+  action: 'status' | 'token' | 'start' | 'cancel' | 'signout',
+  method: 'GET' | 'POST'
+) => Promise<unknown>;
+
+function httpUrl(value: unknown): string | null {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return null;
+  }
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' || url.protocol === 'http:'
+      ? url.href.replace(/\/+$/, '')
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The Oceanum deployment the server signs in to, from the page option, or `null` when the
+ * server offers no device sign-in (or the option is malformed, which is treated the same).
+ */
+export function readServerAuthOption(
+  option: string | undefined,
+  hostname: string
+): IOceanumEnvironment | null {
+  if (!option) {
+    return null;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(option);
+  } catch {
+    return null;
+  }
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return null;
+  }
+  const config = raw as Record<string, unknown>;
+  const urlsIn = (config.urls ?? {}) as Record<string, unknown>;
+  const datamesh = httpUrl(urlsIn.datamesh);
+  const specs = httpUrl(urlsIn.specs);
+  const manage = httpUrl(urlsIn.manage);
+  if (
+    typeof config.auth0Domain !== 'string' ||
+    typeof config.clientId !== 'string' ||
+    !datamesh ||
+    !specs ||
+    !manage
+  ) {
+    return null;
+  }
+  const urls: IOceanumServiceUrls = {
+    datamesh,
+    specs,
+    manage,
+    ...(httpUrl(urlsIn.datameshUi)
+      ? { datameshUi: httpUrl(urlsIn.datameshUi) as string }
+      : {}),
+    ...(httpUrl(urlsIn.ai) ? { ai: httpUrl(urlsIn.ai) as string } : {})
+  };
+  return {
+    // The device grant is indifferent to where the page is served from, so this is simply
+    // wherever that is, rather than a list to match against.
+    hosts: [hostname.toLowerCase()],
+    auth0Domain: config.auth0Domain,
+    clientId: config.clientId,
+    oceanumDomain:
+      typeof config.oceanumDomain === 'string' ? config.oceanumDomain : '',
+    signInRedirect: false,
+    urls
+  };
+}
+
+export interface IServerAuthOptions {
+  /** The deployment the server signs in to, or `null` when it offers no sign-in. */
+  environment: IOceanumEnvironment | null;
+  request: AuthRequest;
+  /** Called when a session ends other than by `signOut()`. */
+  onSessionEnded?: (message: string) => void;
+  /** How often to ask the server whether a pending sign-in has completed. */
+  pendingPollMs?: number;
+  /** How often to pick up a refreshed access token while signed in. */
+  tokenPollMs?: number;
+}
+
+export class ServerAuth implements IOceanumAuth, IDisposable {
+  constructor(options: IServerAuthOptions) {
+    this.environment = options.environment;
+    this._request = options.request;
+    this._onSessionEnded = options.onSessionEnded;
+    this._pendingPollMs = options.pendingPollMs ?? 2000;
+    this._tokenPollMs = options.tokenPollMs ?? 60000;
+    if (!this.environment) {
+      this._ready.resolve();
+      return;
+    }
+    // A server that signed in before this page loaded (a reload, a second tab) is already
+    // signed in; `ready` waits for that answer so nothing downstream sees a false sign-out.
+    void this._sync('token').finally(() => this._ready.resolve());
+  }
+
+  readonly environment: IOceanumEnvironment | null;
+
+  get urls(): IOceanumServiceUrls | null {
+    return this.environment?.urls ?? null;
+  }
+
+  get ready(): Promise<void> {
+    return this._ready.promise;
+  }
+
+  get user(): IOceanumUser | null {
+    return this._user;
+  }
+
+  get userChanged(): ISignal<IOceanumAuth, IOceanumUser | null> {
+    return this._userChanged;
+  }
+
+  get tokenChanged(): ISignal<IOceanumAuth, string | null> {
+    return this._tokenChanged;
+  }
+
+  /** The sign-in waiting on the user, if any. */
+  get pending(): IPendingSignIn | null {
+    return this._pending;
+  }
+
+  /** Why the last sign-in attempt ended, if it failed. */
+  get error(): string | null {
+    return this._error;
+  }
+
+  /** Emits when `pending` or `error` changes. */
+  get stateChanged(): ISignal<ServerAuth, void> {
+    return this._stateChanged;
+  }
+
+  async signIn(): Promise<void> {
+    if (!this.environment || this._user) {
+      return;
+    }
+    await this._sync('start', 'POST');
+  }
+
+  /** Abandon a sign-in that is waiting on the user. */
+  async cancelSignIn(): Promise<void> {
+    if (this._pending) {
+      await this._sync('cancel', 'POST');
+    }
+  }
+
+  async signOut(): Promise<void> {
+    this._signingOut = true;
+    try {
+      await this._sync('signout', 'POST');
+    } finally {
+      this._signingOut = false;
+    }
+  }
+
+  async getAccessToken(): Promise<string | null> {
+    if (!this.environment || !this._user) {
+      return null;
+    }
+    await this._sync('token');
+    return this._token;
+  }
+
+  /** Re-read the server's state, e.g. when the tab becomes visible again. */
+  async refresh(): Promise<void> {
+    if (this.environment) {
+      await this._sync(this._user ? 'token' : 'status');
+    }
+  }
+
+  get isDisposed(): boolean {
+    return this._disposed;
+  }
+
+  dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+    this._disposed = true;
+    this._clearTimer();
+    Signal.clearData(this);
+  }
+
+  private async _sync(
+    action: 'status' | 'token' | 'start' | 'cancel' | 'signout',
+    method: 'GET' | 'POST' = 'GET'
+  ): Promise<void> {
+    let status: IServerStatus;
+    try {
+      status = (await this._request(action, method)) as IServerStatus;
+    } catch (reason) {
+      // The Jupyter server being briefly unreachable is not a sign-out: keep what we have
+      // and let the next poll find out.
+      console.warn(`Oceanum.io sign-in: ${action} failed`, reason);
+      this._schedule();
+      return;
+    }
+    if (this._disposed || !status || typeof status.state !== 'string') {
+      return;
+    }
+    this._apply(status);
+    if (status.state === 'signedIn' && action !== 'token') {
+      // A sign-in that has just completed: fetch the token it produced.
+      await this._sync('token');
+    }
+  }
+
+  private _apply(status: IServerStatus): void {
+    const user =
+      status.state === 'signedIn' ? userFromClaims(status.claims) : null;
+    const pending = status.state === 'pending' ? status.pending : null;
+    const error = status.error ?? null;
+
+    if (
+      pending?.userCode !== this._pending?.userCode ||
+      error !== this._error
+    ) {
+      this._pending = pending;
+      this._error = error;
+      this._stateChanged.emit();
+    }
+
+    const wasSignedIn = this._user !== null;
+    if ((user?.sub ?? null) !== (this._user?.sub ?? null)) {
+      this._user = user;
+      this._userChanged.emit(user);
+      if (wasSignedIn && !user && !this._signingOut) {
+        this._onSessionEnded?.(
+          error ?? 'Your Oceanum.io session has ended. Sign in again.'
+        );
+      }
+    }
+
+    const token = user ? (status.accessToken ?? this._token) : null;
+    if (token !== this._token) {
+      this._token = token;
+      this._tokenChanged.emit(token);
+    }
+    this._schedule();
+  }
+
+  /** Poll quickly while a sign-in is pending, slowly while signed in, not at all otherwise. */
+  private _schedule(): void {
+    this._clearTimer();
+    if (this._disposed) {
+      return;
+    }
+    if (this._pending) {
+      this._timer = setTimeout(
+        () => void this._sync('status'),
+        this._pendingPollMs
+      );
+    } else if (this._user) {
+      this._timer = setTimeout(
+        () => void this._sync('token'),
+        this._tokenPollMs
+      );
+    }
+  }
+
+  private _clearTimer(): void {
+    if (this._timer !== null) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+
+  private _request: AuthRequest;
+  private _onSessionEnded: ((message: string) => void) | undefined;
+  private _pendingPollMs: number;
+  private _tokenPollMs: number;
+  private _ready = new PromiseDelegate<void>();
+  private _user: IOceanumUser | null = null;
+  private _token: string | null = null;
+  private _pending: IPendingSignIn | null = null;
+  private _error: string | null = null;
+  private _signingOut = false;
+  private _disposed = false;
+  private _timer: ReturnType<typeof setTimeout> | null = null;
+  private _userChanged = new Signal<IOceanumAuth, IOceanumUser | null>(this);
+  private _tokenChanged = new Signal<IOceanumAuth, string | null>(this);
+  private _stateChanged = new Signal<ServerAuth, void>(this);
+}