@enbox/auth 0.3.1

package/dist/esm/storage/storage.js

@@ -0,0 +1,152 @@
+/**
+ * Storage adapter implementations for session persistence.
+ * @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());
+    });
+};
+import { Level } from 'level';
+/**
+ * Browser storage adapter backed by `localStorage`.
+ *
+ * All keys are prefixed to avoid collisions with other localStorage users.
+ */
+export class BrowserStorage {
+    constructor(prefix = 'enbox:') {
+        this._prefix = prefix;
+    }
+    get(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return globalThis.localStorage.getItem(this._prefix + key);
+        });
+    }
+    set(key, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            globalThis.localStorage.setItem(this._prefix + key, value);
+        });
+    }
+    remove(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            globalThis.localStorage.removeItem(this._prefix + key);
+        });
+    }
+    clear() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const keysToRemove = [];
+            for (let i = 0; i < globalThis.localStorage.length; i++) {
+                const key = globalThis.localStorage.key(i);
+                if (key === null || key === void 0 ? void 0 : key.startsWith(this._prefix)) {
+                    keysToRemove.push(key);
+                }
+            }
+            for (const key of keysToRemove) {
+                globalThis.localStorage.removeItem(key);
+            }
+        });
+    }
+}
+/**
+ * In-memory storage adapter for testing or environments without persistence.
+ */
+export class MemoryStorage {
+    constructor() {
+        this._store = new Map();
+    }
+    get(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            return (_a = this._store.get(key)) !== null && _a !== void 0 ? _a : null;
+        });
+    }
+    set(key, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this._store.set(key, value);
+        });
+    }
+    remove(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this._store.delete(key);
+        });
+    }
+    clear() {
+        return __awaiter(this, void 0, void 0, function* () {
+            this._store.clear();
+        });
+    }
+}
+/**
+ * LevelDB-backed storage adapter for Node / CLI environments.
+ *
+ * Uses the `level` package (v8), which selects `classic-level` (LevelDB)
+ * in Node and `browser-level` (IndexedDB) in browsers.  Level auto-opens
+ * on construction and queues operations until ready, so no explicit
+ * `open()` call is required.
+ */
+export class LevelStorage {
+    constructor(dataPath = 'DATA/AGENT/AUTH_STORE') {
+        this._db = new Level(dataPath);
+    }
+    get(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield this._db.get(key);
+            }
+            catch (error) {
+                const e = error;
+                if (e.code === 'LEVEL_NOT_FOUND') {
+                    return null;
+                }
+                throw error;
+            }
+        });
+    }
+    set(key, value) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._db.put(key, value);
+        });
+    }
+    remove(key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield this._db.del(key);
+            }
+            catch (error) {
+                const e = error;
+                // Silently ignore deleting a key that doesn't exist.
+                if (e.code !== 'LEVEL_NOT_FOUND') {
+                    throw error;
+                }
+            }
+        });
+    }
+    clear() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._db.clear();
+        });
+    }
+    /** Close the underlying LevelDB database. */
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._db.close();
+        });
+    }
+}
+/**
+ * Detect the runtime environment and return an appropriate default storage adapter.
+ *
+ * - If `localStorage` is available → `BrowserStorage`
+ * - Otherwise → `LevelStorage` (persistent on disk via LevelDB)
+ */
+export function createDefaultStorage() {
+    if (typeof globalThis.localStorage !== 'undefined') {
+        return new BrowserStorage();
+    }
+    return new LevelStorage();
+}
+//# sourceMappingURL=storage.js.map

package/dist/esm/storage/storage.js.map

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

package/dist/esm/types.js

