@enbox/auth 0.6.19 → 0.6.20

package/src/connect/restore.ts

@@ -10,6 +10,14 @@ import type { AuthSession } from '../identity-session.js';
 import type { FlowContext } from './lifecycle.js';
 import type { RestoreSessionOptions } from '../types.js';
 
+import type { StorageAdapter } from '../types.js';
+
+import type { EnboxUserAgent } from '@enbox/agent';
+
+import { Convert } from '@enbox/common';
+import { DataStream } from '@enbox/dwn-sdk-js';
+import { DwnInterface, DwnPermissionGrant } from '@enbox/agent';
+
 import { applyLocalDwnDiscovery } from '../discovery.js';
 import { STORAGE_KEYS } from '../types.js';
 import { ensureVaultReady, finalizeSession, resolveIdentityDids, resolvePassword, startSyncIfEnabled } from './lifecycle.js';
@@ -19,6 +27,11 @@ import { ensureVaultReady, finalizeSession, resolveIdentityDids, resolvePassword
  *
  * Returns `undefined` if no previous session exists.
  * Returns an `AuthSession` if the session was successfully restored.
+ *
+ * Two independent concerns are handled here:
+ * 1. Revocation retry maintenance (from a previous partial disconnect)
+ * 2. Normal session restore
+ * They do NOT depend on each other. Both can run in the same call.
  */
 export async function restoreSession(
   ctx: FlowContext,
@@ -26,27 +39,27 @@ export async function restoreSession(
 ): Promise<AuthSession | undefined> {
   const { userAgent, emitter, storage } = ctx;
 
-  // Check if there was a previous session.
+  // Two independent concerns:
+  // 1. PREVIOUSLY_CONNECTED — normal session restore
+  // 2. REVOCATION_RETRY_CONTEXT — orphaned revocations from partial disconnect
+  // If neither is set, nothing to do.
   const previouslyConnected = await storage.get(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
-  if (previouslyConnected !== 'true') {
+  const retryContextJson = await storage.get(STORAGE_KEYS.REVOCATION_RETRY_CONTEXT);
+  if (previouslyConnected !== 'true' && !retryContextJson) {
     return undefined;
   }
 
-  // Resolve password: explicit option → callback → provider → manager default → insecure fallback.
-  // Note: restoreSession has an extra `onPasswordRequired` callback that sits between
-  // the explicit password and the provider. We handle that here, then delegate the
-  // remainder of the chain to `resolvePassword()`.
+  // Resolve password.
   let explicitPassword = options.password;
-
   if (!explicitPassword && !ctx.defaultPassword && options.onPasswordRequired) {
     explicitPassword = await options.onPasswordRequired();
   }
 
-  // Check for stale session marker: if the vault was never initialized,
-  // previouslyConnected is a leftover — clean up and bail.
+  // Check for stale session marker.
   const isFirstLaunch = await userAgent.firstLaunch();
   if (isFirstLaunch) {
     await storage.remove(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
+    await storage.remove(STORAGE_KEYS.REVOCATION_RETRY_CONTEXT);
     return undefined;
   }
 
@@ -60,12 +73,37 @@ export async function restoreSession(
     isFirstLaunch: false,
   });
 
-  // Apply local DWN discovery (browser redirect payload or persisted endpoint).
-  // In remote mode, discovery already ran before agent creation — skip.
+  // Apply local DWN discovery.
   if (!userAgent.dwn.isRemoteMode) {
     await applyLocalDwnDiscovery(userAgent, storage, emitter);
   }
 
+  // --- Retry maintenance (independent from session restore) ---
+  // Best-effort: start sync temporarily for remote delivery, run retry,
+  // then stop. Failures here must NOT break a legitimate restore path.
+  if (retryContextJson) {
+    try {
+      await startSyncIfEnabled(userAgent, ctx.defaultSync);
+      try {
+        await retryOrphanedRevocations(userAgent, storage);
+      } finally {
+        await userAgent.sync.stopSync(2000);
+      }
+    } catch {
+      // Retry maintenance is best-effort. If sync startup or retry
+      // fails, the retry context remains in storage for next attempt.
+      // Do NOT let this block normal session restore below.
+    }
+  }
+
+  // --- Normal session restore ---
+  if (previouslyConnected !== 'true') {
+    return undefined;
+  }
+
+  // Start sync for the restored session.
+  await startSyncIfEnabled(userAgent, ctx.defaultSync);
+
   // Determine which identity to reconnect.
   const activeIdentityDid = await storage.get(STORAGE_KEYS.ACTIVE_IDENTITY);
   const storedDelegateDid = await storage.get(STORAGE_KEYS.DELEGATE_DID);
@@ -86,8 +124,7 @@ export async function restoreSession(
     }
   }
 
-  // Start sync.
-  await startSyncIfEnabled(userAgent, ctx.defaultSync);
+  // Sync was already started above (for the restored session).
 
   if (!identity) {
     // No identity found — this is valid for agent-only sessions created
@@ -102,6 +139,13 @@ export async function restoreSession(
       await storage.remove(STORAGE_KEYS.ACTIVE_IDENTITY);
       await storage.remove(STORAGE_KEYS.DELEGATE_DID);
       await storage.remove(STORAGE_KEYS.CONNECTED_DID);
+      await storage.remove(STORAGE_KEYS.DELEGATE_DECRYPTION_KEYS);
+      await storage.remove(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS);
+      await storage.remove(STORAGE_KEYS.DELEGATE_MULTI_PARTY_PROTOCOLS);
+      await storage.remove(STORAGE_KEYS.SESSION_REVOCATIONS);
+      // Do NOT remove REVOCATION_RETRY_CONTEXT here — it has its own
+      // lifecycle managed by the retry maintenance path. Stale session
+      // cleanup must not silently drop pending revocations.
       return undefined;
     }
 
@@ -118,6 +162,53 @@ export async function restoreSession(
     identity, storedDelegateDid ?? undefined,
   );
 
+  // Restore delegate decryption keys if persisted.
+  if (delegateDid && connectedDid) {
+    const keysJson = await storage.get(STORAGE_KEYS.DELEGATE_DECRYPTION_KEYS);
+    if (keysJson) {
+      try {
+        const keys = JSON.parse(keysJson);
+        if (Array.isArray(keys) && keys.length > 0) {
+          userAgent.dwn.importDelegateDecryptionKeys(delegateDid, keys);
+        }
+      } catch { /* best effort — keys will be refreshed on next connect */ }
+    }
+
+    // Restore context keys for multi-party encrypted protocols.
+    const ctxKeysJson = await storage.get(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS);
+    // Restore multi-party protocol registrations.
+    const mpProtocolsJson = await storage.get(STORAGE_KEYS.DELEGATE_MULTI_PARTY_PROTOCOLS);
+    let multiPartyProtocols: string[] | undefined;
+    if (mpProtocolsJson) {
+      try {
+        const parsed = JSON.parse(mpProtocolsJson);
+        if (Array.isArray(parsed)) { multiPartyProtocols = parsed; }
+      } catch { /* best effort */ }
+    }
+
+    if (ctxKeysJson || multiPartyProtocols) {
+      try {
+        const ctxKeys = ctxKeysJson ? JSON.parse(ctxKeysJson) : [];
+        userAgent.dwn.importDelegateContextKeys(
+          delegateDid,
+          Array.isArray(ctxKeys) ? ctxKeys : [],
+          multiPartyProtocols,
+        );
+      } catch { /* best effort — keys will be refreshed on next connect */ }
+    }
+
+    // Wire post-connect context key persistence so keys delivered after
+    // restore survive the next restart. Same callback as finalizeDelegateSession.
+    const restoreDelegateDid = delegateDid;
+    userAgent.dwn.onDelegateContextKeysChanged = async (changedDelegateDid: string): Promise<void> => {
+      if (changedDelegateDid !== restoreDelegateDid) { return; }
+      try {
+        const keys = userAgent.dwn.exportDelegateContextKeys(restoreDelegateDid);
+        await storage.set(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS, JSON.stringify(keys));
+      } catch { /* best effort — keys will be re-derived on next connect */ }
+    };
+  }
+
   // Persist session info, build AuthSession, and emit lifecycle events.
   // Session restore does not emit `identity-added` (identity was already added in the original flow).
   return finalizeSession({
@@ -131,3 +222,247 @@ export async function restoreSession(
     emitIdentityAdded    : false,
   });
 }
+
+// ─── Revocation retry helpers ───────────────────────────────────
+
+type RevocationEntry = { grantId: string; revocationGrantId: string };
+
+type RetryEntry = {
+  delegateDid: string;
+  connectedDid: string;
+  revocations: RevocationEntry[];
+};
+
+/**
+ * Load all retry entries from `REVOCATION_RETRY_CONTEXT`.
+ * Returns an empty array if the data is missing or malformed.
+ */
+async function loadRetryEntries(
+  storage: StorageAdapter,
+): Promise<RetryEntry[]> {
+  const json = await storage.get(STORAGE_KEYS.REVOCATION_RETRY_CONTEXT);
+  if (!json) { return []; }
+
+  try {
+    const parsed = JSON.parse(json);
+
+    // Handle legacy single-object format: wrap in array.
+    const entries = Array.isArray(parsed)
+      ? parsed
+      : (parsed?.delegateDid && parsed?.connectedDid && Array.isArray(parsed?.revocations))
+        ? [parsed]
+        : [];
+
+    if (entries.length === 0 && !Array.isArray(parsed)) {
+      // Truly malformed (not a valid legacy object either).
+      await clearRetryState(storage);
+      return [];
+    }
+
+    // Filter out malformed entries.
+    return entries.filter(
+      (e: any): e is RetryEntry => e?.delegateDid && e?.connectedDid && Array.isArray(e?.revocations),
+    );
+  } catch {
+    await clearRetryState(storage);
+    return [];
+  }
+}
+
+/**
+ * Revoke a single grant and send the revocation to remote DWN endpoints.
+ * Returns `true` if at least one remote endpoint confirmed (202/409).
+ */
+/**
+ * Ensure the revocation grant exists on the owner's remote DWN before
+ * attempting to use it. Reads the grant locally by recordId and sends
+ * it to all remote endpoints. This closes the gap where best-effort
+ * fanout at connect time may have failed.
+ */
+async function ensureRevocationGrantOnRemote(
+  userAgent: EnboxUserAgent,
+  connectedDid: string,
+  delegateDid: string,
+  revocationGrantId: string,
+  dwnEndpointUrls: string[],
+): Promise<void> {
+  if (dwnEndpointUrls.length === 0) { return; }
+
+  try {
+    // Read as the delegate (grant recipient), not the owner.
+    const { reply } = await userAgent.dwn.processRequest({
+      author        : delegateDid,
+      target        : connectedDid,
+      messageType   : DwnInterface.RecordsRead,
+      messageParams : { filter: { recordId: revocationGrantId } },
+    });
+    if (reply.status.code !== 200 || !reply.entry?.recordsWrite) { return; }
+
+    const { encodedData, ...rawMessage } = reply.entry.recordsWrite as any;
+    const data = reply.entry.data
+      ? new Blob([await DataStream.toBytes(reply.entry.data) as BlobPart])
+      : undefined;
+
+    for (const dwnUrl of dwnEndpointUrls) {
+      try {
+        await userAgent.rpc.sendDwnRequest({
+          dwnUrl,
+          targetDid : connectedDid,
+          message   : rawMessage,
+          data,
+        });
+      } catch {
+        // Per-endpoint failure — continue.
+      }
+    }
+  } catch {
+    // Best-effort — if the grant can't be read or sent, the revocation
+    // attempt will fail on auth and be retried next time.
+  }
+}
+
+/**
+ * Revoke a single grant and send the revocation to remote DWN endpoints.
+ * First ensures the revocation grant is on the remote DWN (self-healing).
+ * Returns `true` if at least one remote endpoint confirmed (202/409).
+ */
+async function revokeAndSendSingle(
+  userAgent: EnboxUserAgent,
+  connectedDid: string,
+  delegateDid: string,
+  entry: RevocationEntry,
+  dwnEndpointUrls: string[],
+): Promise<boolean> {
+  // Self-healing: ensure the revocation grant is on the remote DWN.
+  await ensureRevocationGrantOnRemote(
+    userAgent, connectedDid, delegateDid, entry.revocationGrantId, dwnEndpointUrls,
+  );
+
+  // Read as the delegate (grant recipient), not the owner.
+  const { reply: readReply } = await userAgent.dwn.processRequest({
+    author        : delegateDid,
+    target        : connectedDid,
+    messageType   : DwnInterface.RecordsRead,
+    messageParams : { filter: { recordId: entry.grantId } },
+  });
+  if (readReply.status.code !== 200 || !readReply.entry) { return false; }
+
+  // Reconstruct DwnDataEncodedRecordsWriteMessage: RecordsRead returns
+  // the data as a stream, but PermissionGrant.parse needs encodedData.
+  const grantDataBytes = readReply.entry.data
+    ? await DataStream.toBytes(readReply.entry.data)
+    : new Uint8Array(0);
+  const grantMessageWithData = {
+    ...readReply.entry.recordsWrite,
+    encodedData: Convert.uint8Array(grantDataBytes).toBase64Url(),
+  };
+  const grant = DwnPermissionGrant.parse(grantMessageWithData as any);
+
+  const { message } = await userAgent.permissions.createRevocation({
+    author            : connectedDid,
+    store             : true,
+    grant,
+    granteeDid        : delegateDid,
+    permissionGrantId : entry.revocationGrantId,
+  });
+
+  return sendRevocationToEndpoints(userAgent, connectedDid, message, dwnEndpointUrls);
+}
+
+/**
+ * Send a revocation message to all owner DWN endpoints.
+ * Returns `true` if at least one endpoint confirmed (202/409).
+ */
+async function sendRevocationToEndpoints(
+  userAgent: EnboxUserAgent,
+  connectedDid: string,
+  revocationMessage: any,
+  dwnEndpointUrls: string[],
+): Promise<boolean> {
+  if (!revocationMessage || dwnEndpointUrls.length === 0) { return false; }
+
+  const { encodedData, ...rawMessage } = revocationMessage;
+  const data = encodedData
+    ? new Blob([Convert.base64Url(encodedData).toUint8Array() as BlobPart])
+    : undefined;
+
+  for (const dwnUrl of dwnEndpointUrls) {
+    try {
+      const reply = await userAgent.rpc.sendDwnRequest({
+        dwnUrl,
+        targetDid : connectedDid,
+        message   : rawMessage as any,
+        data,
+      });
+      if (reply?.status?.code === 202 || reply?.status?.code === 409) {
+        return true;
+      }
+    } catch {
+      // Per-endpoint failure — try the next one.
+    }
+  }
+  return false;
+}
+
+/** Clear the self-contained revocation retry context from storage. */
+async function clearRetryState(storage: StorageAdapter): Promise<void> {
+  await storage.remove(STORAGE_KEYS.REVOCATION_RETRY_CONTEXT);
+}
+
+/**
+ * Retry grant revocations that were not confirmed by the owner's remote
+ * DWN during a previous disconnect. Called from `restoreSession()` AFTER
+ * sync is started and only when `REVOCATION_RETRY_CONTEXT` exists.
+ *
+ * This function does NOT restore a session — the user explicitly
+ * disconnected and the retry is purely a background cleanup.
+ */
+export async function retryOrphanedRevocations(
+  userAgent: EnboxUserAgent,
+  storage: StorageAdapter,
+): Promise<void> {
+  let entries = await loadRetryEntries(storage);
+  if (entries.length === 0) {
+    await clearRetryState(storage);
+    return;
+  }
+
+  for (const entry of [...entries]) {
+    let remoteDwnUrls: string[] = [];
+    try {
+      remoteDwnUrls = await userAgent.dwn.getRemoteDwnEndpointUrls(entry.connectedDid);
+    } catch {
+      continue; // Can't resolve endpoints for this entry — try next.
+    }
+
+    const succeeded: string[] = [];
+    for (const revEntry of entry.revocations) {
+      try {
+        const confirmed = await revokeAndSendSingle(
+          userAgent, entry.connectedDid, entry.delegateDid, revEntry, remoteDwnUrls,
+        );
+        if (confirmed) { succeeded.push(revEntry.grantId); }
+      } catch {
+        // Individual failure — continue.
+      }
+    }
+
+    // Update the in-memory collection so the next iteration sees
+    // the correct state (avoid stale-snapshot overwrites).
+    const remaining = entry.revocations.filter((r) => !succeeded.includes(r.grantId));
+    if (remaining.length === 0) {
+      entries = entries.filter((e) => e.delegateDid !== entry.delegateDid);
+    } else {
+      entries = entries.map((e) =>
+        e.delegateDid === entry.delegateDid ? { ...e, revocations: remaining } : e,
+      );
+    }
+  }
+
+  // Write the final state once after processing all entries.
+  if (entries.length === 0) {
+    await clearRetryState(storage);
+  } else {
+    await storage.set(STORAGE_KEYS.REVOCATION_RETRY_CONTEXT, JSON.stringify(entries));
+  }
+}

package/src/connect/wallet.ts

@@ -53,9 +53,14 @@ export async function walletConnect(
   }
 
   // Import delegate DID, process grants, and set up sync.
-  const { delegatePortableDid, connectedDid, delegateGrants } = result;
+  const {
+    delegatePortableDid, connectedDid, delegateGrants, delegateDecryptionKeys,
+    delegateContextKeys, delegateMultiPartyProtocols, sessionRevocations,
+  } = result;
   const identity = await importDelegateAndSetupSync({
     userAgent, delegatePortableDid, connectedDid, delegateGrants,
+    delegateDecryptionKeys, delegateContextKeys, delegateMultiPartyProtocols,
+    sessionRevocations,
     flowName: 'Wallet connect',
   });
 

package/src/index.ts

@@ -63,6 +63,12 @@ export {
 // Storage adapters
 export { BrowserStorage, LevelStorage, MemoryStorage, createDefaultStorage } from './storage/storage.js';
 
+// Revocation retry (exported for cross-package integration testing)
+export { retryOrphanedRevocations } from './connect/restore.js';
+
+// Storage keys (exported for cross-package integration testing)
+export { STORAGE_KEYS } from './types.js';
+
 // Types
 export type {
   AuthEvent,

package/src/types.ts

@@ -4,12 +4,12 @@
  */
 
 import type { PortableDid } from '@enbox/dids';
-import type { ConnectPermissionRequest, DwnDataEncodedRecordsWriteMessage, DwnProtocolDefinition, EnboxUserAgent, HdIdentityVault, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
+import type { ConnectPermissionRequest, DelegateContextKey, DelegateDecryptionKey, DwnDataEncodedRecordsWriteMessage, DwnProtocolDefinition, EnboxUserAgent, HdIdentityVault, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
 
 import type { PasswordProvider } from './password-provider.js';
 
 // Re-export types that consumers will need
-export type { ConnectPermissionRequest, HdIdentityVault, IdentityVaultBackup, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
+export type { ConnectPermissionRequest, DelegateContextKey, DelegateDecryptionKey, HdIdentityVault, IdentityVaultBackup, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
 
 // Re-export EnboxUserAgent so consumers don't need a direct @enbox/agent dep
 export type { EnboxUserAgent } from '@enbox/agent';
@@ -229,6 +229,30 @@ export interface ConnectResult {
 
   /** The DID of the identity the user approved (the wallet owner's DID). */
   connectedDid: string;
+
+  /**
+   * Scope-aware decryption keys for encrypted protocols.
+   *
+   * Derived only for read-like permission scopes (Read/Query/Subscribe) on
+   * protocols with `encryptionRequired: true` types. Write-only delegates
+   * receive no decryption keys.
+   */
+  delegateDecryptionKeys?: DelegateDecryptionKey[];
+
+  /**
+   * Context-scoped decryption keys for multi-party encrypted protocols.
+   * Each key unlocks one rootContextId for records using ProtocolContext encryption.
+   */
+  delegateContextKeys?: DelegateContextKey[];
+
+  /**
+   * Protocol URIs that have multi-party encrypted access patterns.
+   * Delivered even when no contexts exist yet (cold-start).
+   */
+  delegateMultiPartyProtocols?: string[];
+
+  /** Per-grant revocation mappings for session-bound self-revocation on disconnect. */
+  sessionRevocations?: { grantId: string; revocationGrantId: string }[];
 }
 
 /**
@@ -648,6 +672,26 @@ export const STORAGE_KEYS = {
   /** The connected DID (for wallet-connected sessions). */
   CONNECTED_DID: 'enbox:auth:connectedDid',
 
+  /**
+   * JSON-serialised `DelegateDecryptionKey[]` for delegate decryption of
+   * encrypted protocol records. Persisted so session restore can re-populate
+   * the delegate decryption key cache without requiring a new connect flow.
+   */
+  DELEGATE_DECRYPTION_KEYS: 'enbox:auth:delegateDecryptionKeys',
+
+  /**
+   * JSON-serialised `DelegateContextKey[]` for multi-party encrypted protocol
+   * records. Persisted for session restore.
+   */
+  DELEGATE_CONTEXT_KEYS: 'enbox:auth:delegateContextKeys',
+
+  /**
+   * JSON-serialised `string[]` of multi-party protocol URIs for delegate
+   * context key eligibility. Persisted for session restore so cold-start
+   * delegates (who connected with zero contexts) still receive future keys.
+   */
+  DELEGATE_MULTI_PARTY_PROTOCOLS: 'enbox:auth:delegateMultiPartyProtocols',
+
   /**
    * The base URL of the local DWN server discovered via the `dwn://connect`
    * browser redirect flow. Persisted so subsequent page loads can skip the
@@ -665,4 +709,20 @@ export const STORAGE_KEYS = {
    * @see https://github.com/enboxorg/enbox/issues/690
    */
   REGISTRATION_TOKENS: 'enbox:auth:registrationTokens',
+
+  /**
+   * JSON-serialised `SessionRevocationEntry[]` mapping session grant IDs to
+   * their corresponding revocation grant IDs for disconnect.
+   */
+  SESSION_REVOCATIONS: 'enbox:auth:sessionRevocations',
+
+  /**
+   * Self-contained collection of revocation retry entries from previous
+   * partial disconnects. JSON-serialised array of
+   * `{ delegateDid, connectedDid, revocations }` entries, one per
+   * session. Keyed by `delegateDid` (unique per session).
+   *
+   * Completely independent from active session state.
+   */
+  REVOCATION_RETRY_CONTEXT: 'enbox:auth:revocationRetryContext',
 } as const;

package/src/wallet-connect-client.ts

@@ -94,6 +94,10 @@ async function initClient({
   delegateGrants: EnboxConnectResponse['delegateGrants'];
   delegatePortableDid: EnboxConnectResponse['delegatePortableDid'];
   connectedDid: string;
+  delegateDecryptionKeys?: EnboxConnectResponse['delegateDecryptionKeys'];
+  delegateContextKeys?: EnboxConnectResponse['delegateContextKeys'];
+  delegateMultiPartyProtocols?: EnboxConnectResponse['delegateMultiPartyProtocols'];
+  sessionRevocations?: EnboxConnectResponse['sessionRevocations'];
 } | undefined> {
   // ephemeral client did for ECDH, signing, verification
   const clientDid = await DidJwk.create();
@@ -187,9 +191,13 @@ async function initClient({
     })) as unknown as EnboxConnectResponse;
 
     return {
-      delegateGrants      : verifiedResponse.delegateGrants,
-      delegatePortableDid : verifiedResponse.delegatePortableDid,
-      connectedDid        : verifiedResponse.providerDid,
+      delegateGrants              : verifiedResponse.delegateGrants,
+      delegatePortableDid         : verifiedResponse.delegatePortableDid,
+      connectedDid                : verifiedResponse.providerDid,
+      delegateDecryptionKeys      : verifiedResponse.delegateDecryptionKeys,
+      delegateContextKeys         : verifiedResponse.delegateContextKeys,
+      delegateMultiPartyProtocols : verifiedResponse.delegateMultiPartyProtocols,
+      sessionRevocations          : verifiedResponse.sessionRevocations,
     };
   }
 }