@enbox/auth 0.4.0 → 0.5.0

package/dist/esm/password-provider.js

@@ -0,0 +1,319 @@
+/**
+ * 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
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// ─── 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, stdout, prompt) {
+    stdout.write(prompt);
+    return new Promise((resolve, reject) => {
+        let buf = '';
+        stdin.setRawMode(true);
+        stdin.setEncoding('utf8');
+        stdin.resume();
+        const onData = (ch) => {
+            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);
+    });
+}
+/**
+ * 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 function readPasswordDevTty(prompt, io) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Use injected I/O or import real modules.
+        let fsIo;
+        if (io) {
+            fsIo = io;
+        }
+        else {
+            const { openSync, readSync, writeSync, closeSync } = yield import('node:fs');
+            const { execSync } = yield import('node:child_process');
+            fsIo = {
+                openSync,
+                readSync,
+                writeSync,
+                closeSync,
+                execSync: (cmd, opts) => { execSync(cmd, opts); },
+            };
+        }
+        let readFd;
+        let writeFd;
+        try {
+            readFd = fsIo.openSync('/dev/tty', 'r');
+            writeFd = fsIo.openSync('/dev/tty', 'w');
+        }
+        catch (_a) {
+            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 (_b) {
+                // 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 */_c) { /* best-effort */ }
+            fsIo.closeSync(readFd);
+            fsIo.closeSync(writeFd);
+        }
+    });
+}
+// ─── Factory functions ───────────────────────────────────────────
+export var PasswordProvider;
+(function (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');
+     * ```
+     */
+    function fromEnv(envVar = 'ENBOX_PASSWORD') {
+        return {
+            getPassword() {
+                return __awaiter(this, void 0, void 0, function* () {
+                    const value = process.env[envVar];
+                    if (!value) {
+                        throw new Error(`[@enbox/auth] PasswordProvider.fromEnv: environment variable '${envVar}' is not set.`);
+                    }
+                    return value;
+                });
+            },
+        };
+    }
+    PasswordProvider.fromEnv = fromEnv;
+    /**
+     * 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();
+     * });
+     * ```
+     */
+    function fromCallback(callback) {
+        return { getPassword: callback };
+    }
+    PasswordProvider.fromCallback = fromCallback;
+    /**
+     * 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: ' });
+     * ```
+     */
+    function fromTty(options = {}) {
+        var _a;
+        const prompt = (_a = options.prompt) !== null && _a !== void 0 ? _a : 'Vault password: ';
+        return {
+            getPassword() {
+                return __awaiter(this, void 0, void 0, function* () {
+                    if (!process.stdin.isTTY) {
+                        throw new Error('[@enbox/auth] PasswordProvider.fromTty: stdin is not a TTY.');
+                    }
+                    return readPasswordRawMode(process.stdin, process.stdout, prompt);
+                });
+            },
+        };
+    }
+    PasswordProvider.fromTty = fromTty;
+    /**
+     * 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();
+     * ```
+     */
+    function fromDevTty(options = {}) {
+        var _a;
+        const prompt = (_a = options.prompt) !== null && _a !== void 0 ? _a : 'Vault password: ';
+        return {
+            getPassword() {
+                return __awaiter(this, void 0, void 0, function* () {
+                    return readPasswordDevTty(prompt);
+                });
+            },
+        };
+    }
+    PasswordProvider.fromDevTty = fromDevTty;
+    /**
+     * 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(),
+     * ]);
+     * ```
+     */
+    function chain(providers) {
+        if (providers.length === 0) {
+            throw new Error('[@enbox/auth] PasswordProvider.chain: at least one provider is required.');
+        }
+        return {
+            getPassword(context) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    let lastError;
+                    for (const provider of providers) {
+                        try {
+                            return yield provider.getPassword(context);
+                        }
+                        catch (err) {
+                            lastError = err instanceof Error ? err : new Error(String(err));
+                        }
+                    }
+                    throw lastError !== null && lastError !== void 0 ? lastError : new Error('[@enbox/auth] PasswordProvider.chain: all providers failed.');
+                });
+            },
+        };
+    }
+    PasswordProvider.chain = chain;
+})(PasswordProvider || (PasswordProvider = {}));
+//# sourceMappingURL=password-provider.js.map

package/dist/esm/password-provider.js.map

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

