@enbox/auth 0.6.34 → 0.6.35

package/dist/esm/connect/import.js

@@ -14,19 +14,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { IdentityProtocolDefinition, JwkProtocolDefinition } from '@enbox/agent';
 import { DEFAULT_DWN_ENDPOINTS } from '../types.js';
 import { registerWithDwnEndpoints } from '../registration.js';
 import { createDefaultIdentity, ensureVaultReady, finalizeSession, registerSyncScopeForIdentity, resolveIdentityDids, startSyncIfEnabled } from './lifecycle.js';
-const AGENT_DID_SYNC_PROTOCOLS = [
-    IdentityProtocolDefinition.protocol,
-    JwkProtocolDefinition.protocol,
-];
+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.
+ * 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 function importFromPhrase(ctx, options) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -45,51 +43,64 @@ export function importFromPhrase(ctx, options) {
             recoveryPhrase,
             dwnEndpoints,
         });
-        // The recovery phrase re-derives the same agent DID,
-        // but the user identity might not exist yet — create one if needed.
-        const identities = yield userAgent.identity.list();
-        let identity = identities[0];
-        let isNewIdentity = false;
-        if (!identity) {
-            isNewIdentity = true;
-            identity = yield createDefaultIdentity(userAgent, dwnEndpoints);
-        }
-        const { connectedDid, delegateDid } = resolveIdentityDids(identity);
-        // Register with DWN endpoints (if registration options are provided).
+        // Register agent DID as tenant and for sync — prerequisites for recovery.
         if (ctx.registration) {
             yield registerWithDwnEndpoints({
-                userAgent: userAgent,
+                userAgent,
                 dwnEndpoints,
                 agentDid: userAgent.agentDid.uri,
-                connectedDid,
+                connectedDid: userAgent.agentDid.uri,
                 secretStore: userAgent.secrets,
-                storage: storage,
+                storage,
             }, ctx.registration);
         }
-        // Register sync. For delegate identities, always repair the registration
-        // (derive scope from active grants — revoked grants must not remain in a
-        // stale registration), regardless of whether the identity was just
-        // created or restored from storage. For local identities, register
-        // `protocols: 'all'` only on first creation; a pre-existing local
-        // identity was already registered during its initial flow.
-        if (delegateDid) {
-            yield registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
-        }
-        else if (isNewIdentity && sync !== 'off') {
-            yield registerSyncScopeForIdentity({ userAgent, connectedDid });
-        }
-        // Register the agent DID for sync (same rationale as vaultConnect).
         if (sync !== 'off') {
+            yield registerAgentDidForSync(userAgent);
+        }
+        // Try to recover identities from the remote DWN before falling back
+        // to creating a new one.
+        let identities = yield userAgent.identity.list();
+        let identity = identities[0];
+        let isNewIdentity = false;
+        if (!identity && sync !== 'off') {
             try {
-                yield userAgent.sync.registerIdentity({
-                    did: userAgent.agentDid.uri,
-                    options: { protocols: AGENT_DID_SYNC_PROTOCOLS },
-                });
+                identities = yield recoverIdentitiesFromRemote({ userAgent, dwnEndpoints, registration: ctx.registration, storage });
+                identity = identities[0];
             }
-            catch (_d) {
-                // Already registered from a previous session.
+            catch (err) {
+                console.warn('[@enbox/auth] Seed phrase recovery failed:', err);
             }
         }
+        if (!identity) {
+            isNewIdentity = true;
+            identity = yield 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) {
+                yield registerWithDwnEndpoints({
+                    userAgent,
+                    dwnEndpoints,
+                    agentDid: userAgent.agentDid.uri,
+                    connectedDid,
+                    secretStore: userAgent.secrets,
+                    storage,
+                }, ctx.registration);
+            }
+            if (delegateDid) {
+                yield registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
+            }
+            else if (sync !== 'off') {
+                yield registerSyncScopeForIdentity({ userAgent, connectedDid });
+            }
+        }
+        else if (delegateDid) {
+            // Pre-existing delegate identity: repair sync scope so revoked
+            // grants don't remain in a stale registration.
+            yield registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
+        }
         // Start sync.
         yield startSyncIfEnabled(userAgent, sync);
         // Persist session info, build AuthSession, and emit lifecycle events.

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

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

package/dist/esm/connect/recovery.js

