Addition of Reverse Authentication to LUD-18.md

18.md

@@ -28,6 +28,8 @@ If `SERVICE` wants to get one or more types of payer identities from `WALLET` th
 +       "mandatory": boolean,
 +       "k1": string // hex encoded 32 bytes of challenge
 +    },
++    "lud16": { "mandatory": boolean },
++    "revauth": { "mandatory": boolean },
 +    ...other fields may be negotiated
 +  },
    "tag": "payRequest",
@@ -58,6 +60,11 @@ The JSON object MUST be of the following format (notice that these fields are sh
   },
   "email": string,
   "identifier": string,
+  "lud16": string,
+  "revauth": {
+       "mandatory": boolean,
+       "k1": string // hex encoded 32 bytes of challenge
+  },
   ...other fields may be included if supported by wallet and requested by service
 }
 ```
@@ -68,6 +75,29 @@ Each key in this JSON object should correspond to a requested payerdata from the
 
 `WALLET` SHOULD NOT send payer identity types omitted in `payerData` record, none at all if record is not present.
 
+`LN Service` takes the GET request and returns JSON response of form:
+
+```diff
+{
+-   pr: string, // bech32-serialized lightning invoice
++   pr: string, // bech32-serialized lightning invoice if amount > 0
+    routes: [], // an empty array
++   "revauth": {
++        "key": string, // hex(<linkingKey>)
++        "k1": string, // same as received from wallet
++        "sig": string, // following LUD-04: hex(sign(hexToBytes(<k1>), <linkingPrivKey>))
++   }
+}
+```
+
+or
+
+```JSON
+{"status":"ERROR", "reason":"error details..."}
+```
+
+`SERVICE` should NOT send `revauth` if it was not first provided by `WALLET`. If `WALLET` marked `revauth` as `"mandatory": true` then `SERVICE` MUST provide `revauth`.
+
 ## 3. Committing payer to the invoice
 
 If `SERVICE` requests (section 1) and `WALLET` sends a `payerdata` record in the callback (section 2), the payer ids MUST be committed to the metadata before the invoice is created.
@@ -97,3 +127,20 @@ descriptionToBeHashed = metadata + payerData
 descriptionToBeHashed == '[["text/plain", "description"], ["image/png;base64", "AAA=="]]{"name":"bob","auth":{"key":"02c9323d02fc164f89c8f688dbfba8aad69a96fa8f6253ba8cce2c6f1546073fa3","sig":"2afd21794e2a801d0d516584ceebe1a24ed8991dd5ec708259aeaee5c0d2d1437542b689ee5d39e619a01a257142d49c18a4af3088c46ce87e2d941a1bcc7210"},"identifier":"[email protected]","pubkey":"03ee58475055820fbfa52e356a8920f62f8316129c39369dbdde3e5d0198a9e315"}'
 descriptionHash = sha256(utf8(descriptionToBeHashed))
 ```
+## 4. Usage Notes
+
+The `payerData` allows for verification that a payment uses the same `linkingkey` as a `LUD-04` user and automates provision of user data.  A user could make payments and then log in for the first time to discover that they have already received credit for their payments and that their user profile has already been populated with their user data.  
+
+The `revauth` dialog provides a mechanism for reverse authentication which can prevent spoofing by confirming that the `SERVICE` associated with a `LUD-16` identifier has the same `linkingkey` as a `WALLET`.  The `WALLET` may choose not pay the invoice provided by `SERVICE` if the reverse authorization fails.
+
+Associating more than one `linkingkey` with the same user data or `LUD-16` identifier causes some loss of privacy.  This can be mitigated by using different sets of user data or `LUD-16` identifiers for different contexts.  The choice to associate user data or `LUD-16` identifiers with a `linkingkey` is at the discretion of the the user, `WALLET` and `SERVICE`.
+
+The owner of physical or virtual items or privileges can be identified by a `LUD-16` identifer or `linkingkey` such that the owner can prove their identity and claim their items or privileges using their `WALLET`.
+
+Authentication allows useful payments with low, zero, or negative amounts to be separated from spam based on the `LUD-16` identifer or `linkingkey` of the payer.  A service can signal their acceptance of payments with zero or negative amounts by setting `minsendable` to a zero or a negative value.
+
+A payment with amount=0 might be used to perform a reverse authentication or upload user data without `SERVICE` having to generate an invoice.
+
+A negative payment (amount<0) implies that `WALLET` is requesting to withdraw funds from `SERVICE`.  The negative payment should include `identifier` and `lud16` to enable automatic processing of the withdrawal.  The `SERVICE` can confirm the origin of the negative payment by performing a reverse authorization and then filter out spam payments accordingly.  At a later time when the user logs on to `SERVICE`, the user can click to complete a withdrawal which will prompt `SERVICE` to send payment to the `LUD-16` identity that originated the negative payment with an `identifier` that matches the negative payment. 
+
+Negative payments give the `LUD-16` identifer similar functionality to the pull payments implemented in btcpay, but with a more streamlined user experience.  Merchants only need to know the `LUD-16` identifer of their customers to pull payments from them and the customers can authorize each payout with a single click or apply an automatic payout criteria based on the `LUD-16` identifer of origin.