package/dist/esm/types.js

@@ -19,12 +19,20 @@ export const STORAGE_KEYS = {
     /** The connected DID (for wallet-connected sessions). */
     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',
 };
 //# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuXH,oEAAoE;AAEpE,gEAAgE;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAG,wBAAwB,CAAC;AAElE;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,oDAAoD;IACpD,oBAAoB,EAAE,gCAAgC;IAEtD,+CAA+C;IAC/C,eAAe,EAAE,2BAA2B;IAE5C,4DAA4D;IAC5D,YAAY,EAAE,wBAAwB;IAEtC,yDAAyD;IACzD,aAAa,EAAE,yBAAyB;IAExC;;;;;;OAMG;IACH,kBAAkB,EAAE,6BAA6B;CACzC,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0cH,oEAAoE;AAEpE,gEAAgE;AAChE,MAAM,CAAC,MAAM,yBAAyB,GAAG,wBAAwB,CAAC;AAElE;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,oDAAoD;IACpD,oBAAoB,EAAE,gCAAgC;IAEtD,+CAA+C;IAC/C,eAAe,EAAE,2BAA2B;IAE5C,4DAA4D;IAC5D,YAAY,EAAE,wBAAwB;IAEtC,yDAAyD;IACzD,aAAa,EAAE,yBAAyB;IAExC;;;;;;OAMG;IACH,kBAAkB,EAAE,6BAA6B;IAEjD;;;;;;OAMG;IACH,mBAAmB,EAAE,+BAA+B;CAC5C,CAAC"}

package/dist/types/auth-manager.d.ts

@@ -9,7 +9,7 @@ import { EnboxUserAgent } from '@enbox/agent';
 import type { PortableIdentity } from '@enbox/agent';
 import { AuthSession } from './identity-session.js';
 import { VaultManager } from './vault/vault-manager.js';
-import type { AuthEvent, AuthEventHandler, AuthManagerOptions, AuthState, DisconnectOptions, IdentityInfo, ImportFromPhraseOptions, ImportFromPortableOptions, LocalConnectOptions, RestoreSessionOptions, WalletConnectOptions } from './types.js';
+import type { AuthEvent, AuthEventHandler, AuthManagerOptions, AuthState, DisconnectOptions, HeadlessConnectOptions, IdentityInfo, ImportFromPhraseOptions, ImportFromPortableOptions, LocalConnectOptions, RestoreSessionOptions, ShutdownOptions, WalletConnectOptions } from './types.js';
 /**
  * The primary entry point for authentication and identity management.
  *
@@ -51,10 +51,19 @@ export declare class AuthManager {
     private _session;
     private _state;
     private _isConnecting;
+    private _isShutDown;
     private _defaultPassword?;
+    private _passwordProvider?;
     private _defaultSync?;
     private _defaultDwnEndpoints?;
     private _registration?;
+    /**
+     * 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?;
     private constructor();
     /**
      * Create a new AuthManager instance.
@@ -79,7 +88,7 @@ export declare class AuthManager {
      */
     connect(options?: LocalConnectOptions): Promise<AuthSession>;
     /**
-     * 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.
@@ -110,6 +119,30 @@ export declare class AuthManager {
      * This replaces the manual `previouslyConnected` localStorage pattern.
      */
     restoreSession(options?: RestoreSessionOptions): Promise<AuthSession | undefined>;
+    /**
+     * 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
+     * ```
+     */
+    connectHeadless(options?: HeadlessConnectOptions): Promise<AuthSession>;
     /** The current active session, or `undefined` if not connected. */
     get session(): AuthSession | undefined;
     /**
@@ -137,6 +170,30 @@ export declare class AuthManager {
      * @param options.timeout - Milliseconds to wait for sync to complete.
      */
     disconnect(options?: DisconnectOptions): Promise<void>;
+    /**
+     * 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
+     * ```
+     */
+    shutdown(options?: ShutdownOptions): Promise<void>;
     /**
      * List all stored identities.
      *
@@ -186,6 +243,14 @@ export declare class AuthManager {
     get isConnecting(): boolean;
     /** The underlying EnboxUserAgent (for advanced usage). */
     get agent(): EnboxUserAgent;
