Move heartbeat declaration to event.

Author: msporny

README.md

@@ -87,19 +87,24 @@ const {keyPair: authKeyPair, didDocument: updatedDoc} = await addVm({
 
 ---
 
-### `createEvent({type, data, assertionMethod, previousEventHash})` -> `Promise<{event}>`
+### `createEvent({type, data, assertionMethod, previousEventHash, [heartbeat]})` -> `Promise<{event}>`
 
 Creates a signed event of the given type using the provided assertion method key.
 Use this for `'update'`, `'heartbeat'`, and `'deactivate'` events after the
 initial create. Always call `getPreviousEventHash()` first and pass the result
 as `previousEventHash` so the hash is covered by the operation proof.
 
+For `'heartbeat'` events, pass the rotated heartbeat hashes as `heartbeat`
+rather than embedding them in a DID document. The hashes are placed directly
+on the event object and covered by the proof.
+
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `type` | string | Event type: `'update'`, `'heartbeat'`, or `'deactivate'`. |
 | `data` | object\|undefined | The DID document for update events; `undefined` for heartbeat and deactivate. |
 | `assertionMethod` | KeyPair | The key pair to sign with (from `assertionMethod` in the DID document, or the heartbeat key pair). |
 | `previousEventHash` | string | Base58btc SHA3-256 hash of the previous event from `getPreviousEventHash()`. |
+| `heartbeat` | string[]\|undefined | For heartbeat events: array of new heartbeat hashes to rotate in. |
 
 ```js
 const previousEventHash =
@@ -110,6 +115,18 @@ const {event} = await createEvent({
   assertionMethod: keyPair,
   previousEventHash
 });
+
+// heartbeat event — rotated hashes on the event, no DID document copy
+const hbKeyPair = await deriveHeartbeatKeyPair(heartbeatSecret, 0);
+const nextKeyPair = await deriveHeartbeatKeyPair(heartbeatSecret, 1);
+const nextExported = await nextKeyPair.export({publicKey: true, includeContext: false});
+const nextHash = await hashDidKey(`did:key:${nextExported.publicKeyMultibase}`);
+const {event: hbEvent} = await createEvent({
+  type: 'heartbeat',
+  assertionMethod: hbKeyPair,
+  previousEventHash,
+  heartbeat: [nextHash]
+});
 ```
 
 ---

lib/cel.js

@@ -175,6 +175,10 @@ export async function addEvent({cel, event}) {
 export async function read({cel, trustedWitnesses = [], versionTime = null}) {
   const errors = [];
   let currentDidDocument = null;
+  // effective heartbeat array, updated independently of currentDidDocument:
+  // heartbeat events put rotated hashes on the event itself rather than in the
+  // DID document, so we must track this state separately
+  let currentHeartbeat = null;
   // latest witness timestamp for the previous log entry, used for heartbeat
   // frequency checks at each subsequent entry boundary
   let prevEntryWitnessTime = null;
@@ -274,12 +278,23 @@ export async function read({cel, trustedWitnesses = [], versionTime = null}) {
     // in effect during the gap leading into this entry, not any new frequency
     // introduced by this entry's update.
     const prevDidDocument = currentDidDocument;
+    // Snapshot effective heartbeat array before this entry updates it.
+    const prevHeartbeat = currentHeartbeat;
 
     // Track the current DID document for key lookup on stateless events
     if(event.operation?.data) {
       currentDidDocument = event.operation.data;
     }
 
+    // Update the effective heartbeat array. For heartbeat events the rotated
+    // hashes live on the event itself; for create/update they come from the
+    // DID document. This must stay in sync with the rotation check below.
+    if(event.heartbeat) {
+      currentHeartbeat = event.heartbeat;
+    } else if(currentDidDocument?.heartbeat) {
+      currentHeartbeat = currentDidDocument.heartbeat;
+    }
+
     // Mark the DID as deactivated after processing this entry so that any
     // subsequent entries are rejected at the top of the next iteration.
     if(event.operation?.type === 'deactivate') {
@@ -353,22 +368,23 @@ export async function read({cel, trustedWitnesses = [], versionTime = null}) {
     }
 
     // 5. If the operation was signed by a heartbeat key, verify that the new
-    // DID document no longer contains that heartbeat hash (it must be rotated
-    // out) and contains at least one new heartbeat hash.
-    if(opProof && currentDidDocument) {
+    // heartbeat array no longer contains the used hash (rotated out) and
+    // contains at least one new hash. The new array comes from event.heartbeat
+    // for heartbeat events, or from the DID document for update events.
+    if(opProof) {
       const vmRef = opProof.verificationMethod;
       if(vmRef?.startsWith('did:key:')) {
         const didKeyId = vmRef.split('#')[0];
         const usedHash = await hashDidKey(didKeyId);
-        const prevHeartbeat = prevDidDocument?.heartbeat ?? [];
-        const newHeartbeat = currentDidDocument?.heartbeat ?? [];
-        if(prevHeartbeat.includes(usedHash)) {
+        const oldHeartbeat = prevHeartbeat ?? prevDidDocument?.heartbeat ?? [];
+        const newHeartbeat = currentHeartbeat ?? [];
+        if(oldHeartbeat.includes(usedHash)) {
           if(newHeartbeat.includes(usedHash)) {
             errors.push(
               `entry ${i}: heartbeat key used without rotating its hash - ` +
               `${usedHash} must be removed from heartbeat[]`);
           }
-          if(newHeartbeat.length < prevHeartbeat.length) {
+          if(newHeartbeat.length < oldHeartbeat.length) {
             errors.push(
               `entry ${i}: heartbeat key rotation must add a new heartbeat ` +
               `hash to replace the consumed one`);

lib/didcel.js

@@ -229,7 +229,7 @@ export async function addVm({didDocument, verificationRelationship, curve}) {
  * });
  */
 export async function createEvent(
-  {type, data, assertionMethod, previousEventHash}) {
+  {type, data, assertionMethod, previousEventHash, heartbeat}) {
   const operation = {type};
   if(data !== undefined) {
     operation.data = data;
@@ -239,6 +239,11 @@ export async function createEvent(
   if(previousEventHash !== undefined) {
     event.previousEventHash = previousEventHash;
   }
+  // rotated heartbeat hashes sit on the event (not the DID document) so they
+  // are covered by the operation proof
+  if(heartbeat !== undefined) {
+    event.heartbeat = heartbeat;
+  }
   const signedEvent =
     await _signEvent({event, signer: assertionMethod.signer()});
 

lib/validate.js

@@ -148,6 +148,7 @@ const NON_CREATE_EVENT = {
     '@context': {},
     previousEventHash: MULTIBASE_STRING,
     operation: {oneOf: [UPDATE_OPERATION, STATELESS_OPERATION]},
+    heartbeat: {type: 'array', items: MULTIBASE_STRING},
     proof: DATA_INTEGRITY_PROOF
   },
   additionalProperties: false

tests/mocha/40-heartbeat.js

@@ -11,7 +11,7 @@ import {TEST_WITNESSES} from './helpers.js';
 const {expect} = chai;
 
 async function runHeartbeat() {
-  const {heartbeatSecret, didDocument, cryptographicEventLog} = await create();
+  const {heartbeatSecret, cryptographicEventLog} = await create();
 
   await witness({cel: cryptographicEventLog, witnesses: TEST_WITNESSES});
 
@@ -25,18 +25,13 @@ async function runHeartbeat() {
   const nextHeartbeatHash =
     await hashDidKey(`did:key:${nextExported.publicKeyMultibase}`);
 
-  // build updated DID document: remove key 0 hash, add key 1 hash
-  const updatedDoc = structuredClone(didDocument);
-  updatedDoc.heartbeat = [nextHeartbeatHash];
-  delete updatedDoc.proof;
-
   const previousEventHash =
     await getPreviousEventHash({cel: cryptographicEventLog});
   const {event: hbEvent} = await createEvent({
-    type: 'update',
-    data: updatedDoc,
+    type: 'heartbeat',
     assertionMethod: hbKeyPair,
-    previousEventHash
+    previousEventHash,
+    heartbeat: [nextHeartbeatHash]
   });
   await addEvent({cel: cryptographicEventLog, event: hbEvent});
 
@@ -59,8 +54,8 @@ describe('heartbeat', function() {
     const {cryptographicEventLog} = await runHeartbeat();
 
     const heartbeatEntry = cryptographicEventLog.log[1];
-    expect(heartbeatEntry.event.operation).to.have.property('type', 'update');
-    expect(heartbeatEntry.event.operation.data).to.be.an('object');
+    expect(heartbeatEntry.event.operation).to.have.property('type', 'heartbeat');
+    expect(heartbeatEntry.event.operation.data).to.be.undefined;
   });
 
   it('should hash-link heartbeat event to the witnessed create event',
@@ -90,16 +85,18 @@ describe('heartbeat', function() {
       expect(vm).to.be.a('string').that.matches(/^did:key:/);
     });
 
-  it('should rotate the heartbeat hash in the updated document',
+  it('should rotate the heartbeat hash onto the event, not the DID document',
     async () => {
       const {cryptographicEventLog} = await runHeartbeat();
 
-      const createDoc =
-        cryptographicEventLog.log[0].event.operation.data;
-      const updateDoc =
-        cryptographicEventLog.log[1].event.operation.data;
+      const createDoc = cryptographicEventLog.log[0].event.operation.data;
+      const heartbeatEvent = cryptographicEventLog.log[1].event;
 
-      // the hash in the updated document must differ from the original
-      expect(updateDoc.heartbeat[0]).to.not.equal(createDoc.heartbeat[0]);
+      // rotated hashes live on the event itself
+      expect(heartbeatEvent.heartbeat).to.be.an('array').with.length(1);
+      // the new hash must differ from the one in the original DID document
+      expect(heartbeatEvent.heartbeat[0]).to.not.equal(createDoc.heartbeat[0]);
+      // the heartbeat event has no operation.data (stateless)
+      expect(heartbeatEvent.operation.data).to.be.undefined;
     });
 });