@enbox/auth 0.4.0 → 0.5.0

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,13 +44,21 @@ export async function restoreSession(
     return undefined;
   }
 
-  // Resolve password: explicit option → callback → manager default → insecure fallback.
+  // 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.
@@ -71,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,

package/src/password-provider.ts

@@ -0,0 +1,383 @@
+/**
+ * PasswordProvider — composable password acquisition strategies.
+ *
+ * Replaces ad-hoc password prompting scattered across CLI consumers
+ * (env vars, raw-mode TTY, `/dev/tty` + `stty`, `@clack/prompts`, etc.)
+ * with a single, composable abstraction.
+ *
+ * @example Chained provider (env first, fall back to TTY)
+ * ```ts
+ * import { PasswordProvider } from '@enbox/auth';
+ *
+ * const provider = PasswordProvider.chain([
+ *   PasswordProvider.fromEnv('ENBOX_PASSWORD'),
+ *   PasswordProvider.fromTty({ prompt: 'Vault password: ' }),
+ * ]);
+ *
+ * const auth = await AuthManager.create({ passwordProvider: provider });
+ * ```
+ *
+ * @module
+ */
+
+// ─── Types ───────────────────────────────────────────────────────
+
+/** Context passed to a password provider explaining why a password is needed. */
+export interface PasswordContext {
+  /**
+   * Why the password is being requested.
+   *
+   * - `'create'` — first launch, creating a new vault (prompt may ask
+   *   for confirmation).
+   * - `'unlock'` — unlocking an existing vault.
+   */
+  reason: 'create' | 'unlock';
+}
+
+/**
+ * A strategy for obtaining a vault password.
+ *
+ * Implementations may be interactive (TTY prompts) or non-interactive
+ * (environment variables, cached values). Use {@link PasswordProvider.chain}
+ * to compose multiple strategies with automatic fallback.
+ */
+export interface PasswordProvider {
+  /**
+   * Obtain a password.
+   *
+   * @param context - Why the password is needed.
+   * @returns The password string.
+   * @throws If the provider cannot obtain a password (e.g. env var
+   *   not set, no TTY available). The error is caught by `chain()`
+   *   which falls through to the next provider.
+   */
+  getPassword(context: PasswordContext): Promise<string>;
+}
+
+// ─── Internal I/O interfaces (for testing) ───────────────────────
+
+/** @internal Minimal interface for an stdin-like readable stream. */
+export interface TtyReadable {
+  isTTY?: boolean;
+  setRawMode(mode: boolean): void;
+  setEncoding(encoding: string): void;
+  resume(): void;
+  pause(): void;
+  on(event: 'data', listener: (chunk: string) => void): void;
+  removeListener(event: 'data', listener: (chunk: string) => void): void;
+}
+
+/** @internal Minimal interface for an stdout-like writable stream. */
+export interface TtyWritable {
+  write(data: string): boolean;
+}
+
+// ─── Internal helpers ────────────────────────────────────────────
+
+/**
+ * Read a password from a raw-mode TTY stream.
+ *
+ * Reads character-by-character with no echo. Handles Enter (resolve),
+ * Ctrl-C (reject), backspace, and printable characters.
+ *
+ * @internal Exported for testing only.
+ */
+export function readPasswordRawMode(
+  stdin: TtyReadable,
+  stdout: TtyWritable,
+  prompt: string,
+): Promise<string> {
+  stdout.write(prompt);
+
+  return new Promise<string>((resolve, reject) => {
+    let buf = '';
+    stdin.setRawMode(true);
+    stdin.setEncoding('utf8');
+    stdin.resume();
+
+    const onData = (ch: string): void => {
+      const code = ch.charCodeAt(0);
+
+      if (ch === '\r' || ch === '\n') {
+        // Enter — done.
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdin.removeListener('data', onData);
+        stdout.write('\n');
+        resolve(buf);
+      } else if (code === 3) {
+        // Ctrl-C — abort.
+        stdin.setRawMode(false);
+        stdin.pause();
+        stdin.removeListener('data', onData);
+        stdout.write('\n');
+        reject(new Error('[@enbox/auth] PasswordProvider.fromTty: cancelled by user.'));
+      } else if (code === 127 || code === 8) {
+        // Backspace / Delete.
+        if (buf.length > 0) {
+          buf = buf.slice(0, -1);
+        }
+      } else if (code >= 32) {
+        // Printable character.
+        buf += ch;
+      }
+    };
+
+    stdin.on('data', onData);
+  });
+}
+
+/** @internal Injectable I/O for testing `readPasswordDevTty`. */
+export interface DevTtyIo {
+  openSync(path: string, flags: string): number;
+  readSync(fd: number, buf: Uint8Array, offset: number, length: number, position: null): number;
+  writeSync(fd: number, data: string): number;
+  closeSync(fd: number): void;
+  execSync(cmd: string, opts: { stdio: string }): void;
+}
+
+/**
+ * Read a password from `/dev/tty` using synchronous I/O.
+ *
+ * Opens `/dev/tty` directly, uses `stty -echo` to suppress input,
+ * reads until newline, then restores echo and closes file descriptors.
+ *
+ * @param prompt - The prompt string to display.
+ * @param io - Injectable I/O functions (defaults to `node:fs` + `node:child_process`).
+ * @internal Exported for testing only.
+ */
+export async function readPasswordDevTty(
+  prompt: string,
+  io?: DevTtyIo,
+): Promise<string> {
+  // Use injected I/O or import real modules.
+  let fsIo: DevTtyIo;
+  if (io) {
+    fsIo = io;
+  } else {
+    const { openSync, readSync, writeSync, closeSync } = await import('node:fs');
+    const { execSync } = await import('node:child_process');
+    fsIo = {
+      openSync,
+      readSync,
+      writeSync,
+      closeSync,
+      execSync: (cmd: string, opts: { stdio: string }): void => { execSync(cmd, opts as any); },
+    };
+  }
+
+  let readFd: number;
+  let writeFd: number;
+
+  try {
+    readFd = fsIo.openSync('/dev/tty', 'r');
+    writeFd = fsIo.openSync('/dev/tty', 'w');
+  } catch {
+    throw new Error(
+      '[@enbox/auth] PasswordProvider.fromDevTty: cannot open /dev/tty. ' +
+      'No controlling terminal available.'
+    );
+  }
+
+  try {
+    // Suppress echo.
+    try {
+      fsIo.execSync('stty -echo < /dev/tty', { stdio: 'ignore' });
+    } catch {
+      // Continue — the user sees their password but the flow works.
+    }
+
+    fsIo.writeSync(writeFd, prompt);
+
+    // Cooked-mode read (line-buffered; terminal handles backspace).
+    const readBuf = new Uint8Array(256);
+    const decoder = new TextDecoder('utf-8');
+    let password = '';
+
+    while (true) {
+      const bytesRead = fsIo.readSync(readFd, readBuf, 0, readBuf.length, null);
+      if (bytesRead === 0) { break; }
+
+      password += decoder.decode(readBuf.subarray(0, bytesRead), { stream: true });
+
+      const nlIdx = password.indexOf('\n');
+      if (nlIdx !== -1) { password = password.slice(0, nlIdx); break; }
+
+      const crIdx = password.indexOf('\r');
+      if (crIdx !== -1) { password = password.slice(0, crIdx); break; }
+    }
+
+    fsIo.writeSync(writeFd, '\n');
+    return password;
+  } finally {
+    // Restore echo.
+    try { fsIo.execSync('stty echo < /dev/tty', { stdio: 'ignore' }); } catch { /* best-effort */ }
+    fsIo.closeSync(readFd);
+    fsIo.closeSync(writeFd);
+  }
+}
+
+// ─── Factory functions ───────────────────────────────────────────
+
+
+export namespace PasswordProvider {
+
+  /**
+   * Read the password from an environment variable.
+   *
+   * Throws if the variable is not set or is empty, allowing `chain()`
+   * to fall through to the next provider.
+   *
+   * @param envVar - Name of the environment variable. Default: `'ENBOX_PASSWORD'`.
+   *
+   * @example
+   * ```ts
+   * const provider = PasswordProvider.fromEnv('MY_APP_PASSWORD');
+   * ```
+   */
+  export function fromEnv(envVar = 'ENBOX_PASSWORD'): PasswordProvider {
+    return {
+      async getPassword(): Promise<string> {
+        const value = process.env[envVar];
+        if (!value) {
+          throw new Error(
+            `[@enbox/auth] PasswordProvider.fromEnv: environment variable '${envVar}' is not set.`
+          );
+        }
+        return value;
+      },
+    };
+  }
+
+  /**
+   * Wrap an async callback as a password provider.
+   *
+   * This is the escape hatch for custom UI (e.g. `@clack/prompts`,
+   * Electron dialog, browser modal).
+   *
+   * @param callback - Called with the password context; must return a password string.
+   *
+   * @example
+   * ```ts
+   * const provider = PasswordProvider.fromCallback(async ({ reason }) => {
+   *   if (reason === 'create') {
+   *     return await showCreatePasswordDialog();
+   *   }
+   *   return await showUnlockDialog();
+   * });
+   * ```
+   */
+  export function fromCallback(
+    callback: (context: PasswordContext) => Promise<string>,
+  ): PasswordProvider {
+    return { getPassword: callback };
+  }
+
+  /**
+   * Prompt for a password via `process.stdin` in raw mode.
+   *
+   * Input is read character-by-character with no echo. Handles
+   * backspace and Ctrl-C (rejects with an error). Only works when
+   * `process.stdin.isTTY` is `true`; throws otherwise so `chain()`
+   * can fall through to the next provider.
+   *
+   * Suitable for main CLI processes that own stdin/stdout.
+   *
+   * @param options - Optional configuration.
+   * @param options.prompt - Text to display before reading. Default: `'Vault password: '`.
+   *
+   * @example
+   * ```ts
+   * const provider = PasswordProvider.fromTty({ prompt: 'Password: ' });
+   * ```
+   */
+  export function fromTty(options: { prompt?: string } = {}): PasswordProvider {
+    const prompt = options.prompt ?? 'Vault password: ';
+
+    return {
+      async getPassword(): Promise<string> {
+        if (!process.stdin.isTTY) {
+          throw new Error(
+            '[@enbox/auth] PasswordProvider.fromTty: stdin is not a TTY.'
+          );
+        }
+
+        return readPasswordRawMode(
+          process.stdin as unknown as TtyReadable,
+          process.stdout,
+          prompt,
+        );
+      },
+    };
+  }
+
+  /**
+   * Prompt for a password via `/dev/tty` (Unix only).
+   *
+   * Opens `/dev/tty` directly, bypassing `process.stdin`. This is
+   * essential for subprocesses where stdin is owned by the parent
+   * (e.g. Git credential helpers, SSH, GPG). Uses `stty -echo` to
+   * suppress input echo.
+   *
+   * Throws if `/dev/tty` cannot be opened (e.g. non-Unix platform,
+   * no controlling terminal), allowing `chain()` to fall through.
+   *
+   * @param options - Optional configuration.
+   * @param options.prompt - Text to display before reading. Default: `'Vault password: '`.
+   *
+   * @example
+   * ```ts
+   * // For git credential helpers:
+   * const provider = PasswordProvider.fromDevTty();
+   * ```
+   */
+  export function fromDevTty(options: { prompt?: string } = {}): PasswordProvider {
+    const prompt = options.prompt ?? 'Vault password: ';
+
+    return {
+      async getPassword(): Promise<string> {
+        return readPasswordDevTty(prompt);
+      },
+    };
+  }
+
+  /**
+   * Compose multiple providers with automatic fallback.
+   *
+   * Tries each provider in order. If a provider throws, the next one
+   * is tried. If all providers fail, the last error is rethrown.
+   *
+   * @param providers - Ordered list of providers to try.
+   *
+   * @example
+   * ```ts
+   * // Try env var first, then interactive TTY, then /dev/tty for subprocesses.
+   * const provider = PasswordProvider.chain([
+   *   PasswordProvider.fromEnv('ENBOX_PASSWORD'),
+   *   PasswordProvider.fromTty(),
+   *   PasswordProvider.fromDevTty(),
+   * ]);
+   * ```
+   */
+  export function chain(providers: PasswordProvider[]): PasswordProvider {
+    if (providers.length === 0) {
+      throw new Error('[@enbox/auth] PasswordProvider.chain: at least one provider is required.');
+    }
+
+    return {
+      async getPassword(context: PasswordContext): Promise<string> {
+        let lastError: Error | undefined;
+
+        for (const provider of providers) {
+          try {
+            return await provider.getPassword(context);
+          } catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+          }
+        }
+
+        throw lastError ?? new Error('[@enbox/auth] PasswordProvider.chain: all providers failed.');
+      },
+    };
+  }
+}