From cb37a9320e10fcc4d8c064571461311ca613a1d5 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Wed, 18 Oct 2023 11:48:18 -0300 Subject: [PATCH 1/6] rewrite NIP-46. --- 46.md | 178 +++++++++++++++++----------------------------------------- 1 file changed, 50 insertions(+), 128 deletions(-) diff --git a/46.md b/46.md index 5318541..ccdb535 100644 --- a/46.md +++ b/46.md @@ -2,161 +2,83 @@ NIP-46 ====== Nostr Connect ------------------------- +------------- `draft` `optional` -## Rationale +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. -Private keys should be exposed to as few systems - apps, operating systems, devices - as possible as each system adds to the attack surface. +## Signer Discovery -Entering private keys can also be annoying and requires exposing them to even more systems such as the operating system's clipboard that might be monitored by malicious apps. +The client must somehow be able to contact the signer through a common relay. +### Started by the signer -## Terms +The remote signer generates a connection token in the form -* **App**: Nostr app on any platform that *requires* to act on behalf of a nostr account. -* **Signer**: Nostr app that holds the private key of a nostr account and *can sign* on its behalf. +``` +#?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. -## `TL;DR` +### Started by the client +The client generates a QR code in the following form (URL-encoded): -**App** and **Signer** sends ephemeral encrypted messages to each other using kind `24133`, using a relay of choice. +``` +nostrconnect://?relay=wss://...&metadata={"name":"client-name"} +``` -App prompts the Signer to do things such as fetching the public key or signing events. +The signer scans the QR code and sends a `connect` message to the client in the specified relays. -The `content` field must be an encrypted JSONRPC-ish **request** or **response**. +## Event payloads -## Signer Protocol +Event payloads are [NIP-04](04.md)-encrypted JSON blobs that look like JSONRPC. -### Messages +Events sent by the client to the remote signer have the following format: -#### Request - -```json +```js { - "id": , - "method": , - "params": [, ] + "pubkey": "" + "kind": 24133, + "tags": [ + ["p", ""] + ], + "content": "nip04_encrypted_json({id: , method: , params: []})", + ... } ``` -#### Response +And the events the remote signer sends to the client have the following format: -```json -{ - "id": , - "result": , - "error": -} +```js + "pubkey": "" + "kind": 24133, + "tags": [ + ["p", ""] + ], + "content": "nip04_encrypted_json({id: , result: , error: })", + ... ``` ### Methods - -#### Mandatory - -These are mandatory methods the remote signer app MUST implement: - -- **describe** - - params [] - - result `["describe", "get_public_key", "sign_event", "connect", "disconnect", "delegate", ...]` -- **get_public_key** - - params [] - - result `pubkey` -- **sign_event** - - params [`event`] - - result `event_with_signature` - -#### optional - - - **connect** - - params [`pubkey`] -- **disconnect** - - params [] -- **delegate** - - params [`delegatee`, `{ kind: number, since: number, until: number }`] - - result `{ from: string, to: string, cond: string, sig: string }` + - params: [`pubkey`, `secret`] + - result: `null` +- **get_public_key** + - params: [] + - result: `pubkey` +- **sign_event** + - params: [`event`] + - result: `event_with_pubkey_id_and_signature` - **get_relays** - - params [] - - result `{ [url: string]: {read: boolean, write: boolean} }` + - params: [] + - result: `{ [url: string]: {read: boolean, write: boolean} }` - **nip04_encrypt** - - params [`pubkey`, `plaintext`] - - result `nip4 ciphertext` + - params: [`pubkey`, `plaintext`] + - result: `nip4 ciphertext` - **nip04_decrypt** - - params [`pubkey`, `nip4 ciphertext`] - - result [`plaintext`] - - -NOTICE: `pubkey` and `signature` are hex-encoded strings. - - -### Nostr Connect URI - -**Signer** discovers **App** by scanning a QR code, clicking on a deep link or copy-pasting an URI. - -The **App** generates a special URI with prefix `nostrconnect://` and base path the hex-encoded `pubkey` with the following querystring parameters **URL encoded** - -- `relay` URL of the relay of choice where the **App** is connected and the **Signer** must send and listen for messages. -- `metadata` metadata JSON of the **App** - - `name` human-readable name of the **App** - - `url` (optional) URL of the website requesting the connection - - `description` (optional) description of the **App** - - `icons` (optional) array of URLs for icons of the **App**. - -#### JavaScript - -```js -const uri = `nostrconnect://?relay=${encodeURIComponent("wss://relay.damus.io")}&metadata=${encodeURIComponent(JSON.stringify({"name": "Example"}))}` -``` - -#### Example -```sh -nostrconnect://b889ff5b1513b641e2a139f661a661364979c5beee91842f8f0ef42ab558e9d4?relay=wss%3A%2F%2Frelay.damus.io&metadata=%7B%22name%22%3A%22Example%22%7D -``` - - - -## Flows - -The `content` field contains encrypted message as specified by [NIP04](https://github.com/nostr-protocol/nips/blob/master/04.md). The `kind` chosen is `24133`. - -### Connect - -1. User clicks on **"Connect"** button on a website or scan it with a QR code -2. It will show an URI to open a "nostr connect" enabled **Signer** -3. In the URI there is a pubkey of the **App** ie. `nostrconnect://&relay=&metadata=` -4. The **Signer** will send a message to ACK the `connect` request, along with his public key - -### Disconnect (from App) - -1. User clicks on **"Disconnect"** button on the **App** -2. The **App** will send a message to the **Signer** with a `disconnect` request -3. The **Signer** will send a message to ACK the `disconnect` request - -### Disconnect (from Signer) - -1. User clicks on **"Disconnect"** button on the **Signer** -2. The **Signer** will send a message to the **App** with a `disconnect` request - - -### Get Public Key - -1. The **App** will send a message to the **Signer** with a `get_public_key` request -3. The **Signer** will send back a message with the public key as a response to the `get_public_key` request - -### Sign Event - -1. The **App** will send a message to the **Signer** with a `sign_event` request along with the **event** to be signed -2. The **Signer** will show a popup to the user to inspect the event and sign it -3. The **Signer** will send back a message with the event including the `id` and the schnorr `signature` as a response to the `sign_event` request - -### Delegate - -1. The **App** will send a message with metadata to the **Signer** with a `delegate` request along with the **conditions** query string and the **pubkey** of the **App** to be delegated. -2. The **Signer** will show a popup to the user to delegate the **App** to sign on his behalf -3. The **Signer** will send back a message with the signed [NIP-26 delegation token](https://github.com/nostr-protocol/nips/blob/master/26.md) or reject it - - + - params: [`pubkey`, `nip4 ciphertext`] + - result: [`plaintext`] From c5c2d86a479d1ca52065b50faddc72220c3896cf Mon Sep 17 00:00:00 2001 From: fiatjaf_ Date: Tue, 21 Nov 2023 20:49:35 -0300 Subject: [PATCH 2/6] peer-pubkey Co-authored-by: monlovesmango <96307647+monlovesmango@users.noreply.github.com> --- 46.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/46.md b/46.md index ccdb535..baefa4b 100644 --- a/46.md +++ b/46.md @@ -80,5 +80,5 @@ And the events the remote signer sends to the client have the following format: - params: [`pubkey`, `plaintext`] - result: `nip4 ciphertext` - **nip04_decrypt** - - params: [`pubkey`, `nip4 ciphertext`] + - params: [`peer-pubkey`, `nip4 ciphertext`] - result: [`plaintext`] From e4bddbee7b90b701ea2041532c88935f5176850e Mon Sep 17 00:00:00 2001 From: fiatjaf_ Date: Tue, 21 Nov 2023 22:25:19 -0300 Subject: [PATCH 3/6] peer-pubkey Co-authored-by: monlovesmango <96307647+monlovesmango@users.noreply.github.com> --- 46.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/46.md b/46.md index baefa4b..6610e82 100644 --- a/46.md +++ b/46.md @@ -77,7 +77,7 @@ And the events the remote signer sends to the client have the following format: - params: [] - result: `{ [url: string]: {read: boolean, write: boolean} }` - **nip04_encrypt** - - params: [`pubkey`, `plaintext`] + - params: [`peer-pubkey`, `plaintext`] - result: `nip4 ciphertext` - **nip04_decrypt** - params: [`peer-pubkey`, `nip4 ciphertext`] From 6c35537ca425f154ca1c92897ab0eac599a80c87 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Tue, 21 Nov 2023 22:31:13 -0300 Subject: [PATCH 4/6] @v0l improvements. --- 46.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/46.md b/46.md index 6610e82..1a9be03 100644 --- a/46.md +++ b/46.md @@ -10,7 +10,7 @@ This NIP describes a method for 2-way communication between a **remote signer** ## Signer Discovery -The client must somehow be able to contact the signer through a common relay. +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 @@ -27,7 +27,7 @@ The user copies that token and pastes it in the client UI somehow. Then the clie The client generates a QR code in the following form (URL-encoded): ``` -nostrconnect://?relay=wss://...&metadata={"name":"client-name"} +nostrconnect://?relay=wss://...&metadata={"name":"...", "url": "...", "description": "..."} ``` The signer scans the QR code and sends a `connect` message to the client in the specified relays. From 3983a52d3bb720852090ee02911f56ee2701dd73 Mon Sep 17 00:00:00 2001 From: fiatjaf Date: Sat, 2 Dec 2023 14:45:10 -0300 Subject: [PATCH 5/6] latest discoveries. --- 46.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/46.md b/46.md index 1a9be03..ce31970 100644 --- a/46.md +++ b/46.md @@ -12,12 +12,12 @@ This NIP describes a method for 2-way communication between a **remote signer** 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 +### Started by the signer (nsecBunker) The remote signer generates a connection token in the form ``` -#?relay=wss://...&relay=wss://... +#?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. @@ -34,7 +34,7 @@ The signer scans the QR code and sends a `connect` message to the client in the ## Event payloads -Event payloads are [NIP-04](04.md)-encrypted JSON blobs that look like JSONRPC. +Event payloads are [NIP-04](04.md)-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: @@ -45,7 +45,7 @@ Events sent by the client to the remote signer have the following format: "tags": [ ["p", ""] ], - "content": "nip04_encrypted_json({id: , method: , params: []})", + "content": "nip04_encrypted_json({id: , method: , params: [array_of_strings]})", ... } ``` @@ -58,27 +58,29 @@ And the events the remote signer sends to the client have the following format: "tags": [ ["p", ""] ], - "content": "nip04_encrypted_json({id: , result: , error: })", + "content": "nip04_encrypted_json({id: , result: , error: })", ... ``` +The signer key will always be the key of the user who controls the signer device. + ### Methods - **connect** - params: [`pubkey`, `secret`] - - result: `null` + - result: `"ack"` - **get_public_key** - params: [] - - result: `pubkey` + - result: `pubkey-hex` - **sign_event** - params: [`event`] - - result: `event_with_pubkey_id_and_signature` + - result: `json_string(event_with_pubkey_id_and_signature)` - **get_relays** - params: [] - - result: `{ [url: string]: {read: boolean, write: boolean} }` + - result: `json_string({[url: string]: {read: boolean, write: boolean}})` - **nip04_encrypt** - - params: [`peer-pubkey`, `plaintext`] - - result: `nip4 ciphertext` + - params: [`third-party-pubkey`, `plaintext`] + - result: `nip04-ciphertext` - **nip04_decrypt** - - params: [`peer-pubkey`, `nip4 ciphertext`] - - result: [`plaintext`] + - params: [`third-party-pubkey`, `nip04-ciphertext`] + - result: `plaintext` From d0aef4c1581807a046b00396f67f3dd03cf599e8 Mon Sep 17 00:00:00 2001 From: Pablo Fernandez Date: Thu, 7 Dec 2023 17:01:25 +0000 Subject: [PATCH 6/6] add nip-44 calls --- 46.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/46.md b/46.md index ce31970..3ab71e9 100644 --- a/46.md +++ b/46.md @@ -84,3 +84,15 @@ The signer key will always be the key of the user who controls the signer device - **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"`