mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-12-13 02:46:24 +00:00
nip46: remove words, introduce distinction between bunker key and user key.
This commit is contained in:
fiatjaf
parent
e3afd7ac5b
commit
42a4f43c93
85
46.md
85
46.md
@ -4,6 +4,10 @@ NIP-46
|
||||
Nostr Remote Signing
|
||||
--------------------
|
||||
|
||||
## Changes
|
||||
|
||||
`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.
|
||||
|
||||
## Rationale
|
||||
|
||||
Private keys should be exposed to as few systems - apps, operating systems, devices - as possible as each system adds to the attack surface.
|
||||
@ -12,51 +16,53 @@ This NIP describes a method for 2-way communication between a remote signer and
|
||||
|
||||
## Terminology
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
- **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.
|
||||
- **user**: A person that is trying to use Nostr.
|
||||
- **client**: A user-facing application that _user_ is looking at and clicking buttons in. This application will send requests to _remote-signer_.
|
||||
- **remote-signer**: A daemon or server running somewhere that will answer requests from _client_, also known as "bunker".
|
||||
- **client-keypair/pubkey**: The keys generated by _client_. Used to encrypt content and communicate with _remote-signer_.
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
All pubkeys specified in this NIP are in hex format.
|
||||
|
||||
## Initiating a connection
|
||||
|
||||
To initiate a connection between a client and a remote signer there are a few different options.
|
||||
There are two ways to initiate a connection:
|
||||
|
||||
### Direct connection initiated by remote signer
|
||||
### Direct connection initiated by _remote-signer_
|
||||
|
||||
This 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.
|
||||
|
||||
The remote signer would provide a connection token in the form:
|
||||
_remote-signer_ provides connection token in the form:
|
||||
|
||||
```
|
||||
bunker://<remote-user-pubkey>?relay=<wss://relay-to-connect-on>&relay=<wss://another-relay-to-connect-on>&secret=<optional-secret-value>
|
||||
bunker://<remote-signer-pubkey>?relay=<wss://relay-to-connect-on>&relay=<wss://another-relay-to-connect-on>&secret=<optional-secret-value>
|
||||
```
|
||||
|
||||
This 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). Optional secret can be used for single successfully established connection only, remote signer SHOULD ignore new attempts to establish connection with old optional secret.
|
||||
_user_ pastes this token on _client_, which then uses the details to connect 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 optional secret.
|
||||
|
||||
### Direct connection initiated by the client
|
||||
|
||||
In 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).
|
||||
In this case, basically the opposite direction of the first case, _client_ provides a connection token (or encodes the token in a QR code) and _remote-signer_ initiates a connection via the specified relays.
|
||||
|
||||
```
|
||||
nostrconnect://<local-keypair-pubkey>?relay=<wss://relay-to-connect-on>&metadata=<json metadata in the form: {"name":"...", "url": "...", "description": "..."}>
|
||||
nostrconnect://<client-pubkey>?relay=<wss://relay-to-connect-on>&metadata=<json metadata in the form: {"name":"...", "url": "...", "description": "..."}>
|
||||
```
|
||||
|
||||
## The flow
|
||||
|
||||
1. 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.
|
||||
2. Client gets the remote user pubkey (either via a `bunker://` connection string or a NIP-05 login-flow; shown below)
|
||||
3. Clients use the local keypair to send requests to the remote signer by `p`-tagging and encrypting to the remote user pubkey.
|
||||
4. The remote signer responds to the client by `p`-tagging and encrypting to the local keypair pubkey.
|
||||
1. _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;
|
||||
2. _client_ gets `remote-signer-pubkey` (either via a `bunker://` connection string or a NIP-05 login-flow; shown below);
|
||||
3. _client_ use `client-keypair` to send requests to _remote-signer_ by `p`-tagging and encrypting to `remote-signer-pubkey`;
|
||||
4. _remote-signer_ responds to _client_ by `p`-tagging and encrypting to the `client-pubkey`.
|
||||
|
||||
### Example flow for signing an event
|
||||
|
||||
- Remote user pubkey (e.g. signing as) `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
|
||||
- Local pubkey is `eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86`
|
||||
- `remote-signer-pubkey` is `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
|
||||
- `user-pubkey` is also `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
|
||||
- `client-pubkey` is `eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86`
|
||||
|
||||
#### Signature request
|
||||
|
||||
```json
|
||||
```js
|
||||
{
|
||||
"kind": 24133,
|
||||
"pubkey": "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86",
|
||||
@ -70,13 +76,13 @@ nostrconnect://<local-keypair-pubkey>?relay=<wss://relay-to-connect-on>&metadata
|
||||
created_at: 1714078911
|
||||
}>)]
|
||||
}),
|
||||
"tags": [["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"]], // p-tags the remote user pubkey
|
||||
"tags": [["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"]], // p-tags the remote-signer-pubkey
|
||||
}
|
||||
```
|
||||
|
||||
#### Response event
|
||||
|
||||
```json
|
||||
```js
|
||||
{
|
||||
"kind": 24133,
|
||||
"pubkey": "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
|
||||
@ -84,7 +90,7 @@ nostrconnect://<local-keypair-pubkey>?relay=<wss://relay-to-connect-on>&metadata
|
||||
"id": <random_string>,
|
||||
"result": json_stringified(<signed-event>)
|
||||
}),
|
||||
"tags": [["p", "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86"]], // p-tags the local keypair pubkey
|
||||
"tags": [["p", "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86"]], // p-tags the client-pubkey
|
||||
}
|
||||
```
|
||||
|
||||
@ -94,20 +100,18 @@ nostrconnect://<local-keypair-pubkey>?relay=<wss://relay-to-connect-on>&metadata
|
||||
|
||||
## Request Events `kind: 24133`
|
||||
|
||||
```jsonc
|
||||
```js
|
||||
{
|
||||
"id": <id>,
|
||||
"kind": 24133,
|
||||
"pubkey": <local_keypair_pubkey>,
|
||||
"content": <nip04(<request>)>,
|
||||
"tags": [["p", <remote_user_pubkey>]], // NB: in the `create_account` event, the remote signer pubkey should be `p` tagged.
|
||||
"created_at": <unix timestamp in seconds>
|
||||
"tags": [["p", <remote-signer-pubkey>]],
|
||||
}
|
||||
```
|
||||
|
||||
The `content` field is a JSON-RPC-like message that is [NIP-04](04.md) encrypted and has the following structure:
|
||||
|
||||
```json
|
||||
```jsonc
|
||||
{
|
||||
"id": <random_string>,
|
||||
"method": <method_name>,
|
||||
@ -125,15 +129,16 @@ Each of the following are methods that the client sends to the remote signer.
|
||||
|
||||
| Command | Params | Result |
|
||||
| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| `connect` | `[<remote_user_pubkey>, <optional_secret>, <optional_requested_permissions>]` | "ack" |
|
||||
| `connect` | `[<user_pubkey>, <optional_secret>, <optional_requested_permissions>]` | "ack" |
|
||||
| `sign_event` | `[<{kind, content, tags, created_at}>]` | `json_stringified(<signed_event>)` |
|
||||
| `ping` | `[]` | "pong" |
|
||||
| `get_relays` | `[]` | `json_stringified({<relay_url>: {read: <boolean>, write: <boolean>}})` |
|
||||
| `get_public_key` | `[]` | `<hex-pubkey>` |
|
||||
| `get_public_key` | `[]` | `<user-pubkey>` |
|
||||
| `nip04_encrypt` | `[<third_party_pubkey>, <plaintext_to_encrypt>]` | `<nip04_ciphertext>` |
|
||||
| `nip04_decrypt` | `[<third_party_pubkey>, <nip04_ciphertext_to_decrypt>]` | `<plaintext>` |
|
||||
| `nip44_encrypt` | `[<third_party_pubkey>, <plaintext_to_encrypt>]` | `<nip44_ciphertext>` |
|
||||
| `nip44_decrypt` | `[<third_party_pubkey>, <nip44_ciphertext_to_decrypt>]` | `<plaintext>` |
|
||||
| `create_account` | `[<username>, <domain>, <optional_email>, <optional_requested_permissions>]` | `<newly_created_user_pubkey>` |
|
||||
|
||||
### Requested permissions
|
||||
|
||||
@ -145,9 +150,9 @@ The `connect` method may be provided with `optional_requested_permissions` for u
|
||||
{
|
||||
"id": <id>,
|
||||
"kind": 24133,
|
||||
"pubkey": <remote_signer_pubkey>,
|
||||
"pubkey": <remote-signer-pubkey>,
|
||||
"content": <nip04(<response>)>,
|
||||
"tags": [["p", <local_keypair_pubkey>]],
|
||||
"tags": [["p", <client-pubkey>]],
|
||||
"created_at": <unix timestamp in seconds>
|
||||
}
|
||||
```
|
||||
@ -184,18 +189,6 @@ Clients should display (in a popup or new tab) the URL from the `error` field an
|
||||
|
||||
|
||||
|
||||
## Remote Signer Commands
|
||||
|
||||
Remote 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.
|
||||
|
||||
### Methods/Commands
|
||||
|
||||
Each of the following are methods that the client sends to the remote signer.
|
||||
|
||||
| Command | Params | Result |
|
||||
| ---------------- | ------------------------------------------ | ------------------------------------ |
|
||||
| `create_account` | `[<username>, <domain>, <optional_email>, <optional_requested_permissions>]` | `<newly_created_remote_user_pubkey>` |
|
||||
|
||||
## Appendix
|
||||
|
||||
### NIP-05 Login Flow
|
||||
@ -204,7 +197,7 @@ Clients might choose to present a more familiar login flow, so users can type a
|
||||
|
||||
When the user types a NIP-05 the client:
|
||||
|
||||
- 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**)
|
||||
- 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 `user-pubkey`)
|
||||
- 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.
|
||||
- Now the client has enough information to send commands to the remote signer on behalf of the user.
|
||||
|
||||
@ -216,9 +209,9 @@ In this last case, most often used to facilitate an OAuth-like signin flow, the
|
||||
|
||||
First the client will query for `kind: 31990` events that have a `k` tag of `24133`.
|
||||
|
||||
These 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.
|
||||
These are generally shown to a user, and once the user selects which remote signer to use and provides the `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 `user-keypair` that they would like to use in this case. If the `user-pubkey` is managed on another _remote-signer_ the connection will fail.
|
||||
|
||||
In 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.
|
||||
In 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.
|
||||
|
||||
Clients 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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user