@enbox/dwn-sdk-js 0.0.6 → 0.0.8

package/src/index.ts

@@ -1,13 +1,17 @@
 // export everything that we want to be consumable
 export type { DwnConfig } from './dwn.js';
-export type { EventListener, EventStream, EventSubscription, MessageEvent, SubscriptionReply } from './types/subscriptions.js';
+export type { EventListener, EventLog, EventLogEntry, EventLogReadOptions, EventLogReadResult, EventLogSubscribeOptions, EventSubscription, MessageEvent, SubscriptionEose, SubscriptionEvent, SubscriptionListener, SubscriptionMessage, SubscriptionReply } from './types/subscriptions.js';
 export type { AuthorizationModel, Descriptor, DelegatedGrantRecordsWriteMessage, GenericMessage, GenericMessageReply, GenericSignaturePayload, MessageSort, MessageSubscription, Pagination, QueryResultEntry, Status } from './types/message-types.js';
 export type { MessagesFilter, MessagesReadMessage as MessagesReadMessage, MessagesReadReply as MessagesReadReply, MessagesReadReplyEntry as MessagesReadReplyEntry, MessagesReadDescriptor, MessagesSubscribeDescriptor, MessagesSubscribeMessage, MessagesSubscribeReply, MessageSubscriptionHandler, MessagesSubscribeMessageOptions, MessagesSyncAction, MessagesSyncDescriptor, MessagesSyncMessage, MessagesSyncReply } from './types/messages-types.js';
 export type { GT, LT, Filter, FilterValue, KeyValues, EqualFilter, OneOfFilter, RangeFilter, RangeCriterion, PaginationCursor, QueryOptions, RangeValue, StartsWithFilter } from './types/query-types.js';
-export type { ProtocolsConfigureDescriptor, ProtocolDefinition, ProtocolTypes, ProtocolRuleSet, ProtocolsQueryFilter, ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply, ProtocolActionRule, ProtocolPathEncryption, ProtocolsQueryDescriptor, ProtocolSizeDefinition, ProtocolTagsDefinition, ProtocolTagSchema, ProtocolType, ProtocolUses } from './types/protocols-types.js';
+export type { ProtocolsConfigureDescriptor, ProtocolDefinition, ProtocolTypes, ProtocolRuleSet, ProtocolsQueryFilter, ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply, ProtocolActionRule, ProtocolPathEncryption, ProtocolsQueryDescriptor, ProtocolRecordLimitDefinition, ProtocolSizeDefinition, ProtocolTagsDefinition, ProtocolTagSchema, ProtocolType, ProtocolUses } from './types/protocols-types.js';
+export { ProtocolRecordLimitStrategy } from './types/protocols-types.js';
 export type { DataEncodedRecordsWriteMessage, RecordsCountDescriptor, RecordsCountMessage, RecordsCountReply, RecordsDeleteMessage, RecordsFilter, RecordsQueryMessage, RecordsQueryReply, RecordsQueryReplyEntry, RecordsReadMessage, RecordsReadReply, RecordsSubscribeDescriptor, RecordsSubscribeMessage, RecordsSubscribeReply, RecordSubscriptionHandler, RecordsWriteDescriptor, RecordsWriteTags, RecordsWriteTagValue, RecordsWriteMessage, RecordsWriteSignaturePayload, RecordsDeleteDescriptor, RecordsQueryDescriptor, RecordsReadDescriptor, RecordsSubscribeMessageOptions, RecordsWriteMessageOptions, InternalRecordsWriteMessage, RecordEvent, RecordsWriteTagsFilter } from './types/records-types.js';
 export type { GeneralJws, SignatureEntry } from './types/jws-types.js';
 export { authenticate } from './core/auth.js';
+export { CoreProtocolRegistry } from './core/core-protocol.js';
+export { PERMISSIONS_REVOCATION_PATH } from './core/constants.js';
+export type { CoreProtocol, CoreProtocolStores } from './core/core-protocol.js';
 export { AllowAllTenantGate } from './core/tenant-gate.js';
 export type { ActiveTenantCheckResult, TenantGate } from './core/tenant-gate.js';
 export { Cid } from './utils/cid.js';
@@ -72,7 +76,7 @@ export { Time } from './utils/time.js';
 export * from './types/permission-types.js';
 export * from './types/records-types.js';
 
-// concrete implementations of stores and event stream
+// concrete implementations of stores and event log
 export { BlockstoreLevel } from './store/blockstore-level.js';
 export type { BlockstoreLevelConfig } from './store/blockstore-level.js';
 export { DataStoreLevel } from './store/data-store-level.js';
@@ -85,8 +89,8 @@ export { MessageStoreLevel } from './store/message-store-level.js';
 export type { MessageStoreLevelConfig } from './store/message-store-level.js';
 export { ResumableTaskStoreLevel } from './store/resumable-task-store-level.js';
 export type { ResumableTaskStoreLevelConfig } from './store/resumable-task-store-level.js';