+    /**
+     * 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;
     private _setState;
     private _guardConcurrency;
 }

package/dist/types/auth-manager.d.ts.map

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

package/dist/types/flows/dwn-discovery.d.ts

@@ -7,26 +7,21 @@
  *
  * ## Discovery channels (browser, highest to lowest priority)
  *
- * 1. **URL fragment payload** — A `dwn://register` redirect just landed
+ * 1. **URL fragment payload** — A `dwn://connect` 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
+ * In Node/Bun environments, the agent's `LocalDwnDiscovery` reads the
+ * `~/.enbox/dwn.json` discovery file 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.
+ * are not needed in those environments.
  *
- * @see https://github.com/enboxorg/enbox/issues/589
+ * @see https://github.com/enboxorg/enbox/issues/677
  * @module
  */
 import type { EnboxUserAgent } from '@enbox/agent';
@@ -36,7 +31,7 @@ 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
+ * the user was just redirected back from a `dwn://connect` handler. If a
  * valid payload is found, the endpoint is persisted and the fragment is
  * cleared to prevent double-reads.
  *
@@ -44,6 +39,28 @@ import type { StorageAdapter } from '../types.js';
  *   was found in the URL.
  */
 export declare function checkUrlForDwnDiscoveryPayload(): string | undefined;
+/**
+ * Run local DWN discovery **before the agent exists**.
+ *
+ * This is the standalone counterpart of {@link applyLocalDwnDiscovery} and
+ * is designed to be called in `AuthManager.create()`, before
+ * `EnboxUserAgent.create()`, so the agent creation can decide whether to
+ * spin up an in-process DWN or operate in remote mode.
+ *
+ * Discovery channels (highest → lowest priority):
+ * 1. **URL fragment payload** — A `dwn://connect` redirect just landed.
+ * 2. **Persisted endpoint** (localStorage) — A previously discovered
+ *    endpoint, re-validated via `GET /info`.
+ *
+ * When a valid endpoint is found it is persisted to storage. When a
+ * previously-persisted endpoint is stale, it is removed.
+ *
+ * @param storage - The auth storage adapter (for reading/writing the
+ *   cached endpoint).
+ * @returns The validated endpoint URL, or `undefined` if no local DWN
+ *   server is available.
+ */
+export declare function discoverLocalDwn(storage: StorageAdapter): Promise<string | undefined>;
 /**
  * Persist a discovered local DWN endpoint in auth storage.
  *
@@ -76,25 +93,18 @@ export declare function restoreLocalDwnEndpoint(agent: EnboxUserAgent, storage:
  * 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
+ * the browser. It does NOT trigger the `dwn://connect` 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
+ * 1. **URL fragment payload** — A `dwn://connect` 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.
@@ -106,52 +116,29 @@ export declare function restoreLocalDwnEndpoint(agent: EnboxUserAgent, storage:
  */
 export declare function applyLocalDwnDiscovery(agent: EnboxUserAgent, storage: StorageAdapter, emitter?: AuthEventEmitter): Promise<boolean>;
 /**
- * Initiate the `dwn://register` flow by opening the register URL.
+ * Initiate the `dwn://connect` flow by opening the connect URL.
  *
- * This asks the operating system to route `dwn://register?callback=<url>`
+ * This asks the operating system to route `dwn://connect?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.
+ * **Note:** 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.
  *
  * @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
+ * @returns `true` if the connect 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.
- * }
+ * // Trigger the dwn://connect flow to discover a local DWN.
+ * requestLocalDwnDiscovery();
+ * // The page will reload with the endpoint in the URL fragment.
+ * // On the next connect/restore, applyLocalDwnDiscovery() reads it.
  * ```
  */
 export declare function requestLocalDwnDiscovery(callbackUrl?: string): boolean;
-/**
- * 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 declare function probeLocalDwn(): Promise<string | undefined>;
 //# sourceMappingURL=dwn-discovery.d.ts.map

package/dist/types/flows/dwn-discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dwn-discovery.d.ts","sourceRoot":"","sources":["../../../src/flows/dwn-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,GAAG,SAAS,CAkBnE;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAuBtE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAsBjE"}
+{"version":3,"file":"dwn-discovery.d.ts","sourceRoot":"","sources":["../../../src/flows/dwn-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAKnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,GAAG,SAAS,CAkBnE;AA4BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAwB7B;AAID;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAuBtE"}