@@ -0,0 +1,30 @@
+/**
+ * @module @enbox/auth
+ * Public types for the authentication and identity management SDK.
+ */
+// ─── Internal helpers ────────────────────────────────────────────
+/** The insecure default password used when none is provided. */
+export const INSECURE_DEFAULT_PASSWORD = 'insecure-static-phrase';
+/**
+ * Storage keys used by the auth manager for session persistence.
+ * @internal
+ */
+export const STORAGE_KEYS = {
+    /** Whether a session was previously established. */
+    PREVIOUSLY_CONNECTED: 'enbox:auth:previouslyConnected',
+    /** The DID URI of the last active identity. */
+    ACTIVE_IDENTITY: 'enbox:auth:activeIdentity',
+    /** The delegate DID URI (for wallet-connected sessions). */
+    DELEGATE_DID: 'enbox:auth:delegateDid',
+    /** 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`
+     * 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',
+};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

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

package/dist/esm/vault/vault-manager.js

@@ -0,0 +1,95 @@
+/**
+ * VaultManager wraps {@link HdIdentityVault} with a high-level API
+ * and emits events on lock/unlock.
+ * @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());
+    });
+};
+/**
+ * Manages the encrypted identity vault lifecycle.
+ *
+ * The vault stores the agent's DID and content encryption key (CEK),
+ * protected by a user password using PBES2-HS512+A256KW with a 210K
+ * iteration work factor. The vault supports HD key derivation from
+ * a BIP-39 mnemonic for recovery.
+ */
+export class VaultManager {
+    constructor(vault, emitter) {
+        this._vault = vault;
+        this._emitter = emitter;
+    }
+    /** The underlying vault instance (for advanced usage). */
+    get raw() {
+        return this._vault;
+    }
+    /** Whether the vault has been initialized (has encrypted data). */
+    isInitialized() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._vault.isInitialized();
+        });
+    }
+    /** Whether the vault is currently locked (synchronous check). */
+    get isLocked() {
+        return this._vault.isLocked();
+    }
+    /**
+     * Unlock the vault with the given password.
+     * Decrypts the CEK into memory so the agent DID can be retrieved.
+     *
+     * @throws If the password is incorrect or vault is not initialized.
+     */
+    unlock(password) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._vault.unlock({ password });
+            this._emitter.emit('vault-unlocked', {});
+        });
+    }
+    /**
+     * Lock the vault, clearing the CEK from memory.
+     * After locking, the password must be provided again to unlock.
+     */
+    lock() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._vault.lock();
+            this._emitter.emit('vault-locked', {});
+        });
+    }
+    /**
+     * Change the vault password. Re-encrypts the CEK with the new password.
+     *
+     * @throws If the old password is incorrect or vault is locked.
+     */
+    changePassword(oldPassword, newPassword) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._vault.changePassword({ oldPassword, newPassword });
+        });
+    }
+    /**
+     * Create a backup of the vault.
+     *
+     * @throws If the vault is not initialized or is locked.
+     */
+    backup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this._vault.backup();
+        });
+    }
+    /**
+     * Restore the vault from a backup.
+     *
+     * @throws If the password doesn't match the backup's encryption.
+     */
+    restore(backup, password) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this._vault.restore({ backup, password });
+        });
+    }
+}
+//# sourceMappingURL=vault-manager.js.map

package/dist/esm/vault/vault-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-manager.js","sourceRoot":"","sources":["../../../src/vault/vault-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;;;;;;;;;;AAMH;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IAIvB,YAAY,KAAsB,EAAE,OAAyB;QAC3D,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,0DAA0D;IAC1D,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,mEAAmE;IAC7D,aAAa;;YACjB,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;QACrC,CAAC;KAAA;IAED,iEAAiE;IACjE,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACG,MAAM,CAAC,QAAgB;;YAC3B,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YACvC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;QAC3C,CAAC;KAAA;IAED;;;OAGG;IACG,IAAI;;YACR,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QACzC,CAAC;KAAA;IAED;;;;OAIG;IACG,cAAc,CAAC,WAAmB,EAAE,WAAmB;;YAC3D,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC;QACjE,CAAC;KAAA;IAED;;;;OAIG;IACG,MAAM;;YACV,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC9B,CAAC;KAAA;IAED;;;;OAIG;IACG,OAAO,CAAC,MAA2B,EAAE,QAAgB;;YACzD,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClD,CAAC;KAAA;CACF"}

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

