pryv 3.12.1 → 3.13.0

package/README.md

@@ -603,8 +603,9 @@ The [authentication process](https://api.pryv.com/reference/#authenticate-your-a
 2. `INITIALIZED`: visuals assets are loaded, or when [polling](https://api.pryv.com/reference/#poll-request) concludes with **Result: Refused**
 3. `NEED_SIGNIN`: from the response of the [auth request](https://api.pryv.com/reference/#auth-request) through [polling](https://api.pryv.com/reference/#poll-request)
 4. `AUTHORIZED`: When [polling](https://api.pryv.com/reference/#poll-request) concludes with **Result: Accepted**
-5. `SIGNOUT`: when the user triggers a deletion of the client-side authorization credentials, usually by clicking the button after being signed in
-6. `ERROR`: see message for more information
+5. `SIGNOUT`: with the account menu, when the user confirms "Log out", just before the client-side authorization credentials are deleted. With `menu: false`, on the click itself, before the "Log out?" question: if the user cancels, the controller re-initializes from the stored credentials (`LOADING` then `AUTHORIZED`)
+6. `SWITCHING`: an account switch started (`{ from, to }`, `to` is `null` when the account is chosen in the sign-in popup); followed by `AUTHORIZED` for the new account, or for the previous one when the switch sign-in is refused. Listeners that ignore it see the usual `NEED_SIGNIN` then `AUTHORIZED` sequence
+7. `ERROR`: see message for more information
 
 You will need to provide a function to react depending on the state. The states `NEED_SIGNIN` and `AUTHORIZED` carry the same properties as the [auth process polling responses](https://api.pryv.com/reference/#poll-request). `LOADING`, `INITIALIZED` and `SIGNOUT` only have `status`. The `ERROR` state carries a `message` property.
 
@@ -634,11 +635,8 @@ async onStateChange (state) {
       });
       break;
     case AuthStates.SIGNOUT:
-      const message = this.messages.SIGNOUT_CONFIRM ? this.messages.SIGNOUT_CONFIRM : 'Logout ?';
-      if (confirm(message)) {
-        this.deleteAuthorizationData();
-        this.auth.init();
-      }
+      // Emitted by auth.signOut() after the user confirmed in showMenu()
+      // (below); the controller clears the credentials itself.
       break;
     case AuthStates.ERROR:
       this.text = getErrorMessage(this, state.message);
@@ -661,12 +659,22 @@ The button actions should be handled by the [AuthController](src/Auth/AuthContro
 onClick () {
   this.auth.handleClick();
 }
+
+// Optional: called on a click once signed in. Ask in your own dialog (never
+// window.confirm), then log out through the controller. Return false to get
+// the SIGNOUT state on the click instead.
+showMenu () {
+  myDialog.open({ onLogout: () => this.auth.signOut() });
+  return true;
+}
 ```
 
 ```js
 // AuthController.js
 async handleClick () {
   if (isAuthorized.call(this)) {
+    // a button implementing showMenu() opens its menu (logout through auth.signOut())
+    if (typeof this.loginButton?.showMenu === 'function' && this.loginButton.showMenu() !== false) return;
     this.state = { status: AuthStates.SIGNOUT };
   } else if (isInitialized.call(this)) {
     this.startAuthRequest();
@@ -679,6 +687,30 @@ async handleClick () {
 }
 ```
 
+##### Account menu
+
+Clicking the default button once signed in opens a small account menu: the signed-in username, the service and the app id, **Manage my account** (opens the platform's account app in a new tab) and **Log out**. `SIGNOUT` is emitted once, when "Log out" is chosen.
+
+- `authSettings.menu: false` restores the previous flow: `SIGNOUT` on click, then a plain "Log out?" confirmation (a built-in dialog, no longer `window.confirm()`).
+- `authSettings.menu: { hide: ['account', 'info'] }` (or `{ account: false }`) hides entries: `'logout'`, `'account'`, `'switch'`, `'info'`.
+- `authSettings.accountUrl` sets the account app root. Otherwise it is the service's `account` (`service/info`), then the auth page URL of the last sign-in without its trailing `/auth`; when none is known, "Manage my account" is not shown.
+- The menu uses the `.pryv-menu*` CSS classes, which a service's button stylesheet can override; its texts come from the button messages (`MENU_TITLE`, `LOGOUT`, `MANAGE_ACCOUNT`, `APP`, `CLOSE`).
+
+The controller exposes the same actions: `auth.signOut()`, `auth.openAccountApp()` and `auth.accountUrl()`. A custom button may implement `showMenu()` to show its own menu (return `false` to fall back to `SIGNOUT`).
+
+##### Several accounts and account switching
+
+The button remembers the accounts signed in on the app (at most `authSettings.maxProfiles`, default 5; the least recently used is forgotten first). The default button keeps the active account in its usual cookie (`pryv-libjs-<appId>`, `apiEndpoint` + `username`, removed when no account is active) and the remembered accounts in a second one (`pryv-libjs-<appId>-profiles`), so a version without account switching never reads the list as a signed-in account. `getAuthorizationData()` returns both merged (`profiles` next to the active account); a custom button stores that object as it is.
+
+- The menu lists them under "Use this app for". Choosing one activates it without a sign-in when its access is still valid (checked with `access-info`); an access that was revoked (for example by the end of an account delegation) is marked "no longer available" and asked for again through the sign-in popup.
+- On platforms with account delegation (`features.delegation` in `service/info`), "Another account..." runs the auth request again with `actAs: 'allow'`: after signing in, the popup asks whom the access is for (the user's own account or an account they control). An access granted for a controlled account is shown as `kim (via parent)`, and the menu offers "Switch back to parent". The app receives an access on the controlled account, never the delegate's own credentials; `connection.accessInfo().delegation` tells it so authoritatively.
+- "Log out" logs out of the active account and keeps the others (no account is signed in afterwards); "Log out of all accounts", shown when several are remembered, forgets them all.
+- `authSettings.authRequest.actAs`: `'allow'` (the server default: the popup may offer the accounts the user controls), `'deny'` (never), or a username to preselect. An app that supplies its own fixed access `token` and lets users switch accounts ends up with the same token value on several accounts; use `actAs: 'deny'` to avoid it.
+
+A switch that needs no sign-in, and the return to the previous account after a switch that did not complete, end in an `AUTHORIZED` state without a `key`: like the sign-in from stored credentials on page load, it carries the stored `username` and `apiEndpoint`.
+
+Controller API: `auth.switchTo(username)` (`null`: the user's own account), `auth.addAccount()`, `auth.profiles()` (`[{ username, actingAs?, active, available }]`), `auth.currentProfile()` and `auth.signOut({ all: true })`.
+
 ##### Custom button usage
 
 You must then provide this class as follows:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pryv",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "description": "Pryv JavaScript library",
   "keywords": [
     "Pryv",

package/src/Auth/AuthController.js

@@ -5,6 +5,8 @@
 const utils = require('../utils');
 const AuthStates = require('./AuthStates');
 const Messages = require('./LoginMessages');
+const ProfileStore = require('./ProfileStore');
+const handoff = require('../lib/handoff');
 
 /**
  * Controller for authentication flow
@@ -39,6 +41,11 @@ class AuthController {
     this.messages = Messages(this.languageCode);
 
     this.loginButton = loginButton;
+    // Incremented by every new auth request, sign-out and re-initialization:
+    // an older request's poll then no longer changes the state.
+    this._authFlowId = 0;
+    /** @type {Object|null} signed-in state to return to if a switch does not complete */
+    this._switchPrevious = null;
 
     function validateSettings (settings) {
       if (!settings) { throw new Error('settings cannot be null'); }
@@ -55,6 +62,18 @@ class AuthController {
       if (!settings.authRequest.requestedPermissions) {
         throw new Error('Missing settings.authRequest.requestedPermissions');
       }
+
+      // Delivery mode. Default to the one-time shared-secret hand-off so the
+      // token is never returned in the poll: a new core echoes
+      // `credentialHandoff` and delivers a `handoff` key (redeemed once here),
+      // an older core drops the field and falls back to inline delivery.
+      // Opt out with `authRequest.credentialHandoff = 'inline'`, which sends no
+      // field at all, so the request is byte-identical to the legacy one.
+      if (settings.authRequest.credentialHandoff === 'inline') {
+        delete settings.authRequest.credentialHandoff;
+      } else if (settings.authRequest.credentialHandoff == null) {
+        settings.authRequest.credentialHandoff = 'shared-secret';
+      }
     }
   }
 
@@ -63,6 +82,7 @@ class AuthController {
    * @returns {Promise<Service>} Promise resolving to the Service instance
    */
   async init () {
+    cancelAuthFlow(this);
     this.serviceInfo = this.service.infoSync();
     this.state = { status: AuthStates.LOADING };
     this.assets = await loadAssets(this);
@@ -99,6 +119,8 @@ class AuthController {
    * Stops poll for auth request
    */
   stopAuthRequest (msg) {
+    // its poll must not change the state any more
+    cancelAuthFlow(this);
     this.state = { status: AuthStates.ERROR, message: msg };
   }
 
@@ -108,9 +130,19 @@ class AuthController {
    */
   async handleClick () {
     if (isAuthorized.call(this)) {
+      // A button with an account menu opens it (logout happens from there,
+      // through `signOut()`); otherwise the legacy SIGNOUT state lets the
+      // button confirm the logout itself.
+      const loginButton = this.loginButton;
+      if (loginButton != null && typeof loginButton.showMenu === 'function' &&
+          loginButton.showMenu() !== false) {
+        return;
+      }
       this.state = { status: AuthStates.SIGNOUT };
     } else if (isInitialized.call(this)) {
       this.startAuthRequest();
+    } else if (this.state.status === AuthStates.SWITCHING) {
+      // a switch is running; its outcome arrives as a state change
     } else if (isNeedSignIn.call(this)) {
       // reopen popup (HACK for now: set to private property to avoid self-assignment)
       this.state = this._state;
@@ -129,6 +161,192 @@ class AuthController {
     }
   }
 
+  /**
+   * Log out: emit SIGNOUT once, forget the active account and return to
+   * INITIALIZED. The other remembered accounts are kept (`all` forgets them
+   * too). This is the confirmed logout (no further confirmation).
+   * @param {Object} [options]
+   * @param {boolean} [options.all] - forget every remembered account
+   * @returns {Promise<void>}
+   */
+  async signOut (options) {
+    const all = options?.all === true;
+    cancelAuthFlow(this);
+    const store = this._readProfiles();
+    // during a switch, the account being left
+    const current = this.state?.username ?? this.state?.from;
+    this._signingOut = true;
+    try {
+      this.state = { status: AuthStates.SIGNOUT };
+    } finally {
+      this._signingOut = false;
+    }
+    // Drop any cached hand-off credential for this flow's key. Guard the
+    // key: on a cookie-autologin session there is no `_authFlowKey`, and
+    // clearing with `undefined` would wipe an unrelated concurrent flow.
+    if (this._authFlowKey != null) handoff.cacheClear(this._authFlowKey);
+    const others = current == null ? store.profiles : ProfileStore.remove(store, current).profiles;
+    const loginButton = this.loginButton;
+    if (!all && others.length > 0 && loginButton != null && typeof loginButton.saveAuthorizationData === 'function') {
+      loginButton.saveAuthorizationData(ProfileStore.write(Object.assign({}, store, { active: null, profiles: others })));
+    } else if (loginButton != null && typeof loginButton.deleteAuthorizationData === 'function') {
+      await loginButton.deleteAuthorizationData();
+    }
+    await this.init();
+  }
+
+  /**
+   * The accounts remembered for this app, most recently used first.
+   * @returns {Array<{username: string, actingAs?: {username: string, delegate: string}, active: boolean, available: boolean}>}
+   */
+  profiles () {
+    const current = this.currentProfile();
+    return this._readProfiles().profiles.map((p) => {
+      const out = { username: p.username, active: current != null && current.username === p.username, available: p.unavailable !== true };
+      if (p.actingAs != null) out.actingAs = p.actingAs;
+      return out;
+    });
+  }
+
+  /**
+   * The signed-in account, or null.
+   * @returns {{username: string, actingAs?: {username: string, delegate: string}}|null}
+   */
+  currentProfile () {
+    if (this.state?.status !== AuthStates.AUTHORIZED || this.state.profile == null) return null;
+    const out = { username: this.state.profile.username };
+    if (this.state.profile.actingAs != null) out.actingAs = this.state.profile.actingAs;
+    return out;
+  }
+
+  /**
+   * Switch to another account. `username` null means the signed-in person's
+   * own account (switch back). A remembered account whose access is still
+   * valid is activated without a sign-in; otherwise the auth request runs
+   * again, asking for that account (`actAs`). Emits SWITCHING first; ends in
+   * AUTHORIZED, or back on the previous account when the sign-in is refused.
+   * @param {string|null} username
+   * @returns {Promise<void>}
+   */
+  async switchTo (username) {
+    const store = this._readProfiles();
+    const current = this.currentProfile();
+    let target;
+    if (username == null) {
+      if (current != null && current.actingAs == null) return;
+      const delegate = current?.actingAs?.delegate;
+      // Acting for an account: back to the delegate's own account only, never
+      // to another remembered one. Not signed in: the most recent own account.
+      target = delegate != null
+        ? store.profiles.find((p) => p.username === delegate && p.actingAs == null)
+        : store.profiles.find((p) => p.actingAs == null);
+    } else {
+      if (current != null && current.username === username) return;
+      target = store.profiles.find((p) => p.username === username);
+    }
+    const toUsername = target?.username ?? username ?? null;
+    const previous = restorableState(this.state);
+    // a log out or re-initialization during the access check ends this switch
+    cancelAuthFlow(this);
+    const flowId = this._authFlowId;
+    this.state = { status: AuthStates.SWITCHING, from: current?.username ?? null, to: toUsername };
+
+    if (target != null && target.unavailable !== true) {
+      let info;
+      try {
+        info = await this._accessInfo(target.apiEndpoint);
+      } catch (e) {
+        if (this._authFlowId !== flowId) throw e;
+        // network failure: stay on the previous account
+        this.state = previous ?? { status: AuthStates.INITIALIZED, serviceInfo: this.serviceInfo };
+        throw e;
+      }
+      if (this._authFlowId !== flowId) return;
+      if (info != null && info.error == null) {
+        const profile = profileFromAccessInfo(target, info);
+        this.state = { status: AuthStates.AUTHORIZED, username: profile.username, apiEndpoint: profile.apiEndpoint, profile };
+        return;
+      }
+      if (!ACCESS_GONE_ERRORS.includes(info?.error?.id)) {
+        // any other answer (server error, rate limit) says nothing about the access
+        this.state = previous ?? { status: AuthStates.INITIALIZED, serviceInfo: this.serviceInfo };
+        throw new Error('Cannot check the access of ' + target.username + ': ' + JSON.stringify(info?.error));
+      }
+      // revoked or expired (a detach revokes the accesses granted through it)
+      this._saveProfiles(ProfileStore.markUnavailable(this._readProfiles(), target.username));
+    }
+    // own account: a sign-in that offers no other account; otherwise ask for that one
+    await this.startAuthRequest({ actAs: username == null ? 'deny' : username }, previous);
+  }
+
+  /**
+   * Sign in to one more account (the popup may offer the accounts the person
+   * can act for); the remembered accounts are kept.
+   * @returns {Promise<void>}
+   */
+  async addAccount () {
+    const current = this.currentProfile();
+    const previous = restorableState(this.state);
+    this.state = { status: AuthStates.SWITCHING, from: current?.username ?? null, to: null };
+    await this.startAuthRequest({ actAs: 'allow' }, previous);
+  }
+
+  /**
+   * @private The access-info of a stored account (`{ error }` when refused).
+   * @param {string} apiEndpoint
+   */
+  async _accessInfo (apiEndpoint) {
+    // required here: Connection is not needed before the first switch
+    const Connection = require('../Connection');
+    return await new Connection(apiEndpoint).accessInfo(true);
+  }
+
+  /** @private */
+  _readProfiles () {
+    const loginButton = this.loginButton;
+    if (loginButton == null || typeof loginButton.getAuthorizationData !== 'function') return ProfileStore.read(null);
+    return ProfileStore.read(loginButton.getAuthorizationData());
+  }
+
+  /** @private */
+  _saveProfiles (store) {
+    const loginButton = this.loginButton;
+    if (loginButton == null || typeof loginButton.saveAuthorizationData !== 'function') return;
+    const data = ProfileStore.write(store);
+    if (data == null && typeof loginButton.deleteAuthorizationData === 'function') {
+      loginButton.deleteAuthorizationData();
+    } else if (data != null) {
+      loginButton.saveAuthorizationData(data);
+    }
+  }
+
+  /**
+   * URL of the account app (profile page) for this platform, or null when
+   * it cannot be determined. Resolution order: `settings.accountUrl`, then
+   * the service's `account`, then the auth page URL of the last auth
+   * request with its trailing `/auth` removed.
+   * @returns {string|null}
+   */
+  accountUrl () {
+    let base = this.settings.accountUrl || this.serviceInfo?.account || accountUrlFromAuthUrl(this._authUrl);
+    if (typeof base !== 'string' || base === '') return null;
+    base = base.replace(/\/+$/, '');
+    // @ts-ignore - Service keeps the URL it was created with
+    const serviceInfoUrl = this.service?._serviceInfoUrl;
+    return base + '/account/profile' +
+      (serviceInfoUrl ? '?pryvServiceInfoUrl=' + encodeURIComponent(serviceInfoUrl) : '');
+  }
+
+  /**
+   * Open the account app in a new tab.
+   * @returns {string|null} the URL opened, or null when unknown
+   */
+  openAccountApp () {
+    const url = this.accountUrl();
+    if (url != null) window.open(url, '_blank', 'noopener');
+    return url;
+  }
+
   /**
    * Compute the return URL for authentication redirect.
    * Used only in browser environments.
@@ -174,16 +392,26 @@ class AuthController {
 
   /**
    * Start the authentication request and polling process
+   * @param {Object} [overrides] - auth request fields for this request only (e.g. `actAs`)
+   * @param {Object} [previous] - AUTHORIZED state to return to when this
+   *   request (an account switch) does not end in AUTHORIZED
    * @returns {Promise<void>}
    * @see https://pryv.github.io/reference/#auth-request
    */
-  async startAuthRequest () {
+  async startAuthRequest (overrides, previous) {
+    cancelAuthFlow(this);
+    const flowId = this._authFlowId;
+    this._switchPrevious = previous ?? null;
     // @ts-ignore - postAccess uses .call(this) for context
-    this.state = await postAccess.call(this);
+    const requested = await postAccess.call(this);
+    if (this._authFlowId !== flowId) return; // replaced while posting
+    this.state = requested;
     // Remember the polling key so listeners on the terminal AUTHORIZED
     // state can be handed `{ key, serviceInfo? }` (the polling response
     // itself doesn't echo `key` back).
     this._authFlowKey = this.state?.key;
+    // Kept to locate the account app when the service does not name it.
+    if (this.state?.authUrl) this._authUrl = this.state.authUrl;
 
     await doPolling.call(this);
 
@@ -194,14 +422,17 @@ class AuthController {
           // @ts-ignore - this is bound via .call()
           this.serviceInfo.access,
           // @ts-ignore - this is bound via .call()
-          this.settings.authRequest
+          Object.assign({}, this.settings.authRequest, overrides)
         );
         if (!response.ok) {
           throw new Error('Access request failed: ' + JSON.stringify(body));
         }
         return body;
       } catch (e) {
-        this.state = {
+        if (this._authFlowId !== flowId) throw e; // replaced while posting
+        const previous = this._switchPrevious;
+        this._switchPrevious = null;
+        this.state = previous ?? {
           status: AuthStates.ERROR,
           message: 'Requesting access',
           error: e
@@ -213,21 +444,59 @@ class AuthController {
     /** @this {AuthController} */
     async function doPolling () {
       // @ts-ignore - this is bound via .call()
-      if (this.state?.status !== AuthStates.NEED_SIGNIN) {
+      if (this._authFlowId !== flowId || this.state?.status !== AuthStates.NEED_SIGNIN) {
         return;
       }
       // @ts-ignore - this is bound via .call()
       const pollResponse = await pollAccess(this.state?.poll);
+      // a newer request, a sign-out or a re-initialization replaced this one
+      // @ts-ignore - this is bound via .call()
+      if (this._authFlowId !== flowId) return;
 
       if (pollResponse.status === AuthStates.NEED_SIGNIN) {
         // @ts-ignore - this is bound via .call()
         setTimeout(await doPolling.bind(this), this.state?.poll_rate_ms);
       } else {
+        // Shared-secret delivery: the ACCEPTED body carries a one-time
+        // `handoff` key, not the token. Redeem it once here (caching under the
+        // poll key so a later connectFromKey reuses it) and rewrite the body to
+        // the legacy shape, so the cookie / LoginButton path and the external
+        // listener filter are untouched.
+        if (handoff.isHandoffBody(pollResponse)) {
+          try {
+            const entry = await handoff.resolveHandoff(pollResponse, this._authFlowKey);
+            pollResponse.apiEndpoint = entry.apiEndpoint;
+            pollResponse.token = entry.token;
+            pollResponse.username = entry.username;
+            delete pollResponse.handoff;
+          } catch (e) {
+            // @ts-ignore - this is bound via .call()
+            if (this._authFlowId !== flowId) return;
+            // @ts-ignore - this is bound via .call()
+            const previous = this._switchPrevious;
+            // @ts-ignore - this is bound via .call()
+            this._switchPrevious = null;
+            this.state = previous ?? { status: AuthStates.ERROR, message: 'Credential hand-off failed', error: e };
+            return;
+          }
+          // a newer request, a sign-out or a re-initialization replaced this one
+          // @ts-ignore - this is bound via .call()
+          if (this._authFlowId !== flowId) return;
+        }
         // Carry the key forward — listeners on the narrow public surface
         // need it, and the server doesn't echo it back on ACCEPTED.
         if (this._authFlowKey != null && pollResponse.key == null) {
           pollResponse.key = this._authFlowKey;
         }
+        const previous = this._switchPrevious;
+        this._switchPrevious = null;
+        if (pollResponse.status === AuthStates.AUTHORIZED) {
+          pollResponse.profile = ProfileStore.fromAccepted(pollResponse);
+        } else if (previous != null) {
+          // an account switch that did not complete: stay on the previous account
+          this.state = previous;
+          return;
+        }
         this.state = pollResponse;
       }
 
@@ -307,6 +576,22 @@ function filterForExternalListener (state) {
   return out;
 }
 
+/**
+ * The account app is served next to the auth page: strip a trailing `/auth`
+ * path segment (and the query) from the auth page URL. Null when the URL
+ * does not have that shape.
+ * @param {string} [authUrl]
+ * @returns {string|null}
+ */
+function accountUrlFromAuthUrl (authUrl) {
+  if (typeof authUrl !== 'string') return null;
+  let url;
+  try { url = new URL(authUrl); } catch (e) { return null; }
+  const path = url.pathname.replace(/\/+$/, '');
+  if (!path.endsWith('/auth')) return null;
+  return url.origin + path.slice(0, -'/auth'.length);
+}
+
 async function checkAutoLogin (authController) {
   const loginButton = authController.loginButton;
   if (loginButton == null) {
@@ -314,9 +599,52 @@ async function checkAutoLogin (authController) {
   }
 
   const storedCredentials = await loginButton.getAuthorizationData();
-  if (storedCredentials != null) {
-    authController.state = Object.assign({}, { status: AuthStates.AUTHORIZED }, storedCredentials);
+  if (storedCredentials == null) return;
+  if (typeof storedCredentials.authUrl === 'string') authController._authUrl = storedCredentials.authUrl;
+  if (Array.isArray(storedCredentials.profiles)) {
+    // Several remembered accounts: sign in to the active one, if any
+    const store = ProfileStore.read(storedCredentials);
+    if (store.active == null) return;
+    const state = { status: AuthStates.AUTHORIZED, username: store.active.username, apiEndpoint: store.active.apiEndpoint, profile: store.active };
+    if (store.authUrl != null) state.authUrl = store.authUrl;
+    authController.state = state;
+    return;
   }
+  const state = Object.assign({}, { status: AuthStates.AUTHORIZED }, storedCredentials);
+  if (typeof state.username === 'string' && typeof state.apiEndpoint === 'string') state.profile = ProfileStore.profileOf(state);
+  authController.state = state;
+}
+
+/** A stored profile refreshed with what its access says about itself. */
+function profileFromAccessInfo (stored, info) {
+  const profile = { username: stored.username, apiEndpoint: stored.apiEndpoint };
+  const d = info.delegation;
+  if (d != null && d.isDelegatedAccess === true && typeof d.delegate?.username === 'string') {
+    profile.actingAs = { username: stored.username, delegate: d.delegate.username };
+  }
+  return profile;
+}
+
+/** API errors that mean a stored access is no longer usable. */
+const ACCESS_GONE_ERRORS = ['invalid-access-token', 'forbidden'];
+
+/**
+ * The signed-in state to return to when an account switch does not
+ * complete: the account as stored, without the `key` of its sign-in (that
+ * auth request is consumed), like a sign-in from stored credentials.
+ */
+function restorableState (state) {
+  if (state?.status !== AuthStates.AUTHORIZED) return null;
+  const restored = { status: AuthStates.AUTHORIZED, username: state.username, apiEndpoint: state.apiEndpoint };
+  if (state.profile != null) restored.profile = state.profile;
+  if (state.authUrl != null) restored.authUrl = state.authUrl;
+  return restored;
+}
+
+/** Stop any auth request in progress: its poll no longer changes the state. */
+function cancelAuthFlow (authController) {
+  authController._authFlowId = (authController._authFlowId || 0) + 1;
+  authController._switchPrevious = null;
 }
 
 // ------------------ ACTIONS  ----------- //

package/src/Auth/AuthStates.js

@@ -4,7 +4,8 @@
  */
 /**
  * The possible auth states:
- * ERROR, LOADING, INITIALIZED, NEED_SIGNIN, AUTHORIZED, SIGNOUT, REFUSED
+ * ERROR, LOADING, INITIALIZED, NEED_SIGNIN, AUTHORIZED, SIGNOUT, REFUSED,
+ * SWITCHING (an account switch is running)
  * @readonly
  * @enum {string}
  * @memberof pryv.Browser
@@ -16,5 +17,6 @@ module.exports = {
   NEED_SIGNIN: 'NEED_SIGNIN',
   AUTHORIZED: 'ACCEPTED',
   SIGNOUT: 'SIGNOUT',
-  REFUSED: 'REFUSED'
+  REFUSED: 'REFUSED',
+  SWITCHING: 'SWITCHING'
 };

package/src/Auth/LoginMessages.js

@@ -19,11 +19,80 @@ const Messages = {
   SIGNOUT_CONFIRM: {
     en: 'Logout?',
     fr: 'Se déconnecter ?'
+  },
+  MENU_TITLE: {
+    en: 'Account',
+    fr: 'Compte'
+  },
+  LOGOUT: {
+    en: 'Log out',
+    fr: 'Se déconnecter'
+  },
+  MANAGE_ACCOUNT: {
+    en: 'Manage my account',
+    fr: 'Gérer mon compte'
+  },
+  APP: {
+    en: 'app',
+    fr: 'app'
+  },
+  CLOSE: {
+    en: 'Close',
+    fr: 'Fermer'
+  },
+  CANCEL: {
+    en: 'Cancel',
+    fr: 'Annuler'
+  },
+  LOGOUT_ALL: {
+    en: 'Log out of all accounts',
+    fr: 'Se déconnecter de tous les comptes'
+  },
+  MANAGE_ACCOUNT_OF: {
+    en: 'Manage {username}\'s account',
+    fr: 'Gérer le compte de {username}'
+  },
+  USE_FOR: {
+    en: 'Use this app for',
+    fr: 'Utiliser cette app pour'
+  },
+  ME: {
+    en: 'me',
+    fr: 'moi'
+  },
+  VIA: {
+    en: 'via',
+    fr: 'via'
+  },
+  ACTING_AS: {
+    en: 'acting as',
+    fr: 'pour le compte'
+  },
+  SWITCH_BACK: {
+    en: 'Switch back to {username}',
+    fr: 'Revenir à {username}'
+  },
+  SWITCHING: {
+    en: 'Switching...',
+    fr: 'Changement...'
+  },
+  OTHER_ACCOUNT: {
+    en: 'Another account...',
+    fr: 'Un autre compte...'
+  },
+  UNAVAILABLE: {
+    en: 'no longer available',
+    fr: 'plus disponible'
   }
 };
 
+/**
+ * Messages for a language. `definitions` (a service's own messages) override
+ * the defaults key by key, so a key the service does not define still has
+ * its default text.
+ */
 function get (languageCode, definitions) {
-  const myMessages = definitions || Messages;
+  const myMessages = Object.assign({}, Messages, definitions || {});
   const res = {};
   Object.keys(myMessages).forEach((key) => {
     res[key] = myMessages[key][languageCode] || myMessages[key].en;