@formstr/signer 0.2.2 → 0.3.1

package/dist/{signer-BepGdtJs.d.cts → signer-CQyqBYxq.d.cts}

@@ -68,6 +68,197 @@ interface AndroidLoginResult {
     packageName: string;
 }
 declare function loginWithAndroidSigner(plugin: AndroidSignerPlugin, packageName?: string): Promise<AndroidLoginResult>;
+/**
+ * Normalize whatever a NIP-55 transport handed us in the pubkey slot into a
+ * `{ pubkey, npub }` pair. Accepts:
+ *   - a 32-byte lowercase hex pubkey (newer Amber builds return this),
+ *   - a bech32 `npub1…` (the original NIP-55 spec shape),
+ *   - a bech32 `nprofile1…`, which the web/clipboard transport may return.
+ * Throws a debuggable error for anything else, including the preview of
+ * what was actually received so the caller can triage.
+ *
+ * Shared by the Capacitor (`loginWithAndroidSigner`) and pure-web
+ * (`nip55Web.ts`) flows — both transports are NIP-55 and must agree on
+ * how identifiers normalize.
+ */
+declare function normalizeNip55Identifier(rawIdentifier: unknown): {
+    pubkey: string;
+    npub: string;
+};
+
+/**
+ * NIP-55 over the web, without a Capacitor/native bridge.
+ *
+ * A plain browser page cannot call an Android signer in the background, so
+ * this transport hands the OS a `nostrsigner` intent and then reads the
+ * result back from the **clipboard** once the user returns to the tab. It
+ * is the mechanism used by applesauce's `AmberClipboardSigner` and
+ * gitworkshop's "Use Amber" button; no package is named in the intent, so
+ * Android resolves it against whatever app registered the scheme — one
+ * installed signer opens directly, several show the "Open with" chooser.
+ *
+ * The alternative NIP-55 web path — `?callbackUrl=` — is not used here: it
+ * navigates the page away and back, which cannot be hidden behind a
+ * promise-returning {@link ActiveSigner}. Use NIP-46 when a persistent
+ * session is wanted; the spec recommends it for web clients.
+ *
+ * @see https://github.com/nostr-protocol/nips/blob/master/55.md
+ */
+/** Why the browser NIP-55 flow cannot run here. */
+type Nip55WebSupportReason = 'native' | 'not-android' | 'no-clipboard' | 'firefox';
+/**
+ * Whether the browser NIP-55 option should be shown, plus an advisory
+ * warning where it is known to be flaky.
+ *
+ * Visibility and warnings are deliberately separate, and nothing is
+ * hard-blocked. The option is hidden only where the mechanism cannot exist
+ * at all — a Capacitor native shell (the plugin path is strictly better)
+ * and non-Android platforms (the `nostrsigner` intent cannot resolve).
+ *
+ * Firefox for Android is **shown with a warning** rather than blocked. It
+ * advertises `readText` but never grants a persistent permission, so every
+ * read needs transient activation and the poll loop cannot complete —
+ * verified on an emulator (Firefox 125). We still let the user try, because
+ * blocking a browser outright is a worse failure than a warning, and
+ * browser behaviour changes.
+ */
+interface Nip55WebSupport {
+    /** Render the option at all. False in native shells and on non-Android. */
+    visible: boolean;
+    /**
+     * Advisory, non-blocking message to show beside the option. The flow
+     * remains attemptable; this only sets expectations.
+     */
+    warning?: string;
+    /** Machine-readable reason for the warning / hidden state. */
+    reason?: Nip55WebSupportReason;
+}
+interface Nip55WebTransport {
+    /**
+     * Whether this environment can run the intent + clipboard flow at all.
+     * The package's browser transport requires an Android user agent and the
+     * async clipboard API; anything else must fail loudly rather than open a
+     * dead intent.
+     */
+    isSupported(): boolean;
+    /**
+     * Richer form of {@link isSupported}: whether to *offer* the option and
+     * whether it actually works. Hosts should prefer this so they can show an
+     * explanatory hint (e.g. "does not work on Firefox") rather than hide a
+     * capability that other browsers on the same device do have.
+     */
+    supportStatus?(): Nip55WebSupport;
+    /** Hand the intent URI to the OS (a browser typically `window.open`s it). */
+    open(intent: string): void;
+    /** Read the current clipboard text. */
+    readClipboard(): Promise<string>;
+    /**
+     * Overwrite the clipboard. Used to plant a sentinel before opening the
+     * signer, so the result can be told apart from whatever the user had
+     * copied earlier. Best-effort — a failure just means we fall back to
+     * accepting the first non-empty read.
+     */
+    writeClipboard(text: string): Promise<void>;
+}
+interface Nip55WebOptions {
+    /**
+     * Environment bridge. Defaults to a browser implementation
+     * ({@link browserNip55Transport}). Tests inject a fake.
+     */
+    transport?: Nip55WebTransport;
+    /**
+     * Cached user pubkey. When supplied, {@link Nip55WebSigner.getPublicKey}
+     * returns it without a signer roundtrip — used on cold start to avoid a
+     * fresh `get_public_key` approval prompt for an already-paired account.
+     */
+    pubkey?: string;
+    /**
+     * How often to poll the clipboard while waiting for the signer app to
+     * return a result. Default 500ms.
+     *
+     * Polling, not events: on Android Chrome the return from the signer app
+     * fires **no** `visibilitychange`/`focus` event at all (the tab was never
+     * reported hidden), so an event-driven read simply never happens.
+     * `setInterval` keeps running while the tab is backgrounded, so polling
+     * is what actually observes the result.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Max time to wait for the signer app to return a result. A rejection is
+     * invisible over NIP-55 web (the app just never calls back), so without
+     * this a denied or abandoned request hangs forever. Default 120000ms;
+     * `0` disables the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Lifetime abort. Aborts the in-flight request and makes every future
+     * request reject immediately (rejections carry `name === 'AbortError'`,
+     * matching the NIP-46 flow).
+     *
+     * This is a property of the *signer*, not of one attempt. Do **not**
+     * pass a controller that is aborted once a login modal closes — that
+     * would leave the signer permanently unusable. To cancel a single
+     * pairing attempt, use {@link Signer.loginWithNip55Web}'s `signal`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Diagnostic sink for the intent/clipboard round-trip. The flow is hard
+     * to observe (it leaves the page and returns), so a host can pass a
+     * logger — e.g. to an on-screen list — to see what actually happened.
+     */
+    debug?: (message: string) => void;
+}
+/**
+ * Browser transport: `window.open` for the intent, `navigator.clipboard`
+ * for the result. Globals are read lazily so importing this module stays
+ * safe in Node.
+ *
+ * This transport is for a **plain browser only**. Inside a Capacitor
+ * native shell the same device has the real NIP-55 plugin, which supports
+ * every method and does not need the clipboard or a per-operation
+ * approval, so this flow is not offered there — a native host should use
+ * `loginWithAndroidSigner` instead.
+ */
+declare function browserNip55Transport(): Nip55WebTransport;
+/**
+ * {@link ActiveSigner} backed by any installed NIP-55 signer app, used from
+ * a plain (Android) browser via intents + clipboard.
+ *
+ * Every operation is a separate user approval — there is no background
+ * channel and no way to learn that the user rejected a request, so callers
+ * must impose their own timeout (the flow simply never resolves otherwise).
+ */
+declare class Nip55WebSigner implements ActiveSigner {
+    #private;
+    constructor(options?: Nip55WebOptions);
+    /** True when the configured transport can actually open a signer app. */
+    isSupported(): boolean;
+    /**
+     * Whether to offer the option and whether it works. Prefer this over
+     * {@link isSupported} so a host can surface `message` — notably the
+     * Firefox case, which is shown but cannot complete.
+     */
+    supportStatus(): Nip55WebSupport;
+    getPublicKey(): Promise<string>;
+    signEvent(event: EventTemplate): Promise<Event>;
+    nip04Encrypt(peerPubkey: string, plaintext: string): Promise<string>;
+    nip04Decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
+    nip44Encrypt(peerPubkey: string, plaintext: string): Promise<string>;
+    nip44Decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
+    /**
+     * Cancel any in-flight request and stop its clipboard poll. Subsequent
+     * operations still work — this is a teardown of live resources, not a
+     * permanent disable (the {@link Signer} calls it when replacing the
+     * active signer).
+     */
+    close(): void;
+    static getPublicKeyIntent(): string;
+    static signEventIntent(draft: object): string;
+    static nip04EncryptIntent(peerPubkey: string, plaintext: string): string;
+    static nip04DecryptIntent(peerPubkey: string, ciphertext: string): string;
+    static nip44EncryptIntent(peerPubkey: string, plaintext: string): string;
+    static nip44DecryptIntent(peerPubkey: string, ciphertext: string): string;
+}
 
 interface StorageAdapter {
     get(key: string): string | null;
@@ -82,8 +273,10 @@ declare function localStorageAdapter(prefix?: string): StorageAdapter;
  *  - `nip46`: NIP-46 remote signer (bunker URI or nostrconnect QR).
  *  - `ncryptsec`: NIP-49 encrypted nsec — decrypted into memory on unlock.
  *  - `android`: NIP-55 Android external signer app via a Capacitor plugin.
+ *  - `nip55-web`: NIP-55 Android external signer app from a plain browser,
+ *     via `nostrsigner` intents + clipboard (no native bridge).
  */
-type LoginMethod = 'extension' | 'nip46' | 'ncryptsec' | 'android';
+type LoginMethod = 'extension' | 'nip46' | 'ncryptsec' | 'android' | 'nip55-web';
 /**
  * Serialized account record persisted by the {@link StorageAdapter}.
  *
@@ -142,6 +335,14 @@ interface ActiveSigner {
     nip04Decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
     nip44Encrypt(peerPubkey: string, plaintext: string): Promise<string>;
     nip44Decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
+    /**
+     * Optional teardown, called by {@link Signer} when this signer is
+     * replaced — on a subsequent login/unlock, `switchAccount`, or
+     * `logout`. Implementations with live resources (an open bunker relay
+     * subscription, a clipboard poll, an in-flight request) should release
+     * them here. Omitted by stateless signers.
+     */
+    close?(): void | Promise<void>;
 }
 interface RelayMismatchInfo {
     userRelays: string[];
@@ -182,6 +383,33 @@ interface UnlockOptions {
      */
     pool?: AbstractSimplePool;
 }
+/**
+ * Options for {@link Signer.loginWithNip55Web} — the pure-browser NIP-55
+ * flow (Android intents + clipboard, no Capacitor bridge).
+ */
+interface Nip55WebLoginOptions {
+    /**
+     * Environment bridge for this call. Falls back to
+     * {@link SignerConfig.nip55WebTransport}, then to the browser default.
+     */
+    transport?: Nip55WebTransport;
+    /**
+     * How often to poll the clipboard while waiting for the signer app.
+     * Default 500ms. Polling is required because returning from the signer
+     * fires no foreground event on Android Chrome.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Max time to wait for the signer app. NIP-55 web has no rejection
+     * signal, so a denied/abandoned request never resolves without this.
+     * Default 120000ms; `0` disables it.
+     */
+    timeoutMs?: number;
+    /** Abort the pairing request (rejects with `name === 'AbortError'`). */
+    signal?: AbortSignal;
+    /** Diagnostic sink for the intent/clipboard round-trip. */
+    debug?: (message: string) => void;
+}
 interface NostrConnectOptions {
     relays: string[];
     metadata?: {
@@ -251,6 +479,12 @@ interface SignerConfig {
      * or `listAndroidSignerApps(plugin)`.
      */
     androidSignerPlugin?: AndroidSignerPlugin;
+    /**
+     * Environment bridge for the pure-web NIP-55 flow (Android browser,
+     * intents + clipboard). Defaults to a browser implementation; supply a
+     * stub in tests or non-browser hosts.
+     */
+    nip55WebTransport?: Nip55WebTransport;
 }
 
 /**
@@ -346,6 +580,52 @@ declare class Signer {
      * resolved to a package name, or the user denies the request.
      */
     loginWithAndroidSigner(options?: AndroidLoginOptions): Promise<StoredAccount>;
+    /**
+     * Whether `loginWithNip55Web` can run in this environment — a plain
+     * Android browser with async clipboard access. False in a Capacitor
+     * native shell (use {@link loginWithAndroidSigner} there), and on
+     * desktop/iOS/SSR.
+     *
+     * A **capability** check, not an availability one: there is no web API
+     * to detect an installed Android app, so this says nothing about
+     * whether a signer app is actually installed. Use it to hide the
+     * browser flow where it cannot work, not to promise that it will.
+     */
+    supportsNip55Web(transport?: Nip55WebTransport): boolean;
+    /**
+     * Whether to offer the browser NIP-55 option, plus an advisory `warning`
+     * where it is known to be flaky. Prefer this in UI code.
+     *
+     * Nothing here is a hard block. `visible: false` covers only environments
+     * where the mechanism cannot exist — a Capacitor native shell (the plugin
+     * path is better) and non-Android platforms (no `nostrsigner` handler).
+     * Firefox for Android is `visible: true` **with a warning**, because it
+     * advertises `readText` but never grants a persistent permission, so the
+     * poll loop usually cannot complete. Users are still allowed to try.
+     */
+    nip55WebSupport(transport?: Nip55WebTransport): Nip55WebSupport;
+    /**
+     * Sign in via a NIP-55 Android external signer (Amber, etc) **from a
+     * plain browser**, with no Capacitor/native bridge. Opens the installed
+     * signer app through a `nostrsigner` intent and reads the result back
+     * from the clipboard once the user returns to the tab. Because the
+     * intent names no package, this works with any app that registered the
+     * `nostrsigner` scheme — one opens directly, several show the Android
+     * "Open with" chooser.
+     *
+     * Not for native builds — inside a Capacitor shell use
+     * {@link loginWithAndroidSigner}, which needs no clipboard and no
+     * per-operation approval.
+     *
+     * Every operation is a separate approval, and a rejection is
+     * indistinguishable from the user simply not returning, so callers must
+     * impose their own timeout. Prefer NIP-46 when a persistent session is
+     * acceptable — the NIP-55 spec recommends it for web clients.
+     *
+     * @throws if the environment cannot run the flow (not Android, no async
+     * clipboard) or the signer returns an unexpected value.
+     */
+    loginWithNip55Web(options?: Nip55WebLoginOptions): Promise<StoredAccount>;
     /** Snapshot of every persisted account, in insertion order. */
     listAccounts(): StoredAccount[];
     /**
@@ -392,6 +672,10 @@ declare class Signer {
      *    {@link loginWithAndroidSigner} performs and that — on Amber —
      *    surfaces as a permission prompt every cold start.
      *
+     *  - `nip55-web`: constructs a {@link Nip55WebSigner} with the stored
+     *    `pubkey` cached. Like `android`, this opens no signer app during
+     *    unlock; the first sign/encrypt call is what prompts.
+     *
      *  - `ncryptsec`: returns `null`. There is no silent path — the user's
      *    passphrase isn't (and shouldn't be) persisted. The caller must
      *    drive the passphrase prompt and call {@link loginWithNcryptsec}.
@@ -428,4 +712,4 @@ declare class Signer {
 /** Convenience wrapper around `new Signer(config)`. */
 declare function createSigner(config?: SignerConfig): Signer;
 
-export { type ActiveSigner as A, type BunkerLoginOptions as B, type LoginMethod as L, type NostrConnectOptions as N, type RelayMismatchHandler as R, Signer as S, type UnlockOptions as U, type AndroidLoginOptions as a, type AndroidLoginResult as b, AndroidSigner as c, type AndroidSignerAppInfo as d, type AndroidSignerPlugin as e, type RelayMismatchInfo as f, type SignerConfig as g, type SignerEvent as h, type StorageAdapter as i, type StoredAccount as j, createSigner as k, localStorageAdapter as l, loginWithAndroidSigner as m };
+export { type ActiveSigner as A, type BunkerLoginOptions as B, type LoginMethod as L, type Nip55WebLoginOptions as N, type RelayMismatchHandler as R, Signer as S, type UnlockOptions as U, type AndroidLoginOptions as a, type AndroidLoginResult as b, AndroidSigner as c, type AndroidSignerAppInfo as d, type AndroidSignerPlugin as e, type Nip55WebOptions as f, Nip55WebSigner as g, type Nip55WebSupport as h, type Nip55WebSupportReason as i, type Nip55WebTransport as j, type NostrConnectOptions as k, type RelayMismatchInfo as l, type SignerConfig as m, type SignerEvent as n, type StorageAdapter as o, type StoredAccount as p, browserNip55Transport as q, createSigner as r, localStorageAdapter as s, loginWithAndroidSigner as t, normalizeNip55Identifier as u };

package/dist/{signer-BepGdtJs.d.ts → signer-CQyqBYxq.d.ts}

@@ -68,6 +68,197 @@ interface AndroidLoginResult {
     packageName: string;
 }
 declare function loginWithAndroidSigner(plugin: AndroidSignerPlugin, packageName?: string): Promise<AndroidLoginResult>;
+/**
+ * Normalize whatever a NIP-55 transport handed us in the pubkey slot into a
+ * `{ pubkey, npub }` pair. Accepts:
+ *   - a 32-byte lowercase hex pubkey (newer Amber builds return this),
+ *   - a bech32 `npub1…` (the original NIP-55 spec shape),
+ *   - a bech32 `nprofile1…`, which the web/clipboard transport may return.
+ * Throws a debuggable error for anything else, including the preview of
+ * what was actually received so the caller can triage.
+ *
+ * Shared by the Capacitor (`loginWithAndroidSigner`) and pure-web
+ * (`nip55Web.ts`) flows — both transports are NIP-55 and must agree on
+ * how identifiers normalize.
+ */
+declare function normalizeNip55Identifier(rawIdentifier: unknown): {
+    pubkey: string;
+    npub: string;
+};
+
+/**
+ * NIP-55 over the web, without a Capacitor/native bridge.
+ *
+ * A plain browser page cannot call an Android signer in the background, so
+ * this transport hands the OS a `nostrsigner` intent and then reads the
+ * result back from the **clipboard** once the user returns to the tab. It
+ * is the mechanism used by applesauce's `AmberClipboardSigner` and
+ * gitworkshop's "Use Amber" button; no package is named in the intent, so
+ * Android resolves it against whatever app registered the scheme — one
+ * installed signer opens directly, several show the "Open with" chooser.
+ *
+ * The alternative NIP-55 web path — `?callbackUrl=` — is not used here: it
+ * navigates the page away and back, which cannot be hidden behind a
+ * promise-returning {@link ActiveSigner}. Use NIP-46 when a persistent
+ * session is wanted; the spec recommends it for web clients.
+ *
+ * @see https://github.com/nostr-protocol/nips/blob/master/55.md
+ */
+/** Why the browser NIP-55 flow cannot run here. */
+type Nip55WebSupportReason = 'native' | 'not-android' | 'no-clipboard' | 'firefox';
+/**
+ * Whether the browser NIP-55 option should be shown, plus an advisory
+ * warning where it is known to be flaky.
+ *
+ * Visibility and warnings are deliberately separate, and nothing is
+ * hard-blocked. The option is hidden only where the mechanism cannot exist
+ * at all — a Capacitor native shell (the plugin path is strictly better)
+ * and non-Android platforms (the `nostrsigner` intent cannot resolve).
+ *
+ * Firefox for Android is **shown with a warning** rather than blocked. It
+ * advertises `readText` but never grants a persistent permission, so every
+ * read needs transient activation and the poll loop cannot complete —
+ * verified on an emulator (Firefox 125). We still let the user try, because
+ * blocking a browser outright is a worse failure than a warning, and
+ * browser behaviour changes.
+ */
+interface Nip55WebSupport {
+    /** Render the option at all. False in native shells and on non-Android. */
+    visible: boolean;
+    /**
+     * Advisory, non-blocking message to show beside the option. The flow
+     * remains attemptable; this only sets expectations.
+     */
+    warning?: string;
+    /** Machine-readable reason for the warning / hidden state. */
+    reason?: Nip55WebSupportReason;
+}
+interface Nip55WebTransport {
+    /**
+     * Whether this environment can run the intent + clipboard flow at all.
+     * The package's browser transport requires an Android user agent and the
+     * async clipboard API; anything else must fail loudly rather than open a
+     * dead intent.
+     */
+    isSupported(): boolean;
+    /**
+     * Richer form of {@link isSupported}: whether to *offer* the option and
+     * whether it actually works. Hosts should prefer this so they can show an
+     * explanatory hint (e.g. "does not work on Firefox") rather than hide a
+     * capability that other browsers on the same device do have.
+     */
+    supportStatus?(): Nip55WebSupport;
+    /** Hand the intent URI to the OS (a browser typically `window.open`s it). */
+    open(intent: string): void;
+    /** Read the current clipboard text. */
+    readClipboard(): Promise<string>;
+    /**
+     * Overwrite the clipboard. Used to plant a sentinel before opening the
+     * signer, so the result can be told apart from whatever the user had
+     * copied earlier. Best-effort — a failure just means we fall back to
+     * accepting the first non-empty read.
+     */
+    writeClipboard(text: string): Promise<void>;
+}
+interface Nip55WebOptions {
+    /**
+     * Environment bridge. Defaults to a browser implementation
+     * ({@link browserNip55Transport}). Tests inject a fake.
+     */
+    transport?: Nip55WebTransport;
+    /**
+     * Cached user pubkey. When supplied, {@link Nip55WebSigner.getPublicKey}
+     * returns it without a signer roundtrip — used on cold start to avoid a
+     * fresh `get_public_key` approval prompt for an already-paired account.
+     */
+    pubkey?: string;
+    /**
+     * How often to poll the clipboard while waiting for the signer app to
+     * return a result. Default 500ms.
+     *
+     * Polling, not events: on Android Chrome the return from the signer app
+     * fires **no** `visibilitychange`/`focus` event at all (the tab was never
+     * reported hidden), so an event-driven read simply never happens.
+     * `setInterval` keeps running while the tab is backgrounded, so polling
+     * is what actually observes the result.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Max time to wait for the signer app to return a result. A rejection is
+     * invisible over NIP-55 web (the app just never calls back), so without
+     * this a denied or abandoned request hangs forever. Default 120000ms;
+     * `0` disables the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Lifetime abort. Aborts the in-flight request and makes every future
+     * request reject immediately (rejections carry `name === 'AbortError'`,
+     * matching the NIP-46 flow).
+     *
+     * This is a property of the *signer*, not of one attempt. Do **not**
+     * pass a controller that is aborted once a login modal closes — that
+     * would leave the signer permanently unusable. To cancel a single
+     * pairing attempt, use {@link Signer.loginWithNip55Web}'s `signal`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Diagnostic sink for the intent/clipboard round-trip. The flow is hard
+     * to observe (it leaves the page and returns), so a host can pass a
+     * logger — e.g. to an on-screen list — to see what actually happened.
+     */
+    debug?: (message: string) => void;
+}
+/**
+ * Browser transport: `window.open` for the intent, `navigator.clipboard`
+ * for the result. Globals are read lazily so importing this module stays
+ * safe in Node.
+ *
+ * This transport is for a **plain browser only**. Inside a Capacitor
+ * native shell the same device has the real NIP-55 plugin, which supports
+ * every method and does not need the clipboard or a per-operation
+ * approval, so this flow is not offered there — a native host should use
+ * `loginWithAndroidSigner` instead.
+ */
+declare function browserNip55Transport(): Nip55WebTransport;
+/**
+ * {@link ActiveSigner} backed by any installed NIP-55 signer app, used from
+ * a plain (Android) browser via intents + clipboard.
+ *
+ * Every operation is a separate user approval — there is no background
+ * channel and no way to learn that the user rejected a request, so callers
+ * must impose their own timeout (the flow simply never resolves otherwise).
+ */
+declare class Nip55WebSigner implements ActiveSigner {
+    #private;
+    constructor(options?: Nip55WebOptions);
+    /** True when the configured transport can actually open a signer app. */
+    isSupported(): boolean;
+    /**
+     * Whether to offer the option and whether it works. Prefer this over
+     * {@link isSupported} so a host can surface `message` — notably the
+     * Firefox case, which is shown but cannot complete.
+     */
+    supportStatus(): Nip55WebSupport;
+    getPublicKey(): Promise<string>;
+    signEvent(event: EventTemplate): Promise<Event>;
+    nip04Encrypt(peerPubkey: string, plaintext: string): Promise<string>;
+    nip04Decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
+    nip44Encrypt(peerPubkey: string, plaintext: string): Promise<string>;
+    nip44Decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
+    /**
+     * Cancel any in-flight request and stop its clipboard poll. Subsequent
+     * operations still work — this is a teardown of live resources, not a
+     * permanent disable (the {@link Signer} calls it when replacing the
+     * active signer).
+     */
+    close(): void;
+    static getPublicKeyIntent(): string;
+    static signEventIntent(draft: object): string;
+    static nip04EncryptIntent(peerPubkey: string, plaintext: string): string;
+    static nip04DecryptIntent(peerPubkey: string, ciphertext: string): string;
+    static nip44EncryptIntent(peerPubkey: string, plaintext: string): string;
+    static nip44DecryptIntent(peerPubkey: string, ciphertext: string): string;
+}
 
 interface StorageAdapter {
     get(key: string): string | null;
@@ -82,8 +273,10 @@ declare function localStorageAdapter(prefix?: string): StorageAdapter;
  *  - `nip46`: NIP-46 remote signer (bunker URI or nostrconnect QR).
  *  - `ncryptsec`: NIP-49 encrypted nsec — decrypted into memory on unlock.
  *  - `android`: NIP-55 Android external signer app via a Capacitor plugin.
+ *  - `nip55-web`: NIP-55 Android external signer app from a plain browser,
+ *     via `nostrsigner` intents + clipboard (no native bridge).
  */
-type LoginMethod = 'extension' | 'nip46' | 'ncryptsec' | 'android';
+type LoginMethod = 'extension' | 'nip46' | 'ncryptsec' | 'android' | 'nip55-web';
 /**
  * Serialized account record persisted by the {@link StorageAdapter}.
  *
@@ -142,6 +335,14 @@ interface ActiveSigner {
     nip04Decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
     nip44Encrypt(peerPubkey: string, plaintext: string): Promise<string>;
     nip44Decrypt(peerPubkey: string, ciphertext: string): Promise<string>;
+    /**
+     * Optional teardown, called by {@link Signer} when this signer is
+     * replaced — on a subsequent login/unlock, `switchAccount`, or
+     * `logout`. Implementations with live resources (an open bunker relay
+     * subscription, a clipboard poll, an in-flight request) should release
+     * them here. Omitted by stateless signers.
+     */
+    close?(): void | Promise<void>;
 }
 interface RelayMismatchInfo {
     userRelays: string[];
@@ -182,6 +383,33 @@ interface UnlockOptions {
      */
     pool?: AbstractSimplePool;
 }
+/**
+ * Options for {@link Signer.loginWithNip55Web} — the pure-browser NIP-55
+ * flow (Android intents + clipboard, no Capacitor bridge).
+ */
+interface Nip55WebLoginOptions {
+    /**
+     * Environment bridge for this call. Falls back to
+     * {@link SignerConfig.nip55WebTransport}, then to the browser default.
+     */
+    transport?: Nip55WebTransport;
+    /**
+     * How often to poll the clipboard while waiting for the signer app.
+     * Default 500ms. Polling is required because returning from the signer
+     * fires no foreground event on Android Chrome.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Max time to wait for the signer app. NIP-55 web has no rejection
+     * signal, so a denied/abandoned request never resolves without this.
+     * Default 120000ms; `0` disables it.
+     */
+    timeoutMs?: number;
+    /** Abort the pairing request (rejects with `name === 'AbortError'`). */
+    signal?: AbortSignal;
+    /** Diagnostic sink for the intent/clipboard round-trip. */
+    debug?: (message: string) => void;
+}
 interface NostrConnectOptions {
     relays: string[];
     metadata?: {
@@ -251,6 +479,12 @@ interface SignerConfig {
      * or `listAndroidSignerApps(plugin)`.
      */
     androidSignerPlugin?: AndroidSignerPlugin;
+    /**
+     * Environment bridge for the pure-web NIP-55 flow (Android browser,
+     * intents + clipboard). Defaults to a browser implementation; supply a
+     * stub in tests or non-browser hosts.
+     */
+    nip55WebTransport?: Nip55WebTransport;
 }
 
 /**
@@ -346,6 +580,52 @@ declare class Signer {
      * resolved to a package name, or the user denies the request.
      */
     loginWithAndroidSigner(options?: AndroidLoginOptions): Promise<StoredAccount>;
+    /**
+     * Whether `loginWithNip55Web` can run in this environment — a plain
+     * Android browser with async clipboard access. False in a Capacitor
+     * native shell (use {@link loginWithAndroidSigner} there), and on
+     * desktop/iOS/SSR.
+     *
+     * A **capability** check, not an availability one: there is no web API
+     * to detect an installed Android app, so this says nothing about
+     * whether a signer app is actually installed. Use it to hide the
+     * browser flow where it cannot work, not to promise that it will.
+     */
+    supportsNip55Web(transport?: Nip55WebTransport): boolean;
+    /**
+     * Whether to offer the browser NIP-55 option, plus an advisory `warning`
+     * where it is known to be flaky. Prefer this in UI code.
+     *
+     * Nothing here is a hard block. `visible: false` covers only environments
+     * where the mechanism cannot exist — a Capacitor native shell (the plugin
+     * path is better) and non-Android platforms (no `nostrsigner` handler).
+     * Firefox for Android is `visible: true` **with a warning**, because it
+     * advertises `readText` but never grants a persistent permission, so the
+     * poll loop usually cannot complete. Users are still allowed to try.
+     */
+    nip55WebSupport(transport?: Nip55WebTransport): Nip55WebSupport;
+    /**
+     * Sign in via a NIP-55 Android external signer (Amber, etc) **from a
+     * plain browser**, with no Capacitor/native bridge. Opens the installed
+     * signer app through a `nostrsigner` intent and reads the result back
+     * from the clipboard once the user returns to the tab. Because the
+     * intent names no package, this works with any app that registered the
+     * `nostrsigner` scheme — one opens directly, several show the Android
+     * "Open with" chooser.
+     *
+     * Not for native builds — inside a Capacitor shell use
+     * {@link loginWithAndroidSigner}, which needs no clipboard and no
+     * per-operation approval.
+     *
+     * Every operation is a separate approval, and a rejection is
+     * indistinguishable from the user simply not returning, so callers must
+     * impose their own timeout. Prefer NIP-46 when a persistent session is
+     * acceptable — the NIP-55 spec recommends it for web clients.
+     *
+     * @throws if the environment cannot run the flow (not Android, no async
+     * clipboard) or the signer returns an unexpected value.
+     */
+    loginWithNip55Web(options?: Nip55WebLoginOptions): Promise<StoredAccount>;
     /** Snapshot of every persisted account, in insertion order. */
     listAccounts(): StoredAccount[];
     /**
@@ -392,6 +672,10 @@ declare class Signer {
      *    {@link loginWithAndroidSigner} performs and that — on Amber —
      *    surfaces as a permission prompt every cold start.
      *
+     *  - `nip55-web`: constructs a {@link Nip55WebSigner} with the stored
+     *    `pubkey` cached. Like `android`, this opens no signer app during
+     *    unlock; the first sign/encrypt call is what prompts.
+     *
      *  - `ncryptsec`: returns `null`. There is no silent path — the user's
      *    passphrase isn't (and shouldn't be) persisted. The caller must
      *    drive the passphrase prompt and call {@link loginWithNcryptsec}.
@@ -428,4 +712,4 @@ declare class Signer {
 /** Convenience wrapper around `new Signer(config)`. */
 declare function createSigner(config?: SignerConfig): Signer;
 
-export { type ActiveSigner as A, type BunkerLoginOptions as B, type LoginMethod as L, type NostrConnectOptions as N, type RelayMismatchHandler as R, Signer as S, type UnlockOptions as U, type AndroidLoginOptions as a, type AndroidLoginResult as b, AndroidSigner as c, type AndroidSignerAppInfo as d, type AndroidSignerPlugin as e, type RelayMismatchInfo as f, type SignerConfig as g, type SignerEvent as h, type StorageAdapter as i, type StoredAccount as j, createSigner as k, localStorageAdapter as l, loginWithAndroidSigner as m };
+export { type ActiveSigner as A, type BunkerLoginOptions as B, type LoginMethod as L, type Nip55WebLoginOptions as N, type RelayMismatchHandler as R, Signer as S, type UnlockOptions as U, type AndroidLoginOptions as a, type AndroidLoginResult as b, AndroidSigner as c, type AndroidSignerAppInfo as d, type AndroidSignerPlugin as e, type Nip55WebOptions as f, Nip55WebSigner as g, type Nip55WebSupport as h, type Nip55WebSupportReason as i, type Nip55WebTransport as j, type NostrConnectOptions as k, type RelayMismatchInfo as l, type SignerConfig as m, type SignerEvent as n, type StorageAdapter as o, type StoredAccount as p, browserNip55Transport as q, createSigner as r, localStorageAdapter as s, loginWithAndroidSigner as t, normalizeNip55Identifier as u };