@enbox/auth 0.6.39 → 0.6.40

package/src/auth-manager.ts

@@ -29,9 +29,9 @@ import type {
   DisconnectOptions,
   HandlerConnectOptions,
   HeadlessConnectOptions,
-  ImportFromPhraseOptions,
   ImportFromPortableOptions,
   RegistrationOptions,
+  RestoreFromPhraseOptions,
   RestoreSessionOptions,
   ShutdownOptions,
   StorageAdapter,
@@ -48,13 +48,13 @@ import { AuthEventEmitter } from './events.js';
 import { AuthSession } from './identity-session.js';
 import { createDefaultStorage } from './storage/storage.js';
 import { discoverLocalDwn } from './discovery.js';
+import { importFromPortable } from './connect/import.js';
 import { normalizeProtocolRequests } from './permissions.js';
 import { restoreSession } from './connect/restore.js';
 import { STORAGE_KEYS } from './types.js';
 import { vaultConnect } from './connect/vault.js';
 import { walletConnect } from './connect/wallet.js';
 import { deriveActiveSyncScope, ensureVaultReady, finalizeDelegateSession, importDelegateAndSetupSync, resolveIdentityDids, resolvePassword, startSyncIfEnabled, toSyncIdentityProtocols } from './connect/lifecycle.js';
-import { importFromPhrase, importFromPortable } from './connect/import.js';
 
 /**
  * The primary entry point for authentication and identity management.
@@ -71,7 +71,7 @@ import { importFromPhrase, importFromPortable } from './connect/import.js';
  *
  * // First time: creates a new identity
  * // Subsequent times: restores the previous session
- * const session = await auth.restoreSession() ?? await auth.connect();
+ * const session = await auth.restoreSession() ?? await auth.connectVault({ createIdentity: true });
  *
  * // session.agent  — the authenticated Enbox agent
  * // session.did    — the connected DID URI
@@ -206,17 +206,20 @@ export class AuthManager {
    * This is the primary entry point for dapps. It routes to the
    * appropriate flow based on the options:
    *
+   * **Recovery phrase restore** (wallets / CLI): Explicitly restores or
+   * re-unlocks a vault. Triggered first when `recoveryPhrase` is provided.
+   *
    * **Handler-based connect** (dapps): Delegates credential acquisition
    * to a {@link ConnectHandler}. Triggered when `protocols` or
-   * `connectHandler` is provided.
+   * `connectHandler` is provided and no `recoveryPhrase` is present.
    *
    * **Local connect** (wallets / CLI): Creates or unlocks a local vault.
    * Triggered when `password`, `createIdentity`, or `recoveryPhrase`
    * is provided.
    *
-   * In both cases, `connect()` first attempts to restore a previous
-   * session. If a valid session exists, it is returned immediately
-   * without any user interaction.
+   * `connect()` first attempts to restore a previous session unless a
+   * recovery phrase is provided. Recovery is an explicit user action and
+   * bypasses stored-session restore.
    *
    * @example Dapp (browser)
    * ```ts
@@ -245,6 +248,11 @@ export class AuthManager {
    */
   async connect(options?: ConnectOptions): Promise<AuthSession> {
     return this._withConnect(async () => {
+      // Recovery is an explicit user action. Do not let a stale stored session intercept it.
+      if (this._isPhraseRestore(options)) {
+        return vaultConnect(this._flowContext(), options);
+      }
+
       // 1. Try to restore a previous session first.
       const restored = await restoreSession(this._flowContext());
       if (restored) { return restored; }
@@ -261,32 +269,28 @@ export class AuthManager {
   }
 
   /**
-   * Create or reconnect a local identity (explicit vault connect).
+   * Create or reconnect an identity via the local HD vault.
    *
    * Use this when you explicitly want the vault flow, bypassing
-   * auto-detection. This is the preferred method for wallet apps.
+   * auto-detection. This is the preferred method for wallet apps
+   * and CLI tools that own the identity vault directly.
    *
    * @param options - Vault connect options.
    * @returns An active AuthSession.
    * @throws If a connection attempt is already in progress.
-   * @deprecated Use {@link connectVault} instead. Will be removed in 1.0.
    */
-  async connectLocal(options?: VaultConnectOptions): Promise<AuthSession> {
-    return this.connectVault(options);
+  async connectVault(options?: VaultConnectOptions): Promise<AuthSession> {
+    return this._withConnect(() => vaultConnect(this._flowContext(), options));
   }
 
   /**
-   * Create or reconnect an identity via the local HD vault.
+   * Restore or re-unlock the local vault from a BIP-39 recovery phrase.
    *
-   * Use this when you explicitly want the vault flow, bypassing
-   * auto-detection. This is the preferred method for wallet apps
-   * and CLI tools that own the identity vault directly.
-   *
-   * @param options - Vault connect options.
-   * @returns An active AuthSession.
-   * @throws If a connection attempt is already in progress.
+   * - Fresh device: initializes the vault from the phrase and recovers remote identities.
+   * - Same local vault: verifies the phrase matches, resets the local password, and preserves data.
+   * - Different local vault: throws without clearing or replacing the existing vault.
    */
-  async connectVault(options?: VaultConnectOptions): Promise<AuthSession> {
+  async restoreFromPhrase(options: RestoreFromPhraseOptions): Promise<AuthSession> {
     return this._withConnect(() => vaultConnect(this._flowContext(), options));
   }
 
@@ -305,16 +309,6 @@ export class AuthManager {
     return this._withConnect(() => walletConnect(this._flowContext(), options));
   }
 
-  /**
-   * Import an identity from a BIP-39 recovery phrase.
-   *
-   * This re-derives the vault and agent DID from the mnemonic,
-   * recovering the identity on this device.
-   */
-  async importFromPhrase(options: ImportFromPhraseOptions): Promise<AuthSession> {
-    return this._withConnect(() => importFromPhrase(this._flowContext(), options));
-  }
-
   /**
    * Import an identity from a PortableIdentity JSON object.
    *
@@ -1014,6 +1008,12 @@ export class AuthManager {
     return true;
   }
 
+  private _isPhraseRestore(options?: ConnectOptions): options is RestoreFromPhraseOptions {
+    return options !== undefined
+      && options !== null
+      && typeof (options as { recoveryPhrase?: unknown }).recoveryPhrase === 'string';
+  }
+
   /**
    * Run a handler-based (delegated) connect flow.
    *
@@ -1093,7 +1093,7 @@ export class AuthManager {
    *
    * Replaces the 5 manual inline context constructions that were
    * previously duplicated across `connect()`, `walletConnect()`,
-   * `importFromPhrase()`, `importFromPortable()`, and `restoreSession()`.
+   * `restoreFromPhrase()`, `importFromPortable()`, and `restoreSession()`.
    */
   private _flowContext(): FlowContext {
     return {
@@ -1113,7 +1113,7 @@ export class AuthManager {
    *
    * Consolidates the duplicated concurrency guard, `_isConnecting` flag management,
    * session assignment, and state transition across `connect()`, `walletConnect()`,
-   * `importFromPhrase()`, and `importFromPortable()`.
+   * `restoreFromPhrase()`, and `importFromPortable()`.
    *
    * Also short-circuits if the manager has already been shut down — using
    * a closed manager would otherwise fail deep inside sync/storage with an

package/src/connect/import.ts

@@ -1,129 +1,17 @@
 /**
  * Identity import flows.
  *
- * - Import from BIP-39 recovery phrase (re-derive vault + identity).
  * - Import from PortableIdentity JSON.
  * @module
  */
 
 import type { AuthSession } from '../identity-session.js';
 import type { FlowContext } from './lifecycle.js';
-import type { ImportFromPhraseOptions, ImportFromPortableOptions } from '../types.js';
+import type { ImportFromPortableOptions } from '../types.js';
 
 import { DEFAULT_DWN_ENDPOINTS } from '../types.js';
 import { registerWithDwnEndpoints } from '../registration.js';
-import { createDefaultIdentity, ensureVaultReady, finalizeSession, registerSyncScopeForIdentity, resolveIdentityDids, startSyncIfEnabled } from './lifecycle.js';
-import { recoverIdentitiesFromRemote, registerAgentDidForSync } from './recovery.js';
-
-/**
- * Import (or recover) an identity from a BIP-39 recovery phrase.
- *
- * This re-initializes the vault with the given phrase and password,
- * recovering the agent DID and all derived keys. If the recovery phrase
- * was previously used to create identities, they are pulled from the
- * remote DWN. Otherwise a new default identity is created.
- */
-export async function importFromPhrase(
-  ctx: FlowContext,
-  options: ImportFromPhraseOptions,
-): Promise<AuthSession> {
-  const { userAgent, emitter, storage } = ctx;
-  const { recoveryPhrase, password } = options;
-  const sync = options.sync ?? ctx.defaultSync;
-  const dwnEndpoints = options.dwnEndpoints ?? ctx.defaultDwnEndpoints ?? DEFAULT_DWN_ENDPOINTS;
-
-  // Initialize the vault with the recovery phrase and start the agent.
-  const isFirstLaunch = await userAgent.firstLaunch();
-  await ensureVaultReady({
-    userAgent,
-    emitter,
-    password,
-    isFirstLaunch,
-    recoveryPhrase,
-    dwnEndpoints,
-  });
-
-  // Register agent DID as tenant and for sync — prerequisites for recovery.
-  if (ctx.registration) {
-    await registerWithDwnEndpoints(
-      {
-        userAgent,
-        dwnEndpoints,
-        agentDid     : userAgent.agentDid.uri,
-        connectedDid : userAgent.agentDid.uri,
-        secretStore  : userAgent.secrets,
-        storage,
-      },
-      ctx.registration,
-    );
-  }
-  if (sync !== 'off') {
-    await registerAgentDidForSync(userAgent);
-  }
-
-  // Try to recover identities from the remote DWN before falling back
-  // to creating a new one.
-  let identities = await userAgent.identity.list();
-  let identity = identities[0];
-  let isNewIdentity = false;
-
-  if (!identity && sync !== 'off') {
-    try {
-      identities = await recoverIdentitiesFromRemote({ userAgent, dwnEndpoints, registration: ctx.registration, storage });
-      identity = identities[0];
-    } catch (err) {
-      console.warn('[@enbox/auth] Seed phrase recovery failed:', err);
-    }
-  }
-
-  if (!identity) {
-    isNewIdentity = true;
-    identity = await createDefaultIdentity(userAgent, dwnEndpoints);
-  }
-
-  const { connectedDid, delegateDid } = resolveIdentityDids(identity);
-
-  // Register sync for the identity DID.
-  if (isNewIdentity) {
-    // New identity: register as tenant first, then for sync.
-    if (ctx.registration) {
-      await registerWithDwnEndpoints(
-        {
-          userAgent,
-          dwnEndpoints,
-          agentDid    : userAgent.agentDid.uri,
-          connectedDid,
-          secretStore : userAgent.secrets,
-          storage,
-        },
-        ctx.registration,
-      );
-    }
-    if (delegateDid) {
-      await registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
-    } else if (sync !== 'off') {
-      await registerSyncScopeForIdentity({ userAgent, connectedDid });
-    }
-  } else if (delegateDid) {
-    // Pre-existing delegate identity: repair sync scope so revoked
-    // grants don't remain in a stale registration.
-    await registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
-  }
-
-  // Start sync.
-  await startSyncIfEnabled(userAgent, sync);
-
-  // Persist session info, build AuthSession, and emit lifecycle events.
-  return finalizeSession({
-    userAgent,
-    emitter,
-    storage,
-    connectedDid,
-    delegateDid,
-    identityName         : identity.metadata.name,
-    identityConnectedDid : identity.metadata.connectedDid,
-  });
-}
+import { finalizeSession, registerSyncScopeForIdentity, resolveIdentityDids, startSyncIfEnabled } from './lifecycle.js';
 
 /**
  * Import an identity from a PortableIdentity JSON object.

package/src/connect/lifecycle.ts

@@ -25,9 +25,10 @@ import { Convert } from '@enbox/common';
 import type { GenericMessage } from '@enbox/dwn-sdk-js';
 
 import { DataStream, PermissionsProtocol } from '@enbox/dwn-sdk-js';
-import { DwnInterface, DwnPermissionGrant, KeyDeliveryProtocolDefinition } from '@enbox/agent';
+import { DwnInterface, DwnPermissionGrant, HdIdentityVaultRecoveryPhraseMismatchError, KeyDeliveryProtocolDefinition } from '@enbox/agent';
 
 import { AuthSession } from '../identity-session.js';
+import { RecoveryPhraseMismatchError } from '../errors.js';
 import { DEFAULT_DWN_ENDPOINTS, INSECURE_DEFAULT_PASSWORD, STORAGE_KEYS } from '../types.js';
 
 // ─── FlowContext ─────────────────────────────────────────────────
@@ -109,7 +110,7 @@ export async function resolvePassword(
 // ─── ensureVaultReady ────────────────────────────────────────────
 
 /**
- * Initialize (on first launch) and start the agent, then emit `vault-unlocked`.
+ * Initialize or recover the vault, start the agent, then emit `vault-unlocked`.
  *
  * This consolidates the 5 copies of:
  * ```ts
@@ -118,6 +119,9 @@ export async function resolvePassword(
  * emitter.emit('vault-unlocked', {});
  * ```
  *
+ * When `recoveryPhrase` is supplied for an already-initialized vault, the phrase is verified
+ * against the stored agent DID and the vault password is reset without replacing local data.
+ *
  * @returns The recovery phrase if the vault was just initialized, otherwise `undefined`.
  *
  * @internal
@@ -139,6 +143,18 @@ export async function ensureVaultReady(params: {
       recoveryPhrase : params.recoveryPhrase,
       dwnEndpoints   : params.dwnEndpoints,
     });
+  } else if (params.recoveryPhrase) {
+    try {
+      await userAgent.vault.resetPasswordWithRecoveryPhrase({
+        recoveryPhrase: params.recoveryPhrase,
+        password,
+      });
+    } catch (error) {
+      if (error instanceof HdIdentityVaultRecoveryPhraseMismatchError) {
+        throw new RecoveryPhraseMismatchError();
+      }
+      throw error;
+    }
   }
 
   await userAgent.start({ password });
@@ -184,7 +200,7 @@ export async function startSyncIfEnabled(
  * encryption keys, and a DWN service endpoint.
  *
  * This consolidates the identical identity creation block that was
- * duplicated in `vaultConnect` and `importFromPhrase`.
+ * duplicated across vault recovery and identity import flows.
  *
  * @internal
  */

package/src/connect/vault.ts

@@ -16,7 +16,7 @@ import type { VaultConnectOptions } from '../types.js';
 import { applyLocalDwnDiscovery } from '../discovery.js';
 import { DEFAULT_DWN_ENDPOINTS } from '../types.js';
 import { registerWithDwnEndpoints } from '../registration.js';
-import { createDefaultIdentity, ensureVaultReady, finalizeSession, resolveIdentityDids, resolvePassword, startSyncIfEnabled } from './lifecycle.js';
+import { createDefaultIdentity, ensureVaultReady, finalizeSession, registerSyncScopeForIdentity, resolveIdentityDids, resolvePassword, startSyncIfEnabled } from './lifecycle.js';
 import { recoverIdentitiesFromRemote, registerAgentDidForSync } from './recovery.js';
 
 /**
@@ -26,8 +26,8 @@ import { recoverIdentitiesFromRemote, registerAgentDidForSync } from './recovery
  *   `options.createIdentity: true`.
  * - On subsequent launches: unlocks the vault and reconnects to the existing identity.
  * - On recovery: when `recoveryPhrase` is provided on a fresh vault, pulls
- *   identities and their data from the remote DWN before falling back to
- *   identity creation.
+ *   identities and their data from the remote DWN before optionally creating
+ *   a default identity.
  *
  * When no identities exist and `createIdentity` is not `true`, the session
  * is returned with the **agent DID** as the connected DID. This allows apps to
@@ -88,9 +88,9 @@ export async function vaultConnect(
   let identity = identities[0];
   let isNewIdentity = false;
 
-  // Seed phrase recovery: when a recovery phrase was provided on a fresh
-  // vault and no identities exist locally, pull them from the remote DWN.
-  if (!identity && isFirstLaunch && options.recoveryPhrase && sync !== 'off') {
+  // Seed phrase recovery: when a recovery phrase was provided and no identities exist locally,
+  // pull them from the remote DWN before deciding whether to create a new identity.
+  if (!identity && options.recoveryPhrase && sync !== 'off') {
     try {
       identities = await recoverIdentitiesFromRemote({ userAgent, dwnEndpoints, registration: ctx.registration, storage });
       identity = identities[0];
@@ -99,7 +99,7 @@ export async function vaultConnect(
     }
   }
 
-  // Create a default identity if none were found or recovered.
+  // Create a default identity if none were found or recovered and the caller asked for one.
   if (!identity && shouldCreateIdentity) {
     isNewIdentity = true;
     identity = await createDefaultIdentity(userAgent, dwnEndpoints, options.metadata?.name ?? 'Default');
@@ -108,13 +108,9 @@ export async function vaultConnect(
   // When no identity exists (createIdentity: false on first launch), use the
   // agent DID as the session's connected DID. The session is still valid but
   // operates in the agent's context rather than a user identity's context.
-  const connectedDid = identity
-    ? resolveIdentityDids(identity).connectedDid
-    : userAgent.agentDid.uri;
-
-  const delegateDid = identity
-    ? resolveIdentityDids(identity).delegateDid
-    : undefined;
+  const identityDids = identity ? resolveIdentityDids(identity) : undefined;
+  const connectedDid = identityDids?.connectedDid ?? userAgent.agentDid.uri;
+  const delegateDid = identityDids?.delegateDid;
 
   // Register the new identity DID as a tenant and for sync.
   // Tenant registration must come before sync registration — with live
@@ -134,10 +130,11 @@ export async function vaultConnect(
     );
   }
   if (isNewIdentity && sync !== 'off') {
-    await userAgent.sync.registerIdentity({
-      did     : connectedDid,
-      options : { delegateDid, protocols: 'all' },
-    });
+    await registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
+  } else if (!isNewIdentity && delegateDid) {
+    // Persisted delegate identities need their sync scope refreshed from
+    // current grants so revoked protocols do not keep syncing after restore.
+    await registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
   }
 
   // Start sync.

package/src/errors.ts

@@ -0,0 +1,12 @@
+export class RecoveryPhraseMismatchError extends Error {
+  public readonly code = 'RECOVERY_PHRASE_MISMATCH';
+
+  constructor(message = 'Recovery phrase does not match the initialized vault.') {
+    super(message);
+    this.name = 'RecoveryPhraseMismatchError';
+  }
+}
+
+export function isRecoveryPhraseMismatchError(error: unknown): error is RecoveryPhraseMismatchError {
+  return error instanceof RecoveryPhraseMismatchError;
+}

package/src/identity-session.ts

@@ -11,7 +11,7 @@
  * ```ts
  * import { Enbox } from '@enbox/api';
  *
- * const session = await auth.connect();
+ * const session = await auth.connectVault({ createIdentity: true });
  * const enbox = Enbox.fromSession(session);
  * ```
  *

package/src/index.ts

@@ -10,7 +10,7 @@
  * import { AuthManager } from '@enbox/auth';
  *
  * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.connectVault({ password: userPin });
+ * const session = await auth.connectVault({ password: userPin, createIdentity: true });
  * ```
  *
  * @example Dapp with browser connect handler
@@ -31,6 +31,7 @@
 export { AuthManager } from './auth-manager.js';
 export { AuthSession } from './identity-session.js';
 export { AuthEventEmitter } from './events.js';
+export { RecoveryPhraseMismatchError, isRecoveryPhraseMismatchError } from './errors.js';
 
 // Password providers
 export { PasswordProvider } from './password-provider.js';
@@ -86,9 +87,7 @@ export type {
   HeadlessConnectOptions,
   IdentityInfo,
   IdentityVaultBackup,
-  ImportFromPhraseOptions,
   ImportFromPortableOptions,
-  LocalConnectOptions,
   LocalDwnStrategy,
   VaultConnectOptions,
   Permission,
@@ -98,6 +97,7 @@ export type {
   ProviderAuthResult,
   RegistrationOptions,
   RegistrationTokenData,
+  RestoreFromPhraseOptions,
   RestoreSessionOptions,
   ShutdownOptions,
   StorageAdapter,

package/src/types.ts

@@ -403,7 +403,7 @@ export interface VaultConnectOptions {
   /** Vault password (overrides manager default). */
   password?: string;
 
-  /** Re-derive identity from an existing BIP-39 recovery phrase. */
+  /** Initialize or recover the vault from an existing BIP-39 recovery phrase. */
   recoveryPhrase?: string;
 
   /** Override manager default sync interval. */
@@ -434,8 +434,18 @@ export interface VaultConnectOptions {
   createIdentity?: boolean;
 }
 
-/** @deprecated Use {@link VaultConnectOptions} instead. */
-export type LocalConnectOptions = VaultConnectOptions;
+/** Options for {@link AuthManager.restoreFromPhrase}. */
+export interface RestoreFromPhraseOptions extends Omit<VaultConnectOptions, 'password' | 'recoveryPhrase'> {
+  /** The BIP-39 recovery phrase for the existing or remote wallet vault. */
+  recoveryPhrase: string;
+
+  /**
+   * Password to protect the restored vault locally.
+   *
+   * If the local vault already belongs to this phrase, this becomes the new local unlock password.
+   */
+  password: string;
+}
 
 // ─── DWeb Connect ────────────────────────────────────────────────
 
@@ -508,16 +518,19 @@ export interface HandlerConnectOptions {
  *
  * `connect()` routes to the appropriate flow based on the options:
  *
+ * - **Recovery phrase restore** (wallets / CLI): triggered first when
+ *   `recoveryPhrase` is provided.
+ *
  * - **Handler-based connect** (dapps): triggered when `protocols` or
- *   `connectHandler` is provided. Delegates to the connect handler
- *   for credential acquisition.
+ *   `connectHandler` is provided and no `recoveryPhrase` is present.
+ *   Delegates to the connect handler for credential acquisition.
  *
  * - **Vault connect** (wallets / CLI): triggered when `password`,
  *   `createIdentity`, or `recoveryPhrase` is provided.
  *
- * In both cases, `connect()` first attempts to restore a previous session
- * from storage. If a valid session exists, it is returned immediately
- * without any user interaction.
+ * `connect()` first attempts to restore a previous session from storage
+ * unless `recoveryPhrase` is provided. Recovery is treated as an explicit
+ * user action and routes directly to the phrase restore flow.
  */
 export type ConnectOptions = HandlerConnectOptions | VaultConnectOptions;
 
@@ -552,21 +565,6 @@ export interface WalletConnectOptions {
   sync?: SyncOption;
 }
 
-/** Options for {@link AuthManager.importFromPhrase}. */
-export interface ImportFromPhraseOptions {
-  /** The BIP-39 recovery phrase. */
-  recoveryPhrase: string;
-
-  /** Password to protect the vault. */
-  password: string;
-
-  /** Override manager default sync interval. */
-  sync?: SyncOption;
-
-  /** Override manager default DWN endpoints. */
-  dwnEndpoints?: string[];
-}
-
 /** Options for {@link AuthManager.importFromPortable}. */
 export interface ImportFromPortableOptions {
   /** The portable identity JSON to import. */