@enbox/dwn-sdk-js 0.4.7 → 0.4.9

package/src/protocols/encryption.ts

@@ -6,14 +6,42 @@ import type { PermissionScope } from '../types/permission-types.js';
 import type { ProtocolDefinition } from '../types/protocols-types.js';
 import type { RecordsWriteMessage } from '../types/records-types.js';
 import type { ValidationStateReader } from '../types/validation-state-reader.js';
+import type { ContentEncryptionAlgorithm, X25519KeyEncryptionBase } from '../utils/encryption.js';
 
+import { DwnConstant } from '../core/dwn-constant.js';
+import { Encoder } from '../utils/encoder.js';
 import { ENCRYPTION_PROTOCOL_URI } from '../core/constants.js';
 import { FilterUtility } from '../utils/filter.js';
 import { Message } from '../core/message.js';
 import { Records } from '../utils/records.js';
+import { validateJsonSchema } from '../schema-validator.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { grantKeyScopeCoversDeliveredScope, isGrantKeyEligibleRecordsScope, isGrantKeyRecordsScope } from '../utils/grant-key-coverage.js';
 
+export const WRAPPED_GRANT_KEY_FORMAT = 'enbox/wrapped-grant-key@1';
+
+export type WrappedGrantKeyEnvelope = {
+  format: typeof WRAPPED_GRANT_KEY_FORMAT;
+  keyEncryption: X25519KeyEncryptionBase;
+  contentEncryption: {
+    algorithm: typeof ContentEncryptionAlgorithm.A256CTR;
+    initializationVector: string;
+  };
+  ciphertext: string;
+};
+
+export function assertWrappedGrantKeyEnvelope(envelope: unknown): asserts envelope is WrappedGrantKeyEnvelope {
+  try {
+    validateJsonSchema('WrappedGrantKeyEnvelope', envelope);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new DwnError(
+      DwnErrorCode.EncryptionProtocolValidateGrantKeyWrappedDeliveryInvalid,
+      `wrapped grantKey envelope is invalid: ${detail}`
+    );
+  }
+}
+
 export class EncryptionProtocol implements CoreProtocol {
   public static readonly uri = ENCRYPTION_PROTOCOL_URI;
   public static readonly grantKeyPath = 'grantKey';
@@ -64,9 +92,9 @@ export class EncryptionProtocol implements CoreProtocol {
     }
   }
 
