Nostr Book of NIPs

NIP-55

Android Signer Application

draft optional

Rationale

This NIP describes a method for 2-way communication between an Android signer and any Nostr client running on the same device, so that the client never needs to handle the user’s private key. The signer is an Android application; the client may be another Android application or a web page.

Terminology

All pubkeys in this NIP are in hex format.

Communication methods

A client can talk to the signer in three ways:

Setup

To detect and call the signer, an Android client must declare the nostrsigner scheme in its AndroidManifest.xml:

<queries>
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="nostrsigner" />
  </intent>
</queries>

It can then check whether a signer is installed:

fun isExternalSignerInstalled(context: Context): Boolean {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse("nostrsigner:"))
  return context.packageManager.queryIntentActivities(intent, 0).isNotEmpty()
}

Initiating a connection

  1. client sends a get_public_key request.
  2. signer responds with the user-pubkey and its package name.
  3. client stores both, and SHOULD NOT call get_public_key again while the user stays logged in.
  4. client addresses all further requests to that package name.

A client MAY pass a list of permissions with get_public_key so the user can pre-authorize methods (used by the Content Resolver to answer in the background). Each permission is an object with a type (a method name) and, for sign_event, an optional kind:

[{ "type": "sign_event", "kind": 22242 }, { "type": "nip44_decrypt" }]

Methods

Every request has a type (the method name) and a payload. The payload is passed differently per transport (see below) but its meaning is shared:

Method Payload Extra params Result
get_public_key (empty) permissions user-pubkey
sign_event event JSON current_user the signature, and signed event
nip04_encrypt plaintext pubkey, current_user the ciphertext
nip44_encrypt plaintext pubkey, current_user the ciphertext
nip04_decrypt ciphertext pubkey, current_user the plaintext
nip44_decrypt ciphertext pubkey, current_user the plaintext
decrypt_zap_event event JSON current_user the decrypted event JSON

Using Intents

The payload is the nostrsigner: URI data; all other params are intent extras. The result is returned via registerForActivityResult / rememberLauncherForActivityResult.

val intent = Intent(Intent.ACTION_VIEW, Uri.parse("nostrsigner:$payload")).apply {
  `package` = signerPackageName        // omit only for get_public_key
  putExtra("type", "sign_event")
  putExtra("id", event.id)             // optional, echoed back
  putExtra("current_user", userPubkey)
}
launcher.launch(intent)

The result is read from the returned intent’s extras:

Extra Description
result the method result (pubkey, signature, ciphertext, etc.)
id the id sent in the request
event the signed event JSON (sign_event only)
package the signer package name (get_public_key only)
rejected true when the user rejected the request

A resultCode other than Activity.RESULT_OK means the signer failed (e.g. it crashed), not that the user rejected the request. When the user rejects, the signer returns RESULT_OK with a rejected extra set to true.

onResult = { result ->
  if (result.resultCode != Activity.RESULT_OK) {
    // signer error (e.g. crash)
  } else if (result.data?.getBooleanExtra("rejected", false) == true) {
    // user rejected the request
  } else {
    val value = result.data?.getStringExtra("result")
  }
}

To sign multiple events without reopening the signer for each one, client adds the flags below and the signer returns an array of results. The signer must declare android:launchMode="singleTop" for this to work.

intent.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP)

// signer answers with:
intent.putExtra("results", listOf(Result(package = signerPackageName, result = signature, id = intentId)).toJson())

Using Content Resolver

The client queries content://<package-name>.<TYPE> (e.g. SIGN_EVENT, NIP44_ENCRYPT). The query’s selectionArgs carry the payload and params in the order [payload, pubkey, current_user]:

val result = context.contentResolver.query(
  Uri.parse("content://com.example.signer.SIGN_EVENT"),
  listOf(eventJson, "", loggedInUserPubkey),
  null, null, null,
)

The cursor returns a result column (and, for sign_event, an event column with the signed event JSON). The query returns null, or a rejected column is present, when:

if (result == null) return
if (result.getColumnIndex("rejected") > -1) return
if (result.moveToFirst()) {
  val value = result.getString(result.getColumnIndex("result"))
  // for sign_event also: result.getColumnIndex("event")
}

Clients SHOULD store the user-pubkey locally and avoid calling get_public_key after the user is logged in.

Using Web Applications

Web clients can’t receive a result from an intent, so the signer returns the result via a callbackUrl (appended to the URL) or, if none is given, by copying it to the clipboard. The request is a nostrsigner: URL whose path is the payload and whose query string carries the params:

nostrsigner:<payload>?type=<method>&pubkey=<hex_pubkey>&callbackUrl=https://example.com/?result=

Query parameters:

window.href = `nostrsigner:${eventJson}?compressionType=none&returnType=signature&type=sign_event&callbackUrl=https://example.com/?event=`;

Consider using NIP-46: Nostr Remote Signing for web applications. With the approach here the web client can’t call the signer in the background, so the user sees a popup for every request.

Example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
    <h1>Test</h1>

    <script>
        window.onload = function() {
            var params = new URL(window.location.href).searchParams;
            var result = params.get("event");
            if (result) alert(result);

            var json = { kind: 1, content: "test" };
            var encodedJson = encodeURIComponent(JSON.stringify(json));
            var anchor = document.createElement("a");
            anchor.href = `nostrsigner:${encodedJson}?compressionType=none&returnType=signature&type=sign_event&callbackUrl=https://example.com/?event=`;
            anchor.textContent = "Open External Signer";
            document.body.appendChild(anchor);
        }
    </script>
</body>
</html>