pryv 3.12.0 → 3.13.0

package/src/Auth/ProfileStore.js

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * The accounts a sign-in button remembers for one app, as stored in its
+ * authorization data:
+ * `{ apiEndpoint, username, actingAs?, authUrl?, profiles: [...] }`.
+ * The top-level `apiEndpoint` / `username` are the active account (what
+ * versions without profiles read); `profiles` lists every remembered
+ * account, most recently used first, the active one included.
+ * A profile is `{ username, apiEndpoint, actingAs?, unavailable? }`, where
+ * `actingAs = { username, delegate }` marks an account used through account
+ * delegation (`delegate` is the username of the person acting).
+ * @memberof pryv.Auth
+ */
+module.exports = {
+  DEFAULT_LIMIT: 5,
+  read,
+  write,
+  activate,
+  remove,
+  markUnavailable,
+  profileOf,
+  fromAccepted
+};
+
+/**
+ * Parse stored authorization data (any version) into
+ * `{ active, profiles, authUrl }`; `active` is `profiles[0]` or null.
+ * @param {Object|null|undefined} stored
+ */
+function read (stored) {
+  const store = { active: null, profiles: [], authUrl: undefined };
+  if (stored == null || typeof stored !== 'object' || stored.deleted === true) return store;
+  if (typeof stored.authUrl === 'string') store.authUrl = stored.authUrl;
+  if (Array.isArray(stored.profiles)) {
+    store.profiles = stored.profiles.filter(isProfile).map(profileOf);
+  }
+  if (isProfile(stored)) {
+    const active = profileOf(stored);
+    store.profiles = [active].concat(store.profiles.filter((p) => p.username !== active.username));
+    store.active = active;
+  }
+  return store;
+}
+
+/**
+ * The authorization data to store for `store`.
+ * @returns {Object|null} null when nothing is left to remember
+ */
+function write (store) {
+  if (store.profiles.length === 0) return null;
+  const data = {};
+  if (store.active != null) {
+    data.apiEndpoint = store.active.apiEndpoint;
+    data.username = store.active.username;
+    if (store.active.actingAs != null) data.actingAs = store.active.actingAs;
+  }
+  if (store.authUrl != null) data.authUrl = store.authUrl;
+  data.profiles = store.profiles.map(profileOf);
+  return data;
+}
+
+/**
+ * Make `profile` the active account (replacing a stored one with the same
+ * username), then forget the least recently used accounts beyond `limit`.
+ */
+function activate (store, profile, limit) {
+  const max = Math.max(1, limit || module.exports.DEFAULT_LIMIT);
+  const active = profileOf(profile);
+  const profiles = [active].concat(store.profiles.filter((p) => p.username !== active.username));
+  return Object.assign({}, store, { active, profiles: profiles.slice(0, max) });
+}
+
+/** Forget `username`; forgetting the active account leaves none active. */
+function remove (store, username) {
+  const profiles = store.profiles.filter((p) => p.username !== username);
+  const active = (store.active != null && store.active.username !== username) ? store.active : null;
+  return Object.assign({}, store, { active, profiles });
+}
+
+/** Keep `username` listed, marked as no longer usable (revoked, detached). */
+function markUnavailable (store, username) {
+  const mark = (p) => (p.username === username ? Object.assign(profileOf(p), { unavailable: true }) : p);
+  const profiles = store.profiles.map(mark);
+  const active = (store.active != null && store.active.username === username) ? null : store.active;
+  return Object.assign({}, store, { active, profiles });
+}
+
+/** The stored fields of a profile, nothing else (credentials included). */
+function profileOf (p) {
+  const profile = { username: p.username, apiEndpoint: p.apiEndpoint };
+  if (p.actingAs != null && typeof p.actingAs.delegate === 'string') {
+    profile.actingAs = { username: p.username, delegate: p.actingAs.delegate };
+  }
+  if (p.unavailable === true) profile.unavailable = true;
+  return profile;
+}
+
+function isProfile (p) {
+  return p != null && typeof p.username === 'string' && typeof p.apiEndpoint === 'string';
+}
+
+/**
+ * The profile of an ACCEPTED auth-request body. Its `delegation` block is a
+ * display hint posted by the auth page; `accessInfo().delegation` is
+ * authoritative and replaces it when the profile is next activated.
+ */
+function fromAccepted (body) {
+  const profile = { username: body.username, apiEndpoint: body.apiEndpoint };
+  const d = body.delegation;
+  if (d != null && d.isDelegatedAccess === true && d.controlledUsername === body.username &&
+      typeof d.delegate?.username === 'string') {
+    profile.actingAs = { username: body.username, delegate: d.delegate.username };
+  }
+  return profile;
+}

