LUD-21: pinLimit for withdrawRequest - resolves #201

21.md

@@ -0,0 +1,51 @@
+LUD-21: pinLimit for withdrawRequest
+====================================
+
+`author: titusz` `discussion: https://t.me/lnurl/34810`
+
+---
+
+## Optional Second Factor for `withdrawRequest` Authorization
+
+Adding the optional `pinLimit` property to an LNURL-withdraw response allows a `SERVICE` to require a PIN to authorize a withdrawal above a given amount.
+
+```diff
+{
+    "tag": "withdrawRequest",
+    "callback": string,
+    "defaultDescription": string, 
+    "minWithdrawable": number,
++   "pinLimit": number,
+    "maxWithdrawable": number
+}
+```
+
+The `pinLimit` value must be a positive integer (including 0) with a maximum of 15 digits. If the `pinLimit` property is present and a `WALLET` (Point of Sale) intends to withdraw an amount equal to or greater than the `pinLimit` value (in millisatoshis) it must first acquire a PIN from the user (customer) and then add it as `pin=<pin>` to the query string of the callback URL to authorize the withdrawal.
+
+**Example callback:**
+
+`https://ln-example.com?k1=<k1>&pr=<ln-invoice>&pin=<pin>`
+
+If the `pinLimit` property is used, the `SERVICE` must check for and validate the `pin` query parameter of the callback request according to its policy before paying the invoice.
+
+## Wallet Implementation Notes
+
+If an LNURL-withdraw response includes a `pinLimit` property a `WALLET` should not automatically propose the invoice amount based on the `minWithdrawable`, `maxWithdrawable` or `pinLimit` values.
+
+When acquiring a PIN from the user (customer) via a PIN entry screen a `WALLET` should show the invoice amount on that same screen.
+
+## Service Implementation Notes
+
+Other than a maximum length of 8 digits this document makes no assumptions about whether PINs are static (multiple-use) or one-time passwords (OTPs) or other digit based PIN security schemes.
+
+A `SERVICE` may add the `pinLimit` property to its LNURL-withdraw response in accordance with its individual security policy.
+
+A `SERVICE` should protect against brute force attacks by invalidating LNURLw links after the third PIN authorization failure.
+
+## Security Considerations
+
+PIN support improves security in cases of lost or maliciously scanned NFC payment devices.
+
+Implementors should be aware that the PIN is leaked to the merchant point of sales device when entered by the customer.
+
+Depending on the implementation of a `SERVICE`, security can be improved by using one-time PINs or by appropriate privacy configuration of NFC payment devices (e.g., enabling Random-ID support).

README.md

@@ -7,7 +7,7 @@ These are all the individual documents describing each small piece of protocol t
 |----------|-------------------------------------------------------------|---------|
 | [01][01] | Base LNURL encoding and decoding.                           | _all the ones listed below_ |
 | [02][02] | `channelRequest` base spec.                                 | [Balance of Satoshis][bos], [BitBanana][bitbanana], [Blixt][blixt], [Breez][breez], [cliché][cliche], [OBW][obw], [Zap Android][zap], [Zap Desktop][zap], [Zeus][zeus] |
-| [03][03] | `withdrawRequest` base spec.                                | [Alby][alby], [Balance of Satoshis][bos], [BitBanana][bitbanana], [Blixt][blixt], [BlueWallet][bluewallet], [Breez][breez], [Clams][clams], [CoinCorner][coincorner], [coinos][coinos], [Fountain][fountain], [LifPay][lifpay], [LNbits][lnbits], [LightningTipBot][ltb], [Muun][muun], [Phoenix][phoenix], [Pouch.ph][pouchph], [ShockWallet][shockwallet], [OBW][obw], [ThunderHub][thunderhub], [Wallet of Satoshi][wos], [Zap Android][zap], [Zap Desktop][zap], [Zap iOS][zap], [ZBD Discord][zbd], [ZBD Extension][zbd], [ZBD Telegram][zbd], [ZEBEDEE][zbd], [Zeus][zeus] |
+| [03][03] | `withdrawRequest` base spec.                                | [Alby][alby], [Balance of Satoshis][bos], [BitBanana][bitbanana], [Blixt][blixt], [BlueWallet][bluewallet], [Bolt Card Wallet][boltcardwallet], [Breez][breez], [Clams][clams], [CoinCorner][coincorner], [coinos][coinos], [Fountain][fountain], [LifPay][lifpay], [LNbits][lnbits], [LightningTipBot][ltb], [Muun][muun], [Phoenix][phoenix], [Pouch.ph][pouchph], [ShockWallet][shockwallet], [OBW][obw], [ThunderHub][thunderhub], [Wallet of Satoshi][wos], [Zap Android][zap], [Zap Desktop][zap], [Zap iOS][zap], [ZBD Discord][zbd], [ZBD Extension][zbd], [ZBD Telegram][zbd], [ZEBEDEE][zbd], [Zeus][zeus] |
 | [04][04] | Auth base spec.                                             | [Alby][alby], [Balance of Satoshis][bos], [Blixt][blixt], [Breez][breez], [BlueWallet][bluewallet], [Clams][clams], [coinos][coinos], [Geyser][geyser], [LifPay][lifpay], [LNbits][lnbits], [LightningTipBot][ltb], [Phoenix][phoenix], [SeedAuth][seedauth], [SeedAuthExtension][sae], [OBW][obw], [Sparrow Wallet][sparrow], [ThunderHub][thunderhub], [Zap Desktop][zap], [Zeus][zeus] |
 | [05][05] | BIP32-based seed generation for auth protocol.              | [Alby][alby], [coinos][coinos], [OBW][obw], [Phoenix][phoenix] |
 | [06][06] | `payRequest` base spec.                                     | [Alby][alby], [Balance of Satoshis][bos], [BitBanana][bitbanana], [Blixt][blixt], [BlueWallet][bluewallet], [Breez][breez], [BTCPayServer][btcp], [Clams][clams], [cliché][cliche], [CoinCorner][coincorner], [coinos][coinos], [Electrum][electrum], [Fountain][fountain], [Galoy][galoy], [Geyser][geyser], [LifPay][lifpay], [LNbits][lnbits], [LNLink][lnlink], [LNPay.co][lnpay], [LightningTipBot][ltb], [Machankura][machankura], [Phoenix][phoenix], [Pouch.ph][pouchph], [ShockWallet][shockwallet], [OBW][obw], [ThunderHub][thunderhub], [Wallet of Satoshi][wos], [Zap Android][zap], [ZBD Discord][zbd], [ZBD Extension][zbd], [ZBD Telegram][zbd], [ZEBEDEE][zbd], [Zeus][zeus] |
