pryv 3.12.1 → 3.14.2

package/src/Service.js

@@ -5,6 +5,8 @@
 const utils = require('./utils.js');
 const PryvError = require('./lib/PryvError.js');
 const MfaRequiredError = require('./lib/MfaRequiredError.js');
+const handoff = require('./lib/handoff.js');
+const pollUrls = require('./lib/pollUrls.js');
 // Connection is required at the end of this file to allow circular requires.
 const Assets = require('./ServiceAssets.js');
 
@@ -203,9 +205,8 @@ class Service {
     }
 
     if (!body || !body.token) {
-      throw new PryvError(
-        'Invalid login response: ' + JSON.stringify(body)
-      );
+      // The answer rides on `innerObject`, never in the message (it may hold secrets).
+      throw new PryvError('Invalid login response: no token', body);
     }
     return new Connection(
       Service.buildAPIEndpoint(await this.info(), username, body.token),
@@ -254,9 +255,7 @@ class Service {
     });
     if (!response.ok) throw PryvError.fromApiResponse(response, body);
     if (!body || !body.token) {
-      throw new PryvError(
-        'mfa.verify did not return a token: ' + JSON.stringify(body)
-      );
+      throw new PryvError('mfa.verify did not return a token', body);
     }
     return new Connection(
       Service.buildAPIEndpoint(await this.info(), userId, body.token),
@@ -487,7 +486,9 @@ class Service {
    * @param {string[]} [authRequest.consent.optIn] - ids offered NOT
    *   pre-selected, so the user has to choose them.
    * @param {string} [authRequest.languageCode='en']
-   * @param {string|boolean} [authRequest.returnUrl]
+   * @param {string} [authRequest.returnURL] - URL the auth page returns
+   *   to after the decision, sent as is (the 'auto#' / 'self#' shortcuts
+   *   are resolved only by the sign-in button, not here).
    * @param {string} [authRequest.referer]
    * @param {Object} [authRequest.clientData]
    * @param {string} [authRequest.deviceName]
@@ -510,9 +511,7 @@ class Service {
     );
     if (!response.ok) throw PryvError.fromApiResponse(response, body);
     if (!body || !body.key || !body.poll) {
-      throw new PryvError(
-        'Invalid access-request response: ' + JSON.stringify(body)
-      );
+      throw new PryvError('Invalid access-request response: no key or poll', body);
     }
     const envelope = {
       key: body.key,
@@ -525,19 +524,27 @@ class Service {
     // all-or-nothing, which a caller may want to know before showing the
     // approve link.
     if (body.consent != null) envelope.consent = body.consent;
+    // polling by key (pollAccessRequest, connectFromKey) then reaches the
+    // core that holds the request
+    pollUrls.remember(envelope.key, envelope.poll);
     return envelope;
   }
 
   /**
    * Poll an in-progress access request once. Accepts either:
-   *   - a `key` returned by `startAccessRequest` (poll URL is built from
+   *   - a `key` returned by `startAccessRequest` (polls the poll URL the
+   *     server issued for it when this process started the request, else
    *     `serviceInfo.access + key`)
    *   - a full poll URL (use as-is — recommended, since the server-issued
-   *     URL is canonical and may include a different subdomain).
+   *     URL is canonical and may point at a specific core: on a multi-core
+   *     platform `access + key` can reach a core that does not know the
+   *     request).
    *
    * 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
@@ -550,8 +557,14 @@ class Service {
     }
     let pollUrl = keyOrPollUrl;
     if (!/^https?:\/\//.test(keyOrPollUrl)) {
-      const serviceInfo = await this.info();
-      pollUrl = serviceInfo.access + keyOrPollUrl;
+      // the core-specific URL the server issued, when this process started
+      // the request; `access + key` may reach another core on a multi-core
+      // platform
+      pollUrl = pollUrls.lookup(keyOrPollUrl);
+      if (pollUrl == null) {
+        const serviceInfo = await this.info();
+        pollUrl = serviceInfo.access + keyOrPollUrl;
+      }
     }
     const { response, body } = await utils.fetchGet(pollUrl);
     // 403 with status=REFUSED is the canonical "user declined" terminal
@@ -572,7 +585,9 @@ class Service {
    * `key` returned by the auth-flow (not the underlying token /
    * apiEndpoint), and uses this method to build a working `Connection`.
    *
-   * The implementation polls `<access>/<key>` once; the call MUST be
+   * The implementation polls the request once (at the server-issued poll
+   * URL when this process started it, else `<access>/<key>`, which may
+   * miss the request on a multi-core platform); the call MUST be
    * 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
@@ -580,20 +595,38 @@ class Service {
    * 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;
   }

package/src/index.d.ts

@@ -160,7 +160,8 @@ declare module 'pryv' {
    */
   export class PryvError extends globalThis.Error {
     constructor(message: string, innerObject?: globalThis.Error | object);
-    name: 'PryvError';
+    /** `'PryvError'`, or the subclass name (`'MfaRequiredError'`, ...). */
+    name: string;
     innerObject?: globalThis.Error | object;
     id?: string;
     status?: number;
@@ -684,6 +685,19 @@ declare module 'pryv' {
   export type AccessInfo =  Access & {
     calls: KeyValue;
     user: KeyValue;
+    /**
+     * Present when the access works through account delegation: a delegate
+     * token or an access granted through it (`isDelegatedAccess`, with
+     * `grantedVia: 'app'` for an app access granted by the delegate), or the
+     * control access of a delegation (`kind: 'control'`).
+     */
+    delegation?: {
+      isDelegatedAccess?: true;
+      kind?: 'control';
+      controlledUsername: string;
+      delegate: { username: string; hostSlug?: string };
+      grantedVia?: 'app';
+    };
   }
 
   export type EventAPICallRes = {
@@ -793,12 +807,16 @@ declare module 'pryv' {
     terms: string;
     eventTypes: string;
     version?: string;
+    /** Root URL of the platform's account app, when the platform names one. */
+    account?: string;
     assets?: {
       definitions: string;
     };
     serial?: string;
     features?: {
       noHF?: boolean;
+      /** Account delegation is available on this platform. */
+      delegation?: boolean;
       [key: string]: any;
     };
   };
@@ -874,10 +892,17 @@ declare module 'pryv' {
       /** Echoed only by a core that understood `authRequest.consent`. */
       consent?: AuthRequestConsentForm;
     }>;
+    /**
+     * Poll an access request once, by its full poll URL (recommended) or its
+     * `key`. A key started in this process polls the poll URL the server issued
+     * for it (the core holding the request); an unknown key polls
+     * `access + key`, which may miss the request on a multi-core platform.
+     */
     pollAccessRequest(keyOrPollUrl: string): Promise<any>;
     /**
      * Resolve an auth-flow polling `key` (from {@link Service.startAccessRequest})
-     * into a working {@link Connection}. Polls the access request once; throws a
+     * into a working {@link Connection}. Polls the access request once (as
+     * {@link Service.pollAccessRequest} does with a key); throws a
      * {@link PryvError} unless the access is `ACCEPTED`.
      */
     connectFromKey(key: string): Promise<Connection>;
@@ -964,7 +989,17 @@ declare module 'pryv' {
     | 'NEED_SIGNIN'
     | 'ACCEPTED'
     | 'SIGNOUT'
-    | 'REFUSED';
+    | 'REFUSED'
+    | 'SWITCHING';
+
+  /**
+   * An account remembered by the sign-in button. `actingAs` marks an account
+   * used through account delegation (`delegate`: the person acting).
+   */
+  export type AuthProfile = {
+    username: string;
+    actingAs?: { username: string; delegate: string };
+  };
 
   export type StateChangeTypes = {
     ERROR: {
@@ -991,16 +1026,42 @@ declare module 'pryv' {
       }>;
       consent?: AuthRequestConsentForm;
       requestingAppId: string;
-      returnUrl?: string | null;
+      returnURL?: string | null;
       serviceInfo?: ServiceInfo;
     };
     ACCEPTED: {
       serviceInfo?: ServiceInfo;
       apiEndpoint: string;
       username: string;
+      /** Present on inline delivery; absent when a one-time `handoff` key is used. */
       token?: string;
+      /**
+       * Key of the auth request that just completed (use it with
+       * `connectFromKey`). Absent when the account comes from stored
+       * credentials: page load, an account switch without sign-in, or the
+       * return to the previous account after a switch that did not complete.
+       * Also absent on the return from a sign-in by redirection (`returnURL`,
+       * including `'auto#'` on a phone or tablet): that state carries
+       * `apiEndpoint` with its token instead. Handle both:
+       * `state.key ? connectFromKey(state.key) : new Connection(state.apiEndpoint)`.
+       */
+      key?: string;
+      /** Display hint posted by the auth page for a grant on a controlled account; `accessInfo().delegation` is authoritative. */
+      delegation?: {
+        isDelegatedAccess: true;
+        controlledUsername: string;
+        delegate: { username: string; hostSlug?: string };
+      };
+      profile?: AuthProfile;
+      /** One-time credential hand-off key (shared-secret delivery), in place of `token`. */
+      handoff?: { type: 'shared-secret'; key: string };
     };
     SIGNOUT: {};
+    SWITCHING: {
+      from: string | null;
+      /** null: the account is chosen in the sign-in popup */
+      to: string | null;
+    };
     REFUSED: {
       reasonID?: string;
       message?: string;
@@ -1034,21 +1095,70 @@ declare module 'pryv' {
     serviceInfo?: ServiceInfo;
   };
 
+  /**
+   * Account menu entries of the sign-in button. `false` on an entry, or its
+   * name in `hide`, hides it.
+   */
+  export type LoginButtonMenuSettings = {
+    logout?: boolean;
+    account?: boolean;
+    info?: boolean;
+    /** Account switcher (remembered accounts, "Another account...", "Switch back"). */
+    switch?: boolean;
+    hide?: Array<'logout' | 'account' | 'info' | 'switch'>;
+  };
+
   export type AuthSettings = {
     spanButtonID?: string;
     onStateChange?: (state: StateChange<States>) => void;
-    returnURL?: string;
+    /**
+     * Account menu shown when the signed-in button is clicked (default: on).
+     * `false` restores the plain logout confirmation.
+     */
+    menu?: LoginButtonMenuSettings | false;
+    /** Root URL of the account app; overrides the service's `account`. */
+    accountUrl?: string;
+    /** Most accounts remembered for this app (default 5); the least recently used is forgotten first. */
+    maxProfiles?: number;
     authRequest: {
       requestingAppId: string;
       languageCode?: string;
       requestedPermissions: AuthRequestedPermission[];
       consent?: AuthRequestConsent;
-      returnUrl?: string | boolean;
+      /**
+       * Where the sign-in happens: `'auto#'` (default, also when unset or
+       * `false`) opens a popup on desktop and redirects on a phone or tablet;
+       * `'self#'` always redirects and comes back to the current page; a URL
+       * always redirects and comes back to that URL. Must end with `#`, `?`
+       * or `&`.
+       */
+      returnURL?: string | false;
+      /**
+       * Your own auth page for this request (query parameters allowed, e.g. a
+       * `username` hint or `backUrl` / `backLabel`). The platform honours it
+       * only when it matches one of its `access:trustedAuthUrls` entries and
+       * refuses the request otherwise; unset, the platform's default auth page
+       * is used.
+       */
+      authUrl?: string;
       referer?: string;
       clientData?: KeyValue;
       deviceName?: string;
       expireAfter?: number;
+      /**
+       * Credential delivery mode. Defaults to `'shared-secret'`: the token is
+       * delivered through a one-time secret instead of the ACCEPTED poll, and
+       * `connectFromKey` redeems it. `'inline'` opts out (no field sent, legacy
+       * inline delivery). An older core ignores the field and delivers inline.
+       */
+      credentialHandoff?: 'shared-secret' | 'inline';
       serviceInfo?: Partial<ServiceInfo>;
+      /**
+       * Whether the sign-in may grant the access for an account the user
+       * controls through account delegation: 'allow' (server default),
+       * 'deny', or the username to preselect.
+       */
+      actAs?: 'allow' | 'deny' | string;
     };
   };
 
@@ -1072,6 +1182,7 @@ declare module 'pryv' {
     AUTHORIZED: 'ACCEPTED';
     SIGNOUT: 'SIGNOUT';
     REFUSED: 'REFUSED';
+    SWITCHING: 'SWITCHING';
   };
 
   type AuthStatePayload = {
@@ -1080,9 +1191,25 @@ declare module 'pryv' {
     error?: Error | unknown;
   };
 
-  export type StoredAuthorizationData = {
+  /** A remembered account as stored (credentials included). */
+  export type StoredAuthProfile = AuthProfile & {
     apiEndpoint: string;
-    username: string;
+    unavailable?: true;
+  };
+
+  /**
+   * Stored sign-in data. The top-level `apiEndpoint` / `username` are the
+   * active account (absent after logging out of one of several accounts);
+   * `profiles` lists every remembered account, most recently used first.
+   * The default button stores the two parts in two cookies.
+   */
+  export type StoredAuthorizationData = {
+    apiEndpoint?: string;
+    username?: string;
+    actingAs?: AuthProfile['actingAs'];
+    /** Auth page of the sign-in (without query), kept to locate the account app. */
+    authUrl?: string;
+    profiles?: StoredAuthProfile[];
   } | null;
 
   export type CustomLoginButton = {
@@ -1093,6 +1220,12 @@ declare module 'pryv' {
     saveAuthorizationData?: (authData: StoredAuthorizationData) => void;
     deleteAuthorizationData?: () => Promise<void>;
     finishAuthProcessAfterRedirection?: (authController: AuthController) => Promise<void>;
+    /**
+     * Called when the signed-in button is clicked. Return `false` to fall
+     * back to the SIGNOUT state (logout confirmation); log out from the menu
+     * with `AuthController.signOut()`.
+     */
+    showMenu?: () => boolean | void;
   };
 
   export class LoginButton implements CustomLoginButton {
@@ -1115,6 +1248,11 @@ declare module 'pryv' {
     saveAuthorizationData(authData: StoredAuthorizationData): void;
     deleteAuthorizationData(): Promise<void>;
     finishAuthProcessAfterRedirection(authController: AuthController): Promise<void>;
+    showMenu(): boolean;
+    /** Resolves when the re-initialization it may start (a dismissed "Log out?") is done. */
+    closeMenu(): Promise<void>;
+    /** The re-initialization started by the last menu action, if any. */
+    pending?: Promise<void>;
   }
 
   export class AuthController {
@@ -1136,11 +1274,34 @@ declare module 'pryv' {
     stopAuthRequest(msg: string): void;
     handleClick(): Promise<void>;
     getReturnURL(
-      returnURL?: string,
+      returnURL?: string | false,
       windowLocationForTest?: string,
-      navigatorForTests?: string,
+      navigatorForTests?: string | Navigator,
     ): string | boolean;
-    startAuthRequest(): Promise<AuthRequestResponse>;
+    /** `overrides`: auth request fields for this request only; `previous`: state to return to if an account switch does not complete. */
+    startAuthRequest(overrides?: Partial<AuthSettings['authRequest']>, previous?: AuthStatePayload): Promise<AuthRequestResponse>;
+    /**
+     * Log out: emits SIGNOUT once, forgets the active account (every
+     * remembered account with `all`), re-initializes.
+     */
+    signOut(options?: { all?: boolean }): Promise<void>;
+    /** The remembered accounts, most recently used first. */
+    profiles(): Array<AuthProfile & { active: boolean; available: boolean }>;
+    /** The signed-in account, or null. */
+    currentProfile(): AuthProfile | null;
+    /**
+     * Switch account (`null`: the signed-in person's own account). A
+     * remembered account with a valid access needs no sign-in; otherwise the
+     * auth request runs again with `actAs`. Emits SWITCHING, ends in ACCEPTED,
+     * or back on the previous account when the sign-in is refused.
+     */
+    switchTo(username: string | null): Promise<void>;
+    /** Sign in to one more account (`actAs: 'allow'`), keeping the remembered ones. */
+    addAccount(): Promise<void>;
+    /** Account app profile URL, or null when it cannot be determined. */
+    accountUrl(): string | null;
+    /** Opens the account app in a new tab; returns the URL, or null. */
+    openAccountApp(): string | null;
     set state(newState: AuthStatePayload);
     get state(): AuthStatePayload;
   }

package/src/lib/handoff.js

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * Credential hand-off (shared-secret delivery) support for the auth-request
+ * flow.
+ *
+ * When an access request set `credentialHandoff: 'shared-secret'`, the ACCEPTED
+ * poll body carries a one-time `handoff.key` and a token-less `apiEndpoint`
+ * instead of the token. This module redeems that key ONCE against the user's
+ * core (`shared-secrets/retrieve`, no credentials needed) and turns the result
+ * into a token-bearing apiEndpoint the rest of the library already understands.
+ *
+ * A module-level cache keyed by the auth-flow poll key holds the result for a
+ * short TTL: `pryv.connectFromKey(key, ...)` builds a fresh `Service` on every
+ * call and the `AuthController` polling loop also reads the ACCEPTED body, so
+ * without a shared cache the one-shot secret would be redeemed twice and the
+ * second read would fail. Whoever redeems first fills the cache; the others
+ * reuse it.
+ */
+
+const utils = require('../utils');
+const SharedSecrets = require('../SharedSecrets');
+const PryvError = require('./PryvError');
+
+/** How long a redeemed credential stays cached (10 min, or until sign-out). */
+const TTL_MS = 10 * 60 * 1000;
+
+/** poll key -> { apiEndpoint, username, token, expiresAt } */
+const cache = new Map();
+/** poll key -> Promise, so concurrent resolves for one key redeem once. */
+const inflight = new Map();
+
+function cacheGet (key) {
+  if (key == null) return null;
+  const entry = cache.get(key);
+  if (entry == null) return null;
+  if (Date.now() > entry.expiresAt) {
+    cache.delete(key);
+    return null;
+  }
+  return entry;
+}
+
+/** Drop expired entries so cached tokens do not linger for the process
+ * lifetime in a long-running Node service (a browser page is short-lived, but
+ * the same module runs server-side too). Called on every set; the map holds
+ * one entry per in-flight sign-in, so the scan is trivially small. */
+function sweep () {
+  const now = Date.now();
+  for (const [k, entry] of cache) {
+    if (now > entry.expiresAt) cache.delete(k);
+  }
+}
+
+function cacheSet (key, value) {
+  if (key == null) return;
+  sweep();
+  cache.set(key, Object.assign({}, value, { expiresAt: Date.now() + TTL_MS }));
+}
+
+/** Drop one entry (sign-out). Passing no key is an explicit clear-all. */
+function cacheClear (key) {
+  if (arguments.length === 0) cache.clear();
+  else cache.delete(key);
+}
+
+/** Does an ACCEPTED poll body deliver by shared-secret hand-off? */
+function isHandoffBody (body) {
+  return body != null && body.handoff != null &&
+    body.handoff.type === 'shared-secret' && typeof body.handoff.key === 'string';
+}
+
+/**
+ * Redeem a hand-off poll body into a token-bearing apiEndpoint, caching the
+ * result under `cacheKey`. Throws a `PryvError` (id `credential-handoff-failed`)
+ * telling the caller to restart the auth request when the one-time secret is
+ * gone (already redeemed, expired) or the retrieve fails.
+ *
+ * @param {Object} pollBody an ACCEPTED body carrying `apiEndpoint` + `handoff.key`
+ * @param {string} [cacheKey] the auth-flow poll key, so a repeat resolve reuses this
+ * @returns {Promise<{ apiEndpoint: string, username: string, token: string }>}
+ */
+async function resolveHandoff (pollBody, cacheKey) {
+  const cached = cacheGet(cacheKey);
+  if (cached != null) return cached;
+  // De-duplicate concurrent redemptions of the same key (e.g. React
+  // StrictMode double-invoking an effect that calls connectFromKey twice):
+  // both would otherwise miss the cache and the second would 403 the
+  // already-consumed one-time secret.
+  if (cacheKey != null && inflight.has(cacheKey)) return inflight.get(cacheKey);
+
+  const promise = doResolve(pollBody, cacheKey);
+  if (cacheKey == null) return promise;
+  inflight.set(cacheKey, promise);
+  try {
+    return await promise;
+  } finally {
+    inflight.delete(cacheKey);
+  }
+}
+
+async function doResolve (pollBody, cacheKey) {
+  let result;
+  try {
+    result = await SharedSecrets.retrieve(pollBody.apiEndpoint, pollBody.handoff.key);
+  } catch (err) {
+    const pe = new PryvError(
+      'Credential hand-off could not be retrieved (' +
+        (err && (err.id || err.message)) + '); restart the auth request.',
+      err
+    );
+    // Stable id for callers that branch on the hand-off failure; the finer
+    // reason (`shared-secret-unavailable`) rides on `innerObject.id`, which
+    // `SharedSecrets.retrieve` now takes from the refusal's `data.id`.
+    pe.id = 'credential-handoff-failed';
+    throw pe;
+  }
+
+  const secret = (result && result.secret) || {};
+  if (typeof secret.token !== 'string' || typeof secret.apiEndpoint !== 'string') {
+    const pe = new PryvError('Credential hand-off returned an incomplete secret.');
+    pe.id = 'credential-handoff-failed';
+    throw pe;
+  }
+
+  // The secret's apiEndpoint may be token-less or token-bearing; rebuild a
+  // canonical token-bearing endpoint from the authoritative `token` so the
+  // rest of the library (Connection, the LoginButton cookie) is unchanged.
+  const { endpoint } = utils.extractTokenAndAPIEndpoint(secret.apiEndpoint);
+  const apiEndpoint = utils.buildAPIEndpoint({ endpoint, token: secret.token });
+  const entry = { apiEndpoint, username: secret.username, token: secret.token };
+  cacheSet(cacheKey, entry);
+  return entry;
+}
+
+module.exports = { resolveHandoff, isHandoffBody, cacheGet, cacheSet, cacheClear };

package/src/lib/pollUrls.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * The poll URL the server issued for each auth request started in this
+ * process, by key.
+ *
+ * A pending auth request lives on the core that created it, and its poll URL
+ * points at that core. The service's `access` URL may reach any core of a
+ * multi-core platform, so polling `access + key` can land on a core that does
+ * not know the request. Polling by key therefore uses the server-issued URL
+ * when this process started the request, and falls back to `access + key`
+ * only for a key it never saw.
+ *
+ * Keys are long random server values, so one process-wide map (like the
+ * hand-off cache) serves every Service.
+ */
+
+/** Most entries kept (oldest dropped first), sized for a busy Node service. */
+const MAX_ENTRIES = 1000;
+/** How long an entry is kept: well beyond any auth request's lifetime. */
+const TTL_MS = 60 * 60 * 1000;
+
+/** key -> { pollUrl, expiresAt }, in insertion order */
+const pollUrls = new Map();
+
+/** Drop expired entries (called on every remember). */
+function sweep () {
+  const now = Date.now();
+  for (const [key, entry] of pollUrls) {
+    if (now > entry.expiresAt) pollUrls.delete(key);
+  }
+}
+
+/**
+ * Remember the poll URL of an auth request (ignored unless both look valid).
+ * @param {string} key
+ * @param {string} pollUrl
+ */
+function remember (key, pollUrl) {
+  if (typeof key !== 'string' || key === '' || typeof pollUrl !== 'string' || !/^https?:\/\//.test(pollUrl)) return;
+  sweep();
+  pollUrls.delete(key);
+  pollUrls.set(key, { pollUrl, expiresAt: Date.now() + TTL_MS });
+  while (pollUrls.size > MAX_ENTRIES) pollUrls.delete(pollUrls.keys().next().value);
+}
+
+/**
+ * The server-issued poll URL of `key`, or null when this process did not
+ * start that request (or it expired).
+ * @param {string} key
+ * @returns {string|null}
+ */
+function lookup (key) {
+  const entry = pollUrls.get(key);
+  if (entry == null) return null;
+  if (Date.now() > entry.expiresAt) {
+    pollUrls.delete(key);
+    return null;
+  }
+  return entry.pollUrl;
+}
+
+/** Forget every entry. */
+function clear () {
+  pollUrls.clear();
+}
+
+module.exports = { remember, lookup, clear, MAX_ENTRIES, TTL_MS };