Merge feat/lib-3.1.0: Plan 58 pryv@3.1.0 + accesses.update rollout

Author: perki

package-lock.json

@@ -62,11 +62,11 @@
     "webpack-cli": "^6.0.1"
   },
   "dependencies": {
-    "@pryv/monitor": "3.0.3",
-    "@pryv/socket.io": "3.0.3",
+    "@pryv/monitor": "3.1.0",
+    "@pryv/socket.io": "3.1.0",
     "ajv": "^8.20.0",
     "events": "^3.3.0",
-    "pryv": "3.0.4",
+    "pryv": "3.1.0",
     "short-unique-id": "^5.3.2"
   }
 }

package.json

@@ -382,8 +382,8 @@ describe('[APTX] appTemplates', function () {
       assert.equal(invite.errorType, 'revoked');
 
       // check if authorization is revoked
-
-      const res = await invite.connection.accessInfo();
+      // pryv@3.1.0 caches accessInfo per Connection — pass forceRefresh to bypass the cache after revoke
+      const res = await invite.connection.accessInfo(true);
       assert.equal(res.error.id, 'invalid-access-token');
     });
 

tests/apptemplates.test.js

@@ -5,19 +5,19 @@ import { assert } from './test-utils/deps-node.js';
 // The main integration test is in the bridge-mira tests.
 
 // Import to verify the module loads correctly
-import { getOrCreateBridgeAccess, recreateBridgeAccess, ensureBridgeAccess } from '../ts/appTemplates/bridgeAccess.ts';
+import { getOrCreateBridgeAccess, ensureBridgeAccess } from '../ts/appTemplates/bridgeAccess.ts';
 
 describe('[BACC] Bridge Access helpers', function () {
-  it('[BA01] should export all three helper functions', () => {
+  it('[BA01] should export both helper functions', () => {
     assert.equal(typeof getOrCreateBridgeAccess, 'function');
-    assert.equal(typeof recreateBridgeAccess, 'function');
     assert.equal(typeof ensureBridgeAccess, 'function');
   });
 
   it('[BA02] should be importable from appTemplates', async () => {
     const appTemplates = await import('../ts/appTemplates/appTemplates.ts');
     assert.equal(typeof appTemplates.getOrCreateBridgeAccess, 'function');
-    assert.equal(typeof appTemplates.recreateBridgeAccess, 'function');
     assert.equal(typeof appTemplates.ensureBridgeAccess, 'function');
+    // recreateBridgeAccess was dropped in Plan 58 Phase 4b — accesses.update replaces delete+create.
+    assert.equal(typeof appTemplates.recreateBridgeAccess, 'undefined');
   });
 });

tests/bridgeAccess.test.js

@@ -302,6 +302,21 @@ describe('[CTCT] Contact class', function () {
       assert.equal(c.eventIsFromContact({ modifiedBy: 'a2-older' }), true);
       assert.equal(c.eventIsFromContact({ modifiedBy: 'unknown' }), false);
     });
+
+    it('[CTAQ3] should match across Plan 66 composite ids (base-only equality)', () => {
+      const c = new Contact('u', 'U');
+      // Updated access serialises as composite `<base>:<serial>` on the wire
+      c.addAccessObject({ id: 'a1:2' });
+      // Event written when the access was at serial 0 (bare cuid)
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'a1' }), true);
+      // Event written when the access was at serial 1 (composite, lower serial)
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'a1:1' }), true);
+      // Event written at current serial
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'a1:2' }), true);
+      // Different base → no match
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'a2' }), false);
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'a2:2' }), false);
+    });
   });
 
   // ---- sourceFromAccess (static) ---- //

tests/contact.test.js

@@ -213,6 +213,14 @@ export class Collector {
       };
       updateInvite.content.sourceEventId = responseEvent.id;
 
