@enbox/dwn-sdk-js 0.0.7 → 0.1.0

package/src/interfaces/protocols-configure.ts

@@ -16,7 +16,7 @@ import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import { isCrossProtocolRef, parseCrossProtocolRef } from '../utils/protocols.js';
 import { normalizeProtocolUrl, normalizeSchemaUrl, validateProtocolUrlNormalized, validateSchemaUrlNormalized } from '../utils/url.js';
-import { ProtocolAction, ProtocolActor } from '../types/protocols-types.js';
+import { ProtocolAction, ProtocolActor, ProtocolRecordLimitStrategy } from '../types/protocols-types.js';
 
 export type ProtocolsConfigureOptions = {
   messageTimestamp?: string;
@@ -68,7 +68,7 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
    * @param messageStore Used to check if the grant has been revoked.
    */
   public async authorizeAuthorDelegate(messageStore: MessageStore): Promise<void> {
-    const delegatedGrant = await PermissionGrant.parse(this.message.authorization.authorDelegatedGrant!);
+    const delegatedGrant = PermissionGrant.parse(this.message.authorization.authorDelegatedGrant!);
     await ProtocolsGrantAuthorization.authorizeConfigure({
       protocolsConfigureMessage : this.message,
       expectedGrantor           : this.author!,
@@ -232,6 +232,27 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       }
     }
 
+    // Validate $recordLimit
+    if (ruleSet.$recordLimit !== undefined) {
+      const { max, strategy } = ruleSet.$recordLimit;
+
+      if (!Number.isInteger(max) || max < 1) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidRecordLimit,
+          `Invalid $recordLimit.max value ${max} at protocol path '${ruleSetProtocolPath}': must be an integer >= 1.`
+        );
+      }
+
+      const validStrategies = Object.values(ProtocolRecordLimitStrategy) as string[];
+      if (!validStrategies.includes(strategy as string)) {
+        throw new DwnError(
+          DwnErrorCode.ProtocolsConfigureInvalidRecordLimit,
+          `Invalid $recordLimit.strategy '${strategy}' at protocol path '${ruleSetProtocolPath}': ` +
+          `must be one of ${validStrategies.join(', ')}.`
+        );
+      }
+    }
+
     if (ruleSet.$tags) {
       const ajv = new Ajv.default();
       const { $allowUndefinedTags, $requiredTags, ...tagProperties } = ruleSet.$tags;
@@ -397,6 +418,33 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       }
     }
 
