@enbox/dwn-sdk-js 0.4.3 → 0.4.5

package/src/utils/encryption.ts

@@ -2,387 +2,317 @@ import type { Jwk } from '@enbox/crypto';
 import type { PublicKeyJwk } from '../types/jose-types.js';
 
 import { concatBytes } from '@noble/ciphers/utils';
+import { AesCtr, AesKw, computeJwkThumbprint, Hkdf, X25519 } from '@enbox/crypto';
+
 import { Encoder } from './encoder.js';
 import { KeyDerivationScheme } from './hd-key.js';
-import { AesGcm, AesKw, ConcatKdf, X25519, XChaCha20Poly1305 } from '@enbox/crypto';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
-/**
- * Content encryption algorithms supported by the DWN.
- * Both are AEAD (Authenticated Encryption with Associated Data) ciphers.
- */
 export enum ContentEncryptionAlgorithm {
-  /** AES-256 in Galois/Counter Mode. NIST-approved, hardware-accelerated. 96-bit nonce. */
-  A256GCM = 'A256GCM',
-  /** XChaCha20-Poly1305. 192-bit nonce (safe to randomize). Constant-time. */
-  XC20P = 'XC20P',
+  A256CTR = 'A256CTR',
 }
 
-/**
- * Key agreement algorithm used by the DWN.
- * ECDH-ES with X25519 key agreement and AES-256 Key Wrap.
- */
 export enum KeyAgreementAlgorithm {
-  EcdhEsA256kw = 'ECDH-ES+A256KW',
+  X25519HkdfSha256A256Kw = 'X25519-HKDF-SHA256+A256KW',
 }
 
-/** Size of the AES-GCM authentication tag in bytes. */
-const AES_GCM_TAG_LENGTH_BYTES = 16;
+export const ROLE_AUDIENCE_DERIVATION_SCHEME = 'roleAudience';
 
-/** Size of the Poly1305 authentication tag in bytes. */
-const POLY1305_TAG_LENGTH_BYTES = 16;
+const AES_256_KEY_LENGTH_BYTES = 32;
+const AES_CTR_COUNTER_LENGTH_BYTES = 16;
+const AES_CTR_COUNTER_LENGTH_BITS = 128;
+const KEK_INFO_PREFIX = KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
 
