nips/46.md

NIP-46

Nostr Connect

draft optional

This NIP describes a method for 2-way communication between a remote signer and a normal Nostr client. The remote signer could be, for example, a hardware device dedicated to signing Nostr events, while the client is a normal Nostr client.

Signer Discovery

The client always starts by generating a random key which is used to communicate with the signer, then it one of the methods below is used to allow the client to know what is the signer public key for the session and which relays to use.

Started by the signer (nsecBunker)

The remote signer generates a connection token in the form

<npub1...>#<optional-secret>?relay=wss://...&relay=wss://...

The user copies that token and pastes it in the client UI somehow. Then the client can send events of kind 24133 to the specified relays and wait for responses from the remote signer.

Started by the client

The client generates a QR code in the following form (URL-encoded):

nostrconnect://<client-key-hex>?relay=wss://...&metadata={"name":"...", "url": "...", "description": "..."}

The signer scans the QR code and sends a connect message to the client in the specified relays.

Event payloads

Event payloads are NIP-04-encrypted JSON blobs that look like JSONRPC messages (their format is specified inside the .content of the event formats nelow).

Events sent by the client to the remote signer have the following format:

{
  "pubkey": "<client-key-hex>"
  "kind": 24133,
  "tags": [
    ["p", "<signer-key-hex>"]
  ],
  "content": "nip04_encrypted_json({id: <random-string>, method: <see-below>, params: [array_of_strings]})",
  ...
}

And the events the remote signer sends to the client have the following format:

  "pubkey": "<signer-key-hex>"
  "kind": 24133,
  "tags": [
    ["p", "<client-key-hex>"]
  ],
  "content": "nip04_encrypted_json({id: <request-id>, result: <string>, error: <reason-string>})",
  ...

The signer key will always be the key of the user who controls the signer device.

Methods

• connect
  • params: [pubkey, secret]
  • result: "ack"
• get_public_key
  • params: []
  • result: pubkey-hex
• sign_event
  • params: [event]
  • result: json_string(event_with_pubkey_id_and_signature)
• get_relays
  • params: []
  • result: json_string({[url: string]: {read: boolean, write: boolean}})
• nip04_encrypt
  • params: [third-party-pubkey, plaintext]
  • result: nip04-ciphertext
• nip04_decrypt
  • params: [third-party-pubkey, nip04-ciphertext]
  • result: plaintext
• nip44_get_key
  • params: [third-party-pubkey]
  • result: nip44-conversation-key
• nip44_encrypt
  • params: [third-party-pubkey, plaintext]
  • result: nip44-ciphertext
• nip44_decrypt
  • params: [third-party-pubkey, nip44-ciphertext]
  • result: plaintext
• ping
  • params: []
  • result: "pong"