@enbox/agent 0.6.5 → 0.6.7

package/src/sync-replication-ledger.ts

@@ -21,7 +21,7 @@ const KEY_SEP = '^';
  */
 export class ReplicationLedger {
   private readonly db: AbstractLevel<string | Buffer | Uint8Array>;
-  private sublevel;
+  private readonly sublevel;
 
   constructor(db: AbstractLevel<string | Buffer | Uint8Array>) {
     this.db = db;
@@ -126,6 +126,31 @@ 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
   // ---------------------------------------------------------------------------

package/src/test-harness.ts

@@ -23,6 +23,7 @@ import { SyncEngineLevel } from './sync-engine-level.js';
 import { DwnDidStore, InMemoryDidStore } from './store-did.js';
 import { DwnIdentityStore, InMemoryIdentityStore } from './store-identity.js';
 import { DwnKeyStore, InMemoryKeyStore } from './store-key.js';
+import { InMemorySecretStore, VaultBackedSecretStore } from './secret-store.js';
 
 type StoreSetupResult = {
   agentVault: HdIdentityVault;
@@ -31,6 +32,9 @@ type StoreSetupResult = {
   identityApi: AgentIdentityApi<LocalKeyManager>;
   keyManager: LocalKeyManager;
   permissionsApi: AgentPermissionsApi;
+  secretsApi: InMemorySecretStore | VaultBackedSecretStore;
+  /** Backing KeyValueStore for VaultBackedSecretStore (for clear/close lifecycle). */
+  secretStore?: KeyValueStore<string, string>;
   vaultStore: KeyValueStore<string, string>;
 };
 
@@ -44,6 +48,8 @@ type PlatformAgentTestHarnessParams = {
   dwnStateIndex: StateIndexLevel;
   dwnMessageStore: MessageStoreLevel;
   dwnResumableTaskStore: ResumableTaskStoreLevel;
+  /** Backing KeyValueStore for VaultBackedSecretStore (disk mode only). */
+  secretStore?: KeyValueStore<string, string>;
   syncStore: AbstractLevel<string | Buffer | Uint8Array>;
   vaultStore: KeyValueStore<string, string>;
   dwnStores: {
@@ -64,6 +70,7 @@ export class PlatformAgentTestHarness {
   public dwnStateIndex: StateIndexLevel;
   public dwnMessageStore: MessageStoreLevel;
   public dwnResumableTaskStore: ResumableTaskStoreLevel;
+  public secretStore?: KeyValueStore<string, string>;
   public syncStore: AbstractLevel<string | Buffer | Uint8Array>;
   public vaultStore: KeyValueStore<string, string>;
 
@@ -87,6 +94,7 @@ export class PlatformAgentTestHarness {
     this.dwnDataStore = params.dwnDataStore;
     this.dwnStateIndex = params.dwnStateIndex;
     this.dwnMessageStore = params.dwnMessageStore;
+    this.secretStore = params.secretStore;
     this.syncStore = params.syncStore;
     this.vaultStore = params.vaultStore;
     this.dwnResumableTaskStore = params.dwnResumableTaskStore;
@@ -97,6 +105,12 @@ export class PlatformAgentTestHarness {
     // first stop any ongoing sync operations
     await this.agent.sync.stopSync();
 
+    // Drain any in-flight fire-and-forget eager-send promises dispatched by
+    // `AgentDwnApi.writeContextKeyRecord` so they cannot outlive the agent
+    // and touch a nulled `agentDid` or a cleared LevelDB store. Fast path
+    // when the tracker is empty (no pending sends).
+    await this.agent.dwn.drainPendingEagerSends();
+
     // @ts-expect-error since normally this property shouldn't be set to undefined.
     this.agent.agentDid = undefined;
     await this.didResolverCache.clear();
@@ -106,6 +120,7 @@ export class PlatformAgentTestHarness {
     await this.dwnResumableTaskStore.clear();
     await this.syncStore.clear();
     await this.vaultStore.clear();
+    if (this.secretStore) { await this.secretStore.clear(); }
     (this.agent.vault as any)['_cachedInitialized'] = undefined;
     await this.agent.permissions.clear();
     this.dwnStores.clear();
@@ -120,11 +135,12 @@ export class PlatformAgentTestHarness {
 
     // Easiest way to start with fresh in-memory stores is to re-instantiate Agent components.
     if (this.agentStores === 'memory') {
-      const { didApi, identityApi, permissionsApi, keyManager } = PlatformAgentTestHarness.useMemoryStores({ agent: this.agent });
+      const { didApi, identityApi, permissionsApi, keyManager, secretsApi } = PlatformAgentTestHarness.useMemoryStores({ agent: this.agent });
       this.agent.did = didApi;
       this.agent.identity = identityApi;
       this.agent.keyManager = keyManager;
       this.agent.permissions = permissionsApi;
+      this.agent.secrets = secretsApi;
     }
   }
 
@@ -148,11 +164,18 @@ export class PlatformAgentTestHarness {
   }
 
   public async closeStorage(): Promise<void> {
+    // Drain any in-flight fire-and-forget eager-send promises dispatched by
+    // `AgentDwnApi.writeContextKeyRecord` before closing the LevelDB-backed
+    // stores. Prevents orphan promises from hitting closed handles with
+    // `LEVEL_DATABASE_NOT_OPEN` after teardown. Fast path when empty.
+    await this.agent.dwn.drainPendingEagerSends();
+
     await this.didResolverCache.close();
     await this.dwnDataStore.close();
     await this.dwnStateIndex.close();
     await this.dwnMessageStore.close();
     await this.dwnResumableTaskStore.close();
+    if (this.secretStore) { await this.secretStore.close(); }
     await this.syncStore.close();
     await this.vaultStore.close();
   }
@@ -248,7 +271,9 @@ export class PlatformAgentTestHarness {
       keyManager,
       didResolverCache,
       vaultStore,
-      permissionsApi
+      permissionsApi,
+      secretsApi,
+      secretStore,
     } = (agentStores === 'memory')
       ? PlatformAgentTestHarness.useMemoryStores()
       : PlatformAgentTestHarness.useDiskStores({ testDataLocation, stores: dwnStores });
@@ -294,6 +319,7 @@ export class PlatformAgentTestHarness {
       keyManager,
       permissionsApi,
       rpcClient,
+      secretsApi,
       syncApi,
     });
 
@@ -307,8 +333,9 @@ export class PlatformAgentTestHarness {
       dwnMessageStore,
       dwnResumableTaskStore,
       dwnStores,
+      secretStore,
       syncStore,
-      vaultStore
+      vaultStore,
     });
   }
 
@@ -346,7 +373,13 @@ export class PlatformAgentTestHarness {
 
     const permissionsApi = new AgentPermissionsApi({ agent });
 
-    return { agentVault, didApi, didResolverCache, identityApi, keyManager, permissionsApi, vaultStore };
+    const secretStore = new LevelStore<string, string>({ location: testDataPath('SECRET_STORE') });
+    const secretsApi = new VaultBackedSecretStore({
+      vault : agentVault,
+      store : secretStore,
+    });
+
+    return { agentVault, didApi, didResolverCache, identityApi, keyManager, permissionsApi, secretsApi, secretStore, vaultStore };
   }
 
   private static useMemoryStores({ agent }: { agent?: EnboxPlatformAgent<LocalKeyManager> } = {}): StoreSetupResult {
@@ -369,6 +402,8 @@ export class PlatformAgentTestHarness {
 
     const permissionsApi = new AgentPermissionsApi({ agent });
 
-    return { agentVault, didApi, didResolverCache, identityApi, keyManager, permissionsApi, vaultStore };
+    const secretsApi = new InMemorySecretStore();
+
+    return { agentVault, didApi, didResolverCache, identityApi, keyManager, permissionsApi, secretsApi, vaultStore };
   }
 }

package/src/types/agent.ts

@@ -7,6 +7,7 @@ import type { AgentKeyManager } from './key-manager.js';
 import type { AgentPermissionsApi } from '../permissions-api.js';
 import type { EnboxRpc } from '@enbox/dwn-clients';
 import type { IdentityVault } from './identity-vault.js';
+import type { SecretStore } from '../secret-store.js';
 import type { SyncEngine } from './sync.js';
 import type { AgentDidApi, DidInterface, DidRequest, DidResponse } from '../did-api.js';
 import type { DwnInterface, DwnResponse, ProcessDwnRequest, SendDwnRequest } from './dwn.js';
@@ -169,6 +170,8 @@ export interface EnboxPlatformAgent<TKeyManager extends AgentKeyManager = AgentK
    */
   sync: SyncEngine;
 
+  /** Vault-backed secret store for classified credentials, encrypted at rest with the vault key. */
+  secrets: SecretStore;
   /**
    * An instance of {@link IdentityVault}, providing secure storage and management of an Enbox Agent's
    * DID and cryptographic keys.

package/src/types/sync.ts

@@ -11,9 +11,11 @@ export type SyncIdentityOptions = {
    */
   delegateDid?: string;
   /**
-   * The protocols that should be synced for this identity, if an empty array is provided, all messages for all protocols will be synced.
+   * The protocols that should be synced for this identity.
+   * - `'all'` — sync all protocols (full replica).
+   * - `string[]` — sync only the listed protocol URIs.
    */
-  protocols: string[];
+  protocols: 'all' | [string, ...string[]];
 };
 
 /**
@@ -65,10 +67,10 @@ export async function computeScopeId(scope: SyncScope): Promise<string> {
   if (scope.kind === 'protocol') {
     canonical.protocol = scope.protocol;
     if (scope.protocolPathPrefixes !== undefined) {
-      canonical.protocolPathPrefixes = [...new Set(scope.protocolPathPrefixes)].sort();
+      canonical.protocolPathPrefixes = [...new Set(scope.protocolPathPrefixes)].sort((a, b) => a.localeCompare(b));
     }
     if (scope.contextIdPrefixes !== undefined) {
-      canonical.contextIdPrefixes = [...new Set(scope.contextIdPrefixes)].sort();
+      canonical.contextIdPrefixes = [...new Set(scope.contextIdPrefixes)].sort((a, b) => a.localeCompare(b));
     }
   }
 
@@ -83,7 +85,11 @@ export async function computeScopeId(scope: SyncScope): Promise<string> {
   for (const b of hashArray) {
     base64 += String.fromCharCode(b);
   }
-  return btoa(base64).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  const result = btoa(base64).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);
 }
 
 // ---------------------------------------------------------------------------
@@ -323,13 +329,35 @@ export interface SyncEngine {
    */
   readonly connectivityState: SyncConnectivityState;
 
+  /**
+   * Whether at least one live pull or push subscription is open.
+   *
+   * This is specifically about live-mode subscriptions — it is `false` in
+   * poll mode and `false` when only the integrity timer remains (e.g. after
+   * the last identity was removed). Callers use this to avoid calling
+   * `startSync()` when live subscriptions are active, which would tear
+   * them all down and rebuild from scratch.
+   */
+  readonly hasActiveSubscriptions: boolean;
+
   /**
    * Register an identity to be managed by the SyncEngine for syncing.
-   * The options can define specific protocols that should only be synced, or a delegate DID that should be used to sign the sync messages.
+   * Callers must explicitly specify which protocols to sync (`'all'` for a
+   * full replica, or a list of protocol URIs) so that sync scope is always
+   * a deliberate choice rather than an invisible default.
+   *
+   * When live sync is active, the new identity is hot-added: its replication
+   * links are created and subscriptions opened immediately, without tearing
+   * down existing subscriptions for other identities. This enables
+   * multi-identity agents (e.g. ElectroBun desktop DWN, multi-persona dApps)
+   * to add identities at runtime without disrupting sync for others.
    */
-  registerIdentity(params: { did: string, options?: SyncIdentityOptions }): Promise<void>;
+  registerIdentity(params: { did: string, options: SyncIdentityOptions }): Promise<void>;
   /**
    * Unregister an identity from the SyncEngine, this will stop syncing messages for this identity.
+   *
+   * When live sync is active, the identity is hot-removed: its subscriptions
+   * are closed and runtime state cleaned up without affecting other identities.
    */
   unregisterIdentity(did: string): Promise<void>;
   /**

package/src/utils.ts

@@ -19,7 +19,7 @@ export async function getDwnServiceEndpointUrls(didUri: string, dereferencer: Di
       ? [serviceEndpoint]
       : Array.isArray(serviceEndpoint) && serviceEndpoint.every(endpoint => typeof endpoint === 'string')
       // If the service endpoint is an array of strings, use it as is.
-        ? serviceEndpoint as string[]
+        ? serviceEndpoint
         // If the service endpoint is neither a string nor an array of strings, return an empty array.
         : [];