@enbox/auth 0.5.0 → 0.6.1

package/dist/esm/auth-manager.js

@@ -18,13 +18,14 @@ 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 './flows/dwn-discovery.js';
-import { localConnect } from './flows/local-connect.js';
-import { restoreSession } from './flows/session-restore.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 { VaultManager } from './vault/vault-manager.js';
-import { walletConnect } from './flows/wallet-connect.js';
-import { importFromPhrase, importFromPortable } from './flows/import-identity.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.
  *
@@ -66,13 +67,13 @@ export class AuthManager {
         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;
     }
     /**
      * Create a new AuthManager instance.
@@ -110,22 +111,21 @@ export class AuthManager {
                 localDwnStrategy: options.localDwnStrategy,
                 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 (yield vault.isInitialized()) {
-                manager._setState(vault.isLocked ? 'locked' : 'unlocked');
+            if (yield userAgent.vault.isInitialized()) {
+                manager._setState(userAgent.vault.isLocked() ? 'locked' : 'unlocked');
             }
             else {
                 manager._setState('uninitialized');
@@ -135,37 +135,77 @@ export class AuthManager {
     }
     // ─── Connection flows ──────────────────────────────────────────
     /**
-     * Create or reconnect a local identity.
+     * Connect to a wallet or create a local session.
      *
-     * On first use, this creates a new vault, agent DID, and user identity.
-     * On subsequent uses, it unlocks the vault and reconnects.
+     * This is the primary entry point for dapps. It routes to the
+     * appropriate flow based on the options:
      *
-     * @param options - Optional overrides for password, sync, DWN endpoints.
+     * **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],
+     * });
+     * ```
+     *
+     * @example Wallet / CLI
+     * ```ts
+     * const session = await auth.connect({
+     *   password: userPin,
+     *   createIdentity: true,
+     * });
+     * ```
+     *
+     * @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.
      */
     connect(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            this._guardConcurrency();
-            this._isConnecting = true;
-            try {
-                const session = yield 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);
-                this._session = session;
-                this._setState('connected');
-                return session;
-            }
-            finally {
-                this._isConnecting = false;
-            }
+            return this._withConnect(() => __awaiter(this, void 0, void 0, function* () {
+                // 1. Try to restore a previous session first.
+                const restored = yield restoreSession(this._flowContext());
+                if (restored) {
+                    return restored;
+                }
+                // 2. Route to the appropriate flow.
+                if (this._isLocalConnect(options)) {
+                    return localConnect(this._flowContext(), options);
+                }
+                return this._handlerConnect(options);
+            }));
+        });
+    }
+    /**
+     * 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.
+     */
+    connectLocal(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._withConnect(() => localConnect(this._flowContext(), options));
         });
     }
     /**
@@ -181,43 +221,7 @@ export class AuthManager {
      */
     walletConnect(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            this._guardConcurrency();
-            this._isConnecting = true;
-            try {
-                // Ensure the agent is initialized and started before wallet connect.
-                const isFirstLaunch = yield this._userAgent.firstLaunch();
-                let password = this._defaultPassword;
-                if (!password && this._passwordProvider) {
-                    try {
-                        password = yield this._passwordProvider.getPassword({
-                            reason: isFirstLaunch ? 'create' : 'unlock',
-                        });
-                    }
-                    catch (_a) {
-                        // Provider failed — fall through to insecure default.
-                    }
-                }
-                password !== null && password !== void 0 ? password : (password = 'insecure-static-phrase');
-                if (isFirstLaunch) {
-                    yield this._userAgent.initialize({ password });
-                }
-                yield this._userAgent.start({ password });
-                this._emitter.emit('vault-unlocked', {});
-                const session = yield 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));
         });
     }
     /**
@@ -228,24 +232,7 @@ export class AuthManager {
      */
     importFromPhrase(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            this._guardConcurrency();
-            this._isConnecting = true;
-            try {
-                const session = yield 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));
         });
     }
     /**
@@ -255,24 +242,7 @@ export class AuthManager {
      */
     importFromPortable(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            this._guardConcurrency();
-            this._isConnecting = true;
-            try {
-                const session = yield 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));
         });
     }
     /**
@@ -286,14 +256,7 @@ export class AuthManager {
             this._guardConcurrency();
             this._isConnecting = true;
             try {
-                const session = yield restoreSession({
-                    userAgent: this._userAgent,
-                    emitter: this._emitter,
-                    storage: this._storage,
-                    defaultPassword: this._defaultPassword,
-                    passwordProvider: this._passwordProvider,
-                    defaultSync: this._defaultSync,
-                }, options);
+                const session = yield restoreSession(this._flowContext(), options);
                 if (session) {
                     this._session = session;
                     this._setState('connected');
@@ -330,11 +293,11 @@ export class AuthManager {
      */
     connectHeadless(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c;
+            var _a, _b;
             let password = (_a = options === null || options === void 0 ? void 0 : options.password) !== null && _a !== void 0 ? _a : this._defaultPassword;
+            const isFirstLaunch = yield this._userAgent.firstLaunch();
             // Try the password provider if no explicit password.
             if (!password && this._passwordProvider) {
-                const isFirstLaunch = yield this._userAgent.firstLaunch();
                 password = yield this._passwordProvider.getPassword({
                     reason: isFirstLaunch ? 'create' : 'unlock',
                 });
@@ -343,14 +306,13 @@ export class AuthManager {
                 throw new Error('[@enbox/auth] connectHeadless() requires a password. ' +
                     'Provide one via options.password, a passwordProvider, or the AuthManager default.');
             }
-            // Unlock the vault (initialise on first launch).
-            if (yield this._userAgent.firstLaunch()) {
-                yield this._userAgent.initialize({ password });
-            }
-            else {
-                yield this._userAgent.start({ password });
-            }
-            this._emitter.emit('vault-unlocked', {});
+            // Unlock the vault (initialise on first launch, always start).
+            yield ensureVaultReady({
+                userAgent: this._userAgent,
+                emitter: this._emitter,
+                password,
+                isFirstLaunch,
+            });
             // Find the active identity.
             const identities = yield this._userAgent.identity.list();
             if (identities.length === 0) {
@@ -361,8 +323,7 @@ export class AuthManager {
             const identity = (_b = (savedDid
                 ? identities.find(id => id.did.uri === savedDid || id.metadata.connectedDid === savedDid)
                 : undefined)) !== null && _b !== void 0 ? _b : identities[0];
-            const connectedDid = (_c = identity.metadata.connectedDid) !== null && _c !== void 0 ? _c : identity.did.uri;
-            const delegateDid = identity.metadata.connectedDid ? identity.did.uri : undefined;
+            const { connectedDid, delegateDid } = resolveIdentityDids(identity);
             const identityInfo = {
                 didUri: connectedDid,
                 name: identity.metadata.name,
@@ -399,17 +360,16 @@ export class AuthManager {
      */
     lock() {
         return __awaiter(this, arguments, void 0, function* (options = {}) {
-            var _a, _b;
+            var _a;
             const { timeout = 2000 } = options;
             const did = (_a = this._session) === null || _a === void 0 ? void 0 : _a.did;
             // 1. Stop sync.
-            if ('sync' in this._userAgent && typeof ((_b = this._userAgent.sync) === null || _b === void 0 ? void 0 : _b.stopSync) === 'function') {
-                yield this._userAgent.sync.stopSync(timeout);
-            }
+            yield 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').
-            yield this._vault.lock();
+            // 3. Lock the vault.
+            yield this._userAgent.vault.lock();
+            this._emitter.emit('vault-locked', {});
             // 4. Transition state.
             this._setState('locked');
             // 5. Emit session-end if there was an active session.
@@ -428,14 +388,12 @@ export class AuthManager {
      */
     disconnect() {
         return __awaiter(this, arguments, void 0, function* (options = {}) {
-            var _a, _b;
+            var _a;
             const { clearStorage = false, timeout = 2000 } = options;
             const did = (_a = this._session) === null || _a === void 0 ? void 0 : _a.did;
             // Stop sync.
             if (this._session) {
-                if ('sync' in this._userAgent && typeof ((_b = this._userAgent.sync) === null || _b === void 0 ? void 0 : _b.stopSync) === 'function') {
-                    yield this._userAgent.sync.stopSync(timeout);
-                }
+                yield this._userAgent.sync.stopSync(timeout);
             }
             this._session = undefined;
             if (clearStorage) {
@@ -454,7 +412,7 @@ export class AuthManager {
                             }
                         }
                     }
-                    catch (_c) {
+                    catch (_b) {
                         // indexedDB.databases() not available in all browsers.
                     }
                 }
@@ -497,47 +455,42 @@ export class AuthManager {
      */
     shutdown() {
         return __awaiter(this, arguments, void 0, function* (options = {}) {
-            var _a, _b, _c;
+            var _a;
             if (this._isShutDown) {
                 return;
             }
             const { timeout = 2000 } = options;
             const did = (_a = this._session) === null || _a === void 0 ? void 0 : _a.did;
             // 1. Stop sync.
-            if ('sync' in this._userAgent &&
-                typeof ((_b = this._userAgent.sync) === null || _b === void 0 ? void 0 : _b.stopSync) === 'function') {
-                try {
-                    yield this._userAgent.sync.stopSync(timeout);
-                }
-                catch (_d) {
-                    // Best-effort — don't block shutdown on sync errors.
-                }
+            try {
+                yield this._userAgent.sync.stopSync(timeout);
+            }
+            catch (_b) {
+                // 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 {
-                yield this._vault.lock();
+                yield this._userAgent.vault.lock();
+                this._emitter.emit('vault-locked', {});
             }
-            catch (_e) {
+            catch (_c) {
                 // 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 ((_c = this._userAgent.sync) === null || _c === void 0 ? void 0 : _c.close) === 'function') {
-                try {
-                    yield this._userAgent.sync.close();
-                }
-                catch (_f) {
-                    // Best-effort.
-                }
+            try {
+                yield this._userAgent.sync.close();
+            }
+            catch (_d) {
+                // Best-effort.
             }
             // 5. Close the storage adapter (e.g. LevelDB session store).
             if (typeof this._storage.close === 'function') {
                 try {
                     yield this._storage.close();
                 }
-                catch (_g) {
+                catch (_e) {
                     // Best-effort.
                 }
             }
@@ -575,7 +528,6 @@ export class AuthManager {
      */
     switchIdentity(didUri) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
             // Disconnect current session cleanly (keep data).
             if (this._session) {
                 yield this.disconnect();
@@ -584,8 +536,7 @@ export class AuthManager {
             if (!identity) {
                 throw new Error(`[@enbox/auth] Identity not found: ${didUri}`);
             }
-            const connectedDid = (_a = identity.metadata.connectedDid) !== null && _a !== void 0 ? _a : identity.did.uri;
-            const delegateDid = identity.metadata.connectedDid ? identity.did.uri : undefined;
+            const { connectedDid, delegateDid } = resolveIdentityDids(identity);
             // Persist the switch.
             yield this._storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
             yield this._storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
@@ -604,13 +555,10 @@ export class AuthManager {
                         options: { delegateDid, protocols: [] },
                     });
                 }
-                catch (_b) {
+                catch (_a) {
                     // Already registered — safe to ignore.
                 }
-                const syncMode = sync === undefined ? 'live' : 'poll';
-                const syncInterval = sync !== null && sync !== void 0 ? sync : (syncMode === 'live' ? '5m' : '2m');
-                this._userAgent.sync.startSync({ mode: syncMode, interval: syncInterval })
-                    .catch((err) => console.error('[@enbox/auth] Sync failed:', err));
+                startSyncIfEnabled(this._userAgent, sync);
             }
             this._session = new AuthSession({
                 agent: this._userAgent,
@@ -671,9 +619,9 @@ export class AuthManager {
         });
     }
     // ─── Vault ─────────────────────────────────────────────────────
-    /** Access the vault manager for lock/unlock/backup operations. */
+    /** Access the underlying identity vault for lock/unlock/backup operations. */
     get vault() {
-        return this._vault;
+        return this._userAgent.vault;
     }
     // ─── Events ────────────────────────────────────────────────────
     /**
@@ -697,7 +645,7 @@ export class AuthManager {
     }
     /** Whether the vault is currently locked. */
     get isLocked() {
-        return this._vault.isLocked;
+        return this._userAgent.vault.isLocked();
     }
     /** Whether a connection attempt is in progress. */
     get isConnecting() {
@@ -718,6 +666,127 @@ export class AuthManager {
         return this._localDwnEndpoint;
     }
     // ─── 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.
+     */
+    _isLocalConnect(options) {
+        const o = (options !== null && options !== void 0 ? options : {});
+        // 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.
+     */
+    _handlerConnect(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const ctx = this._flowContext();
+            const { userAgent, emitter, storage } = ctx;
+            const sync = (_a = options === null || options === void 0 ? void 0 : options.sync) !== null && _a !== void 0 ? _a : 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 = yield userAgent.firstLaunch();
+            const password = yield resolvePassword(ctx, undefined, isFirstLaunch);
+            yield ensureVaultReady({ userAgent, emitter, password, isFirstLaunch });
+            // 2. Normalize protocol requests.
+            const permissionRequests = normalizeProtocolRequests(options === null || options === void 0 ? void 0 : options.protocols);
+            // 3. Resolve the handler.
+            const handler = (_b = options === null || options === void 0 ? void 0 : options.connectHandler) !== null && _b !== void 0 ? _b : 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 = yield 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 = yield 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()`.
+     */
+    _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()`.
+     */
+    _withConnect(fn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this._guardConcurrency();
+            this._isConnecting = true;
+            try {
+                const session = yield fn();
+                this._session = session;
+                this._setState('connected');
+                return session;
+            }
+            finally {
+                this._isConnecting = false;
+            }
+        });
+    }
     _setState(state) {
         if (state === this._state) {
             return;