@enbox/agent 0.1.8 → 0.1.9

package/src/dwn-protocol-cache.ts

@@ -0,0 +1,216 @@
+/**
+ * Protocol definition fetching and caching utilities for {@link AgentDwnApi}.
+ *
+ * Extracted from `dwn-api.ts` to keep protocol-resolution logic in its own
+ * module.
+ *
+ * @module
+ */
+
+import type { DidUrlDereferencer } from '@enbox/dids';
+import type { PublicKeyJwk } from '@enbox/crypto';
+import type { TtlCache } from '@enbox/common';
+import type {
+  ProtocolDefinition,
+  ProtocolsQueryReply,
+  RecordsQueryReply,
+} from '@enbox/dwn-sdk-js';
+
+import type {
+  DwnInterface,
+  DwnMessage,
+  DwnMessageReply,
+  DwnSigner,
+  MessageHandler,
+} from './types/dwn.js';
+
+import { KeyDerivationScheme } from '@enbox/dwn-sdk-js';
+
+import { getDwnServiceEndpointUrls } from './utils.js';
+import { DwnInterface as DwnInterfaceEnum, dwnMessageConstructors } from './types/dwn.js';
+
+// ---------------------------------------------------------------------------
+// Dependency signatures — keep the extracted code free of `this` references.
+// ---------------------------------------------------------------------------
+
+/** Callback to obtain a DWN signer for a given DID. */
+type GetSignerFn = (author: string) => Promise<DwnSigner>;
+
+/** Callback to send a raw DWN request to a remote endpoint. */
+type SendDwnRpcRequestFn = <T extends DwnInterface>(params: {
+  targetDid: string;
+  dwnEndpointUrls: string[];
+  message: DwnMessage[T];
+  data?: Blob;
+  subscriptionHandler?: MessageHandler[T];
+}) => Promise<DwnMessageReply[T]>;
+
+/** Minimal DWN interface needed for local `processMessage` calls. */
+interface DwnNode {
+  processMessage(tenant: string, message: unknown, options?: unknown): Promise<any>;
+}
+
+// ---------------------------------------------------------------------------
+// Exported functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetches a protocol definition from the **local** DWN, backed by a TTL cache.
+ *
+ * @param tenantDid - The DID whose DWN to query
+ * @param protocolUri - The protocol URI to look up
+ * @param dwn - The local DWN instance
+ * @param getSigner - Callback to obtain the signer for `tenantDid`
+ * @param cache - The shared protocol definition cache
+ * @returns The protocol definition, or `undefined` if not installed
+ */
+export async function getProtocolDefinition(
+  tenantDid: string,
+  protocolUri: string,
+  dwn: DwnNode,
+  getSigner: GetSignerFn,
+  cache: TtlCache<string, ProtocolDefinition>,
+): Promise<ProtocolDefinition | undefined> {
+  const cacheKey = `${tenantDid}~${protocolUri}`;
+
+  const cached = cache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const signer = await getSigner(tenantDid);
+  const protocolsQuery = await dwnMessageConstructors[
+    DwnInterfaceEnum.ProtocolsQuery
+  ].create({
+    filter: { protocol: protocolUri },
+    signer,
+  });
+
+  const reply = await dwn.processMessage(
+    tenantDid, protocolsQuery.message,
+  );
+  if (reply.status.code !== 200 || !reply.entries?.length) {
+    return undefined;
+  }
+
+  const definition = reply.entries[0].descriptor.definition;
+  cache.set(cacheKey, definition);
+  return definition;
+}
+
+/**
+ * Fetches a protocol definition from a **remote** DWN.
+ *
+ * Uses an unsigned `ProtocolsQuery` since public protocols can be queried
+ * anonymously.
+ *
+ * @param targetDid - The remote DWN owner
+ * @param protocolUri - The protocol URI to look up
+ * @param didDereferencer - A DID URL dereferencer for resolving service endpoints
+ * @param sendDwnRpcRequest - Callback to send the RPC query
+ * @param cache - The shared protocol definition cache
+ * @returns The protocol definition
+ * @throws If the protocol cannot be fetched
+ */
+export async function fetchRemoteProtocolDefinition(
+  targetDid: string,
+  protocolUri: string,
+  didDereferencer: DidUrlDereferencer,
+  sendDwnRpcRequest: SendDwnRpcRequestFn,
+  cache: TtlCache<string, ProtocolDefinition>,
+): Promise<ProtocolDefinition> {
+  const cacheKey = `remote~${targetDid}~${protocolUri}`;
+  const cached = cache.get(cacheKey);
+  if (cached) { return cached; }
+
+  const protocolsQuery = await dwnMessageConstructors[
+    DwnInterfaceEnum.ProtocolsQuery
+  ].create({
+    filter: { protocol: protocolUri },
+  });
+
+  const reply = await sendDwnRpcRequest({
+    targetDid,
+    dwnEndpointUrls : await getDwnServiceEndpointUrls(targetDid, didDereferencer),
+    message         : protocolsQuery.message,
+  }) as ProtocolsQueryReply;
+
+  if (reply.status.code !== 200 || !reply.entries?.length) {
+    throw new Error(
+      `AgentDwnApi: Failed to fetch protocol '${protocolUri}' from ` +
+      `'${targetDid}'. The recipient may not have the protocol installed.`
+    );
+  }
+
+  const definition = reply.entries[0].descriptor.definition;
+  cache.set(cacheKey, definition);
+  return definition;
+}
+
+/**
+ * Extracts the `derivedPublicKey` from an existing `ProtocolContext`-encrypted
+ * record in a context on a remote DWN.
+ *
+ * This key allows an external author to encrypt new records in the same
+ * context without knowing the context private key.
+ *
+ * @param targetDid      - The DWN owner's DID
+ * @param protocolUri    - The protocol URI to search
+ * @param rootContextId  - The root context ID
+ * @param requesterDid   - The DID of the requester (used for signing the query)
+ * @param didDereferencer - A DID URL dereferencer for resolving service endpoints
+ * @param getSigner      - Callback to obtain the signer for `requesterDid`
+ * @param sendDwnRpcRequest - Callback to send the RPC query
+ * @returns The rootKeyId and derivedPublicKey, or `undefined` if no
+ *          `ProtocolContext` record exists yet
+ */
+export async function extractDerivedPublicKey(
+  targetDid: string,
+  protocolUri: string,
+  rootContextId: string,
+  requesterDid: string,
+  didDereferencer: DidUrlDereferencer,
+  getSigner: GetSignerFn,
+  sendDwnRpcRequest: SendDwnRpcRequestFn,
+): Promise<{ rootKeyId: string; derivedPublicKey: PublicKeyJwk } | undefined> {
+  const signer = await getSigner(requesterDid);
+
+  // Query the target's DWN for any record in this context
+  const recordsQuery = await dwnMessageConstructors[DwnInterfaceEnum.RecordsQuery].create({
+    signer,
+    filter: {
+      protocol  : protocolUri,
+      contextId : rootContextId,
+    },
+  });
+
+  const dwnEndpointUrls = await getDwnServiceEndpointUrls(targetDid, didDereferencer);
+  const queryReply = await sendDwnRpcRequest<DwnInterfaceEnum.RecordsQuery>({
+    targetDid,
+    dwnEndpointUrls,
+    message: recordsQuery.message,
+  }) as RecordsQueryReply;
+
+  if (queryReply.status.code !== 200 || !queryReply.entries?.length) {
+    return undefined;
+  }
+
+  // Search entries for one with a ProtocolContext recipient entry
+  // that includes derivedPublicKey
+  for (const entry of queryReply.entries) {
+    if (entry.encryption?.recipients) {
+      const contextEntry = entry.encryption.recipients.find(
+        (r: { header: { derivationScheme: string; derivedPublicKey?: PublicKeyJwk } }) =>
+          r.header.derivationScheme === KeyDerivationScheme.ProtocolContext && r.header.derivedPublicKey
+      );
+      if (contextEntry?.header.derivedPublicKey) {
+        return {
+          rootKeyId        : contextEntry.header.kid,
+          derivedPublicKey : contextEntry.header.derivedPublicKey,
+        };
+      }
+    }
+  }
+
+  return undefined;
+}