+      // Plan 58 Phase 4d: legacy update-accept events (pre-Plan-58, delete+create era)
+      // carry an apiEndpoint field that must be adopted (token rotation happened).
+      // New update-accept events omit apiEndpoint (token preserved by accesses.update).
+      // When archiving a legacy event, opportunistically strip apiEndpoint from its
+      // content so the archive stays clean. events.update REPLACES content (not merges),
+      // so the strip is just "write current content minus the field".
+      let stripLegacyApiEndpointFromResponse = false;
+
       // check type of response
       switch (responseEvent.content.type) {
         case 'accept':
@@ -222,9 +230,13 @@ export class Collector {
           if (responseEvent.content.system) updateInvite.content.system = responseEvent.content.system;
           break;
         case 'update-accept':
-          // Patient accepted an access update — new apiEndpoint, stays active
           (updateInvite as any).streamIds = [this.streamIdFor(Collector.STREAMID_SUFFIXES.active)];
-          updateInvite.content.apiEndpoint = responseEvent.content.apiEndpoint;
+          // Legacy events: adopt the rotated apiEndpoint and flag the response for migration.
+          // New events: omit the field; the stored apiEndpoint stays valid in place.
+          if (responseEvent.content.apiEndpoint != null) {
+            updateInvite.content.apiEndpoint = responseEvent.content.apiEndpoint;
+            stripLegacyApiEndpointFromResponse = true;
+          }
           if (responseEvent.content.chat) updateInvite.content.chat = responseEvent.content.chat;
           if (responseEvent.content.system) updateInvite.content.system = responseEvent.content.system;
           break;
@@ -244,6 +256,15 @@ export class Collector {
           throw new HDSLibError(`Unkown or undefined ${responseEvent.content.type}`, responseEvent);
       }
 
+      // Archive update — also strip legacy apiEndpoint when applicable.
+      const responseArchiveUpdate: { streamIds: string[], content?: any } = {
+        streamIds: [this.streamIdFor(Collector.STREAMID_SUFFIXES.archive)]
+      };
+      if (stripLegacyApiEndpointFromResponse) {
+        const { apiEndpoint: _stripped, ...cleanedContent } = responseEvent.content;
+        responseArchiveUpdate.content = cleanedContent;
+      }
+
       // update inviteEvent and archive inbox message
       const apiCalls = [
         {
@@ -257,9 +278,7 @@ export class Collector {
           method: 'events.update',
           params: {
             id: responseEvent.id,
-            update: {
-              streamIds: [this.streamIdFor(Collector.STREAMID_SUFFIXES.archive)]
-            }
+            update: responseArchiveUpdate
           }
         }
       ];

ts/appTemplates/Collector.ts

@@ -511,12 +511,26 @@ export class CollectorClient {
   }
 
   /**
-   * Accept a pending update request: delete old access, create new one with updated permissions,
-   * notify requester via inbox with new apiEndpoint.
+   * Accept a pending update request: update the access in place via accesses.update
+   * (Plan 66), notify requester via inbox.
+   *
+   * The access id, token and apiEndpoint are preserved across the update; only
+   * the wire id becomes composite (`<base>:<serial>`). The requester does not
+   * need to re-store an apiEndpoint.
+   *
+   * `clientData` is intentionally NOT sent: the server merges (verified empirically
+   * on Plan 66 demo) so existing keys including legacy `hdsCollectorClient.previousAccessIds`
+   * chains stay intact. The current `hdsCollectorClient.eventData` snapshot remains
+   * valid because `this.eventData` is unchanged at update time.
+   *
+   * `StaleAccessIdError` handling: if another writer updated the access between
+   * the load of `pendingUpdate` and now, refetch the access by name and retry
+   * once. Two consecutive stale errors propagate.
    */
   async acceptUpdate (): Promise<{ accessData: any, requesterEvent: any } | null> {
     if (!this.pendingUpdate) throw new HDSLibError('No pending update to accept');
     if (this.status !== CollectorClient.STATUSES.active) throw new HDSLibError('Can only accept updates on active CollectorClients');
+    if (!this.accessData?.id) throw new HDSLibError('No access to update', this.accessData);
 
     const update = this.pendingUpdate.content;
 
@@ -527,7 +541,7 @@ export class CollectorClient {
     });
 
     // Handle chat feature if requested
-    const responseContent: { apiEndpoint?: string, chat?: any } = {};
+    const responseContent: { chat?: any } = {};
     if (update.features?.chat && !this.hasChatFeature) {
       const chatStreamMain = `chat-${this.requesterUsername}`;
       const chatStreamIncoming = `chat-${this.requesterUsername}-in`;
@@ -559,44 +573,30 @@ export class CollectorClient {
       );
     }
 
-    // Collect previous access IDs for event attribution (modifiedBy tracking)
-    const previousAccessIds: string[] = [];
-    if (this.accessData) {
-      if (this.accessData.id) previousAccessIds.push(this.accessData.id);
-      // Chain: carry forward any IDs from the old access's clientData
-      const oldPrevIds = this.accessData.clientData?.hdsCollectorClient?.previousAccessIds;
-      if (Array.isArray(oldPrevIds)) {
-        for (const id of oldPrevIds) {
-          if (!previousAccessIds.includes(id)) previousAccessIds.push(id);
+    // Update access in place. 1-retry on StaleAccessIdError.
+    let attempt = 0;
+    while (true) {
+      try {
+        const updated = await (this.app.connection as any).updateAccess(this.accessData.id, {
+          permissions: cleanedPermissions
+        });
+        this.accessData = updated;
+        break;
+      } catch (e: any) {
+        if (e instanceof (pryv as any).StaleAccessIdError && attempt === 0) {
+          attempt++;
+          // Refetch the access by name (composite serial may have advanced)
+          const accesses = await this.app.connection.apiOne('accesses.get', {}, 'accesses');
+          const fresh = accesses.find((a: any) => a.name === this.key);
+          if (!fresh) throw new HDSLibError('Access disappeared during update', accesses);
+          this.accessData = fresh;
+          continue;
         }
+        throw e;
       }
     }
 
-    // Delete old access
-    if (this.accessData && !this.accessData.deleted) {
-      await this.app.connection.apiOne('accesses.delete', { id: this.accessData.id }, 'accessDeletion');
-    }
-
-    // Create new access with updated permissions
-    const accessCreateData = {
-      name: this.key,
-      type: 'shared',
-      permissions: cleanedPermissions,
-      clientData: {
-        hdsCollectorClient: {
-          version: 0,
-          eventData: this.eventData,
-          previousAccessIds
-        }
-      }
-    };
-    const accessData = await this.app.connection.apiOne('accesses.create', accessCreateData, 'access');
-    this.accessData = accessData;
-    if (!this.accessData?.apiEndpoint) throw new HDSLibError('Failed creating updated access', accessData);
-
-    responseContent.apiEndpoint = this.accessData.apiEndpoint;
-
-    // Notify requester via inbox
+    // Notify requester via inbox. No `apiEndpoint` field — token is preserved.
     const requesterEvent = await this.#updateRequester('update-accept', responseContent);
     if (requesterEvent != null) {
       this.pendingUpdate = null;

ts/appTemplates/CollectorClient.ts

@@ -160,12 +160,16 @@ export class CollectorInvite {
   /**
    * Check if connection is valid. (only if active)
    * If result is "forbidden" update and set as revoked
-   * @returns accessInfo if valid.
+   *
+   * Caching is delegated to `pryv.Connection.accessInfo()` (per-Connection cache
+   * introduced in pryv@3.1.0). Pass `forceRefresh=true` to bust the cache —
+   * required after operations that invalidate the access (revoke, delete).
+   *
+   * The `#accessInfo` field mirrors the result for the sync `patientUsername` getter.
    */
   async checkAndGetAccessInfo (forceRefresh: boolean = false): Promise<any> {
-    if (!forceRefresh && this.#accessInfo) return this.#accessInfo;
     try {
-      this.#accessInfo = await this.connection.accessInfo();
+      this.#accessInfo = await this.connection.accessInfo(forceRefresh);
       return this.#accessInfo;
     } catch (e: any) {
       this.#accessInfo = null;

ts/appTemplates/CollectorInvite.ts

@@ -6,6 +6,27 @@ import { HDSModelAppStreams } from '../HDSModel/HDSModel-AppStreams.ts';
 import { getStreamIdAndChildrenIds } from '../toolkit/StreamsTools.ts';
 import { pryv } from '../patchedPryv.ts';
 
+/**
+ * Plan 66 composite-id base extractor. Refs serialise as either bare cuid
+ * (`"abc123"`) for never-updated accesses or composite (`"abc123:3"`) for
+ * updated heads / historical writes. Equality must be on the *base* — an
+ * event's `modifiedBy` may carry a serial different from the current
+ * access head, but it still attributes to the same access chain.
+ *
+ * Returns the input unchanged when `parseAccessRef` is unavailable
+ * (older pryv lib), letting callers keep working under pre-Plan-66 servers.
+ */
+function refBase (ref: string | null | undefined): string | null {
+  if (ref == null) return null;
+  const parse = (pryv as any).utils?.parseAccessRef;
+  if (typeof parse !== 'function') return ref;
+  try {
+    return parse(ref).base;
+  } catch {
+    return null;
+  }
+}
+
 /** Doctor-side: a form invite pair (which collector + which invite) */
 export interface ContactInvite {
   collector: Collector;
@@ -141,14 +162,28 @@ export class Contact {
 
   /** Check if an event was created/modified by this contact (including replaced accesses) */
   eventIsFromContact (event: pryv.Event): boolean {
+    const eventBase = refBase(event.modifiedBy);
+    if (eventBase == null) return false;
     for (const access of this.accessObjects) {
-      if (access.id && event.modifiedBy === access.id) return true;
-      // Check previous access IDs from replaced accesses (collector pattern)
+      // Plan 66: access.id may be composite (`<base>:<serial>`) on updated accesses.
+      // An event's modifiedBy carries the serial active at write time, possibly
+      // different from the current head. Compare on base only.
+      if (refBase(access.id) === eventBase) return true;
+      // Check previous access IDs from replaced accesses (collector pattern, legacy delete+create).
+      // The historical chain stays in clientData even after Plan 58 switches to in-place update.
       const collectorPrevIds = access.clientData?.hdsCollectorClient?.previousAccessIds;
-      if (Array.isArray(collectorPrevIds) && collectorPrevIds.includes(event.modifiedBy)) return true;
-      // Check previous access IDs from bridge access recreate pattern
+      if (Array.isArray(collectorPrevIds)) {
+        for (const prev of collectorPrevIds) {
+          if (refBase(prev) === eventBase) return true;
+        }
+      }
+      // Check previous access IDs from bridge access recreate pattern (legacy)
       const bridgePrevIds = access.clientData?.previousAccessIds;
-      if (Array.isArray(bridgePrevIds) && bridgePrevIds.includes(event.modifiedBy)) return true;
+      if (Array.isArray(bridgePrevIds)) {
+        for (const prev of bridgePrevIds) {
+          if (refBase(prev) === eventBase) return true;
+        }
+      }
     }
     return false;
   }

ts/appTemplates/Contact.ts

@@ -8,7 +8,7 @@ import { CollectorRequest } from './CollectorRequest.ts';
 import { Contact } from './Contact.ts';
 export type { ContactInvite } from './Contact.ts';
 export type { AccessUpdateRequest, AccessUpdateRequestContent, AccessUpdateAction } from './interfaces.ts';
-export { getOrCreateBridgeAccess, recreateBridgeAccess, ensureBridgeAccess } from './bridgeAccess.ts';
+export { getOrCreateBridgeAccess, ensureBridgeAccess } from './bridgeAccess.ts';
 export type { BridgeAccessOptions, BridgeAccessResult } from './bridgeAccess.ts';
 export {
   getSectionItemLabels,