@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/pluggableElementTypes/models/InternetAccountModel.d.ts

@@ -1,61 +1,161 @@
-import type React from 'react';
 import { RemoteFileWithRangeCache } from '../../util/io/index.ts';
-import type { AnyReactComponentType, UriLocation } from '../../util/types/index.ts';
+import type { UriLocation } from '../../util/types/index.ts';
 import type { Instance } from '@jbrowse/mobx-state-tree';
+import type React from 'react';
+/**
+ * #stateModel BaseInternetAccountModel
+ * #category internetAccount
+ */
 export declare const InternetAccount: import("@jbrowse/mobx-state-tree").IModelType<{
+    /**
+     * #property
+     */
     id: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ISimpleType<string>, [undefined]>;
+    /**
+     * #property
+     */
     type: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    configuration: import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
-        name: {
-            description: string;
-            type: string;
-            defaultValue: string;
+    /**
+     * #property
+     */
+    configuration: import("../../configuration/configurationSchema.ts").IConfigurationReference<import("../../configuration/configurationSchema.ts").ConfigurationSchemaType<{
+        readonly name: {
+            readonly description: "descriptive name of the internet account";
+            readonly type: "string";
+            readonly defaultValue: "";
         };
-        description: {
-            description: string;
-            type: string;
-            defaultValue: string;
+        readonly description: {
+            readonly description: "a description of the internet account";
+            readonly type: "string";
+            readonly defaultValue: "";
         };
-        authHeader: {
-            description: string;
-            type: string;
-            defaultValue: string;
+        readonly authHeader: {
+            readonly description: "request header for credentials";
+            readonly type: "string";
+            readonly defaultValue: "Authorization";
         };
-        tokenType: {
-            description: string;
-            type: string;
-            defaultValue: string;
+        readonly tokenType: {
+            readonly description: "a custom name for a token to include in the header";
+            readonly type: "string";
+            readonly defaultValue: "";
         };
-        domains: {
-            description: string;
-            type: string;
-            defaultValue: never[];
+        readonly domains: {
+            readonly description: "array of valid domains the url can contain to use this account";
+            readonly type: "stringArray";
+            readonly defaultValue: readonly [];
         };
-    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "internetAccountId">>;
+    }, import("../../configuration/configurationSchema.ts").ConfigurationSchemaOptions<undefined, "internetAccountId">>>;
 }, {
+    /**
+     * #getter
+     */
     readonly name: string;
+    /**
+     * #getter
+     */
     readonly description: string;
+    /**
+     * #getter
+     */
     readonly internetAccountId: string;
+    /**
+     * #getter
+     */
     readonly authHeader: string;
+    /**
+     * #getter
+     */
     readonly tokenType: string;
+    /**
+     * #getter
+     */
     readonly domains: string[];
+    /**
+     * #getter
+     * Can use this to customize what is displayed in fileSelector's toggle box
+     */
     readonly toggleContents: React.ReactNode;
-    readonly SelectorComponent: AnyReactComponentType | undefined;
+    /**
+     * #getter
+     * Can use this to add a label to the UrlChooser
+     */
     readonly selectorLabel: string | undefined;
+    /**
+     * #getter
+     * Whether the fileSelector offers this account as a source to pick. Turn it
+     * off for an account that only ever matches by domain and has nothing of
+     * its own to enter — HTTP Basic, whose ephemeral per-origin accounts would
+     * otherwise pile up as toggles nobody asked for.
+     */
+    readonly showInFileSelector: boolean;
 } & {
+    /**
+     * #method
+     * Determine whether this internetAccount provides credentials for a URL
+     * @param location  - UriLocation of resource
+     * @returns true or false
+     */
     handlesLocation(location: UriLocation): boolean;
+    /**
+     * #getter
+     * The key used to store this internetAccount's token in sessionStorage
+     */
     readonly tokenKey: string;
 } & {
+    /**
+     * #action
+     * Must be implemented by a model extending or composing this one. Pass the
+     * user's token to `resolve`.
+     * @param resolve - Pass the token to this function
+     * @param reject - If there is an error getting the token, call this function
+     */
     getTokenFromUser(_resolve: (token: string) => void, _reject: (error: Error) => void): void;
+    /**
+     * #action
+     */
     storeToken(token: string): void;
-    removeToken(): void;
-    retrieveToken(): string | null;
+    /**
+     * #action
+     */
+    retrieveToken(): string | undefined;
+    /**
+     * #action
+     * This can be used by an internetAccount to validate a token works before
+     * it is used. This is run when preAuthorizationInformation is requested,
+     * so it can be used to check that a token is valid before sending it to a
+     * worker thread. It expects the token to be returned so that this action
+     * can also be used to generate a new token (e.g. by using a refresh token)
+     * if the original one was invalid. Should throw an error if a token is
+     * invalid.
+     *
+     * @param token - Auth token
+     * @param loc - UriLocation of the resource
+     * @returns - Valid auth token
+     */
     validateToken(token: string, _loc: UriLocation): Promise<string>;
 } & {
+    /**
+     * #action
+     * Clears the stored token. Also drops the in-memory cached promise so a
+     * subsequent `getToken` re-prompts / re-derives rather than handing back
+     * the token that was just invalidated.
+     */
+    removeToken(): void;
+    /**
+     * #action
+     * Try to get the token from the location pre-auth, from local storage,
+     * or from a previously cached promise. If token is not available, uses
+     * `getTokenFromUser`.
+     *
+     * @param location - UriLocation of the resource
+     * @returns A promise for the token
+     */
     getToken(location?: UriLocation): Promise<string>;
 } & {
+    /**
+     * #action
+     */
     addAuthHeaderToInit(init?: RequestInit, token?: string): {
-        headers: Headers;
         body?: BodyInit | null;
         cache?: RequestCache;
         credentials?: RequestCredentials;
@@ -69,17 +169,51 @@ export declare const InternetAccount: import("@jbrowse/mobx-state-tree").IModelT
         referrerPolicy?: ReferrerPolicy;
         signal?: AbortSignal | null;
         window?: null;
+        headers: Headers;
     };
+    /**
+     * #action
+     * Run a request with the current token and, only if it comes back 401, put
+     * the token through `validateToken` and run it exactly once more. This is
+     * how every account's fetcher reaches a resource.
+     *
+     * @param loc - UriLocation of the resource
+     * @param run - issues the request with a given token
+     */
+    fetchWithToken(loc: UriLocation | undefined, run: (token: string) => Promise<Response>): Promise<Response>;
+    /**
+     * #action
+     * Gets the token and returns it along with the information needed to
+     * create a new internetAccount.
+     *
+     * @param location - UriLocation of the resource
+     * @returns
+     */
     getPreAuthorizationInformation(location: UriLocation): Promise<{
         internetAccountType: string;
         authInfo: {
             token: string;
-            configuration: any;
+            configuration: import("@jbrowse/mobx-state-tree").ModelSnapshotType<Record<string, any>>;
         };
     }>;
 } & {
+    /**
+     * #action
+     * Get a fetch method that will add any needed authentication headers to
+     * the request before sending it. If location is provided, it will be
+     * checked to see if it includes a token in it pre-auth information.
+     *
+     * @param loc - UriLocation of the resource
+     * @returns A function that can be used to fetch
+     */
     getFetcher(loc?: UriLocation): (input: RequestInfo, init?: RequestInit) => Promise<Response>;
 } & {
+    /**
+     * #action
+     * Gets a filehandle that uses a fetch that adds auth headers
+     * @param location - UriLocation of the resource
+     * @returns A filehandle
+     */
     openLocation(location: UriLocation): RemoteFileWithRangeCache;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export type BaseInternetAccountStateModel = typeof InternetAccount;

package/esm/pluggableElementTypes/models/InternetAccountModel.js

@@ -1,73 +1,181 @@
 import { types } from '@jbrowse/mobx-state-tree';
-import { BaseInternetAccountConfig } from "./baseInternetAccountConfig.js";
-import { ConfigurationReference, getConf } from "../../configuration/index.js";
-import { RemoteFileWithRangeCache } from "../../util/io/index.js";
-import { ElementId } from "../../util/types/mst.js";
-const inWebWorker = typeof sessionStorage === 'undefined';
-function x() { }
+import { ConfigurationReference, getConf } from '../../configuration/index.js';
+import { RemoteFileWithRangeCache } from '../../util/io/index.js';
+import { isWebWorker } from '../../util/isWebWorker.js';
+import { sessionStorageGetItem, sessionStorageRemoveItem, sessionStorageSetItem, } from '../../util/sessionStorage.js';
+import { ElementId } from '../../util/types/mst.js';
+import { BaseInternetAccountConfig } from './baseInternetAccountConfig.js';
+import { uriMatchesDomains } from './uriMatchesDomains.js';
+/**
+ * #stateModel BaseInternetAccountModel
+ * #category internetAccount
+ */
 export const InternetAccount = types
     .model('InternetAccount', {
+    /**
+     * #property
+     */
     id: ElementId,
+    /**
+     * #property
+     */
     type: types.string,
+    /**
+     * #property
+     */
     configuration: ConfigurationReference(BaseInternetAccountConfig),
 })
     .views(self => ({
+    /**
+     * #getter
+     */
     get name() {
         return getConf(self, 'name');
     },
+    /**
+     * #getter
+     */
     get description() {
         return getConf(self, 'description');
     },
+    /**
+     * #getter
+     */
     get internetAccountId() {
-        return getConf(self, 'internetAccountId');
+        return getConf(self, 'internetAccountId'); // NOTE: this is the explicitIdentifier of the config schema
     },
+    /**
+     * #getter
+     */
     get authHeader() {
         return getConf(self, 'authHeader');
     },
+    /**
+     * #getter
+     */
     get tokenType() {
         return getConf(self, 'tokenType');
     },
+    /**
+     * #getter
+     */
     get domains() {
         return getConf(self, 'domains');
     },
+    /**
+     * #getter
+     * Can use this to customize what is displayed in fileSelector's toggle box
+     */
     get toggleContents() {
         return null;
     },
-    get SelectorComponent() {
-        return undefined;
-    },
+    /**
+     * #getter
+     * Can use this to add a label to the UrlChooser
+     */
     get selectorLabel() {
         return undefined;
     },
+    /**
+     * #getter
+     * Whether the fileSelector offers this account as a source to pick. Turn it
+     * off for an account that only ever matches by domain and has nothing of
+     * its own to enter — HTTP Basic, whose ephemeral per-origin accounts would
+     * otherwise pile up as toggles nobody asked for.
+     */
+    get showInFileSelector() {
+        return true;
+    },
 }))
     .views(self => ({
+    /**
+     * #method
+     * Determine whether this internetAccount provides credentials for a URL
+     * @param location  - UriLocation of resource
+     * @returns true or false
+     */
     handlesLocation(location) {
-        return self.domains.some(domain => location.uri.includes(domain));
+        return uriMatchesDomains(location.uri, self.domains);
     },
+    /**
+     * #getter
+     * The key used to store this internetAccount's token in sessionStorage
+     */
     get tokenKey() {
         return `${self.internetAccountId}-token`;
     },
 }))
     .actions(self => ({
+    /**
+     * #action
+     * Must be implemented by a model extending or composing this one. Pass the
+     * user's token to `resolve`.
+     * @param resolve - Pass the token to this function
+     * @param reject - If there is an error getting the token, call this function
+     */
     getTokenFromUser(_resolve, _reject) {
         throw new Error('getTokenFromUser must be implemented by extending model');
     },
+    /**
+     * #action
+     */
+    // Through the guarded helpers rather than `sessionStorage` directly: in the
+    // embedded products this runs on someone else's page, where reading the
+    // global at all throws if third-party storage is blocked. A token that
+    // cannot be cached costs one more auth prompt per tab; a throw here takes
+    // the auth flow down with it.
     storeToken(token) {
-        sessionStorage.setItem(self.tokenKey, token);
-    },
-    removeToken() {
-        sessionStorage.removeItem(self.tokenKey);
+        sessionStorageSetItem(self.tokenKey, token);
     },
+    /**
+     * #action
+     */
     retrieveToken() {
-        return sessionStorage.getItem(self.tokenKey);
+        return sessionStorageGetItem(self.tokenKey);
     },
+    /**
+     * #action
+     * This can be used by an internetAccount to validate a token works before
+     * it is used. This is run when preAuthorizationInformation is requested,
+     * so it can be used to check that a token is valid before sending it to a
+     * worker thread. It expects the token to be returned so that this action
+     * can also be used to generate a new token (e.g. by using a refresh token)
+     * if the original one was invalid. Should throw an error if a token is
+     * invalid.
+     *
+     * @param token - Auth token
+     * @param loc - UriLocation of the resource
+     * @returns - Valid auth token
+     */
     async validateToken(token, _loc) {
         return token;
     },
 }))
     .actions(self => {
     let tokenPromise = undefined;
+    function clearToken() {
+        sessionStorageRemoveItem(self.tokenKey);
+        tokenPromise = undefined;
+    }
     return {
+        /**
+         * #action
+         * Clears the stored token. Also drops the in-memory cached promise so a
+         * subsequent `getToken` re-prompts / re-derives rather than handing back
+         * the token that was just invalidated.
+         */
+        removeToken() {
+            clearToken();
+        },
+        /**
+         * #action
+         * Try to get the token from the location pre-auth, from local storage,
+         * or from a previously cached promise. If token is not available, uses
+         * `getTokenFromUser`.
+         *
+         * @param location - UriLocation of the resource
+         * @returns A promise for the token
+         */
         async getToken(location) {
             if (tokenPromise) {
                 return tokenPromise;
@@ -77,7 +185,11 @@ export const InternetAccount = types
                 tokenPromise = Promise.resolve(token);
                 return tokenPromise;
             }
-            if (inWebWorker) {
+            // `isWebWorker()`, not a `typeof sessionStorage` probe: that asks a
+            // different question (it is also false on a page where storage is
+            // blocked, which is a main thread that CAN prompt) and it throws
+            // outright in exactly that case, at module load.
+            if (isWebWorker()) {
                 throw new Error('Did not get internet account pre-authorization info in worker');
             }
             token = self.retrieveToken();
@@ -85,64 +197,122 @@ export const InternetAccount = types
                 tokenPromise = Promise.resolve(token);
                 return tokenPromise;
             }
+            // The catch, rather than a clearToken() in the reject callback: a
+            // getTokenFromUser that throws on the way *in* — the token-entry
+            // accounts reach for `root.session` to queue their dialog, and an
+            // embedded root need not have one — never calls either callback, and
+            // the rejected promise it leaves behind would then be handed to every
+            // request for the rest of the session. Failing to get a token must
+            // never be a state the account stays in.
             tokenPromise = new Promise((resolve, reject) => {
                 self.getTokenFromUser(token => {
                     self.storeToken(token);
                     resolve(token);
-                }, error => {
-                    self.removeToken();
-                    reject(error);
-                });
+                }, reject);
+            }).catch((error) => {
+                clearToken();
+                throw error;
             });
             return tokenPromise;
         },
     };
 })
     .actions(self => ({
+    /**
+     * #action
+     */
     addAuthHeaderToInit(init, token) {
-        return {
-            ...init,
-            headers: new Headers({
-                ...init?.headers,
-                ...(token
-                    ? {
-                        [self.authHeader]: self.tokenType
-                            ? `${self.tokenType} ${token}`
-                            : token,
-                    }
-                    : {}),
-            }),
-        };
+        // build from init.headers via the Headers constructor so all HeadersInit
+        // shapes are preserved — object-spreading a Headers *instance* yields
+        // nothing (no enumerable own props), silently dropping caller headers
+        const headers = new Headers(init?.headers);
+        if (token) {
+            headers.set(self.authHeader, self.tokenType ? `${self.tokenType} ${token}` : token);
+        }
+        return { ...init, headers };
+    },
+    /**
+     * #action
+     * Run a request with the current token and, only if it comes back 401, put
+     * the token through `validateToken` and run it exactly once more. This is
+     * how every account's fetcher reaches a resource.
+     *
+     * @param loc - UriLocation of the resource
+     * @param run - issues the request with a given token
+     */
+    async fetchWithToken(loc, run) {
+        // Deliberately not a validateToken pre-flight on every request — a HEAD
+        // here, a metadata call for Dropbox and Google Drive — to re-prove a
+        // token that had just worked. A range-read track issues hundreds of
+        // requests, so that doubled both the round trips and the provider quota
+        // each track spent.
+        const token = await self.getToken(loc);
+        const response = await run(token);
+        if (response.status !== 401 || !loc) {
+            return response;
+        }
+        // A worker has neither storage nor a user to prompt, so it cannot mint a
+        // token — only the main thread can, and it re-validates before shipping
+        // the next pre-authorization. Going on into validateToken here died on
+        // `ReferenceError: sessionStorage is not defined` partway through a
+        // refresh; hand back the 401 so the caller reports it.
+        if (isWebWorker()) {
+            return response;
+        }
+        // validateToken renews an expired token, or throws if it can't. An
+        // account with nothing to renew it with — no refresh token, or
+        // `validateWithHEAD` off — hands the same one straight back, and
+        // re-running the request with a token that just failed only buys a
+        // second identical 401.
+        const validated = await self.validateToken(token, loc);
+        return validated === token ? response : run(validated);
     },
+    /**
+     * #action
+     * Gets the token and returns it along with the information needed to
+     * create a new internetAccount.
+     *
+     * @param location - UriLocation of the resource
+     * @returns
+     */
     async getPreAuthorizationInformation(location) {
         const authToken = await self.getToken(location);
-        let validatedToken;
         try {
-            validatedToken = await self.validateToken(authToken, location);
+            return {
+                internetAccountType: self.type,
+                authInfo: {
+                    token: await self.validateToken(authToken, location),
+                    configuration: getConf(self),
+                },
+            };
         }
         catch (error) {
             self.removeToken();
             throw error;
         }
-        return {
-            internetAccountType: self.type,
-            authInfo: {
-                token: validatedToken,
-                configuration: getConf(self),
-            },
-        };
     },
 }))
     .actions(self => ({
+    /**
+     * #action
+     * Get a fetch method that will add any needed authentication headers to
+     * the request before sending it. If location is provided, it will be
+     * checked to see if it includes a token in it pre-auth information.
+     *
+     * @param loc - UriLocation of the resource
+     * @returns A function that can be used to fetch
+     */
     getFetcher(loc) {
-        return async (input, init) => {
-            const authToken = await self.getToken(loc);
-            const newInit = self.addAuthHeaderToInit(init, authToken);
-            return fetch(input, newInit);
-        };
+        return (input, init) => self.fetchWithToken(loc, token => fetch(input, self.addAuthHeaderToInit(init, token)));
     },
 }))
     .actions(self => ({
+    /**
+     * #action
+     * Gets a filehandle that uses a fetch that adds auth headers
+     * @param location - UriLocation of the resource
+     * @returns A filehandle
+     */
     openLocation(location) {
         return new RemoteFileWithRangeCache(location.uri, {
             fetch: self.getFetcher(location),