pryv 3.15.0 → 3.16.0

package/README.md

@@ -607,14 +607,15 @@ getAuthorizationData () {
 The [authentication process](https://api.pryv.com/reference/#authenticate-your-app) implementation on the frontend can go through the following states:
 
 1. `LOADING`: while the visual assets are loading
-2. `INITIALIZED`: visuals assets are loaded, or when [polling](https://api.pryv.com/reference/#poll-request) concludes with **Result: Refused**
+2. `INITIALIZED`: visuals assets are loaded, or right after `REFUSED` (the button is back to its sign-in state)
 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`: 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
+5. `REFUSED`: when [polling](https://api.pryv.com/reference/#poll-request) concludes with **Result: Refused**; carries the auth page's `reasonId` (e.g. `'REFUSED_BY_USER'`, or `'REFUSED_MANDATORY_CONSENT'` when a mandatory consent was declined), its `message` and `serviceInfo`, and is followed by `INITIALIZED`. A refused account switch returns to the previous account instead (see `SWITCHING`)
+6. `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`)
+7. `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
+8. `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, and an `error` (with an `id` such as `'unexpected-auth-return'` when available); a click on the button in `ERROR` starts over.
+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), except that an `AUTHORIZED` reached through the popup hands the app `{ status, id, key, serviceInfo?, cmcInvites?, delegation? }` (credentials through `connectFromKey(key)`). `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) {

package/package.json

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

package/src/Auth/AuthController.js

@@ -9,6 +9,7 @@ const ProfileStore = require('./ProfileStore');
 const handoff = require('../lib/handoff');
 const pollUrls = require('../lib/pollUrls');
 const PryvError = require('../lib/PryvError');
+const { refusedState, unreadableAnswerState } = require('./pollOutcome');
 
 /**
  * Controller for authentication flow
@@ -26,7 +27,8 @@ class AuthController {
     validateSettings.call(this, settings);
 
     this.stateChangeListeners = [];
-    // External `onStateChange` callers only see `{ status, id, key, serviceInfo? }`
+    // External `onStateChange` callers only see
+    // `{ status, id, key, serviceInfo?, cmcInvites?, delegation? }`
     // on AUTHORIZED — credentials (`username`, `token`, `apiEndpoint`) stay
     // inside the lib. Internal listeners (e.g. LoginButton, for cookie
     // autologin) get the full unfiltered state.
@@ -142,12 +144,35 @@ class AuthController {
       }
       this.state = { status: AuthStates.SIGNOUT };
     } else if (isInitialized.call(this)) {
-      this.startAuthRequest();
+      // Not awaited (the click returns at once), so the rejection is handled
+      // here. A failed request is already the state (ERROR, or the previous
+      // account). A failure in the first poll round leaves NEED_SIGNIN: it
+      // becomes ERROR, as in the later rounds (a click-started request is
+      // never an account switch). Any other failure is logged rather than lost.
+      const started = this.startAuthRequest();
+      // startAuthRequest begins a new flow synchronously: this is its id
+      const flowId = this._authFlowId;
+      started.catch((e) => {
+        const status = this.state?.status;
+        if (status === AuthStates.NEED_SIGNIN && this._authFlowId === flowId) {
+          this.state = { status: AuthStates.ERROR, message: 'Error while polling for auth request', error: e };
+        } else if (status !== AuthStates.ERROR && status !== AuthStates.AUTHORIZED) {
+          console.warn('pryv: sign-in request failed', e);
+        }
+      });
     } 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();
+      try {
+        await this.init();
+      } catch (e) {
+        // failed before reaching a usable state: show it, as a failed request does
+        if (this.state.status === AuthStates.LOADING) {
+          this.state = { status: AuthStates.ERROR, message: 'Initializing', error: e };
+        }
+        throw e;
+      }
     } else if (isNeedSignIn.call(this)) {
       // reopen popup (HACK for now: set to private property to avoid self-assignment)
       this.state = this._state;
@@ -159,7 +184,9 @@ class AuthController {
       return this.state.status === AuthStates.AUTHORIZED;
     }
     function isInitialized () {
-      return this.state.status === AuthStates.INITIALIZED;
+      // REFUSED is followed by INITIALIZED in the same dispatch: a click
+      // from a listener in between is a click on the reset button
+      return this.state.status === AuthStates.INITIALIZED || this.state.status === AuthStates.REFUSED;
     }
     function isNeedSignIn () {
       return this.state.status === AuthStates.NEED_SIGNIN;
@@ -426,11 +453,15 @@ class AuthController {
     /** @this {AuthController} */
     async function postAccess () {
       try {
+        // @ts-ignore - this is bound via .call()
+        const request = Object.assign({}, this.settings.authRequest, overrides);
+        // A core refuses `actAsManagedOnly` with `actAs: 'deny'`, which a
+        // switch back to the signed-in account sends.
+        if (request.actAs === 'deny') delete request.actAsManagedOnly;
         const { response, body } = await utils.fetchPost(
           // @ts-ignore - this is bound via .call()
           this.serviceInfo.access,
-          // @ts-ignore - this is bound via .call()
-          Object.assign({}, this.settings.authRequest, overrides)
+          request
         );
         if (!response.ok) {
           // The server's message, id and status; the body stays on `response`,
@@ -464,8 +495,17 @@ class AuthController {
       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);
+        // A later round has no caller to reject to: its failure becomes the
+        // state, as a poll that cannot reach the server does.
+        setTimeout(() => {
+          doPolling.call(this).catch((e) => {
+            if (this._authFlowId !== flowId) return;
+            const previous = this._switchPrevious;
+            this._switchPrevious = null;
+            if (previous != null) console.warn('pryv: account switch did not complete (polling failed); keeping the previous account');
+            this.state = previous ?? { status: AuthStates.ERROR, message: 'Error while polling for auth request', error: e };
+          });
+        }, 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
@@ -509,16 +549,26 @@ class AuthController {
             (pollResponse?.error?.id ?? pollResponse?.message ?? pollResponse?.status) + '); keeping the previous account');
           this.state = previous;
           return;
+        } else if (pollResponse.status === AuthStates.REFUSED) {
+          // Refused on the auth page (403): tell the listeners why, then
+          // return to the sign-in button.
+          this.state = refusedState(pollResponse, this.serviceInfo);
+          // a listener started over (new request, sign-out, re-initialization)
+          // @ts-ignore - this is bound via .call()
+          if (this._authFlowId !== flowId) return;
+          this.state = { status: AuthStates.INITIALIZED, serviceInfo: this.serviceInfo };
+          return;
         }
         this.state = pollResponse;
       }
 
       async function pollAccess (pollUrl) {
         try {
-          const { response, body } = await utils.fetchGet(pollUrl);
-          if (response.status === 403 && body?.status === 'REFUSED') {
-            return { status: AuthStates.INITIALIZED };
-          }
+          // a REFUSED answer (403) is handled by the caller like any other body
+          const { body } = await utils.fetchGet(pollUrl);
+          // unknown or expired key, a server error body, no body: ERROR, as
+          // the redirect path (never a state without a status)
+          if (body?.status == null) return unreadableAnswerState(body);
           return body;
         } catch (e) {
           return { status: AuthStates.ERROR, message: 'Error while polling for auth request', error: e };
@@ -559,7 +609,8 @@ class AuthController {
 
 /**
  * Narrow the state passed to *external* `onStateChange` callers so the
- * calling app sees only `{ status, id, key, serviceInfo? }` on the
+ * calling app sees only `{ status, id, key, serviceInfo?, cmcInvites?,
+ * delegation? }` on the
  * terminal AUTHORIZED state reached through the auth-flow polling path.
  * `username` / `token` / `apiEndpoint` are kept inside the lib; the
  * calling app uses `pryv.connectFromKey(key, serviceInfoUrl)` to obtain
@@ -570,6 +621,10 @@ class AuthController {
  * existing pages that build a `Connection` directly from the restored
  * state on page load keep working.
  *
+ * `cmcInvites` (the auth page's outcome for each invite: event and access
+ * ids, or why not) and `delegation` (a display hint) carry no credential
+ * and are kept when present.
+ *
  * Non-AUTHORIZED states pass through unchanged so error messages /
  * loading flags / etc. still reach the listener.
  *
@@ -586,6 +641,8 @@ function filterForExternalListener (state) {
   }
   const out = { status: state.status, id: state.id, key: state.key };
   if (state.serviceInfo != null) out.serviceInfo = state.serviceInfo;
+  if (state.cmcInvites != null) out.cmcInvites = state.cmcInvites;
+  if (state.delegation != null) out.delegation = state.delegation;
   return out;
 }
 

package/src/Auth/pollOutcome.js

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+const AuthStates = require('./AuthStates');
+
+/**
+ * States built from the answer to an auth-request poll, shared by the popup
+ * (AuthController) and the redirect (LoginButton) paths so both emit the
+ * same shapes.
+ */
+module.exports = {
+  refusedState,
+  unreadableAnswerState
+};
+
+/**
+ * The REFUSED state for a refused auth request: the core's `reasonId`
+ * (e.g. `REFUSED_BY_USER`, `REFUSED_MANDATORY_CONSENT`) and `message`, with
+ * the service info. Nothing else of the answer is kept.
+ * @param {Object} body - the poll answer (`status: 'REFUSED'`)
+ * @param {Object} [serviceInfo]
+ * @returns {Object}
+ */
+function refusedState (body, serviceInfo) {
+  return { status: AuthStates.REFUSED, reasonId: body?.reasonId, message: body?.message, serviceInfo };
+}
+
+/**
+ * The ERROR state for a poll answer without a `status` (unknown or expired
+ * key, a server error body, no body): nothing the sign-in button can show.
+ * @param {Object} [body] - the poll answer
+ * @returns {Object}
+ */
+function unreadableAnswerState (body) {
+  return { status: AuthStates.ERROR, message: 'Cannot fetch result', error: body?.error ?? body };
+}

package/src/Browser/LoginButton.js

@@ -6,6 +6,7 @@ const Cookies = require('./CookieUtils');
 const AuthStates = require('../Auth/AuthStates');
 const AuthController = require('../Auth/AuthController');
 const ProfileStore = require('../Auth/ProfileStore');
+const { refusedState, unreadableAnswerState } = require('../Auth/pollOutcome');
 const Messages = require('../Auth/LoginMessages');
 const handoff = require('../lib/handoff');
 const pollUrls = require('../lib/pollUrls');
@@ -51,7 +52,11 @@ class LoginButton {
   }
 
   onClick () {
-    this.auth.handleClick();
+    // A click handler has no caller to reject to: a failure is shown as the
+    // ERROR state; anything else is logged rather than left unhandled.
+    Promise.resolve(this.auth.handleClick()).catch((e) => {
+      if (this.auth.state?.status !== AuthStates.ERROR) console.warn('pryv: sign-in button click failed', e);
+    });
   }
 
   async onStateChange (state) {
@@ -107,6 +112,9 @@ class LoginButton {
       case AuthStates.ERROR:
         this.text = getErrorMessage(this, state.message);
         break;
+      case AuthStates.REFUSED:
+        // followed by INITIALIZED, which resets the button
+        break;
       default:
         console.log('WARNING Unhandled state for Login: ' + state.status);
     }
@@ -258,9 +266,9 @@ class LoginButton {
       pollUrls.remember(key, pollUrl);
       // the flow of this sign-in: a sign-out clears its cached credential
       authController._authFlowKey = key;
-      let response, body;
+      let body;
       try {
-        ({ response, body } = await utils.fetchGet(pollUrl));
+        ({ body } = await utils.fetchGet(pollUrl));
       } catch (e) {
         body = {
           status: AuthStates.ERROR,
@@ -268,12 +276,21 @@ class LoginButton {
           error: e
         };
       }
-      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) {
+      if (body?.status === AuthStates.REFUSED && !signedIn) {
+        // Refused on the auth page (403): tell the listeners why, then back
+        // to the sign-in button (as the popup path).
+        const flowId = authController._authFlowId;
+        authController.state = refusedState(body, authController.serviceInfo);
+        // unless a listener started over (new request, sign-out, re-initialization)
+        if (authController._authFlowId === flowId) {
+          authController.state = { status: AuthStates.INITIALIZED, serviceInfo: authController.serviceInfo };
+        }
+        cleanUrl();
+        return;
+      }
+      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 };
+        body = unreadableAnswerState(body);
       }
       // Shared-secret delivery: the ACCEPTED body carries a one-time
       // `handoff` key, not the token. Redeem it exactly as the polling path

package/src/Connection.js

@@ -411,7 +411,7 @@ class Connection {
   /**
    * Create an event with attached file
    * NODE.jS ONLY
-   * @param {Event} event
+   * @param {PryvEvent} event
    * @param {string} filePath
    */
   async createEventWithFile (event, filePath) {
@@ -458,7 +458,7 @@ class Connection {
   /**
    * Create an event with attached formData
    * !! BROWSER ONLY
-   * @param {Event} event
+   * @param {PryvEvent} event
    * @param {FormData} formData https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData
    */
   async createEventWithFormData (event, formData) {

package/src/Service.js

@@ -493,9 +493,12 @@ class Service {
    * @param {Object} [authRequest.clientData]
    * @param {string} [authRequest.deviceName]
    * @param {number} [authRequest.expireAfter]
-   * @returns {Promise<{ key: string, authUrl: string, poll: string, pollRateMs: number, consent?: Object }>}
-   *   `consent` is echoed back only by a core that understood the
-   *   annotations, which is how you detect support.
+   * @param {boolean} [authRequest.actAsManagedOnly] - true: the access must
+   *   be granted for an account the user manages; requires `actAs: 'allow'`
+   *   or a username.
+   * @returns {Promise<{ key: string, authUrl: string, poll: string, pollRateMs: number, consent?: Object, cmcInvites?: Array<Object>, actAsManagedOnly?: true }>}
+   *   `consent`, `cmcInvites` and `actAsManagedOnly` are echoed back only by
+   *   a core that understood them, which is how you detect support.
    * @throws {PryvError} on non-2xx
    */
   async startAccessRequest (authRequest) {
@@ -526,6 +529,9 @@ class Service {
     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;
+    // Echoed only by a core that understood `actAsManagedOnly`: an older core
+    // drops the field, and the auth page then behaves per `actAs` alone.
+    if (body.actAsManagedOnly === true) envelope.actAsManagedOnly = true;
     // polling by key (pollAccessRequest, connectFromKey) then reaches the
     // core that holds the request
     pollUrls.remember(envelope.key, envelope.poll);

package/src/globals.d.ts

@@ -11,10 +11,8 @@ declare global {
   type TokenAndEndpoint = PryvModule.TokenAndAPIEndpoint;
 
   // Core classes (for JSDoc @param {Connection} etc.)
-  interface Connection extends PryvModule.Connection {
-    socket?: any;
-    _chunkedBatchCall?: any;
-  }
+  // `socket` comes from the @pryv/socket.io augmentation of `Connection`
+  type Connection = PryvModule.Connection;
   type Service = PryvModule.Service;
   type ServiceInfo = PryvModule.ServiceInfo;
   type ServiceAssets = PryvModule.ServiceAssets;
@@ -32,7 +30,8 @@ declare global {
   type AccessInfo = PryvModule.AccessInfo & { error?: PryvModule.Error };
   type HFSeriesAddResult = PryvModule.HFSeriesAddResult;
   type APICall = PryvModule.APICall;
-  type Event = PryvModule.Event;
+  // not `Event`: that name is the DOM event (lib.dom)
+  type PryvEvent = PryvModule.Event;
   type Stream = PryvModule.Stream;
 
   // Method call type for socket.io

package/src/index.d.ts

@@ -893,6 +893,11 @@ declare module 'pryv' {
       consent?: AuthRequestConsentForm;
       /** Echoed only by a core that understood `authRequest.cmcInvites`. */
       cmcInvites?: AuthCmcInvite[];
+      /**
+       * Echoed (`true`) only by a core that understood
+       * `authRequest.actAsManagedOnly`; absent otherwise.
+       */
+      actAsManagedOnly?: true;
     }>;
     /**
      * Poll an access request once, by its full poll URL (recommended) or its
@@ -995,6 +1000,13 @@ declare module 'pryv' {
     capabilityUrl: string;
     mandatory?: boolean;
     for?: 'self' | 'target';
+    /**
+     * Name of the data grant the user mints when accepting the invite (1 to
+     * 256 characters); unset, the grant takes the platform's default name.
+     * Requires a core that supports it: an older core refuses the whole
+     * request with `400 invalid-parameters`.
+     */
+    accessName?: string;
   };
 
   /** An invite as the core echoes it back, with its defaults filled in. */
@@ -1002,6 +1014,8 @@ declare module 'pryv' {
     capabilityUrl: string;
     mandatory: boolean;
     for: 'self' | 'target';
+    /** Present only when the invite was sent with an `accessName`. */
+    accessName?: string;
   };
 
   /**
@@ -1058,14 +1072,23 @@ declare module 'pryv' {
       consent?: AuthRequestConsentForm;
       /** Present only when the request carried `cmcInvites` the core understood. */
       cmcInvites?: AuthCmcInvite[];
+      /** Present only when the request carried `actAsManagedOnly: true` and the core understood it. */
+      actAsManagedOnly?: true;
       requestingAppId: string;
       returnURL?: string | null;
       serviceInfo?: ServiceInfo;
     };
     ACCEPTED: {
       serviceInfo?: ServiceInfo;
-      apiEndpoint: string;
-      username: string;
+      /**
+       * Present only when the account comes from stored credentials or from
+       * the return of a sign-in by redirection (the states without `key`).
+       * The state an `onStateChange` listener receives after a popup sign-in
+       * carries `key` instead: use `connectFromKey(key, serviceInfoUrl)`.
+       */
+      apiEndpoint?: string;
+      /** Present only when `apiEndpoint` is (see above). */
+      username?: string;
       /** Present on inline delivery; absent when a one-time `handoff` key is used. */
       token?: string;
       /**
@@ -1097,8 +1120,16 @@ declare module 'pryv' {
       /** null: the account is chosen in the sign-in popup */
       to: string | null;
     };
+    /**
+     * The auth request was refused on the auth page; followed by
+     * INITIALIZED (the sign-in button resets).
+     */
     REFUSED: {
-      reasonID?: string;
+      /**
+       * Why, as set by the auth page, e.g. `'REFUSED_BY_USER'`,
+       * `'REFUSED_MANDATORY_CONSENT'` or `'MANDATORY_CONSENT_FAILED'`.
+       */
+      reasonId?: string;
       message?: string;
       serviceInfo?: ServiceInfo;
     };
@@ -1125,6 +1156,7 @@ declare module 'pryv' {
     requestedPermissions: AuthRequestedPermission[];
     consent?: AuthRequestConsentForm;
     cmcInvites?: AuthCmcInvite[];
+    actAsManagedOnly?: true;
     lang?: string;
     returnURL?: string;
     clientData?: KeyValue;
@@ -1202,6 +1234,17 @@ declare module 'pryv' {
        * 'deny', or the username to preselect.
        */
       actAs?: 'allow' | 'deny' | string;
+      /**
+       * `true`: the access must be granted for an account the user manages
+       * through account delegation, never for the signed-in account itself.
+       * Requires `actAs: 'allow'` or a username (a core refuses it with
+       * `actAs: 'deny'` or without `actAs`). The sign-in button leaves it out
+       * of any request it sends with `actAs: 'deny'` (a switch back to the
+       * signed-in account sends it); `Service.startAccessRequest` sends it as given.
+       * Enforced by the auth page, not the core. An older core drops the
+       * field and does not echo it (see `Service.startAccessRequest`).
+       */
+      actAsManagedOnly?: boolean;
     };
   };
 

package/test/AuthController.pollOutcome.test.js

@@ -0,0 +1,404 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, beforeEach, afterEach, expect */
+
+const AuthController = require('../src/Auth/AuthController');
+const AuthStates = require('../src/Auth/AuthStates');
+const utils = require('../src/utils');
+
+/**
+ * [APLX] What the popup (polling) path delivers to the app's onStateChange
+ * when the auth request ends. No platform needed: the access POST and the
+ * poll GET are stubbed.
+ */
+describe('[APLX] AuthController popup poll outcome', function () {
+  const SERVICE_INFO = { access: 'https://reg.test.local/access/', name: 'Test' };
+  const POLL = 'https://core-a.test.local/reg/access/plk1';
+  let saved;
+  let pollBody;
+  let pollStatus;
+
+  beforeEach(() => {
+    saved = { fetchPost: utils.fetchPost, fetchGet: utils.fetchGet };
+    utils.fetchPost = async () => ({
+      response: { ok: true, status: 201 },
+      body: { status: 'NEED_SIGNIN', key: 'plk1', poll: POLL, poll_rate_ms: 5, authUrl: 'https://ui.test.local/auth?key=plk1' }
+    });
+    utils.fetchGet = async () => ({ response: { ok: pollStatus < 400, status: pollStatus }, body: pollBody });
+  });
+
+  afterEach(() => {
+    utils.fetchPost = saved.fetchPost;
+    utils.fetchGet = saved.fetchGet;
+  });
+
+  /** A controller past init(): INITIALIZED, as the sign-in button shows it. */
+  function makeAuth (onStateChange) {
+    const auth = new AuthController({
+      onStateChange,
+      authRequest: { requestingAppId: 'apl-app', requestedPermissions: [], credentialHandoff: 'inline' }
+    }, { infoSync: () => SERVICE_INFO });
+    auth.serviceInfo = SERVICE_INFO;
+    auth.state = { status: AuthStates.INITIALIZED, serviceInfo: SERVICE_INFO };
+    return auth;
+  }
+
+  it('[APL1] a refused request emits REFUSED with the reasonId and message, then INITIALIZED', async () => {
+    pollStatus = 403;
+    pollBody = { status: 'REFUSED', reasonId: 'REFUSED_MANDATORY_CONSENT', message: 'A mandatory consent was declined' };
+    const seen = [];
+    const auth = makeAuth((s) => seen.push(s));
+    await auth.startAuthRequest();
+
+    expect(seen.map((s) => s.status)).to.deep.equal(['INITIALIZED', 'NEED_SIGNIN', 'REFUSED', 'INITIALIZED']);
+    // the core's answer, nothing more (no key of the refused request)
+    expect(seen[2]).to.deep.equal({
+      status: 'REFUSED',
+      id: 'REFUSED',
+      reasonId: 'REFUSED_MANDATORY_CONSENT',
+      message: 'A mandatory consent was declined',
+      serviceInfo: SERVICE_INFO
+    });
+    expect(seen[3]).to.deep.equal({ status: 'INITIALIZED', id: 'INITIALIZED', serviceInfo: SERVICE_INFO });
+  });
+
+  it('[APL2] after a refusal the button is back to its initial state: a click starts a new request', async () => {
+    pollStatus = 403;
+    pollBody = { status: 'REFUSED', reasonId: 'REFUSED_BY_USER', message: 'access refused by user' };
+    const auth = makeAuth(() => {});
+    await auth.startAuthRequest();
+    expect(auth.state.status).to.equal(AuthStates.INITIALIZED);
+
+    let started = 0;
+    auth.startAuthRequest = async () => { started++; };
+    await auth.handleClick();
+    expect(started).to.equal(1);
+  });
+
+  it('[APL3] a listener that starts over on REFUSED is not overridden by the reset', async () => {
+    pollStatus = 403;
+    pollBody = { status: 'REFUSED', reasonId: 'REFUSED_BY_USER' };
+    let auth = null;
+    auth = makeAuth((s) => {
+      if (s.status === 'REFUSED') auth.stopAuthRequest('stopped by the app');
+    });
+    await auth.startAuthRequest();
+    expect(auth.state.status).to.equal(AuthStates.ERROR);
+    expect(auth.state.message).to.equal('stopped by the app');
+  });
+
+  it('[APL4] an account switch that is refused keeps the previous account', async () => {
+    pollStatus = 403;
+    pollBody = { status: 'REFUSED', reasonId: 'REFUSED_BY_USER' };
+    const seen = [];
+    const auth = makeAuth((s) => seen.push(s.status));
+    const previous = { status: AuthStates.AUTHORIZED, username: 'bob', apiEndpoint: 'https://tb@bob.test.local/' };
+    const warn = console.warn;
+    console.warn = () => {};
+    try {
+      await auth.startAuthRequest({ actAs: 'allow' }, previous);
+    } finally {
+      console.warn = warn;
+    }
+    expect(auth.state.status).to.equal(AuthStates.AUTHORIZED);
+    expect(auth.state.username).to.equal('bob');
+    expect(seen.slice(-2)).to.deep.equal(['NEED_SIGNIN', 'ACCEPTED']);
+  });
+
+  it('[APL5] ACCEPTED keeps cmcInvites and delegation for the app; the credentials stay inside', async () => {
+    pollStatus = 200;
+    const cmcInvites = [
+      { acceptEventId: 'evt-1', dataGrantAccessId: 'acc-1' },
+      { declined: true },
+      { acceptEventId: 'evt-3', acceptedFor: 'self' }
+    ];
+    const delegation = { isDelegatedAccess: true, controlledUsername: 'kim', delegate: { username: 'alice' } };
+    pollBody = { status: 'ACCEPTED', username: 'kim', token: 'tok-kim', apiEndpoint: 'https://tok-kim@kim.test.local/', cmcInvites, delegation };
+    const seen = [];
+    const auth = makeAuth((s) => seen.push(s));
+    await auth.startAuthRequest();
+
+    const accepted = seen[seen.length - 1];
+    expect(accepted).to.deep.equal({ status: 'ACCEPTED', id: 'ACCEPTED', key: 'plk1', cmcInvites, delegation });
+    expect(auth.state.token).to.equal('tok-kim');
+  });
+
+  it('[APL7] a switch back to the signed-in account sends no actAsManagedOnly (it sends actAs: \'deny\')', async () => {
+    pollStatus = 403;
+    pollBody = { status: 'REFUSED', reasonId: 'REFUSED_BY_USER' };
+    const posted = [];
+    utils.fetchPost = async (url, body) => {
+      posted.push(body);
+      return {
+        response: { ok: true, status: 201 },
+        body: { status: 'NEED_SIGNIN', key: 'plk1', poll: POLL, poll_rate_ms: 5, authUrl: 'https://ui.test.local/auth?key=plk1' }
+      };
+    };
+    const auth = new AuthController({
+      onStateChange: () => {},
+      authRequest: { requestingAppId: 'apl-app', requestedPermissions: [], credentialHandoff: 'inline', actAs: 'allow', actAsManagedOnly: true }
+    }, { infoSync: () => SERVICE_INFO });
+    auth.serviceInfo = SERVICE_INFO;
+    auth.state = { status: AuthStates.AUTHORIZED, username: 'kim', apiEndpoint: 'https://tk@kim.test.local/', profile: { username: 'kim', actingAs: { username: 'kim', delegate: 'alice' } } };
+    const warn = console.warn;
+    console.warn = () => {};
+    try {
+      await auth.switchTo(null);
+      // the other requests keep it: one more account, or a managed account by name
+      await auth.addAccount();
+      await auth.startAuthRequest({ actAs: 'kim' });
+    } finally {
+      console.warn = warn;
+    }
+    expect(posted).to.have.lengthOf(3);
+    expect(posted[0].actAs).to.equal('deny');
+    expect(posted[0]).to.not.have.property('actAsManagedOnly');
+    expect(posted[1].actAs).to.equal('allow');
+    expect(posted[1].actAsManagedOnly).to.equal(true);
+    expect(posted[2].actAs).to.equal('kim');
+    expect(posted[2].actAsManagedOnly).to.equal(true);
+    // the app's settings are left untouched
+    expect(auth.settings.authRequest.actAsManagedOnly).to.equal(true);
+  });
+
+  /** Runs `fn`, then collects the promise rejections nobody handled. */
+  async function unhandledDuring (fn) {
+    const saved = process.listeners('unhandledRejection');
+    process.removeAllListeners('unhandledRejection');
+    const seen = [];
+    const onUnhandled = (reason) => seen.push(reason);
+    process.on('unhandledRejection', onUnhandled);
+    try {
+      await fn();
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    } finally {
+      process.removeListener('unhandledRejection', onUnhandled);
+      saved.forEach((l) => process.on('unhandledRejection', l));
+    }
+    return seen;
+  }
+
+  it('[APL8] a click whose access request fails shows ERROR and leaves no unhandled rejection', async () => {
+    utils.fetchPost = async () => ({
+      response: { ok: false, status: 500 },
+      body: { error: { id: 'unexpected-error', message: 'boom' } }
+    });
+    const seen = [];
+    const auth = makeAuth((s) => seen.push(s.status));
+    const unhandled = await unhandledDuring(() => auth.handleClick());
+    expect(unhandled).to.deep.equal([]);
+    expect(auth.state.status).to.equal(AuthStates.ERROR);
+    expect(auth.state.message).to.equal('Requesting access');
+    expect(seen).to.deep.equal(['INITIALIZED', 'ERROR']);
+  });
+
+  /** Runs `fn` with `console[method]` captured; returns the captured calls. */
+  async function captured (method, fn) {
+    const original = console[method];
+    const calls = [];
+    console[method] = (...args) => calls.push(args);
+    try {
+      await fn();
+    } finally {
+      console[method] = original;
+    }
+    return calls;
+  }
+
+  /** A controller on ERROR whose re-initialization fails with `failure`. */
+  function failingReinit (failure) {
+    const loginButton = {
+      onStateChange () {},
+      getAuthorizationData () { throw failure; }
+    };
+    const auth = new AuthController({
+      authRequest: { requestingAppId: 'apl-app', requestedPermissions: [], credentialHandoff: 'inline' }
+    }, { infoSync: () => SERVICE_INFO, assets: async () => ({}) }, loginButton);
+    auth.state = { status: AuthStates.ERROR, message: 'Requesting access' };
+    return auth;
+  }
+
+  it('[APL9] a click on ERROR whose re-initialization fails shows ERROR and rejects for an awaiting caller', async () => {
+    const failure = new Error('storage unavailable');
+    const auth = failingReinit(failure);
+    let rejected = null;
+    await auth.handleClick().catch((e) => { rejected = e; });
+    expect(rejected).to.equal(failure);
+    expect(auth.state.status).to.equal(AuthStates.ERROR);
+    expect(auth.state.message).to.equal('Initializing');
+    expect(auth.state.error).to.equal(failure);
+  });
+
+  it('[APL10] the sign-in button click leaves no unhandled rejection and no warning when the failure is shown as ERROR', async () => {
+    const LoginButton = require('../src/Browser/LoginButton');
+    const auth = failingReinit(new Error('storage unavailable'));
+    let unhandled;
+    const warned = await captured('warn', async () => {
+      unhandled = await unhandledDuring(() => LoginButton.prototype.onClick.call({ auth }));
+    });
+    expect(unhandled).to.deep.equal([]);
+    expect(warned).to.deep.equal([]);
+    expect(auth.state.status).to.equal(AuthStates.ERROR);
+  });
+
+  it('[APL11] the sign-in button click logs any other failure instead of leaving it unhandled', async () => {
+    const LoginButton = require('../src/Browser/LoginButton');
+    const failure = new Error('unexpected');
+    const auth = { state: { status: AuthStates.INITIALIZED }, handleClick: async () => { throw failure; } };
+    let unhandled;
+    const warned = await captured('warn', async () => {
+      unhandled = await unhandledDuring(() => LoginButton.prototype.onClick.call({ auth }));
+    });
+    expect(unhandled).to.deep.equal([]);
+    expect(warned).to.have.lengthOf(1);
+    expect(warned[0][1]).to.equal(failure);
+  });
+
+  it('[APL12] a click whose request fails unexpectedly (state neither ERROR nor the previous account) is logged', async () => {
+    const failure = new Error('unexpected');
+    const NEED_SIGNIN = { status: AuthStates.NEED_SIGNIN, key: 'k', poll: POLL, poll_rate_ms: 5 };
+    const outcomes = [
+      { set: null, warns: 1, ends: AuthStates.INITIALIZED }, // nothing shows it
+      { set: { status: AuthStates.ERROR, message: 'Requesting access' }, warns: 0, ends: AuthStates.ERROR },
+      { set: { status: AuthStates.AUTHORIZED, username: 'bob', apiEndpoint: 'https://tb@bob.test.local/' }, warns: 0, ends: AuthStates.AUTHORIZED },
+      // the request failed while polling: shown as ERROR
+      { set: NEED_SIGNIN, warns: 0, ends: AuthStates.ERROR },
+      // a newer request is the one waiting for the sign-in: left alone
+      { set: NEED_SIGNIN, newer: true, warns: 1, ends: AuthStates.NEED_SIGNIN }
+    ];
+    for (const outcome of outcomes) {
+      const auth = makeAuth(() => {});
+      auth.startAuthRequest = async () => {
+        await null; // the click has read the flow id by now
+        if (outcome.newer) auth._authFlowId++;
+        if (outcome.set != null) auth.state = { ...outcome.set };
+        throw failure;
+      };
+      let unhandled;
+      const label = (outcome.set?.status ?? 'INITIALIZED') + (outcome.newer ? ' (newer)' : '');
+      const warned = await captured('warn', async () => {
+        unhandled = await unhandledDuring(() => auth.handleClick());
+      });
+      expect(unhandled).to.deep.equal([]);
+      expect(warned.length, 'warnings with ' + label).to.equal(outcome.warns);
+      if (outcome.warns > 0) expect(warned[0][1]).to.equal(failure);
+      expect(auth.state.status, 'state with ' + label).to.equal(outcome.ends);
+      if (outcome.ends === AuthStates.ERROR && outcome.set === NEED_SIGNIN) {
+        expect(auth.state.message).to.equal('Error while polling for auth request');
+        expect(auth.state.error).to.equal(failure);
+      }
+    }
+  });
+
+  it('[APL16] a click whose first poll round fails ends in ERROR, as the later rounds do', async () => {
+    const handoff = require('../src/lib/handoff');
+    const failure = new Error('unexpected');
+    const isHandoffBody = handoff.isHandoffBody;
+    pollStatus = 200;
+    pollBody = { status: 'ACCEPTED', username: 'alice', apiEndpoint: 'https://tok@alice.test.local/' };
+    // AuthController calls handoff.isHandoffBody on the module object at call
+    // time, so replacing the property makes the round throw after the answer.
+    handoff.isHandoffBody = () => { throw failure; };
+    const seen = [];
+    const auth = makeAuth((s) => seen.push(s.status));
+    let unhandled;
+    let warned;
+    try {
+      warned = await captured('warn', async () => {
+        unhandled = await unhandledDuring(() => auth.handleClick());
+      });
+    } finally {
+      handoff.isHandoffBody = isHandoffBody;
+    }
+    expect(unhandled).to.deep.equal([]);
+    expect(warned).to.deep.equal([]);
+    expect(seen).to.deep.equal(['INITIALIZED', 'NEED_SIGNIN', 'ERROR']);
+    expect(auth.state.message).to.equal('Error while polling for auth request');
+    expect(auth.state.error).to.equal(failure);
+  });
+
+  it('[APL13] a click from a listener on REFUSED starts a new request (no "Unhandled action", no reset over it)', async () => {
+    pollStatus = 403;
+    pollBody = { status: 'REFUSED', reasonId: 'REFUSED_BY_USER' };
+    const seen = [];
+    let auth = null;
+    let clicked = false;
+    auth = makeAuth((s) => {
+      seen.push(s.status);
+      if (s.status === 'REFUSED' && !clicked) {
+        clicked = true;
+        // the new request is accepted
+        pollStatus = 200;
+        pollBody = { status: 'ACCEPTED', username: 'alice', token: 'tok', apiEndpoint: 'https://tok@alice.test.local/' };
+        auth.handleClick();
+      }
+    });
+    const logged = await captured('log', async () => {
+      await auth.startAuthRequest();
+      for (let i = 0; i < 50 && auth.state.status !== AuthStates.AUTHORIZED; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      }
+    });
+    expect(logged.filter((args) => String(args[0]).includes('Unhandled action'))).to.deep.equal([]);
+    expect(seen).to.deep.equal(['INITIALIZED', 'NEED_SIGNIN', 'REFUSED', 'NEED_SIGNIN', 'ACCEPTED']);
+  });
+
+  it('[APL14] a later poll round that fails ends in ERROR, not in an unhandled rejection', async () => {
+    const handoff = require('../src/lib/handoff');
+    const failure = new Error('unexpected');
+    const isHandoffBody = handoff.isHandoffBody;
+    let polls = 0;
+    utils.fetchGet = async () => {
+      polls++;
+      return polls === 1
+        ? { response: { ok: true, status: 201 }, body: { status: 'NEED_SIGNIN' } }
+        : { response: { ok: true, status: 200 }, body: { status: 'ACCEPTED', username: 'alice', apiEndpoint: 'https://tok@alice.test.local/' } };
+    };
+    // AuthController calls handoff.isHandoffBody on the module object at call
+    // time, so replacing the property makes the second round throw after the answer.
+    handoff.isHandoffBody = () => { throw failure; };
+    const seen = [];
+    const auth = makeAuth((s) => seen.push(s.status));
+    let unhandled;
+    try {
+      unhandled = await unhandledDuring(async () => {
+        await auth.startAuthRequest();
+        for (let i = 0; i < 50 && auth.state.status === AuthStates.NEED_SIGNIN; i++) {
+          await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+      });
+    } finally {
+      handoff.isHandoffBody = isHandoffBody;
+    }
+    expect(polls).to.equal(2);
+    expect(unhandled).to.deep.equal([]);
+    expect(auth.state.status).to.equal(AuthStates.ERROR);
+    expect(auth.state.message).to.equal('Error while polling for auth request');
+    expect(auth.state.error).to.equal(failure);
+    expect(seen).to.deep.equal(['INITIALIZED', 'NEED_SIGNIN', 'ERROR']);
+  });
+
+  it('[APL15] a poll answer without a status (unknown key, error body, no body) ends in ERROR \'Cannot fetch result\'', async () => {
+    for (const [status, body] of [[404, { error: { id: 'unknown-access-key', message: 'Unknown key' } }], [502, null]]) {
+      pollStatus = status;
+      pollBody = body;
+      const seen = [];
+      const auth = makeAuth((s) => seen.push(s.status));
+      await auth.startAuthRequest();
+      expect(seen, 'states for HTTP ' + status).to.deep.equal(['INITIALIZED', 'NEED_SIGNIN', 'ERROR']);
+      expect(auth.state.message).to.equal('Cannot fetch result');
+      expect(auth.state.error).to.deep.equal(body?.error ?? null);
+    }
+  });
+
+  it('[APL6] ACCEPTED without invites nor delegation stays { status, id, key }', async () => {
+    pollStatus = 200;
+    pollBody = { status: 'ACCEPTED', username: 'alice', token: 'tok', apiEndpoint: 'https://tok@alice.test.local/' };
+    const seen = [];
+    const auth = makeAuth((s) => seen.push(s));
+    await auth.startAuthRequest();
+    expect(seen[seen.length - 1]).to.deep.equal({ status: 'ACCEPTED', id: 'ACCEPTED', key: 'plk1' });
+  });
+});

package/test/LoginButton.urlCleanup.test.js

@@ -234,13 +234,24 @@ describe('[LBRH] LoginButton redirect return with credential hand-off', function
     await loginBtn.deleteAuthorizationData();
   });
 
-  it('[LBH5] a refused request returns to the sign-in button; an unknown key is an ERROR', async () => {
-    const authController = { serviceInfo: { access: 'https://reg.test.local/access/' } };
+  it('[LBH5] a refused request emits REFUSED (reasonId, message) then returns to the sign-in button; an unknown key is an ERROR', async () => {
+    const serviceInfo = { access: 'https://reg.test.local/access/' };
+    const states = [];
+    const authController = {
+      serviceInfo,
+      get state () { return states[states.length - 1]; },
+      set state (s) { states.push(s); }
+    };
     f.setPage('http://localhost/app?prYvpoll=https%3A%2F%2Freg.test.local%2Faccess%2Fflowkey5');
     seedFlow('flowkey5', 'https://reg.test.local/access/flowkey5');
-    f.poll({ status: 'REFUSED', reasonID: 'REFUSED_BY_USER' }, { status: 403 });
+    f.poll({ status: 'REFUSED', reasonId: 'REFUSED_MANDATORY_CONSENT', message: 'A mandatory consent was declined', other: 'x' }, { status: 403 });
     await LoginButton.prototype.finishAuthProcessAfterRedirection.call(THIS, authController);
-    expect(authController.state.status).to.equal('INITIALIZED');
+    expect(states).to.deep.equal([
+      { status: 'REFUSED', reasonId: 'REFUSED_MANDATORY_CONSENT', message: 'A mandatory consent was declined', serviceInfo },
+      { status: 'INITIALIZED', serviceInfo }
+    ]);
+    expect(global.window.location.href).to.equal('http://localhost/app');
+    states.length = 0;
 
     f.setPage('http://localhost/app?prYvpoll=https%3A%2F%2Freg.test.local%2Faccess%2Fflowkey6');
     seedFlow('flowkey6', 'https://reg.test.local/access/flowkey6');
@@ -250,6 +261,58 @@ describe('[LBRH] LoginButton redirect return with credential hand-off', function
     expect(authController.state.error).to.eql({ id: 'unknown-access-key' });
   });
 
+  it('[LBH7] end to end: a refused redirect return reaches the app as REFUSED, then the button resets to INITIALIZED', async () => {
+    f.setPage('http://localhost/app?pryvKey=flowkey7');
+    seedFlow('flowkey7', 'https://reg.test.local/access/flowkey7', 'pryv-libjs-lbh7-app');
+    f.poll({ status: 'REFUSED', reasonId: 'REFUSED_BY_USER', message: 'access refused by user' }, { status: 403 });
+    const external = [];
+    const serviceInfo = { access: 'https://reg.test.local/access/', name: 'Test' };
+    const loginBtn = new LoginButton({
+      onStateChange: (s) => external.push(s),
+      authRequest: { requestingAppId: 'lbh7-app', requestedPermissions: [], returnURL: 'self#' }
+    }, fakeService(serviceInfo));
+    const warnings = [];
+    const log = console.log;
+    console.log = (...args) => { warnings.push(args.join(' ')); };
+    try {
+      await loginBtn.init();
+    } finally {
+      console.log = log;
+    }
+
+    const refused = external.filter((s) => s.status === 'REFUSED');
+    expect(refused).to.have.length(1);
+    expect(refused[0]).to.deep.equal({ status: 'REFUSED', id: 'REFUSED', reasonId: 'REFUSED_BY_USER', message: 'access refused by user', serviceInfo });
+    expect(external[external.length - 1].status).to.equal('INITIALIZED');
+    expect(external.indexOf(refused[0])).to.equal(external.length - 2);
+    // the button is back to its sign-in label, ready for a new request
+    expect(loginBtn.auth.state.status).to.equal('INITIALIZED');
+    expect(loginBtn.text).to.equal(loginBtn.messages.LOGIN + ': Test');
+    expect(warnings.filter((w) => w.includes('Unhandled state'))).to.deep.equal([]);
+    expect(loginBtn.getAuthorizationData()).to.equal(undefined);
+    expect(global.window.location.href).to.equal('http://localhost/app');
+  });
+
+  it('[LBH8] a listener that starts over on a refused redirect return is not overridden by the reset', async () => {
+    f.setPage('http://localhost/app?pryvKey=flowkey8');
+    seedFlow('flowkey8', 'https://reg.test.local/access/flowkey8', 'pryv-libjs-lbh8-app');
+    f.poll({ status: 'REFUSED', reasonId: 'REFUSED_BY_USER' }, { status: 403 });
+    const external = [];
+    let loginBtn = null;
+    loginBtn = new LoginButton({
+      onStateChange: (s) => {
+        external.push(s.status);
+        if (s.status === 'REFUSED') loginBtn.auth.stopAuthRequest('stopped by the app');
+      },
+      authRequest: { requestingAppId: 'lbh8-app', requestedPermissions: [], returnURL: 'self#' }
+    }, fakeService({ access: 'https://reg.test.local/access/', name: 'Test' }));
+    await loginBtn.init();
+
+    expect(loginBtn.auth.state.status).to.equal('ERROR');
+    expect(loginBtn.auth.state.message).to.equal('stopped by the app');
+    expect(external.slice(-2)).to.deep.equal(['REFUSED', 'ERROR']);
+  });
+
   it('[LBH3] a failed redemption ends in ERROR, never a token-less AUTHORIZED', async () => {
     f.setPage('http://localhost/app?prYvpoll=https%3A%2F%2Freg.test.local%2Faccess%2Fflowkey3');
     seedFlow('flowkey3', 'https://reg.test.local/access/flowkey3');

package/test/Service.accessRequestConsent.test.js

@@ -124,4 +124,30 @@ describe('[ARQC] auth-request consent sidecar', function () {
     const envOld = await older.startAccessRequest({ ...REQUEST, cmcInvites: invites });
     expect(envOld).to.not.have.property('cmcInvites');
   });
+
+  it('[SARM1] posts actAsManagedOnly and invite accessName verbatim; returns the actAsManagedOnly echo only when a core sends true', async function () {
+    const invites = [{ capabilityUrl: 'https://cap@doctor.test.local/', accessName: 'Dr Who data' }];
+    const request = { ...REQUEST, actAs: 'allow', actAsManagedOnly: true, cmcInvites: invites };
+    stubFetch({ key: 'k5', authUrl: 'https://auth/', poll: 'https://poll/k5', poll_rate_ms: 1000, actAsManagedOnly: true });
+    const service = new pryv.Service('https://reg.test.local/service/info');
+    const env = await service.startAccessRequest(request);
+    expect(posted[0].actAsManagedOnly).to.equal(true);
+    expect(posted[0].actAs).to.equal('allow');
+    expect(posted[0].cmcInvites).to.deep.equal(invites);
+    expect(env.actAsManagedOnly).to.equal(true);
+    if (realFetch) { global.fetch = realFetch; realFetch = null; }
+
+    // An older core drops the field: no echo, the signal an app reads.
+    stubFetch({ key: 'k6', authUrl: 'https://auth/', poll: 'https://poll/k6', poll_rate_ms: 1000 });
+    const older = new pryv.Service('https://reg.test.local/service/info');
+    const envOld = await older.startAccessRequest(request);
+    expect(envOld).to.not.have.property('actAsManagedOnly');
+    if (realFetch) { global.fetch = realFetch; realFetch = null; }
+
+    // Only `true` counts as the echo.
+    stubFetch({ key: 'k7', authUrl: 'https://auth/', poll: 'https://poll/k7', poll_rate_ms: 1000, actAsManagedOnly: 'true' });
+    const odd = new pryv.Service('https://reg.test.local/service/info');
+    const envOdd = await odd.startAccessRequest(request);
+    expect(envOdd).to.not.have.property('actAsManagedOnly');
+  });
 });

package/test/typings/acceptedState.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+// Compiled (never run) by typings.test.js: what an app's onStateChange
+// listener may write about the ACCEPTED state.
+import type { StateChange } from 'pryv';
+
+// After a popup sign-in, the listener gets the narrowed state: no apiEndpoint, no username.
+export const popup: StateChange<'ACCEPTED'> = { status: 'ACCEPTED', id: 'ACCEPTED', key: 'k1' };
+
+// Restored or redirect path: apiEndpoint and username are there.
+export const restored: StateChange<'ACCEPTED'> = {
+  status: 'ACCEPTED',
+  id: 'ACCEPTED',
+  apiEndpoint: 'https://tok@alice.pryv.me/',
+  username: 'alice'
+};
+
+export function endpointOf (state: StateChange<'ACCEPTED'>): string | null {
+  // @ts-expect-error apiEndpoint may be absent (popup sign-in)
+  const direct: string = state.apiEndpoint;
+  // @ts-expect-error username may be absent (popup sign-in)
+  const name: string = state.username;
+  return state.apiEndpoint ?? (direct && name ? direct : null);
+}

package/test/typings.test.js

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, expect */
+
+const path = require('path');
+const ts = require('typescript');
+
+/**
+ * [TYPX] The declarations match what an app receives. The fixtures under
+ * `typings/` are compiled (strict) against `src/index.d.ts`; a declaration
+ * that drifts from the runtime shape makes them fail to compile.
+ */
+describe('[TYPX] typings', function () {
+  this.timeout(60000);
+
+  function compile (fixture) {
+    const file = path.join(__dirname, 'typings', fixture);
+    const program = ts.createProgram([path.join(__dirname, '../src/index.d.ts'), file], {
+      noEmit: true,
+      strict: true,
+      skipLibCheck: true,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.CommonJS,
+      moduleResolution: ts.ModuleResolutionKind.Node10,
+      lib: ['lib.es2022.d.ts', 'lib.dom.d.ts'],
+      types: []
+    });
+    return ts.getPreEmitDiagnostics(program)
+      .filter((d) => d.file != null && path.resolve(d.file.fileName) === file)
+      .map((d) => ts.flattenDiagnosticMessageText(d.messageText, '\n'));
+  }
+
+  it('[TYP1] ACCEPTED: apiEndpoint and username are optional (absent from a popup sign-in state)', function () {
+    expect(compile('acceptedState.ts')).to.deep.equal([]);
+  });
+});