@enbox/auth 0.6.33 → 0.6.35

package/src/connect/recovery.ts

@@ -0,0 +1,111 @@
+/**
+ * Seed phrase recovery helpers.
+ *
+ * When a vault is re-derived from a recovery phrase on a new device,
+ * the local DWN is empty. This module provides the building blocks
+ * for pulling identity metadata, keys, and user data from the remote
+ * DWN in a controlled two-phase sequence.
+ *
+ * @module
+ * @internal
+ */
+
+import type { BearerIdentity, EnboxUserAgent } from '@enbox/agent';
+
+import { IdentityProtocolDefinition, JwkProtocolDefinition } from '@enbox/agent';
+
+import type { RegistrationOptions, StorageAdapter } from '../types.js';
+
+import { registerWithDwnEndpoints } from '../registration.js';
+
+/**
+ * Internal protocols that store recovery-critical data in the agent DID's DWN.
+ * Syncing these ensures that seed phrase recovery can pull identity metadata,
+ * portable DIDs, and encrypted private keys from the remote.
+ */
+export const AGENT_DID_SYNC_PROTOCOLS: [string, ...string[]] = [
+  IdentityProtocolDefinition.protocol,
+  JwkProtocolDefinition.protocol,
+];
+
+/**
+ * Register the agent DID for sync with the recovery-critical protocols.
+ *
+ * This is a prerequisite for both normal operation (pushing identity
+ * metadata to the remote) and seed phrase recovery (pulling it back).
+ * Silently succeeds if the agent DID is already registered.
+ */
+export async function registerAgentDidForSync(userAgent: EnboxUserAgent): Promise<void> {
+  try {
+    await userAgent.sync.registerIdentity({
+      did     : userAgent.agentDid.uri,
+      options : { protocols: AGENT_DID_SYNC_PROTOCOLS },
+    });
+  } catch {
+    // Already registered from a previous session.
+  }
+}
+
+/**
+ * Recover identities and their data from remote DWN endpoints.
+ *
+ * Assumes the agent DID is already registered for sync (via
+ * {@link registerAgentDidForSync}) and as a DWN tenant.
+ *
+ * Phase 1 — pull identity metadata and DID private keys stored in the
+ *   agent DID's DWN.
+ *
+ * Phase 2 — register each recovered identity DID as a tenant and for
+ *   sync, then pull their profile data, protocol configurations, and
+ *   records.
+ *
+ * Returns the recovered identities, or an empty array if the remote
+ * had nothing (e.g. first-ever setup with a pre-generated phrase).
+ */
+export async function recoverIdentitiesFromRemote(params: {
+  userAgent: EnboxUserAgent;
+  dwnEndpoints: string[];
+  registration?: RegistrationOptions;
+  storage: StorageAdapter;
+}): Promise<BearerIdentity[]> {
+  const { userAgent, dwnEndpoints, registration, storage } = params;
+  const agentDid = userAgent.agentDid.uri;
+
+  // Phase 1: pull identity metadata + encrypted DID keys.
+  await userAgent.sync.sync('pull');
+
+  const identities = await userAgent.identity.list();
+  if (identities.length === 0) {
+    return [];
+  }
+
+  // Register each recovered identity DID as a DWN tenant, then for sync.
+  // Tenant registration must come first — sync('pull') issues
+  // MessagesSync which requires the DID to be a recognised tenant.
+  for (const identity of identities) {
+    const did = identity.metadata.connectedDid ?? identity.did.uri;
+
+    if (registration) {
+      try {
+        await registerWithDwnEndpoints(
+          { userAgent, dwnEndpoints, agentDid, connectedDid: did, secretStore: userAgent.secrets, storage },
+          registration,
+        );
+      } catch {
+        // Best effort — the DID may already be registered, or the
+        // endpoint may be temporarily unreachable.
+      }
+    }
+
+    try {
+      await userAgent.sync.registerIdentity({ did, options: { protocols: 'all' } });
+    } catch {
+      // Already registered from a previous session.
+    }
+  }
+
+  // Phase 2: pull profile data, protocol configurations, and records.
+  await userAgent.sync.sync('pull');
+
+  return userAgent.identity.list();
+}

package/src/connect/{local.ts → vault.ts}

@@ -1,34 +1,41 @@
 /**
- * Local DID connect flow.
+ * Vault connect flow.
  *
  * Creates or reconnects a local identity with vault-protected keys.
- * This replaces the "Mode D/E" paths in Enbox.connect().
+ * Used by wallets and CLI tools that own the HD identity vault directly
+ * (as opposed to handler-based connect, which delegates credential
+ * acquisition to an external wallet).
+ *
  * @module
  */
 
 import type { AuthSession } from '../identity-session.js';
 import type { FlowContext } from './lifecycle.js';
