@enbox/auth 0.5.0 → 0.6.1

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;
-}

package/src/flows/wallet-connect.ts

@@ -1,226 +0,0 @@
-/**
- * Wallet connect (Enbox Connect relay) flow.
- *
- * Connects to an external wallet via the Enbox Connect relay protocol,
- * importing a delegated DID with permission grants.
- * This replaces the "Mode B/C" paths in Enbox.connect().
- * @module
- */
-
-import { Convert } from '@enbox/common';
-import { WalletConnect } from '@enbox/agent';
-import type { DwnDataEncodedRecordsWriteMessage, DwnMessagesPermissionScope, DwnRecordsPermissionScope, EnboxUserAgent } from '@enbox/agent';
-import { DwnInterface, DwnPermissionGrant } 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 { RegistrationOptions, StorageAdapter, SyncOption, WalletConnectOptions } from '../types.js';
-
-/** @internal */
-export interface WalletConnectContext {
-  userAgent: EnboxUserAgent;
-  emitter: AuthEventEmitter;
-  storage: StorageAdapter;
-  defaultSync?: SyncOption;
-  defaultDwnEndpoints?: string[];
-  registration?: RegistrationOptions;
-}
-
-/**
- * Process connected grants by storing them in the local DWN as the owner.
- *
- * This is the agent-level equivalent of `Enbox.processConnectedGrants()`.
- * It stores each grant, signed as owner, and returns the deduplicated
- * list of protocol URIs represented by the grants.
- *
- * @internal
- */
-export async function processConnectedGrants(params: {
-  agent: EnboxUserAgent;
-  delegateDid: string;
-  grants: DwnDataEncodedRecordsWriteMessage[];
-}): Promise<string[]> {
-  const { agent, delegateDid, grants } = params;
-  const connectedProtocols = new Set<string>();
-
-  for (const grantMessage of grants) {
-    const grant = DwnPermissionGrant.parse(grantMessage);
-
-    // Store the grant as the owner of the DWN so the delegateDid
-    // can use it when impersonating the connectedDid.
-    const { encodedData, ...rawMessage } = grantMessage;
-    const dataStream = new Blob([Convert.base64Url(encodedData).toUint8Array() as BlobPart]);
-
-    const { reply } = await agent.processDwnRequest({
-      store       : true,
-      author      : delegateDid,
-      target      : delegateDid,
-      messageType : DwnInterface.RecordsWrite,
-      signAsOwner : true,
-      rawMessage,
-      dataStream,
-    });
-
-    if (reply.status.code !== 202) {
-      throw new Error(
-        `[@enbox/auth] Failed to process connected grant: ${reply.status.detail}`
-      );
-    }
-
-    const protocol = (grant.scope as DwnMessagesPermissionScope | DwnRecordsPermissionScope).protocol;
-    if (protocol) {
-      connectedProtocols.add(protocol);
-    }
-  }
-
-  return [...connectedProtocols];
-}
-
-/**
- * Execute the wallet connect flow.
- *
- * 1. Passes the permission requests directly to `WalletConnect.initClient()`.
- * 2. Imports the delegate DID and processes grants.
- * 3. Sets up sync and returns an AuthSession.
- */
-export async function walletConnect(
-  ctx: WalletConnectContext,
-  options: WalletConnectOptions,
-): Promise<AuthSession> {
-  const { userAgent, emitter, storage } = ctx;
-  const sync = options.sync ?? ctx.defaultSync;
-
-  if (sync === 'off') {
-    throw new Error(
-      '[@enbox/auth] Sync must be enabled when using wallet connect. ' +
-      'Remove sync: "off" or set an interval like "15s".'
-    );
-  }
-
-  // Run the Enbox Connect relay flow.
-  // permissionRequests are already agent-level ConnectPermissionRequest objects.
-  const result = await WalletConnect.initClient({
-    displayName        : options.displayName,
-    connectServerUrl   : options.connectServerUrl,
-    walletUri          : options.walletUri ?? 'enbox://connect',
-    permissionRequests : options.permissionRequests,
-    onWalletUriReady   : options.onWalletUriReady,
-    validatePin        : options.validatePin,
-  });
-
-  if (!result) {
-    throw new Error('[@enbox/auth] Wallet connect flow was cancelled or returned no result.');
-  }
-
-  const { delegatePortableDid, connectedDid, delegateGrants } = result;
-
-  // Import the delegated DID as an Identity.
-  let identity;
-  try {
-    identity = await userAgent.identity.import({
-      portableIdentity: {
-        portableDid : delegatePortableDid,
-        metadata    : {
-          connectedDid,
-          name   : 'Default',
-          uri    : delegatePortableDid.uri,
-          tenant : userAgent.agentDid.uri,
-        },
-      },
-    });
-
-    // Process the connected grants using agent primitives.
-    const connectedProtocols = await processConnectedGrants({
-      agent       : userAgent,
-      delegateDid : delegatePortableDid.uri,
-      grants      : delegateGrants,
-    });
-
-    // Register with DWN endpoints (if registration options are provided).
-    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 sync for the connected identity.
-    await userAgent.sync.registerIdentity({
-      did     : connectedDid,
-      options : {
-        delegateDid : delegatePortableDid.uri,
-        protocols   : connectedProtocols,
-      },
-    });
-
-    // Pull down existing messages from the connected DID's DWN.
-    await userAgent.sync.sync('pull');
-  } catch (error: unknown) {
-    // Clean up on failure.
-    if (identity) {
-      try {
-        await userAgent.did.delete({
-          didUri    : identity.did.uri,
-          tenant    : identity.metadata.tenant,
-          deleteKey : true,
-        });
-      } catch { /* best effort */ }
-
-      try {
-        await userAgent.identity.delete({ didUri: identity.did.uri });
-      } catch { /* best effort */ }
-    }
-
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`[@enbox/auth] Wallet connect failed: ${message}`);
-  }
-
-  // Start sync.
-  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);
-    });
-
-  const delegateDid = delegatePortableDid.uri;
-
-  // Persist session info.
-  await storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
-  await storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
-  await storage.set(STORAGE_KEYS.DELEGATE_DID, delegateDid);
-  await storage.set(STORAGE_KEYS.CONNECTED_DID, 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      : session.did,
-      delegateDid,
-      identity : identityInfo,
-    },
-  });
-
-  return session;
-}

