@enbox/auth 0.4.0 → 0.5.0

package/src/auth-manager.ts

@@ -12,23 +12,28 @@ import type { BearerIdentity, PortableIdentity } from '@enbox/agent';
 import { AuthEventEmitter } from './events.js';
 import { AuthSession } from './identity-session.js';
 import { createDefaultStorage } from './storage/storage.js';
+import { discoverLocalDwn } from './flows/dwn-discovery.js';
 import { localConnect } from './flows/local-connect.js';
 import { restoreSession } from './flows/session-restore.js';
 import { STORAGE_KEYS } from './types.js';
 import { VaultManager } from './vault/vault-manager.js';
 import { walletConnect } from './flows/wallet-connect.js';
+
+import type { PasswordProvider } from './password-provider.js';
 import type {
   AuthEvent,
   AuthEventHandler,
   AuthManagerOptions,
   AuthState,
   DisconnectOptions,
+  HeadlessConnectOptions,
   IdentityInfo,
   ImportFromPhraseOptions,
   ImportFromPortableOptions,
   LocalConnectOptions,
   RegistrationOptions,
   RestoreSessionOptions,
+  ShutdownOptions,
   StorageAdapter,
   SyncOption,
   WalletConnectOptions,
@@ -76,31 +81,45 @@ export class AuthManager {
   private _session: AuthSession | undefined;
   private _state: AuthState = 'uninitialized';
   private _isConnecting = false;
+  private _isShutDown = false;
 
   // Default options from create()
   private _defaultPassword?: string;
+  private _passwordProvider?: PasswordProvider;
   private _defaultSync?: SyncOption;
   private _defaultDwnEndpoints?: string[];
   private _registration?: RegistrationOptions;
 
+  /**
+   * The local DWN server endpoint discovered during `create()`, if any.
+   * `undefined` means no local server was found. This is set before any
+   * event listeners are attached, so consumers should check this property
+   * after `create()` returns rather than relying solely on events.
+   */
+  private _localDwnEndpoint?: string;
+
   private constructor(params: {
     userAgent: EnboxUserAgent;
     emitter: AuthEventEmitter;
     storage: StorageAdapter;
     vault: VaultManager;
     defaultPassword?: string;
+    passwordProvider?: PasswordProvider;
     defaultSync?: SyncOption;
     defaultDwnEndpoints?: string[];
     registration?: RegistrationOptions;
+    localDwnEndpoint?: string;
   }) {
     this._userAgent = params.userAgent;
     this._emitter = params.emitter;
     this._storage = params.storage;
     this._vault = params.vault;
     this._defaultPassword = params.defaultPassword;
+    this._passwordProvider = params.passwordProvider;
     this._defaultSync = params.defaultSync;
     this._defaultDwnEndpoints = params.defaultDwnEndpoints;
     this._registration = params.registration;
+    this._localDwnEndpoint = params.localDwnEndpoint;
   }
 
   /**
@@ -117,11 +136,27 @@ export class AuthManager {
     const emitter = new AuthEventEmitter();
     const storage = options.storage ?? createDefaultStorage();
 
+    // Run local DWN discovery BEFORE creating the agent. Discovery has
+    // zero vault/DWN dependencies — it only checks the URL fragment,
+    // reads localStorage, and validates via GET /info.
+    //
+    // When a local DWN server is available, the agent is created in
+    // "remote mode": it skips creating an in-process DWN and routes all
+    // DWN operations through RPC to the local server.
+    let localDwnEndpoint: string | undefined;
+    if (!options.agent && options.localDwnStrategy !== 'off') {
+      localDwnEndpoint = await discoverLocalDwn(storage);
+      // NOTE: We intentionally do NOT emit 'local-dwn-available' here
+      // because event listeners aren't attached yet. Consumers should
+      // check `authManager.localDwnEndpoint` after create() returns.
+    }
+
     // Use a pre-built agent or create one with the given options.
     const userAgent = options.agent ?? await EnboxUserAgent.create({
       dataPath         : options.dataPath,
       agentVault       : options.agentVault,
       localDwnStrategy : options.localDwnStrategy,
+      localDwnEndpoint,
     });
 
     const vault = new VaultManager(userAgent.vault, emitter);
@@ -132,9 +167,11 @@ export class AuthManager {
       storage,
       vault,
       defaultPassword     : options.password,
+      passwordProvider    : options.passwordProvider,
       defaultSync         : options.sync,
       defaultDwnEndpoints : options.dwnEndpoints,
       registration        : options.registration,
+      localDwnEndpoint,
     });
 
     // Determine initial state.
@@ -170,6 +207,7 @@ export class AuthManager {
           emitter             : this._emitter,
           storage             : this._storage,
           defaultPassword     : this._defaultPassword,
+          passwordProvider    : this._passwordProvider,
           defaultSync         : this._defaultSync,
           defaultDwnEndpoints : this._defaultDwnEndpoints,
           registration        : this._registration,
@@ -186,7 +224,7 @@ export class AuthManager {
   }
 
   /**
-   * Connect to an external wallet via the OIDC/QR relay protocol.
+   * Connect to an external wallet via the Enbox Connect relay protocol.
    *
    * This runs the full WalletConnect flow: generates a URI for QR display,
    * validates the PIN, imports the delegated DID, and processes grants.
@@ -202,8 +240,22 @@ export class AuthManager {
 
     try {
       // Ensure the agent is initialized and started before wallet connect.
-      const password = this._defaultPassword ?? 'insecure-static-phrase';
-      if (await this._userAgent.firstLaunch()) {
+      const isFirstLaunch = await this._userAgent.firstLaunch();
+      let password = this._defaultPassword;
+
+      if (!password && this._passwordProvider) {
+        try {
+          password = await this._passwordProvider.getPassword({
+            reason: isFirstLaunch ? 'create' : 'unlock',
+          });
+        } catch {
+          // Provider failed — fall through to insecure default.
+        }
+      }
+
+      password ??= 'insecure-static-phrase';
+
+      if (isFirstLaunch) {
         await this._userAgent.initialize({ password });
       }
       await this._userAgent.start({ password });
@@ -303,11 +355,12 @@ export class AuthManager {
     try {
       const session = await restoreSession(
         {
-          userAgent       : this._userAgent,
-          emitter         : this._emitter,
-          storage         : this._storage,
-          defaultPassword : this._defaultPassword,
-          defaultSync     : this._defaultSync,
+          userAgent        : this._userAgent,
+          emitter          : this._emitter,
+          storage          : this._storage,
+          defaultPassword  : this._defaultPassword,
+          passwordProvider : this._passwordProvider,
+          defaultSync      : this._defaultSync,
         },
         options,
       );
@@ -322,6 +375,90 @@ export class AuthManager {
     }
   }
 
+  /**
+   * Lightweight vault unlock for one-shot utilities and subprocesses.
+   *
+   * Unlocks the vault and retrieves the active (or first available)
+   * identity **without** starting sync, DWN registration, or persisting
+   * session markers. This is the recommended replacement for calling
+   * `agent.start({ password })` directly.
+   *
+   * Typical use cases:
+   * - Git credential helpers that need to sign a token and exit
+   * - CLI utilities that perform a single operation
+   * - Any subprocess that shares a data directory with a long-running daemon
+   *
+   * @param options - Optional password override.
+   * @returns An active AuthSession (with sync disabled).
+   *
+   * @example
+   * ```ts
+   * const session = await auth.connectHeadless({ password });
+   * const did = session.did; // ready to use
+   * await auth.shutdown();   // clean exit
+   * ```
+   */
+  async connectHeadless(options?: HeadlessConnectOptions): Promise<AuthSession> {
+    let password = options?.password ?? this._defaultPassword;
+
+    // Try the password provider if no explicit password.
+    if (!password && this._passwordProvider) {
+      const isFirstLaunch = await this._userAgent.firstLaunch();
+      password = await this._passwordProvider.getPassword({
+        reason: isFirstLaunch ? 'create' : 'unlock',
+      });
+    }
+
+    if (!password) {
+      throw new Error(
+        '[@enbox/auth] connectHeadless() requires a password. ' +
+        'Provide one via options.password, a passwordProvider, or the AuthManager default.'
+      );
+    }
+
+    // Unlock the vault (initialise on first launch).
+    if (await this._userAgent.firstLaunch()) {
+      await this._userAgent.initialize({ password });
+    } else {
+      await this._userAgent.start({ password });
+    }
+    this._emitter.emit('vault-unlocked', {});
+
+    // Find the active identity.
+    const identities = await this._userAgent.identity.list();
+    if (identities.length === 0) {
+      throw new Error('[@enbox/auth] No identities found in vault.');
+    }
+
+    // Prefer the previously-active identity, fall back to first.
+    const savedDid = await this._storage.get(STORAGE_KEYS.ACTIVE_IDENTITY);
+    const identity = (savedDid
+      ? identities.find(id => id.did.uri === savedDid || id.metadata.connectedDid === savedDid)
+      : undefined
+    ) ?? identities[0];
+
+    const connectedDid = identity.metadata.connectedDid ?? identity.did.uri;
+    const delegateDid = identity.metadata.connectedDid ? identity.did.uri : undefined;
+
+    const identityInfo: IdentityInfo = {
+      didUri       : connectedDid,
+      name         : identity.metadata.name,
+      connectedDid : identity.metadata.connectedDid,
+    };
+
+    // No sync, no registration, no session persistence markers.
+    this._session = new AuthSession({
+      agent    : this._userAgent,
+      did      : connectedDid,
+      delegateDid,
+      identity : identityInfo,
+    });
+
+    this._setState('connected');
+
+    return this._session;
+  }
+
   // ─── Session management ────────────────────────────────────────
 
   /** The current active session, or `undefined` if not connected. */
@@ -422,6 +559,86 @@ export class AuthManager {
     }
   }
 
+  /**
+   * Gracefully shut down the auth manager, releasing all resources.
+   *
+   * This goes beyond {@link disconnect} or {@link lock}: it stops sync,
+   * clears the active session, locks the vault, and **closes** the
+   * underlying storage handles (e.g. LevelDB) so the process can exit
+   * without dangling timers or open file descriptors.
+   *
+   * After calling `shutdown()`, the `AuthManager` instance should not be
+   * reused — create a new one via {@link AuthManager.create} if needed.
+   *
+   * Idempotent: calling `shutdown()` more than once is safe.
+   *
+   * @param options - Optional shutdown configuration.
+   * @param options.timeout - Milliseconds to wait for sync to stop. Default: `2000`.
+   *
+   * @example
+   * ```ts
+   * const session = await auth.connectHeadless({ password });
+   * // ... perform work ...
+   * await auth.shutdown(); // clean exit, no process.exit() needed
+   * ```
+   */
+  async shutdown(options: ShutdownOptions = {}): Promise<void> {
+    if (this._isShutDown) {
+      return;
+    }
+
+    const { timeout = 2000 } = options;
+    const did = this._session?.did;
+
+    // 1. Stop sync.
+    if ('sync' in this._userAgent &&
+        typeof (this._userAgent as any).sync?.stopSync === 'function') {
+      try {
+        await (this._userAgent as any).sync.stopSync(timeout);
+      } catch {
+        // Best-effort — don't block shutdown on sync errors.
+      }
+    }
+
+    // 2. Clear the active session.
+    this._session = undefined;
+
+    // 3. Lock the vault (emits 'vault-locked').
+    try {
+      await this._vault.lock();
+    } catch {
+      // Vault may already be locked or uninitialised — safe to ignore.
+    }
+
+    // 4. Close the sync engine (releases LevelDB handles, timers).
+    if ('sync' in this._userAgent &&
+        typeof (this._userAgent as any).sync?.close === 'function') {
+      try {
+        await (this._userAgent as any).sync.close();
+      } catch {
+        // Best-effort.
+      }
+    }
+
+    // 5. Close the storage adapter (e.g. LevelDB session store).
+    if (typeof this._storage.close === 'function') {
+      try {
+        await this._storage.close();
+      } catch {
+        // Best-effort.
+      }
+    }
+
+    // 6. Mark as shut down and transition state.
+    this._isShutDown = true;
+    this._setState('locked');
+
+    // 7. Emit session-end if there was an active session.
+    if (did) {
+      this._emitter.emit('session-end', { did });
+    }
+  }
+
   // ─── Multi-identity ────────────────────────────────────────────
 
   /**
@@ -596,6 +813,17 @@ export class AuthManager {
     return this._userAgent;
   }
 
+  /**
+   * The local DWN server endpoint discovered during `create()`, if any.
+   *
+   * When set, the agent is operating in remote mode (no in-process DWN).
+   * This property is available immediately after `create()` returns,
+   * before any event listeners are attached.
+   */
+  get localDwnEndpoint(): string | undefined {
+    return this._localDwnEndpoint;
+  }
+
   // ─── Private helpers ───────────────────────────────────────────
 
   private _setState(state: AuthState): void {

package/src/flows/dwn-discovery.ts

@@ -7,32 +7,28 @@
  *
  * ## Discovery channels (browser, highest to lowest priority)
  *
- * 1. **URL fragment payload** — A `dwn://register` redirect just landed
+ * 1. **URL fragment payload** — A `dwn://connect` redirect just landed
  *    on the page with the endpoint in `#`. Highest priority because it's
  *    fresh and explicit.
  * 2. **Persisted endpoint** (localStorage) — A previously discovered
  *    endpoint restored and re-validated via `GET /info`.
- * 3. **Agent-level discovery** (transparent, runs on every `sendRequest`)
- *    — `~/.enbox/dwn.json` discovery file (Node/Bun only; skipped in
- *    browsers) and sequential port probing on `127.0.0.1:{3000,55500–55509}`.
- *    This channel works even if the browser-specific functions here
- *    return `false`.
  *
  * ## Discovery channels (CLI / native, all transparent)
  *
- * In Node/Bun environments, all discovery happens automatically inside
+ * In Node/Bun environments, the agent's `LocalDwnDiscovery` reads the
+ * `~/.enbox/dwn.json` discovery file automatically inside
  * `AgentDwnApi.getLocalDwnEndpoint()`. The browser-specific functions
  * in this module (`checkUrlForDwnDiscoveryPayload`, `requestLocalDwnDiscovery`)
- * are not needed — the agent reads `~/.enbox/dwn.json` and probes ports
- * on its own.
+ * are not needed in those environments.
  *
- * @see https://github.com/enboxorg/enbox/issues/589
+ * @see https://github.com/enboxorg/enbox/issues/677
  * @module
  */
 
 import type { EnboxUserAgent } from '@enbox/agent';
 
-import { buildDwnRegisterUrl, readDwnDiscoveryPayloadFromUrl } 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';
@@ -42,7 +38,7 @@ import type { StorageAdapter } from '../types.js';
  * Check the current page URL for a `DwnDiscoveryPayload` in the fragment.
  *
  * This is called once at the start of a connection flow to detect whether
- * the user was just redirected back from a `dwn://register` handler. If a
+ * the user was just redirected back from a `dwn://connect` handler. If a
  * valid payload is found, the endpoint is persisted and the fragment is
  * cleared to prevent double-reads.
  *
@@ -69,6 +65,83 @@ export function checkUrlForDwnDiscoveryPayload(): string | undefined {
   return payload.endpoint;
 }
 
+// ─── Standalone (pre-agent) discovery ───────────────────────────
+
+/**
+ * Validate a local DWN endpoint by calling `GET /info` and checking
+ * that the server identifies itself as `@enbox/dwn-server`.
+ *
+ * This function has **zero** agent or vault dependencies — it only uses
+ * the network. It is safe to call before the agent exists.
+ *
+ * @param endpoint - The candidate endpoint URL.
+ * @returns The normalised endpoint if valid, `undefined` otherwise.
+ */
+async function validateEndpointStandalone(endpoint: string): Promise<string | undefined> {
+  const normalized = normalizeBaseUrl(endpoint);
+  try {
+    const rpc = new EnboxRpcClient();
+    const serverInfo = await rpc.getServerInfo(normalized);
+    if (serverInfo.server === localDwnServerName) {
+      return normalized;
+    }
+  } catch {
+    // Server not reachable or not ours.
+  }
+  return undefined;
+}
+
+/**
+ * Run local DWN discovery **before the agent exists**.
+ *
+ * This is the standalone counterpart of {@link applyLocalDwnDiscovery} and
+ * is designed to be called in `AuthManager.create()`, before
+ * `EnboxUserAgent.create()`, so the agent creation can decide whether to
+ * spin up an in-process DWN or operate in remote mode.
+ *
+ * Discovery channels (highest → lowest priority):
+ * 1. **URL fragment payload** — A `dwn://connect` redirect just landed.
+ * 2. **Persisted endpoint** (localStorage) — A previously discovered
+ *    endpoint, re-validated via `GET /info`.
+ *
+ * When a valid endpoint is found it is persisted to storage. When a
+ * previously-persisted endpoint is stale, it is removed.
+ *
+ * @param storage - The auth storage adapter (for reading/writing the
+ *   cached endpoint).
+ * @returns The validated endpoint URL, or `undefined` if no local DWN
+ *   server is available.
+ */
+export async function discoverLocalDwn(
+  storage: StorageAdapter,
+): Promise<string | undefined> {
+  // Channel 1: Fresh redirect payload in the URL fragment.
+  const freshEndpoint = checkUrlForDwnDiscoveryPayload();
+  if (freshEndpoint) {
+    const validated = await validateEndpointStandalone(freshEndpoint);
+    if (validated) {
+      await persistLocalDwnEndpoint(storage, validated);
+      return validated;
+    }
+    // Payload was in the URL but the server is unreachable — fall through.
+  }
+
+  // Channel 2: Persisted endpoint from a previous session.
+  const cached = await storage.get(STORAGE_KEYS.LOCAL_DWN_ENDPOINT);
+  if (cached) {
+    const validated = await validateEndpointStandalone(cached);
+    if (validated) {
+      return validated;
+    }
+    // Stale — server no longer running.
+    await clearLocalDwnEndpoint(storage);
+  }
+
+  return undefined;
+}
+
+// ─── Storage helpers ────────────────────────────────────────────
+
 /**
  * Persist a discovered local DWN endpoint in auth storage.
  *
@@ -130,25 +203,18 @@ export async function restoreLocalDwnEndpoint(
  * Run the full local DWN discovery sequence for a browser connection flow.
  *
  * This function handles the **receiving** side of local DWN discovery in
- * the browser. It does NOT trigger the `dwn://register` redirect — use
+ * the browser. It does NOT trigger the `dwn://connect` redirect — use
  * {@link requestLocalDwnDiscovery} for that.
  *
  * The discovery channels, from highest to lowest priority:
  *
- * 1. **URL fragment payload** — A `dwn://register` redirect just landed on
+ * 1. **URL fragment payload** — A `dwn://connect` redirect just landed on
  *    this page with the DWN endpoint in `#`. This is the highest-priority
  *    signal because it's fresh and explicit.
  *
  * 2. **Persisted endpoint** (localStorage) — A previously discovered
  *    endpoint is restored and re-validated via `GET /info`.
  *
- * 3. **Agent-level discovery** (transparent) — Even if this function
- *    returns `false`, the agent's `LocalDwnDiscovery` will independently
- *    try the discovery file (`~/.enbox/dwn.json`) and port probing on
- *    every `sendRequest()` call. Those channels are not available in
- *    browsers (no filesystem access, CORS may block probes), but they
- *    work transparently in Node/Bun CLI environments.
- *
  * When an `emitter` is provided, this function emits:
  * - `'local-dwn-available'` with the endpoint when discovery succeeds.
  * - `'local-dwn-unavailable'` when no local DWN could be reached.
@@ -191,37 +257,31 @@ export async function applyLocalDwnDiscovery(
   return restored;
 }
 
-// ─── dwn://register trigger ─────────────────────────────────────
+// ─── dwn://connect trigger ──────────────────────────────────────
 
 /**
- * Initiate the `dwn://register` flow by opening the register URL.
+ * Initiate the `dwn://connect` flow by opening the connect URL.
  *
- * This asks the operating system to route `dwn://register?callback=<url>`
+ * This asks the operating system to route `dwn://connect?callback=<url>`
  * to the registered handler (electrobun-dwn), which will redirect the
  * user's browser back to `callbackUrl` with the local DWN endpoint
  * encoded in the URL fragment.
  *
- * **Important:** There is no reliable cross-browser API to detect whether
- * a `dwn://` handler is installed. If no handler is registered, this call
- * will silently fail or show an OS-level error dialog. Use
- * {@link probeLocalDwn} first to check if a local DWN is already
- * reachable via port probing — if it is, you can skip the register flow
- * entirely and call {@link applyLocalDwnDiscovery} instead.
+ * **Note:** There is no reliable cross-browser API to detect whether a
+ * `dwn://` handler is installed. If no handler is registered, this call
+ * will silently fail or show an OS-level error dialog.
  *
  * @param callbackUrl - The URL to redirect back to. Defaults to the
  *   current page URL (without its fragment) if running in a browser.
- * @returns `true` if the register URL was opened, `false` if no
+ * @returns `true` if the connect URL was opened, `false` if no
  *   callback URL could be determined (e.g. no `globalThis.location`).
  *
  * @example
  * ```ts
- * // Check if local DWN is already available via direct probe.
- * const alreadyAvailable = await probeLocalDwn();
- * if (!alreadyAvailable) {
- *   // No local DWN found — trigger the dwn://register flow.
- *   requestLocalDwnDiscovery();
- *   // The page will reload with the endpoint in the URL fragment.
- * }
+ * // Trigger the dwn://connect flow to discover a local DWN.
+ * requestLocalDwnDiscovery();
+ * // The page will reload with the endpoint in the URL fragment.
+ * // On the next connect/restore, applyLocalDwnDiscovery() reads it.
  * ```
  */
 export function requestLocalDwnDiscovery(callbackUrl?: string): boolean {
@@ -230,7 +290,7 @@ export function requestLocalDwnDiscovery(callbackUrl?: string): boolean {
     return false;
   }
 
-  const registerUrl = buildDwnRegisterUrl(resolvedCallback);
+  const registerUrl = buildDwnConnectUrl(resolvedCallback);
 
   // Open the dwn:// URL. Use window.open() rather than location.href
   // assignment to avoid navigating away from the current page if the
@@ -249,46 +309,6 @@ export function requestLocalDwnDiscovery(callbackUrl?: string): boolean {
   return false;
 }
 
-/**
- * Probe whether a local DWN server is reachable via direct HTTP fetch.
- *
- * Attempts `GET http://127.0.0.1:{port}/info` on the well-known port
- * candidates and returns the endpoint URL of the first server that
- * responds with a valid `@enbox/dwn-server` identity.
- *
- * This is useful in browsers to check if a local DWN is available
- * *before* triggering the `dwn://register` redirect flow — if the
- * server is already reachable (CORS permitting), the redirect is
- * unnecessary.
- *
- * @returns The local DWN endpoint URL, or `undefined` if no server
- *   was found. Returns `undefined` (rather than throwing) on CORS
- *   errors or network failures.
- */
-export async function probeLocalDwn(): Promise<string | undefined> {
-  // Import port candidates from @enbox/agent. Using a dynamic import
-  // here keeps the function self-contained and avoids circular deps.
-  const { localDwnPortCandidates, localDwnHostCandidates } = await import('@enbox/agent');
-
-  for (const port of localDwnPortCandidates) {
-    for (const host of localDwnHostCandidates) {
-      const endpoint = `http://${host}:${port}`;
-      try {
-        const response = await fetch(`${endpoint}/info`, { signal: AbortSignal.timeout(2_000) });
-        if (!response.ok) { continue; }
-
-        const serverInfo = await response.json() as { server?: string };
-        if (serverInfo?.server === '@enbox/dwn-server') {
-          return endpoint;
-        }
-      } catch {
-        // Network error, CORS block, or timeout — try next candidate.
-      }
-    }
-  }
-  return undefined;
-}
-
 // ─── Internal helpers ───────────────────────────────────────────
 
 /** Return the current page URL without the fragment, or `undefined`. */