@enbox/auth 0.3.1 → 0.5.0

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`. */

package/src/flows/dwn-registration.ts

@@ -15,9 +15,12 @@ import type { EnboxUserAgent } from '@enbox/agent';
 
 import { DwnRegistrar } from '@enbox/dwn-clients';
 
+import { STORAGE_KEYS } from '../types.js';
+
 import type {
   RegistrationOptions,
   RegistrationTokenData,
+  StorageAdapter,
 } from '../types.js';
 
 /** @internal */
@@ -33,6 +36,12 @@ export interface RegistrationContext {
 
   /** The connected DID URI (the identity's DID). */
   connectedDid: string;
+
+  /**
+   * Storage adapter for automatic token persistence.
+   * Only used when `registration.persistTokens` is `true`.
+   */
+  storage?: StorageAdapter;
 }
 
 /**
@@ -51,11 +60,19 @@ export async function registerWithDwnEndpoints(
   ctx: RegistrationContext,
   registration: RegistrationOptions,
 ): Promise<void> {
-  const { userAgent, dwnEndpoints, agentDid, connectedDid } = ctx;
+  const { userAgent, dwnEndpoints, agentDid, connectedDid, storage } = ctx;
+
+  // Load initial tokens: when persistTokens is enabled, load from storage
+  // (ignoring any explicit registrationTokens). Otherwise use the explicit map.
+  let seedTokens: Record<string, RegistrationTokenData> = {};
 
-  const updatedTokens: Record<string, RegistrationTokenData> = {
-    ...(registration.registrationTokens ?? {}),
-  };
+  if (registration.persistTokens && storage) {
+    seedTokens = await loadTokensFromStorage(storage);
+  } else {
+    seedTokens = registration.registrationTokens ?? {};
+  }
+
+  const updatedTokens: Record<string, RegistrationTokenData> = { ...seedTokens };
 
   try {
     for (const dwnEndpoint of dwnEndpoints) {
@@ -145,7 +162,12 @@ export async function registerWithDwnEndpoints(
       }
     }
 
-    // Notify app of updated tokens for persistence.
+    // Persist tokens to storage when auto-persistence is enabled.
+    if (registration.persistTokens && storage) {
+      await saveTokensToStorage(storage, updatedTokens);
+    }
+
+    // Notify app of updated tokens (always, even when auto-persisting).
     if (registration.onRegistrationTokens) {
       registration.onRegistrationTokens(updatedTokens);
     }
@@ -155,3 +177,36 @@ export async function registerWithDwnEndpoints(
     registration.onFailure(error);
   }
 }
+
+// ─── Storage helpers ──────────────────────────────────────────────
+
+/**
+ * Load registration tokens from a `StorageAdapter`.
+ *
+ * Returns an empty record if no tokens are stored or the stored value
+ * is corrupt (best-effort — never throws).
+ *
+ * @internal
+ */
+export async function loadTokensFromStorage(
+  storage: StorageAdapter,
+): Promise<Record<string, RegistrationTokenData>> {
+  try {
+    const raw = await storage.get(STORAGE_KEYS.REGISTRATION_TOKENS);
+    if (!raw) { return {}; }
+    return JSON.parse(raw) as Record<string, RegistrationTokenData>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save registration tokens to a `StorageAdapter`.
+ * @internal
+ */
+export async function saveTokensToStorage(
+  storage: StorageAdapter,
+  tokens: Record<string, RegistrationTokenData>,
+): Promise<void> {
+  await storage.set(STORAGE_KEYS.REGISTRATION_TOKENS, JSON.stringify(tokens));
+}

package/src/flows/import-identity.ts

@@ -105,6 +105,7 @@ export async function importFromPhrase(
         dwnEndpoints,
         agentDid  : userAgent.agentDid.uri,
         connectedDid,
+        storage   : storage,
       },
       ctx.registration,
     );
@@ -174,6 +175,7 @@ export async function importFromPortable(
         dwnEndpoints,
         agentDid  : userAgent.agentDid.uri,
         connectedDid,
+        storage   : storage,
       },
       ctx.registration,
     );

package/src/flows/local-connect.ts

@@ -9,6 +9,7 @@
 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';
@@ -22,6 +23,7 @@ export interface LocalConnectContext {
   emitter: AuthEventEmitter;
   storage: StorageAdapter;
   defaultPassword?: string;
+  passwordProvider?: PasswordProvider;
   defaultSync?: SyncOption;
   defaultDwnEndpoints?: string[];
   registration?: RegistrationOptions;
@@ -39,7 +41,22 @@ export async function localConnect(
 ): Promise<AuthSession> {
   const { userAgent, emitter, storage } = ctx;
 
-  const password = options.password ?? ctx.defaultPassword ?? INSECURE_DEFAULT_PASSWORD;
+  // 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'];
 
@@ -55,7 +72,7 @@ export async function localConnect(
   let recoveryPhrase: string | undefined;
 
   // Initialize vault on first launch.
-  if (await userAgent.firstLaunch()) {
+  if (isFirstLaunch) {
     recoveryPhrase = await userAgent.initialize({
       password,
       recoveryPhrase: options.recoveryPhrase,
@@ -68,7 +85,10 @@ export async function localConnect(
   emitter.emit('vault-unlocked', {});
 
   // Apply local DWN discovery (browser redirect payload or persisted endpoint).
-  await applyLocalDwnDiscovery(userAgent, storage, emitter);
+  // 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();
@@ -117,6 +137,7 @@ export async function localConnect(
         dwnEndpoints,
         agentDid  : userAgent.agentDid.uri,
         connectedDid,
+        storage   : storage,
       },
       ctx.registration,
     );

package/src/flows/session-restore.ts

@@ -9,6 +9,7 @@
 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';
@@ -21,6 +22,7 @@ export interface SessionRestoreContext {
   emitter: AuthEventEmitter;
   storage: StorageAdapter;
   defaultPassword?: string;
+  passwordProvider?: PasswordProvider;
   defaultSync?: SyncOption;
 }
 
@@ -42,7 +44,22 @@ export async function restoreSession(
     return undefined;
   }
 
-  const password = options.password ?? ctx.defaultPassword ?? INSECURE_DEFAULT_PASSWORD;
+  // 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) {
@@ -64,7 +81,10 @@ export async function restoreSession(
   emitter.emit('vault-unlocked', {});
 
   // Apply local DWN discovery (browser redirect payload or persisted endpoint).
-  await applyLocalDwnDiscovery(userAgent, storage, emitter);
+  // 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);

package/src/flows/wallet-connect.ts

@@ -1,7 +1,7 @@
 /**
- * Wallet connect (OIDC/QR) flow.
+ * Wallet connect (Enbox Connect relay) flow.
  *
- * Connects to an external wallet via the WalletConnect relay protocol,
+ * 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
@@ -99,12 +99,12 @@ export async function walletConnect(
     );
   }
 
-  // Run the full OIDC wallet connect flow.
+  // 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 ?? 'web5://connect',
+    walletUri          : options.walletUri ?? 'enbox://connect',
     permissionRequests : options.permissionRequests,
     onWalletUriReady   : options.onWalletUriReady,
     validatePin        : options.validatePin,
@@ -147,6 +147,7 @@ export async function walletConnect(
           dwnEndpoints,
           agentDid  : userAgent.agentDid.uri,
           connectedDid,
+          storage   : storage,
         },
         ctx.registration,
       );

package/src/index.ts

@@ -40,6 +40,10 @@ export { AuthSession } from './identity-session.js';
 export { VaultManager } from './vault/vault-manager.js';
 export { AuthEventEmitter } from './events.js';
 
+// Password providers
+export { PasswordProvider } from './password-provider.js';
+export type { PasswordContext } from './password-provider.js';
+
 // Re-export agent classes so consumers can construct custom agents/vaults
 // without a direct @enbox/agent dependency.
 export { EnboxUserAgent, HdIdentityVault } from '@enbox/agent';
@@ -47,13 +51,16 @@ export { EnboxUserAgent, HdIdentityVault } from '@enbox/agent';
 // Wallet-connect helpers
 export { processConnectedGrants } from './flows/wallet-connect.js';
 
+// Registration token storage helpers
+export { loadTokensFromStorage, saveTokensToStorage } from './flows/dwn-registration.js';
+
 // Local DWN discovery (browser dwn:// protocol integration)
 export {
   applyLocalDwnDiscovery,
   checkUrlForDwnDiscoveryPayload,
   clearLocalDwnEndpoint,
+  discoverLocalDwn,
   persistLocalDwnEndpoint,
-  probeLocalDwn,
   requestLocalDwnDiscovery,
   restoreLocalDwnEndpoint,
 } from './flows/dwn-discovery.js';
@@ -71,6 +78,7 @@ export type {
   AuthState,
   ConnectPermissionRequest,
   DisconnectOptions,
+  HeadlessConnectOptions,
   IdentityInfo,
   IdentityVaultBackup,
   ImportFromPhraseOptions,
@@ -83,6 +91,7 @@ export type {
   RegistrationOptions,
   RegistrationTokenData,
   RestoreSessionOptions,
+  ShutdownOptions,
   StorageAdapter,
   SyncOption,
   WalletConnectOptions,