package/src/Browser/LoginButton.js

@@ -5,10 +5,16 @@
 const Cookies = require('./CookieUtils');
 const AuthStates = require('../Auth/AuthStates');
 const AuthController = require('../Auth/AuthController');
+const ProfileStore = require('../Auth/ProfileStore');
 const Messages = require('../Auth/LoginMessages');
 const utils = require('../utils');
 
-/* global location, confirm */
+/* global location */
+
+/** Suffix of the cookie that holds the remembered accounts. */
+const PROFILES_COOKIE_SUFFIX = '-profiles';
+/** Encoded length kept under the ~4096-byte cookie limit (name and attributes included). */
+const PROFILES_COOKIE_MAX_LENGTH = 3500;
 
 /**
  * @memberof pryv.Browser
@@ -64,19 +70,29 @@ class LoginButton {
         }
         break;
       }
-      case AuthStates.AUTHORIZED:
-        this.text = state.username;
-        this.saveAuthorizationData({
-          apiEndpoint: state.apiEndpoint,
-          username: state.username
-        });
+      case AuthStates.AUTHORIZED: {
+        const profile = state.profile || ProfileStore.fromAccepted(state);
+        this.text = profileLabel(this, profile);
+        const store = ProfileStore.read(this.getAuthorizationData());
+        // Kept to locate the account app after a reload (see AuthController.accountUrl).
+        const authUrl = withoutQuery(state.authUrl || this.auth?._authUrl) || store.authUrl;
+        this.saveAuthorizationData(ProfileStore.write(Object.assign(
+          ProfileStore.activate(store, profile, this.authSettings.maxProfiles),
+          { authUrl }
+        )));
+        break;
+      }
+      case AuthStates.SWITCHING:
+        this.text = this.messages.SWITCHING || '...';
         break;
       case AuthStates.SIGNOUT: {
-        const message = this.messages.SIGNOUT_CONFIRM ? this.messages.SIGNOUT_CONFIRM : 'Logout ?';
-        if (confirm(message)) {
-          this.deleteAuthorizationData();
-          this.auth.init();
-        }
+        // A confirmed logout (the menu's "Log out", or `auth.signOut()`)
+        // clears the credentials itself.
+        if (this.auth?._signingOut) break;
+        // Menu disabled (`settings.menu: false`): confirm in a small built-in
+        // dialog, then clear the credentials (see buildMenu: the re-init is
+        // awaited there, never left running in the background).
+        this.openMenu({ confirmLogout: true });
         break;
       }
       case AuthStates.ERROR:
@@ -92,16 +108,104 @@ class LoginButton {
     }
   }
 
+  /**
+   * Open the account menu (signed-in account, "Manage my account",
+   * "Log out"). Returns false, and opens nothing, when the menu is disabled
+   * with `settings.menu: false`: the caller then falls back to the logout
+   * confirmation.
+   * @returns {boolean}
+   */
+  showMenu () {
+    if (this.authSettings.menu === false) return false;
+    return this.openMenu({ confirmLogout: false });
+  }
+
+  /**
+   * @private Open the account menu, or (`confirmLogout`) the plain "Log out?"
+   * confirmation used when the menu is disabled.
+   */
+  openMenu ({ confirmLogout }) {
+    if (typeof document === 'undefined') return false;
+    this.closeMenu();
+    this.menu = buildMenu(this, confirmLogout);
+    document.body.appendChild(this.menu.overlay);
+    this.menu.focusables()[0]?.focus();
+    return true;
+  }
+
+  /**
+   * Close the account menu if it is open. Dismissing the "Log out?" question
+   * (anything but "Log out") returns to the signed-in state: SIGNOUT was
+   * already emitted by the click, and the button would otherwise stay inert.
+   * @param {boolean} [loggingOut] - closed by the "Log out" action
+   * @returns {Promise<void>} resolves when any re-init it started is done
+   */
+  closeMenu (loggingOut) {
+    if (this.menu == null) return Promise.resolve();
+    const menu = this.menu;
+    this.menu = null;
+    document.removeEventListener('keydown', menu.onKeyDown, true);
+    if (menu.overlay.parentNode != null) menu.overlay.parentNode.removeChild(menu.overlay);
+    const previousFocus = /** @type {HTMLElement|null} */ (menu.previousFocus);
+    if (previousFocus != null && typeof previousFocus.focus === 'function') {
+      previousFocus.focus();
+    }
+    if (menu.confirmLogout && !loggingOut) {
+      // init() reports its own failures as the ERROR state
+      this.pending = this.auth.init().then(() => {}, (e) => { console.log('Error while re-initializing', e); });
+      return this.pending;
+    }
+    return Promise.resolve();
+  }
+
+  /**
+   * The stored sign-in: the active account from the main cookie (the only
+   * cookie versions without account switching read) and the remembered
+   * accounts from a second one.
+   */
   getAuthorizationData () {
-    return Cookies.get(this._cookieKey);
+    const active = Cookies.get(this._cookieKey);
+    const remembered = Cookies.get(this._cookieKey + PROFILES_COOKIE_SUFFIX);
+    if (remembered == null || !Array.isArray(remembered.profiles)) return active;
+    const data = Object.assign({}, active != null && active.deleted !== true ? active : {}, { profiles: remembered.profiles });
+    if (data.authUrl == null && remembered.authUrl != null) data.authUrl = remembered.authUrl;
+    return data;
   }
 
