@formstr/signer 0.1.0

package/dist/signer-DiKj4PR7.d.ts

@@ -0,0 +1,377 @@
+import { EventTemplate, Event } from 'nostr-tools';
+import { AbstractSimplePool } from 'nostr-tools/abstract-pool';
+
+/**
+ * Subset of `nostr-signer-capacitor-plugin`'s exported `NostrSignerPlugin`
+ * that we depend on. Signatures intentionally mirror that library
+ * (positional args, per-call `packageName`) so the real plugin is
+ * structurally assignable here — and any mock written against this
+ * interface is a faithful stand-in. The conformance is enforced by a
+ * compile-time guard in `tests/helpers/mockAndroidPlugin.ts`.
+ */
+interface AndroidSignerAppInfo {
+    name: string;
+    packageName: string;
+    iconUrl?: string;
+}
+interface AndroidSignerPlugin {
+    setPackageName(packageName: string): Promise<void>;
+    getInstalledSignerApps(): Promise<{
+        apps: AndroidSignerAppInfo[];
+    }>;
+    getPublicKey(packageName?: string, permissions?: string): Promise<{
+        npub: string;
+        package: string;
+    }>;
+    signEvent(packageName: string, eventJson: string, id: string, npub: string): Promise<{
+        signature: string;
+        id: string;
+        event: string;
+    }>;
+    nip04Encrypt(packageName: string, plainText: string, id: string, pubKey: string, npub: string): Promise<{
+        result: string;
+        id: string;
+    }>;
+    nip04Decrypt(packageName: string, encryptedText: string, id: string, pubKey: string, npub: string): Promise<{
+        result: string;
+        id: string;
+    }>;
+    nip44Encrypt(packageName: string, plainText: string, id: string, pubKey: string, npub: string): Promise<{
+        result: string;
+        id: string;
+    }>;
+    nip44Decrypt(packageName: string, encryptedText: string, id: string, pubKey: string, npub: string): Promise<{
+        result: string;
+        id: string;
+    }>;
+}
+interface AndroidLoginOptions {
+    /** The Android package name of the external signer app (e.g. com.greenart7c3.nostrsigner). */
+    packageName?: string;
+    /** Override the plugin for this call. Falls back to SignerConfig.androidSignerPlugin. */
+    plugin?: AndroidSignerPlugin;
+}
+declare class AndroidSigner implements ActiveSigner {
+    #private;
+    constructor(plugin: AndroidSignerPlugin, packageName: string, npub: string, pubkey: string);
+    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>;
+}
+interface AndroidLoginResult {
+    signer: AndroidSigner;
+    pubkey: string;
+    npub: string;
+    packageName: string;
+}
+declare function loginWithAndroidSigner(plugin: AndroidSignerPlugin, packageName?: string): Promise<AndroidLoginResult>;
+
+interface StorageAdapter {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+declare function localStorageAdapter(prefix?: string): StorageAdapter;
+
+/**
+ * How the user's key material is held for an account:
+ *  - `extension`: NIP-07 browser extension (window.nostr).
+ *  - `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.
+ */
+type LoginMethod = 'extension' | 'nip46' | 'ncryptsec' | 'android';
+/**
+ * Serialized account record persisted by the {@link StorageAdapter}.
+ *
+ * Survives reloads. Re-hydrates as **locked** — the account is present in
+ * `listAccounts()` and reachable via `getActiveAccount()`, but
+ * `getActiveSigner()` returns `null` until the user re-authenticates
+ * (passphrase for ncryptsec, page granted for extension, signer app for
+ * NIP-46/NIP-55).
+ *
+ * Method-specific fields:
+ *  - `ncryptsec` — present when `method === 'ncryptsec'`. The encrypted nsec.
+ *  - `nip46` — present when `method === 'nip46'`. URI, remote signer pubkey,
+ *     relays, and the per-account client session keypair (hex). The client
+ *     secret key is stored in plaintext on purpose — see the README's
+ *     threat-model note.
+ *  - `androidPackageName` — present when `method === 'android'`. Identifies
+ *     which installed signer app fulfilled the login (e.g. Amber).
+ */
+interface StoredAccount {
+    npub: string;
+    pubkey: string;
+    method: LoginMethod;
+    ncryptsec?: string;
+    nip46?: {
+        uri: string;
+        remoteSignerPubkey: string;
+        relays: string[];
+        clientSecretKey: string;
+    };
+    androidPackageName?: string;
+}
+/**
+ * The runtime signing surface exposed once an account is **unlocked**.
+ *
+ * Every concrete signer ({@link LocalSigner}, {@link ExtensionSigner},
+ * {@link BunkerSigner}, {@link AndroidSigner}) conforms to this. The
+ * abstraction has one deliberate omission: there is no `getPrivateKey()`.
+ * The raw secret key is never reachable through this interface — that is
+ * the package's central security invariant. Local signing holds the key
+ * in memory; the other methods sign remotely.
+ *
+ * `signEvent` accepts an unsigned {@link EventTemplate} (no `pubkey`,
+ * `id`, or `sig`) and returns a fully-signed {@link NostrEvent} —
+ * the implementation sets the `pubkey` to the active account's and fills
+ * in `id`/`sig`.
+ *
+ * `nip04Encrypt`/`nip44Encrypt` and their decrypt counterparts perform
+ * ECDH against `peerPubkey` (a 32-byte x-only hex pubkey). All four
+ * may throw if the remote signer (extension / bunker / Android) denies
+ * the operation.
+ */
+interface ActiveSigner {
+    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>;
+}
+interface RelayMismatchInfo {
+    userRelays: string[];
+    bunkerRelays: string[];
+}
+/**
+ * Called after pairing if the bunker's preferred relays (via get_relays)
+ * differ from the user-supplied list. Return `true` to accept the bunker's
+ * list — it will be stored on the account for future sessions. Return
+ * `false` (or anything falsy) to keep the user's list. Either way, the
+ * current in-memory session keeps using the user's relays since those
+ * just worked for pairing.
+ */
+type RelayMismatchHandler = (info: RelayMismatchInfo) => boolean | Promise<boolean>;
+interface BunkerLoginOptions {
+    pool?: AbstractSimplePool;
+    onAuth?: (url: string) => void;
+    /** Reuse a stored client session keypair to resume a NIP-46 connection. */
+    clientSecretKey?: Uint8Array;
+    onRelayMismatch?: RelayMismatchHandler;
+    /**
+     * NIP-46 permissions to request as part of the `connect` call
+     * (e.g. `['sign_event:1', 'nip44_encrypt']`). Without this, many
+     * bunker UIs (e.g. Amber) show no approve/deny prompt because the
+     * connect request has nothing concrete to authorize.
+     */
+    perms?: string[];
+}
+interface NostrConnectOptions {
+    relays: string[];
+    metadata?: {
+        name?: string;
+        url?: string;
+        image?: string;
+    };
+    perms?: string[];
+    /** Called once with the generated nostrconnect URI so the caller can render it. */
+    onUri: (uri: string) => void;
+    pool?: AbstractSimplePool;
+    onAuth?: (url: string) => void;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    onRelayMismatch?: RelayMismatchHandler;
+}
+/**
+ * Emitted by {@link Signer.onChange}. Variants:
+ *  - `login` — a new account became active (no previous active account).
+ *  - `switch` — the active account changed (including unlocking an already
+ *     hydrated account, since unlock re-asserts the active signer).
+ *  - `logout` — `logout(pubkey)` removed an account; emitted with the
+ *     removed account's `pubkey` (the account itself is already gone from
+ *     `listAccounts()` by the time the event fires).
+ */
+type SignerEvent = {
+    type: 'login';
+    account: StoredAccount;
+} | {
+    type: 'logout';
+    pubkey: string;
+} | {
+    type: 'switch';
+    account: StoredAccount;
+};
+interface SignerConfig {
+    /**
+     * Persistence backend. Defaults to a `localStorage`-backed adapter.
+     * Provide a custom adapter to use sessionStorage, an in-memory map,
+     * IndexedDB, or any other key/value store. See {@link StorageAdapter}.
+     */
+    storage?: StorageAdapter;
+    /** Prefix applied to all keys written by the default localStorage adapter. */
+    storageKeyPrefix?: string;
+    /**
+     * Human-readable app name used as the default `name` metadata in
+     * the nostrconnect:// URI generated by `loginWithNostrConnect`.
+     * Remote signers (Amber, etc.) display this on the consent screen.
+     * Overridden by a per-call `metadata.name`.
+     */
+    appName?: string;
+    /**
+     * Canonical app URL used as the default `url` metadata in the
+     * nostrconnect:// URI. Overridden by a per-call `metadata.url`.
+     */
+    appUrl?: string;
+    /**
+     * Icon URL used as the default `image` metadata in the
+     * nostrconnect:// URI. Overridden by a per-call `metadata.image`.
+     */
+    appImage?: string;
+    /**
+     * Default Android signer plugin (NIP-55). Provide the host app's
+     * `nostr-signer-capacitor-plugin` instance or an equivalent stub that
+     * satisfies {@link import('../nip55.js').AndroidSignerPlugin}.
+     * Can be overridden per-call via `loginWithAndroidSigner({ plugin })`
+     * or `listAndroidSignerApps(plugin)`.
+     */
+    androidSignerPlugin?: AndroidSignerPlugin;
+}
+
+/**
+ * Multi-account Nostr signer with persistence.
+ *
+ * **Hydration.** The constructor reads previously-saved accounts from
+ * the configured storage adapter. Every hydrated account starts
+ * **locked**: present in `listAccounts()` and (if it was the active one
+ * before) reachable via `getActiveAccount()`, but `getActiveSigner()`
+ * returns `null` until the user re-authenticates. The matching
+ * `loginWith*` method unlocks the active account.
+ *
+ * **Locked vs unlocked.** Use `getActiveAccount()` to render UI ("logged
+ * in as @alice") and `getActiveSigner()` to decide whether the user can
+ * actually sign. The pattern is "show the account always, gate signing
+ * on the signer."
+ *
+ * **Events.** Subscribe via `onChange()` to re-render when an account
+ * is added, switched, or removed. See {@link SignerEvent}.
+ */
+declare class Signer {
+    #private;
+    constructor(config?: SignerConfig);
+    /**
+     * Generate a brand-new nsec, encrypt it with `passphrase` (NIP-49),
+     * persist the resulting `ncryptsec` account, and activate it. Returns
+     * the new account's `npub` and `ncryptsec` — the caller must surface
+     * the `ncryptsec` to the user **immediately** since it is the only way
+     * back into the account on a fresh device.
+     *
+     * @throws if `passphrase` is empty.
+     */
+    createAccount(passphrase: string): Promise<{
+        npub: string;
+        ncryptsec: string;
+    }>;
+    /**
+     * Decrypt an ncryptsec with the user's passphrase, persist the account
+     * (overwriting any previous entry for the same pubkey), and activate it.
+     *
+     * @throws if either argument is empty, or if the passphrase doesn't
+     * decrypt the ncryptsec.
+     */
+    loginWithNcryptsec(ncryptsec: string, passphrase: string): Promise<StoredAccount>;
+    /**
+     * Connect via the NIP-07 browser extension exposed at `window.nostr`.
+     * The extension prompts the user for permission on first use.
+     *
+     * @throws if no extension is installed or the user denies the request.
+     */
+    loginWithExtension(): Promise<StoredAccount>;
+    /**
+     * Connect to a NIP-46 remote signer via a `bunker://` URI. Relays are
+     * read from the URI itself — no hardcoded fallbacks. Pass a `pool`
+     * to reuse an existing relay connection; pass `clientSecretKey` to
+     * resume a previous session (the hex from `StoredAccount.nip46`).
+     *
+     * @throws if the URI is malformed, no relay is reachable, or the
+     * remote signer rejects pairing within the implementation's timeout.
+     */
+    loginWithBunkerUri(uri: string, options?: BunkerLoginOptions): Promise<StoredAccount>;
+    /**
+     * Initiate a NIP-46 `nostrconnect://` pairing. Generates a client
+     * keypair, publishes a connect request to the supplied `relays`, and
+     * waits for a remote signer to pair. Call `options.onUri(uri)` to
+     * render the URI as a QR code; the returned promise resolves once
+     * pairing completes. Cancel by aborting `options.signal`.
+     *
+     * @throws if `relays` is empty, the user aborts, the pairing times
+     * out, or no signer responds.
+     */
+    loginWithNostrConnect(options: NostrConnectOptions): Promise<StoredAccount>;
+    /**
+     * Enumerate NIP-55 signer apps installed on the device, via the
+     * configured Android plugin (or `plugin` if supplied). Useful for
+     * rendering a "pick your signer" list — the built-in UI does this
+     * automatically when the Android tab is selected.
+     *
+     * Only meaningful inside a Capacitor Android shell. On web/iOS the
+     * configured plugin is typically absent and this throws.
+     *
+     * @throws if no plugin is configured and none is passed in.
+     */
+    listAndroidSignerApps(plugin?: AndroidSignerPlugin): Promise<AndroidSignerAppInfo[]>;
+    /**
+     * Sign in via a NIP-55 Android external signer (Amber, etc). If
+     * `options.packageName` is given, that specific signer app is invoked;
+     * otherwise the plugin picks a default (typically the only installed
+     * signer, or an OS chooser). Pass `options.plugin` to override the
+     * configured default for this call.
+     *
+     * @throws if no plugin is configured, the signer app cannot be
+     * resolved to a package name, or the user denies the request.
+     */
+    loginWithAndroidSigner(options?: AndroidLoginOptions): Promise<StoredAccount>;
+    /** Snapshot of every persisted account, in insertion order. */
+    listAccounts(): StoredAccount[];
+    /**
+     * The currently selected account, or `null` if none. Present even when
+     * the account is locked (no active signer yet). Use this to render
+     * "logged in as @alice" — pair with {@link getActiveSigner} to decide
+     * whether signing is actually available.
+     */
+    getActiveAccount(): StoredAccount | null;
+    /**
+     * The unlocked signer for the active account, or `null` if locked.
+     * After a fresh page load this is `null` for every account type
+     * (passphrase / extension grant / signer-app handshake all need to
+     * be redone). Calling the matching `loginWith*` method unlocks it.
+     */
+    getActiveSigner(): ActiveSigner | null;
+    /**
+     * Make `pubkey` the active account. Clears the in-memory signer —
+     * the new account starts **locked** even if it was previously
+     * unlocked in this session.
+     *
+     * @throws if `pubkey` does not match any persisted account.
+     */
+    switchAccount(pubkey: string): Promise<void>;
+    /**
+     * Remove an account from storage. `pubkey` defaults to the active
+     * account. If the active account is removed, the in-memory signer is
+     * cleared. No-op if there is nothing to remove.
+     */
+    logout(pubkey?: string): Promise<void>;
+    /**
+     * Subscribe to account-state changes. Returns an unsubscribe function.
+     * Listener errors are swallowed so one bad listener can't break others.
+     * See {@link SignerEvent} for the variants.
+     */
+    onChange(cb: (event: SignerEvent) => void): () => void;
+}
+/** 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 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 };