@enbox/dwn-sdk-js 0.0.5 → 0.0.7

package/src/core/record-chain.ts

@@ -0,0 +1,99 @@
+import type { Filter } from '../types/query-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { RecordsWriteMessage } from '../types/records-types.js';
+
+import { RecordsWrite } from '../interfaces/records-write.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+/**
+ * Fetches the initial RecordsWrite message associated with the given (tenant + recordId).
+ */
+export async function fetchInitialWrite(
+  tenant: string,
+  recordId: string,
+  messageStore: MessageStore
+): Promise<RecordsWriteMessage | undefined> {
+
+  const query: Filter = {
+    interface : DwnInterfaceName.Records,
+    method    : DwnMethodName.Write,
+    recordId  : recordId
+  };
+  const { messages } = await messageStore.query(tenant, [query]);
+
+  if (messages.length === 0) {
+    return undefined;
+  }
+
+  const initialWrite = await RecordsWrite.getInitialWrite(messages);
+  return initialWrite;
+}
+
+/**
+ * Constructs the chain of EXISTING records in the datastore where the first record is the root initial `RecordsWrite` of the record chain
+ * and last record is the initial `RecordsWrite` of the descendant record specified.
+ * @param descendantRecordId The ID of the descendent record to start constructing the record chain from by repeatedly looking up the parent.
+ * @returns the record chain where each record is represented by its initial `RecordsWrite`;
+ *          returns empty array if `descendantRecordId` is `undefined`.
+ * @throws {DwnError} if `descendantRecordId` is defined but any initial `RecordsWrite` is not found in the chain of records.
+ */
+export async function constructRecordChain(
+  tenant: string,
+  descendantRecordId: string | undefined,
+  messageStore: MessageStore
+): Promise<RecordsWriteMessage[]> {
+
+  if (descendantRecordId === undefined) {
+    return [];
+  }
+
+  const recordChain: RecordsWriteMessage[] = [];
+
+  // keep walking up the chain from the inbound message's parent, until there is no more parent
+  let currentRecordId: string | undefined = descendantRecordId;
+  while (currentRecordId !== undefined) {
+
+    const initialWrite = await fetchInitialWrite(tenant, currentRecordId, messageStore);
+
+    // RecordsWrite needed should be available since we perform necessary checks at the time of writes,
+    // eg. check the immediate parent in `verifyProtocolPathAndContextId` at the time of writing,
+    // so if this condition is triggered, it means there is an unexpected bug that caused an incomplete chain.
+    // We add additional defensive check here because returning an unexpected/incorrect record chain could lead to security vulnerabilities.
+    if (initialWrite === undefined) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolAuthorizationParentNotFoundConstructingRecordChain,
+        `Unexpected error that should never trigger: no parent found with ID ${currentRecordId} when constructing record chain.`
+      );
+    }
+
+    recordChain.push(initialWrite);
+    currentRecordId = initialWrite.descriptor.parentId;
+  }
+
+  return recordChain.reverse(); // root record first
+}
+
+/**
+ * Determines the timestamp that governs which protocol definition version applies to the given RecordsWrite.
+ * For an update, this is the initial write's `messageTimestamp` (the protocol version is locked at creation time).
+ * For a new initial write, returns `undefined` — the latest protocol definition should be used because the
+ * record is being created now and must conform to the current protocol rules.
+ */
+export async function getGoverningTimestamp(
+  tenant: string,
+  incomingMessage: RecordsWrite,
+  messageStore: MessageStore,
+): Promise<string | undefined> {
+  const existingInitialWrite = await fetchInitialWrite(
+    tenant, incomingMessage.message.recordId, messageStore
+  );
+
+  if (existingInitialWrite !== undefined) {
+    // update case: use the initial write's timestamp
+    return existingInitialWrite.descriptor.messageTimestamp;
+  }
+
+  // initial write case: validate against the latest protocol definition
+  return undefined;
+}

package/src/handlers/records-read.ts

