Skip to content

Commit

Permalink
New version of NIP-46 (#1047)
Browse files Browse the repository at this point in the history 
* New version of NIP-46

* Update pubkey references

* Document what we have

* Update terms and kind number in discovery

* Update encypt/decrypt calls to handle arrays. Add redirect_uri param for auth_challenges

* Move remote signer commands to own section, add appendix for oauth-like stuff.

* Add diagrams
  • Loading branch information
@erskingardner
erskingardner authored Feb 20, 2024
1 parent cbffa7a commit c6cd655
Showing 1 changed file with 195 additions and 70 deletions.
265 changes: 195 additions & 70 deletions 46.md
View file
Original file line number Diff line number Diff line change
@@ -1,98 +1,223 @@
NIP-46
======
# NIP-46 - Nostr Remote Signing

Nostr Connect
-------------
## Rationale

`draft` `optional`
Private keys should be exposed to as few systems - apps, operating systems, devices - as possible as each system adds to the attack surface.

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.
This NIP describes a method for 2-way communication between a remote signer and a 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
## Terminology

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.
- **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.

### Started by the signer (nsecBunker)
All pubkeys specified in this NIP are in hex format.

The remote signer generates a connection token in the form
## Initiating a connection

To initiate a connection between a client and a remote signer there are a few different options.

### 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:

```
bunker://<remote-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).

### 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).

```
bunker://<hex-pubkey>?relay=wss://...&relay=wss://...&secret=<optional-secret>
nostrconnect://<local-keypair-pubkey>?relay=<wss://relay-to-connect-on>&metadata=<json metadata in the form: {"name":"...", "url": "...", "description": "..."}>
```

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.
## 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.

### Example flow for signing an event

### Started by the client
- Remote user pubkey (e.g. signing as) `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
- Local pubkey is `eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86`

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

```json
{
"kind": 24133,
"pubkey": "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86",
"content": nip04({
"id": <random_string>,
"method": "sign_event",
"params": [json_stringified(<{
content: "Hello, I'm signing remotely",
pubkey: "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
// ...the rest of the event data
}>)]
}),
"tags": [["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"]], // p-tags the remote user pubkey
}
```
nostrconnect://<client-key-hex>?relay=wss://...&metadata={"name":"...", "url": "...", "description": "..."}

#### Response event

```json
{
"kind": 24133,
"pubkey": "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
"content": nip04({
"id": <random_string>,
"result": json_stringified(<signed-event>)
}),
"tags": [["p", "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86"]], // p-tags the local keypair pubkey
}
```

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

## Event payloads
![signing-example](https://i.nostr.build/P3gW.png)

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 below).
## Request Events `kind: 24133`

```json
{
"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>,
}
```

Events sent by the client to the remote signer have the following format:
The `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:

```js
```json
{
"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]})",
...
"id": <random_string>,
"method": <method_name>,
"params": [array_of_strings]
}
```

And the events the remote signer sends to the client have the following format:
- `id` is a random string that is a request ID. This same ID will be sent back in the response payload.
- `method` is the name of the method/command (detailed below).
- `params` is a positional array of string parameters.

### Methods/Commands

Each of the following are methods that the client sends to the remote signer.

```js
"pubkey": "<signer-key-hex>"
"kind": 24133,
"tags": [
["p", "<client-key-hex>"]
],
"content": "nip04_encrypted_json({id: <request-id>, result: <string>, error: <reason-string>})",
...
| Command | Params | Result |
| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- |
| `connect` | `[<remote_user_pubkey>, <optional_secret>]` | "ack" |
| `sign_event` | `[<json_stringified_event_to_sign>]` | `json_stringified(<signed_event>)` |
| `ping` | `[]` | "pong" |
| `get_relays` | `[]` | `json_stringified({<relay_url>: {read: <boolean>, write: <boolean>}})` |
| `get_public_key` | `[]` | `<hex-pubkey>` |
| `nip04_encrypt` | `[<third_party_pubkey>, <plaintext_to_encrypt>]` | `<nip04_ciphertext>` |
| `nip04_decrypt` | `[<third_party_pubkey>, <ciphertext_to_decrypt>]` | `<plaintext>` |
| `nip44_conversation_key` | Potential future addition | |
| `nip44_encrypt` | Potential future addition | |
| `nip44_decrypt` | Potential future addition | |

## Response Events `kind:24133`

```json
{
"id": <id>,
"kind": 24133,
"pubkey": <remote_signer_pubkey>,
"content": <nip04(<response>)>,
"tags": [["p", <local_keypair_pubkey>]],
"created_at": <unix timestamp in seconds>,
}
```

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"`
The `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:

```json
{
"id": <request_id>,
"result": <results_string>,
"error": <error_string>
}
```

- `id` is the request ID that this response is for.
- `results` is a string of the result of the call (this can be either a string or a JSON stringified object)
- `error` is an error in string form.

### Auth Challenges

An 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:

```json
{
"id": <request_id>,
"result": "auth_url",
"error": <URL_to_display_to_end_user>
}
```

Clients 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.

#### Example event signing request with auth challenge

![signing-example-with-auth-challenge](https://i.nostr.build/W3aj.png)

## 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>]` | `<newly_created_remote_user_pubkey>` |

## Appendix

### NIP-05 Login Flow

Clients might choose to present a more familiar login flow, so users can type a NIP-05 address instead of a `bunker://` string.

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**)
- 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.

### OAuth-like Flow

#### Remote signer discovery via NIP-89

In 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.

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.

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.

#### Example Oauth-like flow to create a new user account with Nsecbunker

Coming soon...

## References

- [NIP-04 - Encryption](https://github.com/nostr-protocol/nips/blob/master/04.md)

0 comments on commit c6cd655

Please sign in to comment.