mirror of
https://github.com/vitorpamplona/amethyst.git
synced 2026-10-30 07:37:38 +00:00
Claude
8bd5063e10
Quartz now lives in github.com/vitorpamplona/quartz, split into quartz-core, quartz-social, quartz-relay-client and the other quartz-* libraries, with history kept. Amethyst depends on the `quartz` umbrella artifact at a released version (1.20.0) instead of the :quartz project. - Remove the quartz/ module, jitpack.yml and the Quartz CI, release and pre-push steps; tools/unicode-nfkc moved with it. - Point every module at libs.quartz. - Move the device-test fixtures the benchmark and relayBench still read to testdata/. - NostrConnectLoginUseCase parses bunker messages with BunkerJson, which now owns NIP-46 JSON. - Repoint docs and skills at the Quartz repository; the nostr-expert scripts read a Quartz checkout (QUARTZ_REPO, default ../quartz). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014ZR5ZBfhFzRiXubJc5Evyv
105 lines
6.1 KiB
Markdown
105 lines
6.1 KiB
Markdown
---
|
||
name: auth-signers
|
||
description: NostrSigner in Amethyst: NostrSignerInternal (local key), NostrSignerRemote (NIP-46 bunker), NostrSignerExternal (NIP-55 Android app). Use when signing/encrypting, adding a signer kind, login flows, or debugging sign timeouts.
|
||
---
|
||
|
||
# Signers
|
||
|
||
Every signed event and every NIP-04/NIP-44 operation goes through a `NostrSigner`. Feature
|
||
code never knows which of the three kinds the user has.
|
||
|
||
## The contract (all `suspend`)
|
||
|
||
[core/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/signers/NostrSigner.kt](https://github.com/vitorpamplona/quartz/blob/main/core/src/commonMain/kotlin/com/vitorpamplona/quartz/nip01Core/signers/NostrSigner.kt):
|
||
|
||
```kotlin
|
||
abstract class NostrSigner(pubKey: HexKey) {
|
||
open val pubKey: HexKey // open: NIP-46 resolves it from the bunker
|
||
abstract fun isWriteable(): Boolean
|
||
suspend fun <T : Event> sign(ev: EventTemplate<T>): T
|
||
abstract suspend fun <T : Event> sign(createdAt: Long, kind: Int, tags: Array<Array<String>>, content: String): T
|
||
abstract suspend fun nip04Encrypt(plaintext: String, toPublicKey: HexKey): String
|
||
abstract suspend fun nip04Decrypt(ciphertext: String, fromPublicKey: HexKey): String
|
||
abstract suspend fun nip44Encrypt(plaintext: String, toPublicKey: HexKey): String
|
||
abstract suspend fun nip44Decrypt(ciphertext: String, fromPublicKey: HexKey): String
|
||
abstract suspend fun decryptZapEvent(event: ZapRequestEvent): PrivateZapEvent
|
||
abstract suspend fun deriveKey(nonce: HexKey): HexKey
|
||
abstract suspend fun signPsbt(psbtHex: String): String // NIP-BC; may throw UnsupportedMethodException
|
||
abstract fun hasForegroundSupport(): Boolean
|
||
suspend fun decrypt(encryptedContent: String, fromPublicKey: HexKey): String // picks NIP-04 vs NIP-44
|
||
}
|
||
```
|
||
|
||
Failures are thrown as `SignerExceptions` (`nip01Core/signers/SignerExceptions.kt`):
|
||
`ReadOnlyException`, `UnauthorizedDecryptionException`, `NothingToDecrypt`,
|
||
`AutomaticallyUnauthorizedException`, `ManuallyUnauthorizedException`, `TimedOutException`,
|
||
`CouldNotPerformException`, `RunningOnBackgroundWithoutAutomaticPermissionException`,
|
||
`SignerNotFoundException`, `UnsupportedMethodException`. Same folder: `NostrSignerSync`
|
||
(blocking, for tests/scripts), `EventTemplate.kt`, `caches/` (`DecryptCache`).
|
||
|
||
## The three signers
|
||
|
||
| Signer | File | Notes |
|
||
|---|---|---|
|
||
| `NostrSignerInternal` | `core/.../nip01Core/signers/NostrSignerInternal.kt` | key in process memory; created/imported accounts |
|
||
| `NostrSignerRemote` | `nip46-remote-signer/.../nip46RemoteSigner/signer/NostrSignerRemote.kt` | NIP-46 bunker over kind 24133; `references/nip46-remote-signer.md` |
|
||
| `NostrSignerExternal` | `nip55-android-signer/src/androidMain/.../nip55AndroidSigner/client/NostrSignerExternal.kt` | NIP-55 app (Amber…) via intents + content provider; Android only; `references/nip55-android-signer.md` |
|
||
|
||
## Calling it from feature code
|
||
|
||
Prefer an `Account` method (`commons/.../commons/model/Account.kt`) — e.g. `reactTo(...)`,
|
||
`follow(user)` — which builds the template, signs with `account.signer`, updates local
|
||
state and broadcasts (`sendMyPublicAndPrivateOutbox`, `sendAutomatic`). If none fits, build
|
||
the template from the event class's `build(...)` and `account.signer.sign(template)`.
|
||
|
||
From a ViewModel, run signer work through `BaseAccountViewModel.launchSigner { … }`
|
||
(`commons/.../commons/viewmodels/BaseAccountViewModel.kt`): it runs on IO and turns
|
||
`SignerExceptions` into user notices, so don't add your own catch-and-toast. Never retry a
|
||
sign yourself: a timeout usually means the user didn't answer in time.
|
||
|
||
## Login / choosing a signer
|
||
|
||
- **nsec / hex / ncryptsec** → `NostrSignerInternal`.
|
||
- **`bunker://…`** → `NostrSignerRemote.fromBunkerUri(bunkerUri, signer, client)` (`signer`
|
||
is a fresh `NostrSignerInternal` transport key), then `suspend fun connect()`.
|
||
- **NIP-55 app** → `ExternalSignerLogin.createIntent(...)`, launch it, then
|
||
`ExternalSignerLogin.parseResult(data)` for the pubkey and package; build
|
||
`NostrSignerExternal(pubKey, packageName, contentResolver)`.
|
||
|
||
The login form is shared: `commonsUI/.../commons/account/ui/login/` (`LoginScreen`,
|
||
`LoginViewModel`, `RemoteSignerLogin`, `KeyTextField`, …) driving
|
||
`commons/.../commons/account/AccountSessionManager.kt`. The Android signer-app button,
|
||
`amethyst/.../ui/screen/loggedOff/login/ExternalSignerButton.kt`, reaches the form through
|
||
`AppPlatform.ExternalSignerLoginButton` (`commonsUI/.../commons/ui/platform/AppPlatform.kt`,
|
||
implemented in `amethyst/.../ui/platform/AndroidAppPlatform.kt`).
|
||
|
||
## Trade-offs
|
||
|
||
| Signer | Latency | Offline | Key location | UX |
|
||
|---|---|---|---|---|
|
||
| Internal | µs | yes | app memory | no prompts |
|
||
| Remote (NIP-46) | 100 ms – seconds | no (bunker relay must be reachable) | bunker | occasional approvals |
|
||
| External (NIP-55) | 100–500 ms | yes | other app | prompt per sign unless pre-approved |
|
||
|
||
## Gotchas
|
||
|
||
- **Timeouts are real and long**: `RemoteSignerManager` waits 65 s per request (one retry);
|
||
the NIP-55 foreground path waits 30 s (`IntentRequestManager.foregroundApprovalTimeout`).
|
||
Anything that stamps a time before asking to sign (NIP-98, NIP-42) can expire during the
|
||
prompt — sign right before use.
|
||
- **Bunker identity ≠ transport key.** `NostrSignerRemote.pubKey` is the bunker's
|
||
`get_public_key` answer (or `bindUserPubkey(...)` from a saved account); until bound it is the
|
||
transport key. Self-encryption keyed off the wrong one breaks private lists and drafts.
|
||
- **External signer needs a foreground Activity** (`IActivityLauncher`); a background caller
|
||
without pre-approved permissions gets `RunningOnBackgroundWithoutAutomaticPermissionException`.
|
||
- **NIP-04 is legacy** — new DM code is NIP-17 → `nip44Encrypt`.
|
||
- `signPsbt` is unsupported on remote bunkers and older NIP-55 apps; catch
|
||
`UnsupportedMethodException`.
|
||
|
||
## References
|
||
|
||
- `references/nip46-remote-signer.md` — bunker request/response taxonomy, connection flow.
|
||
- `references/nip55-android-signer.md` — foreground/background transports, command types.
|
||
- Related skills: `nostr-expert` (crypto under the signers), `account-state` (`Account`),
|
||
`android-expert` (activity/intent plumbing).
|