mirror of
https://github.com/vitorpamplona/amethyst.git
synced 2026-10-30 07:37:38 +00:00
Claude
9afa8127da
Quartz moves to its own repo, the way the crypto primitives moved to crypto-kmp. Every module depends on com.vitorpamplona.quartz:quartz 2.0.0 (libs.quartz) instead of :quartz, and -PquartzDir=../quartz builds a local checkout instead of the artifact, for every module and for quic's own quartz dependency (which replaces the root build's substitution of the published quartz with :quartz). What moved with quartz: its CI jobs (lint tasks, test-quartz-linux-native, test-quartz-ios), the Maven Central publish step of the release workflow, jitpack.yml, tools/unicode-nfkc, the nostr-expert and event-store-semantics skills, the agent-skill check, and the README's library usage docs. What stays here: - The four quartz client tests that need a real Ktor socket relay (TrustNetworkSync*, GiantReqStreamTest, BulkDownloadBenchmark) move to geode's tests; geode forwards -PprodRelayBench for the latter. quartz's other relay-client tests now use a test relay of its own, which ends quartz's test dependency on geode. - The benchmark module's resources (previously read from quartz's androidDeviceTest resources) move into benchmark/; relayBench --real reads the corpus from there. - NoteComposeKindCoverageTest reads EventFactory.kt from quartz's JVM sources jar, or from the -PquartzDir checkout, passed by commonsUI's build. - commons and commonsUI declare crypto-kmp (and commons mls-kmp), which they import directly. Through quartz's api alone, a -PcryptoKmpDir checkout never reached the common metadata compile. - The catalog drops what only quartz used (kchesslib, negentropy, jackson-databind, sqlite-bundled, secp256k1-kmp common, compose runtime-annotation, the maven-publish plugin). agent_config_check checks a skill's quartz/... paths against a ../quartz checkout when there is one and skips them otherwise. AGENTS.md, the skills, CONTRIBUTING, BUILDING, RELEASE_OPS, PLANS and the READMEs point at the new repo. Needs quartz 2.0.0 (and crypto-kmp 1.0.0) on Maven Central before CI can resolve it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DEkJaDWYrcTbGvT8JLQCrG
105 lines
6.0 KiB
Markdown
105 lines
6.0 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`)
|
||
|
||
`quartz/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` | `quartz/.../nip01Core/signers/NostrSignerInternal.kt` | key in process memory; created/imported accounts |
|
||
| `NostrSignerRemote` | `quartz/.../nip46RemoteSigner/signer/NostrSignerRemote.kt` | NIP-46 bunker over kind 24133; `references/nip46-remote-signer.md` |
|
||
| `NostrSignerExternal` | `quartz/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: quartz's `nostr-expert` (crypto under the signers), `account-state` (`Account`),
|
||
`android-expert` (activity/intent plumbing).
|