nips/26.md

NIP: 26

Delegated Event Signing

draft optional author:markharding author:minds

This NIP defines how events can be delegated so that they can be signed by other keypairs.

Another application of this proposal is to abstract away the use of the 'root' keypairs when interacting with clients. For example, a user could generate new keypairs for each client they wish to use and authorize those keypairs to generate events on behalf of their root pubkey, where the root keypair is stored in cold storage.

Introducing the 'delegation' tag

This NIP introduces a new tag: delegation which is formatted as follows:

[
  "delegation",
  <pubkey of the delegator>,
  <conditions query string>,
  <delegation token: 64-byte Schnorr signature of the sha256 hash of the delegation string>
]

Delegation Token

The delegation token should be a 64-byte Schnorr signature of the sha256 hash of the following string:

nostr:delegation:<pubkey of publisher (delegatee)>:<conditions query string>

Conditions Query String

The following fields and operators are supported in the above query string:

Fields:

1. kind
   • Operators:
     • =${KIND_NUMBER} - delegatee may only sign events of this kind
2. created_at
   • Operators:
     • <${TIMESTAMP} - delegatee may only sign events created before the specified timestamp
     • >${TIMESTAMP} - delegatee may only sign events created after the specified timestamp

In order to create a single condition, you must use a supported field and operator. Multiple conditions can be used in a single query string, including on the same field. Conditions must be combined with &.

For example, the following condition strings are valid:

• kind=1&created_at<1675721813
• kind=0&kind=1&created_at>1675721813
• kind=1&created_at>1674777689&created_at<1675721813

For the vast majority of use-cases, it is advisable that query strings should include a created_at after condition reflecting the current time, to prevent the delegatee from publishing historic notes on the delegator's behalf.

Example

# Delegator:
privkey: ee35e8bb71131c02c1d7e73231daa48e9953d329a4b701f7133c8f46dd21139c
pubkey:  8e0d3d3eb2881ec137a11debe736a9086715a8c8beeeda615780064d68bc25dd

# Delegatee:
privkey: 777e4f60b4aa87937e13acc84f7abcc3c93cc035cb4c1e9f7a9086dd78fffce1
pubkey:  477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396

Delegation string to grant note publishing authorization to the delegatee (477318cf) from now, for the next 30 days, given the current timestamp is 1674834236.

nostr:delegation:477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396:kind=1&created_at>1674834236&created_at<1677426236

The delegator (8e0d3d3e) then signs a SHA256 hash of the above delegation string, the result of which is the delegation token:

6f44d7fe4f1c09f3954640fb58bd12bae8bb8ff4120853c4693106c82e920e2b898f1f9ba9bd65449a987c39c0423426ab7b53910c0c6abfb41b30bc16e5f524

The delegatee (477318cf) can now construct an event on behalf of the delegator (8e0d3d3e). The delegatee then signs the event with its own private key and publishes.

{
  "id": "e93c6095c3db1c31d15ac771f8fc5fb672f6e52cd25505099f62cd055523224f",
  "pubkey": "477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396",
  "created_at": 1677426298,
  "kind": 1,
  "tags": [
    [
      "delegation",
      "8e0d3d3eb2881ec137a11debe736a9086715a8c8beeeda615780064d68bc25dd",
      "kind=1&created_at>1674834236&created_at<1677426236",
      "6f44d7fe4f1c09f3954640fb58bd12bae8bb8ff4120853c4693106c82e920e2b898f1f9ba9bd65449a987c39c0423426ab7b53910c0c6abfb41b30bc16e5f524"
    ]
  ],
  "content": "Hello, world!",
  "sig": "633db60e2e7082c13a47a6b19d663d45b2a2ebdeaf0b4c35ef83be2738030c54fc7fd56d139652937cdca875ee61b51904a1d0d0588a6acd6168d7be2909d693"
}

The event should be considered a valid delegation if the conditions are satisfied (kind=1, created_at>1674834236 and created_at<1677426236 in this example) and, upon validation of the delegation token, are found to be unchanged from the conditions in the original delegation string.

Clients should display the delegated note as if it was published directly by the delegator (8e0d3d3e).

Relay & Client Support

Relays should answer requests such as ["REQ", "", {"authors": ["A"]}] by querying both the pubkey and delegation tags [1] value.

Relays SHOULD allow the delegator (8e0d3d3e) to delete the events published by the delegatee (477318cf).

Protocol Handler Support

Using NIP26, a new oauth-style protocol handler can allow oauth-style login for nostr apps that do not want to be the primary custodians of identity keys.:

Consider the following link that can be opened as an intent in browser and mobile apps:

nkey://auth?id=<uuid>&uri=<uri>&kinds=1,2,4,5&action=delegate&from=<epoch>&to=<epoch>&pubkey=<64-char hex pub key>&relays=r1,r2...

This can open up an associated app or browser that displays the requesting URI information in detail, including certificate information.

Care must be taken to let the user know the full scope requested, the ability of the app to be able to post the kinds requested, etc.

• On success:
  • Posts NIP26 delegate info to the requested relays (if any)
  • Optionally posts delegate info to additional relays (if configured
  • POSTs a response to the uri containing a delegate key encrypted with the requested pubkey and information about what was approved (if anything)

  {
   id:"<request-id>",
   status:"authorized",
   key:"<b64 encoded nip44 encrypted with the **pubkey**>",
   from:<epoch-approved-from-time>
   to:<epoch-approved-to-time>,
   kinds: [1,2]
  } 
  

-On rejection, POSTs a "rejection" to the uri { id:"", status:"denied", }