package/src/dwn-record-upgrade.ts

@@ -118,7 +118,7 @@ export async function upgradeExternalRootRecord(
   // We must also update the state index and event stream to keep sync and
   // real-time subscribers consistent — without this, the upgraded record
   // would never propagate to remote DWNs or notify subscribers.
-  const { messageStore, stateIndex, eventStream } = dwn.storage;
+  const { messageStore, stateIndex, eventLog } = dwn.storage;
 
   // Validate the upgrade only changed encryption and authorization fields.
   // The descriptor, recordId, contextId, and data must remain identical.
@@ -157,8 +157,8 @@ export async function upgradeExternalRootRecord(
   await stateIndex.delete(tenantDid, [originalCid]);
 
   // Notify real-time subscribers (mirrors handler behavior)
-  if (eventStream !== undefined) {
-    eventStream.emit(tenantDid, { message: upgradedMessage }, upgradedIndexes);
+  if (eventLog !== undefined) {
+    await eventLog.emit(tenantDid, { message: upgradedMessage }, upgradedIndexes);
   }
 
   // Cache context key info for subsequent writes in this context

package/src/hd-identity-vault.ts

@@ -530,8 +530,6 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
           id              : 'dwn',
           type            : 'DecentralizedWebNode',
           serviceEndpoint : dwnEndpoints,
-          enc             : '#enc',
-          sig             : '#sig',
         }
       ];
     }

