@enbox/auth 0.5.0 → 0.6.1

package/dist/esm/wallet-connect-client.js

@@ -0,0 +1,188 @@
+/**
+ * WalletConnect client — initiates the relay-mediated connect flow.
+ *
+ * Moved from `@enbox/agent/src/connect.ts` because `initClient` has zero
+ * coupling to agent internals (no vault, no key store, no DWN processing,
+ * no sync). Its only consumer is `auth/src/connect/wallet.ts`.
+ *
+ * The server-side counterpart (`EnboxConnectProtocol`) correctly stays in
+ * `@enbox/agent` because it uses `agent.processDwnRequest()`,
+ * `agent.sendDwnRequest()`, and `AgentPermissionsApi`.
+ *
+ * @module
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { CryptoUtils } from '@enbox/crypto';
+import { DidJwk } from '@enbox/dids';
+import { Convert, logger } from '@enbox/common';
+import { DwnInterfaceName, DwnMethodName } from '@enbox/dwn-sdk-js';
+import { EnboxConnectProtocol, pollWithTtl } from '@enbox/agent';
+/**
+ * Initiates the wallet connect process. Used when a client wants to obtain
+ * a did from a provider.
+ */
+function initClient(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ displayName, connectServerUrl, walletUri, permissionRequests, onWalletUriReady, validatePin, }) {
+        // ephemeral client did for ECDH, signing, verification
+        const clientDid = yield DidJwk.create();
+        // TODO: properly implement PKCE. this implementation is lacking server side validations and more.
+        // https://github.com/enboxorg/enbox/issues/829
+        // Derive the code challenge based on the code verifier
+        // const { codeChallengeBytes, codeChallengeBase64Url } =
+        //   await Oidc.generateCodeChallenge();
+        const encryptionKey = CryptoUtils.randomBytes(32);
+        // Build callback URL for the connect request.
+        const callbackEndpoint = EnboxConnectProtocol.buildConnectUrl({
+            baseURL: connectServerUrl,
+            endpoint: 'callback',
+        });
+        // Build the connect request.
+        const request = yield EnboxConnectProtocol.createConnectRequest({
+            clientDid: clientDid.uri,
+            callbackUrl: callbackEndpoint,
+            permissionRequests: permissionRequests,
+            appName: displayName,
+        });
+        // Sign the request as a JWT.
+        const requestJwt = yield EnboxConnectProtocol.signJwt({
+            did: clientDid,
+            data: request,
+        });
+        if (!requestJwt) {
+            throw new Error('Unable to sign requestObject');
+        }
+        // Encrypt the request JWT with the symmetric key.
+        const requestObjectJwe = yield EnboxConnectProtocol.encryptRequest({
+            jwt: requestJwt,
+            encryptionKey,
+        });
+        const pushedAuthorizationRequestEndpoint = EnboxConnectProtocol.buildConnectUrl({
+            baseURL: connectServerUrl,
+            endpoint: 'pushedAuthorizationRequest',
+        });
+        const parResponse = yield fetch(pushedAuthorizationRequestEndpoint, {
+            body: JSON.stringify({ request: requestObjectJwe }),
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            signal: AbortSignal.timeout(30000),
+        });
+        if (!parResponse.ok) {
+            throw new Error(`${parResponse.status}: ${parResponse.statusText}`);
+        }
+        const parData = yield parResponse.json();
+        // a deeplink to a compatible wallet. if the wallet scans this link it should receive
+        // a route to its Connect provider flow and the params of where to fetch the auth request.
+        logger.log(`Wallet URI: ${walletUri}`);
+        const generatedWalletUri = new URL(walletUri);
+        generatedWalletUri.searchParams.set('request_uri', parData.request_uri);
+        generatedWalletUri.searchParams.set('encryption_key', Convert.uint8Array(encryptionKey).toBase64Url());
+        // call user's callback so they can send the URI to the wallet as they see fit
+        onWalletUriReady(generatedWalletUri.toString());
+        const tokenUrl = EnboxConnectProtocol.buildConnectUrl({
+            baseURL: connectServerUrl,
+            endpoint: 'token',
+            tokenParam: request.state,
+        });
+        // subscribe to receiving a response from the wallet with default TTL. receive ciphertext of {@link EnboxConnectResponse}
+        const authResponse = yield pollWithTtl(() => fetch(tokenUrl, { signal: AbortSignal.timeout(30000) }));
+        if (authResponse) {
+            const jwe = yield (authResponse === null || authResponse === void 0 ? void 0 : authResponse.text());
+            // Get the PIN from the user and use it as AAD to decrypt.
+            const pin = yield validatePin();
+            const jwt = yield EnboxConnectProtocol.decryptResponse(clientDid, jwe, pin);
+            const verifiedResponse = (yield EnboxConnectProtocol.verifyJwt({
+                jwt,
+            }));
+            return {
+                delegateGrants: verifiedResponse.delegateGrants,
+                delegatePortableDid: verifiedResponse.delegatePortableDid,
+                connectedDid: verifiedResponse.providerDid,
+            };
+        }
+    });
+}
+/**
+ * Creates a set of Dwn Permission Scopes to request for a given protocol.
+ *
+ * If no permissions are provided, the default is to request all relevant record permissions (write, read, delete, query, subscribe).
+ * 'configure' is not included by default, as this gives the application a lot of control over the protocol.
+ */
+function createPermissionRequestForProtocol({ definition, permissions }) {
+    const requests = [];
+    // Add the ability to query for the specific protocol
+    requests.push({
+        protocol: definition.protocol,
+        interface: DwnInterfaceName.Protocols,
+        method: DwnMethodName.Query,
+    });
+    // A Messages.Read grant is a unified scope that covers MessagesRead, MessagesSync, and MessagesSubscribe.
+    // This single grant enables sync and real-time subscriptions for the protocol.
+    requests.push({
+        protocol: definition.protocol,
+        interface: DwnInterfaceName.Messages,
+        method: DwnMethodName.Read,
+    });
+    // We also request any additional permissions the user has requested for this protocol
+    for (const permission of permissions) {
+        switch (permission) {
+            case 'write':
+                requests.push({
+                    protocol: definition.protocol,
+                    interface: DwnInterfaceName.Records,
+                    method: DwnMethodName.Write,
+                });
+                break;
+            case 'read':
+                requests.push({
+                    protocol: definition.protocol,
+                    interface: DwnInterfaceName.Records,
+                    method: DwnMethodName.Read,
+                });
+                break;
+            case 'delete':
+                requests.push({
+                    protocol: definition.protocol,
+                    interface: DwnInterfaceName.Records,
+                    method: DwnMethodName.Delete,
+                });
+                break;
+            case 'query':
+                requests.push({
+                    protocol: definition.protocol,
+                    interface: DwnInterfaceName.Records,
+                    method: DwnMethodName.Query,
+                });
+                break;
+            case 'subscribe':
+                requests.push({
+                    protocol: definition.protocol,
+                    interface: DwnInterfaceName.Records,
+                    method: DwnMethodName.Subscribe,
+                });
+                break;
+            case 'configure':
+                requests.push({
+                    protocol: definition.protocol,
+                    interface: DwnInterfaceName.Protocols,
+                    method: DwnMethodName.Configure,
+                });
+                break;
+        }
+    }
+    return {
+        protocolDefinition: definition,
+        permissionScopes: requests,
+    };
+}
+export const WalletConnect = { initClient, createPermissionRequestForProtocol };
+//# sourceMappingURL=wallet-connect-client.js.map

