pryv 3.8.0 → 3.10.0

package/README.md

@@ -58,6 +58,7 @@ Other distributions available:
 - Socket.IO: [NPM package](https://www.npmjs.com/package/@pryv/socket.io), [README](https://github.com/pryv/lib-js/tree/master/components/pryv-socket.io#readme)
 - Monitor: [NPM package](https://www.npmjs.com/package/@pryv/monitor), [README](https://github.com/pryv/lib-js/tree/master/components/pryv-monitor#readme)
 - CMC (Cross-account Messaging & Consent) client helpers: [NPM package](https://www.npmjs.com/package/@pryv/cmc), [README](https://github.com/pryv/lib-js/tree/master/components/pryv-cmc#readme)
+- Encryption (client-side event encryption/decryption): [README](https://github.com/pryv/lib-js/tree/master/components/pryv-encryption#readme)
 
 
 ### Quick example
@@ -144,6 +145,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 +540,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
 
@@ -679,6 +718,7 @@ The project is structured as a monorepo with components (a.k.a. workspaces in NP
 - `pryv-socket.io`: Socket.IO add-on
 - `pryv-monitor`: Monitor add-on
 - `pryv-cmc`: CMC (Cross-account Messaging & Consent) client helpers
+- `pryv-encryption`: client-side event encryption/decryption add-on
 
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pryv",
-  "version": "3.8.0",
+  "version": "3.10.0",
   "description": "Pryv JavaScript library",
   "keywords": [
     "Pryv",
@@ -18,8 +18,10 @@
   "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/Connection.js

@@ -263,7 +263,7 @@ class Connection {
    */
   async _postFetchRaw (path, data, contentType) {
     const headers = {
-      Authorization: this.token,
+      ...(await this._authHeaders('POST', this.endpoint + path)),
       Accept: 'application/json'
     };
     // optional for form-data llowing fetch to
@@ -280,6 +280,19 @@ class Connection {
     return { response, body };
   }
 
+  /**
+   * @protected
+   * Authentication headers for a request. The base Connection sends the
+   * bearer token as-is; {@link SignedConnection} overrides this to attach a
+   * per-request DPoP (RFC 9449) proof. Async because a proof requires signing.
+   * @param {string} method - HTTP method (informs the proof's `htm`)
+   * @param {string} url - full request URL WITHOUT query (informs `htu`)
+   * @returns {Promise<Object>} header map to merge into the request
+   */
+  async _authHeaders (method, url) {
+    return { Authorization: this.token };
+  }
+
   /**
    * GET from API and return results
    * @param {string} path - API path
@@ -308,7 +321,7 @@ class Connection {
     }
     const response = await fetch(this.endpoint + path + queryStr, {
       headers: {
-        Authorization: this.token,
+        ...(await this._authHeaders('GET', this.endpoint + path)),
         Accept: 'application/json'
       }
     });

package/src/OAuth2Client.js

@@ -0,0 +1,391 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+const oauth = require('oauth4webapi');
+const Connection = require('./Connection');
+const SignedConnection = require('./SignedConnection');
+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).
+   * @param {boolean} [options.dpop=false] - Opt into RFC 9449 DPoP: an ES256 key
+   *   pair is generated per client, the token is bound to it at issuance, and
+   *   `handleCallback()` / `refresh()` return a {@link SignedConnection} that
+   *   proves possession of the key on every request. A token stolen from the
+   *   resulting connection is useless without the private key. The key is
+   *   session-scoped (not persisted) — re-seeding a `refreshToken` after reload
+   *   mints a fresh binding for the new key.
+   */
+  constructor (options = {}) {
+    const { authorizationServer, clientId, redirectUri, scope, storage, refreshToken, onTokenRotated, dpop } = 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;
+    // DPoP (RFC 9449): lazily generated ES256 key pair + oauth4webapi handle,
+    // shared between the token-endpoint proofs (handle) and the resulting
+    // SignedConnection's per-request proofs (same key → same bound thumbprint).
+    this._dpop = dpop === true;
+    this._dpopKeyPair = null;
+    this._dpopHandle = 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 generate the DPoP ES256 key pair + oauth4webapi handle (once).
+   * Returns `undefined` when DPoP is off, so call sites can spread it as an
+   * absent option. The key is `extractable` so the resulting
+   * {@link SignedConnection} can export the public JWK into each proof.
+   * @returns {Promise<Object|undefined>} the DPoP handle, or undefined
+   */
+  async _ensureDPoP () {
+    if (!this._dpop) return undefined;
+    if (this._dpopHandle == null) {
+      this._dpopKeyPair = await oauth.generateKeyPair('ES256', { extractable: true });
+      // DPoP() only reads the optional `clockSkew` symbol off the client; our
+      // public-client literal carries none, which trips oauth4webapi's
+      // weak-type guard on the branded param. Cast — the value is correct.
+      this._dpopHandle = oauth.DPoP(/** @type {any} */ (this._client), this._dpopKeyPair);
+    }
+    return this._dpopHandle;
+  }
+
+  /**
+   * @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 dpopHandle = await this._ensureDPoP();
+      const response = await oauth.authorizationCodeGrantRequest(
+        as, this._client, this._clientAuth, callbackParams, this.redirectUri, codeVerifier,
+        dpopHandle ? { DPoP: dpopHandle } : undefined
+      );
+      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 dpopHandle = await this._ensureDPoP();
+    const response = await oauth.refreshTokenGrantRequest(
+      as, this._client, this._clientAuth, this._refreshToken,
+      dpopHandle ? { DPoP: dpopHandle } : undefined
+    );
+    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);
+    // DPoP flow → a SignedConnection bound to the same key the token was
+    // issued against; every request then carries a proof of possession.
+    if (this._dpop) return new SignedConnection(String(apiEndpoint), this._dpopKeyPair);
+    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;