-import type { LocalConnectOptions } from '../types.js';
+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 { recoverIdentitiesFromRemote, registerAgentDidForSync } from './recovery.js';
 
 /**
- * Execute the local connect flow.
+ * Execute the vault 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.
+ * - 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.
  *
  * 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 async function localConnect(
+export async function vaultConnect(
   ctx: FlowContext,
-  options: LocalConnectOptions = {},
+  options: VaultConnectOptions = {},
 ): Promise<AuthSession> {
   const { userAgent, emitter, storage } = ctx;
 
@@ -56,11 +63,43 @@ export async function localConnect(
     await applyLocalDwnDiscovery(userAgent, storage, emitter);
   }
 
-  // Find or create the user identity.
-  const identities = await userAgent.identity.list();
+  // Register the agent DID as a DWN tenant and for sync early — both are
+  // prerequisites for seed phrase recovery and for normal push/pull of
+  // identity metadata after identity creation.
+  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);
+  }
+
+  // Find existing identities.
+  let identities = await userAgent.identity.list();
   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') {
+    try {
+      identities = await recoverIdentitiesFromRemote({ userAgent, dwnEndpoints, registration: ctx.registration, storage });
+      identity = identities[0];
+    } catch (err) {
+      console.warn('[@enbox/auth] Seed phrase recovery failed:', err);
+    }
+  }
+
+  // Create a default identity if none were found or recovered.
   if (!identity && shouldCreateIdentity) {
     isNewIdentity = true;
     identity = await createDefaultIdentity(userAgent, dwnEndpoints, options.metadata?.name ?? 'Default');
@@ -77,22 +116,23 @@ export async function localConnect(
     ? resolveIdentityDids(identity).delegateDid
     : undefined;
 
-  // Register with DWN endpoints (if registration options are provided).
-  if (ctx.registration) {
+  // Register the new identity DID as a tenant and for sync.
+  // Tenant registration must come before sync registration — with live
+  // sync active, registerIdentity hot-adds a subscription that needs
+  // the DID to be a recognised tenant on the remote DWN.
+  if (isNewIdentity && ctx.registration) {
     await registerWithDwnEndpoints(
       {
-        userAgent   : userAgent,
+        userAgent,
         dwnEndpoints,
         agentDid    : userAgent.agentDid.uri,
         connectedDid,
         secretStore : userAgent.secrets,
-        storage     : storage,
+        storage,
       },
       ctx.registration,
     );
   }
-
-  // Register sync for new identities.
   if (isNewIdentity && sync !== 'off') {
     await userAgent.sync.registerIdentity({
       did     : connectedDid,

package/src/index.ts

@@ -10,7 +10,7 @@
  * import { AuthManager } from '@enbox/auth';
  *
  * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.connectLocal({ password: userPin });
+ * const session = await auth.connectVault({ password: userPin });
  * ```
  *
  * @example Dapp with browser connect handler
@@ -90,6 +90,7 @@ export type {
   ImportFromPortableOptions,
   LocalConnectOptions,
   LocalDwnStrategy,
+  VaultConnectOptions,
   Permission,
   PortableIdentity,
   ProtocolRequest,

package/src/types.ts

@@ -381,7 +381,7 @@ export interface AuthManagerOptions {
    * Default connect handler for delegated connect flows.
    *
    * Used by `connect()` when the caller provides `protocols` (or other
-   * non-local-connect options) but does not pass a per-call handler.
+   * non-vault-connect options) but does not pass a per-call handler.
    *
    * @example
    * ```ts
@@ -398,8 +398,8 @@ export interface AuthManagerOptions {
   connectHandler?: ConnectHandler;
 }
 
-/** Options for {@link AuthManager.connect}. */
-export interface LocalConnectOptions {
+/** Options for {@link AuthManager.connectVault}. */
+export interface VaultConnectOptions {
   /** Vault password (overrides manager default). */
   password?: string;
 
@@ -434,6 +434,9 @@ export interface LocalConnectOptions {
   createIdentity?: boolean;
 }
 
+/** @deprecated Use {@link VaultConnectOptions} instead. */
+export type LocalConnectOptions = VaultConnectOptions;
+
 // ─── DWeb Connect ────────────────────────────────────────────────
 
 /**
@@ -509,14 +512,14 @@ export interface HandlerConnectOptions {
  *   `connectHandler` is provided. Delegates to the connect handler
  *   for credential acquisition.
  *
- * - **Local connect** (wallets / CLI): triggered when `password`,
+ * - **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.
  */
-export type ConnectOptions = HandlerConnectOptions | LocalConnectOptions;
+export type ConnectOptions = HandlerConnectOptions | VaultConnectOptions;
 
 /** Options for {@link AuthManager.walletConnect}. */
 export interface WalletConnectOptions {

package/dist/esm/connect/local.js.map

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

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

@@ -1 +0,0 @@
-{"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,CAqFtB"}