mirror of
https://github.com/vitorpamplona/amethyst.git
synced 2026-10-30 07:37:38 +00:00
Vitor PamplonaandClaude Opus 5.5
395af4dc9c
The 33 descriptions (~16k chars, ~19k with paths) overran Codex's skill-list budget (2% of the context window, or 8,000 chars when unknown), and a review found most bodies stale: paths from before the commons/commonsUI moves, the deleted legacy desktop app, a callback signer API that no longer exists, and example APIs that were never in the tree. Kept, rewritten and checked against the code (every path, class and command): account-state (+feeds), amy-expert, android-expert, auth-signers, compose-expert (+API style, Navigation 3 back stacks), desktop-expert (+run/package), event-store-semantics (+NIP-50 search), find-missing- translations, kotlin-coroutines (+structured concurrency, flow modeling), kotlin-multiplatform (+Gradle, composable extraction), ngit-pr, nip85-trusted-assertions, nostr-expert (+NIP lookup, generated NIP catalog), relay-client. Dropped: textbook Compose/Kotlin technique skills, kotlin-expert, kotlin-types-value-class, gradle-expert, quartz-integration (external-facing; see the Quartz docs commit), find-non-lambda-logs (audit finished; the rule is now in AGENTS.md Kotlin Style), and the /nip, /desktop-run, /extract commands. The skill list is now ~4k chars. Also drops .claude/core-skills-plan.md (stale history) and repoints SearchableEvent's KDoc to event-store-semantics. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
105 lines
5.9 KiB
Markdown
105 lines
5.9 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: `nostr-expert` (crypto under the signers), `account-state` (`Account`),
|
||
`android-expert` (activity/intent plumbing).
|