pryv 3.0.4 → 3.2.0

package/package.json

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

package/src/Connection.js

@@ -6,6 +6,7 @@ const utils = require('./utils.js');
 const jsonParser = require('./lib/json-parser');
 const libGetEventStreamed = require('./lib/getEventStreamed');
 const PryvError = require('./lib/PryvError');
+const StaleAccessIdError = require('./lib/StaleAccessIdError');
 const buildSearchParams = require('./lib/buildSearchParams');
 
 /**
@@ -71,11 +72,22 @@ class Connection {
 
   /**
    * Get access info for this connection.
-   * It's async as it is fetched from the API.
+   *
+   * Memoized per-Connection: the first call fetches from the server and
+   * caches the result; subsequent calls return the cached copy in O(1).
+   * Pass `forceRefresh: true` to invalidate the cache and fetch a fresh
+   * copy from the server — used internally by `connection.socket` to
+   * react to Plan 66 `accessUpdated` server-push events. A failed
+   * server fetch leaves any prior cached value intact.
+   *
+   * @param {boolean} [forceRefresh=false] - bypass + refresh the cache
    * @returns {Promise<AccessInfo>} Promise resolving to the access info
    */
-  async accessInfo () {
-    return this.get('access-info', null);
+  async accessInfo (forceRefresh = false) {
+    if (!forceRefresh && this._accessInfoCache != null) return this._accessInfoCache;
+    const fresh = await this.get('access-info', null);
+    this._accessInfoCache = fresh;
+    return fresh;
   }
 
   /**
@@ -416,6 +428,48 @@ class Connection {
     return utils.buildAPIEndpoint(this);
   }
 
+  /**
+   * Plan 66 (open-pryv.io ≥ 2.0.0-pre.X): update an access by composite id.
+   * Wraps `accesses.update` and translates the 409 `stale-resource` response
+   * into a typed `StaleAccessIdError` so callers can `instanceof`-test and
+   * refetch + retry without re-parsing the inner error.
+   *
+   * Pass `id` as the wire-format reference returned by the server — bare
+   * cuid on a never-updated access, composite `<base>:<serial>` otherwise.
+   * `changes` is the body of mutable fields (name, deviceName, permissions,
+   * expireAfter, expires:null, clientData).
+   *
+   * @param {string} id
+   * @param {Object} changes
+   * @returns {Promise<Object>} the updated access (with new composite id)
+   * @throws {StaleAccessIdError} if the server reports the id is stale
+   */
+  async updateAccess (id, changes) {
+    try {
+      return await this.apiOne('accesses.update', { id, update: changes }, 'access');
+    } catch (e) {
+      if (e && e.innerObject && e.innerObject.id === 'stale-resource') {
+        throw new StaleAccessIdError(e.message, e.innerObject.data || {});
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Plan 66: fetch an access by composite id including its full version
+   * history (oldest first). Server: `accesses.getOne ?includeHistory=true`.
+   *
+   * Useful for audit views. Pass the composite `<base>:<serial>` to
+   * inspect a specific past version (the result's `current` field then
+   * points at the live head's composite id).
+   *
+   * @param {string} id
+   * @returns {Promise<{ access: Object, current?: string, history?: Object[] }>}
+   */
+  async getAccessWithHistory (id) {
+    return await this.apiOne('accesses.getOne', { id, includeHistory: true });
+  }
+
   // private method that handle meta data parsing
   _handleMeta (res, requestLocalTimestamp) {
     if (!res.meta) throw new Error('Cannot find .meta in response.');

package/src/cmc.js

@@ -0,0 +1,348 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+/**
+ * CMC (Cross-account Messaging & Consent) client-side helpers.
+ *
+ * Mirrors the server plugin's slug + stream-id helpers so app code can
+ * build stream-ids deterministically without depending on the server's
+ * private modules. See server-side `components/cmc/src/{slug,constants}.ts`.
+ *
+ * Stream-id model:
+ *   :_cmc:                                  reserved root
+ *   :_cmc:inbox                             one-shot lifecycle (cross-app)
+ *   :_cmc:apps:<app-code>:[<path>:]chats:<counterparty-slug>
+ *   :_cmc:apps:<app-code>:[<path>:]collectors:<counterparty-slug>
+ *
+ * `counterparty-slug` = `<username>--<host-slug>` where host-slug is the
+ * host with `.` replaced by `-`.
+ *
+ * @memberof pryv
+ * @namespace pryv.cmc
+ */
+
+// --- Constants ---
+// All :_cmc:* identifiers compose from NS. If the namespace is ever
+// rebranded (e.g. to ':_xchg:' or similar), changing NS alone updates
+// every constant + every helper that builds a stream-id.
+const NS = ':_cmc:';
+const NS_INBOX = NS + 'inbox';
+const NS_APPS = NS + 'apps';
+const NS_INTERNAL = NS + '_internal';
+const NS_INTERNAL_RETRIES = NS_INTERNAL + ':retries';
+
+const ET_REQUEST = 'consent/request-cmc';
+const ET_ACCEPT = 'consent/accept-cmc';
+const ET_REFUSE = 'consent/refuse-cmc';
+const ET_REVOKE = 'consent/revoke-cmc';
+const ET_CHAT = 'message/chat-cmc';
+const ET_SYSTEM_ALERT = 'notification/alert-cmc';
+const ET_SYSTEM_ACK = 'notification/ack-cmc';
+const ET_SYSTEM_SCOPE_REQUEST = 'consent/scope-request-cmc';
+const ET_SYSTEM_SCOPE_UPDATE = 'consent/scope-update-cmc';
+
+const EVENT_TYPES_LIFECYCLE = [ET_REQUEST, ET_ACCEPT, ET_REFUSE, ET_REVOKE];
+const EVENT_TYPES_CHAT = [ET_CHAT];
+const EVENT_TYPES_SYSTEM = [
+  ET_SYSTEM_ALERT,
+  ET_SYSTEM_ACK,
+  ET_SYSTEM_SCOPE_REQUEST,
+  ET_SYSTEM_SCOPE_UPDATE
+];
+
+// --- Slug helpers ---
+
+const SEPARATOR = '--';
+const SLUG_PIECE_RE = /^[a-z0-9-]+$/;
+
+function assertNonEmpty (label, value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error('cmc-slug: ' + label + ' must be a non-empty string');
+  }
+  return value;
+}
+
+function assertSlugPiece (label, value) {
+  if (!SLUG_PIECE_RE.test(value)) {
+    throw new Error(
+      'cmc-slug: ' + label + ' "' + value + '" must match ' + SLUG_PIECE_RE.toString()
+    );
+  }
+  if (value.includes(SEPARATOR)) {
+    throw new Error(
+      'cmc-slug: ' + label + ' "' + value + '" must not contain the double-hyphen separator'
+    );
+  }
+}
+
+/**
+ * Slugify a host: lowercase and replace `.` with `-`.
+ */
+function slugifyHost (host) {
+  assertNonEmpty('host', host);
+  // Strip trailing port (`:3000`) — port doesn't affect cross-account
+  // identity. Two users on the same hostname are the same platform
+  // regardless of which port their api endpoint listens on. Mirrors
+  // the server-side helper in open-pryv.io components/cmc/src/slug.ts.
+  const hostNoPort = host.replace(/:\d+$/, '');
+  return hostNoPort.toLowerCase().replace(/\./g, '-');
+}
+
+/**
+ * Build a counterparty slug `<username>--<host-slug>`.
+ *
+ * @param {Object} params
+ * @param {string} params.username
+ * @param {string} params.host - full hostname (e.g. 'pryv.me')
+ * @returns {string}
+ */
+function counterpartySlug (params) {
+  const username = assertNonEmpty('username', params.username).toLowerCase();
+  assertSlugPiece('username', username);
+  const hostSlug = slugifyHost(params.host);
+  assertSlugPiece('host-slug', hostSlug);
+  return username + SEPARATOR + hostSlug;
+}
+
+/**
+ * Parse a counterparty slug back to its pieces. Note: the host-slug is
+ * lossy — `pryv-me` could come from `pryv.me` or `pryv-me`. Store the
+ * canonical host alongside the slug if you need it.
+ *
+ * @param {string} slug
+ * @returns {{ username: string, hostSlug: string }}
+ */
+function parseCounterpartySlug (slug) {
+  assertNonEmpty('slug', slug);
+  const pieces = slug.split(SEPARATOR);
+  if (pieces.length !== 2) {
+    throw new Error(
+      'cmc-slug: counterparty slug "' + slug + '" must have exactly 2 ' +
+      'double-hyphen-separated pieces, got ' + pieces.length
+    );
+  }
+  for (const piece of pieces) {
+    assertSlugPiece('slug piece', piece);
+  }
+  return { username: pieces[0], hostSlug: pieces[1] };
+}
+
+// --- Stream-id builders ---
+
+/** `<scopeStreamId>:chats` */
+function chatsParentUnder (scopeStreamId) {
+  return scopeStreamId + ':chats';
+}
+
+/** `<scopeStreamId>:chats:<counterparty-slug>` */
+function chatStreamUnder (scopeStreamId, slug) {
+  return scopeStreamId + ':chats:' + slug;
+}
+
+/** `<scopeStreamId>:collectors` */
+function collectorsParentUnder (scopeStreamId) {
+  return scopeStreamId + ':collectors';
+}
+
+/** `<scopeStreamId>:collectors:<counterparty-slug>` */
+function collectorStreamUnder (scopeStreamId, slug) {
+  return scopeStreamId + ':collectors:' + slug;
+}
+
+/**
+ * Build the app-scope root `:_cmc:apps:<app-code>`.
+ */
+function appScope (appCode) {
+  assertNonEmpty('appCode', appCode);
+  return NS_APPS + ':' + appCode;
+}
+
+// --- Classification predicates ---
+
+/** Does this stream-id live under the :_cmc: namespace? */
+function isCmcStreamId (streamId) {
+  return streamId === ':_cmc' || streamId.startsWith(NS);
+}
+
+const APP_NESTED_PLUGIN_RE = /:_cmc:apps:[^:]+(?::[^:]+)*:(chats|collectors)(?::|$)/;
+
+/** True if this id is at or beneath chats/collectors under :_cmc:apps:*. */
+function isAppNestedPluginStream (streamId) {
+  return APP_NESTED_PLUGIN_RE.test(streamId);
+}
+
+/**
+ * Extract the app-code segment from `:_cmc:apps:<app-code>[:...]`.
+ * Returns null for ids that aren't under `:_cmc:apps:`.
+ */
+function getAppCode (streamId) {
+  if (!streamId.startsWith(NS_APPS + ':')) return null;
+  const rest = streamId.substring(NS_APPS.length + 1);
+  const colonIdx = rest.indexOf(':');
+  return colonIdx === -1 ? rest : rest.substring(0, colonIdx);
+}
+
+const CHAT_STREAM_ID_RE = /^(:_cmc:apps:[^:]+(?::[^:]+)*):chats:([a-z0-9-]+--[a-z0-9-]+)$/;
+const COLLECTOR_STREAM_ID_RE = /^(:_cmc:apps:[^:]+(?::[^:]+)*):collectors:([a-z0-9-]+--[a-z0-9-]+)$/;
+
+/**
+ * Parse a chat trigger stream-id into its components.
+ * Returns null on shape mismatch.
+ */
+function parseChatStreamId (streamId) {
+  if (typeof streamId !== 'string') return null;
+  const m = streamId.match(CHAT_STREAM_ID_RE);
+  if (m == null) return null;
+  let counterparty;
+  try {
+    counterparty = parseCounterpartySlug(m[2]);
+  } catch (_e) {
+    return null;
+  }
+  return {
+    appCode: getAppCode(m[1]),
+    scopeStreamId: m[1],
+    counterpartySlug: m[2],
+    counterparty
+  };
+}
+
+/**
+ * Parse a collectors trigger stream-id into its components.
+ * Returns null on shape mismatch.
+ */
+function parseCollectorStreamId (streamId) {
+  if (typeof streamId !== 'string') return null;
+  const m = streamId.match(COLLECTOR_STREAM_ID_RE);
+  if (m == null) return null;
+  let counterparty;
+  try {
+    counterparty = parseCounterpartySlug(m[2]);
+  } catch (_e) {
+    return null;
+  }
+  return {
+    appCode: getAppCode(m[1]),
+    scopeStreamId: m[1],
+    counterpartySlug: m[2],
+    counterparty
+  };
+}
+
+// --- Actor helpers (apiEndpoint → { token, username, host }) ---
+
+/**
+ * Extract `{ token, username, host }` from a Pryv apiEndpoint, given
+ * the platform's `service.info.api` URL template.
+ *
+ * Pryv apiEndpoints follow one of two URL shapes (the difference is
+ * platform-defined, encoded in `service.info.api`):
+ *
+ *   subdomain  template `https://{username}.<domain>/`
+ *              endpoint `https://<token>@<username>.<domain>/`
+ *   path-style template `https://<host>/{username}/`
+ *              endpoint `https://<token>@<host>/<username>/`
+ *
+ * This helper inverts whichever template the platform serves, returning
+ * the **canonical host** (no `<username>.` subdomain prefix in subdomain
+ * mode) — that's the host CMC uses for cross-account identity (slugs,
+ * counterparty matching).
+ *
+ * @param {string} apiEndpoint  e.g. 'https://t0k3n@alice.pryv.me/'
+ * @param {string} serviceInfoApi  e.g. 'https://{username}.pryv.me/'
+ *                                 from /service/info → field `api`.
+ * @returns {{ token: string|null, username: string|null, host: string }}
+ *
+ * @example
+ *   const conn = new pryv.Connection(apiEndpoint);
+ *   const info = await conn.service.info();
+ *   const me = pryv.cmc.extractActor(apiEndpoint, info.api);
+ *   // → { token: 't0k3n', username: 'alice', host: 'pryv.me' }
+ */
+function extractActor (apiEndpoint, serviceInfoApi) {
+  // Avoid circular require: utils is the consumer, cmc the provider.
+  // We pull at call-time so cmc.js stays loadable without requiring
+  // utils early.
+  const utils = require('./utils');
+  const { token, endpoint } = utils.extractTokenAndAPIEndpoint(apiEndpoint);
+  // Match the api template's variable position to find the username.
+  // Both endpoint + template are guaranteed to have a trailing slash.
+  const tplIdx = serviceInfoApi.indexOf('{username}');
+  if (tplIdx < 0) {
+    // Template doesn't carry {username} — operator-defined, can't decompose.
+    let host = '';
+    try { host = new URL(endpoint).host; } catch (_e) {}
+    return { token, username: null, host };
+  }
+  const tplPrefix = serviceInfoApi.slice(0, tplIdx);
+  const tplSuffix = serviceInfoApi.slice(tplIdx + '{username}'.length);
+  if (!endpoint.startsWith(tplPrefix) || !endpoint.endsWith(tplSuffix)) {
+    let host = '';
+    try { host = new URL(endpoint).host; } catch (_e) {}
+    return { token, username: null, host };
+  }
+  const username = endpoint.slice(tplPrefix.length, endpoint.length - tplSuffix.length);
+  // For subdomain templates, host is `<username>.<domain>` — but the
+  // canonical CMC host is the bare `<domain>` (the platform identity,
+  // not per-user). For path-style, host is just the literal host.
+  // Disambiguate by where {username} sits in the template:
+  //   - subdomain  → prefix ends with `://` (username right after scheme)
+  //   - path-style → prefix has more after `://` (host already in prefix)
+  const isSubdomainTemplate = /:\/\/$/.test(tplPrefix);
+  let host;
+  if (isSubdomainTemplate) {
+    // tplSuffix starts with the domain (e.g. '.pryv.me/')
+    host = tplSuffix.replace(/^\.+/, '').replace(/\/+$/, '');
+  } else {
+    // path-style — host is in the prefix's URL
+    try {
+      host = new URL(tplPrefix).host;
+    } catch (_e) {
+      host = '';
+    }
+  }
+  return { token, username, host };
+}
+
+module.exports = {
+  // namespace constants
+  NS,
+  NS_INBOX,
+  NS_APPS,
+  NS_INTERNAL,
+  NS_INTERNAL_RETRIES,
+  // actor helper
+  extractActor,
+  // event types
+  ET_REQUEST,
+  ET_ACCEPT,
+  ET_REFUSE,
+  ET_REVOKE,
+  ET_CHAT,
+  ET_SYSTEM_ALERT,
+  ET_SYSTEM_ACK,
+  ET_SYSTEM_SCOPE_REQUEST,
+  ET_SYSTEM_SCOPE_UPDATE,
+  EVENT_TYPES_LIFECYCLE,
+  EVENT_TYPES_CHAT,
+  EVENT_TYPES_SYSTEM,
+  // slug helpers
+  SEPARATOR,
+  slugifyHost,
+  counterpartySlug,
+  parseCounterpartySlug,
+  // stream-id builders
+  appScope,
+  chatsParentUnder,
+  chatStreamUnder,
+  collectorsParentUnder,
+  collectorStreamUnder,
+  // classification + parsing
+  isCmcStreamId,
+  isAppNestedPluginStream,
+  getAppCode,
+  parseChatStreamId,
+  parseCollectorStreamId
+};

package/src/index.d.ts

@@ -723,7 +723,12 @@ declare module 'pryv' {
       fields: string[],
       points: Array<Array<number | string>>,
     ): Promise<HFSeriesAddResult>;
-    accessInfo(): Promise<AccessInfo>;
+    /** Memoized; pass `forceRefresh: true` to bypass + refresh the cache. */
+    accessInfo(forceRefresh?: boolean): Promise<AccessInfo>;
+    /** Plan 66: update an access by composite id. */
+    updateAccess(id: string, changes: object): Promise<object>;
+    /** Plan 66: fetch an access including its full version history. */
+    getAccessWithHistory(id: string): Promise<{ access: object, current?: string, history?: object[] }>;
     revoke(throwOnFail?: boolean, usingConnection?: Connection): Promise<any>;
     readonly deltaTime: number;
     readonly apiEndpoint: string;

package/src/index.js

@@ -10,7 +10,10 @@
  * @property {pryv.Browser} Browser - Browser Tools - Access request helpers and visuals (button)
  * @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`.
+ * @property {pryv.StaleAccessIdError} StaleAccessIdError - Plan 66: thrown when a Pryv.io server rejects an `accesses.update` / `accesses.delete` with a 409 stale-resource. Refetch + retry.
  * @property {Object} ERRORS - Catalogue of Pryv API error ids (mirrors open-pryv.io/components/errors)
+ * @property {pryv.cmc} cmc - Cross-account Messaging & Consent helpers (slug + stream-id builders + parsers)
  */
 module.exports = {
   Service: require('./Service'),
@@ -20,6 +23,8 @@ module.exports = {
   utils: require('./utils'),
   PryvError: require('./lib/PryvError'),
   MfaRequiredError: require('./lib/MfaRequiredError'),
+  StaleAccessIdError: require('./lib/StaleAccessIdError'),
   ERRORS: require('./lib/errorIds'),
+  cmc: require('./cmc'),
   version: require('../package.json').version
 };

package/src/lib/StaleAccessIdError.js

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+
+const PryvError = require('./PryvError');
+
+/**
+ * Plan 66: typed error surfaced when a Pryv.io server (≥ 2.0.0-pre.X)
+ * rejects an `accesses.update` or `accesses.delete` call with a
+ * 409 `stale-resource` response.
+ *
+ * The composite access id `<base>:<serial>` carries the version the
+ * caller last observed. If the access has since been updated, the
+ * server rejects the call so the caller refetches the current head
+ * (`connection.api('accesses.getOne', { id: base })`) and retries
+ * with the fresh composite id.
+ *
+ * Reach for `.data.provided` to see what the caller sent and
+ * `.data.currentSerial` to see what the server currently has.
+ *
+ * @extends PryvError
+ */
+class StaleAccessIdError extends PryvError {
+  /**
+   * @param {string} message
+   * @param {{ provided?: string, currentSerial?: number | null }} data
+   */
+  constructor (message, data) {
+    super(message);
+    this.name = 'StaleAccessIdError';
+    /** @type {{ provided?: string, currentSerial?: number | null }} */
+    this.data = data || {};
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, StaleAccessIdError);
+    }
+  }
+}
+
+module.exports = StaleAccessIdError;

package/src/utils.js

@@ -155,6 +155,56 @@ const utils = module.exports = {
     return url.replace(PRYV_REGEXP, '');
   },
 
+  /**
+   * Plan 66 (open-pryv.io ≥ 2.0.0-pre.X): parse a wire-format access
+   * reference into `{ base, serial }`. Accepts both bare cuid
+   * (`"abc123"` → `{ base: 'abc123', serial: null }`) and composite
+   * (`"abc123:3"` → `{ base: 'abc123', serial: 3 }`). Throws on
+   * malformed input. Apply this to `access.id`, `access.createdBy`,
+   * `access.modifiedBy`, and `streamIds` entries of the form
+   * `access-<base>:<serial>` from audit events.
+   * @memberof pryv.utils
+   * @param {string} ref - Access reference string
+   * @returns {{ base: string, serial: number | null }}
+   */
+  parseAccessRef: function (ref) {
+    if (typeof ref !== 'string' || ref.length === 0) {
+      throw new Error('parseAccessRef: expected a non-empty string, got ' + JSON.stringify(ref));
+    }
+    const colonIdx = ref.indexOf(':');
+    if (colonIdx === -1) return { base: ref, serial: null };
+    const base = ref.slice(0, colonIdx);
+    const tail = ref.slice(colonIdx + 1);
+    if (base.length === 0) {
+      throw new Error('parseAccessRef: empty base in ' + JSON.stringify(ref));
+    }
+    const serial = Number(tail);
+    if (!Number.isInteger(serial) || serial < 1) {
+      throw new Error('parseAccessRef: serial must be a positive integer, got ' + JSON.stringify(tail));
+    }
+    return { base, serial };
+  },
+
+  /**
+   * Plan 66: render an `{ base, serial }` pair back to the wire
+   * format. Bare cuid when serial is null/undefined; `<base>:<serial>`
+   * otherwise. Mostly used to construct the composite id when calling
+   * `connection.api()` for `accesses.update` / `accesses.delete`.
+   * @memberof pryv.utils
+   * @param {{ base: string, serial?: number | null }} ref
+   * @returns {string}
+   */
+  serializeAccessRef: function (ref) {
+    if (ref == null || typeof ref.base !== 'string' || ref.base.length === 0) {
+      throw new Error('serializeAccessRef: ref.base must be a non-empty string');
+    }
+    if (ref.serial == null) return ref.base;
+    if (!Number.isInteger(ref.serial) || ref.serial < 1) {
+      throw new Error('serializeAccessRef: serial must be a positive integer, got ' + JSON.stringify(ref.serial));
+    }
+    return ref.base + ':' + ref.serial;
+  },
+
   /**
    * Extract query parameters from a URL
    * @memberof pryv.utils

package/test/Connection.test.js

@@ -499,5 +499,31 @@ describe('[CONX] Connection', () => {
       expect(accessInfoUser.token).to.exist;
       expect(newUser.access.token).to.equal(accessInfoUser.token);
     });
+
+    // Plan 66 — accessInfo caching + forceRefresh.
+
+    it('[CAIC] accessInfo() memoizes — second call returns the same object reference', async () => {
+      const regexAPIandToken = /(.+):\/\/(.+)/gm;
+      const res = regexAPIandToken.exec(testData.apiEndpoint);
+      const apiEndpointWithToken = res[1] + '://' + newUser.access.token + '@' + res[2];
+      const cachingConn = new pryv.Connection(apiEndpointWithToken);
+      const first = await cachingConn.accessInfo();
+      const second = await cachingConn.accessInfo();
+      expect(second).to.equal(first); // same reference — served from cache
+    });
+
+    it('[CAID] accessInfo(true) forces a refresh and replaces the cached object', async () => {
+      const regexAPIandToken = /(.+):\/\/(.+)/gm;
+      const res = regexAPIandToken.exec(testData.apiEndpoint);
+      const apiEndpointWithToken = res[1] + '://' + newUser.access.token + '@' + res[2];
+      const cachingConn = new pryv.Connection(apiEndpointWithToken);
+      const first = await cachingConn.accessInfo();
+      const refreshed = await cachingConn.accessInfo(true);
+      expect(refreshed).to.not.equal(first); // distinct object — re-fetched
+      expect(refreshed.token).to.equal(first.token); // same content
+      // Next non-forced call returns the refreshed copy from cache.
+      const cached = await cachingConn.accessInfo();
+      expect(cached).to.equal(refreshed);
+    });
   });
 });

package/test/cmc.test.js

@@ -0,0 +1,172 @@
+/**
+ * @license
+ * [BSD-3-Clause](https://github.com/pryv/lib-js/blob/master/LICENSE)
+ */
+/* global describe, it, expect */
+
+const cmc = require('../src/cmc');
+
+describe('[CMCX] pryv.cmc client helpers', function () {
+  describe('[CMCXC] constants', function () {
+    it('[CMCXCA] exposes namespace + event-type constants', function () {
+      expect(cmc.NS).to.equal(':_cmc:');
+      expect(cmc.NS_INBOX).to.equal(':_cmc:inbox');
+      expect(cmc.NS_APPS).to.equal(':_cmc:apps');
+      expect(cmc.NS_INTERNAL).to.equal(':_cmc:_internal');
+      expect(cmc.NS_INTERNAL_RETRIES).to.equal(':_cmc:_internal:retries');
+      expect(cmc.ET_REQUEST).to.equal('consent/request-cmc');
+      expect(cmc.ET_ACCEPT).to.equal('consent/accept-cmc');
+      expect(cmc.ET_CHAT).to.equal('message/chat-cmc');
+      expect(cmc.ET_SYSTEM_ALERT).to.equal('notification/alert-cmc');
+      expect(cmc.EVENT_TYPES_LIFECYCLE).to.include('consent/request-cmc');
+      expect(cmc.EVENT_TYPES_SYSTEM).to.include('consent/scope-update-cmc');
+    });
+  });
+
+  describe('[CMCXS] slug helpers', function () {
+    it('[CMCXSA] slugifyHost lowercases + replaces dots with hyphens', function () {
+      expect(cmc.slugifyHost('PRYV.me')).to.equal('pryv-me');
+      expect(cmc.slugifyHost('a.b.c.example.org')).to.equal('a-b-c-example-org');
+    });
+
+    it('[CMCXSB] counterpartySlug joins username + host-slug with --', function () {
+      expect(cmc.counterpartySlug({ username: 'alice', host: 'pryv.me' }))
+        .to.equal('alice--pryv-me');
+      expect(cmc.counterpartySlug({ username: 'provider-a', host: 'example.com' }))
+        .to.equal('provider-a--example-com');
+    });
+
+    it('[CMCXSC] counterpartySlug rejects invalid pieces', function () {
+      expect(() => cmc.counterpartySlug({ username: 'has space', host: 'a.b' })).to.throw();
+      expect(() => cmc.counterpartySlug({ username: '', host: 'a.b' })).to.throw();
+      expect(() => cmc.counterpartySlug({ username: 'a--b', host: 'a.b' })).to.throw();
+    });
+
+    it('[CMCXSD] parseCounterpartySlug round-trips the slug', function () {
+      const s = cmc.counterpartySlug({ username: 'alice', host: 'pryv.me' });
+      const parsed = cmc.parseCounterpartySlug(s);
+      expect(parsed).to.deep.equal({ username: 'alice', hostSlug: 'pryv-me' });
+    });
+
+    it('[CMCXSE] parseCounterpartySlug rejects malformed input', function () {
+      expect(() => cmc.parseCounterpartySlug('no-separator')).to.throw();
+      expect(() => cmc.parseCounterpartySlug('a--b--c')).to.throw();
+      expect(() => cmc.parseCounterpartySlug('')).to.throw();
+    });
+  });
+
+  describe('[CMCXB] stream-id builders', function () {
+    it('[CMCXBA] appScope produces :_cmc:apps:<app-code>', function () {
+      expect(cmc.appScope('my-app')).to.equal(':_cmc:apps:my-app');
+    });
+
+    it('[CMCXBB] chats helpers build the nested path', function () {
+      const scope = cmc.appScope('my-app');
+      expect(cmc.chatsParentUnder(scope)).to.equal(':_cmc:apps:my-app:chats');
+      const slug = cmc.counterpartySlug({ username: 'alice', host: 'pryv.me' });
+      expect(cmc.chatStreamUnder(scope, slug)).to.equal(':_cmc:apps:my-app:chats:alice--pryv-me');
+    });
+
+    it('[CMCXBC] collectors helpers build the nested path', function () {
+      const scope = ':_cmc:apps:my-app:campaign-2026';
+      expect(cmc.collectorsParentUnder(scope)).to.equal(':_cmc:apps:my-app:campaign-2026:collectors');
+      expect(cmc.collectorStreamUnder(scope, 'alice--pryv-me'))
+        .to.equal(':_cmc:apps:my-app:campaign-2026:collectors:alice--pryv-me');
+    });
+  });
+
+  describe('[CMCXP] predicates + parsers', function () {
+    it('[CMCXPA] isCmcStreamId true for :_cmc:* + false for non-cmc', function () {
+      expect(cmc.isCmcStreamId(':_cmc:apps:foo')).to.equal(true);
+      expect(cmc.isCmcStreamId(':_cmc:inbox')).to.equal(true);
+      expect(cmc.isCmcStreamId('fertility')).to.equal(false);
+      expect(cmc.isCmcStreamId(':_system:account:email')).to.equal(false);
+    });
+
+    it('[CMCXPB] isAppNestedPluginStream true for chats/collectors leaves', function () {
+      expect(cmc.isAppNestedPluginStream(':_cmc:apps:my-app:chats:alice--pryv-me')).to.equal(true);
+      expect(cmc.isAppNestedPluginStream(':_cmc:apps:my-app:collectors:alice--pryv-me')).to.equal(true);
+      expect(cmc.isAppNestedPluginStream(':_cmc:apps:my-app:study-A:chats')).to.equal(true);
+      expect(cmc.isAppNestedPluginStream(':_cmc:apps:my-app:study-A')).to.equal(false);
+      expect(cmc.isAppNestedPluginStream(':_cmc:apps:my-app:chats-style-data')).to.equal(false);
+    });
+
+    it('[CMCXPC] getAppCode pulls the app segment', function () {
+      expect(cmc.getAppCode(':_cmc:apps:my-app')).to.equal('my-app');
+      expect(cmc.getAppCode(':_cmc:apps:my-app:campaign-2026')).to.equal('my-app');
+      expect(cmc.getAppCode(':_cmc:inbox')).to.equal(null);
+      expect(cmc.getAppCode('fertility')).to.equal(null);
+    });
+
+    it('[CMCXPD] parseChatStreamId extracts scope + counterparty', function () {
+      const r = cmc.parseChatStreamId(':_cmc:apps:my-app:campaign-2026:chats:alice--pryv-me');
+      expect(r.appCode).to.equal('my-app');
+      expect(r.scopeStreamId).to.equal(':_cmc:apps:my-app:campaign-2026');
+      expect(r.counterpartySlug).to.equal('alice--pryv-me');
+      expect(r.counterparty).to.deep.equal({ username: 'alice', hostSlug: 'pryv-me' });
+    });
+
+    it('[CMCXPE] parseChatStreamId returns null for non-chat ids', function () {
+      expect(cmc.parseChatStreamId(':_cmc:inbox')).to.equal(null);
+      expect(cmc.parseChatStreamId(':_cmc:apps:my-app:collectors:foo--bar')).to.equal(null);
+      expect(cmc.parseChatStreamId('arbitrary-stream')).to.equal(null);
+    });
+
+    it('[CMCXPF] parseCollectorStreamId extracts scope + counterparty', function () {
+      const r = cmc.parseCollectorStreamId(':_cmc:apps:my-app:collectors:alice--pryv-me');
+      expect(r.appCode).to.equal('my-app');
+      expect(r.scopeStreamId).to.equal(':_cmc:apps:my-app');
+      expect(r.counterpartySlug).to.equal('alice--pryv-me');
+    });
+
+    it('[CMCXPG] parseCollectorStreamId returns null for non-collector ids', function () {
+      expect(cmc.parseCollectorStreamId(':_cmc:apps:my-app:chats:foo--bar')).to.equal(null);
+      expect(cmc.parseCollectorStreamId(':_cmc:apps:my-app:collectors:no-separator')).to.equal(null);
+    });
+  });
+
+  describe('[CMCXI] integration with pryv module', function () {
+    it('[CMCXIA] exposed as pryv.cmc', function () {
+      const pryv = require('../src');
+      expect(pryv.cmc).to.exist;
+      expect(pryv.cmc.counterpartySlug).to.be.a('function');
+      expect(pryv.cmc.NS).to.equal(':_cmc:');
+    });
+  });
+
+  describe('[CMCXA] extractActor', function () {
+    it('[CMCXAA] subdomain template — host strips the {username}. prefix', function () {
+      const r = cmc.extractActor(
+        'https://t0k3n@alice.pryv.me/',
+        'https://{username}.pryv.me/'
+      );
+      expect(r).to.deep.equal({ token: 't0k3n', username: 'alice', host: 'pryv.me' });
+    });
+
+    it('[CMCXAB] path-style template — host is the literal hostname[:port]', function () {
+      const r = cmc.extractActor(
+        'http://t0k3n@127.0.0.1:3000/alice/',
+        'http://127.0.0.1:3000/{username}/'
+      );
+      expect(r).to.deep.equal({ token: 't0k3n', username: 'alice', host: '127.0.0.1:3000' });
+    });
+
+    it('[CMCXAC] returns username:null when the endpoint doesn\'t match the template', function () {
+      const r = cmc.extractActor(
+        'https://t0k3n@somewhere.else.com/',
+        'https://{username}.pryv.me/'
+      );
+      expect(r.username).to.equal(null);
+    });
+
+    it('[CMCXAD] returns token:null when endpoint carries no token', function () {
+      const r = cmc.extractActor(
+        'https://alice.pryv.me/',
+        'https://{username}.pryv.me/'
+      );
+      expect(r.token).to.equal(null);
+      expect(r.username).to.equal('alice');
+      expect(r.host).to.equal('pryv.me');
+    });
+  });
+});

package/test/utils.test.js

@@ -59,4 +59,48 @@ describe('[UTLX] utils', function () {
     expect(apiEndpoint).to.equal(testData.apiEndpoint);
     done();
   });
+
+  // Plan 66 — composite access references.
+
+  it('[UTLF] parseAccessRef on a bare cuid returns { base, serial: null }', function () {
+    const ref = pryv.utils.parseAccessRef('abc123def456');
+    expect(ref).to.eql({ base: 'abc123def456', serial: null });
+  });
+
+  it('[UTLG] parseAccessRef on a composite returns { base, serial }', function () {
+    const ref = pryv.utils.parseAccessRef('abc123:7');
+    expect(ref).to.eql({ base: 'abc123', serial: 7 });
+  });
+
+  it('[UTLH] parseAccessRef on garbage throws', function () {
+    expect(() => pryv.utils.parseAccessRef('')).to.throw();
+    expect(() => pryv.utils.parseAccessRef(':1')).to.throw();
+    expect(() => pryv.utils.parseAccessRef('abc:notanumber')).to.throw();
+    expect(() => pryv.utils.parseAccessRef('abc:0')).to.throw();
+    expect(() => pryv.utils.parseAccessRef('abc:-1')).to.throw();
+    expect(() => pryv.utils.parseAccessRef(null)).to.throw();
+  });
+
+  it('[UTLI] serializeAccessRef round-trips parseAccessRef', function () {
+    const samples = ['plainCuid', 'plainCuid:1', 'plainCuid:42'];
+    for (const s of samples) {
+      expect(pryv.utils.serializeAccessRef(pryv.utils.parseAccessRef(s))).to.equal(s);
+    }
+  });
+
+  it('[UTLJ] serializeAccessRef rejects bad inputs', function () {
+    expect(() => pryv.utils.serializeAccessRef(null)).to.throw();
+    expect(() => pryv.utils.serializeAccessRef({ base: '' })).to.throw();
+    expect(() => pryv.utils.serializeAccessRef({ base: 'abc', serial: 0 })).to.throw();
+    expect(() => pryv.utils.serializeAccessRef({ base: 'abc', serial: 1.5 })).to.throw();
+  });
+
+  it('[UTLK] StaleAccessIdError extends PryvError', function () {
+    const err = new pryv.StaleAccessIdError('stale!', { provided: 'abc:1', currentSerial: 2 });
+    expect(err).to.be.instanceOf(pryv.StaleAccessIdError);
+    expect(err).to.be.instanceOf(pryv.PryvError);
+    expect(err.data.provided).to.equal('abc:1');
+    expect(err.data.currentSerial).to.equal(2);
+    expect(err.name).to.equal('StaleAccessIdError');
+  });
 });