Add access update flow and bridge access helpers (Plan 27 Phase 5)

- AccessUpdateRequest types and CollectorClient.checkForUpdateRequests/acceptUpdate/refuseUpdate
- Collector.requestAccessUpdate and checkInbox extension for update-accept/update-refuse
- Contact.hasPendingUpdate/pendingUpdateClients getters
- AppClientAccount.getContacts scans for update requests in parallel
- bridgeAccess.ts: ensureBridgeAccess/recreateBridgeAccess/getOrCreateBridgeAccess helpers
- Tests for access update and bridge access

Author: perki

tests/accessUpdate.test.js

@@ -0,0 +1,188 @@
+import { assert } from './test-utils/deps-node.js';
+import { Contact } from '../ts/appTemplates/Contact.ts';
+import { CollectorClient } from '../ts/appTemplates/CollectorClient.ts';
+
+/**
+ * Unit tests for access update request functionality.
+ * Tests the data structures and Contact-level getters.
+ * Integration tests (actual API calls) are in apptemplates.test.js.
+ */
+
+// ---- Test helpers ---- //
+
+function makeSource (overrides = {}) {
+  return {
+    remoteUsername: 'dr-alice',
+    displayName: 'Dr. Alice',
+    chatStreams: null,
+    appStreamId: null,
+    permissions: [{ streamId: 'health', level: 'read' }],
+    status: 'Active',
+    type: 'collector',
+    accessId: 'acc-1',
+    ...overrides
+  };
+}
+
+function makeMockCollectorClient (overrides = {}) {
+  return {
+    status: 'Active',
+    pendingUpdate: null,
+    key: 'dr-alice:a-form1',
+    requesterUsername: 'dr-alice',
+    hasChatFeature: false,
+    ...overrides
+  };
+}
+
+describe('[AUPD] Access Update Requests', function () {
+  // ---- Contact.hasPendingUpdate ---- //
+
+  describe('[AUCT] Contact.hasPendingUpdate', function () {
+    it('[AU01] should return false when no collectorClients', () => {
+      const c = new Contact('dr-alice', 'Dr. Alice');
+      c.addSource(makeSource());
+      assert.equal(c.hasPendingUpdate, false);
+    });
+
+    it('[AU02] should return false when no pending updates', () => {
+      const c = new Contact('dr-alice', 'Dr. Alice');
+      c.addSource(makeSource());
+      c.addCollectorClient(makeMockCollectorClient());
+      assert.equal(c.hasPendingUpdate, false);
+    });
+
+    it('[AU03] should return true when a collectorClient has pendingUpdate', () => {
+      const c = new Contact('dr-alice', 'Dr. Alice');
+      c.addSource(makeSource());
+      c.addCollectorClient(makeMockCollectorClient({
+        pendingUpdate: {
+          eventId: 'evt-1',
+          content: {
+            version: 0,
+            targetAccessName: 'dr-alice:a-form1',
+            action: 'update-permissions',
+            permissions: [{ streamId: 'diary', level: 'read' }]
+          }
+        }
+      }));
+      assert.equal(c.hasPendingUpdate, true);
+    });
+  });
+
+  // ---- Contact.pendingUpdateClients ---- //
+
+  describe('[AUPC] Contact.pendingUpdateClients', function () {
+    it('[AU04] should return empty array when no pending updates', () => {
+      const c = new Contact('dr-alice', 'Dr. Alice');
+      c.addCollectorClient(makeMockCollectorClient());
+      c.addCollectorClient(makeMockCollectorClient({ key: 'dr-alice:a-form2' }));
+      assert.equal(c.pendingUpdateClients.length, 0);
+    });
+
+    it('[AU05] should return only clients with pending updates', () => {
+      const c = new Contact('dr-alice', 'Dr. Alice');
+      c.addCollectorClient(makeMockCollectorClient());
+      c.addCollectorClient(makeMockCollectorClient({
+        key: 'dr-alice:a-form2',
+        pendingUpdate: {
+          eventId: 'evt-2',
+          content: {
+            version: 0,
+            targetAccessName: 'dr-alice:a-form2',
+            action: 'update-permissions',
+            permissions: [{ streamId: 'diary', level: 'contribute' }]
+          }
+        }
+      }));
+      assert.equal(c.pendingUpdateClients.length, 1);
+      assert.equal(c.pendingUpdateClients[0].key, 'dr-alice:a-form2');
+    });
+  });
+
+  // ---- CollectorClient.pendingUpdate field ---- //
+
+  describe('[AUCC] CollectorClient.pendingUpdate', function () {
+    it('[AU06] should default to null', () => {
+      // pendingUpdate is a plain field, tested via mock
+      const cc = makeMockCollectorClient();
+      assert.equal(cc.pendingUpdate, null);
+    });
+
+    it('[AU07] should hold update request data when set', () => {
+      const updateReq = {
+        eventId: 'evt-1',
+        content: {
+          version: 0,
+          targetAccessName: 'dr-alice:a-form1',
+          action: 'update-permissions',
+          permissions: [
+            { streamId: 'health', level: 'read' },
+            { streamId: 'diary', level: 'contribute' }
+          ],
+          features: { chat: { type: 'user' } },
+          message: 'I\'d like to also access your diary entries.'
+        }
+      };
+      const cc = makeMockCollectorClient({ pendingUpdate: updateReq });
+      assert.equal(cc.pendingUpdate.eventId, 'evt-1');
+      assert.equal(cc.pendingUpdate.content.action, 'update-permissions');
+      assert.equal(cc.pendingUpdate.content.permissions.length, 2);
+      assert.equal(cc.pendingUpdate.content.message, 'I\'d like to also access your diary entries.');
+      assert.deepEqual(cc.pendingUpdate.content.features, { chat: { type: 'user' } });
+    });
+  });
+
+  // ---- AccessUpdateRequestContent structure ---- //
+
+  describe('[AURC] AccessUpdateRequestContent schema', function () {
+    it('[AU08] should validate minimal update request content', () => {
+      const content = {
+        version: 0,
+        targetAccessName: 'dr-alice:a-form1',
+        action: 'update-permissions',
+        permissions: [{ streamId: 'health', level: 'manage' }]
+      };
+      assert.equal(content.version, 0);
+      assert.equal(content.targetAccessName, 'dr-alice:a-form1');
+      assert.equal(content.action, 'update-permissions');
+      assert.equal(content.permissions.length, 1);
+      assert.equal(content.permissions[0].streamId, 'health');
+    });
+
+    it('[AU09] should support add-feature action', () => {
+      const content = {
+        version: 0,
+        targetAccessName: 'dr-alice:a-form1',
+        action: 'add-feature',
+        permissions: [{ streamId: 'health', level: 'read' }],
+        features: { chat: { type: 'user' } },
+        message: 'Adding chat capability'
+      };
+      assert.equal(content.action, 'add-feature');
+      assert.ok(content.features.chat);
+    });
+  });
+
+  // ---- Multiple contacts with mixed update states ---- //
+
+  describe('[AUMX] Mixed contacts with updates', function () {
+    it('[AU10] should correctly report updates across multiple contacts', () => {
+      const alice = new Contact('dr-alice', 'Dr. Alice');
+      alice.addSource(makeSource());
+      alice.addCollectorClient(makeMockCollectorClient({
+        pendingUpdate: {
+          eventId: 'evt-1',
+          content: { version: 0, targetAccessName: 'dr-alice:a-form1', action: 'update-permissions', permissions: [] }
+        }
+      }));
+
+      const bob = new Contact('dr-bob', 'Dr. Bob');
+      bob.addSource(makeSource({ remoteUsername: 'dr-bob', displayName: 'Dr. Bob' }));
+      bob.addCollectorClient(makeMockCollectorClient({ key: 'dr-bob:a-form1', pendingUpdate: null }));
+
+      assert.equal(alice.hasPendingUpdate, true);
+      assert.equal(bob.hasPendingUpdate, false);
+    });
+  });
+});