package/src/identity-api.ts

@@ -254,8 +254,6 @@ export class AgentIdentityApi<TKeyManager extends AgentKeyManager = AgentKeyMana
         id              : 'dwn',
         type            : 'DecentralizedWebNode',
         serviceEndpoint : endpoints,
-        enc             : '#enc',
-        sig             : '#sig'
       };
 
       // if no other services exist, create a new array with the DWN service

package/src/permissions-api.ts

@@ -114,7 +114,7 @@ export class AgentPermissionsApi implements PermissionsApi {
       if (revokedGrantIds.has(entry.recordId)) {
         continue;
       }
-      const grant = await DwnPermissionGrant.parse(entry);
+      const grant = DwnPermissionGrant.parse(entry);
       grants.push({ grant, message: entry });
     }
 
@@ -193,7 +193,7 @@ export class AgentPermissionsApi implements PermissionsApi {
 
     const requests: PermissionRequestEntry[] = [];
     for (const entry of reply.entries! as DwnDataEncodedRecordsWriteMessage[]) {
-      const request = await DwnPermissionRequest.parse(entry);
+      const request = DwnPermissionRequest.parse(entry);
       requests.push({ request, message: entry });
     }
 
@@ -275,7 +275,7 @@ export class AgentPermissionsApi implements PermissionsApi {
       encodedData: Convert.uint8Array(permissionsGrantBytes).toBase64Url()
     };
 
-    const grant = await DwnPermissionGrant.parse(dataEncodedMessage);
+    const grant = DwnPermissionGrant.parse(dataEncodedMessage);
 
     return { grant, message: dataEncodedMessage };
   }
@@ -321,7 +321,7 @@ export class AgentPermissionsApi implements PermissionsApi {
       encodedData: Convert.uint8Array(permissionRequestBytes).toBase64Url()
     };
 
-    const request = await DwnPermissionRequest.parse(dataEncodedMessage);
+    const request = DwnPermissionRequest.parse(dataEncodedMessage);
 
     return { request, message: dataEncodedMessage };
   }
