@oceanum/oceanumlab 4.7.0 → 4.7.2

package/lib/share/client.js

@@ -0,0 +1,205 @@
+import { isSpecId } from './notebook';
+const MESSAGES = {
+    'signed-out': 'Sign in to Oceanum.io to continue.',
+    expired: 'Your Oceanum session has expired, sign in again.',
+    forbidden: 'You have no access to this notebook. It may not exist, or was created under another organisation.',
+    'not-found': 'This notebook no longer exists on Oceanum.io.',
+    'too-large': 'The notebook is too large for Oceanum.io (32 MiB limit).',
+    network: 'Could not reach Oceanum.io. Check your connection; very large notebooks can also fail this way.',
+    invalid: 'Oceanum.io returned an unexpected response.',
+    unsupported: 'This Oceanum.io service does not offer that operation yet.'
+};
+/** A spec store failure with a message that is safe to show to the user. */
+export class SpecStoreError extends Error {
+    constructor(kind, status = null) {
+        super(kind === 'server'
+            ? `Oceanum.io returned an error (HTTP ${status}).`
+            : MESSAGES[kind]);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'SpecStoreError';
+    }
+}
+/** Map a failed HTTP status to an error. */
+export function errorForStatus(status) {
+    switch (status) {
+        // The spec store's authentication middleware answers a bad or expired token with 400.
+        case 400:
+            return new SpecStoreError('expired', status);
+        // Casbin answers 403 both for no access and for a record that does not exist.
+        case 403:
+            return new SpecStoreError('forbidden', status);
+        case 404:
+            return new SpecStoreError('not-found', status);
+        case 405:
+            // The route is there but not this method: a store from before it had PATCH.
+            return new SpecStoreError('unsupported', status);
+        case 413:
+            return new SpecStoreError('too-large', status);
+        default:
+            return new SpecStoreError('server', status);
+    }
+}
+function isSummary(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    return (isSpecId(v.id) &&
+        typeof v.name === 'string' &&
+        typeof v.modified === 'string');
+}
+function isRecord(value) {
+    return isSummary(value) && 'spec' in value;
+}
+/** Client for the `notebook` spec type of the Oceanum spec store. */
+export class SpecStoreClient {
+    constructor(options) {
+        var _a;
+        this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/notebook`;
+        this._getAccessToken = options.getAccessToken;
+        this._fetch = (_a = options.fetch) !== null && _a !== void 0 ? _a : ((input, init) => fetch(input, init));
+    }
+    /** Every notebook the user may read, including public ones. */
+    async list() {
+        const data = await this._request('GET', this._base, { auth: 'required' });
+        if (!Array.isArray(data) || !data.every(isSummary)) {
+            throw new SpecStoreError('invalid');
+        }
+        return data;
+    }
+    /** Read a record, anonymously when signed out. */
+    async get(id) {
+        return this._record(await this._request('GET', this._url(id), { auth: 'optional' }));
+    }
+    /** Create a record. The server mints the id: use the returned record's. */
+    async create(body) {
+        return this._record(await this._request('POST', this._base, {
+            auth: 'required',
+            body: pick(body)
+        }));
+    }
+    /** Replace a record's name, description and notebook. */
+    async update(id, body) {
+        return this._record(await this._request('PUT', this._url(id), {
+            auth: 'required',
+            body: pick(body)
+        }));
+    }
+    /**
+     * Change some of a record's fields and leave the rest as they are. Needs the same
+     * write access as `update`, which the store enforces a patch as.
+     */
+    async patch(id, changes) {
+        if (Object.keys(changes).length === 0) {
+            // The store answers an empty patch with 400; there is nothing to send anyway.
+            throw new SpecStoreError('invalid');
+        }
+        return this._record(await this._request('PATCH', this._url(id), {
+            auth: 'required',
+            body: changes
+        }));
+    }
+    /**
+     * Give a record a new name, without sending the notebook back with it.
+     *
+     * Falls back to reading the record and putting it back where the store has no PATCH
+     * (production had none when this was written). That fallback races another writer's
+     * change to the notebook, which is the whole reason to prefer a patch.
+     */
+    async rename(id, name) {
+        try {
+            return await this.patch(id, { name });
+        }
+        catch (error) {
+            if (!(error instanceof SpecStoreError) || error.kind !== 'unsupported') {
+                throw error;
+            }
+            const record = await this.get(id);
+            return this.update(id, {
+                name,
+                description: record.description,
+                spec: record.spec
+            });
+        }
+    }
+    /** Delete a record (requires admin access to it). */
+    async remove(id) {
+        await this._request('DELETE', this._url(id), { auth: 'required' });
+    }
+    /** Grant a permission on a record (requires admin access to it). */
+    async addPermission(id, grant) {
+        await this._request('POST', `${this._url(id)}/permissions`, {
+            auth: 'required',
+            body: {
+                type: grant.type,
+                entity: grant.entity,
+                permission: grant.permission
+            }
+        });
+    }
+    /**
+     * Remove a permission (requires admin access). The server matches the exact grant and
+     * answers 404 when there is no such permission.
+     */
+    async removePermission(id, grant) {
+        await this._request('DELETE', `${this._url(id)}/permissions`, {
+            auth: 'required',
+            body: {
+                type: grant.type,
+                entity: grant.entity,
+                permission: grant.permission
+            }
+        });
+    }
+    _url(id) {
+        if (!isSpecId(id)) {
+            throw new SpecStoreError('invalid');
+        }
+        return `${this._base}/${id}`;
+    }
+    _record(data) {
+        if (!isRecord(data)) {
+            throw new SpecStoreError('invalid');
+        }
+        return data;
+    }
+    async _request(method, url, options) {
+        const token = await this._getAccessToken();
+        if (token === null && options.auth === 'required') {
+            throw new SpecStoreError('signed-out');
+        }
+        const headers = {};
+        if (token !== null) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+        const init = { method, headers };
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(options.body);
+        }
+        let response;
+        try {
+            response = await this._fetch(url, init);
+        }
+        catch (_a) {
+            throw new SpecStoreError('network');
+        }
+        if (!response.ok) {
+            throw errorForStatus(response.status);
+        }
+        if (response.status === 204) {
+            return null;
+        }
+        try {
+            return await response.json();
+        }
+        catch (_b) {
+            throw new SpecStoreError('invalid');
+        }
+    }
+}
+/** Only the fields the server accepts; in particular never send an `id`. */
+function pick(body) {
+    return { name: body.name, description: body.description, spec: body.spec };
+}

package/lib/share/events.d.ts

@@ -0,0 +1,7 @@
+import { Signal } from '@lumino/signaling';
+/**
+ * Emits after this extension creates, renames or deletes a notebook record, so the
+ * Notebooks tab can list again. A plain module-level signal: the tab and the commands
+ * live in different plugins, and the change is the only thing they need to share.
+ */
+export declare const notebooksChanged: Signal<object, void>;

package/lib/share/events.js

@@ -0,0 +1,9 @@
+import { Signal } from '@lumino/signaling';
+/**
+ * Emits after this extension creates, renames or deletes a notebook record, so the
+ * Notebooks tab can list again. A plain module-level signal: the tab and the commands
+ * live in different plugins, and the change is the only thing they need to share.
+ */
+// The sender is a throwaway object, not null: Lumino keys its receivers by sender in a
+// WeakMap, which refuses null.
+export const notebooksChanged = new Signal({});

package/lib/share/notebook.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Notebook records in the Oceanum spec store: the link a local notebook keeps to its
+ * record, the body that is stored, and the names, paths and addresses around them.
+ *
+ * Ported from oceanum-notebook's share-oceanum package, which notebook.oceanum.io will
+ * drop in favour of this one.
+ */
+import type { INotebookContent } from '@jupyterlab/nbformat';
+/** Notebook metadata key linking a local notebook to its spec store record. */
+export declare const METADATA_KEY = "oceanum";
+/** Folder that notebooks opened from Oceanum.io are written to. */
+export declare const OCEANUM_DIR = "Oceanum";
+/** Query parameter carrying a shared notebook id. */
+export declare const QUERY_PARAM = "oceanum-notebook";
+/**
+ * Largest request body we send. Cloud Run rejects requests over 32 MiB; keep a margin
+ * for headers and the server's own encoding.
+ */
+export declare const MAX_BODY_BYTES: number;
+/** The `oceanum` notebook metadata value. */
+export interface IOceanumLink {
+    spec_id: string;
+    /** Spec store the id belongs to, so a development id is never PUT to production. */
+    specs_url: string;
+    description?: string;
+}
+/** A spec store request body for `POST`/`PUT /specs/notebook`. */
+export interface ISpecBody {
+    name: string;
+    description: string | null;
+    spec: INotebookContent;
+}
+/**
+ * The fields a `PATCH /specs/notebook/{id}` may change. A field left out keeps its
+ * stored value, so a rename need not send the notebook back.
+ *
+ * The store refuses anything else outright rather than ignoring it, and refuses a patch
+ * that carries no field at all, so never send an empty one. `spec` is replaced whole:
+ * there is no way to change one key of a stored notebook.
+ */
+export interface ISpecPatch {
+    name?: string;
+    description?: string | null;
+    spec?: INotebookContent;
+}
+/** A spec store list entry (the list omits `spec`). */
+export interface ISpecSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    /**
+     * When the record was created, or last patched. A `PUT` does not touch it, so for a
+     * record nothing has patched this is still a creation time.
+     */
+    modified: string;
+    /** Null unless the caller created the record: the store hides other creators. */
+    creator: string | null;
+}
+/** A full spec store record. */
+export interface ISpecRecord extends ISpecSummary {
+    spec: unknown;
+}
+export type BuildResult = {
+    ok: true;
+    body: ISpecBody;
+    bytes: number;
+    strippedOutputs: boolean;
+} | {
+    ok: false;
+    bytes: number;
+};
+/** Whether `value` is a UUID, and so safe to put in a spec store URL. */
+export declare function isSpecId(value: unknown): value is string;
+/**
+ * Read the link from an `oceanum` metadata value, or `null` if it is missing, malformed,
+ * or belongs to a different spec store.
+ */
+export declare function readLink(value: unknown, specsUrl: string): IOceanumLink | null;
+/** The notebook name stored on Oceanum.io for a local path. */
+export declare function nameFromPath(path: string): string;
+/**
+ * The notebook with every cell's `trusted` metadata removed.
+ *
+ * JupyterLab trusts a cell whose metadata says `trusted: true` and then renders its HTML
+ * and Markdown unsanitised, running any script in them. A notebook from the spec store
+ * (anyone with write access can edit a record) must arrive untrusted; its outputs
+ * become trusted again when the reader re-runs the cells.
+ */
+export declare function withoutTrust(content: INotebookContent): INotebookContent;
+/**
+ * Build the spec store body for a notebook. The `oceanum` link is not stored in the
+ * record. If the body is over `maxBytes`, code-cell outputs and execution counts are
+ * dropped; if it is still too large, the result is not ok.
+ */
+export declare function buildSpecBody(content: INotebookContent, path: string, specsUrl: string, maxBytes?: number): BuildResult;
+/**
+ * The notebook stored in a record, with its `oceanum` link set. Throws if the record
+ * does not hold an nbformat 4 notebook.
+ */
+export declare function notebookFromRecord(record: ISpecRecord, specsUrl: string): INotebookContent;
+/** Make a record name safe to use as a single path segment. */
+export declare function sanitizeName(name: string): string;
+/**
+ * A path `Oceanum/<name>.ipynb` that does not collide with `existing` (file names in the
+ * `Oceanum` folder), appending ` (1)`, ` (2)`, ... as needed.
+ */
+export declare function uniqueNotebookPath(name: string, existing: Iterable<string>): string;
+/**
+ * The names in `existing` that `uniqueNotebookPath` could have given a record called
+ * `name`, in the order it would have tried them: `<base>.ipynb`, then `<base> (1).ipynb`,
+ * `<base> (2).ipynb` and so on.
+ *
+ * Opening a record looks through these for the copy a previous session left, so the same
+ * record keeps one local file. Without that the second copy is named `<base> (1)`, and
+ * since a record takes its name from the file on every save, opening a notebook twice
+ * would quietly rename it on Oceanum.
+ */
+export declare function notebookNamesFor(name: string, existing: Iterable<string>): string[];
+/**
+ * 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 declare function partitionSummaries(items: readonly ISpecSummary[], email: string | null): {
+    mine: ISpecSummary[];
+    shared: ISpecSummary[];
+};
+/** Parse a spec store timestamp, which is UTC but usually has no zone designator. */
+export declare function parseTimestamp(value: string): Date | null;
+/**
+ * Whether `email` can be granted access. Glob characters are refused: the server
+ * matches user entities as globs.
+ */
+export declare function isShareableEmail(email: string): boolean;
+/** Addresses typed into the share dialog, split into the ones we can grant and the rest. */
+export interface IParsedShareEmails {
+    /** Valid, lower-cased and de-duplicated, in the order first written. */
+    emails: string[];
+    /** Everything that is not a shareable address, as written, for reporting back. */
+    invalid: string[];
+}
+/**
+ * Split what the user typed into individual addresses. Commas, semicolons and any
+ * whitespace all separate, so one-per-line and a comma-separated list both work.
+ *
+ * Bare addresses only: a mail client's "To:" line carries display names, and
+ * `"Alice B" <alice@example.com>` splits into tokens that are not addresses. Those
+ * come back in `invalid` so the user is told, rather than being silently dropped.
+ *
+ * Addresses are lower-cased because the spec store matches the user entity as a
+ * case-sensitive glob against the Auth0 email claim, which Auth0 stores lower case.
+ */
+export declare function parseShareEmails(raw: string): IParsedShareEmails;
+/**
+ * How to report share failures.
+ *
+ * `original` means hand the underlying error to the reporter untouched — it holds the
+ * only explanation the user gets, and the reporter reads its type to decide whether to
+ * offer sign-in. `partial` is only for the case the original error cannot describe on
+ * its own: some addresses worked and some did not, so the message has to name them.
+ */
+export type ShareReport = {
+    kind: 'original';
+} | {
+    kind: 'partial';
+    named: string[];
+};
+/**
+ * Decide how to report a set of failed grants.
+ *
+ * `entities` are the failed grants' entities, in order; the public grant's entity is
+ * the empty string, which names nobody.
+ */
+export declare function reportForShareFailures(grantCount: number, entities: readonly string[], needsSignIn: boolean): ShareReport;
+/**
+ * The link that opens a shared notebook in this deployment.
+ *
+ * JupyterLite is static files, so its page is `lab/index.html`; a JupyterLab server
+ * serves the application at `lab` and has no `index.html` to route.
+ */
+export declare function shareLink(baseUrl: string, pageHref: string, id: string): string;

package/lib/share/notebook.js

@@ -0,0 +1,277 @@
+/** Notebook metadata key linking a local notebook to its spec store record. */
+export const METADATA_KEY = 'oceanum';
+/** Folder that notebooks opened from Oceanum.io are written to. */
+export const OCEANUM_DIR = 'Oceanum';
+/** Query parameter carrying a shared notebook id. */
+export const QUERY_PARAM = 'oceanum-notebook';
+/**
+ * Largest request body we send. Cloud Run rejects requests over 32 MiB; keep a margin
+ * for headers and the server's own encoding.
+ */
+export const MAX_BODY_BYTES = 30 * 1024 * 1024;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Whether `value` is a UUID, and so safe to put in a spec store URL. */
+export function isSpecId(value) {
+    return typeof value === 'string' && UUID_RE.test(value);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Read the link from an `oceanum` metadata value, or `null` if it is missing, malformed,
+ * or belongs to a different spec store.
+ */
+export function readLink(value, specsUrl) {
+    if (!isObject(value) ||
+        !isSpecId(value.spec_id) ||
+        value.specs_url !== specsUrl) {
+        return null;
+    }
+    const link = { spec_id: value.spec_id, specs_url: specsUrl };
+    if (typeof value.description === 'string') {
+        link.description = value.description;
+    }
+    return link;
+}
+/** The notebook name stored on Oceanum.io for a local path. */
+export function nameFromPath(path) {
+    var _a;
+    const base = (_a = path.split('/').pop()) !== null && _a !== void 0 ? _a : '';
+    return base.replace(/\.ipynb$/i, '') || 'Untitled';
+}
+function byteLength(text) {
+    return new TextEncoder().encode(text).length;
+}
+function withoutLink(content) {
+    const metadata = { ...content.metadata };
+    delete metadata[METADATA_KEY];
+    return { ...content, metadata };
+}
+/**
+ * The notebook with every cell's `trusted` metadata removed.
+ *
+ * JupyterLab trusts a cell whose metadata says `trusted: true` and then renders its HTML
+ * and Markdown unsanitised, running any script in them. A notebook from the spec store
+ * (anyone with write access can edit a record) must arrive untrusted; its outputs
+ * become trusted again when the reader re-runs the cells.
+ */
+export function withoutTrust(content) {
+    const cells = content.cells.map(cell => {
+        if (!isObject(cell.metadata) || !('trusted' in cell.metadata)) {
+            return cell;
+        }
+        const metadata = { ...cell.metadata };
+        delete metadata.trusted;
+        return { ...cell, metadata };
+    });
+    return { ...content, cells };
+}
+function withoutOutputs(content) {
+    const cells = content.cells.map(cell => cell.cell_type === 'code'
+        ? { ...cell, outputs: [], execution_count: null }
+        : cell);
+    return { ...content, cells };
+}
+/**
+ * Build the spec store body for a notebook. The `oceanum` link is not stored in the
+ * record. If the body is over `maxBytes`, code-cell outputs and execution counts are
+ * dropped; if it is still too large, the result is not ok.
+ */
+export function buildSpecBody(content, path, specsUrl, maxBytes = MAX_BODY_BYTES) {
+    var _a;
+    const link = readLink((_a = content.metadata) === null || _a === void 0 ? void 0 : _a[METADATA_KEY], specsUrl);
+    const make = (spec) => {
+        var _a;
+        return ({
+            name: nameFromPath(path),
+            description: (_a = link === null || link === void 0 ? void 0 : link.description) !== null && _a !== void 0 ? _a : null,
+            spec
+        });
+    };
+    const full = make(withoutTrust(withoutLink(content)));
+    const fullBytes = byteLength(JSON.stringify(full));
+    if (fullBytes <= maxBytes) {
+        return { ok: true, body: full, bytes: fullBytes, strippedOutputs: false };
+    }
+    const stripped = make(withoutOutputs(full.spec));
+    const strippedBytes = byteLength(JSON.stringify(stripped));
+    if (strippedBytes <= maxBytes) {
+        return {
+            ok: true,
+            body: stripped,
+            bytes: strippedBytes,
+            strippedOutputs: true
+        };
+    }
+    return { ok: false, bytes: strippedBytes };
+}
+/**
+ * The notebook stored in a record, with its `oceanum` link set. Throws if the record
+ * does not hold an nbformat 4 notebook.
+ */
+export function notebookFromRecord(record, specsUrl) {
+    const spec = record.spec;
+    if (!isObject(spec) ||
+        spec.nbformat !== 4 ||
+        !Array.isArray(spec.cells) ||
+        !isObject(spec.metadata)) {
+        throw new Error('This Oceanum.io record is not a valid notebook.');
+    }
+    const link = { spec_id: record.id, specs_url: specsUrl };
+    if (record.description) {
+        link.description = record.description;
+    }
+    const content = withoutTrust(spec);
+    return {
+        ...content,
+        metadata: { ...content.metadata, [METADATA_KEY]: { ...link } }
+    };
+}
+/** Make a record name safe to use as a single path segment. */
+export function sanitizeName(name) {
+    const clean = name
+        .trim()
+        .replace(/\.ipynb$/i, '')
+        .replace(/[/\\]/g, '-')
+        .trim();
+    return clean === '' || clean === '.' || clean === '..' ? 'Untitled' : clean;
+}
+/**
+ * A path `Oceanum/<name>.ipynb` that does not collide with `existing` (file names in the
+ * `Oceanum` folder), appending ` (1)`, ` (2)`, ... as needed.
+ */
+export function uniqueNotebookPath(name, existing) {
+    const taken = new Set(existing);
+    const base = sanitizeName(name);
+    let candidate = `${base}.ipynb`;
+    for (let i = 1; taken.has(candidate); i++) {
+        candidate = `${base} (${i}).ipynb`;
+    }
+    return `${OCEANUM_DIR}/${candidate}`;
+}
+/**
+ * The names in `existing` that `uniqueNotebookPath` could have given a record called
+ * `name`, in the order it would have tried them: `<base>.ipynb`, then `<base> (1).ipynb`,
+ * `<base> (2).ipynb` and so on.
+ *
+ * Opening a record looks through these for the copy a previous session left, so the same
+ * record keeps one local file. Without that the second copy is named `<base> (1)`, and
+ * since a record takes its name from the file on every save, opening a notebook twice
+ * would quietly rename it on Oceanum.
+ */
+export function notebookNamesFor(name, existing) {
+    const base = sanitizeName(name);
+    const prefix = `${base} (`;
+    const suffix = ').ipynb';
+    const plain = [];
+    const numbered = [];
+    for (const candidate of existing) {
+        if (candidate === `${base}.ipynb`) {
+            plain.push(candidate);
+            continue;
+        }
+        if (!candidate.startsWith(prefix) || !candidate.endsWith(suffix)) {
+            continue;
+        }
+        const index = candidate.slice(prefix.length, candidate.length - suffix.length);
+        if (/^\d+$/.test(index)) {
+            numbered.push({ name: candidate, index: Number(index) });
+        }
+    }
+    numbered.sort((a, b) => a.index - b.index);
+    return [...plain, ...numbered.map(entry => entry.name)];
+}
+/**
+ * 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 partitionSummaries(items, email) {
+    var _a;
+    const me = (_a = email === null || email === void 0 ? void 0 : email.toLowerCase()) !== null && _a !== void 0 ? _a : null;
+    const sorted = [...items].sort((a, b) => b.modified.localeCompare(a.modified));
+    const isMine = (item) => { var _a; return me !== null && ((_a = item.creator) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === me; };
+    return {
+        mine: sorted.filter(isMine),
+        shared: sorted.filter(item => !isMine(item))
+    };
+}
+/** Parse a spec store timestamp, which is UTC but usually has no zone designator. */
+export function parseTimestamp(value) {
+    const zoned = /(Z|[+-]\d{2}:?\d{2})$/i.test(value) ? value : `${value}Z`;
+    const date = new Date(zoned);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+/**
+ * Whether `email` can be granted access. Glob characters are refused: the server
+ * matches user entities as globs.
+ */
+export function isShareableEmail(email) {
+    return /^[^\s@*?[\]]+@[^\s@*?[\]]+\.[^\s@*?[\]]+$/.test(email);
+}
+/**
+ * Split what the user typed into individual addresses. Commas, semicolons and any
+ * whitespace all separate, so one-per-line and a comma-separated list both work.
+ *
+ * Bare addresses only: a mail client's "To:" line carries display names, and
+ * `"Alice B" <alice@example.com>` splits into tokens that are not addresses. Those
+ * come back in `invalid` so the user is told, rather than being silently dropped.
+ *
+ * Addresses are lower-cased because the spec store matches the user entity as a
+ * case-sensitive glob against the Auth0 email claim, which Auth0 stores lower case.
+ */
+export function parseShareEmails(raw) {
+    const emails = [];
+    const invalid = [];
+    const seen = new Set();
+    for (const part of raw.split(/[\s,;]+/)) {
+        const entry = part.trim();
+        if (entry === '') {
+            continue;
+        }
+        const email = entry.toLowerCase();
+        if (!isShareableEmail(email)) {
+            // Report it as written, so the user recognises what they typed.
+            invalid.push(entry);
+            continue;
+        }
+        if (!seen.has(email)) {
+            seen.add(email);
+            emails.push(email);
+        }
+    }
+    return { emails, invalid };
+}
+/**
+ * Decide how to report a set of failed grants.
+ *
+ * `entities` are the failed grants' entities, in order; the public grant's entity is
+ * the empty string, which names nobody.
+ */
+export function reportForShareFailures(grantCount, entities, needsSignIn) {
+    const named = entities.filter(entity => entity !== '');
+    // A sign-in problem must reach the reporter as the original error or the user is
+    // never offered a way back in; an unnamed or total failure has nothing extra worth
+    // saying.
+    if (needsSignIn || named.length === 0 || entities.length >= grantCount) {
+        return { kind: 'original' };
+    }
+    return { kind: 'partial', named };
+}
+/**
+ * The link that opens a shared notebook in this deployment.
+ *
+ * JupyterLite is static files, so its page is `lab/index.html`; a JupyterLab server
+ * serves the application at `lab` and has no `index.html` to route.
+ */
+export function shareLink(baseUrl, pageHref, id) {
+    const app = new URL(pageHref).pathname.endsWith('/index.html')
+        ? 'lab/index.html'
+        : 'lab';
+    const url = new URL(app, new URL(baseUrl, pageHref));
+    url.searchParams.set(QUERY_PARAM, id);
+    return url.toString();
+}