@enbox/auth 0.3.1 → 0.5.0

package/dist/types/types.d.ts

@@ -3,6 +3,7 @@
  * Public types for the authentication and identity management SDK.
  */
 import type { ConnectPermissionRequest, EnboxUserAgent, HdIdentityVault, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
+import type { PasswordProvider } from './password-provider.js';
 export type { ConnectPermissionRequest, HdIdentityVault, IdentityVaultBackup, LocalDwnStrategy, PortableIdentity } from '@enbox/agent';
 export type { EnboxUserAgent } from '@enbox/agent';
 /**
@@ -132,13 +133,44 @@ 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}. */
 export interface AuthManagerOptions {
@@ -182,8 +214,32 @@ 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
@@ -256,6 +312,39 @@ 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}. */
 export interface DisconnectOptions {
@@ -284,6 +373,14 @@ export interface StorageAdapter {
     remove(key: string): Promise<void>;
     /** 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>;
 }
 /** The insecure default password used when none is provided. */
 export declare const INSECURE_DEFAULT_PASSWORD = "insecure-static-phrase";
@@ -301,12 +398,20 @@ export declare const STORAGE_KEYS: {
     /** The connected DID (for wallet-connected sessions). */
     readonly 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
      */
     readonly 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
+     */
+    readonly REGISTRATION_TOKENS: "enbox:auth:registrationTokens";
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@enbox/auth",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Headless authentication and identity management SDK for Enbox",
   "type": "module",
   "main": "./dist/esm/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
   "scripts": {
-    "clean": "rimraf dist",
-    "build:esm": "rimraf dist/esm dist/types && bun tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "build:esm": "rm -rf dist/esm dist/types && bun tsc -p tsconfig.json",
     "build": "bun run clean && bun run build:esm",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix",
@@ -56,16 +56,15 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "@enbox/agent": "0.3.1",
+    "@enbox/agent": "0.4.0",
     "@enbox/common": "0.0.7",
     "@enbox/dids": "0.0.9",
     "@enbox/dwn-clients": "0.1.0",
-    "level": "8.0.0"
+    "level": "8.0.1"
   },
   "devDependencies": {
-    "@types/node": "20.14.8",
-    "bun-types": "latest",
-    "rimraf": "4.4.0",
-    "typescript": "5.5.4"
+    "@types/node": "22.19.15",
+    "bun-types": "1.3.10",
+    "typescript": "5.9.3"
   }
 }

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. */
@@ -329,6 +466,43 @@ export class AuthManager {
     return this._session;
   }
 
+  /**
+   * Lock the auth manager.
+   *
+   * Stops sync, clears the active session, and locks the underlying vault
+   * so the password must be provided again to resume. Session storage
+   * markers are preserved so {@link restoreSession} can reconnect after
+   * the vault is unlocked again.
+   *
+   * After locking, the state transitions to `'locked'`.
+   *
+   * @param options - Optional lock configuration.
+   * @param options.timeout - Milliseconds to wait for sync to stop. Default: `2000`.
+   */
+  async lock(options: { timeout?: number } = {}): Promise<void> {
+    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') {
+      await (this._userAgent as any).sync.stopSync(timeout);
+    }
+
+    // 2. Clear the session (but keep storage markers for restore).
+    this._session = undefined;
+
+    // 3. Lock the vault (also emits 'vault-locked').
+    await this._vault.lock();
+
+    // 4. Transition state.
+    this._setState('locked');
+
+    // 5. Emit session-end if there was an active session.
+    if (did) {
+      this._emitter.emit('session-end', { did });
+    }
+  }
+
   /**
    * Disconnect the current session.
    *
@@ -385,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 ────────────────────────────────────────────
 
   /**
@@ -432,9 +686,19 @@ export class AuthManager {
       connectedDid : identity.metadata.connectedDid,
     };
 
-    // Restart sync.
+    // Register the identity for sync and restart sync.
     const sync = this._defaultSync;
     if (sync !== 'off') {
+      // Register the identity for sync (idempotent — ignores "already registered" errors).
+      try {
+        await this._userAgent.sync.registerIdentity({
+          did     : connectedDid,
+          options : { delegateDid, protocols: [] },
+        });
+      } catch {
+        // Already registered — safe to ignore.
+      }
+
       const syncMode = sync === undefined ? 'live' : 'poll';
       const syncInterval = sync ?? (syncMode === 'live' ? '5m' : '2m');
       this._userAgent.sync.startSync({ mode: syncMode, interval: syncInterval })
@@ -549,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 {