@formstr/signer 0.2.2 → 0.3.1

package/dist/index.cjs

@@ -24,7 +24,9 @@ __export(src_exports, {
   BunkerSigner: () => BunkerSigner,
   ExtensionSigner: () => ExtensionSigner,
   LocalSigner: () => LocalSigner,
+  Nip55WebSigner: () => Nip55WebSigner,
   Signer: () => Signer,
+  browserNip55Transport: () => browserNip55Transport,
   bytesToHex: () => bytesToHex,
   connectWithBunkerUri: () => connectWithBunkerUri,
   createSigner: () => createSigner,
@@ -35,12 +37,13 @@ __export(src_exports, {
   hexToBytes: () => hexToBytes,
   initiateNostrConnect: () => initiateNostrConnect,
   localStorageAdapter: () => localStorageAdapter,
-  loginWithAndroidSigner: () => loginWithAndroidSigner
+  loginWithAndroidSigner: () => loginWithAndroidSigner,
+  normalizeNip55Identifier: () => normalizeNip55Identifier
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/core/signer.ts
-var import_nostr_tools5 = require("nostr-tools");
+var import_nostr_tools6 = require("nostr-tools");
 var import_nip462 = require("nostr-tools/nip46");
 
 // src/core/storage.ts
@@ -400,7 +403,7 @@ async function loginWithAndroidSigner(plugin, packageName) {
       "@formstr/signer: android signer did not return a package name and none was supplied"
     );
   }
-  const { pubkey, npub } = normalizeAndroidIdentifier(rawIdentifier);
+  const { pubkey, npub } = normalizeNip55Identifier(rawIdentifier);
   return {
     signer: new AndroidSigner(plugin, resolvedPackage, npub, pubkey),
     pubkey,
@@ -408,7 +411,7 @@ async function loginWithAndroidSigner(plugin, packageName) {
     packageName: resolvedPackage
   };
 }
-function normalizeAndroidIdentifier(rawIdentifier) {
+function normalizeNip55Identifier(rawIdentifier) {
   if (typeof rawIdentifier === "string" && HEX_PUBKEY_RE.test(rawIdentifier)) {
     const pubkey = rawIdentifier.toLowerCase();
     return { pubkey, npub: import_nostr_tools4.nip19.npubEncode(pubkey) };
@@ -418,16 +421,301 @@ function normalizeAndroidIdentifier(rawIdentifier) {
     decoded = import_nostr_tools4.nip19.decode(rawIdentifier);
   } catch (e) {
     throw new Error(
-      `@formstr/signer: android signer returned an undecodable identifier (got ${describeIdentifier(rawIdentifier)}): ${e.message}`
+      `@formstr/signer: signer returned an undecodable identifier (got ${describeIdentifier(rawIdentifier)}): ${e.message}`
     );
   }
-  if (decoded.type !== "npub") {
+  if (decoded.type === "npub") {
+    return { pubkey: decoded.data, npub: rawIdentifier };
+  }
+  if (decoded.type === "nprofile") {
+    const pubkey = decoded.data.pubkey;
+    return { pubkey, npub: import_nostr_tools4.nip19.npubEncode(pubkey) };
+  }
+  throw new Error(
+    `@formstr/signer: signer returned a non-pubkey identifier (type=${decoded.type}, got ${describeIdentifier(rawIdentifier)})`
+  );
+}
+
+// src/nip55Web.ts
+var import_nostr_tools5 = require("nostr-tools");
+var DEFAULT_POLL_INTERVAL_MS = 500;
+var DEFAULT_TIMEOUT_MS = 12e4;
+var sentinelCounter = 0;
+function makeSentinel() {
+  sentinelCounter += 1;
+  return `__formstr_nip55_sentinel_${Date.now()}_${sentinelCounter}__`;
+}
+function abortError() {
+  const error = new Error("@formstr/signer: NIP-55 request aborted");
+  error.name = "AbortError";
+  return error;
+}
+function isNativeShell() {
+  const cap = globalThis.Capacitor;
+  return typeof cap?.isNativePlatform === "function" && cap.isNativePlatform();
+}
+function isGeckoBrowser() {
+  const ua = navigator.userAgent;
+  return /Firefox\/|FxiOS\/|Focus\/|Gecko\//.test(ua);
+}
+function browserNip55Transport() {
+  return {
+    supportStatus() {
+      if (typeof navigator === "undefined") {
+        return { visible: false, reason: "not-android" };
+      }
+      if (isNativeShell()) {
+        return { visible: false, reason: "native" };
+      }
+      if (!/Android/i.test(navigator.userAgent)) {
+        return { visible: false, reason: "not-android" };
+      }
+      if (typeof navigator.clipboard?.readText !== "function") {
+        return { visible: false, reason: "no-clipboard" };
+      }
+      if (isGeckoBrowser()) {
+        return {
+          visible: true,
+          reason: "firefox",
+          warning: "May not work in Firefox for Android \u2014 the clipboard usually cannot be read automatically. If it hangs, try Chrome, Brave, or the Android app."
+        };
+      }
+      return { visible: true };
+    },
+    isSupported() {
+      return this.supportStatus().visible;
+    },
+    open(intent) {
+      window.open(intent, "_blank");
+    },
+    readClipboard() {
+      return navigator.clipboard.readText();
+    },
+    writeClipboard(text) {
+      return navigator.clipboard.writeText(text);
+    }
+  };
+}
+var Nip55WebSigner = class _Nip55WebSigner {
+  #transport;
+  #pollIntervalMs;
+  #timeoutMs;
+  #signal;
+  #debug;
+  #pending = null;
+  #pubkey = null;
+  constructor(options = {}) {
+    this.#transport = options.transport ?? browserNip55Transport();
+    this.#pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#signal = options.signal;
+    this.#debug = options.debug;
+    this.#pubkey = options.pubkey ?? null;
+  }
+  #log(message) {
+    this.#debug?.(message);
+  }
+  /** True when the configured transport can actually open a signer app. */
+  isSupported() {
+    return this.#transport.isSupported();
+  }
+  /**
+   * 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() {
+    const status = this.#transport.supportStatus;
+    if (status) return status.call(this.#transport);
+    return { visible: this.#transport.isSupported() };
+  }
+  async getPublicKey() {
+    if (this.#pubkey !== null) return this.#pubkey;
+    this.#checkSupport();
+    const raw = await this.#request(_Nip55WebSigner.getPublicKeyIntent());
+    const { pubkey } = normalizeNip55Identifier(raw);
+    this.#pubkey = pubkey;
+    return pubkey;
+  }
+  async signEvent(event) {
+    this.#checkSupport();
+    const pubkey = this.#pubkey ?? await this.getPublicKey();
+    const unsigned = { ...event, pubkey };
+    const draftWithId = { ...unsigned, id: (0, import_nostr_tools5.getEventHash)(unsigned) };
+    const sig = (await this.#request(_Nip55WebSigner.signEventIntent(draftWithId))).trim();
+    if (!/^[0-9a-f]{128}$/i.test(sig)) {
+      throw new Error(
+        "@formstr/signer: NIP-55 signer did not return a hex signature"
+      );
+    }
+    const signed = { ...draftWithId, sig: sig.toLowerCase() };
+    if (!(0, import_nostr_tools5.verifyEvent)(signed)) {
+      throw new Error("@formstr/signer: NIP-55 signer returned an invalid signature");
+    }
+    return signed;
+  }
+  async nip04Encrypt(peerPubkey, plaintext) {
+    this.#checkSupport();
+    return this.#request(_Nip55WebSigner.nip04EncryptIntent(peerPubkey, plaintext));
+  }
+  async nip04Decrypt(peerPubkey, ciphertext) {
+    this.#checkSupport();
+    return this.#request(_Nip55WebSigner.nip04DecryptIntent(peerPubkey, ciphertext));
+  }
+  async nip44Encrypt(peerPubkey, plaintext) {
+    this.#checkSupport();
+    return this.#request(_Nip55WebSigner.nip44EncryptIntent(peerPubkey, plaintext));
+  }
+  async nip44Decrypt(peerPubkey, ciphertext) {
+    this.#checkSupport();
+    return this.#request(_Nip55WebSigner.nip44DecryptIntent(peerPubkey, ciphertext));
+  }
+  /**
+   * 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() {
+    if (this.#pending) {
+      const pending = this.#pending;
+      this.#settle();
+      pending.reject(abortError());
+    }
+  }
+  #checkSupport() {
+    const { visible, reason } = this.supportStatus();
+    if (visible) return;
+    if (reason === "native") {
+      throw new Error(
+        "@formstr/signer: the browser NIP-55 flow is not for native builds \u2014 use loginWithAndroidSigner() with the Capacitor plugin instead"
+      );
+    }
     throw new Error(
-      `@formstr/signer: android signer returned a non-npub identifier (type=${decoded.type}, got ${describeIdentifier(rawIdentifier)})`
+      "@formstr/signer: NIP-55 web signing requires an Android browser with clipboard access (a signer app registering the `nostrsigner` scheme must be installed)"
     );
   }
-  return { pubkey: decoded.data, npub: rawIdentifier };
-}
+  /** One poll tick: read the clipboard and settle if the signer answered. */
+  #poll = async (pending) => {
+    let text;
+    try {
+      text = await this.#transport.readClipboard();
+    } catch (error) {
+      this.#log(`clipboard read failed: ${error.message}`);
+      return;
+    }
+    if (this.#pending !== pending) return;
+    const trimmed = text.trim();
+    if (trimmed.length === 0) return;
+    if (pending.sentinel !== null && trimmed === pending.sentinel) return;
+    this.#log(`clipboard result (${trimmed.length} chars)`);
+    this.#settle();
+    pending.resolve(trimmed);
+  };
+  #request(intent) {
+    this.#checkAborted();
+    this.#cancelPending();
+    return new Promise((resolve, reject) => {
+      const pending = {
+        resolve,
+        reject,
+        sentinel: null,
+        poll: null,
+        timer: null,
+        onAbort: null
+      };
+      this.#pending = pending;
+      if (this.#signal) {
+        const onAbort = () => this.#fail(pending, abortError());
+        this.#signal.addEventListener("abort", onAbort);
+        pending.onAbort = onAbort;
+      }
+      if (this.#timeoutMs > 0) {
+        pending.timer = setTimeout(() => {
+          this.#fail(
+            pending,
+            new Error(
+              `@formstr/signer: NIP-55 request timed out after ${this.#timeoutMs}ms (the signer app never returned a result)`
+            )
+          );
+        }, this.#timeoutMs);
+      }
+      void (async () => {
+        try {
+          const sentinel = makeSentinel();
+          await this.#transport.writeClipboard(sentinel);
+          if (this.#pending === pending) pending.sentinel = sentinel;
+          this.#log("planted clipboard sentinel");
+        } catch (error) {
+          this.#log(`sentinel write failed: ${error.message}`);
+        }
+        if (this.#pending !== pending) return;
+        try {
+          this.#log(`opening signer app: ${intent.slice(0, 80)}\u2026`);
+          this.#transport.open(intent);
+        } catch (error) {
+          this.#fail(pending, error);
+          return;
+        }
+        pending.poll = setInterval(() => {
+          void this.#poll(pending);
+        }, this.#pollIntervalMs);
+      })();
+    });
+  }
+  /**
+   * Reject the current request. Every caller is cleared on settle — the
+   * timeout timer and abort listener are removed, and `open()` is
+   * synchronous — so `pending` is always the active request here.
+   */
+  #fail(pending, error) {
+    this.#settle();
+    pending.reject(error);
+  }
+  #settle() {
+    const pending = this.#pending;
+    this.#pending = null;
+    if (pending?.poll) clearInterval(pending.poll);
+    if (pending?.timer) clearTimeout(pending.timer);
+    if (pending?.onAbort && this.#signal) {
+      this.#signal.removeEventListener("abort", pending.onAbort);
+    }
+  }
+  #cancelPending() {
+    if (!this.#pending) return;
+    const pending = this.#pending;
+    this.#settle();
+    pending.reject(new Error("@formstr/signer: NIP-55 request superseded"));
+  }
+  #checkAborted() {
+    if (this.#signal?.aborted) throw abortError();
+  }
+  static getPublicKeyIntent() {
+    return "intent:#Intent;scheme=nostrsigner;S.compressionType=none;S.returnType=signature;S.type=get_public_key;end";
+  }
+  static signEventIntent(draft) {
+    return `intent:${encodeURIComponent(
+      JSON.stringify(draft)
+    )}#Intent;scheme=nostrsigner;S.compressionType=none;S.returnType=signature;S.type=sign_event;end`;
+  }
+  static nip04EncryptIntent(peerPubkey, plaintext) {
+    return _Nip55WebSigner.#cryptoIntent("nip04_encrypt", peerPubkey, plaintext);
+  }
+  static nip04DecryptIntent(peerPubkey, ciphertext) {
+    return _Nip55WebSigner.#cryptoIntent("nip04_decrypt", peerPubkey, ciphertext);
+  }
+  static nip44EncryptIntent(peerPubkey, plaintext) {
+    return _Nip55WebSigner.#cryptoIntent("nip44_encrypt", peerPubkey, plaintext);
+  }
+  static nip44DecryptIntent(peerPubkey, ciphertext) {
+    return _Nip55WebSigner.#cryptoIntent("nip44_decrypt", peerPubkey, ciphertext);
+  }
+  static #cryptoIntent(type, peerPubkey, payload) {
+    return `intent:${encodeURIComponent(
+      payload
+    )}#Intent;scheme=nostrsigner;S.pubKey=${peerPubkey};S.compressionType=none;S.returnType=signature;S.type=${type};end`;
+  }
+};
 
 // src/core/signer.ts
 var ACCOUNTS_KEY = "accounts";
@@ -435,6 +723,7 @@ var ACTIVE_KEY = "active-pubkey";
 var Signer = class {
   #storage;
   #defaultAndroidPlugin;
+  #nip55WebTransport;
   #appMetadata;
   #accounts = [];
   #activePubkey = null;
@@ -443,6 +732,7 @@ var Signer = class {
   constructor(config = {}) {
     this.#storage = config.storage ?? localStorageAdapter(config.storageKeyPrefix);
     this.#defaultAndroidPlugin = config.androidSignerPlugin;
+    this.#nip55WebTransport = config.nip55WebTransport;
     this.#appMetadata = {
       name: config.appName,
       url: config.appUrl,
@@ -476,8 +766,28 @@ var Signer = class {
     else this.#accounts.push(account);
     this.#persistAccounts();
   }
+  /**
+   * Release the currently-held signer, if it has a `close()`. Called
+   * whenever the active signer is replaced or cleared so live resources
+   * (bunker subscriptions, `visibilitychange` listeners, in-flight NIP-55
+   * requests) don't outlive the session. Errors are swallowed — teardown
+   * must never block a login/switch/logout.
+   */
+  #closeActiveSigner() {
+    const signer = this.#activeSigner;
+    if (!signer?.close) return;
+    try {
+      const result = signer.close();
+      if (result && typeof result.catch === "function") {
+        result.catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
   #setActive(account, signer) {
     const wasDifferent = this.#activePubkey !== null && this.#activePubkey !== account.pubkey;
+    if (this.#activeSigner !== signer) this.#closeActiveSigner();
     this.#activePubkey = account.pubkey;
     this.#activeSigner = signer;
     this.#persistActive();
@@ -519,8 +829,8 @@ var Signer = class {
     if (!ncryptsec) throw new Error("loginWithNcryptsec: ncryptsec required");
     if (!passphrase) throw new Error("loginWithNcryptsec: passphrase required");
     const secretKey = decryptNcryptsec(ncryptsec, passphrase);
-    const pubkey = (0, import_nostr_tools5.getPublicKey)(secretKey);
-    const npub = import_nostr_tools5.nip19.npubEncode(pubkey);
+    const pubkey = (0, import_nostr_tools6.getPublicKey)(secretKey);
+    const npub = import_nostr_tools6.nip19.npubEncode(pubkey);
     const account = { npub, pubkey, method: "ncryptsec", ncryptsec };
     this.#upsertAccount(account);
     this.#setActive(account, new LocalSigner(secretKey));
@@ -535,7 +845,7 @@ var Signer = class {
   async loginWithExtension() {
     const extension = new ExtensionSigner();
     const pubkey = await extension.getPublicKey();
-    const npub = import_nostr_tools5.nip19.npubEncode(pubkey);
+    const npub = import_nostr_tools6.nip19.npubEncode(pubkey);
     const account = { npub, pubkey, method: "extension" };
     this.#upsertAccount(account);
     this.#setActive(account, extension);
@@ -552,7 +862,7 @@ var Signer = class {
    */
   async loginWithBunkerUri(uri, options = {}) {
     const result = await connectWithBunkerUri(uri, options);
-    const npub = import_nostr_tools5.nip19.npubEncode(result.pubkey);
+    const npub = import_nostr_tools6.nip19.npubEncode(result.pubkey);
     const account = {
       npub,
       pubkey: result.pubkey,
@@ -604,7 +914,7 @@ var Signer = class {
     });
     options.onUri(init.uri);
     const result = await init.complete;
-    const npub = import_nostr_tools5.nip19.npubEncode(result.pubkey);
+    const npub = import_nostr_tools6.nip19.npubEncode(result.pubkey);
     const account = {
       npub,
       pubkey: result.pubkey,
@@ -669,6 +979,84 @@ var Signer = class {
     this.#setActive(account, result.signer);
     return account;
   }
+  /**
+   * 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) {
+    return this.nip55WebSupport(transport).visible;
+  }
+  /**
+   * 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) {
+    const t = transport ?? this.#nip55WebTransport ?? browserNip55Transport();
+    if (t.supportStatus) return t.supportStatus();
+    return { visible: t.isSupported() };
+  }
+  /**
+   * 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.
+   */
+  async loginWithNip55Web(options = {}) {
+    const transport = options.transport ?? this.#nip55WebTransport;
+    const pairing = new Nip55WebSigner({
+      transport,
+      pollIntervalMs: options.pollIntervalMs,
+      timeoutMs: options.timeoutMs,
+      signal: options.signal,
+      debug: options.debug
+    });
+    const pubkey = await pairing.getPublicKey();
+    const signer = new Nip55WebSigner({
+      transport,
+      pollIntervalMs: options.pollIntervalMs,
+      timeoutMs: options.timeoutMs,
+      pubkey,
+      debug: options.debug
+    });
+    const npub = import_nostr_tools6.nip19.npubEncode(pubkey);
+    const account = {
+      npub,
+      pubkey,
+      method: "nip55-web"
+    };
+    this.#upsertAccount(account);
+    this.#setActive(account, signer);
+    return account;
+  }
   /** Snapshot of every persisted account, in insertion order. */
   listAccounts() {
     return [...this.#accounts];
@@ -722,6 +1110,10 @@ var Signer = class {
    *    {@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}.
@@ -770,6 +1162,14 @@ var Signer = class {
         this.#setActive(account, signer);
         return signer;
       }
+      case "nip55-web": {
+        const signer = new Nip55WebSigner({
+          transport: this.#nip55WebTransport,
+          pubkey: account.pubkey
+        });
+        this.#setActive(account, signer);
+        return signer;
+      }
       case "ncryptsec":
         return null;
     }
@@ -784,6 +1184,7 @@ var Signer = class {
   async switchAccount(pubkey) {
     const account = this.#accounts.find((a) => a.pubkey === pubkey);
     if (!account) throw new Error(`switchAccount: no account for pubkey ${pubkey}`);
+    this.#closeActiveSigner();
     this.#activePubkey = pubkey;
     this.#activeSigner = null;
     this.#persistActive();
@@ -800,6 +1201,7 @@ var Signer = class {
     this.#accounts = this.#accounts.filter((a) => a.pubkey !== target);
     this.#persistAccounts();
     if (this.#activePubkey === target) {
+      this.#closeActiveSigner();
       this.#activePubkey = null;
       this.#activeSigner = null;
       this.#persistActive();
@@ -827,7 +1229,9 @@ function createSigner(config = {}) {
   BunkerSigner,
   ExtensionSigner,
   LocalSigner,
+  Nip55WebSigner,
   Signer,
+  browserNip55Transport,
   bytesToHex,
   connectWithBunkerUri,
   createSigner,
@@ -838,6 +1242,7 @@ function createSigner(config = {}) {
   hexToBytes,
   initiateNostrConnect,
   localStorageAdapter,
-  loginWithAndroidSigner
+  loginWithAndroidSigner,
+  normalizeNip55Identifier
 });
 //# sourceMappingURL=index.cjs.map