pryv 3.11.0 → 3.12.1

package/README.md

@@ -114,8 +114,23 @@ Here is an implementation of the [Pryv.io authentication process](https://api.pr
             streamId: 'test',
             defaultName: 'test',
             level: 'manage'
+          },
+          {
+            streamId: 'location',
+            defaultName: 'Location',
+            level: 'read'
           }
         ],
+        // optional: how the consent screen should present each permission.
+        // Ids are a stream permission's streamId (or a feature permission's
+        // feature). Ignored by older cores, which fall back to
+        // all-or-nothing rather than failing.
+        consent: {
+          allowUserChoice: true,   // false (the default) = accept all or deny
+          mandatory: ['test'],     // required: cannot be unticked
+          optIn: ['location']      // offered UNticked; the user opts in
+          // a permission in neither list is optional and shown pre-selected
+        },
         clientData: {
           'app-web-auth:description': {
             'type': 'note/txt', 'content': 'This is a consent message.'

package/package.json

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

package/src/Auth/AuthController.js

@@ -70,7 +70,14 @@ class AuthController {
     const loginButton = this.loginButton;
     // initialize human interaction interface
     if (loginButton != null) {
-      this.stateChangeListeners.push(loginButton.onStateChange.bind(loginButton));
+      // Register the button's state listener at most once: init() can run again
+      // on the same controller (the LoginButton re-inits after a confirmed
+      // logout), and a duplicate listener would fire the logout confirm twice
+      // and compound the listener list on every re-login.
+      if (!this._loginButtonListenerRegistered) {
+        this.stateChangeListeners.push(loginButton.onStateChange.bind(loginButton));
+        this._loginButtonListenerRegistered = true;
+      }
       // autologin needs cookies/storage implemented in human interaction interface
       await checkAutoLogin(this);
     }
@@ -245,9 +252,16 @@ class AuthController {
 
     this._state = newState;
 
+    // Dispatch the state that was just set (`newState`), NOT the live `this.state`
+    // getter: a listener that synchronously changes the state mid-dispatch (e.g. a
+    // custom listener re-initializing to INITIALIZED on SIGNOUT; the LoginButton's
+    // own re-init now starts a microtask later) would otherwise overwrite
+    // `this._state`, so later listeners in this loop would receive the wrong state
+    // (a logout would deliver INITIALIZED instead of SIGNOUT to the app's
+    // onStateChange).
     this.stateChangeListeners.forEach((listener) => {
       try {
-        listener(this.state);
+        listener(newState);
       } catch (e) {
         console.log('Error during set state ()', e);
       }

package/src/Browser/LoginButton.js

@@ -74,8 +74,11 @@ class LoginButton {
       case AuthStates.SIGNOUT: {
         const message = this.messages.SIGNOUT_CONFIRM ? this.messages.SIGNOUT_CONFIRM : 'Logout ?';
         if (confirm(message)) {
-          this.deleteAuthorizationData();
-          this.auth.init();
+          // Awaited: a re-init left running in the background resumes later
+          // (after loading assets) and consumes whatever poll URL the page shows
+          // by then, racing any other sign-in in progress.
+          await this.deleteAuthorizationData();
+          await this.auth.init();
         }
         break;
       }

package/src/Service.js

@@ -473,13 +473,28 @@ class Service {
    * @param {Object} authRequest - The auth-request body
    * @param {string} authRequest.requestingAppId
    * @param {Array<{ streamId: string, level: string, defaultName: string }>} authRequest.requestedPermissions
+   * @param {Object} [authRequest.consent] - Says how the consent screen
+   *   should present each requested permission. `mandatory` and `optIn`
+   *   name permission ids (a stream permission's `streamId`, a feature
+   *   permission's `feature`); an id in neither list is optional and
+   *   shown pre-selected. Ignored by cores that predate it, so the flow
+   *   falls back to all-or-nothing rather than failing: the returned
+   *   `consent` tells you which happened.
+   * @param {boolean} [authRequest.consent.allowUserChoice=false] - false
+   *   means the user may only accept the whole set or deny.
+   * @param {string[]} [authRequest.consent.mandatory] - ids the user
+   *   cannot leave out.
+   * @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.referer]
    * @param {Object} [authRequest.clientData]
    * @param {string} [authRequest.deviceName]
    * @param {number} [authRequest.expireAfter]
-   * @returns {Promise<{ key: string, authUrl: string, poll: string, pollRateMs: number }>}
+   * @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.
    * @throws {PryvError} on non-2xx
    */
   async startAccessRequest (authRequest) {
@@ -499,12 +514,18 @@ class Service {
         'Invalid access-request response: ' + JSON.stringify(body)
       );
     }
-    return {
+    const envelope = {
       key: body.key,
       authUrl: body.authUrl || body.url,
       poll: body.poll,
       pollRateMs: body.poll_rate_ms != null ? body.poll_rate_ms : body.pollRateMs
     };
+    // Present only when the core understood a `consent` sidecar. Absent
+    // means the annotations were ignored and the consent screen will be
+    // all-or-nothing, which a caller may want to know before showing the
+    // approve link.
+    if (body.consent != null) envelope.consent = body.consent;
+    return envelope;
   }
 
   /**
@@ -552,8 +573,12 @@ class Service {
    * apiEndpoint), and uses this method to build a working `Connection`.
    *
    * The implementation polls `<access>/<key>` once; the call MUST be
-   * made while the access is still in the ACCEPTED state (which
-   * persists until expiry — see `expireAfter` on the access request).
+   * made while the access request is still readable in the ACCEPTED
+   * state. Servers keep a decided request only for a short retention
+   * window after it is first polled (default 2 minutes, operator setting
+   * `access.terminalRetentionMs`), so call this promptly after the flow
+   * completes; afterwards the key is unknown. (`expireAfter` on the
+   * access request is the lifetime of the access created, not of the key.)
    *
    * @param {string} key - polling key from `startAccessRequest`
    * @returns {Promise<Connection>}

package/src/SharedSecrets.js

@@ -96,6 +96,9 @@ async function hmacSha256Hex (verifierSecret, message) {
  */
 async function create (connection, params) {
   const { signature, ...rest } = params || {};
+  /** The request body: built here, so its shape is wider than `params`
+   * (the HMAC form adds `keyHash` and a computed `signature`).
+   * @type {Record<string, any>} */
   const body = { ...rest };
   let key = null;
 
@@ -108,12 +111,12 @@ async function create (connection, params) {
       type: 'hmac-sha256',
       value: await hmacSha256Hex(signature.verifierSecret, random)
     };
-    const res = await connection.post('shared-secrets', body);
-    return { ...res.sharedSecret, key: res.sharedSecret.id + '.' + random };
+    const hmacRes = /** @type {any} */ (await connection.post('shared-secrets', body));
+    return { ...hmacRes.sharedSecret, key: hmacRes.sharedSecret.id + '.' + random };
   }
 
   if (signature != null) body.signature = signature;
-  const res = await connection.post('shared-secrets', body);
+  const res = /** @type {any} */ (await connection.post('shared-secrets', body));
   key = res.sharedSecret.key;
   return { ...res.sharedSecret, key };
 }
@@ -149,7 +152,11 @@ async function retrieve (apiEndpoint, key, options = {}) {
   });
   const parsed = await res.json();
   if (!res.ok) {
-    const err = new Error(parsed?.error?.message || 'Shared secret unavailable.');
+    // The API error id and the creator's returnUrl ride on the Error so a
+    // caller can tell WHY it was refused and where to send the user next.
+    const err = /** @type {Error & { id?: string, returnUrl?: string }} */ (
+      new Error(parsed?.error?.message || 'Shared secret unavailable.')
+    );
     err.id = parsed?.error?.id;
     err.returnUrl = parsed?.error?.data?.returnUrl;
     throw err;

package/src/index.d.ts

@@ -871,8 +871,16 @@ declare module 'pryv' {
       authUrl: string;
       poll: string;
       pollRateMs: number;
+      /** Echoed only by a core that understood `authRequest.consent`. */
+      consent?: AuthRequestConsentForm;
     }>;
     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
+     * {@link PryvError} unless the access is `ACCEPTED`.
+     */
+    connectFromKey(key: string): Promise<Connection>;
 
     static buildAPIEndpoint(
       serviceInfo: ServiceInfo,
@@ -881,12 +889,74 @@ declare module 'pryv' {
     ): string;
   }
 
+  /**
+   * Module-level convenience over {@link Service#connectFromKey}: builds a
+   * transient {@link Service} for `serviceInfoUrl`, fetches its info, and
+   * resolves the auth-flow polling `key` into a working {@link Connection}.
+   * Mirrors the `pryv.connectFromKey(key, serviceInfoUrl)` shape the headless
+   * polling pattern documents.
+   */
+  export function connectFromKey(
+    key: string,
+    serviceInfoUrl: string,
+    serviceCustomizations?: serviceCustomizations,
+  ): Promise<Connection>;
+
   export type AuthRequestedPermission = {
     streamId: Identifier;
     defaultName: string;
     level: PermissionLevel;
   };
 
+  /**
+   * How the consent screen should present each requested permission.
+   *
+   * The lists name permission ids: a stream permission's `streamId`, a
+   * feature permission's `feature`. Together they give three words for
+   * what an entry means to the user:
+   *
+   *   mandatory  listed in `mandatory` : required; cannot be unticked
+   *   opt-out    in neither list       : optional, shown pre-selected
+   *   opt-in     listed in `optIn`     : optional, shown NOT pre-selected
+   *
+   * An id may not appear in both lists, and every id must match exactly
+   * one requested permission. A core that predates this ignores the whole
+   * object, so the consent falls back to all-or-nothing instead of
+   * failing; `AuthRequestConsentForm` echoed back is how you tell.
+   */
+  export type AuthRequestConsent = {
+    /** Default false: the user may only accept the whole set or deny. */
+    allowUserChoice?: boolean;
+    mandatory?: string[];
+    optIn?: string[];
+  };
+
+  /**
+   * The resolved consent form: the requested permissions with their
+   * annotations attached, as the auth page renders them. Returned by the
+   * auth-request POST and carried on the NEED_SIGNIN poll, in both cases
+   * ONLY when the request carried a `consent` object the core understood.
+   */
+  export type AuthRequestConsentForm = {
+    allowUserChoice: boolean;
+    permissions: Array<
+      (
+        | {
+            streamId: Identifier;
+            level: PermissionLevel;
+            /** Echoed only when the request carried it. */
+            defaultName?: string;
+            /** Present when the core resolved the stream's real name. */
+            name?: string;
+          }
+        | { feature: string; setting: string }
+      ) & {
+        mandatory?: true;
+        optIn?: true;
+      }
+    >;
+  };
+
   export type States =
     | 'ERROR'
     | 'LOADING'
@@ -919,6 +989,7 @@ declare module 'pryv' {
         level: PermissionLevel;
         defaultName: string;
       }>;
+      consent?: AuthRequestConsentForm;
       requestingAppId: string;
       returnUrl?: string | null;
       serviceInfo?: ServiceInfo;
@@ -956,6 +1027,7 @@ declare module 'pryv' {
     poll_rate_ms: number;
     requestingAppId: string;
     requestedPermissions: AuthRequestedPermission[];
+    consent?: AuthRequestConsentForm;
     lang?: string;
     returnURL?: string;
     clientData?: KeyValue;
@@ -970,6 +1042,7 @@ declare module 'pryv' {
       requestingAppId: string;
       languageCode?: string;
       requestedPermissions: AuthRequestedPermission[];
+      consent?: AuthRequestConsent;
       returnUrl?: string | boolean;
       referer?: string;
       clientData?: KeyValue;
@@ -1202,6 +1275,7 @@ declare module 'pryv' {
     MfaRequiredError: typeof MfaRequiredError;
     ERRORS: typeof ERRORS;
     version: version;
+    connectFromKey: typeof connectFromKey;
   };
 
   export default pryv;

package/test/Browser.AuthController.test.js

@@ -7,11 +7,13 @@
 const utils = require('../src/utils.js');
 const Service = require('../src/Service');
 const AuthController = require('../src/Auth/AuthController.js');
+const AuthStates = require('../src/Auth/AuthStates');
 
 describe('[AUTX] Browser.LoginButton', function () {
   this.timeout(15000);
 
   let auth;
+  let service;
   let cleanupDom = false;
   before(async function () {
     if (typeof document !== 'undefined') return; // in browser
@@ -32,7 +34,7 @@ describe('[AUTX] Browser.LoginButton', function () {
     delete global.location;
   });
   before(async function () {
-    const service = new Service(testData.serviceInfoUrl);
+    service = new Service(testData.serviceInfoUrl);
     await service.info();
     auth = new AuthController({
       authRequest: {
@@ -92,4 +94,76 @@ describe('[AUTX] Browser.LoginButton', function () {
     expect('https://my.Url.com/#bobby=2').to.equal(utils.cleanURLFromPrYvParams(
       'https://my.Url.com/#bobby=2&prYvZoutOu=1&prYvstatus=2jsadh'));
   });
+
+  // Logout state dispatch (https://github.com/pryv/lib-js/issues/13): a listener
+  // that synchronously re-enters the setter (the LoginButton's logout confirm
+  // re-initializing to INITIALIZED) must not corrupt the state delivered to the
+  // other listeners in the same dispatch, and init() must not register the button
+  // listener twice (which would fire the logout confirm dialog more than once).
+  describe('[ACLO] logout state dispatch (re-entrancy)', function () {
+    function makeAuth (onStateChange) {
+      return new AuthController({
+        authRequest: { requestingAppId: 'test-app', requestedPermissions: [] },
+        onStateChange
+      }, service);
+    }
+
+    it('[ACLO1] the app onStateChange receives SIGNOUT on logout, then INITIALIZED', async function () {
+      const seen = [];
+      const a = makeAuth((s) => seen.push(s.status));
+      await a.init();
+      // Worst case of a LoginButton-like listener (registered after the external
+      // app listener): on SIGNOUT it re-initializes synchronously, driving the
+      // state to INITIALIZED during the same dispatch. (The real LoginButton
+      // awaits its re-init, which starts a microtask later.)
+      a.stateChangeListeners.push((s) => {
+        if (s.status === AuthStates.SIGNOUT) a.state = { status: AuthStates.INITIALIZED, serviceInfo: {} };
+      });
+      a._state = { status: AuthStates.AUTHORIZED };
+      seen.length = 0;
+      await a.handleClick(); // AUTHORIZED -> SIGNOUT
+      expect(seen).to.include(AuthStates.SIGNOUT);
+      expect(seen[seen.length - 1]).to.equal(AuthStates.INITIALIZED);
+    });
+
+    it('[ACLO2] a listener re-entering the setter must not corrupt the state delivered to later listeners', function () {
+      // The setter must hand each listener the state dispatched to IT, not a value
+      // an earlier listener mutated mid-dispatch. Worst case: a re-entrant listener
+      // registered BEFORE the recorder.
+      const a = makeAuth(() => {});
+      const seen = [];
+      let reentered = false;
+      a.stateChangeListeners.push((s) => {
+        if (s.status === AuthStates.SIGNOUT && !reentered) {
+          reentered = true;
+          a.state = { status: AuthStates.INITIALIZED, serviceInfo: {} };
+        }
+      });
+      a.stateChangeListeners.push((s) => seen.push(s.status));
+      seen.length = 0;
+      a.state = { status: AuthStates.SIGNOUT };
+      // The re-entrant INITIALIZED dispatch completes first (inner), then the outer
+      // SIGNOUT dispatch resumes to the recorder; the recorder MUST see SIGNOUT.
+      expect(seen).to.deep.equal([AuthStates.INITIALIZED, AuthStates.SIGNOUT]);
+    });
+
+    it('[ACLO3] init() registers the LoginButton listener only once, so logout confirms exactly once', async function () {
+      let confirms = 0;
+      const fakeButton = {
+        onStateChange: (s) => { if (s.status === AuthStates.SIGNOUT) confirms++; },
+        getAuthorizationData: () => null
+      };
+      const a = new AuthController({
+        authRequest: { requestingAppId: 'test-app', requestedPermissions: [] }
+      }, service, fakeButton);
+      await a.init();
+      const nAfterFirst = a.stateChangeListeners.length;
+      await a.init(); // the confirmed-logout path re-inits the same controller
+      await a.init();
+      expect(a.stateChangeListeners.length).to.equal(nAfterFirst); // no compounding
+      confirms = 0;
+      a.state = { status: AuthStates.SIGNOUT }; // one dispatch -> one confirm
+      expect(confirms).to.equal(1);
+    });
+  });
 });

package/test/LoginButton.test.js

@@ -39,6 +39,7 @@ describe('[LBTX] LoginButton', function () {
     delete global.document;
     delete global.window;
     delete global.location;
+    delete global.navigator;
     delete global.confirm;
   });
 
@@ -174,6 +175,23 @@ describe('[LBTX] LoginButton', function () {
       // Confirm is mocked to return true
     });
 
+    it('[LBSG] SIGNOUT waits for the re-init to finish (none left running in the background)', async function () {
+      // A re-init that outlives onStateChange resumes later and consumes
+      // whatever poll URL the page shows by then (it raced [LBRU] on CI).
+      const originalInit = loginBtn.auth.init;
+      let reinitDone = false;
+      loginBtn.auth.init = async function () {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        reinitDone = true;
+      };
+      try {
+        await loginBtn.onStateChange({ status: AuthStates.SIGNOUT });
+        expect(reinitDone).to.equal(true);
+      } finally {
+        loginBtn.auth.init = originalInit;
+      }
+    });
+
     it('[LBSF] handles unknown state gracefully', async function () {
       // Should log warning but not throw
       await loginBtn.onStateChange({ status: 'UNKNOWN_STATE' });

package/test/LoginButton.urlCleanup.test.js

@@ -9,14 +9,19 @@ const utils = require('../src/utils');
 
 describe('[LBRU] LoginButton URL cleanup after redirect', function () {
   const PAGE_URL = 'http://localhost/app?x=1&prYvpoll=http%3A%2F%2Flocalhost%2Fpoll%2Fkey123&prYvstatus=ACCEPTED';
-  let dom;
-  let cleanupDom = false;
+  const GLOBALS = ['document', 'window', 'location', 'navigator'];
+  let saved;
   let originalFetchGet;
 
   before(() => {
-    if (typeof document === 'undefined') {
-      cleanupDom = true;
-      dom = new JSDOM('<!DOCTYPE html><body></body>', { url: PAGE_URL });
+    // Always our own page: reusing a DOM left by another file would test that
+    // page's URL, not PAGE_URL. Node only (a real browser run has no JSDOM).
+    if (typeof JSDOM !== 'undefined') {
+      saved = {};
+      for (const name of GLOBALS) {
+        saved[name] = Object.getOwnPropertyDescriptor(global, name);
+      }
+      const dom = new JSDOM('<!DOCTYPE html><body></body>', { url: PAGE_URL });
       global.document = dom.window.document;
       global.window = dom.window;
       global.location = dom.window.location;
@@ -28,11 +33,11 @@ describe('[LBRU] LoginButton URL cleanup after redirect', function () {
 
   after(() => {
     utils.fetchGet = originalFetchGet;
-    if (!cleanupDom) return;
-    delete global.document;
-    delete global.window;
-    delete global.location;
-    delete global.navigator;
+    if (saved == null) return;
+    for (const name of GLOBALS) {
+      if (saved[name]) Object.defineProperty(global, name, saved[name]);
+      else delete global[name];
+    }
   });
 
   it('[LBR1] strips consumed prYv* params from the visible URL', async () => {

package/test/Service.accessRequestConsent.test.js

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, afterEach, expect, pryv */
+
+/**
+ * [ARQC] The `consent` sidecar of an auth request travels untouched.
+ *
+ * The sidecar is how an app says which permissions are required, which are
+ * offered pre-selected, and which the user must opt into. This library must
+ * neither invent it nor filter it: it posts what the caller gave it and
+ * hands back what the core answered. These pin that, so a future "helpful"
+ * field whitelist in `startAccessRequest` cannot silently drop consent
+ * semantics on their way to the server.
+ *
+ * Driven through a stubbed global fetch rather than a live core: what is
+ * being tested is this library's pass-through, and a core that predates
+ * the sidecar is one of the cases.
+ */
+
+const SERVICE_INFO = {
+  register: 'https://reg.test.local/',
+  access: 'https://reg.test.local/access',
+  api: 'https://{username}.test.local/',
+  name: 'Test'
+};
+
+const CONSENT = {
+  allowUserChoice: true,
+  mandatory: ['diary'],
+  optIn: ['weight']
+};
+
+const REQUEST = {
+  requestingAppId: 'jslib-test',
+  requestedPermissions: [
+    { streamId: 'diary', level: 'read', defaultName: 'Journal' },
+    { streamId: 'weight', level: 'read', defaultName: 'Weight' }
+  ],
+  consent: CONSENT
+};
+
+describe('[ARQC] auth-request consent sidecar', function () {
+  let realFetch;
+  let posted;
+
+  /** Stub fetch: serve service-info, capture the access POST, answer it. */
+  function stubFetch (accessResponse) {
+    realFetch = global.fetch;
+    posted = [];
+    global.fetch = async function (url, options) {
+      if (String(url).includes('/access')) {
+        posted.push(JSON.parse(options.body));
+        return {
+          ok: true,
+          status: 201,
+          json: async () => accessResponse
+        };
+      }
+      return { ok: true, status: 200, json: async () => SERVICE_INFO };
+    };
+  }
+
+  afterEach(function () {
+    if (realFetch) global.fetch = realFetch;
+    realFetch = null;
+  });
+
+  it('[SARC1] posts the consent sidecar verbatim', async function () {
+    stubFetch({ key: 'k1', authUrl: 'https://auth/', poll: 'https://poll/k1', poll_rate_ms: 1000 });
+    const service = new pryv.Service('https://reg.test.local/service/info');
+    await service.startAccessRequest(REQUEST);
+    expect(posted).to.have.lengthOf(1);
+    expect(posted[0].consent).to.deep.equal(CONSENT);
+    // And the permissions stay plain: the annotations live in the sidecar,
+    // never inside an entry (the API rejects unknown per-entry fields).
+    expect(posted[0].requestedPermissions).to.deep.equal(REQUEST.requestedPermissions);
+  });
+
+  it('[SARC2] returns the consent form a core echoes back, and nothing when it does not', async function () {
+    const form = {
+      allowUserChoice: true,
+      permissions: [
+        { streamId: 'diary', level: 'read', defaultName: 'Journal', mandatory: true },
+        { streamId: 'weight', level: 'read', defaultName: 'Weight', optIn: true }
+      ]
+    };
+    stubFetch({
+      key: 'k1',
+      authUrl: 'https://auth/',
+      poll: 'https://poll/k1',
+      poll_rate_ms: 1000,
+      consent: form
+    });
+    const service = new pryv.Service('https://reg.test.local/service/info');
+    const env = await service.startAccessRequest(REQUEST);
+    // The echo is how an app knows the core understood the annotations.
+    expect(env.consent).to.deep.equal(form);
+    if (realFetch) { global.fetch = realFetch; realFetch = null; }
+
+    // A core that predates the sidecar answers without it. The request
+    // still succeeds and the consent screen falls back to all-or-nothing,
+    // so the absence is the signal, not an error.
+    stubFetch({ key: 'k2', authUrl: 'https://auth/', poll: 'https://poll/k2', poll_rate_ms: 1000 });
+    const older = new pryv.Service('https://reg.test.local/service/info');
+    const envOld = await older.startAccessRequest(REQUEST);
+    expect(envOld.key).to.equal('k2');
+    expect(envOld).to.not.have.property('consent');
+  });
+});