package/src/vault/vault-manager.ts

@@ -1,89 +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 class VaultManager {
-  private readonly _vault: HdIdentityVault;
-  private readonly _emitter: AuthEventEmitter;
-
-  constructor(vault: HdIdentityVault, emitter: AuthEventEmitter) {
-    this._vault = vault;
-    this._emitter = emitter;
-  }
-
-  /** The underlying vault instance (for advanced usage). */
-  get raw(): HdIdentityVault {
-    return this._vault;
-  }
-
-  /** Whether the vault has been initialized (has encrypted data). */
-  async isInitialized(): Promise<boolean> {
-    return this._vault.isInitialized();
-  }
-
-  /** Whether the vault is currently locked (synchronous check). */
-  get isLocked(): boolean {
-    return this._vault.isLocked();
-  }
-
-  /**
-   * 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.
-   */
-  async unlock(password: string): Promise<void> {
-    await this._vault.unlock({ password });
-    this._emitter.emit('vault-unlocked', {});
-  }
-
-  /**
-   * Lock the vault, clearing the CEK from memory.
-   * After locking, the password must be provided again to unlock.
-   */
-  async lock(): Promise<void> {
-    await this._vault.lock();
-    this._emitter.emit('vault-locked', {});
-  }
-
-  /**
-   * Change the vault password. Re-encrypts the CEK with the new password.
-   *
-   * @throws If the old password is incorrect or vault is locked.
-   */
-  async changePassword(oldPassword: string, newPassword: string): Promise<void> {
-    await this._vault.changePassword({ oldPassword, newPassword });
-  }
-
-  /**
-   * Create a backup of the vault.
-   *
-   * @throws If the vault is not initialized or is locked.
-   */
-  async backup(): Promise<IdentityVaultBackup> {
-    return this._vault.backup();
-  }
-
-  /**
-   * Restore the vault from a backup.
-   *
-   * @throws If the password doesn't match the backup's encryption.
-   */
-  async restore(backup: IdentityVaultBackup, password: string): Promise<void> {
-    await this._vault.restore({ backup, password });
-  }
-}