pryv 3.7.1 → 3.8.1

package/README.md

@@ -144,6 +144,44 @@ Here is an implementation of the [Pryv.io authentication process](https://api.pr
 </html>
 ```
 
+#### With OAuth2 (`pryv.OAuth2Client`)
+
+For apps registered as OAuth2 clients on a Pryv.io deployment, `pryv.OAuth2Client`
+drives the authorization-code flow (PKCE). The authorization-server endpoints are
+discovered from the issuer via RFC 8414. The `scope` value is a consent-offer
+reference (`cmc:<offer-name>`) registered on your OAuth client — the user grants
+a granular permission set resolved from that offer, and may untick individual
+permissions on the consent screen.
+
+```js
+const client = new pryv.OAuth2Client({
+  authorizationServer: 'https://host', // Pryv API base URL (issuer)
+  clientId: 'my-app',                  // from the app-account registration
+  redirectUri: 'https://my-app.example/callback',
+  scope: 'cmc:study-A'                 // your registered consent-offer reference
+});
+
+// On "Login with Pryv":
+await client.redirectToAuthorize();
+
+// On the redirect_uri page:
+const connection = await client.handleCallback(window.location.search);
+// `connection` is a regular pryv.Connection
+
+// Later, to renew the access token:
+const renewed = await client.refresh();
+```
+
+The PKCE verifier is generated per flow and stored in `sessionStorage` (pass
+`storage` to override). This flow is browser-oriented; the polling flow below
+stays fully supported.
+
+> **Requirements.** `pryv.OAuth2Client` uses the ESM-only `oauth4webapi`
+> dependency, so `pryv` now requires **Node >= 20.19 (or >= 22.12)**. Consumers
+> who bundle `pryv` themselves need an `exports`-field-aware bundler
+> (webpack 5 / vite / rollup / esbuild); webpack-4 / browserify users should use
+> the prebuilt `dist/` bundle.
+
 #### Fetching access info
 
 [API reference](https://api.pryv.com/reference/#access-info).
@@ -501,7 +539,7 @@ To customize visual assets, please refer to the [pryv.me assets repository](http
 You can customize the authentication process ([API reference](https://api.pryv.com/reference/#authenticate-your-app)) at different levels:
 
 - Using a custom login button
-- Using a custom UI, including the flow of [app-web-auth3](https://github.com/pryv/app-web-auth3)
+- Using a custom UI, including the flow of [app-web-user-account](https://github.com/pryv/app-web-user-account)
 
 #### Using a custom login button
 
@@ -651,7 +689,7 @@ There is a possibility that you would like to register the user in another page.
 
 You can find HTML examples in the [`./examples`](https://github.com/pryv/lib-js/blob/master/examples) directory. You can run them in two ways:
 
-1. With [backloop.dev](https://github.com/pryv/backloop.dev), which allows to run local code with a valid SSL certificate (you must have run `just build` beforehand):
+1. With [backloop.dev](https://backloop.dev), which allows to run local code with a valid SSL certificate (you must have run `just build` beforehand):
    ```
    just serve
    ```
@@ -702,7 +740,7 @@ just test <component> [...params]
 - Extra parameters at the end are passed on to [Mocha](https://mochajs.org/) (default settings are defined in `.mocharc.js` files)
 - Replace `test` with `test-debug`, `test-cover` for common presets
 
-By default, tests are run against [Pryv Lab](https://www.pryv.com/pryvlab/) with service information URL `https://reg.pryv.me/service/info`.
+By default, tests are run against Pryv Lab with service information URL `https://reg.pryv.me/service/info`.
 
 To run the tests against another Pryv.io platform, set the `TEST_PRYVLIB_SERVICEINFO_URL` environment variable; for example:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pryv",
-  "version": "3.7.1",
+  "version": "3.8.1",
   "description": "Pryv JavaScript library",
   "keywords": [
     "Pryv",
@@ -15,11 +15,13 @@
     "url": "git://github.com/pryv/lib-js.git"
   },
   "license": "BSD-3-Clause",
-  "author": "Pryv S.A. <info@pryv.com> (https://pryv.com)",
+  "author": "Pryv <info@pryv.com> (https://pryv.com)",
   "main": "src/index.js",
   "types": "src/index.d.ts",
-  "dependencies": {},
+  "dependencies": {
+    "oauth4webapi": "^3.8.6"
+  },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.0"
   }
 }

package/src/Browser/LoginButton.js

@@ -112,7 +112,8 @@ class LoginButton {
     // this step should be applied only for the browser
     if (!utils.isBrowser()) return;
 
-    // 3. Check if there is a prYvkey as result of "out of page login"
+    // 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) {
@@ -126,21 +127,27 @@ class LoginButton {
           error: e
         };
       }
