pryv 3.13.0 → 3.15.0

package/README.md

@@ -131,6 +131,13 @@ Here is an implementation of the [Pryv.io authentication process](https://api.pr
           optIn: ['location']      // offered UNticked; the user opts in
           // a permission in neither list is optional and shown pre-selected
         },
+        // optional (core 2.0.0-rc.32+): cross-account messaging invites the
+        // user answers in the same sign-in (1 to 8). The ACCEPTED state then
+        // carries `cmcInvites`, one outcome per invite ({ acceptEventId, ... },
+        // { declined: true } or { reason }), a hint: the requester learns the
+        // truth from its own inbox. Declining a mandatory one refuses the sign-in
+        // (REFUSED, reasonId 'REFUSED_MANDATORY_CONSENT'). Ignored by older cores.
+        // cmcInvites: [{ capabilityUrl: invite.capabilityUrl, mandatory: true }],
         clientData: {
           'app-web-auth:description': {
             'type': 'note/txt', 'content': 'This is a consent message.'
@@ -607,7 +614,7 @@ The [authentication process](https://api.pryv.com/reference/#authenticate-your-a
 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.
+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, and an `error` (with an `id` such as `'unexpected-auth-return'` when available); a click on the button in `ERROR` starts over.
 
 ```js
 async onStateChange (state) {
@@ -732,6 +739,8 @@ For a more advanced scenario, you can check the default button implementation in
 
 There is a possibility that you would like to register the user in another page. You can find an example [here](https://github.com/pryv/lib-js/blob/master/examples/auth-with-redirection.html), and try it running [there](https://api.pryv.com/lib-js/examples/auth-with-redirection.html). Again, to run these examples locally, see below.
 
+Set `authRequest.returnURL`: `'self#'` always redirects and comes back to the current page, `'auto#'` (the default) opens a popup on desktop and redirects on a phone or tablet, and a URL always redirects and comes back to that URL. Before leaving, the button keeps the auth request it started in `sessionStorage`; on the way back it finishes only that request, in the same tab and on the same origin, and any other return ends in `ERROR` with `error.id` `'unexpected-auth-return'` (or keeps the account the page is already signed in to). If your app starts the auth request itself (`Service.startAccessRequest`) and comes back to a page with the button, finish the sign-in yourself: poll the `poll` URL the request returned with `Service.pollAccessRequest(pollUrl)`. `Service.connectFromKey(key)` reaches the right core only within the page load (or Node process) that started the request, or after the button finished a redirect sign-in it started; after your own redirect (the page reloads) on a multi-core platform, pass the poll URL instead, since a key alone may reach a core that does not hold the request.
+
 
 ### Running examples locally
 

package/package.json

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

package/src/Auth/AuthController.js

@@ -7,6 +7,8 @@ const AuthStates = require('./AuthStates');
 const Messages = require('./LoginMessages');
 const ProfileStore = require('./ProfileStore');
 const handoff = require('../lib/handoff');
+const pollUrls = require('../lib/pollUrls');
+const PryvError = require('../lib/PryvError');
 
 /**
  * Controller for authentication flow
@@ -143,6 +145,9 @@ class AuthController {
       this.startAuthRequest();
     } else if (this.state.status === AuthStates.SWITCHING) {
       // a switch is running; its outcome arrives as a state change
+    } else if (this.state.status === AuthStates.ERROR) {
+      // start over (stored sign-in or the sign-in button) rather than stay inert
+      await this.init();
     } else if (isNeedSignIn.call(this)) {
       // reopen popup (HACK for now: set to private property to avoid self-assignment)
       this.state = this._state;
@@ -270,7 +275,7 @@ class AuthController {
       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));
+        throw new PryvError('Cannot check the access of ' + target.username + ': ' + (info?.error?.id ?? 'unexpected answer'), info?.error);
       }
       // revoked or expired (a detach revokes the accesses granted through it)
       this._saveProfiles(ProfileStore.markUnavailable(this._readProfiles(), target.username));
@@ -350,9 +355,9 @@ class AuthController {
   /**
    * Compute the return URL for authentication redirect.
    * Used only in browser environments.
-   * @param {string} [returnURL] - The return URL setting ('auto#', 'self#', or custom URL)
+   * @param {string|false} [returnURL] - The return URL setting ('auto#', 'self#', or custom URL)
    * @param {string} [windowLocationForTest] - Mock window.location.href for testing
-   * @param {string|Navigator} [navigatorForTests] - Mock navigator for testing
+   * @param {string|Navigator} [navigatorForTests] - Mock navigator for testing (defaults to the browser's own)
    * @returns {string|boolean} The computed return URL, or false if using popup mode
    */
   getReturnURL (
@@ -361,6 +366,7 @@ class AuthController {
     navigatorForTests
   ) {
     const RETURN_URL_AUTO = 'auto';
+    const nav = navigatorForTests ?? globalThis.navigator;
 
     returnURL = returnURL || RETURN_URL_AUTO + '#';
 
@@ -372,11 +378,11 @@ class AuthController {
     }
     // auto mode for desktop
     if (returnUrlIsAuto(returnURL) &&
-        !utils.browserIsMobileOrTablet(navigatorForTests)) {
+        !utils.browserIsMobileOrTablet(nav)) {
       return false;
     // auto mode for mobile or self
     } else if ((returnUrlIsAuto(returnURL) &&
-                utils.browserIsMobileOrTablet(navigatorForTests)) ||
+                utils.browserIsMobileOrTablet(nav)) ||
                returnURL.indexOf('self') === 0) {
       // set self as return url?
       // eventually clean-up current url from previous pryv returnURL
@@ -410,6 +416,8 @@ class AuthController {
     // state can be handed `{ key, serviceInfo? }` (the polling response
     // itself doesn't echo `key` back).
     this._authFlowKey = this.state?.key;
+    // an app's later connectFromKey(key) then polls the core holding the request
+    pollUrls.remember(this.state?.key, this.state?.poll);
     // Kept to locate the account app when the service does not name it.
     if (this.state?.authUrl) this._authUrl = this.state.authUrl;
 
@@ -425,7 +433,9 @@ class AuthController {
           Object.assign({}, this.settings.authRequest, overrides)
         );
         if (!response.ok) {
-          throw new Error('Access request failed: ' + JSON.stringify(body));
+          // The server's message, id and status; the body stays on `response`,
+          // never in the message (it echoes the request's permissions and data).
+          throw PryvError.fromApiResponse(response, body);
         }
         return body;
       } catch (e) {
@@ -476,6 +486,7 @@ class AuthController {
             const previous = this._switchPrevious;
             // @ts-ignore - this is bound via .call()
             this._switchPrevious = null;
+            if (previous != null) console.warn('pryv: account switch did not complete (credential hand-off failed); keeping the previous account');
             this.state = previous ?? { status: AuthStates.ERROR, message: 'Credential hand-off failed', error: e };
             return;
           }
@@ -494,6 +505,8 @@ class AuthController {
           pollResponse.profile = ProfileStore.fromAccepted(pollResponse);
         } else if (previous != null) {
           // an account switch that did not complete: stay on the previous account
+          console.warn('pryv: account switch did not complete (' +
+            (pollResponse?.error?.id ?? pollResponse?.message ?? pollResponse?.status) + '); keeping the previous account');
           this.state = previous;
           return;
         }
@@ -598,18 +611,30 @@ async function checkAutoLogin (authController) {
     return;
   }
 
-  const storedCredentials = await loginButton.getAuthorizationData();
+  let storedCredentials = await loginButton.getAuthorizationData();
   if (storedCredentials == null) return;
+  // Forget the stored sign-ins that carry no token (3.13.0 saved some after a
+  // redirect return): they would sign in to a session the API refuses, or
+  // stay listed as available accounts.
+  const stored = ProfileStore.read(storedCredentials);
+  const tokenless = stored.profiles.filter((p) => !ProfileStore.carriesToken(p.apiEndpoint));
+  if (tokenless.length > 0) {
+    authController._saveProfiles(tokenless.reduce((s, p) => ProfileStore.remove(s, p.username), stored));
+    storedCredentials = await loginButton.getAuthorizationData();
+    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;
+    if (store.active == null || !ProfileStore.carriesToken(store.active.apiEndpoint)) 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;
   }
+  // a button that cannot rewrite its storage still must not sign in to it
+  if (typeof storedCredentials.apiEndpoint === 'string' && !ProfileStore.carriesToken(storedCredentials.apiEndpoint)) 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;

package/src/Auth/ProfileStore.js

@@ -23,9 +23,27 @@ module.exports = {
   remove,
   markUnavailable,
   profileOf,
-  fromAccepted
+  fromAccepted,
+  carriesToken
 };
 
+const utils = require('../utils');
+
+/**
+ * Whether an apiEndpoint carries a token. A stored sign-in without one
+ * cannot call the API (3.13.0 saved such sign-ins after a redirect return,
+ * the credential hand-off not being redeemed).
+ * @param {string} apiEndpoint
+ * @returns {boolean}
+ */
+function carriesToken (apiEndpoint) {
+  try {
+    return Boolean(utils.extractTokenAndAPIEndpoint(apiEndpoint).token);
+  } catch (e) {
+    return false;
+  }
+}
+
 /**
  * Parse stored authorization data (any version) into
  * `{ active, profiles, authUrl }`; `active` is `profiles[0]` or null.

package/src/Auth/index.js

@@ -26,11 +26,14 @@ module.exports = {
  * @param {string} [settings.authRequest.languageCode] Language code, as per LoginButton Messages: 'en', 'fr
  * @param {string} settings.authRequest.requestingAppId Application id, ex: 'my-app'
  * @param {Object} settings.authRequest.requestedPermissions
- * @param {string | boolean} settings.authRequest.returnURL : false, // set this if you don't want a popup
+ * @param {string | false} [settings.authRequest.returnURL] 'auto#' (default, also when unset or false):
+ *   popup on desktop, redirect on a phone or tablet; 'self#': always redirect back to this page;
+ *   a URL: always redirect back to that URL. Must end with '#', '?' or '&'.
+ * @param {string} [settings.authRequest.authUrl] Your own auth page for this request; honoured only
+ *   when it matches the platform's `access:trustedAuthUrls`
  * @param {string} [settings.authRequest.referer] To track registration source
  * @param {string} settings.spanButtonID set and <span> id in DOM to insert default login button or null for custom
  * @param {Function} settings.onStateChange
- * @param {string} [settings.returnURL] Set to "self#" to disable popup and force using the same page
  * @param {string} serviceInfoUrl
  * @param {Object} [serviceCustomizations] override properties of serviceInfoUrl
  * @returns {Promise<Service>}

package/src/Browser/LoginButton.js

@@ -7,6 +7,8 @@ const AuthStates = require('../Auth/AuthStates');
 const AuthController = require('../Auth/AuthController');
 const ProfileStore = require('../Auth/ProfileStore');
 const Messages = require('../Auth/LoginMessages');
+const handoff = require('../lib/handoff');
+const pollUrls = require('../lib/pollUrls');
 const utils = require('../utils');
 
 /* global location */
@@ -63,6 +65,10 @@ class LoginButton {
       case AuthStates.NEED_SIGNIN: {
         const loginUrl = state.authUrl || state.url; // url is deprecated
         if (this.authSettings.authRequest.returnURL) { // open on same page (no Popup)
+          // Remember the request this page started: on the way back, only
+          // its key is accepted and only its (server-issued) poll URL is
+          // fetched (see finishAuthProcessAfterRedirection).
+          writeAuthFlow(this._cookieKey, { key: state.key, poll: state.poll, authUrl: loginUrl });
           location.href = loginUrl;
           return;
         } else {
@@ -73,6 +79,9 @@ class LoginButton {
       case AuthStates.AUTHORIZED: {
         const profile = state.profile || ProfileStore.fromAccepted(state);
         this.text = profileLabel(this, profile);
+        // Never remember a sign-in that cannot call the API (it would be
+        // restored on every page load).
+        if (!ProfileStore.carriesToken(profile?.apiEndpoint)) break;
         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;
@@ -219,46 +228,147 @@ class LoginButton {
     // 3. Check if there is a pryvKey / pryvPoll (or legacy prYvkey /
     //    prYvpoll) as result of "out of page login"
     const url = window.location.href;
-    const pollUrl = retrievePollUrl(url);
-    if (pollUrl !== null) {
+    const key = retrieveKey(url);
+    if (key !== null) {
+      // Already signed in (from the stored sign-in): a return that does not
+      // end in a new sign-in (an account switch refused or failed, a stray
+      // link) leaves that account in place, as the popup path does for a
+      // switch. The state is then left as it is (no second AUTHORIZED).
+      const signedIn = authController.state?.status === AuthStates.AUTHORIZED;
+      // Only finish the auth request this page started (kept across the
+      // redirect by onStateChange), and poll the URL the server gave for
+      // it: a link carrying another key or poll URL must not sign the page
+      // in (to a foreign host, or to someone else's account).
+      const flow = readAuthFlow(this._cookieKey);
+      if (flow == null || flow.key !== key || typeof flow.poll !== 'string') {
+        console.warn('pryv: ignoring a sign-in return for a request this page did not start');
+        if (!signedIn) {
+          authController.state = {
+            status: AuthStates.ERROR,
+            message: 'Sign-in return does not match a sign-in started on this page',
+            error: { id: 'unexpected-auth-return' }
+          };
+        }
+        cleanUrl();
+        return;
+      }
+      clearAuthFlow(this._cookieKey);
+      const pollUrl = flow.poll;
+      // an app's connectFromKey(key) on this page then polls the same core
+      pollUrls.remember(key, pollUrl);
+      // the flow of this sign-in: a sign-out clears its cached credential
+      authController._authFlowKey = key;
+      let response, body;
       try {
-        const { body } = await utils.fetchGet(pollUrl);
-        if (body?.status === AuthStates.AUTHORIZED && typeof body.username === 'string') body.profile = ProfileStore.fromAccepted(body);
-        authController.state = body;
+        ({ response, body } = await utils.fetchGet(pollUrl));
       } catch (e) {
-        authController.state = {
+        body = {
           status: AuthStates.ERROR,
           message: 'Cannot fetch result',
           error: e
         };
       }
-      // These params are one-shot; leaving them in the visible URL puts
-      // stale auth state into bookmarks / copied links.
+      if (response?.status === 403 && body?.status === 'REFUSED') {
+        // refused on the auth page: back to the sign-in button (as the popup path)
+        body = { status: AuthStates.INITIALIZED, serviceInfo: authController.serviceInfo };
+      } else if (body?.status == null) {
+        // unknown or expired key, or no answer the button can show
+        body = { status: AuthStates.ERROR, message: 'Cannot fetch result', error: body?.error ?? body };
+      }
+      // Shared-secret delivery: the ACCEPTED body carries a one-time
+      // `handoff` key, not the token. Redeem it exactly as the polling path
+      // does, under the flow key, and never report a token-less AUTHORIZED.
+      // Unlike the polling path, the state keeps its legacy shape (no `key`,
+      // credentials included), which existing redirect apps read.
+      if (handoff.isHandoffBody(body)) {
+        try {
+          const entry = await handoff.resolveHandoff(body, key);
+          body.apiEndpoint = entry.apiEndpoint;
+          body.token = entry.token;
+          body.username = entry.username;
+          delete body.handoff;
+        } catch (e) {
+          body = { status: AuthStates.ERROR, message: 'Credential hand-off failed', error: e };
+        }
+      }
+      if (body?.status === AuthStates.AUTHORIZED && typeof body.username === 'string') {
+        body.profile = ProfileStore.fromAccepted(body);
+        // the auth page of this sign-in locates the account app
+        if (typeof flow.authUrl === 'string') authController._authUrl = flow.authUrl;
+      } else if (signedIn) {
+        // refused or failed: stay on the account already signed in
+        console.warn('pryv: sign-in by redirection did not complete (' +
+          (body?.error?.id ?? body?.message ?? body?.status) + '); keeping the signed-in account');
+        cleanUrl();
+        return;
+      }
+      authController.state = body;
+      cleanUrl();
+    } else if (utils.cleanURLFromPrYvParams(url) !== url) {
+      // leftover one-shot params without a key (e.g. only `prYvstatus`)
+      cleanUrl();
+    }
+
+    // These params are one-shot; leaving them in the visible URL puts
+    // stale auth state into bookmarks / copied links.
+    function cleanUrl () {
       if (window.history && typeof window.history.replaceState === 'function') {
         window.history.replaceState(null, '', utils.cleanURLFromPrYvParams(url));
       }
     }
 
-    function retrievePollUrl (url) {
+    /** The key of the returning auth request, or null when the URL is not a return. */
+    function retrieveKey (url) {
       // Modern lowercase form (pryvKey / pryvPoll) is preferred; the
       // capital-Y form (prYvkey / prYvpoll) is accepted for back-compat
       // with apps emitting the legacy URL contract — see
       // [DEPRECATED] notes on cleanURLFromPrYvParams.
       const params = utils.getQueryParamsFromURL(url);
-      let pollUrl = null;
       const key = params.pryvKey || params.prYvkey;
-      if (key) {
-        pollUrl = authController.serviceInfo.access + key;
-      }
+      if (key) return key;
       const poll = params.pryvPoll || params.prYvpoll;
-      if (poll) {
-        pollUrl = poll;
-      }
-      return pollUrl;
+      // the poll URL ends with the key (`<access>/<key>`); only the key is
+      // used, the poll URL fetched is the one stored when the flow started
+      if (poll) return poll.split(/[?#]/)[0].split('/').filter(Boolean).pop() || null;
+      return null;
     }
   }
 }
 
+// ---- the auth request started by this page, kept across the redirect ----
+// sessionStorage: per tab and origin, gone when the tab closes, readable by
+// no other origin. Any failure (storage blocked) reads as "no flow".
+
+function authFlowStorageKey (cookieKey) {
+  return cookieKey + '-authflow';
+}
+
+function writeAuthFlow (cookieKey, flow) {
+  try {
+    window.sessionStorage.setItem(authFlowStorageKey(cookieKey), JSON.stringify(flow));
+  } catch (e) {
+    // the return will then be refused, as for any unknown request
+  }
+}
+
+function readAuthFlow (cookieKey) {
+  try {
+    const raw = window.sessionStorage.getItem(authFlowStorageKey(cookieKey));
+    const flow = raw == null ? null : JSON.parse(raw);
+    return flow != null && typeof flow === 'object' ? flow : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+function clearAuthFlow (cookieKey) {
+  try {
+    window.sessionStorage.removeItem(authFlowStorageKey(cookieKey));
+  } catch (e) {
+    // nothing stored
+  }
+}
+
 module.exports = LoginButton;
 
 async function startLoginScreen (loginButton, authUrl) {

package/src/Connection.js

@@ -116,7 +116,10 @@ class Connection {
    * @param {Object|Array} [params={}] - The params associated with this method
    * @param {string} [expectedKey] - If given, returns the value of this key or throws an error if not present
    * @returns {Promise<Object>} Promise resolving to the API result or the value of expectedKey
-   * @throws {Error} If .error is present in the response or expectedKey is missing
+   * @throws {Error} If .error is present in the response or expectedKey is missing.
+   *   The message names the method and the server's error id and message; the full
+   *   error (or result) is on `innerObject`. The call's params are never in the message:
+   *   they can carry passwords and tokens, and error messages end up in logs and on screen.
    */
   async apiOne (method, params = {}, expectedKey) {
     const result = await this.api([{ method, params }]);
@@ -125,11 +128,18 @@ class Connection {
       result[0].error ||
       (expectedKey != null && result[0][expectedKey] == null)
     ) {
-      const innerObject = result[0]?.error || result;
+      const error = result[0]?.error;
+      const innerObject = error || result;
+      let reason;
+      if (error) {
+        reason = [error.id, error.message].filter((v) => v != null && v !== '').join(': ') || 'error answer';
+      } else if (result[0] == null) {
+        reason = 'no result';
+      } else {
+        reason = `"${expectedKey}" missing in result`;
+      }
       throw new PryvError(
-        `Error for api method: "${method}" with params: ${JSON.stringify(
-          params
-        )} >> Result: ${JSON.stringify(innerObject)}"`,
+        `Error for api method: "${method}" >> ${reason}`,
         innerObject
       );
     }
@@ -197,17 +207,13 @@ class Connection {
         });
       }
       const resRequest = await callHandler(thisBatch);
-      // result checks
+      // result checks: the answer rides on `innerObject`, never in the message
+      // (results can hold tokens, e.g. from accesses.*)
       if (!resRequest || !Array.isArray(resRequest.results)) {
-        throw new Error(
-          'API call result is not an Array: ' + JSON.stringify(resRequest)
-        );
+        throw new PryvError('API call result is not an Array', resRequest);
       }
       if (resRequest.results.length !== thisBatch.length) {
-        throw new Error(
-          'API call result Array does not match request: ' +
-            JSON.stringify(resRequest)
-        );
+        throw new PryvError('API call result Array does not match request', resRequest);
       }
 
       // eventually call handleResult

package/src/Service.js

@@ -6,6 +6,7 @@ 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');
 
@@ -204,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),
@@ -255,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),
@@ -488,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]
@@ -511,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,
@@ -526,15 +524,23 @@ 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;
+    // Same for consent invites: echoed only by a core that understood them.
+    if (body.cmcInvites != null) envelope.cmcInvites = body.cmcInvites;
+    // 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.
@@ -553,8 +559,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
@@ -575,7 +587,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