@enbox/dwn-sdk-js 0.4.3 → 0.4.5

package/src/interfaces/records-write.ts

@@ -3,7 +3,6 @@ import type { KeyValues } from '../types/query-types.js';
 import type { MessageInterface } from '../types/message-interface.js';
 import type { MessageSigner } from '../types/signer.js';
 import type { MessageStore } from '../types/message-store.js';
-import type { PublicKeyJwk } from '../types/jose-types.js';
 import type { ValidationStateReader } from '../types/validation-state-reader.js';
 import type {
   DataEncodedRecordsWriteMessage,
@@ -13,10 +12,11 @@ import type {
   RecordsWriteSignaturePayload,
   RecordsWriteTags
 } from '../types/records-types.js';
-import type { EncryptionInput, JweEncryption } from '../utils/encryption.js';
+import type { DwnEncryption, EncryptionInput } from '../utils/encryption.js';
 import type { GenericMessage, GenericSignaturePayload } from '../types/message-types.js';
 
 import { Cid } from '../utils/cid.js';
+import { Encryption } from '../utils/encryption.js';
 import { Jws } from '../utils/jws.js';
 import { Message } from '../core/message.js';
 import { PermissionGrant } from '../protocols/permission-grant.js';
@@ -77,6 +77,11 @@ export type RecordsWriteOptions = {
   delegatedGrant?: DataEncodedRecordsWriteMessage;
 
   attestationSigners?: MessageSigner[];
+
+  /**
+   * Pre-built encryption envelope. Use `encryptionInput` when wrapping a CEK from plaintext/ciphertext inputs.
+   */
+  encryption?: DwnEncryption;
   encryptionInput?: EncryptionInput;
   permissionGrantId?: string;
 
@@ -87,19 +92,14 @@ export type RecordsWriteOptions = {
    */
   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
-   * can encrypt context keys back to the author without querying the
-   * author's DWN.
-   */
-  authorKeyDeliveryPublicKey?: {
-    rootKeyId: string;
-    publicKeyJwk: PublicKeyJwk;
-  };
 };
 
-export type { EncryptionInput, KeyEncryptionInput } from '../utils/encryption.js';
+export type {
+  EncryptionInput,
+  KeyEncryptionInput,
+  ProtocolPathKeyEncryptionInput,
+  RoleAudienceKeyEncryptionInput,
+} from '../utils/encryption.js';
 
 export type CreateFromOptions = {
   recordsWriteMessage: RecordsWriteMessage,
@@ -262,6 +262,9 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     //   - `initialWrite`: the initial RecordsWrite when this message is an update
     const { encodedData: _, initialWrite: __, ...messageToValidate } = message as RecordsWriteMessage & Record<string, unknown>;
     Message.validateJsonSchema(messageToValidate);
+    if (message.encryption !== undefined) {
+      Encryption.validateEncryptionProperty(message.encryption);
+    }
 
     // asynchronous checks that are required by the constructor to initialize members properly
 
@@ -298,23 +301,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
    *                                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) {
-      throw new DwnError(DwnErrorCode.RecordsWriteCreateMissingProtocol, '`protocol` and `protocolPath` are required');
-    }
-
-    if ((options.data === undefined && options.dataCid === undefined) ||
-      (options.data !== undefined && options.dataCid !== undefined)) {
-      throw new DwnError(DwnErrorCode.RecordsWriteCreateDataAndDataCidMutuallyExclusive, 'one and only one parameter between `data` and `dataCid` is required');
-    }
-
-    if ((options.dataCid === undefined && options.dataSize !== undefined) ||
-      (options.dataCid !== undefined && options.dataSize === undefined)) {
-      throw new DwnError(DwnErrorCode.RecordsWriteCreateDataCidAndDataSizeMutuallyInclusive, '`dataCid` and `dataSize` must both be defined or undefined at the same time');
-    }
-
-    if (options.signer === undefined && options.delegatedGrant !== undefined) {
-      throw new DwnError(DwnErrorCode.RecordsWriteCreateMissingSigner, '`signer` must be given when `delegatedGrant` is given');
-    }
+    RecordsWrite.validateCreateOptions(options);
 
     const dataCid = options.dataCid ?? await Cid.computeDagPbCidFromBytes(options.data!);
     const dataSize = options.dataSize ?? options.data!.length;
@@ -362,7 +349,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     const attestation = await createAttestation(descriptorCid, options.attestationSigners);
 
     // `encryption` generation
-    const encryption = await createEncryptionProperty(options.encryptionInput);
+    const encryption = options.encryption ?? await createEncryptionProperty(options.encryptionInput);
 
     const message: InternalRecordsWriteMessage = {
       recordId,
@@ -377,17 +364,43 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
 
     if (options.signer !== undefined) {
       await recordsWrite.sign({
-        signer                     : options.signer,
-        delegatedGrant             : options.delegatedGrant,
+        signer         : options.signer,
+        delegatedGrant : options.delegatedGrant,
         ...permissionGrantInvocation,
-        protocolRole               : options.protocolRole,
-        authorKeyDeliveryPublicKey : options.authorKeyDeliveryPublicKey,
+        protocolRole   : options.protocolRole,
       });
     }
 
     return recordsWrite;
   }
 
+  private static validateCreateOptions(options: RecordsWriteOptions): void {
+    if (options.protocol === undefined || options.protocolPath === undefined) {
+      throw new DwnError(DwnErrorCode.RecordsWriteCreateMissingProtocol, '`protocol` and `protocolPath` are required');
+    }
+
+    if ((options.data === undefined && options.dataCid === undefined) ||
+      (options.data !== undefined && options.dataCid !== undefined)) {
+      throw new DwnError(DwnErrorCode.RecordsWriteCreateDataAndDataCidMutuallyExclusive, 'one and only one parameter between `data` and `dataCid` is required');
+    }
+
+    if ((options.dataCid === undefined && options.dataSize !== undefined) ||
+      (options.dataCid !== undefined && options.dataSize === undefined)) {
+      throw new DwnError(DwnErrorCode.RecordsWriteCreateDataCidAndDataSizeMutuallyInclusive, '`dataCid` and `dataSize` must both be defined or undefined at the same time');
+    }
+
+    if (options.signer === undefined && options.delegatedGrant !== undefined) {
+      throw new DwnError(DwnErrorCode.RecordsWriteCreateMissingSigner, '`signer` must be given when `delegatedGrant` is given');
+    }
+
+    if (options.encryption !== undefined && options.encryptionInput !== undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteCreateEncryptionAndEncryptionInputMutuallyExclusive,
+        '`encryption` and `encryptionInput` cannot both be defined'
+      );
+    }
+  }
+
   private static getRecordIdFromContextId(contextId: string | undefined): string | undefined {
     return contextId?.split('/').filter(segment => segment !== '').pop();
   }
@@ -454,7 +467,9 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       delegatedGrant     : options.delegatedGrant,
       // finally still need signers
       signer             : options.signer,
-      attestationSigners : options.attestationSigners
+      attestationSigners : options.attestationSigners,
+      encryption         : options.encryptionInput === undefined && options.data === undefined ? sourceMessage.encryption : undefined,
+      encryptionInput    : options.encryptionInput,
     };
 
     const recordsWrite = await RecordsWrite.create(createOptions);
