upleb.uk

Public git repos — served from a NIP-34 GRASP relay at git.upleb.uk

summaryrefslogtreecommitdiff
path: root/46.md
diff options
context:
space:
mode:
Diffstat (limited to '46.md')
-rw-r--r--46.md243
1 files changed, 117 insertions, 126 deletions
diff --git a/46.md b/46.md
index 8ba65d9..ce6764d 100644
--- a/46.md
+++ b/46.md
@@ -1,4 +1,12 @@
1# NIP-46 - Nostr Remote Signing 1NIP-46
2======
3
4Nostr Remote Signing
5--------------------
6
7## Changes
8
9`remote-signer-key` is introduced, passed in bunker url, clients must differentiate between `remote-signer-pubkey` and `user-pubkey`, must call `get_public_key` after connect, nip05 login is removed, create_account moved to another NIP.
2 10
3## Rationale 11## Rationale
4 12
@@ -8,101 +16,60 @@ This NIP describes a method for 2-way communication between a remote signer and
8 16
9## Terminology 17## Terminology
10 18
11- **Local keypair**: A local public and private key-pair used to encrypt content and communicate with the remote signer. Usually created by the client application. 19- **user**: A person that is trying to use Nostr.
12- **Remote user pubkey**: The public key that the user wants to sign as. The remote signer has control of the private key that matches this public key. 20- **client**: A user-facing application that _user_ is looking at and clicking buttons in. This application will send requests to _remote-signer_.
13- **Remote signer pubkey**: This is the public key of the remote signer itself. This is needed in both `create_account` command because you don't yet have a remote user pubkey. 21- **remote-signer**: A daemon or server running somewhere that will answer requests from _client_, also known as "bunker".
22- **client-keypair/pubkey**: The keys generated by _client_. Used to encrypt content and communicate with _remote-signer_.
23- **remote-signer-keypair/pubkey**: The keys used by _remote-signer_ to encrypt content and communicate with _client_. This keypair MAY be same as _user-keypair_, but not necessarily.
24- **user-keypair/pubkey**: The actual keys representing _user_ (that will be used to sign events in response to `sign_event` requests, for example). The _remote-signer_ generally has control over these keys.
14 25
15All pubkeys specified in this NIP are in hex format. 26All pubkeys specified in this NIP are in hex format.
16 27
17## Initiating a connection 28## Overview
18
19To initiate a connection between a client and a remote signer there are a few different options.
20
21### Direct connection initiated by remote signer
22 29
23This is most common in a situation where you have your own nsecbunker or other type of remote signer and want to connect through a client that supports remote signing. 301. _client_ generates `client-keypair`. This keypair doesn't need to be communicated to _user_ since it's largely disposable. _client_ might choose to store it locally and they should delete it on logout;
312. A connection is established (see below), _remote-signer_ learns `client-pubkey`, _client_ learns `remote-signer-pubkey`.
323. _client_ uses `client-keypair` to send requests to _remote-signer_ by `p`-tagging and encrypting to `remote-signer-pubkey`;
334. _remote-signer_ responds to _client_ by `p`-tagging and encrypting to the `client-pubkey`.
345. _client_ requests `get_public_key` to learn `user-pubkey`.
24 35
25The remote signer would provide a connection token in the form: 36## Initiating a connection
26
27```
28bunker://<remote-pubkey>?relay=<wss://relay-to-connect-on>&relay=<wss://another-relay-to-connect-on>&secret=<optional-secret-value>
29```
30 37
31This token is pasted into the client by the user and the client then uses the details to connect to the remote signer via the specified relay(s). 38There are two ways to initiate a connection:
32 39
33### Direct connection initiated by the client 40### Direct connection initiated by _remote-signer_
34 41
35In this case, basically the opposite direction of the first case, the client provides a connection token (or encodes the token in a QR code) and the signer initiates a connection to the client via the specified relay(s). 42_remote-signer_ provides connection token in the form:
36 43
37``` 44```
38nostrconnect://<local-keypair-pubkey>?relay=<wss://relay-to-connect-on>&metadata=<json metadata in the form: {"name":"...", "url": "...", "description": "..."}> 45bunker://<remote-signer-pubkey>?relay=<wss://relay-to-connect-on>&relay=<wss://another-relay-to-connect-on>&secret=<optional-secret-value>
39``` 46```
40 47
41## The flow 48_user_ passes this token to _client_, which then sends `connect` request to _remote-signer_ via the specified relays. Optional secret can be used for single successfully established connection only, _remote-signer_ SHOULD ignore new attempts to establish connection with old secret.
42
431. Client creates a local keypair. This keypair doesn't need to be communicated to the user since it's largely disposable (i.e. the user doesn't need to see this pubkey). Clients might choose to store it locally and they should delete it when the user logs out.
442. Client gets the remote user pubkey (either via a `bunker://` connection string or a NIP-05 login-flow; shown below)
453. Clients use the local keypair to send requests to the remote signer by `p`-tagging and encrypting to the remote user pubkey.
464. The remote signer responds to the client by `p`-tagging and encrypting to the local keypair pubkey.
47 49
48### Example flow for signing an event 50### Direct connection initiated by the _client_
49 51
50- Remote user pubkey (e.g. signing as) `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52` 52_client_ provides a connection token in the form:
51- Local pubkey is `eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86`
52 53
53#### Signature request
54
55```json
56{
57 "kind": 24133,
58 "pubkey": "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86",
59 "content": nip04({
60 "id": <random_string>,
61 "method": "sign_event",
62 "params": [json_stringified(<{
63 content: "Hello, I'm signing remotely",
64 pubkey: "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
65 // ...the rest of the event data
66 }>)]
67 }),
68 "tags": [["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"]], // p-tags the remote user pubkey
69}
70``` 54```
71 55nostrconnect://<client-pubkey>?relay=<wss://relay-to-connect-on>&metadata=<json metadata: {"name":"...", "url": "...", "description": "...", "perms": "..."}>&secret=<required-secret-value>
72#### Response event
73
74```json
75{
76 "kind": 24133,
77 "pubkey": "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
78 "content": nip04({
79 "id": <random_string>,
80 "result": json_stringified(<signed-event>)
81 }),
82 "tags": [["p", "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86"]], // p-tags the local keypair pubkey
83}
84``` 56```
85 57_user_ passes this token to _remote-signer_, which then sends `connect` *response* event to the `client-pubkey` via the specified relays. Client discovers `remote-signer-pubkey` from connect response author. `secret` value MUST be provided to avoid connection spoofing, _client_ MUST validate the `secret` returned by `connect` response.
86#### Diagram
87
88![signing-example](https://i.nostr.build/P3gW.png)
89 58
90## Request Events `kind: 24133` 59## Request Events `kind: 24133`
91 60
92```json 61```jsonc
93{ 62{
94 "id": <id>,
95 "kind": 24133, 63 "kind": 24133,
96 "pubkey": <local_keypair_pubkey>, 64 "pubkey": <local_keypair_pubkey>,
97 "content": <nip04(<request>)>, 65 "content": <nip04(<request>)>,
98 "tags": [["p", <remote_user_pubkey>]], // NB: in the `create_account` event, the remote signer pubkey should be `p` tagged. 66 "tags": [["p", <remote-signer-pubkey>]],
99 "created_at": <unix timestamp in seconds>
100} 67}
101``` 68```
102 69
103The `content` field is a JSON-RPC-like message that is [NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md) encrypted and has the following structure: 70The `content` field is a JSON-RPC-like message that is [NIP-04](04.md) encrypted and has the following structure:
104 71
105```json 72```jsonc
106{ 73{
107 "id": <random_string>, 74 "id": <random_string>,
108 "method": <method_name>, 75 "method": <method_name>,
@@ -116,23 +83,23 @@ The `content` field is a JSON-RPC-like message that is [NIP-04](https://github.c
116 83
117### Methods/Commands 84### Methods/Commands
118 85
119Each of the following are methods that the client sends to the remote signer. 86Each of the following are methods that the _client_ sends to the _remote-signer_.
120 87
121| Command | Params | Result | 88| Command | Params | Result |
122| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- | 89| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- |
123| `connect` | `[<remote_user_pubkey>, <optional_secret>, <optional_requested_permissions>]` | "ack" | 90| `connect` | `[<remote-signer-pubkey>, <optional_secret>, <optional_requested_permissions>]` | "ack" OR `<required-secret-value>` |
124| `sign_event` | `[<json_stringified_event_to_sign>]` | `json_stringified(<signed_event>)` | 91| `sign_event` | `[<{kind, content, tags, created_at}>]` | `json_stringified(<signed_event>)` |
125| `ping` | `[]` | "pong" | 92| `ping` | `[]` | "pong" |
126| `get_relays` | `[]` | `json_stringified({<relay_url>: {read: <boolean>, write: <boolean>}})` | 93| `get_relays` | `[]` | `json_stringified({<relay_url>: {read: <boolean>, write: <boolean>}})` |
127| `get_public_key` | `[]` | `<hex-pubkey>` | 94| `get_public_key` | `[]` | `<user-pubkey>` |
128| `nip04_encrypt` | `[<third_party_pubkey>, <plaintext_to_encrypt>]` | `<nip04_ciphertext>` | 95| `nip04_encrypt` | `[<third_party_pubkey>, <plaintext_to_encrypt>]` | `<nip04_ciphertext>` |
129| `nip04_decrypt` | `[<third_party_pubkey>, <nip04_ciphertext_to_decrypt>]` | `<plaintext>` | 96| `nip04_decrypt` | `[<third_party_pubkey>, <nip04_ciphertext_to_decrypt>]` | `<plaintext>` |
130| `nip44_encrypt` | `[<third_party_pubkey>, <plaintext_to_encrypt>]` | `<nip44_ciphertext>` | 97| `nip44_encrypt` | `[<third_party_pubkey>, <plaintext_to_encrypt>]` | `<nip44_ciphertext>` |
131| `nip44_decrypt` | `[<third_party_pubkey>, <nip44_ciphertext_to_decrypt>]` | `<plaintext>` | 98| `nip44_decrypt` | `[<third_party_pubkey>, <nip44_ciphertext_to_decrypt>]` | `<plaintext>` |
132 99
133### Requested permissions 100### Requested permissions
134 101
135The `connect` method may be provided with `optional_requested_permissions` for user convenience. The permissions are a comma-separated list of `method[:params]`, i.e. `nip04_encrypt,sign_event:4` meaning permissions to call `nip04_encrypt` and to call `sign_event` with `kind:4`. Optional parameter for `sign_event` is the kind number, parameters for other methods are to be defined later. 102The `connect` method may be provided with `optional_requested_permissions` for user convenience. The permissions are a comma-separated list of `method[:params]`, i.e. `nip04_encrypt,sign_event:4` meaning permissions to call `nip04_encrypt` and to call `sign_event` with `kind:4`. Optional parameter for `sign_event` is the kind number, parameters for other methods are to be defined later. Same permission format may be used for `perms` field of `metadata` in `nostrconnect://` string.
136 103
137## Response Events `kind:24133` 104## Response Events `kind:24133`
138 105
@@ -140,87 +107,111 @@ The `connect` method may be provided with `optional_requested_permissions` for u
140{ 107{
141 "id": <id>, 108 "id": <id>,
142 "kind": 24133, 109 "kind": 24133,
143 "pubkey": <remote_signer_pubkey>, 110 "pubkey": <remote-signer-pubkey>,
144 "content": <nip04(<response>)>, 111 "content": <nip04(<response>)>,
145 "tags": [["p", <local_keypair_pubkey>]], 112 "tags": [["p", <client-pubkey>]],
146 "created_at": <unix timestamp in seconds> 113 "created_at": <unix timestamp in seconds>
147} 114}
148``` 115```
149 116
150The `content` field is a JSON-RPC-like message that is [NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md) encrypted and has the following structure: 117The `content` field is a JSON-RPC-like message that is [NIP-04](04.md) encrypted and has the following structure:
151 118
152```json 119```json
153{ 120{
154 "id": <request_id>, 121 "id": <request_id>,
155 "result": <results_string>, 122 "result": <results_string>,
156 "error": <error_string> 123 "error": <optional_error_string>
157} 124}
158``` 125```
159 126
160- `id` is the request ID that this response is for. 127- `id` is the request ID that this response is for.
161- `results` is a string of the result of the call (this can be either a string or a JSON stringified object) 128- `results` is a string of the result of the call (this can be either a string or a JSON stringified object)
162- `error` is an error in string form. 129- `error`, _optionally_, it is an error in string form, if any. Its presence indicates an error with the request.
163 130
164### Auth Challenges 131## Example flow for signing an event
165 132
166An Auth Challenge is a response that a remote signer can send back when it needs the user to authenticate via other means. This is currently used in the OAuth-like flow enabled by signers like [Nsecbunker](https://github.com/kind-0/nsecbunkerd/). The response `content` object will take the following form: 133- `remote-signer-pubkey` is `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
134- `user-pubkey` is also `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
135- `client-pubkey` is `eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86`
167 136
168```json 137### Signature request
138
139```jsonc
169{ 140{
170 "id": <request_id>, 141 "kind": 24133,
171 "result": "auth_url", 142 "pubkey": "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86",
172 "error": <URL_to_display_to_end_user> 143 "content": nip04({
144 "id": <random_string>,
145 "method": "sign_event",
146 "params": [json_stringified(<{
147 content: "Hello, I'm signing remotely",
148 kind: 1,
149 tags: [],
150 created_at: 1714078911
151 }>)]
152 }),
153 "tags": [["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"]], // p-tags the remote-signer-pubkey
173} 154}
174``` 155```
175 156
176Clients should display (in a popup or new tab) the URL from the `error` field and then subscribe/listen for another response from the remote signer (reusing the same request ID). This event will be sent once the user authenticates in the other window (or will never arrive if the user doesn't authenticate). It's also possible to add a `redirect_uri` url parameter to the auth_url, which is helpful in situations when a client cannot open a new window or tab to display the auth challenge. 157### Response event
177
178#### Example event signing request with auth challenge
179
180![signing-example-with-auth-challenge](https://i.nostr.build/W3aj.png)
181
182## Remote Signer Commands
183
184Remote signers might support additional commands when communicating directly with it. These commands follow the same flow as noted above, the only difference is that when the client sends a request event, the `p`-tag is the pubkey of the remote signer itself and the `content` payload is encrypted to the same remote signer pubkey.
185 158
186### Methods/Commands 159```jsonc
187 160{
188Each of the following are methods that the client sends to the remote signer. 161 "kind": 24133,
189 162 "pubkey": "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
190| Command | Params | Result | 163 "content": nip04({
191| ---------------- | ------------------------------------------ | ------------------------------------ | 164 "id": <random_string>,
192| `create_account` | `[<username>, <domain>, <optional_email>, <optional_requested_permissions>]` | `<newly_created_remote_user_pubkey>` | 165 "result": json_stringified(<signed-event>)
166 }),
167 "tags": [["p", "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86"]], // p-tags the client-pubkey
168}
169```
193 170
194## Appendix 171### Diagram
195 172
196### NIP-05 Login Flow 173![signing-example](https://i.nostr.build/P3gW.png)
197 174
198Clients might choose to present a more familiar login flow, so users can type a NIP-05 address instead of a `bunker://` string.
199 175
200When the user types a NIP-05 the client: 176## Auth Challenges
201 177
202- Queries the `/.well-known/nostr.json` file from the domain for the NIP-05 address provided to get the user's pubkey (this is the **remote user pubkey**) 178An Auth Challenge is a response that a _remote-signer_ can send back when it needs the _user_ to authenticate via other means. The response `content` object will take the following form:
203- In the same `/.well-known/nostr.json` file, queries for the `nip46` key to get the relays that the remote signer will be listening on.
204- Now the client has enough information to send commands to the remote signer on behalf of the user.
205 179
206### OAuth-like Flow 180```json
181{
182 "id": <request_id>,
183 "result": "auth_url",
184 "error": <URL_to_display_to_end_user>
185}
186```
207 187
208#### Remote signer discovery via NIP-89 188_client_ should display (in a popup or new tab) the URL from the `error` field and then subscribe/listen for another response from the _remote-signer_ (reusing the same request ID). This event will be sent once the user authenticates in the other window (or will never arrive if the user doesn't authenticate).
209 189
210In this last case, most often used to fascilitate an OAuth-like signin flow, the client first looks for remote signers that have announced themselves via NIP-89 application handler events. 190### Example event signing request with auth challenge
211 191
212First the client will query for `kind: 31990` events that have a `k` tag of `24133`. 192![signing-example-with-auth-challenge](https://i.nostr.build/W3aj.png)
213 193
214These are generally shown to a user, and once the user selects which remote signer to use and provides the remote user pubkey they want to use (via npub, pubkey, or nip-05 value), the client can initiate a connection. Note that it's on the user to select the remote signer that is actually managing the remote key that they would like to use in this case. If the remote user pubkey is managed on another remote signer, the connection will fail. 194## Appendix
215 195
216In addition, it's important that clients validate that the pubkey of the announced remote signer matches the pubkey of the `_` entry in the `/.well-known/nostr.json` file of the remote signer's announced domain. 196### Announcing _remote-signer_ metadata
217 197
218Clients that allow users to create new accounts should also consider validating the availability of a given username in the namespace of remote signer's domain by checking the `/.well-known/nostr.json` file for existing usernames. Clients can then show users feedback in the UI before sending a `create_account` event to the remote signer and receiving an error in return. Ideally, remote signers would also respond with understandable error messages if a client tries to create an account with an existing username. 198_remote-signer_ MAY publish it's metadata by using [NIP-05](05.md) and [NIP-89](89.md). With NIP-05, a request to `<remote-signer>/.well-known/nostr.json?name=_` MAY return this:
199```jsonc
200{
201 "names":{
202 "_": <remote-signer-app-pubkey>,
203 },
204 "nip46": {
205 "relays": ["wss://relay1","wss://relay2"...],
206 "nostrconnect_url": "https://remote-signer-domain.com/<nostrconnect>"
207 }
208}
209```
219 210
220#### Example Oauth-like flow to create a new user account with Nsecbunker 211The `<remote-signer-app-pubkey>` MAY be used to verify the domain from _remote-signer_'s NIP-89 event (see below). `relays` SHOULD be used to construct a more precise `nostrconnect://` string for the specific `remote-signer`. `nostrconnect_url` template MAY be used to redirect users to _remote-signer_'s connection flow by replacing `<nostrconnect>` placeholder with an actual `nostrconnect://` string.
221 212
222Coming soon... 213### Remote signer discovery via NIP-89
223 214
224## References 215_remote-signer_ MAY publish a NIP-89 `kind: 31990` event with `k` tag of `24133`, which MAY also include one or more `relay` tags and MAY include `nostrconnect_url` tag. The semantics of `relay` and `nostrconnect_url` tags are the same as in the section above.
225 216
226- [NIP-04 - Encryption](https://github.com/nostr-protocol/nips/blob/master/04.md) 217_client_ MAY improve UX by discovering _remote-signers_ using their `kind: 31990` events. _client_ MAY then pre-generate `nostrconnect://` strings for the _remote-signers_, and SHOULD in that case verify that `kind: 31990` event's author is mentioned in signer's `nostr.json?name=_` file as `<remote-signer-app-pubkey>`.
generated by cgit v1.2.3 (git 2.39.1) at 2026-08-22 17:45:04 +0000