@enbox/agent 0.6.5 → 0.6.6

package/src/dwn-api.ts

@@ -130,20 +130,20 @@ export class AgentDwnApi {
    * `undefined` in remote mode — all operations route through RPC to
    * the local DWN server endpoint.
    */
-  private _dwn?: Dwn;
+  private readonly _dwn?: Dwn;
 
   /**
    * The local DWN server endpoint for remote mode.
    * When set, `_dwn` is `undefined` and `processRequest()` routes
    * through `sendDwnRpcRequest()`.
    */
-  private _localDwnEndpoint?: string;
+  private readonly _localDwnEndpoint?: string;
 
   /**
    * Protocol definition cache — TTL 30 minutes. Protocols rarely change.
    * Keyed by `${tenantDid}~${protocolUri}`.
    */
-  private _protocolDefinitionCache = new TtlCache<string, ProtocolDefinition>({
+  private readonly _protocolDefinitionCache = new TtlCache<string, ProtocolDefinition>({
     ttl: 30 * 60 * 1000
   });
 
@@ -151,7 +151,7 @@ export class AgentDwnApi {
    * Context key cache — stores resolved context encryption key info for
    * multi-party protocols. Keyed by rootContextId. TTL 30 minutes.
    */
-  private _contextKeyCache = new TtlCache<string, {
+  private readonly _contextKeyCache = new TtlCache<string, {
     keyId: string;
     keyUri: KeyIdentifier;
     contextDerivationPath: string[];
@@ -162,7 +162,7 @@ export class AgentDwnApi {
    * where the current user is a participant (not the creator).
    * Keyed by `ctx~${authorDid}~${rootContextId}`. TTL 30 minutes.
    */
-  private _contextDerivedKeyCache = new TtlCache<string, DerivedPrivateJwk>({
+  private readonly _contextDerivedKeyCache = new TtlCache<string, DerivedPrivateJwk>({
     ttl: 30 * 60 * 1000
   });
 
@@ -176,7 +176,7 @@ export class AgentDwnApi {
    * granted read scopes for that delegate session.
    * TTL 24 hours (keys are re-populated on session restore).
    */
-  private _delegateDecryptionKeyCache = new TtlCache<string, {
+  private readonly _delegateDecryptionKeyCache = new TtlCache<string, {
     protocol: string;
     scope: { kind: 'protocol' } | { kind: 'protocolPath'; protocolPath: string; match: 'exact' };
     derivedPrivateKey: DerivedPrivateJwk;
@@ -190,12 +190,12 @@ export class AgentDwnApi {
    * Keyed by `dctx~${delegateDid}~${protocol}~${rootContextId}`.
    * TTL 24 hours (re-populated on session restore).
    */
-  private _delegateContextKeyCache = new TtlCache<string, DerivedPrivateJwk>({
+  private readonly _delegateContextKeyCache = new TtlCache<string, DerivedPrivateJwk>({
     ttl: 24 * 60 * 60 * 1000
   });
 
   /** Tracks which context key cache entries belong to which delegate DID. */
-  private _delegateContextKeyCacheIndex = new Map<string, string[]>();
+  private readonly _delegateContextKeyCacheIndex = new Map<string, string[]>();
 
   /**
    * Explicit registry of which multi-party protocols each delegate has
@@ -207,7 +207,7 @@ export class AgentDwnApi {
    * Unlike the context key cache, this registry is NOT time-limited —
    * it persists for the lifetime of the session.
    */
-  private _delegateMultiPartyProtocols = new Map<string, Set<string>>();
+  private readonly _delegateMultiPartyProtocols = new Map<string, Set<string>>();
 
   /**
    * Optional callback invoked when post-connect context keys are delivered
@@ -219,7 +219,7 @@ export class AgentDwnApi {
    * Cache of locally-managed DIDs (agent DID + identities). Used to decide
    * whether a target DID should be routed through the local DWN server.
    */
-  private _localManagedDidCache = new TtlCache<string, boolean>({
+  private readonly _localManagedDidCache = new TtlCache<string, boolean>({
     ttl: 30 * 60 * 1000
   });
 
@@ -229,6 +229,17 @@ export class AgentDwnApi {
   /** Lazy-initialized local DWN discovery instance. */
   private _localDwnDiscovery?: LocalDwnDiscovery;
 
+  /**
+   * Tracks fire-and-forget eager-send promises dispatched by
+   * `writeContextKeyRecord`. The set is consumed by `drainPendingEagerSends()`
+   * during test-harness teardown so orphan promises cannot outlive the agent
+   * and touch closed LevelDB handles or nulled state.
+   *
+   * Entries auto-remove on settlement via the `.finally` attached in
+   * `trackEagerSend`.
+   */
+  private readonly _pendingEagerSends: Set<Promise<void>> = new Set();
+
   constructor(params: DwnApiParams) {
     const { agent, localDwnStrategy = 'prefer' } = params;
 
@@ -535,11 +546,11 @@ export class AgentDwnApi {
       });
     }
 
-    // Post-write key delivery: detect new participants and write contextKey records.
-    await this.postWriteKeyDelivery(request, message, reply);
-
-    // Auto-decrypt reply data if encryption is enabled (Component 7)
-    await this.maybeDecryptReply(request, reply);
+    // Post-write key delivery and reply decryption are independent — run in parallel.
+    await Promise.all([
+      this.postWriteKeyDelivery(request, message, reply),
+      this.maybeDecryptReply(request, reply),
+    ]);
 
     // Returns an object containing the reply from processing the message, the original message,
     // and the content identifier (CID) of the message.
@@ -629,9 +640,9 @@ export class AgentDwnApi {
     let resubscribeFactory: ResubscribeFactory | undefined;
     if (subscriptionHandler !== undefined && !('messageCid' in request)) {
       resubscribeFactory = async (cursor?: ProgressToken): Promise<GenericMessage> => {
-        const resumeParams = cursor !== undefined
-          ? { ...request.messageParams, cursor } as DwnMessageParams[T]
-          : request.messageParams;
+        const resumeParams = cursor === undefined
+          ? request.messageParams
+          : { ...request.messageParams, cursor } as DwnMessageParams[T];
 
         const resumeRequest: ProcessDwnRequest<T> = { ...request, messageParams: resumeParams };
         const { message: resumeMessage } = await this.constructDwnMessage({ request: resumeRequest });
@@ -756,8 +767,13 @@ export class AgentDwnApi {
         && !isExternallyAuthored
         && this.hasEligibleDelegatesForProtocol(writeParams.protocol);
 
-      if (newParticipants.size > 0 || needsDelegateDelivery) {
-        // Derive the context key once (shared for participant + delegate delivery).
+      // Cross-device delegate delivery (via DWN) runs whenever the owner
+      // creates a root record in a multi-party context, regardless of
+      // whether same-process delegates exist.
+      const needsCrossDeviceDelivery = isMultiParty && isRootRecord && !isExternallyAuthored;
+
+      // Derive the context key once and share it across all delivery paths.
+      if (newParticipants.size > 0 || needsDelegateDelivery || needsCrossDeviceDelivery) {
         const { keyId, keyUri } = await getEncryptionKeyInfoFn(this.agent, request.target);
         const contextDerivationPath = [
           KeyDerivationScheme.ProtocolContext,
@@ -818,38 +834,18 @@ export class AgentDwnApi {
             writeParams.protocol, rootContextId, contextKeyPayload,
           );
         }
-      }
 
-      // --- Cross-device delegate context key delivery (#826) ---
-      // Query grants to find ALL eligible delegates (including those on
-      // other agents) and write contextKey records to the DWN.
-      // This is separate from same-process delivery: it discovers delegates
-      // from the owner's DWN grants, not just in-memory caches. It must
-      // run even when no same-process delegates or participants exist.
-      if (isMultiParty && isRootRecord && !isExternallyAuthored) {
-        // Derive the context key if not already done above.
-        const { keyId: xdKeyId, keyUri: xdKeyUri } = await getEncryptionKeyInfoFn(this.agent, request.target);
-        const xdContextDerivationPath = [
-          KeyDerivationScheme.ProtocolContext,
-          rootContextId,
-        ];
-        const xdContextDerivedPrivateKeyBytes =
-          await this.agent.keyManager.derivePrivateKeyBytes({
-            keyUri         : xdKeyUri,
-            derivationPath : xdContextDerivationPath,
-          });
-        const xdContextDerivedPrivateJwk =
-          await X25519.bytesToPrivateKey({ privateKeyBytes: xdContextDerivedPrivateKeyBytes });
-        const xdContextKeyPayload: DerivedPrivateJwk = {
-          rootKeyId         : xdKeyId,
-          derivationScheme  : KeyDerivationScheme.ProtocolContext,
-          derivationPath    : xdContextDerivationPath,
-          derivedPrivateKey : xdContextDerivedPrivateJwk as PrivateKeyJwk,
-        };
-
-        await this.deliverContextKeyToDelegatesViaDwn(
-          request.target, writeParams.protocol, rootContextId, xdContextKeyPayload,
-        );
+        // --- Cross-device delegate context key delivery (#826) ---
+        // Query grants to find ALL eligible delegates (including those on
+        // other agents) and write contextKey records to the DWN.
+        // This is separate from same-process delivery: it discovers delegates
+        // from the owner's DWN grants, not just in-memory caches. It must
+        // run even when no same-process delegates or participants exist.
+        if (needsCrossDeviceDelivery) {
+          await this.deliverContextKeyToDelegatesViaDwn(
+            request.target, writeParams.protocol, rootContextId, contextKeyPayload,
+          );
+        }
       }
     } catch (detectionError: any) {
       // Participant detection failure is non-fatal — the record is still stored.
@@ -1226,8 +1222,22 @@ export class AgentDwnApi {
     let dwnMessage: DwnMessageInstance[T];
     const dwnMessageConstructor = dwnMessageConstructors[request.messageType];
 
-    // if there is no raw message provided, we need to create the dwn message
-    if (!rawMessage) {
+    // if a raw message is provided, parse it; otherwise create a new dwn message
+    if (rawMessage) {
+      dwnMessage = await dwnMessageConstructor.parse(rawMessage);
+      if (isRecordsWrite(dwnMessage) && request.signAsOwner) {
+        // if we are signing as owner, we use the author's signer
+        const signer = await this.getSigner(request.author);
+        await dwnMessage.signAsOwner(signer);
+      } else if (request.granteeDid && isRecordsWrite(dwnMessage) && request.signAsOwnerDelegate) {
+        // if we are signing as owner delegate, we use the grantee's signer and the provided delegated grant
+        const signer = await this.getSigner(request.granteeDid);
+
+        //if we have reached here, the presence of the grant params has already been checked
+        const messageParams = request.messageParams as DwnMessageParams[DwnInterface.RecordsWrite];
+        await dwnMessage.signAsOwnerDelegate(signer, messageParams.delegatedGrant!);
+      }
+    } else {
       if (request.messageParams === undefined) {
         throw new Error('AgentDwnApi: messageParams must be provided when rawMessage is not given.');
       }
@@ -1290,21 +1300,6 @@ export class AgentDwnApi {
         // Cache context key info for subsequent writes in this context
         this._contextKeyCache.set(contextId, { keyId, keyUri, contextDerivationPath });
       }
-
-    } else {
-      dwnMessage = await dwnMessageConstructor.parse(rawMessage);
-      if (isRecordsWrite(dwnMessage) && request.signAsOwner) {
-        // if we are signing as owner, we use the author's signer
-        const signer = await this.getSigner(request.author);
-        await dwnMessage.signAsOwner(signer);
-      } else if (request.granteeDid && isRecordsWrite(dwnMessage) && request.signAsOwnerDelegate) {
-        // if we are signing as owner delegate, we use the grantee's signer and the provided delegated grant
-        const signer = await this.getSigner(request.granteeDid);
-
-        //if we have reached here, the presence of the grant params has already been checked
-        const messageParams = request.messageParams as DwnMessageParams[DwnInterface.RecordsWrite];
-        await dwnMessage.signAsOwnerDelegate(signer, messageParams.delegatedGrant!);
-      }
     }
 
     return {
@@ -1603,7 +1598,7 @@ export class AgentDwnApi {
    * Cache for key delivery protocol installation status per tenant.
    * Once confirmed installed, we skip re-checking for 21 days.
    */
-  private _keyDeliveryProtocolInstalledCache = new TtlCache<string, boolean>({
+  private readonly _keyDeliveryProtocolInstalledCache = new TtlCache<string, boolean>({
     ttl : 21 * 24 * 60 * 60 * 1000,
     max : 1000,
   });
@@ -1946,6 +1941,48 @@ export class AgentDwnApi {
     }
   }
 
+  /**
+   * Registers a fire-and-forget eager-send promise in the in-flight tracker so
+   * it can be awaited by `drainPendingEagerSends()` during teardown. The entry
+   * auto-removes on settlement via `.finally`.
+   *
+   * The promise is returned **unchanged** so callers can still chain `.catch`
+   * on it for observability (e.g. the existing `console.warn` on failure).
+   *
+   * @param p - The eager-send promise to track. Must always resolve (callers
+   *   are expected to attach a `.catch` handler before passing).
+   * @returns The same `p`, unchanged.
+   */
+  private trackEagerSend(p: Promise<void>): Promise<void> {
+    this._pendingEagerSends.add(p);
+    p.finally((): void => { this._pendingEagerSends.delete(p); });
+    return p;
+  }
+
+  /**
+   * Waits for all currently-tracked eager-send promises to settle. Used by
+   * the test harness during teardown (`clearStorage()`/`closeStorage()`) to
+   * prevent orphan promises from touching closed stores or nulled state.
+   *
+   * Snapshot semantics: awaits only the sends tracked at the moment of
+   * invocation. Sends registered **after** this call begins are not joined
+   * into its drain — a subsequent `drainPendingEagerSends()` is needed to
+   * await them.
+   *
+   * Fast path: when no sends are tracked, resolves immediately without
+   * invoking `Promise.allSettled([])`.
+   *
+   * @returns A promise that resolves to `undefined` once all snapshotted
+   *   sends have settled. Never rejects (uses `allSettled` semantics).
+   */
+  public async drainPendingEagerSends(): Promise<void> {
+    if (this._pendingEagerSends.size === 0) {
+      return;
+    }
+    const snapshot = [...this._pendingEagerSends];
+    await Promise.allSettled(snapshot);
+  }
+
   /**
    * Writes a `contextKey` record to the owner's DWN, delivering an encrypted
    * context key to a participant.
@@ -1966,6 +2003,7 @@ export class AgentDwnApi {
       this.processRequest.bind(this),
       this.ensureKeyDeliveryProtocol.bind(this),
       this.eagerSendContextKeyRecord.bind(this),
+      this.trackEagerSend.bind(this),
     );
   }
 

package/src/dwn-discovery-payload.ts

@@ -276,10 +276,11 @@ function stringToBase64Url(input: string): string {
   for (let i = 0; i < bytes.length; i++) {
     binary += String.fromCharCode(bytes[i]);
   }
-  return btoa(binary)
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=+$/, '');
+  const result = btoa(binary).replaceAll('+', '-').replaceAll('/', '_');
+  // Strip trailing '=' padding without regex quantifiers (avoids ReDoS scanners).
+  let end = result.length;
+  while (end > 0 && result.codePointAt(end - 1) === 61) { end--; } // 61 === '='
+  return end === result.length ? result : result.slice(0, end);
 }
 
 /**

package/src/dwn-key-delivery.ts

@@ -116,6 +116,9 @@ export async function ensureKeyDeliveryProtocol(
  * @param processRequest - The agent's processRequest method (bound)
  * @param ensureProtocol - Function to ensure key delivery protocol is installed
  * @param eagerSend - Function to eagerly send the record to the remote DWN
+ * @param trackEagerSend - Tracker callback that registers the fire-and-forget
+ *   eager-send promise so it can be awaited during teardown via
+ *   `AgentDwnApi.drainPendingEagerSends()`. Returns the same promise unchanged.
  * @returns The recordId of the written contextKey record
  */
 export async function writeContextKeyRecord(
@@ -124,6 +127,7 @@ export async function writeContextKeyRecord(
   processRequest: ProcessRequestFn,
   ensureProtocol: (tenantDid: string) => Promise<void>,
   eagerSend: (tenantDid: string, message: DwnMessage[DwnInterface.RecordsWrite]) => Promise<void>,
+  trackEagerSend: (p: Promise<void>) => Promise<void>,
 ): Promise<string> {
   const { tenantDid, recipientDid, contextKeyData, sourceProtocol, sourceContextId, recipientKeyDeliveryPublicKey } = params;
 
@@ -198,12 +202,14 @@ export async function writeContextKeyRecord(
   // Eagerly send the contextKey record to the tenant's remote DWN so that
   // participants can fetch it immediately without waiting for sync.
   // This is fire-and-forget — sync will guarantee eventual consistency.
-  eagerSend(tenantDid, message).catch((err: Error) => {
+  // `trackEagerSend` registers the promise with `AgentDwnApi` so it can be
+  // drained during teardown (prevents orphan promises leaking past close).
+  trackEagerSend(eagerSend(tenantDid, message).catch((err: Error) => {
     console.warn(
       `AgentDwnApi: Eager send of contextKey record '${message.recordId}' ` +
       `to remote DWN failed: ${err.message}. Sync will deliver it later.`
     );
-  });
+  }));
 
   return message.recordId;
 }

package/src/enbox-connect-protocol.ts

@@ -435,18 +435,21 @@ async function decryptRequest({
 // Encryption: response (ECDH shared key + optional PIN)
 // ---------------------------------------------------------------------------
 
-/** Derives a shared ECDH key for encrypting/decrypting the connect response. */
-async function deriveSharedKey(
+/**
+ * Core ECDH key derivation from a raw public key JWK.
+ *
+ * Converts both keys to X25519, performs ECDH, and derives the final
+ * symmetric key via HKDF-SHA-256.
+ */
+async function deriveSharedKeyFromJwk(
   privateKeyDid: BearerDid,
-  publicKeyDid: DidDocument
+  publicKeyJwk: Jwk
 ): Promise<Uint8Array> {
   const privatePortableDid = await privateKeyDid.export();
-
-  const publicJwk = publicKeyDid.verificationMethod?.[0].publicKeyJwk!;
   const privateJwk = privatePortableDid.privateKeys?.[0]!;
-  publicJwk.alg = 'EdDSA';
+  const pubJwk = { ...publicKeyJwk, alg: 'EdDSA' };
 
-  const publicX25519 = await Ed25519.convertPublicKeyToX25519({ publicKey: publicJwk });
+  const publicX25519 = await Ed25519.convertPublicKeyToX25519({ publicKey: pubJwk });
   const privateX25519 = await Ed25519.convertPrivateKeyToX25519({ privateKey: privateJwk });
 
   const sharedKey = await X25519.sharedSecret({
@@ -463,6 +466,15 @@ async function deriveSharedKey(
   });
 }
 
+/** Derives a shared ECDH key for encrypting/decrypting the connect response. */
+async function deriveSharedKey(
+  privateKeyDid: BearerDid,
+  publicKeyDid: DidDocument
+): Promise<Uint8Array> {
+  const publicJwk = publicKeyDid.verificationMethod?.[0].publicKeyJwk!;
+  return deriveSharedKeyFromJwk(privateKeyDid, publicJwk);
+}
+
 /**
  * Encrypts the connect response JWT.
  *
@@ -475,20 +487,29 @@ async function deriveSharedKey(
 async function encryptResponse({
   jwt,
   encryptionKey,
-  delegateDidKeyId,
+  delegatePublicKeyJwk,
   pin,
 }: {
   jwt: string;
   encryptionKey: Uint8Array;
-  delegateDidKeyId: string;
+  delegatePublicKeyJwk: Jwk;
   pin?: string;
 }): Promise<string> {
+  // Include only the minimum key material (kty, crv, x) in the ephemeral
+  // public key header.  This avoids leaking DID-level identifiers (kid,
+  // alg, etc.) that would let the relay correlate sessions or resolve
+  // the delegate DID.  See https://github.com/enboxorg/enbox/issues/890
+  const epk: Jwk = {
+    kty : delegatePublicKeyJwk.kty,
+    crv : delegatePublicKeyJwk.crv,
+    x   : delegatePublicKeyJwk.x,
+  };
   const protectedHeader = {
     alg : 'dir',
     cty : 'JWT',
     enc : 'XC20P',
     typ : 'JWT',
-    kid : delegateDidKeyId,
+    epk,
   };
   const nonce = CryptoUtils.randomBytes(24);
 
@@ -533,16 +554,12 @@ async function decryptResponse(
     authenticationTagB64U,
   ] = jwe.split('.');
 
-  const header = Convert.base64Url(protectedHeaderB64U).toObject() as Jwk;
-  if (!header.kid) {
-    throw new Error('Connect: JWE protected header is missing required "kid" property.');
+  const header = Convert.base64Url(protectedHeaderB64U).toObject() as Record<string, unknown>;
+  if (!header.epk || typeof header.epk !== 'object') {
+    throw new Error('Connect: JWE protected header is missing required "epk" property.');
   }
-  const delegateResolvedDid = await DidJwk.resolve(header.kid.split('#')[0]);
 
-  const sharedKey = await EnboxConnectProtocol.deriveSharedKey(
-    clientDid,
-    delegateResolvedDid.didDocument!
-  );
+  const sharedKey = await deriveSharedKeyFromJwk(clientDid, header.epk as Jwk);
 
   // Build AAD — include PIN if provided (must match what was used during encryption).
   const aadObject = pin
@@ -1297,9 +1314,9 @@ async function submitConnectResponse(
 
   logger.log('Encrypting connect response...');
   const encryptedResponse = await EnboxConnectProtocol.encryptResponse({
-    jwt              : responseObjectJwt!,
-    encryptionKey    : sharedKey,
-    delegateDidKeyId : delegateBearerDid.document.verificationMethod![0].id,
+    jwt                  : responseObjectJwt,
+    encryptionKey        : sharedKey,
+    delegatePublicKeyJwk : delegateBearerDid.document.verificationMethod![0].publicKeyJwk!,
     pin,
   });
 

package/src/enbox-user-agent.ts

@@ -3,6 +3,7 @@ import type { BearerDid } from '@enbox/dids';
 import type { EnboxPlatformAgent } from './types/agent.js';
 import type { EnboxRpc } from '@enbox/dwn-clients';
 import type { LocalDwnStrategy } from './local-dwn.js';
+import type { SecretStore } from './secret-store.js';
 import type { SyncEngine } from './types/sync.js';
 import type { DidInterface, DidRequest, DidResponse } from './did-api.js';
 import type { DwnInterface, DwnResponse, ProcessDwnRequest, SendDwnRequest } from './types/dwn.js';
@@ -23,6 +24,7 @@ import { LevelStore } from '@enbox/common';
 import { LocalKeyManager } from './local-key-manager.js';
 import { SyncEngineLevel } from './sync-engine-level.js';
 import { DidDht, DidJwk } from '@enbox/dids';
+import { InMemorySecretStore, VaultBackedSecretStore } from './secret-store.js';
 
 /**
  * Initialization parameters for {@link EnboxUserAgent}, including an optional recovery phrase that
@@ -84,6 +86,8 @@ export type AgentParams<TKeyManager extends AgentKeyManager = LocalKeyManager> =
   permissionsApi: AgentPermissionsApi;
   /** Remote procedure call (RPC) client used to communicate with other Enbox services. */
   rpcClient: EnboxRpc;
+  /** Vault-backed secret store for classified credentials. */
+  secretsApi?: SecretStore;
   /** Facilitates data synchronization of DWN records between nodes. */
   syncApi: SyncEngine;
 };
@@ -110,6 +114,7 @@ export class EnboxUserAgent<TKeyManager extends AgentKeyManager = LocalKeyManage
   public keyManager: TKeyManager;
   public permissions: AgentPermissionsApi;
   public rpc: EnboxRpc;
+  public secrets: SecretStore;
   public sync: SyncEngine;
   public vault: HdIdentityVault;
 
@@ -124,6 +129,7 @@ export class EnboxUserAgent<TKeyManager extends AgentKeyManager = LocalKeyManage
     this.keyManager = params.keyManager;
     this.permissions = params.permissionsApi;
     this.rpc = params.rpcClient;
+    this.secrets = params.secretsApi ?? new InMemorySecretStore();
     this.sync = params.syncApi;
     this.vault = params.agentVault;
 
@@ -157,7 +163,7 @@ export class EnboxUserAgent<TKeyManager extends AgentKeyManager = LocalKeyManage
     dataPath = 'DATA/AGENT',
     localDwnStrategy,
     localDwnEndpoint,
-    agentDid, agentVault, cryptoApi, didApi, dwnApi, identityApi, keyManager, permissionsApi, rpcClient, syncApi
+    agentDid, agentVault, cryptoApi, didApi, dwnApi, identityApi, keyManager, permissionsApi, rpcClient, secretsApi, syncApi
   }: CreateUserAgentParams = {}
   ): Promise<EnboxUserAgent> {
 
@@ -166,6 +172,11 @@ export class EnboxUserAgent<TKeyManager extends AgentKeyManager = LocalKeyManage
       store                   : new LevelStore<string, string>({ location: `${dataPath}/VAULT_STORE` })
     });
 
+    secretsApi ??= new VaultBackedSecretStore({
+      vault : agentVault,
+      store : new LevelStore<string, string>({ location: `${dataPath}/SECRET_STORE` }),
+    });
+
     cryptoApi ??= new AgentCryptoApi();
 
     didApi ??= new AgentDidApi({
@@ -211,11 +222,12 @@ export class EnboxUserAgent<TKeyManager extends AgentKeyManager = LocalKeyManage
       cryptoApi,
       didApi,
       dwnApi,
+      identityApi,
       keyManager,
       permissionsApi,
-      identityApi,
       rpcClient,
-      syncApi
+      secretsApi,
+      syncApi,
     });
   }
 

package/src/hd-identity-vault.ts

@@ -1,7 +1,8 @@
-import type { DidDhtCreateOptions } from '@enbox/dids';
 import type { Jwk } from '@enbox/crypto';
 import type { KeyValueStore } from '@enbox/common';
 
+import type { DidDhtCreateOptions, PortableDid } from '@enbox/dids';
+
 import { HDKey } from 'ed25519-keygen/hdkey';
 import { wordlist } from '@scure/bip39/wordlists/english';
 import { BearerDid, DidDht, isPortableDid } from '@enbox/dids';
@@ -142,10 +143,10 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
   public crypto = new AgentCryptoApi();
 
   /** Determines the computational intensity of the key derivation process. */
-  private _keyDerivationWorkFactor: number;
+  private readonly _keyDerivationWorkFactor: number;
 
   /** The underlying key-value store for the vault's encrypted content. */
-  private _store: KeyValueStore<string, string>;
+  private readonly _store: KeyValueStore<string, string>;
 
   /** The cryptographic key used to encrypt and decrypt the vault's content securely. */
   private _contentEncryptionKey: Jwk | undefined;
@@ -158,6 +159,14 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
    */
   private _cachedInitialized: boolean | undefined;
 
+  /**
+   * Cached decrypted PortableDid from the last successful {@link getDid} call.
+   * Caching the PortableDid (not the BearerDid) avoids the expensive JWE
+   * decrypt + LevelDB read on every call, while still returning a fresh
+   * BearerDid instance each time so callers cannot mutate shared state.
+   */
+  private _cachedPortableDid: PortableDid | undefined;
+
   /**
    * Constructs an instance of `HdIdentityVault`, initializing the key derivation factor and data
    * store. It sets the default key derivation work factor and initializes the internal data store,
@@ -298,26 +307,34 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
       throw new Error(`HdIdentityVault: Vault has not been initialized and unlocked.`);
     }
 
-    // Retrieve the encrypted DID record as compact JWE from the vault store.
-    const didJwe = await this.getStoredDid();
+    // If the decrypted PortableDid is not yet cached, decrypt it from the
+    // vault store.  This avoids the expensive LevelDB read + JWE decrypt on
+    // every call while the vault is unlocked.
+    if (!this._cachedPortableDid) {
+      const didJwe = await this.getStoredDid();
 
-    // Decrypt the compact JWE to obtain the PortableDid as a byte array.
-    const { plaintext: portableDidBytes } = await CompactJwe.decrypt({
-      jwe        : didJwe,
-      key        : this._contentEncryptionKey!,
-      crypto     : this.crypto,
-      keyManager : new LocalKeyManager(),
-      options    : { minP2cCount: 1 }, // Vault decrypts its own JWEs; no external-input floor needed.
-    });
+      const { plaintext: portableDidBytes } = await CompactJwe.decrypt({
+        jwe        : didJwe,
+        key        : this._contentEncryptionKey!,
+        crypto     : this.crypto,
+        keyManager : new LocalKeyManager(),
+        options    : { minP2cCount: 1 }, // Vault decrypts its own JWEs; no external-input floor needed.
+      });
+
+      const portableDid = Convert.uint8Array(portableDidBytes).toObject();
+      if (!isPortableDid(portableDid)) {
+        throw new Error('HdIdentityVault: Unable to decode malformed DID in identity vault');
+      }
 
-    // Convert the DID from a byte array to PortableDid format.
-    const portableDid = Convert.uint8Array(portableDidBytes).toObject();
-    if (!isPortableDid(portableDid)) {
-      throw new Error('HdIdentityVault: Unable to decode malformed DID in identity vault');
+      this._cachedPortableDid = portableDid;
     }
 
-    // Return the DID in Bearer DID format.
-    return await BearerDid.import({ portableDid });
+    // Always return a fresh BearerDid from a deep copy of the cached
+    // PortableDid.  BearerDid is mutable (document, metadata, keyManager
+    // are public) and BearerDid.import() takes document/metadata by
+    // reference, so without the clone a caller mutating a returned DID
+    // would corrupt the cache for all subsequent getDid() calls.
+    return await BearerDid.import({ portableDid: structuredClone(this._cachedPortableDid) });
   }
 
   /**
@@ -661,6 +678,7 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
     // Clear the vault content encryption key (CEK), effectively locking the vault.
     if (this._contentEncryptionKey) {this._contentEncryptionKey.k = '';}
     this._contentEncryptionKey = undefined;
+    this._cachedPortableDid = undefined;
   }
 
   /**
@@ -767,8 +785,16 @@ export class HdIdentityVault implements IdentityVault<{ InitializeResult: string
    *         incorrect.
    */
   public async unlock({ password }: { password: string }): Promise<void> {
-    // Lock the vault.
-    await this.lock();
+    // Verify the vault has been initialized before attempting to unlock.
+    if (await this.isInitialized() === false) {
+      throw new Error(`HdIdentityVault: Unable to unlock the vault. Vault has not been initialized.`);
+    }
+
+    // Lock the vault if not already locked — avoids an unnecessary
+    // redundant isInitialized() store read inside lock().
+    if (!this.isLocked()) {
+      await this.lock();
+    }
 
     // Retrieve the content encryption key (CEK) record as a compact JWE from the data store.
     const cekJwe = await this.getStoredContentEncryptionKey();