-/**
- * JWE Protected Header for DWN encryption.
- */
-export type JweProtectedHeader = {
-  alg: KeyAgreementAlgorithm;
-  enc: ContentEncryptionAlgorithm;
+export type ProtocolPathKeyEncryption = {
+  algorithm: KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
+  keyId: string;
+  derivationScheme: KeyDerivationScheme.ProtocolPath;
+  ephemeralPublicKey: PublicKeyJwk;
+  encryptedKey: string;
 };
 
-/**
- * Per-recipient header in a JWE General JSON Serialization.
- */
-export type JweRecipientHeader = {
-  /** Fully qualified key ID of the root key used in key derivation (e.g. did:example:alice#enc). */
-  kid: string;
-  /** Ephemeral X25519 public key used for ECDH key agreement. */
-  epk: PublicKeyJwk;
-  /** Key derivation scheme used to derive the recipient's key. */
-  derivationScheme: KeyDerivationScheme;
-  /** Derived public key. Present when derivationScheme is 'protocolContext'. */
-  derivedPublicKey?: PublicKeyJwk;
+export type RoleAudienceKeyEncryption = {
+  algorithm: KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
+  keyId: string;
+  derivationScheme: typeof ROLE_AUDIENCE_DERIVATION_SCHEME;
+  protocol: string;
+  role: string;
+  epoch: number;
+  ephemeralPublicKey: PublicKeyJwk;
+  encryptedKey: string;
 };
 
-/**
- * A single recipient entry in the JWE General JSON Serialization.
- */
-export type JweRecipient = {
-  header: JweRecipientHeader;
-  encrypted_key: string;
+export type KeyEncryption = ProtocolPathKeyEncryption | RoleAudienceKeyEncryption;
+
+export type DwnEncryption = {
+  algorithm: ContentEncryptionAlgorithm.A256CTR;
+  initializationVector: string;
+  keyEncryption: KeyEncryption[];
 };
 
-/**
- * JWE-inspired structure used as the `encryption` property on RecordsWrite messages.
- *
- * This follows the JWE General JSON Serialization (RFC 7516 Section 7.2) with one adaptation:
- * the `ciphertext` is NOT included here because the encrypted record data is stored separately
- * in the DataStore (or as inline `encodedData`). Only the key wrapping metadata, IV, and
- * authentication tag are stored in this structure.
- */
-export type JweEncryption = {
-  /** Base64url-encoded JWE Protected Header. */
-  protected: string;
-  /** Base64url-encoded initialization vector for content encryption. */
-  iv: string;
-  /** Base64url-encoded authentication tag from the AEAD cipher. */
-  tag: string;
-  /** Array of recipient entries, one per recipient or derivation path. */
-  recipients: JweRecipient[];
+export type ProtocolPathKeyEncryptionInput = {
+  keyId: string;
+  publicKey: PublicKeyJwk;
+  derivationScheme: KeyDerivationScheme.ProtocolPath;
 };
 
-/**
- * Input describing how to encrypt a key for a single recipient.
- */
-export type KeyEncryptionInput = {
-  /** Fully qualified key ID of the recipient's root encryption key. */
-  publicKeyId: string;
-  /** The recipient's derived X25519 public key. */
+export type RoleAudienceKeyEncryptionInput = {
+  keyId: string;
   publicKey: PublicKeyJwk;
-  /** Key derivation scheme. */
-  derivationScheme: KeyDerivationScheme;
-  /** Algorithm for key agreement. Defaults to ECDH-ES+A256KW. */
-  algorithm?: KeyAgreementAlgorithm;
+  derivationScheme: typeof ROLE_AUDIENCE_DERIVATION_SCHEME;
+  protocol: string;
+  role: string;
+  epoch: number;
 };
 
-/**
- * Input describing how to encrypt record data.
- */
+export type KeyEncryptionInput = ProtocolPathKeyEncryptionInput | RoleAudienceKeyEncryptionInput;
+
 export type EncryptionInput = {
-  /** Content encryption algorithm. Defaults to A256GCM. */
   algorithm?: ContentEncryptionAlgorithm;
-  /** The Content Encryption Key (CEK). Must be 32 bytes (256-bit). */
   key: Uint8Array;
-  /** Initialization vector. 12 bytes for A256GCM, 24 bytes for XC20P. */
   initializationVector: Uint8Array;
-  /** Authentication tag from the AEAD encryption of the record data. */
-  authenticationTag: Uint8Array;
-  /** Recipient key encryption inputs. */
   keyEncryptionInputs: KeyEncryptionInput[];
 };
 
-/**
- * Payload passed to a KeyDecrypter callback for JWE-based key unwrapping.
- */
-export type JweKeyUnwrapPayload = {
-  /** The wrapped CEK bytes. */
+export type KeyUnwrapPayload = {
   encryptedKey: Uint8Array;
-  /** The ephemeral X25519 public key used for ECDH. */
   ephemeralPublicKey: PublicKeyJwk;
+  keyEncryption: KeyEncryption;
 };
 
-/**
- * Utility class for DWN encryption operations using JWE (RFC 7516).
- * Uses ECDH-ES+A256KW key agreement with X25519 and either AES-256-GCM or XChaCha20-Poly1305
- * for authenticated content encryption.
- */
 export class Encryption {
-
-  /**
-   * Encrypts data using an AEAD cipher (A256GCM or XC20P).
-   * Returns ciphertext with the authentication tag appended.
-   */
-  public static async aeadEncrypt(
+  public static async encrypt(
     algorithm: ContentEncryptionAlgorithm,
     keyBytes: Uint8Array,
-    iv: Uint8Array,
+    initializationVector: Uint8Array,
     plaintext: Uint8Array,
-  ): Promise<{ ciphertext: Uint8Array; tag: Uint8Array }> {
-    if (algorithm === ContentEncryptionAlgorithm.A256GCM) {
-      const keyJwk: Jwk = { kty: 'oct', k: Encoder.bytesToBase64Url(keyBytes), alg: 'A256GCM' };
-      // Web Crypto AES-GCM returns ciphertext || tag
-      const combined = await AesGcm.encrypt({ data: plaintext, iv, key: keyJwk });
-      const ciphertext = combined.slice(0, combined.length - AES_GCM_TAG_LENGTH_BYTES);
-      const tag = combined.slice(combined.length - AES_GCM_TAG_LENGTH_BYTES);
-      return { ciphertext, tag };
-
-    } else if (algorithm === ContentEncryptionAlgorithm.XC20P) {
-      // @noble/ciphers XChaCha20-Poly1305 returns ciphertext || tag
-      const combined = await XChaCha20Poly1305.encryptRaw({ data: plaintext, keyBytes, nonce: iv });
-      const ciphertext = combined.slice(0, combined.length - POLY1305_TAG_LENGTH_BYTES);
-      const tag = combined.slice(combined.length - POLY1305_TAG_LENGTH_BYTES);
-      return { ciphertext, tag };
-
-    } else {
-      throw new Error(`Unsupported content encryption algorithm: ${algorithm as string}`);
-    }
+  ): Promise<Uint8Array> {
+    Encryption.validateContentEncryptionParameters(algorithm, keyBytes, initializationVector);
+    return AesCtr.encrypt({
+      counter : initializationVector,
+      data    : plaintext,
+      key     : Encryption.toA256CtrJwk(keyBytes),
+      length  : AES_CTR_COUNTER_LENGTH_BITS,
+    });
   }
 
-  /**
-   * Decrypts data using an AEAD cipher (A256GCM or XC20P).
-   * Expects ciphertext and tag as separate inputs.
-   */
-  public static async aeadDecrypt(
+  public static async decrypt(
     algorithm: ContentEncryptionAlgorithm,
     keyBytes: Uint8Array,
-    iv: Uint8Array,
+    initializationVector: Uint8Array,
     ciphertext: Uint8Array,
-    tag: Uint8Array,
   ): Promise<Uint8Array> {
-    // Both Web Crypto (AES-GCM) and @noble/ciphers (XChaCha20-Poly1305) expect ciphertext || tag
-    const combined = concatBytes(ciphertext, tag);
-
-    if (algorithm === ContentEncryptionAlgorithm.A256GCM) {
-      const keyJwk: Jwk = { kty: 'oct', k: Encoder.bytesToBase64Url(keyBytes), alg: 'A256GCM' };
-      return AesGcm.decrypt({ data: combined, iv, key: keyJwk });
-
-    } else if (algorithm === ContentEncryptionAlgorithm.XC20P) {
-      return XChaCha20Poly1305.decryptRaw({ data: combined, keyBytes, nonce: iv });
-
-    } else {
-      throw new Error(`Unsupported content encryption algorithm: ${algorithm as string}`);
-    }
+    Encryption.validateContentEncryptionParameters(algorithm, keyBytes, initializationVector);
+    return AesCtr.decrypt({
+      counter : initializationVector,
+      data    : ciphertext,
+      key     : Encryption.toA256CtrJwk(keyBytes),
+      length  : AES_CTR_COUNTER_LENGTH_BITS,
+    });
   }
 
-  /**
-   * Encrypts data as a ReadableStream using an AEAD cipher.
-   * Collects all chunks, encrypts, and returns a new stream of ciphertext || tag.
-   * The iv and tag are NOT embedded in the stream — they are stored in the JWE structure.
-   */
-  public static async aeadEncryptStream(
+  public static async encryptStream(
     algorithm: ContentEncryptionAlgorithm,
     keyBytes: Uint8Array,
-    iv: Uint8Array,
+    initializationVector: Uint8Array,
     plaintextStream: ReadableStream<Uint8Array>,
-  ): Promise<{ ciphertextStream: ReadableStream<Uint8Array>; tag: Uint8Array }> {
+  ): Promise<ReadableStream<Uint8Array>> {
     const plaintext = await Encryption.readStream(plaintextStream);
-    const { ciphertext, tag } = await Encryption.aeadEncrypt(algorithm, keyBytes, iv, plaintext);
-    const ciphertextStream = new ReadableStream<Uint8Array>({
-      start(controller): void {
-        controller.enqueue(ciphertext);
-        controller.close();
-      }
-    });
-    return { ciphertextStream, tag };
+    const ciphertext = await Encryption.encrypt(algorithm, keyBytes, initializationVector, plaintext);
+    return Encryption.toStream(ciphertext);
   }
 
-  /**
-   * Decrypts a ciphertext stream using an AEAD cipher.
-   * Returns a ReadableStream of plaintext.
-   */
-  public static async aeadDecryptStream(
+  public static async decryptStream(
     algorithm: ContentEncryptionAlgorithm,
     keyBytes: Uint8Array,
-    iv: Uint8Array,
+    initializationVector: Uint8Array,
     ciphertextStream: ReadableStream<Uint8Array>,
-    tag: Uint8Array,
   ): Promise<ReadableStream<Uint8Array>> {
     const ciphertext = await Encryption.readStream(ciphertextStream);
-    const plaintext = await Encryption.aeadDecrypt(algorithm, keyBytes, iv, ciphertext, tag);
-    return new ReadableStream<Uint8Array>({
-      start(controller): void {
-        controller.enqueue(plaintext);
-        controller.close();
-      }
-    });
+    const plaintext = await Encryption.decrypt(algorithm, keyBytes, initializationVector, ciphertext);
+    return Encryption.toStream(plaintext);
   }
 
-  /**
-   * Performs ECDH-ES key agreement with X25519 and wraps the CEK using AES-256 Key Wrap.
-   *
-   * @param ephemeralPrivateKey - Ephemeral X25519 private key (JWK).
-   * @param recipientPublicKey - Recipient's X25519 public key (JWK).
-   * @param cek - The Content Encryption Key to wrap.
-   * @returns The wrapped CEK bytes.
-   */
-  public static async ecdhEsWrapKey(
-    ephemeralPrivateKey: Jwk,
-    recipientPublicKey: Jwk,
+  public static async wrapKey(
+    recipientPublicKey: PublicKeyJwk,
     cek: Uint8Array,
-  ): Promise<Uint8Array> {
-    // 1. ECDH shared secret
-    const sharedSecret = await X25519.sharedSecret({
-      privateKeyA : ephemeralPrivateKey,
-      publicKeyB  : recipientPublicKey,
-    });
+    keyInput: KeyEncryptionInput,
+    ephemeralPrivateKey?: Jwk,
+  ): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
+    Encryption.validateContentEncryptionKey(cek);
 
-    // 2. Derive KEK via Concat KDF (RFC 7518 Section 4.6.2)
-    const kek = await ConcatKdf.deriveKey({
-      sharedSecret,
-      keyDataLen : 256,
-      fixedInfo  : {
-        algorithmId : 'A256KW',
-        partyUInfo  : '',
-        partyVInfo  : '',
-        suppPubInfo : 256,
-      },
+    const privateKey = ephemeralPrivateKey ?? await X25519.generateKey();
+    const publicKey = await X25519.getPublicKey({ key: privateKey }) as PublicKeyJwk;
+    const sharedSecret = await X25519.sharedSecret({
+      privateKeyA : privateKey,
+      publicKeyB  : recipientPublicKey as Jwk,
     });
+    const kek = await Encryption.deriveKek(sharedSecret, keyInput);
+    const cekJwk = Encryption.toA256CtrJwk(cek);
+    const kekJwk: Jwk = { alg: 'A256KW', k: Encoder.bytesToBase64Url(kek), kty: 'oct' };
+    const encryptedKey = await AesKw.wrapKey({ encryptionKey: kekJwk, unwrappedKey: cekJwk });
 
-    // 3. AES-256 Key Wrap
-    const cekJwk: Jwk = { kty: 'oct', k: Encoder.bytesToBase64Url(cek), alg: 'A256GCM' };
-    const kekJwk: Jwk = { kty: 'oct', k: Encoder.bytesToBase64Url(kek), alg: 'A256KW' };
-    const wrappedKey = await AesKw.wrapKey({ unwrappedKey: cekJwk, encryptionKey: kekJwk });
-
-    return wrappedKey;
+    return { encryptedKey, ephemeralPublicKey: publicKey };
   }
 
-  /**
-   * Performs ECDH-ES key agreement with X25519 and unwraps the CEK using AES-256 Key Unwrap.
-   *
-   * @param recipientPrivateKey - Recipient's X25519 private key (JWK).
-   * @param ephemeralPublicKey - Ephemeral X25519 public key from the JWE recipient header (JWK).
-   * @param wrappedKey - The wrapped CEK bytes.
-   * @returns The unwrapped CEK bytes.
-   */
-  public static async ecdhEsUnwrapKey(
+  public static async unwrapKey(
     recipientPrivateKey: Jwk,
-    ephemeralPublicKey: Jwk,
-    wrappedKey: Uint8Array,
+    keyEncryption: KeyEncryption,
   ): Promise<Uint8Array> {
-    // 1. ECDH shared secret
     const sharedSecret = await X25519.sharedSecret({
       privateKeyA : recipientPrivateKey,
-      publicKeyB  : ephemeralPublicKey,
+      publicKeyB  : keyEncryption.ephemeralPublicKey as Jwk,
     });
-
-    // 2. Derive KEK via Concat KDF
-    const kek = await ConcatKdf.deriveKey({
-      sharedSecret,
-      keyDataLen : 256,
-      fixedInfo  : {
-        algorithmId : 'A256KW',
-        partyUInfo  : '',
-        partyVInfo  : '',
-        suppPubInfo : 256,
-      },
-    });
-
-    // 3. AES-256 Key Unwrap
-    const kekJwk: Jwk = { kty: 'oct', k: Encoder.bytesToBase64Url(kek), alg: 'A256KW' };
+    const kek = await Encryption.deriveKek(sharedSecret, keyEncryption);
+    const kekJwk: Jwk = { alg: 'A256KW', k: Encoder.bytesToBase64Url(kek), kty: 'oct' };
     const unwrappedJwk = await AesKw.unwrapKey({
-      wrappedKeyBytes     : wrappedKey,
-      wrappedKeyAlgorithm : 'A256GCM',
       decryptionKey       : kekJwk,
+      wrappedKeyAlgorithm : ContentEncryptionAlgorithm.A256CTR,
+      wrappedKeyBytes     : Encoder.base64UrlToBytes(keyEncryption.encryptedKey),
     });
 
     return Encoder.base64UrlToBytes(unwrappedJwk.k!);
   }
 
-  /**
-   * Builds a JWE encryption property structure from encryption input.
-   * The ciphertext (encrypted record data) is stored separately in the DataStore,
-   * so only the key wrapping metadata, IV, and authentication tag are included here.
-   *
-   * @param encryptionInput - Describes the CEK, IV, and recipient key encryption inputs.
-   * @param tag - The authentication tag produced by the AEAD cipher during data encryption.
-   */
-  public static async buildJwe(
+  public static async buildEncryptionProperty(
     encryptionInput: EncryptionInput,
-    tag: Uint8Array,
-  ): Promise<JweEncryption> {
-    const enc = encryptionInput.algorithm ?? ContentEncryptionAlgorithm.A256GCM;
-    const protectedHeader: JweProtectedHeader = {
-      alg: KeyAgreementAlgorithm.EcdhEsA256kw,
-      enc,
-    };
-
-    const protectedHeaderBase64url = Encoder.stringToBase64Url(JSON.stringify(protectedHeader));
+  ): Promise<DwnEncryption> {
+    const algorithm = encryptionInput.algorithm ?? ContentEncryptionAlgorithm.A256CTR;
+    Encryption.validateContentEncryptionParameters(algorithm, encryptionInput.key, encryptionInput.initializationVector);
 
-    const recipients: JweRecipient[] = [];
+    const keyEncryption: KeyEncryption[] = [];
     for (const keyInput of encryptionInput.keyEncryptionInputs) {
-      // Generate ephemeral X25519 key pair for each recipient
-      const ephemeralPrivateKey = await X25519.generateKey();
-      const ephemeralPublicKey = await X25519.getPublicKey({ key: ephemeralPrivateKey });
-
-      // Wrap the CEK
-      const wrappedKey = await Encryption.ecdhEsWrapKey(
-        ephemeralPrivateKey,
-        keyInput.publicKey as Jwk,
+      const { encryptedKey, ephemeralPublicKey } = await Encryption.wrapKey(
+        keyInput.publicKey,
         encryptionInput.key,
+        keyInput,
       );
-
-      const recipientHeader: JweRecipientHeader = {
-        kid              : keyInput.publicKeyId,
-        epk              : ephemeralPublicKey as PublicKeyJwk,
-        derivationScheme : keyInput.derivationScheme,
+      const common = {
+        algorithm    : KeyAgreementAlgorithm.X25519HkdfSha256A256Kw,
+        encryptedKey : Encoder.bytesToBase64Url(encryptedKey),
+        ephemeralPublicKey,
+        keyId        : keyInput.keyId,
       };
-
-      // Attach derived public key for protocolContext scheme
-      if (keyInput.derivationScheme === (KeyDerivationScheme.ProtocolContext as KeyDerivationScheme)) {
-        recipientHeader.derivedPublicKey = keyInput.publicKey;
+      if (keyInput.derivationScheme === KeyDerivationScheme.ProtocolPath) {
+        keyEncryption.push({
+          ...common,
+          derivationScheme: KeyDerivationScheme.ProtocolPath,
+        });
+      } else {
+        keyEncryption.push({
+          ...common,
+          derivationScheme : ROLE_AUDIENCE_DERIVATION_SCHEME,
+          epoch            : keyInput.epoch,
+          protocol         : keyInput.protocol,
+          role             : keyInput.role,
+        });
       }
-
-      recipients.push({
-        header        : recipientHeader,
-        encrypted_key : Encoder.bytesToBase64Url(wrappedKey),
-      });
     }
 
     return {
-      protected : protectedHeaderBase64url,
-      iv        : Encoder.bytesToBase64Url(encryptionInput.initializationVector),
-      tag       : Encoder.bytesToBase64Url(tag),
-      recipients,
+      algorithm,
+      initializationVector: Encoder.bytesToBase64Url(encryptionInput.initializationVector),
+      keyEncryption,
     };
   }
 
-  /**
-   * Parses the JWE protected header from its base64url encoding.
-   */
-  public static parseProtectedHeader(protectedBase64url: string): JweProtectedHeader {
-    return Encoder.base64UrlToObject(protectedBase64url) as JweProtectedHeader;
+  public static async getKeyId(publicKeyJwk: PublicKeyJwk): Promise<string> {
+    return computeJwkThumbprint({ jwk: publicKeyJwk });
+  }
+
+  public static validateEncryptionProperty(encryption: DwnEncryption): void {
+    const initializationVector = Encoder.base64UrlToBytes(encryption.initializationVector);
+    if (initializationVector.byteLength !== AES_CTR_COUNTER_LENGTH_BYTES) {
+      throw new DwnError(
+        DwnErrorCode.RecordsWriteValidateIntegrityEncryptionInitializationVectorInvalid,
+        `A256CTR initializationVector must decode to ${AES_CTR_COUNTER_LENGTH_BYTES} bytes.`
+      );
+    }
+
+    for (const entry of encryption.keyEncryption) {
+      if (entry.ephemeralPublicKey.kty !== 'OKP' || entry.ephemeralPublicKey.crv !== 'X25519') {
+        throw new DwnError(
+          DwnErrorCode.RecordsWriteValidateIntegrityEncryptionEphemeralPublicKeyInvalid,
+          'ephemeralPublicKey must be an OKP X25519 public key.'
+        );
+      }
+    }
+  }
+
+  private static async deriveKek(
+    sharedSecret: Uint8Array,
+    keyEncryption: KeyEncryptionInput | KeyEncryption,
+  ): Promise<Uint8Array> {
+    Encryption.validateSharedSecret(sharedSecret);
+    const info = Encryption.getKekInfo(keyEncryption);
+    return Hkdf.deriveKeyBytes({
+      baseKeyBytes : sharedSecret,
+      hash         : 'SHA-256',
+      info,
+      length       : 256,
+      salt         : new Uint8Array(),
+    });
+  }
+
+  private static getKekInfo(keyEncryption: KeyEncryptionInput | KeyEncryption): string {
+    if (keyEncryption.derivationScheme === ROLE_AUDIENCE_DERIVATION_SCHEME) {
+      return `${KEK_INFO_PREFIX}|roleAudience|${keyEncryption.protocol}|${keyEncryption.role}|${keyEncryption.epoch}|${keyEncryption.keyId}`;
+    }
+
+    return `${KEK_INFO_PREFIX}|protocolPath|${keyEncryption.keyId}`;
+  }
+
+  private static validateContentEncryptionParameters(
+    algorithm: ContentEncryptionAlgorithm,
+    keyBytes: Uint8Array,
+    initializationVector: Uint8Array,
+  ): void {
+    if (algorithm !== ContentEncryptionAlgorithm.A256CTR) {
+      throw new Error(`Unsupported content encryption algorithm: ${algorithm as string}`);
+    }
+
+    Encryption.validateContentEncryptionKey(keyBytes);
+
+    if (initializationVector.byteLength !== AES_CTR_COUNTER_LENGTH_BYTES) {
+      throw new Error(`A256CTR initializationVector must be ${AES_CTR_COUNTER_LENGTH_BYTES} bytes.`);
+    }
+  }
+
+  private static validateContentEncryptionKey(keyBytes: Uint8Array): void {
+    if (keyBytes.byteLength !== AES_256_KEY_LENGTH_BYTES) {
+      throw new Error(`A256CTR content encryption key must be ${AES_256_KEY_LENGTH_BYTES} bytes.`);
+    }
+  }
+
+  private static validateSharedSecret(sharedSecret: Uint8Array): void {
+    if (sharedSecret.every((byte): boolean => byte === 0)) {
+      throw new Error('X25519 shared secret MUST NOT be all zeros.');
+    }
+  }
+
+  private static toA256CtrJwk(keyBytes: Uint8Array): Jwk {
+    return { alg: ContentEncryptionAlgorithm.A256CTR, k: Encoder.bytesToBase64Url(keyBytes), kty: 'oct' };
   }
 
-  /**
-   * Reads a ReadableStream to completion and returns all bytes concatenated.
-   */
   private static async readStream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
     const reader = stream.getReader();
     const chunks: Uint8Array[] = [];
     for (;;) {
       const { done, value } = await reader.read();
-      if (done) { break; }
+      if (done) {
+        break;
+      }
       chunks.push(value);
     }
     return concatBytes(...chunks);
   }
+
+  private static toStream(data: Uint8Array): ReadableStream<Uint8Array> {
+    return new ReadableStream<Uint8Array>({
+      start(controller): void {
+        controller.enqueue(data);
+        controller.close();
+      }
+    });
+  }
 }

package/src/utils/hd-key.ts

@@ -6,12 +6,12 @@ import { X25519 } from '@enbox/crypto';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 
 export enum KeyDerivationScheme {
-  ProtocolContext = 'protocolContext',
   ProtocolPath = 'protocolPath',
 }
 
 export type DerivedPrivateJwk = {
   rootKeyId: string,
+  keyId?: string,
   derivationScheme: KeyDerivationScheme;
   derivationPath?: string[];
   derivedPrivateKey: PrivateKeyJwk,

package/src/utils/permission-scope.ts

@@ -16,9 +16,9 @@ export type ProtocolScope = {
  *
  * Matching fails closed for invalid combinations: `protocolPath` and
  * `contextId` are mutually exclusive, and either field requires `protocol`.
- * `protocol` and `protocolPath` match by exact equality. `contextId` scopes
- * match a context subtree: the target context must equal the scoped context or
- * begin with the scoped context followed by `/`.
+ * `protocol` matches by exact equality. `protocolPath` and `contextId` scopes
+ * match subtrees: the target value must equal the scoped value or begin with the
+ * scoped value followed by `/`.
  */
 export class PermissionScopeMatcher {
   /**
@@ -38,7 +38,7 @@ export class PermissionScopeMatcher {
     }
 
     if (scope.protocolPath !== undefined) {
-      return scope.protocolPath === target.protocolPath;
+      return PermissionScopeMatcher.matchesSubtree(scope.protocolPath, target.protocolPath);
     }
 
     if (scope.contextId !== undefined) {
@@ -49,7 +49,11 @@ export class PermissionScopeMatcher {
   }
 
   private static matchesContextId(scopeContextId: string, candidateContextId: unknown): boolean {
-    return typeof candidateContextId === 'string' &&
-      (candidateContextId === scopeContextId || candidateContextId.startsWith(scopeContextId + '/'));
+    return PermissionScopeMatcher.matchesSubtree(scopeContextId, candidateContextId);
+  }
+
+  private static matchesSubtree(scopeValue: string, candidateValue: unknown): boolean {
+    return typeof candidateValue === 'string' &&
+      (candidateValue === scopeValue || candidateValue.startsWith(scopeValue + '/'));
   }
 }