@@ -0,0 +1,176 @@
+/**
+ * AuthManager — the primary entry point for `@enbox/auth`.
+ *
+ * Replaces `Enbox.connect()` (formerly `Web5.connect()`) with a composable,
+ * multi-identity-aware auth system that works in both browser and CLI environments.
+ * @module
+ */
+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';
+/**
+ * The primary entry point for authentication and identity management.
+ *
+ * `AuthManager` replaces `Enbox.connect()` (formerly `Web5.connect()`) with a composable, multi-identity-aware
+ * system. It manages vault lifecycle, identity CRUD, session persistence,
+ * and all connection flows (local DID, wallet connect, import, restore).
+ *
+ * @example Basic usage
+ * ```ts
+ * import { AuthManager } from '@enbox/auth';
+ *
+ * const auth = await AuthManager.create({ sync: '15s' });
+ *
+ * // First time: creates a new identity
+ * // Subsequent times: restores the previous session
+ * const session = await auth.restoreSession() ?? await auth.connect();
+ *
+ * // session.agent  — the authenticated Enbox agent
+ * // session.did    — the connected DID URI
+ * // session.identity — metadata about the connected identity
+ * ```
+ *
+ * @example Wallet connect
+ * ```ts
+ * const session = await auth.walletConnect({
+ *   displayName: 'My App',
+ *   connectServerUrl: 'https://enbox-dwn.fly.dev/connect',
+ *   permissionRequests: [{ protocolDefinition: MyProtocol.definition }],
+ *   onWalletUriReady: (uri) => showQRCode(uri),
+ *   validatePin: () => promptUserForPin(),
+ * });
+ * ```
+ */
+export declare class AuthManager {
+    private _userAgent;
+    private _emitter;
+    private _storage;
+    private _vault;
+    private _session;
+    private _state;
+    private _isConnecting;
+    private _defaultPassword?;
+    private _defaultSync?;
+    private _defaultDwnEndpoints?;
+    private _registration?;
+    private constructor();
+    /**
+     * Create a new AuthManager instance.
+     *
+     * When a pre-built `agent` is provided, it is used as-is and
+     * `dataPath`, `agentVault`, and `localDwnStrategy` are ignored.
+     * Otherwise, a new `EnboxUserAgent` is created with the given options.
+     *
+     * @param options - Configuration options for the auth manager.
+     * @returns A ready-to-use AuthManager instance.
+     */
+    static create(options?: AuthManagerOptions): Promise<AuthManager>;
+    /**
+     * Create or reconnect a local identity.
+     *
+     * On first use, this creates a new vault, agent DID, and user identity.
+     * On subsequent uses, it unlocks the vault and reconnects.
+     *
+     * @param options - Optional overrides for password, sync, DWN endpoints.
+     * @returns An active AuthSession.
+     * @throws If a connection attempt is already in progress.
+     */
+    connect(options?: LocalConnectOptions): Promise<AuthSession>;
+    /**
+     * Connect to an external wallet via the OIDC/QR relay protocol.
+     *
+     * This runs the full WalletConnect flow: generates a URI for QR display,
+     * validates the PIN, imports the delegated DID, and processes grants.
+     *
+     * @param options - Wallet connect configuration.
+     * @returns An active AuthSession with delegated permissions.
+     * @throws If sync is disabled (required for wallet connect).
+     * @throws If a connection attempt is already in progress.
+     */
+    walletConnect(options: WalletConnectOptions): Promise<AuthSession>;
+    /**
+     * Import an identity from a BIP-39 recovery phrase.
+     *
+     * This re-derives the vault and agent DID from the mnemonic,
+     * recovering the identity on this device.
+     */
+    importFromPhrase(options: ImportFromPhraseOptions): Promise<AuthSession>;
+    /**
+     * Import an identity from a PortableIdentity JSON object.
+     *
+     * The portable identity contains the DID's private keys and metadata.
+     */
+    importFromPortable(options: ImportFromPortableOptions): Promise<AuthSession>;
+    /**
+     * Restore a previous session from persisted storage.
+     *
+     * Returns `undefined` if no previous session exists.
+     * This replaces the manual `previouslyConnected` localStorage pattern.
+     */
+    restoreSession(options?: RestoreSessionOptions): Promise<AuthSession | undefined>;
+    /** The current active session, or `undefined` if not connected. */
+    get session(): AuthSession | undefined;
+    /**
+     * Disconnect the current session.
+     *
+     * @param options - Disconnect options.
+     * @param options.clearStorage - If `true`, performs a nuclear wipe:
+     *   clears all persisted data (localStorage + IndexedDB). Default: `false`.
+     * @param options.timeout - Milliseconds to wait for sync to complete.
+     */
+    disconnect(options?: DisconnectOptions): Promise<void>;
+    /**
+     * List all stored identities.
+     *
+     * Each identity has a DID URI, name, and optional connected DID
+     * (for wallet-connected/delegated identities).
+     */
+    listIdentities(): Promise<IdentityInfo[]>;
+    /**
+     * Switch the active identity.
+     *
+     * Disconnects the current session (if any) and creates a new session
+     * for the specified identity.
+     */
+    switchIdentity(didUri: string): Promise<AuthSession>;
+    /**
+     * Delete a stored identity.
+     *
+     * If the identity is currently active, it will be disconnected first.
+     *
+     * @throws If the identity is not found.
+     */
+    deleteIdentity(didUri: string): Promise<void>;
+    /**
+     * Export an identity as a PortableIdentity JSON object.
+     *
+     * This can be used for backup or transferring the identity
+     * to another device.
+     */
+    exportIdentity(didUri: string): Promise<PortableIdentity>;
+    /** Access the vault manager for lock/unlock/backup operations. */
+    get vault(): VaultManager;
+    /**
+     * Subscribe to an auth lifecycle event.
+     *
+     * @param event - The event name.
+     * @param handler - The event handler.
+     * @returns An unsubscribe function.
+     */
+    on<E extends AuthEvent>(event: E, handler: AuthEventHandler<E>): () => void;
+    /** The current auth state. */
+    get state(): AuthState;
+    /** Whether an active session exists. */
+    get isConnected(): boolean;
+    /** Whether the vault is currently locked. */
+    get isLocked(): boolean;
+    /** Whether a connection attempt is in progress. */
+    get isConnecting(): boolean;
+    /** The underlying EnboxUserAgent (for advanced usage). */
+    get agent(): EnboxUserAgent;
+    private _setState;
+    private _guardConcurrency;
+}
+//# sourceMappingURL=auth-manager.d.ts.map

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

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