-export { EventEmitterStream } from './event-stream/event-emitter-stream.js';
-export type { EventEmitterStreamConfig } from './event-stream/event-emitter-stream.js';
+export { EventEmitterEventLog } from './event-stream/event-emitter-event-log.js';
+export type { EventEmitterEventLogConfig } from './event-stream/event-emitter-event-log.js';
 
 // Sparse Merkle Tree and StateIndex
 export type { StateIndex } from './types/state-index.js';

package/src/interfaces/messages-subscribe.ts

@@ -13,8 +13,13 @@ import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.j
 export type MessagesSubscribeOptions = {
   signer: MessageSigner;
   messageTimestamp?: string;
-  filters?: MessagesFilter[]
+  filters?: MessagesFilter[];
   permissionGrantId?: 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;
 };
 
 export class MessagesSubscribe extends AbstractMessage<MessagesSubscribeMessage> {
@@ -48,6 +53,7 @@ export class MessagesSubscribe extends AbstractMessage<MessagesSubscribeMessage>
       filters           : options.filters ?? [],
       messageTimestamp  : options.messageTimestamp ?? currentTime,
       permissionGrantId : options.permissionGrantId,
+      cursor            : options.cursor,
     };
 
     removeUndefinedProperties(descriptor);

package/src/interfaces/protocols-configure.ts

@@ -1,7 +1,10 @@
 import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
 import type { MessageSigner } from '../types/signer.js';
 import type { MessageStore } from '../types/message-store.js';
-import type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureDescriptor, ProtocolsConfigureMessage, ProtocolUses } from '../types/protocols-types.js';
+import type {
+  ProtocolActionRule, ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureDescriptor,
+  ProtocolsConfigureMessage, ProtocolTypes, ProtocolUses
+} from '../types/protocols-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import Ajv from 'ajv/dist/2020.js';
@@ -13,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;
@@ -65,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!,
@@ -151,7 +154,8 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       ruleSetProtocolPath : '',
       recordTypes,
       roles,
-      uses
+      uses,
+      types               : definition.types,
     });
   }
 
@@ -196,9 +200,12 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
    * Validates the given rule set structure then recursively validates its nested child rule sets.
    */
   private static validateRuleSetRecursively(
-    input: { ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, recordTypes: string[], roles: string[], uses?: ProtocolUses }
+    input: {
+      ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, recordTypes: string[],
+      roles: string[], uses?: ProtocolUses, types: ProtocolTypes
+    }
   ): void {
-    const { ruleSet, ruleSetProtocolPath, recordTypes, roles, uses } = input;
+    const { ruleSet, ruleSetProtocolPath, recordTypes, roles, uses, types } = input;
 
     // Validate $ref constraints: $ref is only supported at root level (no `/` in protocol path),
     // and a $ref node is a pure attachment point with no other directives.
@@ -225,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;
@@ -370,6 +398,42 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       }
     }
 
+    // Warn when `encryptionRequired: true` is combined with `{ who: 'anyone', can: ['read'] }`.
+    // Authorization allows anyone to read the record, but encryption prevents them from
+    // decrypting the data — almost certainly unintentional. (issue #115)
+    if (ruleSetProtocolPath !== '') {
+      const typeName = ruleSetProtocolPath.split('/').pop()!;
+      const protocolType = types[typeName];
+      if (protocolType?.encryptionRequired === true) {
+        const anyoneCanRead = actionRules.some(
+          (rule: ProtocolActionRule): boolean => rule.who === ProtocolActor.Anyone && rule.can.includes(ProtocolAction.Read)
+        );
+        if (anyoneCanRead) {
+          console.warn(
+            `ProtocolsConfigure: type '${typeName}' at path '${ruleSetProtocolPath}' has ` +
+            `encryptionRequired: true but allows { who: 'anyone', can: ['read'] }. ` +
+            `Anyone can read the record but no one outside the key holders can decrypt it.`
+          );
+        }
+      }
+    }
+
+    // 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('$')) {
@@ -399,7 +463,8 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
         ruleSetProtocolPath : childRuleSetProtocolPath,
         recordTypes,
         roles,
-        uses
+        uses,
+        types,
       });
     }
   }
@@ -429,7 +494,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'] 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-query.ts

