nips/43.md

NIP-43

Delegated Authentication of Clients to Relays

draft optional

This NIP defines how authentication can be delegated so that a user or client can authenticate with a relay using other keypairs.

Motivation

A user may want to delegate authentication to another keypair in order to selectively grant access to relay restricted resources. For example,

• A user may want to login to clients with a NostrConnect remote signer over an authenticated relay that requires membership to send ephemeral events
• A user may want to authorize others to access a particular NIP-71 Restricted Event in exchange for payment or other services
• A user may want to create subscription services to certain kinds of NIP-71 Restricted Event in exchange for payment or other services

Terminology

• delegator: The user who would like to delegate authentication to another key pair.
• delegatee: The alternate key pair the user has delegated authentication to.

Definitions

'auth-delegation' tag

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

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

This tag will only be used on events of kind 22242 - Client Authentication as defined in NIP-42 Authentication of Clients to Relays. Each Client Authentication event MAY contain multiple auth-delegation tags to allow for different authentication delegation conditions for a single key pair.

Authentication Delegation Token

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

nostr|auth-delegation|<pubkey of delegatee>|<delegation conditions>

Delegation Conditions

The delegation conditions define the scope of REQ filters the delegatee has been allowed access to by the delgator. The delegation conditions are comprised of an expiration condition, a mode condition, a filter condition, and a relay condition which are concatenated together with ;.

Expiration Condition

The expiration condition is REQUIRED. The authentication delegation token is invalid if the expiration condition is missing. It is denoted as a unix timestamp in seconds.

The timestamp is the time at which this particular authentication delegation token expires and will no longer be valid. The timestamp is to be compared to the relay's current local time and NOT the created_at field on events.

Mode Condition

The mode condition is OPTIONAL. It indicates whether the delegatee should be fully authenticated as the delegator and granted all access and priveleges that are granted to the delegator. It is denoted by a single integer value:

• 0: Login - (DEFAULT) delegatee should be fully authenticated as the delegator
• 1: Restricted Event Permission - delegatee should not be fully authenticated as the delegator and access is limited by the filter condition

If mode condition is set to 0 it is STRONGLY RECOMMENDED that the expiration condition is set to no more than one day in the future.

Filter Condition

The filter condition is OPTIONAL and only applies if the mode condition is set to 1. It defines what a REQ sent by a delegatee can filter for within NIP-71 Restricted Events. The filter condition is a JSON stringified filter object as defined in NIP-01, however only the following attributes are valid within the filter condition:

• "ids"
• "kinds"
• "since"
• "until"
• "#<single-letter (a-zA-Z)>"

The filter condition ALWAYS IMPLICITLY includes the filter criteria "authors": ["${delegator pubkey}"], even if the filter condition is omitted altogether.

Any REQ filter sent by the delegatee using an authentication delegation token MUST BE narrower in scope than the filter condition in order for the token to be valid for that REQ. In order for an authentication delegation token to be valid for a REQ filter, all filter condition attributes must be found within the REQ filter. The REQ filter is allowed to have additional attributes not contained in the filter condition that add specificity.

Relay Condition

The relay condition is OPTIONAL. It defines which relays the authentication delegation token is valid for. It is denoted as an array of relay URL strings. If this condition is ommited it is assumed that the authentication delegation token is valid for all relays.

Examples

• 1707409439;;; // delegatee can query all restricted events published by the delegator on any relay until Feb 08 2024 16:23:59 GMT
• 9999999999;;{"ids": ["123abc"]};["wss://example.com", "wss://example2.com"] // delegatee can query for event id "123abc" (published by delegator) on relays "wss://example.com" and "wss://example2.com" for forever
• 1707409439;1;; // delegatee can be fully authenticated as delegator on any relay until Feb 08 2024 16:23:59 GMT

Application

Delegated authentication allows delegatees to use NIP-42 Authentication of Clients to Relays with an auth-delegation tag to:

• authenticate as or
• gain access to NIP-71 Restricted Events owned by

the delegator.

The method in which the delegatee obtains the authentication delegation token is not prescribed here and should be detailed in any new specification that employs this NIP. This has been intentionally left unspecified as the range of applications of this NIP are large and may have varying requirements or flows.

When using delegated authentication, the delegatee will respond to authentication challenges with a authentication event that has an additional auth-delegation tag. Once verified, the delegatee will be granted access according to the conditions of the authentication delegation token.

If the filter condition is employed in the authentication delegation conditions the relay SHOULD cache the conditioins for the duration of the authenticated session and ensure that all delegatee REQ filters fall within the granted access.

Example

# Delegator:
privkey: ee35e8bb71131c02c1d7e73231daa48e9953d329a4b701f7133c8f46dd21139c
pubkey:  8e0d3d3eb2881ec137a11debe736a9086715a8c8beeeda615780064d68bc25dd

# Delegatee:
privkey: 777e4f60b4aa87937e13acc84f7abcc3c93cc035cb4c1e9f7a9086dd78fffce1
pubkey:  477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396

Authentication delegation string to grant delegatee (477318cf) permission to authentication as delegator (8e0d3d3e) until Feb 08 2024 16:23:59 GMT.

nostr|auth-delegation|477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396|1707409439;1;;

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

22f12761e0d0311c29341b6c58e2ddfb66ef8895bf7c3c1456dcf5a1d4a1b22b4461d53b47142a516c768abd39366a57c24b4045673a979553201b2f41674c68

The delegatee (477318cf) can now construct an authentication event on behalf of the delegator (8e0d3d3e). The delegatee then signs the authentication event with its own private key and sends it in an AUTH message.

{
  "pubkey": "477318cfb5427b9cfc66a9fa376150c1ddbc62115ae27cef72417eb959691396",
  "created_at": 1707408434,
  "kind": 22242,
  "tags": [
    ["relay", "wss://relay.example.com/"],
    ["challenge", "challengestringhere"]
    [
      "auth-delegation",
      "8e0d3d3eb2881ec137a11debe736a9086715a8c8beeeda615780064d68bc25dd",
      "1707409439;1;;",
      "22f12761e0d0311c29341b6c58e2ddfb66ef8895bf7c3c1456dcf5a1d4a1b22b4461d53b47142a516c768abd39366a57c24b4045673a979553201b2f41674c68"
    ]
  ],
  ...
}

Verification

To verify delegated authentication events, relays must ensure:

• all of the requirements in NIP-42 Authentication Event Verification are satisfied
• the expiration condition is in the future
• the relay condition is omitted OR the relay condition contains the relay's URL
  • URL normalization techniques can be applied. For most cases just checking if the domain name is correct should be enough.
• validate the authentication delegation token to be the delegator's 64-byte Schnorr signature of the sha256 hash of the authentication delegation token string