diff --git a/21.md b/21.md new file mode 100644 index 0000000..80ae070 --- /dev/null +++ b/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 4-digit PIN from the user (customer) and then add it as `pin=` to the query string of the callback URL to authorize the withdrawal. + +**Example callback:** + +`https://ln-example.com?k1=&pr=&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 4-digit 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 fixed length of 4 digits this document makes no assumptions about whether PINs are static (multiple-use) or one-time passwords (OTPs) or other 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). diff --git a/README.md b/README.md index 3ac88d5..a19c0ab 100644 --- a/README.md +++ b/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], [Mash][mash], [Muun][muun], [Phoenix][phoenix], [Pouch.ph][pouchph], [ShockWallet][shockwallet], [OBW][obw], [OneKey][onekey], [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], [Mash][mash], [Muun][muun], [Phoenix][phoenix], [Pouch.ph][pouchph], [ShockWallet][shockwallet], [OBW][obw], [OneKey][onekey], [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], [OneKey][onekey], [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], [OneKey][onekey], [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], [Mash][mash], [Phoenix][phoenix], [Pouch.ph][pouchph], [ShockWallet][shockwallet], [OBW][obw], [OneKey][onekey], [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], [Mash][mash], [Phoenix][phoenix], [Pouch.ph][pouchph], [OBW][obw], [OneKey][onekey], [Stacker.News][stacker.news], [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], [Mash][mash], [OneKey][onekey], [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], [Mash][mash], [OneKey][onekey], [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], [Mash][mash], [OneKey][onekey], [Phoenix][phoenix] | +| [21][21] | pinLimit for withdrawRequest | [Bolt Card Wallet][boltcardwallet], [Bolt Card PoS][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 @@ -76,6 +78,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] | @@ -211,6 +216,7 @@ Tools for developers [18]: 18.md [19]: 19.md [20]: 20.md +[21]: 21.md Dependency Tree ---------------