amethyst: Skill for Claude Code

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.