pryv 3.8.0 → 3.10.0

package/src/SharedSecrets.js

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * Copyright (C) Pryv https://pryv.com
+ * This file is part of Pryv.io and released under BSD-Clause-3 License
+ * Refer to LICENSE file
+ */
+
+/**
+ * Shared secrets — hand a secret to a third party by one-time key.
+ *
+ * The problem this solves: passing a secret (typically an apiEndpoint carrying
+ * an access token) to a third party usually means putting it in a URL, where it
+ * survives in browser history, referrer headers and server access logs. Instead,
+ * store the secret on the account and hand over a random key that can be
+ * redeemed exactly once.
+ *
+ * Redemption needs no credentials — the key IS the credential — so the third
+ * party can use `retrieve` with nothing but the URL you gave them.
+ *
+ * All crypto goes through the Web Crypto API rather than Node's `crypto`, so the
+ * same code runs in the browser bundle and in Node.
+ */
+
+/** Reads `key` back into the pieces the API expects. */
+function parseKey (key) {
+  if (typeof key !== 'string') return null;
+  const parts = key.split('.');
+  if (parts.length !== 2 || parts[0].length === 0 || parts[1].length === 0) return null;
+  return { id: parts[0], randomPart: parts[1] };
+}
+
+function base64url (bytes) {
+  let binary = '';
+  for (const b of new Uint8Array(bytes)) binary += String.fromCharCode(b);
+  const b64 = typeof btoa === 'function'
+    ? btoa(binary)
+    : Buffer.from(binary, 'binary').toString('base64');
+  return b64.replace(/=+$/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+function toHex (buffer) {
+  return Array.from(new Uint8Array(buffer))
+    .map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+function subtle () {
+  const c = globalThis.crypto;
+  if (c == null || c.subtle == null) {
+    throw new Error('Web Crypto is unavailable — Node 20+ or a secure browser context is required.');
+  }
+  return c.subtle;
+}
+
+/** 24 random bytes (192 bits), base64url — the strength of the key itself. */
+function randomPart () {
+  const bytes = new Uint8Array(24);
+  globalThis.crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+/** SHA-256 of a string, hex — what the server stores in place of the key. */
+async function sha256Hex (value) {
+  const data = new TextEncoder().encode(value);
+  return toHex(await subtle().digest('SHA-256', data));
+}
+
+/**
+ * HMAC-SHA256 of `message` under `verifierSecret`, hex.
+ *
+ * Used for the `hmac-sha256` signature: creator and redeemer share the verifier
+ * secret out of band, and only the HMAC ever reaches the server — so the server
+ * can check the proof without being able to produce one.
+ */
+async function hmacSha256Hex (verifierSecret, message) {
+  const enc = new TextEncoder();
+  const cryptoKey = await subtle().importKey(
+    'raw', enc.encode(verifierSecret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  return toHex(await subtle().sign('HMAC', cryptoKey, enc.encode(message)));
+}
+
+/**
+ * Create a shared secret on the account `connection` is authenticated against.
+ *
+ * @param {Connection} connection
+ * @param {Object} params
+ * @param {number} params.ttl seconds the secret stays redeemable (required)
+ * @param {string} params.title shown to the account owner (required)
+ * @param {Object} params.onConsumed `{ message, returnUrl? }` shown once spent
+ * @param {*} params.secret the payload — any JSON value
+ * @param {Object} [params.signature] `{ type: 'secret', value }` or
+ *   `{ type: 'hmac-sha256', verifierSecret }`. For the HMAC form the key
+ *   material is generated here so the proof can be bound before creation.
+ * @returns {Promise<Object>} `{ id, key, expires, ... }` — `key` is returned
+ *   only here and cannot be recovered later.
+ */
+async function create (connection, params) {
+  const { signature, ...rest } = params || {};
+  const body = { ...rest };
+  let key = null;
+
+  if (signature != null && signature.type === 'hmac-sha256') {
+    // The HMAC is bound to key material that must exist BEFORE the item does,
+    // so the client generates the random half and sends only its hash.
+    const random = randomPart();
+    body.keyHash = await sha256Hex(random);
+    body.signature = {
+      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 };
+  }
+
+  if (signature != null) body.signature = signature;
+  const res = await connection.post('shared-secrets', body);
+  key = res.sharedSecret.key;
+  return { ...res.sharedSecret, key };
+}
+
+/**
+ * Redeem a key. Needs no credentials, so a third party can call it directly.
+ *
+ * @param {string} apiEndpoint the account's API endpoint (no token needed)
+ * @param {string} key
+ * @param {Object} [options]
+ * @param {string} [options.passphrase] for a `secret`-type signature
+ * @param {string} [options.verifierSecret] for an `hmac-sha256` signature
+ * @returns {Promise<{secret: *}>} on success. On refusal the API error carries
+ *   the creator's `message` and optional `returnUrl` to show the end user.
+ */
+async function retrieve (apiEndpoint, key, options = {}) {
+  const body = { key };
+  if (options.passphrase != null) {
+    body.signature = { type: 'secret', payload: options.passphrase };
+  } else if (options.verifierSecret != null) {
+    const parsed = parseKey(key);
+    if (parsed == null) throw new Error('Malformed shared-secret key.');
+    body.signature = {
+      type: 'hmac-sha256',
+      payload: await hmacSha256Hex(options.verifierSecret, parsed.randomPart)
+    };
+  }
+  const base = apiEndpoint.endsWith('/') ? apiEndpoint : apiEndpoint + '/';
+  const res = await fetch(base + 'shared-secrets/retrieve', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body)
+  });
+  const parsed = await res.json();
+  if (!res.ok) {
+    const err = new Error(parsed?.error?.message || 'Shared secret unavailable.');
+    err.id = parsed?.error?.id;
+    err.returnUrl = parsed?.error?.data?.returnUrl;
+    throw err;
+  }
+  return parsed;
+}
+
+/** Status of a shared secret, without consuming it. Creator or personal token. */
+async function status (connection, key) {
+  const res = await connection.post('shared-secrets/status', { key });
+  return res.sharedSecret;
+}
+
+module.exports = {
+  create,
+  retrieve,
+  status,
+  parseKey,
+  hmacSha256Hex,
+  sha256Hex
+};

package/src/SignedConnection.js

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+const Connection = require('./Connection');
+const { createDPoPProof } = require('./dpopProof');
+
+/**
+ * @class SignedConnection
+ * A {@link Connection} whose access token is sender-constrained via DPoP
+ * (RFC 9449): every request carries a fresh proof signed with a client-held
+ * key, and presents the token under the `DPoP` auth-scheme. A token stolen
+ * from this connection is useless to anyone who does not also hold the
+ * private key.
+ *
+ * Built by {@link OAuth2Client} with `dpop: true` (which binds the token to
+ * the key at issuance and hands the same key pair here). It can also be
+ * constructed directly from an `apiEndpoint` whose token was already bound
+ * to `keyPair` — mismatched keys make every request fail the server's
+ * proof-of-possession check.
+ *
+ * The key pair is ES256 (EC P-256), the only algorithm the server accepts;
+ * its public key must be exportable to JWK. Attachment downloads via a
+ * `readToken` need no proof (the server exempts that capability), so those
+ * keep working through a plain URL.
+ *
+ * @memberof pryv
+ */
+class SignedConnection extends Connection {
+  /**
+   * @param {string} apiEndpoint - Pryv API endpoint carrying the DPoP-bound token
+   * @param {CryptoKeyPair} keyPair - the ES256 key the token is bound to
+   * @param {Service} [service] - optional pre-built Service
+   */
+  constructor (apiEndpoint, keyPair, service) {
+    super(apiEndpoint, service);
+    if (keyPair == null || keyPair.privateKey == null || keyPair.publicKey == null) {
+      throw new Error('SignedConnection: an ES256 CryptoKeyPair ({ publicKey, privateKey }) is required');
+    }
+    this._dpopKeyPair = keyPair;
+  }
+
+  /**
+   * @protected
+   * @override
+   * Attach a per-request DPoP proof and present the token under the DPoP
+   * scheme. `url` is the request URL without query — the proof's `htu`.
+   * @param {string} method
+   * @param {string} url
+   * @returns {Promise<Object>}
+   */
+  async _authHeaders (method, url) {
+    const proof = await createDPoPProof({
+      keyPair: this._dpopKeyPair,
+      htm: method,
+      htu: url,
+      accessToken: this.token
+    });
+    return {
+      Authorization: 'DPoP ' + this.token,
+      DPoP: proof
+    };
+  }
+}
+
+module.exports = SignedConnection;

package/src/dpopProof.js

@@ -0,0 +1,96 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * DPoP (RFC 9449) proof builder — isomorphic (browser + Node ≥ 20), built
+ * only on WebCrypto (`globalThis.crypto.subtle`) so it survives the webpack
+ * browser bundle unchanged. ES256 only, matching the server
+ * (`open-pryv.io/components/oauth2/src/dpop.ts`).
+ *
+ * A proof is a compact JWS whose header carries the public JWK and whose
+ * payload binds the request: `htm` (method), `htu` (URL without query —
+ * the server compares in RFC 9449 §4.3 normalized form), `iat`, a fresh
+ * single-use `jti`, and — for resource-server requests — `ath`
+ * (`base64url(sha256(access_token))`).
+ */
+
+const subtle = globalThis.crypto.subtle;
+const textEncoder = new TextEncoder();
+
+/**
+ * @private
+ * base64url-encode raw bytes (no padding). `btoa` is available in browsers
+ * and Node ≥ 16.
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+function base64url (bytes) {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/=+$/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+/**
+ * @private
+ * @param {string} str
+ * @returns {Promise<string>} base64url(sha256(str))
+ */
+async function sha256base64url (str) {
+  const digest = await subtle.digest('SHA-256', textEncoder.encode(str));
+  return base64url(new Uint8Array(digest));
+}
+
+/**
+ * @private
+ * htu comparison form: scheme + host + path, query and fragment dropped
+ * (RFC 9449 §4.3 — the server normalizes the same way, so a signed URL that
+ * still carries a query would match too, but we strip for clarity).
+ * @param {string} url
+ * @returns {string}
+ */
+function stripQuery (url) {
+  const parsed = new URL(url);
+  return parsed.origin + parsed.pathname;
+}
+
+/**
+ * Build a DPoP proof for one request.
+ *
+ * @param {Object} params
+ * @param {CryptoKeyPair} params.keyPair - ES256 (EC P-256) key pair. The public
+ *   key MUST be exportable to JWK; the private key is used to sign.
+ * @param {string} params.htm - HTTP method (e.g. `'GET'`, `'POST'`).
+ * @param {string} params.htu - full request URL; query/fragment are stripped.
+ * @param {string} [params.accessToken] - when present, the proof carries
+ *   `ath = base64url(sha256(accessToken))`, binding it to that token
+ *   (required on resource-server requests; omitted on the token endpoint).
+ * @returns {Promise<string>} the compact JWS proof for the `DPoP` header
+ */
+async function createDPoPProof ({ keyPair, htm, htu, accessToken }) {
+  const jwk = await subtle.exportKey('jwk', keyPair.publicKey);
+  const header = {
+    typ: 'dpop+jwt',
+    alg: 'ES256',
+    jwk: { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y }
+  };
+  const payload = {
+    jti: globalThis.crypto.randomUUID(),
+    htm,
+    htu: stripQuery(htu),
+    iat: Math.floor(Date.now() / 1000)
+  };
+  if (accessToken != null) payload.ath = await sha256base64url(accessToken);
+
+  const signingInput = base64url(textEncoder.encode(JSON.stringify(header))) +
+    '.' + base64url(textEncoder.encode(JSON.stringify(payload)));
+  // ECDSA WebCrypto signatures are the raw 64-byte r||s concatenation — exactly
+  // the JWS ES256 form (the server rejects DER).
+  const signature = await subtle.sign(
+    { name: 'ECDSA', hash: 'SHA-256' }, keyPair.privateKey, textEncoder.encode(signingInput)
+  );
+  return signingInput + '.' + base64url(new Uint8Array(signature));
+}
+
+module.exports = { createDPoPProof };

package/src/index.d.ts

@@ -763,6 +763,17 @@ declare module 'pryv' {
     ): Promise<any[]>;
   }
 
+  /**
+   * A {@link Connection} whose access token is DPoP-sender-constrained
+   * (RFC 9449): every request carries a fresh proof signed with `keyPair`
+   * and presents the token under the `DPoP` scheme. Built by
+   * {@link OAuth2Client} with `dpop: true`, or directly from an apiEndpoint
+   * whose token was bound to `keyPair`.
+   */
+  export class SignedConnection extends Connection {
+    constructor (apiEndpoint: string, keyPair: CryptoKeyPair, service?: Service);
+  }
+
   export type serviceCustomizations = {
     name?: string;
     assets?: {
@@ -1059,6 +1070,53 @@ 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;
+    /** Seed a previously-persisted refresh token so `refresh()` works after a reload. */
+    refreshToken?: string;
+    /** Called with the NEW refresh token every time it rotates, to persist the minimal secret. */
+    onTokenRotated?: (refreshToken: string) => void;
+    /** Opt into RFC 9449 DPoP: token bound to a per-client ES256 key; `handleCallback()` / `refresh()` return a {@link SignedConnection}. */
+    dpop?: boolean;
+  };
+
+  /**
+   * 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 +1174,7 @@ declare module 'pryv' {
   let pryv: {
     Service: typeof Service;
     Connection: typeof Connection;
+    OAuth2Client: typeof OAuth2Client;
     Auth: {
       setupAuth: SetupAuth;
       AuthStates: AuthStates;

package/src/index.js

@@ -7,7 +7,9 @@
  * @exports pryv
  * @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.SignedConnection} SignedConnection - A Connection whose token is DPoP-sender-constrained (RFC 9449)
  * @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`.
@@ -19,8 +21,11 @@ const Service = require('./Service');
 module.exports = {
   Service,
   Connection: require('./Connection'),
+  SignedConnection: require('./SignedConnection'),
   Auth: require('./Auth'),
   Browser: require('./Browser'),
+  OAuth2Client: require('./OAuth2Client'),
+  SharedSecrets: require('./SharedSecrets'),
   utils: require('./utils'),
   PryvError: require('./lib/PryvError'),
   MfaRequiredError: require('./lib/MfaRequiredError'),

package/src/utils.js

@@ -232,7 +232,7 @@ const utils = module.exports = {
    */
   cleanURLFromPrYvParams: function (url) {
     // Legacy form: kept for back-compat with apps still emitting
-    // `prYv<anything>=...` (notably app-web-auth3's close_or_redirect).
+    // `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.

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');
+  });
+});