NIPs nostr improvement proposals

NIP-46 - Nostr Remote Signing

Table of Contents

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.

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.

Terminology

All pubkeys specified in this NIP are in hex format.

Initiating a connection

There are two ways to initiate a connection:

Direct connection initiated by remote-signer

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.

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.

nostrconnect://<client-pubkey>?relay=<wss://relay-to-connect-on>&metadata=<json metadata in the form: {"name":"...", "url": "...", "description": "..."}>

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

Signature request

{

    "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

{

    "kind": 24133,

    "pubkey": "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52",

    "content": nip04({

        "id": <random_string>,

        "result": json_stringified(<signed-event>)

    }),

    "tags": [["p", "eff37350d839ce3707332348af4549a96051bd695d3223af4aabce4993531d86"]], // p-tags the client-pubkey

}

Diagram

signing-example

Request Events kind: 24133

{

    "kind": 24133,

    "pubkey": <local_keypair_pubkey>,

    "content": <nip04(<request>)>,

    "tags": [["p", <remote-signer-pubkey>]],

}

The content field is a JSON-RPC-like message that is NIP-04 encrypted and has the following structure:

{

    "id": <random_string>,

    "method": <method_name>,

    "params": [array_of_strings]

}

Methods/Commands

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"
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 [] <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

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.

Response Events kind:24133

{

    "id": <id>,

    "kind": 24133,

    "pubkey": <remote-signer-pubkey>,

    "content": <nip04(<response>)>,

    "tags": [["p", <client-pubkey>]],

    "created_at": <unix timestamp in seconds>

}

The content field is a JSON-RPC-like message that is NIP-04 encrypted and has the following structure:

{

    "id": <request_id>,

    "result": <results_string>,

    "error": <optional_error_string>

}

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. The response content object will take the following form:

{

    "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

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:

OAuth-like Flow

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