@@ -0,0 +1,105 @@
+/**
+ * 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
+ */
+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 { IdentityProtocolDefinition, JwkProtocolDefinition } from '@enbox/agent';
+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 = [
+    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 function registerAgentDidForSync(userAgent) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            yield userAgent.sync.registerIdentity({
+                did: userAgent.agentDid.uri,
+                options: { protocols: AGENT_DID_SYNC_PROTOCOLS },
+            });
+        }
+        catch (_a) {
+            // 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 function recoverIdentitiesFromRemote(params) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const { userAgent, dwnEndpoints, registration, storage } = params;
+        const agentDid = userAgent.agentDid.uri;
+        // Phase 1: pull identity metadata + encrypted DID keys.
+        yield userAgent.sync.sync('pull');
+        const identities = yield 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 = (_a = identity.metadata.connectedDid) !== null && _a !== void 0 ? _a : identity.did.uri;
+            if (registration) {
+                try {
+                    yield registerWithDwnEndpoints({ userAgent, dwnEndpoints, agentDid, connectedDid: did, secretStore: userAgent.secrets, storage }, registration);
+                }
+                catch (_b) {
+                    // Best effort — the DID may already be registered, or the
+                    // endpoint may be temporarily unreachable.
+                }
+            }
+            try {
+                yield userAgent.sync.registerIdentity({ did, options: { protocols: 'all' } });
+            }
+            catch (_c) {
+                // Already registered from a previous session.
+            }
+        }
+        // Phase 2: pull profile data, protocol configurations, and records.
+        yield userAgent.sync.sync('pull');
+        return userAgent.identity.list();
+    });
+}
+//# sourceMappingURL=recovery.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../../../src/connect/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;;;;;;;;;;AAIH,OAAO,EAAE,0BAA0B,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAIjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAA0B;IAC7D,0BAA0B,CAAC,QAAQ;IACnC,qBAAqB,CAAC,QAAQ;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAgB,uBAAuB,CAAC,SAAyB;;QACrE,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC;gBACpC,GAAG,EAAO,SAAS,CAAC,QAAQ,CAAC,GAAG;gBAChC,OAAO,EAAG,EAAE,SAAS,EAAE,wBAAwB,EAAE;aAClD,CAAC,CAAC;QACL,CAAC;QAAC,WAAM,CAAC;YACP,8CAA8C;QAChD,CAAC;IACH,CAAC;CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAgB,2BAA2B,CAAC,MAKjD;;;QACC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAClE,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC;QAExC,wDAAwD;QACxD,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAElC,MAAM,UAAU,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,uEAAuE;QACvE,4DAA4D;QAC5D,iEAAiE;QACjE,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;YAClC,MAAM,GAAG,GAAG,MAAA,QAAQ,CAAC,QAAQ,CAAC,YAAY,mCAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;YAE/D,IAAI,YAAY,EAAE,CAAC;gBACjB,IAAI,CAAC;oBACH,MAAM,wBAAwB,CAC5B,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,EACjG,YAAY,CACb,CAAC;gBACJ,CAAC;gBAAC,WAAM,CAAC;oBACP,0DAA0D;oBAC1D,2CAA2C;gBAC7C,CAAC;YACH,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,SAAS,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YAChF,CAAC;YAAC,WAAM,CAAC;gBACP,8CAA8C;YAChD,CAAC;QACH,CAAC;QAED,oEAAoE;QACpE,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAElC,OAAO,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,CAAC;CAAA"}

package/dist/esm/connect/vault.js

@@ -17,26 +17,20 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { IdentityProtocolDefinition, JwkProtocolDefinition } from '@enbox/agent';
 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';
