@enbox/auth 0.5.0 → 0.6.0

package/src/connect/import.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 { DEFAULT_DWN_ENDPOINTS } from '../types.js';
+import { registerWithDwnEndpoints } from '../registration.js';
+import { createDefaultIdentity, ensureVaultReady, finalizeSession, resolveIdentityDids, startSyncIfEnabled } from './lifecycle.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 async function importFromPhrase(
+  ctx: FlowContext,
+  options: ImportFromPhraseOptions,
+): Promise<AuthSession> {
+  const { userAgent, emitter, storage } = ctx;
+  const { recoveryPhrase, password } = options;
+  const sync = options.sync ?? ctx.defaultSync;
+  const dwnEndpoints = options.dwnEndpoints ?? ctx.defaultDwnEndpoints ?? DEFAULT_DWN_ENDPOINTS;
+
+  // Initialize the vault with the recovery phrase and start the agent.
+  const isFirstLaunch = await userAgent.firstLaunch();
+  await ensureVaultReady({
+    userAgent,
+    emitter,
+    password,
+    isFirstLaunch,
+    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 = 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).
+  if (ctx.registration) {
+    await registerWithDwnEndpoints(
+      {
+        userAgent : userAgent,
+        dwnEndpoints,
+        agentDid  : userAgent.agentDid.uri,
+        connectedDid,
+        storage   : storage,
+      },
+      ctx.registration,
+    );
+  }
+
+  // Register sync for new identities.
+  if (isNewIdentity && sync !== 'off') {
+    await userAgent.sync.registerIdentity({
+      did     : connectedDid,
+      options : { delegateDid, protocols: [] },
+    });
+  }
+
+  // Start sync.
+  startSyncIfEnabled(userAgent, sync);
+
+  // Persist session info, build AuthSession, and emit lifecycle events.
+  return finalizeSession({
+    userAgent,
+    emitter,
+    storage,
+    connectedDid,
+    delegateDid,
+    identityName         : identity.metadata.name,
+    identityConnectedDid : identity.metadata.connectedDid,
+  });
+}
+
+/**
+ * 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 async function importFromPortable(
+  ctx: FlowContext,
+  options: ImportFromPortableOptions,
+): Promise<AuthSession> {
+  const { userAgent, emitter, storage } = ctx;
+  const sync = options.sync ?? ctx.defaultSync;
+
+  const identity = await userAgent.identity.import({
+    portableIdentity: options.portableIdentity,
+  });
+
+  const { connectedDid, delegateDid } = resolveIdentityDids(identity);
+
+  // Register with DWN endpoints (if registration options are provided).
+  // For portable imports, extract endpoints from the DID document's DWN service.
+  if (ctx.registration) {
+    const dwnEndpoints = ctx.defaultDwnEndpoints ?? DEFAULT_DWN_ENDPOINTS;
+    await registerWithDwnEndpoints(
+      {
+        userAgent : userAgent,
+        dwnEndpoints,
+        agentDid  : userAgent.agentDid.uri,
+        connectedDid,
+        storage   : storage,
+      },
+      ctx.registration,
+    );
+  }
+
+  // Register and start sync.
+  if (sync !== 'off') {
+    await userAgent.sync.registerIdentity({
+      did     : connectedDid,
+      options : { delegateDid, protocols: [] },
+    });
+  }
+
+  startSyncIfEnabled(userAgent, sync);
+
+  // Persist session info, build AuthSession, and emit lifecycle events.
+  return finalizeSession({
+    userAgent,
+    emitter,
+    storage,
+    connectedDid,
+    delegateDid,
+    identityName         : identity.metadata.name,
+    identityConnectedDid : identity.metadata.connectedDid,
+  });
+}

package/src/connect/lifecycle.ts

@@ -0,0 +1,321 @@
+/**
+ * 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 { BearerIdentity, EnboxUserAgent } from '@enbox/agent';
+
+import type { AuthEventEmitter } from '../events.js';
+import type { PasswordProvider } from '../password-provider.js';
+import type { IdentityInfo, RegistrationOptions, StorageAdapter, SyncOption } from '../types.js';
+
+import { AuthSession } from '../identity-session.js';
+import { DEFAULT_DWN_ENDPOINTS, INSECURE_DEFAULT_PASSWORD, STORAGE_KEYS } from '../types.js';
+
+// ─── FlowContext ─────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ─── resolvePassword ─────────────────────────────────────────────
+
+/**
+ * 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 async function resolvePassword(
+  ctx: Pick<FlowContext, 'defaultPassword' | 'passwordProvider'>,
+  explicit: string | undefined,
+  isFirstLaunch: boolean,
+): Promise<string> {
+  let password = explicit ?? ctx.defaultPassword;
+
+  if (!password && ctx.passwordProvider) {
+    try {
+      password = await ctx.passwordProvider.getPassword({
+        reason: isFirstLaunch ? 'create' : 'unlock',
+      });
+    } catch {
+      // Provider failed — fall through to insecure default.
+    }
+  }
+
+  password ??= INSECURE_DEFAULT_PASSWORD;
+
+  if (password === INSECURE_DEFAULT_PASSWORD) {
+    console.warn(
+      '[@enbox/auth] SECURITY WARNING: No password set. Using insecure default. ' +
+      'Set a password via AuthManager.create({ password }) or connect({ password }) ' +
+      'to protect your identity vault.'
+    );
+  }
+
+  return password;
+}
+
+// ─── ensureVaultReady ────────────────────────────────────────────
+
+/**
+ * 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 async function ensureVaultReady(params: {
+  userAgent: EnboxUserAgent;
+  emitter: AuthEventEmitter;
+  password: string;
+  isFirstLaunch: boolean;
+  recoveryPhrase?: string;
+  dwnEndpoints?: string[];
+}): Promise<string | undefined> {
+  const { userAgent, emitter, password, isFirstLaunch } = params;
+  let recoveryPhrase: string | undefined;
+
+  if (isFirstLaunch) {
+    recoveryPhrase = await userAgent.initialize({
+      password,
+      recoveryPhrase : params.recoveryPhrase,
+      dwnEndpoints   : params.dwnEndpoints,
+    });
+  }
+
+  await userAgent.start({ password });
+  emitter.emit('vault-unlocked', {});
+
+  return recoveryPhrase;
+}
+
+// ─── startSyncIfEnabled ─────────────────────────────────────────
+
+/**
+ * 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 function startSyncIfEnabled(
+  userAgent: EnboxUserAgent,
+  sync: SyncOption | undefined,
+): void {
+  if (sync === 'off') {
+    return;
+  }
+
+  const syncMode = sync === undefined ? 'live' : 'poll';
+  const syncInterval = sync ?? (syncMode === 'live' ? '5m' : '2m');
+
+  userAgent.sync.startSync({ mode: syncMode, interval: syncInterval })
+    .catch((err: unknown) => {
+      console.error('[@enbox/auth] Sync failed:', err);
+    });
+}
+
+// ─── createDefaultIdentity ──────────────────────────────────────
+
+/**
+ * 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 async function createDefaultIdentity(
+  userAgent: EnboxUserAgent,
+  dwnEndpoints: string[] = DEFAULT_DWN_ENDPOINTS,
+  name = 'Default',
+): Promise<BearerIdentity> {
+  return userAgent.identity.create({
+    didMethod  : 'dht',
+    metadata   : { name },
+    didOptions : {
+      services: [
+        {
+          id              : 'dwn',
+          type            : 'DecentralizedWebNode',
+          serviceEndpoint : dwnEndpoints,
+        }
+      ],
+      verificationMethods: [
+        {
+          algorithm : 'Ed25519',
+          id        : 'sig',
+          purposes  : ['assertionMethod', 'authentication'],
+        },
+        {
+          algorithm : 'X25519',
+          id        : 'enc',
+          purposes  : ['keyAgreement'],
+        },
+      ],
+    },
+  });
+}
+
+// ─── resolveIdentityDids ────────────────────────────────────────
+
+/**
+ * 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 function resolveIdentityDids(
+  identity: BearerIdentity,
+  storedDelegateDid?: string,
+): {
+  connectedDid: string;
+  delegateDid: string | undefined;
+} {
+  const connectedDid = identity.metadata.connectedDid ?? identity.did.uri;
+  const delegateDid = identity.metadata.connectedDid
+    ? identity.did.uri
+    : (storedDelegateDid ?? undefined);
+  return { connectedDid, delegateDid };
+}
+
+// ─── finalizeSession ────────────────────────────────────────────
+
+/**
+ * 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 async 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> {
+  const {
+    userAgent,
+    emitter,
+    storage,
+    connectedDid,
+    delegateDid,
+    recoveryPhrase,
+    identityName,
+    identityConnectedDid,
+    emitIdentityAdded = true,
+    extraStorageKeys,
+  } = params;
+
+  // Persist session markers.
+  await storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
+  await storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
+
+  if (extraStorageKeys) {
+    for (const [key, value] of Object.entries(extraStorageKeys)) {
+      await storage.set(key, value);
+    }
+  }
+
+  const identityInfo: IdentityInfo = {
+    didUri       : connectedDid,
+    name         : identityName,
+    connectedDid : identityConnectedDid,
+  };
+
+  const session = new AuthSession({
+    agent    : userAgent,
+    did      : connectedDid,
+    delegateDid,
+    recoveryPhrase,
+    identity : identityInfo,
+  });
+
+  if (emitIdentityAdded) {
+    emitter.emit('identity-added', { identity: identityInfo });
+  }
+
+  emitter.emit('session-start', {
+    session: { did: connectedDid, delegateDid, identity: identityInfo },
+  });
+
+  return session;
+}

package/src/connect/local.ts

@@ -0,0 +1,101 @@
+/**
+ * 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';
+
+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';
+
+/**
+ * Execute the local connect flow.
+ *
+ * - On first launch: initializes the vault, creates a new DID, returns recovery phrase.
+ * - On subsequent launches: unlocks the vault and reconnects to the existing identity.
+ */
+export async function localConnect(
+  ctx: FlowContext,
+  options: LocalConnectOptions = {},
+): Promise<AuthSession> {
+  const { userAgent, emitter, storage } = ctx;
+
+  // Resolve password through the standard chain.
+  const isFirstLaunch = await userAgent.firstLaunch();
+  const password = await resolvePassword(ctx, options.password, isFirstLaunch);
+
+  const sync = options.sync ?? ctx.defaultSync;
+  const dwnEndpoints = options.dwnEndpoints ?? ctx.defaultDwnEndpoints ?? DEFAULT_DWN_ENDPOINTS;
+
+  // Initialize vault on first launch and start the agent.
+  const recoveryPhrase = await ensureVaultReady({
+    userAgent,
+    emitter,
+    password,
+    isFirstLaunch,
+    recoveryPhrase: options.recoveryPhrase,
+    dwnEndpoints,
+  });
+
+  // Apply local DWN discovery (browser redirect payload or persisted endpoint).
+  // In remote mode, discovery already ran before agent creation — skip.
+  if (!userAgent.dwn.isRemoteMode) {
+    await applyLocalDwnDiscovery(userAgent, storage, emitter);
+  }
+
+  // Find or create the user identity.
+  const identities = await userAgent.identity.list();
+  let identity = identities[0];
+  let isNewIdentity = false;
+
+  if (!identity) {
+    isNewIdentity = true;
+    identity = await createDefaultIdentity(userAgent, dwnEndpoints, options.metadata?.name ?? 'Default');
+  }
+
+  const { connectedDid, delegateDid } = resolveIdentityDids(identity);
+
+  // Register with DWN endpoints (if registration options are provided).
+  if (ctx.registration) {
+    await registerWithDwnEndpoints(
+      {
+        userAgent : userAgent,
+        dwnEndpoints,
+        agentDid  : userAgent.agentDid.uri,
+        connectedDid,
+        storage   : storage,
+      },
+      ctx.registration,
+    );
+  }
+
+  // Register sync for new identities.
+  if (isNewIdentity && sync !== 'off') {
+    await userAgent.sync.registerIdentity({
+      did     : connectedDid,
+      options : { delegateDid, protocols: [] },
+    });
+  }
+
+  // Start sync.
+  startSyncIfEnabled(userAgent, sync);
+
+  // Persist session info, build AuthSession, and emit lifecycle events.
+  return finalizeSession({
+    userAgent,
+    emitter,
+    storage,
+    connectedDid,
+    delegateDid,
+    recoveryPhrase,
+    identityName         : identity.metadata.name,
+    identityConnectedDid : identity.metadata.connectedDid,
+  });
+}

package/src/connect/restore.ts

@@ -0,0 +1,117 @@
+/**
+ * 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';
+
+import { applyLocalDwnDiscovery } from '../discovery.js';
+import { STORAGE_KEYS } from '../types.js';
+import { ensureVaultReady, finalizeSession, resolveIdentityDids, resolvePassword, startSyncIfEnabled } from './lifecycle.js';
+
+/**
+ * Attempt to restore a previous session.
+ *
+ * Returns `undefined` if no previous session exists.
+ * Returns an `AuthSession` if the session was successfully restored.
+ */
+export async function restoreSession(
+  ctx: FlowContext,
+  options: RestoreSessionOptions = {},
+): Promise<AuthSession | undefined> {
+  const { userAgent, emitter, storage } = ctx;
+
+  // Check if there was a previous session.
+  const previouslyConnected = await storage.get(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
+  if (previouslyConnected !== 'true') {
+    return undefined;
+  }
+
+  // Resolve password: explicit option → callback → provider → manager default → insecure fallback.
+  // Note: restoreSession has an extra `onPasswordRequired` callback that sits between
+  // the explicit password and the provider. We handle that here, then delegate the
+  // remainder of the chain to `resolvePassword()`.
+  let explicitPassword = options.password;
+
+  if (!explicitPassword && !ctx.defaultPassword && options.onPasswordRequired) {
+    explicitPassword = await options.onPasswordRequired();
+  }
+
+  // Check for stale session marker: if the vault was never initialized,
+  // previouslyConnected is a leftover — clean up and bail.
+  const isFirstLaunch = await userAgent.firstLaunch();
+  if (isFirstLaunch) {
+    await storage.remove(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
+    return undefined;
+  }
+
+  const password = await resolvePassword(ctx, explicitPassword, false);
+
+  // Start the agent (vault is known to exist).
+  await ensureVaultReady({
+    userAgent,
+    emitter,
+    password,
+    isFirstLaunch: false,
+  });
+
+  // Apply local DWN discovery (browser redirect payload or persisted endpoint).
+  // In remote mode, discovery already ran before agent creation — skip.
+  if (!userAgent.dwn.isRemoteMode) {
+    await applyLocalDwnDiscovery(userAgent, storage, emitter);
+  }
+
+  // Determine which identity to reconnect.
+  const activeIdentityDid = await storage.get(STORAGE_KEYS.ACTIVE_IDENTITY);
+  const storedDelegateDid = await storage.get(STORAGE_KEYS.DELEGATE_DID);
+
+  // First try the connected identity (wallet-connected sessions).
+  let identity = await userAgent.identity.connectedIdentity();
+
+  if (!identity) {
+    // Try to find the specific active identity.
+    if (activeIdentityDid) {
+      identity = await userAgent.identity.get({ didUri: activeIdentityDid });
+    }
+
+    // Fall back to the first available identity.
+    if (!identity) {
+      const identities = await userAgent.identity.list();
+      identity = identities[0];
+    }
+  }
+
+  if (!identity) {
+    // No identity found — clean up stale session data.
+    await storage.remove(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
+    await storage.remove(STORAGE_KEYS.ACTIVE_IDENTITY);
+    await storage.remove(STORAGE_KEYS.DELEGATE_DID);
+    await storage.remove(STORAGE_KEYS.CONNECTED_DID);
+    return undefined;
+  }
+
+  const { connectedDid, delegateDid } = resolveIdentityDids(
+    identity, storedDelegateDid ?? undefined,
+  );
+
+  // Start sync.
+  startSyncIfEnabled(userAgent, ctx.defaultSync);
+
+  // Persist session info, build AuthSession, and emit lifecycle events.
+  // Session restore does not emit `identity-added` (identity was already added in the original flow).
+  return finalizeSession({
+    userAgent,
+    emitter,
+    storage,
+    connectedDid,
+    delegateDid,
+    identityName         : identity.metadata.name,
+    identityConnectedDid : identity.metadata.connectedDid,
+    emitIdentityAdded    : false,
+  });
+}