@enbox/dwn-sdk-js 0.4.6 → 0.4.8

package/src/core/message.ts

@@ -49,6 +49,13 @@ export class Message {
     return author;
   }
 
+  /**
+   * Gets the DID whose authority is being exercised by the request.
+   */
+  public static getRequester(message: GenericMessage): string | undefined {
+    return Message.isSignedByAuthorDelegate(message) ? Message.getSigner(message) : Message.getAuthor(message);
+  }
+
   /**
    * Validates the given message against the corresponding JSON schema.
    * @throws {Error} if fails validation.

package/src/core/messages-grant-authorization.ts

@@ -10,11 +10,18 @@ import type { MessagesQueryMessage, MessagesReadMessage, MessagesSubscribeMessag
 import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
 import { EncryptionProtocol } from '../protocols/encryption.js';
 import { GrantAuthorization } from './grant-authorization.js';
+import { Jws } from '../utils/jws.js';
+import { Message } from './message.js';
 import { PermissionScopeMatcher } from '../utils/permission-scope.js';
 import { PermissionsProtocol } from '../protocols/permissions.js';
 import { Records } from '../utils/records.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 
+export type MessagesQueryOrSubscribeGrantSet = {
+  permissionGrants: PermissionGrant[];
+  requester: string;
+};
+
 export class MessagesGrantAuthorization {
 
   public static async fetchPermissionGrants(
@@ -53,7 +60,12 @@ export class MessagesGrantAuthorization {
 
     for (const permissionGrant of permissionGrants) {
       const scope = permissionGrant.scope as MessagesPermissionScope;
-      if (await MessagesGrantAuthorization.isScopeAuthorized(expectedGrantor, messageToRead, scope, validationStateReader)) {
+      if (await MessagesGrantAuthorization.isScopeAuthorized({
+        tenant                : expectedGrantor,
+        messageToGet          : messageToRead,
+        incomingScope         : scope,
+        validationStateReader : validationStateReader,
+      })) {
         return;
       }
     }
@@ -89,6 +101,36 @@ export class MessagesGrantAuthorization {
     MessagesGrantAuthorization.authorizeFilterScope(incomingMessage, scopes);
   }
 
+  public static async authorizeQueryOrSubscribeInvocation(input: {
+    tenant: string;
+    incomingMessage: MessagesQueryMessage | MessagesSubscribeMessage;
+    validationStateReader: ValidationStateReader;
+    failureCode: DwnErrorCode;
+  }): Promise<MessagesQueryOrSubscribeGrantSet | undefined> {
+    const {
+      tenant, incomingMessage, validationStateReader, failureCode
+    } = input;
+    const requester = Message.getRequester(incomingMessage);
+    if (Message.getAuthor(incomingMessage) === tenant && requester === tenant) {
+      return undefined;
+    }
+
+    const permissionGrantIds = Message.getPermissionGrantIds(Jws.decodePlainObjectPayload(incomingMessage.authorization.signature));
+    if (requester !== undefined && permissionGrantIds.length > 0) {
+      const permissionGrants = await MessagesGrantAuthorization.fetchPermissionGrants(tenant, validationStateReader, permissionGrantIds);
+      await MessagesGrantAuthorization.authorizeQueryOrSubscribe({
+        incomingMessage       : incomingMessage,
+        expectedGrantor       : tenant,
+        expectedGrantee       : requester,
+        permissionGrants      : permissionGrants,
+        validationStateReader : validationStateReader,
+      });
+      return { permissionGrants, requester };
+    }
+
+    throw new DwnError(failureCode, 'message failed authorization');
+  }
+
   private static authorizeFilterScope(
     messagesMessage: MessagesQueryMessage | MessagesSubscribeMessage,
     scopes: MessagesPermissionScope[]
@@ -192,15 +234,16 @@ export class MessagesGrantAuthorization {
    * Determines whether the given record is inside a grant scope.
    */
   private static async isScopeAuthorized(
-    tenant: string,
-    messageToGet: GenericMessage,
-    incomingScope: MessagesPermissionScope,
-    validationStateReader: ValidationStateReader,
+    input: {
+      tenant: string;
+      messageToGet: GenericMessage;
+      incomingScope: MessagesPermissionScope;
+      validationStateReader: ValidationStateReader;
+    },
   ): Promise<boolean> {
-    if (incomingScope.protocol === undefined) {
-      return true;
-    }
-
+    const {
+      tenant, messageToGet, incomingScope, validationStateReader
+    } = input;
     if (messageToGet.descriptor.interface === DwnInterfaceName.Records) {
       return MessagesGrantAuthorization.isRecordsMessageScopeAuthorized(
         tenant,
@@ -210,6 +253,10 @@ export class MessagesGrantAuthorization {
       );
     }
 
+    if (incomingScope.protocol === undefined) {
+      return true;
+    }
+
     if (messageToGet.descriptor.interface === DwnInterfaceName.Protocols) {
       return MessagesGrantAuthorization.isProtocolsConfigureScopeAuthorized(
         messageToGet as ProtocolsConfigureMessage,
@@ -232,6 +279,10 @@ export class MessagesGrantAuthorization {
       validationStateReader
     );
 
+    if (incomingScope.protocol === undefined) {
+      return true;
+    }
+
     if (recordsWriteMessage.descriptor.protocol === PermissionsProtocol.uri) {
       return MessagesGrantAuthorization.isPermissionRecordScopeAuthorized(
         tenant,

package/src/core/protocol-authorization-action.ts

@@ -10,7 +10,7 @@ import type { ProtocolActionRule, ProtocolDefinition, ProtocolRuleSet } from '..
 import { DwnMethodName } from '../enums/dwn-interface-method.js';
 import { RecordsWrite } from '../interfaces/records-write.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
-import { getRuleSetAtPath, isCrossProtocolRef, parseCrossProtocolRef } from '../utils/protocols.js';
+import { getRoleContextPrefix, getRuleSetAtPath, isCrossProtocolRef, parseCrossProtocolRef } from '../utils/protocols.js';
 import { ProtocolAction, ProtocolActor } from '../types/protocols-types.js';
 
 /**
@@ -80,24 +80,14 @@ export async function verifyInvokedRole(
     }
   }
 
-  const ancestorSegmentCountOfRolePath = roleProtocolPath.split('/').length - 1;
-  if (contextId === undefined && ancestorSegmentCountOfRolePath > 0) {
+  const contextIdPrefix = getRoleContextPrefix(roleProtocolPath, contextId);
+  if (contextIdPrefix === undefined && roleProtocolPath.includes('/')) {
     throw new DwnError(
       DwnErrorCode.ProtocolAuthorizationMissingContextId,
       'Could not verify role because contextId is missing.'
     );
   }
 
-  // Compute `contextId` prefix for fetching the invoked role record if the role path is not at the root level.
-  // e.g. if invoked role path is `Thread/Participant`, and the `contextId` of the message is `threadX/messageY/attachmentZ`,
-  // then we need to use the prefix `threadX` for the `contextId`
-  // because the `contextId` of the Participant record would be in the form of be `threadX/participantA`
-  let contextIdPrefix: string | undefined;
-  if (ancestorSegmentCountOfRolePath > 0) {
-    const contextIdSegments = contextId!.split('/'); // NOTE: currently contextId segment count is never shorter than the role path count.
-    contextIdPrefix = contextIdSegments.slice(0, ancestorSegmentCountOfRolePath).join('/');
-  }
-
   // fetch the invoked role record
   const matchingRoleRecordExists = await validationStateReader.hasMatchingRoleRecord({
     tenant,

package/src/core/protocol-authorization-validation.ts

@@ -1,6 +1,6 @@
 import type { RecordsWrite } from '../interfaces/records-write.js';
 import type { RecordsWriteMessage } from '../types/records-types.js';
-import type { RoleAudienceKeyEncryption } from '../utils/encryption.js';
+import type { SourceRoleAudienceKeyEncryption } from '../utils/encryption.js';
 import type { ValidationStateReader } from '../types/validation-state-reader.js';
 import type { ProtocolActionRule, ProtocolDefinition, ProtocolRuleSet, ProtocolType, ProtocolTypes } from '../types/protocols-types.js';
 
@@ -9,9 +9,20 @@ import { Records } from '../utils/records.js';
 import { validateProtocolTags } from '../utils/protocol-tags.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 import { Encryption, ROLE_AUDIENCE_DERIVATION_SCHEME } from '../utils/encryption.js';
-import { getRuleSetAtPath, getTypeName, parseCrossProtocolRef } from '../utils/protocols.js';
+import { getRoleAudienceContextId, getRuleSetAtPath, getTypeName, parseCrossProtocolRef } from '../utils/protocols.js';
 import { ProtocolAction, ProtocolRecordLimitStrategy } from '../types/protocols-types.js';
 
+type ResolvedRoleAudience = {
+  contextId: string;
+  protocol: string;
+  rolePath: string;
+};
+
+type RoleAudienceEntryValidationResult = {
+  hasAudience: boolean;
+  hasEntry: boolean;
+};
+
 /**
  * Verifies the `protocolPath` declared in the given message matches the path of actual record chain.
  * For cross-protocol composition, the parent record may belong to a different protocol (resolved via `$ref` in the composing protocol).
@@ -319,42 +330,73 @@ async function verifyRoleAudienceEncryptionIfNeeded(
       continue;
     }
 
-    const matchingEntry = inboundMessage.encryption!.keyEncryption.find((entry): entry is RoleAudienceKeyEncryption =>
-      entry.derivationScheme === ROLE_AUDIENCE_DERIVATION_SCHEME &&
-      entry.protocol === roleAudience.protocol &&
-      entry.role === roleAudience.role
+    await verifyResolvedRoleAudienceEncryption(tenant, inboundMessage, roleAudience, validationStateReader);
+  }
+}
+
+async function verifyResolvedRoleAudienceEncryption(
+  tenant: string,
+  inboundMessage: RecordsWriteMessage,
+  roleAudience: ResolvedRoleAudience,
+  validationStateReader: ValidationStateReader,
+): Promise<void> {
+  const sourceEntryValidation = await validateSourceRoleAudienceEntry(tenant, roleAudience, inboundMessage, validationStateReader);
+  if (sourceEntryValidation.hasAudience) {
+    return;
+  }
+
+  if (!sourceEntryValidation.hasEntry) {
+    throw new DwnError(
+      DwnErrorCode.ProtocolAuthorizationEncryptionRoleAudienceEntryMissing,
+      `encrypted record is missing a roleAudience keyEncryption entry for role '${roleAudience.rolePath}'`
     );
+  }
 
-    if (matchingEntry === undefined) {
-      throw new DwnError(
-        DwnErrorCode.ProtocolAuthorizationEncryptionRoleAudienceEntryMissing,
-        `encrypted record is missing a roleAudience keyEncryption entry for role '${roleAudience.role}'`
-      );
-    }
+  throw new DwnError(
+    DwnErrorCode.ProtocolAuthorizationEncryptionRoleAudienceMissing,
+    `encrypted record references a missing audience for role '${roleAudience.rolePath}'`
+  );
+}
 
-    const matchingEpochs = await validationStateReader.queryAudienceEpochs({
+async function validateSourceRoleAudienceEntry(
+  tenant: string,
+  roleAudience: ResolvedRoleAudience,
+  inboundMessage: RecordsWriteMessage,
+  validationStateReader: ValidationStateReader,
+): Promise<RoleAudienceEntryValidationResult> {
+  const matchingEntries = inboundMessage.encryption!.keyEncryption.filter((entry): entry is SourceRoleAudienceKeyEncryption =>
+    entry.derivationScheme === ROLE_AUDIENCE_DERIVATION_SCHEME &&
+    entry.protocol === roleAudience.protocol &&
+    'rolePath' in entry &&
+    entry.rolePath === roleAudience.rolePath
+  );
+
+  if (matchingEntries.length === 0) {
+    return { hasAudience: false, hasEntry: false };
+  }
+
+  for (const matchingEntry of matchingEntries) {
+    const matchingAudienceRecords = await validationStateReader.queryAudienceRecords({
       tenant,
       protocol  : roleAudience.protocol,
       contextId : roleAudience.contextId,
-      role      : roleAudience.role,
-      epoch     : matchingEntry.epoch,
+      rolePath  : roleAudience.rolePath,
       keyId     : matchingEntry.keyId,
     });
 
-    if (matchingEpochs.length === 0) {
-      throw new DwnError(
-        DwnErrorCode.ProtocolAuthorizationEncryptionRoleAudienceEpochMissing,
-        `encrypted record references a missing audienceEpoch for role '${roleAudience.role}'`
-      );
+    if (matchingAudienceRecords.length > 0) {
+      return { hasAudience: true, hasEntry: true };
     }
   }
+
+  return { hasAudience: false, hasEntry: true };
 }
 
 function resolveRoleAudience(
   actionRule: ProtocolActionRule,
   inboundMessage: RecordsWriteMessage,
   protocolDefinition: ProtocolDefinition,
-): { protocol: string; role: string; contextId: string } | undefined {
+): ResolvedRoleAudience | undefined {
   const roleRef = actionRule.role;
   if (roleRef === undefined) {
     return undefined;
@@ -364,35 +406,13 @@ function resolveRoleAudience(
   const protocol = parsed === undefined
     ? inboundMessage.descriptor.protocol
     : protocolDefinition.uses?.[parsed.alias];
-  const role = parsed === undefined ? roleRef : parsed.protocolPath;
+  const rolePath = parsed === undefined ? roleRef : parsed.protocolPath;
   if (protocol === undefined) {
     return undefined;
   }
 
-  const contextId = getRoleAudienceContextId(inboundMessage, role);
-  return contextId === undefined ? undefined : { protocol, role, contextId };
-}
-
-function getRoleAudienceContextId(
-  inboundMessage: RecordsWriteMessage,
-  rolePath: string,
-): string | undefined {
-  const parentDepth = rolePath.split('/').length - 1;
-  if (parentDepth === 0) {
-    return '';
-  }
-
-  const contextId = inboundMessage.contextId;
-  if (typeof contextId !== 'string') {
-    return undefined;
-  }
-
-  const contextSegments = contextId.split('/');
-  if (contextSegments.length < parentDepth) {
-    return undefined;
-  }
-
-  return contextSegments.slice(0, parentDepth).join('/');
+  const contextId = getRoleAudienceContextId(rolePath, inboundMessage.contextId);
+  return contextId === undefined ? undefined : { protocol, rolePath, contextId };
 }
 
 /**

package/src/core/protocol-authorization.ts

@@ -8,7 +8,9 @@ import type { RecordsWriteMessage } from '../types/records-types.js';
 import type { ValidationStateReader } from '../types/validation-state-reader.js';
 import type { ProtocolDefinition, ProtocolRuleSet } from '../types/protocols-types.js';
 
+import { EncryptionControl } from './encryption-control.js';
 import { getRuleSetAtPath } from '../utils/protocols.js';
+import { isEncryptionControlPath } from './constants.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 import { ProtocolAction, ProtocolActor } from '../types/protocols-types.js';
 
@@ -35,6 +37,11 @@ export class ProtocolAuthorization {
     incomingMessage: RecordsWrite,
     validationStateReader: ValidationStateReader,
   ): Promise<ProtocolRuleSet> {
+    if (isEncryptionControlPath(incomingMessage.message.descriptor.protocolPath)) {
+      await EncryptionControl.validateReferentialIntegrity(tenant, incomingMessage, validationStateReader);
+      return {};
+    }
+
     const protocolDefinitionTimestamp = incomingMessage.message.descriptor.messageTimestamp;
 
     // fetch the protocol definition active at the incoming message timestamp

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

@@ -88,16 +88,15 @@ export class RecordingValidationStateReader implements ValidationStateReader {
   }
 
   /** @inheritdoc */
-  public async queryAudienceEpochs(input: {
+  public async queryAudienceRecords(input: {
     tenant: string;
     protocol: string;
+    rolePath: string;
     contextId: string;
-    role: string;
-    epoch: number;
     keyId?: string;
   }): Promise<RecordsWriteMessage[]> {
-    this.recordedReads.push({ method: 'queryAudienceEpochs' });
-    return this.inner.queryAudienceEpochs(input);
+    this.recordedReads.push({ method: 'queryAudienceRecords' });
+    return this.inner.queryAudienceRecords(input);
   }
 
   /** @inheritdoc */