@enbox/auth 0.3.1

package/src/flows/local-connect.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 { 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;
+  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;
+
+  const password = options.password ?? ctx.defaultPassword ?? 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 (await userAgent.firstLaunch()) {
+    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).
+  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,
+      },
+      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

@@ -0,0 +1,135 @@
+/**
+ * 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 { 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;
+  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;
+  }
+
+  const password = options.password ?? ctx.defaultPassword ?? 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).
+  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

@@ -0,0 +1,225 @@
+/**
+ * Wallet connect (OIDC/QR) flow.
+ *
+ * Connects to an external wallet via the WalletConnect 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 full OIDC wallet connect flow.
+  // permissionRequests are already agent-level ConnectPermissionRequest objects.
+  const result = await WalletConnect.initClient({
+    displayName        : options.displayName,
+    connectServerUrl   : options.connectServerUrl,
+    walletUri          : options.walletUri ?? 'web5://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,
+        },
+        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/identity-session.ts

@@ -0,0 +1,65 @@
+/**
+ * AuthSession represents an active, authenticated session with a specific identity.
+ * @module
+ */
+
+import type { EnboxAgent } from '@enbox/agent';
+
+import type { IdentityInfo } from './types.js';
+
+/**
+ * An active, authenticated session bound to a specific identity.
+ *
+ * The session exposes the authenticated **agent**, **did**, and
+ * **delegateDid** — the primitives needed to interact with the DWN
+ * network. Consumers that use `@enbox/api` can construct an `Enbox`
+ * instance from these properties:
+ *
+ * ```ts
+ * import { Enbox } from '@enbox/api';
+ *
+ * const session = await auth.connect();
+ * const enbox = Enbox.connect({
+ *   agent: session.agent,
+ *   connectedDid: session.did,
+ *   delegateDid: session.delegateDid,
+ * });
+ * ```
+ */
+export class AuthSession {
+  /** The authenticated Enbox agent managing keys, DIDs, and DWN access. */
+  readonly agent: EnboxAgent;
+
+  /** The DID URI of the connected identity. */
+  readonly did: string;
+
+  /**
+   * The delegate DID URI, present when connected via wallet connect.
+   * This is the locally-created DID that holds delegated permissions
+   * from the wallet's identity.
+   */
+  readonly delegateDid?: string;
+
+  /**
+   * The BIP-39 recovery phrase, present only on first-time local connect.
+   * Should be shown to the user for backup and then discarded from memory.
+   */
+  readonly recoveryPhrase?: string;
+
+  /** Metadata about the connected identity. */
+  readonly identity: IdentityInfo;
+
+  constructor(params: {
+    agent: EnboxAgent;
+    did: string;
+    delegateDid?: string;
+    recoveryPhrase?: string;
+    identity: IdentityInfo;
+  }) {
+    this.agent = params.agent;
+    this.did = params.did;
+    this.delegateDid = params.delegateDid;
+    this.recoveryPhrase = params.recoveryPhrase;
+    this.identity = params.identity;
+  }
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * @enbox/auth — Headless authentication and identity management SDK.
+ *
+ * Provides composable, multi-identity-aware authentication that works
+ * in both browser and CLI environments. Depends only on `@enbox/agent`
+ * and can be used standalone or consumed by `@enbox/api`.
+ *
+ * @example Standalone auth
+ * ```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
+ * ```
+ *
+ * @example With @enbox/api
+ * ```ts
+ * import { AuthManager } from '@enbox/auth';
+ * import { Enbox } from '@enbox/api';
+ *
+ * const auth = await AuthManager.create({ sync: '15s' });
+ * const session = await auth.connect();
+ *
+ * const enbox = Enbox.connect({
+ *   agent: session.agent,
+ *   connectedDid: session.did,
+ *   delegateDid: session.delegateDid,
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// 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';
+
+// Re-export agent classes so consumers can construct custom agents/vaults
+// without a direct @enbox/agent dependency.
+export { EnboxUserAgent, HdIdentityVault } from '@enbox/agent';
+
+// Wallet-connect helpers
+export { processConnectedGrants } from './flows/wallet-connect.js';
+
+// Local DWN discovery (browser dwn:// protocol integration)
+export {
+  applyLocalDwnDiscovery,
+  checkUrlForDwnDiscoveryPayload,
+  clearLocalDwnEndpoint,
+  persistLocalDwnEndpoint,
+  probeLocalDwn,
+  requestLocalDwnDiscovery,
+  restoreLocalDwnEndpoint,
+} from './flows/dwn-discovery.js';
+
+// Storage adapters
+export { BrowserStorage, LevelStorage, MemoryStorage, createDefaultStorage } from './storage/storage.js';
+
+// Types
+export type {
+  AuthEvent,
+  AuthEventHandler,
+  AuthEventMap,
+  AuthManagerOptions,
+  AuthSessionInfo,
+  AuthState,
+  ConnectPermissionRequest,
+  DisconnectOptions,
+  IdentityInfo,
+  IdentityVaultBackup,
+  ImportFromPhraseOptions,
+  ImportFromPortableOptions,
+  LocalConnectOptions,
+  LocalDwnStrategy,
+  PortableIdentity,
+  ProviderAuthParams,
+  ProviderAuthResult,
+  RegistrationOptions,
+  RegistrationTokenData,
+  RestoreSessionOptions,
+  StorageAdapter,
+  SyncOption,
+  WalletConnectOptions,
+} from './types.js';