Move heartbeat and heartbeatFrequency to event level properties.

Author: msporny

README.md

@@ -30,8 +30,7 @@ All public functions are exported from the package entry point:
 ```js
 import {
   // DID document operations
-  create, addVm, createEvent, deriveHeartbeatKeyPair,
-  hashDidKey, setHeartbeatFrequency,
+  create, addVm, createEvent, deriveHeartbeatKeyPair, hashDidKey,
   // CEL operations
   createCel, addEvent, getPreviousEventHash, witness,
   read, loadFromFile, saveToFile,
@@ -55,7 +54,7 @@ initial signed create event already wrapped in a Cryptographic Event Log.
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `options.curve` | string | Elliptic curve for key generation. Default: `'P-256'`. |
-| `options.heartbeatFrequency` | string | ISO 8601 duration for the required heartbeat interval. Default: `'P10Y'`. |
+| `options.heartbeatFrequency` | string | ISO 8601 duration for the required heartbeat interval. Default: `'P1M'`. |
 
 ```js
 const {keyPair, heartbeatSecret, didDocument, cryptographicEventLog} =
@@ -87,24 +86,25 @@ const {keyPair: authKeyPair, didDocument: updatedDoc} = await addVm({
 
 ---
 
-### `createEvent({type, data, assertionMethod, previousEventHash, [heartbeat]})` -> `Promise<{event}>`
+### `createEvent({type, data, assertionMethod, previousEventHash, [heartbeat], [heartbeatFrequency]})` -> `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.
+`heartbeat` hashes and `heartbeatFrequency` are event-level fields — they belong
+directly on the event object, not inside the DID document. Both are covered by
+the operation 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. |
+| `heartbeat` | string[]\|undefined | Array of new heartbeat hashes to rotate in (required for heartbeat events). |
+| `heartbeatFrequency` | string\|undefined | ISO 8601 duration to change the required heartbeat interval (e.g. `'P1M'`, `'P1D'`). |
 
 ```js
 const previousEventHash =
@@ -177,26 +177,6 @@ await witness({
 
 ---
 
-### `setHeartbeatFrequency({didDocument, heartbeatFrequency})` -> `{didDocument}`
-
-Updates the `heartbeatFrequency` field on a DID document and removes the proof.
-The document must be re-signed with `createEvent` before appending an update
-event.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `didDocument` | object | The current DID document. |
-| `heartbeatFrequency` | string | ISO 8601 duration (e.g. `'P3M'`, `'P1Y'`). |
-
-```js
-const {didDocument: updatedDoc} = setHeartbeatFrequency({
-  didDocument,
-  heartbeatFrequency: 'P3M'
-});
-```
-
----
-
 ### `deriveHeartbeatKeyPair(masterSecret, index)` -> `Promise<KeyPair>`
 
 Derives an ECDSA P-256 Multikey key pair from a heartbeat master secret and an
@@ -404,18 +384,20 @@ The library implements the `did:cel` DID method, which consists of:
 - **Blind witness attestations:** Witness services receive only a SHA3-256 hash
   of each event and return `DataIntegrityProof` attestations, providing temporal
   anchoring and distributed trust without learning DID document contents.
-- **Heartbeat keys:** Each DID document stores SHA3-256 hashes of heartbeat
-  `did:key:` URIs. A heartbeat operation signs an update with the heartbeat key
-  (derived via `deriveHeartbeatKeyPair(masterSecret, index)`) and must rotate
-  out the used hash, replacing it with the hash of the next derived key. Only
-  the 16-byte master secret is stored; individual keys are derived on demand.
+- **Heartbeat keys:** The initial create event carries a `heartbeat` array
+  (SHA3-256 hashes of heartbeat `did:key:` URIs) and a `heartbeatFrequency`
+  ISO 8601 duration — both as event-level fields, not inside the DID document.
+  A heartbeat operation signs an event with the heartbeat key (derived via
+  `deriveHeartbeatKeyPair(masterSecret, index)`), rotates out the used hash,
+  and adds the hash of the next derived key on the event itself. Only the
+  16-byte master secret is stored; individual keys are derived on demand.
 - **Encrypted secret storage:** Private keys encrypted with AES-256-GCM using a
   scrypt-derived key and stored in YAML format.
 
 ## File Structure
 
 - `lib/index.js` - Package entry point; explicit named exports for all public functions
-- `lib/didcel.js` - DID document operations: `create`, `addVm`, `createEvent`, `setHeartbeatFrequency`, `hashDidKey`
+- `lib/didcel.js` - DID document operations: `create`, `addVm`, `createEvent`, `deriveHeartbeatKeyPair`, `hashDidKey`
 - `lib/cel.js` - Cryptographic Event Log: `createCel`, `addEvent`, `getPreviousEventHash`, `witness`, `read`, `loadFromFile`, `saveToFile`
 - `lib/secrets.js` - Encrypted key storage: `saveSecrets`, `loadSecrets`
 - `lib/witness.js` - HTTP client for witness services

lib/cel.js

@@ -179,6 +179,8 @@ export async function read({cel, trustedWitnesses = [], versionTime = null}) {
   // 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;
+  // effective heartbeatFrequency, updated from event-level field
+  let currentHeartbeatFrequency = null;
   // latest witness timestamp for the previous log entry, used for heartbeat
   // frequency checks at each subsequent entry boundary
   let prevEntryWitnessTime = null;
@@ -273,26 +275,26 @@ export async function read({cel, trustedWitnesses = [], versionTime = null}) {
       }
     }
 
-    // Snapshot the document state from the previous entry before advancing.
-    // The heartbeatFrequency check (step 5) must use the frequency that was
-    // in effect during the gap leading into this entry, not any new frequency
-    // introduced by this entry's update.
+    // Snapshot state from the previous entry before advancing.
+    // The heartbeatFrequency check must use the frequency in effect during the
+    // gap leading into this entry, not any new frequency this entry introduces.
     const prevDidDocument = currentDidDocument;
-    // Snapshot effective heartbeat array before this entry updates it.
     const prevHeartbeat = currentHeartbeat;
+    const prevHeartbeatFrequency = currentHeartbeatFrequency;
 
     // 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.
+    // Update the effective heartbeat array. Hashes live on the event itself.
     if(event.heartbeat) {
       currentHeartbeat = event.heartbeat;
-    } else if(currentDidDocument?.heartbeat) {
-      currentHeartbeat = currentDidDocument.heartbeat;
+    }
+
+    // Update heartbeatFrequency from the event-level field.
+    if(event.heartbeatFrequency !== undefined) {
+      currentHeartbeatFrequency = event.heartbeatFrequency;
     }
 
     // Mark the DID as deactivated after processing this entry so that any
@@ -320,7 +322,7 @@ export async function read({cel, trustedWitnesses = [], versionTime = null}) {
       try {
         const verified = await _verifyOperationProof(
           {event, opProof, currentDidDocument: verifyDidDocument,
-            prevDidDocument: prevDidDocument ?? verifyDidDocument});
+            prevHeartbeat: prevHeartbeat ?? []});
         if(!verified) {
           errors.push(`entry ${i}: operation proof invalid`);
         }
@@ -403,8 +405,7 @@ export async function read({cel, trustedWitnesses = [], versionTime = null}) {
     // Use the frequency from the previous document state so a tightened
     // heartbeatFrequency introduced by this entry is not applied retroactively
     // to the gap that preceded it.
-    const heartbeatFrequency =
-      (prevDidDocument ?? currentDidDocument)?.heartbeatFrequency ?? 'P10Y';
+    const heartbeatFrequency = prevHeartbeatFrequency ?? 'P1M';
     if(i > 0 && prevEntryWitnessTime !== null && entryWitnessTime !== null) {
       const freq = moment.duration(heartbeatFrequency);
       const elapsed = entryWitnessTime - prevEntryWitnessTime;
@@ -472,7 +473,7 @@ function _isTrustedWitnessProof({wp, trustedWitnesses}) {
  * @returns {Promise<boolean>} True if the proof is valid.
  */
 async function _verifyOperationProof(
-  {event, opProof, currentDidDocument, prevDidDocument}) {
+  {event, opProof, currentDidDocument, prevHeartbeat}) {
   const vmRef = opProof.verificationMethod;
 
   // try assertionMethod first; if not found, check heartbeat keys
@@ -488,11 +489,11 @@ async function _verifyOperationProof(
     keyController = currentDidDocument.id;
   } else if(vmRef.startsWith('did:key:')) {
     // heartbeat key path: hash the did:key URI and check it against the
-    // heartbeat[] of the *previous* document - the update will rotate it out,
-    // so it is absent from currentDidDocument by the time we verify
+    // effective heartbeat[] from the *previous* entry — the new entry will
+    // rotate it out, so it must not be looked up in the current state
     const didKeyId = vmRef.split('#')[0];
     const hash = await hashDidKey(didKeyId);
-    const heartbeat = prevDidDocument?.heartbeat ?? [];
+    const heartbeat = prevHeartbeat ?? [];
     if(!heartbeat.includes(hash)) {
       throw new Error(
         `verification method not found in DID document: ${vmRef}`);

lib/didcel.js

@@ -43,7 +43,7 @@ const jdl = new JsonLdDocumentLoader();
  * console.log(didDocument.id);  // did:cel:z...
  */
 export async function create(
-  {curve = 'P-256', heartbeatFrequency = 'P10Y'} = {}) {
+  {curve = 'P-256', heartbeatFrequency = 'P1M'} = {}) {
   // generate a new ECDSA key pair using the specified curve (defaults to P-256)
   let keyPair;
   try {
@@ -73,14 +73,13 @@ export async function create(
   const heartbeatHash = await hashDidKey(heartbeatDidKey);
 
   // create initial DID document structure with assertion method
+  // heartbeat[] and heartbeatFrequency belong on the event, not the DID document
   const didDocument = {
     '@context': [
       'https://www.w3.org/ns/did/v1.1',
       'https://w3id.org/didcel/v1'
     ],
-    heartbeatFrequency,
     assertionMethod: [publicKey],
-    heartbeat: [heartbeatHash],
     service: [
       {
         type: 'CelStorageService',
@@ -112,7 +111,12 @@ export async function create(
 
   assertValidDidDocument({didDocument});
 
-  const event = {operation: {type: 'create', data: didDocument}};
+  // heartbeat[] and heartbeatFrequency sit on the event, not the DID document
+  const event = {
+    operation: {type: 'create', data: didDocument},
+    heartbeat: [heartbeatHash],
+    heartbeatFrequency
+  };
   const signedEvent = await _signEvent({event, signer: keyPair.signer()});
 
   const cryptographicEventLog = celCreate({event: signedEvent});
@@ -229,7 +233,8 @@ export async function addVm({didDocument, verificationRelationship, curve}) {
  * });
  */
 export async function createEvent(
-  {type, data, assertionMethod, previousEventHash, heartbeat}) {
+  {type, data, assertionMethod, previousEventHash, heartbeat,
+    heartbeatFrequency}) {
   const operation = {type};
   if(data !== undefined) {
     operation.data = data;
@@ -239,34 +244,19 @@ 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
+  // heartbeat[] and heartbeatFrequency sit on the event, covered by the proof
   if(heartbeat !== undefined) {
     event.heartbeat = heartbeat;
   }
+  if(heartbeatFrequency !== undefined) {
+    event.heartbeatFrequency = heartbeatFrequency;
+  }
   const signedEvent =
     await _signEvent({event, signer: assertionMethod.signer()});
 
   return {event: signedEvent};
 }
 
-/**
- * Sets the heartbeatFrequency on an existing DID document. The proof is
- * removed and must be regenerated with createEvent before adding to the CEL.
- *
- * @param {object} options - Configuration options.
- * @param {object} options.didDocument - The DID document to modify.
- * @param {string} options.heartbeatFrequency - ISO 8601 duration string
- *   (e.g. 'P3M', 'P1Y', 'P1D').
- * @returns {object} An object containing the updated |didDocument| (no proof).
- */
-export function setHeartbeatFrequency({didDocument, heartbeatFrequency}) {
-  const newDidDocument = structuredClone(didDocument);
-  newDidDocument.heartbeatFrequency = heartbeatFrequency;
-  delete newDidDocument.proof;
-  return {didDocument: newDidDocument};
-}
-
 /**
  * Computes the base58btc-encoded SHA3-256 multihash of a did:key URI string.
  * This is the value stored in the `heartbeat` array of a DID document.
@@ -298,6 +288,5 @@ async function _signEvent({event, signer}) {
 }
 
 export default {
-  addVm, create, createEvent, deriveHeartbeatKeyPair, hashDidKey,
-  setHeartbeatFrequency
+  addVm, create, createEvent, deriveHeartbeatKeyPair, hashDidKey
 };

lib/index.js

@@ -6,8 +6,7 @@ export {
 
 // didcel.js: DID document creation and management
 export {
-  addVm, create, createEvent, deriveHeartbeatKeyPair, hashDidKey,
-  setHeartbeatFrequency
+  addVm, create, createEvent, deriveHeartbeatKeyPair, hashDidKey
 } from './didcel.js';
 
 // secrets.js: Encrypted private key storage

lib/validate.js

@@ -43,8 +43,7 @@ const SERVICE_ENTRY = {
 
 const DID_DOCUMENT_SCHEMA = {
   type: 'object',
-  required: ['@context', 'id', 'heartbeatFrequency', 'assertionMethod',
-    'heartbeat', 'service'],
+  required: ['@context', 'id', 'assertionMethod', 'service'],
   properties: {
     '@context': {
       type: 'array',
@@ -56,7 +55,6 @@ const DID_DOCUMENT_SCHEMA = {
       items: {type: 'string'}
     },
     id: DID_CEL,
-    heartbeatFrequency: ISO_DURATION,
     assertionMethod: {
       type: 'array',
       items: VERIFICATION_METHOD,
@@ -66,11 +64,6 @@ const DID_DOCUMENT_SCHEMA = {
     keyAgreement: {type: 'array', items: VERIFICATION_METHOD},
     capabilityDelegation: {type: 'array', items: VERIFICATION_METHOD},
     capabilityInvocation: {type: 'array', items: VERIFICATION_METHOD},
-    heartbeat: {
-      type: 'array',
-      items: MULTIBASE_STRING,
-      minItems: 1
-    },
     service: {
       type: 'array',
       items: SERVICE_ENTRY,
@@ -132,10 +125,12 @@ const STATELESS_OPERATION = {
 
 const CREATE_EVENT = {
   type: 'object',
-  required: ['operation', 'proof'],
+  required: ['operation', 'heartbeat', 'heartbeatFrequency', 'proof'],
   properties: {
     '@context': {},
     operation: CREATE_OPERATION,
+    heartbeat: {type: 'array', items: MULTIBASE_STRING, minItems: 1},
+    heartbeatFrequency: ISO_DURATION,
     proof: DATA_INTEGRITY_PROOF
   },
   additionalProperties: false
@@ -149,6 +144,7 @@ const NON_CREATE_EVENT = {
     previousEventHash: MULTIBASE_STRING,
     operation: {oneOf: [UPDATE_OPERATION, STATELESS_OPERATION]},
     heartbeat: {type: 'array', items: MULTIBASE_STRING},
+    heartbeatFrequency: ISO_DURATION,
     proof: DATA_INTEGRITY_PROOF
   },
   additionalProperties: false

tests/mocha/10-create.js

@@ -20,19 +20,19 @@ describe('create', function() {
     expect(didDocument['@context']).to.include('https://www.w3.org/ns/did/v1.1');
     expect(didDocument['@context']).to.include('https://w3id.org/didcel/v1');
 
-    // heartbeat frequency
-    expect(didDocument.heartbeatFrequency).to.be.a('string').that.is.not.empty;
-
     // assertionMethod: one embedded key with required fields
     expect(didDocument.assertionMethod).to.be.an('array').with.length(1);
     const assertionKey = didDocument.assertionMethod[0];
     expect(assertionKey.type).to.equal('Multikey');
     expect(assertionKey.controller).to.equal(didDocument.id);
     expect(assertionKey.publicKeyMultibase).to.be.a('string').that.is.not.empty;
 
-    // heartbeat: one base58btc-encoded SHA3-256 multihash of a did:key URI
-    expect(didDocument.heartbeat).to.be.an('array').with.length(1);
-    const heartbeatHash = didDocument.heartbeat[0];
+    // heartbeat and heartbeatFrequency belong on the create event, not the DID document
+    const createEventEntry = cryptographicEventLog.log[0];
+    expect(createEventEntry.event.heartbeatFrequency)
+      .to.be.a('string').that.is.not.empty;
+    expect(createEventEntry.event.heartbeat).to.be.an('array').with.length(1);
+    const heartbeatHash = createEventEntry.event.heartbeat[0];
     expect(heartbeatHash).to.be.a('string').that.matches(/^z/);
 
     // heartbeatSecret: 16-byte KDF master secret returned to caller for storage

tests/mocha/40-heartbeat.js

@@ -89,13 +89,13 @@ describe('heartbeat', function() {
     async () => {
       const {cryptographicEventLog} = await runHeartbeat();
 
-      const createDoc = cryptographicEventLog.log[0].event.operation.data;
+      const createEntry = cryptographicEventLog.log[0].event;
       const heartbeatEvent = cryptographicEventLog.log[1].event;
 
       // 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 new hash must differ from the one in the original create event
+      expect(heartbeatEvent.heartbeat[0]).to.not.equal(createEntry.heartbeat[0]);
       // the heartbeat event has no operation.data (stateless)
       expect(heartbeatEvent.operation.data).to.be.undefined;
     });