@@ -498,51 +513,16 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
   }
 
   /**
-   * Encrypts the symmetric encryption key using the public keys given and attach the resulting `encryption` property to the RecordsWrite.
-   *
-   * @param options.append - When `true`, appends new `recipients` entries to the existing
-   *   `encryption` property instead of replacing it. Requires `this._message.encryption` to
-   *   already exist (i.e., the record must already be encrypted).
+   * Encrypts the symmetric encryption key using the public keys given and attaches the resulting `encryption` property.
    */
   public async encryptSymmetricEncryptionKey(
     encryptionInput: EncryptionInput,
-    options?: { append?: boolean },
   ): Promise<void> {
-    if (options?.append) {
-      if (!this._message.encryption) {
-        throw new DwnError(
-          DwnErrorCode.RecordsWriteMissingEncryption,
-          'Cannot append recipients: record does not have an existing `encryption` property.'
-        );
-      }
-
-      // Build only the new recipients (reuses createEncryptionProperty for ECDH-ES+A256KW logic)
-      const newEncryption = await createEncryptionProperty(encryptionInput);
-      if (newEncryption) {
-        this._message.encryption.recipients.push(...newEncryption.recipients);
-      }
-
-      // In append mode, preserve the author's identity and authorization so
-      // that signAsOwner() can be called afterwards. The author's signature
-      // payload will have a stale encryptionCid (since we just appended new
-      // recipients), but the owner's signature vouches for the
-      // updated state. validateIntegrity() skips the encryptionCid check on
-      // the author's signature when an ownerSignature is present.
-      //
-      // NOTE: An alternative design would deliver the DEK out-of-band via the
-      // key-delivery protocol (as a field on the contextKey record) instead of
-      // mutating the record's encryption property. That avoids the stale
-      // encryptionCid issue entirely but adds complexity to the read path and
-      // 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(encryptionInput);
+    this._message.encryption = await createEncryptionProperty(encryptionInput);
 
-      // Full replacement invalidates the authorization — caller must re-sign.
-      delete this._message.authorization;
-      this._signaturePayload = undefined;
-      this._author = undefined;
-    }
+    delete this._message.authorization;
+    this._signaturePayload = undefined;
+    this._author = undefined;
   }
 
   /**
@@ -553,9 +533,8 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     delegatedGrant?: DataEncodedRecordsWriteMessage,
     permissionGrantId?: string,
     protocolRole?: string,
-    authorKeyDeliveryPublicKey?: { rootKeyId: string; publicKeyJwk: PublicKeyJwk },
   }): Promise<void> {
-    const { signer, delegatedGrant, permissionGrantId, protocolRole, authorKeyDeliveryPublicKey } = options;
+    const { signer, delegatedGrant, permissionGrantId, protocolRole } = options;
 
     // compute delegated grant ID and author if delegated grant is given
     let delegatedGrantId;
@@ -601,10 +580,6 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       this._message.authorization.authorDelegatedGrant = delegatedGrant;
     }
 
-    if (authorKeyDeliveryPublicKey !== undefined) {
-      this._message.authorization.authorKeyDeliveryPublicKey = authorKeyDeliveryPublicKey;
-    }
-
     // there is opportunity to optimize here as the payload is constructed within `createAuthorization(...)`
     this._signaturePayload = Jws.decodePlainObjectPayload(signature);
     this._author = authorDid;
@@ -719,16 +694,24 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
       }
     }
 
-    // If `encryption` is given in message, make sure the correct `encryptionCid`
-    // is in the payload of the message signature — UNLESS the message has an
-    // ownerSignature. When the DWN owner appends recipients to an externally-authored
-    // record before normal admission, the author's encryptionCid becomes stale. The
-    // owner's signature vouches for the updated encryption property, so the mismatch
-    // is expected and safe.
-    const hasOwnerSignature = this.message.authorization?.ownerSignature !== undefined;
-    if (signaturePayload.encryptionCid !== undefined && !hasOwnerSignature) {
+    // if `encryption` is given in message, make sure the correct `encryptionCid` is in the payload of the message signature
+    if (this.message.encryption !== undefined && signaturePayload.encryptionCid === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteValidateIntegrityEncryptionCidMissing,
+        'encryptionCid must be present in the authorization payload when encryption is present in the message'
+      );
+    }
+
+    if (this.message.encryption === undefined && signaturePayload.encryptionCid !== undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteValidateIntegrityEncryptionCidMissing,
+        'encryption must be present in the message when encryptionCid is present in the authorization payload'
+      );
+    }
+
+    if (this.message.encryption !== undefined) {
       const expectedEncryptionCid = await Cid.computeCid(this.message.encryption);
-      const actualEncryptionCid = signaturePayload.encryptionCid;
+      const actualEncryptionCid = signaturePayload.encryptionCid!;
       if (actualEncryptionCid !== expectedEncryptionCid) {
         throw new DwnError(
           DwnErrorCode.RecordsWriteValidateIntegrityEncryptionCidMismatch,
@@ -871,7 +854,7 @@ export class RecordsWrite implements MessageInterface<RecordsWriteMessage> {
     contextId: string,
     descriptorCid: string,
     attestation: GeneralJws | undefined,
-    encryption: JweEncryption | undefined,
+    encryption: DwnEncryption | undefined,
     signer: MessageSigner,
     delegatedGrantId?: string,
     permissionGrantId?: string,