@enbox/agent 0.7.7 → 0.7.9

package/src/sync-permission-grants.ts

@@ -0,0 +1,297 @@
+import type { DwnInterface } from './types/dwn.js';
+import type { GenericMessage, GenericSignaturePayload, MessagesPermissionScope, RecordsProjectionScope } from '@enbox/dwn-sdk-js';
+import type { NonEmptyStringArray, SyncAuthorizationGrant, SyncScope } from './types/sync.js';
+import type { PermissionGrantEntry, PermissionsApi } from './types/permissions.js';
+
+import { Jws, Message, PermissionScopeMatcher } from '@enbox/dwn-sdk-js';
+
+import { lexicographicalCompare, syncScopeFromRecordsProjectionScopes } from './types/sync.js';
+
+export type MessagesSyncScopeResolution = {
+  scope: SyncScope;
+  permissionGrants: PermissionGrantEntry[];
+};
+
+/** Returns a sorted, duplicate-free grant ID set, or `undefined` for owner requests. */
+export function toMessagesPermissionGrantIds(permissionGrantIds: string[] | undefined): NonEmptyStringArray | undefined {
+  if (permissionGrantIds === undefined || permissionGrantIds.length === 0) {
+    return undefined;
+  }
+  return [...new Set(permissionGrantIds)].sort(lexicographicalCompare) as NonEmptyStringArray;
+}
+
+/**
+ * Gets the active permission grant IDs that authorize a Messages operation.
+ *
+ * Owner-authored sync does not invoke grants. Delegate full sync requires at
+ * least one active unscoped Messages.Read grant. Delegate protocol-set sync
+ * requires each requested protocol to be covered by an active Messages.Read
+ * grant, then invokes every active grant that participates in the projection.
+ * This keeps the authorization epoch tied to grant churn without widening the
+ * CID projection being compared.
+ */
+export async function getMessagesPermissionGrantsForScope({
+  did,
+  delegateDid,
+  protocols,
+  messageType,
+  permissionsApi,
+}: {
+  did: string;
+  delegateDid?: string;
+  protocols?: NonEmptyStringArray;
+  messageType: DwnInterface;
+  permissionsApi: PermissionsApi;
+}): Promise<PermissionGrantEntry[]> {
+  const requestedScope: SyncScope = protocols === undefined
+    ? { kind: 'full' }
+    : { kind: 'protocolSet', protocols };
+  const resolutions = await resolveMessagesSyncScopes({
+    did,
+    delegateDid,
+    requestedScope,
+    messageType,
+    permissionsApi,
+  });
+  return resolutions
+    .flatMap(resolution => resolution.permissionGrants)
+    .sort((a, b) => lexicographicalCompare(a.grant.id, b.grant.id));
+}
+
+/**
+ * Resolves active Messages.Read grants into one or more sync targets.
+ *
+ * Broad protocol coverage remains on StateIndex full/protocol roots. Exact
+ * protocolPath and contextId grants are grouped into a Records-primary
+ * projection target so a narrow grant never authorizes a broad protocol root.
+ */
+export async function resolveMessagesSyncScopes({
+  did,
+  delegateDid,
+  requestedScope,
+  messageType,
+  permissionsApi,
+}: {
+  did: string;
+  delegateDid?: string;
+  requestedScope: SyncScope;
+  messageType: DwnInterface;
+  permissionsApi: PermissionsApi;
+}): Promise<MessagesSyncScopeResolution[]> {
+  if (!delegateDid) {
+    return [{ scope: requestedScope, permissionGrants: [] }];
+  }
+
+  const now = new Date().toISOString();
+  const permissionGrants = (await permissionsApi.fetchGrants({
+    author  : delegateDid,
+    target  : delegateDid,
+    grantor : did,
+    grantee : delegateDid,
+  })).filter(entry => isActiveMessagesGrant(entry, did, delegateDid, now));
+
+  if (requestedScope.kind === 'full') {
+    return [resolveFullScope(permissionGrants, requestedScope, messageType)];
+  }
+
+  if (requestedScope.kind === 'protocolSet') {
+    return resolveProtocolSetScope(permissionGrants, requestedScope, messageType);
+  }
+
+  return [resolveRecordsProjectionScope(permissionGrants, requestedScope, messageType)];
+}
+
+function resolveFullScope(
+  permissionGrants: PermissionGrantEntry[],
+  requestedScope: Extract<SyncScope, { kind: 'full' }>,
+  messageType: DwnInterface,
+): MessagesSyncScopeResolution {
+  const grants = permissionGrants
+    .filter(entry => grantMatchesProtocol(entry, undefined))
+    .sort((a, b) => lexicographicalCompare(a.grant.id, b.grant.id));
+  if (grants.length === 0) {
+    throw new Error(`SyncPermissions: No active Messages.Read permission found for ${messageType}: all protocols`);
+  }
+
+  return { scope: requestedScope, permissionGrants: grants };
+}
+
+function resolveProtocolSetScope(
+  permissionGrants: PermissionGrantEntry[],
+  requestedScope: Extract<SyncScope, { kind: 'protocolSet' }>,
+  messageType: DwnInterface,
+): MessagesSyncScopeResolution[] {
+  const broadProtocols: string[] = [];
+  const narrowScopes: RecordsProjectionScope[] = [];
+
+  for (const protocol of requestedScope.protocols) {
+    if (permissionGrants.some(entry => grantMatchesProtocol(entry, protocol))) {
+      broadProtocols.push(protocol);
+      continue;
+    }
+
+    const protocolNarrowScopes = permissionGrants
+      .map(entry => grantProjectionScopeForProtocol(entry, protocol))
+      .filter((scope): scope is RecordsProjectionScope => scope !== undefined);
+    if (protocolNarrowScopes.length === 0) {
+      throw new Error(`SyncPermissions: No active Messages.Read permission found for ${messageType}: ${protocol}`);
+    }
+    narrowScopes.push(...protocolNarrowScopes);
+  }
+
+  return [
+    ...broadProtocolResolution(permissionGrants, broadProtocols),
+    ...recordsProjectionResolution(permissionGrants, narrowScopes, messageType),
+  ];
+}
+
+function resolveRecordsProjectionScope(
+  permissionGrants: PermissionGrantEntry[],
+  requestedScope: Extract<SyncScope, { kind: 'recordsProjection' }>,
+  messageType: DwnInterface,
+): MessagesSyncScopeResolution {
+  if (!requestedScope.scopes.every(scope => isProjectionScopeCovered(permissionGrants, scope))) {
+    throw new Error(`SyncPermissions: No active Messages.Read permission found for ${messageType}: projected Records scope`);
+  }
+
+  const grants = permissionGrants
+    .filter(entry => requestedScope.scopes.some(scope => PermissionScopeMatcher.matches(entry.grant.scope, scope)))
+    .sort((a, b) => lexicographicalCompare(a.grant.id, b.grant.id));
+
+  return { scope: requestedScope, permissionGrants: grants };
+}
+
+function isProjectionScopeCovered(
+  permissionGrants: PermissionGrantEntry[],
+  scope: RecordsProjectionScope,
+): boolean {
+  return permissionGrants.some(entry => PermissionScopeMatcher.matches(entry.grant.scope, scope));
+}
+
+function broadProtocolResolution(
+  permissionGrants: PermissionGrantEntry[],
+  broadProtocols: string[],
+): MessagesSyncScopeResolution[] {
+  if (broadProtocols.length === 0) {
+    return [];
+  }
+
+  const protocols = [...new Set(broadProtocols)].sort(lexicographicalCompare) as NonEmptyStringArray;
+  const grants = permissionGrants
+    .filter(entry => grantParticipatesInProtocolSet(entry, protocols))
+    .sort((a, b) => lexicographicalCompare(a.grant.id, b.grant.id));
+
+  return [{
+    scope: {
+      kind: 'protocolSet',
+      protocols,
+    },
+    permissionGrants: grants,
+  }];
+}
+
+function recordsProjectionResolution(
+  permissionGrants: PermissionGrantEntry[],
+  projectionScopes: RecordsProjectionScope[],
+  messageType: DwnInterface,
+): MessagesSyncScopeResolution[] {
+  const [firstScope, ...remainingScopes] = projectionScopes;
+  if (firstScope === undefined) {
+    return [];
+  }
+
+  const requestedScope = syncScopeFromRecordsProjectionScopes([firstScope, ...remainingScopes]);
+  return [resolveRecordsProjectionScope(permissionGrants, requestedScope, messageType)];
+}
+
+function grantProjectionScopeForProtocol(
+  entry: PermissionGrantEntry,
+  protocol: string,
+): RecordsProjectionScope | undefined {
+  const scope = entry.grant.scope;
+  if (!isMessagesReadScope(scope) || scope.protocol !== protocol) {
+    return undefined;
+  }
+  if (scope.protocolPath !== undefined) {
+    return { protocol, protocolPath: scope.protocolPath };
+  }
+  if (scope.contextId !== undefined) {
+    return { protocol, contextId: scope.contextId };
+  }
+}
+
+function isMessagesReadScope(scope: PermissionGrantEntry['grant']['scope']): scope is MessagesPermissionScope {
+  return scope.interface === 'Messages' &&
+    scope.method === 'Read';
+}
+
+function grantParticipatesInProtocolSet(
+  entry: PermissionGrantEntry,
+  protocols: NonEmptyStringArray,
+): boolean {
+  return protocols.some(protocol => grantMatchesProtocol(entry, protocol));
+}
+
+/** Converts permission grant entries into authorization epoch inputs. */
+export function toSyncAuthorizationGrants(permissionGrants: PermissionGrantEntry[]): [SyncAuthorizationGrant, ...SyncAuthorizationGrant[]] {
+  if (permissionGrants.length === 0) {
+    throw new Error('SyncPermissions: delegate authorization requires at least one grant.');
+  }
+  return permissionGrants
+    .map(({ grant }) => ({
+      dateExpires : grant.dateExpires,
+      dateGranted : grant.dateGranted,
+      id          : grant.id,
+    }))
+    .sort((a, b) => lexicographicalCompare(a.id, b.id)) as [SyncAuthorizationGrant, ...SyncAuthorizationGrant[]];
+}
+
+function isActiveMessagesGrant(
+  entry: PermissionGrantEntry,
+  grantor: string,
+  grantee: string,
+  now: string,
+): boolean {
+  const { grant } = entry;
+  if (grant.grantor !== grantor || grant.grantee !== grantee) {
+    return false;
+  }
+
+  if (grant.dateGranted > now || grant.dateExpires <= now) {
+    return false;
+  }
+
+  const scope = grant.scope;
+  return scope.interface === 'Messages' &&
+    scope.method === 'Read';
+}
+
+function grantMatchesProtocol(
+  entry: PermissionGrantEntry,
+  protocol: string | undefined,
+): boolean {
+  return PermissionScopeMatcher.matches(entry.grant.scope, { protocol });
+}
+
+/** Returns sorted grant IDs from permission grant entries. */
+export function permissionGrantIdsFromEntries(permissionGrants: PermissionGrantEntry[]): NonEmptyStringArray | undefined {
+  return toMessagesPermissionGrantIds(permissionGrants.map(entry => entry.grant.id));
+}
+
+/**
+ * Returns the permission grant IDs invoked by a message.
+ *
+ * Real DWN messages use the author signature payload as the source of truth.
+ */
+export function getInvokedPermissionGrantIds(message: GenericMessage): string[] {
+  if (message.authorization === undefined) {
+    return [];
+  }
+
+  try {
+    const signaturePayload = Jws.decodePlainObjectPayload(message.authorization.signature) as GenericSignaturePayload;
+    return Message.getPermissionGrantIds(signaturePayload);
+  } catch {
+    return [];
+  }
+}