-/**
- * Internal protocols that store recovery-critical data in the agent DID's DWN.
- * These must be synced so that seed phrase recovery can pull identity metadata,
- * portable DIDs, and encrypted private keys from the remote DWN.
- */
-const AGENT_DID_SYNC_PROTOCOLS = [
-    IdentityProtocolDefinition.protocol,
-    JwkProtocolDefinition.protocol,
-];
+import { recoverIdentitiesFromRemote, registerAgentDidForSync } from './recovery.js';
 /**
  * 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
@@ -66,10 +60,38 @@ export function vaultConnect(ctx_1) {
         if (!userAgent.dwn.isRemoteMode) {
             yield applyLocalDwnDiscovery(userAgent, storage, emitter);
         }
-        // Find or create the user identity.
-        const identities = yield 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) {
+            yield registerWithDwnEndpoints({
+                userAgent,
+                dwnEndpoints,
+                agentDid: userAgent.agentDid.uri,
+                connectedDid: userAgent.agentDid.uri,
+                secretStore: userAgent.secrets,
+                storage,
+            }, ctx.registration);
+        }
+        if (sync !== 'off') {
+            yield registerAgentDidForSync(userAgent);
+        }
+        // Find existing identities.
+        let identities = yield 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 = yield 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 = yield createDefaultIdentity(userAgent, dwnEndpoints, (_e = (_d = options.metadata) === null || _d === void 0 ? void 0 : _d.name) !== null && _e !== void 0 ? _e : 'Default');
@@ -83,38 +105,26 @@ export function vaultConnect(ctx_1) {
         const delegateDid = identity
             ? 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) {
             yield 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') {
             yield userAgent.sync.registerIdentity({
                 did: connectedDid,
                 options: { delegateDid, protocols: 'all' },
             });
         }
-        // Register the agent DID for sync so that identity metadata, portable
-        // DIDs, and encrypted private keys are pushed to the remote DWN. Without
-        // this, seed phrase recovery on a new device has nothing to pull.
-        if (sync !== 'off') {
-            try {
-                yield userAgent.sync.registerIdentity({
-                    did: userAgent.agentDid.uri,
-                    options: { protocols: AGENT_DID_SYNC_PROTOCOLS },
-                });
-            }
-            catch (_f) {
-                // Already registered from a previous session — no action needed.
-            }
-        }
         // Start sync.
         yield startSyncIfEnabled(userAgent, sync);
         // Persist session info, build AuthSession, and emit lifecycle events.

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

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

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

@@ -12,7 +12,9 @@ import type { ImportFromPhraseOptions, ImportFromPortableOptions } from '../type
  * 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.
+ * 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 declare function importFromPhrase(ctx: FlowContext, options: ImportFromPhraseOptions): Promise<AuthSession>;
 /**

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

@@ -1 +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;AAatF;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAkFtB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,WAAW,CAAC,CA8CtB"}
+{"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;AAOtF;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CAiGtB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,WAAW,CAAC,CA8CtB"}

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

@@ -0,0 +1,50 @@
+/**
+ * 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 type { RegistrationOptions, StorageAdapter } from '../types.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 declare const AGENT_DID_SYNC_PROTOCOLS: [string, ...string[]];
+/**
+ * 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 declare function registerAgentDidForSync(userAgent: EnboxUserAgent): Promise<void>;
+/**
+ * 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 declare function recoverIdentitiesFromRemote(params: {
+    userAgent: EnboxUserAgent;
+    dwnEndpoints: string[];
+    registration?: RegistrationOptions;
+    storage: StorageAdapter;
+}): Promise<BearerIdentity[]>;
+//# sourceMappingURL=recovery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../../src/connect/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInE,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIvE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAG1D,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAStF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,SAAS,EAAE,cAAc,CAAC;IAC1B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAyC5B"}

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

@@ -17,6 +17,9 @@ import type { VaultConnectOptions } from '../types.js';
  * - 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

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

@@ -1 +1 @@
-{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../src/connect/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;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;AAmBvD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,WAAW,CAAC,CAmGtB"}
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../../src/connect/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;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;AAQvD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,WAAW,CAAC,CAsHtB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/auth",
-  "version": "0.6.34",
+  "version": "0.6.35",
   "description": "Headless authentication and identity management SDK for Enbox",
   "type": "module",
   "main": "./dist/esm/index.js",

package/src/connect/import.ts

@@ -10,22 +10,18 @@ import type { AuthSession } from '../identity-session.js';
 import type { FlowContext } from './lifecycle.js';
 import type { ImportFromPhraseOptions, ImportFromPortableOptions } from '../types.js';
 
-import { IdentityProtocolDefinition, JwkProtocolDefinition } from '@enbox/agent';
-
 import { DEFAULT_DWN_ENDPOINTS } from '../types.js';
 import { registerWithDwnEndpoints } from '../registration.js';
 import { createDefaultIdentity, ensureVaultReady, finalizeSession, registerSyncScopeForIdentity, resolveIdentityDids, startSyncIfEnabled } from './lifecycle.js';
-
-const AGENT_DID_SYNC_PROTOCOLS: [string, ...string[]] = [
-  IdentityProtocolDefinition.protocol,
-  JwkProtocolDefinition.protocol,
-];
+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.
+ * 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,
@@ -47,58 +43,73 @@ export async function importFromPhrase(
     dwnEndpoints,
   });
 
-  // The recovery phrase re-derives the same agent DID,
-  // but the user identity might not exist yet — create one if needed.
-  const identities = await userAgent.identity.list();
-  let identity = identities[0];
-  let isNewIdentity = false;
-
-  if (!identity) {
-    isNewIdentity = true;
-    identity = await createDefaultIdentity(userAgent, dwnEndpoints);
-  }
-
-  const { connectedDid, delegateDid } = resolveIdentityDids(identity);
-
-  // Register with DWN endpoints (if registration options are provided).
+  // Register agent DID as tenant and for sync — prerequisites for recovery.
   if (ctx.registration) {
     await registerWithDwnEndpoints(
       {
-        userAgent   : userAgent,
+        userAgent,
         dwnEndpoints,
-        agentDid    : userAgent.agentDid.uri,
-        connectedDid,
-        secretStore : userAgent.secrets,
-        storage     : storage,
+        agentDid     : userAgent.agentDid.uri,
+        connectedDid : userAgent.agentDid.uri,
+        secretStore  : userAgent.secrets,
+        storage,
       },
       ctx.registration,
     );
   }
-
-  // Register sync. For delegate identities, always repair the registration
-  // (derive scope from active grants — revoked grants must not remain in a
-  // stale registration), regardless of whether the identity was just
-  // created or restored from storage. For local identities, register
-  // `protocols: 'all'` only on first creation; a pre-existing local
-  // identity was already registered during its initial flow.
-  if (delegateDid) {
-    await registerSyncScopeForIdentity({ userAgent, connectedDid, delegateDid });
-  } else if (isNewIdentity && sync !== 'off') {
-    await registerSyncScopeForIdentity({ userAgent, connectedDid });
+  if (sync !== 'off') {
+    await registerAgentDidForSync(userAgent);
   }
 
-  // Register the agent DID for sync (same rationale as vaultConnect).
-  if (sync !== 'off') {
+  // 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 {
-      await userAgent.sync.registerIdentity({
-        did     : userAgent.agentDid.uri,
-        options : { protocols: AGENT_DID_SYNC_PROTOCOLS },
-      });
-    } catch {
-      // Already registered from a previous session.
+      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);
 

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/vault.ts

@@ -13,22 +13,11 @@ import type { AuthSession } from '../identity-session.js';
 import type { FlowContext } from './lifecycle.js';
 import type { VaultConnectOptions } from '../types.js';
 
-import { IdentityProtocolDefinition, JwkProtocolDefinition } from '@enbox/agent';
-
 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';
-
-/**
- * Internal protocols that store recovery-critical data in the agent DID's DWN.
- * These must be synced so that seed phrase recovery can pull identity metadata,
- * portable DIDs, and encrypted private keys from the remote DWN.
- */
-const AGENT_DID_SYNC_PROTOCOLS: [string, ...string[]] = [
-  IdentityProtocolDefinition.protocol,
-  JwkProtocolDefinition.protocol,
-];
+import { recoverIdentitiesFromRemote, registerAgentDidForSync } from './recovery.js';
 
 /**
  * Execute the vault connect flow.
@@ -36,6 +25,9 @@ const AGENT_DID_SYNC_PROTOCOLS: [string, ...string[]] = [
  * - 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
@@ -71,11 +63,43 @@ export async function vaultConnect(
     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');
@@ -92,22 +116,23 @@ export async function vaultConnect(
     ? 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,
@@ -115,20 +140,6 @@ export async function vaultConnect(
     });
   }
 
-  // Register the agent DID for sync so that identity metadata, portable
-  // DIDs, and encrypted private keys are pushed to the remote DWN. Without
-  // this, seed phrase recovery on a new device has nothing to pull.
-  if (sync !== 'off') {
-    try {
-      await userAgent.sync.registerIdentity({
-        did     : userAgent.agentDid.uri,
-        options : { protocols: AGENT_DID_SYNC_PROTOCOLS },
-      });
-    } catch {
-      // Already registered from a previous session — no action needed.
-    }
-  }
-
   // Start sync.
   await startSyncIfEnabled(userAgent, sync);