tests/bridgeAccess.test.js

@@ -0,0 +1,23 @@
+import { assert } from './test-utils/deps-node.js';
+
+// We can't easily unit-test the API-calling functions without a real connection,
+// but we can test the exported types compile and the permissionsMatch logic indirectly.
+// 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';
+
+describe('[BACC] Bridge Access helpers', function () {
+  it('[BA01] should export all three 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');
+  });
+});

tests/contact.test.js

@@ -284,6 +284,24 @@ describe('[CTCT] Contact class', function () {
       assert.equal(c.eventIsFromContact({ modifiedBy: 'a2' }), true);
       assert.equal(c.eventIsFromContact({ modifiedBy: 'other' }), false);
     });
+
+    it('[CTAQ2] should match events from previous (replaced) accesses via clientData chain', () => {
+      const c = new Contact('u', 'U');
+      // Current access (after update) carries previousAccessIds
+      c.addAccessObject({
+        id: 'a3-new',
+        clientData: {
+          hdsCollectorClient: {
+            version: 0,
+            previousAccessIds: ['a1-old', 'a2-older']
+          }
+        }
+      });
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'a3-new' }), true);
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'a1-old' }), true);
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'a2-older' }), true);
+      assert.equal(c.eventIsFromContact({ modifiedBy: 'unknown' }), false);
+    });
   });
 
   // ---- sourceFromAccess (static) ---- //