+    // Warn when `$delivery` is set without `$actions`.
+    // Delivery targets are determined from `$actions` role records and actor rules.
+    // Without `$actions`, the server cannot determine who to deliver records to.
+    if (ruleSet.$delivery !== undefined && (ruleSet.$actions === undefined || ruleSet.$actions.length === 0)) {
+      console.warn(
+        `ProtocolsConfigure: protocol path '${ruleSetProtocolPath}' has $delivery: '${ruleSet.$delivery}' ` +
+        `but no $actions rules. The server uses $actions to determine delivery targets — ` +
+        `without $actions, no participants can be resolved for delivery.`
+      );
+    }
+
+    // Warn when `$immutable: true` is combined with `$actions` that include `update` or `co-update`.
+    // The `$immutable` directive overrides any update permission — updates are always rejected.
+    if (ruleSet.$immutable === true && actionRules.length > 0) {
+      const hasUpdateAction = actionRules.some(
+        (rule: ProtocolActionRule): boolean =>
+          rule.can.includes(ProtocolAction.Update) || rule.can.includes(ProtocolAction.CoUpdate)
+      );
+      if (hasUpdateAction) {
+        console.warn(
+          `ProtocolsConfigure: protocol path '${ruleSetProtocolPath}' has $immutable: true ` +
+          `but $actions include 'update' or 'co-update'. The $immutable directive takes ` +
+          `precedence — updates will always be rejected regardless of action rules.`
+        );
+      }
+    }
+
     // Validate nested rule sets
     for (const recordType in ruleSet) {
       if (recordType.startsWith('$')) {
@@ -457,7 +505,7 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
     }
 
     // validate that `$ref` nodes do not have other directives
-    const forbiddenDirectives = ['$actions', '$role', '$size', '$tags', '$encryption'] as const;
+    const forbiddenDirectives = ['$actions', '$role', '$size', '$tags', '$encryption', '$recordLimit', '$immutable', '$delivery', '$squash'] as const;
     for (const directive of forbiddenDirectives) {
       if (ruleSet[directive] !== undefined) {
         throw new DwnError(

package/src/interfaces/records-count.ts

@@ -94,7 +94,7 @@ export class RecordsCount extends AbstractMessage<RecordsCountMessage> {
    * @param messageStore Used to check if the grant has been revoked.
    */
   public async authorizeDelegate(messageStore: MessageStore): Promise<void> {
-    const delegatedGrant = await PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
+    const delegatedGrant = PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
     await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
       incomingMessage : this.message,
       expectedGrantor : this.author!,

package/src/interfaces/records-delete.ts

@@ -110,7 +110,7 @@ export class RecordsDelete extends AbstractMessage<RecordsDeleteMessage> {
    * @param messageStore Used to check if the grant has been revoked.
    */
   public async authorizeDelegate(recordsWriteToDelete: RecordsWriteMessage, messageStore: MessageStore): Promise<void> {
-    const delegatedGrant = await PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
+    const delegatedGrant = PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
     await RecordsGrantAuthorization.authorizeDelete({
       recordsDeleteMessage : this.message,
       recordsWriteToDelete,

package/src/interfaces/records-query.ts

@@ -119,7 +119,7 @@ export class RecordsQuery extends AbstractMessage<RecordsQueryMessage> {
    * @param messageStore Used to check if the grant has been revoked.
    */
   public async authorizeDelegate(messageStore: MessageStore): Promise<void> {
-    const delegatedGrant = await PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
+    const delegatedGrant = PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
     await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
       incomingMessage : this.message,
       expectedGrantee : this.signer!,

package/src/interfaces/records-read.ts

@@ -110,7 +110,7 @@ export class RecordsRead extends AbstractMessage<RecordsReadMessage> {
    * @param messageStore Used to check if the grant has been revoked.
    */
   public async authorizeDelegate(matchedRecordsWrite: RecordsWriteMessage, messageStore: MessageStore): Promise<void> {
-    const delegatedGrant = await PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
+    const delegatedGrant = PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
     await RecordsGrantAuthorization.authorizeRead({
       recordsReadMessage          : this.message,
       recordsWriteMessageToBeRead : matchedRecordsWrite,

package/src/interfaces/records-subscribe.ts

@@ -22,6 +22,12 @@ export type RecordsSubscribeOptions = {
   signer?: MessageSigner;
   protocolRole?: string;
 
+  /**
+   * Opaque EventLog cursor string to resume from. When provided, catch-up events are
+   * replayed from the EventLog and an EOSE marker is delivered before live events.
+   */
+  cursor?: string;
+
   /**
    * The delegated grant to sign on behalf of the logical author, which is the grantor (`grantedBy`) of the delegated grant.
    */
@@ -68,6 +74,7 @@ export class RecordsSubscribe extends AbstractMessage<RecordsSubscribeMessage> {
       filter           : Records.normalizeFilter(options.filter),
       dateSort         : options.dateSort,
       pagination       : options.pagination,
+      cursor           : options.cursor,
     };
 
     // delete all descriptor properties that are `undefined` else the code will encounter the following IPLD issue when attempting to generate CID:
@@ -97,7 +104,7 @@ export class RecordsSubscribe extends AbstractMessage<RecordsSubscribeMessage> {
  * @param messageStore Used to check if the grant has been revoked.
  */
   public async authorizeDelegate(messageStore: MessageStore): Promise<void> {
-    const delegatedGrant = await PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
+    const delegatedGrant = PermissionGrant.parse(this.message.authorization!.authorDelegatedGrant!);
     await RecordsGrantAuthorization.authorizeQueryOrSubscribe({
       incomingMessage : this.message,
       expectedGrantor : this.author!,

package/src/interfaces/records-write-signing.ts

@@ -1,48 +1,28 @@
 import type { GeneralJws } from '../types/jws-types.js';
 import type { MessageSigner } from '../types/signer.js';
 import type { EncryptionInput, JweEncryption } from '../utils/encryption.js';
-import type { RecordsWriteAttestationPayload, RecordsWriteDescriptor, RecordsWriteMessage, RecordsWriteSignaturePayload } from '../types/records-types.js';
+import type { RecordsWriteAttestationPayload, RecordsWriteMessage, RecordsWriteSignaturePayload } from '../types/records-types.js';
 
 import { Cid } from '../utils/cid.js';
 import { Encoder } from '../utils/encoder.js';
 import { Encryption } from '../utils/encryption.js';
 import { GeneralJwsBuilder } from '../jose/jws/general/builder.js';
 import { Jws } from '../utils/jws.js';
-import { KeyDerivationScheme } from '../utils/hd-key.js';
 import { removeUndefinedProperties } from '../utils/object.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
 /**
  * Creates the JWE `encryption` property if encryption input is given. Else `undefined` is returned.
  * Uses ECDH-ES+A256KW key agreement with X25519 and AEAD content encryption (A256GCM or XC20P).
- * @param descriptor Descriptor of the `RecordsWrite` message which contains the information needed by key path derivation schemes.
  * @param encryptionInput The encryption input containing CEK, IV, authentication tag, and recipient key encryption inputs.
  */
 export async function createEncryptionProperty(
-  descriptor: RecordsWriteDescriptor,
   encryptionInput: EncryptionInput | undefined,
 ): Promise<JweEncryption | undefined> {
   if (encryptionInput === undefined) {
     return undefined;
   }
 
-  // Validate derivation scheme prerequisites
-  for (const keyEncryptionInput of encryptionInput.keyEncryptionInputs) {
-    if (keyEncryptionInput.derivationScheme === KeyDerivationScheme.ProtocolPath && descriptor.protocol === undefined) {
-      throw new DwnError(
-        DwnErrorCode.RecordsWriteMissingProtocol,
-        '`protocols` encryption scheme cannot be applied to record without the `protocol` property.'
-      );
-    }
-
-    if (keyEncryptionInput.derivationScheme === KeyDerivationScheme.Schemas && descriptor.schema === undefined) {
-      throw new DwnError(
-        DwnErrorCode.RecordsWriteMissingSchema,
-        '`schemas` encryption scheme cannot be applied to record without the `schema` property.'
-      );
-    }
-  }
-
   // Build the JWE structure. The authentication tag comes from the AEAD encryption of record data.
   const jwe = await Encryption.buildJwe(encryptionInput, encryptionInput.authenticationTag);
 
@@ -69,7 +49,7 @@ export async function createAttestation(descriptorCid: string, signers?: Message
  */
 export async function createSignerSignature(input: {
   recordId: string,
-  contextId: string | undefined,
+  contextId: string,
   descriptorCid: string,
   attestation: GeneralJws | undefined,
   encryption: JweEncryption | undefined,

package/src/interfaces/records-write.ts

@@ -43,8 +43,8 @@ import { normalizeProtocolUrl, normalizeSchemaUrl, validateProtocolUrlNormalized
 
 export type RecordsWriteOptions = {
   recipient?: string;
-  protocol?: string;
-  protocolPath?: string;
+  protocol: string;
+  protocolPath: string;
   protocolRole?: string;
   schema?: string;
   tags?: RecordsWriteTags;
@@ -52,7 +52,7 @@ export type RecordsWriteOptions = {
 
   /**
    * Must be given if this message is for a non-root protocol record.
-   * If not given, it either means this write is for a root protocol record or a flat-space record.
+   * If not given, it means this write is for a root protocol record.
    */
   parentContextId?: string;
 
@@ -79,6 +79,13 @@ export type RecordsWriteOptions = {
   encryptionInput?: EncryptionInput;
   permissionGrantId?: string;
 
+  /**
+   * When `true`, this record is a squash (snapshot) write that atomically creates a snapshot
+   * and deletes all older sibling records at the same protocol path within the same parent context.
+   * Only valid at protocol paths with `$squash: true`. Must be an initial write (new record).
+   */
+  squash?: true;
+
   /**
    * The author's ProtocolPath-derived public key for key delivery.
    * When set, this is attached to the authorization model so the DWN owner
@@ -282,12 +289,11 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    * @param options.dateCreated If `undefined`, it will be auto-filled with current time.
    * @param options.messageTimestamp If `undefined`, it will be auto-filled with current time.
    * @param options.parentContextId Must be given if this message is for a non-root protocol record.
-   *                                If not given, it either means this write is for a root protocol record or a flat-space record.
+   *                                If not given, it means this write is for a root protocol record.
    */
   public static async create(options: RecordsWriteOptions): Promise<RecordsWrite> {
-    if ((options.protocol === undefined && options.protocolPath !== undefined) ||
-      (options.protocol !== undefined && options.protocolPath === undefined)) {
-      throw new DwnError(DwnErrorCode.RecordsWriteCreateProtocolAndProtocolPathMutuallyInclusive, '`protocol` and `protocolPath` must both be defined or undefined at the same time');
+    if (options.protocol === undefined || options.protocolPath === undefined) {
+      throw new DwnError(DwnErrorCode.RecordsWriteCreateMissingProtocol, '`protocol` and `protocolPath` are required');
     }
 
     if ((options.data === undefined && options.dataCid === undefined) ||
@@ -312,7 +318,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     const descriptor: RecordsWriteDescriptor = {
       interface         : DwnInterfaceName.Records,
       method            : DwnMethodName.Write,
-      protocol          : options.protocol !== undefined ? normalizeProtocolUrl(options.protocol) : undefined,
+      protocol          : normalizeProtocolUrl(options.protocol),
       protocolPath      : options.protocolPath,
       recipient         : options.recipient,
       schema            : options.schema !== undefined ? normalizeSchemaUrl(options.schema) : undefined,
@@ -326,6 +332,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       datePublished     : options.datePublished,
       dataFormat        : options.dataFormat,
       permissionGrantId : options.permissionGrantId,
+      squash            : options.squash,
     };
 
     // generate `datePublished` if the message is to be published but `datePublished` is not given
@@ -346,7 +353,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     const attestation = await createAttestation(descriptorCid, options.attestationSigners);
 
     // `encryption` generation
-    const encryption = await createEncryptionProperty(descriptor, options.encryptionInput);
+    const encryption = await createEncryptionProperty(options.encryptionInput);
 
     const message: InternalRecordsWriteMessage = {
       recordId,
@@ -474,7 +481,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       }
 
       // Build only the new recipients (reuses createEncryptionProperty for ECDH-ES+A256KW logic)
-      const newEncryption = await createEncryptionProperty(this._message.descriptor, encryptionInput);
+      const newEncryption = await createEncryptionProperty(encryptionInput);
       if (newEncryption) {
         this._message.encryption.recipients.push(...newEncryption.recipients);
       }
@@ -493,7 +500,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       // the contextKey schema. We chose the in-record approach because it keeps
       // records self-contained and the read/decrypt path unchanged.
     } else {
-      this._message.encryption = await createEncryptionProperty(this._message.descriptor, encryptionInput);
+      this._message.encryption = await createEncryptionProperty(encryptionInput);
 
       // Full replacement invalidates the authorization — caller must re-sign.
       delete this._message.authorization;
@@ -530,22 +537,19 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     // compute `recordId` if not given at construction time
     this._message.recordId = this._message.recordId ?? await RecordsWrite.getEntryId(authorDid, descriptor);
 
-    // compute `contextId` if this is a protocol-space record
-    if (this._message.descriptor.protocol !== undefined) {
-      // if `parentContextId` is not given, this is a root protocol record
-      if (this.parentContextId === undefined || this.parentContextId === '') {
-        this._message.contextId = this._message.recordId;
-      } else {
-        // else this is a non-root protocol record
-
-        this._message.contextId = this.parentContextId + '/' + this._message.recordId;
-      }
+    // compute `contextId` — all records belong to a protocol
+    if (this.parentContextId === undefined || this.parentContextId === '') {
+      // root protocol record
+      this._message.contextId = this._message.recordId;
+    } else {
+      // non-root protocol record
+      this._message.contextId = this.parentContextId + '/' + this._message.recordId;
     }
 
     // `signature` generation
     const signature = await createSignerSignature({
       recordId    : this._message.recordId,
-      contextId   : this._message.contextId,
+      contextId   : this._message.contextId!, // contextId is computed just above, always defined here
       descriptorCid,
       attestation : this._message.attestation,
       encryption  : this._message.encryption,
@@ -589,7 +593,6 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
 
     this._ownerSignaturePayload = Jws.decodePlainObjectPayload(ownerSignature);
     this._owner = Jws.extractDid(signer.keyId);
-    ;
   }
 
   /**
@@ -634,9 +637,8 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
         );
       }
 
-      // if the message is also a protocol context root, the `contextId` must match the expected deterministic value
-      if (this.message.descriptor.protocol !== undefined &&
-        this.message.descriptor.parentId === undefined) {
+      // if the message is a protocol context root, the `contextId` must match the expected deterministic value
+      if (this.message.descriptor.parentId === undefined) {
         const expectedContextId = await this.getEntryId();
 
         if (this.message.contextId !== expectedContextId) {
@@ -699,9 +701,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       }
     }
 
-    if (this.message.descriptor.protocol !== undefined) {
-      validateProtocolUrlNormalized(this.message.descriptor.protocol);
-    }
+    validateProtocolUrlNormalized(this.message.descriptor.protocol);
     if (this.message.descriptor.schema !== undefined) {
       validateSchemaUrlNormalized(this.message.descriptor.schema);
     }
@@ -713,13 +713,6 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     }
   }
 
-  /**
-   * Delegate to the standalone `validateAttestationIntegrity` function for backward compatibility.
-   */
-  private static async validateAttestationIntegrity(message: RecordsWriteMessage): Promise<void> {
-    return validateAttestationIntegrity(message);
-  }
-
   /**
    * Computes the deterministic Entry ID of this message.
    */
@@ -757,11 +750,13 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     // we want to process tags separately from the rest of descriptors as it is an object and not a primitive KeyValue type.
     const { tags, ...descriptor } = message.descriptor;
     delete descriptor.published; // handle `published` specifically further down
+    delete descriptor.squash; // handle `squash` specifically further down
 
     let indexes: KeyValues = {
       ...descriptor,
       isLatestBaseState,
       published : !!message.descriptor.published,
+      squash    : !!message.descriptor.squash,
       author    : this.author!, //author will not be undefined when indexes are constructed as it's been authorized
       recordId  : message.recordId,
       entryId   : await RecordsWrite.getEntryId(this.author, this.message.descriptor)
@@ -778,7 +773,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     // add additional indexes to optional values if given
     // TODO: index multiple attesters (https://github.com/enboxorg/enbox/issues/223)
     if (this.attesters.length > 0) { indexes.attester = this.attesters[0]; }
-    if (message.contextId !== undefined) { indexes.contextId = message.contextId; }
+    indexes.contextId = message.contextId;
 
     return indexes;
   }
@@ -788,7 +783,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    * @param messageStore Used to check if the grant has been revoked.
    */
   public async authorizeAuthorDelegate(messageStore: MessageStore): Promise<void> {
-    const delegatedGrant = await PermissionGrant.parse(this.message.authorization.authorDelegatedGrant!);
+    const delegatedGrant = PermissionGrant.parse(this.message.authorization.authorDelegatedGrant!);
     await RecordsGrantAuthorization.authorizeWrite({
       recordsWriteMessage : this.message,
       expectedGrantor     : this.author!,
@@ -803,7 +798,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    * @param messageStore Used to check if the grant has been revoked.
    */
   public async authorizeOwnerDelegate(messageStore: MessageStore): Promise<void> {
-    const delegatedGrant = await PermissionGrant.parse(this.message.authorization.ownerDelegatedGrant!);
+    const delegatedGrant = PermissionGrant.parse(this.message.authorization.ownerDelegatedGrant!);
     await RecordsGrantAuthorization.authorizeWrite({
       recordsWriteMessage : this.message,
       expectedGrantor     : this.owner!,
@@ -829,14 +824,6 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     return (entryId === recordsWriteMessage.recordId);
   }
 
-  /** Delegate to `createEncryptionProperty` in `records-write-signing.ts`. */
-  private static async createEncryptionProperty(
-    descriptor: RecordsWriteDescriptor,
-    encryptionInput: EncryptionInput | undefined,
-  ): Promise<JweEncryption | undefined> {
-    return createEncryptionProperty(descriptor, encryptionInput);
-  }
-
   /** Delegate to `createAttestation` in `records-write-signing.ts`. */
   public static async createAttestation(descriptorCid: string, signers?: MessageSigner[]): Promise<GeneralJws | undefined> {
     return createAttestation(descriptorCid, signers);
@@ -845,7 +832,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
   /** Delegate to `createSignerSignature` in `records-write-signing.ts`. */
   public static async createSignerSignature(input: {
     recordId: string,
-    contextId: string | undefined,
+    contextId: string,
     descriptorCid: string,
     attestation: GeneralJws | undefined,
     encryption: JweEncryption | undefined,

package/src/protocols/permission-grant.ts

@@ -68,7 +68,7 @@ export class PermissionGrant {
    * and that the decoded data contains `scope` and `dateExpires`.
    * @throws {DwnError} if any required field is missing.
    */
-  public static async parse(message: DataEncodedRecordsWriteMessage): Promise<PermissionGrant> {
+  public static parse(message: DataEncodedRecordsWriteMessage): PermissionGrant {
     PermissionGrant.validateMessage(message);
     const permissionGrant = new PermissionGrant(message);
     return permissionGrant;

package/src/protocols/permission-request.ts

@@ -49,7 +49,7 @@ export class PermissionRequest {
    * and that the decoded data contains `scope`.
    * @throws {DwnError} if any required field is missing.
    */
-  public static async parse(message: DataEncodedRecordsWriteMessage): Promise<PermissionRequest> {
+  public static parse(message: DataEncodedRecordsWriteMessage): PermissionRequest {
     PermissionRequest.validateMessage(message);
     const permissionRequest = new PermissionRequest(message);
     return permissionRequest;