@enbox/auth 0.4.0 → 0.5.0

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
@@ -340,6 +399,21 @@ export interface RestoreSessionOptions {
   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 {
   /**
@@ -374,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 ────────────────────────────────────────────
@@ -399,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;