@enbox/auth 0.3.1

package/src/flows/dwn-discovery.ts

@@ -0,0 +1,300 @@
+/**
+ * Local DWN discovery integration for browser and CLI environments.
+ *
+ * This module bridges the local DWN discovery mechanisms (implemented in
+ * `@enbox/agent`) with the `@enbox/auth` storage, session lifecycle, and
+ * event system.
+ *
+ * ## Discovery channels (browser, highest to lowest priority)
+ *
+ * 1. **URL fragment payload** — A `dwn://register` 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
+ * `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.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/589
+ * @module
+ */
+
+import type { EnboxUserAgent } from '@enbox/agent';
+
+import { buildDwnRegisterUrl, readDwnDiscoveryPayloadFromUrl } from '@enbox/agent';
+
+import type { AuthEventEmitter } from '../events.js';
+import { STORAGE_KEYS } from '../types.js';
+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
+ * valid payload is found, the endpoint is persisted and the fragment is
+ * cleared to prevent double-reads.
+ *
+ * @returns The discovered endpoint string, or `undefined` if no payload
+ *   was found in the URL.
+ */
+export function checkUrlForDwnDiscoveryPayload(): string | undefined {
+  if (typeof globalThis.location === 'undefined') {
+    return undefined;
+  }
+
+  const payload = readDwnDiscoveryPayloadFromUrl(globalThis.location.href);
+  if (!payload) {
+    return undefined;
+  }
+
+  // Clear the fragment to prevent re-reading on subsequent calls or
+  // if the user refreshes the page after the redirect.
+  if (typeof globalThis.history !== 'undefined' && globalThis.history.replaceState) {
+    const cleanUrl = globalThis.location.href.split('#')[0];
+    globalThis.history.replaceState(null, '', cleanUrl);
+  }
+
+  return payload.endpoint;
+}
+
+/**
+ * Persist a discovered local DWN endpoint in auth storage.
+ *
+ * @param storage - The auth storage adapter.
+ * @param endpoint - The local DWN server base URL.
+ */
+export async function persistLocalDwnEndpoint(
+  storage: StorageAdapter,
+  endpoint: string,
+): Promise<void> {
+  await storage.set(STORAGE_KEYS.LOCAL_DWN_ENDPOINT, endpoint);
+}
+
+/**
+ * Clear the persisted local DWN endpoint from auth storage.
+ *
+ * Call this when the cached endpoint is found to be stale (server no
+ * longer running).
+ *
+ * @param storage - The auth storage adapter.
+ */
+export async function clearLocalDwnEndpoint(
+  storage: StorageAdapter,
+): Promise<void> {
+  await storage.remove(STORAGE_KEYS.LOCAL_DWN_ENDPOINT);
+}
+
+/**
+ * Restore a previously persisted local DWN endpoint and inject it into the
+ * agent's discovery cache.
+ *
+ * The endpoint is validated by the agent (via `GET /info`) before being
+ * accepted. If validation fails, the stale entry is removed from storage.
+ *
+ * @param agent - The running EnboxUserAgent.
+ * @param storage - The auth storage adapter.
+ * @returns `true` if an endpoint was restored and validated, `false` otherwise.
+ */
+export async function restoreLocalDwnEndpoint(
+  agent: EnboxUserAgent,
+  storage: StorageAdapter,
+): Promise<boolean> {
+  const endpoint = await storage.get(STORAGE_KEYS.LOCAL_DWN_ENDPOINT);
+  if (!endpoint) {
+    return false;
+  }
+
+  const accepted = await agent.dwn.setCachedLocalDwnEndpoint(endpoint);
+  if (!accepted) {
+    // The server is no longer running — remove the stale entry.
+    await clearLocalDwnEndpoint(storage);
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * 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
+ * {@link requestLocalDwnDiscovery} for that.
+ *
+ * The discovery channels, from highest to lowest priority:
+ *
+ * 1. **URL fragment payload** — A `dwn://register` 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.
+ *
+ * @param agent - The running EnboxUserAgent.
+ * @param storage - The auth storage adapter.
+ * @param emitter - Optional event emitter for local DWN status notifications.
+ * @returns `true` if a local DWN endpoint was discovered and injected.
+ */
+export async function applyLocalDwnDiscovery(
+  agent: EnboxUserAgent,
+  storage: StorageAdapter,
+  emitter?: AuthEventEmitter,
+): Promise<boolean> {
+  // Step 1: Check for a fresh payload in the URL fragment (redirect just happened).
+  const freshEndpoint = checkUrlForDwnDiscoveryPayload();
+
+  if (freshEndpoint) {
+    const accepted = await agent.dwn.setCachedLocalDwnEndpoint(freshEndpoint);
+    if (accepted) {
+      await persistLocalDwnEndpoint(storage, freshEndpoint);
+      emitter?.emit('local-dwn-available', { endpoint: freshEndpoint });
+      return true;
+    }
+    // Payload was in the URL but the server is not reachable — fall through.
+  }
+
+  // Step 2: Try restoring from storage.
+  const restored = await restoreLocalDwnEndpoint(agent, storage);
+
+  if (restored) {
+    const endpoint = await storage.get(STORAGE_KEYS.LOCAL_DWN_ENDPOINT);
+    if (endpoint) {
+      emitter?.emit('local-dwn-available', { endpoint });
+    }
+  } else {
+    emitter?.emit('local-dwn-unavailable', {});
+  }
+
+  return restored;
+}
+
+// ─── dwn://register trigger ─────────────────────────────────────
+
+/**
+ * Initiate the `dwn://register` flow by opening the register URL.
+ *
+ * This asks the operating system to route `dwn://register?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.
+ *
+ * @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
+ *   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.
+ * }
+ * ```
+ */
+export function requestLocalDwnDiscovery(callbackUrl?: string): boolean {
+  const resolvedCallback = callbackUrl ?? currentPageUrl();
+  if (!resolvedCallback) {
+    return false;
+  }
+
+  const registerUrl = buildDwnRegisterUrl(resolvedCallback);
+
+  // Open the dwn:// URL. Use window.open() rather than location.href
+  // assignment to avoid navigating away from the current page if the
+  // OS handler isn't installed.
+  if (typeof globalThis.open === 'function') {
+    globalThis.open(registerUrl);
+    return true;
+  }
+
+  // Fallback for environments with location but no window.open.
+  if (typeof globalThis.location !== 'undefined') {
+    globalThis.location.href = registerUrl;
+    return true;
+  }
+
+  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`. */
+function currentPageUrl(): string | undefined {
+  if (typeof globalThis.location === 'undefined') {
+    return undefined;
+  }
+  return globalThis.location.href.split('#')[0];
+}

package/src/flows/dwn-registration.ts

@@ -0,0 +1,157 @@
+/**
+ * DWN registration flow.
+ *
+ * Registers the agent DID and connected DID with DWN endpoints.
+ * Supports two registration paths:
+ * 1. Provider auth (`provider-auth-v0`) — OAuth-style with tokens
+ * 2. Proof of Work (default) — PoW challenge-response
+ *
+ * This matches the registration logic from `Enbox.connect()` but as a
+ * standalone, reusable function.
+ * @module
+ */
+
+import type { EnboxUserAgent } from '@enbox/agent';
+
+import { DwnRegistrar } from '@enbox/dwn-clients';
+
+import type {
+  RegistrationOptions,
+  RegistrationTokenData,
+} from '../types.js';
+
+/** @internal */
+export interface RegistrationContext {
+  /** The user agent with RPC access for getServerInfo(). */
+  userAgent: EnboxUserAgent;
+
+  /** DWN endpoints to register with. */
+  dwnEndpoints: string[];
+
+  /** The agent DID URI. */
+  agentDid: string;
+
+  /** The connected DID URI (the identity's DID). */
+  connectedDid: string;
+}
+
+/**
+ * Register the agent and connected DIDs with the configured DWN endpoints.
+ *
+ * For each endpoint:
+ * 1. Fetches server info to check registration requirements.
+ * 2. If the server requires `provider-auth-v0` and the app provides
+ *    `onProviderAuthRequired`, runs the OAuth flow (with token refresh).
+ * 3. Otherwise falls back to PoW registration.
+ * 4. Calls `onSuccess` when all endpoints succeed, `onFailure` on error.
+ *
+ * @internal
+ */
+export async function registerWithDwnEndpoints(
+  ctx: RegistrationContext,
+  registration: RegistrationOptions,
+): Promise<void> {
+  const { userAgent, dwnEndpoints, agentDid, connectedDid } = ctx;
+
+  const updatedTokens: Record<string, RegistrationTokenData> = {
+    ...(registration.registrationTokens ?? {}),
+  };
+
+  try {
+    for (const dwnEndpoint of dwnEndpoints) {
+      const serverInfo = await userAgent.rpc.getServerInfo(dwnEndpoint);
+
+      if (serverInfo.registrationRequirements.length === 0) {
+        continue;
+      }
+
+      // Deduplicate DIDs to register.
+      const didsToRegister = [agentDid, connectedDid]
+        .filter((did, i, arr): did is string => arr.indexOf(did) === i);
+
+      const hasProviderAuth =
+        serverInfo.registrationRequirements.includes('provider-auth-v0')
+        && serverInfo.providerAuth !== undefined;
+
+      if (hasProviderAuth && registration.onProviderAuthRequired) {
+        // --- Provider Auth Path ---
+        let tokenData = updatedTokens[dwnEndpoint] as RegistrationTokenData | undefined;
+
+        // Refresh expired tokens.
+        if (tokenData?.expiresAt !== undefined && tokenData.expiresAt < Date.now()) {
+          if (tokenData.refreshUrl && tokenData.refreshToken) {
+            const refreshed = await DwnRegistrar.refreshRegistrationToken(
+              tokenData.refreshUrl, tokenData.refreshToken,
+            );
+            tokenData = {
+              registrationToken : refreshed.registrationToken,
+              refreshToken      : refreshed.refreshToken,
+              expiresAt         : refreshed.expiresIn !== undefined
+                ? Date.now() + (refreshed.expiresIn * 1000) : undefined,
+              tokenUrl   : tokenData.tokenUrl,
+              refreshUrl : tokenData.refreshUrl,
+            };
+            updatedTokens[dwnEndpoint] = tokenData;
+          } else {
+            tokenData = undefined;
+          }
+        }
+
+        // Run the auth flow if no valid token exists.
+        if (tokenData === undefined) {
+          const state = crypto.randomUUID();
+          const providerAuth = serverInfo.providerAuth!;
+          const separator = providerAuth.authorizeUrl.includes('?') ? '&' : '?';
+          const authorizeUrl = `${providerAuth.authorizeUrl}${separator}`
+            + `redirect_uri=${encodeURIComponent(dwnEndpoint)}`
+            + `&state=${encodeURIComponent(state)}`;
+
+          const authResult = await registration.onProviderAuthRequired({
+            authorizeUrl,
+            dwnEndpoint,
+            state,
+          });
+
+          if (authResult.state !== state) {
+            throw new Error('Provider auth state mismatch \u2014 possible CSRF attack.');
+          }
+
+          const tokenResponse = await DwnRegistrar.exchangeAuthCode(
+            providerAuth.tokenUrl, authResult.code, dwnEndpoint,
+          );
+
+          tokenData = {
+            registrationToken : tokenResponse.registrationToken,
+            refreshToken      : tokenResponse.refreshToken,
+            expiresAt         : tokenResponse.expiresIn !== undefined
+              ? Date.now() + (tokenResponse.expiresIn * 1000) : undefined,
+            tokenUrl   : providerAuth.tokenUrl,
+            refreshUrl : providerAuth.refreshUrl,
+          };
+          updatedTokens[dwnEndpoint] = tokenData;
+        }
+
+        // Register each DID using the provider auth token.
+        for (const did of didsToRegister) {
+          await DwnRegistrar.registerTenantWithToken(
+            dwnEndpoint, did, tokenData.registrationToken,
+          );
+        }
+      } else {
+        // --- Default Path (PoW / general registration) ---
+        for (const did of didsToRegister) {
+          await DwnRegistrar.registerTenant(dwnEndpoint, did);
+        }
+      }
+    }
+
+    // Notify app of updated tokens for persistence.
+    if (registration.onRegistrationTokens) {
+      registration.onRegistrationTokens(updatedTokens);
+    }
+
+    registration.onSuccess();
+  } catch (error: unknown) {
+    registration.onFailure(error);
+  }
+}

package/src/flows/import-identity.ts

@@ -0,0 +1,217 @@
+/**
+ * Identity import flows.
+ *
+ * - Import from BIP-39 recovery phrase (re-derive vault + identity).
+ * - Import from PortableIdentity JSON.
+ * @module
+ */
+
+import type { EnboxUserAgent } 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 {
+  ImportFromPhraseOptions,
+  ImportFromPortableOptions,
+  RegistrationOptions,
+  StorageAdapter,
+  SyncOption,
+} from '../types.js';
+
+/** @internal */
+export interface ImportContext {
+  userAgent: EnboxUserAgent;
+  emitter: AuthEventEmitter;
+  storage: StorageAdapter;
+  defaultSync?: SyncOption;
+  defaultDwnEndpoints?: string[];
+  registration?: RegistrationOptions;
+}
+
+/**
+ * Import (or recover) an identity from a BIP-39 recovery phrase.
+ *
+ * This re-initializes the vault with the given phrase and password,
+ * recovering the agent DID and all derived keys.
+ */
+export async function importFromPhrase(
+  ctx: ImportContext,
+  options: ImportFromPhraseOptions,
+): Promise<AuthSession> {
+  const { userAgent, emitter, storage } = ctx;
+  const { recoveryPhrase, password } = options;
+  const sync = options.sync ?? ctx.defaultSync;
+  const dwnEndpoints = options.dwnEndpoints ?? ctx.defaultDwnEndpoints ?? ['https://enbox-dwn.fly.dev'];
+
+  // Initialize the vault with the recovery phrase.
+  // This re-derives the same agent DID and CEK from the mnemonic.
+  if (await userAgent.firstLaunch()) {
+    await userAgent.initialize({
+      password,
+      recoveryPhrase,
+      dwnEndpoints,
+    });
+  }
+
+  await userAgent.start({ password });
+  emitter.emit('vault-unlocked', {});
+
+  // The recovery phrase re-derives the same agent DID,
+  // but the user identity might not exist yet — create one if needed.
+  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: '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.did.uri;
+
+  // 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 and start sync.
+  if (isNewIdentity && sync !== 'off') {
+    await userAgent.sync.registerIdentity({ did: connectedDid, options: { protocols: [] } });
+  }
+
+  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));
+  }
+
+  await storage.set(STORAGE_KEYS.PREVIOUSLY_CONNECTED, 'true');
+  await storage.set(STORAGE_KEYS.ACTIVE_IDENTITY, connectedDid);
+
+  const identityInfo = {
+    didUri : connectedDid,
+    name   : identity.metadata.name,
+  };
+
+  const session = new AuthSession({
+    agent    : userAgent,
+    did      : connectedDid,
+    identity : identityInfo,
+  });
+
+  emitter.emit('identity-added', { identity: identityInfo });
+  emitter.emit('session-start', {
+    session: { did: connectedDid, identity: identityInfo },
+  });
+
+  return session;
+}
+
+/**
+ * Import an identity from a PortableIdentity JSON object.
+ *
+ * The portable identity contains the DID's private keys and metadata,
+ * allowing it to be used on this device.
+ */
+export async function importFromPortable(
+  ctx: ImportContext,
+  options: ImportFromPortableOptions,
+): Promise<AuthSession> {
+  const { userAgent, emitter, storage } = ctx;
+  const sync = options.sync ?? ctx.defaultSync;
+
+  const identity = await userAgent.identity.import({
+    portableIdentity: options.portableIdentity,
+  });
+
+  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).
+  // For portable imports, extract endpoints from the DID document's DWN service.
+  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 and start sync.
+  if (sync !== 'off') {
+    await userAgent.sync.registerIdentity({
+      did     : connectedDid,
+      options : { delegateDid, protocols: [] },
+    });
+
+    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));
+  }
+
+  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,
+    identity : identityInfo,
+  });
+
+  emitter.emit('identity-added', { identity: identityInfo });
+  emitter.emit('session-start', {
+    session: { did: connectedDid, delegateDid, identity: identityInfo },
+  });
+
+  return session;
+}