package/src/sync-replication-ledger.ts

@@ -1,9 +1,9 @@
 import type { AbstractLevel } from 'abstract-level';
 import type { ProgressToken } from '@enbox/dwn-sdk-js';
 
-import type { DirectionCheckpoint, LinkStatus, ReplicationLinkState, SyncScope } from './types/sync.js';
+import type { DirectionCheckpoint, LinkStatus, ReplicationLinkState, SyncAuthorization, SyncScope } from './types/sync.js';
 
-import { computeScopeId } from './types/sync.js';
+import { canonicalizeSyncScope, computeProjectionId } from './types/sync.js';
 
 /** Separator used in compound LevelDB keys. */
 const KEY_SEP = '^';
@@ -13,7 +13,7 @@ const KEY_SEP = '^';
  * sync link in a LevelDB sublevel. Provides CRUD operations and replication
  * checkpoint helpers.
  *
- * Key format: `{tenantDid}^{remoteEndpoint}^{scopeId}`
+ * Key format: `{tenantDid}^{remoteEndpoint}^{projectionId}^{authorizationEpoch}`
  *
  * Each link tracks independent pull and push {@link DirectionCheckpoint}s.
  * The ledger does not own subscriptions or timers — it is a passive state
@@ -33,13 +33,19 @@ export class ReplicationLedger {
   // ---------------------------------------------------------------------------
 
   /** Build the compound key for a link. */
-  private static buildKey(tenantDid: string, remoteEndpoint: string, scopeId: string): string {
-    return `${tenantDid}${KEY_SEP}${remoteEndpoint}${KEY_SEP}${scopeId}`;
+  private static buildKey(
+    tenantDid: string,
+    remoteEndpoint: string,
+    projectionId: string,
+    authorizationEpoch: string,
+  ): string {
+    return `${tenantDid}${KEY_SEP}${remoteEndpoint}${KEY_SEP}${projectionId}${KEY_SEP}${authorizationEpoch}`;
   }
 
   // Note: compound keys use raw '^' separator. This is safe because tenantDid
-  // (DID URI), remoteEndpoint (URL), and scopeId (base64url hash) cannot
-  // contain '^'. If future fields can contain '^', keys must be escaped.
+  // (DID URI), remoteEndpoint (URL), projectionId (base64url hash), and
+  // authorizationEpoch (base64url hash) cannot contain '^'. If future fields
+  // can contain '^', keys must be escaped.
 
   // ---------------------------------------------------------------------------
   // CRUD
@@ -53,16 +59,22 @@ export class ReplicationLedger {
     tenantDid : string;
     remoteEndpoint : string;
     scope : SyncScope;
+    authorizationEpoch : string;
+    authorization : SyncAuthorization;
     delegateDid? : string;
-    protocol? : string;
   }): Promise<ReplicationLinkState> {
-    const scopeId = await computeScopeId(params.scope);
-    const key = ReplicationLedger.buildKey(params.tenantDid, params.remoteEndpoint, scopeId);
+    const scope = canonicalizeSyncScope(params.scope);
+    const projectionId = await computeProjectionId(params.tenantDid, scope);
+    const key = ReplicationLedger.buildKey(
+      params.tenantDid,
+      params.remoteEndpoint,
+      projectionId,
+      params.authorizationEpoch,
+    );
 
     try {
       const raw = await this.sublevel.get(key);
       const link = JSON.parse(raw) as ReplicationLinkState;
-      delete (link as any).push; // strip legacy push field from old persisted links
       // connectivity is runtime state — always reset to 'unknown' on load
       // so stale 'online' from a previous session doesn't give false positives.
       link.connectivity = 'unknown';
@@ -76,16 +88,17 @@ export class ReplicationLedger {
 
     // Create a new link with empty checkpoints.
     const link: ReplicationLinkState = {
-      tenantDid      : params.tenantDid,
-      remoteEndpoint : params.remoteEndpoint,
-      scopeId,
-      scope          : params.scope,
-      status         : 'initializing',
-      connectivity   : 'unknown',
-      pull           : {},
-      needsReconcile : false,
-      delegateDid    : params.delegateDid,
-      protocol       : params.protocol,
+      tenantDid          : params.tenantDid,
+      remoteEndpoint     : params.remoteEndpoint,
+      projectionId,
+      authorizationEpoch : params.authorizationEpoch,
+      scope,
+      authorization      : params.authorization,
+      status             : 'initializing',
+      connectivity       : 'unknown',
+      pull               : {},
+      needsReconcile     : false,
+      delegateDid        : params.delegateDid,
     };
 
     await this.sublevel.put(key, JSON.stringify(link));
@@ -94,14 +107,24 @@ export class ReplicationLedger {
 
   /** Persist the current state of a link. */
   public async saveLink(link: ReplicationLinkState): Promise<void> {
-    const key = ReplicationLedger.buildKey(link.tenantDid, link.remoteEndpoint, link.scopeId);
+    const key = ReplicationLedger.buildKey(
+      link.tenantDid,
+      link.remoteEndpoint,
+      link.projectionId,
+      link.authorizationEpoch,
+    );
     link.lastActivityAt = new Date().toISOString();
     await this.sublevel.put(key, JSON.stringify(link));
   }
 
   /** Delete a link. */
-  public async deleteLink(tenantDid: string, remoteEndpoint: string, scopeId: string): Promise<void> {
-    const key = ReplicationLedger.buildKey(tenantDid, remoteEndpoint, scopeId);
+  public async deleteLink(
+    tenantDid: string,
+    remoteEndpoint: string,
+    projectionId: string,
+    authorizationEpoch: string,
+  ): Promise<void> {
+    const key = ReplicationLedger.buildKey(tenantDid, remoteEndpoint, projectionId, authorizationEpoch);
     await this.sublevel.del(key);
   }
 
@@ -126,31 +149,6 @@ export class ReplicationLedger {
     return links;
   }
 
-  // ---------------------------------------------------------------------------
-  // Delegate updates
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Update the `delegateDid` on all persisted links for a tenant and persist.
-   * This ensures that repair and reconcile paths — which read `delegateDid`
-   * from the durable {@link ReplicationLinkState} — use the current delegate
-   * after a hot-swap via `updateIdentityOptions()`.
-   *
-   * @returns the links that were updated.
-   */
-  public async updateDelegateDid(tenantDid: string, delegateDid: string | undefined): Promise<ReplicationLinkState[]> {
-    const links = await this.getLinksForTenant(tenantDid);
-    const updated: ReplicationLinkState[] = [];
-    for (const link of links) {
-      if (link.delegateDid !== delegateDid) {
-        link.delegateDid = delegateDid;
-        await this.saveLink(link);
-        updated.push(link);
-      }
-    }
-    return updated;
-  }
-
   // ---------------------------------------------------------------------------
   // Status transitions
   // ---------------------------------------------------------------------------
@@ -208,6 +206,14 @@ export class ReplicationLedger {
    * are durably committed before calling this.
    */
   public static commitContiguousToken(checkpoint: DirectionCheckpoint, token: ProgressToken): void {
+    if (
+      checkpoint.contiguousAppliedToken !== undefined &&
+      token.streamId === checkpoint.contiguousAppliedToken.streamId &&
+      token.epoch === checkpoint.contiguousAppliedToken.epoch &&
+      ReplicationLedger.comparePosition(token, checkpoint.contiguousAppliedToken) <= 0
+    ) {
+      return;
+    }
     checkpoint.contiguousAppliedToken = token;
   }
 
@@ -245,4 +251,3 @@ export class ReplicationLedger {
     }
   }
 }
-

package/src/sync-scope-acceptance.ts

@@ -0,0 +1,186 @@
+import type { GenericMessage, MessageEvent, ProtocolScope, RecordsWriteMessage } from '@enbox/dwn-sdk-js';
+
+import { DwnInterfaceName, DwnMethodName, PermissionScopeMatcher, PermissionsProtocol } from '@enbox/dwn-sdk-js';
+
+import type { SyncScope } from './types/sync.js';
+
+/** Result of testing whether an inbound sync message belongs to a link scope. */
+export type SyncScopeClassification = 'in-scope' | 'out-of-scope' | 'unknown';
+
+type SyncMessageScopeClassificationParams = {
+  message: GenericMessage;
+  initialWrite?: RecordsWriteMessage;
+  scope: SyncScope;
+};
+
+type ProtocolSetSyncScope = Extract<SyncScope, { kind: 'protocolSet' }>;
+type RecordsProjectionSyncScope = Extract<SyncScope, { kind: 'recordsProjection' }>;
+
+/**
+ * Classifies whether a live event belongs to the link's current sync scope.
+ *
+ * Full links accept every message. Protocol-set links accept records for a
+ * covered protocol, ProtocolsConfigure messages that install a covered
+ * protocol, and permission records tagged for a covered protocol. RecordsDelete
+ * messages carry no protocol in their descriptor, so they must be classified
+ * from the event's initial write metadata.
+ */
+export function classifySyncEventScope(event: MessageEvent, scope: SyncScope): SyncScopeClassification {
+  return classifySyncMessageScope({
+    message      : event.message,
+    initialWrite : event.initialWrite,
+    scope,
+  });
+}
+
+/**
+ * Classifies whether a DWN message belongs to a sync scope before local apply.
+ *
+ * If a RecordsDelete cannot be tied to its initial write, the result is
+ * `unknown` so callers fail closed instead of applying an unclassified delete.
+ */
+export function classifySyncMessageScope({
+  message,
+  initialWrite,
+  scope,
+}: SyncMessageScopeClassificationParams): SyncScopeClassification {
+  if (scope.kind === 'full') { return 'in-scope'; }
+  if (scope.kind === 'recordsProjection') {
+    return classifyRecordsProjectionScope(message, initialWrite, scope);
+  }
+
+  return classifyProtocolSetScope(message, initialWrite, scope);
+}
+
+function classifyProtocolSetScope(
+  message: GenericMessage,
+  initialWrite: RecordsWriteMessage | undefined,
+  scope: ProtocolSetSyncScope,
+): SyncScopeClassification {
+  const descriptor = message.descriptor as Record<string, unknown>;
+  const scopedDescriptor = getScopedMessageDescriptor(message, initialWrite);
+  if (scopedDescriptor === undefined) {
+    return 'unknown';
+  }
+
+  const permissionRecordClassification = classifyTaggedPermissionRecord(scopedDescriptor, scope.protocols);
+  if (permissionRecordClassification !== undefined) { return permissionRecordClassification; }
+
+  const protocolClassification = classifyProtocolField(scopedDescriptor.protocol, scope.protocols);
+  if (protocolClassification !== undefined) { return protocolClassification; }
+
+  return classifyProtocolsConfigureDescriptor(descriptor, scope.protocols);
+}
+
+function classifyTaggedPermissionRecord(
+  descriptor: Record<string, unknown>,
+  protocols: readonly string[],
+): SyncScopeClassification | undefined {
+  if (descriptor.protocol !== PermissionsProtocol.uri || !isRecordObject(descriptor.tags)) {
+    return undefined;
+  }
+
+  const taggedProtocol = descriptor.tags.protocol;
+  return typeof taggedProtocol === 'string' && protocols.includes(taggedProtocol)
+    ? 'in-scope'
+    : 'out-of-scope';
+}
+
+function classifyProtocolField(protocol: unknown, protocols: readonly string[]): SyncScopeClassification | undefined {
+  if (typeof protocol !== 'string') {
+    return undefined;
+  }
+
+  return protocols.includes(protocol) ? 'in-scope' : 'out-of-scope';
+}
+
+function classifyProtocolsConfigureDescriptor(
+  descriptor: Record<string, unknown>,
+  protocols: readonly string[],
+): SyncScopeClassification {
+  if (
+    descriptor.interface === DwnInterfaceName.Protocols &&
+    descriptor.method === DwnMethodName.Configure &&
+    isRecordObject(descriptor.definition)
+  ) {
+    const definitionProtocol = descriptor.definition.protocol;
+    return typeof definitionProtocol === 'string' && protocols.includes(definitionProtocol)
+      ? 'in-scope'
+      : 'out-of-scope';
+  }
+
+  return 'out-of-scope';
+}
+
+function getScopedMessageDescriptor(
+  message: GenericMessage,
+  initialWrite: RecordsWriteMessage | undefined,
+): Record<string, unknown> | undefined {
+  const descriptor = message.descriptor as Record<string, unknown>;
+  if (
+    descriptor.interface === DwnInterfaceName.Records &&
+    descriptor.method === DwnMethodName.Delete
+  ) {
+    return initialWrite?.descriptor as Record<string, unknown> | undefined;
+  }
+
+  return descriptor;
+}
+
+function classifyRecordsProjectionScope(
+  message: GenericMessage,
+  initialWrite: RecordsWriteMessage | undefined,
+  scope: RecordsProjectionSyncScope,
+): SyncScopeClassification {
+  const target = getRecordsProjectionTarget(message, initialWrite);
+  if (target === undefined) {
+    return isRecordsDelete(message) ? 'unknown' : 'out-of-scope';
+  }
+
+  return scope.scopes.some(projectionScope => PermissionScopeMatcher.matches(projectionScope, target))
+    ? 'in-scope'
+    : 'out-of-scope';
+}
+
+function getRecordsProjectionTarget(
+  message: GenericMessage,
+  initialWrite: RecordsWriteMessage | undefined,
+): ProtocolScope | undefined {
+  const descriptor = message.descriptor as Record<string, unknown>;
+  if (descriptor.interface !== DwnInterfaceName.Records) {
+    return undefined;
+  }
+
+  if (descriptor.method === DwnMethodName.Write) {
+    return {
+      protocol     : stringField(descriptor.protocol),
+      protocolPath : stringField(descriptor.protocolPath),
+      contextId    : (message as RecordsWriteMessage).contextId,
+    };
+  }
+
+  if (descriptor.method === DwnMethodName.Delete) {
+    if (initialWrite === undefined) {
+      return undefined;
+    }
+    return {
+      protocol     : initialWrite.descriptor.protocol,
+      protocolPath : initialWrite.descriptor.protocolPath,
+      contextId    : initialWrite.contextId,
+    };
+  }
+}
+
+function isRecordsDelete(message: GenericMessage): boolean {
+  const descriptor = message.descriptor as Record<string, unknown>;
+  return descriptor.interface === DwnInterfaceName.Records &&
+    descriptor.method === DwnMethodName.Delete;
+}
+
+function isRecordObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}