-      // The prYv* params are one-shot; leaving them in the visible URL
-      // puts stale auth state into bookmarks / copied links.
+      // These params are one-shot; leaving them in the visible URL puts
+      // stale auth state into bookmarks / copied links.
       if (window.history && typeof window.history.replaceState === 'function') {
         window.history.replaceState(null, '', utils.cleanURLFromPrYvParams(url));
       }
     }
 
     function retrievePollUrl (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;
-      if (params.prYvkey) { // deprecated method - To be removed
-        pollUrl = authController.serviceInfo.access + params.prYvkey;
+      const key = params.pryvKey || params.prYvkey;
+      if (key) {
+        pollUrl = authController.serviceInfo.access + key;
       }
-      if (params.prYvpoll) {
-        pollUrl = params.prYvpoll;
+      const poll = params.pryvPoll || params.prYvpoll;
+      if (poll) {
+        pollUrl = poll;
       }
       return pollUrl;
     }

package/src/OAuth2Client.js

@@ -0,0 +1,348 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+const oauth = require('oauth4webapi');
+const Connection = require('./Connection');
+const utils = require('./utils');
+
+// sessionStorage key prefix for the per-flow PKCE verifier, keyed by `state`.
+const VERIFIER_KEY_PREFIX = 'pryv-oauth2-verifier:';
+
+/**
+ * Minimal Web-Storage-like contract used to persist the per-flow PKCE verifier.
+ * A browser `sessionStorage` satisfies it structurally.
+ * @typedef {Object} OAuth2Storage
+ * @property {(key: string) => (string | null)} getItem
+ * @property {(key: string, value: string) => void} setItem
+ * @property {(key: string) => void} removeItem
+ */
+
+/**
+ * @class OAuth2Client
+ * Browser-side consumer of the Pryv OAuth2 authorization-code flow (PKCE).
+ *
+ * Sibling to {@link Browser}: an OAuth-aware app runs
+ * `redirectToAuthorize()` → (the browser bounces through `/oauth2/authorize`
+ * and back to `redirectUri`) → `handleCallback()`, which returns a ready
+ * {@link Connection}. `refresh()` swaps the refresh token for a fresh one.
+ *
+ * PKCE is handled internally: a random `code_verifier` is generated per flow,
+ * stored in `sessionStorage` keyed by `state`, and consumed on callback.
+ *
+ * The authorization-server endpoints are discovered from the issuer via
+ * RFC 8414 (`GET <issuer>/.well-known/oauth-authorization-server`).
+ *
+ * @example
+ * const client = new pryv.OAuth2Client({
+ *   authorizationServer: 'https://host', // Pryv API base (issuer)
+ *   clientId: 'my-app',
+ *   redirectUri: 'https://my-app.example/callback',
+ *   scope: 'cmc:study-A'
+ * });
+ * // on "Login with Pryv":
+ * await client.redirectToAuthorize();
+ * // on the redirect_uri page:
+ * const connection = await client.handleCallback(window.location.search);
+ *
+ * @memberof pryv
+ */
+class OAuth2Client {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.authorizationServer] - Issuer / Pryv API base URL. The
+   *   discovery document is fetched from `<authorizationServer>/.well-known/oauth-authorization-server`.
+   *   (This is the concrete issuer URL, not the `/service/info` URL — client-side
+   *   derivation from the per-user `service:api` template is unreliable for multi-core.)
+   *   Required at runtime.
+   * @param {string} [options.clientId] - App-account client id. Required at runtime.
+   * @param {string} [options.redirectUri] - Registered redirect URI. Required at runtime.
+   * @param {string} [options.scope] - Consent-offer reference registered on the client, e.g. `'cmc:study-A'`.
+   * @param {OAuth2Storage} [options.storage] - Web-Storage-like `{ getItem, setItem, removeItem }`.
+   *   Defaults to `globalThis.sessionStorage` in a browser, else an in-memory store.
+   * @param {string} [options.refreshToken] - Seed the client with a previously-persisted
+   *   refresh token so `refresh()` works after a page reload WITHOUT re-running the
+   *   authorization flow. Persist ONLY this value (read it from `client.refreshToken`
+   *   or the `onTokenRotated` callback) — never the whole `lastTokenResponse`, which
+   *   also carries the access token and so is a larger XSS surface.
+   * @param {(refreshToken: string) => void} [options.onTokenRotated] - Called with the
+   *   NEW refresh token every time it rotates (after `handleCallback()` and each
+   *   `refresh()`), so the app can persist the minimal secret. Exceptions it throws
+   *   are swallowed (persistence must not break the token exchange).
+   */
+  constructor (options = {}) {
+    const { authorizationServer, clientId, redirectUri, scope, storage, refreshToken, onTokenRotated } = options;
+    if (!authorizationServer) throw new Error('OAuth2Client: "authorizationServer" is required');
+    if (!clientId) throw new Error('OAuth2Client: "clientId" is required');
+    if (!redirectUri) throw new Error('OAuth2Client: "redirectUri" is required');
+
+    this.issuer = new URL(authorizationServer);
+    this.clientId = clientId;
+    this.redirectUri = redirectUri;
+    this.scope = scope;
+    this.storage = storage || defaultStorage();
+
+    // Public client (PKCE, no secret) — token_endpoint auth method "none".
+    this._client = { client_id: clientId };
+    this._clientAuth = oauth.None();
+    this._as = null;
+    this._refreshToken = refreshToken || null;
+    this._onTokenRotated = (typeof onTokenRotated === 'function') ? onTokenRotated : null;
+    // In-flight refresh() promise — dedups concurrent callers onto one token
+    // request so they can't each present the same refresh token and have the
+    // loser rejected as reuse (invalid_grant) by an always-rotating server.
+    this._refreshInFlight = null;
+    /** Last raw token-endpoint response (access_token, scope, apiEndpoint, …). */
+    this.lastTokenResponse = null;
+  }
+
+  /**
+   * The current refresh token (rotates on every `handleCallback()` / `refresh()`).
+   * Read it to persist the minimal secret across reloads; re-seed via the
+   * `refreshToken` constructor option. `null` before the first exchange.
+   * @returns {string | null}
+   */
+  get refreshToken () {
+    return this._refreshToken;
+  }
+
+  /**
+   * @private
+   * Lazily discover + cache the authorization-server metadata (RFC 8414).
+   * @returns {Promise<Object>} the `AuthorizationServer` metadata
+   */
+  async _discover () {
+    if (this._as) return this._as;
+    const response = await oauth.discoveryRequest(this.issuer, { algorithm: 'oauth2' });
+    this._as = await oauth.processDiscoveryResponse(this.issuer, response);
+    return this._as;
+  }
+
+  /**
+   * Build the `/oauth2/authorize` URL (generating + storing the PKCE verifier)
+   * and navigate to it. Returns the URL so non-browser callers can drive the
+   * redirect themselves.
+   *
+   * @param {Object} [options]
+   * @param {string} [options.state] - CSRF/correlation value; a random one is generated when omitted.
+   * @param {(url: string) => void} [options.redirect] - Navigation function; defaults to
+   *   `globalThis.location.assign` when available, else a no-op (URL still returned).
+   * @returns {Promise<string>} the authorization URL
+   */
+  async redirectToAuthorize (options = {}) {
+    const as = await this._discover();
+    const state = options.state || oauth.generateRandomState();
+    const codeVerifier = oauth.generateRandomCodeVerifier();
+    const codeChallenge = await oauth.calculatePKCECodeChallenge(codeVerifier);
+    this.storage.setItem(VERIFIER_KEY_PREFIX + state, codeVerifier);
+
+    const url = new URL(as.authorization_endpoint);
+    // The browser is about to be navigated to this URL. `oauth4webapi` only
+    // enforces https on endpoints it fetches itself, not on this navigation
+    // target — a tampered/MITM discovery document could return an http:/other
+    // `authorization_endpoint` and send the user somewhere hostile. Assert the
+    // scheme with the same https-or-loopback rule used for the apiEndpoint.
+    assertHttpsOrLoopback(url, 'authorization_endpoint');
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', this.clientId);
+    url.searchParams.set('redirect_uri', this.redirectUri);
+    if (this.scope) url.searchParams.set('scope', this.scope);
+    url.searchParams.set('code_challenge', codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('state', state);
+
+    const authorizationUrl = url.href;
+    const redirect = options.redirect || defaultRedirect;
+    redirect(authorizationUrl);
+    return authorizationUrl;
+  }
+
+  /**
+   * Validate the redirect_uri callback, exchange the code for tokens (PKCE),
+   * and build a {@link Connection} from the Pryv `apiEndpoint` extension.
+   *
+   * @param {string} queryString - `window.location.search` (with or without leading `?`).
+   * @returns {Promise<Connection>} an authenticated Pryv connection
+   */
+  async handleCallback (queryString) {
+    const as = await this._discover();
+    const params = new URLSearchParams(stripLeadingQuestionMark(queryString));
+
+    const state = params.get('state');
+    if (!state) throw new Error('OAuth2Client: callback is missing "state"');
+    const storageKey = VERIFIER_KEY_PREFIX + state;
+    const codeVerifier = this.storage.getItem(storageKey);
+    if (!codeVerifier) {
+      throw new Error('OAuth2Client: no stored PKCE verifier for this state (expired session or forged callback)');
+    }
+
+    // The verifier is single-use and bound to this state; drop it on every
+    // exit path (success OR error) so a failed/denied callback never leaves it
+    // behind in sessionStorage.
+    try {
+      // Throws on authorization errors (e.g. access_denied) or a state mismatch.
+      const callbackParams = oauth.validateAuthResponse(as, this._client, params, state);
+      const response = await oauth.authorizationCodeGrantRequest(
+        as, this._client, this._clientAuth, callbackParams, this.redirectUri, codeVerifier
+      );
+      const result = await oauth.processAuthorizationCodeResponse(as, this._client, response);
+      return this._connectionFromTokenResponse(result);
+    } finally {
+      this.storage.removeItem(storageKey);
+    }
+  }
+
+  /**
+   * Exchange the stored refresh token for a fresh access token and return a
+   * new {@link Connection}. Requires a prior successful `handleCallback()`.
+   *
+   * @returns {Promise<Connection>}
+   */
+  async refresh () {
+    // Serialize concurrent callers onto a single in-flight exchange (F1). An
+    // always-rotating server consumes the refresh token on first use, so two
+    // parallel refresh() calls presenting the same token would rotate once and
+    // have the loser rejected as reuse. Dedup to one request; both callers get
+    // the same fresh Connection.
+    if (this._refreshInFlight) return this._refreshInFlight;
+    this._refreshInFlight = this._doRefresh();
+    // Clear the slot once settled (success OR failure) so the next call retries.
+    this._refreshInFlight.catch(() => {}).finally(() => { this._refreshInFlight = null; });
+    return this._refreshInFlight;
+  }
+
+  /**
+   * @private
+   * The actual refresh exchange, wrapped by `refresh()`'s in-flight dedup.
+   * @returns {Promise<Connection>}
+   */
+  async _doRefresh () {
+    if (!this._refreshToken) {
+      throw new Error('OAuth2Client: no refresh token available; call handleCallback() first');
+    }
+    const as = await this._discover();
+    const response = await oauth.refreshTokenGrantRequest(as, this._client, this._clientAuth, this._refreshToken);
+    const result = await oauth.processRefreshTokenResponse(as, this._client, response);
+    return this._connectionFromTokenResponse(result);
+  }
+
+  /**
+   * @private
+   * @param {Object} tokenResponse - a processed token-endpoint response
+   * @returns {Connection}
+   */
+  _connectionFromTokenResponse (tokenResponse) {
+    // Persist the rotated refresh token FIRST — before any validation that can
+    // throw (F2). The server has already committed the rotation (old token
+    // consumed, new one issued in this response). If we validated first and it
+    // threw (e.g. a momentarily-missing or http: apiEndpoint), we would strand
+    // the client on the now-dead old token AND lose the new one — permanently
+    // bricking the session. Storing first lets a later refresh() retry with the
+    // current token.
+    this._ingestTokens(tokenResponse);
+
+    const apiEndpoint = tokenResponse.apiEndpoint;
+    if (!apiEndpoint) {
+      throw new Error('OAuth2Client: token response is missing the Pryv "apiEndpoint" extension');
+    }
+    // Validate the endpoint the Connection will actually send the token to, not
+    // the raw apiEndpoint string: Connection splits token/endpoint on the LAST
+    // `@` (utils regex), so a crafted `http://tok@127.0.0.1/x@evil/` parses as
+    // loopback here but posts the token to `evil` there. Assert on the extracted
+    // endpoint to close that parser-divergence gap.
+    const { endpoint } = utils.extractTokenAndAPIEndpoint(String(apiEndpoint));
+    assertSecureApiEndpoint(endpoint);
+    return new Connection(String(apiEndpoint));
+  }
+
+  /**
+   * @private
+   * Non-throwing: record the rotated refresh token + raw response and notify the
+   * app so it can persist the minimal secret. Runs before validation so a
+   * validation failure never loses the rotation (see `_connectionFromTokenResponse`).
+   * @param {Object} tokenResponse - a processed token-endpoint response
+   */
+  _ingestTokens (tokenResponse) {
+    this.lastTokenResponse = tokenResponse;
+    if (!tokenResponse.refresh_token) return;
+    this._refreshToken = tokenResponse.refresh_token;
+    if (this._onTokenRotated) {
+      // Persistence must never break the exchange — swallow app callback errors.
+      try { this._onTokenRotated(this._refreshToken); } catch (_) { /* ignore */ }
+    }
+  }
+}
+
+/**
+ * @private
+ * Refuse an `apiEndpoint` that would send the bearer token in cleartext. The
+ * token is embedded in the endpoint (`https://<token>@host/`) and then sent on
+ * every request, so a non-https endpoint leaks it on the wire. Defense-in-depth
+ * against a compromised/misconfigured authorization server.
+ * @param {string} apiEndpoint
+ */
+function assertSecureApiEndpoint (apiEndpoint) {
+  assertHttpsOrLoopback(apiEndpoint, 'apiEndpoint');
+}
+
+/**
+ * @private
+ * Enforce a "must be transport-secure" rule on a URL that is either navigated
+ * to (the authorize redirect) or used to send the bearer token (the
+ * apiEndpoint): allow `https:` everywhere, and `http:` only for loopback hosts
+ * (local development). Single source of truth so both call sites stay in sync.
+ * @param {string | URL} rawUrl - the URL to check (string or a parsed `URL`)
+ * @param {string} label - human-readable name of the value, used in errors
+ */
+function assertHttpsOrLoopback (rawUrl, label) {
+  let url;
+  try {
+    url = (rawUrl instanceof URL) ? rawUrl : new URL(rawUrl);
+  } catch {
+    throw new Error('OAuth2Client: ' + label + ' is not a valid URL');
+  }
+  const host = url.hostname;
+  const isLoopback = host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1';
+  if (url.protocol === 'https:') return;
+  if (url.protocol === 'http:' && isLoopback) return;
+  throw new Error('OAuth2Client: refusing insecure ' + label + ' (' + url.protocol + '//' + host + '); https is required');
+}
+
+/**
+ * @private
+ * Default navigation: use the browser's `location.assign` when present,
+ * otherwise a no-op (the caller gets the URL back from `redirectToAuthorize`).
+ * @param {string} url
+ */
+function defaultRedirect (url) {
+  const loc = (typeof globalThis !== 'undefined') ? globalThis.location : undefined;
+  if (loc && typeof loc.assign === 'function') loc.assign(url);
+}
+
+/**
+ * @private
+ * `globalThis.sessionStorage` in a browser, else a process-local in-memory store
+ * (sufficient for tests and non-browser callers that inject nothing).
+ * @returns {OAuth2Storage}
+ */
+function defaultStorage () {
+  if (typeof globalThis !== 'undefined' && globalThis.sessionStorage) return globalThis.sessionStorage;
+  const map = new Map();
+  return {
+    getItem: (k) => (map.has(k) ? map.get(k) : null),
+    setItem: (k, v) => { map.set(k, String(v)); },
+    removeItem: (k) => { map.delete(k); }
+  };
+}
+
+/**
+ * @private
+ * @param {string} queryString
+ * @returns {string}
+ */
+function stripLeadingQuestionMark (queryString) {
+  const s = queryString || '';
+  return s.charAt(0) === '?' ? s.slice(1) : s;
+}
+
+module.exports = OAuth2Client;

package/src/index.d.ts

@@ -1059,6 +1059,47 @@ declare module 'pryv' {
     get state(): AuthStatePayload;
   }
 
+  /**
+   * Web-Storage-like store used by OAuth2Client to hold the per-flow PKCE verifier.
+   */
+  export type OAuth2ClientStorage = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+  };
+
+  export type OAuth2ClientOptions = {
+    /** Issuer / Pryv API base URL; discovery doc read from `<url>/.well-known/oauth-authorization-server`. */
+    authorizationServer: string;
+    /** App-account client id. */
+    clientId: string;
+    /** Registered redirect URI. */
+    redirectUri: string;
+    /** Consent-offer reference registered on the client, e.g. `'cmc:study-A'`. */
+    scope?: string;
+    /** Defaults to `globalThis.sessionStorage` (browser) or an in-memory store. */
+    storage?: OAuth2ClientStorage;
+  };
+
+  /**
+   * Browser-side consumer of the Pryv OAuth2 authorization-code (PKCE) flow.
+   */
+  export class OAuth2Client {
+    constructor(options: OAuth2ClientOptions);
+    issuer: URL;
+    clientId: string;
+    redirectUri: string;
+    scope?: string;
+    /** Last raw token-endpoint response (access_token, scope, apiEndpoint, …). */
+    lastTokenResponse: { [key: string]: unknown } | null;
+    /** Build + navigate to the `/oauth2/authorize` URL; returns the URL. */
+    redirectToAuthorize(options?: { state?: string; redirect?: (url: string) => void }): Promise<string>;
+    /** Validate the callback, exchange the code (PKCE), return a Connection. */
+    handleCallback(queryString: string): Promise<Connection>;
+    /** Exchange the stored refresh token for a fresh Connection. */
+    refresh(): Promise<Connection>;
+  }
+
   export const Auth: {
     setupAuth: SetupAuth;
     AuthStates: AuthStates;
@@ -1116,6 +1157,7 @@ declare module 'pryv' {
   let pryv: {
     Service: typeof Service;
     Connection: typeof Connection;
+    OAuth2Client: typeof OAuth2Client;
     Auth: {
       setupAuth: SetupAuth;
       AuthStates: AuthStates;
@@ -1132,15 +1174,11 @@ declare module 'pryv' {
       setupAuth: SetupAuth;
       serviceInfoFromUrl: getServiceInfoFromURL;
     };
-    utils: {
-      isBrowser(): boolean;
-      extractTokenAndAPIEndpoint(apiEndpoint: string): TokenAndAPIEndpoint;
-      buildAPIEndpoint(tokenAndAPI: TokenAndAPIEndpoint): string;
-      decomposeAPIEndpoint(apiEndpoint: string, serviceInfoApi: string): DecomposedAPIEndpoint;
-      browserIsMobileOrTablet(navigator?: string | Navigator): boolean;
-      cleanURLFromPrYvParams(url: string): string;
-      getQueryParamsFromURL(url: string): KeyValue;
-    };
+    // Reference the named export's type — a duplicated inline shape here
+    // drifted from it once already (the deprecated aliases were missing),
+    // which broke structural typing for add-ons taking the default export
+    // (e.g. @pryv/socket.io's PryvLibrary).
+    utils: typeof utils;
     PryvError: typeof PryvError;
     MfaRequiredError: typeof MfaRequiredError;
     ERRORS: typeof ERRORS;

package/src/index.js

@@ -8,6 +8,7 @@
  * @property {pryv.Service} Service - To interact with Pryv.io at a "Platform level"
  * @property {pryv.Connection} Connection - To interact with an individual's (user) data set
  * @property {pryv.Browser} Browser - Browser Tools - Access request helpers and visuals (button)
+ * @property {pryv.OAuth2Client} OAuth2Client - Browser-side OAuth2 authorization-code (PKCE) flow consumer
  * @property {pryv.utils} utils - Exposes some utils for HTTP calls and tools to manipulate Pryv's API endpoints
  * @property {pryv.PryvError} PryvError - Custom error class with innerObject + structured API-error fields
  * @property {pryv.MfaRequiredError} MfaRequiredError - Thrown by Service.login when the platform returns an mfaToken instead of a token. Carries `.mfaToken`.
@@ -21,6 +22,7 @@ module.exports = {
   Connection: require('./Connection'),
   Auth: require('./Auth'),
   Browser: require('./Browser'),
+  OAuth2Client: require('./OAuth2Client'),
   utils: require('./utils'),
   PryvError: require('./lib/PryvError'),
   MfaRequiredError: require('./lib/MfaRequiredError'),

package/src/utils.js

@@ -215,14 +215,29 @@ const utils = module.exports = {
   },
 
   /**
-   * Remove Pryv-specific query parameters from URL
+   * Remove the one-shot Pryv auth-completion query parameters from a URL,
+   * keeping any long-lived `pryv*` params intact.
+   *
+   * Both casings are stripped:
+   *   - Modern lowercase: `pryvKey`, `pryvPoll`
+   *   - Legacy capital-Y: `prYv<anything>` (anything starting with `prYv`)
+   *
+   * `pryv*` params that are NOT in the modern allowlist (e.g.
+   * `pryvServiceInfoUrl`, `pryvApiEndpoint`) are intentionally preserved —
+   * they are not one-shot.
+   *
    * @memberof pryv.utils
    * @param {string} url - URL to clean
-   * @returns {string} URL without prYv* parameters
+   * @returns {string} URL without the one-shot auth-completion params
    */
   cleanURLFromPrYvParams: function (url) {
-    const PRYV_REGEXP = /[?#&]+prYv([^=&]+)=([^&]*)/g;
-    return url.replace(PRYV_REGEXP, '');
+    // Legacy form: kept for back-compat with apps still emitting
+    // `prYv<anything>=...` (notably app-web-user-account's close_or_redirect).
+    const LEGACY = /[?#&]+prYv([^=&]+)=([^&]*)/g;
+    // Modern form: an explicit allowlist of one-shot params so we never
+    // wipe long-lived camelCase `pryv*` params by accident.
+    const MODERN = /[?#&]+(pryvKey|pryvPoll)=([^&]*)/g;
+    return url.replace(LEGACY, '').replace(MODERN, '');
   },
 
   /**

package/test/Connection.authHeader.test.js

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, beforeEach, afterEach, expect, pryv */
+
+// Pure unit check of the Authorization header shape. The API expects the bare
+// access token (optionally suffixed with a caller id) in the Authorization
+// header — NOT an RFC 6750 `Bearer <token>` scheme. Older/released cores parse
+// the header by splitting on the first space, so a `Bearer ` prefix would be
+// taken as the token and break auth; the bare token is what every core version
+// accepts. This asserts no scheme prefix is added on the GET or POST path.
+describe('[CAUTH] Connection Authorization header', function () {
+  let originalFetch;
+  let captured;
+
+  beforeEach(function () {
+    captured = [];
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = async (url, init) => {
+      captured.push({ url: String(url), headers: (init && init.headers) || {} });
+      return new Response(JSON.stringify({ meta: { serverTime: 1 } }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' }
+      });
+    };
+  });
+  afterEach(function () { globalThis.fetch = originalFetch; });
+
+  it('[CAU1] GET requests send the bare token (no scheme prefix)', async function () {
+    const conn = new pryv.Connection('https://TESTTOKEN@user.example.com/');
+    await conn.get('events');
+    expect(captured).to.have.length(1);
+    expect(captured[0].headers.Authorization).to.equal('TESTTOKEN');
+  });
+
+  it('[CAU2] POST requests send the bare token (no scheme prefix)', async function () {
+    const conn = new pryv.Connection('https://TESTTOKEN@user.example.com/');
+    await conn.post('events', { streamIds: ['x'], type: 'note/txt', content: 'hi' });
+    expect(captured).to.have.length(1);
+    expect(captured[0].headers.Authorization).to.equal('TESTTOKEN');
+  });
+});

package/test/OAuth2Client.test.js

@@ -0,0 +1,394 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, beforeEach, afterEach, expect */
+
+const OAuth2Client = require('../src/OAuth2Client');
+const oauth = require('oauth4webapi');
+
+const ISSUER = 'https://host';
+const DISCOVERY = {
+  issuer: ISSUER,
+  authorization_endpoint: ISSUER + '/oauth2/authorize',
+  token_endpoint: ISSUER + '/oauth2/token',
+  response_types_supported: ['code'],
+  grant_types_supported: ['authorization_code', 'refresh_token'],
+  token_endpoint_auth_methods_supported: ['client_secret_basic', 'none'],
+  code_challenge_methods_supported: ['S256']
+};
+
+// A Pryv token-endpoint response (RFC 6749 §5.1 + the `apiEndpoint` extension).
+function tokenBody (overrides = {}) {
+  return Object.assign({
+    access_token: 'TOKEN123',
+    token_type: 'Bearer',
+    expires_in: 3600,
+    refresh_token: 'REFRESH456',
+    scope: 'cmc:study-A',
+    apiEndpoint: 'https://TOKEN123@host/path/'
+  }, overrides);
+}
+
+function jsonResponse (body, status = 200) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' }
+  });
+}
+
+function memoryStorage () {
+  const map = new Map();
+  return {
+    map,
+    getItem: (k) => (map.has(k) ? map.get(k) : null),
+    setItem: (k, v) => { map.set(k, String(v)); },
+    removeItem: (k) => { map.delete(k); }
+  };
+}
+
+// Install a global.fetch mock serving discovery + a configurable token response.
+// Returns a handle exposing the captured token request and lets tests override
+// the token response.
+function installFetchMock () {
+  const state = { tokenResponse: jsonResponse(tokenBody()), lastTokenRequest: null, discovery: null, tokenRequestCount: 0 };
+  const original = globalThis.fetch;
+  globalThis.fetch = async (input, init) => {
+    const url = String(input && input.url ? input.url : input);
+    if (url.includes('.well-known/oauth-authorization-server')) {
+      return jsonResponse(state.discovery || DISCOVERY);
+    }
+    if (url === DISCOVERY.token_endpoint) {
+      state.tokenRequestCount++;
+      state.lastTokenRequest = { url, init, body: init && init.body ? init.body.toString() : '' };
+      // A Response body is single-use; clone so a test can reuse one response
+      // object across sequential requests without an "already read" error.
+      return (state.tokenResponse instanceof Response) ? state.tokenResponse.clone() : state.tokenResponse;
+    }
+    throw new Error('unexpected fetch: ' + url);
+  };
+  state.restore = () => { globalThis.fetch = original; };
+  return state;
+}
+
+function newClient (storage, overrides = {}) {
+  return new OAuth2Client(Object.assign({
+    authorizationServer: ISSUER,
+    clientId: 'app1',
+    redirectUri: 'https://app.example/cb',
+    scope: 'cmc:study-A',
+    storage
+  }, overrides));
+}
+
+describe('[OAUTH-LIB] OAuth2Client', function () {
+  let fetchMock;
+  beforeEach(function () { fetchMock = installFetchMock(); });
+  afterEach(function () { fetchMock.restore(); });
+
+  describe('[OAL-CTOR] constructor validation', function () {
+    it('[OAL-C1] throws without authorizationServer', function () {
+      expect(() => new OAuth2Client({ clientId: 'a', redirectUri: 'b' }))
+        .to.throw(/authorizationServer/);
+    });
+    it('[OAL-C2] throws without clientId', function () {
+      expect(() => new OAuth2Client({ authorizationServer: ISSUER, redirectUri: 'b' }))
+        .to.throw(/clientId/);
+    });
+    it('[OAL-C3] throws without redirectUri', function () {
+      expect(() => new OAuth2Client({ authorizationServer: ISSUER, clientId: 'a' }))
+        .to.throw(/redirectUri/);
+    });
+  });
+
+  describe('[OAL-AUTH] redirectToAuthorize', function () {
+    it('[OAL-A1] builds the authorize URL with all required params', async function () {
+      const storage = memoryStorage();
+      const client = newClient(storage);
+      const url = await client.redirectToAuthorize({ state: 'STATE123' });
+      const u = new URL(url);
+      expect(u.origin + u.pathname).to.equal(DISCOVERY.authorization_endpoint);
+      expect(u.searchParams.get('response_type')).to.equal('code');
+      expect(u.searchParams.get('client_id')).to.equal('app1');
+      expect(u.searchParams.get('redirect_uri')).to.equal('https://app.example/cb');
+      expect(u.searchParams.get('scope')).to.equal('cmc:study-A');
+      expect(u.searchParams.get('state')).to.equal('STATE123');
+      expect(u.searchParams.get('code_challenge_method')).to.equal('S256');
+    });
+
+    it('[OAL-A2] stores a PKCE verifier keyed by state; challenge = base64url(sha256(verifier))', async function () {
+      const storage = memoryStorage();
+      const client = newClient(storage);
+      const url = await client.redirectToAuthorize({ state: 'S' });
+      const verifier = storage.getItem('pryv-oauth2-verifier:S');
+      expect(verifier).to.be.a('string').with.length.greaterThan(42);
+      const challenge = new URL(url).searchParams.get('code_challenge');
+      expect(challenge).to.match(/^[A-Za-z0-9_-]{43}$/);
+      const expected = await oauth.calculatePKCECodeChallenge(verifier);
+      expect(challenge).to.equal(expected);
+    });
+
+    it('[OAL-A3] generates a random state when none is supplied', async function () {
+      const storage = memoryStorage();
+      const client = newClient(storage);
+      const url = await client.redirectToAuthorize();
+      const state = new URL(url).searchParams.get('state');
+      expect(state).to.be.a('string').with.length.greaterThan(0);
+      expect(storage.getItem('pryv-oauth2-verifier:' + state)).to.be.a('string');
+    });
+
+    it('[OAL-A4] invokes the provided redirect function with the URL', async function () {
+      const storage = memoryStorage();
+      const client = newClient(storage);
+      let redirected = null;
+      const url = await client.redirectToAuthorize({ state: 'S', redirect: (u) => { redirected = u; } });
+      expect(redirected).to.equal(url);
+    });
+
+    it('[OAL-A5] omits scope from the URL when not configured', async function () {
+      const storage = memoryStorage();
+      const client = newClient(storage, { scope: undefined });
+      const url = await client.redirectToAuthorize({ state: 'S' });
+      expect(new URL(url).searchParams.has('scope')).to.equal(false);
+    });
+
+    it('[OAL-A6] allows an http authorization_endpoint on a loopback host (local dev)', async function () {
+      const storage = memoryStorage();
+      fetchMock.discovery = Object.assign({}, DISCOVERY, {
+        authorization_endpoint: 'http://127.0.0.1:3000/oauth2/authorize'
+      });
+      const client = newClient(storage);
+      const url = await client.redirectToAuthorize({ state: 'S', redirect: () => {} });
+      expect(new URL(url).protocol).to.equal('http:');
+      expect(new URL(url).hostname).to.equal('127.0.0.1');
+    });
+
+    it('[OAL-A7] refuses a non-loopback http authorization_endpoint (MITM discovery)', async function () {
+      const storage = memoryStorage();
+      fetchMock.discovery = Object.assign({}, DISCOVERY, {
+        authorization_endpoint: 'http://evil.example/oauth2/authorize'
+      });
+      const client = newClient(storage);
+      let navigated = null;
+      await expect(client.redirectToAuthorize({ state: 'S', redirect: (u) => { navigated = u; } }))
+        .to.be.rejectedWith(/insecure|https/);
+      expect(navigated).to.equal(null); // never navigated the browser
+    });
+
+    it('[OAL-A8] refuses a javascript: authorization_endpoint', async function () {
+      const storage = memoryStorage();
+      fetchMock.discovery = Object.assign({}, DISCOVERY, {
+        authorization_endpoint: 'javascript:alert(document.cookie)'
+      });
+      const client = newClient(storage);
+      await expect(client.redirectToAuthorize({ state: 'S', redirect: () => {} }))
+        .to.be.rejectedWith(/insecure|https/);
+    });
+  });
+
+  describe('[OAL-CB] handleCallback', function () {
+    async function primedClient (storage) {
+      const client = newClient(storage);
+      await client.redirectToAuthorize({ state: 'S', redirect: () => {} });
+      return client;
+    }
+
+    it('[OAL-B1] exchanges the code and returns a Connection built from apiEndpoint', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      const connection = await client.handleCallback('?code=CODE&state=S');
+      expect(connection.constructor.name).to.equal('Connection');
+      expect(connection.token).to.equal('TOKEN123');
+      expect(connection.endpoint).to.equal('https://host/path/');
+    });
+
+    it('[OAL-B2] sends grant_type=authorization_code + the PKCE verifier to the token endpoint', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      const verifier = storage.getItem('pryv-oauth2-verifier:S');
+      await client.handleCallback('?code=CODE&state=S');
+      const body = new URLSearchParams(fetchMock.lastTokenRequest.body);
+      expect(body.get('grant_type')).to.equal('authorization_code');
+      expect(body.get('code')).to.equal('CODE');
+      expect(body.get('code_verifier')).to.equal(verifier);
+      expect(body.get('redirect_uri')).to.equal('https://app.example/cb');
+    });
+
+    it('[OAL-B3] removes the stored verifier after a successful exchange', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      await client.handleCallback('?code=CODE&state=S');
+      expect(storage.getItem('pryv-oauth2-verifier:S')).to.equal(null);
+    });
+
+    it('[OAL-B4] accepts a query string without a leading question mark', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      const connection = await client.handleCallback('code=CODE&state=S');
+      expect(connection.token).to.equal('TOKEN123');
+    });
+
+    it('[OAL-B5] throws when the callback has no state', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      await expect(client.handleCallback('?code=CODE')).to.be.rejectedWith(/state/);
+    });
+
+    it('[OAL-B6] throws when no verifier is stored for the state (forged/expired)', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      await expect(client.handleCallback('?code=CODE&state=OTHER')).to.be.rejectedWith(/verifier/);
+    });
+
+    it('[OAL-B7] throws when the token response lacks the apiEndpoint extension', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      const body = tokenBody();
+      delete body.apiEndpoint;
+      fetchMock.tokenResponse = jsonResponse(body);
+      await expect(client.handleCallback('?code=CODE&state=S')).to.be.rejectedWith(/apiEndpoint/);
+    });
+
+    it('[OAL-B8] removes the stored verifier even when the exchange fails', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      const body = tokenBody();
+      delete body.apiEndpoint; // force _connectionFromTokenResponse to throw
+      fetchMock.tokenResponse = jsonResponse(body);
+      await expect(client.handleCallback('?code=CODE&state=S')).to.be.rejected;
+      expect(storage.getItem('pryv-oauth2-verifier:S')).to.equal(null);
+    });
+
+    it('[OAL-B9] refuses an insecure (non-https, non-loopback) apiEndpoint', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ apiEndpoint: 'http://TOKEN123@evil.example/path/' }));
+      await expect(client.handleCallback('?code=CODE&state=S')).to.be.rejectedWith(/insecure|https/);
+    });
+
+    it('[OAL-B10] allows an http apiEndpoint on a loopback host (local dev)', async function () {
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ apiEndpoint: 'http://TOKEN123@127.0.0.1:3000/path/' }));
+      const connection = await client.handleCallback('?code=CODE&state=S');
+      expect(connection.token).to.equal('TOKEN123');
+    });
+
+    it('[OAL-B11] refuses a loopback-spoofing apiEndpoint whose real endpoint is a remote http host', async function () {
+      // Connection splits token/endpoint on the LAST `@`, so this parses as
+      // token `tok@127.0.0.1/x`, endpoint `http://evil.example/` — the token
+      // would go to evil.example in cleartext. The guard must validate the
+      // extracted endpoint, not the loopback-looking raw string.
+      const storage = memoryStorage();
+      const client = await primedClient(storage);
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ apiEndpoint: 'http://tok@127.0.0.1/x@evil.example/' }));
+      await expect(client.handleCallback('?code=CODE&state=S')).to.be.rejectedWith(/insecure|https/);
+    });
+  });
+
+  describe('[OAL-RF] refresh', function () {
+    it('[OAL-R1] throws before any successful callback', async function () {
+      const storage = memoryStorage();
+      const client = newClient(storage);
+      await expect(client.refresh()).to.be.rejectedWith(/refresh token/);
+    });
+
+    it('[OAL-R2] exchanges the stored refresh token for a fresh Connection', async function () {
+      const storage = memoryStorage();
+      const client = newClient(storage);
+      await client.redirectToAuthorize({ state: 'S', redirect: () => {} });
+      await client.handleCallback('?code=CODE&state=S');
+      fetchMock.tokenResponse = jsonResponse(tokenBody({
+        access_token: 'TOKEN789',
+        apiEndpoint: 'https://TOKEN789@host/path/'
+      }));
+      const connection = await client.refresh();
+      expect(connection.token).to.equal('TOKEN789');
+      const body = new URLSearchParams(fetchMock.lastTokenRequest.body);
+      expect(body.get('grant_type')).to.equal('refresh_token');
+      expect(body.get('refresh_token')).to.equal('REFRESH456');
+    });
+
+    async function primed (storage, overrides = {}) {
+      const client = newClient(storage, overrides);
+      await client.redirectToAuthorize({ state: 'S', redirect: () => {} });
+      await client.handleCallback('?code=CODE&state=S');
+      return client;
+    }
+
+    it('[OAL-R3-F1] serializes concurrent refresh() onto ONE token request', async function () {
+      const client = await primed(memoryStorage());
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ access_token: 'T2', refresh_token: 'R2', apiEndpoint: 'https://T2@host/p/' }));
+      fetchMock.tokenRequestCount = 0;
+      const [c1, c2] = await Promise.all([client.refresh(), client.refresh()]);
+      expect(fetchMock.tokenRequestCount).to.equal(1); // deduped, no reuse loser
+      expect(c1.token).to.equal('T2');
+      expect(c2.token).to.equal('T2');
+    });
+
+    it('[OAL-R4-F1] a new refresh() after the in-flight one settles issues a fresh request', async function () {
+      const client = await primed(memoryStorage());
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ refresh_token: 'R2', apiEndpoint: 'https://T2@host/p/' }));
+      await client.refresh();
+      fetchMock.tokenRequestCount = 0;
+      await client.refresh();
+      expect(fetchMock.tokenRequestCount).to.equal(1); // slot cleared, not stuck
+    });
+
+    it('[OAL-R5-F2] persists the rotated refresh token even when apiEndpoint validation throws', async function () {
+      const client = await primed(memoryStorage());
+      // Server rotates (REFRESH456 -> ROTATED1) but the response has no apiEndpoint
+      // => _connectionFromTokenResponse throws AFTER the token was ingested.
+      const bad = tokenBody({ refresh_token: 'ROTATED1' });
+      delete bad.apiEndpoint;
+      fetchMock.tokenResponse = jsonResponse(bad);
+      await expect(client.refresh()).to.be.rejectedWith(/apiEndpoint/);
+      // The old token is dead server-side; the client must now hold ROTATED1,
+      // and a subsequent refresh() must present it (not the stale REFRESH456).
+      expect(client.refreshToken).to.equal('ROTATED1');
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ access_token: 'T3', refresh_token: 'R3', apiEndpoint: 'https://T3@host/p/' }));
+      const conn = await client.refresh();
+      expect(conn.token).to.equal('T3');
+      expect(new URLSearchParams(fetchMock.lastTokenRequest.body).get('refresh_token')).to.equal('ROTATED1');
+    });
+  });
+
+  describe('[OAL-SEAM] refresh-token persistence seam (F3)', function () {
+    it('[OAL-S1] refresh() works from a constructor-seeded refresh token (no handleCallback)', async function () {
+      const client = newClient(memoryStorage(), { refreshToken: 'SEEDED' });
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ access_token: 'T2', apiEndpoint: 'https://T2@host/p/' }));
+      const conn = await client.refresh();
+      expect(conn.token).to.equal('T2');
+      expect(new URLSearchParams(fetchMock.lastTokenRequest.body).get('refresh_token')).to.equal('SEEDED');
+    });
+
+    it('[OAL-S2] the refreshToken getter reflects the rotated value', async function () {
+      const client = newClient(memoryStorage(), { refreshToken: 'SEEDED' });
+      expect(client.refreshToken).to.equal('SEEDED');
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ refresh_token: 'ROTATED', apiEndpoint: 'https://T2@host/p/' }));
+      await client.refresh();
+      expect(client.refreshToken).to.equal('ROTATED');
+    });
+
+    it('[OAL-S3] onTokenRotated fires with the new token on callback and each refresh', async function () {
+      const storage = memoryStorage();
+      const rotations = [];
+      const client = newClient(storage, { onTokenRotated: (t) => rotations.push(t) });
+      await client.redirectToAuthorize({ state: 'S', redirect: () => {} });
+      await client.handleCallback('?code=CODE&state=S'); // REFRESH456
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ refresh_token: 'ROTATED', apiEndpoint: 'https://T2@host/p/' }));
+      await client.refresh();
+      expect(rotations).to.deep.equal(['REFRESH456', 'ROTATED']);
+    });
+
+    it('[OAL-S4] a throwing onTokenRotated never breaks the exchange', async function () {
+      const client = newClient(memoryStorage(), {
+        refreshToken: 'SEEDED',
+        onTokenRotated: () => { throw new Error('persist boom'); }
+      });
+      fetchMock.tokenResponse = jsonResponse(tokenBody({ access_token: 'T2', apiEndpoint: 'https://T2@host/p/' }));
+      const conn = await client.refresh();
+      expect(conn.token).to.equal('T2');
+    });
+  });
+});

