@enbox/auth 0.5.0 → 0.6.1

package/src/connect/local.ts

@@ -0,0 +1,116 @@
+/**
+ * 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. Identity creation is opt-in via
+ *   `options.createIdentity: true`.
+ * - On subsequent launches: unlocks the vault and reconnects to the existing identity.
+ *
+ * When no identities exist and `createIdentity` is not `true`, the session
+ * is returned with the **agent DID** as the connected DID. This allows apps to
+ * manage identity creation separately from vault setup.
+ */
+export async function localConnect(
+  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;
+  const shouldCreateIdentity = options.createIdentity === true;
+
+  // 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 && shouldCreateIdentity) {
+    isNewIdentity = true;
+    identity = await createDefaultIdentity(userAgent, dwnEndpoints, options.metadata?.name ?? 'Default');
+  }
+
+  // When no identity exists (createIdentity: false on first launch), use the
+  // agent DID as the session's connected DID. The session is still valid but
+  // operates in the agent's context rather than a user identity's context.
+  const connectedDid = identity
+    ? resolveIdentityDids(identity).connectedDid
+    : userAgent.agentDid.uri;
+
+  const delegateDid = identity
+    ? resolveIdentityDids(identity).delegateDid
+    : 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.
+  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,133 @@
+/**
+ * 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];
+    }
+  }
+
+  // Start sync.
+  startSyncIfEnabled(userAgent, ctx.defaultSync);
+
+  if (!identity) {
+    // No identity found — this is valid for agent-only sessions created
+    // with `createIdentity: false`. Restore a session using the agent DID.
+    // If the active identity stored was the agent DID, this is an
+    // intentional agent-only session rather than stale data.
+    const isAgentOnlySession = activeIdentityDid === userAgent.agentDid.uri;
+
+    if (!isAgentOnlySession) {
+      // Truly stale session data — clean up and bail.
+      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;
+    }
+
+    return finalizeSession({
+      userAgent,
+      emitter,
+      storage,
+      connectedDid      : userAgent.agentDid.uri,
+      emitIdentityAdded : false,
+    });
+  }
+
+  const { connectedDid, delegateDid } = resolveIdentityDids(
+    identity, storedDelegateDid ?? undefined,
+  );
+
+  // 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,
+  });
+}

package/src/connect/wallet.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 type { AuthSession } from '../identity-session.js';
+import type { FlowContext } from './lifecycle.js';
+import type { WalletConnectOptions } from '../types.js';
+
+import { DEFAULT_DWN_ENDPOINTS } from '../types.js';
+import { registerWithDwnEndpoints } from '../registration.js';
+import { WalletConnect } from '../wallet-connect-client.js';
+import { ensureVaultReady, finalizeDelegateSession, importDelegateAndSetupSync, resolvePassword } from './lifecycle.js';
+
+// Re-export for backward compatibility — processConnectedGrants moved to lifecycle.ts.
+export { processConnectedGrants } from './lifecycle.js';
+
+/**
+ * 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: FlowContext,
+  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".'
+    );
+  }
+
+  // Ensure the agent is initialized and started before the relay flow.
+  const isFirstLaunch = await userAgent.firstLaunch();
+  const password = await resolvePassword(ctx, undefined, isFirstLaunch);
+  await ensureVaultReady({ userAgent, emitter, password, isFirstLaunch });
+
+  // Run the Enbox Connect relay flow.
+  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.');
+  }
+
+  // Import delegate DID, process grants, and set up sync.
+  const { delegatePortableDid, connectedDid, delegateGrants } = result;
+  const identity = await importDelegateAndSetupSync({
+    userAgent, delegatePortableDid, connectedDid, delegateGrants,
+    flowName: 'Wallet connect',
+  });
+
+  // Register with DWN endpoints (if registration options are provided).
+  if (ctx.registration) {
+    const dwnEndpoints = ctx.defaultDwnEndpoints ?? DEFAULT_DWN_ENDPOINTS;
+    await registerWithDwnEndpoints(
+      {
+        userAgent,
+        dwnEndpoints,
+        agentDid: userAgent.agentDid.uri,
+        connectedDid,
+        storage,
+      },
+      ctx.registration,
+    );
+  }
+
+  // Finalize session.
+  return finalizeDelegateSession({
+    userAgent, emitter, storage, identity,
+    connectedDid, delegateDid: delegatePortableDid.uri, sync,
+  });
+}

package/src/{flows/dwn-discovery.ts → discovery.ts}

@@ -30,9 +30,10 @@ import type { EnboxUserAgent } from '@enbox/agent';
 import { EnboxRpcClient } from '@enbox/dwn-clients';
 import { buildDwnConnectUrl, localDwnServerName, normalizeBaseUrl, readDwnDiscoveryPayloadFromUrl } from '@enbox/agent';
 
-import type { AuthEventEmitter } from '../events.js';
-import { STORAGE_KEYS } from '../types.js';
-import type { StorageAdapter } from '../types.js';
+import type { AuthEventEmitter } from './events.js';
+import type { StorageAdapter } from './types.js';
+
+import { STORAGE_KEYS } from './types.js';
 
 /**
  * Check the current page URL for a `DwnDiscoveryPayload` in the fragment.

package/src/index.ts

@@ -5,30 +5,23 @@
  * in both browser and CLI environments. Depends only on `@enbox/agent`
  * and can be used standalone or consumed by `@enbox/api`.
  *
- * @example Standalone auth
+ * @example Standalone auth (wallet app)
  * ```ts
  * import { AuthManager } from '@enbox/auth';
  *
  * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.restoreSession() ?? await auth.connect();
- *
- * // session.agent — the authenticated Enbox agent
- * // session.did   — the connected DID URI
+ * const session = await auth.connectLocal({ password: userPin });
  * ```
  *
- * @example With @enbox/api
+ * @example Dapp with browser connect handler
  * ```ts
  * import { AuthManager } from '@enbox/auth';
- * import { Enbox } from '@enbox/api';
- *
- * const auth = await AuthManager.create({ sync: '15s' });
- * const session = await auth.connect();
+ * import { BrowserConnectHandler } from '@enbox/browser';
  *
- * const enbox = Enbox.connect({
- *   agent: session.agent,
- *   connectedDid: session.did,
- *   delegateDid: session.delegateDid,
+ * const auth = await AuthManager.create({
+ *   connectHandler: BrowserConnectHandler(),
  * });
+ * const session = await auth.connect({ protocols: [NotesProtocol] });
  * ```
  *
  * @packageDocumentation
@@ -37,7 +30,6 @@
 // Core classes
 export { AuthManager } from './auth-manager.js';
 export { AuthSession } from './identity-session.js';
-export { VaultManager } from './vault/vault-manager.js';
 export { AuthEventEmitter } from './events.js';
 
 // Password providers
@@ -48,11 +40,14 @@ export type { PasswordContext } from './password-provider.js';
 // without a direct @enbox/agent dependency.
 export { EnboxUserAgent, HdIdentityVault } from '@enbox/agent';
 
-// Wallet-connect helpers
-export { processConnectedGrants } from './flows/wallet-connect.js';
+// Connect helpers
+export { processConnectedGrants } from './connect/wallet.js';
+export { normalizeProtocolRequests } from './permissions.js';
+export { WalletConnect } from './wallet-connect-client.js';
+export type { ProtocolPermissionOptions, WalletConnectClientOptions } from './wallet-connect-client.js';
 
 // Registration token storage helpers
-export { loadTokensFromStorage, saveTokensToStorage } from './flows/dwn-registration.js';
+export { loadTokensFromStorage, saveTokensToStorage } from './registration.js';
 
 // Local DWN discovery (browser dwn:// protocol integration)
 export {
@@ -63,7 +58,7 @@ export {
   persistLocalDwnEndpoint,
   requestLocalDwnDiscovery,
   restoreLocalDwnEndpoint,
-} from './flows/dwn-discovery.js';
+} from './discovery.js';
 
 // Storage adapters
 export { BrowserStorage, LevelStorage, MemoryStorage, createDefaultStorage } from './storage/storage.js';
@@ -76,8 +71,12 @@ export type {
   AuthManagerOptions,
   AuthSessionInfo,
   AuthState,
+  ConnectHandler,
+  ConnectOptions,
   ConnectPermissionRequest,
+  ConnectResult,
   DisconnectOptions,
+  HandlerConnectOptions,
   HeadlessConnectOptions,
   IdentityInfo,
   IdentityVaultBackup,
@@ -85,7 +84,9 @@ export type {
   ImportFromPortableOptions,
   LocalConnectOptions,
   LocalDwnStrategy,
+  Permission,
   PortableIdentity,
+  ProtocolRequest,
   ProviderAuthParams,
   ProviderAuthResult,
   RegistrationOptions,

package/src/permissions.ts

@@ -0,0 +1,48 @@
+/**
+ * Permission request normalization utilities.
+ *
+ * Converts simplified `ProtocolRequest` entries (just a protocol definition
+ * or `{ definition, permissions }`) into agent-level `ConnectPermissionRequest`
+ * objects used by connect handlers.
+ *
+ * @module
+ * @internal
+ */
+
+import type { ConnectPermissionRequest, DwnProtocolDefinition } from '@enbox/agent';
+
+import type { ProtocolRequest } from './types.js';
+
+import { DEFAULT_PERMISSIONS } from './types.js';
+import { WalletConnect } from './wallet-connect-client.js';
+
+/**
+ * Normalize simplified `ProtocolRequest[]` into agent-level
+ * `ConnectPermissionRequest[]`.
+ */
+export function normalizeProtocolRequests(
+  protocols: ProtocolRequest[] | undefined,
+): ConnectPermissionRequest[] {
+  if (!protocols || protocols.length === 0) { return []; }
+
+  return protocols.map((entry) => {
+    let definition: DwnProtocolDefinition;
+    let permissions: string[];
+
+    if ('protocol' in entry && 'types' in entry && 'structure' in entry) {
+      // Bare protocol definition — use default permissions.
+      definition = entry as DwnProtocolDefinition;
+      permissions = [...DEFAULT_PERMISSIONS];
+    } else {
+      // Object with explicit permissions.
+      const explicit = entry as { definition: DwnProtocolDefinition; permissions: string[] };
+      definition = explicit.definition;
+      permissions = explicit.permissions;
+    }
+
+    return WalletConnect.createPermissionRequestForProtocol({
+      definition,
+      permissions: permissions as Parameters<typeof WalletConnect.createPermissionRequestForProtocol>[0]['permissions'],
+    });
+  });
+}

package/src/{flows/dwn-registration.ts → registration.ts}

@@ -15,13 +15,13 @@ import type { EnboxUserAgent } from '@enbox/agent';
 
 import { DwnRegistrar } from '@enbox/dwn-clients';
 
-import { STORAGE_KEYS } from '../types.js';
+import { STORAGE_KEYS } from './types.js';
 
 import type {
   RegistrationOptions,
   RegistrationTokenData,
   StorageAdapter,
-} from '../types.js';
+} from './types.js';
 
 /** @internal */
 export interface RegistrationContext {