package/dist/esm/wallet-connect-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-connect-client.js","sourceRoot":"","sources":["../../src/wallet-connect-client.ts"],"names":[],"mappings":"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"}

package/dist/types/auth-manager.d.ts

@@ -5,11 +5,10 @@
  * multi-identity-aware auth system that works in both browser and CLI environments.
  * @module
  */
+import type { HdIdentityVault, PortableIdentity } from '@enbox/agent';
+import type { AuthEvent, AuthEventHandler, AuthManagerOptions, AuthState, ConnectOptions, DisconnectOptions, HeadlessConnectOptions, IdentityInfo, ImportFromPhraseOptions, ImportFromPortableOptions, LocalConnectOptions, RestoreSessionOptions, ShutdownOptions, WalletConnectOptions } from './types.js';
 import { EnboxUserAgent } from '@enbox/agent';
-import type { PortableIdentity } from '@enbox/agent';
 import { AuthSession } from './identity-session.js';
-import { VaultManager } from './vault/vault-manager.js';
-import type { AuthEvent, AuthEventHandler, AuthManagerOptions, AuthState, DisconnectOptions, HeadlessConnectOptions, IdentityInfo, ImportFromPhraseOptions, ImportFromPortableOptions, LocalConnectOptions, RestoreSessionOptions, ShutdownOptions, WalletConnectOptions } from './types.js';
 /**
  * The primary entry point for authentication and identity management.
  *
@@ -47,7 +46,6 @@ export declare class AuthManager {
     private _userAgent;
     private _emitter;
     private _storage;
-    private _vault;
     private _session;
     private _state;
     private _isConnecting;
@@ -57,6 +55,7 @@ export declare class AuthManager {
     private _defaultSync?;
     private _defaultDwnEndpoints?;
     private _registration?;
+    private _connectHandler?;
     /**
      * The local DWN server endpoint discovered during `create()`, if any.
      * `undefined` means no local server was found. This is set before any
@@ -77,16 +76,60 @@ export declare class AuthManager {
      */
     static create(options?: AuthManagerOptions): Promise<AuthManager>;
     /**
-     * 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?: ConnectOptions): Promise<AuthSession>;
+    /**
+     * 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.
      */
