@enbox/auth 0.5.0 → 0.6.0

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

@@ -1,57 +0,0 @@
-/**
- * VaultManager wraps {@link HdIdentityVault} with a high-level API
- * and emits events on lock/unlock.
- * @module
- */
-import type { HdIdentityVault, IdentityVaultBackup } from '@enbox/agent';
-import type { AuthEventEmitter } from '../events.js';
-/**
- * Manages the encrypted identity vault lifecycle.
- *
- * The vault stores the agent's DID and content encryption key (CEK),
- * protected by a user password using PBES2-HS512+A256KW with a 210K
- * iteration work factor. The vault supports HD key derivation from
- * a BIP-39 mnemonic for recovery.
- */
-export declare class VaultManager {
-    private readonly _vault;
-    private readonly _emitter;
-    constructor(vault: HdIdentityVault, emitter: AuthEventEmitter);
-    /** The underlying vault instance (for advanced usage). */
-    get raw(): HdIdentityVault;
-    /** Whether the vault has been initialized (has encrypted data). */
-    isInitialized(): Promise<boolean>;
-    /** Whether the vault is currently locked (synchronous check). */
-    get isLocked(): boolean;
-    /**
-     * Unlock the vault with the given password.
-     * Decrypts the CEK into memory so the agent DID can be retrieved.
-     *
-     * @throws If the password is incorrect or vault is not initialized.
-     */
-    unlock(password: string): Promise<void>;
-    /**
-     * Lock the vault, clearing the CEK from memory.
-     * After locking, the password must be provided again to unlock.
-     */
-    lock(): Promise<void>;
-    /**
-     * Change the vault password. Re-encrypts the CEK with the new password.
-     *
-     * @throws If the old password is incorrect or vault is locked.
-     */
-    changePassword(oldPassword: string, newPassword: string): Promise<void>;
-    /**
-     * Create a backup of the vault.
-     *
-     * @throws If the vault is not initialized or is locked.
-     */
-    backup(): Promise<IdentityVaultBackup>;
-    /**
-     * Restore the vault from a backup.
-     *
-     * @throws If the password doesn't match the backup's encryption.
-     */
-    restore(backup: IdentityVaultBackup, password: string): Promise<void>;
-}
-//# sourceMappingURL=vault-manager.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"vault-manager.d.ts","sourceRoot":"","sources":["../../../src/vault/vault-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;gBAEhC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB;IAK7D,0DAA0D;IAC1D,IAAI,GAAG,IAAI,eAAe,CAEzB;IAED,mEAAmE;IAC7D,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAIvC,iEAAiE;IACjE,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;OAKG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B;;;;OAIG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI5C;;;;OAIG;IACG,OAAO,CAAC,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5E"}

package/src/flows/import-identity.ts