@@ -21,13 +21,15 @@ These are all the individual documents describing each small piece of protocol t
 | [14][14] | `balanceCheck`: reusable `withdrawRequest`s.                | [Alby][alby], [Blixt][blixt], [LNbits][lnbits], |
 | [15][15] | `balanceNotify`: services hurrying up the withdraw process. | [LNbits][lnbits] |
 | [16][16] | Paying to static internet identifiers.                      | [Alby][alby], [Balance of Satoshis][bos], [BitBanana][bitbanana], [Blixt][blixt], [BTCPayServer][btcp], [Clams][clams], [cliché][cliche], [CoinCorner][coincorner], [coinos][coinos], [Fountain][fountain], [LifPay][lifpay], [LNbits][lnbits], [LNLink][lnlink], [LightningTipBot][ltb], [Machankura][machankura], [Phoenix][phoenix], [Pouch.ph][pouchph], [OBW][obw], [Zap Android][zap], [ZBD Discord][zbd], [ZBD Extension][zbd], [ZBD Telegram][zbd], [ZEBEDEE][zbd], [Zeus][zeus] |
-| [17][17] | Scheme prefixes and raw (non bech32-encoded) URLs.          | [Alby][alby], [BitBanana][bitbanana], [Blixt][blixt], [BTCPayServer][btcp], [Clams][clams], [cliché][cliche], [CoinCorner][coincorner], [ZBD Discord][zbd], [ZBD Telegram][zbd] | [Wallet of Satoshi][wos] |
+| [17][17] | Scheme prefixes and raw (non bech32-encoded) URLs.          | [Alby][alby], [BitBanana][bitbanana], [Blixt][blixt], [Bolt Card Wallet][boltcardwallet], [BTCPayServer][btcp], [Clams][clams], [cliché][cliche], [CoinCorner][coincorner], [ZBD Discord][zbd], [ZBD Telegram][zbd] | [Wallet of Satoshi][wos] |
 | [18][18] | Payer identity in `payRequest` protocol.                    | [Alby][alby], [BitBanana][bitbanana], [Blixt][blixt], [cliché][cliche], [OBW][obw], [ZBD Discord][zbd], [ZBD Telegram][zbd] |
 | [19][19] | Pay link discoverable from withdraw link.                   | [Blixt][blixt], [CoinCorner][coincorner], [OBW][obw] |
 | [20][20] | Long payment description for pay protocol.                  | [Alby][alby], [BitBanana][bitbanana], [Blixt][blixt], [Clams][clams], [cliché][cliche], [Phoenix][phoenix] |
+| [21][21] | pinLimit for withdrawRequest                                | [Bolt Card Wallet][boltcardwallet] |
 
 [alby]: https://github.com/getAlby/lightning-browser-extension
 [bitbanana]: https://bitbanana.app
+[boltcardwallet]: https://boltcardwallet.com
 [bos]: https://github.com/alexbosworth/balanceofsatoshis
 [blixt]: https://blixtwallet.github.io
 [bluewallet]: https://bluewallet.io
@@ -74,6 +76,9 @@ Services
 | [Bitcoin Bounce](https://thndr.games/)                                                              | [01][01] [03][03] [08][08]                                     |
 | [Bitrefill](https://bitrefill.com/)                                                                 | [01][01] [02][02] [06][06] [16][16]                            |
 | [Blocktank](https://synonym.to/blocktank/)                                                          | [01][01] [02][02]                                              |
+| [Bolt Card PoS](https://github.com/boltcard/bolt-card-pos)                                          | [03][03] [17][17] [19][19]                                     |
+| [Bolt Card Wallet](https://boltcardwallet.com)                                                      | [03][03] [17][17] [19][19]                                     |
+| [Blocktank](https://synonym.to/blocktank/)                                                          | [01][01] [02][02]                                              |
 | [Bull Bitcoin](https://www.bullbitcoin.com/)                                                        | [01][01] [03][03]                                              |
 | [CoinCorner](https://www.coincorner.com)                                                            | [01][01] [03][03] [06][06] [16][16] [17][17] [19][19]          |
 | [Fountain Podcasts](https://fountain.fm)                                                            | [01][01] [03][03] [06][06] [09][09] [12][12] [16][16]          |
@@ -208,6 +213,7 @@ Tools for developers
 [18]: 18.md
 [19]: 19.md
 [20]: 20.md
+[21]: 21.md
 
 Dependency Tree
 ---------------