-    connect(options?: LocalConnectOptions): Promise<AuthSession>;
+    connectLocal(options?: LocalConnectOptions): Promise<AuthSession>;
     /**
      * Connect to an external wallet via the Enbox Connect relay protocol.
      *
@@ -223,8 +266,8 @@ export declare class AuthManager {
      * to another device.
      */
     exportIdentity(didUri: string): Promise<PortableIdentity>;
-    /** Access the vault manager for lock/unlock/backup operations. */
-    get vault(): VaultManager;
+    /** Access the underlying identity vault for lock/unlock/backup operations. */
+    get vault(): HdIdentityVault;
     /**
      * Subscribe to an auth lifecycle event.
      *
@@ -251,6 +294,41 @@ export declare class AuthManager {
      * before any event listeners are attached.
      */
     get localDwnEndpoint(): string | undefined;
+    /**
+     * 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;
+    /**
+     * 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 _handlerConnect;
+    /**
+     * 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;
+    /**
+     * 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 _withConnect;
     private _setState;
     private _guardConcurrency;
 }

package/dist/types/auth-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-manager.d.ts","sourceRoot":"","sources":["../../src/auth-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-manager.d.ts","sourceRoot":"","sources":["../../src/auth-manager.ts"],"names":[],"mappings":"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"}

package/dist/types/connect/import.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 (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.
+ */
+export declare function importFromPhrase(ctx: FlowContext, options: ImportFromPhraseOptions): Promise<AuthSession>;
+/**
+ * Import an identity from a PortableIdentity JSON object.
+ *
+ * The portable identity contains the DID's private keys and metadata,
+ * allowing it to be used on this device.
+ */
+export declare function importFromPortable(ctx: FlowContext, options: ImportFromPortableOptions): Promise<AuthSession>;
+//# sourceMappingURL=import.d.ts.map

package/dist/types/connect/import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../../src/connect/import.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAMtF;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAiEtB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,WAAW,CAAC,CA8CtB"}

