pryv 3.8.1 → 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
@@ -717,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.1",
+  "version": "3.10.0",
   "description": "Pryv JavaScript library",
   "keywords": [
     "Pryv",

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

@@ -4,6 +4,7 @@
  */
 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`.
@@ -69,9 +70,16 @@ class OAuth2Client {
    *   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 } = 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');
@@ -88,6 +96,12 @@ class OAuth2Client {
     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.
@@ -106,6 +120,26 @@ class OAuth2Client {
     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).
@@ -182,8 +216,10 @@ class OAuth2Client {
     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
+        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);
@@ -221,7 +257,11 @@ class OAuth2Client {
       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 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);
   }
@@ -252,6 +292,9 @@ class OAuth2Client {
     // 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));
   }
 

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?: {
@@ -1079,6 +1090,12 @@ declare module 'pryv' {
     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;
   };
 
   /**

package/src/index.js

@@ -7,6 +7,7 @@
  * @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
@@ -20,9 +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/test/OAuth2Client.test.js

@@ -391,4 +391,49 @@ describe('[OAUTH-LIB] OAuth2Client', function () {
       expect(conn.token).to.equal('T2');
     });
   });
+
+  describe('[OAL-DPOP] DPoP option (RFC 9449)', function () {
+    function headerValue (init, name) {
+      const h = init && init.headers;
+      if (h == null) return null;
+      if (typeof h.get === 'function') return h.get(name);
+      const key = Object.keys(h).find((k) => k.toLowerCase() === name.toLowerCase());
+      return key ? h[key] : null;
+    }
+    const dpopTokenBody = (o = {}) => tokenBody(Object.assign({ token_type: 'DPoP' }, o));
+
+    it('[OAL-DP1] handleCallback with dpop:true returns a SignedConnection and sends a DPoP proof on the token request', async function () {
+      fetchMock.tokenResponse = jsonResponse(dpopTokenBody());
+      const client = newClient(memoryStorage(), { dpop: true });
+      await client.redirectToAuthorize({ state: 'S', redirect: () => {} });
+      const connection = await client.handleCallback('?code=CODE&state=S');
+      expect(connection.constructor.name).to.equal('SignedConnection');
+      expect(connection.token).to.equal('TOKEN123');
+      const proof = headerValue(fetchMock.lastTokenRequest.init, 'DPoP');
+      expect(proof, 'token request carries a DPoP header').to.be.a('string');
+      expect(proof.split('.')).to.have.length(3); // compact JWS
+    });
+
+    it('[OAL-DP2] default (no dpop) sends NO DPoP header and returns a plain Connection', async function () {
+      const client = newClient(memoryStorage());
+      await client.redirectToAuthorize({ state: 'S', redirect: () => {} });
+      const connection = await client.handleCallback('?code=CODE&state=S');
+      expect(connection.constructor.name).to.equal('Connection');
+      expect(headerValue(fetchMock.lastTokenRequest.init, 'DPoP')).to.equal(null);
+    });
+
+    it('[OAL-DP3] refresh() keeps the DPoP binding — SignedConnection with the same key, proof on the request', async function () {
+      fetchMock.tokenResponse = jsonResponse(dpopTokenBody());
+      const client = newClient(memoryStorage(), { dpop: true });
+      await client.redirectToAuthorize({ state: 'S', redirect: () => {} });
+      const first = await client.handleCallback('?code=CODE&state=S');
+      fetchMock.tokenResponse = jsonResponse(dpopTokenBody({ access_token: 'TOKEN789', apiEndpoint: 'https://TOKEN789@host/path/' }));
+      const refreshed = await client.refresh();
+      expect(refreshed.constructor.name).to.equal('SignedConnection');
+      expect(refreshed.token).to.equal('TOKEN789');
+      // Same key pair reused across the flow (binding is stable).
+      expect(refreshed._dpopKeyPair).to.equal(first._dpopKeyPair);
+      expect(headerValue(fetchMock.lastTokenRequest.init, 'DPoP')).to.be.a('string');
+    });
+  });
 });

package/test/SharedSecrets.test.js

@@ -0,0 +1,110 @@
+/**
+ * @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 helper — unit tests.
+ *
+ * Driven with a stub connection that records what would be sent, so the crypto
+ * and the request shape are checked without a server (same approach as the CMC
+ * helper tests).
+ */
+
+/* global describe, it */
+
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const SharedSecrets = require('../src/SharedSecrets');
+
+function stubConnection (reply) {
+  const calls = [];
+  return {
+    calls,
+    async post (path, body) {
+      calls.push({ path, body });
+      return reply(path, body);
+    }
+  };
+}
+
+describe('[SSEC] shared-secrets helper', function () {
+  it('[SS01] parses a key and rejects malformed ones without throwing', function () {
+    assert.deepEqual(SharedSecrets.parseKey('abc.def'), { id: 'abc', randomPart: 'def' });
+    for (const bad of ['', '.', 'nodot', 'a.', '.b', 'a.b.c', null, undefined, 42, {}]) {
+      assert.equal(SharedSecrets.parseKey(bad), null, 'must reject ' + JSON.stringify(bad));
+    }
+  });
+
+  it('[SS02] hashes and HMACs identically to the server side', async function () {
+    const hex = await SharedSecrets.sha256Hex('hello');
+    assert.equal(hex, crypto.createHash('sha256').update('hello').digest('hex'));
+
+    const mac = await SharedSecrets.hmacSha256Hex('V', 'message');
+    assert.equal(mac, crypto.createHmac('sha256', 'V').update('message').digest('hex'));
+  });
+
+  it('[SS03] plain create passes the params through and returns the server key', async function () {
+    const conn = stubConnection(() => ({
+      sharedSecret: { id: 'evt1', key: 'evt1.RANDOM', status: 'pending' }
+    }));
+    const out = await SharedSecrets.create(conn, {
+      ttl: 300, title: 't', onConsumed: { message: 'm' }, secret: { a: 1 }
+    });
+    assert.equal(conn.calls[0].path, 'shared-secrets');
+    assert.equal(conn.calls[0].body.ttl, 300);
+    assert.equal(conn.calls[0].body.keyHash, undefined, 'server mints the key in this mode');
+    assert.equal(out.key, 'evt1.RANDOM');
+  });
+
+  it('[SS04] hmac create sends only a hash and a proof, never the verifier secret', async function () {
+    const conn = stubConnection(() => ({ sharedSecret: { id: 'evt2', status: 'pending' } }));
+    const out = await SharedSecrets.create(conn, {
+      ttl: 300,
+      title: 't',
+      onConsumed: { message: 'm' },
+      secret: { a: 1 },
+      signature: { type: 'hmac-sha256', verifierSecret: 'V' }
+    });
+
+    const sent = conn.calls[0].body;
+    assert.match(sent.keyHash, /^[0-9a-f]{64}$/);
+    assert.equal(sent.signature.type, 'hmac-sha256');
+    const serialized = JSON.stringify(sent);
+    assert.ok(!serialized.includes('"V"'), 'the verifier secret must never be sent');
+
+    // The key is composed client-side, and its random half is what was hashed.
+    const parsed = SharedSecrets.parseKey(out.key);
+    assert.equal(parsed.id, 'evt2');
+    assert.equal(await SharedSecrets.sha256Hex(parsed.randomPart), sent.keyHash);
+    // …and the proof is the HMAC over that same random half.
+    assert.equal(sent.signature.value,
+      crypto.createHmac('sha256', 'V').update(parsed.randomPart).digest('hex'));
+  });
+
+  it('[SS05] the random half carries real entropy and never repeats', async function () {
+    const conn = stubConnection(() => ({ sharedSecret: { id: 'e', status: 'pending' } }));
+    const seen = new Set();
+    for (let i = 0; i < 50; i++) {
+      const out = await SharedSecrets.create(conn, {
+        ttl: 60, title: 't', onConsumed: { message: 'm' }, secret: 1,
+        signature: { type: 'hmac-sha256', verifierSecret: 'V' }
+      });
+      const { randomPart } = SharedSecrets.parseKey(out.key);
+      assert.ok(randomPart.length >= 32, 'too short: ' + randomPart);
+      assert.match(randomPart, /^[A-Za-z0-9_-]+$/);
+      seen.add(randomPart);
+    }
+    assert.equal(seen.size, 50);
+  });
+
+  it('[SS06] status posts the key in the body, never in the path', async function () {
+    const conn = stubConnection(() => ({ sharedSecret: { id: 'e', status: 'consumed' } }));
+    await SharedSecrets.status(conn, 'e.RANDOM');
+    assert.equal(conn.calls[0].path, 'shared-secrets/status',
+      'the key must not appear in the path — it would land in access logs');
+    assert.equal(conn.calls[0].body.key, 'e.RANDOM');
+  });
+});

package/test/SignedConnection.test.js

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, before, expect */
+
+const SignedConnection = require('../src/SignedConnection');
+const { createDPoPProof } = require('../src/dpopProof');
+
+const subtle = globalThis.crypto.subtle;
+const decoder = new TextDecoder();
+
+function b64urlToBytes (s) {
+  const b64 = s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4);
+  const bin = atob(b64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+}
+function decodeSegment (seg) { return JSON.parse(decoder.decode(b64urlToBytes(seg))); }
+async function sha256b64url (str) {
+  const d = await subtle.digest('SHA-256', new TextEncoder().encode(str));
+  return btoa(String.fromCharCode(...new Uint8Array(d))).replace(/=+$/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+describe('[OAUTH-SC] SignedConnection + DPoP proof', function () {
+  let keyPair;
+  before(async function () {
+    keyPair = await subtle.generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
+  });
+
+  describe('[SC-PROOF] createDPoPProof', function () {
+    it('[SC-P1] builds a compact JWS whose signature verifies against the embedded key', async function () {
+      const proof = await createDPoPProof({ keyPair, htm: 'GET', htu: 'https://host/path/events', accessToken: 'TOK' });
+      const [h, p, sig] = proof.split('.');
+      expect(proof.split('.')).to.have.length(3);
+
+      const header = decodeSegment(h);
+      expect(header.typ).to.equal('dpop+jwt');
+      expect(header.alg).to.equal('ES256');
+      expect(header.jwk).to.include.keys(['kty', 'crv', 'x', 'y']);
+      expect(header.jwk).to.not.have.property('d'); // never the private half
+
+      // The signature verifies against the public key embedded in the header.
+      const pub = await subtle.importKey('jwk', header.jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+      const ok = await subtle.verify(
+        { name: 'ECDSA', hash: 'SHA-256' }, pub, b64urlToBytes(sig), new TextEncoder().encode(h + '.' + p)
+      );
+      expect(ok).to.equal(true);
+    });
+
+    it('[SC-P2] binds htm, htu (query stripped), iat, a unique jti, and ath', async function () {
+      const proof = await createDPoPProof({ keyPair, htm: 'POST', htu: 'https://host/path/events?a=1#frag', accessToken: 'THE-TOKEN' });
+      const payload = decodeSegment(proof.split('.')[1]);
+      expect(payload.htm).to.equal('POST');
+      expect(payload.htu).to.equal('https://host/path/events'); // no query / fragment
+      expect(payload.iat).to.be.a('number');
+      expect(payload.jti).to.be.a('string').with.length.greaterThan(8);
+      expect(payload.ath).to.equal(await sha256b64url('THE-TOKEN'));
+
+      const again = await createDPoPProof({ keyPair, htm: 'POST', htu: 'https://host/path/events', accessToken: 'THE-TOKEN' });
+      expect(decodeSegment(again.split('.')[1]).jti).to.not.equal(payload.jti); // fresh each call
+    });
+
+    it('[SC-P3] omits ath when no access token is given (token-endpoint shape)', async function () {
+      const proof = await createDPoPProof({ keyPair, htm: 'POST', htu: 'https://host/oauth2/token' });
+      expect(decodeSegment(proof.split('.')[1])).to.not.have.property('ath');
+    });
+  });
+
+  describe('[SC-CONN] SignedConnection', function () {
+    it('[SC-C1] rejects construction without a key pair', function () {
+      expect(() => new SignedConnection('https://TOK@host/path/')).to.throw(/CryptoKeyPair/);
+      expect(() => new SignedConnection('https://TOK@host/path/', {})).to.throw(/CryptoKeyPair/);
+    });
+
+    it('[SC-C2] _authHeaders presents the token under the DPoP scheme + a matching proof', async function () {
+      const conn = new SignedConnection('https://TOK@host/path/', keyPair);
+      expect(conn.token).to.equal('TOK');
+      const headers = await conn._authHeaders('GET', conn.endpoint + 'events');
+      expect(headers.Authorization).to.equal('DPoP TOK');
+      expect(headers.DPoP).to.be.a('string');
+      const payload = decodeSegment(headers.DPoP.split('.')[1]);
+      expect(payload.htm).to.equal('GET');
+      expect(payload.htu).to.equal('https://host/path/events');
+      expect(payload.ath).to.equal(await sha256b64url('TOK')); // bound to THIS connection's token
+    });
+
+    it('[SC-C3] is a Connection (inherits the data API)', function () {
+      const conn = new SignedConnection('https://TOK@host/path/', keyPair);
+      const Connection = require('../src/Connection');
+      expect(conn).to.be.instanceOf(Connection);
+      expect(typeof conn.get).to.equal('function');
+      expect(typeof conn.post).to.equal('function');
+    });
+  });
+});