+  /**
+   * Store the sign-in. The main cookie holds the active account only (or is
+   * removed when none is active), so an older version never reads a list of
+   * remembered accounts as a signed-in one.
+   */
   saveAuthorizationData (authData) {
-    Cookies.set(this._cookieKey, authData);
+    if (authData == null) {
+      Cookies.del(this._cookieKey);
+      Cookies.del(this._cookieKey + PROFILES_COOKIE_SUFFIX);
+      return;
+    }
+    const { profiles, ...active } = authData;
+    if (typeof active.username === 'string' && typeof active.apiEndpoint === 'string') {
+      Cookies.set(this._cookieKey, active);
+    } else {
+      Cookies.del(this._cookieKey);
+    }
+    if (Array.isArray(profiles)) {
+      const remembered = Object.assign({ profiles: profiles.slice() }, active.authUrl != null ? { authUrl: active.authUrl } : {});
+      // A browser drops a cookie over ~4 KB: forget the least recently used
+      // accounts (the list is most recent first) until it fits.
+      while (remembered.profiles.length > 1 &&
+             encodeURIComponent(JSON.stringify(remembered)).length > PROFILES_COOKIE_MAX_LENGTH) {
+        remembered.profiles.pop();
+      }
+      Cookies.set(this._cookieKey + PROFILES_COOKIE_SUFFIX, remembered);
+    } else {
+      Cookies.del(this._cookieKey + PROFILES_COOKIE_SUFFIX);
+    }
   }
 
   async deleteAuthorizationData () {
     Cookies.del(this._cookieKey);
+    Cookies.del(this._cookieKey + PROFILES_COOKIE_SUFFIX);
   }
 
   /**
@@ -119,6 +223,7 @@ class LoginButton {
     if (pollUrl !== null) {
       try {
         const { body } = await utils.fetchGet(pollUrl);
+        if (body?.status === AuthStates.AUTHORIZED && typeof body.username === 'string') body.profile = ProfileStore.fromAccepted(body);
         authController.state = body;
       } catch (e) {
         authController.state = {
@@ -182,6 +287,270 @@ async function startLoginScreen (loginButton, authUrl) {
   }
 }
 
+const MENU_OPTIONS = ['logout', 'account', 'switch', 'info'];
+
+/** `kim-doe (via parent-doe)` for an account used through delegation. */
+function profileLabel (loginButton, profile) {
+  if (profile?.actingAs == null) return profile?.username;
+  return profile.username + ' (' + loginButton.messages.VIA + ' ' + profile.actingAs.delegate + ')';
+}
+
+/** The auth page URL without its query and fragment (they may carry a key). */
+function withoutQuery (url) {
+  if (typeof url !== 'string') return undefined;
+  try {
+    const u = new URL(url);
+    return u.origin + u.pathname;
+  } catch (e) {
+    return undefined;
+  }
+}
+
+/**
+ * Which menu entries to show: all by default; `settings.menu.<option>: false`
+ * or `settings.menu.hide: ['<option>', ...]` hides one.
+ */
+function menuOptions (menuSettings) {
+  const options = {};
+  MENU_OPTIONS.forEach((o) => { options[o] = true; });
+  if (menuSettings != null && typeof menuSettings === 'object') {
+    MENU_OPTIONS.forEach((o) => { if (menuSettings[o] === false) options[o] = false; });
+    if (Array.isArray(menuSettings.hide)) {
+      menuSettings.hide.forEach((o) => { if (o in options) options[o] = false; });
+    }
+  }
+  return options;
+}
+
+const MENU_CSS = `
+.pryv-menu-overlay { position: fixed; top: 0; right: 0; bottom: 0; left: 0; z-index: 2147483000; display: flex;
+  align-items: center; justify-content: center; background: rgba(0, 0, 0, 0.35); }
+.pryv-menu { background: #fff; color: #222; min-width: 280px; max-width: 90vw; border-radius: 8px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.25); font: 14px/1.4 system-ui, sans-serif; }
+.pryv-menu-header { display: flex; align-items: flex-start; justify-content: space-between;
+  gap: 16px; padding: 16px 16px 8px; }
+.pryv-menu-username { font-weight: 600; font-size: 16px; overflow-wrap: anywhere; }
+.pryv-menu-info { color: #666; font-size: 13px; padding: 0 16px 12px; overflow-wrap: anywhere; }
+.pryv-menu-close { border: 0; background: none; font-size: 20px; line-height: 1; cursor: pointer; color: #666; }
+.pryv-menu-actions { display: flex; flex-wrap: wrap; gap: 8px; justify-content: flex-end;
+  padding: 12px 16px 16px; border-top: 1px solid #eee; }
+.pryv-menu-actions button { padding: 6px 12px; border-radius: 4px; border: 1px solid #ccc;
+  background: #f7f7f7; cursor: pointer; font: inherit; }
+.pryv-menu-actions button:focus-visible, .pryv-menu-close:focus-visible,
+.pryv-menu-switch button:focus-visible { outline: 2px solid #4a90d9; }
+.pryv-menu-acting { font-weight: 400; color: #666; font-size: 13px; }
+.pryv-menu-switch { padding: 8px 16px 12px; border-top: 1px solid #eee; }
+.pryv-menu-switch-title { color: #666; font-size: 13px; margin-bottom: 4px; }
+.pryv-menu-switch button { display: block; width: 100%; text-align: left; padding: 6px 8px; border: 0;
+  border-radius: 4px; background: none; cursor: pointer; font: inherit; color: inherit; }
+.pryv-menu-switch button:hover { background: #f2f2f2; }
+.pryv-menu-switch button[aria-current="true"] { font-weight: 600; cursor: default; }
+.pryv-menu-switch .pryv-menu-note { color: #888; font-size: 12px; }
+`;
+
+/** The built-in menu style, added once. A service's button CSS can override
+ * the `.pryv-menu*` classes. */
+function ensureMenuStyle () {
+  if (document.getElementById('pryv-menu-style') != null) return;
+  const style = document.createElement('style');
+  style.id = 'pryv-menu-style';
+  style.textContent = MENU_CSS;
+  // First in <head>: a service stylesheet loaded before or after the menu
+  // opens then wins at equal specificity.
+  document.head.insertBefore(style, document.head.firstChild);
+}
+
+function menuElement (tag, className, text) {
+  const el = document.createElement(tag);
+  if (className) el.className = className;
+  if (text != null) el.textContent = text;
+  return el;
+}
+
+/**
+ * Build the account menu: a modal dialog, closed by its close button,
+ * Escape, or a click outside it, with focus kept inside while open.
+ * `confirmLogout`: the same dialog reduced to the "Log out?" question, for
+ * `settings.menu: false` (SIGNOUT was already emitted by the click).
+ */
+function buildMenu (loginBtn, confirmLogout) {
+  ensureMenuStyle();
+  const auth = loginBtn.auth;
+  const messages = Object.assign({}, loginBtn.messages, auth.messages);
+  const options = confirmLogout
+    ? { logout: true, account: false, info: false }
+    : menuOptions(loginBtn.authSettings.menu);
+  const username = confirmLogout
+    ? (messages.SIGNOUT_CONFIRM || 'Logout?')
+    : (auth.state?.username || '');
+
+  const overlay = menuElement('div', 'pryv-menu-overlay');
+  const dialog = menuElement('div', 'pryv-menu');
+  // A question that needs an answer is an alertdialog; the menu is a dialog.
+  dialog.setAttribute('role', confirmLogout ? 'alertdialog' : 'dialog');
+  dialog.setAttribute('aria-modal', 'true');
+  dialog.setAttribute('aria-labelledby', 'pryv-menu-username');
+  overlay.appendChild(dialog);
+
+  const header = menuElement('div', 'pryv-menu-header');
+  const title = menuElement('div', 'pryv-menu-username', username || messages.MENU_TITLE);
+  title.id = 'pryv-menu-username';
+  const current = confirmLogout ? null : auth.currentProfile();
+  const actingAs = current?.actingAs;
+  if (actingAs != null) {
+    title.appendChild(menuElement('span', 'pryv-menu-acting',
+      ' (' + messages.ACTING_AS + ', ' + messages.VIA + ' ' + actingAs.delegate + ')'));
+  }
+  header.appendChild(title);
+  const close = menuElement('button', 'pryv-menu-close', '×');
+  close.type = 'button';
+  close.setAttribute('aria-label', messages.CLOSE);
+  close.addEventListener('click', () => loginBtn.closeMenu());
+  header.appendChild(close);
+  dialog.appendChild(header);
+
+  if (options.info) {
+    const serviceName = loginBtn.serviceInfo?.name || '';
+    const appId = loginBtn.authSettings.authRequest.requestingAppId;
+    dialog.appendChild(menuElement('div', 'pryv-menu-info', serviceName + ' · ' + messages.APP + ': ' + appId));
+  }
+
+  const profiles = confirmLogout ? [] : auth.profiles();
+  if (options.switch) {
+    const section = switchSection(loginBtn, messages, current, profiles);
+    if (section != null) dialog.appendChild(section);
+  }
+
+  const actions = menuElement('div', 'pryv-menu-actions');
+  if (options.account && auth.accountUrl() != null) {
+    const manageText = actingAs != null
+      ? (messages.MANAGE_ACCOUNT_OF || '').replace('{username}', current.username)
+      : messages.MANAGE_ACCOUNT;
+    const manage = menuElement('button', 'pryv-menu-account', manageText + ' ');
+    const arrow = menuElement('span', null, '↗');
+    arrow.setAttribute('aria-hidden', 'true');
+    manage.appendChild(arrow);
+    manage.type = 'button';
+    manage.addEventListener('click', () => {
+      auth.openAccountApp();
+      loginBtn.closeMenu();
+    });
+    actions.appendChild(manage);
+  }
+  if (options.logout) {
+    const logout = menuElement('button', 'pryv-menu-logout', messages.LOGOUT);
+    logout.type = 'button';
+    logout.addEventListener('click', () => {
+      loginBtn.closeMenu(true);
+      // Kept on the button (`pending`) so the re-init is awaited by whoever
+      // needs it, never left running unnoticed: a stray re-init would later
+      // consume whatever poll URL the page shows.
+      loginBtn.pending = confirmLogout
+        // SIGNOUT was emitted by the click already (legacy contract).
+        ? loginBtn.deleteAuthorizationData().then(() => auth.init()).then(() => {})
+        : auth.signOut();
+    });
+    if (confirmLogout) {
+      const cancel = menuElement('button', 'pryv-menu-cancel', messages.CANCEL);
+      cancel.type = 'button';
+      cancel.addEventListener('click', () => loginBtn.closeMenu());
+      actions.appendChild(cancel);
+    }
+    actions.appendChild(logout);
+    // "Log out" leaves the other remembered accounts; this one forgets them all
+    if (profiles.length > 1) {
+      const logoutAll = menuElement('button', 'pryv-menu-logout-all', messages.LOGOUT_ALL);
+      logoutAll.type = 'button';
+      logoutAll.addEventListener('click', () => {
+        loginBtn.closeMenu(true);
+        loginBtn.pending = auth.signOut({ all: true });
+      });
+      actions.appendChild(logoutAll);
+    }
+  }
+  dialog.appendChild(actions);
+
+  // Close on a click outside the dialog, not on a text selection that
+  // started inside it and ended outside.
+  let pressedOutside = false;
+  overlay.addEventListener('mousedown', (event) => { pressedOutside = event.target === overlay; });
+  overlay.addEventListener('click', (event) => {
+    if (event.target === overlay && pressedOutside) loginBtn.closeMenu();
+    pressedOutside = false;
+  });
+
+  const focusables = () => Array.from(dialog.querySelectorAll('button'));
+  const onKeyDown = (event) => {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      loginBtn.closeMenu();
+    } else if (event.key === 'Tab') {
+      const list = focusables();
+      if (list.length === 0) return;
+      const first = list[0];
+      const last = list[list.length - 1];
+      const active = document.activeElement;
+      if (event.shiftKey && (active === first || !dialog.contains(active))) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && (active === last || !dialog.contains(active))) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+  };
+  document.addEventListener('keydown', onKeyDown, true);
+
+  return { overlay, dialog, onKeyDown, focusables, previousFocus: document.activeElement, confirmLogout };
+}
+
+/**
+ * The account switcher: "Switch back to <delegate>" while acting for an
+ * account; otherwise the remembered accounts and "Another account..." (when
+ * the platform has account delegation). Null when there is nothing to offer.
+ */
+function switchSection (loginBtn, messages, current, profiles) {
+  const auth = loginBtn.auth;
+  const run = (action) => {
+    loginBtn.closeMenu();
+    loginBtn.pending = action().catch((e) => { console.log('Error while switching account', e); });
+  };
+  const section = menuElement('div', 'pryv-menu-switch');
+  if (current?.actingAs != null) {
+    const back = menuElement('button', 'pryv-menu-switch-back',
+      (messages.SWITCH_BACK || '').replace('{username}', current.actingAs.delegate));
+    back.type = 'button';
+    back.addEventListener('click', () => run(() => auth.switchTo(null)));
+    section.appendChild(back);
+    return section;
+  }
+  const delegation = loginBtn.serviceInfo?.features?.delegation === true;
+  if (profiles.length < 2 && !delegation) return null;
+  section.appendChild(menuElement('div', 'pryv-menu-switch-title', messages.USE_FOR));
+  profiles.forEach((p) => {
+    const item = menuElement('button', 'pryv-menu-profile', p.username + ' ');
+    item.type = 'button';
+    const note = p.actingAs != null
+      ? messages.VIA + ' ' + p.actingAs.delegate
+      : '(' + messages.ME + ')';
+    item.appendChild(menuElement('span', 'pryv-menu-note',
+      note + (p.available ? '' : ' · ' + messages.UNAVAILABLE)));
+    if (p.active) {
+      item.setAttribute('aria-current', 'true');
+    } else {
+      item.addEventListener('click', () => run(() => auth.switchTo(p.username)));
+    }
+    section.appendChild(item);
+  });
+  if (delegation) {
+    const other = menuElement('button', 'pryv-menu-add-account', messages.OTHER_ACCOUNT);
+    other.type = 'button';
+    other.addEventListener('click', () => run(() => auth.addAccount()));
+    section.appendChild(other);
+  }
+  return section;
+}
+
 function setupButton (loginBtn) {
   loginBtn.loginButtonSpan = document.getElementById(loginBtn.authSettings.spanButtonID);
 

package/src/Service.js

@@ -5,6 +5,7 @@
 const utils = require('./utils.js');
 const PryvError = require('./lib/PryvError.js');
 const MfaRequiredError = require('./lib/MfaRequiredError.js');
+const handoff = require('./lib/handoff.js');
 // Connection is required at the end of this file to allow circular requires.
 const Assets = require('./ServiceAssets.js');
 
@@ -537,7 +538,9 @@ class Service {
    *
    * Returns the raw body. Inspect `body.status` to drive the flow:
    *   - `'NEED_SIGNIN'` → user has not interacted yet; keep polling.
-   *   - `'ACCEPTED'`    → `body.apiEndpoint` + `body.username` + `body.token` are set.
+   *   - `'ACCEPTED'`    → `body.apiEndpoint` + `body.username`, plus either
+   *     `body.token` (inline) or a one-time `body.handoff` key (shared-secret
+   *     delivery). Prefer `connectFromKey`, which handles both shapes.
    *   - `'REFUSED'`     → user declined.
    *
    * @param {string} keyOrPollUrl
@@ -573,23 +576,45 @@ class Service {
    * apiEndpoint), and uses this method to build a working `Connection`.
    *
    * The implementation polls `<access>/<key>` once; the call MUST be
-   * made while the access is still in the ACCEPTED state (which
-   * persists until expiry — see `expireAfter` on the access request).
+   * made while the access request is still readable in the ACCEPTED
+   * state. Servers keep a decided request only for a short retention
+   * window after it is first polled (default 2 minutes, operator setting
+   * `access.terminalRetentionMs`), so call this promptly after the flow
+   * completes; afterwards the key is unknown. (`expireAfter` on the
+   * access request is the lifetime of the access created, not of the key.)
+   *
+   * When the request asked for shared-secret delivery the ACCEPTED body
+   * carries a one-time `handoff` key instead of the token; this redeems it
+   * exactly once and caches the result keyed by `key`, so it is safe to call
+   * more than once for the same key (the second call reuses the cache rather
+   * than hitting the already-consumed one-time secret). A retrieve that finds
+   * the secret gone throws a `PryvError` (id `credential-handoff-failed`);
+   * restart the auth request.
    *
    * @param {string} key - polling key from `startAccessRequest`
    * @returns {Promise<Connection>}
    * @throws {PryvError} if the key is not ACCEPTED (NEED_SIGNIN, REFUSED, ERROR)
+   *   or the hand-off secret could not be retrieved
    */
   async connectFromKey (key) {
     if (!key) {
       throw new PryvError('connectFromKey requires a key');
     }
+    // A prior resolve (this call, or the AuthController polling loop) may have
+    // already redeemed the one-time secret; reuse it rather than re-polling.
+    const cached = handoff.cacheGet(key);
+    if (cached != null) return new Connection(cached.apiEndpoint, this);
+
     const body = await this.pollAccessRequest(key);
     if (body.status !== 'ACCEPTED') {
       throw new PryvError(
         'connectFromKey: access is not ACCEPTED (status=' + body.status + ')'
       );
     }
+    if (handoff.isHandoffBody(body)) {
+      const entry = await handoff.resolveHandoff(body, key);
+      return new Connection(entry.apiEndpoint, this);
+    }
     if (!body.apiEndpoint) {
       throw new PryvError(
         'connectFromKey: ACCEPTED response missing apiEndpoint'

package/src/ServiceAssets.js

@@ -132,6 +132,9 @@ class ServiceAssets {
 module.exports = ServiceAssets;
 
 function loadCSS (url) {
+  // Once per page: the controller re-initializes (and reloads assets) on
+  // logout and on a cancelled logout.
+  if (document.getElementById(url) != null) return;
   const head = document.getElementsByTagName('head')[0];
   const link = document.createElement('link');
   link.id = url;

package/src/SharedSecrets.js

@@ -157,7 +157,10 @@ async function retrieve (apiEndpoint, key, options = {}) {
     const err = /** @type {Error & { id?: string, returnUrl?: string }} */ (
       new Error(parsed?.error?.message || 'Shared secret unavailable.')
     );
-    err.id = parsed?.error?.id;
+    // Prefer the fine machine id the method carries in `data.id`
+    // (e.g. `shared-secret-unavailable`) over the coarse HTTP id (`forbidden`),
+    // so a caller can tell a consumed/expired secret from a generic refusal.
+    err.id = parsed?.error?.data?.id || parsed?.error?.id;
     err.returnUrl = parsed?.error?.data?.returnUrl;
     throw err;
   }