package/dist/types/connect/lifecycle.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Shared helpers for connect flows.
+ *
+ * Consolidates duplicated logic across `local-connect`, `session-restore`,
+ * `wallet-connect`, and `import-identity` flows:
+ *
+ * - Password resolution chain
+ * - Vault init/start lifecycle
+ * - Sync mode/interval calculation and startup
+ * - `connectedDid` / `delegateDid` derivation from identity metadata
+ * - Session finalization (storage persistence + AuthSession construction + events)
+ *
+ * @module
+ * @internal
+ */
+import type { PortableDid } from '@enbox/dids';
+import type { BearerIdentity, DwnDataEncodedRecordsWriteMessage, EnboxUserAgent } from '@enbox/agent';
+import type { AuthEventEmitter } from '../events.js';
+import type { PasswordProvider } from '../password-provider.js';
+import type { RegistrationOptions, StorageAdapter, SyncOption } from '../types.js';
+import { AuthSession } from '../identity-session.js';
+/**
+ * Unified context passed from `AuthManager` to every connect flow.
+ *
+ * Replaces the per-flow `LocalConnectContext`, `SessionRestoreContext`,
+ * `WalletConnectContext`, and `ImportContext` interfaces. All fields are
+ * optional beyond the core triple (`userAgent`, `emitter`, `storage`) so
+ * flows only consume what they need.
+ *
+ * @internal
+ */
+export interface FlowContext {
+    userAgent: EnboxUserAgent;
+    emitter: AuthEventEmitter;
+    storage: StorageAdapter;
+    defaultPassword?: string;
+    passwordProvider?: PasswordProvider;
+    defaultSync?: SyncOption;
+    defaultDwnEndpoints?: string[];
+    registration?: RegistrationOptions;
+}
+/**
+ * Resolve a password through the standard chain:
+ * explicit option → manager default → provider → insecure fallback.
+ *
+ * Emits a console warning when the insecure default is used.
+ *
+ * @param ctx          - The flow context (provides `defaultPassword` and `passwordProvider`).
+ * @param explicit     - An explicit password from the caller (highest priority).
+ * @param isFirstLaunch - Whether the vault has never been initialized.
+ * @returns The resolved password string.
+ *
+ * @internal
+ */
+export declare function resolvePassword(ctx: Pick<FlowContext, 'defaultPassword' | 'passwordProvider'>, explicit: string | undefined, isFirstLaunch: boolean): Promise<string>;
+/**
+ * Initialize (on first launch) and start the agent, then emit `vault-unlocked`.
+ *
+ * This consolidates the 5 copies of:
+ * ```ts
+ * if (isFirstLaunch) { await userAgent.initialize({ password, ... }); }
+ * await userAgent.start({ password });
+ * emitter.emit('vault-unlocked', {});
+ * ```
+ *
+ * @returns The recovery phrase if the vault was just initialized, otherwise `undefined`.
+ *
+ * @internal
+ */
+export declare function ensureVaultReady(params: {
+    userAgent: EnboxUserAgent;
+    emitter: AuthEventEmitter;
+    password: string;
+    isFirstLaunch: boolean;
+    recoveryPhrase?: string;
+    dwnEndpoints?: string[];
+}): Promise<string | undefined>;
+/**
+ * Start DWN synchronisation if `sync` is not `'off'`.
+ *
+ * Consolidates 6 copies of:
+ * ```ts
+ * const syncMode = sync === undefined ? 'live' : 'poll';
+ * const syncInterval = sync ?? (syncMode === 'live' ? '5m' : '2m');
+ * userAgent.sync.startSync({ mode: syncMode, interval: syncInterval })
+ *   .catch((err) => console.error('[@enbox/auth] Sync failed:', err));
+ * ```
+ *
+ * @internal
+ */
+export declare function startSyncIfEnabled(userAgent: EnboxUserAgent, sync: SyncOption | undefined): void;
+/**
+ * Create a new `did:dht` identity with Ed25519 signing and X25519
+ * encryption keys, and a DWN service endpoint.
+ *
+ * This consolidates the identical identity creation block that was
+ * duplicated in `localConnect` and `importFromPhrase`.
+ *
+ * @internal
+ */
+export declare function createDefaultIdentity(userAgent: EnboxUserAgent, dwnEndpoints?: string[], name?: string): Promise<BearerIdentity>;
+/**
+ * Derive `connectedDid` and `delegateDid` from identity metadata.
+ *
+ * For a **local** identity: `connectedDid` is the identity's own DID URI
+ * and `delegateDid` is `undefined`.
+ *
+ * For a **wallet-connected** identity: `connectedDid` is the external wallet
+ * DID, and `delegateDid` is the local identity's DID URI.
+ *
+ * @param identity            - The bearer identity to extract DIDs from.
+ * @param storedDelegateDid   - Optional fallback delegate DID from storage,
+ *   used by session-restore when the identity metadata doesn't include a
+ *   `connectedDid` but a delegate DID was persisted in a prior session.
+ *
+ * @internal
+ */
+export declare function resolveIdentityDids(identity: BearerIdentity, storedDelegateDid?: string): {
+    connectedDid: string;
+    delegateDid: string | undefined;
+};
+/**
+ * Process connected grants by storing them in the local DWN as the owner.
+ *
+ * This is the agent-level equivalent of `Enbox.processConnectedGrants()`.
+ * It stores each grant, signed as owner, and returns the deduplicated
+ * list of protocol URIs represented by the grants.
+ *
+ * @internal
+ */
+export declare function processConnectedGrants(params: {
+    agent: EnboxUserAgent;
+    delegateDid: string;
+    grants: DwnDataEncodedRecordsWriteMessage[];
+}): Promise<string[]>;
+/**
+ * Import a delegated DID, process its grants, register sync, and pull.
+ *
+ * This is the shared post-connect lifecycle used by both the DWeb Connect
+ * and relay WalletConnect flows. On failure, the imported identity is
+ * cleaned up before re-throwing.
+ *
+ * @internal
+ */
+export declare function importDelegateAndSetupSync(params: {
+    userAgent: EnboxUserAgent;
+    delegatePortableDid: PortableDid;
+    connectedDid: string;
+    delegateGrants: DwnDataEncodedRecordsWriteMessage[];
+    flowName: string;
+}): Promise<BearerIdentity>;
+/**
+ * Build an `AuthSession` for a delegated connect flow (DWeb Connect or
+ * relay WalletConnect). Starts sync and persists delegate/connected DID
+ * markers.
+ *
+ * @internal
+ */
+export declare function finalizeDelegateSession(params: {
+    userAgent: EnboxUserAgent;
+    emitter: AuthEventEmitter;
+    storage: StorageAdapter;
+    identity: BearerIdentity;
+    connectedDid: string;
+    delegateDid: string;
+    sync: SyncOption | undefined;
+}): Promise<AuthSession>;
+/**
+ * Persist session markers, build an `AuthSession`, and emit lifecycle events.
+ *
+ * Consolidates 5 copies of:
+ * ```ts
+ * await storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
+ * await storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
+ * const session = new AuthSession({ ... });
+ * emitter.emit('identity-added', { identity: identityInfo });
+ * emitter.emit('session-start', { session: { ... } });
+ * ```
+ *
+ * @param params.emitIdentityAdded - Whether to emit `identity-added`. Defaults to `true`.
+ *   Set to `false` for session-restore (identity was already added in the original flow).
+ * @param params.extraStorageKeys  - Additional key-value pairs to persist (e.g. delegate/connected DIDs
+ *   for wallet-connect flows).
+ *
+ * @internal
+ */
+export declare function finalizeSession(params: {
+    userAgent: EnboxUserAgent;
+    emitter: AuthEventEmitter;
+    storage: StorageAdapter;
+    connectedDid: string;
+    delegateDid?: string;
+    recoveryPhrase?: string;
+    identityName?: string;
+    identityConnectedDid?: string;
+    emitIdentityAdded?: boolean;
+    extraStorageKeys?: Record<string, string>;
+}): Promise<AuthSession>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/types/connect/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/connect/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/types/connect/local.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Local DID connect flow.
+ *
+ * Creates or reconnects a local identity with vault-protected keys.
+ * This replaces the "Mode D/E" paths in Enbox.connect().
+ * @module
+ */
+import type { AuthSession } from '../identity-session.js';
+import type { FlowContext } from './lifecycle.js';
+import type { LocalConnectOptions } from '../types.js';
+/**
+ * Execute the local connect flow.
+ *
+ * - On first launch: initializes the vault. Identity creation is opt-in via
+ *   `options.createIdentity: true`.
+ * - On subsequent launches: unlocks the vault and reconnects to the existing 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
+ * manage identity creation separately from vault setup.
+ */
+export declare function localConnect(ctx: FlowContext, options?: LocalConnectOptions): Promise<AuthSession>;
+//# sourceMappingURL=local.d.ts.map

package/dist/types/connect/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/connect/local.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAOvD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,WAAW,CAAC,CAoFtB"}

package/dist/types/connect/restore.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Session restore flow.
+ *
+ * Restores a previously established session from persisted storage,
+ * replacing the "previouslyConnected" pattern in apps.
+ * @module
+ */
+import type { AuthSession } from '../identity-session.js';
+import type { FlowContext } from './lifecycle.js';
+import type { RestoreSessionOptions } from '../types.js';
+/**
+ * Attempt to restore a previous session.
+ *
+ * Returns `undefined` if no previous session exists.
+ * Returns an `AuthSession` if the session was successfully restored.
+ */
+export declare function restoreSession(ctx: FlowContext, options?: RestoreSessionOptions): Promise<AuthSession | undefined>;
+//# sourceMappingURL=restore.d.ts.map

package/dist/types/connect/restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.d.ts","sourceRoot":"","sources":["../../../src/connect/restore.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAMzD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CA2GlC"}