@enbox/auth 0.3.1 → 0.5.0

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.');
+      },
+    };
+  }
+}

package/src/types.ts

@@ -5,6 +5,8 @@
 
 import type { ConnectPermissionRequest, EnboxUserAgent, HdIdentityVault, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
 
+import type { PasswordProvider } from './password-provider.js';
+
 // Re-export types that consumers will need
 export type { ConnectPermissionRequest, HdIdentityVault, IdentityVaultBackup, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
 
@@ -166,14 +168,46 @@ export interface RegistrationOptions {
    * Pre-existing registration tokens from a previous session, keyed by
    * DWN endpoint URL. If a valid (non-expired) token exists for an
    * endpoint, it is used directly without re-running the auth flow.
+   *
+   * When {@link persistTokens} is `true`, this field is ignored —
+   * tokens are loaded automatically from the `StorageAdapter`.
    */
   registrationTokens?: Record<string, RegistrationTokenData>;
 
   /**
    * Called when new or refreshed registration tokens are obtained.
    * The app should persist these for future sessions.
+   *
+   * When {@link persistTokens} is `true`, tokens are saved automatically
+   * to the `StorageAdapter`. This callback is still invoked (if provided)
+   * **after** the automatic save, so consumers can observe token changes
+   * without handling persistence themselves.
    */
   onRegistrationTokens?: (tokens: Record<string, RegistrationTokenData>) => void;
+
+  /**
+   * Automatically persist and restore registration tokens using the
+   * auth manager's `StorageAdapter`.
+   *
+   * When `true`, tokens are loaded from storage before registration and
+   * saved back after new or refreshed tokens are obtained. This removes
+   * the need for consumers to implement their own token I/O via
+   * {@link registrationTokens} and {@link onRegistrationTokens}.
+   *
+   * Defaults to `false` for backward compatibility.
+   *
+   * @example
+   * ```ts
+   * const auth = await AuthManager.create({
+   *   registration: {
+   *     onSuccess: () => {},
+   *     onFailure: (err) => console.error(err),
+   *     persistTokens: true,
+   *   },
+   * });
+   * ```
+   */
+  persistTokens?: boolean;
 }
 
 /** Options for {@link AuthManager.create}. */
@@ -223,9 +257,34 @@ export interface AuthManagerOptions {
   /**
    * Default password for vault operations.
    * If not provided, an insecure default is used (with a console warning).
+   *
+   * For more flexible password acquisition (env vars, TTY prompts,
+   * chained fallbacks), use {@link passwordProvider} instead.
    */
   password?: string;
 
+  /**
+   * A composable password provider for obtaining the vault password.
+   *
+   * When set, this provider is consulted by `connect()`,
+   * `restoreSession()`, and `connectHeadless()` whenever a password
+   * is needed and none was given explicitly. It takes precedence over
+   * the static {@link password} option.
+   *
+   * @example
+   * ```ts
+   * import { AuthManager, PasswordProvider } from '@enbox/auth';
+   *
+   * const auth = await AuthManager.create({
+   *   passwordProvider: PasswordProvider.chain([
+   *     PasswordProvider.fromEnv('ENBOX_PASSWORD'),
+   *     PasswordProvider.fromTty(),
+   *   ]),
+   * });
+   * ```
+   */
+  passwordProvider?: PasswordProvider;
+
   /**
    * Sync interval for DWN synchronization.
    * - `'off'` — disable sync
@@ -317,6 +376,42 @@ export interface ImportFromPortableOptions {
 export interface RestoreSessionOptions {
   /** Password to unlock the vault (needed if vault is locked). */
   password?: string;
+
+  /**
+   * Called when the vault is locked and a password is required to proceed.
+   *
+   * If provided, this callback is invoked instead of falling back to the
+   * default password or the insecure static phrase. This is the recommended
+   * way to implement interactive password prompts (e.g., a PIN entry dialog
+   * or CLI prompt).
+   *
+   * @returns The password entered by the user.
+   *
+   * @example Browser PIN dialog
+   * ```ts
+   * const session = await auth.restoreSession({
+   *   onPasswordRequired: async () => {
+   *     return await showPinDialog();
+   *   },
+   * });
+   * ```
+   */
+  onPasswordRequired?: () => Promise<string>;
+}
+
+/** Options for {@link AuthManager.connectHeadless}. */
+export interface HeadlessConnectOptions {
+  /** Vault password (overrides manager default). */
+  password?: string;
+}
+
+/** Options for {@link AuthManager.shutdown}. */
+export interface ShutdownOptions {
+  /**
+   * Milliseconds to wait for pending sync operations before shutting down.
+   * Default: `2000`.
+   */
+  timeout?: number;
 }
 
 /** Options for {@link AuthManager.disconnect}. */
@@ -353,6 +448,15 @@ export interface StorageAdapter {
 
   /** Clear all stored data. */
   clear(): Promise<void>;
+
+  /**
+   * Close the underlying storage resources (e.g. LevelDB handles).
+   *
+   * Optional — not all adapters need cleanup. Called by
+   * {@link AuthManager.shutdown} to release resources so the process
+   * can exit cleanly.
+   */
+  close?(): Promise<void>;
 }
 
 // ─── Internal helpers ────────────────────────────────────────────
@@ -378,11 +482,20 @@ export const STORAGE_KEYS = {
   CONNECTED_DID: 'enbox:auth:connectedDid',
 
   /**
-   * The base URL of the local DWN server discovered via the `dwn://register`
+   * The base URL of the local DWN server discovered via the `dwn://connect`
    * browser redirect flow. Persisted so subsequent page loads can skip the
    * redirect and inject the endpoint directly.
    *
    * @see https://github.com/enboxorg/enbox/issues/589
    */
   LOCAL_DWN_ENDPOINT: 'enbox:auth:localDwnEndpoint',
+
+  /**
+   * JSON-serialised `Record<string, RegistrationTokenData>` for DWN endpoint
+   * registration tokens. Automatically loaded before registration and saved
+   * after new/refreshed tokens are obtained when `persistTokens` is enabled.
+   *
+   * @see https://github.com/enboxorg/enbox/issues/690
+   */
+  REGISTRATION_TOKENS: 'enbox:auth:registrationTokens',
 } as const;