@enbox/dwn-sdk-js 0.4.6 → 0.4.8

package/src/utils/encryption.ts

@@ -1,7 +1,6 @@
 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';
@@ -17,73 +16,128 @@ export enum KeyAgreementAlgorithm {
 }
 
 export const ROLE_AUDIENCE_DERIVATION_SCHEME = 'roleAudience';
+export const SEAL_DERIVATION_SCHEME = 'seal';
 
 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;
 
-export type ProtocolPathKeyEncryption = {
+function concatBytes(...arrays: Uint8Array[]): Uint8Array {
+  const byteLength = arrays.reduce((total, array): number => total + array.byteLength, 0);
+  const result = new Uint8Array(byteLength);
+  let offset = 0;
+
+  for (const array of arrays) {
+    result.set(array, offset);
+    offset += array.byteLength;
+  }
+
+  return result;
+}
+
+export type X25519KeyEncryptionBase = {
   algorithm: KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
   keyId: string;
-  derivationScheme: KeyDerivationScheme.ProtocolPath;
   ephemeralPublicKey: PublicKeyJwk;
   encryptedKey: string;
 };
 
-export type RoleAudienceKeyEncryption = {
-  algorithm: KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
-  keyId: string;
+export type ProtocolPathKeyEncryption = X25519KeyEncryptionBase & {
+  derivationScheme: KeyDerivationScheme.ProtocolPath;
+};
+
+export type SourceRoleAudienceKeyEncryption = X25519KeyEncryptionBase & {
   derivationScheme: typeof ROLE_AUDIENCE_DERIVATION_SCHEME;
   protocol: string;
-  role: string;
-  epoch: number;
-  ephemeralPublicKey: PublicKeyJwk;
-  encryptedKey: string;
+  rolePath: string;
 };
 
-export type KeyEncryption = ProtocolPathKeyEncryption | RoleAudienceKeyEncryption;
+export type X25519KeyEncryption = ProtocolPathKeyEncryption | SourceRoleAudienceKeyEncryption;
 
-export type X25519KeyEncryption = ProtocolPathKeyEncryption | RoleAudienceKeyEncryption;
+export type SealKeyWrap = X25519KeyEncryptionBase & {
+  derivationScheme: typeof SEAL_DERIVATION_SCHEME;
+};
 
 export type DwnEncryption = {
   algorithm: ContentEncryptionAlgorithm.A256CTR;
   initializationVector: string;
-  keyEncryption: KeyEncryption[];
+  keyEncryption: X25519KeyEncryption[];
 };
 
-export type ProtocolPathKeyEncryptionInput = {
+export type X25519KeyEncryptionInputBase = {
+  algorithm: KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
   keyId: string;
   publicKey: PublicKeyJwk;
+};
+
+export type ProtocolPathKeyEncryptionInput = X25519KeyEncryptionInputBase & {
   derivationScheme: KeyDerivationScheme.ProtocolPath;
 };
 
-export type RoleAudienceKeyEncryptionInput = {
-  keyId: string;
-  publicKey: PublicKeyJwk;
+export type SourceRoleAudienceKeyEncryptionInput = X25519KeyEncryptionInputBase & {
   derivationScheme: typeof ROLE_AUDIENCE_DERIVATION_SCHEME;
   protocol: string;
-  role: string;
-  epoch: number;
+  rolePath: string;
 };
 
-export type KeyEncryptionInput = ProtocolPathKeyEncryptionInput | RoleAudienceKeyEncryptionInput;
+export type X25519KeyEncryptionInput = ProtocolPathKeyEncryptionInput | SourceRoleAudienceKeyEncryptionInput;
 
-export type X25519KeyEncryptionInput = ProtocolPathKeyEncryptionInput | RoleAudienceKeyEncryptionInput;
+export type SealKeyWrapInput = X25519KeyEncryptionInputBase & {
+  derivationScheme: typeof SEAL_DERIVATION_SCHEME;
+  protocol: string;
+  rolePath: string;
+  contextId: string;
+  audienceKeyId: string;
+};
 
 export type EncryptionInput = {
   algorithm?: ContentEncryptionAlgorithm;
   key: Uint8Array;
   initializationVector: Uint8Array;
-  keyEncryptionInputs: KeyEncryptionInput[];
+  keyEncryptionInputs: X25519KeyEncryptionInput[];
 };
 
 export type KeyUnwrapPayload = {
   encryptedKey: Uint8Array;
   ephemeralPublicKey: PublicKeyJwk;
-  keyEncryption: KeyEncryption;
+  keyEncryption: X25519KeyEncryption;
+};
+
+export type X25519KeyWrapInput = {
+  cek: Uint8Array;
+  keyInput: X25519KeyEncryptionInput;
+  ephemeralPrivateKey?: Jwk;
+};
+
+export type SealWrapInput = {
+  privateKeyBytes: Uint8Array;
+  keyInput: SealKeyWrapInput;
+  ephemeralPrivateKey?: Jwk;
+};
+
+export type SealUnwrapInput = {
+  seal: SealKeyWrap;
+  recipientPrivateKey: Jwk;
+  protocol: string;
+  rolePath: string;
+  contextId: string;
+  audienceKeyId: string;
 };
 
+type SealKeyUnwrapInfo = SealKeyWrap & {
+  protocol: string;
+  rolePath: string;
+  contextId: string;
+  audienceKeyId: string;
+};
+
+type X25519KekDerivationInput =
+  | X25519KeyEncryptionInput
+  | X25519KeyEncryption
+  | SealKeyWrapInput
+  | SealKeyUnwrapInfo;
+
 export class Encryption {
   public static async encrypt(
     algorithm: ContentEncryptionAlgorithm,
@@ -137,31 +191,54 @@ export class Encryption {
     return Encryption.toStream(plaintext);
   }
 
-  public static async wrapKey(
-    recipientPublicKey: PublicKeyJwk,
-    cek: Uint8Array,
-    keyInput: KeyEncryptionInput,
-    ephemeralPrivateKey?: Jwk,
-  ): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
-    return Encryption.wrapX25519Key(recipientPublicKey, cek, keyInput, ephemeralPrivateKey);
+  public static async wrapKey(input: X25519KeyWrapInput): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
+    if (Encryption.isX25519KeyAgreementAlgorithm(input.keyInput.algorithm)) {
+      return Encryption.wrapX25519Key(input);
+    }
+
+    throw new Error(Encryption.unsupportedKeyAgreementAlgorithmMessage(input.keyInput.algorithm));
   }
 
-  private static async wrapX25519Key(
-    recipientPublicKey: PublicKeyJwk,
-    cek: Uint8Array,
-    keyInput: X25519KeyEncryptionInput,
-    ephemeralPrivateKey?: Jwk,
-  ): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
-    Encryption.validateContentEncryptionKey(cek);
+  public static async wrapSeal(input: SealWrapInput): Promise<SealKeyWrap> {
+    if (!Encryption.isX25519KeyAgreementAlgorithm(input.keyInput.algorithm)) {
+      throw new Error(Encryption.unsupportedKeyAgreementAlgorithmMessage(input.keyInput.algorithm));
+    }
+
+    Encryption.validateContentEncryptionKey(input.privateKeyBytes);
+
+    const privateKey = input.ephemeralPrivateKey ?? await X25519.generateKey();
+    const publicKey = await X25519.getPublicKey({ key: privateKey }) as PublicKeyJwk;
+    const sharedSecret = await X25519.sharedSecret({
+      privateKeyA : privateKey,
+      publicKeyB  : input.keyInput.publicKey as Jwk,
+    });
+    const kek = await Encryption.deriveKek(sharedSecret, input.keyInput);
+    const unwrappedKey = await AesKw.bytesToPrivateKey({ privateKeyBytes: input.privateKeyBytes });
+    const encryptedKey = await AesKw.wrapKey({
+      encryptionKey: Encryption.toA256KwJwk(kek),
+      unwrappedKey,
+    });
 
-    const privateKey = ephemeralPrivateKey ?? await X25519.generateKey();
+    return {
+      algorithm          : input.keyInput.algorithm,
+      derivationScheme   : SEAL_DERIVATION_SCHEME,
+      encryptedKey       : Encoder.bytesToBase64Url(encryptedKey),
+      ephemeralPublicKey : publicKey,
+      keyId              : input.keyInput.keyId,
+    };
+  }
+
+  private static async wrapX25519Key(input: X25519KeyWrapInput): Promise<{ encryptedKey: Uint8Array; ephemeralPublicKey: PublicKeyJwk }> {
+    Encryption.validateContentEncryptionKey(input.cek);
+
+    const privateKey = input.ephemeralPrivateKey ?? await X25519.generateKey();
     const publicKey = await X25519.getPublicKey({ key: privateKey }) as PublicKeyJwk;
     const sharedSecret = await X25519.sharedSecret({
       privateKeyA : privateKey,
-      publicKeyB  : recipientPublicKey as Jwk,
+      publicKeyB  : input.keyInput.publicKey as Jwk,
     });
-    const kek = await Encryption.deriveKek(sharedSecret, keyInput);
-    const cekJwk = Encryption.toA256CtrJwk(cek);
+    const kek = await Encryption.deriveKek(sharedSecret, input.keyInput);
+    const cekJwk = Encryption.toA256CtrJwk(input.cek);
     const kekJwk: Jwk = { alg: 'A256KW', k: Encoder.bytesToBase64Url(kek), kty: 'oct' };
     const encryptedKey = await AesKw.wrapKey({ encryptionKey: kekJwk, unwrappedKey: cekJwk });
 
@@ -170,13 +247,39 @@ export class Encryption {
 
   public static async unwrapKey(
     recipientPrivateKey: Jwk,
-    keyEncryption: KeyEncryption,
+    keyEncryption: X25519KeyEncryption,
   ): Promise<Uint8Array> {
-    if (keyEncryption.algorithm === KeyAgreementAlgorithm.X25519HkdfSha256A256Kw) {
+    if (Encryption.isX25519KeyAgreementAlgorithm(keyEncryption.algorithm)) {
       return Encryption.unwrapX25519Key(recipientPrivateKey, keyEncryption);
     }
 
-    throw new Error(`Unsupported key agreement algorithm: ${(keyEncryption as KeyEncryption).algorithm}`);
+    throw new Error(Encryption.unsupportedKeyAgreementAlgorithmMessage(keyEncryption.algorithm));
+  }
+
+  public static async unwrapSeal(input: SealUnwrapInput): Promise<Uint8Array> {
+    if (!Encryption.isX25519KeyAgreementAlgorithm(input.seal.algorithm)) {
+      throw new Error(Encryption.unsupportedKeyAgreementAlgorithmMessage(input.seal.algorithm));
+    }
+
+    const keyEncryption: SealKeyUnwrapInfo = {
+      ...input.seal,
+      audienceKeyId : input.audienceKeyId,
+      contextId     : input.contextId,
+      protocol      : input.protocol,
+      rolePath      : input.rolePath,
+    };
+    const sharedSecret = await X25519.sharedSecret({
+      privateKeyA : input.recipientPrivateKey,
+      publicKeyB  : input.seal.ephemeralPublicKey as Jwk,
+    });
+    const kek = await Encryption.deriveKek(sharedSecret, keyEncryption);
+    const unwrappedKey = await AesKw.unwrapKey({
+      decryptionKey       : Encryption.toA256KwJwk(kek),
+      wrappedKeyAlgorithm : 'A256KW',
+      wrappedKeyBytes     : Encoder.base64UrlToBytes(input.seal.encryptedKey),
+    });
+
+    return AesKw.privateKeyToBytes({ privateKey: unwrappedKey });
   }
 
   private static async unwrapX25519Key(
@@ -204,7 +307,7 @@ export class Encryption {
     const algorithm = encryptionInput.algorithm ?? ContentEncryptionAlgorithm.A256CTR;
     Encryption.validateContentEncryptionParameters(algorithm, encryptionInput.key, encryptionInput.initializationVector);
 
-    const keyEncryption: KeyEncryption[] = [];
+    const keyEncryption: X25519KeyEncryption[] = [];
     for (const keyInput of encryptionInput.keyEncryptionInputs) {
       keyEncryption.push(await Encryption.buildKeyEncryptionEntry(encryptionInput.key, keyInput));
     }
@@ -236,15 +339,14 @@ export class Encryption {
 
   private static async buildKeyEncryptionEntry(
     cek: Uint8Array,
-    keyInput: KeyEncryptionInput,
-  ): Promise<KeyEncryption> {
-    const { encryptedKey, ephemeralPublicKey } = await Encryption.wrapKey(
-      keyInput.publicKey,
+    keyInput: X25519KeyEncryptionInput,
+  ): Promise<X25519KeyEncryption> {
+    const { encryptedKey, ephemeralPublicKey } = await Encryption.wrapKey({
       cek,
       keyInput,
-    );
+    });
     const common = {
-      algorithm    : KeyAgreementAlgorithm.X25519HkdfSha256A256Kw,
+      algorithm    : keyInput.algorithm,
       encryptedKey : Encoder.bytesToBase64Url(encryptedKey),
       ephemeralPublicKey,
       keyId        : keyInput.keyId,
@@ -260,21 +362,20 @@ export class Encryption {
     return {
       ...common,
       derivationScheme : ROLE_AUDIENCE_DERIVATION_SCHEME,
-      epoch            : keyInput.epoch,
       protocol         : keyInput.protocol,
-      role             : keyInput.role,
+      rolePath         : keyInput.rolePath,
     };
   }
 
-  private static validateKeyEncryptionEntry(entry: KeyEncryption): void {
-    if (entry.algorithm === KeyAgreementAlgorithm.X25519HkdfSha256A256Kw) {
+  private static validateKeyEncryptionEntry(entry: X25519KeyEncryption): void {
+    if (Encryption.isX25519KeyAgreementAlgorithm(entry.algorithm)) {
       Encryption.validateX25519KeyEncryptionEntry(entry);
       return;
     }
 
     throw new DwnError(
       DwnErrorCode.RecordsWriteValidateIntegrityEncryptionEphemeralPublicKeyInvalid,
-      `Unsupported key agreement algorithm: ${(entry as KeyEncryption).algorithm}`
+      Encryption.unsupportedKeyAgreementAlgorithmMessage(entry.algorithm)
     );
   }
 
@@ -289,7 +390,7 @@ export class Encryption {
 
   private static async deriveKek(
     sharedSecret: Uint8Array,
-    keyEncryption: X25519KeyEncryptionInput | X25519KeyEncryption,
+    keyEncryption: X25519KekDerivationInput,
   ): Promise<Uint8Array> {
     Encryption.validateSharedSecret(sharedSecret);
     const info = Encryption.getKekInfo(keyEncryption);
@@ -302,12 +403,29 @@ export class Encryption {
     });
   }
 
-  private static getKekInfo(keyEncryption: X25519KeyEncryptionInput | X25519KeyEncryption): string {
+  private static getKekInfo(keyEncryption: X25519KekDerivationInput): string {
+    if (keyEncryption.derivationScheme === SEAL_DERIVATION_SCHEME) {
+      return JSON.stringify([
+        KEK_INFO_PREFIX,
+        SEAL_DERIVATION_SCHEME,
+        keyEncryption.protocol,
+        keyEncryption.rolePath,
+        keyEncryption.contextId,
+        keyEncryption.audienceKeyId,
+      ]);
+    }
+
     if (keyEncryption.derivationScheme === ROLE_AUDIENCE_DERIVATION_SCHEME) {
-      return `${KEK_INFO_PREFIX}|roleAudience|${keyEncryption.protocol}|${keyEncryption.role}|${keyEncryption.epoch}|${keyEncryption.keyId}`;
+      return JSON.stringify([
+        KEK_INFO_PREFIX,
+        ROLE_AUDIENCE_DERIVATION_SCHEME,
+        keyEncryption.protocol,
+        keyEncryption.rolePath,
+        keyEncryption.keyId,
+      ]);
     }
 
-    return `${KEK_INFO_PREFIX}|protocolPath|${keyEncryption.keyId}`;
+    return JSON.stringify([KEK_INFO_PREFIX, KeyDerivationScheme.ProtocolPath, keyEncryption.keyId]);
   }
 
   private static validateContentEncryptionParameters(
@@ -338,10 +456,22 @@ export class Encryption {
     }
   }
 
+  private static isX25519KeyAgreementAlgorithm(algorithm: unknown): algorithm is KeyAgreementAlgorithm.X25519HkdfSha256A256Kw {
+    return algorithm === KeyAgreementAlgorithm.X25519HkdfSha256A256Kw;
+  }
+
+  private static unsupportedKeyAgreementAlgorithmMessage(algorithm: unknown): string {
+    return `Unsupported key agreement algorithm: ${String(algorithm)}`;
+  }
+
   private static toA256CtrJwk(keyBytes: Uint8Array): Jwk {
     return { alg: ContentEncryptionAlgorithm.A256CTR, k: Encoder.bytesToBase64Url(keyBytes), kty: 'oct' };
   }
 
+  private static toA256KwJwk(keyBytes: Uint8Array): Jwk {
+    return { alg: 'A256KW', k: Encoder.bytesToBase64Url(keyBytes), kty: 'oct' };
+  }
+
   private static async readStream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array> {
     const reader = stream.getReader();
     const chunks: Uint8Array[] = [];

package/src/utils/grant-key-coverage.ts

@@ -0,0 +1,303 @@
+import type { PermissionScope, RecordsPermissionScope } from '../types/permission-types.js';
+import type { ProtocolDefinition, ProtocolRuleSet } from '../types/protocols-types.js';
+
+import { KeyDerivationScheme } from './hd-key.js';
+import { ProtocolAction } from '../types/protocols-types.js';
+import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+import { getRuleSetAtPath, parseCrossProtocolRef } from './protocols.js';
+
+type GrantKeyRecordsScopeBase = RecordsPermissionScope & {
+  interface: typeof DwnInterfaceName.Records;
+  protocol: string;
+};
+
+export type GrantKeyRecordsScope = GrantKeyRecordsScopeBase & {
+  method: typeof DwnMethodName.Read | typeof DwnMethodName.Write;
+};
+
+export type GrantKeyReadRecordsScope = GrantKeyRecordsScopeBase & {
+  contextId?: undefined;
+  method: typeof DwnMethodName.Read;
+};
+
+export type GrantKeyWriteRecordsScope = GrantKeyRecordsScopeBase & {
+  contextId?: undefined;
+  method: typeof DwnMethodName.Write;
+};
+
+export type GrantKeyEligibleRecordsScope = GrantKeyReadRecordsScope | GrantKeyWriteRecordsScope;
+
+export type GrantKeyProtocolPathScope = {
+  scheme: typeof KeyDerivationScheme.ProtocolPath;
+  protocol: string;
+  protocolPath?: string;
+};
+
+type GrantKeyDeliveryScopeBuilder = (
+  grantScope: GrantKeyEligibleRecordsScope,
+  protocolDefinition?: ProtocolDefinition,
+) => GrantKeyProtocolPathScope[];
+
+type GrantKeyCoveragePredicate = (
+  input: {
+    grantScope: GrantKeyEligibleRecordsScope;
+    deliveredScope: Pick<GrantKeyProtocolPathScope, 'protocol' | 'protocolPath'>;
+    protocolDefinition?: ProtocolDefinition;
+  },
+) => boolean;
+
+const grantKeyRecordsMethods = new Set<string>([
+  DwnMethodName.Read,
+  DwnMethodName.Write,
+]);
+
+const grantKeyDeliveryScopeBuilders: Record<GrantKeyRecordsScope['method'], GrantKeyDeliveryScopeBuilder> = {
+  [DwnMethodName.Read]  : getReadGrantKeyDeliveryScopes,
+  [DwnMethodName.Write] : getWriteGrantKeyDeliveryScopes,
+};
+
+const grantKeyCoveragePredicates: Record<GrantKeyRecordsScope['method'], GrantKeyCoveragePredicate> = {
+  [DwnMethodName.Read]  : readGrantKeyScopeCoversDeliveredScope,
+  [DwnMethodName.Write] : writeGrantKeyScopeCoversDeliveredScope,
+};
+
+export function isGrantKeyRecordsScope(scope: PermissionScope): scope is GrantKeyRecordsScope {
+  const maybeProtocol = (scope as { protocol?: unknown }).protocol;
+  return [
+    scope.interface === DwnInterfaceName.Records,
+    grantKeyRecordsMethods.has(scope.method),
+    typeof maybeProtocol === 'string',
+  ].every(Boolean);
+}
+
+export function isGrantKeyEligibleRecordsScope(scope: PermissionScope): scope is GrantKeyEligibleRecordsScope {
+  return isGrantKeyRecordsScope(scope) &&
+    !('contextId' in scope && scope.contextId !== undefined);
+}
+
+export function getGrantKeyDeliveryScopes(
+  grantScope: GrantKeyReadRecordsScope,
+  protocolDefinition?: ProtocolDefinition,
+): GrantKeyProtocolPathScope[];
+
+export function getGrantKeyDeliveryScopes(
+  grantScope: GrantKeyWriteRecordsScope,
+  protocolDefinition: ProtocolDefinition,
+): GrantKeyProtocolPathScope[];
+
+export function getGrantKeyDeliveryScopes(
+  grantScope: GrantKeyEligibleRecordsScope,
+  protocolDefinition?: ProtocolDefinition,
+): GrantKeyProtocolPathScope[] {
+  return uniqueGrantKeyScopes(grantKeyDeliveryScopeBuilders[grantScope.method](grantScope, protocolDefinition));
+}
+
+export function grantKeyScopeCoversDeliveredScope(input: {
+  grantScope: GrantKeyEligibleRecordsScope;
+  deliveredScope: Pick<GrantKeyProtocolPathScope, 'protocol' | 'protocolPath'>;
+  protocolDefinition?: ProtocolDefinition;
+}): boolean {
+  const { grantScope, deliveredScope, protocolDefinition } = input;
+  if (grantScope.protocol !== deliveredScope.protocol) {
+    return false;
+  }
+
+  return grantKeyCoveragePredicates[grantScope.method]({ grantScope, deliveredScope, protocolDefinition });
+}
+
+function getReadGrantKeyDeliveryScopes(
+  grantScope: GrantKeyEligibleRecordsScope,
+  protocolDefinition?: ProtocolDefinition,
+): GrantKeyProtocolPathScope[] {
+  if (grantScope.protocolPath === undefined) {
+    return [createProtocolGrantKeyScope(grantScope.protocol)];
+  }
+
+  const scopes = [
+    createProtocolPathGrantKeyScope(grantScope.protocol, grantScope.protocolPath),
+  ];
+
+  if (protocolDefinition === undefined) {
+    return scopes;
+  }
+
+  for (const rolePath of getGrantKeyReadRolePathsForScope(protocolDefinition, grantScope.protocolPath)) {
+    scopes.push(createProtocolPathGrantKeyScope(grantScope.protocol, rolePath));
+  }
+
+  return scopes;
+}
+
+function getWriteGrantKeyDeliveryScopes(
+  grantScope: GrantKeyEligibleRecordsScope,
+  protocolDefinition?: ProtocolDefinition,
+): GrantKeyProtocolPathScope[] {
+  if (protocolDefinition === undefined) {
+    throw new Error('getGrantKeyDeliveryScopes: write grants require a protocol definition.');
+  }
+
+  return getGrantKeyRolePathsCoveredByScope(protocolDefinition, grantScope.protocolPath)
+    .map((rolePath) => createProtocolPathGrantKeyScope(grantScope.protocol, rolePath));
+}
+
+function createProtocolGrantKeyScope(protocol: string): GrantKeyProtocolPathScope {
+  return {
+    scheme: KeyDerivationScheme.ProtocolPath,
+    protocol,
+  };
+}
+
+function createProtocolPathGrantKeyScope(protocol: string, protocolPath: string): GrantKeyProtocolPathScope {
+  return {
+    scheme: KeyDerivationScheme.ProtocolPath,
+    protocol,
+    protocolPath,
+  };
+}
+
+function readGrantKeyScopeCoversDeliveredScope(input: {
+  grantScope: GrantKeyEligibleRecordsScope;
+  deliveredScope: Pick<GrantKeyProtocolPathScope, 'protocol' | 'protocolPath'>;
+  protocolDefinition?: ProtocolDefinition;
+}): boolean {
+  const { grantScope, deliveredScope, protocolDefinition } = input;
+  const grantProtocolPath = grantScope.protocolPath;
+  if (grantProtocolPath === undefined) {
+    return true;
+  }
+
+  const deliveredProtocolPath = deliveredScope.protocolPath;
+  if (deliveredProtocolPath === undefined) {
+    return false;
+  }
+
+  if (isBoundaryAwareSubtree(grantProtocolPath, deliveredProtocolPath)) {
+    return true;
+  }
+
+  if (protocolDefinition === undefined) {
+    return false;
+  }
+
+  return grantKeyReadScopeReferencesRolePath(protocolDefinition, grantProtocolPath, deliveredProtocolPath);
+}
+
+function writeGrantKeyScopeCoversDeliveredScope(input: {
+  grantScope: GrantKeyEligibleRecordsScope;
+  deliveredScope: Pick<GrantKeyProtocolPathScope, 'protocol' | 'protocolPath'>;
+  protocolDefinition?: ProtocolDefinition;
+}): boolean {
+  const { grantScope, deliveredScope, protocolDefinition } = input;
+  const deliveredProtocolPath = deliveredScope.protocolPath;
+  if (deliveredProtocolPath === undefined) {
+    return false;
+  }
+
+  if (protocolDefinition === undefined) {
+    return false;
+  }
+
+  if (!isGrantKeyLocalRolePath(protocolDefinition, deliveredProtocolPath)) {
+    return false;
+  }
+
+  const grantProtocolPath = grantScope.protocolPath;
+  if (grantProtocolPath === undefined) {
+    return true;
+  }
+
+  return isBoundaryAwareSubtree(grantProtocolPath, deliveredProtocolPath);
+}
+
+function getGrantKeyReadRolePathsForScope(protocolDefinition: ProtocolDefinition, scopeProtocolPath: string): string[] {
+  const scopedRuleSet = getRuleSetAtPath(scopeProtocolPath, protocolDefinition.structure);
+  if (scopedRuleSet === undefined) {
+    return [];
+  }
+
+  return [...collectReadRolePaths(protocolDefinition, scopedRuleSet)];
+}
+
+function grantKeyReadScopeReferencesRolePath(
+  protocolDefinition: ProtocolDefinition,
+  scopeProtocolPath: string,
+  rolePath: string,
+): boolean {
+  if (!isGrantKeyLocalRolePath(protocolDefinition, rolePath)) {
+    return false;
+  }
+
+  return getGrantKeyReadRolePathsForScope(protocolDefinition, scopeProtocolPath).includes(rolePath);
+}
+
+function collectReadRolePaths(protocolDefinition: ProtocolDefinition, ruleSet: ProtocolRuleSet): Set<string> {
+  const rolePaths = new Set<string>();
+
+  for (const actionRule of ruleSet.$actions ?? []) {
+    if (!actionRule.can.includes(ProtocolAction.Read) || actionRule.role === undefined || parseCrossProtocolRef(actionRule.role) !== undefined) {
+      continue;
+    }
+
+    if (isGrantKeyLocalRolePath(protocolDefinition, actionRule.role)) {
+      rolePaths.add(actionRule.role);
+    }
+  }
+
+  for (const [key, value] of Object.entries(ruleSet)) {
+    if (key.startsWith('$')) {
+      continue;
+    }
+    for (const rolePath of collectReadRolePaths(protocolDefinition, value as ProtocolRuleSet)) {
+      rolePaths.add(rolePath);
+    }
+  }
+
+  return rolePaths;
+}
+
+function getGrantKeyRolePathsCoveredByScope(protocolDefinition: ProtocolDefinition, scopeProtocolPath?: string): string[] {
+  return collectRolePaths(protocolDefinition, protocolDefinition.structure as ProtocolRuleSet)
+    .filter((rolePath) => scopeProtocolPath === undefined || isBoundaryAwareSubtree(scopeProtocolPath, rolePath));
+}
+
+function collectRolePaths(protocolDefinition: ProtocolDefinition, ruleSet: ProtocolRuleSet, parentPath: string[] = []): string[] {
+  const rolePaths: string[] = [];
+
+  for (const [key, value] of Object.entries(ruleSet)) {
+    if (key.startsWith('$')) {
+      continue;
+    }
+
+    const path = [...parentPath, key];
+    const protocolPath = path.join('/');
+    const childRuleSet = value as ProtocolRuleSet;
+    if (isGrantKeyLocalRolePath(protocolDefinition, protocolPath)) {
+      rolePaths.push(protocolPath);
+    }
+    rolePaths.push(...collectRolePaths(protocolDefinition, childRuleSet, path));
+  }
+
+  return rolePaths;
+}
+
+function isGrantKeyLocalRolePath(protocolDefinition: ProtocolDefinition, protocolPath: string): boolean {
+  const ruleSet = getRuleSetAtPath(protocolPath, protocolDefinition.structure);
+  return ruleSet?.$role === true && ruleSet.$keyAgreement !== undefined;
+}
+
+function isBoundaryAwareSubtree(scopePath: string, candidatePath: string): boolean {
+  return `${candidatePath}/`.startsWith(`${scopePath}/`);
+}
+
+function getGrantKeyScopeCacheKey(scope: GrantKeyProtocolPathScope): string {
+  return JSON.stringify([scope.protocol, scope.protocolPath]);
+}
+
+function uniqueGrantKeyScopes(scopes: GrantKeyProtocolPathScope[]): GrantKeyProtocolPathScope[] {
+  const deliveredScopes = new Map<string, GrantKeyProtocolPathScope>();
+  for (const scope of scopes) {
+    deliveredScopes.set(getGrantKeyScopeCacheKey(scope), scope);
+  }
+
+  return [...deliveredScopes.values()];
+}