OpenParable
Skip to content
← Back to skills

Auth Signers

Development
auth-signers

Auth Signers is an Agent Skill for development published in the vitorpamplona/amethyst repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Signer abstraction patterns in Amethyst. Use when working with event signing, choosing between a local keypair (`NostrSignerInternal`), a remote NIP-46 bunker signer (`NostrSignerRemote`), or a NIP-55 Android external-app signer (`NostrSignerExternal`). Covers the abstract `NostrSigner` base class, `SignerResult` contract, how to wire a new flow that needs to sign events, and the security/UX trade-offs between signer kinds.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/vitorpamplona/amethyst/blob/HEAD/.claude/skills/auth-signers/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/auth-signers, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Auth & Signers

Any time Amethyst produces a signed Nostr event, it goes through a NostrSigner. There are three kinds; all three implement the same abstract contract so feature code doesn't care which one the user has configured.

When to Use This Skill

  • Adding a new flow that publishes an event (follow, post, react, zap, profile edit).
  • Reviewing whether a feature works when the user has a remote bunker signer or an external Android signer.
  • Debugging "Sign request approved but nothing happens" / timeouts on sign operations.
  • Onboarding a new signer kind (hardware signer, browser extension, etc.).
  • Understanding the NIP-46 bunker request/response taxonomy.

The Abstract Contract

quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/signers/NostrSigner.kt:

abstract class NostrSigner(val pubKey: HexKey) {
    abstract fun <T : Event> sign(
        template: EventTemplate<T>,
        onReady: (T) -> Unit,
    )
    abstract fun nip04Encrypt(plaintext: String, toPubKey: HexKey, onReady: (String) -> Unit)
    abstract fun nip04Decrypt(ciphertext: String, fromPubKey: HexKey, onReady: (String) -> Unit)
    abstract fun nip44Encrypt(...)
    abstract fun nip44Decrypt(...)
    abstract fun decryptZapEvent(event: LnZapRequestEvent, onReady: (LnZapRequestEvent) -> Unit)
}

Sibling files in the same folder:

  • NostrSignerInternal.kt — in-process signer with the user's seckey in memory. Fastest; used for locally-stored accounts.
  • NostrSignerSync.kt — blocking wrapper for scripts / migrations / tests where callbacks are inconvenient.
  • EventTemplate.kt — the unsigned holder passed to sign().
  • SignerExceptions.kt — the error taxonomy (user denied, timeout, unsupported method, etc.).
  • caches/ — request cache so duplicate sign/encrypt requests coalesce.

Concrete implementations

  • Local (in-process): NostrSignerInternal — direct Secp256k1Instance.signSchnorr + NIP-44 inline. Used by accounts created/imported into Amethyst.
  • Remote (NIP-46 bunker): quartz/.../nip46RemoteSigner/signer/NostrSignerRemote.kt. Talks to a bunker service over Nostr DMs using the BunkerRequest* / BunkerResponse* event taxonomy (BunkerRequestConnect, BunkerRequestSign, BunkerRequestNip44Encrypt, …).
  • Android external (NIP-55): quartz/src/androidMain/.../nip55AndroidSigner/client/NostrSignerExternal.kt. Uses Android intents + content provider to delegate to another app on the same device. Launcher: ExternalSignerLogin.kt, IActivityLauncher.kt. Install-check: IsExternalSignerInstalled.kt.

The SignerResult Contract

Signers return via callback (and internally track via SignerResult sealed types in nip46RemoteSigner/signer/SignerResult.kt and nip55AndroidSigner/api/SignerResult.kt). Result variants cover success, user-denied, timeout, remote-disconnected, unsupported. Feature code should:

  1. Pass a callback that handles success.
  2. Trust the cache/timeout behavior — don't roll your own retry.
  3. Surface SignerExceptions to the user with actionable messaging (e.g. "Bunker disconnected — reconnect?").

Typical Flow (Feature Code)

// High-level: Account methods already do this internally.
val signer: NostrSigner = account.signer     // whichever kind the user configured

val template = reactionEventTemplate(noteId, authorPubKey, "+")

signer.sign(template) { signed ->
    account.sendToRelays(signed)             // or similar pipeline
}

Most feature code should go through Account's mutation methods (account.sendReaction, account.follow) rather than touching the signer directly — the account layer handles signing + publishing + local state update atomically. Reach for the signer directly only when Account doesn't have a helper.

Choosing a Signer at Sign-Up

Entry points:

  • Existing private key (nsec, 32-byte hex, file) → NostrSignerInternal.
  • Bunker URL (bunker://...) → NostrSignerRemote.fromBunkerUri(bunkerUri, localSigner, client) in nip46RemoteSigner/signer/NostrSignerRemote.kt parses the URI and returns a NostrSignerRemote; then call its suspend fun connect() to perform the NIP-46 handshake.
  • Installed external signer app (Amber, nos2x, etc. on Android) → ExternalSignerLogin.launch(...) opens the signer app; approval yields a NostrSignerExternal.

The UI hosts both flows via amethyst/.../ui/screen/loggedOff/login/ — look there for ExternalSignerButton.kt and the bunker-URL paste screen.

Trade-offs

SignerLatencyOffline OK?SecurityUX
InternalµsYesKey in app memoryNo confirmation prompts
Remote (NIP-46)100ms–secondsNo (needs bunker reachable)Key never touches AmethystOccasional approval prompts
External (NIP-55)100–500msYesKey in separate appPrompt on every sign by default (configurable)

Gotchas

  • Callbacks may never fire. External signers can be dismissed without result; remote signers can time out. Use SignerExceptions / timeout handling at every call site or rely on the Account layer's wrapping.
  • nip04Encrypt is legacy for NIP-04 DMs. New DM code should use NIP-17 gift-wrap → nip44Encrypt path.
  • Don't cache signer output beyond the caches/ that quartz already maintains. Stale cache entries lead to duplicate publishes.
  • Remote signer disconnects need explicit reconnection UX — RemoteSignerManager exposes state; hook into it for an account-switching warning.
  • External signer launch requires an Activity context — it can't happen from a background service. Structure flows so signing is on the main dispatcher through an activity-scoped launcher.
  • NostrSignerSync is rare. If you reach for it, you're probably in a test or migration — production code uses the async API.

References

  • references/nip46-remote-signer.md — the NIP-46 bunker message taxonomy and connection lifecycle.
  • references/nip55-android-signer.md — Android intent-based external signer flow.
  • Complements: nostr-expert/references/crypto-and-encryption.md (the crypto under all signers), account-state (which wraps signer calls), android-expert (intent launcher patterns).