@@ -388,6 +388,11 @@ export class AgentPermissionsApi implements PermissionsApi {
     grants: PermissionGrantEntry[],
     delegated: boolean = false
   ): Promise<PermissionGrantEntry | undefined> {
+    // Two-pass matching: prefer exact scope matches over unified Messages.Read fallback.
+    // This ensures that if both a Messages.Sync grant and a Messages.Read grant exist,
+    // the specific Messages.Sync grant is returned for MessagesSync lookups.
+    let unifiedFallback: PermissionGrantEntry | undefined;
+
     for (const entry of grants) {
       const { grant, message } = entry;
       if (delegated === true && grant.delegated !== true) {
@@ -396,9 +401,19 @@ export class AgentPermissionsApi implements PermissionsApi {
       const { messageType, protocol, protocolPath, contextId } = messageParams;
 
       if (this.matchScopeFromGrant(grantor, grantee, messageType, grant, protocol, protocolPath, contextId)) {
-        return { grant, message };
+        const scopeMessageType = grant.scope.interface + grant.scope.method;
+        // Exact match — return immediately
+        if (scopeMessageType === messageType) {
+          return { grant, message };
+        }
+        // Unified fallback match — hold for later in case an exact match is found
+        if (!unifiedFallback) {
+          unifiedFallback = { grant, message };
+        }
       }
     }
+
+    return unifiedFallback;
   }
 
   private static matchScopeFromGrant<T extends DwnInterface>(
@@ -417,7 +432,14 @@ export class AgentPermissionsApi implements PermissionsApi {
 
     const scope = grant.scope;
     const scopeMessageType = scope.interface + scope.method;
-    if (scopeMessageType === messageType) {
+
+    // Messages.Read is a unified scope that covers Messages.Read, Messages.Sync, and Messages.Subscribe.
+    // When looking for a MessagesSync or MessagesSubscribe grant, also accept a MessagesRead grant.
+    const isMessagesScopeMatch = scopeMessageType === messageType
+      || (scopeMessageType === DwnInterface.MessagesRead
+        && (messageType === DwnInterface.MessagesSync || messageType === DwnInterface.MessagesSubscribe));
+
+    if (isMessagesScopeMatch) {
       if (isRecordsType(messageType)) {
         const recordScope = scope as DwnRecordsPermissionScope;
         if (recordScope.protocol !== protocol) {

package/src/store-data-protocols.ts

@@ -1,7 +1,7 @@
 import type { ProtocolDefinition } from '@enbox/dwn-sdk-js';
 
 export const IdentityProtocolDefinition: ProtocolDefinition = {
-  protocol  : 'http://identity.foundation/protocols/web5/identity-store',
+  protocol  : 'https://identity.foundation/protocols/web5/identity-store',
   published : false,
   types     : {
     portableDid: {
@@ -47,7 +47,7 @@ export const KeyDeliveryProtocolDefinition: ProtocolDefinition = {
 };
 
 export const JwkProtocolDefinition: ProtocolDefinition = {
-  protocol  : 'http://identity.foundation/protocols/web5/jwk-store',
+  protocol  : 'https://identity.foundation/protocols/web5/jwk-store',
   published : false,
   types     : {
     privateJwk: {

package/src/test-harness.ts

@@ -6,7 +6,7 @@ import type { KeyValueStore } from '@enbox/common';
 import type { Web5PlatformAgent } from './types/agent.js';
 
 import { Level } from 'level';
-import { DataStoreLevel, EventEmitterStream, MessageStoreLevel, ResumableTaskStoreLevel, StateIndexLevel } from '@enbox/dwn-sdk-js';
+import { DataStoreLevel, EventEmitterEventLog, MessageStoreLevel, ResumableTaskStoreLevel, StateIndexLevel } from '@enbox/dwn-sdk-js';
 import { DidDht, DidJwk, DidResolverCacheMemory } from '@enbox/dids';
 import { LevelStore, MemoryStore } from '@enbox/common';
 
@@ -193,8 +193,6 @@ export class PlatformAgentTestHarness {
             id              : 'dwn',
             type            : 'DecentralizedWebNode',
             serviceEndpoint : testDwnUrls,
-            enc             : '#enc',
-            sig             : '#sig',
           }
         ],
         verificationMethods: [
@@ -259,7 +257,7 @@ export class PlatformAgentTestHarness {
     // Note: There is no in-memory store for DWN, so we always use LevelDB-based disk stores.
     const dwnDataStore = new DataStoreLevel({ blockstoreLocation: testDataPath('DWN_DATASTORE') });
     const dwnStateIndex = new StateIndexLevel({ location: testDataPath('DWN_STATEINDEX') });
-    const dwnEventStream = new EventEmitterStream();
+    const dwnEventLog = new EventEmitterEventLog();
     const dwnResumableTaskStore = new ResumableTaskStoreLevel({ location: testDataPath('DWN_RESUMABLETASKSTORE') });
 
     const dwnMessageStore = new MessageStoreLevel({
@@ -273,7 +271,7 @@ export class PlatformAgentTestHarness {
       dataStore          : dwnDataStore,
       didResolver        : didApi,
       stateIndex         : dwnStateIndex,
-      eventStream        : dwnEventStream,
+      eventLog           : dwnEventLog,
       messageStore       : dwnMessageStore,
       resumableTaskStore : dwnResumableTaskStore
     });

package/src/types/dwn.ts

@@ -11,7 +11,6 @@ import type {
   MessagesSubscribeReply,
   MessagesSyncMessage,
   MessagesSyncReply,
-  MessageSubscriptionHandler,
   ProtocolsConfigureMessage,
   ProtocolsConfigureOptions,
   ProtocolsQueryMessage,
@@ -28,9 +27,9 @@ import type {
   RecordsSubscribeMessage,
   RecordsSubscribeOptions,
   RecordsSubscribeReply,
-  RecordSubscriptionHandler,
   RecordsWriteMessage,
   RecordsWriteOptions,
+  SubscriptionListener,
 } from '@enbox/dwn-sdk-js';
 
 import type { MessagesSyncOptions } from '@enbox/dwn-sdk-js';
@@ -54,38 +53,37 @@ import {
  * Represents a Decentralized Web Node (DWN) service in a DID Document.
  *
  * A DWN DID service is a specialized type of DID service with the `type` set to
- * `DecentralizedWebNode`. It includes specific properties `enc` and `sig` that are used to identify
- * the public keys that can be used to interact with the DID Subject. The values of these properties
- * are strings or arrays of strings containing one or more verification method `id` values present in
- * the same DID document. If the `enc` and/or `sig` properties are an array of strings, an entity
- * interacting with the DID subject is expected to use the verification methods in the order they
- * are listed.
+ * `DecentralizedWebNode`. Encryption and signing keys are resolved from the DID document's
+ * verification methods, not from the service entry.
+ *
+ * The `enc` and `sig` properties are optional legacy fields that may be present on existing
+ * DID documents for backward compatibility. New implementations should resolve keys from the
+ * DID document's verification methods by purpose (`keyAgreement` for encryption,
+ * `authentication`/`assertionMethod` for signing).
  *
  * @example
  * ```ts
  * const service: DwnDidService = {
  *   id: 'did:example:123#dwn',
  *   type: 'DecentralizedWebNode',
- *   serviceEndpoint: 'https://enbox-dwn.fly.dev',
- *   enc: 'did:example:123#key-1',
- *   sig: 'did:example:123#key-2'
+ *   serviceEndpoint: 'https://enbox-dwn.fly.dev'
  * }
  * ```
  *
- * @see {@link https://identity.foundation/decentralized-web-node/spec/ | DIF Decentralized Web Node (DWN) Specification}
+ * @see {@link https://github.com/enboxorg/dwn-spec | Enbox DWN Specification}
  */
 export interface DwnDidService extends DidService {
   /**
-   * One or more verification method `id` values that can be used to encrypt information
-   * intended for the DID subject.
+   * @deprecated Optional legacy field. Resolve encryption keys from the DID document's
+   * `keyAgreement` verification methods instead.
    */
   enc?: string | string[];
 
   /**
-   * One or more verification method `id` values that will be used by the DID subject to sign data
-   * or by another entity to verify signatures created by the DID subject.
+   * @deprecated Optional legacy field. Resolve signing keys from the DID document's
+   * `authentication` or `assertionMethod` verification methods instead.
    */
-  sig: string | string[];
+  sig?: string | string[];
 }
 
 export enum DwnInterface {
@@ -158,8 +156,8 @@ export interface DwnMessageReply {
 }
 
 export interface MessageHandler {
-  [DwnInterface.MessagesSubscribe] : MessageSubscriptionHandler;
-  [DwnInterface.RecordsSubscribe] : RecordSubscriptionHandler;
+  [DwnInterface.MessagesSubscribe] : SubscriptionListener;
+  [DwnInterface.RecordsSubscribe] : SubscriptionListener;
 
   // define all of them individually as undefined
   [DwnInterface.MessagesRead] : undefined;
@@ -273,7 +271,6 @@ export type {
   DataEncodedRecordsWriteMessage as DwnDataEncodedRecordsWriteMessage,
   MessageSigner as DwnSigner,
   MessageSubscription as DwnMessageSubscription,
-  MessageSubscriptionHandler as DwnMessageSubscriptionHandler,
   MessagesPermissionScope as DwnMessagesPermissionScope,
   PaginationCursor as DwnPaginationCursor,
   PermissionConditions as DwnPermissionConditions,
@@ -283,6 +280,7 @@ export type {
   ProtocolDefinition as DwnProtocolDefinition,
   ProtocolPermissionScope as DwnProtocolPermissionScope,
   PublicKeyJwk as DwnPublicKeyJwk,
-  RecordSubscriptionHandler as DwnRecordSubscriptionHandler,
   RecordsPermissionScope as DwnRecordsPermissionScope,
+  SubscriptionListener as DwnSubscriptionListener,
+  SubscriptionMessage as DwnSubscriptionMessage,
 } from '@enbox/dwn-sdk-js';