@@ -0,0 +1,139 @@
+import type { GenericMessage } from '../types/message-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { RecordsWrite } from './records-write.js';
+import type { InternalRecordsWriteMessage, RecordsWriteMessage } from '../types/records-types.js';
+
+import { Jws } from '../utils/jws.js';
+import { Message } from '../core/message.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+// Late-bound import to avoid circular dependency at module-evaluation time.
+// `RecordsWrite` imports this module; this module needs `RecordsWrite.isInitialWrite` and `.parse`.
+let _RecordsWriteClass: typeof RecordsWrite;
+async function getRecordsWrite(): Promise<typeof RecordsWrite> {
+  if (!_RecordsWriteClass) {
+    const mod = await import('./records-write.js');
+    _RecordsWriteClass = mod.RecordsWrite;
+  }
+  return _RecordsWriteClass;
+}
+
+/**
+ * Gets the initial write from the given list of messages.
+ */
+export async function getInitialWrite(messages: GenericMessage[]): Promise<RecordsWriteMessage> {
+  const RW = await getRecordsWrite();
+  for (const message of messages) {
+    if (await RW.isInitialWrite(message)) {
+      return message as RecordsWriteMessage;
+    }
+  }
+
+  throw new DwnError(DwnErrorCode.RecordsWriteGetInitialWriteNotFound, `Initial write is not found.`);
+}
+
+/**
+ * Verifies that immutable properties of the two given messages are identical.
+ * @throws {DwnError} if immutable properties between two RecordsWrite messages differ.
+ */
+export function verifyEqualityOfImmutableProperties(
+  existingWriteMessage: RecordsWriteMessage, newMessage: RecordsWriteMessage
+): boolean {
+  const mutableDescriptorProperties = ['dataCid', 'dataSize', 'dataFormat', 'datePublished', 'published', 'messageTimestamp', 'tags'];
+
+  // get distinct property names that exist in either the existing message given or new message
+  let descriptorPropertyNames: string[] = [];
+  descriptorPropertyNames.push(...Object.keys(existingWriteMessage.descriptor));
+  descriptorPropertyNames.push(...Object.keys(newMessage.descriptor));
+  descriptorPropertyNames = [...new Set(descriptorPropertyNames)]; // step to remove duplicates
+
+  // ensure all immutable properties are not modified
+  for (const descriptorPropertyName of descriptorPropertyNames) {
+    // if property is supposed to be immutable
+    if (mutableDescriptorProperties.indexOf(descriptorPropertyName) === -1) {
+      const valueInExistingWrite = (existingWriteMessage.descriptor as Record<string, unknown>)[descriptorPropertyName];
+      const valueInNewMessage = (newMessage.descriptor as Record<string, unknown>)[descriptorPropertyName];
+      if (valueInNewMessage !== valueInExistingWrite) {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteImmutablePropertyChanged,
+          `${descriptorPropertyName} is an immutable property: cannot change '${valueInExistingWrite}' to '${valueInNewMessage}'`
+        );
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Gets the DID of the attesters of the given message.
+ */
+export function getAttesters(message: InternalRecordsWriteMessage): string[] {
+  const attestationSignatures = message.attestation?.signatures ?? [];
+  const attesters = attestationSignatures.map((signature): string => Jws.getSignerDid(signature));
+  return attesters;
+}
+
+/**
+ * Fetches the newest RecordsWrite for a given recordId from the message store.
+ * @throws {DwnError} if no write is found.
+ */
+export async function fetchNewestRecordsWrite(
+  messageStore: MessageStore,
+  tenant: string,
+  recordId: string,
+): Promise<RecordsWriteMessage> {
+  // get existing RecordsWrite messages matching the `recordId`
+  const query = {
+    interface : DwnInterfaceName.Records,
+    method    : DwnMethodName.Write,
+    recordId  : recordId
+  };
+
+  const { messages: existingMessages } = await messageStore.query(tenant, [ query ]);
+  const newestWrite = await Message.getNewestMessage(existingMessages);
+  if (newestWrite !== undefined) {
+    return newestWrite as RecordsWriteMessage;
+  }
+
+  throw new DwnError(DwnErrorCode.RecordsWriteGetNewestWriteRecordNotFound, 'record not found');
+}
+
+/**
+ * Fetches the initial RecordsWrite of a record.
+ * @returns The initial RecordsWrite if found; `undefined` otherwise.
+ */
+export async function fetchInitialRecordsWrite(
+  messageStore: MessageStore,
+  tenant: string,
+  recordId: string
+): Promise<RecordsWrite | undefined> {
+  const initialRecordsWriteMessage = await fetchInitialRecordsWriteMessage(messageStore, tenant, recordId);
+  if (initialRecordsWriteMessage === undefined) {
+    return undefined;
+  }
+
+  const RW = await getRecordsWrite();
+  const initialRecordsWrite = await RW.parse(initialRecordsWriteMessage);
+  return initialRecordsWrite;
+}
+
+/**
+ * Fetches the initial RecordsWrite message of a record.
+ * @returns The initial RecordsWriteMessage if found; `undefined` otherwise.
+ */
+export async function fetchInitialRecordsWriteMessage(
+  messageStore: MessageStore,
+  tenant: string,
+  recordId: string
+): Promise<RecordsWriteMessage | undefined> {
+  const query = { entryId: recordId };
+  const { messages } = await messageStore.query(tenant, [query]);
+
+  if (messages.length === 0) {
+    return undefined;
+  }
+
+  return messages[0] as RecordsWriteMessage;
+}

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

@@ -0,0 +1,123 @@
+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, 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 { 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 encryptionInput The encryption input containing CEK, IV, authentication tag, and recipient key encryption inputs.
+ */
+export async function createEncryptionProperty(
+  encryptionInput: EncryptionInput | undefined,
+): Promise<JweEncryption | undefined> {
+  if (encryptionInput === undefined) {
+    return undefined;
+  }
+
+  // Build the JWE structure. The authentication tag comes from the AEAD encryption of record data.
+  const jwe = await Encryption.buildJwe(encryptionInput, encryptionInput.authenticationTag);
+
+  return jwe;
+}
+
+/**
+ * Creates the `attestation` property of a RecordsWrite message if given signature inputs; returns `undefined` otherwise.
+ */
+export async function createAttestation(descriptorCid: string, signers?: MessageSigner[]): Promise<GeneralJws | undefined> {
+  if (signers === undefined || signers.length === 0) {
+    return undefined;
+  }
+
+  const attestationPayload: RecordsWriteAttestationPayload = { descriptorCid };
+  const attestationPayloadBytes = Encoder.objectToBytes(attestationPayload);
+
+  const builder = await GeneralJwsBuilder.create(attestationPayloadBytes, signers);
+  return builder.getJws();
+}
+
+/**
+ * Creates the `signature` property in the `authorization` of a `RecordsWrite` message.
+ */
+export async function createSignerSignature(input: {
+  recordId: string,
+  contextId: string,
+  descriptorCid: string,
+  attestation: GeneralJws | undefined,
+  encryption: JweEncryption | undefined,
+  signer: MessageSigner,
+  delegatedGrantId?: string,
+  permissionGrantId?: string,
+  protocolRole?: string
+}): Promise<GeneralJws> {
+  const { recordId, contextId, descriptorCid, attestation, encryption, signer, delegatedGrantId, permissionGrantId, protocolRole } = input;
+
+  const attestationCid = attestation ? await Cid.computeCid(attestation) : undefined;
+  const encryptionCid = encryption ? await Cid.computeCid(encryption) : undefined;
+
+  const signaturePayload: RecordsWriteSignaturePayload = {
+    recordId,
+    descriptorCid,
+    contextId,
+    attestationCid,
+    encryptionCid,
+    delegatedGrantId,
+    permissionGrantId,
+    protocolRole
+  };
+  removeUndefinedProperties(signaturePayload);
+
+  const signaturePayloadBytes = Encoder.objectToBytes(signaturePayload);
+
+  const builder = await GeneralJwsBuilder.create(signaturePayloadBytes, [signer]);
+  const signature = builder.getJws();
+
+  return signature;
+}
+
+/**
+ * Validates the structural integrity of the `attestation` property.
+ * NOTE: Cryptographic verification of attestation signatures is performed in `authenticate()`.
+ */
+export async function validateAttestationIntegrity(message: RecordsWriteMessage): Promise<void> {
+  if (message.attestation === undefined) {
+    return;
+  }
+
+  // TODO: support multiple attesters (https://github.com/enboxorg/enbox/issues/223)
+  if (message.attestation.signatures.length !== 1) {
+    throw new DwnError(
+      DwnErrorCode.RecordsWriteAttestationIntegrityMoreThanOneSignature,
+      `Currently implementation only supports 1 attester, but got ${message.attestation.signatures.length}`
+    );
+  }
+
+  const payloadJson = Jws.decodePlainObjectPayload(message.attestation);
+  const { descriptorCid } = payloadJson;
+
+  // `descriptorCid` validation - ensure that the provided descriptorCid matches the CID of the actual message
+  const expectedDescriptorCid = await Cid.computeCid(message.descriptor);
+  if (descriptorCid !== expectedDescriptorCid) {
+    throw new DwnError(
+      DwnErrorCode.RecordsWriteAttestationIntegrityDescriptorCidMismatch,
+      `descriptorCid ${descriptorCid} does not match expected descriptorCid ${expectedDescriptorCid}`
+    );
+  }
+
+  // check to ensure that no other unexpected properties exist in payload.
+  const propertyCount = Object.keys(payloadJson).length;
+  if (propertyCount > 1) {
+    throw new DwnError(
+      DwnErrorCode.RecordsWriteAttestationIntegrityInvalidPayloadProperty,
+      `Only 'descriptorCid' is allowed in attestation payload, but got ${propertyCount} properties.`
+    );
+  }
+}