-  public async validateRecord(message: RecordsWriteMessage, _dataBytes: Uint8Array): Promise<void> {
+  public async validateRecord(message: RecordsWriteMessage, dataBytes: Uint8Array): Promise<void> {
     if (message.descriptor.protocolPath === EncryptionProtocol.grantKeyPath) {
-      EncryptionProtocol.verifyEncryptedDelivery(message);
+      EncryptionProtocol.verifyGrantKeyDelivery(message, dataBytes);
       return;
     }
 
@@ -81,7 +109,7 @@ export class EncryptionProtocol implements CoreProtocol {
     message: RecordsWriteMessage,
     validationStateReader: ValidationStateReader,
   ): Promise<void> {
-    EncryptionProtocol.verifyEncryptedDelivery(message);
+    EncryptionProtocol.verifyInlineWrappedGrantKeyDelivery(message);
 
     const grantId = EncryptionProtocol.getRequiredStringTag(message, 'grantId');
     const protocol = EncryptionProtocol.getRequiredStringTag(message, 'protocol');
@@ -102,11 +130,36 @@ export class EncryptionProtocol implements CoreProtocol {
     });
   }
 
-  private static verifyEncryptedDelivery(message: RecordsWriteMessage): void {
-    if (message.encryption === undefined) {
+  private static verifyInlineWrappedGrantKeyDelivery(message: RecordsWriteMessage): void {
+    if (message.encryption !== undefined) {
+      return;
+    }
+
+    if (message.descriptor.dataSize > DwnConstant.maxDataSizeAllowedToBeEncoded) {
+      throw new DwnError(
+        DwnErrorCode.EncryptionProtocolValidateEncryptedDeliveryMissingEncryption,
+        'plaintext grantKey records must carry an inline wrapped grantKey envelope.'
+      );
+    }
+  }
+
+  private static verifyGrantKeyDelivery(message: RecordsWriteMessage, dataBytes: Uint8Array): void {
+    if (message.encryption !== undefined) {
+      return;
+    }
+
+    try {
+      const envelope = Encoder.bytesToObject(dataBytes);
+      assertWrappedGrantKeyEnvelope(envelope);
+    } catch (error) {
+      if (error instanceof DwnError) {
+        throw error;
+      }
+
+      const detail = error instanceof Error ? error.message : String(error);
       throw new DwnError(
         DwnErrorCode.EncryptionProtocolValidateEncryptedDeliveryMissingEncryption,
-        `${message.descriptor.protocolPath} records must be encrypted.`
+        `${message.descriptor.protocolPath} records must be encrypted or carry a valid wrapped grantKey envelope: ${detail}`
       );
     }
   }

package/src/store/index-level-compound.ts

@@ -1,9 +1,6 @@
+import type { CompoundIndexDefinition, IndexedItem, IndexLevelOptions } from './index-level.js';
 import type { Filter, KeyValues, QueryOptions } from '../types/query-types.js';
-import type { IndexedItem, IndexLevelOptions } from './index-level.js';
-import type { LevelWrapperBatchOperation, LevelWrapperIteratorOptions } from './level-wrapper.js';
-
-import type { CompoundIndexDefinition } from './index-level.js';
-import type { LevelWrapper } from './level-wrapper.js';
+import type { LevelWrapper, LevelWrapperBatchOperation, LevelWrapperIteratorOptions } from './level-wrapper.js';
 
 import { FilterUtility } from '../utils/filter.js';
 import { SortDirection } from '../types/query-types.js';

package/src/store/level-wrapper.ts

@@ -251,8 +251,12 @@ export class LevelWrapper<V> {
     }
 
     // derive an exclusive `maxKey` by changing the last prefix character to the immediate succeeding character in unicode
-    // (which matches how `abstract-level` creates a `boundary`)
-    const maxKey = prefix.slice(0, -1) + String.fromCharCode(prefix.charCodeAt(prefix.length - 1) + 1);
+    // (which matches how `abstract-level` creates a `boundary`).
+    //
+    // This MUST stay UTF-16 code-unit based (`charCodeAt`/`fromCharCode`) to match `abstract-level`'s
+    // boundary semantics: `fromCharCode` wraps at 0xFFFF whereas `fromCodePoint` would emit an astral
+    // surrogate pair, producing a different — and incorrect — key range. NOSONAR (typescript:S7758).
+    const maxKey = prefix.slice(0, -1) + String.fromCharCode(prefix.charCodeAt(prefix.length - 1) + 1); // NOSONAR
     const minKey = prefix;
 
     return [minKey, maxKey];

package/src/types/protocols-types.ts

@@ -237,7 +237,8 @@ type ProtocolRuleSetValue =
   | ProtocolTagsDefinition
   | ProtocolSizeDefinition
   | ProtocolRecordLimitDefinition
-  | ProtocolDeliveryStrategy
+  // `ProtocolDeliveryStrategy` ('direct' | 'subscribe') is intentionally omitted here: its
+  // values are already covered by the `string` member below (see the `$delivery` field typing).
   | boolean
   | string
   | undefined;

package/src/utils/jws.ts

@@ -1,6 +1,5 @@
-import type { GeneralJws } from '../types/jws-types.js';
 import type { MessageSigner } from '../types/signer.js';
-import type { SignatureEntry } from '../types/jws-types.js';
+import type { GeneralJws, SignatureEntry } from '../types/jws-types.js';
 import type { KeyMaterial, PublicKeyJwk } from '../types/jose-types.js';
 
 import { Encoder } from './encoder.js';