@enbox/dwn-sdk-js 0.4.3 → 0.4.5

package/src/core/validation-state-reader.ts

@@ -7,6 +7,7 @@ import type { ValidationStateReader } from '../types/validation-state-reader.js'
 import type { DataEncodedRecordsWriteMessage, RecordsWriteMessage } from '../types/records-types.js';
 import type { ProtocolDefinition, ProtocolsConfigureMessage } from '../types/protocols-types.js';
 
+import { ENCRYPTION_PROTOCOL_URI } from './constants.js';
 import { FilterUtility } from '../utils/filter.js';
 import { PermissionGrant } from '../protocols/permission-grant.js';
 import { PermissionsProtocol } from '../protocols/permissions.js';
@@ -165,6 +166,35 @@ export class StoreValidationStateReader implements ValidationStateReader {
     return matchingMessages as RecordsWriteMessage[];
   }
 
+  /** @inheritdoc */
+  public async queryAudienceEpochs(input: {
+    tenant: string;
+    protocol: string;
+    contextId: string;
+    role: string;
+    epoch: number;
+    keyId?: string;
+  }): Promise<RecordsWriteMessage[]> {
+    const filter: Filter = {
+      interface         : DwnInterfaceName.Records,
+      method            : DwnMethodName.Write,
+      isLatestBaseState : true,
+      protocol          : ENCRYPTION_PROTOCOL_URI,
+      protocolPath      : 'audienceEpoch',
+      'tag.protocol'    : input.protocol,
+      'tag.contextId'   : input.contextId,
+      'tag.role'        : input.role,
+      'tag.epoch'       : input.epoch,
+    };
+
+    if (input.keyId !== undefined) {
+      filter['tag.keyId'] = input.keyId;
+    }
+
+    const { messages } = await this.messageStore.query(input.tenant, [filter]);
+    return messages as RecordsWriteMessage[];
+  }
+
   /** @inheritdoc */
   public async fetchGrant(tenant: string, permissionGrantId: string): Promise<PermissionGrant> {
     const grantQuery = {

package/src/dwn.ts

@@ -41,6 +41,7 @@ import { Cid } from './utils/cid.js';
 import { CoreProtocolRegistry } from './core/core-protocol.js';
 import { DataStream } from './utils/data-stream.js';
 import { DwnConstant } from './core/dwn-constant.js';
+import { EncryptionProtocol } from './protocols/encryption.js';
 import { Message } from './core/message.js';
 import { messageReplyFromError } from './core/message-reply.js';
 import { MessagesQueryHandler } from './handlers/messages-query.js';
@@ -115,6 +116,7 @@ export class Dwn {
 
     // Initialize the core protocol registry with built-in system protocols.
     this._coreProtocols = new CoreProtocolRegistry();
+    this._coreProtocols.register(new EncryptionProtocol());
     this._coreProtocols.register(new PermissionsProtocol());
 
     // The single narrow surface through which validation logic reads state (replay-basis closure).
@@ -426,7 +428,7 @@ export class Dwn {
       RecordsWrite.validateDataIntegrity(message.descriptor.dataCid, message.descriptor.dataSize, dataCid, dataBytes.length);
 
       if (coreProtocol?.validateRecord !== undefined) {
-        coreProtocol.validateRecord(message, dataBytes);
+        await coreProtocol.validateRecord(message, dataBytes);
       }
 
       return;
@@ -492,7 +494,10 @@ export class Dwn {
     reply: { status: { detail?: string } },
   ): Promise<ProtocolDefinition | undefined> {
     const detail = reply.status.detail ?? '';
-    if (!detail.startsWith(`${DwnErrorCode.ProtocolAuthorizationMatchingRoleRecordNotFound}:`)) {
+    if (
+      !detail.startsWith(`${DwnErrorCode.ProtocolAuthorizationMatchingRoleRecordNotFound}:`) &&
+      !detail.startsWith(`${DwnErrorCode.EncryptionProtocolValidateAudienceWriterUnauthorized}:`)
+    ) {
       return undefined;
     }
 
@@ -516,6 +521,14 @@ export class Dwn {
     message: GenericMessage,
   ): ReplicationApplyProtocolDefinitionLookup | undefined {
     if (Dwn.isRecordsWriteMessage(message)) {
+      const taggedProtocol = Dwn.getEncryptionRecordTaggedProtocol(message);
+      if (taggedProtocol !== undefined) {
+        return {
+          protocol         : taggedProtocol,
+          messageTimestamp : message.descriptor.messageTimestamp,
+        };
+      }
+
       return {
         protocol         : message.descriptor.protocol,
         messageTimestamp : message.descriptor.messageTimestamp,
@@ -526,6 +539,15 @@ export class Dwn {
     return protocol === undefined ? undefined : { protocol };
   }
 
+  private static getEncryptionRecordTaggedProtocol(message: RecordsWriteMessage): string | undefined {
+    if (message.descriptor.protocol !== EncryptionProtocol.uri) {
+      return undefined;
+    }
+
+    const protocol = message.descriptor.tags?.protocol;
+    return typeof protocol === 'string' ? protocol : undefined;
+  }
+
   private static getMessageProtocolForReplicationApply(message: GenericMessage): string | undefined {
     const descriptor = message.descriptor as { protocol?: unknown; filter?: { protocol?: unknown } };
     if (typeof descriptor.protocol === 'string') {

package/src/handlers/messages-query.ts

@@ -9,7 +9,6 @@ import { messageReplyFromError } from '../core/message-reply.js';
 import { Messages } from '../utils/messages.js';
 import { MessagesGrantAuthorization } from '../core/messages-grant-authorization.js';
 import { MessagesQuery } from '../interfaces/messages-query.js';
-import { PermissionsProtocol } from '../protocols/permissions.js';
 import { Replication } from '../utils/replication.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
@@ -187,10 +186,12 @@ export class MessagesQueryHandler implements MethodHandler {
       protocols.add(filter.protocol);
     }
 
-    const protocolList = [...protocols];
-    const scopes = protocolList.map(protocol => Replication.protocolDomain(protocol));
-    if (!protocols.has(PermissionsProtocol.uri)) {
-      scopes.push(...protocolList.map(protocol => Replication.permissionDomain(protocol)));
+    const scopes: string[] = [];
+    for (const protocol of protocols) {
+      scopes.push(
+        Replication.protocolDomain(protocol),
+        ...Replication.taggedCoreProtocolDomains(protocol, protocols),
+      );
     }
 
     return scopes;

package/src/handlers/protocols-configure.ts

@@ -15,7 +15,7 @@ import { RecordsWrite } from '../interfaces/records-write.js';
 import { StorageController } from '../store/storage-controller.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
-import { getRuleSetAtPath, parseCrossProtocolRef } from '../utils/protocols.js';
+import { getRuleSetAtPath, getTypeName, parseCrossProtocolRef } from '../utils/protocols.js';
 
 type StoredInitialWriteConfigValidity = 'valid' | 'invalid' | 'unknown';
 
@@ -291,7 +291,12 @@ export class ProtocolsConfigureHandler implements MethodHandler {
     }
 
     // Walk the structure and validate all $ref paths and cross-protocol role references
-    ProtocolsConfigureHandler.validateRefsAndRolesRecursively(definition.structure as ProtocolRuleSet, '', referencedDefinitions);
+    ProtocolsConfigureHandler.validateRefsAndRolesRecursively(
+      definition,
+      definition.structure as ProtocolRuleSet,
+      '',
+      referencedDefinitions,
+    );
   }
 
   /**
@@ -300,6 +305,7 @@ export class ProtocolsConfigureHandler implements MethodHandler {
    * - Cross-protocol `role` references point to valid `$role: true` paths in the referenced protocol
    */
   private static validateRefsAndRolesRecursively(
+    definition: ProtocolDefinition,
     ruleSet: ProtocolRuleSet,
     protocolPath: string,
     referencedDefinitions: Map<string, ProtocolDefinition>
@@ -362,6 +368,8 @@ export class ProtocolsConfigureHandler implements MethodHandler {
 
       // Validate cross-protocol references in $actions (roles and `of` paths)
       const actionRules = childRuleSet.$actions ?? [];
+      const typeName = getTypeName(childProtocolPath);
+      const isEncryptedPath = definition.types[typeName]?.encryptionRequired === true;
       for (const actionRule of actionRules) {
         // Validate cross-protocol role references
         if (actionRule.role !== undefined) {
@@ -385,6 +393,14 @@ export class ProtocolsConfigureHandler implements MethodHandler {
                 `does not point to a valid role ($role: true) in protocol '${refDefinition.protocol}'.`
               );
             }
+
+            if (isEncryptedPath && actionRule.can.includes('read') && roleRuleSet.$keyAgreement === undefined) {
+              throw new DwnError(
+                DwnErrorCode.ProtocolsConfigureInvalidEncryptedRoleMissingKeyAgreement,
+                `encrypted protocol path '${childProtocolPath}' references cross-protocol role '${actionRule.role}' ` +
+                `with no $keyAgreement.`
+              );
+            }
           }
         }
 
@@ -414,7 +430,7 @@ export class ProtocolsConfigureHandler implements MethodHandler {
       }
 
       // Recurse into children
-      ProtocolsConfigureHandler.validateRefsAndRolesRecursively(childRuleSet, childProtocolPath, referencedDefinitions);
+      ProtocolsConfigureHandler.validateRefsAndRolesRecursively(definition, childRuleSet, childProtocolPath, referencedDefinitions);
     }
   }
 }

package/src/handlers/records-write.ts

@@ -244,7 +244,7 @@ export class RecordsWriteHandler implements MethodHandler {
         ? undefined
         : this.deps.coreProtocols?.get(message.descriptor.protocol);
       if (coreProtocol?.validateRecord !== undefined) {
-        coreProtocol.validateRecord(message, dataBytes);
+        await coreProtocol.validateRecord(message, dataBytes);
       }
 
       messageWithOptionalEncodedData = await this.cloneAndAddEncodedData(message, dataBytes);

package/src/index.ts

@@ -10,7 +10,7 @@ export type { RecordedValidationRead } from './core/recording-validation-state-r
 export { RecordingValidationStateReader } from './core/recording-validation-state-reader.js';
 export type { MessagesFilter, MessagesQueryDescriptor, MessagesQueryMessage, MessagesQueryReply, MessagesQueryReplyEntry, MessagesReadMessage, MessagesReadReply, MessagesReadReplyEntry, MessagesReadDescriptor, MessagesSubscribeDescriptor, MessagesSubscribeMessage, MessagesSubscribeReply, MessagesSubscribeMessageOptions } 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, ProtocolDeliveryStrategy, ProtocolPathEncryption, ProtocolsQueryDescriptor, ProtocolRecordLimitDefinition, ProtocolSizeDefinition, ProtocolTagsDefinition, ProtocolTagSchema, ProtocolType, ProtocolUses } from './types/protocols-types.js';
+export type { ProtocolsConfigureDescriptor, ProtocolDefinition, ProtocolTypes, ProtocolRuleSet, ProtocolsQueryFilter, ProtocolsConfigureMessage, ProtocolsQueryMessage, ProtocolsQueryReply, ProtocolActionRule, ProtocolDeliveryStrategy, ProtocolKeyAgreement, 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, 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';
@@ -38,10 +38,19 @@ export { DwnInterfaceName, DwnMethodName } from './enums/dwn-interface-method.js
 export { Encoder } from './utils/encoder.js';
 export { MessagesSubscribe } from './interfaces/messages-subscribe.js';
 export type { MessagesSubscribeOptions } from './interfaces/messages-subscribe.js';
-export { Encryption, ContentEncryptionAlgorithm, KeyAgreementAlgorithm } from './utils/encryption.js';
-export type { JweEncryption, JweRecipient, JweRecipientHeader, JweProtectedHeader, JweKeyUnwrapPayload } from './utils/encryption.js';
+export { Encryption, ContentEncryptionAlgorithm, KeyAgreementAlgorithm, ROLE_AUDIENCE_DERIVATION_SCHEME } from './utils/encryption.js';
+export type {
+  DwnEncryption,
+  KeyEncryption,
+  KeyEncryptionInput,
+  KeyUnwrapPayload,
+  ProtocolPathKeyEncryption,
+  ProtocolPathKeyEncryptionInput,
+  RoleAudienceKeyEncryption,
+  RoleAudienceKeyEncryptionInput,
+} from './utils/encryption.js';
 export { RecordsWrite } from './interfaces/records-write.js';
-export type { EncryptionInput, KeyEncryptionInput, RecordsWriteOptions, CreateFromOptions } from './interfaces/records-write.js';
+export type { EncryptionInput, RecordsWriteOptions, CreateFromOptions } from './interfaces/records-write.js';
 export { executeUnlessAborted } from './utils/abort.js';
 export { Jws } from './utils/jws.js';
 export type { KeyMaterial, PrivateKeyJwk, PublicKeyJwk, Jwk } from './types/jose-types.js';
@@ -57,6 +66,7 @@ export type { MessageInterface } from './types/message-interface.js';
 export { PermissionGrant } from './protocols/permission-grant.js';
 export { PermissionRequest } from './protocols/permission-request.js';
 export { PermissionsProtocol } from './protocols/permissions.js';
+export { EncryptionProtocol } from './protocols/encryption.js';
 export type { PermissionGrantCreateOptions, PermissionRequestCreateOptions, PermissionRevocationCreateOptions } from './protocols/permissions.js';
 export { PermissionScopeMatcher } from './utils/permission-scope.js';
 export type { ProtocolScope } from './utils/permission-scope.js';
@@ -80,7 +90,7 @@ export { Secp256r1 } from './utils/secp256r1.js';
 export type { SupportedCurve } from './jose/algorithms/signing/signature-algorithms.js';
 export type { MessageSigner } from './types/signer.js';
 export { SortDirection } from './types/query-types.js';
-export type { EncryptionKeyDeriver, KeyDecrypter } from './types/encryption-types.js';
+export type { EncryptionKeyDeriver, KeyDecrypter, KeyDecrypterDerivationScheme } from './types/encryption-types.js';
 export { Time } from './utils/time.js';
 export * from './types/permission-types.js';
 export * from './types/records-types.js';

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,