@enbox/agent 0.5.16 → 0.6.0

package/src/permissions-api.ts

@@ -244,9 +244,16 @@ export class AgentPermissionsApi implements PermissionsApi {
       requestId   : createGrantParams.requestId,
       description : createGrantParams.description,
       delegated,
-      scope       : createGrantParams.scope
+      scope       : createGrantParams.scope,
     };
 
+    // Attach delegate key-delivery metadata to the grant data payload.
+    // This is stored in the grant's encoded data (not tags) to avoid
+    // SQL column size limits on tag values.
+    if (createGrantParams.delegateKeyDelivery) {
+      permissionGrantData.delegateKeyDelivery = createGrantParams.delegateKeyDelivery;
+    }
+
     const permissionsGrantBytes = Convert.object(permissionGrantData).toUint8Array();
 
     const messageParams: DwnMessageParams[DwnInterface.RecordsWrite] = {
@@ -346,12 +353,17 @@ export class AgentPermissionsApi implements PermissionsApi {
       tags
     };
 
+    if (params.permissionGrantId) {
+      messageParams.permissionGrantId = params.permissionGrantId;
+    }
+
     const { reply, message } = await this.agent.processDwnRequest({
       store,
       author,
       target      : author,
       messageType : DwnInterface.RecordsWrite,
       messageParams,
+      granteeDid  : params.granteeDid,
       dataStream  : new Blob([ permissionRevocationBytes as BlobPart ])
     });
 

package/src/sync-engine-level.ts

@@ -10,8 +10,8 @@ import { Encoder, hashToHex, initDefaultHashes, Message } from '@enbox/dwn-sdk-j
 
 import type { ClosureEvaluationContext } from './sync-closure-types.js';
 import type { PermissionsApi } from './types/permissions.js';
+import type { DeadLetterCategory, DeadLetterEntry, PushResult, ReplicationLinkState, StartSyncParams, SyncConnectivityState, SyncEngine, SyncEvent, SyncEventListener, SyncHealthSummary, SyncIdentityOptions, SyncMode, SyncScope } from './types/sync.js';
 import type { EnboxAgent, EnboxPlatformAgent } from './types/agent.js';
-import type { PushResult, ReplicationLinkState, StartSyncParams, SyncConnectivityState, SyncEngine, SyncEvent, SyncEventListener, SyncIdentityOptions, SyncMode, SyncScope } from './types/sync.js';
 
 import { evaluateClosure } from './sync-closure-resolver.js';
 import { MAX_PENDING_TOKENS } from './types/sync.js';
@@ -268,6 +268,14 @@ export class SyncEngineLevel implements SyncEngine {
   /** Backoff multiplier for consecutive failures (caps at 4x the configured interval). */
   private static readonly MAX_BACKOFF_MULTIPLIER = 4;
 
+  /**
+   * Bound browser event handlers so they can be added and removed.
+   * Set in `startBrowserConnectivityListeners`, cleared in `stopBrowserConnectivityListeners`.
+   */
+  private _onOnline?: () => void;
+  private _onOffline?: () => void;
+  private _onVisibilityChange?: () => void;
+
   constructor({ agent, dataPath, db }: SyncEngineLevelParams) {
     this._agent = agent;
     this._permissionsApi = new AgentPermissionsApi({ agent: agent as EnboxAgent });
@@ -282,6 +290,11 @@ export class SyncEngineLevel implements SyncEngine {
     return this._ledger;
   }
 
+  /** LevelDB sublevel for permanently failed messages (dead letters). */
+  private get _deadLetters(): AbstractLevel<string | Buffer | Uint8Array, string, string> {
+    return this._db.sublevel('deadLetters') as unknown as AbstractLevel<string | Buffer | Uint8Array, string, string>;
+  }
+
   /**
    * Retrieves the `EnboxPlatformAgent` execution context.
    *
@@ -584,6 +597,10 @@ export class SyncEngineLevel implements SyncEngine {
    * 4. Schedules an infrequent SMT integrity check at `interval`.
    */
   private async startLiveSync(intervalMilliseconds: number): Promise<void> {
+    // Step 0: Register browser connectivity listeners for instant recovery
+    // on network switch, sleep/wake, or tab foregrounding. No-op in Node.
+    this.startBrowserConnectivityListeners();
+
     // Step 1: Initial SMT catch-up.
     try {
       await this.sync();
@@ -980,6 +997,12 @@ export class SyncEngineLevel implements SyncEngine {
       const prevRepairConnectivity = link.connectivity;
       link.connectivity = 'online';
       await this.ledger.setStatus(link, 'live');
+
+      // Auto-clear dead letters for this link — repair has verified
+      // convergence via SMT reconciliation so any previously recorded
+      // failures (closure, push-exhausted, pull-processing) for this
+      // specific link are no longer current.
+      void this.clearDeadLettersForLink(did, dwnUrl, protocol);
       this.emitEvent({ type: 'repair:completed', tenantDid: did, remoteEndpoint: dwnUrl, protocol });
       if (prevRepairConnectivity !== 'online') {
         this.emitEvent({ type: 'link:connectivity-change', tenantDid: did, remoteEndpoint: dwnUrl, protocol, from: prevRepairConnectivity, to: 'online' });
@@ -1095,7 +1118,112 @@ export class SyncEngineLevel implements SyncEngine {
   /**
    * Tears down all live subscriptions and push listeners.
    */
+  // ---------------------------------------------------------------------------
+  // Browser connectivity: online/offline + visibilitychange
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Registers browser `online`, `offline`, and `visibilitychange` event
+   * listeners to detect connectivity changes that WebSocket `close` events
+   * miss (NAT timeout, network switch, sleep/wake). Safe to call in Node —
+   * the guards skip registration when browser APIs are unavailable.
+   */
+  private startBrowserConnectivityListeners(): void {
+    this.stopBrowserConnectivityListeners();
+
+    // Guard: only run in browser environments with the required APIs.
+    if (typeof globalThis.addEventListener !== 'function') { return; }
+
+    const generation = this._engineGeneration;
+
+    this._onOnline = (): void => {
+      if (this._engineGeneration !== generation) { return; }
+      console.info('SyncEngineLevel: browser online — triggering immediate integrity check');
+      // Don't set _connectivityState here — individual links will transition
+      // to online as their WebSocket connections actually recover during the
+      // sync below. The public getter uses per-link aggregation.
+
+      // Kick off an immediate SMT reconciliation to catch up after being offline.
+      if (!this._syncLock) {
+        this.sync().catch((err) => {
+          console.error('SyncEngineLevel: post-online sync failed', err);
+        });
+      }
+    };
+
+    this._onOffline = (): void => {
+      if (this._engineGeneration !== generation) { return; }
+      console.info('SyncEngineLevel: browser offline');
+      this._connectivityState = 'offline';
+
+      // Transition every active link to offline so the public
+      // connectivityState getter (which aggregates per-link state)
+      // reflects the browser's network status immediately.
+      for (const link of this._activeLinks.values()) {
+        const prev = link.connectivity;
+        if (prev !== 'offline') {
+          link.connectivity = 'offline';
+          this.emitEvent({
+            type           : 'link:connectivity-change',
+            tenantDid      : link.tenantDid,
+            remoteEndpoint : link.remoteEndpoint,
+            protocol       : link.protocol,
+            from           : prev,
+            to             : 'offline',
+          });
+        }
+      }
+    };
+
+    this._onVisibilityChange = (): void => {
+      if (this._engineGeneration !== generation) { return; }
+
+      // Only act when the page becomes visible again — the user is back.
+      if (typeof document === 'undefined' || document.visibilityState !== 'visible') { return; }
+
+      console.info('SyncEngineLevel: page became visible — triggering integrity check');
+
+      // The device may have slept and WebSockets may be dead. An immediate
+      // sync via SMT reconciliation detects and repairs any divergence.
+      if (!this._syncLock) {
+        this.sync().catch((err) => {
+          console.error('SyncEngineLevel: post-visibility sync failed', err);
+        });
+      }
+    };
+
+    globalThis.addEventListener('online', this._onOnline);
+    globalThis.addEventListener('offline', this._onOffline);
+
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', this._onVisibilityChange);
+    }
+  }
+
+  /** Removes browser connectivity listeners if they were registered. */
+  private stopBrowserConnectivityListeners(): void {
+    if (this._onOnline) {
+      globalThis.removeEventListener('online', this._onOnline);
+      this._onOnline = undefined;
+    }
+    if (this._onOffline) {
+      globalThis.removeEventListener('offline', this._onOffline);
+      this._onOffline = undefined;
+    }
+    if (this._onVisibilityChange && typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this._onVisibilityChange);
+      this._onVisibilityChange = undefined;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Teardown
+  // ---------------------------------------------------------------------------
+
   private async teardownLiveSync(): Promise<void> {
+    // Remove browser connectivity listeners before tearing down.
+    this.stopBrowserConnectivityListeners();
+
     // Increment generation to invalidate all in-flight async operations
     // (repairs, retry timers, degraded-poll ticks). Any async work that
     // captured the previous generation will bail on its next checkpoint.
@@ -1357,10 +1485,25 @@ export class SyncEngineLevel implements SyncEngine {
             );
 
             if (!closureResult.complete) {
+              const failureCode = closureResult.failure!.code;
+              const failureDetail = closureResult.failure!.detail;
               console.warn(
                 `SyncEngineLevel: Closure incomplete for ${did} -> ${dwnUrl}: ` +
-                `${closureResult.failure!.code} — ${closureResult.failure!.detail}`
+                `${failureCode} — ${failureDetail}`
               );
+
+              // Record the message that triggered the closure failure.
+              const closureCid = await Message.getCid(event.message);
+              void this.recordDeadLetter({
+                messageCid     : closureCid,
+                tenantDid      : did,
+                remoteEndpoint : dwnUrl,
+                protocol,
+                category       : 'closure',
+                errorCode      : failureCode,
+                errorDetail    : failureDetail,
+              });
+
               await this.transitionToRepairing(cursorKey, link);
               return;
             }
@@ -1380,6 +1523,10 @@ export class SyncEngineLevel implements SyncEngine {
           this._recentlyPulledCids.set(`${pulledCid}|${dwnUrl}`, Date.now() + SyncEngineLevel.ECHO_SUPPRESS_TTL_MS);
           this.evictExpiredEchoEntries();
 
+          // Auto-clear any dead letter for this CID — it was processed
+          // successfully, so a previous failure has been self-healed.
+          this.clearFailedMessage(pulledCid, dwnUrl).catch(() => { /* teardown race */ });
+
           // Mark this ordinal as committed and drain the checkpoint.
           // Guard: if the link transitioned to repairing while this handler was
           // in-flight (e.g., an earlier ordinal's handler failed concurrently),
@@ -1413,6 +1560,24 @@ export class SyncEngineLevel implements SyncEngine {
           }
         } catch (error: any) {
           console.error(`SyncEngineLevel: Error processing live-pull event for ${did}`, error);
+
+          // Record the failing message in the dead letter store before
+          // transitioning to repair. The CID identifies which specific
+          // message caused the transition.
+          try {
+            const failedCid = await Message.getCid(event.message);
+            void this.recordDeadLetter({
+              messageCid     : failedCid,
+              tenantDid      : did,
+              remoteEndpoint : dwnUrl,
+              protocol,
+              category       : 'pull-processing',
+              errorDetail    : error.message ?? String(error),
+            });
+          } catch {
+            // Best effort — don't let dead letter recording block repair.
+          }
+
           // A failed processRawMessage means local state is incomplete.
           // Transition to repairing immediately — do NOT advance the checkpoint
           // past this failure or let later ordinals commit past it. SMT
@@ -1647,6 +1812,25 @@ export class SyncEngineLevel implements SyncEngine {
         permissionsApi : this._permissionsApi,
       });
 
+      // Auto-clear dead letters for CIDs that succeeded — a previously
+      // failed message may have been repaired by reconciliation.
+      for (const cid of result.succeeded) {
+        this.clearFailedMessage(cid, dwnUrl).catch(() => { /* teardown race */ });
+      }
+
+      // Record permanently failed messages in the dead letter store.
+      for (const entry of result.permanentlyFailed) {
+        await this.recordDeadLetter({
+          messageCid     : entry.cid,
+          tenantDid      : did,
+          remoteEndpoint : dwnUrl,
+          protocol,
+          category       : 'push-permanent',
+          errorCode      : String(entry.statusCode ?? ''),
+          errorDetail    : entry.detail ?? 'permanent push failure',
+        });
+      }
+
       if (result.failed.length > 0) {
         const failedSet = new Set(result.failed);
         const failedEntries = pushEntries.filter((entry) => failedSet.has(entry.cid));
@@ -1703,7 +1887,18 @@ export class SyncEngineLevel implements SyncEngine {
     const pushRuntime = this.getOrCreatePushRuntime(targetKey, pending);
 
     if (pending.retryCount >= maxRetries) {
-      // Retry budget exhausted — mark link dirty for reconciliation.
+      // Retry budget exhausted — record each CID as a dead letter and mark
+      // the link dirty for reconciliation.
+      for (const entry of pending.entries) {
+        void this.recordDeadLetter({
+          messageCid     : entry.cid,
+          tenantDid      : pending.did,
+          remoteEndpoint : pending.dwnUrl,
+          protocol       : pending.protocol,
+          category       : 'push-exhausted',
+          errorDetail    : `push retries exhausted after ${maxRetries} attempts`,
+        });
+      }
       if (pushRuntime.timer) {
         clearTimeout(pushRuntime.timer);
       }
@@ -1815,6 +2010,9 @@ export class SyncEngineLevel implements SyncEngine {
 
       if (reconcileOutcome.converged) {
         await this.ledger.clearNeedsReconcile(link);
+        // SMT roots match — this link is converged. Clear dead letters
+        // scoped to this specific link (tenantDid, remoteEndpoint, protocol).
+        void this.clearDeadLettersForLink(did, dwnUrl, protocol);
         this.emitEvent({ type: 'reconcile:completed', tenantDid: did, remoteEndpoint: dwnUrl, protocol });
       } else {
         // Roots still differ — retry after a delay. This can happen when
@@ -2282,11 +2480,23 @@ export class SyncEngineLevel implements SyncEngine {
     messageCids: string[];
     prefetched?: MessagesSyncDiffEntry[];
   }): Promise<void> {
-    return pullMessages({
+    const failedCids = await pullMessages({
       did, dwnUrl, delegateDid, protocol, messageCids, prefetched,
       agent          : this.agent,
       permissionsApi : this._permissionsApi,
     });
+
+    // Record permanently failed pull entries in the dead letter store.
+    for (const cid of failedCids) {
+      await this.recordDeadLetter({
+        messageCid     : cid,
+        tenantDid      : did,
+        remoteEndpoint : dwnUrl,
+        protocol,
+        category       : 'pull-processing',
+        errorDetail    : 'pull processing failed after retry passes exhausted',
+      });
+    }
   }
 
   // ---------------------------------------------------------------------------
@@ -2367,6 +2577,160 @@ export class SyncEngineLevel implements SyncEngine {
     return topologicalSort(messages);
   }
 
+  // ---------------------------------------------------------------------------
+  // Dead letter tracking
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Clear dead letter entries scoped to a specific sync link. Matches on
+   * (tenantDid, remoteEndpoint, protocol) so that repairing protocol A
+   * does not erase still-valid failures for protocol B on the same remote.
+   * When `protocol` is undefined (full-tenant link), clears entries that
+   * also have no protocol.
+   */
+  private async clearDeadLettersForLink(tenantDid: string, remoteEndpoint: string, protocol?: string): Promise<void> {
+    const batch: { type: 'del'; key: string }[] = [];
+    try {
+      for await (const [key, value] of this._deadLetters.iterator()) {
+        const entry = JSON.parse(value) as DeadLetterEntry;
+        if (entry.tenantDid === tenantDid &&
+            entry.remoteEndpoint === remoteEndpoint &&
+            entry.protocol === protocol) {
+          batch.push({ type: 'del', key });
+        }
+      }
+      if (batch.length > 0) {
+        await this._deadLetters.batch(batch);
+      }
+    } catch (error) {
+      const e = error as { code?: string };
+      if (e.code !== 'LEVEL_DATABASE_NOT_OPEN') { throw error; }
+    }
+  }
+
+  /**
+   * Build a compound dead letter key. Different remotes can fail the same CID
+   * for different reasons, so the key includes the remote endpoint.
+   */
+  private static deadLetterKey(messageCid: string, remoteEndpoint?: string): string {
+    return remoteEndpoint ? `${messageCid}|${remoteEndpoint}` : messageCid;
+  }
+
+  public async recordDeadLetter(params: {
+    messageCid : string;
+    tenantDid : string;
+    remoteEndpoint? : string;
+    protocol? : string;
+    category : DeadLetterCategory;
+    errorCode? : string;
+    errorDetail : string;
+  }): Promise<void> {
+    const entry: DeadLetterEntry = {
+      ...params,
+      failedAt: new Date().toISOString(),
+    };
+    const key = SyncEngineLevel.deadLetterKey(params.messageCid, params.remoteEndpoint);
+    try {
+      await this._deadLetters.put(key, JSON.stringify(entry));
+    } catch (error) {
+      // Suppress only the expected teardown race — any other error surfaces.
+      const e = error as { code?: string };
+      if (e.code !== 'LEVEL_DATABASE_NOT_OPEN') {
+        throw error;
+      }
+    }
+  }
+
+  public async getFailedMessages(tenantDid?: string): Promise<DeadLetterEntry[]> {
+    const entries: DeadLetterEntry[] = [];
+    for await (const [, value] of this._deadLetters.iterator()) {
+      const entry = JSON.parse(value) as DeadLetterEntry;
+      if (!tenantDid || entry.tenantDid === tenantDid) {
+        entries.push(entry);
+      }
+    }
+    // Deterministic ordering: newest first so apps see the most recent failures.
+    entries.sort((a, b) => b.failedAt.localeCompare(a.failedAt));
+    return entries;
+  }
+
+  public async clearFailedMessage(messageCid: string, remoteEndpoint?: string): Promise<boolean> {
+    if (remoteEndpoint) {
+      // Clear a specific CID + remote pair.
+      const key = SyncEngineLevel.deadLetterKey(messageCid, remoteEndpoint);
+      try {
+        await this._deadLetters.get(key);
+        await this._deadLetters.del(key);
+        return true;
+      } catch (error) {
+        const e = error as { code?: string };
+        if (e.code === 'LEVEL_NOT_FOUND') { return false; }
+        throw error;
+      }
+    }
+
+    // No remote specified — clear ALL entries for this CID (any remote).
+    let found = false;
+    const batch: { type: 'del'; key: string }[] = [];
+    for await (const [key, value] of this._deadLetters.iterator()) {
+      const entry = JSON.parse(value) as DeadLetterEntry;
+      if (entry.messageCid === messageCid) {
+        batch.push({ type: 'del', key });
+        found = true;
+      }
+    }
+    if (batch.length > 0) {
+      await this._deadLetters.batch(batch);
+    }
+    return found;
+  }
+
+  public async clearAllFailedMessages(tenantDid?: string): Promise<void> {
+    if (!tenantDid) {
+      await this._deadLetters.clear();
+      return;
+    }
+
+    const batch: { type: 'del'; key: string }[] = [];
+    for await (const [key, value] of this._deadLetters.iterator()) {
+      const entry = JSON.parse(value) as DeadLetterEntry;
+      if (entry.tenantDid === tenantDid) {
+        batch.push({ type: 'del', key });
+      }
+    }
+    if (batch.length > 0) {
+      await this._deadLetters.batch(batch);
+    }
+  }
+
+  public async getSyncHealth(): Promise<SyncHealthSummary> {
+    let failedMessageCount = 0;
+    for await (const _ of this._deadLetters.iterator()) {
+      failedMessageCount++;
+    }
+
+    // Count degraded links from the durable ledger, not just in-memory
+    // _activeLinks. Links persist across restarts; a repairing/degraded_poll
+    // link from a previous session must still be reported.
+    let degradedLinkCount = 0;
+    const allLinks = await this.ledger.getAllLinks();
+    for (const link of allLinks) {
+      if (link.status === 'repairing' || link.status === 'degraded_poll') {
+        degradedLinkCount++;
+      }
+    }
+
+    return {
+      connectivity: this.connectivityState,
+      failedMessageCount,
+      degradedLinkCount,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Sync targets
+  // ---------------------------------------------------------------------------
+
   /**
    * Returns the list of sync targets: (did, dwnUrl, delegateDid?, protocol?) tuples.
    */

package/src/sync-messages.ts

@@ -1,7 +1,8 @@
+import type { GenericMessage, MessagesReadReply, MessagesSyncDiffEntry, UnionMessageReply } from '@enbox/dwn-sdk-js';
+
 import type { EnboxPlatformAgent } from './types/agent.js';
 import type { PermissionsApi } from './types/permissions.js';
-import type { PushResult } from './types/sync.js';
-import type { GenericMessage, MessagesReadReply, MessagesSyncDiffEntry, UnionMessageReply } from '@enbox/dwn-sdk-js';
+import type { PermanentPushFailure, PushResult } from './types/sync.js';
 
 import { DwnInterfaceName, DwnMethodName, Encoder, Message } from '@enbox/dwn-sdk-js';
 
@@ -81,7 +82,7 @@ export async function pullMessages({ did, dwnUrl, delegateDid, protocol, message
   prefetched?: MessagesSyncDiffEntry[];
   agent: EnboxPlatformAgent;
   permissionsApi: PermissionsApi;
-}): Promise<void> {
+}): Promise<string[]> {
   // Convert prefetched diff entries into SyncMessageEntry format.
   const prefetchedEntries: SyncMessageEntry[] = [];
   if (prefetched) {
@@ -165,6 +166,14 @@ export async function pullMessages({ did, dwnUrl, delegateDid, protocol, message
       pending = [];
     }
   }
+
+  // Return CIDs that permanently failed after all retry passes.
+  const permanentlyFailed: string[] = [];
+  for (const entry of pending) {
+    const cid = await getMessageCid(entry.message);
+    permanentlyFailed.push(cid);
+  }
+  return permanentlyFailed;
 }
 
 /**
@@ -327,7 +336,7 @@ export async function pushMessages({ did, dwnUrl, delegateDid, protocol, message
 }): Promise<PushResult> {
   const succeeded: string[] = [];
   const failed: string[] = [];
-  const permanentlyFailed: string[] = [];
+  const permanentlyFailed: PermanentPushFailure[] = [];
 
   // Step 1: Fetch all local messages (streams are pull-based, not yet consumed).
   const fetched: SyncMessageEntry[] = [];
@@ -369,7 +378,7 @@ export async function pushMessages({ did, dwnUrl, delegateDid, protocol, message
         } else {
           console.warn(`SyncEngineLevel: push permanently failed for ${cid}: ${reply.status.code} ${reply.status.detail}`);
         }
-        permanentlyFailed.push(cid);
+        permanentlyFailed.push({ cid, statusCode: reply.status.code, detail: reply.status.detail ?? '' });
       } else {
         // Transient failures (5xx, etc.) — worth retrying.
         console.error(`SyncEngineLevel: push failed for ${cid}: ${reply.status.code} ${reply.status.detail}`);

package/src/types/permissions.ts

@@ -48,6 +48,11 @@ export type CreateGrantParams = {
   grantedTo: string;
   scope: DwnPermissionScope;
   delegated?: boolean;
+  /** Delegate key-delivery metadata for cross-device context key delivery. */
+  delegateKeyDelivery?: {
+    rootKeyId: string;
+    publicKeyJwk: Record<string, any>;
+  };
 };
 
 export type CreateRequestParams = {
@@ -63,6 +68,10 @@ export type CreateRevocationParams = {
   author: string;
   grant: DwnPermissionGrant;
   description?: string;
+  /** For delegated revocation: the delegate DID that signs the revocation. */
+  granteeDid?: string;
+  /** For delegated revocation: the grant ID that authorizes the revocation write. */
+  permissionGrantId?: string;
 };
 
 export type GetPermissionParams = {