From 58131607c3d00fa8849fa898d5887f86f5674967 Mon Sep 17 00:00:00 2001 From: tiero <3596602+tiero@users.noreply.github.com> Date: Wed, 4 Jan 2023 18:33:37 +0100 Subject: [PATCH] Add revised README --- README.md | 133 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 111 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index a4b6904..7c6bfab 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,120 @@ -# Nostr Connect +Nostr Connect allows Nostr apps to connect with remote signing devices +------------------------ + +Having to enter your Nostr private key on each website or random app _sucks_. + +## Protocol -## Nostr Connect -PAIRING - -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 Wallet -3. In the URI there is a pubkey of the App ie. nc:// -4. The Wallet will send a kind 4 encrypted message to ACK the pairing request, along with his public key +### `TL;DR` -ENABLE +**App** (*typically a web app, it generates a random ephemeral keypair*) and **Wallet** (*typically a mobile app, it holds the private key of the user that represents his Nostr account*) send to each other `kind:4` encrypted DMs, using a relay of choice. -1. The App will send a kind 4 encrypted message with metadata to the Wallet with a Enable Request -2. The Wallet will show a popup to the user to enable the App to requesta data or remote siging requests -3. The Wallet will send a kind 4 encrypted message to ACK the Enable Request or reject it -4. All others subsequent Enabled Requests will be ACKed automatically +App prompts the Wallet to do things such as fetching the public key or signing events. -DELEGATE +The `content` field must be a JSONRPC-ish **request** or **response**. -1. The App will send a kind 4 encrypted message with metadata to the Wallet with a Delegate Request -2. The Wallet will show a popup to the user to delegate the App to sign with a child key -3. The Wallet will send a kind 4 encrypted message to ACK the Delegate Request with the child private key or reject it -4. All others subsequent Delegate Requests will be ACKed automatically -REMOTE SIGNING +### Messages -1. The App will send a kind 4 encrypted message with metadata to the Wallet with a Sign Event Request -2. The Wallet will show a popup to the user to sign the event -3. The Wallet will send a kind 4 encrypted message to ACK the Sign Event Request with the signed event or reject it \ No newline at end of file +#### Request + +```json +{ + "id": , + "method": , + "params": [, ] +} +``` + +#### Response + +```json +{ + "id": , + "result": , + "error": +} +``` + +### Methods + +- `connect` + - params [`pubkey`] +- `disconnect` + - params [] +- `get_public_key` + - params [] + - result `pubkey` +- `sign_event` + - params [`event`] + - result `signature` + +#### optional + +- `delegate` +- `get_relays` +- `nip04_encrypt` +- `nip04_decrypt` + + +### Nostr Connect URI + +**Walle** discovers **App** by scanning a QR code or clicking on a deep link or copy-pasting an URI. + +The **App** generates a special URI with prefix `nostr://` and base path `connect` with the following querystring parameters + +- `target` hexadecimal public key of the **App** +- `relay` URL of the relay of choice where the **App** is connected and the **Wallet** must send and listen for messages. +- `metadata` metadata JSON of the **App** + - `url` URL of the website requesting the connection + - `name` human-readable name of the **App** + - `description` (optional) description of the **App** + - `icons` (optional) array of URLs for icons of the **App**. + +#### Example + +```sh +nostr://conect?target=&relay=&metadata={"url": "example.com","name": "Example"} +``` + +## Flow + + +## 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 **Wallet** +3. In the URI there is a pubkey of the **App** ie. `nostr://conect?target=&relay=&metadata=` +4. The **Wallet** will send a kind 4 encrypted 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 kind 4 encrypted message to the **Wallet** with a `disconnect` request +3. The **Wallet** will send a kind 4 encrypted message to ACK the `disconnect` request + +## Disconnect (from Wallet) + +1. User clicks on **"Disconnect"** button on the **Wallet** +2. The **Wallet** will send a kind 4 encrypted message to the **App** with a `disconnect` request + + +## Get Public Key + +1. The **App** will send a kind 4 encrypted message to the **Wallet** with a `get_public_key` request +3. The **Wallet** will send back a kind 4 encrypted message with the public key as a response to the `get_public_key` request + +## Sign Event + +1. The **App** will send a kind 4 encrypted message to the **Wallet** with a `sign_event` request along with the **event** to be signed +2. The **Wallet** will show a popup to the user to inspect the event and sign it +3. The **Wallet** will send back a kind 4 encrypted message with the schnorr `signature` of the event as a response to the `sign_event` request + +## Delegate + +1. The **App** will send a kind 4 encrypted message with metadata to the **Wallet** with a `delegate` request along with the **conditions** query string and the **pubkey** of the **App** to be delegated. +2. The **Wallet** will show a popup to the user to delegate the **App** to sign on his behalf +3. The **Wallet** will send back a kind 4 encrypted message with the signed [NIP-26 delegation token](https://github.com/nostr-protocol/nips/blob/master/26.md) or reject it +4. All others subsequent `delegate` Requests will be ACKed automatically