initial commit

docs/CARD.md

@@ -0,0 +1,151 @@
+# Steps for making a bolt card
+
+## Introduction
+
+Here we describe how to create your own bolt card.
+
+## Resources
+ 
+- some cards
+  - NXP DNA 424 NTAG cards
+
+- a good NFC reader/writer
+  - Identiv uTrust 3700 F
+
+- software
+  - [NXP TagXplorer software](https://www.nxp.com/products/rfid-nfc/mifare-hf/mifare-desfire/tagxplorer-pc-based-nfc-tag-reader-writer-tool:TAGXPLORER)
+  - [Java Run Time environment](https://java.com/de/download/)
+
+## Steps
+
+### Connect to the card
+- start the NFC TagXplorer software
+- `Connect` to the NFC card reader
+- place a card on the reader and click `Connect Tag`
+- verify the card description
+
+![tag connected](images/con.webp)
+
+### Read the card
+- select `NDEF Operations` and `Read NDEF`
+- if you get this error, click `Format NDEF` and try again
+
+![bytes to read should be greater than zero](images/btr.webp)
+
+- verify that the read completes without erroring
+
+### Start to set up the URI template
+- select `NTAG Operations`, `Mirroring Features` and `NTAG 424 DNA`
+- set `Protocol` to `https://`
+- set `URI Data` to
+```
+lnurlw://card.yourdomain.com
+```
+- select `Add PICCDATA` and `Enable SUN Message`
+- adjust the `URI Data` to
+```
+lnurlw://card.yourdomain.com/ln?p=00000000000000000000000000000000&c=0000000000000000
+```
+- click after `p=` and note the p_position (38 in this case)
+- click after `c=` and note the c_position (73 in this case)
+- select `Write To Tag`
+
+![NDEF message written successfully](images/nfwc.webp)
+
+- now go back to `NDEF Operations` and `Read NDEF`
+- verify that the `NDEF Payload Info` is as expected
+
+![read payload as text](images/rd-txt.webp)
+	 
+### Finish setting up the URI template
+- notice that the URI shows as `https://lnurlw://card ...` but we want `lnurlw://card ...`
+- go to `NTAG Operations` and `NTAG 424 DNA`
+- select `Read/Write data`
+- select `File No` as `NDEF File - 02`
+- click `Read`
+
+![read NDEF data](images/rdh.webp)
+
+- the NDEF file is `0057D1015355046C6E75726C ...`.
+- look for the bytes `5504` (6 bytes from the start)
+- `04` is the code for `https://` URI prepending
+- change the `04` to `00` to indicate no prepending for the URI
+
+![write NDEF data](images/wrh.webp)
+
+- click `Write`
+
+![written successfully](images/ws.webp)
+
+- now go back to `NDEF Operations` and `Read NDEF`
+- verify that the `NDEF Payload(HEX) Info` is similar to that shown
+
+![read payload as hex](images/nrd.webp)
+
+- copy the hex data and convert to text, without the `0x00` prefix
+- verify you have your expected `URI data` value  
+
+[Online hex to text tool](http://www.unit-conversion.info/texttools/hexadecimal/)
+
+![hex to text online tool](images/hex.webp)
+
+### Set up the SUN authentication message
+- go to `NTAG Operations` and `NTAG 424 DNA`
+- select `Security Management` and click `Authentiate First`
+
+![success dialog](images/avs.webp)
+
+- select `Get/Change File Settings`
+
+![success dialog](images/gfs.webp)
+
+- set up the values in the order shown
+
+![file and SDM options with field entry order](images/fs-add.webp)
+
+- select `Change File Settings`
+
+![success message](images/cfs.webp)
+
+- now go back to `NDEF Operations` and `Read NDEF`
+- convert the hex data to text again
+- verify that the `p` and `c` values are non zero
+- select `Read NDEF` again
+- convert the hex data to text again
+- verify that the `p` and `c` values are in the right place
+- verify that the `p` and `c` values change on each read
+ 
+### Change the application keys
+- go to `NTAG Operations` and `NTAG 424 DNA`
+- select `Security Management`
+- select `Authenticate`
+- leave the `Card Key No` set to `00`
+- leave the `Key` value set to `00000000000000000000000000000000` if not changed yet
+- click `Authenticate First`
+
+![success message](images/avs.webp)
+
+- select `Change Key`
+- select the `Card Key No` to change the key value for `00` to `04`
+- leave the `Old Key` value set to `00000000000000000000000000000000` if not changed yet
+- enter a `New Key` value as required
+- enter a `New Key Version` value of `00` or as required to keep track of your keys
+- click `Change Key`
+
+![success message](images/ccs.webp)
+
+- repeat this to change all 5 application keys to your own values
+
+### Lock the card
+- go to `NTAG Operations` and `NTAG 424 DNA`
+- select `Security Management` and click `Authentiate First`
+- select `Get/Change File Settings`
+- adjust the `Access Rights` settings as shown
+
+![success message](images/lock.webp)
+
+## Testing
+- set up a [bolt card service](INSTALL.md)
+- add a record in the database for the new card
+- use a merchant point of sale to scan your bolt card, e.g. [Breez wallet](https://breez.technology/)
+- watch the bolt card service logs and verify that the requests are received and processed

docs/FAQ.md

@@ -0,0 +1,16 @@
+# FAQ
+
+> Why do I get a payment failure with NO_ROUTE ?  
+
+This is due to your payment lightning node not finding a route to the merchant lightning node.  
+It may help to open well funded channels to other well connected nodes.  
+It may also help to increase your maximum network fee in your service variables, **FEE_LIMIT_SAT** .  
+It can be useful to test paying invoices directly from your lightning node.  
+
+> Why do my payments take so long ?  
+
+
+This is due to the time taken for your payment lightning node to find a route.  
+It can be improved by opening channels using clearnet rather than on the tor network.  
+It may also help to improve your lightning node hardware or software setup.  
+It can be useful to test paying invoices directly from your lightning node.  

docs/INSTALL.md

@@ -0,0 +1,82 @@
+# Bolt card service installation
+
+## hardware & o/s
+
+1 GHz processor, 2 GB RAM, 10GB storage minimum  
+Ubuntu 20.04 LTS server
+
+### install Go
+
+[Go download & install](https://go.dev/doc/install)  
+`$ go version` >= 1.18.3
+
+### install Postgres
+
+[Postgres download & install](https://www.postgresql.org/download/linux/ubuntu/)  
+`$ psql --version` >= 12.11
+
+### install Caddy
+
+[Caddy download & install](https://caddyserver.com/docs/install)  
+`$ caddy version` >= 2.5.2
+
+### download the boltcard repository
+
+`$ git clone https://github.com/boltcard/boltcard`
+
+### get a macaroon and tls.cert from the lightning node
+
+create a macaroon with limited permissions to the lightning node  
+```
+$ lncli \                                                    
+--rpcserver=lightning-node.io:10009 \
+--macaroonpath=admin.macaroon \
+--tlscertpath="tls.cert" \
+bakemacaroon uri:/routerrpc.Router/SendPaymentV2 > SendPaymentV2.macaroon.hex
+
+$ xxd -r -p SendPaymentV2.macaroon.hex SendPaymentV2.macaroon
+```
+
+### setup the boltcard server
+edit `boltcard.service` in the section named `boltcard service settings`  
+edit `Caddyfile` to set the boltcard domain name  
+edit `add_card_data.sql` to set up the individual bolt card records
+
+### database creation
+`$ ./s_create_db`
+
+### boltcard service install
+`$ sudo cp boltcard.service /etc/systemd/system/boltcard.service`  
+`$ ./s_build`  
+`$ systemctl status boltcard`
+
+### https setup
+set up the domain A record to point to the server  
+set up the server hosting firewall to allow open access to https (port 443) only  
+
+### caddy setup for https
+`$ sudo cp Caddyfile /etc/caddy`  
+`$ sudo systemctl stop caddy`  
+`$ sudo systemctl start caddy`  
+`$ sudo systemctl status caddy`  
+you should see 'certificate obtained successfully' in the service log
+
+### service bring-up and testing
+#### service log
+the service log should be monitored on a separate console while tests are run  
+`$ journalctl -u boltcard.service -f`
+#### local http
+`$ curl http://127.0.0.1:9000/ln?1`  
+this should respond with 'bad request' and show up in the service log  
+#### remote https
+navigate to the service URL from a browser, for example `https://card.yourdomain.com/ln?2`  
+this should respond with 'bad request' and show up in the service log  
+#### bolt card
+[create a bolt card](docs/CARD.md) with the URI pointing to this server  
+use a PoS setup to read the bolt card, e.g. [Breez wallet](https://breez.technology/)   
+monitor the service log to ensure decryption, authentication, payment rules and lightning payment work as expected  
+
+# Further information and support
+
+[bolt card FAQ](docs/FAQ.md)  
+[bolt card telegram group](https://t.me/bolt_card)

docs/SECURITY.md

@@ -0,0 +1,11 @@
+# Security
+
+## secrets
+- card AES decrypt key to the environment variable `AES_DECRYPT_KEY`
+- card AES cmac keys into the database table `cards`
+
+- `tls.cert` and `SendPaymentV2.macaroon` for the lightning node
+
+- password for the application database user `cardapp`
+  - database script in `create_db.sql`
+  - application environment variable in `lnurlw.service`

docs/SPEC.md

@@ -0,0 +1,34 @@
+# Bolt card specification
+
+The bolt card system is built on the open standards listed below.
+
+- [LUD-03: withdrawRequest base spec.](https://github.com/fiatjaf/lnurl-rfc/blob/luds/03.md)
+- [LUD-17: Protocol schemes and raw (non bech32-encoded) URLs.](https://github.com/fiatjaf/lnurl-rfc/blob/luds/17.md)
+
+## Bolt card interaction
+
+- the point-of-sale (POS) will read an NDEF message from the card, for example
+```
+lnurlw://card.yourdomain.com?p=A2EF40F6D46F1BB36E6EBF0114D4A464&c=F509EEA788E37E32
+```
+- the POS will call your server here
+```
+https://card.yourdomain.com?p=A2EF40F6D46F1BB36E6EBF0114D4A464&c=F509EEA788E37E32
+```
+- your server should verify the payment request and issue an LNURLw response
+
+### Server side verification 
+- for the `p` value and the `SDM Meta Read Access Key` value, decrypt the UID and counter
+- for the `c` value and the `SDM File Read Access Key` value, check with AES-CMAC
+
+![decrypt and cmac steps](images/ac.webp)
+
+- the authenticated UID and counter values can be used on your server to verify the request
+- your server should only accept an increasing counter value
+- additional validation rules can be added at your server, for example
+  - an enable flag
+  - payment limits
+  - a list of allowed merchants
+  - a verification of your location from your phone
+- your server can then make payment from your lightning node
+

docs/SYSTEM.md

@@ -0,0 +1,41 @@
+## System
+
+The customer and the merchant must have a supporting infrastructure to make and accept payments using a bolt card.
+
+### Interaction
+```mermaid
+flowchart TB
+    BoltCard(bolt card)-. NFC .-PointOfSale(point of sale)
+    MerchantServer(merchant server)-. LNURLw .-BoltCardServer(bolt card server)
+    LightningNodeA(lightning node)-. lightning network .-LightningNodeB(lightning node)
+    
+    subgraph merchant
+    PointOfSale<-->MerchantServer
+    LightningNodeB-->MerchantServer
+    end
+    
+    subgraph customer
+    BoltCardServer-->LightningNodeA
+    end
+```
+
+### Sequencing
+```mermaid
+sequenceDiagram
+    participant p1 as customer bolt card
+    participant p2 as merchant point of sale
+    participant p3 as merchant server
+    participant p4 as customer bolt card server
+    participant p5 as customer lightining node
+    participant p6 as merchant lightning node
+    p1->>p2: NFC read
+    p2->>p3: API call
+    p3->>p4: LNURLw request
+    p4->>p3: LNURLw response
+    p3->>p4: LNURLw callback
+    p4->>p3: LNURLw response
+    p4->>p5: API call
+    p5-->>p6: lightning network payment
+    p6->>p3: payment notification
+    p3->>p2: user notification
+```