Manual Implementation of the UMA Auth Protocol for VASPs

1. OAuth 2.0 Exchange: Implement the OAuth 2.0 flow to establish connections between client applications and your users' UMA-enabled wallets.
2. NWC Connection: Implement the Nostr Wallet Connect (NWC) protocol to handle the actual communication between the client app and the user's wallet. This includes all of the NWC methods like get_balance, pay_invoice, etc.
3. Permissions and Budgets: Implement the logic to handle permissions and budgets for each connected app.
4. UI: Implement the UI for managing connections, permissions, and budgets.

• authorization_endpoint: The URL of the your OAuth authorization endpoint. This is where the client application should send the user to authenticate and authorize the client application to access their wallet.
• token_endpoint: The URL of the VASP's token endpoint. This is where the client application exchanges an authorization code for an access token (a new NWC Connection), and where the client application can refresh an access token.
• nwc_commands_supported: An array of strings representing the NWC commands that the VASP supports. This should be an array of strings, where each string is a valid NWC command name.
• grant_types_supported: An array of strings representing the OAuth grant types that the VASP supports. For now, in most cases, this should just be ["authorization_code"].
• code_challenge_methods_supported: An array of strings representing the PKCE code challenge methods that the VASP supports. For now, in most cases, this should just be ["S256"].
• connection_management_endpoint: The URL of the VASP's connection management endpoint. This is where the user can create, update, and delete NWC Connections.
• revocation_endpoint: The URL of the VASP's revocation endpoint. This is where the client application can revoke an access token (NWC Connection).

<authorization_endpoint>?client_id=npub37fd9…%3Awss%3A%2F%2Fmyrelay.info&redirect_uri=https%3A%2F%2Fexample.com&response_type=code&code_challenge=a43f6ed&code_challenge_method=S256&state=foobar&required_commands=pay_invoice%20make_invoice%20lookup_invoice&optional_commands=list_transactions&budget=10.USD%2Fmonthly&expires_at=1717964120

• client_id in the format identity_npub identity_relay: This will be used to lookup the client app as described below. in the client app registration section.
• redirect_uri: The redirect URI which will receive callback data from the wallet service on successful authentication. It will get back the auth code that can be exchanged for a token. If there was a kind-13195 nostr event as described above, the wallet will validate this redirect URI against declared allowed patterns.
• response_type=code: Indicates that the “Authorization Code” flow will be used.
• code_challenge and code_challenge_method: The PKCE exchange details.
• state: Optional oauth state param for CSRF and state restoration.

• required_commands: A space-separated list of commands that the app requires from the wallet. The wallet MUST NOT connect if it does not support all of these permissions, or if the user does not grant one of them.
• optional_commands: (optional) A space-separated list of commands that the wallet can enable to add additional functionality. The wallet MAY ignore these.
• budget: (optional) Requested budget in the format <max_amount>.<currency>/<period>. If the .<currency> is omitted, satoshis are assumed. If /<period> is omitted, it’s a budget forever. For example, a budget string of “1000” would mean that this connection can only ever be used for a maximum of 1000 satoshis sent.
• expires_at: (optional) connection cannot be used after this date. Unix timestamp in seconds.

{
  "kind": 13195,
  // ... other fields
  "content": {
    "name": "Zappy Bird",
    "nip05": "_@zappybird.com",
    "image": "https://zappybird.com/logo.png",
    "allowed_redirect_uris": ["https://zappybird.com/auth/callback", "zappybird://auth/callback"],
  }
}

["REQ", <subscription_id>, {"kind": 13195, "authors": "4b50722cfcd12236b4ac0700008e9da56ef9f712945564e8fc4549a89afc660e"}]

1. The allowed redirect URIs in the registration event should match the redirect_uri in the auth request. As mentioned, this is to guard against phishing attacks. If the redirect URI is not in the list of allowed URIs, the VASP should reject the auth request.
2. The NIP-05 address should be verified in accordance with the NIP-05 spec. This is to ensure that the app owns the domain it claims to own.

• NDK (js)
• Alby JS SDK (js)
• Rust Nostr Bindings (python, kotlin/java, js)
• ZBD's go-nostr (golang)

POST /oauth/token HTTP/1.1
Host: https://umanwc.examplevasp.com
 
grant_type=authorization_code
&code=xxxxxxxxxxx
&redirect_uri=https://example-app.com/redirect
&code_verifier=Th7UHJdLswIYQxwSg29DbK1a_d9o41uNMTRmuH0PM8zyoMAQ
&client_id=npub16f80k0f4vg0nnlepxrqxeh81slyzst2d wss://myrelay.info

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
 
{
  "access_token":"b9d11fe05e266fe7389fdf1359211e7859656a7898d64f3066092156de109b31",
  "token_type":"Bearer",
  "expires_in":86400,
  "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTDk",
  "nwc_connection_uri": 
"nostr+walletconnect://a421a5e2a615eff3b797be5318e4e187d24b100748cfaa8d0b390ce659906d8f?relay=wss://relay.getalby.com/v1&secret=b9d11fe05e266fe7389fdf1359211e7859656a7898d64f3066092156de109b31&lud16=$bob@examplevasp.com"
  "commands": ["pay_invoice", "fetch_quote", "execute_quote", "make_invoice", "pay_to_address"],
  "budget": "100.USD/month",
  "nwc_expires_at": 1721796505
}

POST /oauth/token HTTP/1.1
Host: https://nwc.uma.jeremykle.in
 
grant_type=refresh_token
&refresh_token=IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk
&client_id=npub16f80k0f4vg0nnlepxrqxeh81slyzst2d%20wss://myrelay.info

1. Establish a websocket connection to the relay of your choice that you've added to the nwc_connection_uri.
2. (Only needed once): Publish an info event (kind 13194) to the relay with your list of supported NWC commands.
3. Send a REQ message to the relay to wait for incoming 23194 events (NWC requests).
4. When you receive a 23194 event, parse the event, verify its signature, and decrypt the message payload
5. Respond by publishing the appropriate 23195 event (NWC response) to the relay.