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](https://github.com/nostr-protocol/nips/blob/master/71.md) in exchange for payment or other services
 - A user may want to create subscription services to certain kinds of [NIP-71 Restricted Event](https://github.com/nostr-protocol/nips/blob/master/71.md) 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:

```json
[
  "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](https://github.com/nostr-protocol/nips/blob/master/42.md). 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](https://github.com/nostr-protocol/nips/blob/master/71.md). The filter condition is a JSON stringified filter object as defined in [NIP-01](https://github.com/nostr-protocol/nips/blob/master/01.md), however only the following attributes are valid within the filter condition:

- `"ids"`
- `"kinds"`
- `"since"`
- `"until"`

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](https://github.com/nostr-protocol/nips/blob/master/42.md) with an `auth-delegation` tag to:

- authenticate as or
- gain access to [NIP-71 Restricted Events](https://github.com/nostr-protocol/nips/blob/master/71.md) 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.
```json
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.

```json
{
  "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](https://github.com/nostr-protocol/nips/blob/master/42.md#signed-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