NUT-21/22: Mint Authentication (Clear and Blind Auth)

[variablefate]

Summary

Implement mint authentication support (NUT-21 Clear Auth + NUT-22 Blind Auth) to access mints that require user authentication. This enables using premium mints, rate-limited mints, and mints with compliance requirements.

Background

Some mints restrict access to authenticated users. The Cashu authentication system uses two layers:

1. Clear Auth Token (CAT) - NUT-21: User authenticates via OpenID Connect/OAuth 2.0
2. Blind Auth Token (BAT) - NUT-22: User exchanges CAT for anonymous ecash tokens to use on protected endpoints

This preserves privacy: the mint sees the CAT once (during BAT minting) but subsequent requests use anonymous BATs.

Authentication Flow

Step 1: Discover Auth Requirements (NUT-06)

Check mint info for auth configuration:

• OpenID discovery URL
• Client ID for OAuth
• Protected endpoints (regex patterns)

Step 2: Obtain Clear Auth Token (CAT)

OAuth 2.0 Authorization Code flow:

1. Open browser to OIDC authorization URL
2. User logs in
3. Redirect to app with auth code
4. Exchange code for access token (CAT)

Step 3: Mint Blind Auth Tokens (BAT)

POST to mint with CAT in header:

• Header: Clear-auth: <CAT>
• Body: Blinded messages for BAT ecash
• Response: Signed BATs (special keyset with unit=auth)

Step 4: Use BATs on Protected Endpoints

Include BAT in request header:

• Header: Blind-auth: authA<base64_proof>
• BATs are single-use (marked spent after each request)
• Wallet must request more BATs before running out

Implementation Plan

Phase 1: Auth Discovery

Add to CashuBackend.kt:

• Parse NUT-21 config from /v1/info
• Store auth requirements
• Check if endpoint is protected before requests

Phase 2: OAuth Integration

New file: MintAuthManager.kt

• Handle OAuth Authorization Code flow
• Store CAT securely (encrypted prefs)
• Refresh CAT before expiry

Phase 3: BAT Management

New methods in CashuBackend.kt:

• mintBats(catToken): Mint BAT ecash using CAT
• getBatForRequest(): Get a BAT for protected endpoint
• trackBatUsage(): Mark BATs as spent
• shouldRefreshBats(): Check if running low

Phase 4: Request Interceptor

Modify all HTTP requests:

• Check if endpoint is protected
• Add Blind-auth header if needed
• Handle auth errors (401/403) gracefully

Key Considerations

BAT Budget

• bat_max_mint: Max BATs mintable per request
• Need to mint more before running out
• Track usage to preemptively refresh

Protected Endpoints

Mint specifies protected paths as:

• Exact strings: /v1/auth/blind/mint
• Regex patterns: ^/v1/mint/quote/bolt11/.*

Single-Use Requirement

BATs cannot be swapped or reused. Each protected request consumes one BAT.

DLEQ Requirement

Per NUT-22, BAT signatures MUST include DLEQ proofs for verification (depends on NUT-12).

Files to Modify/Create

File	Changes
NEW: MintAuthManager.kt	OAuth flow, CAT storage, BAT lifecycle
CashuBackend.kt	Auth discovery, BAT request headers
WalletStorage.kt	Encrypted CAT/BAT storage
WalletSettingsScreen.kt	Mint auth UI (login/logout)

UI Requirements

• Mint login button (when auth required)
• Auth status indicator
• BAT count display (in diagnostics)
• Logout/clear auth option

Benefits

1. Access premium mints: Higher limits, better reliability
2. Compliance ready: Mints can require KYC while preserving tx privacy
3. Rate limiting: Mints can manage load per-user
4. Future-proof: Auth becoming more common in Cashu ecosystem

References

• NUT-21 Clear Auth
• NUT-22 Blind Auth
• NUT-12 DLEQ (required for BAT verification)

Dependencies

• NUT-12 (DLEQ) should be implemented first for BAT verification
• Android OAuth library (AppAuth recommended)

Acceptance Criteria

• Detect auth requirements from mint info
• OAuth flow opens browser for user login
• CAT stored securely, refreshed before expiry
• BATs minted and stored as special ecash
• Protected requests include Blind-auth header
• BAT refresh triggered when running low
• Settings UI for auth status and logout