@enbox/dwn-sdk-js 0.4.4 → 0.4.6

package/src/interfaces/protocols-configure.ts

@@ -15,7 +15,7 @@ import { Time } from '../utils/time.js';
 import { validateProtocolTagSchemaDefinition } from '../utils/protocol-tags.js';
 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 { getRuleSetAtPath, isCrossProtocolRef, parseCrossProtocolRef } from '../utils/protocols.js';
 import { normalizeProtocolUrl, normalizeSchemaUrl, validateProtocolUrlNormalized, validateSchemaUrlNormalized } from '../utils/url.js';
 import { ProtocolAction, ProtocolActor, ProtocolRecordLimitStrategy } from '../types/protocols-types.js';
 
@@ -150,6 +150,14 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
     // gather all declared record types
     const recordTypes = Object.keys(definition.types);
 
+    const hasEncryptedTypes = Object.values(definition.types).some((type): boolean => type.encryptionRequired === true);
+    if (hasEncryptedTypes && definition.$keyAgreement === undefined) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolsConfigureMissingTopLevelKeyAgreement,
+        `Protocol '${definition.protocol}' declares encrypted types but has no top-level $keyAgreement.`
+      );
+    }
+
     // gather all roles (local roles only — cross-protocol roles are validated by alias existence)
     const roles = ProtocolsConfigure.fetchAllRolePathsRecursively('', definition.structure as ProtocolRuleSet, []);
 
@@ -161,6 +169,7 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       roles,
       uses,
       types               : definition.types,
+      rootStructure       : definition.structure,
     });
   }
 
@@ -207,10 +216,10 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
   private static validateRuleSetRecursively(
     input: {
       ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, recordTypes: string[],
-      roles: string[], uses?: ProtocolUses, types: ProtocolTypes
+      roles: string[], uses?: ProtocolUses, types: ProtocolTypes, rootStructure: { [key: string]: ProtocolRuleSet }
     }
   ): void {
-    const { ruleSet, ruleSetProtocolPath, recordTypes, roles, uses, types } = input;
+    const { ruleSet, ruleSetProtocolPath, recordTypes, roles, uses, types, rootStructure } = 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.
@@ -412,23 +421,40 @@ 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) {
+        if (ruleSet.$keyAgreement === undefined) {
+          throw new DwnError(
+            DwnErrorCode.ProtocolsConfigureMissingEncryptedPathKeyAgreement,
+            `Encrypted protocol path '${ruleSetProtocolPath}' has no $keyAgreement.`
+          );
+        }
+
         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.`
+          throw new DwnError(
+            DwnErrorCode.ProtocolsConfigureInvalidEncryptedAnyoneRead,
+            `Encrypted protocol path '${ruleSetProtocolPath}' allows { who: 'anyone', can: ['read'] }.`
           );
         }
+
+        for (const actionRule of actionRules) {
+          if (actionRule.role === undefined || !actionRule.can.includes(ProtocolAction.Read) || isCrossProtocolRef(actionRule.role)) {
+            continue;
+          }
+
+          const roleRuleSet = getRuleSetAtPath(actionRule.role, rootStructure);
+          if (roleRuleSet?.$keyAgreement === undefined) {
+            throw new DwnError(
+              DwnErrorCode.ProtocolsConfigureInvalidEncryptedRoleMissingKeyAgreement,
+              `Encrypted protocol path '${ruleSetProtocolPath}' references role '${actionRule.role}' with no $keyAgreement.`
+            );
+          }
+        }
       }
     }
 
@@ -490,13 +516,14 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
         roles,
         uses,
         types,
+        rootStructure,
       });
     }
   }
 
   /**
    * Validates that a `$ref` node is a pure attachment point: it must NOT have
-   * `$actions`, `$role`, `$size`, `$tags`, or `$encryption`.
+   * `$actions`, `$role`, `$size`, `$tags`, or `$keyAgreement`.
    * Also validates that the `$ref` alias exists in the `uses` map.
    */
   private static validateRefNode(ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, uses: ProtocolUses | undefined): void {
@@ -519,7 +546,7 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
     }
 
     // validate that `$ref` nodes do not have other directives
-    const forbiddenDirectives = ['$actions', '$role', '$size', '$tags', '$encryption', '$recordLimit', '$immutable', '$delivery', '$squash'] as const;
+    const forbiddenDirectives = ['$actions', '$role', '$size', '$tags', '$keyAgreement', '$encryption', '$recordLimit', '$immutable', '$delivery', '$squash'] as const;
     for (const directive of forbiddenDirectives) {
       if (ruleSet[directive] !== undefined) {
         throw new DwnError(

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

@@ -1,6 +1,6 @@
 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 { DwnEncryption, EncryptionInput } from '../utils/encryption.js';
 import type { RecordsWriteAttestationPayload, RecordsWriteMessage, RecordsWriteSignaturePayload } from '../types/records-types.js';
 
 import { Cid } from '../utils/cid.js';
@@ -11,22 +11,15 @@ import { Jws } from '../utils/jws.js';
 import { removeUndefinedProperties } from '@enbox/common';
 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.
- */
+/** Creates the RecordsWrite `encryption` property if encryption input is given. */
 export async function createEncryptionProperty(
   encryptionInput: EncryptionInput | undefined,
-): Promise<JweEncryption | undefined> {
+): Promise<DwnEncryption | 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;
+  return Encryption.buildEncryptionProperty(encryptionInput);
 }
 
 /**
@@ -52,7 +45,7 @@ export async function createSignerSignature(input: {
   contextId: string,
   descriptorCid: string,
   attestation: GeneralJws | undefined,
-  encryption: JweEncryption | undefined,
+  encryption: DwnEncryption | undefined,
   signer: MessageSigner,
   delegatedGrantId?: string,
   permissionGrantId?: string,

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,