@@ -1,219 +0,0 @@
-/**
- * Identity import flows.
- *
- * - Import from BIP-39 recovery phrase (re-derive vault + identity).
- * - Import from PortableIdentity JSON.
- * @module
- */
-
-import type { EnboxUserAgent } from '@enbox/agent';
-
-import type { AuthEventEmitter } from '../events.js';
-import { AuthSession } from '../identity-session.js';
-import { registerWithDwnEndpoints } from './dwn-registration.js';
-import { STORAGE_KEYS } from '../types.js';
-import type {
-  ImportFromPhraseOptions,
-  ImportFromPortableOptions,
-  RegistrationOptions,
-  StorageAdapter,
-  SyncOption,
-} from '../types.js';
-
-/** @internal */
-export interface ImportContext {
-  userAgent: EnboxUserAgent;
-  emitter: AuthEventEmitter;
-  storage: StorageAdapter;
-  defaultSync?: SyncOption;
-  defaultDwnEndpoints?: string[];
-  registration?: RegistrationOptions;
-}
-
-/**
- * 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: ImportContext,
-  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 ?? ['https://enbox-dwn.fly.dev'];
-
-  // Initialize the vault with the recovery phrase.
-  // This re-derives the same agent DID and CEK from the mnemonic.
-  if (await userAgent.firstLaunch()) {
-    await userAgent.initialize({
-      password,
-      recoveryPhrase,
-      dwnEndpoints,
-    });
-  }
-
-  await userAgent.start({ password });
-  emitter.emit('vault-unlocked', {});
-
-  // 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 userAgent.identity.create({
-      didMethod  : 'dht',
-      metadata   : { name: 'Default' },
-      didOptions : {
-        services: [
-          {
-            id              : 'dwn',
-            type            : 'DecentralizedWebNode',
-            serviceEndpoint : dwnEndpoints,
-            enc             : '#enc',
-            sig             : '#sig',
-          }
-        ],
-        verificationMethods: [
-          {
-            algorithm : 'Ed25519',
-            id        : 'sig',
-            purposes  : ['assertionMethod', 'authentication'],
-          },
-          {
-            algorithm : 'X25519',
-            id        : 'enc',
-            purposes  : ['keyAgreement'],
-          },
-        ],
-      },
-    });
-  }
-
-  const connectedDid = identity.did.uri;
-
-  // 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 and start sync.
-  if (isNewIdentity && sync !== 'off') {
-    await userAgent.sync.registerIdentity({ did: connectedDid, options: { protocols: [] } });
-  }
-
-  if (sync !== 'off') {
-    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));
-  }
-
-  await storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
-  await storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
-
-  const identityInfo = {
-    didUri : connectedDid,
-    name   : identity.metadata.name,
-  };
-
-  const session = new AuthSession({
-    agent    : userAgent,
-    did      : connectedDid,
-    identity : identityInfo,
-  });
-
-  emitter.emit('identity-added', { identity: identityInfo });
-  emitter.emit('session-start', {
-    session: { did: connectedDid, identity: identityInfo },
-  });
-
-  return session;
-}
-
-/**
- * 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: ImportContext,
-  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 = identity.metadata.connectedDid ?? identity.did.uri;
-  const delegateDid = identity.metadata.connectedDid ? identity.did.uri : undefined;
-
-  // 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 ?? ['https://enbox-dwn.fly.dev'];
-    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: [] },
-    });
-
-    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));
-  }
-
-  await storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
-  await storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
-
-  const identityInfo = {
-    didUri       : connectedDid,
-    name         : identity.metadata.name,
-    connectedDid : identity.metadata.connectedDid,
-  };
-
-  const session = new AuthSession({
-    agent    : userAgent,
-    did      : connectedDid,
-    delegateDid,
-    identity : identityInfo,
-  });
-
-  emitter.emit('identity-added', { identity: identityInfo });
-  emitter.emit('session-start', {
-    session: { did: connectedDid, delegateDid, identity: identityInfo },
-  });
-
-  return session;
-}

package/src/flows/local-connect.ts

@@ -1,192 +0,0 @@
-/**
- * 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 { EnboxUserAgent } from '@enbox/agent';
-
-import type { AuthEventEmitter } from '../events.js';
-import type { PasswordProvider } from '../password-provider.js';
-import type { LocalConnectOptions, RegistrationOptions, StorageAdapter, SyncOption } from '../types.js';
-
-import { applyLocalDwnDiscovery } from './dwn-discovery.js';
-import { AuthSession } from '../identity-session.js';
-import { registerWithDwnEndpoints } from './dwn-registration.js';
-import { INSECURE_DEFAULT_PASSWORD, STORAGE_KEYS } from '../types.js';
-
-/** @internal */
-export interface LocalConnectContext {
-  userAgent: EnboxUserAgent;
-  emitter: AuthEventEmitter;
-  storage: StorageAdapter;
-  defaultPassword?: string;
-  passwordProvider?: PasswordProvider;
-  defaultSync?: SyncOption;
-  defaultDwnEndpoints?: string[];
-  registration?: RegistrationOptions;
-}
-
-/**
- * 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: LocalConnectContext,
-  options: LocalConnectOptions = {},
-): Promise<AuthSession> {
-  const { userAgent, emitter, storage } = ctx;
-
-  // Resolve password: explicit option → provider → manager default → insecure fallback.
-  const isFirstLaunch = await userAgent.firstLaunch();
-  let password = options.password ?? 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;
-
-  const sync = options.sync ?? ctx.defaultSync;
-  const dwnEndpoints = options.dwnEndpoints ?? ctx.defaultDwnEndpoints ?? ['https://enbox-dwn.fly.dev'];
-
-  // Warn if using insecure default.
-  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.'
-    );
-  }
-
-  let recoveryPhrase: string | undefined;
-
-  // Initialize vault on first launch.
-  if (isFirstLaunch) {
-    recoveryPhrase = await userAgent.initialize({
-      password,
-      recoveryPhrase: options.recoveryPhrase,
-      dwnEndpoints,
-    });
-  }
-
-  // Start the agent (unlocks vault if locked, sets agentDid).
-  await userAgent.start({ password });
-  emitter.emit('vault-unlocked', {});
-
-  // 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 userAgent.identity.create({
-      didMethod  : 'dht',
-      metadata   : { name: options.metadata?.name ?? 'Default' },
-      didOptions : {
-        services: [
-          {
-            id              : 'dwn',
-            type            : 'DecentralizedWebNode',
-            serviceEndpoint : dwnEndpoints,
-            enc             : '#enc',
-            sig             : '#sig',
-          }
-        ],
-        verificationMethods: [
-          {
-            algorithm : 'Ed25519',
-            id        : 'sig',
-            purposes  : ['assertionMethod', 'authentication'],
-          },
-          {
-            algorithm : 'X25519',
-            id        : 'enc',
-            purposes  : ['keyAgreement'],
-          },
-        ],
-      },
-    });
-  }
-
-  const connectedDid = identity.metadata.connectedDid ?? identity.did.uri;
-  const delegateDid = identity.metadata.connectedDid ? identity.did.uri : undefined;
-
-  // 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.
-  if (sync !== 'off') {
-    const syncMode = sync === undefined ? 'live' : 'poll';
-    const syncInterval = sync ?? (syncMode === 'live' ? '5m' : '2m');
-    userAgent.sync.startSync({ mode: syncMode, interval: syncInterval })
-      .catch((error: unknown) => {
-        console.error('[@enbox/auth] Sync failed:', error);
-      });
-  }
-
-  // Persist session info.
-  await storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
-  await storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
-
-  const identityInfo = {
-    didUri       : connectedDid,
-    name         : identity.metadata.name,
-    connectedDid : identity.metadata.connectedDid,
-  };
-
-  const session = new AuthSession({
-    agent    : userAgent,
-    did      : connectedDid,
-    delegateDid,
-    recoveryPhrase,
-    identity : identityInfo,
-  });
-
-  emitter.emit('identity-added', { identity: identityInfo });
-  emitter.emit('session-start', {
-    session: {
-      did      : session.did,
-      delegateDid,
-      identity : identityInfo,
-    },
-  });
-
-  return session;
-}

package/src/flows/session-restore.ts

@@ -1,155 +0,0 @@
-/**
- * Session restore flow.
- *
- * Restores a previously established session from persisted storage,
- * replacing the "previouslyConnected" pattern in apps.
- * @module
- */
-
-import type { EnboxUserAgent } from '@enbox/agent';
-
-import type { AuthEventEmitter } from '../events.js';
-import type { PasswordProvider } from '../password-provider.js';
-import type { RestoreSessionOptions, StorageAdapter, SyncOption } from '../types.js';
-
-import { applyLocalDwnDiscovery } from './dwn-discovery.js';
-import { AuthSession } from '../identity-session.js';
-import { INSECURE_DEFAULT_PASSWORD, STORAGE_KEYS } from '../types.js';
-
-/** @internal */
-export interface SessionRestoreContext {
-  userAgent: EnboxUserAgent;
-  emitter: AuthEventEmitter;
-  storage: StorageAdapter;
-  defaultPassword?: string;
-  passwordProvider?: PasswordProvider;
-  defaultSync?: SyncOption;
-}
-
-/**
- * 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: SessionRestoreContext,
-  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.
-  let password = options.password ?? ctx.defaultPassword;
-
-  if (!password && options.onPasswordRequired) {
-    password = await options.onPasswordRequired();
-  }
-
-  if (!password && ctx.passwordProvider) {
-    try {
-      password = await ctx.passwordProvider.getPassword({ reason: 'unlock' });
-    } catch {
-      // Provider failed — fall through to insecure default.
-    }
-  }
-
-  password ??= INSECURE_DEFAULT_PASSWORD;
-
-  // Warn if using insecure default.
-  if (password === INSECURE_DEFAULT_PASSWORD) {
-    console.warn(
-      '[@enbox/auth] SECURITY WARNING: No password set. Using insecure default. ' +
-      'Set a password to protect your identity vault.'
-    );
-  }
-
-  // Start the agent (initializes + unlocks vault).
-  if (await userAgent.firstLaunch()) {
-    // Vault doesn't exist yet — this shouldn't happen if previouslyConnected is true.
-    // Clean up the stale flag and return undefined.
-    await storage.remove(STORAGE_KEYS.PREVIOUSLY_CONNECTED);
-    return undefined;
-  }
-
-  await userAgent.start({ password });
-  emitter.emit('vault-unlocked', {});
-
-  // 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 = identity.metadata.connectedDid ?? identity.did.uri;
-  const delegateDid = identity.metadata.connectedDid
-    ? identity.did.uri
-    : (storedDelegateDid ?? undefined);
-
-  // Start sync.
-  const sync = ctx.defaultSync;
-  if (sync !== 'off') {
-    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);
-      });
-  }
-
-  // Update persisted session info.
-  await storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
-
-  const identityInfo = {
-    didUri       : connectedDid,
-    name         : identity.metadata.name,
-    connectedDid : identity.metadata.connectedDid,
-  };
-
-  const session = new AuthSession({
-    agent    : userAgent,
-    did      : connectedDid,
-    delegateDid,
-    identity : identityInfo,
-  });
-
-  emitter.emit('session-start', {
-    session: { did: connectedDid, delegateDid, identity: identityInfo },
-  });
-
-  return session;
-}