NUT-XX: Clear authentication – NUT-XX+1: Blind authentication

[callebtc]

These NUTs describe a blind authentication protocol that uses OAuth2.0 OpenID connect standards to limit access to their mint. Mint operators can restrict access to their mint to a known set of users with registered accounts, while still providing them privacy during the use of the mint with the help of blind signatures (blind auth tokens).

Essentially, we're using ecash tokens for blind authentication. We're using ecash to secure ecash.

There are two NUTs in this PR:

• NUT-XX: Clear authentication describes how connect a mint to an OpenID Connect service and wallets to obtain a clear auth token (CAT) that identifies the user
• NUT-XX+1: Blind authentication describes how to turn a CAT into multiple blind auth tokens (BATs) which can then be used to access the protected endpoints of the mint.

The diagram below illustrates the protocol flow.

┌──────────────────────────────────────────────────────────────────────────┐
│ ┌────────┐                     ┌────────┐                  ┌───────────┐ │
│ │  User  │                     │  Mint  │                  │   OpenID  │ │
├─┴────────┘─────────────────────└────────┴──────────────────└───────────┴─┤
│                                                                          │
│                           1. Clear authentication                        │
│                           =======================                        │
│                                                                          │
│                                       Mint registers OpenID service      │
│                                     ◄───────────────────────────────     │
│                                                                          │
│           Wallet GET /v1/info                                            │
│    ─────────────────────────────────►                                    │
│                                                                          │
│                                OpenID login                              │
│    ────────────────────────────────────────────────────────────────►     │
│                                                                          │
│                              Respond with CAT                            │
│    ◄────────────────────────────────────────────────────────────────     │
│                                                                          │
│                           2. Blind authentication                        │
│                           =======================                        │
│                                                                          │
│           Request BAT using CAT                                          │
│    ─────────────────────────────────►                                    │
│                                                                          │
│                Return BAT                                                │
│    ◄─────────────────────────────────                                    │
│                                                                          │
│           Use BAT to access mint                                         │
│    ─────────────────────────────────►                                    │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Notes

• This requires the use of an external OpenID Connect service. I have used Keycloak so far and it was very easy to set up. Another popular choice seems to be ory/hydra.
• NUT-XX does not describe how the OAuth2.0 and OpenID Connect protocols work. There are many libraries that can handle this for you but I found it also easy to implement it myself.
• NUT-XX+1 begins after you have obtained an access token from the OpenID connect server.
• NUT-XX+1 defines a bunch of endpoints that behave very similarly to the normal /v1/ ecash endpoints we already use. I found it quite convenient to re-use code from the wallet and the mint side to mint, validate, and keep track of spent blind auth tokens.

Todo:

• Mints should not burn a BAT on an errored request so that external users with a BAT contained in a TokenV4 can re-try melting (instead of having only one shot)
• client_id should be part of the info endpoint so it can be dynamic (instead of requiring the OICD use cashu-client)
• Add recommended parameters for max_bat_mint, rate-limiting BAT minting (in time), and rotating auth keysets

[starbackr-dev]

I’m glad to see 2 NUT specs (Clear +Bind) and it is what is needed. I’ve made some suggestions below which are open for debate and acceptance.

1. We need to provide a way for the mint to use clear or blinded authed endpoints depending on the types of endpoint. E.g. Minting and melting may require clear authed endpoint while transfer/swap may require blinded auth. This information can be provided using NUT-96 mint information.

There can also be mints with only blinded auth. E.g. whitelisted pubkeys. Simply call the blind_auth endpoint with Auth as pubkey and get blinded auth tokens. No need for clear auth or open ID.

"XX" : {
  "openid_discovery": "https://mint.com:8080/realms/nutshell/.well-known/openid-configuration",

  "CAT_endpoints": [
    {
        "method": "POST",
        "path": "/v1/auth/blind/mint"
        “Path”: “/v1/mint/quote/bolt11”

    }
  ]
}

"XX+1" : {
“Blind_auth”: "/v1/auth/blind/mint",

"BAT_endpoints": [
    {
        "method": "POST",
        "path": "/v1/swap"
    }
  ]

}

This way the protocol is not restricting to use only blinded auth rather the mint can choose to implement clear or blinded auth and provide the information in the manifest/NUT06

2. Always use the “Authorization: Bearer” format. This is typical to all protected APIs in use today. Let’s follow the same pattern. Since BAT starts with authA, the mint should know if this is CAT or BAT.

    Authorization: Bearer <CAT>/<BAT>
   

Questions:

How will the CAT expiry time be attached to BAT expiry time?
"max_mint": 50 - is there a benchmark/best practice for an optimal number to use here?

[callebtc]

1. We need to provide a way for the mint to use clear or blinded authed endpoints depending on the types of endpoint.

This is already possible.

There can also be mints with only blinded auth. E.g. whitelisted pubkeys... No need for clear auth or open ID

This is not in scope of this spec.

2. Always use the “Authorization: Bearer” format.

This is a matter of taste and makes no practical difference. For proprietary API's that don't need interop this is fine. Here, the header should indicate which type of auth is used.

How will the CAT expiry time be attached to BAT expiry time?

Individual BATs have no expiry, only their keyset has.

"max_mint": 50 - is there a benchmark/best practice for an optimal number to use here?

Still to be determined, part of the todo list.