From 1e381b40c8a0ff2856dd43ba36ec026552354ceb Mon Sep 17 00:00:00 2001 From: callebtc <93376500+callebtc@users.noreply.github.com> Date: Wed, 27 Nov 2024 01:10:57 +0100 Subject: [PATCH] prettier --- suppl/README.md | 2 +- suppl/xx.md | 6 +++--- xx+1.md | 17 ++++++++--------- xx.md | 20 ++++++++++++-------- 4 files changed, 24 insertions(+), 21 deletions(-) diff --git a/suppl/README.md b/suppl/README.md index 0a6adf2..e1e8b92 100644 --- a/suppl/README.md +++ b/suppl/README.md @@ -1,3 +1,3 @@ ## Supplementary Material -This directory contains supplementary material for some specifications in the parent directory. \ No newline at end of file +This directory contains supplementary material for some specifications in the parent directory. diff --git a/suppl/xx.md b/suppl/xx.md index a7f1362..1af1bd5 100644 --- a/suppl/xx.md +++ b/suppl/xx.md @@ -6,6 +6,6 @@ Well-known Cashu wallet redirect URLs for the OpenID Connect Authorization Code flow: -| Wallet | Redirect URL | -| -------- | ----------------------- | -| Cashu.me | `https://wallet.cashu.me/callback` | \ No newline at end of file +| Wallet | Redirect URL | +| -------- | ---------------------------------- | +| Cashu.me | `https://wallet.cashu.me/callback` | diff --git a/xx+1.md b/xx+1.md index 21aa96f..9250a32 100644 --- a/xx+1.md +++ b/xx+1.md @@ -6,9 +6,9 @@ --- -This NUT defines a blind authentication scheme that allows mint operators to limit the use of their mint to a set of authorized users while still providing privacy within that anonymity set. +This NUT defines a blind authentication scheme that allows mint operators to limit the use of their mint to a set of authorized users while still providing privacy within that anonymity set. -We use two authentication schemes in conjunction: *clear authentication* using an external OpenID Connect / OAuth 2.0 service (described in [NUT-XX][XX]), and *blind authentication* with the mint to access its resources. A user's wallet first needs to obtain a clear authentication token (CAT) from an OpenID Connect authority that the mint selected, which is not subject of this specification. Once the user has obtained the CAT from the OpenID Connect service, they can use it to obtain multiple blind authentication tokens (BAT) from the mint. We describe this process in this document. +We use two authentication schemes in conjunction: _clear authentication_ using an external OpenID Connect / OAuth 2.0 service (described in [NUT-XX][XX]), and _blind authentication_ with the mint to access its resources. A user's wallet first needs to obtain a clear authentication token (CAT) from an OpenID Connect authority that the mint selected, which is not subject of this specification. Once the user has obtained the CAT from the OpenID Connect service, they can use it to obtain multiple blind authentication tokens (BAT) from the mint. We describe this process in this document. Blind authentication tokens (BATs) are used to access the protected endpoints of the mint and make sure that only users that previously presented a valid CAT can access the mint's features such as minting, melting, or swapping ecash. Wallets provide a BAT in the request header when making a request to one of the mint's protected endpoints. The mint parses the header for a BAT, verifies the signature (like with normal ecash as described in [NUT-00][00]), checks if the token has previously been spent, and if not, adds it to its spent BAT token database. @@ -19,6 +19,7 @@ Blind authentication tokens (BATs) are essentially the same as normal ecash toke BATs can only be used a single time for each request that the wallet makes to the mint's protected endpoints. After each request, the BAT is added to the mint's spent token list after which they are regarded as spent. This is also the case if the wallet's request results in an error. To summarize: + - Wallet connects to mint and user is prompted to register or log in with an OAuth 2.0 service - Upon login, wallet receives a clear authentication (CAT) token that identifies the user - CAT is used to obtain blind authentication tokens (BAT) from the mint @@ -78,7 +79,7 @@ Like in [NUT-01][01] and [NUT-02][02], the mint responds with its BAT keyset for GET /v1/auth/blind/keys ``` -or +or ``` GET /v1/auth/blind/keys/{keyset_id} @@ -102,8 +103,6 @@ where the mint returns a `GetKeysResponse`: Notice that the unit is `auth` and only a single amount of `1` is supported. - - ### Keysets Like in [NUT-02][02] the mint also offers the endpoints returning the keysets: @@ -114,8 +113,6 @@ GET v1/auth/blind/keysets The mint returns the same `GetKeysetsResponse` response types as described in [NUT-02][02]. - - ## Minting blind authentication tokens To mint blind authentication tokens (BATs), the wallet makes a request to the following endpoint: @@ -165,6 +162,7 @@ The wallet un-blinds the response to obtain the signatures `C` as described in [ The wallet checks the `MintBlindAuthSetting` of the mint to determine which endpoints require blind authentication. Similar to `NUT-XX`, the wallet performs a match on the `protected_endpoints` in the `MintBlindAuthSetting` before attempting a request to one of the mint's endpoints. If the match is positive, the wallet needs to add a blind authentication token (BAT) to the request header. ### Serialization + To add a blind authentication token (BAT) to the request header, we need to serialize a single `AuthProof` JSON in base64 with the prefix `authA`: ```sh @@ -181,7 +179,7 @@ We add this serialized BAT to the request header: Blind-auth: ``` -and make the request as we usually would. +and make the request as we usually would. `AuthProofs` are single-use. The wallet MUST delete the `AuthProof` as soon as it has made a request, even if the request errors. If the wallet runs out of `AuthProofs`, it can [mint new ones](#minting-blind-authentication-tokens) using its clear authentication token (CAT). @@ -206,6 +204,7 @@ The mint lists each protected endpoint that requires a blind authentication toke ] } ``` + `max_mint` is the number of blind authentication tokens (BATs) that can be minted in a single request using the `POST /v1/auth/blind/mint` endpoint. `protected_endpoints` contains the endpoints that are protected by blind authentication. `method` denotes the HTTP method of the endpoint, and `path` is a regex pattern that must match the path of the URL. In this example, all `/v1/mint/*` endpoints are protected and require blind authentication. @@ -221,4 +220,4 @@ The mint lists each protected endpoint that requires a blind authentication toke [04]: 04.md [05]: 05.md [06]: 06.md -[XX]: xx.md \ No newline at end of file +[XX]: xx.md diff --git a/xx.md b/xx.md index 00af430..a17355a 100644 --- a/xx.md +++ b/xx.md @@ -13,8 +13,10 @@ This NUT defines a clear authentication scheme that allows mint operators to lim **Warning:** This authentication scheme breaks the user's privacy as the CAT contains user information. Mint operators SHOULD require clear authentication **only on selected endpoints**, such as those for obtaining blind authentication tokens (BATs, see [NUT-XX+1][XX+1]). ## OpenID Connect service configuration -The OpenID Connect (OIDC) service is typically run by the mint operator (but it does not have to be). The OIDC service must be configured to meet the following criteria: -- **Client ID:** The OIDC service MUST enable the client ID `cashu-client`, which is shared by all authenticating wallets. + +The OpenID Connect (OIDC) service is typically run by the mint operator (but it does not have to be). The OIDC service must be configured to meet the following criteria: + +- **Client ID:** The OIDC service MUST enable the client ID `cashu-client`, which is shared by all authenticating wallets. - **Signature algorithm:** The OIDC service MUST support at least one of the two asymmetric JWS signature algorithms for access token and ID token signatures: `ES256` and `RS256`. - **Wallet redirect URLs:** To support the OpenID Connect Authorization Code flow, the OIDC service MUST allow redirect URLs that correspond to the wallets it wants to support. You can find a list of common redirect URLs for well-known Cashu wallets [here][XX-SUPPL]. - **Localhost redirect URL:** The OIDC service MUST also allow redirects to the URL `http://localhost:33388/callback`. @@ -37,21 +39,22 @@ The mint lists each protected endpoint that requires a clear authentication toke ] } ``` -`openid_discovery` is the OpenID Connect Discovery endpoint which has all the information necessary for a client to authenticate with the service. `protected_endpoints` is an array of objects that specify each endpoint that requires a CAT in the request headers. `method` is the HTTP method and `path` the path for the endpoint that is protected. -The `path` can either be a string (exact match), such as `"/v1/auth/blind/mint"` or a regex pattern such as `"^/v1/mint/quote/bolt11/.*"`. +`openid_discovery` is the OpenID Connect Discovery endpoint which has all the information necessary for a client to authenticate with the service. `protected_endpoints` is an array of objects that specify each endpoint that requires a CAT in the request headers. `method` is the HTTP method and `path` the path for the endpoint that is protected. + +The `path` can either be a string (exact match), such as `"/v1/auth/blind/mint"` or a regex pattern such as `"^/v1/mint/quote/bolt11/.*"`. In this example, the entry in `protected_endpoints` is the [NUT-XX+1][XX+1] endpoint for obtaining blind authentication tokens (BATs). ### Clear authentication token verification -When receiving a request to a protected endpoint, the mint checks the included CAT (which is a JWT) in the HTTP request header (see below in section [Wallet](#cat-in-request-header)) and verifies the JWT. To verify the JWT, the mint checks the signature of the OIDC and the expiry of the JWT. +When receiving a request to a protected endpoint, the mint checks the included CAT (which is a JWT) in the HTTP request header (see below in section [Wallet](#cat-in-request-header)) and verifies the JWT. To verify the JWT, the mint checks the signature of the OIDC and the expiry of the JWT. -The JWT includes a `sub` field which identifies a specific user. The `sub` identifier can, for example, be used to rate limit the user. **Note:** The mint does not verify the *audience* field. More on OpenID Connect ID token validation [here](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation). +The JWT includes a `sub` field which identifies a specific user. The `sub` identifier can, for example, be used to rate limit the user. **Note:** The mint does not verify the _audience_ field. More on OpenID Connect ID token validation [here](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation). ## Wallet -To make a request to one of the `protected_endpoints` of the mint, the wallet needs to obtain a valid clear auth token (CAT) from the OIDC service. The wallet uses the `openid_discovery` URL in the `MintClearAuthSetting` from the info endpoint of the mint to authenticate with the OIDC service and obtain a CAT. +To make a request to one of the `protected_endpoints` of the mint, the wallet needs to obtain a valid clear auth token (CAT) from the OIDC service. The wallet uses the `openid_discovery` URL in the `MintClearAuthSetting` from the info endpoint of the mint to authenticate with the OIDC service and obtain a CAT. ### Obtaining a CAT @@ -62,6 +65,7 @@ It is recommended to use language-specific libraries that can handle OpenID Conn The `access_token` is what is referred to as a clear authentication token (CAT) throughout this document. ### CAT in request header + When making a request to the mint's endpoint, the wallet matches the requested URL with the `protected_endpoints` from the `MintClearAuthSetting` (either exact match or regex pattern match). If the match is positive, the mint requires the wallet to provide a CAT with the request. After obtaining a CAT from the OIDC service, the wallet includes a valid CAT in the HTTP request header when it makes requests to one of the mint's `protected_endpoints`: @@ -80,4 +84,4 @@ The `CAT` is a JWT (or `access_token`) encoded with base64 that is signed by and [06]: 06.md [XX-SUPPL]: suppl/xx.md -[XX+1]: xx+1.md \ No newline at end of file +[XX+1]: xx+1.md