@enbox/auth 0.6.28 → 0.6.30

package/src/connect/restore.ts

@@ -14,15 +14,13 @@ import type { StorageAdapter } from '../types.js';
 
 import type { EnboxUserAgent } from '@enbox/agent';
 
-import type { DwnDataEncodedRecordsWriteMessage, DwnMessagesPermissionScope, DwnRecordsPermissionScope } from '@enbox/agent';
-
 import { Convert } from '@enbox/common';
-import { DataStream, PermissionsProtocol } from '@enbox/dwn-sdk-js';
+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';
+import { ensureVaultReady, finalizeSession, registerSyncScopeForIdentity, resolveIdentityDids, resolvePassword, startSyncIfEnabled } from './lifecycle.js';
 
 /**
  * Decrypt a stored key blob.
@@ -45,6 +43,45 @@ async function decryptStoredKeys(
   return stored;
 }
 
+/**
+ * Load delegate keys from SecretStore, falling back to legacy StorageAdapter.
+ *
+ * On a successful legacy read the keys are migrated into the SecretStore and
+ * the plaintext/JWE copy is removed (best-effort). Returns the JSON string
+ * representation of the keys, or `undefined` if nothing is stored.
+ */
+async function loadDelegateKeysWithFallback(
+  userAgent: EnboxUserAgent,
+  storage: StorageAdapter,
+  key: string,
+): Promise<string | undefined> {
+  // 1. Try SecretStore (preferred path).
+  try {
+    const bytes = await userAgent.secrets.get(key);
+    if (bytes) {
+      return Convert.uint8Array(bytes).toString();
+    }
+  } catch { /* vault may be locked — fall through to legacy path */ }
+
+  // 2. Fall back to legacy StorageAdapter (JWE or plaintext JSON).
+  const legacy = await storage.get(key);
+  if (!legacy) { return undefined; }
+
+  try {
+    const json = await decryptStoredKeys(userAgent, legacy);
+
+    // Migrate into SecretStore and remove legacy copy (best-effort).
+    try {
+      await userAgent.secrets.put(key, Convert.string(json).toUint8Array());
+      await storage.remove(key);
+    } catch { /* best-effort migration */ }
+
+    return json;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Attempt to restore a previous session.
  *
@@ -153,6 +190,7 @@ export async function restoreSession(
 
     if (!isAgentOnlySession) {
       // Truly stale session data — clean up and bail.
+      // Remove delegate keys from both SecretStore and legacy StorageAdapter.
       await storage.remove(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
       await storage.remove(STORAGE_KEYS.ACTIVE_IDENTITY);
       await storage.remove(STORAGE_KEYS.DELEGATE_DID);
@@ -161,6 +199,8 @@ export async function restoreSession(
       await storage.remove(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS);
       await storage.remove(STORAGE_KEYS.DELEGATE_MULTI_PARTY_PROTOCOLS);
       await storage.remove(STORAGE_KEYS.SESSION_REVOCATIONS);
+      try { await userAgent.secrets.delete(STORAGE_KEYS.DELEGATE_DECRYPTION_KEYS); } catch { /* best-effort */ }
+      try { await userAgent.secrets.delete(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS); } catch { /* best-effort */ }
       // 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.
@@ -185,37 +225,36 @@ export async function restoreSession(
   // which causes the sync engine to attempt syncing the permissions protocol
   // and fail with "No permissions found for MessagesSync".
   // Derive the correct protocol list from stored grants and update.
-  if (delegateDid && ctx.defaultSync !== 'off') {
+  // Always repair regardless of sync state — a stale registration persists
+  // on disk and would take effect if sync is later enabled.
+  let syncRepairFailed = false;
+  if (delegateDid) {
     try {
-      const protocols = await deriveProtocolsFromGrants(userAgent, delegateDid);
-      const options = { delegateDid, protocols };
-      try {
-        await userAgent.sync.registerIdentity({ did: connectedDid, options });
-      } catch (regError: unknown) {
-        const msg = regError instanceof Error ? regError.message : '';
-        if (msg.includes('already registered')) {
-          await userAgent.sync.updateIdentityOptions({ did: connectedDid, options });
-        }
-        // Other errors are ignored — sync will still work with existing registration.
-      }
+      await registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
     } catch {
-      // Best-effort — don't block restore if grant query fails.
+      // Grant query or registration repair failed — don't block restore,
+      // but don't let a stale registration remain usable.
+      syncRepairFailed = true;
+      // Best-effort: remove any existing registration so a later manual
+      // startSync() cannot use stale scope for this connected DID.
+      try { await userAgent.sync.unregisterIdentity(connectedDid); } catch { /* already gone or store error */ }
     }
   }
 
-  // Start sync after the registration is correct.
-  await startSyncIfEnabled(userAgent, ctx.defaultSync);
-
-  // Restore delegate decryption keys if persisted.
-  // Keys are stored as compact JWE (encrypted with the vault CEK).
-  // Falls back to plaintext JSON for backward compatibility with sessions
-  // created before the encryption-at-rest fix.
+  // Restore delegate decryption/context keys BEFORE starting sync so that
+  // the first sync cycle can decrypt encrypted records.
+  //
+  // Keys are loaded from the vault-backed SecretStore (preferred). When
+  // the SecretStore is empty, we fall back to the legacy StorageAdapter
+  // which may hold either a compact JWE (encrypted with the vault CEK)
+  // or raw JSON (from sessions created before the encryption-at-rest fix).
+  // On successful fallback, the legacy copy is removed (best-effort) so
+  // all future reads come from the SecretStore.
   if (delegateDid && connectedDid) {
-    const storedKeys = await storage.get(STORAGE_KEYS.DELEGATE_DECRYPTION_KEYS);
-    if (storedKeys) {
+    const decryptionKeysJson = await loadDelegateKeysWithFallback(userAgent, storage, STORAGE_KEYS.DELEGATE_DECRYPTION_KEYS);
+    if (decryptionKeysJson) {
       try {
-        const keysJson = await decryptStoredKeys(userAgent, storedKeys);
-        const keys = JSON.parse(keysJson);
+        const keys = JSON.parse(decryptionKeysJson);
         if (Array.isArray(keys) && keys.length > 0) {
           userAgent.dwn.importDelegateDecryptionKeys(delegateDid, keys);
         }
@@ -223,7 +262,7 @@ export async function restoreSession(
     }
 
     // Restore context keys for multi-party encrypted protocols.
-    const storedCtxKeys = await storage.get(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS);
+    const contextKeysJson = await loadDelegateKeysWithFallback(userAgent, storage, STORAGE_KEYS.DELEGATE_CONTEXT_KEYS);
     // Restore multi-party protocol registrations (not encrypted — no key material).
     const mpProtocolsJson = await storage.get(STORAGE_KEYS.DELEGATE_MULTI_PARTY_PROTOCOLS);
     let multiPartyProtocols: string[] | undefined;
@@ -234,12 +273,9 @@ export async function restoreSession(
       } catch { /* best effort */ }
     }
 
-    if (storedCtxKeys || multiPartyProtocols) {
+    if (contextKeysJson || multiPartyProtocols) {
       try {
-        const ctxKeysJson = storedCtxKeys
-          ? await decryptStoredKeys(userAgent, storedCtxKeys)
-          : '[]';
-        const ctxKeys = JSON.parse(ctxKeysJson);
+        const ctxKeys = contextKeysJson ? JSON.parse(contextKeysJson) : [];
         userAgent.dwn.importDelegateContextKeys(
           delegateDid,
           Array.isArray(ctxKeys) ? ctxKeys : [],
@@ -255,13 +291,18 @@ export async function restoreSession(
       if (changedDelegateDid !== restoreDelegateDid) { return; }
       try {
         const keys = userAgent.dwn.exportDelegateContextKeys(restoreDelegateDid);
-        const pt = Convert.string(JSON.stringify(keys)).toUint8Array();
-        const encrypted = await userAgent.vault.encryptData({ plaintext: pt });
-        await storage.set(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS, encrypted);
+        const bytes = Convert.string(JSON.stringify(keys)).toUint8Array();
+        await userAgent.secrets.put(STORAGE_KEYS.DELEGATE_CONTEXT_KEYS, bytes);
       } catch { /* best effort — keys will be re-derived on next connect */ }
     };
   }
 
+  // Start sync only if the registration repair succeeded (or was not needed).
+  // If repair failed, don't start sync with potentially stale scope.
+  if (!syncRepairFailed) {
+    await startSyncIfEnabled(userAgent, ctx.defaultSync);
+  }
+
   // 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({
@@ -444,7 +485,7 @@ async function sendRevocationToEndpoints(
       const reply = await userAgent.rpc.sendDwnRequest({
         dwnUrl,
         targetDid : connectedDid,
-        message   : rawMessage as any,
+        message   : rawMessage,
         data,
       });
       if (reply?.status?.code === 202 || reply?.status?.code === 409) {
@@ -530,32 +571,4 @@ export async function retryOrphanedRevocations(
  * permissions protocol itself (permission records are already included
  * in each protocol's sync stream via `constructAdditionalMessageFilter`).
  */
-async function deriveProtocolsFromGrants(
-  userAgent: EnboxUserAgent,
-  delegateDid: string,
-): Promise<string[]> {
-  const response = await userAgent.processDwnRequest({
-    author        : delegateDid,
-    target        : delegateDid,
-    messageType   : DwnInterface.RecordsQuery,
-    messageParams : {
-      filter: {
-        protocol     : PermissionsProtocol.uri,
-        protocolPath : PermissionsProtocol.grantPath,
-      },
-    },
-  });
-
-  const protocols: string[] = [];
-  if (response.reply.status.code === 200 && response.reply.entries) {
-    for (const entry of response.reply.entries as DwnDataEncodedRecordsWriteMessage[]) {
-      const grant = DwnPermissionGrant.parse(entry);
-      const scopeProtocol = (grant.scope as DwnMessagesPermissionScope | DwnRecordsPermissionScope).protocol;
-      if (scopeProtocol && scopeProtocol !== PermissionsProtocol.uri) {
-        protocols.push(scopeProtocol);
-      }
-    }
-  }
 
-  return [...new Set(protocols)];
-}

package/src/connect/wallet.ts

@@ -71,8 +71,9 @@ export async function walletConnect(
       {
         userAgent,
         dwnEndpoints,
-        agentDid: userAgent.agentDid.uri,
+        agentDid    : userAgent.agentDid.uri,
         connectedDid,
+        secretStore : userAgent.secrets,
         storage,
       },
       ctx.registration,

package/src/discovery.ts

@@ -58,7 +58,7 @@ export function checkUrlForDwnDiscoveryPayload(): string | undefined {
 
   // Clear the fragment to prevent re-reading on subsequent calls or
   // if the user refreshes the page after the redirect.
-  if (typeof globalThis.history !== 'undefined' && globalThis.history.replaceState) {
+  if (globalThis.history?.replaceState) {
     const cleanUrl = globalThis.location.href.split('#')[0];
     globalThis.history.replaceState(null, '', cleanUrl);
   }

package/src/events.ts

@@ -19,7 +19,7 @@ import type { AuthEvent, AuthEventHandler, AuthEventMap } from './types.js';
  * ```
  */
 export class AuthEventEmitter {
-  private _listeners = new Map<AuthEvent, Set<AuthEventHandler<AuthEvent>>>();
+  private readonly _listeners = new Map<AuthEvent, Set<AuthEventHandler<AuthEvent>>>();
 
   /**
    * Subscribe to an event. Returns an unsubscribe function.

package/src/registration.ts

@@ -11,8 +11,9 @@
  * @module
  */
 
-import type { EnboxUserAgent } from '@enbox/agent';
+import type { EnboxUserAgent, SecretStore } from '@enbox/agent';
 
+import { Convert } from '@enbox/common';
 import { DwnRegistrar } from '@enbox/dwn-clients';
 
 import { STORAGE_KEYS } from './types.js';
@@ -38,8 +39,20 @@ export interface RegistrationContext {
   connectedDid: string;
 
   /**
-   * Storage adapter for automatic token persistence.
-   * Only used when `registration.persistTokens` is `true`.
+   * Vault-backed secret store for encrypted token persistence.
+   *
+   * When provided **and** the vault is unlocked, registration tokens are
+   * stored here instead of in the plaintext `StorageAdapter`, keeping
+   * bearer credentials out of `localStorage`.
+   */
+  secretStore?: SecretStore;
+
+  /**
+   * Plaintext storage adapter for automatic token persistence.
+   *
+   * @deprecated Prefer {@link secretStore} when the vault is available.
+   *             This field is retained for backwards compatibility with
+   *             callers that have not yet migrated.
    */
   storage?: StorageAdapter;
 }
@@ -60,14 +73,21 @@ export async function registerWithDwnEndpoints(
   ctx: RegistrationContext,
   registration: RegistrationOptions,
 ): Promise<void> {
-  const { userAgent, dwnEndpoints, agentDid, connectedDid, storage } = ctx;
+  const { userAgent, dwnEndpoints, agentDid, connectedDid, secretStore, storage } = ctx;
 
-  // Load initial tokens: when persistTokens is enabled, load from storage
-  // (ignoring any explicit registrationTokens). Otherwise use the explicit map.
+  // Load initial tokens: when persistTokens is enabled, try the
+  // vault-backed SecretStore first, then fall back to the legacy plaintext
+  // StorageAdapter.  This ensures upgraded clients that already have tokens
+  // in localStorage can still read them (and migrate them on the next save).
   let seedTokens: Record<string, RegistrationTokenData> = {};
 
-  if (registration.persistTokens && storage) {
-    seedTokens = await loadTokensFromStorage(storage);
+  if (registration.persistTokens) {
+    if (secretStore) {
+      seedTokens = await loadTokensFromSecretStore(secretStore);
+    }
+    if (Object.keys(seedTokens).length === 0 && storage) {
+      seedTokens = await loadTokensFromStorage(storage);
+    }
   } else {
     seedTokens = registration.registrationTokens ?? {};
   }
@@ -103,8 +123,8 @@ export async function registerWithDwnEndpoints(
             tokenData = {
               registrationToken : refreshed.registrationToken,
               refreshToken      : refreshed.refreshToken,
-              expiresAt         : refreshed.expiresIn !== undefined
-                ? Date.now() + (refreshed.expiresIn * 1000) : undefined,
+              expiresAt         : refreshed.expiresIn === undefined
+                ? undefined : Date.now() + (refreshed.expiresIn * 1000),
               tokenUrl   : tokenData.tokenUrl,
               refreshUrl : tokenData.refreshUrl,
             };
@@ -140,8 +160,8 @@ export async function registerWithDwnEndpoints(
           tokenData = {
             registrationToken : tokenResponse.registrationToken,
             refreshToken      : tokenResponse.refreshToken,
-            expiresAt         : tokenResponse.expiresIn !== undefined
-              ? Date.now() + (tokenResponse.expiresIn * 1000) : undefined,
+            expiresAt         : tokenResponse.expiresIn === undefined
+              ? undefined : Date.now() + (tokenResponse.expiresIn * 1000),
             tokenUrl   : providerAuth.tokenUrl,
             refreshUrl : providerAuth.refreshUrl,
           };
@@ -162,9 +182,21 @@ export async function registerWithDwnEndpoints(
       }
     }
 
-    // Persist tokens to storage when auto-persistence is enabled.
-    if (registration.persistTokens && storage) {
-      await saveTokensToStorage(storage, updatedTokens);
+    // Persist tokens: prefer vault-backed SecretStore over plaintext StorageAdapter.
+    // When migrating to SecretStore, also clear the legacy plaintext copy so
+    // bearer tokens no longer sit in localStorage.
+    if (registration.persistTokens) {
+      if (secretStore) {
+        await saveTokensToSecretStore(secretStore, updatedTokens);
+        // Best-effort cleanup: remove the legacy plaintext copy so bearer
+        // tokens no longer sit in localStorage.  A failure here must not
+        // turn a successful registration into an error.
+        if (storage) {
+          try { await storage.remove(STORAGE_KEYS.REGISTRATION_TOKENS); } catch { /* best-effort */ }
+        }
+      } else if (storage) {
+        await saveTokensToStorage(storage, updatedTokens);
+      }
     }
 
     // Notify app of updated tokens (always, even when auto-persisting).
@@ -210,3 +242,38 @@ export async function saveTokensToStorage(
 ): Promise<void> {
   await storage.set(STORAGE_KEYS.REGISTRATION_TOKENS, JSON.stringify(tokens));
 }
+
+// ─── SecretStore helpers ─────────────────────────────────────────
+
+/**
+ * Load registration tokens from the vault-backed {@link SecretStore}.
+ *
+ * Returns an empty record if no tokens are stored, the stored value is
+ * corrupt, or the vault is locked (best-effort — never throws).
+ *
+ * @internal
+ */
+export async function loadTokensFromSecretStore(
+  secretStore: SecretStore,
+): Promise<Record<string, RegistrationTokenData>> {
+  try {
+    const bytes = await secretStore.get(STORAGE_KEYS.REGISTRATION_TOKENS);
+    if (!bytes) { return {}; }
+    const json = Convert.uint8Array(bytes).toString();
+    return JSON.parse(json) as Record<string, RegistrationTokenData>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save registration tokens to the vault-backed {@link SecretStore}.
+ * @internal
+ */
+export async function saveTokensToSecretStore(
+  secretStore: SecretStore,
+  tokens: Record<string, RegistrationTokenData>,
+): Promise<void> {
+  const bytes = Convert.string(JSON.stringify(tokens)).toUint8Array();
+  await secretStore.put(STORAGE_KEYS.REGISTRATION_TOKENS, bytes);
+}

package/src/types.ts

@@ -171,7 +171,8 @@ export interface RegistrationOptions {
    * endpoint, it is used directly without re-running the auth flow.
    *
    * When {@link persistTokens} is `true`, this field is ignored —
-   * tokens are loaded automatically from the `StorageAdapter`.
+   * tokens are loaded automatically from the agent's vault-backed
+   * `SecretStore` (preferred) or the legacy `StorageAdapter` (fallback).
    */
   registrationTokens?: Record<string, RegistrationTokenData>;
 
@@ -180,21 +181,29 @@ export interface RegistrationOptions {
    * The app should persist these for future sessions.
    *
    * When {@link persistTokens} is `true`, tokens are saved automatically
-   * to the `StorageAdapter`. This callback is still invoked (if provided)
-   * **after** the automatic save, so consumers can observe token changes
-   * without handling persistence themselves.
+   * to the agent's vault-backed `SecretStore` (or the legacy
+   * `StorageAdapter` when no `SecretStore` is available). This callback
+   * is still invoked (if provided) **after** the automatic save, so
+   * consumers can observe token changes without handling persistence
+   * themselves.
    */
   onRegistrationTokens?: (tokens: Record<string, RegistrationTokenData>) => void;
 
   /**
-   * Automatically persist and restore registration tokens using the
-   * auth manager's `StorageAdapter`.
+   * Automatically persist and restore registration tokens.
    *
-   * When `true`, tokens are loaded from storage before registration and
-   * saved back after new or refreshed tokens are obtained. This removes
-   * the need for consumers to implement their own token I/O via
+   * When `true`, tokens are loaded before registration and saved back
+   * after new or refreshed tokens are obtained, removing the need for
+   * consumers to implement their own token I/O via
    * {@link registrationTokens} and {@link onRegistrationTokens}.
    *
+   * **Storage preference:** tokens are stored in the agent's vault-backed
+   * `SecretStore` (encrypted at rest) when available.  On the first run
+   * after an upgrade, any tokens left in the legacy plaintext
+   * `StorageAdapter` are migrated into the `SecretStore` and the
+   * plaintext copy is removed.  If no `SecretStore` is provided, the
+   * `StorageAdapter` is used as a fallback.
+   *
    * Defaults to `false` for backward compatibility.
    *
    * @example