package/test/esm-deps.test.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, expect */
+
+// `pryv` consumes the ESM-only `oauth4webapi` package via Node's require(esm)
+// (unflagged on Node >= 20.19 / >= 22.12 — hence the engines floor). That only
+// works while nothing in the package's import graph uses top-level await; a
+// future dependency upgrade that introduced TLA would throw
+// ERR_REQUIRE_ASYNC_MODULE at require time. This guard makes such an upgrade
+// fail here in CI instead of at consumer runtime.
+describe('[ESMD] ESM-only deps load via require(esm)', function () {
+  it('[ESMD1] oauth4webapi requires synchronously (no top-level await in its graph)', function () {
+    const oauth = require('oauth4webapi');
+    expect(typeof oauth.generateRandomCodeVerifier).to.equal('function');
+    expect(typeof oauth.calculatePKCECodeChallenge).to.equal('function');
+  });
+});

package/test/utils.test.js

@@ -104,6 +104,36 @@ describe('[UTLX] utils', function () {
     expect(err.name).to.equal('StaleAccessIdError');
   });
 
+  describe('[UTLN] cleanURLFromPrYvParams', function () {
+    it('[UTLNA] strips legacy capital-Y prYv* params', function () {
+      const out = pryv.utils.cleanURLFromPrYvParams(
+        'http://example.com/page?keep=1&prYvkey=abc&prYvpoll=http%3A%2F%2Fpoll&prYvstatus=ACCEPTED'
+      );
+      expect(out).to.equal('http://example.com/page?keep=1');
+    });
+    it('[UTLNB] strips modern lowercase one-shot params (pryvKey, pryvPoll)', function () {
+      const out = pryv.utils.cleanURLFromPrYvParams(
+        'http://example.com/page?keep=1&pryvKey=abc&pryvPoll=http%3A%2F%2Fpoll'
+      );
+      expect(out).to.equal('http://example.com/page?keep=1');
+    });
+    it('[UTLNC] PRESERVES long-lived modern params (pryvServiceInfoUrl, pryvApiEndpoint)', function () {
+      const out = pryv.utils.cleanURLFromPrYvParams(
+        'http://example.com/page?pryvServiceInfoUrl=https%3A%2F%2Freg.pryv.me%2Fservice%2Finfo&pryvApiEndpoint=https%3A%2F%2Fuser.pryv.me%2F&pryvKey=abc'
+      );
+      // pryvKey is stripped (one-shot), the other two stay (long-lived).
+      expect(out).to.contain('pryvServiceInfoUrl=');
+      expect(out).to.contain('pryvApiEndpoint=');
+      expect(out).not.to.contain('pryvKey=');
+    });
+    it('[UTLND] strips both forms in a single URL', function () {
+      const out = pryv.utils.cleanURLFromPrYvParams(
+        'http://example.com/page?keep=1&prYvkey=legacy&pryvKey=modern&prYvpoll=oldpoll&pryvPoll=newpoll'
+      );
+      expect(out).to.equal('http://example.com/page?keep=1');
+    });
+  });
+
   describe('[UTLM] decomposeAPIEndpoint', function () {
     it('[UTLMA] subdomain template — host strips the {username}. prefix', function () {
       const r = pryv.utils.decomposeAPIEndpoint(