@enbox/dwn-sdk-js 0.0.1

package/src/core/message.ts

@@ -0,0 +1,259 @@
+import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
+import type { GeneralJws } from '../types/jws-types.js';
+import type { Signer } from '../types/signer.js';
+import type { AuthorizationModel, Descriptor, GenericMessage, GenericSignaturePayload } from '../types/message-types.js';
+
+import { Cid } from '../utils/cid.js';
+import { Encoder } from '../utils/encoder.js';
+import { GeneralJwsBuilder } from '../jose/jws/general/builder.js';
+import { Jws } from '../utils/jws.js';
+import { lexicographicalCompare } from '../utils/string.js';
+import { removeUndefinedProperties } from '../utils/object.js';
+import { validateJsonSchema } from '../schema-validator.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+
+/**
+ * A class containing utility methods for working with DWN messages.
+ */
+export class Message {
+
+  /**
+   * Gets the DID of the author of the given message.
+   */
+  public static getAuthor(message: GenericMessage): string | undefined {
+    if (message.authorization === undefined) {
+      return undefined;
+    }
+
+    let author;
+    if (message.authorization.authorDelegatedGrant !== undefined) {
+      author = Message.getSigner(message.authorization.authorDelegatedGrant);
+    } else {
+      author = Message.getSigner(message);
+    }
+
+    return author;
+  }
+
+  /**
+   * Validates the given message against the corresponding JSON schema.
+   * @throws {Error} if fails validation.
+   */
+  public static validateJsonSchema(rawMessage: any): void {
+    const dwnInterface = rawMessage.descriptor.interface;
+    const dwnMethod = rawMessage.descriptor.method;
+    const schemaLookupKey = dwnInterface + dwnMethod;
+
+    // throws an error if message is invalid
+    validateJsonSchema(schemaLookupKey, rawMessage);
+  };
+
+  /**
+   * Gets the DID of the signer of the given message, returns `undefined` if message is not signed.
+   */
+  public static getSigner(message: GenericMessage): string | undefined {
+    if (message.authorization === undefined) {
+      return undefined;
+    }
+
+    const signer = Jws.getSignerDid(message.authorization.signature.signatures[0]);
+    return signer;
+  }
+
+  /**
+   * Gets the CID of the given message.
+   */
+  public static async getCid(message: GenericMessage): Promise<string> {
+    // NOTE: we wrap the `computeCid()` here in case that
+    // the message will contain properties that should not be part of the CID computation
+    // and we need to strip them out (like `encodedData` that we historically had for a long time),
+    // but we can remove this method entirely if the code becomes stable and it is apparent that the wrapper is not needed
+
+    // ^--- seems like we might need to keep this around for now.
+    const rawMessage = { ...message } as any;
+    if (rawMessage.encodedData) {
+      delete rawMessage.encodedData;
+    }
+
+    const cid = await Cid.computeCid(rawMessage as GenericMessage);
+    return cid;
+  }
+
+  /**
+   * Compares message CID in lexicographical order according to the spec.
+   * @returns 1 if `a` is larger than `b`; -1 if `a` is smaller/older than `b`; 0 otherwise (same message)
+   */
+  public static async compareCid(a: GenericMessage, b: GenericMessage): Promise<number> {
+    // the < and > operators compare strings in lexicographical order
+    const cidA = await Message.getCid(a);
+    const cidB = await Message.getCid(b);
+    return lexicographicalCompare(cidA, cidB);
+  }
+
+  /**
+   * Creates the `authorization` property to be included in a DWN message.
+   * @param signer Message signer.
+   * @returns {AuthorizationModel} used as an `authorization` property.
+   */
+  public static async createAuthorization(input: {
+    descriptor: Descriptor,
+    signer: Signer,
+    delegatedGrant?: DataEncodedRecordsWriteMessage,
+    permissionGrantId?: string,
+    protocolRole?: string
+  }): Promise<AuthorizationModel> {
+    const { descriptor, signer, delegatedGrant, permissionGrantId, protocolRole } = input;
+
+    let delegatedGrantId;
+    if (delegatedGrant !== undefined) {
+      delegatedGrantId = await Message.getCid(delegatedGrant);
+    }
+
+    const signature = await Message.createSignature(descriptor, signer, { delegatedGrantId, permissionGrantId, protocolRole });
+
+    const authorization: AuthorizationModel = {
+      signature
+    };
+
+    if (delegatedGrant !== undefined) {
+      authorization.authorDelegatedGrant = delegatedGrant;
+    }
+
+    return authorization;
+  }
+
+  /**
+   * Creates a generic signature from the given DWN message descriptor by including `descriptorCid` as the required property in the signature payload.
+   * NOTE: there is an opportunity to consolidate RecordsWrite.createSignerSignature() wth this method
+   */
+  public static async createSignature(
+    descriptor: Descriptor,
+    signer: Signer,
+    additionalPayloadProperties?: { delegatedGrantId?: string, permissionGrantId?: string, protocolRole?: string }
+  ): Promise<GeneralJws> {
+    const descriptorCid = await Cid.computeCid(descriptor);
+
+    const signaturePayload: GenericSignaturePayload = { descriptorCid, ...additionalPayloadProperties };
+    removeUndefinedProperties(signaturePayload);
+
+    const signaturePayloadBytes = Encoder.objectToBytes(signaturePayload);
+
+    const builder = await GeneralJwsBuilder.create(signaturePayloadBytes, [signer]);
+    const signature = builder.getJws();
+
+    return signature;
+  }
+
+  /**
+   * @returns newest message in the array. `undefined` if given array is empty.
+   */
+  public static async getNewestMessage(messages: GenericMessage[]): Promise<GenericMessage | undefined> {
+    let currentNewestMessage: GenericMessage | undefined = undefined;
+    for (const message of messages) {
+      if (currentNewestMessage === undefined || await Message.isNewer(message, currentNewestMessage)) {
+        currentNewestMessage = message;
+      }
+    }
+
+    return currentNewestMessage;
+  }
+
+  /**
+   * @returns oldest message in the array. `undefined` if given array is empty.
+   */
+  public static async getOldestMessage(messages: GenericMessage[]): Promise<GenericMessage | undefined> {
+    let currentOldestMessage: GenericMessage | undefined = undefined;
+    for (const message of messages) {
+      if (currentOldestMessage === undefined || await Message.isOlder(message, currentOldestMessage)) {
+        currentOldestMessage = message;
+      }
+    }
+
+    return currentOldestMessage;
+  }
+
+  /**
+   * Checks if first message is newer than second message.
+   * @returns `true` if `a` is newer than `b`; `false` otherwise
+   */
+  public static async isNewer(a: GenericMessage, b: GenericMessage): Promise<boolean> {
+    const aIsNewer = (await Message.compareMessageTimestamp(a, b) > 0);
+    return aIsNewer;
+  }
+
+  /**
+   * Checks if first message is older than second message.
+   * @returns `true` if `a` is older than `b`; `false` otherwise
+   */
+  public static async isOlder(a: GenericMessage, b: GenericMessage): Promise<boolean> {
+    const aIsOlder = (await Message.compareMessageTimestamp(a, b) < 0);
+    return aIsOlder;
+  }
+
+  /**
+   * See if the given message is signed by an author-delegate.
+   */
+  public static isSignedByAuthorDelegate(message: GenericMessage): boolean {
+    return message.authorization?.authorDelegatedGrant !== undefined;
+  }
+
+  /**
+   * See if the given message is signed by an owner-delegate.
+   */
+  public static isSignedByOwnerDelegate(message: GenericMessage): boolean {
+    return message.authorization?.ownerDelegatedGrant !== undefined;
+  }
+
+  /**
+   * Compares the `messageTimestamp` of the given messages with a fallback to message CID according to the spec.
+   * @returns 1 if `a` is larger/newer than `b`; -1 if `a` is smaller/older than `b`; 0 otherwise (same age)
+   */
+  public static async compareMessageTimestamp(a: GenericMessage, b: GenericMessage): Promise<number> {
+    if (a.descriptor.messageTimestamp > b.descriptor.messageTimestamp) {
+      return 1;
+    } else if (a.descriptor.messageTimestamp < b.descriptor.messageTimestamp) {
+      return -1;
+    }
+
+    // else `messageTimestamp` is the same between a and b
+    // compare the `dataCid` instead, the < and > operators compare strings in lexicographical order
+    return Message.compareCid(a, b);
+  }
+
+  /**
+   * Validates the structural integrity of the message signature given:
+   * 1. The message signature must contain exactly 1 signature
+   * 2. Passes JSON schema validation
+   * 3. The `descriptorCid` property matches the CID of the message descriptor
+   * NOTE: signature is NOT verified.
+   * @param payloadJsonSchemaKey The key to look up the JSON schema referenced in `compile-validators.js` and perform payload schema validation on.
+   * @returns the parsed JSON payload object if validation succeeds.
+   */
+  public static async validateSignatureStructure(
+    messageSignature: GeneralJws,
+    messageDescriptor: Descriptor,
+    payloadJsonSchemaKey: string = 'GenericSignaturePayload',
+  ): Promise<GenericSignaturePayload> {
+
+    if (messageSignature.signatures.length !== 1) {
+      throw new DwnError(DwnErrorCode.AuthenticationMoreThanOneSignatureNotSupported, 'expected no more than 1 signature for authorization purpose');
+    }
+
+    // validate payload integrity
+    const payloadJson = Jws.decodePlainObjectPayload(messageSignature);
+
+    validateJsonSchema(payloadJsonSchemaKey, payloadJson);
+
+    // `descriptorCid` validation - ensure that the provided descriptorCid matches the CID of the actual message
+    const { descriptorCid } = payloadJson;
+    const expectedDescriptorCid = await Cid.computeCid(messageDescriptor);
+    if (descriptorCid !== expectedDescriptorCid) {
+      throw new DwnError(
+        DwnErrorCode.AuthenticateDescriptorCidMismatch,
+        `provided descriptorCid ${descriptorCid} does not match expected CID ${expectedDescriptorCid}`
+      );
+    }
+
+    return payloadJson;
+  }
+}

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