package/dist/types/events.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Typed event emitter for auth state changes.
+ * @module
+ */
+import type { AuthEvent, AuthEventHandler, AuthEventMap } from './types.js';
+/**
+ * A minimal, type-safe event emitter for auth lifecycle events.
+ *
+ * Usage:
+ * ```ts
+ * const emitter = new AuthEventEmitter();
+ * const unsub = emitter.on('state-change', ({ previous, current }) => {
+ *   console.log(`State: ${previous} → ${current}`);
+ * });
+ * emitter.emit('state-change', { previous: 'locked', current: 'unlocked' });
+ * unsub(); // stop listening
+ * ```
+ */
+export declare class AuthEventEmitter {
+    private _listeners;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function.
+     */
+    on<E extends AuthEvent>(event: E, handler: AuthEventHandler<E>): () => void;
+    /**
+     * Emit an event to all registered listeners.
+     * @internal
+     */
+    emit<E extends AuthEvent>(event: E, payload: AuthEventMap[E]): void;
+    /**
+     * Remove all listeners for all events.
+     * @internal
+     */
+    removeAllListeners(): void;
+}
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAA0D;IAE5E;;OAEG;IACH,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAgB3E;;;OAGG;IACH,IAAI,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAYnE;;;OAGG;IACH,kBAAkB,IAAI,IAAI;CAG3B"}

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

@@ -0,0 +1,157 @@
+/**
+ * Local DWN discovery integration for browser and CLI environments.
+ *
+ * This module bridges the local DWN discovery mechanisms (implemented in
+ * `@enbox/agent`) with the `@enbox/auth` storage, session lifecycle, and
+ * event system.
+ *
+ * ## Discovery channels (browser, highest to lowest priority)
+ *
+ * 1. **URL fragment payload** — A `dwn://register` 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
+ * `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.
+ *
+ * @see https://github.com/enboxorg/enbox/issues/589
+ * @module
+ */
+import type { EnboxUserAgent } from '@enbox/agent';
+import type { AuthEventEmitter } from '../events.js';
+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
+ * valid payload is found, the endpoint is persisted and the fragment is
+ * cleared to prevent double-reads.
+ *
+ * @returns The discovered endpoint string, or `undefined` if no payload
+ *   was found in the URL.
+ */
+export declare function checkUrlForDwnDiscoveryPayload(): string | undefined;
+/**
+ * Persist a discovered local DWN endpoint in auth storage.
+ *
+ * @param storage - The auth storage adapter.
+ * @param endpoint - The local DWN server base URL.
+ */
+export declare function persistLocalDwnEndpoint(storage: StorageAdapter, endpoint: string): Promise<void>;
+/**
+ * Clear the persisted local DWN endpoint from auth storage.
+ *
+ * Call this when the cached endpoint is found to be stale (server no
+ * longer running).
+ *
+ * @param storage - The auth storage adapter.
+ */
+export declare function clearLocalDwnEndpoint(storage: StorageAdapter): Promise<void>;
+/**
+ * Restore a previously persisted local DWN endpoint and inject it into the
+ * agent's discovery cache.
+ *
+ * The endpoint is validated by the agent (via `GET /info`) before being
+ * accepted. If validation fails, the stale entry is removed from storage.
+ *
+ * @param agent - The running EnboxUserAgent.
+ * @param storage - The auth storage adapter.
+ * @returns `true` if an endpoint was restored and validated, `false` otherwise.
+ */
+export declare function restoreLocalDwnEndpoint(agent: EnboxUserAgent, storage: StorageAdapter): Promise<boolean>;
+/**
+ * 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
+ * {@link requestLocalDwnDiscovery} for that.
+ *
+ * The discovery channels, from highest to lowest priority:
+ *
+ * 1. **URL fragment payload** — A `dwn://register` 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.
+ *
+ * @param agent - The running EnboxUserAgent.
+ * @param storage - The auth storage adapter.
+ * @param emitter - Optional event emitter for local DWN status notifications.
+ * @returns `true` if a local DWN endpoint was discovered and injected.
+ */
+export declare function applyLocalDwnDiscovery(agent: EnboxUserAgent, storage: StorageAdapter, emitter?: AuthEventEmitter): Promise<boolean>;
+/**
+ * Initiate the `dwn://register` flow by opening the register URL.
+ *
+ * This asks the operating system to route `dwn://register?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.
+ *
+ * @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
+ *   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.
+ * }
+ * ```
+ */
+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

@@ -0,0 +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"}