@enbox/agent 0.1.8 → 0.2.0

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

@@ -250,7 +250,8 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
         jwe        : cekJwe,
         key        : Convert.string(oldPassword).toUint8Array(),
         crypto     : this.crypto,
-        keyManager : new LocalKeyManager()
+        keyManager : new LocalKeyManager(),
+        options    : { minP2cCount: 1 }, // Vault decrypts its own JWEs; no external-input floor needed.
       }));
       contentEncryptionKey = Convert.uint8Array(contentEncryptionKeyBytes).toObject() as Jwk;
 
@@ -297,7 +298,8 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
       jwe        : didJwe,
       key        : this._contentEncryptionKey!,
       crypto     : this.crypto,
-      keyManager : new LocalKeyManager()
+      keyManager : new LocalKeyManager(),
+      options    : { minP2cCount: 1 }, // Vault decrypts its own JWEs; no external-input floor needed.
     });
 
     // Convert the DID from a byte array to PortableDid format.
@@ -530,8 +532,6 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
           id              : 'dwn',
           type            : 'DecentralizedWebNode',
           serviceEndpoint : dwnEndpoints,
-          enc             : '#enc',
-          sig             : '#sig',
         }
       ];
     }
@@ -761,7 +761,8 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
         jwe        : cekJwe,
         key        : Convert.string(password).toUint8Array(),
         crypto     : this.crypto,
-        keyManager : new LocalKeyManager()
+        keyManager : new LocalKeyManager(),
+        options    : { minP2cCount: 1 }, // Vault decrypts its own JWEs; no external-input floor needed.
       });
       const contentEncryptionKey = Convert.uint8Array(contentEncryptionKeyBytes).toObject() as Jwk;
 

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/oidc.ts

@@ -410,7 +410,7 @@ async function verifyJwt({ jwt }: { jwt: string }): Promise<Record<string, unkno
  * using the encryption key passed via QR code.
  */
 const getAuthRequest = async (request_uri: string, encryption_key: string): Promise<Web5ConnectAuthRequest> => {
-  const authRequest = await fetch(request_uri);
+  const authRequest = await fetch(request_uri, { signal: AbortSignal.timeout(30_000) });
   const jwe = await authRequest.text();
   const jwt = await decryptAuthRequest({
     jwe,
@@ -832,6 +832,7 @@ async function submitAuthResponse(
     headers : {
       'Content-Type': 'application/x-www-form-urlencoded',
     },
+    signal: AbortSignal.timeout(30_000),
   });
 }
 

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/prototyping/crypto/jose/jwe-flattened.ts

@@ -270,7 +270,10 @@ export class FlattenedJwe {
         ? Convert.base64Url(jwe.encrypted_key).toUint8Array()
         : undefined;
 
-      cek = await JweKeyManagement.decrypt({ key, encryptedKey, joseHeader, keyManager, crypto });
+      cek = await JweKeyManagement.decrypt(
+        { key, encryptedKey, joseHeader, keyManager, crypto },
+        { minP2cCount: options.minP2cCount }
+      );
 
     } catch (error: any) {
       // If the error is a CryptoError with code "InvalidJwe" or "AlgorithmNotSupported", re-throw.

package/src/prototyping/crypto/jose/jwe.ts

@@ -33,6 +33,15 @@ export interface JweDecryptOptions {
    *
    */
   allowedEncValues?: string[];
+
+  /**
+   * Minimum acceptable PBES2 iteration count ("p2c") for key derivation during decryption.
+   * Per RFC 7518 Section 4.8.1.2, a minimum of 1000 is RECOMMENDED. Set to a lower value
+   * only for test environments where speed is prioritized over security.
+   *
+   * @default 1000
+   */
+  minP2cCount?: number;
 }
 
 /**
@@ -281,11 +290,12 @@ export interface JweKeyManagementDecryptParams<TKeyManager, TCrypto> {
    */
   joseHeader: JweHeaderParams;
 
-  /** Key Manager instanceß responsible for managing cryptographic keys. */
+  /** Key Manager instance responsible for managing cryptographic keys. */
   keyManager: TKeyManager;
 
   /** Crypto API instance that provides the necessary cryptographic operations. */
   crypto: TCrypto;
+
 }
 
 /**
@@ -424,8 +434,10 @@ export class JweKeyManagement {
    */
   public static async decrypt<TKeyManager extends KeyManager, TCrypto extends CryptoApi>({
     key, encryptedKey, joseHeader, crypto
-  }: JweKeyManagementDecryptParams<TKeyManager, TCrypto>
+  }: JweKeyManagementDecryptParams<TKeyManager, TCrypto>,
+  options?: { minP2cCount?: number }
   ): Promise<KeyIdentifier | Jwk> {
+    const minP2cCount = options?.minP2cCount ?? 1000;
     // Determine the Key Management Mode employed by the algorithm specified by the "alg"
     // (algorithm) Header Parameter.
     switch (joseHeader.alg) {
@@ -460,6 +472,16 @@ export class JweKeyManagement {
           throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JOSE Header "p2c" (PBES2 Count) is missing or not a number.');
         }
 
+        // Per RFC 7518, Section 4.8.1.2, a minimum iteration count of 1000 is RECOMMENDED.
+        // Enforce this floor to prevent an attacker from supplying a crafted JWE with a
+        // trivially low iteration count that would weaken key derivation.
+        if (joseHeader.p2c < minP2cCount) {
+          throw new CryptoError(
+            CryptoErrorCode.InvalidJwe,
+            `JOSE Header "p2c" (PBES2 Count) is ${joseHeader.p2c}, which is below the minimum of ${minP2cCount}.`
+          );
+        }
+
         if (typeof joseHeader.p2s !== 'string') {
           throw new CryptoError(CryptoErrorCode.InvalidJwe, 'JOSE Header "p2s" (PBES2 salt) is missing or not a string.');
         }

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/sync-api.ts

@@ -1,5 +1,5 @@
 import type { Web5PlatformAgent } from './types/agent.js';
-import type { SyncEngine, SyncIdentityOptions } from './types/sync.js';
+import type { StartSyncParams, SyncConnectivityState, SyncEngine, SyncIdentityOptions } from './types/sync.js';
 
 export type SyncApiParams = {
   agent?: Web5PlatformAgent;
@@ -41,6 +41,10 @@ export class AgentSyncApi implements SyncEngine {
     this._syncEngine.agent = agent;
   }
 
+  get connectivityState(): SyncConnectivityState {
+    return this._syncEngine.connectivityState;
+  }
+
   public async registerIdentity(params: { did: string; options?: SyncIdentityOptions }): Promise<void> {
     await this._syncEngine.registerIdentity(params);
   }
@@ -61,11 +65,11 @@ export class AgentSyncApi implements SyncEngine {
     return this._syncEngine.sync(direction);
   }
 
-  public startSync(params: { interval: string; }): Promise<void> {
+  public startSync(params: StartSyncParams): Promise<void> {
     return this._syncEngine.startSync(params);
   }
 
   public stopSync(timeout?: number): Promise<void> {
     return this._syncEngine.stopSync(timeout);
   }
-}
+}