feat(auth): add external BAT verification endpoints

4xvgal commented

2026-01-27 07:14:07 +00:00

(Migrated from github.com)

Description

Add post /v1/auth/blind/checkstate for checking BAT state
ADD POST /v1/auth/blind/spend for spending BAT externally
Add client-side methods in AuthMintConnctor trait
Add Intergration tests for new endpoints

This enables external apps to verify and consume BATs issued by the mint.
Mint can act as Blinded token issuer and verifier for third-party interactions. Similar to Kagi's Privacy Pass Privacy Pass, external API servers can now authenticate users via the Mint without compromising user privacy, using the Mint to validate and spend the tokens presented by users.

Notes to the reviewers

The two new endpoints work together to support external authentication flows:
1. checkstate: A non-destructive way for a service to ensure a token is good before providing a service.
2. spend: The final step to "burn" the token, preventing double-spending.
Renamed internal doc references from BAT to blind auth token to satisfy the typos linter while maintaining professional terminology.

Suggested CHANGELOG Updates

ADDED

POST /v1/auth/blind/checkstate: Endpoint for external verification of blind auth tokens.
POST /v1/auth/blind/spend: Endpoint for external spending of blind auth tokens.
Support for third-party authentication flows using the Mint as a blinded token verifier.

Checklist

I followed the code style guidelines
I ran just final-check before committing

### Description - Add post /v1/auth/blind/checkstate for checking BAT state - ADD POST /v1/auth/blind/spend for spending BAT externally - Add client-side methods in AuthMintConnctor trait - Add Intergration tests for new endpoints This enables external apps to verify and consume BATs issued by the mint. Mint can act as Blinded token issuer and verifier for third-party interactions. Similar to Kagi's Privacy Pass [Privacy Pass](https://blog.kagi.com/kagi-privacy-pass), external API servers can now authenticate users via the Mint without compromising user privacy, using the Mint to validate and spend the tokens presented by users. ----- ### Notes to the reviewers - The two new endpoints work together to support external authentication flows: 1. `checkstate`: A non-destructive way for a service to ensure a token is good before providing a service. 2. `spend`: The final step to "burn" the token, preventing double-spending. - Renamed internal doc references from `BAT` to `blind auth token` to satisfy the `typos` linter while maintaining professional terminology. ----- ### Suggested [CHANGELOG](https://github.com/cashubtc/cdk/blob/main/CHANGELOG.md) Updates #### ADDED - `POST /v1/auth/blind/checkstate`: Endpoint for external verification of blind auth tokens. - `POST /v1/auth/blind/spend`: Endpoint for external spending of blind auth tokens. - Support for third-party authentication flows using the Mint as a blinded token verifier. ---- ### Checklist * [x] I followed the [code style guidelines](https://github.com/cashubtc/cdk/blob/main/CODE_STYLE.md) * [x] I ran `just final-check` before committing

❤️ 1

gandlafbtc commented

2026-01-27 07:23:25 +00:00

(Migrated from github.com)

We're planning to use this feature in openpleb, to create blinded sessions instead of user-linked sessions

thesimplekid commented

2026-01-27 09:27:53 +00:00

(Migrated from github.com)

To add custom auth endpoints like this we would need to add them to the spec first to keep cdk inline with the cashu protocol. I have wondered before if a burn endpoint would be useful, but there has not been a push to add it to spec.

You could achieve this use case by not modifying spec and using some other token that is a custom unit as a BAT is just a cashu token with the reserved AUTH unit and a denomination of one. This is what I do for athenut.

To add custom auth endpoints like this we would need to add them to the spec first to keep cdk inline with the cashu protocol. I have wondered before if a burn endpoint would be useful, but there has not been a push to add it to spec. You could achieve this use case by not modifying spec and using some other token that is a custom unit as a BAT is just a cashu token with the reserved AUTH unit and a denomination of one. This is what I do for athenut.

👍 3

gandlafbtc commented

2026-01-27 13:20:41 +00:00

(Migrated from github.com)

Yes, that is true.

However, if I understand it correctly, If both the mint and the 3rd party service want to be "blind authed", that would mean authing with clear auth at oidc, then obtaining bat tokens, then using bat tokens to obtain cashu "auth" tokens for the 3rd party service.

It may be a special usecase for open pleb, in that we want to use both the mint, and the 3rd party service behind blind auth