ts/appTemplates/AppClientAccount.ts

@@ -104,9 +104,25 @@ export class AppClientAccount extends Application {
    * Combines CollectorClients (person-to-person) and bridge/other accesses.
    * Multiple forms from the same doctor → one Contact with multiple sources.
    * Contacts are enriched with CollectorClient instances and access objects.
+   * Also checks for pending access update requests on active CollectorClients.
    */
   async getContacts (forceRefresh: boolean = false): Promise<Contact[]> {
     const collectorClients = await this.getCollectorClients(forceRefresh);
+
+    // Check for pending update requests in parallel (with timeout)
+    const activeClients = collectorClients.filter(cc => cc.status === 'Active');
+    if (activeClients.length > 0) {
+      const UPDATE_CHECK_TIMEOUT = 10000;
+      await Promise.allSettled(
+        activeClients.map(cc =>
+          Promise.race([
+            cc.checkForUpdateRequests(),
+            new Promise(resolve => setTimeout(resolve, UPDATE_CHECK_TIMEOUT))
+          ])
+        )
+      );
+    }
+
     const sources: ContactSource[] = [];
 
     // Collector clients → person contacts

ts/appTemplates/Collector.ts

@@ -3,6 +3,7 @@ import { HDSLibError } from '../errors.ts';
 import { waitUntilFalse } from '../utils.ts';
 import { CollectorInvite } from './CollectorInvite.ts';
 import * as logger from '../logger.ts';
+import type { Permission, AccessUpdateAction } from './interfaces.ts';
 
 const COLLECTOR_STREAMID_SUFFIXES = {
   archive: 'archive',
@@ -219,6 +220,16 @@ export class Collector {
           updateInvite.content.apiEndpoint = responseEvent.content.apiEndpoint;
           if (responseEvent.content.chat) updateInvite.content.chat = responseEvent.content.chat;
           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;
+          if (responseEvent.content.chat) updateInvite.content.chat = responseEvent.content.chat;
+          break;
+        case 'update-refuse':
+          // Patient refused the update — invite stays active with current permissions
+          // No stream change, just archive the response
+          break;
         case 'refuse':
           (updateInvite as any).streamIds = [this.streamIdFor(Collector.STREAMID_SUFFIXES.error)];
           updateInvite.content.errorType = 'refused';
@@ -327,6 +338,50 @@ export class Collector {
     return newSharingApiEndpoint;
   }
 
+  /**
+   * Request an access update for a specific invite.
+   * Creates a `request/access-update-v1` event in the public stream
+   * that the patient will discover via their requesterConnection.
+   *
+   * @param inviteKey - the invite key (CollectorInvite.key)
+   * @param permissions - new full permission set
+   * @param options.action - update action type (default: 'update-permissions')
+   * @param options.features - optional features to add (e.g. { chat: { type: 'user' } })
+   * @param options.message - human-readable explanation for the patient
+   */
+  async requestAccessUpdate (
+    inviteKey: string,
+    permissions: Permission[],
+    options: { action?: AccessUpdateAction, features?: Record<string, any>, message?: string } = {}
+  ): Promise<any> {
+    if (this.statusCode !== Collector.STATUSES.active) {
+      throw new HDSLibError('Collector must be active to request access update');
+    }
+    const invite = await this.getInviteByKey(inviteKey);
+    if (!invite) throw new HDSLibError(`Cannot find invite with key: ${inviteKey}`);
+    if (invite.status !== 'active') throw new HDSLibError(`Invite must be active to request update, current: ${invite.status}`);
+
+    // targetAccessName matches CollectorClient.key on the patient side
+    // which is built from accessInfo: username + ':' + accessName
+    const accessInfo = await invite.checkAndGetAccessInfo();
+    if (!accessInfo) throw new HDSLibError('Cannot get access info for invite — may have been revoked');
+    const targetAccessName = accessInfo.user.username + ':' + accessInfo.name;
+
+    const eventData = {
+      type: 'request/access-update-v1',
+      streamIds: [this.streamIdFor(Collector.STREAMID_SUFFIXES.public)],
+      content: {
+        version: 0,
+        targetAccessName,
+        action: options.action || 'update-permissions',
+        permissions,
+        features: options.features || undefined,
+        message: options.message || undefined
+      }
+    };
+    return await this.appManaging.connection.apiOne('events.create', eventData, 'event');
+  }
+
   /**
    * @private
    * @param {CollectorInvite} invite