@enbox/auth 0.5.0 → 0.6.1

package/src/auth-manager.ts

@@ -6,26 +6,19 @@
  * @module
  */
 
-import { EnboxUserAgent } from '@enbox/agent';
-import type { BearerIdentity, PortableIdentity } from '@enbox/agent';
-
-import { AuthEventEmitter } from './events.js';
-import { AuthSession } from './identity-session.js';
-import { createDefaultStorage } from './storage/storage.js';
-import { discoverLocalDwn } from './flows/dwn-discovery.js';
-import { localConnect } from './flows/local-connect.js';
-import { restoreSession } from './flows/session-restore.js';
-import { STORAGE_KEYS } from './types.js';
-import { VaultManager } from './vault/vault-manager.js';
-import { walletConnect } from './flows/wallet-connect.js';
+import type { BearerIdentity, HdIdentityVault, PortableIdentity } from '@enbox/agent';
 
+import type { FlowContext } from './connect/lifecycle.js';
 import type { PasswordProvider } from './password-provider.js';
 import type {
   AuthEvent,
   AuthEventHandler,
   AuthManagerOptions,
   AuthState,
+  ConnectHandler,
+  ConnectOptions,
   DisconnectOptions,
+  HandlerConnectOptions,
   HeadlessConnectOptions,
   IdentityInfo,
   ImportFromPhraseOptions,
@@ -38,7 +31,20 @@ import type {
   SyncOption,
   WalletConnectOptions,
 } from './types.js';
-import { importFromPhrase, importFromPortable } from './flows/import-identity.js';
+
+import { EnboxUserAgent } from '@enbox/agent';
+
+import { AuthEventEmitter } from './events.js';
+import { AuthSession } from './identity-session.js';
+import { createDefaultStorage } from './storage/storage.js';
+import { discoverLocalDwn } from './discovery.js';
+import { localConnect } from './connect/local.js';
+import { normalizeProtocolRequests } from './permissions.js';
+import { restoreSession } from './connect/restore.js';
+import { STORAGE_KEYS } from './types.js';
+import { walletConnect } from './connect/wallet.js';
+import { ensureVaultReady, finalizeDelegateSession, importDelegateAndSetupSync, resolveIdentityDids, resolvePassword, startSyncIfEnabled } from './connect/lifecycle.js';
+import { importFromPhrase, importFromPortable } from './connect/import.js';
 
 /**
  * The primary entry point for authentication and identity management.
@@ -77,7 +83,6 @@ export class AuthManager {
   private _userAgent: EnboxUserAgent;
   private _emitter: AuthEventEmitter;
   private _storage: StorageAdapter;
-  private _vault: VaultManager;
   private _session: AuthSession | undefined;
   private _state: AuthState = 'uninitialized';
   private _isConnecting = false;
@@ -89,6 +94,7 @@ export class AuthManager {
   private _defaultSync?: SyncOption;
   private _defaultDwnEndpoints?: string[];
   private _registration?: RegistrationOptions;
+  private _connectHandler?: ConnectHandler;
 
   /**
    * The local DWN server endpoint discovered during `create()`, if any.
@@ -102,24 +108,24 @@ export class AuthManager {
     userAgent: EnboxUserAgent;
     emitter: AuthEventEmitter;
     storage: StorageAdapter;
-    vault: VaultManager;
     defaultPassword?: string;
     passwordProvider?: PasswordProvider;
     defaultSync?: SyncOption;
     defaultDwnEndpoints?: string[];
     registration?: RegistrationOptions;
     localDwnEndpoint?: string;
+    connectHandler?: ConnectHandler;
   }) {
     this._userAgent = params.userAgent;
     this._emitter = params.emitter;
     this._storage = params.storage;
-    this._vault = params.vault;
     this._defaultPassword = params.defaultPassword;
     this._passwordProvider = params.passwordProvider;
     this._defaultSync = params.defaultSync;
     this._defaultDwnEndpoints = params.defaultDwnEndpoints;
     this._registration = params.registration;
     this._localDwnEndpoint = params.localDwnEndpoint;
+    this._connectHandler = params.connectHandler;
   }
 
   /**
@@ -159,24 +165,22 @@ export class AuthManager {
       localDwnEndpoint,
     });
 
-    const vault = new VaultManager(userAgent.vault, emitter);
-
     const manager = new AuthManager({
       userAgent,
       emitter,
       storage,
-      vault,
       defaultPassword     : options.password,
       passwordProvider    : options.passwordProvider,
       defaultSync         : options.sync,
       defaultDwnEndpoints : options.dwnEndpoints,
       registration        : options.registration,
       localDwnEndpoint,
+      connectHandler      : options.connectHandler,
     });
 
     // Determine initial state.
-    if (await vault.isInitialized()) {
-      manager._setState(vault.isLocked ? 'locked' : 'unlocked');
+    if (await userAgent.vault.isInitialized()) {
+      manager._setState(userAgent.vault.isLocked() ? 'locked' : 'unlocked');
     } else {
       manager._setState('uninitialized');
     }
@@ -187,40 +191,75 @@ export class AuthManager {
   // ─── Connection flows ──────────────────────────────────────────
 
   /**
-   * Create or reconnect a local identity.
+   * Connect to a wallet or create a local session.
+   *
+   * This is the primary entry point for dapps. It routes to the
+   * appropriate flow based on the options:
+   *
+   * **Handler-based connect** (dapps): Delegates credential acquisition
+   * to a {@link ConnectHandler}. Triggered when `protocols` or
+   * `connectHandler` is provided.
+   *
+   * **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.
+   *
+   * @example Dapp (browser)
+   * ```ts
+   * import { BrowserConnectHandler } from '@enbox/browser';
+   *
+   * const auth = await AuthManager.create({
+   *   connectHandler: BrowserConnectHandler(),
+   * });
+   * const session = await auth.connect({
+   *   protocols: [NotesProtocol],
+   * });
+   * ```
    *
-   * On first use, this creates a new vault, agent DID, and user identity.
-   * On subsequent uses, it unlocks the vault and reconnects.
+   * @example Wallet / CLI
+   * ```ts
+   * const session = await auth.connect({
+   *   password: userPin,
+   *   createIdentity: true,
+   * });
+   * ```
    *
-   * @param options - Optional overrides for password, sync, DWN endpoints.
+   * @param options - Connection options. The shape determines the flow.
    * @returns An active AuthSession.
    * @throws If a connection attempt is already in progress.
+   * @throws If handler-based connect is attempted without a handler.
    */
-  async connect(options?: LocalConnectOptions): Promise<AuthSession> {
-    this._guardConcurrency();
-    this._isConnecting = true;
+  async connect(options?: ConnectOptions): Promise<AuthSession> {
+    return this._withConnect(async () => {
+      // 1. Try to restore a previous session first.
+      const restored = await restoreSession(this._flowContext());
+      if (restored) { return restored; }
+
+      // 2. Route to the appropriate flow.
+      if (this._isLocalConnect(options)) {
+        return localConnect(this._flowContext(), options as LocalConnectOptions);
+      }
 
-    try {
-      const session = await localConnect(
-        {
-          userAgent           : this._userAgent,
-          emitter             : this._emitter,
-          storage             : this._storage,
-          defaultPassword     : this._defaultPassword,
-          passwordProvider    : this._passwordProvider,
-          defaultSync         : this._defaultSync,
-          defaultDwnEndpoints : this._defaultDwnEndpoints,
-          registration        : this._registration,
-        },
-        options,
-      );
+      return this._handlerConnect(options as HandlerConnectOptions | undefined);
+    });
+  }
 
-      this._session = session;
-      this._setState('connected');
-      return session;
-    } finally {
-      this._isConnecting = false;
-    }
+  /**
+   * Create or reconnect a local identity (explicit local connect).
+   *
+   * Use this when you explicitly want the local vault flow, bypassing
+   * auto-detection. This is the preferred method for wallet apps.
+   *
+   * @param options - Local connect options.
+   * @returns An active AuthSession.
+   * @throws If a connection attempt is already in progress.
+   */
+  async connectLocal(options?: LocalConnectOptions): Promise<AuthSession> {
+    return this._withConnect(() => localConnect(this._flowContext(), options));
   }
 
   /**
@@ -235,50 +274,7 @@ export class AuthManager {
    * @throws If a connection attempt is already in progress.
    */
   async walletConnect(options: WalletConnectOptions): Promise<AuthSession> {
-    this._guardConcurrency();
-    this._isConnecting = true;
-
-    try {
-      // Ensure the agent is initialized and started before wallet connect.
-      const isFirstLaunch = await this._userAgent.firstLaunch();
-      let password = this._defaultPassword;
-
-      if (!password && this._passwordProvider) {
-        try {
-          password = await this._passwordProvider.getPassword({
-            reason: isFirstLaunch ? 'create' : 'unlock',
-          });
-        } catch {
-          // Provider failed — fall through to insecure default.
-        }
-      }
-
-      password ??= 'insecure-static-phrase';
-
-      if (isFirstLaunch) {
-        await this._userAgent.initialize({ password });
-      }
-      await this._userAgent.start({ password });
-      this._emitter.emit('vault-unlocked', {});
-
-      const session = await walletConnect(
-        {
-          userAgent           : this._userAgent,
-          emitter             : this._emitter,
-          storage             : this._storage,
-          defaultSync         : this._defaultSync,
-          defaultDwnEndpoints : this._defaultDwnEndpoints,
-          registration        : this._registration,
-        },
-        options,
-      );
-
-      this._session = session;
-      this._setState('connected');
-      return session;
-    } finally {
-      this._isConnecting = false;
-    }
+    return this._withConnect(() => walletConnect(this._flowContext(), options));
   }
 
   /**
@@ -288,28 +284,7 @@ export class AuthManager {
    * recovering the identity on this device.
    */
   async importFromPhrase(options: ImportFromPhraseOptions): Promise<AuthSession> {
-    this._guardConcurrency();
-    this._isConnecting = true;
-
-    try {
-      const session = await importFromPhrase(
-        {
-          userAgent           : this._userAgent,
-          emitter             : this._emitter,
-          storage             : this._storage,
-          defaultSync         : this._defaultSync,
-          defaultDwnEndpoints : this._defaultDwnEndpoints,
-          registration        : this._registration,
-        },
-        options,
-      );
-
-      this._session = session;
-      this._setState('connected');
-      return session;
-    } finally {
-      this._isConnecting = false;
-    }
+    return this._withConnect(() => importFromPhrase(this._flowContext(), options));
   }
 
   /**
@@ -318,28 +293,7 @@ export class AuthManager {
    * The portable identity contains the DID's private keys and metadata.
    */
   async importFromPortable(options: ImportFromPortableOptions): Promise<AuthSession> {
-    this._guardConcurrency();
-    this._isConnecting = true;
-
-    try {
-      const session = await importFromPortable(
-        {
-          userAgent           : this._userAgent,
-          emitter             : this._emitter,
-          storage             : this._storage,
-          defaultSync         : this._defaultSync,
-          defaultDwnEndpoints : this._defaultDwnEndpoints,
-          registration        : this._registration,
-        },
-        options,
-      );
-
-      this._session = session;
-      this._setState('connected');
-      return session;
-    } finally {
-      this._isConnecting = false;
-    }
+    return this._withConnect(() => importFromPortable(this._flowContext(), options));
   }
 
   /**
@@ -353,17 +307,7 @@ export class AuthManager {
     this._isConnecting = true;
 
     try {
-      const session = await restoreSession(
-        {
-          userAgent        : this._userAgent,
-          emitter          : this._emitter,
-          storage          : this._storage,
-          defaultPassword  : this._defaultPassword,
-          passwordProvider : this._passwordProvider,
-          defaultSync      : this._defaultSync,
-        },
-        options,
-      );
+      const session = await restoreSession(this._flowContext(), options);
 
       if (session) {
         this._session = session;
@@ -400,10 +344,10 @@ export class AuthManager {
    */
   async connectHeadless(options?: HeadlessConnectOptions): Promise<AuthSession> {
     let password = options?.password ?? this._defaultPassword;
+    const isFirstLaunch = await this._userAgent.firstLaunch();
 
     // Try the password provider if no explicit password.
     if (!password && this._passwordProvider) {
-      const isFirstLaunch = await this._userAgent.firstLaunch();
       password = await this._passwordProvider.getPassword({
         reason: isFirstLaunch ? 'create' : 'unlock',
       });
@@ -416,13 +360,13 @@ export class AuthManager {
       );
     }
 
-    // Unlock the vault (initialise on first launch).
-    if (await this._userAgent.firstLaunch()) {
-      await this._userAgent.initialize({ password });
-    } else {
-      await this._userAgent.start({ password });
-    }
-    this._emitter.emit('vault-unlocked', {});
+    // Unlock the vault (initialise on first launch, always start).
+    await ensureVaultReady({
+      userAgent : this._userAgent,
+      emitter   : this._emitter,
+      password,
+      isFirstLaunch,
+    });
 
     // Find the active identity.
     const identities = await this._userAgent.identity.list();
@@ -437,8 +381,7 @@ export class AuthManager {
       : undefined
     ) ?? identities[0];
 
-    const connectedDid = identity.metadata.connectedDid ?? identity.did.uri;
-    const delegateDid = identity.metadata.connectedDid ? identity.did.uri : undefined;
+    const { connectedDid, delegateDid } = resolveIdentityDids(identity);
 
     const identityInfo: IdentityInfo = {
       didUri       : connectedDid,
@@ -484,15 +427,14 @@ export class AuthManager {
     const did = this._session?.did;
 
     // 1. Stop sync.
-    if ('sync' in this._userAgent && typeof (this._userAgent as any).sync?.stopSync === 'function') {
-      await (this._userAgent as any).sync.stopSync(timeout);
-    }
+    await this._userAgent.sync.stopSync(timeout);
 
     // 2. Clear the session (but keep storage markers for restore).
     this._session = undefined;
 
-    // 3. Lock the vault (also emits 'vault-locked').
-    await this._vault.lock();
+    // 3. Lock the vault.
+    await this._userAgent.vault.lock();
+    this._emitter.emit('vault-locked', {});
 
     // 4. Transition state.
     this._setState('locked');
@@ -517,9 +459,7 @@ export class AuthManager {
 
     // Stop sync.
     if (this._session) {
-      if ('sync' in this._userAgent && typeof (this._userAgent as any).sync?.stopSync === 'function') {
-        await (this._userAgent as any).sync.stopSync(timeout);
-      }
+      await this._userAgent.sync.stopSync(timeout);
     }
 
     this._session = undefined;
@@ -591,33 +531,28 @@ export class AuthManager {
     const did = this._session?.did;
 
     // 1. Stop sync.
-    if ('sync' in this._userAgent &&
-        typeof (this._userAgent as any).sync?.stopSync === 'function') {
-      try {
-        await (this._userAgent as any).sync.stopSync(timeout);
-      } catch {
-        // Best-effort — don't block shutdown on sync errors.
-      }
+    try {
+      await this._userAgent.sync.stopSync(timeout);
+    } catch {
+      // Best-effort — don't block shutdown on sync errors.
     }
 
     // 2. Clear the active session.
     this._session = undefined;
 
-    // 3. Lock the vault (emits 'vault-locked').
+    // 3. Lock the vault.
     try {
-      await this._vault.lock();
+      await this._userAgent.vault.lock();
+      this._emitter.emit('vault-locked', {});
     } catch {
       // Vault may already be locked or uninitialised — safe to ignore.
     }
 
     // 4. Close the sync engine (releases LevelDB handles, timers).
-    if ('sync' in this._userAgent &&
-        typeof (this._userAgent as any).sync?.close === 'function') {
-      try {
-        await (this._userAgent as any).sync.close();
-      } catch {
-        // Best-effort.
-      }
+    try {
+      await this._userAgent.sync.close();
+    } catch {
+      // Best-effort.
     }
 
     // 5. Close the storage adapter (e.g. LevelDB session store).
@@ -673,8 +608,7 @@ export class AuthManager {
       throw new Error(`[@enbox/auth] Identity not found: ${didUri}`);
     }
 
-    const connectedDid = identity.metadata.connectedDid ?? identity.did.uri;
-    const delegateDid = identity.metadata.connectedDid ? identity.did.uri : undefined;
+    const { connectedDid, delegateDid } = resolveIdentityDids(identity);
 
     // Persist the switch.
     await this._storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
@@ -699,10 +633,7 @@ export class AuthManager {
         // Already registered — safe to ignore.
       }
 
-      const syncMode = sync === undefined ? 'live' : 'poll';
-      const syncInterval = sync ?? (syncMode === 'live' ? '5m' : '2m');
-      this._userAgent.sync.startSync({ mode: syncMode, interval: syncInterval })
-        .catch((err: unknown) => console.error('[@enbox/auth] Sync failed:', err));
+      startSyncIfEnabled(this._userAgent, sync);
     }
 
     this._session = new AuthSession({
@@ -768,9 +699,9 @@ export class AuthManager {
 
   // ─── Vault ─────────────────────────────────────────────────────
 
-  /** Access the vault manager for lock/unlock/backup operations. */
-  get vault(): VaultManager {
-    return this._vault;
+  /** Access the underlying identity vault for lock/unlock/backup operations. */
+  get vault(): HdIdentityVault {
+    return this._userAgent.vault;
   }
 
   // ─── Events ────────────────────────────────────────────────────
@@ -800,7 +731,7 @@ export class AuthManager {
 
   /** Whether the vault is currently locked. */
   get isLocked(): boolean {
-    return this._vault.isLocked;
+    return this._userAgent.vault.isLocked();
   }
 
   /** Whether a connection attempt is in progress. */
@@ -826,6 +757,142 @@ export class AuthManager {
 
   // ─── Private helpers ───────────────────────────────────────────
 
+  /**
+   * Determine whether the given options indicate a local connect flow.
+   *
+   * Local connect is indicated by the presence of `password`,
+   * `createIdentity`, or `recoveryPhrase` — signals that the caller
+   * is managing its own vault/identity lifecycle. In non-browser
+   * environments, local connect is the fallback.
+   */
+  private _isLocalConnect(options?: ConnectOptions): boolean {
+    const o = (options ?? {}) as Record<string, unknown>;
+
+    // If any local-connect-specific keys are present, it's definitely local.
+    const hasLocalSignals = (
+      o.password !== undefined ||
+      o.createIdentity !== undefined ||
+      o.recoveryPhrase !== undefined ||
+      o.dwnEndpoints !== undefined ||
+      o.metadata !== undefined
+    );
+    if (hasLocalSignals) { return true; }
+
+    // If any handler-connect signals are present, use the handler flow.
+    const hasHandlerSignals = (
+      o.protocols !== undefined ||
+      o.connectHandler !== undefined
+    );
+    if (hasHandlerSignals) { return false; }
+
+    // No explicit signals → default to local connect.
+    // Callers that want handler-based connect must provide protocols
+    // or a connectHandler.
+    return true;
+  }
+
+  /**
+   * Run a handler-based (delegated) connect flow.
+   *
+   * 1. Initialize the vault (agent-only, no identity).
+   * 2. Normalize protocol permission requests.
+   * 3. Delegate to the connect handler for credential acquisition.
+   * 4. Import the delegate DID, process grants, set up sync.
+   * 5. Finalize and return the AuthSession.
+   */
+  private async _handlerConnect(
+    options?: HandlerConnectOptions,
+  ): Promise<AuthSession> {
+    const ctx = this._flowContext();
+    const { userAgent, emitter, storage } = ctx;
+    const sync = options?.sync ?? ctx.defaultSync;
+
+    if (sync === 'off') {
+      throw new Error(
+        '[@enbox/auth] Sync must be enabled for delegated connect. ' +
+        'Remove sync: "off" or set an interval like "15s".'
+      );
+    }
+
+    // 1. Initialize vault (agent-only, no identity).
+    const isFirstLaunch = await userAgent.firstLaunch();
+    const password = await resolvePassword(ctx, undefined, isFirstLaunch);
+    await ensureVaultReady({ userAgent, emitter, password, isFirstLaunch });
+
+    // 2. Normalize protocol requests.
+    const permissionRequests = normalizeProtocolRequests(options?.protocols);
+
+    // 3. Resolve the handler.
+    const handler = options?.connectHandler ?? this._connectHandler;
+    if (!handler) {
+      throw new Error(
+        '[@enbox/auth] No connect handler provided. ' +
+        'Install @enbox/browser and pass BrowserConnectHandler(), ' +
+        'or provide a custom ConnectHandler.'
+      );
+    }
+
+    // 4. Delegate to the handler.
+    const result = await handler.requestAccess({ permissionRequests });
+    if (!result) {
+      throw new Error('[@enbox/auth] Connect was denied or cancelled by the user.');
+    }
+
+    // 5. Import delegate DID, process grants, set up sync.
+    const { delegatePortableDid, connectedDid, delegateGrants } = result;
+    const identity = await importDelegateAndSetupSync({
+      userAgent, delegatePortableDid, connectedDid, delegateGrants,
+      flowName: 'Connect',
+    });
+
+    // 6. Finalize session.
+    return finalizeDelegateSession({
+      userAgent, emitter, storage, identity,
+      connectedDid, delegateDid: delegatePortableDid.uri, sync,
+    });
+  }
+
+  /**
+   * Build a `FlowContext` from the manager's current state.
+   *
+   * Replaces the 5 manual inline context constructions that were
+   * previously duplicated across `connect()`, `walletConnect()`,
+   * `importFromPhrase()`, `importFromPortable()`, and `restoreSession()`.
+   */
+  private _flowContext(): FlowContext {
+    return {
+      userAgent           : this._userAgent,
+      emitter             : this._emitter,
+      storage             : this._storage,
+      defaultPassword     : this._defaultPassword,
+      passwordProvider    : this._passwordProvider,
+      defaultSync         : this._defaultSync,
+      defaultDwnEndpoints : this._defaultDwnEndpoints,
+      registration        : this._registration,
+    };
+  }
+
+  /**
+   * Template for connection flows that follow the guard → try/finally → setState pattern.
+   *
+   * Consolidates the duplicated concurrency guard, `_isConnecting` flag management,
+   * session assignment, and state transition across `connect()`, `walletConnect()`,
+   * `importFromPhrase()`, and `importFromPortable()`.
+   */
+  private async _withConnect(fn: () => Promise<AuthSession>): Promise<AuthSession> {
+    this._guardConcurrency();
+    this._isConnecting = true;
+
+    try {
+      const session = await fn();
+      this._session = session;
+      this._setState('connected');
+      return session;
+    } finally {
+      this._isConnecting = false;
+    }
+  }
+
   private _setState(state: AuthState): void {
     if (state === this._state) {return;}
     const previous = this._state;