@oceanum/oceanumlab 4.7.0 → 4.7.2

package/lib/auth/accountWidget.js

@@ -0,0 +1,95 @@
+import { Menu, Widget } from '@lumino/widgets';
+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'
+};
+/**
+ * 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, commands) {
+        super({ node: document.createElement('button') });
+        this._onClick = () => {
+            if (!this._auth.user) {
+                void this._commands.execute(CommandIDs.signIn);
+                return;
+            }
+            const rect = this.node.getBoundingClientRect();
+            this._menu.open(rect.left, rect.bottom);
+        };
+        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() {
+        if (this.isDisposed) {
+            return;
+        }
+        this.node.removeEventListener('click', this._onClick);
+        this._menu.dispose();
+        super.dispose();
+    }
+    _render() {
+        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);
+    }
+}
+/**
+ * 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) {
+        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/lib/auth/claims.d.ts

@@ -0,0 +1,3 @@
+import { IOceanumUser } from './tokens';
+/** Build the user from Auth0 ID token claims; `null` if the claims lack an identity. */
+export declare function userFromClaims(claims: Record<string, unknown> | null | undefined): IOceanumUser | null;

package/lib/auth/claims.js

@@ -0,0 +1,25 @@
+const CLAIM = 'https://oceanum.io/';
+const COLOR_SCHEMES = ['light', 'dark', 'auto'];
+/** Build the user from Auth0 ID token claims; `null` if the claims lack an identity. */
+export function userFromClaims(claims) {
+    var _a;
+    if (!claims) {
+        return null;
+    }
+    const str = (value) => typeof value === 'string' && value.length > 0 ? value : null;
+    const sub = str(claims.sub);
+    const email = (_a = str(claims.email)) !== null && _a !== void 0 ? _a : 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)
+            ? scheme
+            : null
+    };
+}

package/lib/auth/plugin.d.ts

@@ -0,0 +1,9 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+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 declare const DEVICE_AUTH_PLUGIN_ID = "@oceanum/oceanumlab:device-auth";
+export declare const deviceAuthPlugin: JupyterFrontEndPlugin<IOceanumAuth>;

package/lib/auth/plugin.js

@@ -0,0 +1,126 @@
+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 { 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) {
+    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) {
+    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 = () => {
+        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 = {
+    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, palette) => {
+        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)
+        });
+        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/lib/auth/serverAuth.d.ts

@@ -0,0 +1,79 @@
+import { IDisposable } from '@lumino/disposable';
+import { ISignal } from '@lumino/signaling';
+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 declare 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;
+}
+/** 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>;
+/**
+ * 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 declare function readServerAuthOption(option: string | undefined, hostname: string): IOceanumEnvironment | null;
+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 declare class ServerAuth implements IOceanumAuth, IDisposable {
+    constructor(options: IServerAuthOptions);
+    readonly environment: IOceanumEnvironment | null;
+    get urls(): IOceanumServiceUrls | null;
+    get ready(): Promise<void>;
+    get user(): IOceanumUser | null;
+    get userChanged(): ISignal<IOceanumAuth, IOceanumUser | null>;
+    get tokenChanged(): ISignal<IOceanumAuth, string | null>;
+    /** The sign-in waiting on the user, if any. */
+    get pending(): IPendingSignIn | null;
+    /** Why the last sign-in attempt ended, if it failed. */
+    get error(): string | null;
+    /** Emits when `pending` or `error` changes. */
+    get stateChanged(): ISignal<ServerAuth, void>;
+    signIn(): Promise<void>;
+    /** Abandon a sign-in that is waiting on the user. */
+    cancelSignIn(): Promise<void>;
+    signOut(): Promise<void>;
+    getAccessToken(): Promise<string | null>;
+    /** Re-read the server's state, e.g. when the tab becomes visible again. */
+    refresh(): Promise<void>;
+    get isDisposed(): boolean;
+    dispose(): void;
+    private _sync;
+    private _apply;
+    /** Poll quickly while a sign-in is pending, slowly while signed in, not at all otherwise. */
+    private _schedule;
+    private _clearTimer;
+    private _request;
+    private _onSessionEnded;
+    private _pendingPollMs;
+    private _tokenPollMs;
+    private _ready;
+    private _user;
+    private _token;
+    private _pending;
+    private _error;
+    private _signingOut;
+    private _disposed;
+    private _timer;
+    private _userChanged;
+    private _tokenChanged;
+    private _stateChanged;
+}

package/lib/auth/serverAuth.js