@@ -62,7 +62,7 @@ export class RecordsReadHandler implements MethodHandler {
     const matchedMessage = existingMessages[0];
 
     // if the matched message is a RecordsDelete, we mark the record as not-found and return both the RecordsDelete and the initial RecordsWrite
-    // TODO: https://github.com/enboxorg/enbox/issues/819:
+    // TODO: https://github.com/enboxorg/enbox/issues/222
     // Consider performing authorization checks like when records exists before returning RecordsDelete and initial RecordsWrite of a deleted record
     if (matchedMessage.descriptor.method === DwnMethodName.Delete) {
       const recordsDeleteMessage = matchedMessage as RecordsDeleteMessage;

package/src/handlers/records-write.ts

@@ -215,31 +215,47 @@ export class RecordsWriteHandler implements MethodHandler {
 
   /**
    * Performs additional necessary tasks if the RecordsWrite handled is a core DWN RecordsWrite that need additional processing.
-   * For instance: a Permission revocation RecordsWrite.
+   * For instance: when a Permission revocation is written, all messages authorized by the revoked grant
+   * that were created after the revocation timestamp are deleted from all stores.
    */
   private async postProcessingForCoreRecordsWrite(tenant: string, recordsWrite: RecordsWrite): Promise<void> {
-    // If this message is a Permission revocation, we need to delete all grant-authorized messages with timestamp after revocation
-    // TODO: https://github.com/enboxorg/enbox/issues/716
-    // This code is a direct copy and paste from the original PermissionsRevokeHandler (no longer exists),
-    // but it appears that there was no test for it and it does not look like the code worked:
-    // - not seeing `permissionGrantId` being an index
-    // - not seeing `this.dataStore` being called to delete actual data
-    // - test coverage is missing for the main delete logic
-    if (recordsWrite.message.descriptor.protocol === PermissionsProtocol.uri &&
-      recordsWrite.message.descriptor.protocolPath === PermissionsProtocol.revocationPath) {
-      const permissionGrantId = recordsWrite.message.descriptor.parentId!;
-      const grantAuthorizedMessagesQuery = {
-        permissionGrantId,
-        dateCreated: { gte: recordsWrite.message.descriptor.messageTimestamp },
-      };
-      const { messages: grantAuthorizedMessagesAfterRevoke } = await this.messageStore.query(tenant, [ grantAuthorizedMessagesQuery ]);
-      const grantAuthorizedMessageCidsAfterRevoke: string[] = [];
-      for (const grantAuthorizedMessage of grantAuthorizedMessagesAfterRevoke) {
-        const messageCid = await Message.getCid(grantAuthorizedMessage);
-        await this.messageStore.delete(tenant, messageCid);
+    if (recordsWrite.message.descriptor.protocol !== PermissionsProtocol.uri ||
+      recordsWrite.message.descriptor.protocolPath !== PermissionsProtocol.revocationPath) {
+      return;
+    }
+
+    // Delete all messages authorized by the revoked grant that were created after the revocation.
+    // `permissionGrantId` is indexed via the RecordsWriteDescriptor spread in constructIndexes().
+    const permissionGrantId = recordsWrite.message.descriptor.parentId!;
+    const grantAuthorizedMessagesQuery = {
+      permissionGrantId,
+      dateCreated: { gte: recordsWrite.message.descriptor.messageTimestamp },
+    };
+    const { messages: grantAuthorizedMessages } = await this.messageStore.query(tenant, [grantAuthorizedMessagesQuery]);
+
+    if (grantAuthorizedMessages.length === 0) {
+      return;
+    }
+
+    // Delete data from the data store first to avoid orphaned data blobs in case of crash.
+    // Only RecordsWrite messages with data larger than maxDataSizeAllowedToBeEncoded have data in the data store.
+    for (const message of grantAuthorizedMessages) {
+      if (message.descriptor.method === DwnMethodName.Write) {
+        const recordsWriteMessage = message as RecordsWriteMessage;
+        if (recordsWriteMessage.descriptor.dataSize > DwnConstant.maxDataSizeAllowedToBeEncoded) {
+          await this.dataStore.delete(tenant, recordsWriteMessage.recordId, recordsWriteMessage.descriptor.dataCid);
+        }
       }
-      this.stateIndex.delete(tenant, grantAuthorizedMessageCidsAfterRevoke);
     }
+
+    // Compute CIDs for all messages to delete.
+    const messageCids = await Promise.all(grantAuthorizedMessages.map((message): Promise<string> => Message.getCid(message)));
+
+    // Delete from state index before message store so we don't have orphaned state entries.
+    await this.stateIndex.delete(tenant, messageCids);
+
+    // Finally delete all messages from the message store.
+    await Promise.all(messageCids.map((cid): Promise<void> => this.messageStore.delete(tenant, cid)));
   }
 
   /**

package/src/interfaces/protocols-configure.ts

@@ -1,7 +1,10 @@
 import type { DataEncodedRecordsWriteMessage } from '../types/records-types.js';
 import type { MessageSigner } from '../types/signer.js';
 import type { MessageStore } from '../types/message-store.js';
-import type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureDescriptor, ProtocolsConfigureMessage, ProtocolUses } from '../types/protocols-types.js';
+import type {
+  ProtocolActionRule, ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureDescriptor,
+  ProtocolsConfigureMessage, ProtocolTypes, ProtocolUses
+} from '../types/protocols-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
 import Ajv from 'ajv/dist/2020.js';
@@ -151,7 +154,8 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       ruleSetProtocolPath : '',
       recordTypes,
       roles,
-      uses
+      uses,
+      types               : definition.types,
     });
   }
 
@@ -196,9 +200,12 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
    * Validates the given rule set structure then recursively validates its nested child rule sets.
    */
   private static validateRuleSetRecursively(
-    input: { ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, recordTypes: string[], roles: string[], uses?: ProtocolUses }
+    input: {
+      ruleSet: ProtocolRuleSet, ruleSetProtocolPath: string, recordTypes: string[],
+      roles: string[], uses?: ProtocolUses, types: ProtocolTypes
+    }
   ): void {
-    const { ruleSet, ruleSetProtocolPath, recordTypes, roles, uses } = input;
+    const { ruleSet, ruleSetProtocolPath, recordTypes, roles, uses, types } = 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.
@@ -370,6 +377,26 @@ 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) {
+        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.`
+          );
+        }
+      }
+    }
+
     // Validate nested rule sets
     for (const recordType in ruleSet) {
       if (recordType.startsWith('$')) {
@@ -399,7 +426,8 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
         ruleSetProtocolPath : childRuleSetProtocolPath,
         recordTypes,
         roles,
-        uses
+        uses,
+        types,
       });
     }
   }

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

@@ -0,0 +1,139 @@
+import type { GenericMessage } from '../types/message-types.js';
+import type { MessageStore } from '../types/message-store.js';
+import type { RecordsWrite } from './records-write.js';
+import type { InternalRecordsWriteMessage, RecordsWriteMessage } from '../types/records-types.js';
+
+import { Jws } from '../utils/jws.js';
+import { Message } from '../core/message.js';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+// Late-bound import to avoid circular dependency at module-evaluation time.
+// `RecordsWrite` imports this module; this module needs `RecordsWrite.isInitialWrite` and `.parse`.
+let _RecordsWriteClass: typeof RecordsWrite;
+async function getRecordsWrite(): Promise<typeof RecordsWrite> {
+  if (!_RecordsWriteClass) {
+    const mod = await import('./records-write.js');
+    _RecordsWriteClass = mod.RecordsWrite;
+  }
+  return _RecordsWriteClass;
+}
+
+/**
+ * Gets the initial write from the given list of messages.
+ */
+export async function getInitialWrite(messages: GenericMessage[]): Promise<RecordsWriteMessage> {
+  const RW = await getRecordsWrite();
+  for (const message of messages) {
+    if (await RW.isInitialWrite(message)) {
+      return message as RecordsWriteMessage;
+    }
+  }
+
+  throw new DwnError(DwnErrorCode.RecordsWriteGetInitialWriteNotFound, `Initial write is not found.`);
+}
+
+/**
+ * Verifies that immutable properties of the two given messages are identical.
+ * @throws {DwnError} if immutable properties between two RecordsWrite messages differ.
+ */
+export function verifyEqualityOfImmutableProperties(
+  existingWriteMessage: RecordsWriteMessage, newMessage: RecordsWriteMessage
+): boolean {
+  const mutableDescriptorProperties = ['dataCid', 'dataSize', 'dataFormat', 'datePublished', 'published', 'messageTimestamp', 'tags'];
+
+  // get distinct property names that exist in either the existing message given or new message
+  let descriptorPropertyNames: string[] = [];
+  descriptorPropertyNames.push(...Object.keys(existingWriteMessage.descriptor));
+  descriptorPropertyNames.push(...Object.keys(newMessage.descriptor));
+  descriptorPropertyNames = [...new Set(descriptorPropertyNames)]; // step to remove duplicates
+
+  // ensure all immutable properties are not modified
+  for (const descriptorPropertyName of descriptorPropertyNames) {
+    // if property is supposed to be immutable
+    if (mutableDescriptorProperties.indexOf(descriptorPropertyName) === -1) {
+      const valueInExistingWrite = (existingWriteMessage.descriptor as Record<string, unknown>)[descriptorPropertyName];
+      const valueInNewMessage = (newMessage.descriptor as Record<string, unknown>)[descriptorPropertyName];
+      if (valueInNewMessage !== valueInExistingWrite) {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteImmutablePropertyChanged,
+          `${descriptorPropertyName} is an immutable property: cannot change '${valueInExistingWrite}' to '${valueInNewMessage}'`
+        );
+      }
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Gets the DID of the attesters of the given message.
+ */
+export function getAttesters(message: InternalRecordsWriteMessage): string[] {
+  const attestationSignatures = message.attestation?.signatures ?? [];
+  const attesters = attestationSignatures.map((signature): string => Jws.getSignerDid(signature));
+  return attesters;
+}
+
+/**
+ * Fetches the newest RecordsWrite for a given recordId from the message store.
+ * @throws {DwnError} if no write is found.
+ */
+export async function fetchNewestRecordsWrite(
+  messageStore: MessageStore,
+  tenant: string,
+  recordId: string,
+): Promise<RecordsWriteMessage> {
+  // get existing RecordsWrite messages matching the `recordId`
+  const query = {
+    interface : DwnInterfaceName.Records,
+    method    : DwnMethodName.Write,
+    recordId  : recordId
+  };
+
+  const { messages: existingMessages } = await messageStore.query(tenant, [ query ]);
+  const newestWrite = await Message.getNewestMessage(existingMessages);
+  if (newestWrite !== undefined) {
+    return newestWrite as RecordsWriteMessage;
+  }
+
+  throw new DwnError(DwnErrorCode.RecordsWriteGetNewestWriteRecordNotFound, 'record not found');
+}
+
+/**
+ * Fetches the initial RecordsWrite of a record.
+ * @returns The initial RecordsWrite if found; `undefined` otherwise.
+ */
+export async function fetchInitialRecordsWrite(
+  messageStore: MessageStore,
+  tenant: string,
+  recordId: string
+): Promise<RecordsWrite | undefined> {
+  const initialRecordsWriteMessage = await fetchInitialRecordsWriteMessage(messageStore, tenant, recordId);
+  if (initialRecordsWriteMessage === undefined) {
+    return undefined;
+  }
+
+  const RW = await getRecordsWrite();
+  const initialRecordsWrite = await RW.parse(initialRecordsWriteMessage);
+  return initialRecordsWrite;
+}
+
+/**
+ * Fetches the initial RecordsWrite message of a record.
+ * @returns The initial RecordsWriteMessage if found; `undefined` otherwise.
+ */
+export async function fetchInitialRecordsWriteMessage(
+  messageStore: MessageStore,
+  tenant: string,
+  recordId: string
+): Promise<RecordsWriteMessage | undefined> {
+  const query = { entryId: recordId };
+  const { messages } = await messageStore.query(tenant, [query]);
+
+  if (messages.length === 0) {
+    return undefined;
+  }
+
+  return messages[0] as RecordsWriteMessage;
+}

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

@@ -0,0 +1,143 @@
+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 { RecordsWriteAttestationPayload, RecordsWriteDescriptor, RecordsWriteMessage, RecordsWriteSignaturePayload } from '../types/records-types.js';
+
+import { Cid } from '../utils/cid.js';
+import { Encoder } from '../utils/encoder.js';
+import { Encryption } from '../utils/encryption.js';
+import { GeneralJwsBuilder } from '../jose/jws/general/builder.js';
+import { Jws } from '../utils/jws.js';
+import { KeyDerivationScheme } from '../utils/hd-key.js';
+import { removeUndefinedProperties } from '../utils/object.js';
+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 descriptor Descriptor of the `RecordsWrite` message which contains the information needed by key path derivation schemes.
+ * @param encryptionInput The encryption input containing CEK, IV, authentication tag, and recipient key encryption inputs.
+ */
+export async function createEncryptionProperty(
+  descriptor: RecordsWriteDescriptor,
+  encryptionInput: EncryptionInput | undefined,
+): Promise<JweEncryption | undefined> {
+  if (encryptionInput === undefined) {
+    return undefined;
+  }
+
+  // Validate derivation scheme prerequisites
+  for (const keyEncryptionInput of encryptionInput.keyEncryptionInputs) {
+    if (keyEncryptionInput.derivationScheme === KeyDerivationScheme.ProtocolPath && descriptor.protocol === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteMissingProtocol,
+        '`protocols` encryption scheme cannot be applied to record without the `protocol` property.'
+      );
+    }
+
+    if (keyEncryptionInput.derivationScheme === KeyDerivationScheme.Schemas && descriptor.schema === undefined) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteMissingSchema,
+        '`schemas` encryption scheme cannot be applied to record without the `schema` property.'
+      );
+    }
+  }
+
+  // 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;
+}
+
+/**
+ * Creates the `attestation` property of a RecordsWrite message if given signature inputs; returns `undefined` otherwise.
+ */
+export async function createAttestation(descriptorCid: string, signers?: MessageSigner[]): Promise<GeneralJws | undefined> {
+  if (signers === undefined || signers.length === 0) {
+    return undefined;
+  }
+
+  const attestationPayload: RecordsWriteAttestationPayload = { descriptorCid };
+  const attestationPayloadBytes = Encoder.objectToBytes(attestationPayload);
+
+  const builder = await GeneralJwsBuilder.create(attestationPayloadBytes, signers);
+  return builder.getJws();
+}
+
+/**
+ * Creates the `signature` property in the `authorization` of a `RecordsWrite` message.
+ */
+export async function createSignerSignature(input: {
+  recordId: string,
+  contextId: string | undefined,
+  descriptorCid: string,
+  attestation: GeneralJws | undefined,
+  encryption: JweEncryption | undefined,
+  signer: MessageSigner,
+  delegatedGrantId?: string,
+  permissionGrantId?: string,
+  protocolRole?: string
+}): Promise<GeneralJws> {
+  const { recordId, contextId, descriptorCid, attestation, encryption, signer, delegatedGrantId, permissionGrantId, protocolRole } = input;
+
+  const attestationCid = attestation ? await Cid.computeCid(attestation) : undefined;
+  const encryptionCid = encryption ? await Cid.computeCid(encryption) : undefined;
+
+  const signaturePayload: RecordsWriteSignaturePayload = {
+    recordId,
+    descriptorCid,
+    contextId,
+    attestationCid,
+    encryptionCid,
+    delegatedGrantId,
+    permissionGrantId,
+    protocolRole
+  };
+  removeUndefinedProperties(signaturePayload);
+
+  const signaturePayloadBytes = Encoder.objectToBytes(signaturePayload);
+
+  const builder = await GeneralJwsBuilder.create(signaturePayloadBytes, [signer]);
+  const signature = builder.getJws();
+
+  return signature;
+}
+
+/**
+ * Validates the structural integrity of the `attestation` property.
+ * NOTE: Cryptographic verification of attestation signatures is performed in `authenticate()`.
+ */
+export async function validateAttestationIntegrity(message: RecordsWriteMessage): Promise<void> {
+  if (message.attestation === undefined) {
+    return;
+  }
+
+  // TODO: support multiple attesters (https://github.com/enboxorg/enbox/issues/223)
+  if (message.attestation.signatures.length !== 1) {
+    throw new DwnError(
+      DwnErrorCode.RecordsWriteAttestationIntegrityMoreThanOneSignature,
+      `Currently implementation only supports 1 attester, but got ${message.attestation.signatures.length}`
+    );
+  }
+
+  const payloadJson = Jws.decodePlainObjectPayload(message.attestation);
+  const { descriptorCid } = payloadJson;
+
+  // `descriptorCid` validation - ensure that the provided descriptorCid matches the CID of the actual message
+  const expectedDescriptorCid = await Cid.computeCid(message.descriptor);
+  if (descriptorCid !== expectedDescriptorCid) {
+    throw new DwnError(
+      DwnErrorCode.RecordsWriteAttestationIntegrityDescriptorCidMismatch,
+      `descriptorCid ${descriptorCid} does not match expected descriptorCid ${expectedDescriptorCid}`
+    );
+  }
+
+  // check to ensure that no other unexpected properties exist in payload.
+  const propertyCount = Object.keys(payloadJson).length;
+  if (propertyCount > 1) {
+    throw new DwnError(
+      DwnErrorCode.RecordsWriteAttestationIntegrityInvalidPayloadProperty,
+      `Only 'descriptorCid' is allowed in attestation payload, but got ${propertyCount} properties.`
+    );
+  }
+}