Yes, that is true. However, if I understand it correctly, If both the mint and the 3rd party service want to be "blind authed", that would mean authing with clear auth at oidc, then obtaining bat tokens, then using bat tokens to obtain cashu "auth" tokens for the 3rd party service. It may be a special usecase for open pleb, in that we want to use both the mint, and the 3rd party service behind blind auth

4xvgal commented

2026-01-27 14:16:49 +00:00

(Migrated from github.com)

I didn't realize that part of the endpoint also needed to be specified in the spec😅

If it's only meant for internal service use, adding an endpoint and using a custom unit would indeed achieve that.

However, if mint has a trusted OIDC and can process ODIC authentication anonymously via BAT through mint, mint can be used as an authentication server.

How shoud i go about adding this to spec?

btw this pr needs more feature like Keyset rotation

I didn't realize that part of the endpoint also needed to be specified in the spec😅 If it's only meant for internal service use, adding an endpoint and using a custom unit would indeed achieve that. However, if mint has a trusted OIDC and can process ODIC authentication anonymously via BAT through mint, mint can be used as an authentication server. How shoud i go about adding this to spec? btw this pr needs more feature like Keyset rotation

gandlafbtc commented

2026-01-28 05:48:03 +00:00

(Migrated from github.com)

I think automatic keyset rotation for blind auth keysets might even be something to look into separately. It is not strictly necessary, and it has even some downsides when it comes to privacy, as frequent rotation of the keysets will "flush" the anon set.

But I still think it can make in some instances to have the option to enable auto rotation based on a time frame.
The main problem with having a static keyset for auth tokens, is that a malicious user could mint and store tokens over a prolonged period, and then try to dos the mint, without the mint knowing who it is.

The mint could then still take reactive measures by manually rotating the keyset, but having a proactive option might be nice

I think automatic keyset rotation for blind auth keysets might even be something to look into separately. It is not strictly necessary, and it has even some downsides when it comes to privacy, as frequent rotation of the keysets will "flush" the anon set. But I still think it can make in some instances to have the option to enable auto rotation based on a time frame. The main problem with having a static keyset for auth tokens, is that a malicious user could mint and store tokens over a prolonged period, and then try to dos the mint, without the mint knowing who it is. The mint could then still take reactive measures by manually rotating the keyset, but having a proactive option might be nice

thesimplekid commented

2026-01-28 09:46:24 +00:00

(Migrated from github.com)

I think automatic keyset rotation for blind auth keysets might even be something to look into separately. It is not strictly necessary, and it has even some downsides when it comes to privacy, as frequent rotation of the keysets will "flush" the anon set.

But I still think it can make in some instances to have the option to enable auto rotation based on a time frame.

Yes, I think that is a separate issue, but it is one we have discussed for regular units and should discuses more for both regular and auth keysets. It could be done both times based and/or when a certain number of proofs are issued from a keyset. We should open an issue to discuses.

> I think automatic keyset rotation for blind auth keysets might even be something to look into separately. It is not strictly necessary, and it has even some downsides when it comes to privacy, as frequent rotation of the keysets will "flush" the anon set. > > But I still think it can make in some instances to have the option to enable auto rotation based on a time frame. Yes, I think that is a separate issue, but it is one we have discussed for regular units and should discuses more for both regular and auth keysets. It could be done both times based and/or when a certain number of proofs are issued from a keyset. We should open an issue to discuses.

👍 1

This pull request has changes conflicting with the target branch.

crates/cdk/src/wallet/mint_connector/http_client.rs

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin 4xvgal/feat--ext_bat:4xvgal/feat--ext_bat

git switch 4xvgal/feat--ext_bat

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff 4xvgal/feat--ext_bat

git switch 4xvgal/feat--ext_bat

git rebase main

git switch main

git merge --ff-only 4xvgal/feat--ext_bat

git switch 4xvgal/feat--ext_bat

git rebase main

git switch main

git merge --no-ff 4xvgal/feat--ext_bat

git switch main

git merge --squash 4xvgal/feat--ext_bat

git switch main

git merge --ff-only 4xvgal/feat--ext_bat

git switch main

git merge 4xvgal/feat--ext_bat

git push origin main

Rows
Columns

feat(auth): add external BAT verification endpoints #1575

Description

Notes to the reviewers

Suggested CHANGELOG Updates

ADDED

Checklist

Checkout

Merge