@@ -0,0 +1,254 @@
+/**
+ * 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 { Signal } from '@lumino/signaling';
+import { userFromClaims } from './claims';
+/**
+ * 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';
+function httpUrl(value) {
+    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 (_a) {
+        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, hostname) {
+    var _a;
+    if (!option) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(option);
+    }
+    catch (_b) {
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return null;
+    }
+    const config = raw;
+    const urlsIn = ((_a = config.urls) !== null && _a !== void 0 ? _a : {});
+    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 = {
+        datamesh,
+        specs,
+        manage,
+        ...(httpUrl(urlsIn.datameshUi)
+            ? { datameshUi: httpUrl(urlsIn.datameshUi) }
+            : {}),
+        ...(httpUrl(urlsIn.ai) ? { ai: httpUrl(urlsIn.ai) } : {})
+    };
+    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,
+        fileManagement: config.fileManagement === 'oceanum' ? 'oceanum' : 'local',
+        urls
+    };
+}
+export class ServerAuth {
+    constructor(options) {
+        var _a, _b;
+        this._ready = new PromiseDelegate();
+        this._user = null;
+        this._token = null;
+        this._pending = null;
+        this._error = null;
+        this._signingOut = false;
+        this._disposed = false;
+        this._timer = null;
+        this._userChanged = new Signal(this);
+        this._tokenChanged = new Signal(this);
+        this._stateChanged = new Signal(this);
+        this.environment = options.environment;
+        this._request = options.request;
+        this._onSessionEnded = options.onSessionEnded;
+        this._pendingPollMs = (_a = options.pendingPollMs) !== null && _a !== void 0 ? _a : 2000;
+        this._tokenPollMs = (_b = options.tokenPollMs) !== null && _b !== void 0 ? _b : 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());
+    }
+    get urls() {
+        var _a, _b;
+        return (_b = (_a = this.environment) === null || _a === void 0 ? void 0 : _a.urls) !== null && _b !== void 0 ? _b : null;
+    }
+    get ready() {
+        return this._ready.promise;
+    }
+    get user() {
+        return this._user;
+    }
+    get userChanged() {
+        return this._userChanged;
+    }
+    get tokenChanged() {
+        return this._tokenChanged;
+    }
+    /** The sign-in waiting on the user, if any. */
+    get pending() {
+        return this._pending;
+    }
+    /** Why the last sign-in attempt ended, if it failed. */
+    get error() {
+        return this._error;
+    }
+    /** Emits when `pending` or `error` changes. */
+    get stateChanged() {
+        return this._stateChanged;
+    }
+    async signIn() {
+        if (!this.environment || this._user) {
+            return;
+        }
+        await this._sync('start', 'POST');
+    }
+    /** Abandon a sign-in that is waiting on the user. */
+    async cancelSignIn() {
+        if (this._pending) {
+            await this._sync('cancel', 'POST');
+        }
+    }
+    async signOut() {
+        this._signingOut = true;
+        try {
+            await this._sync('signout', 'POST');
+        }
+        finally {
+            this._signingOut = false;
+        }
+    }
+    async getAccessToken() {
+        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() {
+        if (this.environment) {
+            await this._sync(this._user ? 'token' : 'status');
+        }
+    }
+    get isDisposed() {
+        return this._disposed;
+    }
+    dispose() {
+        if (this._disposed) {
+            return;
+        }
+        this._disposed = true;
+        this._clearTimer();
+        Signal.clearData(this);
+    }
+    async _sync(action, method = 'GET') {
+        let status;
+        try {
+            status = (await this._request(action, method));
+        }
+        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');
+        }
+    }
+    _apply(status) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const user = status.state === 'signedIn' ? userFromClaims(status.claims) : null;
+        const pending = status.state === 'pending' ? status.pending : null;
+        const error = (_a = status.error) !== null && _a !== void 0 ? _a : null;
+        if ((pending === null || pending === void 0 ? void 0 : pending.userCode) !== ((_b = this._pending) === null || _b === void 0 ? void 0 : _b.userCode) ||
+            error !== this._error) {
+            this._pending = pending;
+            this._error = error;
+            this._stateChanged.emit();
+        }
+        const wasSignedIn = this._user !== null;
+        if (((_c = user === null || user === void 0 ? void 0 : user.sub) !== null && _c !== void 0 ? _c : null) !== ((_e = (_d = this._user) === null || _d === void 0 ? void 0 : _d.sub) !== null && _e !== void 0 ? _e : null)) {
+            this._user = user;
+            this._userChanged.emit(user);
+            if (wasSignedIn && !user && !this._signingOut) {
+                (_f = this._onSessionEnded) === null || _f === void 0 ? void 0 : _f.call(this, error !== null && error !== void 0 ? error : 'Your Oceanum.io session has ended. Sign in again.');
+            }
+        }
+        const token = user ? ((_g = status.accessToken) !== null && _g !== void 0 ? _g : 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. */
+    _schedule() {
+        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);
+        }
+    }
+    _clearTimer() {
+        if (this._timer !== null) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+    }
+}

package/lib/auth/startSignIn.d.ts

@@ -0,0 +1,11 @@
+import type { CommandRegistry } from '@lumino/commands';
+import type { IOceanumAuth } from './tokens';
+/**
+ * Start signing in the way this host shows it.
+ *
+ * On a JupyterLab server the device sign-in command both starts the flow and shows the
+ * code dialog; `auth.signIn()` alone starts the flow and shows nothing, so the user is
+ * left with a "Signing in…" top bar and no code. notebook.oceanum.io disables that
+ * command and provides an auth whose `signIn()` opens the Oceanum sign-in itself.
+ */
+export declare function startSignIn(commands: CommandRegistry, auth: IOceanumAuth): Promise<void>;

package/lib/auth/startSignIn.js

@@ -0,0 +1,16 @@
+import { CommandIDs } from './accountWidget';
+/**
+ * Start signing in the way this host shows it.
+ *
+ * On a JupyterLab server the device sign-in command both starts the flow and shows the
+ * code dialog; `auth.signIn()` alone starts the flow and shows nothing, so the user is
+ * left with a "Signing in…" top bar and no code. notebook.oceanum.io disables that
+ * command and provides an auth whose `signIn()` opens the Oceanum sign-in itself.
+ */
+export async function startSignIn(commands, auth) {
+    if (commands.hasCommand(CommandIDs.signIn)) {
+        await commands.execute(CommandIDs.signIn);
+        return;
+    }
+    await auth.signIn();
+}