@@ -0,0 +1,134 @@
+import type { GenericMessage } from '../types/message-types.js';
+import type { MessagesPermissionScope } from '../types/permission-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { PermissionGrant } from '../protocols/permission-grant.js';
+import type { ProtocolsConfigureMessage } from '../types/protocols-types.js';
+import type { DataEncodedRecordsWriteMessage, RecordsDeleteMessage, RecordsWriteMessage } from '../types/records-types.js';
+import type { MessagesQueryMessage, MessagesReadMessage, MessagesSubscribeMessage } from '../types/messages-types.js';
+
+import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
+import { GrantAuthorization } from './grant-authorization.js';
+import { PermissionsProtocol } from '../protocols/permissions.js';
+import { Records } from '../utils/records.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+
+export class MessagesGrantAuthorization {
+
+  /**
+   * Authorizes a MessagesReadMessage using the given permission grant.
+   * @param messageStore Used to check if the given grant has been revoked; and to fetch related RecordsWrites if needed.
+   */
+  public static async authorizeMessagesRead(input: {
+    messagesReadMessage: MessagesReadMessage,
+    messageToRead: GenericMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      messagesReadMessage, messageToRead, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+    } = input;
+
+    await GrantAuthorization.performBaseValidation({
+      incomingMessage: messagesReadMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrant,
+      messageStore
+    });
+
+    const scope = permissionGrant.scope as MessagesPermissionScope;
+    await MessagesGrantAuthorization.verifyScope(expectedGrantor, messageToRead, scope, messageStore);
+  }
+
+  /**
+   * Authorizes the scope of a permission grant for MessagesQuery or MessagesSubscribe.
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  public static async authorizeQueryOrSubscribe(input: {
+    incomingMessage: MessagesQueryMessage | MessagesSubscribeMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      incomingMessage, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+    } = input;
+
+    await GrantAuthorization.performBaseValidation({
+      incomingMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrant,
+      messageStore
+    });
+
+    // if the grant is scoped to a specific protocol, ensure that all of the query filters must include that protocol
+    if (PermissionsProtocol.hasProtocolScope(permissionGrant.scope)) {
+      const scopedProtocol = permissionGrant.scope.protocol;
+      for (const filter of incomingMessage.descriptor.filters) {
+        if (filter.protocol !== scopedProtocol) {
+          throw new DwnError(
+            DwnErrorCode.MessagesGrantAuthorizationMismatchedProtocol,
+            `The protocol ${filter.protocol} does not match the scoped protocol ${scopedProtocol}`
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Verifies the given record against the scope of the given grant.
+   */
+  private static async verifyScope(
+    tenant: string,
+    messageToGet: GenericMessage,
+    incomingScope: MessagesPermissionScope,
+    messageStore: MessageStore,
+  ): Promise<void> {
+    if (incomingScope.protocol === undefined) {
+      // if no protocol is specified in the scope, then the grant is for all records
+      return;
+    }
+
+    if (messageToGet.descriptor.interface === DwnInterfaceName.Records) {
+      // if the message is a Records interface message, get the RecordsWrite message associated with the record
+      const recordsMessage = messageToGet as RecordsWriteMessage | RecordsDeleteMessage;
+      const recordsWriteMessage = Records.isRecordsWrite(recordsMessage) ? recordsMessage :
+        await RecordsWrite.fetchNewestRecordsWrite(messageStore, tenant, recordsMessage.descriptor.recordId);
+
+      if (recordsWriteMessage.descriptor.protocol === incomingScope.protocol) {
+        // the record protocol matches the incoming scope protocol
+        return;
+      }
+
+      // we check if the protocol is the internal PermissionsProtocol for further validation
+      if (recordsWriteMessage.descriptor.protocol === PermissionsProtocol.uri) {
+        // get the permission scope from the permission message
+        const permissionScope = await PermissionsProtocol.getScopeFromPermissionRecord(
+          tenant,
+          messageStore,
+          recordsWriteMessage as DataEncodedRecordsWriteMessage
+        );
+
+        if (PermissionsProtocol.hasProtocolScope(permissionScope) && permissionScope.protocol === incomingScope.protocol) {
+          // the permissions record scoped protocol matches the incoming scope protocol
+          return;
+        }
+      }
+    } else if (messageToGet.descriptor.interface === DwnInterfaceName.Protocols) {
+      // if the message is a protocol message, it must be a `ProtocolConfigure` message
+      const protocolsConfigureMessage = messageToGet as ProtocolsConfigureMessage;
+      const configureProtocol = protocolsConfigureMessage.descriptor.definition.protocol;
+      if (configureProtocol === incomingScope.protocol) {
+        // the configured protocol matches the incoming scope protocol
+        return;
+      }
+    }
+
+    throw new DwnError(DwnErrorCode.MessagesReadVerifyScopeFailed, 'record message failed scope authorization');
+  }
+}