mirror of
https://github.com/nostr-protocol/nips.git
synced 2024-12-22 08:25:53 -05:00
Nip46 upgrade part2: remove nip05 and create_account, clarify nostrconnect, cleanup, add nip05 signer metadata (#1553)
This commit is contained in:
Nostr.Band
GitHub
parent
6376fd8c69
commit
926a51e722
173
46.md
173
46.md
|
|
@ -6,7 +6,7 @@ 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.
|
||||
`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.
|
||||
|
||||
## Rationale
|
||||
|
||||
|
|
@ -25,6 +25,14 @@ This NIP describes a method for 2-way communication between a remote signer and
|
|||
|
||||
All pubkeys specified in this NIP are in hex format.
|
||||
|
||||
## Overview
|
||||
|
||||
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. A connection is established (see below), _remote-signer_ learns `client-pubkey`, _client_ learns `remote-signer-pubkey`.
|
||||
3. _client_ uses `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`.
|
||||
5. _client_ requests `get_public_key` to learn `user-pubkey`.
|
||||
|
||||
## Initiating a connection
|
||||
|
||||
There are two ways to initiate a connection:
|
||||
|
|
@ -37,66 +45,16 @@ _remote-signer_ provides connection token in the form:
|
|||
bunker://<remote-signer-pubkey>?relay=<wss://relay-to-connect-on>&relay=<wss://another-relay-to-connect-on>&secret=<optional-secret-value>
|
||||
```
|
||||
|
||||
_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.
|
||||
_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.
|
||||
|
||||
### Direct connection initiated by the client
|
||||
### Direct connection initiated by the _client_
|
||||
|
||||
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.
|
||||
_client_ provides a connection token in the form:
|
||||
|
||||
```
|
||||
nostrconnect://<client-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: {"name":"...", "url": "...", "description": "...", "perms": "..."}>&secret=<required-secret-value>
|
||||
```
|
||||
|
||||
## The flow
|
||||
|
||||
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-signer-pubkey` is `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
|
||||
- `user-pubkey` is also `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
|
||||
- `client-pubkey` is `eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86`
|
||||
|
||||
#### Signature request
|
||||
|
||||
```js
|
||||
{
|
||||
"kind": 24133,
|
||||
"pubkey": "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86",
|
||||
"content": nip04({
|
||||
"id": <random_string>,
|
||||
"method": "sign_event",
|
||||
"params": [json_stringified(<{
|
||||
content: "Hello, I'm signing remotely",
|
||||
kind: 1,
|
||||
tags: [],
|
||||
created_at: 1714078911
|
||||
}>)]
|
||||
}),
|
||||
"tags": [["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"]], // p-tags the remote-signer-pubkey
|
||||
}
|
||||
```
|
||||
|
||||
#### Response event
|
||||
|
||||
```js
|
||||
{
|
||||
"kind": 24133,
|
||||
"pubkey": "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
|
||||
"content": nip04({
|
||||
"id": <random_string>,
|
||||
"result": json_stringified(<signed-event>)
|
||||
}),
|
||||
"tags": [["p", "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86"]], // p-tags the client-pubkey
|
||||
}
|
||||
```
|
||||
|
||||
#### Diagram
|
||||
|
||||
|
||||
_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.
|
||||
|
||||
## Request Events `kind: 24133`
|
||||
|
||||
|
|
@ -125,11 +83,11 @@ The `content` field is a JSON-RPC-like message that is [NIP-04](04.md) encrypted
|
|||
|
||||
### Methods/Commands
|
||||
|
||||
Each of the following are methods that the client sends to the remote signer.
|
||||
Each of the following are methods that the _client_ sends to the _remote-signer_.
|
||||
|
||||
| Command | Params | Result |
|
||||
| ------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| `connect` | `[<user_pubkey>, <optional_secret>, <optional_requested_permissions>]` | "ack" |
|
||||
| `connect` | `[<remote-signer-pubkey>, <optional_secret>, <optional_requested_permissions>]` | "ack" OR `<required-secret-value>` |
|
||||
| `sign_event` | `[<{kind, content, tags, created_at}>]` | `json_stringified(<signed_event>)` |
|
||||
| `ping` | `[]` | "pong" |
|
||||
| `get_relays` | `[]` | `json_stringified({<relay_url>: {read: <boolean>, write: <boolean>}})` |
|
||||
|
|
@ -138,11 +96,10 @@ Each of the following are methods that the client sends to the remote signer.
|
|||
| `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
|
||||
|
||||
The `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.
|
||||
The `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.
|
||||
|
||||
## Response Events `kind:24133`
|
||||
|
||||
|
|
@ -171,9 +128,54 @@ The `content` field is a JSON-RPC-like message that is [NIP-04](04.md) encrypted
|
|||
- `results` is a string of the result of the call (this can be either a string or a JSON stringified object)
|
||||
- `error`, _optionally_, it is an error in string form, if any. Its presence indicates an error with the request.
|
||||
|
||||
### Auth Challenges
|
||||
## Example flow for signing an event
|
||||
|
||||
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:
|
||||
- `remote-signer-pubkey` is `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
|
||||
- `user-pubkey` is also `fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52`
|
||||
- `client-pubkey` is `eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86`
|
||||
|
||||
### Signature request
|
||||
|
||||
```js
|
||||
{
|
||||
"kind": 24133,
|
||||
"pubkey": "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86",
|
||||
"content": nip04({
|
||||
"id": <random_string>,
|
||||
"method": "sign_event",
|
||||
"params": [json_stringified(<{
|
||||
content: "Hello, I'm signing remotely",
|
||||
kind: 1,
|
||||
tags: [],
|
||||
created_at: 1714078911
|
||||
}>)]
|
||||
}),
|
||||
"tags": [["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"]], // p-tags the remote-signer-pubkey
|
||||
}
|
||||
```
|
||||
|
||||
### Response event
|
||||
|
||||
```js
|
||||
{
|
||||
"kind": 24133,
|
||||
"pubkey": "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",
|
||||
"content": nip04({
|
||||
"id": <random_string>,
|
||||
"result": json_stringified(<signed-event>)
|
||||
}),
|
||||
"tags": [["p", "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86"]], // p-tags the client-pubkey
|
||||
}
|
||||
```
|
||||
|
||||
### Diagram
|
||||
|
||||
|
||||
|
||||
|
||||
## 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. The response `content` object will take the following form:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -183,42 +185,33 @@ An Auth Challenge is a response that a remote signer can send back when it needs
|
|||
}
|
||||
```
|
||||
|
||||
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.
|
||||
_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).
|
||||
|
||||
#### Example event signing request with auth challenge
|
||||
### Example event signing request with auth challenge
|
||||
|
||||
|
||||
|
||||
## Appendix
|
||||
|
||||
### NIP-05 Login Flow
|
||||
### Announcing _remote-signer_ metadata
|
||||
|
||||
Clients might choose to present a more familiar login flow, so users can type a NIP-05 address instead of a `bunker://` string.
|
||||
_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:
|
||||
```
|
||||
{
|
||||
"names":{
|
||||
"_": <remote-signer-app-pubkey>,
|
||||
},
|
||||
"nip46": {
|
||||
"relays": ["wss://relay1","wss://relay2"...],
|
||||
"nostrconnect_url": "https://remote-signer-domain.com/<nostrconnect>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When the user types a NIP-05 the client:
|
||||
The `<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.
|
||||
|
||||
- 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.
|
||||
### Remote signer discovery via NIP-89
|
||||
|
||||
### OAuth-like Flow
|
||||
_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.
|
||||
|
||||
#### Remote signer discovery via NIP-89
|
||||
|
||||
In this last case, most often used to facilitate 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 `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.
|
||||
|
||||
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](04.md)
|
||||
_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>`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user