protom/sattle
1
0
Fork 0
mirror of https://github.com/tompro/sattle.git synced 2026-10-25 17:39:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Formatting

Browse Source
This commit is contained in:
protom
2026-09-05 18:30:35 +02:00
parent 454a9db1d5
commit 4caa075052
133 changed files with 8260 additions and 8181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+75 -81
View File
@@ -2,108 +2,102 @@
## [0.0.4](https://github.com/tompro/sattle/compare/sattle-v0.0.3...sattle-v0.0.4) (2026-08-31)
### Features
* **funds:** keep the claimable note of a pending named transfer ([c996393](https://github.com/tompro/sattle/commit/c9963934aa6bc384cd9742e099b2c72b1f69e400))
* **lnurlcash:** claim mint outputs named by a wallet-chosen secret ([58268b2](https://github.com/tompro/sattle/commit/58268b2921d05c29ed4df98891e5ab5069617dfb))
* **lnurlcash:** probe would-be outputs before believing a mutation refusal ([48be23d](https://github.com/tompro/sattle/commit/48be23dceb940b28166b242ff308600864b87dd2))
* **lnurlcash:** transfer to mints with wallet-named outputs ([67b2122](https://github.com/tompro/sattle/commit/67b2122e52399b85e4829a0b3b61224252ae8ebf))
* **nwc:** make_invoice against mints with wallet-named outputs ([ae5064b](https://github.com/tompro/sattle/commit/ae5064b69a545a9ade671b5d701d5399fe3517ed))
* **receive:** accept named mints that serve no verify URL ([39a144c](https://github.com/tompro/sattle/commit/39a144cf50d621908b79cc27c7c664f6f9fc369c))
* support LUD-25 named mint outputs (lnurl-mint v0.4.0) ([f3d5cc4](https://github.com/tompro/sattle/commit/f3d5cc4b31cf0dba845e3abc4fa1b108c34122e5))
- **funds:** keep the claimable note of a pending named transfer ([c996393](https://github.com/tompro/sattle/commit/c9963934aa6bc384cd9742e099b2c72b1f69e400))
- **lnurlcash:** claim mint outputs named by a wallet-chosen secret ([58268b2](https://github.com/tompro/sattle/commit/58268b2921d05c29ed4df98891e5ab5069617dfb))
- **lnurlcash:** probe would-be outputs before believing a mutation refusal ([48be23d](https://github.com/tompro/sattle/commit/48be23dceb940b28166b242ff308600864b87dd2))
- **lnurlcash:** transfer to mints with wallet-named outputs ([67b2122](https://github.com/tompro/sattle/commit/67b2122e52399b85e4829a0b3b61224252ae8ebf))
- **nwc:** make_invoice against mints with wallet-named outputs ([ae5064b](https://github.com/tompro/sattle/commit/ae5064b69a545a9ade671b5d701d5399fe3517ed))
- **receive:** accept named mints that serve no verify URL ([39a144c](https://github.com/tompro/sattle/commit/39a144cf50d621908b79cc27c7c664f6f9fc369c))
- support LUD-25 named mint outputs (lnurl-mint v0.4.0) ([f3d5cc4](https://github.com/tompro/sattle/commit/f3d5cc4b31cf0dba845e3abc4fa1b108c34122e5))
### Bug Fixes
* commit carves before the settlement wait ([#6](https://github.com/tompro/sattle/issues/6)) ([09f7fe0](https://github.com/tompro/sattle/commit/09f7fe02872838253882451ce7ed1f818f4ace62))
* commit send, pay and move carves at the checkpoint ([#6](https://github.com/tompro/sattle/issues/6)) ([9e37fee](https://github.com/tompro/sattle/commit/9e37fee841ab1c8ecb6bf7e3d00dfd61414ce306))
* **lnurlcash:** assert named claims land at the wallet's own secret ([6bb07ff](https://github.com/tompro/sattle/commit/6bb07ff9ec5c69b01c1822471c24312b44707927))
* **lnurlcash:** commit carves before the settlement wait ([#6](https://github.com/tompro/sattle/issues/6)) ([587dd11](https://github.com/tompro/sattle/commit/587dd11ba8a413c12dde134b11b2040c9d383c86))
* **lnurlcash:** rescue landed mutations from retry refusals ([50b2427](https://github.com/tompro/sattle/commit/50b2427b8db07692a590ff2602a034385bbac7df))
* replace forgesworn with moneyer in the public mint suggestions ([4cc8e0a](https://github.com/tompro/sattle/commit/4cc8e0aba2bd7ef8e4ea7d1b0ee9b98f21d19ee7))
- commit carves before the settlement wait ([#6](https://github.com/tompro/sattle/issues/6)) ([09f7fe0](https://github.com/tompro/sattle/commit/09f7fe02872838253882451ce7ed1f818f4ace62))
- commit send, pay and move carves at the checkpoint ([#6](https://github.com/tompro/sattle/issues/6)) ([9e37fee](https://github.com/tompro/sattle/commit/9e37fee841ab1c8ecb6bf7e3d00dfd61414ce306))
- **lnurlcash:** assert named claims land at the wallet's own secret ([6bb07ff](https://github.com/tompro/sattle/commit/6bb07ff9ec5c69b01c1822471c24312b44707927))
- **lnurlcash:** commit carves before the settlement wait ([#6](https://github.com/tompro/sattle/issues/6)) ([587dd11](https://github.com/tompro/sattle/commit/587dd11ba8a413c12dde134b11b2040c9d383c86))
- **lnurlcash:** rescue landed mutations from retry refusals ([50b2427](https://github.com/tompro/sattle/commit/50b2427b8db07692a590ff2602a034385bbac7df))
- replace forgesworn with moneyer in the public mint suggestions ([4cc8e0a](https://github.com/tompro/sattle/commit/4cc8e0aba2bd7ef8e4ea7d1b0ee9b98f21d19ee7))
## [0.0.3](https://github.com/tompro/sattle/compare/sattle-v0.0.2...sattle-v0.0.3) (2026-08-24)
### Features
* activate only proven wallet owners ([c319e11](https://github.com/tompro/sattle/commit/c319e11d3eff2a4ae0bb42d23628750ed12de8fc))
* add persisted owner guards and events ([69fbdb6](https://github.com/tompro/sattle/commit/69fbdb68ee3edccc7561fe4c201ef4497443d331))
* apply owner-aware wallet backups ([7607e47](https://github.com/tompro/sattle/commit/7607e47358fe4d9736c04853b784e05b2bef20c1))
* apply wallet fund changes atomically ([5b3a69e](https://github.com/tompro/sattle/commit/5b3a69e91055082e9c8cabb09d3c02302db05a37))
* await owner-aware Nostr restores ([f55f208](https://github.com/tompro/sattle/commit/f55f20883671ccd0fd696f3696a76fa739738fa6))
* await trusted mint management actions ([3c2a2cc](https://github.com/tompro/sattle/commit/3c2a2cc4a580126e8c199268aa543719ed771c2e))
* bind saved keys to versioned wallet owners ([acfab83](https://github.com/tompro/sattle/commit/acfab8343897f69dd714474724f419eef569fe7a))
* commit bearer changesets in one write ([586d12b](https://github.com/tompro/sattle/commit/586d12b666e13f040254ffbc1c618859cf7659b4))
* converge trusted mints on storage events ([83c9e5b](https://github.com/tompro/sattle/commit/83c9e5b95ff6d7189534437180141bcfd86d282c))
* create owner-bound NWC connections ([228a92b](https://github.com/tompro/sattle/commit/228a92b0f0f3238bee0cf0bcf7315f6b88dbae30))
* drain tracked NWC handlers on stop ([3ed214c](https://github.com/tompro/sattle/commit/3ed214c157743dc6ba2c28be25022bf65765a904))
* expose fund ownership assertions ([845ec41](https://github.com/tompro/sattle/commit/845ec410e506f1ba6a1c9c2666a9e6282d391755))
* fence wallet mutations by lifecycle owner ([9fa4abd](https://github.com/tompro/sattle/commit/9fa4abdaf3f775512e6e9c1caed72bb0ade76544))
* harden passkey ceremonies ([d9be457](https://github.com/tompro/sattle/commit/d9be457221a774d330c9d7c7cfa67487ece2a039))
* invalidate stale wallet tabs ([2e0f003](https://github.com/tompro/sattle/commit/2e0f0038f756d935c3674fb85c0d042a946ff9d8))
* preserve trusted mint rekey transitions ([d890a69](https://github.com/tompro/sattle/commit/d890a69c406b28a7f18bd6b356d9ad7eaab66341))
* restore Nostr backups through wallet lifecycle ([3f6010b](https://github.com/tompro/sattle/commit/3f6010b31262f3ea7ee5ac65c1dd7bcf6fa15635))
* scope NWC storage to wallet owners ([9f6bcad](https://github.com/tompro/sattle/commit/9f6bcad706760cd428e462ae28557f28362fddcf))
* scope passkey slots to proven owners ([12e4ec9](https://github.com/tompro/sattle/commit/12e4ec9199bfd78b741ae38d0fd49135594d85eb))
* scope trusted mint state in Pinia ([81c28ec](https://github.com/tompro/sattle/commit/81c28ec16dee42b7705ac97dc047a3486045c9ab))
* serialize trusted mint transactions ([d735aca](https://github.com/tompro/sattle/commit/d735aca885a63ff2bf9d96dd6732f02e63c382d4))
* serialize wallet lifecycle transitions ([62b93ba](https://github.com/tompro/sattle/commit/62b93baa05789961f2e8ed336c1d079e666f311e))
* validate trusted mint registry envelopes ([82f008b](https://github.com/tompro/sattle/commit/82f008b33f0843b8c999d26f1f7d4dd62e6c45b2))
- activate only proven wallet owners ([c319e11](https://github.com/tompro/sattle/commit/c319e11d3eff2a4ae0bb42d23628750ed12de8fc))
- add persisted owner guards and events ([69fbdb6](https://github.com/tompro/sattle/commit/69fbdb68ee3edccc7561fe4c201ef4497443d331))
- apply owner-aware wallet backups ([7607e47](https://github.com/tompro/sattle/commit/7607e47358fe4d9736c04853b784e05b2bef20c1))
- apply wallet fund changes atomically ([5b3a69e](https://github.com/tompro/sattle/commit/5b3a69e91055082e9c8cabb09d3c02302db05a37))
- await owner-aware Nostr restores ([f55f208](https://github.com/tompro/sattle/commit/f55f20883671ccd0fd696f3696a76fa739738fa6))
- await trusted mint management actions ([3c2a2cc](https://github.com/tompro/sattle/commit/3c2a2cc4a580126e8c199268aa543719ed771c2e))
- bind saved keys to versioned wallet owners ([acfab83](https://github.com/tompro/sattle/commit/acfab8343897f69dd714474724f419eef569fe7a))
- commit bearer changesets in one write ([586d12b](https://github.com/tompro/sattle/commit/586d12b666e13f040254ffbc1c618859cf7659b4))
- converge trusted mints on storage events ([83c9e5b](https://github.com/tompro/sattle/commit/83c9e5b95ff6d7189534437180141bcfd86d282c))
- create owner-bound NWC connections ([228a92b](https://github.com/tompro/sattle/commit/228a92b0f0f3238bee0cf0bcf7315f6b88dbae30))
- drain tracked NWC handlers on stop ([3ed214c](https://github.com/tompro/sattle/commit/3ed214c157743dc6ba2c28be25022bf65765a904))
- expose fund ownership assertions ([845ec41](https://github.com/tompro/sattle/commit/845ec410e506f1ba6a1c9c2666a9e6282d391755))
- fence wallet mutations by lifecycle owner ([9fa4abd](https://github.com/tompro/sattle/commit/9fa4abdaf3f775512e6e9c1caed72bb0ade76544))
- harden passkey ceremonies ([d9be457](https://github.com/tompro/sattle/commit/d9be457221a774d330c9d7c7cfa67487ece2a039))
- invalidate stale wallet tabs ([2e0f003](https://github.com/tompro/sattle/commit/2e0f0038f756d935c3674fb85c0d042a946ff9d8))
- preserve trusted mint rekey transitions ([d890a69](https://github.com/tompro/sattle/commit/d890a69c406b28a7f18bd6b356d9ad7eaab66341))
- restore Nostr backups through wallet lifecycle ([3f6010b](https://github.com/tompro/sattle/commit/3f6010b31262f3ea7ee5ac65c1dd7bcf6fa15635))
- scope NWC storage to wallet owners ([9f6bcad](https://github.com/tompro/sattle/commit/9f6bcad706760cd428e462ae28557f28362fddcf))
- scope passkey slots to proven owners ([12e4ec9](https://github.com/tompro/sattle/commit/12e4ec9199bfd78b741ae38d0fd49135594d85eb))
- scope trusted mint state in Pinia ([81c28ec](https://github.com/tompro/sattle/commit/81c28ec16dee42b7705ac97dc047a3486045c9ab))
- serialize trusted mint transactions ([d735aca](https://github.com/tompro/sattle/commit/d735aca885a63ff2bf9d96dd6732f02e63c382d4))
- serialize wallet lifecycle transitions ([62b93ba](https://github.com/tompro/sattle/commit/62b93baa05789961f2e8ed336c1d079e666f311e))
- validate trusted mint registry envelopes ([82f008b](https://github.com/tompro/sattle/commit/82f008b33f0843b8c999d26f1f7d4dd62e6c45b2))
### Bug Fixes
* await NWC payment bearer commits ([09b7b63](https://github.com/tompro/sattle/commit/09b7b63c9ddf5f19bc14bd35f253387b7862cece))
* await wallet commits in the NWC store ([99e6ae1](https://github.com/tompro/sattle/commit/99e6ae1b12de9f269c456ef015774cbe64c2b205))
* clear runtime state after lifecycle failures ([3acc63e](https://github.com/tompro/sattle/commit/3acc63e96866bd8c7f690499322f6cc631c0e329))
* commit carved wallet funds atomically ([c59521a](https://github.com/tompro/sattle/commit/c59521a421a3a8b40afd9d3e6088a2c36bc56354))
* consume owner monitor transition failures ([e892a33](https://github.com/tompro/sattle/commit/e892a330fc386e68f5ff11237cd3fd54534d68c6))
* drain accepted NWC work before wallet lock ([e983734](https://github.com/tompro/sattle/commit/e98373491fe7295cfc2a817d64ebdab0b1895a18))
* fence carve operations before mutation ([6fa4283](https://github.com/tompro/sattle/commit/6fa4283ed65cd3943beb4486aee8e876732b73c5))
* fence inter-mint transfer operations ([02f901c](https://github.com/tompro/sattle/commit/02f901c87c0f983b67ea50619e0f8a42585acf0a))
* fence invoice payment operations ([c4c9d8a](https://github.com/tompro/sattle/commit/c4c9d8a94ae4856d8e81ca6faa6b1d0a4d871b60))
* fence mint and receive operations ([7f69f78](https://github.com/tompro/sattle/commit/7f69f781f55239de5502d8c17954d582a0ee45e6))
* fence send and pay flows ([401a26d](https://github.com/tompro/sattle/commit/401a26dc6b1221641bcdcbc1aa1e5464025ec41c))
* hide invoice settlement until commit ([513c67f](https://github.com/tompro/sattle/commit/513c67fc143d27c1e57c3c2c6771a0f622152382))
* mirror trusted mint commits across tabs ([e9bbb35](https://github.com/tompro/sattle/commit/e9bbb358aae79d3ce1fa6690749e9d63d3c748ff))
* normalize storage lock failures ([1dbf578](https://github.com/tompro/sattle/commit/1dbf5788f9b82162122eea205ea3d6e9c5badf1a))
* preserve conservative NWC budget debits ([fff24a7](https://github.com/tompro/sattle/commit/fff24a75b24f7a80e4f3f517525c7eb0c2d93155))
* publish activity only after persistence ([54031dc](https://github.com/tompro/sattle/commit/54031dc8de03448aa3cee6c2a8a9d035d92c752c))
* surface receive post-commit trust failures ([f087ebe](https://github.com/tompro/sattle/commit/f087ebe2f2e28bbd0e4c3cfe3407e77c0a78a7aa))
* validate auxiliary wallet storage ([0862a10](https://github.com/tompro/sattle/commit/0862a10b01d33fd9c0f7f7a3f69a738e89af8c19))
* validate NWC requests before dispatch ([b52172c](https://github.com/tompro/sattle/commit/b52172c0cb28884b0d00636f601cac0a52e6d504))
* **wallet:** enforce owner-bound integrity and durable commits ([338b281](https://github.com/tompro/sattle/commit/338b2812e357f01027800985051e62dea6c207d8))
- await NWC payment bearer commits ([09b7b63](https://github.com/tompro/sattle/commit/09b7b63c9ddf5f19bc14bd35f253387b7862cece))
- await wallet commits in the NWC store ([99e6ae1](https://github.com/tompro/sattle/commit/99e6ae1b12de9f269c456ef015774cbe64c2b205))
- clear runtime state after lifecycle failures ([3acc63e](https://github.com/tompro/sattle/commit/3acc63e96866bd8c7f690499322f6cc631c0e329))
- commit carved wallet funds atomically ([c59521a](https://github.com/tompro/sattle/commit/c59521a421a3a8b40afd9d3e6088a2c36bc56354))
- consume owner monitor transition failures ([e892a33](https://github.com/tompro/sattle/commit/e892a330fc386e68f5ff11237cd3fd54534d68c6))
- drain accepted NWC work before wallet lock ([e983734](https://github.com/tompro/sattle/commit/e98373491fe7295cfc2a817d64ebdab0b1895a18))
- fence carve operations before mutation ([6fa4283](https://github.com/tompro/sattle/commit/6fa4283ed65cd3943beb4486aee8e876732b73c5))
- fence inter-mint transfer operations ([02f901c](https://github.com/tompro/sattle/commit/02f901c87c0f983b67ea50619e0f8a42585acf0a))
- fence invoice payment operations ([c4c9d8a](https://github.com/tompro/sattle/commit/c4c9d8a94ae4856d8e81ca6faa6b1d0a4d871b60))
- fence mint and receive operations ([7f69f78](https://github.com/tompro/sattle/commit/7f69f781f55239de5502d8c17954d582a0ee45e6))
- fence send and pay flows ([401a26d](https://github.com/tompro/sattle/commit/401a26dc6b1221641bcdcbc1aa1e5464025ec41c))
- hide invoice settlement until commit ([513c67f](https://github.com/tompro/sattle/commit/513c67fc143d27c1e57c3c2c6771a0f622152382))
- mirror trusted mint commits across tabs ([e9bbb35](https://github.com/tompro/sattle/commit/e9bbb358aae79d3ce1fa6690749e9d63d3c748ff))
- normalize storage lock failures ([1dbf578](https://github.com/tompro/sattle/commit/1dbf5788f9b82162122eea205ea3d6e9c5badf1a))
- preserve conservative NWC budget debits ([fff24a7](https://github.com/tompro/sattle/commit/fff24a75b24f7a80e4f3f517525c7eb0c2d93155))
- publish activity only after persistence ([54031dc](https://github.com/tompro/sattle/commit/54031dc8de03448aa3cee6c2a8a9d035d92c752c))
- surface receive post-commit trust failures ([f087ebe](https://github.com/tompro/sattle/commit/f087ebe2f2e28bbd0e4c3cfe3407e77c0a78a7aa))
- validate auxiliary wallet storage ([0862a10](https://github.com/tompro/sattle/commit/0862a10b01d33fd9c0f7f7a3f69a738e89af8c19))
- validate NWC requests before dispatch ([b52172c](https://github.com/tompro/sattle/commit/b52172c0cb28884b0d00636f601cac0a52e6d504))
- **wallet:** enforce owner-bound integrity and durable commits ([338b281](https://github.com/tompro/sattle/commit/338b2812e357f01027800985051e62dea6c207d8))
## [0.0.2](https://github.com/tompro/sattle/compare/sattle-v0.0.1...sattle-v0.0.2) (2026-08-20)
### Features
* backup and security settings pages, nostr restore onboarding, passkey unlock entry ([1920a00](https://github.com/tompro/sattle/commit/1920a00cd65651f057cc44f4e38d14f8353cfa09))
* capability layer for clipboard, share and deep links with tests ([f525b06](https://github.com/tompro/sattle/commit/f525b069664cc34fbac3c00f5101aaabd774fece))
* capacitor android platform project ([3f22534](https://github.com/tompro/sattle/commit/3f22534cf0f30f1a2bc1ab1aa645517e85a7949c))
* deep link routing for lightning and lnurl schemes plus association files ([229e9fc](https://github.com/tompro/sattle/commit/229e9fcf38addc843a81a4b57e1f70cec76f36fd))
* inter-mint transfer op with fee quote and ambiguity-safe outcomes ([142734b](https://github.com/tompro/sattle/commit/142734b903e932a36db2d0e62a4c66ceb9ee9fd6))
* manage mints and move funds settings pages ([f631c7c](https://github.com/tompro/sattle/commit/f631c7c264fe962b33ba2c8ea1cc3f8974cc6607))
* native biometric unlock via biometric-gated wrap of the linking key ([e59b722](https://github.com/tompro/sattle/commit/e59b722b5e9093e34b336f0cb0446e34383d4df7))
* nip-47 nwc wallet service engine with per-connection budgets ([33318a5](https://github.com/tompro/sattle/commit/33318a5150afd55b5580dd5a15052434aefde90f))
* nostr kind-30078 backup engine with nip-44 self-encryption and merge-on-restore ([7ecade3](https://github.com/tompro/sattle/commit/7ecade32eeb277d9bd6df734ddc76232f06bdee0))
* nwc connections settings page with one-time connection strings and service lifecycle ([5221127](https://github.com/tompro/sattle/commit/52211273b15e0eb503d5466a250f756a3ed3548a))
* pinia wallet, mints and activity stores with wallet boot ([fdd12dc](https://github.com/tompro/sattle/commit/fdd12dcc1eff116bf335673744e519975b3f3ef2))
* reusable mint fee math with cached quotes, fee-aware Max in move funds ([f4b9377](https://github.com/tompro/sattle/commit/f4b9377d17a2736c429a7272fac8b1742098a60d))
* sattle branding, logo assets and generated app icons ([48e4c84](https://github.com/tompro/sattle/commit/48e4c840929e68cd1740669379b7ed5ed37d32b0))
* send/receive dialogs, qr scanner, history and unlock components ([48fffff](https://github.com/tompro/sattle/commit/48fffff02a17c303dbf807de140d56af26cae88f))
* wallet operations engine and encrypted storage with tests ([1c9e716](https://github.com/tompro/sattle/commit/1c9e7165e4269996891e9112951c3ec75a6e6898))
* wallet screens, branded header layout and mobile-first main view ([1fe1453](https://github.com/tompro/sattle/commit/1fe1453745f3ab9132decb984242b586588c3178))
* webauthn prf passkey unlock engine as alternative wrap of the linking key ([7db3408](https://github.com/tompro/sattle/commit/7db34083e6345fb5acbf31722736d24fa0441815))
- backup and security settings pages, nostr restore onboarding, passkey unlock entry ([1920a00](https://github.com/tompro/sattle/commit/1920a00cd65651f057cc44f4e38d14f8353cfa09))
- capability layer for clipboard, share and deep links with tests ([f525b06](https://github.com/tompro/sattle/commit/f525b069664cc34fbac3c00f5101aaabd774fece))
- capacitor android platform project ([3f22534](https://github.com/tompro/sattle/commit/3f22534cf0f30f1a2bc1ab1aa645517e85a7949c))
- deep link routing for lightning and lnurl schemes plus association files ([229e9fc](https://github.com/tompro/sattle/commit/229e9fcf38addc843a81a4b57e1f70cec76f36fd))
- inter-mint transfer op with fee quote and ambiguity-safe outcomes ([142734b](https://github.com/tompro/sattle/commit/142734b903e932a36db2d0e62a4c66ceb9ee9fd6))
- manage mints and move funds settings pages ([f631c7c](https://github.com/tompro/sattle/commit/f631c7c264fe962b33ba2c8ea1cc3f8974cc6607))
- native biometric unlock via biometric-gated wrap of the linking key ([e59b722](https://github.com/tompro/sattle/commit/e59b722b5e9093e34b336f0cb0446e34383d4df7))
- nip-47 nwc wallet service engine with per-connection budgets ([33318a5](https://github.com/tompro/sattle/commit/33318a5150afd55b5580dd5a15052434aefde90f))
- nostr kind-30078 backup engine with nip-44 self-encryption and merge-on-restore ([7ecade3](https://github.com/tompro/sattle/commit/7ecade32eeb277d9bd6df734ddc76232f06bdee0))
- nwc connections settings page with one-time connection strings and service lifecycle ([5221127](https://github.com/tompro/sattle/commit/52211273b15e0eb503d5466a250f756a3ed3548a))
- pinia wallet, mints and activity stores with wallet boot ([fdd12dc](https://github.com/tompro/sattle/commit/fdd12dcc1eff116bf335673744e519975b3f3ef2))
- reusable mint fee math with cached quotes, fee-aware Max in move funds ([f4b9377](https://github.com/tompro/sattle/commit/f4b9377d17a2736c429a7272fac8b1742098a60d))
- sattle branding, logo assets and generated app icons ([48e4c84](https://github.com/tompro/sattle/commit/48e4c840929e68cd1740669379b7ed5ed37d32b0))
- send/receive dialogs, qr scanner, history and unlock components ([48fffff](https://github.com/tompro/sattle/commit/48fffff02a17c303dbf807de140d56af26cae88f))
- wallet operations engine and encrypted storage with tests ([1c9e716](https://github.com/tompro/sattle/commit/1c9e7165e4269996891e9112951c3ec75a6e6898))
- wallet screens, branded header layout and mobile-first main view ([1fe1453](https://github.com/tompro/sattle/commit/1fe1453745f3ab9132decb984242b586588c3178))
- webauthn prf passkey unlock engine as alternative wrap of the linking key ([7db3408](https://github.com/tompro/sattle/commit/7db34083e6345fb5acbf31722736d24fa0441815))
### Bug Fixes
* bind window.fetch at boot so lnurlcash-kit transport works in browsers ([1839700](https://github.com/tompro/sattle/commit/18397002150eca483ba1f00951715e30fbacd792))
* discover a mint's signing key from the mint-address endpoint, not the payRequest ([3926121](https://github.com/tompro/sattle/commit/39261212cf1b27626b2f33de045081a9adfc2592))
- bind window.fetch at boot so lnurlcash-kit transport works in browsers ([1839700](https://github.com/tompro/sattle/commit/18397002150eca483ba1f00951715e30fbacd792))
- discover a mint's signing key from the mint-address endpoint, not the payRequest ([3926121](https://github.com/tompro/sattle/commit/39261212cf1b27626b2f33de045081a9adfc2592))
## Changelog
public/.well-known/assetlinks.json
+1 -3
View File
@@ -4,9 +4,7 @@
"target": {
"namespace": "android_app",
"package_name": "eu.protom.sattle",
"sha256_cert_fingerprints": [
"REPLACE_WITH_RELEASE_KEYSTORE_SHA256_CERT_FINGERPRINT"
]
"sha256_cert_fingerprints": ["REPLACE_WITH_RELEASE_KEYSTORE_SHA256_CERT_FINGERPRINT"]
}
}
]
src-pwa/register-sw.ts
+2 -2
View File
@@ -1,4 +1,4 @@
import { register } from "register-service-worker";
import { register } from 'register-service-worker';
// The ready(), registered(), cached(), updatefound() and updated()
// events passes a ServiceWorkerRegistration instance in their arguments.
@@ -37,5 +37,5 @@ register(import.meta.env.QUASAR_SERVICE_WORKER_FILE, {
error(/* err */) {
// console.error('Error during service worker registration:', err)
}
},
});
src-pwa/sw/custom-sw.ts
+7 -13
View File
@@ -4,13 +4,13 @@
* quasar.config file > pwa > workboxMode is set to "InjectManifest"
*/
import { clientsClaim } from "workbox-core";
import { NavigationRoute, registerRoute } from "workbox-routing";
import { clientsClaim } from 'workbox-core';
import { NavigationRoute, registerRoute } from 'workbox-routing';
import {
cleanupOutdatedCaches,
createHandlerBoundToURL,
precacheAndRoute
} from "workbox-precaching";
precacheAndRoute,
} from 'workbox-precaching';
declare const self: ServiceWorkerGlobalScope & typeof globalThis;
@@ -26,14 +26,8 @@ if (import.meta.env.QUASAR_PROD) {
// Non-SSR/SSG fallbacks to index.html
// Production SSR/SSG fallbacks to offline.html (except for dev)
registerRoute(
new NavigationRoute(
createHandlerBoundToURL(import.meta.env.QUASAR_PWA_FALLBACK_HTML),
{
denylist: [
new RegExp(import.meta.env.QUASAR_PWA_SERVICE_WORKER_REGEX),
/workbox-(.)*\.js$/
]
}
)
new NavigationRoute(createHandlerBoundToURL(import.meta.env.QUASAR_PWA_FALLBACK_HTML), {
denylist: [new RegExp(import.meta.env.QUASAR_PWA_SERVICE_WORKER_REGEX), /workbox-(.)*\.js$/],
}),
);
}
src/capabilities/biometricUnlock.test.ts
+1 -5
View File
@@ -205,11 +205,7 @@ describe('biometric wallet material', () => {
])('returns no material for an authenticated %s and preserves state', async (_label, payload) => {
// Given an authenticated non-canonical payload bound to the saved owner
await saveWalletMaterial(MATERIAL);
await storePayload(
payload,
walletMaterialOwnerId(MATERIAL),
walletMaterialHash(MATERIAL),
);
await storePayload(payload, walletMaterialOwnerId(MATERIAL), walletMaterialHash(MATERIAL));
const before = persistedState();
// When biometric unlock decrypts the payload
src/capabilities/biometricUnlock.ts
+1 -3
View File
@@ -186,9 +186,7 @@ const authenticateOrThrow = async (reason: string): Promise<void> => {
}
};
export const enableBiometricUnlock = async (
material: WalletMaterialV2,
): Promise<void> => {
export const enableBiometricUnlock = async (material: WalletMaterialV2): Promise<void> => {
if (!isNative()) throw new Error('Biometric unlock is only available in the native app.');
const serialized = serializeWalletMaterial(material);
const canonicalMaterial = parseWalletMaterial(serialized);
src/components/QrScanner.vue
+4 -9
View File
@@ -19,19 +19,14 @@ onMounted(async () => {
return;
}
if (!videoEl.value) return;
scanner = new QrScanner(
videoEl.value,
(result) => emit('decode', result.data),
{ highlightScanRegion: true },
);
scanner = new QrScanner(videoEl.value, (result) => emit('decode', result.data), {
highlightScanRegion: true,
});
await scanner.start();
starting.value = false;
} catch (err) {
starting.value = false;
emit(
'error',
err instanceof Error ? err.message : 'Camera access failed.',
);
emit('error', err instanceof Error ? err.message : 'Camera access failed.');
}
});
src/components/receive/ReceiveDialog.vue
+4 -4
View File
@@ -50,9 +50,7 @@
</div>
<div class="col q-ml-md">
<div class="text-body1 text-weight-medium">Bearer note</div>
<div class="text-caption text-grey-5">
Paste or scan a note someone sent you
</div>
<div class="text-caption text-grey-5">Paste or scan a note someone sent you</div>
</div>
<q-icon name="chevron_right" color="grey-5" size="24px" />
</div>
@@ -108,7 +106,9 @@ const onReceived = () => {
border-radius: 12px;
padding: 14px 16px;
cursor: pointer;
transition: background-color 0.15s ease, border-color 0.15s ease;
transition:
background-color 0.15s ease,
border-color 0.15s ease;
}
.action-row:hover,
src/components/send/SendDialog.vue
+6 -1
View File
@@ -34,7 +34,12 @@ const onSent = () => emit('sent');
</script>
<template>
<q-dialog v-model="show" position="bottom" transition-show="slide-up" transition-hide="slide-down">
<q-dialog
v-model="show"
position="bottom"
transition-show="slide-up"
transition-hide="slide-down"
>
<q-card class="sattle-card drawer-card full-width">
<q-card-section class="row items-center q-pb-sm">
<q-btn v-close-popup flat round dense icon="close" color="primary" aria-label="Close" />
src/composables/useMoveFundsPage.ts
+1 -5
View File
@@ -207,11 +207,7 @@ export const useMoveFundsPage = () => {
toast('positive', `Moved ${sats.toLocaleString()} sats.`);
} else if (transfer.outcome === 'failed-funds-returned') {
if (transfer.rotatedNote) {
await wallet.restoreStagedMintSource(
stagedOutput.id,
transfer.rotatedNote,
ownerFence,
);
await wallet.restoreStagedMintSource(stagedOutput.id, transfer.rotatedNote, ownerFence);
}
await activity.log(
'transfer',
src/composables/usePayInvoiceDialog.ts
+1 -2
View File
@@ -166,8 +166,7 @@ export const usePayInvoiceDialog = (props: PayInvoiceProps, emit: PayInvoiceEmit
};
const allocateOutputSecrets = (server: string, count: number) =>
wallet.allocateOutputSecrets(server, count, fence);
const mintSignatureKeys = (server: string) =>
getTrustedMintVerificationKeys(server, ownerId);
const mintSignatureKeys = (server: string) => getTrustedMintVerificationKeys(server, ownerId);
// the pay-return recovery output: staged durably (allocated secret,
// zero value, pendingMint) and linked to the carved source BEFORE the
// classification rotate can burn it
src/composables/walletCarveCommit.test.ts
+1 -3
View File
@@ -165,9 +165,7 @@ describe('commitCarve', () => {
expect(wallet.bearers).toHaveLength(3);
expect(committed.verified).toBe(true);
expect(wallet.bearers.find((bearer) => bearer.id === input.id)?.spent).toBe(true);
expect(
wallet.bearers.filter((bearer) => bearer.url.includes('bb'.repeat(32))),
).toHaveLength(1);
expect(wallet.bearers.filter((bearer) => bearer.url.includes('bb'.repeat(32)))).toHaveLength(1);
const key = await deriveBearerAesKey(wallet.requireLinkingKey());
expect(await loadBearers(key)).toHaveLength(3);
});
src/lnurlcash/fees.ts
+26 -26
View File
@@ -23,29 +23,29 @@ import {
mintAddressUrl,
resolveMintInput,
serverOf,
} from 'lnurlcash-kit'
import type {LnurlcashOptions, MintFee} from 'lnurlcash-kit'
import {ceilMsatToSat, floorMsatToSat} from './units'
} from 'lnurlcash-kit';
import type { LnurlcashOptions, MintFee } from 'lnurlcash-kit';
import { ceilMsatToSat, floorMsatToSat } from './units';
export const netAfterMintFee = (grossMsat: number, fee: MintFee): number =>
applyMintFee(grossMsat, fee)
applyMintFee(grossMsat, fee);
export const grossForMintFee = (netMsat: number, fee: MintFee): number =>
ceilMsatToSat(grossUpForMintFee(netMsat, fee))
ceilMsatToSat(grossUpForMintFee(netMsat, fee));
export const maxNetForBalance = (balanceMsat: number, fee: MintFee | null): number =>
fee ? floorMsatToSat(applyMintFee(balanceMsat, fee)) : balanceMsat
fee ? floorMsatToSat(applyMintFee(balanceMsat, fee)) : balanceMsat;
// Fee quotes are per-mint and change rarely; cache briefly by server.
// nulls are cached too - an unreachable mint shouldn't be retried on
// every render either.
const QUOTE_TTL_MS = 60_000
const QUOTE_TIMEOUT_MS = 5_000
const QUOTE_TTL_MS = 60_000;
const QUOTE_TIMEOUT_MS = 5_000;
const quoteCache = new Map<string, {at: number; fee: MintFee | null}>()
const quoteCache = new Map<string, { at: number; fee: MintFee | null }>();
// tests can reset the cache between cases
export const clearMintFeeQuoteCache = (): void => quoteCache.clear()
export const clearMintFeeQuoteCache = (): void => quoteCache.clear();
// A pre-flight read of a mint's advertised receive fee WITHOUT requesting
// an invoice - the same resolution chain as prepareMint (mint-address
@@ -57,29 +57,29 @@ export const quoteMintFee = async (
mintInput: string,
options: LnurlcashOptions = {},
): Promise<MintFee | null> => {
const url = resolveMintInput(mintInput)
if (!url) return null
const server = serverOf(url)
const cached = quoteCache.get(server)
if (cached && Date.now() - cached.at < QUOTE_TTL_MS) return cached.fee
const url = resolveMintInput(mintInput);
if (!url) return null;
const server = serverOf(url);
const cached = quoteCache.get(server);
if (cached && Date.now() - cached.at < QUOTE_TTL_MS) return cached.fee;
const opts: LnurlcashOptions = {timeoutMs: QUOTE_TIMEOUT_MS, ...options}
let payUrl = url
const addressUrl = mintAddressUrl(url)
const opts: LnurlcashOptions = { timeoutMs: QUOTE_TIMEOUT_MS, ...options };
let payUrl = url;
const addressUrl = mintAddressUrl(url);
if (addressUrl) {
try {
payUrl = (await fetchMintAddress(addressUrl, opts)).payLink
payUrl = (await fetchMintAddress(addressUrl, opts)).payLink;
} catch (error) {
// no mint-address support - the plain payRequest guess still works
if (!(error instanceof Error)) throw error
if (!(error instanceof Error)) throw error;
}
}
let fee: MintFee | null
let fee: MintFee | null;
try {
fee = (await fetchPayRequest(payUrl, opts)).mintFee ?? null
fee = (await fetchPayRequest(payUrl, opts)).mintFee ?? null;
} catch {
fee = null
fee = null;
}
quoteCache.set(server, {at: Date.now(), fee})
return fee
}
quoteCache.set(server, { at: Date.now(), fee });
return fee;
};
src/lnurlcash/jsonParsing.ts
+12 -12
View File
@@ -1,20 +1,20 @@
export const isJsonObject = (value: unknown): value is Record<string, unknown> =>
typeof value === 'object' && value !== null && !Array.isArray(value)
typeof value === 'object' && value !== null && !Array.isArray(value);
export const parseJsonObject = (source: string): Record<string, unknown> => {
const parsed: unknown = JSON.parse(source)
if (!isJsonObject(parsed)) throw new TypeError('Expected a JSON object.')
return parsed
}
const parsed: unknown = JSON.parse(source);
if (!isJsonObject(parsed)) throw new TypeError('Expected a JSON object.');
return parsed;
};
export const parseJsonArray = (source: string): unknown[] => {
const parsed: unknown = JSON.parse(source)
if (!Array.isArray(parsed)) throw new TypeError('Expected a JSON array.')
return Array.from(parsed, (value: unknown) => value)
}
const parsed: unknown = JSON.parse(source);
if (!Array.isArray(parsed)) throw new TypeError('Expected a JSON array.');
return Array.from(parsed, (value: unknown) => value);
};
export const parseJsonObjectArray = (source: string): Array<Record<string, unknown>> =>
parseJsonArray(source).map((value) => {
if (!isJsonObject(value)) throw new TypeError('Expected a JSON object array.')
return value
})
if (!isJsonObject(value)) throw new TypeError('Expected a JSON object array.');
return value;
});
src/lnurlcash/keys.material-commitment.cases.ts
+90 -93
View File
@@ -1,6 +1,6 @@
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex, utf8ToBytes} from '@noble/hashes/utils.js'
import {beforeEach, describe, expect, it} from 'vitest'
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js';
import { beforeEach, describe, expect, it } from 'vitest';
import {
decryptSavedWalletMaterial,
@@ -16,103 +16,102 @@ import {
savedWalletMaterialOwnerId,
walletMaterialLinkingKey,
WalletMaterialProofMismatchError,
} from './keys'
import {walletMaterialOwnerId} from './storage/storedSecret'
import {parseJsonObject, stubLocalStorage} from './test-utils'
} from './keys';
import { walletMaterialOwnerId } from './storage/storedSecret';
import { parseJsonObject, stubLocalStorage } from './test-utils';
const MNEMONIC =
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
const OTHER_MNEMONIC =
'legal winner thank year wave sausage worth useful legal winner thank yellow'
const MATERIAL_STORAGE_KEY = 'sattle_wallet_material_v2'
const PASSWORD = 'correct horse battery staple'
'legal winner thank year wave sausage worth useful legal winner thank yellow';
const MATERIAL_STORAGE_KEY = 'sattle_wallet_material_v2';
const PASSWORD = 'correct horse battery staple';
const materialHash = (serialized: string): string =>
bytesToHex(sha256(utf8ToBytes(serialized)))
const materialHash = (serialized: string): string => bytesToHex(sha256(utf8ToBytes(serialized)));
const readRawMaterialRecord = (): Record<string, unknown> => {
const raw = localStorage.getItem(MATERIAL_STORAGE_KEY)
if (raw === null) throw new Error('expected a saved wallet-material record')
return parseJsonObject(raw)
}
const raw = localStorage.getItem(MATERIAL_STORAGE_KEY);
if (raw === null) throw new Error('expected a saved wallet-material record');
return parseJsonObject(raw);
};
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
describe('baseline: wallet material identity', () => {
it('derives identity only from the linking key when the cash root changes', () => {
const material = deriveWalletMaterial(MNEMONIC)
const other = deriveWalletMaterial(OTHER_MNEMONIC)
const alteredRoot = {...material, cashRootHex: other.cashRootHex}
const material = deriveWalletMaterial(MNEMONIC);
const other = deriveWalletMaterial(OTHER_MNEMONIC);
const alteredRoot = { ...material, cashRootHex: other.cashRootHex };
expect(walletMaterialOwnerId(alteredRoot)).toBe(walletMaterialOwnerId(material))
expect(serializeWalletMaterial(alteredRoot)).not.toBe(serializeWalletMaterial(material))
})
})
expect(walletMaterialOwnerId(alteredRoot)).toBe(walletMaterialOwnerId(material));
expect(serializeWalletMaterial(alteredRoot)).not.toBe(serializeWalletMaterial(material));
});
});
describe('saved wallet material commitment', () => {
it('stores the canonical material commitment on plaintext and encrypted saves', async () => {
const material = deriveWalletMaterial(MNEMONIC)
const expectedHash = materialHash(serializeWalletMaterial(material))
const material = deriveWalletMaterial(MNEMONIC);
const expectedHash = materialHash(serializeWalletMaterial(material));
await saveWalletMaterial(material)
const plaintext = readRawMaterialRecord()
await saveWalletMaterial(material, PASSWORD)
const encrypted = readRawMaterialRecord()
await saveWalletMaterial(material);
const plaintext = readRawMaterialRecord();
await saveWalletMaterial(material, PASSWORD);
const encrypted = readRawMaterialRecord();
expect(plaintext.materialHash).toBe(expectedHash)
expect(encrypted.materialHash).toBe(expectedHash)
})
expect(plaintext.materialHash).toBe(expectedHash);
expect(encrypted.materialHash).toBe(expectedHash);
});
it('rejects authenticated encrypted material when its commitment differs', async () => {
const material = deriveWalletMaterial(MNEMONIC)
await saveWalletMaterial(material, PASSWORD)
const material = deriveWalletMaterial(MNEMONIC);
await saveWalletMaterial(material, PASSWORD);
localStorage.setItem(
MATERIAL_STORAGE_KEY,
JSON.stringify({...readRawMaterialRecord(), materialHash: '00'.repeat(32)}),
)
JSON.stringify({ ...readRawMaterialRecord(), materialHash: '00'.repeat(32) }),
);
await expect(decryptSavedWalletMaterial(PASSWORD)).rejects.toBeInstanceOf(
WalletMaterialProofMismatchError,
)
})
);
});
it('rejects plaintext material when its commitment differs', async () => {
const material = deriveWalletMaterial(MNEMONIC)
await saveWalletMaterial(material)
const before = JSON.stringify({...readRawMaterialRecord(), materialHash: '00'.repeat(32)})
localStorage.setItem(MATERIAL_STORAGE_KEY, before)
const material = deriveWalletMaterial(MNEMONIC);
await saveWalletMaterial(material);
const before = JSON.stringify({ ...readRawMaterialRecord(), materialHash: '00'.repeat(32) });
localStorage.setItem(MATERIAL_STORAGE_KEY, before);
expect(getPlainWalletMaterial()).toBeNull()
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).toBe(before)
})
expect(getPlainWalletMaterial()).toBeNull();
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).toBe(before);
});
it('refuses to stamp same-owner material with an altered cash root', async () => {
const material = deriveWalletMaterial(MNEMONIC)
const other = deriveWalletMaterial(OTHER_MNEMONIC)
await saveWalletMaterial(material, PASSWORD)
const material = deriveWalletMaterial(MNEMONIC);
const other = deriveWalletMaterial(OTHER_MNEMONIC);
await saveWalletMaterial(material, PASSWORD);
expect(() =>
ensureSavedWalletMaterialOwner({...material, cashRootHex: other.cashRootHex}),
).toThrow(WalletMaterialProofMismatchError)
})
ensureSavedWalletMaterialOwner({ ...material, cashRootHex: other.cashRootHex }),
).toThrow(WalletMaterialProofMismatchError);
});
it('requires exactly one lowercase 64-hex commitment at the storage boundary', () => {
const material = deriveWalletMaterial(MNEMONIC)
const serialized = serializeWalletMaterial(material)
const material = deriveWalletMaterial(MNEMONIC);
const serialized = serializeWalletMaterial(material);
const record = {
enc: false,
value: serialized,
materialHash: materialHash(serialized),
ownerId: walletMaterialOwnerId(material),
version: 2,
}
};
expect(isValidStoredWalletMaterial(record)).toBe(true)
expect(isValidStoredWalletMaterial({...record, materialHash: record.materialHash.toUpperCase()})).toBe(
false,
)
expect(isValidStoredWalletMaterial(record)).toBe(true);
expect(
isValidStoredWalletMaterial({ ...record, materialHash: record.materialHash.toUpperCase() }),
).toBe(false);
expect(
isValidStoredWalletMaterial({
enc: record.enc,
@@ -120,13 +119,13 @@ describe('saved wallet material commitment', () => {
ownerId: record.ownerId,
version: record.version,
}),
).toBe(false)
})
).toBe(false);
});
it('rejects malformed authenticated material after its correct commitment matches', async () => {
const material = deriveWalletMaterial(MNEMONIC)
const malformed = JSON.stringify({...material, cashRootHex: '00'.repeat(64)})
const parts = await encryptSecretParts(malformed, PASSWORD)
const material = deriveWalletMaterial(MNEMONIC);
const malformed = JSON.stringify({ ...material, cashRootHex: '00'.repeat(64) });
const parts = await encryptSecretParts(malformed, PASSWORD);
localStorage.setItem(
MATERIAL_STORAGE_KEY,
JSON.stringify({
@@ -136,16 +135,14 @@ describe('saved wallet material commitment', () => {
ownerId: linkingPubKeyHex(walletMaterialLinkingKey(material)),
version: 2,
}),
)
);
await expect(decryptSavedWalletMaterial(PASSWORD)).rejects.toThrow(
'valid v2 wallet material',
)
})
await expect(decryptSavedWalletMaterial(PASSWORD)).rejects.toThrow('valid v2 wallet material');
});
it('preserves a verified restored commitment while discarding its owner claim', () => {
const material = deriveWalletMaterial(MNEMONIC)
const serialized = serializeWalletMaterial(material)
const material = deriveWalletMaterial(MNEMONIC);
const serialized = serializeWalletMaterial(material);
restoreWalletMaterialStored({
enc: false,
@@ -153,50 +150,50 @@ describe('saved wallet material commitment', () => {
materialHash: materialHash(serialized),
ownerId: linkingPubKeyHex(new Uint8Array(32).fill(9)),
version: 2,
})
});
expect(readRawMaterialRecord()).toEqual({
enc: false,
value: serialized,
materialHash: materialHash(serialized),
})
expect(getPlainWalletMaterial()).toEqual(material)
})
});
expect(getPlainWalletMaterial()).toEqual(material);
});
it('proves an encrypted restored commitment before owner stamping', async () => {
const material = deriveWalletMaterial(MNEMONIC)
const serialized = serializeWalletMaterial(material)
const parts = await encryptSecretParts(serialized, PASSWORD)
const material = deriveWalletMaterial(MNEMONIC);
const serialized = serializeWalletMaterial(material);
const parts = await encryptSecretParts(serialized, PASSWORD);
restoreWalletMaterialStored({
enc: true,
...parts,
materialHash: materialHash(serialized),
ownerId: linkingPubKeyHex(new Uint8Array(32).fill(9)),
version: 2,
})
});
expect(savedWalletMaterialOwnerId()).toBeNull()
const proven = await decryptSavedWalletMaterial(PASSWORD)
ensureSavedWalletMaterialOwner(proven)
expect(savedWalletMaterialOwnerId()).toBeNull();
const proven = await decryptSavedWalletMaterial(PASSWORD);
ensureSavedWalletMaterialOwner(proven);
expect(savedWalletMaterialOwnerId()).toBe(walletMaterialOwnerId(material))
})
expect(savedWalletMaterialOwnerId()).toBe(walletMaterialOwnerId(material));
});
it('rejects an unproven restored hash that contradicts encrypted material', async () => {
const material = deriveWalletMaterial(MNEMONIC)
const serialized = serializeWalletMaterial(material)
const parts = await encryptSecretParts(serialized, PASSWORD)
const material = deriveWalletMaterial(MNEMONIC);
const serialized = serializeWalletMaterial(material);
const parts = await encryptSecretParts(serialized, PASSWORD);
restoreWalletMaterialStored({
enc: true,
...parts,
materialHash: '00'.repeat(32),
ownerId: walletMaterialOwnerId(material),
version: 2,
})
});
await expect(decryptSavedWalletMaterial(PASSWORD)).rejects.toBeInstanceOf(
WalletMaterialProofMismatchError,
)
expect(savedWalletMaterialOwnerId()).toBeNull()
})
})
);
expect(savedWalletMaterialOwnerId()).toBeNull();
});
});
src/lnurlcash/keys.material-storage.cases.ts
+91 -89
View File
@@ -1,6 +1,6 @@
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex, utf8ToBytes} from '@noble/hashes/utils.js'
import {describe, expect, it} from 'vitest'
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js';
import { describe, expect, it } from 'vitest';
import {
decryptSavedWalletMaterial,
@@ -17,77 +17,79 @@ import {
saveWalletMaterial,
serializeWalletMaterial,
walletMaterialLinkingKey,
} from './keys'
import {parseJsonObject, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, stubLocalStorage } from './test-utils';
const FIXED_MNEMONIC =
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
const PASSWORD = 'correct horse battery staple'
const MATERIAL_STORAGE_KEY = 'sattle_wallet_material_v2'
const LEGACY_STORAGE_KEY = 'sattle_linking_key'
const LINKING_KEY_HEX = 'da2a752d3d28668288ff50bed644e4a95f726d8711fd8754060f0a9e378f84aa'
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
const PASSWORD = 'correct horse battery staple';
const MATERIAL_STORAGE_KEY = 'sattle_wallet_material_v2';
const LEGACY_STORAGE_KEY = 'sattle_linking_key';
const LINKING_KEY_HEX = 'da2a752d3d28668288ff50bed644e4a95f726d8711fd8754060f0a9e378f84aa';
const CASH_ROOT_HEX =
'c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60'
'c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60';
const materialHash = (serialized: string): string =>
bytesToHex(sha256(utf8ToBytes(serialized)))
const materialHash = (serialized: string): string => bytesToHex(sha256(utf8ToBytes(serialized)));
const readRawMaterialRecord = (): Record<string, unknown> => {
const raw = localStorage.getItem(MATERIAL_STORAGE_KEY)
if (raw === null) throw new Error('expected a saved wallet-material record')
return parseJsonObject(raw)
}
const raw = localStorage.getItem(MATERIAL_STORAGE_KEY);
if (raw === null) throw new Error('expected a saved wallet-material record');
return parseJsonObject(raw);
};
describe('WalletMaterialV2 persistence', () => {
it('round-trips canonical plaintext material in the new namespace', async () => {
// Given complete wallet material and an unrelated legacy record
stubLocalStorage()
localStorage.setItem(LEGACY_STORAGE_KEY, JSON.stringify({enc: false, value: '07'.repeat(32)}))
const material = deriveWalletMaterial(FIXED_MNEMONIC)
stubLocalStorage();
localStorage.setItem(
LEGACY_STORAGE_KEY,
JSON.stringify({ enc: false, value: '07'.repeat(32) }),
);
const material = deriveWalletMaterial(FIXED_MNEMONIC);
// When the material is saved without a password
await saveWalletMaterial(material)
await saveWalletMaterial(material);
// Then only the new namespace carries the exact complete material
expect(savedWalletMaterialExists()).toBe(true)
expect(savedWalletMaterialIsEncrypted()).toBe(false)
expect(getPlainWalletMaterial()).toEqual(material)
expect(savedWalletMaterialExists()).toBe(true);
expect(savedWalletMaterialIsEncrypted()).toBe(false);
expect(getPlainWalletMaterial()).toEqual(material);
expect(readRawMaterialRecord()).toEqual({
enc: false,
value: serializeWalletMaterial(material),
materialHash: materialHash(serializeWalletMaterial(material)),
ownerId: linkingPubKeyHex(walletMaterialLinkingKey(material)),
version: 2,
})
expect(localStorage.getItem(LEGACY_STORAGE_KEY)).not.toBeNull()
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).not.toContain(FIXED_MNEMONIC)
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).not.toContain('"seed"')
})
});
expect(localStorage.getItem(LEGACY_STORAGE_KEY)).not.toBeNull();
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).not.toContain(FIXED_MNEMONIC);
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).not.toContain('"seed"');
});
it('round-trips canonical password-encrypted material without plaintext fields', async () => {
// Given complete wallet material
stubLocalStorage()
const material = deriveWalletMaterial(FIXED_MNEMONIC)
stubLocalStorage();
const material = deriveWalletMaterial(FIXED_MNEMONIC);
// When the material is password protected
await saveWalletMaterial(material, PASSWORD)
await saveWalletMaterial(material, PASSWORD);
// Then only authenticated decryption returns both parts
expect(savedWalletMaterialIsEncrypted()).toBe(true)
expect(getPlainWalletMaterial()).toBeNull()
expect(await decryptSavedWalletMaterial(PASSWORD)).toEqual(material)
await expect(decryptSavedWalletMaterial('wrong password')).rejects.toThrow()
const raw = JSON.stringify(readRawMaterialRecord())
expect(raw).not.toContain(LINKING_KEY_HEX)
expect(raw).not.toContain(CASH_ROOT_HEX)
expect(raw).not.toContain(FIXED_MNEMONIC)
})
expect(savedWalletMaterialIsEncrypted()).toBe(true);
expect(getPlainWalletMaterial()).toBeNull();
expect(await decryptSavedWalletMaterial(PASSWORD)).toEqual(material);
await expect(decryptSavedWalletMaterial('wrong password')).rejects.toThrow();
const raw = JSON.stringify(readRawMaterialRecord());
expect(raw).not.toContain(LINKING_KEY_HEX);
expect(raw).not.toContain(CASH_ROOT_HEX);
expect(raw).not.toContain(FIXED_MNEMONIC);
});
it('strips restored owner claims until the material proves its real owner', () => {
// Given plaintext material carrying a foreign owner claim
stubLocalStorage()
const material = deriveWalletMaterial(FIXED_MNEMONIC)
const foreignOwner = linkingPubKeyHex(new Uint8Array(32).fill(9))
stubLocalStorage();
const material = deriveWalletMaterial(FIXED_MNEMONIC);
const foreignOwner = linkingPubKeyHex(new Uint8Array(32).fill(9));
// When the record is restored and subsequently proven by plaintext unlock
restoreWalletMaterialStored({
@@ -96,25 +98,25 @@ describe('WalletMaterialV2 persistence', () => {
materialHash: materialHash(serializeWalletMaterial(material)),
ownerId: foreignOwner,
version: 2,
})
const beforeProof = readRawMaterialRecord()
const unlocked = getPlainWalletMaterial()
if (unlocked === null) throw new Error('expected restored plaintext material')
ensureSavedWalletMaterialOwner(unlocked)
});
const beforeProof = readRawMaterialRecord();
const unlocked = getPlainWalletMaterial();
if (unlocked === null) throw new Error('expected restored plaintext material');
ensureSavedWalletMaterialOwner(unlocked);
// Then the claim was absent before proof and only the derived owner was stamped
expect(beforeProof).toEqual({
enc: false,
value: serializeWalletMaterial(material),
materialHash: materialHash(serializeWalletMaterial(material)),
})
expect(savedWalletMaterialOwnerId()).toBe(linkingPubKeyHex(walletMaterialLinkingKey(material)))
})
});
expect(savedWalletMaterialOwnerId()).toBe(linkingPubKeyHex(walletMaterialLinkingKey(material)));
});
it('rejects a plaintext owner mismatch without returning or stamping material', () => {
// Given canonical material stamped with a foreign current owner
stubLocalStorage()
const material = deriveWalletMaterial(FIXED_MNEMONIC)
stubLocalStorage();
const material = deriveWalletMaterial(FIXED_MNEMONIC);
localStorage.setItem(
MATERIAL_STORAGE_KEY,
JSON.stringify({
@@ -124,72 +126,72 @@ describe('WalletMaterialV2 persistence', () => {
ownerId: linkingPubKeyHex(new Uint8Array(32).fill(9)),
version: 2,
}),
)
const before = localStorage.getItem(MATERIAL_STORAGE_KEY)
);
const before = localStorage.getItem(MATERIAL_STORAGE_KEY);
// When it is read or offered for proof
const unlocked = getPlainWalletMaterial()
const stamp = () => ensureSavedWalletMaterialOwner(material)
const unlocked = getPlainWalletMaterial();
const stamp = () => ensureSavedWalletMaterialOwner(material);
// Then neither operation trusts or rewrites the foreign record
expect(unlocked).toBeNull()
expect(stamp).toThrow('different wallet')
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).toBe(before)
})
expect(unlocked).toBeNull();
expect(stamp).toThrow('different wallet');
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).toBe(before);
});
it('rejects an encrypted owner mismatch after authentication', async () => {
// Given valid encrypted material whose owner marker was replaced
stubLocalStorage()
const material = deriveWalletMaterial(FIXED_MNEMONIC)
await saveWalletMaterial(material, PASSWORD)
stubLocalStorage();
const material = deriveWalletMaterial(FIXED_MNEMONIC);
await saveWalletMaterial(material, PASSWORD);
const foreign = {
...readRawMaterialRecord(),
ownerId: linkingPubKeyHex(new Uint8Array(32).fill(9)),
}
localStorage.setItem(MATERIAL_STORAGE_KEY, JSON.stringify(foreign))
const before = localStorage.getItem(MATERIAL_STORAGE_KEY)
};
localStorage.setItem(MATERIAL_STORAGE_KEY, JSON.stringify(foreign));
const before = localStorage.getItem(MATERIAL_STORAGE_KEY);
// When the authenticated material contradicts the current owner marker
const unlock = decryptSavedWalletMaterial(PASSWORD)
const unlock = decryptSavedWalletMaterial(PASSWORD);
// Then no material is returned or marker changed
await expect(unlock).rejects.toThrow('different wallet')
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).toBe(before)
})
await expect(unlock).rejects.toThrow('different wallet');
expect(localStorage.getItem(MATERIAL_STORAGE_KEY)).toBe(before);
});
it.each([
['legacy key-only plaintext', LINKING_KEY_HEX, 2],
['wrong outer version', serializeWalletMaterial(deriveWalletMaterial(FIXED_MNEMONIC)), 1],
[
'malformed material plaintext',
JSON.stringify({version: 2, linkingKeyHex: LINKING_KEY_HEX, cashRootHex: '00'}),
JSON.stringify({ version: 2, linkingKeyHex: LINKING_KEY_HEX, cashRootHex: '00' }),
2,
],
])('rejects %s records at the storage boundary', (_name, value, version) => {
// Given an invalid record under the v2 material namespace
stubLocalStorage()
const material = deriveWalletMaterial(FIXED_MNEMONIC)
stubLocalStorage();
const material = deriveWalletMaterial(FIXED_MNEMONIC);
const record = {
enc: false,
value,
materialHash: materialHash(value),
ownerId: linkingPubKeyHex(walletMaterialLinkingKey(material)),
version,
}
localStorage.setItem(MATERIAL_STORAGE_KEY, JSON.stringify(record))
};
localStorage.setItem(MATERIAL_STORAGE_KEY, JSON.stringify(record));
// When storage helpers parse it
// Then the record is unusable as wallet material
expect(isValidStoredWalletMaterial(record)).toBe(false)
expect(savedWalletMaterialExists()).toBe(false)
expect(getPlainWalletMaterial()).toBeNull()
})
expect(isValidStoredWalletMaterial(record)).toBe(false);
expect(savedWalletMaterialExists()).toBe(false);
expect(getPlainWalletMaterial()).toBeNull();
});
it('rejects authenticated ciphertext containing malformed material', async () => {
// Given valid AES-GCM parts whose plaintext is not a v2 material envelope
stubLocalStorage()
const parts = await encryptSecretParts(LINKING_KEY_HEX, PASSWORD)
const material = deriveWalletMaterial(FIXED_MNEMONIC)
stubLocalStorage();
const parts = await encryptSecretParts(LINKING_KEY_HEX, PASSWORD);
const material = deriveWalletMaterial(FIXED_MNEMONIC);
localStorage.setItem(
MATERIAL_STORAGE_KEY,
JSON.stringify({
@@ -199,12 +201,12 @@ describe('WalletMaterialV2 persistence', () => {
ownerId: linkingPubKeyHex(walletMaterialLinkingKey(material)),
version: 2,
}),
)
);
// When the password successfully authenticates the malformed plaintext
const unlock = decryptSavedWalletMaterial(PASSWORD)
const unlock = decryptSavedWalletMaterial(PASSWORD);
// Then it still fails closed as invalid material
await expect(unlock).rejects.toThrow('valid v2 wallet material')
})
})
await expect(unlock).rejects.toThrow('valid v2 wallet material');
});
});
src/lnurlcash/keys.material.cases.ts
+39 -42
View File
@@ -1,7 +1,7 @@
import {describe, expect, it} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import {getPublicKey} from 'nostr-tools/pure'
import {cashNodeToHex} from 'lnurlcash-kit'
import { describe, expect, it } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import { getPublicKey } from 'nostr-tools/pure';
import { cashNodeToHex } from 'lnurlcash-kit';
import {
deriveBearerAesKey,
@@ -12,89 +12,86 @@ import {
serializeWalletMaterial,
walletMaterialCashRoot,
walletMaterialLinkingKey,
} from './keys'
import {backupPubkey, deriveBackupKey} from './nostrBackup'
import {deriveNwcWalletKey, nwcWalletPubkey} from './nwc'
} from './keys';
import { backupPubkey, deriveBackupKey } from './nostrBackup';
import { deriveNwcWalletKey, nwcWalletPubkey } from './nwc';
const FIXED_MNEMONIC =
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
const CLIENT_PUBKEY = getPublicKey(new Uint8Array(32).fill(17))
const LINKING_KEY_HEX = 'da2a752d3d28668288ff50bed644e4a95f726d8711fd8754060f0a9e378f84aa'
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
const CLIENT_PUBKEY = getPublicKey(new Uint8Array(32).fill(17));
const LINKING_KEY_HEX = 'da2a752d3d28668288ff50bed644e4a95f726d8711fd8754060f0a9e378f84aa';
const CASH_ROOT_HEX =
'c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60'
'c7a2496e9b453a67c5d2a1f04936ec1259440d45454c795a99a66269e4cd3005111e1cc966fca2fe32f054f14caceab90449e536d94cf6935ea12a087e414f60';
describe('fixed mnemonic identity characterization', () => {
it('pins every public linking-key-derived identity and bearer encryption behavior', async () => {
// Given a mnemonic accepted by the existing wallet derivation
const linkingKey = deriveWalletLinkingKey(FIXED_MNEMONIC)
const bearerKey = await deriveBearerAesKey(linkingKey)
const linkingKey = deriveWalletLinkingKey(FIXED_MNEMONIC);
const bearerKey = await deriveBearerAesKey(linkingKey);
// When its owner, bearer, Nostr, and NWC observables are derived
const bearerCiphertext = new Uint8Array(
await crypto.subtle.encrypt(
{name: 'AES-GCM', iv: new Uint8Array(12)},
{ name: 'AES-GCM', iv: new Uint8Array(12) },
bearerKey,
new TextEncoder().encode('sattle-vector-v1'),
),
)
);
// Then they match the pre-v2 wallet's independently captured vectors
expect(linkingPubKeyHex(linkingKey)).toBe(
'0249f93654b6db2c0c4194c2fbc5eb54ff36f055e82bb867321a4c7ec7f7c31481',
)
);
expect(bytesToHex(bearerCiphertext)).toBe(
'4caf30a7c3fdb53ad3edefb34f202a67a2e969f267db3a5842ee6cfd23032e78',
)
);
expect(backupPubkey(deriveBackupKey(linkingKey))).toBe(
'6b6dc0633162e1985316d06edb85a99cc31f89b9c42d350ffdcf57853b875577',
)
);
expect(nwcWalletPubkey(deriveNwcWalletKey(linkingKey, CLIENT_PUBKEY))).toBe(
'3aa81f13d0dbccba0df5772abccda43c9a51c1dc99ea9a76090cada33b9fc587',
)
})
})
);
});
});
describe('WalletMaterialV2 derivation and serialization', () => {
it('derives the unchanged linking key and kit cash root from one mnemonic', () => {
// Given the fixed recovery mnemonic
// When its complete wallet material is derived
const material = deriveWalletMaterial(FIXED_MNEMONIC)
const material = deriveWalletMaterial(FIXED_MNEMONIC);
// Then both independently captured vectors and the exact schema are stable
expect(material).toEqual({
version: 2,
linkingKeyHex: LINKING_KEY_HEX,
cashRootHex: CASH_ROOT_HEX,
})
expect(Object.keys(material)).toEqual(['version', 'linkingKeyHex', 'cashRootHex'])
expect(walletMaterialLinkingKey(material)).toEqual(deriveWalletLinkingKey(FIXED_MNEMONIC))
expect(cashNodeToHex(walletMaterialCashRoot(material))).toBe(CASH_ROOT_HEX)
})
});
expect(Object.keys(material)).toEqual(['version', 'linkingKeyHex', 'cashRootHex']);
expect(walletMaterialLinkingKey(material)).toEqual(deriveWalletLinkingKey(FIXED_MNEMONIC));
expect(cashNodeToHex(walletMaterialCashRoot(material))).toBe(CASH_ROOT_HEX);
});
it('round-trips only the canonical exact serialization', () => {
// Given valid v2 material
const material = deriveWalletMaterial(FIXED_MNEMONIC)
const material = deriveWalletMaterial(FIXED_MNEMONIC);
// When it crosses the serialization boundary
const serialized = serializeWalletMaterial(material)
const serialized = serializeWalletMaterial(material);
// Then its bytes and parsed value are canonical
expect(serialized).toBe(
`{"version":2,"linkingKeyHex":"${LINKING_KEY_HEX}","cashRootHex":"${CASH_ROOT_HEX}"}`,
)
expect(parseWalletMaterial(serialized)).toEqual(material)
})
);
expect(parseWalletMaterial(serialized)).toEqual(material);
});
it.each([
['legacy key only', LINKING_KEY_HEX],
[
'wrong version',
JSON.stringify({version: 1, linkingKeyHex: LINKING_KEY_HEX, cashRootHex: CASH_ROOT_HEX}),
],
[
'missing field',
JSON.stringify({version: 2, linkingKeyHex: LINKING_KEY_HEX}),
JSON.stringify({ version: 1, linkingKeyHex: LINKING_KEY_HEX, cashRootHex: CASH_ROOT_HEX }),
],
['missing field', JSON.stringify({ version: 2, linkingKeyHex: LINKING_KEY_HEX })],
[
'extra field',
JSON.stringify({
@@ -146,14 +143,14 @@ describe('WalletMaterialV2 derivation and serialization', () => {
],
[
'non-canonical field order',
JSON.stringify({cashRootHex: CASH_ROOT_HEX, linkingKeyHex: LINKING_KEY_HEX, version: 2}),
JSON.stringify({ cashRootHex: CASH_ROOT_HEX, linkingKeyHex: LINKING_KEY_HEX, version: 2 }),
],
])('rejects %s', (_name, serialized) => {
// Given malformed or non-canonical serialized material
// When it crosses the parser
const parsed = parseWalletMaterial(serialized)
const parsed = parseWalletMaterial(serialized);
// Then no trusted material is returned
expect(parsed).toBeNull()
})
})
expect(parsed).toBeNull();
});
});
src/lnurlcash/keys.test.ts
+166 -166
View File
@@ -5,8 +5,8 @@
// field that binds the saved key to its one proven wallet identity.
// Node env: in-memory localStorage stub, native WebCrypto.
import {beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import {
decryptSavedLinkingKey,
@@ -20,153 +20,153 @@ import {
savedKeyOwnerMatches,
savedKeyOwnerId,
saveLinkingKey,
} from './keys'
import {isWalletOwnerId} from './storage/walletOwner'
import {parseJsonObject, stubLocalStorage} from './test-utils'
} from './keys';
import { isWalletOwnerId } from './storage/walletOwner';
import { parseJsonObject, stubLocalStorage } from './test-utils';
import './keys.version.cases'
import './keys.version.cases';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_KEY = new Uint8Array(32).fill(9)
const PASSWORD = 'hunter2'
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_KEY = new Uint8Array(32).fill(9);
const PASSWORD = 'hunter2';
const STORAGE_KEY = 'sattle_linking_key'
const STORAGE_KEY = 'sattle_linking_key';
const readRawRecord = (): Record<string, unknown> => {
const raw = localStorage.getItem(STORAGE_KEY)
if (raw === null) throw new Error('expected a saved linking-key record')
return parseJsonObject(raw)
}
const raw = localStorage.getItem(STORAGE_KEY);
if (raw === null) throw new Error('expected a saved linking-key record');
return parseJsonObject(raw);
};
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
// hand-written records in the pre-owner-marker shape - what every wallet
// created before this change has on disk
const saveLegacyPlaintext = (key: Uint8Array): void => {
localStorage.setItem(STORAGE_KEY, JSON.stringify({enc: false, value: bytesToHex(key)}))
}
localStorage.setItem(STORAGE_KEY, JSON.stringify({ enc: false, value: bytesToHex(key) }));
};
const saveLegacyEncrypted = async (
key: Uint8Array,
password: string,
): Promise<Record<string, unknown>> => {
const parts = await encryptSecretParts(bytesToHex(key), password)
const record: Record<string, unknown> = {enc: true, ...parts}
localStorage.setItem(STORAGE_KEY, JSON.stringify(record))
return record
}
const parts = await encryptSecretParts(bytesToHex(key), password);
const record: Record<string, unknown> = { enc: true, ...parts };
localStorage.setItem(STORAGE_KEY, JSON.stringify(record));
return record;
};
describe('baseline: saved-key record behavior', () => {
it('saves a plaintext key and reads it back', async () => {
await saveLinkingKey(LINKING_KEY)
await saveLinkingKey(LINKING_KEY);
expect(savedKeyExists()).toBe(true)
expect(savedKeyIsEncrypted()).toBe(false)
expect(readRawRecord()).toMatchObject({enc: false, value: bytesToHex(LINKING_KEY)})
expect(getPlainLinkingKey()).toEqual(LINKING_KEY)
})
expect(savedKeyExists()).toBe(true);
expect(savedKeyIsEncrypted()).toBe(false);
expect(readRawRecord()).toMatchObject({ enc: false, value: bytesToHex(LINKING_KEY) });
expect(getPlainLinkingKey()).toEqual(LINKING_KEY);
});
it('saves a password-encrypted key and decrypts it with the password', async () => {
await saveLinkingKey(LINKING_KEY, PASSWORD)
await saveLinkingKey(LINKING_KEY, PASSWORD);
expect(savedKeyIsEncrypted()).toBe(true)
const record = readRawRecord()
expect(record.enc).toBe(true)
expect(record.value).toBeUndefined()
expect(savedKeyIsEncrypted()).toBe(true);
const record = readRawRecord();
expect(record.enc).toBe(true);
expect(record.value).toBeUndefined();
// an encrypted record never reads through the plaintext path
expect(getPlainLinkingKey()).toBeNull()
expect(await decryptSavedLinkingKey(PASSWORD)).toEqual(LINKING_KEY)
})
expect(getPlainLinkingKey()).toBeNull();
expect(await decryptSavedLinkingKey(PASSWORD)).toEqual(LINKING_KEY);
});
it('rejects the wrong password via the GCM auth tag', async () => {
await saveLinkingKey(LINKING_KEY, PASSWORD)
await expect(decryptSavedLinkingKey('wrong password')).rejects.toThrow()
})
await saveLinkingKey(LINKING_KEY, PASSWORD);
await expect(decryptSavedLinkingKey('wrong password')).rejects.toThrow();
});
it('throws when asked to decrypt a plaintext record', async () => {
await saveLinkingKey(LINKING_KEY)
await saveLinkingKey(LINKING_KEY);
await expect(decryptSavedLinkingKey(PASSWORD)).rejects.toThrow(
'No encrypted linking key saved.',
)
})
);
});
it('restores an ownerless record verbatim and reads it back', async () => {
const parts = await encryptSecretParts(bytesToHex(LINKING_KEY), PASSWORD)
const record = {enc: true as const, ...parts}
restoreLinkingKeyStored(record)
const parts = await encryptSecretParts(bytesToHex(LINKING_KEY), PASSWORD);
const record = { enc: true as const, ...parts };
restoreLinkingKeyStored(record);
expect(readRawRecord()).toEqual(record)
expect(savedKeyIsEncrypted()).toBe(true)
expect(await decryptSavedLinkingKey(PASSWORD)).toEqual(LINKING_KEY)
})
expect(readRawRecord()).toEqual(record);
expect(savedKeyIsEncrypted()).toBe(true);
expect(await decryptSavedLinkingKey(PASSWORD)).toEqual(LINKING_KEY);
});
it('drops a malformed stored record instead of trusting it', () => {
localStorage.setItem(
STORAGE_KEY,
JSON.stringify({enc: true, salt: 'zz', iv: '00', ciphertext: ''}),
)
expect(savedKeyExists()).toBe(false)
localStorage.setItem(STORAGE_KEY, 'not json')
expect(savedKeyExists()).toBe(false)
expect(getPlainLinkingKey()).toBeNull()
})
})
JSON.stringify({ enc: true, salt: 'zz', iv: '00', ciphertext: '' }),
);
expect(savedKeyExists()).toBe(false);
localStorage.setItem(STORAGE_KEY, 'not json');
expect(savedKeyExists()).toBe(false);
expect(getPlainLinkingKey()).toBeNull();
});
});
describe('owner marker on new writes', () => {
it('matches the canonical owner derived from the saved linking key', async () => {
// Given a newly saved owner-bearing key
await saveLinkingKey(LINKING_KEY)
await saveLinkingKey(LINKING_KEY);
// When its freshly derived linking key is compared
const matches = savedKeyOwnerMatches(LINKING_KEY)
const matches = savedKeyOwnerMatches(LINKING_KEY);
// Then the saved owner matches
expect(matches).toBe(true)
})
expect(matches).toBe(true);
});
it('does not match a different linking key', async () => {
// Given a key owned by this wallet
await saveLinkingKey(LINKING_KEY)
await saveLinkingKey(LINKING_KEY);
// When a foreign freshly derived linking key is compared
const matches = savedKeyOwnerMatches(OTHER_KEY)
const matches = savedKeyOwnerMatches(OTHER_KEY);
// Then the foreign key is rejected
expect(matches).toBe(false)
})
expect(matches).toBe(false);
});
it('stamps the same canonical owner on plaintext and encrypted saves', async () => {
await saveLinkingKey(LINKING_KEY)
const plainOwner = savedKeyOwnerId()
expect(plainOwner).toBe(linkingPubKeyHex(LINKING_KEY))
await saveLinkingKey(LINKING_KEY);
const plainOwner = savedKeyOwnerId();
expect(plainOwner).toBe(linkingPubKeyHex(LINKING_KEY));
await saveLinkingKey(LINKING_KEY, PASSWORD)
expect(savedKeyOwnerId()).toBe(plainOwner)
expect(savedKeyOwnerId()).toBe(linkingPubKeyHex(LINKING_KEY))
})
await saveLinkingKey(LINKING_KEY, PASSWORD);
expect(savedKeyOwnerId()).toBe(plainOwner);
expect(savedKeyOwnerId()).toBe(linkingPubKeyHex(LINKING_KEY));
});
it('derives the owner as the lowercase 66-char compressed pubkey hex', async () => {
await saveLinkingKey(LINKING_KEY)
expect(savedKeyOwnerId()).toMatch(/^0[23][0-9a-f]{64}$/)
})
})
await saveLinkingKey(LINKING_KEY);
expect(savedKeyOwnerId()).toMatch(/^0[23][0-9a-f]{64}$/);
});
});
describe('owner marker on legacy records', () => {
it('reads a legacy record without ownerId as ownerless', async () => {
saveLegacyPlaintext(LINKING_KEY)
expect(savedKeyOwnerId()).toBeNull()
saveLegacyPlaintext(LINKING_KEY);
expect(savedKeyOwnerId()).toBeNull();
// the record itself stays a fully valid saved key
expect(getPlainLinkingKey()).toEqual(LINKING_KEY)
expect(getPlainLinkingKey()).toEqual(LINKING_KEY);
await saveLegacyEncrypted(LINKING_KEY, PASSWORD)
expect(savedKeyOwnerId()).toBeNull()
expect(await decryptSavedLinkingKey(PASSWORD)).toEqual(LINKING_KEY)
})
await saveLegacyEncrypted(LINKING_KEY, PASSWORD);
expect(savedKeyOwnerId()).toBeNull();
expect(await decryptSavedLinkingKey(PASSWORD)).toEqual(LINKING_KEY);
});
it('rejects malformed owner-bearing records instead of treating them as legacy', () => {
const real = linkingPubKeyHex(LINKING_KEY)
const real = linkingPubKeyHex(LINKING_KEY);
const junk: unknown[] = [
real.slice(1), // wrong length (65)
real + '00', // wrong length (68)
@@ -176,102 +176,102 @@ describe('owner marker on legacy records', () => {
'02' + 'ff'.repeat(32), // hex of the right length, not a curve point
42, // wrong type
null,
{pubkey: real},
{ pubkey: real },
'',
]
];
for (const ownerId of junk) {
saveLegacyPlaintext(LINKING_KEY)
localStorage.setItem(STORAGE_KEY, JSON.stringify({...readRawRecord(), ownerId}))
saveLegacyPlaintext(LINKING_KEY);
localStorage.setItem(STORAGE_KEY, JSON.stringify({ ...readRawRecord(), ownerId }));
// the junk marker never reads as an owner...
expect(savedKeyOwnerId()).toBeNull()
expect(savedKeyOwnerId()).toBeNull();
// ...or downgrades to an adoptable ownerless legacy record
expect(savedKeyExists()).toBe(false)
expect(getPlainLinkingKey()).toBeNull()
expect(savedKeyExists()).toBe(false);
expect(getPlainLinkingKey()).toBeNull();
}
})
});
it('stamps the owner after a password unlock without touching the ciphertext', async () => {
// Given a legacy encrypted record with no owner marker
const before = await saveLegacyEncrypted(LINKING_KEY, PASSWORD)
const before = await saveLegacyEncrypted(LINKING_KEY, PASSWORD);
// When ownership is proven by a successful unlock and then stamped
const linkingKey = await decryptSavedLinkingKey(PASSWORD)
ensureSavedKeyOwner(linkingKey)
const linkingKey = await decryptSavedLinkingKey(PASSWORD);
ensureSavedKeyOwner(linkingKey);
// Then the marker names the proven key and every ciphertext byte is
// preserved
const after = readRawRecord()
expect(after.ownerId).toBe(linkingPubKeyHex(LINKING_KEY))
expect(after.ciphertext).toBe(before.ciphertext)
expect(after.salt).toBe(before.salt)
expect(after.iv).toBe(before.iv)
})
const after = readRawRecord();
expect(after.ownerId).toBe(linkingPubKeyHex(LINKING_KEY));
expect(after.ciphertext).toBe(before.ciphertext);
expect(after.salt).toBe(before.salt);
expect(after.iv).toBe(before.iv);
});
it('stamps a plaintext legacy record after a plaintext unlock', () => {
saveLegacyPlaintext(LINKING_KEY)
const linkingKey = getPlainLinkingKey()
if (linkingKey === null) throw new Error('expected a plaintext key')
ensureSavedKeyOwner(linkingKey)
saveLegacyPlaintext(LINKING_KEY);
const linkingKey = getPlainLinkingKey();
if (linkingKey === null) throw new Error('expected a plaintext key');
ensureSavedKeyOwner(linkingKey);
expect(readRawRecord()).toEqual({
enc: false,
value: bytesToHex(LINKING_KEY),
version: 1,
ownerId: linkingPubKeyHex(LINKING_KEY),
})
})
});
});
it('is idempotent - stamping twice leaves storage untouched after the first write', async () => {
const before = await saveLegacyEncrypted(LINKING_KEY, PASSWORD)
const linkingKey = await decryptSavedLinkingKey(PASSWORD)
const before = await saveLegacyEncrypted(LINKING_KEY, PASSWORD);
const linkingKey = await decryptSavedLinkingKey(PASSWORD);
ensureSavedKeyOwner(linkingKey)
const afterFirst = localStorage.getItem(STORAGE_KEY)
ensureSavedKeyOwner(linkingKey)
ensureSavedKeyOwner(linkingKey);
const afterFirst = localStorage.getItem(STORAGE_KEY);
ensureSavedKeyOwner(linkingKey);
expect(localStorage.getItem(STORAGE_KEY)).toBe(afterFirst)
expect(readRawRecord().ciphertext).toBe(before.ciphertext)
})
expect(localStorage.getItem(STORAGE_KEY)).toBe(afterFirst);
expect(readRawRecord().ciphertext).toBe(before.ciphertext);
});
it('writes nothing when a new-format record is already correctly stamped', async () => {
await saveLinkingKey(LINKING_KEY, PASSWORD)
const raw = localStorage.getItem(STORAGE_KEY)
ensureSavedKeyOwner(LINKING_KEY)
expect(localStorage.getItem(STORAGE_KEY)).toBe(raw)
})
await saveLinkingKey(LINKING_KEY, PASSWORD);
const raw = localStorage.getItem(STORAGE_KEY);
ensureSavedKeyOwner(LINKING_KEY);
expect(localStorage.getItem(STORAGE_KEY)).toBe(raw);
});
it('refuses to restamp a record owned by a different wallet', async () => {
await saveLinkingKey(OTHER_KEY, PASSWORD)
const before = localStorage.getItem(STORAGE_KEY)
await saveLinkingKey(OTHER_KEY, PASSWORD);
const before = localStorage.getItem(STORAGE_KEY);
expect(() => ensureSavedKeyOwner(LINKING_KEY)).toThrow()
expect(() => ensureSavedKeyOwner(LINKING_KEY)).toThrow();
// the failed stamp leaves the record - marker included - untouched
expect(localStorage.getItem(STORAGE_KEY)).toBe(before)
expect(savedKeyOwnerId()).toBe(linkingPubKeyHex(OTHER_KEY))
})
expect(localStorage.getItem(STORAGE_KEY)).toBe(before);
expect(savedKeyOwnerId()).toBe(linkingPubKeyHex(OTHER_KEY));
});
it('refuses to stamp a key that contradicts a plaintext record', () => {
saveLegacyPlaintext(OTHER_KEY)
expect(() => ensureSavedKeyOwner(LINKING_KEY)).toThrow()
expect(savedKeyOwnerId()).toBeNull()
})
saveLegacyPlaintext(OTHER_KEY);
expect(() => ensureSavedKeyOwner(LINKING_KEY)).toThrow();
expect(savedKeyOwnerId()).toBeNull();
});
it('does not adopt a record carrying a junk owner marker', () => {
saveLegacyPlaintext(LINKING_KEY)
saveLegacyPlaintext(LINKING_KEY);
localStorage.setItem(
STORAGE_KEY,
JSON.stringify({...readRawRecord(), ownerId: 'obviously junk'}),
)
ensureSavedKeyOwner(LINKING_KEY)
expect(savedKeyOwnerId()).toBeNull()
expect(savedKeyExists()).toBe(false)
})
JSON.stringify({ ...readRawRecord(), ownerId: 'obviously junk' }),
);
ensureSavedKeyOwner(LINKING_KEY);
expect(savedKeyOwnerId()).toBeNull();
expect(savedKeyExists()).toBe(false);
});
it('is a no-op when no record is saved at all', () => {
ensureSavedKeyOwner(LINKING_KEY)
expect(savedKeyExists()).toBe(false)
})
})
ensureSavedKeyOwner(LINKING_KEY);
expect(savedKeyExists()).toBe(false);
});
});
describe('owner marker on restore', () => {
it('strips the unproven ownerId a restored record arrives with', async () => {
@@ -281,36 +281,36 @@ describe('owner marker on restore', () => {
enc: false,
value: bytesToHex(LINKING_KEY),
ownerId: linkingPubKeyHex(OTHER_KEY),
})
expect(savedKeyOwnerId()).toBeNull()
expect(getPlainLinkingKey()).toEqual(LINKING_KEY)
});
expect(savedKeyOwnerId()).toBeNull();
expect(getPlainLinkingKey()).toEqual(LINKING_KEY);
// the first proven unlock then establishes the true owner
ensureSavedKeyOwner(LINKING_KEY)
expect(savedKeyOwnerId()).toBe(linkingPubKeyHex(LINKING_KEY))
})
ensureSavedKeyOwner(LINKING_KEY);
expect(savedKeyOwnerId()).toBe(linkingPubKeyHex(LINKING_KEY));
});
it('strips a junk ownerId from a restored encrypted record', async () => {
const parts = await encryptSecretParts(bytesToHex(LINKING_KEY), PASSWORD)
restoreLinkingKeyStored({enc: true, ...parts, ownerId: 42})
expect(savedKeyOwnerId()).toBeNull()
expect(await decryptSavedLinkingKey(PASSWORD)).toEqual(LINKING_KEY)
})
})
const parts = await encryptSecretParts(bytesToHex(LINKING_KEY), PASSWORD);
restoreLinkingKeyStored({ enc: true, ...parts, ownerId: 42 });
expect(savedKeyOwnerId()).toBeNull();
expect(await decryptSavedLinkingKey(PASSWORD)).toEqual(LINKING_KEY);
});
});
describe('isWalletOwnerId', () => {
it('accepts exactly what linkingPubKeyHex produces', () => {
expect(isWalletOwnerId(linkingPubKeyHex(LINKING_KEY))).toBe(true)
expect(isWalletOwnerId(linkingPubKeyHex(OTHER_KEY))).toBe(true)
})
expect(isWalletOwnerId(linkingPubKeyHex(LINKING_KEY))).toBe(true);
expect(isWalletOwnerId(linkingPubKeyHex(OTHER_KEY))).toBe(true);
});
it('rejects everything else', () => {
const real = linkingPubKeyHex(LINKING_KEY)
expect(isWalletOwnerId(real.toUpperCase())).toBe(false)
expect(isWalletOwnerId(real.slice(0, 64))).toBe(false)
expect(isWalletOwnerId('02' + 'ff'.repeat(32))).toBe(false)
expect(isWalletOwnerId(66)).toBe(false)
expect(isWalletOwnerId(undefined)).toBe(false)
expect(isWalletOwnerId(null)).toBe(false)
})
})
const real = linkingPubKeyHex(LINKING_KEY);
expect(isWalletOwnerId(real.toUpperCase())).toBe(false);
expect(isWalletOwnerId(real.slice(0, 64))).toBe(false);
expect(isWalletOwnerId('02' + 'ff'.repeat(32))).toBe(false);
expect(isWalletOwnerId(66)).toBe(false);
expect(isWalletOwnerId(undefined)).toBe(false);
expect(isWalletOwnerId(null)).toBe(false);
});
});
src/lnurlcash/keys.ts
+102 -98
View File
@@ -1,11 +1,11 @@
import {mnemonicToSeedSync, generateMnemonic, validateMnemonic} from '@scure/bip39'
import {wordlist} from '@scure/bip39/wordlists/english.js'
import {HDKey, HARDENED_OFFSET} from '@scure/bip32'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {secp256k1} from '@noble/curves/secp256k1.js'
import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
import {cashNodeFromHex, cashNodeToHex, deriveCashRoot, type CashNode} from 'lnurlcash-kit'
import { mnemonicToSeedSync, generateMnemonic, validateMnemonic } from '@scure/bip39';
import { wordlist } from '@scure/bip39/wordlists/english.js';
import { HDKey, HARDENED_OFFSET } from '@scure/bip32';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { secp256k1 } from '@noble/curves/secp256k1.js';
import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
import { cashNodeFromHex, cashNodeToHex, deriveCashRoot, type CashNode } from 'lnurlcash-kit';
import {
parseStoredSecret,
@@ -16,9 +16,9 @@ import {
STORED_SECRET_VERSION,
type StoredSecret,
type WalletMaterialV2,
} from './storage/storedSecret'
import {decryptSecretParts, encryptSecretParts} from './passwordWrap'
import {LINKING_KEY_STORAGE_KEY} from './storage/walletOwnerEvents'
} from './storage/storedSecret';
import { decryptSecretParts, encryptSecretParts } from './passwordWrap';
import { LINKING_KEY_STORAGE_KEY } from './storage/walletOwnerEvents';
export {
isValidStoredSecret,
@@ -26,95 +26,95 @@ export {
parseWalletMaterial,
serializeWalletMaterial,
walletMaterialHash,
} from './storage/storedSecret'
export type {StoredSecret, StoredWalletMaterial, WalletMaterialV2} from './storage/storedSecret'
export {decryptSecretParts, encryptSecretParts} from './passwordWrap'
export type {EncryptedSecretParts} from './passwordWrap'
export * from './walletMaterialStorage'
} from './storage/storedSecret';
export type { StoredSecret, StoredWalletMaterial, WalletMaterialV2 } from './storage/storedSecret';
export { decryptSecretParts, encryptSecretParts } from './passwordWrap';
export type { EncryptedSecretParts } from './passwordWrap';
export * from './walletMaterialStorage';
// The wallet's identity is derived against this fixed domain rather than
// window.location.hostname, so the same seed phrase always yields the same
// linking key (and thus decrypts the same bearer tokens) no matter where
// this static build happens to be hosted - github.io, a mirror, file://.
export const WALLET_DOMAIN = 'sattle'
export const WALLET_DOMAIN = 'sattle';
export const generateSeedPhrase = (): string => generateMnemonic(wordlist, 128)
export const generateSeedPhrase = (): string => generateMnemonic(wordlist, 128);
export const isValidSeedPhrase = (phrase: string): boolean =>
validateMnemonic(phrase.trim().toLowerCase(), wordlist)
validateMnemonic(phrase.trim().toLowerCase(), wordlist);
const readUint32BE = (bytes: Uint8Array, offset: number): number =>
((bytes[offset] << 24) |
(bytes[offset + 1] << 16) |
(bytes[offset + 2] << 8) |
bytes[offset + 3]) >>>
0
0;
// LUD-05: BIP32-based linking-key derivation, same scheme as lnurl_server -
// a seed restored there or here produces the same identity for a given domain
const deriveLud05LinkingKeyFromSeed = (seed: Uint8Array, domain: string): Uint8Array => {
const master = HDKey.fromMasterSeed(seed)
const master = HDKey.fromMasterSeed(seed);
const hashingKeyNode = master.derive("m/138'/0")
if (!hashingKeyNode.privateKey) throw new Error('Could not derive hashing key')
const suffix = lud05PathSuffix(hashingKeyNode.privateKey, domain)
const hashingKeyNode = master.derive("m/138'/0");
if (!hashingKeyNode.privateKey) throw new Error('Could not derive hashing key');
const suffix = lud05PathSuffix(hashingKeyNode.privateKey, domain);
// path suffix longs are raw BIP32 child indices: whether each level ends up
// hardened depends solely on its own magnitude (>= 2^31), never forced
let node = master.deriveChild(138 + HARDENED_OFFSET)
let node = master.deriveChild(138 + HARDENED_OFFSET);
for (const index of suffix) {
node = node.deriveChild(index)
node = node.deriveChild(index);
}
if (!node.privateKey) throw new Error('Could not derive linking key')
return node.privateKey
}
if (!node.privateKey) throw new Error('Could not derive linking key');
return node.privateKey;
};
export const deriveLud05LinkingKey = (seedPhrase: string, domain: string): Uint8Array =>
deriveLud05LinkingKeyFromSeed(mnemonicToSeedSync(seedPhrase.trim().toLowerCase()), domain)
deriveLud05LinkingKeyFromSeed(mnemonicToSeedSync(seedPhrase.trim().toLowerCase()), domain);
// the HMAC half of the derivation, split out so the LUD-05 test vector
// (which starts from a fixed hashingPrivKey, not a seed phrase) can pin it
// directly - see keys.test.ts
export const lud05PathSuffix = (hashingKey: Uint8Array, domain: string): number[] => {
const material = hmac(sha256, hashingKey, utf8ToBytes(domain))
return [0, 4, 8, 12].map((i) => readUint32BE(material, i))
}
const material = hmac(sha256, hashingKey, utf8ToBytes(domain));
return [0, 4, 8, 12].map((i) => readUint32BE(material, i));
};
export const deriveWalletLinkingKey = (seedPhrase: string): Uint8Array =>
deriveLud05LinkingKey(seedPhrase, WALLET_DOMAIN)
deriveLud05LinkingKey(seedPhrase, WALLET_DOMAIN);
export const deriveWalletMaterial = (seedPhrase: string): WalletMaterialV2 => {
const seed = mnemonicToSeedSync(seedPhrase.trim().toLowerCase())
const seed = mnemonicToSeedSync(seedPhrase.trim().toLowerCase());
try {
return {
version: 2,
linkingKeyHex: bytesToHex(deriveLud05LinkingKeyFromSeed(seed, WALLET_DOMAIN)),
cashRootHex: cashNodeToHex(deriveCashRoot(seed)),
}
};
} finally {
seed.fill(0)
seed.fill(0);
}
}
};
export const walletMaterialLinkingKey = (material: WalletMaterialV2): Uint8Array =>
hexToBytes(material.linkingKeyHex)
hexToBytes(material.linkingKeyHex);
export const walletMaterialCashRoot = (material: WalletMaterialV2): CashNode =>
cashNodeFromHex(material.cashRootHex)
cashNodeFromHex(material.cashRootHex);
export const linkingPubKeyHex = (linkingPrivKey: Uint8Array): string =>
bytesToHex(secp256k1.getPublicKey(linkingPrivKey, true))
bytesToHex(secp256k1.getPublicKey(linkingPrivKey, true));
const readSecret = (storageKey: string): StoredSecret | null => {
const raw = localStorage.getItem(storageKey)
if (!raw) return null
const raw = localStorage.getItem(storageKey);
if (!raw) return null;
try {
const parsed: unknown = JSON.parse(raw)
return parseStoredSecret(parsed)?.secret ?? null
const parsed: unknown = JSON.parse(raw);
return parseStoredSecret(parsed)?.secret ?? null;
} catch {
return null
return null;
}
}
};
// The legacy alpha lifecycle below persists only the linking key under its old
// namespace. Task 5 replaces that lifecycle with the v2 material repository;
@@ -135,24 +135,24 @@ const readSecret = (storageKey: string): StoredSecret | null => {
// preserving ciphertext byte-for-byte; it refuses to restamp a record
// already owned by a different valid owner, and refuses a key that
// contradicts a plaintext record.
export const savedKeyExists = (): boolean => readSecret(LINKING_KEY_STORAGE_KEY) !== null
export const savedKeyExists = (): boolean => readSecret(LINKING_KEY_STORAGE_KEY) !== null;
export const savedKeyIsEncrypted = (): boolean => readSecret(LINKING_KEY_STORAGE_KEY)?.enc === true
export const savedKeyIsEncrypted = (): boolean => readSecret(LINKING_KEY_STORAGE_KEY)?.enc === true;
export const getSavedLinkingKeyStored = (): StoredSecret | null =>
readSecret(LINKING_KEY_STORAGE_KEY)
readSecret(LINKING_KEY_STORAGE_KEY);
// the proven owner of the saved key, or null when there is no record or it
// carries no current version-1 marker (ownerless or compatible unversioned)
export const savedKeyOwnerId = (): string | null => {
const stored = readSecret(LINKING_KEY_STORAGE_KEY)
return stored === null ? null : storedSecretOwnerId(stored)
}
const stored = readSecret(LINKING_KEY_STORAGE_KEY);
return stored === null ? null : storedSecretOwnerId(stored);
};
// Compares only against an owner freshly derived from a linking key. An
// ownerless or unversioned saved marker never matches.
export const savedKeyOwnerMatches = (linkingKey: Uint8Array): boolean =>
savedKeyOwnerId() === linkingPubKeyHex(linkingKey)
savedKeyOwnerId() === linkingPubKeyHex(linkingKey);
// Stamps the owner marker onto the existing record. Call ONLY with the key
// just proven against this record (decryptSavedLinkingKey / a plaintext
@@ -161,99 +161,103 @@ export const savedKeyOwnerMatches = (linkingKey: Uint8Array): boolean =>
// already-correct marker: no write. A DIFFERENT valid owner, or a key that
// contradicts a plaintext record, throws and leaves storage untouched.
export const ensureSavedKeyOwner = (linkingKey: Uint8Array): void => {
const stored = readSecret(LINKING_KEY_STORAGE_KEY)
if (stored === null) return
const ownerId = linkingPubKeyHex(linkingKey)
const stored = readSecret(LINKING_KEY_STORAGE_KEY);
if (stored === null) return;
const ownerId = linkingPubKeyHex(linkingKey);
if (stored.enc === false && stored.value.toLowerCase() !== bytesToHex(linkingKey)) {
throw new Error('Proven key does not match the saved wallet key.')
throw new Error('Proven key does not match the saved wallet key.');
}
const claimedOwnerId = storedSecretClaimedOwnerId(stored)
if (storedSecretOwnerId(stored) === ownerId) return
const claimedOwnerId = storedSecretClaimedOwnerId(stored);
if (storedSecretOwnerId(stored) === ownerId) return;
if (claimedOwnerId !== null && claimedOwnerId !== ownerId) {
throw new Error('Saved wallet key is owned by a different wallet.')
throw new Error('Saved wallet key is owned by a different wallet.');
}
localStorage.setItem(
LINKING_KEY_STORAGE_KEY,
JSON.stringify(stampStoredSecretOwner(stored, ownerId)),
)
}
);
};
export const getPlainLinkingKey = (): Uint8Array | null => {
const stored = readSecret(LINKING_KEY_STORAGE_KEY)
if (stored === null || stored.enc === true) return null
return hexToBytes(stored.value)
}
const stored = readSecret(LINKING_KEY_STORAGE_KEY);
if (stored === null || stored.enc === true) return null;
return hexToBytes(stored.value);
};
export const saveLinkingKey = async (
linkingPrivKey: Uint8Array,
password?: string,
): Promise<void> => {
const hex = bytesToHex(linkingPrivKey)
const ownerId = linkingPubKeyHex(linkingPrivKey)
const hex = bytesToHex(linkingPrivKey);
const ownerId = linkingPubKeyHex(linkingPrivKey);
if (!password) {
localStorage.setItem(
LINKING_KEY_STORAGE_KEY,
JSON.stringify({enc: false, value: hex, ownerId, version: STORED_SECRET_VERSION}),
)
return
JSON.stringify({ enc: false, value: hex, ownerId, version: STORED_SECRET_VERSION }),
);
return;
}
const parts = await encryptSecretParts(hex, password)
const parts = await encryptSecretParts(hex, password);
localStorage.setItem(
LINKING_KEY_STORAGE_KEY,
JSON.stringify({enc: true, ...parts, ownerId, version: STORED_SECRET_VERSION}),
)
}
JSON.stringify({ enc: true, ...parts, ownerId, version: STORED_SECRET_VERSION }),
);
};
// installs a record from a backup/relay. Any ownerId it carries is an
// unproven claim by whoever produced that file, so the marker is stripped
// here - the first proven unlock re-establishes it (see the failure-model
// comment above)
export const restoreLinkingKeyStored = (stored: StoredSecret): void => {
localStorage.setItem(LINKING_KEY_STORAGE_KEY, JSON.stringify(stripStoredSecretOwner(stored)))
}
localStorage.setItem(LINKING_KEY_STORAGE_KEY, JSON.stringify(stripStoredSecretOwner(stored)));
};
export const decryptSavedLinkingKey = async (password: string): Promise<Uint8Array> => {
const stored = readSecret(LINKING_KEY_STORAGE_KEY)
if (!stored || !stored.enc) throw new Error('No encrypted linking key saved.')
return hexToBytes(await decryptSecretParts(stored, password))
}
const stored = readSecret(LINKING_KEY_STORAGE_KEY);
if (!stored || !stored.enc) throw new Error('No encrypted linking key saved.');
return hexToBytes(await decryptSecretParts(stored, password));
};
export const clearSavedLinkingKey = (): void => {
localStorage.removeItem(LINKING_KEY_STORAGE_KEY)
}
localStorage.removeItem(LINKING_KEY_STORAGE_KEY);
};
// The bearer-encryption key is derived (not random): sha256 over the linking
// key plus a fixed context string. Deterministic derivation is what makes
// backup/restore work with nothing but the seed phrase - restore the seed on
// a fresh device and every previously exported ciphertext decrypts again.
const BEARER_KEY_CONTEXT = 'lnurlcash-bearer-encryption-v1'
const BEARER_KEY_CONTEXT = 'lnurlcash-bearer-encryption-v1';
export const deriveBearerAesKey = (linkingPrivKey: Uint8Array): Promise<CryptoKey> => {
const material = sha256(new Uint8Array([...linkingPrivKey, ...utf8ToBytes(BEARER_KEY_CONTEXT)]))
return crypto.subtle.importKey('raw', material, 'AES-GCM', false, ['encrypt', 'decrypt'])
}
const material = sha256(new Uint8Array([...linkingPrivKey, ...utf8ToBytes(BEARER_KEY_CONTEXT)]));
return crypto.subtle.importKey('raw', material, 'AES-GCM', false, ['encrypt', 'decrypt']);
};
export type EncryptedRecordParts = {iv: string; ciphertext: string}
export type EncryptedRecordParts = { iv: string; ciphertext: string };
export const encryptRecord = async (
aesKey: CryptoKey,
value: object,
): Promise<EncryptedRecordParts> => {
const iv = crypto.getRandomValues(new Uint8Array(12))
const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = new Uint8Array(
await crypto.subtle.encrypt({name: 'AES-GCM', iv}, aesKey, utf8ToBytes(JSON.stringify(value))),
)
return {iv: bytesToHex(iv), ciphertext: bytesToHex(ciphertext)}
}
await crypto.subtle.encrypt(
{ name: 'AES-GCM', iv },
aesKey,
utf8ToBytes(JSON.stringify(value)),
),
);
return { iv: bytesToHex(iv), ciphertext: bytesToHex(ciphertext) };
};
export const decryptRecord = async (
aesKey: CryptoKey,
parts: EncryptedRecordParts,
): Promise<unknown> => {
const plaintext = await crypto.subtle.decrypt(
{name: 'AES-GCM', iv: hexToBytes(parts.iv)},
{ name: 'AES-GCM', iv: hexToBytes(parts.iv) },
aesKey,
hexToBytes(parts.ciphertext),
)
return JSON.parse(new TextDecoder().decode(plaintext))
}
);
return JSON.parse(new TextDecoder().decode(plaintext));
};
src/lnurlcash/keys.version.cases.ts
+47 -47
View File
@@ -1,5 +1,5 @@
import {beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import {
ensureSavedKeyOwner,
@@ -9,54 +9,54 @@ import {
savedKeyExists,
savedKeyOwnerId,
saveLinkingKey,
} from './keys'
import {parseJsonObject, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, stubLocalStorage } from './test-utils';
import './keys.material.cases'
import './keys.material-commitment.cases'
import './keys.material-storage.cases'
import './keys.material.cases';
import './keys.material-commitment.cases';
import './keys.material-storage.cases';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const STORAGE_KEY = 'sattle_linking_key'
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const STORAGE_KEY = 'sattle_linking_key';
const readRawRecord = (): Record<string, unknown> => {
const raw = localStorage.getItem(STORAGE_KEY)
if (raw === null) throw new Error('expected a saved linking-key record')
return parseJsonObject(raw)
}
const raw = localStorage.getItem(STORAGE_KEY);
if (raw === null) throw new Error('expected a saved linking-key record');
return parseJsonObject(raw);
};
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
describe('saved-key schema version', () => {
it('writes version 1 on current plaintext and encrypted records', async () => {
// Given a linking key saved through each current persistence path
await saveLinkingKey(LINKING_KEY)
const plaintext = readRawRecord()
await saveLinkingKey(LINKING_KEY, 'correct horse')
const encrypted = readRawRecord()
await saveLinkingKey(LINKING_KEY);
const plaintext = readRawRecord();
await saveLinkingKey(LINKING_KEY, 'correct horse');
const encrypted = readRawRecord();
// When the persisted schema metadata is inspected
// Then both owner-bearing records carry the recognized discriminator
expect(plaintext.version).toBe(1)
expect(encrypted.version).toBe(1)
})
expect(plaintext.version).toBe(1);
expect(encrypted.version).toBe(1);
});
it('upgrades an unversioned same-owner record only after key proof', () => {
// Given the valid owner-bearing shape written before schema versioning
const ownerId = linkingPubKeyHex(LINKING_KEY)
const ownerId = linkingPubKeyHex(LINKING_KEY);
localStorage.setItem(
STORAGE_KEY,
JSON.stringify({enc: false, value: bytesToHex(LINKING_KEY), ownerId}),
)
JSON.stringify({ enc: false, value: bytesToHex(LINKING_KEY), ownerId }),
);
// When it is read before and then stamped after the plaintext key proves ownership
expect(savedKeyOwnerId()).toBeNull()
const provenKey = getPlainLinkingKey()
if (provenKey === null) throw new Error('expected the compatible plaintext key')
ensureSavedKeyOwner(provenKey)
expect(savedKeyOwnerId()).toBeNull();
const provenKey = getPlainLinkingKey();
if (provenKey === null) throw new Error('expected the compatible plaintext key');
ensureSavedKeyOwner(provenKey);
// Then it becomes an explicitly versioned current record
expect(readRawRecord()).toEqual({
@@ -64,8 +64,8 @@ describe('saved-key schema version', () => {
value: bytesToHex(LINKING_KEY),
ownerId,
version: 1,
})
})
});
});
it.each([2, '1', null])('rejects unsupported or malformed version %j', (version) => {
// Given an otherwise valid owner-bearing record with unrecognized metadata
@@ -74,16 +74,16 @@ describe('saved-key schema version', () => {
value: bytesToHex(LINKING_KEY),
ownerId: linkingPubKeyHex(LINKING_KEY),
version,
}
localStorage.setItem(STORAGE_KEY, JSON.stringify(record))
};
localStorage.setItem(STORAGE_KEY, JSON.stringify(record));
// When the saved-key boundary parses it
// Then the record is neither usable nor eligible for legacy adoption
expect(isValidStoredSecret(record)).toBe(false)
expect(savedKeyExists()).toBe(false)
expect(savedKeyOwnerId()).toBeNull()
expect(getPlainLinkingKey()).toBeNull()
})
expect(isValidStoredSecret(record)).toBe(false);
expect(savedKeyExists()).toBe(false);
expect(savedKeyOwnerId()).toBeNull();
expect(getPlainLinkingKey()).toBeNull();
});
it('rejects a foreign current owner at the proven-key stamping boundary', () => {
// Given a versioned record whose owner conflicts with its plaintext key
@@ -92,15 +92,15 @@ describe('saved-key schema version', () => {
value: bytesToHex(LINKING_KEY),
ownerId: linkingPubKeyHex(OTHER_LINKING_KEY),
version: 1,
}
localStorage.setItem(STORAGE_KEY, JSON.stringify(record))
const before = localStorage.getItem(STORAGE_KEY)
};
localStorage.setItem(STORAGE_KEY, JSON.stringify(record));
const before = localStorage.getItem(STORAGE_KEY);
// When the actual key is proven
const stamp = () => ensureSavedKeyOwner(LINKING_KEY)
const stamp = () => ensureSavedKeyOwner(LINKING_KEY);
// Then the foreign claim fails closed without rewriting storage
expect(stamp).toThrow('different wallet')
expect(localStorage.getItem(STORAGE_KEY)).toBe(before)
})
})
expect(stamp).toThrow('different wallet');
expect(localStorage.getItem(STORAGE_KEY)).toBe(before);
});
});
src/lnurlcash/mintContract.test.ts
+142 -132
View File
@@ -13,51 +13,51 @@
// mintToHash alone is only an additive receipt extension, not permission
// to mint.
import {afterEach, describe, expect, it} from 'vitest'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import {buildNoteUrl, fetchMintAddress, hashK1} from 'lnurlcash-kit'
import { afterEach, describe, expect, it } from 'vitest';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import { buildNoteUrl, fetchMintAddress, hashK1 } from 'lnurlcash-kit';
import {claimMintedNote, prepareMint} from './ops'
import {mintAddressCacheInfo} from './trustedMints'
import './mintContract.v08.cases'
import { claimMintedNote, prepareMint } from './ops';
import { mintAddressCacheInfo } from './trustedMints';
import './mintContract.v08.cases';
type Mint = Awaited<ReturnType<typeof createMockMint>>
type Mint = Awaited<ReturnType<typeof createMockMint>>;
const mints: Mint[] = []
const mints: Mint[] = [];
const mint = async (options: Parameters<typeof createMockMint>[0] = {}): Promise<Mint> => {
const m = await createMockMint(options)
mints.push(m)
return m
}
const m = await createMockMint(options);
mints.push(m);
return m;
};
afterEach(async () => {
await Promise.all(mints.splice(0).map((m) => m.close()))
})
await Promise.all(mints.splice(0).map((m) => m.close()));
});
// paying a mint invoice is what brings its note into existence - the mock
// exposes that through its test hook (settle + credit in one step)
const settleLastInvoice = async (m: Mint): Promise<string> => {
const paymentHash = [...m.state.invoices.keys()].at(-1)
if (!paymentHash) throw new Error('no invoice requested yet')
const res = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`)
if (!res.ok) throw new Error(`settle hook failed: ${res.status}`)
const invoice = m.state.invoices.get(paymentHash)
if (!invoice) throw new Error('settled invoice vanished from the mock')
return invoice.preimage
}
const paymentHash = [...m.state.invoices.keys()].at(-1);
if (!paymentHash) throw new Error('no invoice requested yet');
const res = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`);
if (!res.ok) throw new Error(`settle hook failed: ${res.status}`);
const invoice = m.state.invoices.get(paymentHash);
if (!invoice) throw new Error('settled invoice vanished from the mock');
return invoice.preimage;
};
const MINT_PUBKEY = `02${'ab'.repeat(32)}`
const persistOutput = async (): Promise<void> => undefined
const MINT_PUBKEY = `02${'ab'.repeat(32)}`;
const persistOutput = async (): Promise<void> => undefined;
// deterministic stand-in for the wallet's BIP-32 allocation path
let allocatedCounter = 0
let allocatedCounter = 0;
const allocateOutputSecrets = (_server: string, count: number): Promise<readonly string[]> => {
const secrets = Array.from({length: count}, () => {
allocatedCounter += 1
return `03${allocatedCounter.toString(16).padStart(62, '0')}`
})
return Promise.resolve(secrets)
}
const secrets = Array.from({ length: count }, () => {
allocatedCounter += 1;
return `03${allocatedCounter.toString(16).padStart(62, '0')}`;
});
return Promise.resolve(secrets);
};
// a mint-address (LUD-25) wire response exactly as lnurl-mint serves it:
// node stats under their WIRE names - `nodeCapacity` is msat like every
@@ -74,26 +74,26 @@ const mintAddressFixture = {
nodeCapacity: 500_000_000,
nodeNumChannels: 4,
nodeNumPeers: 6,
}
};
const jsonResponse = (body: unknown): Response =>
new Response(JSON.stringify(body), {
status: 200,
headers: {'content-type': 'application/json'},
})
headers: { 'content-type': 'application/json' },
});
// a fetch that serves fixture bodies by URL prefix and 404s everything else,
// so a test drives the real kit HTTP boundary without any network
const fixtureFetch = (routes: ReadonlyArray<readonly [string, unknown]>): typeof fetch => {
const impl: typeof fetch = (input, _init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
for (const [prefix, body] of routes) {
if (url.startsWith(prefix)) return Promise.resolve(jsonResponse(body))
if (url.startsWith(prefix)) return Promise.resolve(jsonResponse(body));
}
return Promise.resolve(new Response('not found', {status: 404}))
}
return impl
}
return Promise.resolve(new Response('not found', { status: 404 }));
};
return impl;
};
// fixtureFetch plus a record of every URL it saw, for canaries about the
// exact query the kit puts on the wire
@@ -102,69 +102,75 @@ const capturingFetch = (
seen: string[],
): typeof fetch => {
const impl: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
seen.push(url)
return fixtureFetch(routes)(input, init)
}
return impl
}
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
seen.push(url);
return fixtureFetch(routes)(input, init);
};
return impl;
};
describe('mint-address wire contract', () => {
it('maps the wire nodeCapacity onto the app-facing nodeCapacityMsat', async () => {
const info = await fetchMintAddress('https://mint.example/.well-known/lnurlw/mint', {
fetch: fixtureFetch([['https://mint.example/', mintAddressFixture]]),
})
});
// renamed fields have to be mapped, not spread: the spread carries the
// wire name through and the typed one reads undefined forever
expect(info.nodePubkey).toBe(MINT_PUBKEY)
expect(info.nodeCapacityMsat).toBe(500_000_000)
expect(info.nodeNumChannels).toBe(4)
expect(info.nodeNumPeers).toBe(6)
})
expect(info.nodePubkey).toBe(MINT_PUBKEY);
expect(info.nodeCapacityMsat).toBe(500_000_000);
expect(info.nodeNumChannels).toBe(4);
expect(info.nodeNumPeers).toBe(6);
});
it('carries node stats into the cached trusted-mint display metadata', async () => {
const info = await fetchMintAddress('https://mint.example/.well-known/lnurlw/mint', {
fetch: fixtureFetch([['https://mint.example/', mintAddressFixture]]),
})
const cached = mintAddressCacheInfo(info, 'mint')
expect(cached?.nodeCapacityMsat).toBe(500_000_000)
expect(cached?.nodeNumChannels).toBe(4)
expect(cached?.nodeNumPeers).toBe(6)
})
});
const cached = mintAddressCacheInfo(info, 'mint');
expect(cached?.nodeCapacityMsat).toBe(500_000_000);
expect(cached?.nodeNumChannels).toBe(4);
expect(cached?.nodeNumPeers).toBe(6);
});
it("surfaces the mock mint's mint-address node stats through prepareMint", async () => {
const m = await mint()
const prepared = await prepareMint(`mint@127.0.0.1:${m.port}`, 21_000, {persistOutput, allocateOutputSecrets})
const m = await mint();
const prepared = await prepareMint(`mint@127.0.0.1:${m.port}`, 21_000, {
persistOutput,
allocateOutputSecrets,
});
// the metadata is advertised at the mint-address endpoint itself -
// the payRequest never carried it
expect(prepared.nodeInfo?.nodePubkey).toBe(m.state.pubkey)
expect(prepared.nodeInfo?.nodeCapacityMsat).toBe(500_000_000)
expect(prepared.nodeInfo?.nodeNumChannels).toBe(4)
expect(prepared.nodeInfo?.nodeNumPeers).toBe(6)
const cached = mintAddressCacheInfo(prepared.nodeInfo, prepared.username)
expect(cached?.nodeCapacityMsat).toBe(500_000_000)
})
})
expect(prepared.nodeInfo?.nodePubkey).toBe(m.state.pubkey);
expect(prepared.nodeInfo?.nodeCapacityMsat).toBe(500_000_000);
expect(prepared.nodeInfo?.nodeNumChannels).toBe(4);
expect(prepared.nodeInfo?.nodeNumPeers).toBe(6);
const cached = mintAddressCacheInfo(prepared.nodeInfo, prepared.username);
expect(cached?.nodeCapacityMsat).toBe(500_000_000);
});
});
describe('withdraw-link forms', () => {
it('accepts the lnurlw:// withdraw link the conformance mock mint advertises', async () => {
// conformance 0.7.0 defaults to plain https links; lnurlw:// is an
// explicit LUD-17 transport form
const m = await mint({testHooks: true, withdrawLinkForm: 'lnurlw'})
const prepared = await prepareMint(`mint@127.0.0.1:${m.port}`, 21_000, {persistOutput, allocateOutputSecrets})
expect(prepared.withdrawLink).toMatch(/^lnurlw:\/\//)
const m = await mint({ testHooks: true, withdrawLinkForm: 'lnurlw' });
const prepared = await prepareMint(`mint@127.0.0.1:${m.port}`, 21_000, {
persistOutput,
allocateOutputSecrets,
});
expect(prepared.withdrawLink).toMatch(/^lnurlw:\/\//);
// and the link is fully usable: settle the invoice, claim the note
const preimage = await settleLastInvoice(m)
const preimage = await settleLastInvoice(m);
const claimed = await claimMintedNote(prepared, {
intervalMs: 10,
intervalCapMs: 50,
maxWaitMs: 5_000,
})
expect(claimed.note.amount).toBe(21_000)
expect(m.state.noteState(preimage)).toBeNull()
expect(m.state.noteState(prepared.noteSecret)).toBe('outstanding')
})
});
expect(claimed.note.amount).toBe(21_000);
expect(m.state.noteState(preimage)).toBeNull();
expect(m.state.noteState(prepared.noteSecret)).toBe('outstanding');
});
it('accepts an HTTPS withdraw link', async () => {
const fetch = fixtureFetch([
@@ -182,21 +188,25 @@ describe('withdraw-link forms', () => {
},
],
// amount-less invoice: the kit skips its amount cross-check
['https://mint.example/pay', {pr: 'lnmock1fixture', verify: null}],
])
const prepared = await prepareMint('mint@mint.example', 21_000, {fetch, persistOutput, allocateOutputSecrets})
expect(prepared.withdrawLink).toBe('https://mint.example/note')
['https://mint.example/pay', { pr: 'lnmock1fixture', verify: null }],
]);
const prepared = await prepareMint('mint@mint.example', 21_000, {
fetch,
persistOutput,
allocateOutputSecrets,
});
expect(prepared.withdrawLink).toBe('https://mint.example/note');
// the mint-address payLink is authoritative - the payRequest came from it
expect(prepared.mintUrl).toBe('https://mint.example/.well-known/lnurlp/mint')
})
expect(prepared.mintUrl).toBe('https://mint.example/.well-known/lnurlp/mint');
});
it('builds the same note URL from both withdraw-link forms', () => {
const k1 = 'ab'.repeat(32)
const k1 = 'ab'.repeat(32);
expect(buildNoteUrl('lnurlw://mint.example/note', k1, 21_000)).toBe(
buildNoteUrl('https://mint.example/note', k1, 21_000),
)
})
})
);
});
});
describe('quote output-naming wire contract', () => {
const payRequestFixture = (extra: Record<string, unknown>) => ({
@@ -207,90 +217,90 @@ describe('quote output-naming wire contract', () => {
withdrawLink: 'https://mint.example/note',
metadata: '[]',
...extra,
})
});
const routesFor = (payRequest: Record<string, unknown>) =>
[
['https://mint.example/.well-known/lnurlw/mint', mintAddressFixture],
['https://mint.example/.well-known/lnurlp/mint', payRequest],
// amount-less invoice: the kit skips its amount cross-check
['https://mint.example/pay', {pr: 'lnmock1fixture', verify: null}],
] as const
['https://mint.example/pay', { pr: 'lnmock1fixture', verify: null }],
] as const;
const callbackUrl = (seen: string[]): URL => {
const hit = seen.find((url) => url.startsWith('https://mint.example/pay?'))
if (!hit) throw new Error('the quote request never hit the wire')
return new URL(hit)
}
const hit = seen.find((url) => url.startsWith('https://mint.example/pay?'));
if (!hit) throw new Error('the quote request never hit the wire');
return new URL(hit);
};
it('rejects a mint that cannot carry the mandatory output commitment', async () => {
const seen: string[] = []
const seen: string[] = [];
await expect(
prepareMint('mint@mint.example', 21_000, {
fetch: capturingFetch(routesFor(payRequestFixture({})), seen),
persistOutput,
allocateOutputSecrets,
}),
).rejects.toThrow(/64-character output commitment/i)
expect(seen.some((url) => url.startsWith('https://mint.example/pay?'))).toBe(false)
})
).rejects.toThrow(/64-character output commitment/i);
expect(seen.some((url) => url.startsWith('https://mint.example/pay?'))).toBe(false);
});
it('persists the wallet output before sending its hash as comment and h', async () => {
const seen: string[] = []
const events: string[] = []
const seen: string[] = [];
const events: string[] = [];
const prepared = await prepareMint('mint@mint.example', 21_000, {
allocateOutputSecrets,
fetch: (input, init) => {
const url =
typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
events.push(url.startsWith('https://mint.example/pay?') ? 'invoice' : 'discovery')
typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
events.push(url.startsWith('https://mint.example/pay?') ? 'invoice' : 'discovery');
return capturingFetch(
routesFor(payRequestFixture({commentAllowed: 64, mintPubkey: `03${'cd'.repeat(32)}`})),
routesFor(payRequestFixture({ commentAllowed: 64, mintPubkey: `03${'cd'.repeat(32)}` })),
seen,
)(input, init)
)(input, init);
},
persistOutput: async (note) => {
events.push('persist')
expect(note.verified).toBe(false)
expect(note.callback).toBe('')
expect(note.amount).toBe(0)
expect(note.pendingMint?.mintPubkey).toBe(MINT_PUBKEY)
events.push('persist');
expect(note.verified).toBe(false);
expect(note.callback).toBe('');
expect(note.amount).toBe(0);
expect(note.pendingMint?.mintPubkey).toBe(MINT_PUBKEY);
},
})
const noteSecret = prepared.noteSecret
const url = callbackUrl(seen)
});
const noteSecret = prepared.noteSecret;
const url = callbackUrl(seen);
// both spellings go out together: `comment` is the LUD-25 form
// lnurl-mint >= 0.4 REQUIRES, `h` the earlier form other mints read
const comment = url.searchParams.get('comment')
const h = url.searchParams.get('h')
expect(comment).toMatch(/^[0-9a-f]{64}$/)
expect(h).toBe(comment)
expect(comment).toBe(hashK1(noteSecret))
expect(prepared.mintPubkey).toBe(MINT_PUBKEY)
expect(events.indexOf('persist')).toBeGreaterThanOrEqual(0)
expect(events.indexOf('persist')).toBeLessThan(events.indexOf('invoice'))
})
const comment = url.searchParams.get('comment');
const h = url.searchParams.get('h');
expect(comment).toMatch(/^[0-9a-f]{64}$/);
expect(h).toBe(comment);
expect(comment).toBe(hashK1(noteSecret));
expect(prepared.mintPubkey).toBe(MINT_PUBKEY);
expect(events.indexOf('persist')).toBeGreaterThanOrEqual(0);
expect(events.indexOf('persist')).toBeLessThan(events.indexOf('invoice'));
});
it('does not request an invoice when output persistence fails', async () => {
const seen: string[] = []
const seen: string[] = [];
await expect(
prepareMint('mint@mint.example', 21_000, {
fetch: capturingFetch(routesFor(payRequestFixture({commentAllowed: 64})), seen),
fetch: capturingFetch(routesFor(payRequestFixture({ commentAllowed: 64 })), seen),
persistOutput: () => Promise.reject(new Error('storage full')),
allocateOutputSecrets,
}),
).rejects.toThrow(/storage full/)
expect(seen.some((url) => url.startsWith('https://mint.example/pay?'))).toBe(false)
})
).rejects.toThrow(/storage full/);
expect(seen.some((url) => url.startsWith('https://mint.example/pay?'))).toBe(false);
});
it('rejects mintToHash without the mandatory comment capacity', async () => {
const seen: string[] = []
const seen: string[] = [];
await expect(
prepareMint('mint@mint.example', 21_000, {
fetch: capturingFetch(routesFor(payRequestFixture({mintToHash: true})), seen),
fetch: capturingFetch(routesFor(payRequestFixture({ mintToHash: true })), seen),
persistOutput,
allocateOutputSecrets,
}),
).rejects.toThrow(/64-character output commitment/i)
expect(seen.some((url) => url.startsWith('https://mint.example/pay?'))).toBe(false)
})
})
).rejects.toThrow(/64-character output commitment/i);
expect(seen.some((url) => url.startsWith('https://mint.example/pay?'))).toBe(false);
});
});
src/lnurlcash/mintContract.v08.cases.ts
+14 -14
View File
@@ -1,7 +1,7 @@
// The wallet's deterministic-secret and signed-output work depends on this
// exact installed API surface, so package drift must fail before funds code runs.
import {describe, expect, it} from 'vitest'
import { describe, expect, it } from 'vitest';
import {
cashNodeFromHex,
cashNodeToHex,
@@ -12,12 +12,12 @@ import {
verifyNoteSignatureAgainst,
verifyNoteSignatureHash,
verifyNoteSignatureHashAgainst,
} from 'lnurlcash-kit'
import type {LnurlcashOptions} from 'lnurlcash-kit'
import conformancePackage from '../../node_modules/lnurlcash-conformance/package.json'
import kitPackage from '../../node_modules/lnurlcash-kit/package.json'
} from 'lnurlcash-kit';
import type { LnurlcashOptions } from 'lnurlcash-kit';
import conformancePackage from '../../node_modules/lnurlcash-conformance/package.json';
import kitPackage from '../../node_modules/lnurlcash-kit/package.json';
const retryOptions = {mutationRetries: 1} satisfies LnurlcashOptions
const retryOptions = { mutationRetries: 1 } satisfies LnurlcashOptions;
const requiredExports = [
deriveCashRoot,
cashNodeToHex,
@@ -28,16 +28,16 @@ const requiredExports = [
verifyNoteSignatureAgainst,
verifyNoteSignatureHash,
verifyNoteSignatureHashAgainst,
] as const
] as const;
describe('lnurlcash 0.8 dependency contract', () => {
it('exposes the BIP-32, recovery, signature, and retry contracts', () => {
expect(requiredExports.every((value) => typeof value === 'function')).toBe(true)
expect(retryOptions.mutationRetries).toBe(1)
})
expect(requiredExports.every((value) => typeof value === 'function')).toBe(true);
expect(retryOptions.mutationRetries).toBe(1);
});
it('runs against the exact installed package versions', () => {
expect(kitPackage.version).toBe('0.8.0')
expect(conformancePackage.version).toBe('0.7.0')
})
})
expect(kitPackage.version).toBe('0.8.0');
expect(conformancePackage.version).toBe('0.7.0');
});
});
src/lnurlcash/nostr/events.ts
+77 -76
View File
@@ -20,25 +20,25 @@
// mints - the trusted-mint registry
// settings - plaintext wallet settings
import {sha256} from '@noble/hashes/sha2.js'
import {utf8ToBytes} from '@noble/hashes/utils.js'
import type {Event as NostrEvent} from 'nostr-tools/core'
import {finalizeEvent, getPublicKey, verifyEvent} from 'nostr-tools/pure'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import { sha256 } from '@noble/hashes/sha2.js';
import { utf8ToBytes } from '@noble/hashes/utils.js';
import type { Event as NostrEvent } from 'nostr-tools/core';
import { finalizeEvent, getPublicKey, verifyEvent } from 'nostr-tools/pure';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import type {EncryptedBearerRecord} from '../storage/bearers'
import type {TrustedMint} from '../trustedMints'
import type {WalletSettings} from '../storage/settings'
import type { EncryptedBearerRecord } from '../storage/bearers';
import type { TrustedMint } from '../trustedMints';
import type { WalletSettings } from '../storage/settings';
export type {NostrEvent}
export type { NostrEvent };
// addressable (parametrized-replaceable) app-data event - relays keep only
// the newest event per (pubkey, kind, d-tag)
export const BACKUP_EVENT_KIND = 30078
export const BACKUP_EVENT_KIND = 30078;
export type BackupPart = 'notes' | 'mints' | 'settings'
export type BackupPart = 'notes' | 'mints' | 'settings';
export const BACKUP_PARTS: readonly BackupPart[] = ['notes', 'mints', 'settings']
export const BACKUP_PARTS: readonly BackupPart[] = ['notes', 'mints', 'settings'];
// the backup key is dedicated to this wallet (derived with a
// sattle-specific context, see below), so its pubkey is ours alone and the
@@ -47,45 +47,46 @@ export const BACKUP_D_TAGS: Record<BackupPart, string> = {
notes: 'notes',
mints: 'mints',
settings: 'settings',
}
};
// the notes payload: bearers plus the counter map, from one consistent
// funds-document read
export type NotesBackupPayload = {
bearers: EncryptedBearerRecord[]
nextByHost: Record<string, number>
}
bearers: EncryptedBearerRecord[];
nextByHost: Record<string, number>;
};
// the decrypted payload of each part, without its envelope
export type BackupPartPayload = {
notes: NotesBackupPayload
mints: TrustedMint[]
settings: WalletSettings
}
notes: NotesBackupPayload;
mints: TrustedMint[];
settings: WalletSettings;
};
const BACKUP_KEY_CONTEXT = 'sattle-nostr-backup-v1'
const BACKUP_KEY_CONTEXT = 'sattle-nostr-backup-v1';
// Deterministic: sha256(linking key || context), mirroring keys.ts's
// deriveBearerAesKey. The result is a secp256k1 secret key used ONLY for
// backup - it signs and decrypts backup events, nothing else.
export const deriveBackupKey = (linkingPrivKey: Uint8Array): Uint8Array =>
sha256(new Uint8Array([...linkingPrivKey, ...utf8ToBytes(BACKUP_KEY_CONTEXT)]))
sha256(new Uint8Array([...linkingPrivKey, ...utf8ToBytes(BACKUP_KEY_CONTEXT)]));
// the x-only nostr pubkey identifying this wallet's backup events
export const backupPubkey = (secretKey: Uint8Array): string => getPublicKey(secretKey)
export const backupPubkey = (secretKey: Uint8Array): string => getPublicKey(secretKey);
// NIP-44 "self-DM": the conversation key between the backup key and its own
// pubkey - decryptable by the seed holder and nobody else
const selfConversationKey = (secretKey: Uint8Array): Uint8Array =>
nip44v2.utils.getConversationKey(secretKey, getPublicKey(secretKey))
nip44v2.utils.getConversationKey(secretKey, getPublicKey(secretKey));
// a relay could serve a multi-megabyte content string; JSON.parse and
// NIP-44 decrypt of that would hang the tab. A real backup is a handful of
// kilobytes per part - this is far beyond generous (applyBackup's own
// per-record bounds still apply on top after decrypt)
const MAX_BACKUP_CONTENT_CHARS = 16 * 1024 * 1024
const MAX_BACKUP_CONTENT_CHARS = 16 * 1024 * 1024;
export const dTagOf = (event: NostrEvent): string => event.tags.find((t) => t[0] === 'd')?.[1] ?? ''
export const dTagOf = (event: NostrEvent): string =>
event.tags.find((t) => t[0] === 'd')?.[1] ?? '';
// per-part envelope versions: the notes part went v2 with the funds
// document (counters joined the payload - a breaking change); mints and
@@ -94,20 +95,20 @@ const PART_ENVELOPE_VERSION: Record<BackupPart, number> = {
notes: 2,
mints: 1,
settings: 1,
}
};
const envelopeFor = (part: BackupPart, payload: BackupPartPayload[BackupPart]): string => {
switch (part) {
case 'notes': {
const notes = payload as NotesBackupPayload
return JSON.stringify({version: 2, bearers: notes.bearers, nextByHost: notes.nextByHost})
const notes = payload as NotesBackupPayload;
return JSON.stringify({ version: 2, bearers: notes.bearers, nextByHost: notes.nextByHost });
}
case 'mints':
return JSON.stringify({version: 1, trustedMints: payload})
return JSON.stringify({ version: 1, trustedMints: payload });
case 'settings':
return JSON.stringify({version: 1, settings: payload})
return JSON.stringify({ version: 1, settings: payload });
}
}
};
// signs one addressable backup event for a single part
export const buildBackupEvent = <P extends BackupPart>(
@@ -124,7 +125,7 @@ export const buildBackupEvent = <P extends BackupPart>(
content: nip44v2.encrypt(envelopeFor(part, payload), selfConversationKey(secretKey)),
},
secretKey,
)
);
// one event per part present in `parts`, all sharing one timestamp
export const buildBackupEvents = (
@@ -132,33 +133,33 @@ export const buildBackupEvents = (
parts: Partial<BackupPartPayload>,
createdAt?: number,
): NostrEvent[] => {
const at = createdAt ?? Math.floor(Date.now() / 1000)
const events: NostrEvent[] = []
const at = createdAt ?? Math.floor(Date.now() / 1000);
const events: NostrEvent[] = [];
for (const part of BACKUP_PARTS) {
const payload = parts[part]
if (payload === undefined) continue
events.push(buildBackupEvent(secretKey, part, payload, at))
const payload = parts[part];
if (payload === undefined) continue;
events.push(buildBackupEvent(secretKey, part, payload, at));
}
return events
}
return events;
};
export type ParsedBackupEvent =
| {part: 'notes'; bearers: EncryptedBearerRecord[]; nextByHost: Record<string, number>}
| {part: 'mints'; trustedMints: TrustedMint[]}
| {part: 'settings'; settings: WalletSettings}
| { part: 'notes'; bearers: EncryptedBearerRecord[]; nextByHost: Record<string, number> }
| { part: 'mints'; trustedMints: TrustedMint[] }
| { part: 'settings'; settings: WalletSettings };
// Light shape checks so parse returns typed values; the strict bounds
// (record counts, field lengths, counter ranges and caps) are enforced by
// applyBackup / commitFundsRestore on the restore path, same as file
// backups.
const parsePayload = (dTag: BackupPart, data: unknown): ParsedBackupEvent | null => {
if (typeof data !== 'object' || data === null) return null
const envelope = data as Record<string, unknown>
if (envelope.version !== PART_ENVELOPE_VERSION[dTag]) return null
if (typeof data !== 'object' || data === null) return null;
const envelope = data as Record<string, unknown>;
if (envelope.version !== PART_ENVELOPE_VERSION[dTag]) return null;
switch (dTag) {
case 'notes': {
if (!Array.isArray(envelope.bearers)) return null
const bearers = envelope.bearers as unknown[]
if (!Array.isArray(envelope.bearers)) return null;
const bearers = envelope.bearers as unknown[];
if (
!bearers.every(
(r) =>
@@ -167,20 +168,20 @@ const parsePayload = (dTag: BackupPart, data: unknown): ParsedBackupEvent | null
typeof (r as EncryptedBearerRecord)?.ciphertext === 'string',
)
) {
return null
return null;
}
if (typeof envelope.nextByHost !== 'object' || envelope.nextByHost === null) return null
const counters = envelope.nextByHost as Record<string, unknown>
if (!Object.values(counters).every((v) => typeof v === 'number')) return null
if (typeof envelope.nextByHost !== 'object' || envelope.nextByHost === null) return null;
const counters = envelope.nextByHost as Record<string, unknown>;
if (!Object.values(counters).every((v) => typeof v === 'number')) return null;
return {
part: 'notes',
bearers: bearers as EncryptedBearerRecord[],
nextByHost: counters as Record<string, number>,
}
};
}
case 'mints': {
if (!Array.isArray(envelope.trustedMints)) return null
const mints = envelope.trustedMints as unknown[]
if (!Array.isArray(envelope.trustedMints)) return null;
const mints = envelope.trustedMints as unknown[];
if (
!mints.every(
(m) =>
@@ -188,22 +189,22 @@ const parsePayload = (dTag: BackupPart, data: unknown): ParsedBackupEvent | null
typeof (m as TrustedMint)?.mintPubkey === 'string',
)
) {
return null
return null;
}
return {part: 'mints', trustedMints: mints as TrustedMint[]}
return { part: 'mints', trustedMints: mints as TrustedMint[] };
}
case 'settings': {
if (typeof envelope.settings !== 'object' || envelope.settings === null) {
return null
return null;
}
const settings = envelope.settings as Record<string, unknown>
const settings = envelope.settings as Record<string, unknown>;
if (settings.defaultMint !== undefined && typeof settings.defaultMint !== 'string') {
return null
return null;
}
return {part: 'settings', settings: settings as WalletSettings}
return { part: 'settings', settings: settings as WalletSettings };
}
}
}
};
// Validates and decrypts one backup event. Returns null for anything that
// isn't a genuine, untampered backup of THIS key: wrong kind, wrong d-tag,
@@ -213,23 +214,23 @@ export const parseBackupEvent = (
secretKey: Uint8Array,
event: NostrEvent,
): ParsedBackupEvent | null => {
if (event.kind !== BACKUP_EVENT_KIND) return null
if (event.pubkey !== getPublicKey(secretKey)) return null
const dTag = dTagOf(event)
if (dTag !== 'notes' && dTag !== 'mints' && dTag !== 'settings') return null
if (!verifyEvent(event)) return null
if (event.content.length > MAX_BACKUP_CONTENT_CHARS) return null
let plaintext: string
if (event.kind !== BACKUP_EVENT_KIND) return null;
if (event.pubkey !== getPublicKey(secretKey)) return null;
const dTag = dTagOf(event);
if (dTag !== 'notes' && dTag !== 'mints' && dTag !== 'settings') return null;
if (!verifyEvent(event)) return null;
if (event.content.length > MAX_BACKUP_CONTENT_CHARS) return null;
let plaintext: string;
try {
plaintext = nip44v2.decrypt(event.content, selfConversationKey(secretKey))
plaintext = nip44v2.decrypt(event.content, selfConversationKey(secretKey));
} catch {
return null
return null;
}
let data: unknown
let data: unknown;
try {
data = JSON.parse(plaintext)
data = JSON.parse(plaintext);
} catch {
return null
return null;
}
return parsePayload(dTag, data)
}
return parsePayload(dTag, data);
};
src/lnurlcash/nostr/publisher.ts
+35 -33
View File
@@ -2,74 +2,76 @@
// edits (a mint plus a receive plus a reorder) collapse into one publish
// of the final state. Trailing-edge debounce with in-flight coalescing.
import type {BackupPartPayload} from './events'
import type { BackupPartPayload } from './events';
export type BackupPublisher = {
// record that local state changed - the latest snapshot wins, and only
// one publish fires per quiet window no matter how many changes landed
schedule: (parts: Partial<BackupPartPayload>) => void
schedule: (parts: Partial<BackupPartPayload>) => void;
// publish any pending snapshot immediately (app backgrounding, logout)
flush: () => Promise<void>
flush: () => Promise<void>;
// drop any pending snapshot without publishing
cancel: () => void
}
cancel: () => void;
};
export type BackupPublisherOptions = {
publish: (parts: Partial<BackupPartPayload>) => Promise<void>
delayMs: number
publish: (parts: Partial<BackupPartPayload>) => Promise<void>;
delayMs: number;
// a debounced publish has no caller to throw to - errors surface here;
// the next scheduled change retries
onError?: (error: unknown) => void
}
onError?: (error: unknown) => void;
};
export const createBackupPublisher = (options: BackupPublisherOptions): BackupPublisher => {
let timer: ReturnType<typeof setTimeout> | null = null
let pending: Partial<BackupPartPayload> | null = null
let running: Promise<void> | null = null
let timer: ReturnType<typeof setTimeout> | null = null;
let pending: Partial<BackupPartPayload> | null = null;
let running: Promise<void> | null = null;
const clearTimer = (): void => {
if (timer !== null) {
clearTimeout(timer)
timer = null
clearTimeout(timer);
timer = null;
}
}
};
const drain = async (): Promise<void> => {
// a change can land mid-publish - keep looping until the newest
// snapshot is the one that's out
while (pending !== null) {
const snapshot = pending
pending = null
const snapshot = pending;
pending = null;
try {
await options.publish(snapshot)
await options.publish(snapshot);
} catch (error) {
options.onError?.(
error instanceof Error ? error : new Error('Backup publication failed.', {cause: error}),
)
error instanceof Error
? error
: new Error('Backup publication failed.', { cause: error }),
);
}
}
}
};
const fire = (): Promise<void> => {
clearTimer()
clearTimer();
// an in-flight drain picks up anything pending itself - a second drain
// would double-publish the same snapshot
running ??= drain().finally(() => {
running = null
})
return running
}
running = null;
});
return running;
};
return {
schedule: (parts) => {
pending = parts
clearTimer()
timer = setTimeout(() => void fire(), options.delayMs)
pending = parts;
clearTimer();
timer = setTimeout(() => void fire(), options.delayMs);
},
flush: fire,
cancel: () => {
clearTimer()
pending = null
clearTimer();
pending = null;
},
}
}
};
};
src/lnurlcash/nostr/sync.ts
+55 -55
View File
@@ -8,11 +8,11 @@
// under different record ids, spent-wins) happens after decrypt in
// bearers.ts's mergeBearers, exactly as with a file backup.
import type {RestoreResult} from '../storage/backup'
import {applyBackup} from '../storage/backup'
import {linkingPubKeyHex} from '../keys'
import type { RestoreResult } from '../storage/backup';
import { applyBackup } from '../storage/backup';
import { linkingPubKeyHex } from '../keys';
import type {BackupPart, BackupPartPayload, NostrEvent} from './events'
import type { BackupPart, BackupPartPayload, NostrEvent } from './events';
import {
BACKUP_EVENT_KIND,
BACKUP_PARTS,
@@ -21,18 +21,18 @@ import {
deriveBackupKey,
dTagOf,
parseBackupEvent,
} from './events'
import type {BackupTransport} from './transport'
import {defaultTransport} from './transport'
} from './events';
import type { BackupTransport } from './transport';
import { defaultTransport } from './transport';
export type PublishBackupOptions = {
transport?: BackupTransport
createdAt?: number
}
transport?: BackupTransport;
createdAt?: number;
};
export type PublishBackupResult = {
published: BackupPart[]
}
published: BackupPart[];
};
// builds and publishes one event per part present in `parts`
export const publishBackup = async (
@@ -41,26 +41,26 @@ export const publishBackup = async (
relays: string[],
options: PublishBackupOptions = {},
): Promise<PublishBackupResult> => {
const at = options.createdAt ?? Math.floor(Date.now() / 1000)
const present = BACKUP_PARTS.filter((part) => parts[part] !== undefined)
if (present.length === 0) return {published: []}
const transport = options.transport ?? (await defaultTransport())
const published: BackupPart[] = []
const at = options.createdAt ?? Math.floor(Date.now() / 1000);
const present = BACKUP_PARTS.filter((part) => parts[part] !== undefined);
if (present.length === 0) return { published: [] };
const transport = options.transport ?? (await defaultTransport());
const published: BackupPart[] = [];
for (const part of present) {
const payload = parts[part]
if (payload === undefined) continue
await transport.publish(relays, buildBackupEvent(secretKey, part, payload, at))
published.push(part)
const payload = parts[part];
if (payload === undefined) continue;
await transport.publish(relays, buildBackupEvent(secretKey, part, payload, at));
published.push(part);
}
return {published}
}
return { published };
};
export type FetchBackupOptions = {
// the pubkey alone can fetch the ciphertext, but only the key holder
// reads it - decryption is part of fetching
secretKey: Uint8Array
transport?: BackupTransport
}
secretKey: Uint8Array;
transport?: BackupTransport;
};
// fetches the newest valid event per d-tag and decrypts it. Honest relays
// already replace addressable events, but a stale or misbehaving relay may
@@ -71,49 +71,49 @@ export const fetchBackup = async (
relays: string[],
options: FetchBackupOptions,
): Promise<Partial<BackupPartPayload>> => {
const transport = options.transport ?? (await defaultTransport())
const transport = options.transport ?? (await defaultTransport());
const events = await transport.fetch(relays, {
kinds: [BACKUP_EVENT_KIND],
authors: [pubkey],
})
const byTag = new Map<string, NostrEvent[]>()
});
const byTag = new Map<string, NostrEvent[]>();
for (const event of events) {
const d = dTagOf(event)
if (!d) continue
const candidates = byTag.get(d)
if (candidates) candidates.push(event)
else byTag.set(d, [event])
const d = dTagOf(event);
if (!d) continue;
const candidates = byTag.get(d);
if (candidates) candidates.push(event);
else byTag.set(d, [event]);
}
const parts: Partial<BackupPartPayload> = {}
const parts: Partial<BackupPartPayload> = {};
for (const candidates of byTag.values()) {
// a hostile relay may serve a tampered "newest" copy - walk
// newest-first and take the first that validates and decrypts
candidates.sort((a, b) => b.created_at - a.created_at)
candidates.sort((a, b) => b.created_at - a.created_at);
for (const event of candidates) {
const parsed = parseBackupEvent(options.secretKey, event)
if (!parsed) continue
const parsed = parseBackupEvent(options.secretKey, event);
if (!parsed) continue;
switch (parsed.part) {
case 'notes':
parts.notes = {bearers: parsed.bearers, nextByHost: parsed.nextByHost}
break
parts.notes = { bearers: parsed.bearers, nextByHost: parsed.nextByHost };
break;
case 'mints':
parts.mints = parsed.trustedMints
break
parts.mints = parsed.trustedMints;
break;
case 'settings':
parts.settings = parsed.settings
break
parts.settings = parsed.settings;
break;
}
break
break;
}
}
return parts
}
return parts;
};
export type NostrRestoreResult = RestoreResult & {
// which d-tags carried a valid payload at all - lets the caller
// distinguish "nothing backed up yet" from "restored an empty wallet"
found: BackupPart[]
}
found: BackupPart[];
};
// The restore path end to end: re-derive the backup key from the linking
// key (the holder already re-entered the seed phrase to get that far),
@@ -124,13 +124,13 @@ export type NostrRestoreResult = RestoreResult & {
export const restoreFromNostr = async (
linkingPrivKey: Uint8Array,
relays: string[],
options: {transport?: BackupTransport} = {},
options: { transport?: BackupTransport } = {},
): Promise<NostrRestoreResult> => {
const secretKey = deriveBackupKey(linkingPrivKey)
const secretKey = deriveBackupKey(linkingPrivKey);
const parts = await fetchBackup(backupPubkey(secretKey), relays, {
secretKey,
transport: options.transport,
})
});
const result = await applyBackup(
{
type: 'sattle-backup',
@@ -142,9 +142,9 @@ export const restoreFromNostr = async (
settings: parts.settings,
},
linkingPubKeyHex(linkingPrivKey),
)
);
return {
...result,
found: BACKUP_PARTS.filter((part) => parts[part] !== undefined),
}
}
};
};
src/lnurlcash/nostr/transport.ts
+12 -12
View File
@@ -3,30 +3,30 @@
// lazily: merely importing the backup module must never open (or even
// reference) a WebSocket.
import type {Filter as NostrFilter} from 'nostr-tools/filter'
import type { Filter as NostrFilter } from 'nostr-tools/filter';
import type {NostrEvent} from './events'
import type { NostrEvent } from './events';
export type {NostrFilter}
export type { NostrFilter };
// publish throws when the event was accepted NOWHERE
export type BackupTransport = {
publish: (relays: string[], event: NostrEvent) => Promise<void>
fetch: (relays: string[], filter: NostrFilter) => Promise<NostrEvent[]>
}
publish: (relays: string[], event: NostrEvent) => Promise<void>;
fetch: (relays: string[], filter: NostrFilter) => Promise<NostrEvent[]>;
};
export const defaultTransport = async (): Promise<BackupTransport> => {
const {SimplePool} = await import('nostr-tools/pool')
const pool = new SimplePool()
const { SimplePool } = await import('nostr-tools/pool');
const pool = new SimplePool();
return {
publish: async (relays, event) => {
const results = await Promise.allSettled(pool.publish(relays, event))
const results = await Promise.allSettled(pool.publish(relays, event));
// one honest relay keeping the event is enough - addressable events
// are re-publishable, and the next debounced publish retries anyway
if (!results.some((r) => r.status === 'fulfilled')) {
throw new Error('No relay accepted the backup event.')
throw new Error('No relay accepted the backup event.');
}
},
fetch: (relays, filter) => pool.querySync(relays, filter),
}
}
};
};
src/lnurlcash/nostrBackup.codec.cases.ts
+87 -87
View File
@@ -2,14 +2,14 @@
// tamper rejection, publish/fetch and restore against an in-memory relay
// (the transport is injected - no network), and the debounced publisher.
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import type {NostrEvent} from 'nostr-tools/core'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl} from 'lnurlcash-kit'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import type { NostrEvent } from 'nostr-tools/core';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl } from 'lnurlcash-kit';
import {deriveBearerAesKey, linkingPubKeyHex, saveLinkingKey} from './keys'
import { deriveBearerAesKey, linkingPubKeyHex, saveLinkingKey } from './keys';
import {
BACKUP_EVENT_KIND,
backupPubkey,
@@ -21,8 +21,8 @@ import {
parseBackupEvent,
publishBackup,
restoreFromNostr,
} from './nostrBackup'
import type {BackupPartPayload, BackupTransport} from './nostrBackup'
} from './nostrBackup';
import type { BackupPartPayload, BackupTransport } from './nostrBackup';
import {
loadBearers,
loadSettings,
@@ -30,21 +30,21 @@ import {
persistBearer,
persistSettings,
readEncryptedBearers,
} from './storage'
import type {Bearer} from './types'
import {addTrustedMint, isMintUnconfirmed, readTrustedMints} from './trustedMints'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './storage';
import type { Bearer } from './types';
import { addTrustedMint, isMintUnconfirmed, readTrustedMints } from './trustedMints';
import { requiredValue, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_KEY = new Uint8Array(32).fill(9)
const OWNER_ID = linkingPubKeyHex(LINKING_KEY)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_KEY = new Uint8Array(32).fill(9);
const OWNER_ID = linkingPubKeyHex(LINKING_KEY);
const K1_A = 'aa'.repeat(32)
const K1_B = 'bb'.repeat(32)
const MINT_PUBKEY = 'ab'.repeat(33)
const K1_A = 'aa'.repeat(32);
const K1_B = 'bb'.repeat(32);
const MINT_PUBKEY = 'ab'.repeat(33);
// never connected - the recording transport below stands in for the relays
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example']
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example'];
const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
id: 'fixture',
@@ -55,20 +55,20 @@ const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
createdAt: 1000,
updatedAt: 1000,
...overrides,
})
});
// an in-memory relay set. It serves EVERY event it ever accepted, older
// addressable copies included - like a relay that never replaces - which
// is exactly the case fetchBackup's client-side latest-pick exists for
const createRecordingTransport = (): {
transport: BackupTransport
events: NostrEvent[]
transport: BackupTransport;
events: NostrEvent[];
} => {
const events: NostrEvent[] = []
const events: NostrEvent[] = [];
const transport: BackupTransport = {
publish: (_relays, event) => {
events.push(event)
return Promise.resolve()
events.push(event);
return Promise.resolve();
},
fetch: (_relays, filter) =>
Promise.resolve(
@@ -78,121 +78,121 @@ const createRecordingTransport = (): {
(!filter.authors || filter.authors.includes(e.pubkey)),
),
),
}
return {transport, events}
}
};
return { transport, events };
};
// flips the end of a base64 payload to different-but-valid characters
const tamperContent = (content: string): string =>
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA')
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA');
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
afterEach(() => {
vi.useRealTimers()
})
vi.useRealTimers();
});
describe('buildBackupEvent / parseBackupEvent', () => {
const secretKey = deriveBackupKey(LINKING_KEY)
const secretKey = deriveBackupKey(LINKING_KEY);
const records = [
// long unique sentinel id: a short id like 'r1' randomly appears in
// base64 ciphertext (~17% for 700 chars), which flakes the no-plaintext
// assertion below
{id: 'record-id-plaintext-sentinel-7f3a', iv: '00'.repeat(12), ciphertext: 'ab'.repeat(40)},
]
const notes = {bearers: records, nextByHost: {'mint.example': 3}}
const mints = [{server: 'mint.example', mintPubkey: MINT_PUBKEY, addedAt: 1000, locked: true}]
const settings = {defaultMint: 'mint.example'}
{ id: 'record-id-plaintext-sentinel-7f3a', iv: '00'.repeat(12), ciphertext: 'ab'.repeat(40) },
];
const notes = { bearers: records, nextByHost: { 'mint.example': 3 } };
const mints = [{ server: 'mint.example', mintPubkey: MINT_PUBKEY, addedAt: 1000, locked: true }];
const settings = { defaultMint: 'mint.example' };
it('round-trips all three parts through build and parse', () => {
const events = buildBackupEvents(secretKey, {notes, mints, settings}, 1000)
expect(events).toHaveLength(3)
const events = buildBackupEvents(secretKey, { notes, mints, settings }, 1000);
expect(events).toHaveLength(3);
expect(events.map((e) => e.kind)).toEqual([
BACKUP_EVENT_KIND,
BACKUP_EVENT_KIND,
BACKUP_EVENT_KIND,
])
]);
expect(events.map((e) => e.tags)).toEqual([
[['d', 'notes']],
[['d', 'mints']],
[['d', 'settings']],
])
expect(events.every((e) => e.pubkey === backupPubkey(secretKey))).toBe(true)
]);
expect(events.every((e) => e.pubkey === backupPubkey(secretKey))).toBe(true);
expect(parseBackupEvent(secretKey, requiredValue(events[0]))).toEqual({
part: 'notes',
bearers: records,
nextByHost: {'mint.example': 3},
})
nextByHost: { 'mint.example': 3 },
});
expect(parseBackupEvent(secretKey, requiredValue(events[1]))).toEqual({
part: 'mints',
trustedMints: mints,
})
});
expect(parseBackupEvent(secretKey, requiredValue(events[2]))).toEqual({
part: 'settings',
settings,
})
})
});
});
it('leaves no plaintext in the payload', () => {
const event = buildBackupEvent(secretKey, 'notes', notes)
expect(event.content).not.toContain('record-id-plaintext-sentinel-7f3a')
expect(event.content).not.toContain('ciphertext')
})
const event = buildBackupEvent(secretKey, 'notes', notes);
expect(event.content).not.toContain('record-id-plaintext-sentinel-7f3a');
expect(event.content).not.toContain('ciphertext');
});
it('builds events only for the parts present', () => {
const events = buildBackupEvents(secretKey, {settings}, 1000)
expect(events).toHaveLength(1)
expect(requiredValue(events[0]).tags).toEqual([['d', 'settings']])
})
const events = buildBackupEvents(secretKey, { settings }, 1000);
expect(events).toHaveLength(1);
expect(requiredValue(events[0]).tags).toEqual([['d', 'settings']]);
});
it('rejects a payload encrypted for a different key', () => {
const event = buildBackupEvent(secretKey, 'settings', settings)
expect(parseBackupEvent(deriveBackupKey(OTHER_KEY), event)).toBeNull()
})
const event = buildBackupEvent(secretKey, 'settings', settings);
expect(parseBackupEvent(deriveBackupKey(OTHER_KEY), event)).toBeNull();
});
it('rejects the wrong kind', () => {
const event = buildBackupEvent(secretKey, 'settings', settings)
expect(parseBackupEvent(secretKey, {...event, kind: 30079})).toBeNull()
})
const event = buildBackupEvent(secretKey, 'settings', settings);
expect(parseBackupEvent(secretKey, { ...event, kind: 30079 })).toBeNull();
});
it('rejects an unknown d-tag', () => {
const event = buildBackupEvent(secretKey, 'settings', settings)
expect(parseBackupEvent(secretKey, {...event, tags: [['d', 'secrets']]})).toBeNull()
})
const event = buildBackupEvent(secretKey, 'settings', settings);
expect(parseBackupEvent(secretKey, { ...event, tags: [['d', 'secrets']] })).toBeNull();
});
it('rejects a modified ciphertext - the signature no longer matches', () => {
const event = buildBackupEvent(secretKey, 'settings', settings)
const tampered = {...event, content: tamperContent(event.content)}
expect(parseBackupEvent(secretKey, tampered)).toBeNull()
})
const event = buildBackupEvent(secretKey, 'settings', settings);
const tampered = { ...event, content: tamperContent(event.content) };
expect(parseBackupEvent(secretKey, tampered)).toBeNull();
});
it('rejects an event signed by a different key', () => {
const foreign = buildBackupEvent(deriveBackupKey(OTHER_KEY), 'settings', settings)
expect(parseBackupEvent(secretKey, foreign)).toBeNull()
})
const foreign = buildBackupEvent(deriveBackupKey(OTHER_KEY), 'settings', settings);
expect(parseBackupEvent(secretKey, foreign)).toBeNull();
});
it('rejects a validly signed event whose payload is not a backup envelope', () => {
// a same-key event of the right kind and d-tag, but its decrypted
// content is not a version-1 envelope
const conversationKey = nip44v2.utils.getConversationKey(secretKey, getPublicKey(secretKey))
const conversationKey = nip44v2.utils.getConversationKey(secretKey, getPublicKey(secretKey));
const event = finalizeEvent(
{
kind: BACKUP_EVENT_KIND,
created_at: 1000,
tags: [['d', 'settings']],
content: nip44v2.encrypt(JSON.stringify({version: 2, settings: {}}), conversationKey),
content: nip44v2.encrypt(JSON.stringify({ version: 2, settings: {} }), conversationKey),
},
secretKey,
)
expect(parseBackupEvent(secretKey, event)).toBeNull()
})
);
expect(parseBackupEvent(secretKey, event)).toBeNull();
});
it('rejects a legacy version-1 notes envelope and a v2 notes envelope without counters', () => {
const conversationKey = nip44v2.utils.getConversationKey(secretKey, getPublicKey(secretKey))
const conversationKey = nip44v2.utils.getConversationKey(secretKey, getPublicKey(secretKey));
const build = (payload: unknown): NostrEvent =>
finalizeEvent(
{
@@ -202,13 +202,13 @@ describe('buildBackupEvent / parseBackupEvent', () => {
content: nip44v2.encrypt(JSON.stringify(payload), conversationKey),
},
secretKey,
)
);
// v1 notes carried bare bearer arrays and no counters - pre-funds-document
expect(parseBackupEvent(secretKey, build({version: 1, bearers: records}))).toBeNull()
expect(parseBackupEvent(secretKey, build({version: 2, bearers: records}))).toBeNull()
expect(parseBackupEvent(secretKey, build({ version: 1, bearers: records }))).toBeNull();
expect(parseBackupEvent(secretKey, build({ version: 2, bearers: records }))).toBeNull();
// a v2 envelope whose counters are malformed is rejected, not coerced
expect(
parseBackupEvent(secretKey, build({version: 2, bearers: records, nextByHost: 'junk'})),
).toBeNull()
})
})
parseBackupEvent(secretKey, build({ version: 2, bearers: records, nextByHost: 'junk' })),
).toBeNull();
});
});
src/lnurlcash/nostrBackup.keys.cases.ts
+39 -39
View File
@@ -2,14 +2,14 @@
// tamper rejection, publish/fetch and restore against an in-memory relay
// (the transport is injected - no network), and the debounced publisher.
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import type {NostrEvent} from 'nostr-tools/core'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl} from 'lnurlcash-kit'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import type { NostrEvent } from 'nostr-tools/core';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl } from 'lnurlcash-kit';
import {deriveBearerAesKey, linkingPubKeyHex, saveLinkingKey} from './keys'
import { deriveBearerAesKey, linkingPubKeyHex, saveLinkingKey } from './keys';
import {
BACKUP_EVENT_KIND,
backupPubkey,
@@ -21,8 +21,8 @@ import {
parseBackupEvent,
publishBackup,
restoreFromNostr,
} from './nostrBackup'
import type {BackupPartPayload, BackupTransport} from './nostrBackup'
} from './nostrBackup';
import type { BackupPartPayload, BackupTransport } from './nostrBackup';
import {
loadBearers,
loadSettings,
@@ -30,21 +30,21 @@ import {
persistBearer,
persistSettings,
readEncryptedBearers,
} from './storage'
import type {Bearer} from './types'
import {addTrustedMint, isMintUnconfirmed, readTrustedMints} from './trustedMints'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './storage';
import type { Bearer } from './types';
import { addTrustedMint, isMintUnconfirmed, readTrustedMints } from './trustedMints';
import { requiredValue, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_KEY = new Uint8Array(32).fill(9)
const OWNER_ID = linkingPubKeyHex(LINKING_KEY)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_KEY = new Uint8Array(32).fill(9);
const OWNER_ID = linkingPubKeyHex(LINKING_KEY);
const K1_A = 'aa'.repeat(32)
const K1_B = 'bb'.repeat(32)
const MINT_PUBKEY = 'ab'.repeat(33)
const K1_A = 'aa'.repeat(32);
const K1_B = 'bb'.repeat(32);
const MINT_PUBKEY = 'ab'.repeat(33);
// never connected - the recording transport below stands in for the relays
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example']
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example'];
const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
id: 'fixture',
@@ -55,20 +55,20 @@ const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
createdAt: 1000,
updatedAt: 1000,
...overrides,
})
});
// an in-memory relay set. It serves EVERY event it ever accepted, older
// addressable copies included - like a relay that never replaces - which
// is exactly the case fetchBackup's client-side latest-pick exists for
const createRecordingTransport = (): {
transport: BackupTransport
events: NostrEvent[]
transport: BackupTransport;
events: NostrEvent[];
} => {
const events: NostrEvent[] = []
const events: NostrEvent[] = [];
const transport: BackupTransport = {
publish: (_relays, event) => {
events.push(event)
return Promise.resolve()
events.push(event);
return Promise.resolve();
},
fetch: (_relays, filter) =>
Promise.resolve(
@@ -78,21 +78,21 @@ const createRecordingTransport = (): {
(!filter.authors || filter.authors.includes(e.pubkey)),
),
),
}
return {transport, events}
}
};
return { transport, events };
};
// flips the end of a base64 payload to different-but-valid characters
const tamperContent = (content: string): string =>
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA')
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA');
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
afterEach(() => {
vi.useRealTimers()
})
vi.useRealTimers();
});
describe('deriveBackupKey', () => {
it('derives a stable key from the linking key', () => {
@@ -101,12 +101,12 @@ describe('deriveBackupKey', () => {
// derive a different pubkey and find nothing to restore
expect(bytesToHex(deriveBackupKey(LINKING_KEY))).toBe(
'a583f5740869d240d3052442957a46ec5f2534f8ae0284f7f7f8b03d602edad9',
)
})
);
});
it('derives a different key from a different linking key', () => {
expect(bytesToHex(deriveBackupKey(OTHER_KEY))).not.toBe(
bytesToHex(deriveBackupKey(LINKING_KEY)),
)
})
})
);
});
});
src/lnurlcash/nostrBackup.publisher.cases.ts
+107 -104
View File
@@ -2,14 +2,14 @@
// tamper rejection, publish/fetch and restore against an in-memory relay
// (the transport is injected - no network), and the debounced publisher.
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import type {NostrEvent} from 'nostr-tools/core'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl} from 'lnurlcash-kit'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import type { NostrEvent } from 'nostr-tools/core';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl } from 'lnurlcash-kit';
import {deriveBearerAesKey, linkingPubKeyHex, saveLinkingKey} from './keys'
import { deriveBearerAesKey, linkingPubKeyHex, saveLinkingKey } from './keys';
import {
BACKUP_EVENT_KIND,
backupPubkey,
@@ -21,8 +21,8 @@ import {
parseBackupEvent,
publishBackup,
restoreFromNostr,
} from './nostrBackup'
import type {BackupPartPayload, BackupTransport} from './nostrBackup'
} from './nostrBackup';
import type { BackupPartPayload, BackupTransport } from './nostrBackup';
import {
loadBearers,
loadSettings,
@@ -30,21 +30,21 @@ import {
persistBearer,
persistSettings,
readEncryptedBearers,
} from './storage'
import type {Bearer} from './types'
import {addTrustedMint, isMintUnconfirmed, readTrustedMints} from './trustedMints'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './storage';
import type { Bearer } from './types';
import { addTrustedMint, isMintUnconfirmed, readTrustedMints } from './trustedMints';
import { requiredValue, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_KEY = new Uint8Array(32).fill(9)
const OWNER_ID = linkingPubKeyHex(LINKING_KEY)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_KEY = new Uint8Array(32).fill(9);
const OWNER_ID = linkingPubKeyHex(LINKING_KEY);
const K1_A = 'aa'.repeat(32)
const K1_B = 'bb'.repeat(32)
const MINT_PUBKEY = 'ab'.repeat(33)
const K1_A = 'aa'.repeat(32);
const K1_B = 'bb'.repeat(32);
const MINT_PUBKEY = 'ab'.repeat(33);
// never connected - the recording transport below stands in for the relays
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example']
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example'];
const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
id: 'fixture',
@@ -55,20 +55,20 @@ const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
createdAt: 1000,
updatedAt: 1000,
...overrides,
})
});
// an in-memory relay set. It serves EVERY event it ever accepted, older
// addressable copies included - like a relay that never replaces - which
// is exactly the case fetchBackup's client-side latest-pick exists for
const createRecordingTransport = (): {
transport: BackupTransport
events: NostrEvent[]
transport: BackupTransport;
events: NostrEvent[];
} => {
const events: NostrEvent[] = []
const events: NostrEvent[] = [];
const transport: BackupTransport = {
publish: (_relays, event) => {
events.push(event)
return Promise.resolve()
events.push(event);
return Promise.resolve();
},
fetch: (_relays, filter) =>
Promise.resolve(
@@ -78,134 +78,137 @@ const createRecordingTransport = (): {
(!filter.authors || filter.authors.includes(e.pubkey)),
),
),
}
return {transport, events}
}
};
return { transport, events };
};
// flips the end of a base64 payload to different-but-valid characters
const tamperContent = (content: string): string =>
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA')
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA');
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
afterEach(() => {
vi.useRealTimers()
})
vi.useRealTimers();
});
describe('createBackupPublisher', () => {
it('coalesces rapid schedules into a single publish of the latest snapshot', async () => {
vi.useFakeTimers()
const published: Partial<BackupPartPayload>[] = []
vi.useFakeTimers();
const published: Partial<BackupPartPayload>[] = [];
const publisher = createBackupPublisher({
publish: (p) => {
published.push(p)
return Promise.resolve()
published.push(p);
return Promise.resolve();
},
delayMs: 1000,
})
});
publisher.schedule({settings: {defaultMint: 'a'}})
publisher.schedule({settings: {defaultMint: 'b'}})
publisher.schedule({settings: {defaultMint: 'c'}})
await vi.advanceTimersByTimeAsync(999)
expect(published).toEqual([])
await vi.advanceTimersByTimeAsync(1)
expect(published).toEqual([{settings: {defaultMint: 'c'}}])
})
publisher.schedule({ settings: { defaultMint: 'a' } });
publisher.schedule({ settings: { defaultMint: 'b' } });
publisher.schedule({ settings: { defaultMint: 'c' } });
await vi.advanceTimersByTimeAsync(999);
expect(published).toEqual([]);
await vi.advanceTimersByTimeAsync(1);
expect(published).toEqual([{ settings: { defaultMint: 'c' } }]);
});
it('publishes again when a change lands after the quiet window', async () => {
vi.useFakeTimers()
const published: Partial<BackupPartPayload>[] = []
vi.useFakeTimers();
const published: Partial<BackupPartPayload>[] = [];
const publisher = createBackupPublisher({
publish: (p) => {
published.push(p)
return Promise.resolve()
published.push(p);
return Promise.resolve();
},
delayMs: 1000,
})
});
publisher.schedule({settings: {defaultMint: 'a'}})
await vi.advanceTimersByTimeAsync(1000)
publisher.schedule({settings: {defaultMint: 'b'}})
await vi.advanceTimersByTimeAsync(1000)
expect(published).toEqual([{settings: {defaultMint: 'a'}}, {settings: {defaultMint: 'b'}}])
})
publisher.schedule({ settings: { defaultMint: 'a' } });
await vi.advanceTimersByTimeAsync(1000);
publisher.schedule({ settings: { defaultMint: 'b' } });
await vi.advanceTimersByTimeAsync(1000);
expect(published).toEqual([
{ settings: { defaultMint: 'a' } },
{ settings: { defaultMint: 'b' } },
]);
});
it('publishes a snapshot that lands mid-publish instead of losing it', async () => {
vi.useFakeTimers()
const published: Partial<BackupPartPayload>[] = []
vi.useFakeTimers();
const published: Partial<BackupPartPayload>[] = [];
// the publish callback re-schedules on the publisher being created -
// a holder indirection keeps both const
const holder: {publisher?: ReturnType<typeof createBackupPublisher>} = {}
const holder: { publisher?: ReturnType<typeof createBackupPublisher> } = {};
const publisher = createBackupPublisher({
publish: (p) => {
published.push(p)
published.push(p);
// a local change lands while the first publish is in flight
if (published.length === 1) {
holder.publisher?.schedule({settings: {defaultMint: 'mid-flight'}})
holder.publisher?.schedule({ settings: { defaultMint: 'mid-flight' } });
}
return Promise.resolve()
return Promise.resolve();
},
delayMs: 1000,
})
holder.publisher = publisher
});
holder.publisher = publisher;
publisher.schedule({settings: {defaultMint: 'first'}})
await vi.advanceTimersByTimeAsync(1000)
publisher.schedule({ settings: { defaultMint: 'first' } });
await vi.advanceTimersByTimeAsync(1000);
expect(published).toEqual([
{settings: {defaultMint: 'first'}},
{settings: {defaultMint: 'mid-flight'}},
])
})
{ settings: { defaultMint: 'first' } },
{ settings: { defaultMint: 'mid-flight' } },
]);
});
it('flush publishes immediately; cancel drops the pending snapshot', async () => {
vi.useFakeTimers()
const published: Partial<BackupPartPayload>[] = []
vi.useFakeTimers();
const published: Partial<BackupPartPayload>[] = [];
const publisher = createBackupPublisher({
publish: (p) => {
published.push(p)
return Promise.resolve()
published.push(p);
return Promise.resolve();
},
delayMs: 60_000,
})
});
publisher.schedule({settings: {defaultMint: 'a'}})
await publisher.flush()
expect(published).toEqual([{settings: {defaultMint: 'a'}}])
publisher.schedule({ settings: { defaultMint: 'a' } });
await publisher.flush();
expect(published).toEqual([{ settings: { defaultMint: 'a' } }]);
publisher.schedule({settings: {defaultMint: 'b'}})
publisher.cancel()
await vi.advanceTimersByTimeAsync(60_000)
expect(published).toHaveLength(1)
})
publisher.schedule({ settings: { defaultMint: 'b' } });
publisher.cancel();
await vi.advanceTimersByTimeAsync(60_000);
expect(published).toHaveLength(1);
});
it('reports a failed publish via onError and retries on the next change', async () => {
vi.useFakeTimers()
const published: Partial<BackupPartPayload>[] = []
const errors: unknown[] = []
let failing = true
vi.useFakeTimers();
const published: Partial<BackupPartPayload>[] = [];
const errors: unknown[] = [];
let failing = true;
const publisher = createBackupPublisher({
publish: (p) => {
if (failing) return Promise.reject(new Error('relay down'))
published.push(p)
return Promise.resolve()
if (failing) return Promise.reject(new Error('relay down'));
published.push(p);
return Promise.resolve();
},
delayMs: 1000,
onError: (e) => {
errors.push(e)
errors.push(e);
},
})
});
publisher.schedule({settings: {defaultMint: 'a'}})
await vi.advanceTimersByTimeAsync(1000)
expect(published).toEqual([])
expect(errors).toHaveLength(1)
publisher.schedule({ settings: { defaultMint: 'a' } });
await vi.advanceTimersByTimeAsync(1000);
expect(published).toEqual([]);
expect(errors).toHaveLength(1);
failing = false
publisher.schedule({settings: {defaultMint: 'b'}})
await vi.advanceTimersByTimeAsync(1000)
expect(published).toEqual([{settings: {defaultMint: 'b'}}])
})
})
failing = false;
publisher.schedule({ settings: { defaultMint: 'b' } });
await vi.advanceTimersByTimeAsync(1000);
expect(published).toEqual([{ settings: { defaultMint: 'b' } }]);
});
});
src/lnurlcash/nostrBackup.restore.cases.ts
+150 -126
View File
@@ -2,14 +2,19 @@
// tamper rejection, publish/fetch and restore against an in-memory relay
// (the transport is injected - no network), and the debounced publisher.
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import type {NostrEvent} from 'nostr-tools/core'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl} from 'lnurlcash-kit'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import type { NostrEvent } from 'nostr-tools/core';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl } from 'lnurlcash-kit';
import {deriveBearerAesKey, deriveWalletMaterial, linkingPubKeyHex, saveWalletMaterial} from './keys'
import {
deriveBearerAesKey,
deriveWalletMaterial,
linkingPubKeyHex,
saveWalletMaterial,
} from './keys';
import {
BACKUP_EVENT_KIND,
backupPubkey,
@@ -21,8 +26,8 @@ import {
parseBackupEvent,
publishBackup,
restoreFromNostr,
} from './nostrBackup'
import type {BackupPartPayload, BackupTransport} from './nostrBackup'
} from './nostrBackup';
import type { BackupPartPayload, BackupTransport } from './nostrBackup';
import {
loadBearers,
loadSettings,
@@ -31,29 +36,29 @@ import {
persistSettings,
readEncryptedBearers,
readNextByHost,
} from './storage'
import {readFundsDocument, writeFundsDocument} from './storage/bearers'
import type {Bearer} from './types'
import {addTrustedMint, isMintUnconfirmed, readTrustedMints} from './trustedMints'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './storage';
import { readFundsDocument, writeFundsDocument } from './storage/bearers';
import type { Bearer } from './types';
import { addTrustedMint, isMintUnconfirmed, readTrustedMints } from './trustedMints';
import { requiredValue, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_KEY = new Uint8Array(32).fill(9)
const OWNER_ID = linkingPubKeyHex(LINKING_KEY)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_KEY = new Uint8Array(32).fill(9);
const OWNER_ID = linkingPubKeyHex(LINKING_KEY);
// full v2 material for the fixed harness linking key (real BIP-32 cash root)
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const K1_A = 'aa'.repeat(32)
const K1_B = 'bb'.repeat(32)
const MINT_PUBKEY = 'ab'.repeat(33)
const K1_A = 'aa'.repeat(32);
const K1_B = 'bb'.repeat(32);
const MINT_PUBKEY = 'ab'.repeat(33);
// never connected - the recording transport below stands in for the relays
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example']
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example'];
const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
id: 'fixture',
@@ -64,20 +69,20 @@ const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
createdAt: 1000,
updatedAt: 1000,
...overrides,
})
});
// an in-memory relay set. It serves EVERY event it ever accepted, older
// addressable copies included - like a relay that never replaces - which
// is exactly the case fetchBackup's client-side latest-pick exists for
const createRecordingTransport = (): {
transport: BackupTransport
events: NostrEvent[]
transport: BackupTransport;
events: NostrEvent[];
} => {
const events: NostrEvent[] = []
const events: NostrEvent[] = [];
const transport: BackupTransport = {
publish: (_relays, event) => {
events.push(event)
return Promise.resolve()
events.push(event);
return Promise.resolve();
},
fetch: (_relays, filter) =>
Promise.resolve(
@@ -87,192 +92,211 @@ const createRecordingTransport = (): {
(!filter.authors || filter.authors.includes(e.pubkey)),
),
),
}
return {transport, events}
}
};
return { transport, events };
};
// flips the end of a base64 payload to different-but-valid characters
const tamperContent = (content: string): string =>
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA')
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA');
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
afterEach(() => {
vi.useRealTimers()
})
vi.useRealTimers();
});
describe('restoreFromNostr', () => {
it('restores notes, mints and settings onto a fresh device through applyBackup', async () => {
const aesKey = await deriveBearerAesKey(LINKING_KEY)
const secretKey = deriveBackupKey(LINKING_KEY)
const {transport} = createRecordingTransport()
const aesKey = await deriveBearerAesKey(LINKING_KEY);
const secretKey = deriveBackupKey(LINKING_KEY);
const { transport } = createRecordingTransport();
// device A: one note, one trusted mint, one setting - all published
await saveWalletMaterial(MATERIAL)
await persistBearer(aesKey, bearerFixture({id: 'note-a'}))
await addTrustedMint('mint.example', MINT_PUBKEY, {ownerId: OWNER_ID})
persistSettings({defaultMint: 'mint.example'})
await saveWalletMaterial(MATERIAL);
await persistBearer(aesKey, bearerFixture({ id: 'note-a' }));
await addTrustedMint('mint.example', MINT_PUBKEY, { ownerId: OWNER_ID });
persistSettings({ defaultMint: 'mint.example' });
await publishBackup(
secretKey,
{
notes: {bearers: readEncryptedBearers(), nextByHost: readNextByHost()},
notes: { bearers: readEncryptedBearers(), nextByHost: readNextByHost() },
mints: readTrustedMints(OWNER_ID),
settings: loadSettings(),
},
RELAYS,
{transport},
)
{ transport },
);
// device B: the same seed on empty storage
stubLocalStorage()
await saveWalletMaterial(MATERIAL)
const result = await restoreFromNostr(LINKING_KEY, RELAYS, {transport})
stubLocalStorage();
await saveWalletMaterial(MATERIAL);
const result = await restoreFromNostr(LINKING_KEY, RELAYS, { transport });
expect(result.found).toEqual(['notes', 'mints', 'settings'])
expect(result.added).toBe(1)
expect(result.trustedMintsAdded).toBe(1)
expect(result.settingsRestored).toBe(true)
expect(result.found).toEqual(['notes', 'mints', 'settings']);
expect(result.added).toBe(1);
expect(result.trustedMintsAdded).toBe(1);
expect(result.settingsRestored).toBe(true);
// the linking key is never part of a nostr backup - the seed phrase
// the holder entered is its recovery path
expect(result.linkingKeyRestored).toBe(false)
expect(result.linkingKeyRestored).toBe(false);
// the note decrypts under this device's bearer key - same seed
expect(await loadBearers(aesKey)).toEqual([bearerFixture({id: 'note-a'})])
expect(loadSettings()).toEqual({defaultMint: 'mint.example'})
expect(await loadBearers(aesKey)).toEqual([bearerFixture({ id: 'note-a' })]);
expect(loadSettings()).toEqual({ defaultMint: 'mint.example' });
// a file/backup-sourced mint pin stays unconfirmed until a live
// response corroborates it - nostr restore inherits that rule from
// applyBackup unchanged
expect(isMintUnconfirmed('mint.example', OWNER_ID)).toBe(true)
})
expect(isMintUnconfirmed('mint.example', OWNER_ID)).toBe(true);
});
it('unions records by id and lets a spent copy win after decrypt', async () => {
const aesKey = await deriveBearerAesKey(LINKING_KEY)
const secretKey = deriveBackupKey(LINKING_KEY)
const {transport} = createRecordingTransport()
const aesKey = await deriveBearerAesKey(LINKING_KEY);
const secretKey = deriveBackupKey(LINKING_KEY);
const { transport } = createRecordingTransport();
// device A publishes its store holding the spendable note
await persistBearer(aesKey, bearerFixture({id: 'rec-a'}))
await publishBackup(secretKey, {notes: {bearers: readEncryptedBearers(), nextByHost: readNextByHost()}}, RELAYS, {
transport,
createdAt: 1000,
})
await persistBearer(aesKey, bearerFixture({ id: 'rec-a' }));
await publishBackup(
secretKey,
{ notes: { bearers: readEncryptedBearers(), nextByHost: readNextByHost() } },
RELAYS,
{
transport,
createdAt: 1000,
},
);
// device B restores, then marks the same note spent under its OWN
// record id, and republishes its full store
stubLocalStorage()
await restoreFromNostr(LINKING_KEY, RELAYS, {transport})
await persistBearer(aesKey, bearerFixture({id: 'rec-b', spent: true, updatedAt: 2000}))
await publishBackup(secretKey, {notes: {bearers: readEncryptedBearers(), nextByHost: readNextByHost()}}, RELAYS, {
transport,
createdAt: 2000,
})
stubLocalStorage();
await restoreFromNostr(LINKING_KEY, RELAYS, { transport });
await persistBearer(aesKey, bearerFixture({ id: 'rec-b', spent: true, updatedAt: 2000 }));
await publishBackup(
secretKey,
{ notes: { bearers: readEncryptedBearers(), nextByHost: readNextByHost() } },
RELAYS,
{
transport,
createdAt: 2000,
},
);
// device C restores from the final published state
stubLocalStorage()
const result = await restoreFromNostr(LINKING_KEY, RELAYS, {transport})
stubLocalStorage();
const result = await restoreFromNostr(LINKING_KEY, RELAYS, { transport });
// union by record id: both copies landed
expect(result.added).toBe(2)
expect(result.added).toBe(2);
expect(
readEncryptedBearers()
.map((r) => r.id)
.sort(),
).toEqual(['rec-a', 'rec-b'])
).toEqual(['rec-a', 'rec-b']);
// after decrypt, the note-level merge (same server + k1) collapses
// them, and the spent copy wins even though its record is the newer
// arrival - a restored backup must never resurrect spendable money
const merged = mergeBearers([], await loadBearers(aesKey))
expect(merged).toHaveLength(1)
expect(requiredValue(merged[0]).id).toBe('rec-b')
expect(requiredValue(merged[0]).spent).toBe(true)
})
const merged = mergeBearers([], await loadBearers(aesKey));
expect(merged).toHaveLength(1);
expect(requiredValue(merged[0]).id).toBe('rec-b');
expect(requiredValue(merged[0]).spent).toBe(true);
});
it('never overwrites local state: records union, settings keep local values', async () => {
const aesKey = await deriveBearerAesKey(LINKING_KEY)
const secretKey = deriveBackupKey(LINKING_KEY)
const {transport} = createRecordingTransport()
const aesKey = await deriveBearerAesKey(LINKING_KEY);
const secretKey = deriveBackupKey(LINKING_KEY);
const { transport } = createRecordingTransport();
await persistBearer(aesKey, bearerFixture({id: 'remote'}))
persistSettings({defaultMint: 'remote.example'})
await persistBearer(aesKey, bearerFixture({ id: 'remote' }));
persistSettings({ defaultMint: 'remote.example' });
await publishBackup(
secretKey,
{notes: {bearers: readEncryptedBearers(), nextByHost: readNextByHost()}, settings: loadSettings()},
{
notes: { bearers: readEncryptedBearers(), nextByHost: readNextByHost() },
settings: loadSettings(),
},
RELAYS,
{transport, createdAt: 1000},
)
{ transport, createdAt: 1000 },
);
// this device already has its own wallet state
stubLocalStorage()
stubLocalStorage();
await persistBearer(
aesKey,
bearerFixture({id: 'local', url: buildNoteUrl('https://mint.example/w', K1_B, 5_000)}),
)
persistSettings({defaultMint: 'local.example'})
bearerFixture({ id: 'local', url: buildNoteUrl('https://mint.example/w', K1_B, 5_000) }),
);
persistSettings({ defaultMint: 'local.example' });
const result = await restoreFromNostr(LINKING_KEY, RELAYS, {transport})
expect(result.added).toBe(1)
const result = await restoreFromNostr(LINKING_KEY, RELAYS, { transport });
expect(result.added).toBe(1);
expect(
readEncryptedBearers()
.map((r) => r.id)
.sort(),
).toEqual(['local', 'remote'])
expect(result.settingsRestored).toBe(false)
expect(loadSettings()).toEqual({defaultMint: 'local.example'})
})
).toEqual(['local', 'remote']);
expect(result.settingsRestored).toBe(false);
expect(loadSettings()).toEqual({ defaultMint: 'local.example' });
});
it('reports nothing found when the relays hold no backup', async () => {
const {transport} = createRecordingTransport()
const result = await restoreFromNostr(LINKING_KEY, RELAYS, {transport})
expect(result.found).toEqual([])
expect(result.added).toBe(0)
})
const { transport } = createRecordingTransport();
const result = await restoreFromNostr(LINKING_KEY, RELAYS, { transport });
expect(result.found).toEqual([]);
expect(result.added).toBe(0);
});
it('merges relayed counters upward-only and never carries pending state', async () => {
const aesKey = await deriveBearerAesKey(LINKING_KEY)
const secretKey = deriveBackupKey(LINKING_KEY)
const {transport} = createRecordingTransport()
const aesKey = await deriveBearerAesKey(LINKING_KEY);
const secretKey = deriveBackupKey(LINKING_KEY);
const { transport } = createRecordingTransport();
// device A: counter at 5 for mint.example, one note, all published
await persistBearer(aesKey, bearerFixture({id: 'note-a'}))
await persistBearer(aesKey, bearerFixture({ id: 'note-a' }));
writeFundsDocument({
version: 2,
bearers: readEncryptedBearers(),
pending: [
{id: 'device-local-pending', kind: 'cash-allocation', phase: 'reserved', iv: '00', ciphertext: '00'},
{
id: 'device-local-pending',
kind: 'cash-allocation',
phase: 'reserved',
iv: '00',
ciphertext: '00',
},
],
nextByHost: {'mint.example': 5},
nextByHost: { 'mint.example': 5 },
revision: 3,
})
});
await publishBackup(
secretKey,
{notes: {bearers: readEncryptedBearers(), nextByHost: readNextByHost()}},
{ notes: { bearers: readEncryptedBearers(), nextByHost: readNextByHost() } },
RELAYS,
{transport, createdAt: 1000},
)
{ transport, createdAt: 1000 },
);
// device B: same seed, a HIGHER local counter for one host and a lower
// incoming one for the other; the pending record must not cross over
stubLocalStorage()
stubLocalStorage();
writeFundsDocument({
version: 2,
bearers: [],
pending: [],
nextByHost: {'mint.example': 2, 'local-only.example': 7},
nextByHost: { 'mint.example': 2, 'local-only.example': 7 },
revision: 1,
})
});
const result = await restoreFromNostr(LINKING_KEY, RELAYS, {transport})
const result = await restoreFromNostr(LINKING_KEY, RELAYS, { transport });
expect(result.found).toEqual(['notes'])
expect(result.added).toBe(1)
expect(result.found).toEqual(['notes']);
expect(result.added).toBe(1);
expect(readFundsDocument().nextByHost).toEqual({
'mint.example': 5,
'local-only.example': 7,
})
expect(readFundsDocument().pending).toEqual([])
expect(await loadBearers(aesKey)).toEqual([bearerFixture({id: 'note-a'})])
})
})
});
expect(readFundsDocument().pending).toEqual([]);
expect(await loadBearers(aesKey)).toEqual([bearerFixture({ id: 'note-a' })]);
});
});
src/lnurlcash/nostrBackup.test.ts
+5 -5
View File
@@ -1,5 +1,5 @@
import './nostrBackup.keys.cases'
import './nostrBackup.codec.cases'
import './nostrBackup.transport.cases'
import './nostrBackup.restore.cases'
import './nostrBackup.publisher.cases'
import './nostrBackup.keys.cases';
import './nostrBackup.codec.cases';
import './nostrBackup.transport.cases';
import './nostrBackup.restore.cases';
import './nostrBackup.publisher.cases';
src/lnurlcash/nostrBackup.transport.cases.ts
+68 -68
View File
@@ -2,14 +2,14 @@
// tamper rejection, publish/fetch and restore against an in-memory relay
// (the transport is injected - no network), and the debounced publisher.
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import type {NostrEvent} from 'nostr-tools/core'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl} from 'lnurlcash-kit'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import type { NostrEvent } from 'nostr-tools/core';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl } from 'lnurlcash-kit';
import {deriveBearerAesKey, linkingPubKeyHex, saveLinkingKey} from './keys'
import { deriveBearerAesKey, linkingPubKeyHex, saveLinkingKey } from './keys';
import {
BACKUP_EVENT_KIND,
backupPubkey,
@@ -21,8 +21,8 @@ import {
parseBackupEvent,
publishBackup,
restoreFromNostr,
} from './nostrBackup'
import type {BackupPartPayload, BackupTransport} from './nostrBackup'
} from './nostrBackup';
import type { BackupPartPayload, BackupTransport } from './nostrBackup';
import {
loadBearers,
loadSettings,
@@ -30,21 +30,21 @@ import {
persistBearer,
persistSettings,
readEncryptedBearers,
} from './storage'
import type {Bearer} from './types'
import {addTrustedMint, isMintUnconfirmed, readTrustedMints} from './trustedMints'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './storage';
import type { Bearer } from './types';
import { addTrustedMint, isMintUnconfirmed, readTrustedMints } from './trustedMints';
import { requiredValue, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_KEY = new Uint8Array(32).fill(9)
const OWNER_ID = linkingPubKeyHex(LINKING_KEY)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_KEY = new Uint8Array(32).fill(9);
const OWNER_ID = linkingPubKeyHex(LINKING_KEY);
const K1_A = 'aa'.repeat(32)
const K1_B = 'bb'.repeat(32)
const MINT_PUBKEY = 'ab'.repeat(33)
const K1_A = 'aa'.repeat(32);
const K1_B = 'bb'.repeat(32);
const MINT_PUBKEY = 'ab'.repeat(33);
// never connected - the recording transport below stands in for the relays
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example']
const RELAYS = ['wss://relay-a.example', 'wss://relay-b.example'];
const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
id: 'fixture',
@@ -55,20 +55,20 @@ const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
createdAt: 1000,
updatedAt: 1000,
...overrides,
})
});
// an in-memory relay set. It serves EVERY event it ever accepted, older
// addressable copies included - like a relay that never replaces - which
// is exactly the case fetchBackup's client-side latest-pick exists for
const createRecordingTransport = (): {
transport: BackupTransport
events: NostrEvent[]
transport: BackupTransport;
events: NostrEvent[];
} => {
const events: NostrEvent[] = []
const events: NostrEvent[] = [];
const transport: BackupTransport = {
publish: (_relays, event) => {
events.push(event)
return Promise.resolve()
events.push(event);
return Promise.resolve();
},
fetch: (_relays, filter) =>
Promise.resolve(
@@ -78,86 +78,86 @@ const createRecordingTransport = (): {
(!filter.authors || filter.authors.includes(e.pubkey)),
),
),
}
return {transport, events}
}
};
return { transport, events };
};
// flips the end of a base64 payload to different-but-valid characters
const tamperContent = (content: string): string =>
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA')
content.slice(0, -4) + (content.endsWith('AAAA') ? 'BBBB' : 'AAAA');
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
afterEach(() => {
vi.useRealTimers()
})
vi.useRealTimers();
});
describe('publishBackup / fetchBackup', () => {
const secretKey = deriveBackupKey(LINKING_KEY)
const secretKey = deriveBackupKey(LINKING_KEY);
it('publishes every part and fetches them back decrypted', async () => {
const {transport} = createRecordingTransport()
const { transport } = createRecordingTransport();
const parts = {
notes: {
bearers: [{id: 'r1', iv: '00'.repeat(12), ciphertext: 'ab'.repeat(40)}],
nextByHost: {'mint.example': 2},
bearers: [{ id: 'r1', iv: '00'.repeat(12), ciphertext: 'ab'.repeat(40) }],
nextByHost: { 'mint.example': 2 },
},
mints: [{server: 'mint.example', mintPubkey: MINT_PUBKEY, addedAt: 1000, locked: false}],
settings: {defaultMint: 'mint.example'},
}
const published = await publishBackup(secretKey, parts, RELAYS, {transport})
expect(published.published).toEqual(['notes', 'mints', 'settings'])
mints: [{ server: 'mint.example', mintPubkey: MINT_PUBKEY, addedAt: 1000, locked: false }],
settings: { defaultMint: 'mint.example' },
};
const published = await publishBackup(secretKey, parts, RELAYS, { transport });
expect(published.published).toEqual(['notes', 'mints', 'settings']);
const fetched = await fetchBackup(backupPubkey(secretKey), RELAYS, {
secretKey,
transport,
})
expect(fetched).toEqual(parts)
})
});
expect(fetched).toEqual(parts);
});
it('publishes nothing when no parts are given', async () => {
const {transport, events} = createRecordingTransport()
const result = await publishBackup(secretKey, {}, RELAYS, {transport})
expect(result.published).toEqual([])
expect(events).toEqual([])
})
const { transport, events } = createRecordingTransport();
const result = await publishBackup(secretKey, {}, RELAYS, { transport });
expect(result.published).toEqual([]);
expect(events).toEqual([]);
});
it('picks the newest event per d-tag when a relay serves stale copies', async () => {
const {transport} = createRecordingTransport()
await publishBackup(secretKey, {settings: {defaultMint: 'old.example'}}, RELAYS, {
const { transport } = createRecordingTransport();
await publishBackup(secretKey, { settings: { defaultMint: 'old.example' } }, RELAYS, {
transport,
createdAt: 1000,
})
await publishBackup(secretKey, {settings: {defaultMint: 'new.example'}}, RELAYS, {
});
await publishBackup(secretKey, { settings: { defaultMint: 'new.example' } }, RELAYS, {
transport,
createdAt: 2000,
})
});
// the recording transport serves BOTH - the newer must win
const parts = await fetchBackup(backupPubkey(secretKey), RELAYS, {
secretKey,
transport,
})
expect(parts.settings).toEqual({defaultMint: 'new.example'})
})
});
expect(parts.settings).toEqual({ defaultMint: 'new.example' });
});
it('falls back to an older valid copy when the newest event is tampered', async () => {
const {transport, events} = createRecordingTransport()
await publishBackup(secretKey, {settings: {defaultMint: 'mint.example'}}, RELAYS, {
const { transport, events } = createRecordingTransport();
await publishBackup(secretKey, { settings: { defaultMint: 'mint.example' } }, RELAYS, {
transport,
createdAt: 1000,
})
const latest = requiredValue(events[0])
});
const latest = requiredValue(events[0]);
events.push({
...latest,
content: tamperContent(latest.content),
created_at: 3000,
})
});
const parts = await fetchBackup(backupPubkey(secretKey), RELAYS, {
secretKey,
transport,
})
expect(parts.settings).toEqual({defaultMint: 'mint.example'})
})
})
});
expect(parts.settings).toEqual({ defaultMint: 'mint.example' });
});
});
src/lnurlcash/nostrBackup.ts
+7 -7
View File
@@ -25,18 +25,18 @@ export {
buildBackupEvent,
buildBackupEvents,
parseBackupEvent,
} from './nostr/events'
export type {NostrEvent, BackupPart, BackupPartPayload, ParsedBackupEvent} from './nostr/events'
} from './nostr/events';
export type { NostrEvent, BackupPart, BackupPartPayload, ParsedBackupEvent } from './nostr/events';
export type {BackupTransport, NostrFilter} from './nostr/transport'
export type { BackupTransport, NostrFilter } from './nostr/transport';
export {publishBackup, fetchBackup, restoreFromNostr} from './nostr/sync'
export { publishBackup, fetchBackup, restoreFromNostr } from './nostr/sync';
export type {
PublishBackupOptions,
PublishBackupResult,
FetchBackupOptions,
NostrRestoreResult,
} from './nostr/sync'
} from './nostr/sync';
export {createBackupPublisher} from './nostr/publisher'
export type {BackupPublisher, BackupPublisherOptions} from './nostr/publisher'
export { createBackupPublisher } from './nostr/publisher';
export type { BackupPublisher, BackupPublisherOptions } from './nostr/publisher';
src/lnurlcash/nwc.connection.cases.ts
+48 -48
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,13 +29,13 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredValue, stubLocalStorage } from './test-utils';
import {
CLIENT_PUBKEY,
@@ -55,90 +55,90 @@ import {
nowSeconds,
storeForeignConnection,
waitFor,
} from './nwc.testProtocol'
import {call, makeBearer, mint, readResponse, startTestService} from './nwc.testService'
} from './nwc.testProtocol';
import { call, makeBearer, mint, readResponse, startTestService } from './nwc.testService';
describe('connection strings', () => {
it('round-trips build -> parse, including several relays', () => {
const uri = buildConnectionString('ab'.repeat(32), 'cd'.repeat(32), [
'wss://relay-a.example',
'wss://relay-b.example/path?q=1',
])
]);
expect(uri).toBe(
`nostr+walletconnect://${'ab'.repeat(32)}?relay=${encodeURIComponent('wss://relay-a.example')}&relay=${encodeURIComponent('wss://relay-b.example/path?q=1')}&secret=${'cd'.repeat(32)}`,
)
);
expect(parseConnectionString(uri)).toEqual({
walletServicePubkey: 'ab'.repeat(32),
clientSecret: 'cd'.repeat(32),
relays: ['wss://relay-a.example', 'wss://relay-b.example/path?q=1'],
})
})
});
});
it('rejects strings that are not connection strings', () => {
expect(parseConnectionString('not a uri')).toBeNull()
expect(parseConnectionString('https://example.com')).toBeNull()
expect(parseConnectionString('not a uri')).toBeNull();
expect(parseConnectionString('https://example.com')).toBeNull();
// missing secret
expect(
parseConnectionString(`nostr+walletconnect://${'ab'.repeat(32)}?relay=wss%3A%2F%2Fr.example`),
).toBeNull()
).toBeNull();
// missing relay
expect(
parseConnectionString(`nostr+walletconnect://${'ab'.repeat(32)}?secret=${'cd'.repeat(32)}`),
).toBeNull()
).toBeNull();
// a non-hex pubkey
expect(
parseConnectionString(
'nostr+walletconnect://zzzz?relay=wss%3A%2F%2Fr.example&secret=' + 'cd'.repeat(32),
),
).toBeNull()
})
).toBeNull();
});
it('createConnection returns a string that parses back to the same connection', () => {
const connection = createConnection(LINKING_KEY, {
relays: RELAYS,
budget: {maxMsat: 100_000, periodMs: 86_400_000},
budget: { maxMsat: 100_000, periodMs: 86_400_000 },
clientSecret: CLIENT_SECRET,
})
const parsed = parseConnectionString(connection.connectionString)
});
const parsed = parseConnectionString(connection.connectionString);
expect(parsed).toEqual({
walletServicePubkey: connection.walletServicePubkey,
clientSecret: '11'.repeat(32),
relays: RELAYS,
})
});
// the record persisted WITHOUT the client secret - it is handed out
// once, in the connection string, and never stored
const records = readNwcConnections(OWNER_ID)
expect(records).toHaveLength(1)
expect(requiredValue(records[0]).clientPubkey).toBe(CLIENT_PUBKEY)
expect(JSON.stringify(records[0])).not.toContain('11'.repeat(32))
})
})
const records = readNwcConnections(OWNER_ID);
expect(records).toHaveLength(1);
expect(requiredValue(records[0]).clientPubkey).toBe(CLIENT_PUBKEY);
expect(JSON.stringify(records[0])).not.toContain('11'.repeat(32));
});
});
describe('deriveNwcWalletKey', () => {
it('is pinned: derivation changes would silently orphan every connection', () => {
expect(bytesToHex(deriveNwcWalletKey(LINKING_KEY, CLIENT_PUBKEY))).toBe(
'71428fc3d77c75f9dc70037283fbed5407cecc44eab56873986a33c24c3e034d',
)
);
expect(getPublicKey(deriveNwcWalletKey(LINKING_KEY, CLIENT_PUBKEY))).toBe(
'bf02224dc973a24466ded285c24fb5baf78352b0a2364de7a15b0263fc048bcf',
)
})
);
});
it('derives a distinct key per client and per linking key', () => {
const base = bytesToHex(deriveNwcWalletKey(LINKING_KEY, CLIENT_PUBKEY))
const base = bytesToHex(deriveNwcWalletKey(LINKING_KEY, CLIENT_PUBKEY));
expect(bytesToHex(deriveNwcWalletKey(LINKING_KEY, getPublicKey(STRANGER_SECRET)))).not.toBe(
base,
)
expect(bytesToHex(deriveNwcWalletKey(OTHER_LINKING_KEY, CLIENT_PUBKEY))).not.toBe(base)
})
);
expect(bytesToHex(deriveNwcWalletKey(OTHER_LINKING_KEY, CLIENT_PUBKEY))).not.toBe(base);
});
it('re-derives the same wallet identity from a persisted record after a reinstall', () => {
const first = createConnection(LINKING_KEY, {
relays: RELAYS,
budget: {maxMsat: 100_000, periodMs: 86_400_000},
budget: { maxMsat: 100_000, periodMs: 86_400_000 },
clientSecret: CLIENT_SECRET,
})
});
expect(first.walletServicePubkey).toBe(
'bf02224dc973a24466ded285c24fb5baf78352b0a2364de7a15b0263fc048bcf',
)
})
})
);
});
});
src/lnurlcash/nwc.fencing.cases.ts
+26 -26
View File
@@ -4,29 +4,29 @@
// no longer possible. What must not happen is any stale-owner WRITE:
// no bearer changeset, no budget debit, no success response.
import {describe, expect, it} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import { describe, expect, it } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import {readNwcConnections} from './nwc'
import { readNwcConnections } from './nwc';
import {
methodRequest,
OTHER_LINKING_KEY,
OTHER_OWNER_ID,
OWNER_ID,
waitFor,
} from './nwc.testProtocol'
import {makeBearer, mint, readResponse, startTestService} from './nwc.testService'
} from './nwc.testProtocol';
import { makeBearer, mint, readResponse, startTestService } from './nwc.testService';
describe('service: post-boundary stale-owner fencing', () => {
it('makes no stale-owner writes when the saved key is replaced mid-melt', async () => {
// Given a running service whose next mint call coincides with a second
// tab installing its own wallet (the first fetch is the melt itself:
// the exact-match carve performs no mint call of its own)
const m = await mint()
let swapped = false
const m = await mint();
let swapped = false;
const swappingFetch: typeof fetch = (input, init) => {
if (!swapped) {
swapped = true
swapped = true;
localStorage.setItem(
'sattle_linking_key',
JSON.stringify({
@@ -35,32 +35,32 @@ describe('service: post-boundary stale-owner fencing', () => {
ownerId: OTHER_OWNER_ID,
version: 1,
}),
)
);
}
return fetch(input, init)
}
const {relay, walletServicePubkey, state, stop} = await startTestService({
kit: {fetch: swappingFetch},
})
state.bearers = [await makeBearer(m, 'd7'.repeat(32), 21_000)]
return fetch(input, init);
};
const { relay, walletServicePubkey, state, stop } = await startTestService({
kit: { fetch: swappingFetch },
});
state.bearers = [await makeBearer(m, 'd7'.repeat(32), 21_000)];
const request = methodRequest(walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
});
// When the pay flows past the irreversible boundary and reaches the
// first owner-bound persistence (the conservative budget debit)
relay.emit(request)
await waitFor(() => state.errors.length > 0)
relay.emit(request);
await waitFor(() => state.errors.length > 0);
// Then the melt genuinely happened (we are past the boundary) ...
expect(swapped).toBe(true)
expect(m.state.noteState('d7'.repeat(32))).toBe('burned')
expect(swapped).toBe(true);
expect(m.state.noteState('d7'.repeat(32))).toBe('burned');
// ... but nothing under the stale owner moved: no budget debit, no
// bearer changeset, no success response (the failure surfaced through
// onError instead)
expect(readNwcConnections(OWNER_ID)[0]?.spent.msat).toBe(0)
expect(state.changesets).toEqual([])
expect(readResponse(relay.published, request.id, 'nip44_v2')).toBeNull()
await stop()
})
})
expect(readNwcConnections(OWNER_ID)[0]?.spent.msat).toBe(0);
expect(state.changesets).toEqual([]);
expect(readResponse(relay.published, request.id, 'nip44_v2')).toBeNull();
await stop();
});
});
src/lnurlcash/nwc.invoice-a.cases.ts
+112 -112
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, hashK1, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, hashK1, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,13 +29,13 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredString, requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredString, requiredValue, stubLocalStorage } from './test-utils';
import {
CLIENT_PUBKEY,
@@ -55,36 +55,36 @@ import {
nowSeconds,
storeForeignConnection,
waitFor,
} from './nwc.testProtocol'
import {call, makeBearer, mint, readResponse, startTestService} from './nwc.testService'
import {invoiceRetireAfter} from './nwc/invoices'
} from './nwc.testProtocol';
import { call, makeBearer, mint, readResponse, startTestService } from './nwc.testService';
import { invoiceRetireAfter } from './nwc/invoices';
export const SIGNED_BOLT11_FIXTURE =
'lnbc250n1p4f4d2ysp5s7pqe2590jtlgpqyzw82m4xtn5wpkehf8jt4fcj754p4s2nf3r3qpp5d2zdf3satrdk5qllx00hwah5tlg69h90w5s78flfg8ffq4fagalsdqhd3h82unvvdshx6pqd45kuaqxqyjw5qcqpjrzjqwda3lfx6jhqd33847rqkfclpnyfv9f74pavem0mtvhdyzlam4lnkr83hqqq55cqqyqqqqqqqqqqzsqq9q9qxpqysgql3u9h88pw0pnfqdqh5hdgstgc8gazln7xeleuu7elmw7ea6q488js0mqwchtcq7rphv9uc3q5yqllx6ksdw8yjfq5e9jcgarlqzrk6gq5ksjdz'
'lnbc250n1p4f4d2ysp5s7pqe2590jtlgpqyzw82m4xtn5wpkehf8jt4fcj754p4s2nf3r3qpp5d2zdf3satrdk5qllx00hwah5tlg69h90w5s78flfg8ffq4fagalsdqhd3h82unvvdshx6pqd45kuaqxqyjw5qcqpjrzjqwda3lfx6jhqd33847rqkfclpnyfv9f74pavem0mtvhdyzlam4lnkr83hqqq55cqqyqqqqqqqqqqzsqq9q9qxpqysgql3u9h88pw0pnfqdqh5hdgstgc8gazln7xeleuu7elmw7ea6q488js0mqwchtcq7rphv9uc3q5yqllx6ksdw8yjfq5e9jcgarlqzrk6gq5ksjdz';
describe('service: make_invoice / lookup_invoice', () => {
it('derives a safe retirement time from a signed BOLT11 invoice', () => {
expect(invoiceRetireAfter(SIGNED_BOLT11_FIXTURE)).toBeGreaterThan(0)
})
expect(invoiceRetireAfter(SIGNED_BOLT11_FIXTURE)).toBeGreaterThan(0);
});
it('rejects a retirement time outside the safe integer range', () => {
const timestamp = 'q'.repeat(7)
const expiryTag = `xqv${'l'.repeat(12)}`
expect(invoiceRetireAfter(`lnbc1${timestamp}${expiryTag}qqqqqq`)).toBeNull()
})
const timestamp = 'q'.repeat(7);
const expiryTag = `xqv${'l'.repeat(12)}`;
expect(invoiceRetireAfter(`lnbc1${timestamp}${expiryTag}qqqqqq`)).toBeNull();
});
it('stages an output, settles it in the background, and reports the preimage', async () => {
const m = await mint({testHooks: true})
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
})
});
const made = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 21_000,
description: 'nwc test',
expiry: 3600,
})
expect(made.error).toBeNull()
});
expect(made.error).toBeNull();
expect(made.result).toMatchObject({
type: 'incoming',
state: 'pending',
@@ -92,131 +92,131 @@ describe('service: make_invoice / lookup_invoice', () => {
description: 'nwc test',
created_at: nowSeconds(),
expires_at: nowSeconds() + 3600,
})
const invoice = requiredValue(made.result).invoice
});
const invoice = requiredValue(made.result).invoice;
if (typeof invoice !== 'string') {
throw new TypeError('make_invoice did not return an invoice')
throw new TypeError('make_invoice did not return an invoice');
}
const paymentHash = made.result?.payment_hash
const paymentHash = made.result?.payment_hash;
if (typeof paymentHash !== 'string') {
throw new TypeError('make_invoice did not return a payment hash')
throw new TypeError('make_invoice did not return a payment hash');
}
expect(invoice).toMatch(/^lnbc/)
expect(paymentHash).toMatch(/^[0-9a-f]{64}$/)
const staged = requiredValue(state.bearers.find((bearer) => bearer.id.startsWith('staged-')))
expect(staged.verified).toBe(false)
expect(staged.callback).toBe('')
expect(invoice).toMatch(/^lnbc/);
expect(paymentHash).toMatch(/^[0-9a-f]{64}$/);
const staged = requiredValue(state.bearers.find((bearer) => bearer.id.startsWith('staged-')));
expect(staged.verified).toBe(false);
expect(staged.callback).toBe('');
// before settlement the lookup reports the pending invoice
const pending = await call(relay, walletServicePubkey, 'lookup_invoice', {
payment_hash: paymentHash,
})
expect(pending.error).toBeNull()
expect(pending.result?.state).toBe('pending')
expect(pending.result?.preimage).toBeUndefined()
});
expect(pending.error).toBeNull();
expect(pending.result?.state).toBe('pending');
expect(pending.result?.preimage).toBeUndefined();
// the "payer" pays the invoice; the background claim settles and
// mints the note
const settleRes = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`)
expect(settleRes.ok).toBe(true)
await waitFor(() => state.bearers.some((bearer) => bearer.verified))
const settleRes = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`);
expect(settleRes.ok).toBe(true);
await waitFor(() => state.bearers.some((bearer) => bearer.verified));
const settled = await call(relay, walletServicePubkey, 'lookup_invoice', {
payment_hash: paymentHash,
})
expect(settled.error).toBeNull()
expect(settled.result?.state).toBe('settled')
expect(settled.result?.settled_at).toBe(nowSeconds())
const preimage = requiredString(settled.result?.preimage)
expect(preimage).toMatch(/^[0-9a-f]{64}$/)
});
expect(settled.error).toBeNull();
expect(settled.result?.state).toBe('settled');
expect(settled.result?.settled_at).toBe(nowSeconds());
const preimage = requiredString(settled.result?.preimage);
expect(preimage).toMatch(/^[0-9a-f]{64}$/);
// The staged record was updated in place before settlement became
// visible. The payment preimage is only a receipt and keys no note.
expect(m.state.noteState(preimage)).toBeNull()
const minted = requiredValue(state.bearers.find((b) => b.id === staged.id))
expect(minted.amount).toBe(21_000)
expect(minted.verified).toBe(true)
expect(noteK1(minted.url)).not.toBe(preimage)
expect(m.state.noteState(requiredValue(noteK1(minted.url)))).toBe('outstanding')
await stop()
})
expect(m.state.noteState(preimage)).toBeNull();
const minted = requiredValue(state.bearers.find((b) => b.id === staged.id));
expect(minted.amount).toBe(21_000);
expect(minted.verified).toBe(true);
expect(noteK1(minted.url)).not.toBe(preimage);
expect(m.state.noteState(requiredValue(noteK1(minted.url)))).toBe('outstanding');
await stop();
});
it('keeps a paid invoice pending while its bearer commit is deferred', async () => {
const m = await mint({testHooks: true})
const commit = deferred()
let commitStarted = false
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
const commit = deferred();
let commitStarted = false;
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
commitChangeset: () => {
commitStarted = true
return commit.promise
commitStarted = true;
return commit.promise;
},
})
});
const made = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 21_000,
})
const paymentHash = made.result?.payment_hash
});
const paymentHash = made.result?.payment_hash;
if (typeof paymentHash !== 'string') {
throw new TypeError('make_invoice did not return a payment hash')
throw new TypeError('make_invoice did not return a payment hash');
}
const settleResponse = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`)
expect(settleResponse.ok).toBe(true)
await waitFor(() => commitStarted)
const settleResponse = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`);
expect(settleResponse.ok).toBe(true);
await waitFor(() => commitStarted);
const pending = await call(relay, walletServicePubkey, 'lookup_invoice', {
payment_hash: paymentHash,
})
expect(pending.result?.state).toBe('pending')
expect(pending.result?.settled_at).toBeUndefined()
expect(pending.result?.preimage).toBeUndefined()
});
expect(pending.result?.state).toBe('pending');
expect(pending.result?.settled_at).toBeUndefined();
expect(pending.result?.preimage).toBeUndefined();
commit.resolve()
await waitFor(() => state.changesets.length === 1)
commit.resolve();
await waitFor(() => state.changesets.length === 1);
const settled = await call(relay, walletServicePubkey, 'lookup_invoice', {
payment_hash: paymentHash,
})
expect(settled.result?.state).toBe('settled')
expect(settled.result?.settled_at).toBe(nowSeconds())
expect(settled.result?.preimage).toMatch(/^[0-9a-f]{64}$/)
await stop()
})
});
expect(settled.result?.state).toBe('settled');
expect(settled.result?.settled_at).toBe(nowSeconds());
expect(settled.result?.preimage).toMatch(/^[0-9a-f]{64}$/);
await stop();
});
it('keeps repeated stops pending until an already-started invoice settlement commits', async () => {
const m = await mint({testHooks: true})
const commit = deferred()
let commitStarted = false
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
const commit = deferred();
let commitStarted = false;
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
commitChangeset: () => {
commitStarted = true
return commit.promise
commitStarted = true;
return commit.promise;
},
})
});
const made = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 21_000,
})
const paymentHash = made.result?.payment_hash
});
const paymentHash = made.result?.payment_hash;
if (typeof paymentHash !== 'string') {
throw new TypeError('make_invoice did not return a payment hash')
throw new TypeError('make_invoice did not return a payment hash');
}
const settleResponse = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`)
expect(settleResponse.ok).toBe(true)
await waitFor(() => commitStarted)
const settleResponse = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`);
expect(settleResponse.ok).toBe(true);
await waitFor(() => commitStarted);
let stopped = false
let stopped = false;
const firstStop = stop().then(() => {
stopped = true
return state.changesets.length
})
const repeatedStop = stop()
for (let turn = 0; turn < 10; turn += 1) await Promise.resolve()
stopped = true;
return state.changesets.length;
});
const repeatedStop = stop();
for (let turn = 0; turn < 10; turn += 1) await Promise.resolve();
expect(stopped).toBe(false)
expect(state.changesets).toHaveLength(0)
expect(stopped).toBe(false);
expect(state.changesets).toHaveLength(0);
commit.resolve()
const [changesetsAtStop] = await Promise.all([firstStop, repeatedStop])
expect(changesetsAtStop).toBe(1)
expect(state.changesets).toHaveLength(1)
})
})
commit.resolve();
const [changesetsAtStop] = await Promise.all([firstStop, repeatedStop]);
expect(changesetsAtStop).toBe(1);
expect(state.changesets).toHaveLength(1);
});
});
src/lnurlcash/nwc.invoice-b.cases.ts
+163 -171
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,13 +29,13 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredValue, stubLocalStorage } from './test-utils';
import {
CLIENT_PUBKEY,
@@ -55,186 +55,186 @@ import {
nowSeconds,
storeForeignConnection,
waitFor,
} from './nwc.testProtocol'
import {call, makeBearer, mint, readResponse, startTestService} from './nwc.testService'
import {SIGNED_BOLT11_FIXTURE} from './nwc.invoice-a.cases'
} from './nwc.testProtocol';
import { call, makeBearer, mint, readResponse, startTestService } from './nwc.testService';
import { SIGNED_BOLT11_FIXTURE } from './nwc.invoice-a.cases';
describe('service: make_invoice / lookup_invoice (continued)', () => {
it('drains a rejected invoice settlement and reports it before stop resolves', async () => {
const m = await mint({testHooks: true})
const commit = deferred()
const commitError = new Error('invoice commit rejected during stop')
let commitStarted = false
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
const commit = deferred();
const commitError = new Error('invoice commit rejected during stop');
let commitStarted = false;
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
commitChangeset: () => {
commitStarted = true
return commit.promise
commitStarted = true;
return commit.promise;
},
})
});
const made = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 21_000,
})
const paymentHash = made.result?.payment_hash
});
const paymentHash = made.result?.payment_hash;
if (typeof paymentHash !== 'string') {
throw new TypeError('make_invoice did not return a payment hash')
throw new TypeError('make_invoice did not return a payment hash');
}
const settleResponse = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`)
expect(settleResponse.ok).toBe(true)
await waitFor(() => commitStarted)
const settleResponse = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`);
expect(settleResponse.ok).toBe(true);
await waitFor(() => commitStarted);
let stopped = false
let stopped = false;
const stopping = stop().then(() => {
stopped = true
return state.errors.length
})
for (let turn = 0; turn < 10; turn += 1) await Promise.resolve()
expect(stopped).toBe(false)
stopped = true;
return state.errors.length;
});
for (let turn = 0; turn < 10; turn += 1) await Promise.resolve();
expect(stopped).toBe(false);
commit.reject(commitError)
expect(await stopping).toBe(1)
expect(state.errors).toEqual([commitError])
expect(state.changesets).toHaveLength(0)
await stop()
})
commit.reject(commitError);
expect(await stopping).toBe(1);
expect(state.errors).toEqual([commitError]);
expect(state.changesets).toHaveLength(0);
await stop();
});
it('does not block stop on an invoice whose claim is still polling', async () => {
// an unpaid invoice's claim poll can legally run for minutes (the
// client pays whenever it pays) - stop must interrupt the wait, not
// sit on it; a settlement that already REACHED the commit phase is
// still awaited (see the drain tests above)
const m = await mint({testHooks: true})
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
claimPoll: {intervalMs: 50, intervalCapMs: 50, maxWaitMs: 60_000},
})
claimPoll: { intervalMs: 50, intervalCapMs: 50, maxWaitMs: 60_000 },
});
const made = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 5_000,
})
expect(made.error).toBeNull()
});
expect(made.error).toBeNull();
// nobody pays the invoice; the claim keeps polling. stop must resolve
// promptly regardless (an un-interrupted stop would wait out the
// whole 60s claim budget)
await stop()
expect(state.changesets).toHaveLength(0)
expect(state.errors).toHaveLength(0)
})
await stop();
expect(state.changesets).toHaveLength(0);
expect(state.errors).toHaveLength(0);
});
it('does not start invoice settlement after stop begins during preparation', async () => {
const m = await mint({testHooks: true})
const prepare = deferred()
let prepareStarted = false
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
const prepare = deferred();
let prepareStarted = false;
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
kit: {
fetch: async (input, init) => {
prepareStarted = true
await prepare.promise
return fetch(input, init)
prepareStarted = true;
await prepare.promise;
return fetch(input, init);
},
},
})
});
const request = methodRequest(walletServicePubkey, 'make_invoice', {
amount: 21_000,
})
relay.emit(request)
await waitFor(() => prepareStarted)
});
relay.emit(request);
await waitFor(() => prepareStarted);
let stopped = false
let stopped = false;
const stopping = stop().then(() => {
stopped = true
})
for (let turn = 0; turn < 10; turn += 1) await Promise.resolve()
expect(stopped).toBe(false)
stopped = true;
});
for (let turn = 0; turn < 10; turn += 1) await Promise.resolve();
expect(stopped).toBe(false);
prepare.resolve()
await stopping
prepare.resolve();
await stopping;
expect(state.changesets).toHaveLength(0)
expect(readResponse(relay.published, request.id, 'nip44_v2')?.error?.code).toBe('INTERNAL')
})
expect(state.changesets).toHaveLength(0);
expect(readResponse(relay.published, request.id, 'nip44_v2')?.error?.code).toBe('INTERNAL');
});
it('marks a paid invoice failed when its bearer commit rejects', async () => {
const m = await mint({testHooks: true})
const commit = deferred()
const commitError = new Error('invoice bearer commit failed')
let commitStarted = false
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
const commit = deferred();
const commitError = new Error('invoice bearer commit failed');
let commitStarted = false;
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
commitChangeset: () => {
commitStarted = true
return commit.promise
commitStarted = true;
return commit.promise;
},
})
});
const made = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 21_000,
})
const paymentHash = made.result?.payment_hash
});
const paymentHash = made.result?.payment_hash;
if (typeof paymentHash !== 'string') {
throw new TypeError('make_invoice did not return a payment hash')
throw new TypeError('make_invoice did not return a payment hash');
}
const settleResponse = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`)
expect(settleResponse.ok).toBe(true)
await waitFor(() => commitStarted)
commit.reject(commitError)
await waitFor(() => state.errors.length === 1)
const settleResponse = await fetch(`${m.url}/_test/settle?payment_hash=${paymentHash}`);
expect(settleResponse.ok).toBe(true);
await waitFor(() => commitStarted);
commit.reject(commitError);
await waitFor(() => state.errors.length === 1);
const failed = await call(relay, walletServicePubkey, 'lookup_invoice', {
payment_hash: paymentHash,
})
expect(failed.result?.state).toBe('failed')
expect(failed.result?.settled_at).toBeUndefined()
expect(failed.result?.preimage).toBeUndefined()
expect(state.errors).toEqual([commitError])
await stop()
})
});
expect(failed.result?.state).toBe('failed');
expect(failed.result?.settled_at).toBeUndefined();
expect(failed.result?.preimage).toBeUndefined();
expect(state.errors).toEqual([commitError]);
await stop();
});
it('finds an invoice by its invoice string too', async () => {
const m = await mint({testHooks: true})
const {relay, walletServicePubkey, stop} = await startTestService({
const m = await mint({ testHooks: true });
const { relay, walletServicePubkey, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
claimPoll: {intervalMs: 1, intervalCapMs: 2, maxWaitMs: 10},
})
claimPoll: { intervalMs: 1, intervalCapMs: 2, maxWaitMs: 10 },
});
const made = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 5_000,
})
const invoice = made.result?.invoice
});
const invoice = made.result?.invoice;
if (typeof invoice !== 'string') {
throw new TypeError('make_invoice did not return an invoice')
throw new TypeError('make_invoice did not return an invoice');
}
const found = await call(relay, walletServicePubkey, 'lookup_invoice', {
invoice: invoice.toUpperCase(),
})
expect(found.error).toBeNull()
expect(found.result?.payment_hash).toBe(made.result?.payment_hash)
await stop()
})
});
expect(found.error).toBeNull();
expect(found.result?.payment_hash).toBe(made.result?.payment_hash);
await stop();
});
it('answers an unknown invoice with NOT_FOUND', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const { relay, walletServicePubkey, stop } = await startTestService({});
const response = await call(relay, walletServicePubkey, 'lookup_invoice', {
payment_hash: 'ab'.repeat(32),
})
expect(response.error?.code).toBe('NOT_FOUND')
await stop()
})
});
expect(response.error?.code).toBe('NOT_FOUND');
await stop();
});
it('answers make_invoice without a default mint with INTERNAL', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({
const { relay, walletServicePubkey, stop } = await startTestService({
defaultMint: null,
})
});
const response = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 21_000,
})
expect(response.error?.code).toBe('INTERNAL')
await stop()
})
});
expect(response.error?.code).toBe('INTERNAL');
await stop();
});
it('rejects invoice creation when the durable pending-output cap is reached', async () => {
const {relay, walletServicePubkey, state, stop} = await startTestService({
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: 'mint@example.com',
})
});
for (let index = 0; index < 20; index += 1) {
state.bearers.push({
id: `pending-${index}`,
@@ -245,91 +245,83 @@ describe('service: make_invoice / lookup_invoice (continued)', () => {
pendingMint: {},
createdAt: index,
updatedAt: index,
})
});
}
const response = await call(relay, walletServicePubkey, 'make_invoice', {
amount: 21_000,
})
});
expect(response.error?.code).toBe('QUOTA_EXCEEDED')
expect(state.bearers).toHaveLength(20)
await stop()
})
expect(response.error?.code).toBe('QUOTA_EXCEEDED');
expect(state.bearers).toHaveLength(20);
await stop();
});
it('removes staged outputs when invoice preparation fails before publication', async () => {
const m = await mint({testHooks: true})
let rejectQuotes = true
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
let rejectQuotes = true;
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
kit: {
fetch: (input, init) => {
const url =
typeof input === 'string'
? input
: input instanceof URL
? input.href
: input.url
typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (rejectQuotes && url.includes('comment=')) {
return Promise.resolve(new Response('quote failed', {status: 500}))
return Promise.resolve(new Response('quote failed', { status: 500 }));
}
return fetch(input, init)
return fetch(input, init);
},
},
})
});
for (let attempt = 0; attempt < 20; attempt += 1) {
const failed = await call(relay, walletServicePubkey, 'make_invoice', {amount: 21_000})
expect(failed.error?.code).toBe('INTERNAL')
expect(state.bearers).toHaveLength(0)
const failed = await call(relay, walletServicePubkey, 'make_invoice', { amount: 21_000 });
expect(failed.error?.code).toBe('INTERNAL');
expect(state.bearers).toHaveLength(0);
}
rejectQuotes = false
const made = await call(relay, walletServicePubkey, 'make_invoice', {amount: 21_000})
expect(made.error).toBeNull()
expect(state.bearers).toHaveLength(1)
await stop()
})
rejectQuotes = false;
const made = await call(relay, walletServicePubkey, 'make_invoice', { amount: 21_000 });
expect(made.error).toBeNull();
expect(state.bearers).toHaveLength(1);
await stop();
});
it('removes an unpublished stage when retirement persistence fails', async () => {
const m = await mint({testHooks: true})
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ testHooks: true });
const { relay, walletServicePubkey, state, stop } = await startTestService({
defaultMint: `mint@127.0.0.1:${m.port}`,
setMintOutputRetirement: () => Promise.reject(new Error('retirement write failed')),
kit: {
fetch: (input, init) => {
const url =
typeof input === 'string'
? input
: input instanceof URL
? input.href
: input.url
typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('comment=')) {
return Promise.resolve(
new Response(JSON.stringify({pr: SIGNED_BOLT11_FIXTURE}), {
new Response(JSON.stringify({ pr: SIGNED_BOLT11_FIXTURE }), {
status: 200,
headers: {'content-type': 'application/json'},
headers: { 'content-type': 'application/json' },
}),
)
);
}
return fetch(input, init)
return fetch(input, init);
},
},
})
});
const response = await call(relay, walletServicePubkey, 'make_invoice', {amount: 25_000})
const response = await call(relay, walletServicePubkey, 'make_invoice', { amount: 25_000 });
expect(response.error?.code).toBe('INTERNAL')
expect(state.bearers).toHaveLength(0)
await stop()
})
expect(response.error?.code).toBe('INTERNAL');
expect(state.bearers).toHaveLength(0);
await stop();
});
it('answers a make_invoice with a bad amount with OTHER', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const { relay, walletServicePubkey, stop } = await startTestService({});
const response = await call(relay, walletServicePubkey, 'make_invoice', {
amount: -5,
})
expect(response.error?.code).toBe('OTHER')
await stop()
})
})
});
expect(response.error?.code).toBe('OTHER');
await stop();
});
});
src/lnurlcash/nwc.ownership.cases.ts
+64 -64
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,13 +29,13 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredValue, stubLocalStorage } from './test-utils';
import {
CLIENT_PUBKEY,
@@ -55,19 +55,19 @@ import {
nowSeconds,
storeForeignConnection,
waitFor,
} from './nwc.testProtocol'
import {call, makeBearer, mint, readResponse, startTestService} from './nwc.testService'
} from './nwc.testProtocol';
import { call, makeBearer, mint, readResponse, startTestService } from './nwc.testService';
describe('service ownership', () => {
it('subscribes only current-owner records and leaves foreign budgets untouched', async () => {
const current = createConnection(LINKING_KEY, {
relays: RELAYS,
budget: {maxMsat: 1000, periodMs: 1000},
budget: { maxMsat: 1000, periodMs: 1000 },
clientSecret: CLIENT_SECRET,
now: 0,
})
const foreign = foreignConnectionFixture({maxMsat: 2000, periodMs: 2000}, 0)
storeForeignConnection(foreign.record)
const relay = createFakeRelay()
});
const foreign = foreignConnectionFixture({ maxMsat: 2000, periodMs: 2000 }, 0);
storeForeignConnection(foreign.record);
const relay = createFakeRelay();
const service = await startService(LINKING_KEY, {
assertCurrentOwner: () => undefined,
@@ -87,14 +87,14 @@ describe('service ownership', () => {
applyChangeset: () => Promise.resolve(),
transport: relay.transport,
nowSeconds,
})
});
expect(service.connections.map((connection) => connection.record)).toEqual([current.record])
expect(relay.subscriptionCount()).toBe(1)
expect(readNwcConnections(OTHER_OWNER_ID)[0]?.spent.msat).toBe(0)
expect(service.connections).not.toContainEqual(foreign)
await service.stop()
})
expect(service.connections.map((connection) => connection.record)).toEqual([current.record]);
expect(relay.subscriptionCount()).toBe(1);
expect(readNwcConnections(OTHER_OWNER_ID)[0]?.spent.msat).toBe(0);
expect(service.connections).not.toContainEqual(foreign);
await service.stop();
});
it('ignores foreign records handed in through the records snapshot', async () => {
// the injected-records path bypasses storage, so the service's own
@@ -102,12 +102,12 @@ describe('service ownership', () => {
// snapshot from a previous wallet must not be served)
const current = createConnection(LINKING_KEY, {
relays: RELAYS,
budget: {maxMsat: 1000, periodMs: 1000},
budget: { maxMsat: 1000, periodMs: 1000 },
clientSecret: CLIENT_SECRET,
now: 0,
})
const foreign = foreignConnectionFixture({maxMsat: 2000, periodMs: 2000}, 0)
const relay = createFakeRelay()
});
const foreign = foreignConnectionFixture({ maxMsat: 2000, periodMs: 2000 }, 0);
const relay = createFakeRelay();
const service = await startService(
LINKING_KEY,
@@ -131,51 +131,51 @@ describe('service ownership', () => {
nowSeconds,
},
[current.record, foreign.record],
)
);
expect(service.connections.map((connection) => connection.record)).toEqual([current.record])
expect(relay.subscriptionCount()).toBe(1)
expect(service.connections.map((connection) => connection.record)).toEqual([current.record]);
expect(relay.subscriptionCount()).toBe(1);
// the foreign snapshot record must not be persisted for the new owner
expect(readNwcConnections(OWNER_ID)).toEqual([current.record])
await service.stop()
})
})
expect(readNwcConnections(OWNER_ID)).toEqual([current.record]);
await service.stop();
});
});
describe('service: info and balance', () => {
it('publishes a kind-13194 info event on startup', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const info = requiredValue(relay.published.find((e) => e.kind === NWC_INFO_KIND))
expect(info.pubkey).toBe(walletServicePubkey)
expect(info.content).toContain('pay_invoice')
expect(info.content).toContain('make_invoice')
expect(info.tags).toContainEqual(['encryption', 'nip44_v2 nip04'])
await stop()
})
const { relay, walletServicePubkey, stop } = await startTestService({});
const info = requiredValue(relay.published.find((e) => e.kind === NWC_INFO_KIND));
expect(info.pubkey).toBe(walletServicePubkey);
expect(info.content).toContain('pay_invoice');
expect(info.content).toContain('make_invoice');
expect(info.tags).toContainEqual(['encryption', 'nip44_v2 nip04']);
await stop();
});
it('answers get_info with the connection identity and method list', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const response = await call(relay, walletServicePubkey, 'get_info', {})
expect(response.error).toBeNull()
expect(response.result_type).toBe('get_info')
const { relay, walletServicePubkey, stop } = await startTestService({});
const response = await call(relay, walletServicePubkey, 'get_info', {});
expect(response.error).toBeNull();
expect(response.result_type).toBe('get_info');
expect(response.result).toMatchObject({
alias: 'sattle',
pubkey: walletServicePubkey,
methods: ['get_info', 'get_balance', 'make_invoice', 'pay_invoice', 'lookup_invoice'],
})
await stop()
})
});
await stop();
});
it('answers get_balance with the spendable total only', async () => {
const m = await mint()
const {relay, walletServicePubkey, state, stop} = await startTestService({})
const m = await mint();
const { relay, walletServicePubkey, state, stop } = await startTestService({});
state.bearers = [
await makeBearer(m, 'aa'.repeat(32), 21_000),
await makeBearer(m, 'bb'.repeat(32), 5_000),
{...(await makeBearer(m, 'cc'.repeat(32), 99_000)), spent: true},
]
const response = await call(relay, walletServicePubkey, 'get_balance', {})
expect(response.error).toBeNull()
expect(response.result).toEqual({balance: 26_000})
await stop()
})
})
{ ...(await makeBearer(m, 'cc'.repeat(32), 99_000)), spent: true },
];
const response = await call(relay, walletServicePubkey, 'get_balance', {});
expect(response.error).toBeNull();
expect(response.result).toEqual({ balance: 26_000 });
await stop();
});
});
src/lnurlcash/nwc.pay-a.cases.ts
+119 -119
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,13 +29,13 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredString, requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredString, requiredValue, stubLocalStorage } from './test-utils';
import {
CLIENT_PUBKEY,
@@ -55,159 +55,159 @@ import {
nowSeconds,
storeForeignConnection,
waitFor,
} from './nwc.testProtocol'
import {call, makeBearer, mint, readResponse, startTestService} from './nwc.testService'
} from './nwc.testProtocol';
import { call, makeBearer, mint, readResponse, startTestService } from './nwc.testService';
describe('service: pay_invoice', () => {
it('applies the settled changeset before publishing success', async () => {
const m = await mint()
const {relay, walletServicePubkey, state, stop} = await startTestService({})
state.bearers = [await makeBearer(m, 'dc'.repeat(32), 21_000)]
const m = await mint();
const { relay, walletServicePubkey, state, stop } = await startTestService({});
state.bearers = [await makeBearer(m, 'dc'.repeat(32), 21_000)];
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
});
expect(response.error).toBeNull()
expect(state.changesets).toHaveLength(1)
expect(state.bearers[0]?.spent).toBe(true)
await stop()
})
expect(response.error).toBeNull();
expect(state.changesets).toHaveLength(1);
expect(state.bearers[0]?.spent).toBe(true);
await stop();
});
it('pays a bolt11 by melting, returning the melt preimage and recording the spend', async () => {
const m = await mint()
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint();
const { relay, walletServicePubkey, state, stop } = await startTestService({
budgetMsat: 50_000,
})
});
const foreign = foreignConnectionFixture(
{maxMsat: 99_000, periodMs: 86_400_000},
{ maxMsat: 99_000, periodMs: 86_400_000 },
nowSeconds() * 1000,
)
storeForeignConnection(foreign.record)
state.bearers = [await makeBearer(m, 'dd'.repeat(32), 21_000)]
);
storeForeignConnection(foreign.record);
state.bearers = [await makeBearer(m, 'dd'.repeat(32), 21_000)];
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
expect(response.error).toBeNull()
expect(requiredString(response.result?.preimage)).toHaveLength(64)
});
expect(response.error).toBeNull();
expect(requiredString(response.result?.preimage)).toHaveLength(64);
// the note is gone (melted) and locked spent via the changeset
expect(m.state.noteState('dd'.repeat(32))).toBe('burned')
expect(requiredValue(state.bearers[0]).spent).toBe(true)
expect(m.state.noteState('dd'.repeat(32))).toBe('burned');
expect(requiredValue(state.bearers[0]).spent).toBe(true);
// the spend was recorded against the budget, persisted
expect(readNwcConnections(OWNER_ID)[0]?.spent.msat).toBe(21_000)
expect(readNwcConnections(OTHER_OWNER_ID)[0]?.spent.msat).toBe(0)
await stop()
})
expect(readNwcConnections(OWNER_ID)[0]?.spent.msat).toBe(21_000);
expect(readNwcConnections(OTHER_OWNER_ID)[0]?.spent.msat).toBe(0);
await stop();
});
it('waits for a deferred bearer commit before publishing payment success', async () => {
const m = await mint()
const commit = deferred()
let commitStarted = false
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint();
const commit = deferred();
let commitStarted = false;
const { relay, walletServicePubkey, state, stop } = await startTestService({
commitChangeset: () => {
commitStarted = true
return commit.promise
commitStarted = true;
return commit.promise;
},
})
state.bearers = [await makeBearer(m, 'db'.repeat(32), 21_000)]
});
state.bearers = [await makeBearer(m, 'db'.repeat(32), 21_000)];
const request = methodRequest(walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
});
relay.emit(request)
await waitFor(() => commitStarted)
relay.emit(request);
await waitFor(() => commitStarted);
// a non-awaiting engine publishes within milliseconds of the commit
// call (one local verify re-read + encrypt); this window is far wider
// than that, so an early response here can only mean a missing barrier
await new Promise((resolve) => setTimeout(resolve, 250))
expect(readResponse(relay.published, request.id, 'nip44_v2')).toBeNull()
commit.resolve()
await waitFor(() => readResponse(relay.published, request.id, 'nip44_v2') !== null)
expect(readResponse(relay.published, request.id, 'nip44_v2')?.error).toBeNull()
await stop()
})
await new Promise((resolve) => setTimeout(resolve, 250));
expect(readResponse(relay.published, request.id, 'nip44_v2')).toBeNull();
commit.resolve();
await waitFor(() => readResponse(relay.published, request.id, 'nip44_v2') !== null);
expect(readResponse(relay.published, request.id, 'nip44_v2')?.error).toBeNull();
await stop();
});
it('reports a rejected bearer commit without publishing payment success', async () => {
const m = await mint()
const commit = deferred()
const commitError = new Error('bearer commit failed')
let commitStarted = false
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint();
const commit = deferred();
const commitError = new Error('bearer commit failed');
let commitStarted = false;
const { relay, walletServicePubkey, state, stop } = await startTestService({
commitChangeset: () => {
commitStarted = true
return commit.promise
commitStarted = true;
return commit.promise;
},
})
state.bearers = [await makeBearer(m, 'da'.repeat(32), 21_000)]
});
state.bearers = [await makeBearer(m, 'da'.repeat(32), 21_000)];
const request = methodRequest(walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
});
relay.emit(request)
await waitFor(() => commitStarted)
commit.reject(commitError)
relay.emit(request);
await waitFor(() => commitStarted);
commit.reject(commitError);
await waitFor(
() =>
state.errors.length > 0 || readResponse(relay.published, request.id, 'nip44_v2') !== null,
)
);
expect(readResponse(relay.published, request.id, 'nip44_v2')).toBeNull()
expect(state.errors).toEqual([commitError])
expect(readResponse(relay.published, request.id, 'nip44_v2')).toBeNull();
expect(state.errors).toEqual([commitError]);
// the conservative budget debit is persisted separately from bearer
// storage and deliberately NOT rolled back: the budget was debited,
// the bearer was never locked spent
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).spent.msat).toBe(21_000)
expect(state.bearers[0]?.spent).toBeUndefined()
await stop()
})
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).spent.msat).toBe(21_000);
expect(state.bearers[0]?.spent).toBeUndefined();
await stop();
});
it('drains an in-flight pay across repeated stops once its deferred commit resolves', async () => {
const m = await mint()
const commit = deferred()
let commitStarted = false
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint();
const commit = deferred();
let commitStarted = false;
const { relay, walletServicePubkey, state, stop } = await startTestService({
commitChangeset: () => {
commitStarted = true
return commit.promise
commitStarted = true;
return commit.promise;
},
})
state.bearers = [await makeBearer(m, 'd9'.repeat(32), 21_000)]
});
state.bearers = [await makeBearer(m, 'd9'.repeat(32), 21_000)];
const request = methodRequest(walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
});
relay.emit(request)
await waitFor(() => commitStarted)
relay.emit(request);
await waitFor(() => commitStarted);
// stop closes subscriptions; in-flight handlers still finish (their
// changesets hold money) - a repeated stop interrupts nothing twice
let stopped = false
let stopped = false;
const firstStop = stop().then(() => {
stopped = true
})
const repeatedStop = stop()
await Promise.resolve()
expect(stopped).toBe(false)
stopped = true;
});
const repeatedStop = stop();
await Promise.resolve();
expect(stopped).toBe(false);
// subscriptions close IMMEDIATELY, before the drain completes
expect(relay.subscriptionCount()).toBe(0)
expect(relay.subscriptionCount()).toBe(0);
const afterStop = methodRequest(walletServicePubkey, 'get_balance', {})
relay.emitAfterClose(afterStop)
await new Promise((resolve) => setTimeout(resolve, 25))
expect(readResponse(relay.published, afterStop.id, 'nip44_v2')).toBeNull()
const afterStop = methodRequest(walletServicePubkey, 'get_balance', {});
relay.emitAfterClose(afterStop);
await new Promise((resolve) => setTimeout(resolve, 25));
expect(readResponse(relay.published, afterStop.id, 'nip44_v2')).toBeNull();
commit.resolve()
await Promise.all([firstStop, repeatedStop])
expect(readResponse(relay.published, request.id, 'nip44_v2')?.error).toBeNull()
expect(state.bearers[0]?.spent).toBe(true)
})
commit.resolve();
await Promise.all([firstStop, repeatedStop]);
expect(readResponse(relay.published, request.id, 'nip44_v2')?.error).toBeNull();
expect(state.bearers[0]?.spent).toBe(true);
});
it('rejects a stale saved owner before touching the mint', async () => {
const m = await mint()
const {relay, walletServicePubkey, state, stop} = await startTestService({})
state.bearers = [await makeBearer(m, 'd8'.repeat(32), 21_000)]
const m = await mint();
const { relay, walletServicePubkey, state, stop } = await startTestService({});
state.bearers = [await makeBearer(m, 'd8'.repeat(32), 21_000)];
localStorage.setItem(
'sattle_linking_key',
JSON.stringify({
@@ -216,20 +216,20 @@ describe('service: pay_invoice', () => {
ownerId: OTHER_OWNER_ID,
version: 1,
}),
)
);
const request = methodRequest(walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
});
relay.emit(request)
relay.emit(request);
await waitFor(
() =>
state.errors.length > 0 || readResponse(relay.published, request.id, 'nip44_v2') !== null,
)
);
expect(m.state.noteState('d8'.repeat(32))).toBe('outstanding')
expect(state.changesets).toEqual([])
expect(readResponse(relay.published, request.id, 'nip44_v2')?.error?.code).toBe('INTERNAL')
await stop()
})
})
expect(m.state.noteState('d8'.repeat(32))).toBe('outstanding');
expect(state.changesets).toEqual([]);
expect(readResponse(relay.published, request.id, 'nip44_v2')?.error?.code).toBe('INTERNAL');
await stop();
});
});
src/lnurlcash/nwc.pay-b.cases.ts
+97 -87
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,13 +29,13 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredValue, stubLocalStorage } from './test-utils';
import {
CLIENT_PUBKEY,
@@ -55,121 +55,131 @@ import {
nowSeconds,
storeForeignConnection,
waitFor,
} from './nwc.testProtocol'
import {call, makeBearer, mint, readResponse, startTestService} from './nwc.testService'
} from './nwc.testProtocol';
import { call, makeBearer, mint, readResponse, startTestService } from './nwc.testService';
describe('service: pay_invoice (continued)', () => {
it('rejects a payment over the connection budget with QUOTA_EXCEEDED', async () => {
const m = await mint()
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint();
const { relay, walletServicePubkey, state, stop } = await startTestService({
budgetMsat: 20_000,
})
state.bearers = [await makeBearer(m, 'ee'.repeat(32), 21_000)]
});
state.bearers = [await makeBearer(m, 'ee'.repeat(32), 21_000)];
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
expect(response.error?.code).toBe('QUOTA_EXCEEDED')
});
expect(response.error?.code).toBe('QUOTA_EXCEEDED');
// nothing moved: the note is untouched, no spend recorded
expect(m.state.noteState('ee'.repeat(32))).toBe('outstanding')
expect(requiredValue(state.bearers[0]).spent).toBeUndefined()
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).spent.msat).toBe(0)
await stop()
})
expect(m.state.noteState('ee'.repeat(32))).toBe('outstanding');
expect(requiredValue(state.bearers[0]).spent).toBeUndefined();
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).spent.msat).toBe(0);
await stop();
});
it('resets the allowance once the budget period has rolled over', async () => {
const m = await mint()
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint();
const { relay, walletServicePubkey, state, stop } = await startTestService({
budgetMsat: 21_000,
periodMs: 60_000,
})
});
// simulate a fully spent budget from a period that ended long ago
const record: NwcConnectionRecord = requiredValue(readNwcConnections(OWNER_ID)[0])
const record: NwcConnectionRecord = requiredValue(readNwcConnections(OWNER_ID)[0]);
writeNwcConnections(OWNER_ID, [
{...record, spent: {periodStart: Date.now() - 120_000, msat: 21_000}},
])
state.bearers = [await makeBearer(m, 'ef'.repeat(32), 21_000)]
{ ...record, spent: { periodStart: Date.now() - 120_000, msat: 21_000 } },
]);
state.bearers = [await makeBearer(m, 'ef'.repeat(32), 21_000)];
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
expect(response.error).toBeNull()
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).spent.msat).toBe(21_000)
await stop()
})
});
expect(response.error).toBeNull();
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).spent.msat).toBe(21_000);
await stop();
});
it('rejects a payment the wallet cannot cover with INSUFFICIENT_BALANCE', async () => {
const m = await mint()
const {relay, walletServicePubkey, state, stop} = await startTestService({})
state.bearers = [await makeBearer(m, 'ff'.repeat(32), 5_000)]
const m = await mint();
const { relay, walletServicePubkey, state, stop } = await startTestService({});
state.bearers = [await makeBearer(m, 'ff'.repeat(32), 5_000)];
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
expect(response.error?.code).toBe('INSUFFICIENT_BALANCE')
expect(m.state.noteState('ff'.repeat(32))).toBe('outstanding')
await stop()
})
});
expect(response.error?.code).toBe('INSUFFICIENT_BALANCE');
expect(m.state.noteState('ff'.repeat(32))).toBe('outstanding');
await stop();
});
it('rejects a request amount that mismatches the invoice amount', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const { relay, walletServicePubkey, stop } = await startTestService({});
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
amount: 5_000,
})
expect(response.error?.code).toBe('OTHER')
expect(response.error?.message).toMatch(/match/i)
await stop()
})
});
expect(response.error?.code).toBe('OTHER');
expect(response.error?.message).toMatch(/match/i);
await stop();
});
it('rejects an amount-less invoice instead of guessing', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const { relay, walletServicePubkey, stop } = await startTestService({});
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc1pjqrstuvwxyz',
})
expect(response.error?.code).toBe('OTHER')
expect(response.error?.message).toMatch(/amount/i)
await stop()
})
});
expect(response.error?.code).toBe('OTHER');
expect(response.error?.message).toMatch(/amount/i);
await stop();
});
it('answers a failed melt with PAYMENT_FAILED and tracks the returned funds', async () => {
const m = await mint({meltAlwaysFails: true})
const {relay, walletServicePubkey, state, stop} = await startTestService({
const m = await mint({ meltAlwaysFails: true });
const { relay, walletServicePubkey, state, stop } = await startTestService({
// a short verify budget: the failed melt is classified by the poll
// running out, and that wait is the test's own clock
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
})
const original = await makeBearer(m, '01'.repeat(32), 21_000)
state.bearers = [original]
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
});
const original = await makeBearer(m, '01'.repeat(32), 21_000);
state.bearers = [original];
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
expect(response.error?.code).toBe('PAYMENT_FAILED')
});
expect(response.error?.code).toBe('PAYMENT_FAILED');
expect(m.state.noteState('01'.repeat(32))).toBe('burned')
expect(state.bearers.find((bearer) => bearer.id === original.id)?.spent).toBe(true)
expect(m.state.noteState('01'.repeat(32))).toBe('burned');
expect(state.bearers.find((bearer) => bearer.id === original.id)?.spent).toBe(true);
expect(
state.bearers.find((bearer) => bearer.id !== original.id && bearer.amount === 21_000 && !bearer.spent),
).toBeDefined()
expect(state.bearers.filter((bearer) => !bearer.spent).reduce((sum, bearer) => sum + bearer.amount, 0)).toBe(21_000)
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).spent.msat).toBe(0)
await stop()
})
state.bearers.find(
(bearer) => bearer.id !== original.id && bearer.amount === 21_000 && !bearer.spent,
),
).toBeDefined();
expect(
state.bearers
.filter((bearer) => !bearer.spent)
.reduce((sum, bearer) => sum + bearer.amount, 0),
).toBe(21_000);
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).spent.msat).toBe(0);
await stop();
});
it('conserves balance when a split payment fails and returns its carved funds', async () => {
const m = await mint({meltAlwaysFails: true})
const {relay, walletServicePubkey, state, stop} = await startTestService({
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
})
state.bearers = [await makeBearer(m, '02'.repeat(32), 30_000)]
const m = await mint({ meltAlwaysFails: true });
const { relay, walletServicePubkey, state, stop } = await startTestService({
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
});
state.bearers = [await makeBearer(m, '02'.repeat(32), 30_000)];
const response = await call(relay, walletServicePubkey, 'pay_invoice', {
invoice: 'lnbc210n1pjqrstuvwxyz',
})
});
expect(response.error?.code).toBe('PAYMENT_FAILED')
expect(state.bearers.filter((bearer) => !bearer.spent).reduce((sum, bearer) => sum + bearer.amount, 0)).toBe(30_000)
expect(state.bearers.find((bearer) => bearer.amount === 21_000 && !bearer.spent)).toBeDefined()
await stop()
})
})
expect(response.error?.code).toBe('PAYMENT_FAILED');
expect(
state.bearers
.filter((bearer) => !bearer.spent)
.reduce((sum, bearer) => sum + bearer.amount, 0),
).toBe(30_000);
expect(state.bearers.find((bearer) => bearer.amount === 21_000 && !bearer.spent)).toBeDefined();
await stop();
});
});
src/lnurlcash/nwc.storage.cases.ts
+68 -68
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,13 +29,13 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredValue, stubLocalStorage } from './test-utils';
import {
CLIENT_PUBKEY,
@@ -55,119 +55,119 @@ import {
nowSeconds,
storeForeignConnection,
waitFor,
} from './nwc.testProtocol'
import {call, makeBearer, mint, readResponse, startTestService} from './nwc.testService'
} from './nwc.testProtocol';
import { call, makeBearer, mint, readResponse, startTestService } from './nwc.testService';
describe('storage validation', () => {
it('drops malformed records instead of throwing', () => {
localStorage.setItem(
'sattle_nwc_connections',
JSON.stringify([
{clientPubkey: 'nope'},
{ clientPubkey: 'nope' },
{
version: 1,
ownerId: OWNER_ID,
clientPubkey: CLIENT_PUBKEY,
relays: RELAYS,
budget: {maxMsat: 1000, periodMs: 1000},
spent: {periodStart: 0, msat: 0},
budget: { maxMsat: 1000, periodMs: 1000 },
spent: { periodStart: 0, msat: 0 },
createdAt: 0,
},
]),
)
expect(readNwcConnections(OWNER_ID)).toHaveLength(1)
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).clientPubkey).toBe(CLIENT_PUBKEY)
})
);
expect(readNwcConnections(OWNER_ID)).toHaveLength(1);
expect(requiredValue(readNwcConnections(OWNER_ID)[0]).clientPubkey).toBe(CLIENT_PUBKEY);
});
it('returns nothing for garbage json', () => {
localStorage.setItem('sattle_nwc_connections', '{{{')
expect(readNwcConnections(OWNER_ID)).toEqual([])
})
localStorage.setItem('sattle_nwc_connections', '{{{');
expect(readNwcConnections(OWNER_ID)).toEqual([]);
});
it('returns only strictly parsed records belonging to the requested owner', () => {
const current = createConnection(LINKING_KEY, {
relays: RELAYS,
budget: {maxMsat: 1000, periodMs: 1000},
budget: { maxMsat: 1000, periodMs: 1000 },
clientSecret: CLIENT_SECRET,
now: 10,
}).record
const foreign = foreignConnectionFixture({maxMsat: 2000, periodMs: 2000}, 20).record
const raw: unknown = JSON.parse(localStorage.getItem('sattle_nwc_connections') ?? '[]')
if (!Array.isArray(raw)) throw new TypeError('Expected stored NWC records')
}).record;
const foreign = foreignConnectionFixture({ maxMsat: 2000, periodMs: 2000 }, 20).record;
const raw: unknown = JSON.parse(localStorage.getItem('sattle_nwc_connections') ?? '[]');
if (!Array.isArray(raw)) throw new TypeError('Expected stored NWC records');
localStorage.setItem(
'sattle_nwc_connections',
JSON.stringify([
...raw,
foreign,
{...current, ownerId: 'malformed'},
{ ...current, ownerId: 'malformed' },
{
clientPubkey: getPublicKey(hexToBytes('33'.repeat(32))),
relays: RELAYS,
budget: {maxMsat: 3000, periodMs: 3000},
spent: {periodStart: 0, msat: 0},
budget: { maxMsat: 3000, periodMs: 3000 },
spent: { periodStart: 0, msat: 0 },
createdAt: 30,
},
]),
)
);
expect(readNwcConnections(OWNER_ID)).toEqual([current])
expect(readNwcConnections(OTHER_OWNER_ID)).toEqual([foreign])
})
expect(readNwcConnections(OWNER_ID)).toEqual([current]);
expect(readNwcConnections(OTHER_OWNER_ID)).toEqual([foreign]);
});
it('adopts ownerless connections and enabled state only after owner proof', async () => {
await saveLinkingKey(LINKING_KEY)
const saved: unknown = JSON.parse(localStorage.getItem('sattle_linking_key') ?? '{}')
await saveLinkingKey(LINKING_KEY);
const saved: unknown = JSON.parse(localStorage.getItem('sattle_linking_key') ?? '{}');
if (typeof saved !== 'object' || saved === null) {
throw new TypeError('Expected a saved linking-key record')
throw new TypeError('Expected a saved linking-key record');
}
Reflect.deleteProperty(saved, 'ownerId')
Reflect.deleteProperty(saved, 'version')
localStorage.setItem('sattle_linking_key', JSON.stringify(saved))
Reflect.deleteProperty(saved, 'ownerId');
Reflect.deleteProperty(saved, 'version');
localStorage.setItem('sattle_linking_key', JSON.stringify(saved));
localStorage.setItem(
'sattle_nwc_connections',
JSON.stringify([
{
clientPubkey: CLIENT_PUBKEY,
relays: RELAYS,
budget: {maxMsat: 1000, periodMs: 1000},
spent: {periodStart: 0, msat: 0},
budget: { maxMsat: 1000, periodMs: 1000 },
spent: { periodStart: 0, msat: 0 },
createdAt: 0,
},
]),
)
localStorage.setItem('sattle_nwc_enabled', 'true')
);
localStorage.setItem('sattle_nwc_enabled', 'true');
expect(() => migrateLegacyNwcStorage(LINKING_KEY)).toThrow()
expect(readNwcConnections(OWNER_ID)).toEqual([])
expect(readNwcEnabled(OWNER_ID)).toBe(false)
expect(() => migrateLegacyNwcStorage(LINKING_KEY)).toThrow();
expect(readNwcConnections(OWNER_ID)).toEqual([]);
expect(readNwcEnabled(OWNER_ID)).toBe(false);
ensureSavedKeyOwner(LINKING_KEY)
ensureSavedKeyOwner(LINKING_KEY);
expect(migrateLegacyNwcStorage(LINKING_KEY)).toEqual({
connections: 1,
enabled: true,
})
expect(readNwcConnections(OWNER_ID)).toHaveLength(1)
expect(readNwcEnabled(OWNER_ID)).toBe(true)
});
expect(readNwcConnections(OWNER_ID)).toHaveLength(1);
expect(readNwcEnabled(OWNER_ID)).toBe(true);
expect(migrateLegacyNwcStorage(LINKING_KEY)).toEqual({
connections: 0,
enabled: false,
})
})
});
});
it('does not expose one wallet enabled state to another owner', () => {
writeNwcEnabled(OWNER_ID, true)
writeNwcEnabled(OWNER_ID, true);
expect(readNwcEnabled(OWNER_ID)).toBe(true)
expect(readNwcEnabled(OTHER_OWNER_ID)).toBe(false)
})
expect(readNwcEnabled(OWNER_ID)).toBe(true);
expect(readNwcEnabled(OTHER_OWNER_ID)).toBe(false);
});
it('treats malformed owner-bearing enabled records as disabled', () => {
for (const value of [
{version: 1, ownerId: 'malformed', enabled: true},
{version: 2, ownerId: OWNER_ID, enabled: true},
{version: 1, ownerId: OWNER_ID, enabled: 'true'},
{ version: 1, ownerId: 'malformed', enabled: true },
{ version: 2, ownerId: OWNER_ID, enabled: true },
{ version: 1, ownerId: OWNER_ID, enabled: 'true' },
]) {
localStorage.setItem('sattle_nwc_enabled', JSON.stringify(value))
expect(readNwcEnabled(OWNER_ID)).toBe(false)
localStorage.setItem('sattle_nwc_enabled', JSON.stringify(value));
expect(readNwcEnabled(OWNER_ID)).toBe(false);
}
})
})
});
});
src/lnurlcash/nwc.test.ts
+9 -9
View File
@@ -1,9 +1,9 @@
import './nwc.connection.cases'
import './nwc.storage.cases'
import './nwc.ownership.cases'
import './nwc.validation.cases'
import './nwc.pay-a.cases'
import './nwc.pay-b.cases'
import './nwc.fencing.cases'
import './nwc.invoice-a.cases'
import './nwc.invoice-b.cases'
import './nwc.connection.cases';
import './nwc.storage.cases';
import './nwc.ownership.cases';
import './nwc.validation.cases';
import './nwc.pay-a.cases';
import './nwc.pay-b.cases';
import './nwc.fencing.cases';
import './nwc.invoice-a.cases';
import './nwc.invoice-b.cases';
src/lnurlcash/nwc.testProtocol.ts
+80 -80
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,29 +29,29 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredValue, stubLocalStorage } from './test-utils';
export const LINKING_KEY = new Uint8Array(32).fill(7)
export const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
export const CLIENT_SECRET = hexToBytes('11'.repeat(32))
export const CLIENT_PUBKEY = getPublicKey(CLIENT_SECRET)
export const STRANGER_SECRET = hexToBytes('22'.repeat(32))
export const OWNER_ID = linkingPubKeyHex(LINKING_KEY)
export const OTHER_OWNER_ID = linkingPubKeyHex(OTHER_LINKING_KEY)
export const LINKING_KEY = new Uint8Array(32).fill(7);
export const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
export const CLIENT_SECRET = hexToBytes('11'.repeat(32));
export const CLIENT_PUBKEY = getPublicKey(CLIENT_SECRET);
export const STRANGER_SECRET = hexToBytes('22'.repeat(32));
export const OWNER_ID = linkingPubKeyHex(LINKING_KEY);
export const OTHER_OWNER_ID = linkingPubKeyHex(OTHER_LINKING_KEY);
// never connected - the in-memory relay below stands in
export const RELAYS = ['wss://relay-a.example']
export const RELAYS = ['wss://relay-a.example'];
let NOW = 1_800_000_000
export const nowSeconds = (): number => NOW
let NOW = 1_800_000_000;
export const nowSeconds = (): number => NOW;
export const FAST_POLL = {intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000}
export const FAST_POLL = { intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000 };
export const foreignConnectionFixture = (budget: NwcConnectionRecord['budget'], now: number) =>
connectionInfoOf(OTHER_LINKING_KEY, {
@@ -60,69 +60,69 @@ export const foreignConnectionFixture = (budget: NwcConnectionRecord['budget'],
clientPubkey: getPublicKey(STRANGER_SECRET),
relays: RELAYS,
budget,
spent: {periodStart: now, msat: 0},
spent: { periodStart: now, msat: 0 },
createdAt: now,
})
});
export const storeForeignConnection = (record: NwcConnectionRecord): void => {
const raw: unknown = JSON.parse(localStorage.getItem('sattle_nwc_connections') ?? '[]')
if (!Array.isArray(raw)) throw new TypeError('Expected stored NWC records')
localStorage.setItem('sattle_nwc_connections', JSON.stringify([...raw, record]))
}
const raw: unknown = JSON.parse(localStorage.getItem('sattle_nwc_connections') ?? '[]');
if (!Array.isArray(raw)) throw new TypeError('Expected stored NWC records');
localStorage.setItem('sattle_nwc_connections', JSON.stringify([...raw, record]));
};
// an in-memory relay set: subscriptions register, emit delivers to every
// matching one, publish records
export const createFakeRelay = (): {
transport: NwcTransport
published: NostrEvent[]
emit: (event: NostrEvent) => void
emitAfterClose: (event: NostrEvent) => void
subscriptionCount: () => number
transport: NwcTransport;
published: NostrEvent[];
emit: (event: NostrEvent) => void;
emitAfterClose: (event: NostrEvent) => void;
subscriptionCount: () => number;
} => {
const published: NostrEvent[] = []
const subs: {filter: NostrFilter; onEvent: (event: NostrEvent) => void}[] = []
const allSubs: {filter: NostrFilter; onEvent: (event: NostrEvent) => void}[] = []
const published: NostrEvent[] = [];
const subs: { filter: NostrFilter; onEvent: (event: NostrEvent) => void }[] = [];
const allSubs: { filter: NostrFilter; onEvent: (event: NostrEvent) => void }[] = [];
const transport: NwcTransport = {
publish: (_relays, event) => {
published.push(event)
return Promise.resolve()
published.push(event);
return Promise.resolve();
},
subscribe: (_relays, filter, onEvent) => {
const sub = {filter, onEvent}
subs.push(sub)
allSubs.push(sub)
const sub = { filter, onEvent };
subs.push(sub);
allSubs.push(sub);
return {
close: () => {
const index = subs.indexOf(sub)
if (index >= 0) subs.splice(index, 1)
const index = subs.indexOf(sub);
if (index >= 0) subs.splice(index, 1);
},
}
};
},
}
};
const deliver = (
targets: {filter: NostrFilter; onEvent: (event: NostrEvent) => void}[],
targets: { filter: NostrFilter; onEvent: (event: NostrEvent) => void }[],
event: NostrEvent,
): void => {
for (const sub of [...targets]) {
const kindsMatch = !sub.filter.kinds || sub.filter.kinds.includes(event.kind)
const wanted = sub.filter['#p']
const pMatch = !wanted || event.tags.some((t) => t[0] === 'p' && wanted.includes(t[1] ?? ''))
const sinceMatch = sub.filter.since === undefined || event.created_at >= sub.filter.since
if (kindsMatch && pMatch && sinceMatch) sub.onEvent(event)
const kindsMatch = !sub.filter.kinds || sub.filter.kinds.includes(event.kind);
const wanted = sub.filter['#p'];
const pMatch = !wanted || event.tags.some((t) => t[0] === 'p' && wanted.includes(t[1] ?? ''));
const sinceMatch = sub.filter.since === undefined || event.created_at >= sub.filter.since;
if (kindsMatch && pMatch && sinceMatch) sub.onEvent(event);
}
}
const emit = (event: NostrEvent): void => deliver(subs, event)
const emitAfterClose = (event: NostrEvent): void => deliver(allSubs, event)
};
const emit = (event: NostrEvent): void => deliver(subs, event);
const emitAfterClose = (event: NostrEvent): void => deliver(allSubs, event);
return {
transport,
published,
emit,
emitAfterClose,
subscriptionCount: () => subs.length,
}
}
};
};
export type Encryption = 'nip44_v2' | 'nip04' | 'none'
export type Encryption = 'nip44_v2' | 'nip04' | 'none';
// a NIP-47 request exactly as a real client would build it, signed by the
// connection's client secret
@@ -132,8 +132,8 @@ export const clientRequest = (
scheme: Encryption = 'nip44_v2',
createdAt: number = NOW,
): NostrEvent => {
const tags: string[][] = [['p', walletServicePubkey]]
if (scheme !== 'none') tags.push(['encryption', scheme])
const tags: string[][] = [['p', walletServicePubkey]];
if (scheme !== 'none') tags.push(['encryption', scheme]);
return finalizeEvent(
{
kind: NWC_REQUEST_KIND,
@@ -148,8 +148,8 @@ export const clientRequest = (
: nip04Encrypt(CLIENT_SECRET, walletServicePubkey, content),
},
CLIENT_SECRET,
)
}
);
};
export const methodRequest = (
walletServicePubkey: string,
@@ -158,31 +158,31 @@ export const methodRequest = (
scheme: Encryption = 'nip44_v2',
createdAt?: number,
): NostrEvent =>
clientRequest(walletServicePubkey, JSON.stringify({method, params}), scheme, createdAt)
clientRequest(walletServicePubkey, JSON.stringify({ method, params }), scheme, createdAt);
// generous: a failed/never-settling melt is only classified after the
// verify-poll budget (seconds) runs out
export const waitFor = async (cond: () => boolean): Promise<void> => {
for (let i = 0; i < 3000 && !cond(); i++) {
await new Promise((resolve) => setTimeout(resolve, 5))
await new Promise((resolve) => setTimeout(resolve, 5));
}
expect(cond()).toBe(true)
}
expect(cond()).toBe(true);
};
export const deferred = (): {
promise: Promise<void>
resolve: () => void
reject: (reason: Error) => void
promise: Promise<void>;
resolve: () => void;
reject: (reason: Error) => void;
} => {
let resolve = (): void => undefined
let reject = (_reason: Error): void => undefined
let resolve = (): void => undefined;
let reject = (_reason: Error): void => undefined;
const promise = new Promise<void>((resolvePromise, rejectPromise) => {
resolve = resolvePromise
reject = rejectPromise
})
return {promise, resolve, reject}
}
resolve = resolvePromise;
reject = rejectPromise;
});
return { promise, resolve, reject };
};
export const resetNow = (): void => {
NOW = 1_800_000_000
}
NOW = 1_800_000_000;
};
src/lnurlcash/nwc.testService.ts
+139 -134
View File
@@ -6,14 +6,14 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1, serverOf} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1, serverOf } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -30,14 +30,14 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredValue, stubLocalStorage} from './test-utils'
import {isJsonObject} from './jsonParsing'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredValue, stubLocalStorage } from './test-utils';
import { isJsonObject } from './jsonParsing';
import {
CLIENT_SECRET,
@@ -50,13 +50,13 @@ import {
nowSeconds,
resetNow,
waitFor,
} from './nwc.testProtocol'
import type {Encryption} from './nwc.testProtocol'
} from './nwc.testProtocol';
import type { Encryption } from './nwc.testProtocol';
export type NwcResponsePayload = {
result_type: string
error: {code: string; message: string} | null
result: Record<string, unknown> | null
}
result_type: string;
error: { code: string; message: string } | null;
result: Record<string, unknown> | null;
};
const isNwcResponsePayload = (value: unknown): value is NwcResponsePayload =>
isJsonObject(value) &&
@@ -65,7 +65,7 @@ const isNwcResponsePayload = (value: unknown): value is NwcResponsePayload =>
(isJsonObject(value.error) &&
typeof value.error.code === 'string' &&
typeof value.error.message === 'string')) &&
(value.result === null || isJsonObject(value.result))
(value.result === null || isJsonObject(value.result));
export const readResponse = (
published: NostrEvent[],
@@ -74,19 +74,19 @@ export const readResponse = (
): NwcResponsePayload | null => {
const event = published.find(
(e) => e.kind === NWC_RESPONSE_KIND && e.tags.some((t) => t[0] === 'e' && t[1] === requestId),
)
if (!event) return null
);
if (!event) return null;
const plaintext =
scheme === 'nip44_v2'
? nip44v2.decrypt(
event.content,
nip44v2.utils.getConversationKey(CLIENT_SECRET, event.pubkey),
)
: nip04Decrypt(CLIENT_SECRET, event.pubkey, event.content)
const parsed: unknown = JSON.parse(plaintext)
if (!isNwcResponsePayload(parsed)) throw new TypeError('Expected a valid NWC response payload.')
return parsed
}
: nip04Decrypt(CLIENT_SECRET, event.pubkey, event.content);
const parsed: unknown = JSON.parse(plaintext);
if (!isNwcResponsePayload(parsed)) throw new TypeError('Expected a valid NWC response payload.');
return parsed;
};
// drives one full request/response round trip over the fake relay
export const call = async (
@@ -96,31 +96,31 @@ export const call = async (
params: Record<string, unknown>,
scheme: Encryption = 'nip44_v2',
): Promise<NwcResponsePayload> => {
const request = methodRequest(walletServicePubkey, method, params, scheme)
relay.emit(request)
await waitFor(() => readResponse(relay.published, request.id, scheme) !== null)
return requiredValue(readResponse(relay.published, request.id, scheme))
}
const request = methodRequest(walletServicePubkey, method, params, scheme);
relay.emit(request);
await waitFor(() => readResponse(relay.published, request.id, scheme) !== null);
return requiredValue(readResponse(relay.published, request.id, scheme));
};
export type Mint = Awaited<ReturnType<typeof createMockMint>>
const mints: Mint[] = []
export type Mint = Awaited<ReturnType<typeof createMockMint>>;
const mints: Mint[] = [];
export const mint = async (options: Parameters<typeof createMockMint>[0] = {}): Promise<Mint> => {
const m = await createMockMint(options)
mints.push(m)
return m
}
const m = await createMockMint(options);
mints.push(m);
return m;
};
afterEach(async () => {
await Promise.all(mints.splice(0).map((m) => m.close()))
})
await Promise.all(mints.splice(0).map((m) => m.close()));
});
let bearerCounter = 0
let allocationCounter = 0
let bearerCounter = 0;
let allocationCounter = 0;
export const makeBearer = async (m: Mint, k1: string, amountMsat: number): Promise<Bearer> => {
m.state.creditNote(k1, amountMsat)
const url = buildNoteUrl(`${m.url}/w`, k1, amountMsat)
const info = await fetchNoteInfo(url)
bearerCounter += 1
m.state.creditNote(k1, amountMsat);
const url = buildNoteUrl(`${m.url}/w`, k1, amountMsat);
const info = await fetchNoteInfo(url);
bearerCounter += 1;
return {
id: `bearer-${bearerCounter}`,
url,
@@ -130,50 +130,50 @@ export const makeBearer = async (m: Mint, k1: string, amountMsat: number): Promi
mintPubkey: m.state.pubkey,
createdAt: Date.now(),
updatedAt: Date.now(),
}
}
};
};
// the harness around startService: a fake relay, an in-memory "store"
// applying changesets the way the Pinia layer will, and a created
// connection with a pinned client secret
export const startTestService = async (options: {
budgetMsat?: number
periodMs?: number
defaultMint?: string | null
linkingKey?: Uint8Array
poll?: typeof FAST_POLL
claimPoll?: typeof FAST_POLL
kit?: NwcServiceDeps['kit']
commitChangeset?: (changeset: NwcChangeset) => Promise<void>
setMintOutputRetirement?: () => Promise<void>
budgetMsat?: number;
periodMs?: number;
defaultMint?: string | null;
linkingKey?: Uint8Array;
poll?: typeof FAST_POLL;
claimPoll?: typeof FAST_POLL;
kit?: NwcServiceDeps['kit'];
commitChangeset?: (changeset: NwcChangeset) => Promise<void>;
setMintOutputRetirement?: () => Promise<void>;
}): Promise<{
relay: ReturnType<typeof createFakeRelay>
walletServicePubkey: string
state: {bearers: Bearer[]; changesets: NwcChangeset[]; errors: unknown[]}
stop: () => Promise<void>
relay: ReturnType<typeof createFakeRelay>;
walletServicePubkey: string;
state: { bearers: Bearer[]; changesets: NwcChangeset[]; errors: unknown[] };
stop: () => Promise<void>;
}> => {
const budgetMsat = options.budgetMsat ?? 1_000_000_000
const budgetMsat = options.budgetMsat ?? 1_000_000_000;
const connection = createConnection(options.linkingKey ?? LINKING_KEY, {
relays: RELAYS,
budget: {maxMsat: budgetMsat, periodMs: options.periodMs ?? 86_400_000},
budget: { maxMsat: budgetMsat, periodMs: options.periodMs ?? 86_400_000 },
clientSecret: CLIENT_SECRET,
now: nowSeconds() * 1000,
})
const relay = createFakeRelay()
const state: {bearers: Bearer[]; changesets: NwcChangeset[]; errors: unknown[]} = {
});
const relay = createFakeRelay();
const state: { bearers: Bearer[]; changesets: NwcChangeset[]; errors: unknown[] } = {
bearers: [],
changesets: [],
errors: [],
}
};
const service = await startService(options.linkingKey ?? LINKING_KEY, {
assertCurrentOwner: () => undefined,
// deterministic stand-in for the wallet's BIP-32 allocation path
allocateOutputSecrets: (_server, count) => {
const secrets = Array.from({length: count}, () => {
allocationCounter += 1
return bytesToHex(sha256(utf8ToBytes(`nwc-test-allocation-${allocationCounter}`)))
})
return Promise.resolve(secrets)
const secrets = Array.from({ length: count }, () => {
allocationCounter += 1;
return bytesToHex(sha256(utf8ToBytes(`nwc-test-allocation-${allocationCounter}`)));
});
return Promise.resolve(secrets);
},
// the keys a production caller serves from the trusted-mint registry:
// each created mock mint's current key plus any it retired
@@ -185,38 +185,38 @@ export const startTestService = async (options: {
getBearers: () => state.bearers,
getDefaultMint: () => options.defaultMint ?? null,
persistMintOutput: (note) => {
bearerCounter += 1
bearerCounter += 1;
const bearer: Bearer = {
...note,
id: `staged-${bearerCounter}`,
createdAt: Date.now(),
updatedAt: Date.now(),
}
state.bearers.push(bearer)
return Promise.resolve(bearer)
};
state.bearers.push(bearer);
return Promise.resolve(bearer);
},
discardMintOutput: (staged) => {
state.bearers = state.bearers.filter((bearer) => bearer.id !== staged.id)
return Promise.resolve()
state.bearers = state.bearers.filter((bearer) => bearer.id !== staged.id);
return Promise.resolve();
},
setMintOutputRetirement: (staged, retireAfter) => {
const override = options.setMintOutputRetirement?.()
if (override) return override
const index = state.bearers.findIndex((bearer) => bearer.id === staged.id)
if (index < 0) return Promise.reject(new Error('The staged bearer is missing.'))
const override = options.setMintOutputRetirement?.();
if (override) return override;
const index = state.bearers.findIndex((bearer) => bearer.id === staged.id);
if (index < 0) return Promise.reject(new Error('The staged bearer is missing.'));
const updated: Bearer = {
...staged,
pendingMint: {...staged.pendingMint, retireAfter},
pendingMint: { ...staged.pendingMint, retireAfter },
updatedAt: Date.now(),
}
state.bearers[index] = updated
return Promise.resolve()
};
state.bearers[index] = updated;
return Promise.resolve();
},
reserveMintOutputSource: (staged, sourceId, recoverySecret) => {
const index = state.bearers.findIndex((bearer) => bearer.id === staged.id)
const source = state.bearers.find((bearer) => bearer.id === sourceId)
if (index < 0 || !source) return Promise.reject(new Error('The payment journal is missing.'))
source.spent = true
const index = state.bearers.findIndex((bearer) => bearer.id === staged.id);
const source = state.bearers.find((bearer) => bearer.id === sourceId);
if (index < 0 || !source) return Promise.reject(new Error('The payment journal is missing.'));
source.spent = true;
state.bearers[index] = {
...state.bearers[index]!,
pendingMint: {
@@ -224,30 +224,35 @@ export const startTestService = async (options: {
sourceBearerId: sourceId,
sourceRecoverySecret: recoverySecret,
},
}
return Promise.resolve()
};
return Promise.resolve();
},
finalizeMintOutput: async (staged, note) => {
const changeset: NwcChangeset = {add: [], markSpent: []}
await options.commitChangeset?.(changeset)
state.changesets.push(changeset)
const index = state.bearers.findIndex((bearer) => bearer.id === staged.id)
if (index < 0) throw new Error('The staged bearer is missing.')
state.bearers[index] = {...staged, ...note, pendingMint: undefined, updatedAt: Date.now()}
const changeset: NwcChangeset = { add: [], markSpent: [] };
await options.commitChangeset?.(changeset);
state.changesets.push(changeset);
const index = state.bearers.findIndex((bearer) => bearer.id === staged.id);
if (index < 0) throw new Error('The staged bearer is missing.');
state.bearers[index] = { ...staged, ...note, pendingMint: undefined, updatedAt: Date.now() };
},
finalizePaymentReturn: async (staged, note) => {
const index = state.bearers.findIndex((bearer) => bearer.id === staged.id)
if (index < 0) throw new Error('The staged bearer is missing.')
const sourceId = state.bearers[index]?.pendingMint?.sourceBearerId
const index = state.bearers.findIndex((bearer) => bearer.id === staged.id);
if (index < 0) throw new Error('The staged bearer is missing.');
const sourceId = state.bearers[index]?.pendingMint?.sourceBearerId;
if (sourceId) {
const source = state.bearers.find((bearer) => bearer.id === sourceId)
if (source) source.spent = true
const source = state.bearers.find((bearer) => bearer.id === sourceId);
if (source) source.spent = true;
}
state.bearers[index] = {...state.bearers[index]!, ...note, pendingMint: undefined, updatedAt: Date.now()}
state.bearers[index] = {
...state.bearers[index]!,
...note,
pendingMint: undefined,
updatedAt: Date.now(),
};
},
finalizeSpentMintOutput: (staged) => {
state.bearers = state.bearers.filter((bearer) => bearer.id !== staged.id)
return Promise.resolve()
state.bearers = state.bearers.filter((bearer) => bearer.id !== staged.id);
return Promise.resolve();
},
commitCarve: async (carve) => {
// a checkpoint is identified by its output secret: the landed phase's
@@ -255,68 +260,68 @@ export const startTestService = async (options: {
const sameOutput = (url: string, noteUrl: string): boolean =>
serverOf(url) === serverOf(noteUrl) &&
noteK1(url) !== null &&
noteK1(url) === noteK1(noteUrl)
noteK1(url) === noteK1(noteUrl);
const additions = [carve.note, ...(carve.change ? [carve.change] : [])].filter(
(note) => !state.bearers.some((bearer) => sameOutput(bearer.url, note.url)),
)
);
const changeset: NwcChangeset = {
add: additions,
markSpent: carve.consumed.map((bearer) => bearer.id),
}
await options.commitChangeset?.(changeset)
state.changesets.push(changeset)
};
await options.commitChangeset?.(changeset);
state.changesets.push(changeset);
for (const bearer of state.bearers) {
if (changeset.markSpent.includes(bearer.id)) bearer.spent = true
if (changeset.markSpent.includes(bearer.id)) bearer.spent = true;
}
for (const note of additions) {
bearerCounter += 1
bearerCounter += 1;
state.bearers.unshift({
...note,
id: `carve-${bearerCounter}`,
createdAt: Date.now(),
updatedAt: Date.now(),
})
});
}
const committed = state.bearers.find((bearer) => sameOutput(bearer.url, carve.note.url))
if (!committed) throw new Error('The carved note was not committed.')
return committed
const committed = state.bearers.find((bearer) => sameOutput(bearer.url, carve.note.url));
if (!committed) throw new Error('The carved note was not committed.');
return committed;
},
applyChangeset: async (changeset: NwcChangeset) => {
await options.commitChangeset?.(changeset)
state.changesets.push(changeset)
await options.commitChangeset?.(changeset);
state.changesets.push(changeset);
for (const id of changeset.markSpent) {
const bearer = state.bearers.find((b) => b.id === id)
if (bearer) bearer.spent = true
const bearer = state.bearers.find((b) => b.id === id);
if (bearer) bearer.spent = true;
}
for (const note of changeset.add) {
bearerCounter += 1
bearerCounter += 1;
state.bearers.push({
...note,
id: `added-${bearerCounter}`,
createdAt: Date.now(),
updatedAt: Date.now(),
})
});
}
},
onError: (err) => {
state.errors.push(err)
state.errors.push(err);
},
transport: relay.transport,
kit: options.kit,
poll: options.poll ?? FAST_POLL,
claimPoll: options.claimPoll ?? FAST_POLL,
nowSeconds,
})
});
return {
relay,
walletServicePubkey: connection.walletServicePubkey,
state,
stop: service.stop,
}
}
};
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
resetNow()
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
resetNow();
});
src/lnurlcash/nwc.ts
+16 -16
View File
@@ -37,7 +37,7 @@
// per-connection request queues
// Budget/connection persistence lives in storage/nwcConnections.ts.
export type {NwcBudget, NwcBudgetSpend, NwcConnectionRecord} from './storage/nwcConnections'
export type { NwcBudget, NwcBudgetSpend, NwcConnectionRecord } from './storage/nwcConnections';
export {
clearNwcStorageForOwner,
clearUnownedNwcStorage,
@@ -46,9 +46,9 @@ export {
readNwcConnections,
removeNwcConnection,
writeNwcConnections,
} from './storage/nwcConnections'
export {readNwcEnabled, writeNwcEnabled} from './storage/nwcEnabled'
export type {NwcLegacyMigrationResult} from './storage/nwcConnections'
} from './storage/nwcConnections';
export { readNwcEnabled, writeNwcEnabled } from './storage/nwcEnabled';
export type { NwcLegacyMigrationResult } from './storage/nwcConnections';
export {
buildConnectionString,
@@ -57,13 +57,13 @@ export {
deriveNwcWalletKey,
nwcWalletPubkey,
parseConnectionString,
} from './nwc/connection'
} from './nwc/connection';
export type {
CreateConnectionOptions,
CreatedConnection,
NwcConnectionInfo,
ParsedConnectionString,
} from './nwc/connection'
} from './nwc/connection';
export {
NWC_INFO_KIND,
@@ -75,7 +75,7 @@ export {
decryptRequest,
errResult,
okResult,
} from './nwc/protocol'
} from './nwc/protocol';
export type {
DecryptedNwcRequest,
NostrEvent,
@@ -84,15 +84,15 @@ export type {
NwcMethod,
NwcRequest,
NwcResponse,
} from './nwc/protocol'
} from './nwc/protocol';
export {defaultNwcTransport} from './nwc/transport'
export type {NostrFilter, NwcSubscription, NwcTransport} from './nwc/transport'
export { defaultNwcTransport } from './nwc/transport';
export type { NostrFilter, NwcSubscription, NwcTransport } from './nwc/transport';
export {budgetRemainingMsat, recordSpend} from './nwc/budget'
export type {PendingInvoice, RequestContext} from './nwc/context'
export {invoiceResult, resolvePaymentHash} from './nwc/invoices'
export {payChangeset} from './nwc/pay'
export { budgetRemainingMsat, recordSpend } from './nwc/budget';
export type { PendingInvoice, RequestContext } from './nwc/context';
export { invoiceResult, resolvePaymentHash } from './nwc/invoices';
export { payChangeset } from './nwc/pay';
export {startService} from './nwc/service'
export type {NwcChangeset, NwcService, NwcServiceDeps} from './nwc/service'
export { startService } from './nwc/service';
export type { NwcChangeset, NwcService, NwcServiceDeps } from './nwc/service';
src/lnurlcash/nwc.validation.cases.ts
+82 -82
View File
@@ -6,13 +6,13 @@
// requests never execute, and a settled preimage only ever reveals an
// already-rotated (burned) note secret.
import {afterEach, beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex, hexToBytes} from '@noble/hashes/utils.js'
import {finalizeEvent, getPublicKey} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import {buildNoteUrl, fetchNoteInfo, noteK1} from 'lnurlcash-kit'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex, hexToBytes } from '@noble/hashes/utils.js';
import { finalizeEvent, getPublicKey } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
import { buildNoteUrl, fetchNoteInfo, noteK1 } from 'lnurlcash-kit';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import {
NWC_INFO_KIND,
@@ -29,13 +29,13 @@ import {
startService,
writeNwcEnabled,
writeNwcConnections,
} from './nwc'
import type {NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport} from './nwc'
import type {NostrFilter} from './nwc/transport'
import type {NwcChangeset} from './nwc'
import type {Bearer} from './types'
import {ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey} from './keys'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './nwc';
import type { NostrEvent, NwcConnectionRecord, NwcServiceDeps, NwcTransport } from './nwc';
import type { NostrFilter } from './nwc/transport';
import type { NwcChangeset } from './nwc';
import type { Bearer } from './types';
import { ensureSavedKeyOwner, linkingPubKeyHex, saveLinkingKey } from './keys';
import { requiredValue, stubLocalStorage } from './test-utils';
import {
CLIENT_PUBKEY,
@@ -55,45 +55,45 @@ import {
nowSeconds,
storeForeignConnection,
waitFor,
} from './nwc.testProtocol'
import {call, makeBearer, mint, readResponse, startTestService} from './nwc.testService'
} from './nwc.testProtocol';
import { call, makeBearer, mint, readResponse, startTestService } from './nwc.testService';
describe('service: request validation', () => {
it('answers an unknown method with NOT_IMPLEMENTED', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const response = await call(relay, walletServicePubkey, 'get_payments', {})
expect(response.result_type).toBe('get_payments')
expect(response.error?.code).toBe('NOT_IMPLEMENTED')
expect(response.result).toBeNull()
await stop()
})
const { relay, walletServicePubkey, stop } = await startTestService({});
const response = await call(relay, walletServicePubkey, 'get_payments', {});
expect(response.result_type).toBe('get_payments');
expect(response.error?.code).toBe('NOT_IMPLEMENTED');
expect(response.result).toBeNull();
await stop();
});
it('answers a malformed (non-JSON) request with an error, not a crash', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const request = clientRequest(walletServicePubkey, 'this is not json')
relay.emit(request)
await waitFor(() => readResponse(relay.published, request.id, 'nip44_v2') !== null)
const response = requiredValue(readResponse(relay.published, request.id, 'nip44_v2'))
expect(response.error?.code).toBe('OTHER')
await stop()
})
const { relay, walletServicePubkey, stop } = await startTestService({});
const request = clientRequest(walletServicePubkey, 'this is not json');
relay.emit(request);
await waitFor(() => readResponse(relay.published, request.id, 'nip44_v2') !== null);
const response = requiredValue(readResponse(relay.published, request.id, 'nip44_v2'));
expect(response.error?.code).toBe('OTHER');
await stop();
});
it('answers a JSON request without a method with an error', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const request = clientRequest(walletServicePubkey, JSON.stringify({params: {}}))
relay.emit(request)
await waitFor(() => readResponse(relay.published, request.id, 'nip44_v2') !== null)
const { relay, walletServicePubkey, stop } = await startTestService({});
const request = clientRequest(walletServicePubkey, JSON.stringify({ params: {} }));
relay.emit(request);
await waitFor(() => readResponse(relay.published, request.id, 'nip44_v2') !== null);
expect(requiredValue(readResponse(relay.published, request.id, 'nip44_v2')).error?.code).toBe(
'OTHER',
)
await stop()
})
);
await stop();
});
it('ignores a request signed by a stranger key - silently', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const { relay, walletServicePubkey, stop } = await startTestService({});
const content = nip44v2.encrypt(
JSON.stringify({method: 'get_balance', params: {}}),
JSON.stringify({ method: 'get_balance', params: {} }),
nip44v2.utils.getConversationKey(STRANGER_SECRET, walletServicePubkey),
)
);
const forged = finalizeEvent(
{
kind: NWC_REQUEST_KIND,
@@ -105,20 +105,20 @@ describe('service: request validation', () => {
content,
},
STRANGER_SECRET,
)
relay.emit(forged)
await new Promise((resolve) => setTimeout(resolve, 100))
expect(relay.published.filter((e) => e.kind === NWC_RESPONSE_KIND)).toHaveLength(0)
await stop()
})
);
relay.emit(forged);
await new Promise((resolve) => setTimeout(resolve, 100));
expect(relay.published.filter((e) => e.kind === NWC_RESPONSE_KIND)).toHaveLength(0);
await stop();
});
it('answers an unsupported encryption scheme with UNSUPPORTED_ENCRYPTION', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const { relay, walletServicePubkey, stop } = await startTestService({});
const content = nip04Encrypt(
CLIENT_SECRET,
walletServicePubkey,
JSON.stringify({method: 'get_balance', params: {}}),
)
JSON.stringify({ method: 'get_balance', params: {} }),
);
const request = finalizeEvent(
{
kind: NWC_REQUEST_KIND,
@@ -130,58 +130,58 @@ describe('service: request validation', () => {
content,
},
CLIENT_SECRET,
)
relay.emit(request)
);
relay.emit(request);
// the error answer goes out in the legacy scheme every client reads
await waitFor(() => readResponse(relay.published, request.id, 'nip04') !== null)
await waitFor(() => readResponse(relay.published, request.id, 'nip04') !== null);
expect(requiredValue(readResponse(relay.published, request.id, 'nip04')).error?.code).toBe(
'UNSUPPORTED_ENCRYPTION',
)
await stop()
})
);
await stop();
});
it('speaks legacy NIP-04: no encryption tag, and an explicit nip04 tag', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const { relay, walletServicePubkey, stop } = await startTestService({});
for (const scheme of ['none', 'nip04'] as const) {
const request = methodRequest(walletServicePubkey, 'get_balance', {}, scheme)
relay.emit(request)
await waitFor(() => readResponse(relay.published, request.id, 'nip04') !== null)
const response = requiredValue(readResponse(relay.published, request.id, 'nip04'))
expect(response.error).toBeNull()
expect(response.result).toEqual({balance: 0})
const request = methodRequest(walletServicePubkey, 'get_balance', {}, scheme);
relay.emit(request);
await waitFor(() => readResponse(relay.published, request.id, 'nip04') !== null);
const response = requiredValue(readResponse(relay.published, request.id, 'nip04'));
expect(response.error).toBeNull();
expect(response.result).toEqual({ balance: 0 });
// the response mirrors the request's scheme
const event = requiredValue(
relay.published.find(
(e) =>
e.kind === NWC_RESPONSE_KIND && e.tags.some((t) => t[0] === 'e' && t[1] === request.id),
),
)
expect(event.tags).toContainEqual(['encryption', 'nip04'])
);
expect(event.tags).toContainEqual(['encryption', 'nip04']);
}
await stop()
})
await stop();
});
it('drops requests older than the replay window unanswered', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
const { relay, walletServicePubkey, stop } = await startTestService({});
const stale = methodRequest(
walletServicePubkey,
'get_balance',
{},
'nip44_v2',
nowSeconds() - 1200,
)
relay.emit(stale)
await new Promise((resolve) => setTimeout(resolve, 100))
expect(relay.published.filter((e) => e.kind === NWC_RESPONSE_KIND)).toHaveLength(0)
await stop()
})
);
relay.emit(stale);
await new Promise((resolve) => setTimeout(resolve, 100));
expect(relay.published.filter((e) => e.kind === NWC_RESPONSE_KIND)).toHaveLength(0);
await stop();
});
it('picks up no new requests after stop', async () => {
const {relay, walletServicePubkey, stop} = await startTestService({})
await stop()
const request = methodRequest(walletServicePubkey, 'get_balance', {})
relay.emitAfterClose(request)
await new Promise((resolve) => setTimeout(resolve, 100))
expect(relay.published.filter((e) => e.kind === NWC_RESPONSE_KIND)).toHaveLength(0)
})
})
const { relay, walletServicePubkey, stop } = await startTestService({});
await stop();
const request = methodRequest(walletServicePubkey, 'get_balance', {});
relay.emitAfterClose(request);
await new Promise((resolve) => setTimeout(resolve, 100));
expect(relay.published.filter((e) => e.kind === NWC_RESPONSE_KIND)).toHaveLength(0);
});
});
src/lnurlcash/nwc/budget.ts
+10 -10
View File
@@ -5,14 +5,14 @@
// check + record below atomic enough: no two pays of one connection ever
// run this concurrently.
import type {NwcConnectionRecord} from '../storage/nwcConnections'
import {persistNwcConnection} from '../storage/nwcConnections'
import type { NwcConnectionRecord } from '../storage/nwcConnections';
import { persistNwcConnection } from '../storage/nwcConnections';
export const budgetRemainingMsat = (record: NwcConnectionRecord, nowMs: number): number => {
const {maxMsat, periodMs} = record.budget
if (nowMs - record.spent.periodStart >= periodMs) return maxMsat
return Math.max(0, maxMsat - record.spent.msat)
}
const { maxMsat, periodMs } = record.budget;
if (nowMs - record.spent.periodStart >= periodMs) return maxMsat;
return Math.max(0, maxMsat - record.spent.msat);
};
// rolls the period when it expired, then adds the spend; persists (the
// caller's queue serialized this read-modify-write)
@@ -22,14 +22,14 @@ export const recordSpend = (
amountMsat: number,
nowMs: number,
): NwcConnectionRecord => {
const expired = nowMs - record.spent.periodStart >= record.budget.periodMs
const expired = nowMs - record.spent.periodStart >= record.budget.periodMs;
return persistNwcConnection(ownerId, {
...record,
spent: expired
? {periodStart: nowMs, msat: amountMsat}
? { periodStart: nowMs, msat: amountMsat }
: {
periodStart: record.spent.periodStart,
msat: record.spent.msat + amountMsat,
},
})
}
});
};
src/lnurlcash/nwc/connection.ts
+49 -49
View File
@@ -20,17 +20,17 @@
// The connection string follows NIP-47 exactly:
// nostr+walletconnect://<wallet-service-pubkey>?relay=wss://...&secret=<client-secret-hex>
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
import {getPublicKey} from 'nostr-tools/pure'
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
import { getPublicKey } from 'nostr-tools/pure';
import {linkingPubKeyHex} from '../keys'
import type {NwcBudget, NwcConnectionRecord} from '../storage/nwcConnections'
import {persistNwcConnection} from '../storage/nwcConnections'
import { linkingPubKeyHex } from '../keys';
import type { NwcBudget, NwcConnectionRecord } from '../storage/nwcConnections';
import { persistNwcConnection } from '../storage/nwcConnections';
const NWC_WALLET_KEY_CONTEXT = 'sattle-nwc-wallet-v1'
const NWC_WALLET_KEY_CONTEXT = 'sattle-nwc-wallet-v1';
const HEX_64 = /^[0-9a-f]{64}$/i
const HEX_64 = /^[0-9a-f]{64}$/i;
// Deterministic: sha256(linking key || context || client pubkey). The
// result is a secp256k1 secret key used ONLY as this connection's
@@ -43,16 +43,16 @@ export const deriveNwcWalletKey = (linkingPrivKey: Uint8Array, clientPubkey: str
...utf8ToBytes(NWC_WALLET_KEY_CONTEXT),
...hexToBytes(clientPubkey),
]),
)
);
// the x-only nostr pubkey the client addresses its requests to
export const nwcWalletPubkey = (walletSecretKey: Uint8Array): string =>
getPublicKey(walletSecretKey)
getPublicKey(walletSecretKey);
export type NwcConnectionInfo = {
record: NwcConnectionRecord
walletServicePubkey: string
}
record: NwcConnectionRecord;
walletServicePubkey: string;
};
// the runtime view of a persisted record: the record plus its re-derived
// wallet-service identity
@@ -62,21 +62,21 @@ export const connectionInfoOf = (
): NwcConnectionInfo => ({
record,
walletServicePubkey: nwcWalletPubkey(deriveNwcWalletKey(linkingPrivKey, record.clientPubkey)),
})
});
export type CreatedConnection = NwcConnectionInfo & {
// shown to the holder exactly once - it carries the client secret,
// which the wallet deliberately does NOT store
connectionString: string
}
connectionString: string;
};
export type CreateConnectionOptions = {
relays: string[]
budget: NwcBudget
relays: string[];
budget: NwcBudget;
// test hook: a fixed client secret (32 bytes) instead of a random one
clientSecret?: Uint8Array
now?: number
}
clientSecret?: Uint8Array;
now?: number;
};
// Creates and persists a connection. The client secret is random by
// default; the wallet-service key falls out of the derivation above.
@@ -85,21 +85,21 @@ export const createConnection = (
options: CreateConnectionOptions,
): CreatedConnection => {
if (options.relays.length === 0) {
throw new Error('A connection needs at least one relay.')
throw new Error('A connection needs at least one relay.');
}
const clientSecret = options.clientSecret ?? crypto.getRandomValues(new Uint8Array(32))
const clientPubkey = getPublicKey(clientSecret)
const ownerId = linkingPubKeyHex(linkingPrivKey)
const clientSecret = options.clientSecret ?? crypto.getRandomValues(new Uint8Array(32));
const clientPubkey = getPublicKey(clientSecret);
const ownerId = linkingPubKeyHex(linkingPrivKey);
const record = persistNwcConnection(ownerId, {
version: 1,
ownerId,
clientPubkey,
relays: options.relays,
budget: options.budget,
spent: {periodStart: options.now ?? Date.now(), msat: 0},
spent: { periodStart: options.now ?? Date.now(), msat: 0 },
createdAt: options.now ?? Date.now(),
})
const info = connectionInfoOf(linkingPrivKey, record)
});
const info = connectionInfoOf(linkingPrivKey, record);
return {
...info,
connectionString: buildConnectionString(
@@ -107,43 +107,43 @@ export const createConnection = (
bytesToHex(clientSecret),
record.relays,
),
}
}
};
};
export const buildConnectionString = (
walletServicePubkey: string,
clientSecretHex: string,
relays: string[],
): string => {
const query = relays.map((relay) => `relay=${encodeURIComponent(relay)}`).join('&')
return `nostr+walletconnect://${walletServicePubkey}?${query}&secret=${clientSecretHex}`
}
const query = relays.map((relay) => `relay=${encodeURIComponent(relay)}`).join('&');
return `nostr+walletconnect://${walletServicePubkey}?${query}&secret=${clientSecretHex}`;
};
export type ParsedConnectionString = {
walletServicePubkey: string
clientSecret: string
relays: string[]
}
walletServicePubkey: string;
clientSecret: string;
relays: string[];
};
// parses a NIP-47 connection string; returns null for anything that isn't
// exactly one (a client-side counterpart of buildConnectionString, here so
// the format has a tested inverse)
export const parseConnectionString = (uri: string): ParsedConnectionString | null => {
let url: URL
let url: URL;
try {
url = new URL(uri.trim())
url = new URL(uri.trim());
} catch {
return null
return null;
}
if (url.protocol !== 'nostr+walletconnect:') return null
if (url.protocol !== 'nostr+walletconnect:') return null;
// the host is the wallet-service pubkey; normalize case so a
// hand-typed uppercase string still parses (nostr pubkeys are
// conventionally lowercase hex)
const walletServicePubkey = url.host.toLowerCase()
if (!HEX_64.test(walletServicePubkey)) return null
const secret = url.searchParams.get('secret')
if (!secret || !HEX_64.test(secret)) return null
const relays = url.searchParams.getAll('relay').filter((relay) => /^wss?:\/\//.test(relay))
if (relays.length === 0) return null
return {walletServicePubkey, clientSecret: secret.toLowerCase(), relays}
}
const walletServicePubkey = url.host.toLowerCase();
if (!HEX_64.test(walletServicePubkey)) return null;
const secret = url.searchParams.get('secret');
if (!secret || !HEX_64.test(secret)) return null;
const relays = url.searchParams.getAll('relay').filter((relay) => /^wss?:\/\//.test(relay));
if (relays.length === 0) return null;
return { walletServicePubkey, clientSecret: secret.toLowerCase(), relays };
};
src/lnurlcash/nwc/context.ts
+57 -57
View File
@@ -5,119 +5,119 @@
// no logic, so every other nwc/ module can import from here without
// cycles.
import type {LnurlcashOptions} from 'lnurlcash-kit'
import type { LnurlcashOptions } from 'lnurlcash-kit';
import type {Bearer, NewBearer} from '../types'
import type {NwcConnectionRecord} from '../storage/nwcConnections'
import type {PreparedMint} from '../ops'
import type {CarveResult} from '../ops'
import type {OutputSecretAllocator} from '../ops/allocation'
import type {MintSignatureKeys} from '../ops/shared'
import type {PollOptions} from '../ops/shared'
import type { Bearer, NewBearer } from '../types';
import type { NwcConnectionRecord } from '../storage/nwcConnections';
import type { PreparedMint } from '../ops';
import type { CarveResult } from '../ops';
import type { OutputSecretAllocator } from '../ops/allocation';
import type { MintSignatureKeys } from '../ops/shared';
import type { PollOptions } from '../ops/shared';
import type {NwcConnectionInfo} from './connection'
import type {NwcMethod} from './protocol'
import type {NwcTransport} from './transport'
import type { NwcConnectionInfo } from './connection';
import type { NwcMethod } from './protocol';
import type { NwcTransport } from './transport';
// the state delta the caller's store applies after an op ran: new notes
// to track, existing bearer ids to lock spent. Born-spent notes (a
// freshly carved note that was melted away) are deliberately NOT part of
// it - they were never the wallet's money in a trackable state
export type NwcChangeset = {
add: NewBearer[]
markSpent: string[]
}
add: NewBearer[];
markSpent: string[];
};
export type NwcServiceDeps = {
getBearers: () => Bearer[]
getBearers: () => Bearer[];
// the mint make_invoice issues invoices against (the wallet's default
// mint - NIP-47's make_invoice carries no mint choice)
getDefaultMint: () => string | null
assertCurrentOwner: () => void
getDefaultMint: () => string | null;
assertCurrentOwner: () => void;
// the wallet's durable allocation path (BIP-32 reservation) for every
// note output secret a request stages
allocateOutputSecrets: (
server: string,
count: number,
assertOwner: () => void,
) => Promise<readonly string[]>
) => Promise<readonly string[]>;
// trusted current+previous signing keys a landed carve output verifies
// against - the trusted-mint registry, owner-scoped
mintSignatureKeys: MintSignatureKeys
recoverPendingMints: (assertOwner: () => void) => Promise<void>
persistMintOutput: (note: NewBearer, assertOwner: () => void) => Promise<Bearer>
discardMintOutput: (staged: Bearer, assertOwner: () => void) => Promise<void>
mintSignatureKeys: MintSignatureKeys;
recoverPendingMints: (assertOwner: () => void) => Promise<void>;
persistMintOutput: (note: NewBearer, assertOwner: () => void) => Promise<Bearer>;
discardMintOutput: (staged: Bearer, assertOwner: () => void) => Promise<void>;
setMintOutputRetirement: (
staged: Bearer,
retireAfter: number,
assertOwner: () => void,
) => Promise<void>
) => Promise<void>;
reserveMintOutputSource: (
staged: Bearer,
sourceId: string,
recoverySecret: string,
assertOwner: () => void,
) => Promise<void>
finalizeMintOutput: (staged: Bearer, note: NewBearer, assertOwner: () => void) => Promise<void>
) => Promise<void>;
finalizeMintOutput: (staged: Bearer, note: NewBearer, assertOwner: () => void) => Promise<void>;
finalizePaymentReturn: (
staged: Bearer,
note: NewBearer,
assertOwner: () => void,
) => Promise<void>
finalizeSpentMintOutput: (staged: Bearer, assertOwner: () => void) => Promise<void>
commitCarve: (carve: CarveResult, assertOwner: () => void) => Promise<Bearer>
) => Promise<void>;
finalizeSpentMintOutput: (staged: Bearer, assertOwner: () => void) => Promise<void>;
commitCarve: (carve: CarveResult, assertOwner: () => void) => Promise<Bearer>;
applyChangeset: (
changeset: NwcChangeset,
connection: NwcConnectionInfo,
method: NwcMethod,
assertOwner: () => void,
) => Promise<void>
transport?: NwcTransport
) => Promise<void>;
transport?: NwcTransport;
// kit transport overrides (fetch injection, timeouts)
kit?: LnurlcashOptions
kit?: LnurlcashOptions;
// verify-poll budget for pay_invoice outcome classification
poll?: PollOptions
poll?: PollOptions;
// verify-poll budget for the background claim after make_invoice -
// generous by default: the client pays the invoice whenever it pays it
claimPoll?: PollOptions
claimPoll?: PollOptions;
// background failures (a lost claim, a rejected publish) have no caller
// to throw to - they surface here
onError?: (error: unknown, connection: NwcConnectionInfo) => void
onError?: (error: unknown, connection: NwcConnectionInfo) => void;
// test hook: pinned clock for event timestamps and expirations
nowSeconds?: () => number
}
nowSeconds?: () => number;
};
export type PendingInvoice = {
invoice: string
paymentHash: string
invoice: string;
paymentHash: string;
// the gross invoiced amount (net + mint fee) - what the payer pays
amountMsat: number
description?: string
createdAt: number // unix seconds
expiresAt?: number
prepared: PreparedMint
stagedOutput: Bearer
state: 'pending' | 'settled' | 'failed'
preimage?: string
settledAt?: number
}
amountMsat: number;
description?: string;
createdAt: number; // unix seconds
expiresAt?: number;
prepared: PreparedMint;
stagedOutput: Bearer;
state: 'pending' | 'settled' | 'failed';
preimage?: string;
settledAt?: number;
};
// what a method handler sees of its connection's runtime: the deps, the
// (fresh) connection info - budget updates replace the record, so it's a
// getter, not a snapshot - the invoice registry, and the clock
export type RequestContext = {
deps: NwcServiceDeps
connection: () => NwcConnectionInfo
updateRecord: (record: NwcConnectionRecord) => void
invoices: Map<string, PendingInvoice>
nowSeconds: () => number
assertOwner: () => void
deps: NwcServiceDeps;
connection: () => NwcConnectionInfo;
updateRecord: (record: NwcConnectionRecord) => void;
invoices: Map<string, PendingInvoice>;
nowSeconds: () => number;
assertOwner: () => void;
// Starts service-owned work only while the service accepts new work.
// Accepted tasks become part of stop's drain before key cleanup.
startBackground: (work: () => Promise<void>) => boolean
startBackground: (work: () => Promise<void>) => boolean;
// fires when the service stops: long OBSERVATION waits (the invoice
// claim poll) must interrupt themselves on it. Work that has already
// reached a fund-critical commit must NOT consult it - stop awaits
// those tasks through its drain
stopSignal: AbortSignal
}
stopSignal: AbortSignal;
};
src/lnurlcash/nwc/dispatch.ts
+64 -68
View File
@@ -4,25 +4,25 @@
// results go OUT through deps.applyChangeset - this engine never touches
// wallet state itself.
import {noteK1, sameInvoice} from 'lnurlcash-kit'
import { noteK1, sameInvoice } from 'lnurlcash-kit';
import type {Bearer} from '../types'
import type {PreparedMint} from '../ops'
import {prepareMint} from '../ops'
import {PollAbortedError} from '../ops/shared'
import type { Bearer } from '../types';
import type { PreparedMint } from '../ops';
import { prepareMint } from '../ops';
import { PollAbortedError } from '../ops/shared';
import type {PendingInvoice, RequestContext} from './context'
import {invoiceResult, invoiceRetireAfter, resolvePaymentHash, settleAndClaim} from './invoices'
import {handlePayInvoice} from './pay'
import type {NwcRequest, NwcResponse} from './protocol'
import {NWC_METHODS, errResult, okResult} from './protocol'
import type { PendingInvoice, RequestContext } from './context';
import { invoiceResult, invoiceRetireAfter, resolvePaymentHash, settleAndClaim } from './invoices';
import { handlePayInvoice } from './pay';
import type { NwcRequest, NwcResponse } from './protocol';
import { NWC_METHODS, errResult, okResult } from './protocol';
const MAX_PENDING_MINT_OUTPUTS = 20
const MAX_PENDING_MINT_OUTPUTS = 20;
// the same eligibility carve applies - the balance answers "what could
// this wallet actually pay with right now"
const spendable = (bearer: Bearer): boolean =>
!bearer.spent && bearer.callback !== '' && !bearer.deviceId && !!noteK1(bearer.url)
!bearer.spent && bearer.callback !== '' && !bearer.deviceId && !!noteK1(bearer.url);
const handleGetInfo = (ctx: RequestContext): NwcResponse =>
okResult('get_info', {
@@ -35,7 +35,7 @@ const handleGetInfo = (ctx: RequestContext): NwcResponse =>
network: 'mainnet',
methods: [...NWC_METHODS],
notifications: [],
})
});
const handleGetBalance = (ctx: RequestContext): NwcResponse =>
okResult('get_balance', {
@@ -43,21 +43,21 @@ const handleGetBalance = (ctx: RequestContext): NwcResponse =>
.getBearers()
.filter(spendable)
.reduce((sum, b) => sum + b.amount, 0),
})
});
const handleMakeInvoice = async (
ctx: RequestContext,
params: Record<string, unknown>,
): Promise<NwcResponse> => {
const amountMsat = Number(params.amount)
const amountMsat = Number(params.amount);
if (!Number.isInteger(amountMsat) || amountMsat <= 0) {
return errResult('make_invoice', 'OTHER', 'Amount must be a positive whole number of msat.')
return errResult('make_invoice', 'OTHER', 'Amount must be a positive whole number of msat.');
}
const mint = ctx.deps.getDefaultMint()
const mint = ctx.deps.getDefaultMint();
if (!mint) {
return errResult('make_invoice', 'INTERNAL', 'No default mint is configured.')
return errResult('make_invoice', 'INTERNAL', 'No default mint is configured.');
}
const now = ctx.nowSeconds()
const now = ctx.nowSeconds();
if (
ctx.deps
.getBearers()
@@ -68,16 +68,16 @@ const handleMakeInvoice = async (
bearer.pendingMint.retireAfter <= now,
)
) {
await ctx.deps.recoverPendingMints(ctx.assertOwner)
await ctx.deps.recoverPendingMints(ctx.assertOwner);
}
const pendingOutputs = ctx.deps
.getBearers()
.filter((bearer) => bearer.pendingMint && !bearer.spent).length
.filter((bearer) => bearer.pendingMint && !bearer.spent).length;
if (pendingOutputs >= MAX_PENDING_MINT_OUTPUTS) {
return errResult('make_invoice', 'QUOTA_EXCEEDED', 'Too many unpaid invoices are pending.')
return errResult('make_invoice', 'QUOTA_EXCEEDED', 'Too many unpaid invoices are pending.');
}
let prepared: PreparedMint
let stagedOutput: Bearer | undefined
let prepared: PreparedMint;
let stagedOutput: Bearer | undefined;
try {
prepared = await prepareMint(mint, amountMsat, {
...(ctx.deps.kit ?? {}),
@@ -85,49 +85,45 @@ const handleMakeInvoice = async (
allocateOutputSecrets: (server, count) =>
ctx.deps.allocateOutputSecrets(server, count, ctx.assertOwner),
persistOutput: async (note) => {
stagedOutput = await ctx.deps.persistMintOutput(note, ctx.assertOwner)
stagedOutput = await ctx.deps.persistMintOutput(note, ctx.assertOwner);
},
})
});
} catch (err) {
if (stagedOutput) {
try {
await ctx.deps.discardMintOutput(stagedOutput, ctx.assertOwner)
await ctx.deps.discardMintOutput(stagedOutput, ctx.assertOwner);
} catch (cleanupError) {
return errResult(
'make_invoice',
'INTERNAL',
cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
)
);
}
}
return errResult('make_invoice', 'INTERNAL', err instanceof Error ? err.message : String(err))
return errResult('make_invoice', 'INTERNAL', err instanceof Error ? err.message : String(err));
}
if (!stagedOutput) {
return errResult('make_invoice', 'INTERNAL', 'The pending mint output was not persisted.')
return errResult('make_invoice', 'INTERNAL', 'The pending mint output was not persisted.');
}
const retireAfter = invoiceRetireAfter(prepared.invoice)
const retireAfter = invoiceRetireAfter(prepared.invoice);
if (retireAfter !== null) {
try {
await ctx.deps.setMintOutputRetirement(
stagedOutput,
retireAfter,
ctx.assertOwner,
)
await ctx.deps.setMintOutputRetirement(stagedOutput, retireAfter, ctx.assertOwner);
} catch (error) {
try {
await ctx.deps.discardMintOutput(stagedOutput, ctx.assertOwner)
await ctx.deps.discardMintOutput(stagedOutput, ctx.assertOwner);
} catch (cleanupError) {
return errResult(
'make_invoice',
'INTERNAL',
cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
)
);
}
return errResult(
'make_invoice',
'INTERNAL',
error instanceof Error ? error.message : String(error),
)
);
}
}
const entry: PendingInvoice = {
@@ -138,68 +134,68 @@ const handleMakeInvoice = async (
prepared,
stagedOutput,
state: 'pending',
}
};
if (typeof params.description === 'string' && params.description) {
entry.description = params.description
entry.description = params.description;
}
const expiry = Number(params.expiry)
const expiry = Number(params.expiry);
if (Number.isInteger(expiry) && expiry > 0) {
entry.expiresAt = entry.createdAt + expiry
entry.expiresAt = entry.createdAt + expiry;
}
ctx.invoices.set(entry.paymentHash, entry)
ctx.invoices.set(entry.paymentHash, entry);
// phase two runs in the background; the invoice goes out now and
// lookup_invoice reports the settlement the service-owned claim observes
const started = ctx.startBackground(() =>
settleAndClaim(ctx, entry).catch((err) => {
entry.state = 'failed'
entry.state = 'failed';
// an interrupted claim poll is normal service teardown (stop
// aborted it), not a background failure worth surfacing
if (err instanceof PollAbortedError) return
ctx.deps.onError?.(err, ctx.connection())
if (err instanceof PollAbortedError) return;
ctx.deps.onError?.(err, ctx.connection());
}),
)
);
if (!started) {
entry.state = 'failed'
return errResult('make_invoice', 'INTERNAL', 'The wallet service is stopping.')
entry.state = 'failed';
return errResult('make_invoice', 'INTERNAL', 'The wallet service is stopping.');
}
return okResult('make_invoice', invoiceResult(entry))
}
return okResult('make_invoice', invoiceResult(entry));
};
const handleLookupInvoice = (ctx: RequestContext, params: Record<string, unknown>): NwcResponse => {
const invoiceParam = typeof params.invoice === 'string' ? params.invoice : undefined
const invoiceParam = typeof params.invoice === 'string' ? params.invoice : undefined;
const hashParam =
typeof params.payment_hash === 'string' ? params.payment_hash.toLowerCase() : undefined
typeof params.payment_hash === 'string' ? params.payment_hash.toLowerCase() : undefined;
if (!invoiceParam && !hashParam) {
return errResult('lookup_invoice', 'OTHER', 'Provide an invoice or a payment hash.')
return errResult('lookup_invoice', 'OTHER', 'Provide an invoice or a payment hash.');
}
let entry = hashParam ? ctx.invoices.get(hashParam) : undefined
let entry = hashParam ? ctx.invoices.get(hashParam) : undefined;
if (!entry && invoiceParam) {
for (const candidate of ctx.invoices.values()) {
if (sameInvoice(candidate.invoice, invoiceParam)) {
entry = candidate
break
entry = candidate;
break;
}
}
}
if (!entry) {
return errResult('lookup_invoice', 'NOT_FOUND', 'Unknown invoice.')
return errResult('lookup_invoice', 'NOT_FOUND', 'Unknown invoice.');
}
return okResult('lookup_invoice', invoiceResult(entry))
}
return okResult('lookup_invoice', invoiceResult(entry));
};
export const dispatch = async (ctx: RequestContext, request: NwcRequest): Promise<NwcResponse> => {
switch (request.method) {
case 'get_info':
return handleGetInfo(ctx)
return handleGetInfo(ctx);
case 'get_balance':
return handleGetBalance(ctx)
return handleGetBalance(ctx);
case 'make_invoice':
return await handleMakeInvoice(ctx, request.params)
return await handleMakeInvoice(ctx, request.params);
case 'pay_invoice':
return await handlePayInvoice(ctx, request.params)
return await handlePayInvoice(ctx, request.params);
case 'lookup_invoice':
return handleLookupInvoice(ctx, request.params)
return handleLookupInvoice(ctx, request.params);
default:
return errResult(request.method, 'NOT_IMPLEMENTED', `Unknown method: ${request.method}.`)
return errResult(request.method, 'NOT_IMPLEMENTED', `Unknown method: ${request.method}.`);
}
}
};
src/lnurlcash/nwc/invoices.ts
+67 -67
View File
@@ -4,73 +4,73 @@
// receipt. Settlement becomes visible only after the staged bearer has
// been replaced with the confirmed note details.
import {isPreimage, sameInvoice} from 'lnurlcash-kit'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex, utf8ToBytes} from '@noble/hashes/utils.js'
import { isPreimage, sameInvoice } from 'lnurlcash-kit';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js';
import type {PreparedMint} from '../ops'
import {MintedNoteSpentError} from '../ops'
import {claimFromSecret} from '../ops/mint'
import {pollVerifyUntilSettled} from '../ops/shared'
import type {PollOptions} from '../ops/shared'
import type { PreparedMint } from '../ops';
import { MintedNoteSpentError } from '../ops';
import { claimFromSecret } from '../ops/mint';
import { pollVerifyUntilSettled } from '../ops/shared';
import type { PollOptions } from '../ops/shared';
import type {PendingInvoice, RequestContext} from './context'
import type { PendingInvoice, RequestContext } from './context';
export const DEFAULT_CLAIM_POLL: Required<Omit<PollOptions, 'signal'>> = {
intervalMs: 2000,
intervalCapMs: 10_000,
maxWaitMs: 15 * 60_000,
}
};
const BECH32_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l'
const BOLT11_EXPIRY_TAG = BECH32_CHARSET.indexOf('x')
const BOLT11_DEFAULT_EXPIRY_SECONDS = 3600
const SETTLEMENT_GRACE_SECONDS = 14 * 24 * 60 * 60
const BECH32_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
const BOLT11_EXPIRY_TAG = BECH32_CHARSET.indexOf('x');
const BOLT11_DEFAULT_EXPIRY_SECONDS = 3600;
const SETTLEMENT_GRACE_SECONDS = 14 * 24 * 60 * 60;
// The kit has already validated the invoice before this parser runs. Read
// only BOLT11's timestamp and optional expiry tag; an unfamiliar shape stays
// durable forever rather than risking retirement while it could still settle.
export const invoiceRetireAfter = (invoice: string): number | null => {
const normalized = invoice.toLowerCase()
const separator = normalized.lastIndexOf('1')
if (separator < 1 || normalized.length - separator <= 6) return null
const normalized = invoice.toLowerCase();
const separator = normalized.lastIndexOf('1');
if (separator < 1 || normalized.length - separator <= 6) return null;
const words = [...normalized.slice(separator + 1, -6)].map((character) =>
BECH32_CHARSET.indexOf(character),
)
if (words.length < 7 || words.some((word) => word < 0)) return null
const timestamp = words.slice(0, 7).reduce((value, word) => value * 32 + word, 0)
if (!Number.isSafeInteger(timestamp)) return null
let expiry = BOLT11_DEFAULT_EXPIRY_SECONDS
let offset = 7
);
if (words.length < 7 || words.some((word) => word < 0)) return null;
const timestamp = words.slice(0, 7).reduce((value, word) => value * 32 + word, 0);
if (!Number.isSafeInteger(timestamp)) return null;
let expiry = BOLT11_DEFAULT_EXPIRY_SECONDS;
let offset = 7;
// Conformance invoices omit the 65-byte signature; real BOLT11 invoices
// include its fixed 104 words after the tagged fields.
const taggedEnd = words.length >= 7 + 104 ? words.length - 104 : words.length
const taggedEnd = words.length >= 7 + 104 ? words.length - 104 : words.length;
while (offset + 3 <= taggedEnd) {
const tag = words[offset]
const firstLength = words[offset + 1]
const secondLength = words[offset + 2]
if (tag === undefined || firstLength === undefined || secondLength === undefined) return null
const length = firstLength * 32 + secondLength
const valueStart = offset + 3
const valueEnd = valueStart + length
if (valueEnd > taggedEnd) return null
const tag = words[offset];
const firstLength = words[offset + 1];
const secondLength = words[offset + 2];
if (tag === undefined || firstLength === undefined || secondLength === undefined) return null;
const length = firstLength * 32 + secondLength;
const valueStart = offset + 3;
const valueEnd = valueStart + length;
if (valueEnd > taggedEnd) return null;
if (tag === BOLT11_EXPIRY_TAG) {
expiry = words.slice(valueStart, valueEnd).reduce((value, word) => value * 32 + word, 0)
if (!Number.isSafeInteger(expiry)) return null
expiry = words.slice(valueStart, valueEnd).reduce((value, word) => value * 32 + word, 0);
if (!Number.isSafeInteger(expiry)) return null;
}
offset = valueEnd
offset = valueEnd;
}
const retireAfter = timestamp + expiry + SETTLEMENT_GRACE_SECONDS
return Number.isSafeInteger(retireAfter) ? retireAfter : null
}
const retireAfter = timestamp + expiry + SETTLEMENT_GRACE_SECONDS;
return Number.isSafeInteger(retireAfter) ? retireAfter : null;
};
// LUD-21 verify URLs conventionally end in the payment hash. A service
// that uses another shape gets a stable wallet-local correlation id.
export const resolvePaymentHash = (prepared: PreparedMint): string => {
const fromVerify = prepared.verifyUrl?.match(/\/([0-9a-f]{64})$/i)?.[1]
if (fromVerify) return fromVerify.toLowerCase()
return bytesToHex(sha256(utf8ToBytes(prepared.invoice)))
}
const fromVerify = prepared.verifyUrl?.match(/\/([0-9a-f]{64})$/i)?.[1];
if (fromVerify) return fromVerify.toLowerCase();
return bytesToHex(sha256(utf8ToBytes(prepared.invoice)));
};
export const invoiceResult = (entry: PendingInvoice): Record<string, unknown> => {
const result: Record<string, unknown> = {
@@ -81,48 +81,48 @@ export const invoiceResult = (entry: PendingInvoice): Record<string, unknown> =>
amount: entry.amountMsat,
created_at: entry.createdAt,
metadata: {},
}
if (entry.description) result.description = entry.description
if (entry.expiresAt) result.expires_at = entry.expiresAt
if (entry.state === 'settled' && entry.preimage) result.preimage = entry.preimage
if (entry.settledAt) result.settled_at = entry.settledAt
return result
}
};
if (entry.description) result.description = entry.description;
if (entry.expiresAt) result.expires_at = entry.expiresAt;
if (entry.state === 'settled' && entry.preimage) result.preimage = entry.preimage;
if (entry.settledAt) result.settled_at = entry.settledAt;
return result;
};
export const settleAndClaim = async (ctx: RequestContext, entry: PendingInvoice): Promise<void> => {
const prepared = entry.prepared
const claimPoll = ctx.deps.claimPoll ?? DEFAULT_CLAIM_POLL
let preimage: string | null = null
const prepared = entry.prepared;
const claimPoll = ctx.deps.claimPoll ?? DEFAULT_CLAIM_POLL;
let preimage: string | null = null;
if (prepared.verifyUrl) {
// Observation remains interruptible. Once settlement is observed, the
// claim and durable update ignore shutdown while stop drains the task.
const result = await pollVerifyUntilSettled(
prepared.verifyUrl,
{...claimPoll, signal: ctx.stopSignal},
{ ...claimPoll, signal: ctx.stopSignal },
ctx.deps.kit ?? {},
)
);
if (!sameInvoice(result.pr, prepared.invoice)) {
throw new Error("The service's verify response is for a different invoice than requested.")
throw new Error("The service's verify response is for a different invoice than requested.");
}
if (result.preimage && isPreimage(result.preimage)) preimage = result.preimage
if (result.preimage && isPreimage(result.preimage)) preimage = result.preimage;
}
let claimed
let claimed;
try {
claimed = await claimFromSecret(
prepared,
prepared.verifyUrl ? claimPoll : {...claimPoll, signal: ctx.stopSignal},
prepared.verifyUrl ? claimPoll : { ...claimPoll, signal: ctx.stopSignal },
{
...(ctx.deps.kit ?? {}),
assertOwner: ctx.assertOwner,
},
)
);
} catch (error) {
if (!(error instanceof MintedNoteSpentError)) throw error
await ctx.deps.finalizeSpentMintOutput(entry.stagedOutput, ctx.assertOwner)
throw error
if (!(error instanceof MintedNoteSpentError)) throw error;
await ctx.deps.finalizeSpentMintOutput(entry.stagedOutput, ctx.assertOwner);
throw error;
}
await ctx.deps.finalizeMintOutput(entry.stagedOutput, claimed.note, ctx.assertOwner)
entry.settledAt = ctx.nowSeconds()
entry.state = 'settled'
if (preimage) entry.preimage = preimage
}
await ctx.deps.finalizeMintOutput(entry.stagedOutput, claimed.note, ctx.assertOwner);
entry.settledAt = ctx.nowSeconds();
entry.state = 'settled';
if (preimage) entry.preimage = preimage;
};
src/lnurlcash/nwc/pay.ts
+62 -62
View File
@@ -11,16 +11,16 @@ import {
isBolt11Invoice,
noteK1,
withNewK1,
} from 'lnurlcash-kit'
} from 'lnurlcash-kit';
import type {Bearer, NewBearer} from '../types'
import type {PayResult} from '../ops'
import {UncertainOutcomeError, payWithBearers} from '../ops'
import type { Bearer, NewBearer } from '../types';
import type { PayResult } from '../ops';
import { UncertainOutcomeError, payWithBearers } from '../ops';
import {budgetRemainingMsat, recordSpend} from './budget'
import type {NwcChangeset, RequestContext} from './context'
import type {NwcResponse} from './protocol'
import {errResult, okResult} from './protocol'
import { budgetRemainingMsat, recordSpend } from './budget';
import type { NwcChangeset, RequestContext } from './context';
import type { NwcResponse } from './protocol';
import { errResult, okResult } from './protocol';
// maps a PayResult onto the store delta, mirroring PayInvoiceDialog's
// semantics: carve inputs lock spent, change is tracked, returned funds
@@ -32,66 +32,66 @@ import {errResult, okResult} from './protocol'
// the next refresh to reconcile, exactly as the UI leaves it - the money
// itself sits in the re-secured note, which IS tracked.
export const payChangeset = (bearers: Bearer[], result: PayResult): NwcChangeset => {
const add: NewBearer[] = []
const markSpent: string[] = result.carve.consumed.map((b) => b.id)
const add: NewBearer[] = [];
const markSpent: string[] = result.carve.consumed.map((b) => b.id);
// the staged change's URL may lack the signature the landed result's URL
// carries - identify outputs by their secret, not the whole URL
const changeK1 = result.carve.change ? noteK1(result.carve.change.url) : null
const changeK1 = result.carve.change ? noteK1(result.carve.change.url) : null;
if (
result.carve.change &&
!bearers.some((bearer) => changeK1 !== null && noteK1(bearer.url) === changeK1)
) {
add.push(result.carve.change)
add.push(result.carve.change);
}
const carvedK1 = noteK1(result.carve.note.url)
const existing = carvedK1 ? bearers.find((bearer) => noteK1(bearer.url) === carvedK1) : undefined
const carvedK1 = noteK1(result.carve.note.url);
const existing = carvedK1 ? bearers.find((bearer) => noteK1(bearer.url) === carvedK1) : undefined;
if (result.outcome === 'failed-funds-returned') {
if (existing) {
const index = markSpent.indexOf(existing.id)
if (index >= 0) markSpent.splice(index, 1)
const index = markSpent.indexOf(existing.id);
if (index >= 0) markSpent.splice(index, 1);
}
} else {
// settled / still-pending / already-spent: the carved note is gone or
// locked. When it was one of the wallet's own bearers (an exact-match
// carve), lock that bearer; a freshly carved note is never added -
// it was born spent
if (existing) markSpent.push(existing.id)
if (existing) markSpent.push(existing.id);
}
return {add, markSpent}
}
return { add, markSpent };
};
export const handlePayInvoice = async (
ctx: RequestContext,
params: Record<string, unknown>,
): Promise<NwcResponse> => {
const invoice = typeof params.invoice === 'string' ? params.invoice.trim() : ''
const invoice = typeof params.invoice === 'string' ? params.invoice.trim() : '';
if (!isBolt11Invoice(invoice)) {
return errResult('pay_invoice', 'OTHER', 'Missing or invalid bolt11 invoice.')
return errResult('pay_invoice', 'OTHER', 'Missing or invalid bolt11 invoice.');
}
// the melt must match the invoice's amount exactly, so the amount is
// read from the invoice itself - never trusted from the request
const amountMsat = decodeBolt11AmountMsat(invoice)
const amountMsat = decodeBolt11AmountMsat(invoice);
if (amountMsat === null || amountMsat <= 0) {
return errResult(
'pay_invoice',
'OTHER',
"Could not read this invoice's amount - amount-less invoices are not supported.",
)
);
}
if (params.amount !== undefined && params.amount !== amountMsat) {
return errResult('pay_invoice', 'OTHER', "The request's amount does not match the invoice.")
return errResult('pay_invoice', 'OTHER', "The request's amount does not match the invoice.");
}
if (amountMsat > budgetRemainingMsat(ctx.connection().record, Date.now())) {
return errResult(
'pay_invoice',
'QUOTA_EXCEEDED',
"This payment exceeds the connection's budget.",
)
);
}
const bearers = ctx.deps.getBearers()
let result: PayResult
let committedCarve: Bearer | undefined
let returnStage: Bearer | undefined
const bearers = ctx.deps.getBearers();
let result: PayResult;
let committedCarve: Bearer | undefined;
let returnStage: Bearer | undefined;
try {
result = await payWithBearers(bearers, invoice, {
poll: ctx.deps.poll ?? {},
@@ -101,92 +101,92 @@ export const handlePayInvoice = async (
ctx.deps.allocateOutputSecrets(server, count, ctx.assertOwner),
mintSignatureKeys: ctx.deps.mintSignatureKeys,
onCarve: async (carve) => {
committedCarve = await ctx.deps.commitCarve(carve, ctx.assertOwner)
committedCarve = await ctx.deps.commitCarve(carve, ctx.assertOwner);
},
onReturnReady: async (carve, recoverySecret) => {
const source =
committedCarve ?? ctx.deps.getBearers().find((bearer) => bearer.url === carve.note.url)
if (!source) throw new Error('The carved note was not tracked.')
committedCarve ?? ctx.deps.getBearers().find((bearer) => bearer.url === carve.note.url);
if (!source) throw new Error('The carved note was not tracked.');
returnStage = await ctx.deps.persistMintOutput(
{
url: withNewK1(carve.note.url, recoverySecret, carve.note.amount),
callback: '',
amount: 0,
verified: false,
pendingMint: {retireAfter: ctx.nowSeconds() + 14 * 24 * 60 * 60},
pendingMint: { retireAfter: ctx.nowSeconds() + 14 * 24 * 60 * 60 },
},
ctx.assertOwner,
)
);
await ctx.deps.reserveMintOutputSource(
returnStage,
source.id,
recoverySecret,
ctx.assertOwner,
)
);
},
})
});
} catch (err) {
if (err instanceof UncertainOutcomeError) {
// the carve's answer was lost and the probe couldn't tell: the
// possible outputs carry fresh secrets that may be the only money
// left - tracked unverified, never dropped
await ctx.deps.applyChangeset(
{add: err.possibleOutputs, markSpent: []},
{ add: err.possibleOutputs, markSpent: [] },
ctx.connection(),
'pay_invoice',
ctx.assertOwner,
)
);
return errResult(
'pay_invoice',
'INTERNAL',
'The payment preparation could not be confirmed; possible new notes were stored unverified.',
)
);
}
const message = err instanceof Error ? err.message : String(err)
const message = err instanceof Error ? err.message : String(err);
return errResult(
'pay_invoice',
/enough/i.test(message) ? 'INSUFFICIENT_BALANCE' : 'INTERNAL',
message,
)
);
}
if (returnStage) {
const returned = result.rotatedNote ?? result.rescuedNote
const returned = result.rotatedNote ?? result.rescuedNote;
if (returned) {
await ctx.deps.finalizePaymentReturn(returnStage, returned, ctx.assertOwner)
await ctx.deps.finalizePaymentReturn(returnStage, returned, ctx.assertOwner);
} else if (result.outcome !== 'unknown-still-pending') {
await ctx.deps.finalizeSpentMintOutput(returnStage, ctx.assertOwner)
await ctx.deps.finalizeSpentMintOutput(returnStage, ctx.assertOwner);
}
}
const spendRecorded = (): void => {
// This conservative budget debit is persisted separately from bearer
// storage. A later bearer commit failure does not roll it back.
const connection = ctx.connection().record
ctx.updateRecord(recordSpend(connection.ownerId, connection, amountMsat, Date.now()))
}
const connection = ctx.connection().record;
ctx.updateRecord(recordSpend(connection.ownerId, connection, amountMsat, Date.now()));
};
switch (result.outcome) {
case 'settled': {
spendRecorded()
spendRecorded();
await ctx.deps.applyChangeset(
payChangeset(ctx.deps.getBearers(), result),
ctx.connection(),
'pay_invoice',
ctx.assertOwner,
)
);
// the receipt NIP-47 clients expect: the melt's own payment
// preimage, re-read from the settle proof. A mint that reveals
// none yields an empty preimage rather than a fabricated one.
let preimage = ''
let preimage = '';
if (result.verifyUrl) {
try {
const proof = await fetchInvoiceVerification(result.verifyUrl, ctx.deps.kit ?? {})
preimage = proof.preimage ?? ''
const proof = await fetchInvoiceVerification(result.verifyUrl, ctx.deps.kit ?? {});
preimage = proof.preimage ?? '';
} catch (error) {
// the settle proof was already polled inside payWithBearers;
// a failed re-read must not flip the outcome
if (!(error instanceof Error)) throw error
if (!(error instanceof Error)) throw error;
}
}
return okResult('pay_invoice', {preimage})
return okResult('pay_invoice', { preimage });
}
case 'failed-funds-returned':
await ctx.deps.applyChangeset(
@@ -194,36 +194,36 @@ export const handlePayInvoice = async (
ctx.connection(),
'pay_invoice',
ctx.assertOwner,
)
);
return errResult(
'pay_invoice',
'PAYMENT_FAILED',
'The payment failed; the funds are back in the wallet.',
)
);
case 'note-already-spent':
await ctx.deps.applyChangeset(
payChangeset(ctx.deps.getBearers(), result),
ctx.connection(),
'pay_invoice',
ctx.assertOwner,
)
);
return errResult(
'pay_invoice',
'PAYMENT_FAILED',
'The note backing this payment was already spent; nothing was paid.',
)
);
case 'unknown-still-pending':
spendRecorded()
spendRecorded();
await ctx.deps.applyChangeset(
payChangeset(ctx.deps.getBearers(), result),
ctx.connection(),
'pay_invoice',
ctx.assertOwner,
)
);
return errResult(
'pay_invoice',
'OTHER',
'The payment is still in flight; the note stays locked until it reconciles.',
)
);
}
}
};
src/lnurlcash/nwc/protocol.ts
+53 -52
View File
@@ -13,16 +13,16 @@
// - a kind 13194 replaceable info event advertises the supported methods
// and encryption schemes
import type {Event as NostrEvent} from 'nostr-tools/core'
import {finalizeEvent, verifyEvent} from 'nostr-tools/pure'
import {encrypt as nip04Encrypt, decrypt as nip04Decrypt} from 'nostr-tools/nip04'
import {v2 as nip44v2} from 'nostr-tools/nip44'
import type { Event as NostrEvent } from 'nostr-tools/core';
import { finalizeEvent, verifyEvent } from 'nostr-tools/pure';
import { encrypt as nip04Encrypt, decrypt as nip04Decrypt } from 'nostr-tools/nip04';
import { v2 as nip44v2 } from 'nostr-tools/nip44';
export type {NostrEvent}
export type { NostrEvent };
export const NWC_REQUEST_KIND = 23194
export const NWC_RESPONSE_KIND = 23195
export const NWC_INFO_KIND = 13194
export const NWC_REQUEST_KIND = 23194;
export const NWC_RESPONSE_KIND = 23195;
export const NWC_INFO_KIND = 13194;
export const NWC_METHODS = [
'get_info',
@@ -30,9 +30,9 @@ export const NWC_METHODS = [
'make_invoice',
'pay_invoice',
'lookup_invoice',
] as const
] as const;
export type NwcMethod = (typeof NWC_METHODS)[number]
export type NwcMethod = (typeof NWC_METHODS)[number];
export type NwcErrorCode =
| 'RATE_LIMITED'
@@ -45,38 +45,38 @@ export type NwcErrorCode =
| 'UNSUPPORTED_ENCRYPTION'
| 'PAYMENT_FAILED'
| 'NOT_FOUND'
| 'OTHER'
| 'OTHER';
export type NwcRequest = {
method: string
params: Record<string, unknown>
}
method: string;
params: Record<string, unknown>;
};
export type NwcResponse = {
result_type: string
error: {code: NwcErrorCode; message: string} | null
result: unknown
}
result_type: string;
error: { code: NwcErrorCode; message: string } | null;
result: unknown;
};
export const okResult = (method: string, result: unknown): NwcResponse => ({
result_type: method,
error: null,
result,
})
});
export const errResult = (method: string, code: NwcErrorCode, message: string): NwcResponse => ({
result_type: method,
error: {code, message},
error: { code, message },
result: null,
})
});
// the two encryption schemes this service speaks; the scheme of a request
// decides the scheme of its response (NIP-47: "Encrypted using the scheme
// requested by the client")
export type NwcEncryption = 'nip44_v2' | 'nip04'
export type NwcEncryption = 'nip44_v2' | 'nip04';
const conversationKey = (walletSecretKey: Uint8Array, clientPubkey: string): Uint8Array =>
nip44v2.utils.getConversationKey(walletSecretKey, clientPubkey)
nip44v2.utils.getConversationKey(walletSecretKey, clientPubkey);
export const encryptFor = (
scheme: NwcEncryption,
@@ -86,7 +86,7 @@ export const encryptFor = (
): string =>
scheme === 'nip44_v2'
? nip44v2.encrypt(plaintext, conversationKey(walletSecretKey, clientPubkey))
: nip04Encrypt(walletSecretKey, clientPubkey, plaintext)
: nip04Encrypt(walletSecretKey, clientPubkey, plaintext);
const decryptFrom = (
scheme: NwcEncryption,
@@ -96,10 +96,10 @@ const decryptFrom = (
): string =>
scheme === 'nip44_v2'
? nip44v2.decrypt(content, conversationKey(walletSecretKey, clientPubkey))
: nip04Decrypt(walletSecretKey, clientPubkey, content)
: nip04Decrypt(walletSecretKey, clientPubkey, content);
const tagValue = (event: NostrEvent, name: string): string | undefined =>
event.tags.find((t) => t[0] === name)?.[1]
event.tags.find((t) => t[0] === name)?.[1];
// The outcome of validating + decrypting a candidate request event:
// - a request to dispatch (encryption scheme carried so the response can
@@ -112,8 +112,8 @@ const tagValue = (event: NostrEvent, name: string): string | undefined =>
// dropped silently, exactly what a relay full of strangers' traffic
// demands
export type DecryptedNwcRequest =
| {respond: false; request: NwcRequest; encryption: NwcEncryption}
| {respond: true; response: NwcResponse; encryption: NwcEncryption}
| { respond: false; request: NwcRequest; encryption: NwcEncryption }
| { respond: true; response: NwcResponse; encryption: NwcEncryption };
export const decryptRequest = (
walletSecretKey: Uint8Array,
@@ -122,24 +122,24 @@ export const decryptRequest = (
event: NostrEvent,
nowSeconds: number = Math.floor(Date.now() / 1000),
): DecryptedNwcRequest | null => {
if (event.kind !== NWC_REQUEST_KIND) return null
if (event.kind !== NWC_REQUEST_KIND) return null;
// only the authorized client may talk to this connection, and the
// request must actually be addressed to it
if (event.pubkey !== clientPubkey) return null
if (tagValue(event, 'p') !== walletServicePubkey) return null
if (!verifyEvent(event)) return null
if (event.pubkey !== clientPubkey) return null;
if (tagValue(event, 'p') !== walletServicePubkey) return null;
if (!verifyEvent(event)) return null;
// an expired request is ignored, never answered (NIP-47)
const expiration = tagValue(event, 'expiration')
const expiration = tagValue(event, 'expiration');
if (expiration !== undefined && Number(expiration) < nowSeconds) {
return null
return null;
}
// encryption negotiation: no tag means legacy NIP-04 (NIP-47)
const advertised = tagValue(event, 'encryption')
let encryption: NwcEncryption
const advertised = tagValue(event, 'encryption');
let encryption: NwcEncryption;
if (advertised === undefined || advertised === 'nip04') {
encryption = 'nip04'
encryption = 'nip04';
} else if (advertised === 'nip44_v2') {
encryption = 'nip44_v2'
encryption = 'nip44_v2';
} else {
// the client asked for a scheme we don't speak - answer in the
// legacy default, the one scheme every NIP-47 client must read
@@ -151,24 +151,24 @@ export const decryptRequest = (
'UNSUPPORTED_ENCRYPTION',
`Unsupported encryption scheme: ${advertised}.`,
),
}
};
}
let plaintext: string
let plaintext: string;
try {
plaintext = decryptFrom(encryption, walletSecretKey, clientPubkey, event.content)
plaintext = decryptFrom(encryption, walletSecretKey, clientPubkey, event.content);
} catch {
// undecryptable - indistinguishable from relay noise; stay silent
return null
return null;
}
let data: unknown
let data: unknown;
try {
data = JSON.parse(plaintext)
data = JSON.parse(plaintext);
} catch {
return {
respond: true,
encryption,
response: errResult('', 'OTHER', 'The request is not valid JSON.'),
}
};
}
if (
typeof data !== 'object' ||
@@ -180,12 +180,13 @@ export const decryptRequest = (
respond: true,
encryption,
response: errResult('', 'OTHER', 'The request has no method.'),
}
};
}
const request = data as NwcRequest
const params = typeof request.params === 'object' && request.params !== null ? request.params : {}
return {respond: false, request: {method: request.method, params}, encryption}
}
const request = data as NwcRequest;
const params =
typeof request.params === 'object' && request.params !== null ? request.params : {};
return { respond: false, request: { method: request.method, params }, encryption };
};
// signs the kind-23195 answer to a request, mirroring its encryption
// scheme and referencing it via the 'e' tag
@@ -209,7 +210,7 @@ export const buildResponseEvent = (
content: encryptFor(encryption, walletSecretKey, clientPubkey, JSON.stringify(response)),
},
walletSecretKey,
)
);
// the replaceable info event advertising this service's capabilities
export const buildInfoEvent = (
@@ -224,4 +225,4 @@ export const buildInfoEvent = (
content: NWC_METHODS.join(' '),
},
walletSecretKey,
)
);
src/lnurlcash/nwc/service.ts
+98 -96
View File
@@ -14,60 +14,60 @@
// foreground-only design itself is documented in the nwc.ts façade
// header.
import {linkingPubKeyHex} from '../keys'
import type {NwcConnectionRecord} from '../storage/nwcConnections'
import {readNwcConnections} from '../storage/nwcConnections'
import {assertSavedKeyOwner} from '../storage/currentOwner'
import { linkingPubKeyHex } from '../keys';
import type { NwcConnectionRecord } from '../storage/nwcConnections';
import { readNwcConnections } from '../storage/nwcConnections';
import { assertSavedKeyOwner } from '../storage/currentOwner';
import type {NwcConnectionInfo} from './connection'
import {deriveNwcWalletKey, nwcWalletPubkey} from './connection'
import type {NwcServiceDeps, PendingInvoice, RequestContext} from './context'
import {dispatch} from './dispatch'
import type {NostrEvent, NwcEncryption, NwcRequest, NwcResponse} from './protocol'
import {NWC_REQUEST_KIND, buildInfoEvent, buildResponseEvent, decryptRequest} from './protocol'
import type {NwcSubscription} from './transport'
import {defaultNwcTransport} from './transport'
import type { NwcConnectionInfo } from './connection';
import { deriveNwcWalletKey, nwcWalletPubkey } from './connection';
import type { NwcServiceDeps, PendingInvoice, RequestContext } from './context';
import { dispatch } from './dispatch';
import type { NostrEvent, NwcEncryption, NwcRequest, NwcResponse } from './protocol';
import { NWC_REQUEST_KIND, buildInfoEvent, buildResponseEvent, decryptRequest } from './protocol';
import type { NwcSubscription } from './transport';
import { defaultNwcTransport } from './transport';
export type {NwcConnectionInfo}
export type {NwcChangeset, NwcServiceDeps} from './context'
export type { NwcConnectionInfo };
export type { NwcChangeset, NwcServiceDeps } from './context';
// requests older than this are dropped unanswered (see the header)
const MAX_REQUEST_AGE_SECONDS = 600
const MAX_REQUEST_AGE_SECONDS = 600;
type ConnectionRuntime = {
info: NwcConnectionInfo
info: NwcConnectionInfo;
// nulled and zeroed only after every tracked handler drains
walletSecret: Uint8Array | null
walletSecret: Uint8Array | null;
// invoices this connection issued, by payment hash - in-memory only:
// pending invoices don't survive a restart (lookup then answers
// NOT_FOUND), same as any foreground-only wallet
invoices: Map<string, PendingInvoice>
invoices: Map<string, PendingInvoice>;
// serializes pay_invoice handling per connection - the budget check and
// the spend record can't interleave
queue: Promise<unknown>
sub: NwcSubscription
}
queue: Promise<unknown>;
sub: NwcSubscription;
};
export type NwcService = {
// a snapshot of the served connections at startup; the persisted
// records (storage/nwcConnections) carry the live budget state
connections: NwcConnectionInfo[]
connections: NwcConnectionInfo[];
// closes every relay subscription. In-flight handlers still finish -
// their changesets hold money - but no new requests are picked up
stop: () => Promise<void>
}
stop: () => Promise<void>;
};
export const startService = async (
linkingPrivKey: Uint8Array,
deps: NwcServiceDeps,
records?: NwcConnectionRecord[],
): Promise<NwcService> => {
const transport = deps.transport ?? (await defaultNwcTransport())
const ownerId = linkingPubKeyHex(linkingPrivKey)
const transport = deps.transport ?? (await defaultNwcTransport());
const ownerId = linkingPubKeyHex(linkingPrivKey);
const ownedRecords = (records ?? readNwcConnections(ownerId)).filter(
(record) => record.ownerId === ownerId,
)
const nowSeconds = (): number => deps.nowSeconds?.() ?? Math.floor(Date.now() / 1000)
);
const nowSeconds = (): number => deps.nowSeconds?.() ?? Math.floor(Date.now() / 1000);
const publishResponse = async (
runtime: ConnectionRuntime,
@@ -86,10 +86,10 @@ export const startService = async (
response,
nowSeconds(),
),
)
}
);
};
let invoiceQueue: Promise<unknown> = Promise.resolve()
let invoiceQueue: Promise<unknown> = Promise.resolve();
// Payments serialize per connection for budget atomicity. Invoice
// creation serializes across the service so different clients cannot
@@ -103,37 +103,37 @@ export const startService = async (
const run = invoiceQueue.then(
() => dispatch(ctx, request),
() => dispatch(ctx, request),
)
invoiceQueue = run.catch(() => undefined)
return run
);
invoiceQueue = run.catch(() => undefined);
return run;
}
if (request.method !== 'pay_invoice') return dispatch(ctx, request)
if (request.method !== 'pay_invoice') return dispatch(ctx, request);
const run = runtime.queue.then(
() => dispatch(ctx, request),
() => dispatch(ctx, request),
)
runtime.queue = run.catch(() => undefined)
return run
}
);
runtime.queue = run.catch(() => undefined);
return run;
};
const handleEvent = async (
runtime: ConnectionRuntime,
ctx: RequestContext,
event: NostrEvent,
): Promise<void> => {
const walletSecret = runtime.walletSecret
if (walletSecret === null) return
const at = nowSeconds()
const walletSecret = runtime.walletSecret;
if (walletSecret === null) return;
const at = nowSeconds();
// replay safety (see the header): too-old requests are dropped
if (event.created_at < at - MAX_REQUEST_AGE_SECONDS) return
if (event.created_at < at - MAX_REQUEST_AGE_SECONDS) return;
const decrypted = decryptRequest(
walletSecret,
runtime.info.walletServicePubkey,
runtime.info.record.clientPubkey,
event,
at,
)
if (decrypted === null) return
);
if (decrypted === null) return;
if (decrypted.respond) {
await publishResponse(
runtime,
@@ -141,56 +141,56 @@ export const startService = async (
event.id,
decrypted.encryption,
decrypted.response,
)
return
);
return;
}
const response = await dispatchSerialized(runtime, ctx, decrypted.request)
await publishResponse(runtime, walletSecret, event.id, decrypted.encryption, response)
}
const response = await dispatchSerialized(runtime, ctx, decrypted.request);
await publishResponse(runtime, walletSecret, event.id, decrypted.encryption, response);
};
let accepting = true
let accepting = true;
// interrupts long observation waits (the invoice claim poll) at stop;
// the drain below still awaits tasks that reached a fund-critical commit
const stopController = new AbortController()
const inFlight = new Set<Promise<void>>()
const stopController = new AbortController();
const inFlight = new Set<Promise<void>>();
const track = (task: Promise<void>): void => {
inFlight.add(task)
inFlight.add(task);
void task.then(
() => inFlight.delete(task),
() => inFlight.delete(task),
)
}
);
};
const startBackground = (work: () => Promise<void>): boolean => {
if (!accepting) return false
track(work())
return true
}
if (!accepting) return false;
track(work());
return true;
};
let runtimes = ownedRecords.map((record) => {
const walletSecret = deriveNwcWalletKey(linkingPrivKey, record.clientPubkey)
const walletSecret = deriveNwcWalletKey(linkingPrivKey, record.clientPubkey);
const runtime: ConnectionRuntime = {
info: {record, walletServicePubkey: nwcWalletPubkey(walletSecret)},
info: { record, walletServicePubkey: nwcWalletPubkey(walletSecret) },
walletSecret,
invoices: new Map(),
queue: Promise.resolve(),
// replaced below, immediately - the field exists because the
// subscription callback closes over the runtime
sub: {close: () => undefined},
}
sub: { close: () => undefined },
};
const ctx: RequestContext = {
deps,
connection: () => runtime.info,
updateRecord: (updated) => {
runtime.info = {...runtime.info, record: updated}
runtime.info = { ...runtime.info, record: updated };
},
invoices: runtime.invoices,
nowSeconds,
assertOwner: () => {
deps.assertCurrentOwner()
assertSavedKeyOwner(ownerId)
deps.assertCurrentOwner();
assertSavedKeyOwner(ownerId);
},
startBackground,
stopSignal: stopController.signal,
}
};
runtime.sub = transport.subscribe(
record.relays,
{
@@ -199,60 +199,62 @@ export const startService = async (
since: nowSeconds(),
},
(event) => {
if (!accepting) return
if (!accepting) return;
const handler = handleEvent(runtime, ctx, event).catch((err) => {
deps.onError?.(err, runtime.info)
})
track(handler)
deps.onError?.(err, runtime.info);
});
track(handler);
},
)
return runtime
})
);
return runtime;
});
// info events: best-effort - a rejected publish must not sink startup;
// the client learns capabilities from its first error-free exchange too
for (const runtime of runtimes) {
const walletSecret = runtime.walletSecret
if (walletSecret === null) continue
const walletSecret = runtime.walletSecret;
if (walletSecret === null) continue;
try {
await transport.publish(
runtime.info.record.relays,
buildInfoEvent(walletSecret, nowSeconds()),
)
);
} catch (error) {
deps.onError?.(
error instanceof Error ? error : new Error('NWC info publication failed.', {cause: error}),
error instanceof Error
? error
: new Error('NWC info publication failed.', { cause: error }),
runtime.info,
)
);
}
}
const connections = runtimes.map((runtime) => runtime.info)
let stopPromise: Promise<void> | null = null
const connections = runtimes.map((runtime) => runtime.info);
let stopPromise: Promise<void> | null = null;
const stop = (): Promise<void> => {
if (stopPromise !== null) return stopPromise
accepting = false
for (const runtime of runtimes) runtime.sub.close()
stopController.abort()
if (stopPromise !== null) return stopPromise;
accepting = false;
for (const runtime of runtimes) runtime.sub.close();
stopController.abort();
stopPromise = Promise.allSettled([...inFlight])
.then((results) => {
for (const result of results) {
if (result.status === 'rejected') throw result.reason
if (result.status === 'rejected') throw result.reason;
}
})
.finally(() => {
for (const runtime of runtimes) {
runtime.walletSecret?.fill(0)
runtime.walletSecret = null
runtime.invoices.clear()
runtime.walletSecret?.fill(0);
runtime.walletSecret = null;
runtime.invoices.clear();
}
runtimes = []
})
return stopPromise
}
runtimes = [];
});
return stopPromise;
};
return {
connections,
stop,
}
}
};
};
src/lnurlcash/nwc/transport.ts
+16 -15
View File
@@ -4,36 +4,37 @@
// importing the service module never opens (or even references) a
// WebSocket.
import type {Filter as NostrFilter} from 'nostr-tools/filter'
import type { Filter as NostrFilter } from 'nostr-tools/filter';
import type {NostrEvent} from './protocol'
import type { NostrEvent } from './protocol';
export type {NostrFilter}
export type { NostrFilter };
export type NwcSubscription = {
close: () => void
}
close: () => void;
};
export type NwcTransport = {
publish: (relays: string[], event: NostrEvent) => Promise<void>
publish: (relays: string[], event: NostrEvent) => Promise<void>;
subscribe: (
relays: string[],
filter: NostrFilter,
onEvent: (event: NostrEvent) => void,
) => NwcSubscription
}
) => NwcSubscription;
};
export const defaultNwcTransport = async (): Promise<NwcTransport> => {
const {SimplePool} = await import('nostr-tools/pool')
const pool = new SimplePool()
const { SimplePool } = await import('nostr-tools/pool');
const pool = new SimplePool();
return {
publish: async (relays, event) => {
const results = await Promise.allSettled(pool.publish(relays, event))
const results = await Promise.allSettled(pool.publish(relays, event));
// one honest relay accepting is enough - same rule as the backup
if (!results.some((r) => r.status === 'fulfilled')) {
throw new Error('No relay accepted the event.')
throw new Error('No relay accepted the event.');
}
},
subscribe: (relays, filter, onEvent) => pool.subscribeMany(relays, filter, {onevent: onEvent}),
}
}
subscribe: (relays, filter, onEvent) =>
pool.subscribeMany(relays, filter, { onevent: onEvent }),
};
};
src/lnurlcash/ops.carve-crash.cases.ts
+100 -98
View File
@@ -1,165 +1,167 @@
import {describe, expect, it} from 'vitest'
import {noteK1} from 'lnurlcash-kit'
import { describe, expect, it } from 'vitest';
import { noteK1 } from 'lnurlcash-kit';
import type {CarveResult} from './ops'
import {ensureExactAmount, UnsupportedMultiBatchMergeError} from './ops'
import {requiredValue} from './test-utils'
import {makeBearer, mint, secret} from './ops.testHarness'
import type { CarveResult } from './ops';
import { ensureExactAmount, UnsupportedMultiBatchMergeError } from './ops';
import { requiredValue } from './test-utils';
import { makeBearer, mint, secret } from './ops.testHarness';
const allocatedSecrets = (...secrets: string[]): ((server: string, count: number) => Promise<readonly string[]>) => {
let served = false
const allocatedSecrets = (
...secrets: string[]
): ((server: string, count: number) => Promise<readonly string[]>) => {
let served = false;
return (_server, count) => {
if (served) throw new Error('The test expected a single allocation.')
served = true
return Promise.resolve(secrets.slice(0, count))
}
}
if (served) throw new Error('The test expected a single allocation.');
served = true;
return Promise.resolve(secrets.slice(0, count));
};
};
describe('ensureExactAmount crash safety', () => {
it('stages both split secrets before either hash reaches the mint', async () => {
const instance = await mint()
const sourceSecret = secret('70')
const targetSecret = secret('71')
const changeSecret = secret('72')
const bearer = await makeBearer(instance, sourceSecret, 21_000)
let staged: CarveResult | undefined
const instance = await mint();
const sourceSecret = secret('70');
const targetSecret = secret('71');
const changeSecret = secret('72');
const bearer = await makeBearer(instance, sourceSecret, 21_000);
let staged: CarveResult | undefined;
const observingFetch: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) {
expect(staged).toBeDefined()
expect(noteK1(requiredValue(staged).note.url)).toBe(targetSecret)
expect(noteK1(requiredValue(requiredValue(staged).change).url)).toBe(changeSecret)
expect(instance.state.noteState(sourceSecret)).toBe('outstanding')
expect(staged).toBeDefined();
expect(noteK1(requiredValue(staged).note.url)).toBe(targetSecret);
expect(noteK1(requiredValue(requiredValue(staged).change).url)).toBe(changeSecret);
expect(instance.state.noteState(sourceSecret)).toBe('outstanding');
}
return fetch(input, init)
}
return fetch(input, init);
};
const result = await ensureExactAmount([bearer], 5_000, {
fetch: observingFetch,
allocateOutputSecrets: allocatedSecrets(targetSecret, changeSecret),
onCarve: (prepared) => {
staged = prepared
staged = prepared;
},
})
});
expect(result.consumed.map((entry) => entry.id)).toEqual([bearer.id])
})
expect(result.consumed.map((entry) => entry.id)).toEqual([bearer.id]);
});
it('stages the merge secret before its hash reaches the mint', async () => {
const instance = await mint()
const firstSecret = secret('73')
const secondSecret = secret('74')
const mergedSecret = secret('75')
const first = await makeBearer(instance, firstSecret, 3_000)
const second = await makeBearer(instance, secondSecret, 4_000)
let staged: CarveResult | undefined
const instance = await mint();
const firstSecret = secret('73');
const secondSecret = secret('74');
const mergedSecret = secret('75');
const first = await makeBearer(instance, firstSecret, 3_000);
const second = await makeBearer(instance, secondSecret, 4_000);
let staged: CarveResult | undefined;
const observingFetch: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) {
expect(staged).toBeDefined()
expect(noteK1(requiredValue(staged).note.url)).toBe(mergedSecret)
expect(instance.state.noteState(firstSecret)).toBe('outstanding')
expect(instance.state.noteState(secondSecret)).toBe('outstanding')
expect(staged).toBeDefined();
expect(noteK1(requiredValue(staged).note.url)).toBe(mergedSecret);
expect(instance.state.noteState(firstSecret)).toBe('outstanding');
expect(instance.state.noteState(secondSecret)).toBe('outstanding');
}
return fetch(input, init)
}
return fetch(input, init);
};
await ensureExactAmount([first, second], 7_000, {
fetch: observingFetch,
allocateOutputSecrets: allocatedSecrets(mergedSecret),
onCarve: (prepared) => {
staged = prepared
staged = prepared;
},
})
});
expect(staged?.consumed.map((entry) => entry.id)).toEqual([first.id, second.id])
})
expect(staged?.consumed.map((entry) => entry.id)).toEqual([first.id, second.id]);
});
it('does not expose a staged split output to a second ambiguous rotation', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('76'), 21_000)
let mutationCount = 0
const instance = await mint();
const bearer = await makeBearer(instance, secret('76'), 21_000);
let mutationCount = 0;
const dropSecondMutation: typeof fetch = async (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
if (!url.includes('/w/cb')) return fetch(input, init)
mutationCount += 1
const response = await fetch(input, init)
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (!url.includes('/w/cb')) return fetch(input, init);
mutationCount += 1;
const response = await fetch(input, init);
if (mutationCount === 2) {
await response.arrayBuffer()
throw new Error('second mutation response lost')
await response.arrayBuffer();
throw new Error('second mutation response lost');
}
return response
}
return response;
};
const result = await ensureExactAmount([bearer], 5_000, {
fetch: dropSecondMutation,
mutationRetries: 0,
allocateOutputSecrets: allocatedSecrets(secret('77'), secret('78')),
onCarve: () => undefined,
})
});
expect(mutationCount).toBe(1)
const targetSecret = requiredValue(noteK1(result.note.url))
const changeSecret = requiredValue(noteK1(requiredValue(result.change).url))
expect(instance.state.noteState(targetSecret)).toBe('outstanding')
expect(instance.state.noteState(changeSecret)).toBe('outstanding')
})
expect(mutationCount).toBe(1);
const targetSecret = requiredValue(noteK1(result.note.url));
const changeSecret = requiredValue(noteK1(requiredValue(result.change).url));
expect(instance.state.noteState(targetSecret)).toBe('outstanding');
expect(instance.state.noteState(changeSecret)).toBe('outstanding');
});
it('rejects a multi-batch merge before any partial fold can land', async () => {
const instance = await mint()
const instance = await mint();
const bearers = await Promise.all(
Array.from({length: 21}, (_, index) =>
Array.from({ length: 21 }, (_, index) =>
makeBearer(instance, secret((128 + index).toString(16)), 1_000),
),
)
let mutationCount = 0
);
let mutationCount = 0;
const countingFetch: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
if (url.includes('/w/cb')) mutationCount += 1
return fetch(input, init)
}
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) mutationCount += 1;
return fetch(input, init);
};
const failure = ensureExactAmount(bearers, 21_000, {
fetch: countingFetch,
onCarve: () => undefined,
})
await expect(failure).rejects.toBeInstanceOf(UnsupportedMultiBatchMergeError)
expect(mutationCount).toBe(0)
});
await expect(failure).rejects.toBeInstanceOf(UnsupportedMultiBatchMergeError);
expect(mutationCount).toBe(0);
expect(
bearers.every(
(bearer) => instance.state.noteState(requiredValue(noteK1(bearer.url))) === 'outstanding',
),
).toBe(true)
})
).toBe(true);
});
it('checks ownership again immediately before a merge mutation', async () => {
const instance = await mint()
const firstSecret = secret('79')
const secondSecret = secret('7a')
const first = await makeBearer(instance, firstSecret, 3_000)
const second = await makeBearer(instance, secondSecret, 4_000)
let ownerChecks = 0
let mutationCount = 0
const instance = await mint();
const firstSecret = secret('79');
const secondSecret = secret('7a');
const first = await makeBearer(instance, firstSecret, 3_000);
const second = await makeBearer(instance, secondSecret, 4_000);
let ownerChecks = 0;
let mutationCount = 0;
const countingFetch: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
if (url.includes('/w/cb')) mutationCount += 1
return fetch(input, init)
}
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) mutationCount += 1;
return fetch(input, init);
};
await expect(
ensureExactAmount([first, second], 7_000, {
fetch: countingFetch,
allocateOutputSecrets: allocatedSecrets(secret('7b')),
assertOwner: () => {
ownerChecks += 1
if (ownerChecks === 3) throw new Error('wallet owner changed')
ownerChecks += 1;
if (ownerChecks === 3) throw new Error('wallet owner changed');
},
onCarve: () => undefined,
}),
).rejects.toThrow(/owner changed/)
).rejects.toThrow(/owner changed/);
expect(mutationCount).toBe(0)
expect(instance.state.noteState(firstSecret)).toBe('outstanding')
expect(instance.state.noteState(secondSecret)).toBe('outstanding')
})
})
expect(mutationCount).toBe(0);
expect(instance.state.noteState(firstSecret)).toBe('outstanding');
expect(instance.state.noteState(secondSecret)).toBe('outstanding');
});
});
src/lnurlcash/ops.carve.cases.ts
+220 -208
View File
@@ -1,15 +1,15 @@
import {describe, expect, it} from 'vitest'
import {fetchNoteInfo, noteK1, noteSignature} from 'lnurlcash-kit'
import { describe, expect, it } from 'vitest';
import { fetchNoteInfo, noteK1, noteSignature } from 'lnurlcash-kit';
import type {Bearer} from './types'
import type {CarveResult} from './ops'
import type { Bearer } from './types';
import type { CarveResult } from './ops';
import {
CarveCheckpointRequiredError,
OutputSecretAllocationRequiredError,
UncertainOutcomeError,
ensureExactAmount,
} from './ops'
import {requiredValue} from './test-utils'
} from './ops';
import { requiredValue } from './test-utils';
import {
allocateOutputSecrets,
makeBearer,
@@ -17,333 +17,345 @@ import {
noteUrl,
secret,
signatureKeysFor,
} from './ops.testHarness'
} from './ops.testHarness';
describe('ensureExactAmount', () => {
it('returns an already-exact note untouched, burning nothing', async () => {
const instance = await mint()
const k1 = secret('01')
const bearer = await makeBearer(instance, k1, 21_000)
const result = await ensureExactAmount([bearer], 21_000)
expect(noteK1(result.note.url)).toBe(k1)
expect(result.consumed).toEqual([])
expect(result.change).toBeUndefined()
expect(instance.state.noteState(k1)).toBe('outstanding')
})
const instance = await mint();
const k1 = secret('01');
const bearer = await makeBearer(instance, k1, 21_000);
const result = await ensureExactAmount([bearer], 21_000);
expect(noteK1(result.note.url)).toBe(k1);
expect(result.consumed).toEqual([]);
expect(result.change).toBeUndefined();
expect(instance.state.noteState(k1)).toBe('outstanding');
});
it('split path: carves an exact note off a larger one, with change', async () => {
const instance = await mint()
const k1 = secret('02')
const bearer = await makeBearer(instance, k1, 21_000)
const instance = await mint();
const k1 = secret('02');
const bearer = await makeBearer(instance, k1, 21_000);
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets,
mintSignatureKeys: signatureKeysFor(instance),
})
expect(result.note.amount).toBe(5_000)
expect(result.note.verified).toBe(true)
expect(result.change?.amount).toBe(16_000)
expect(result.consumed.map((entry) => entry.id)).toEqual([bearer.id])
expect(instance.state.noteState(k1)).toBe('burned')
const partK1 = requiredValue(noteK1(result.note.url))
const changeK1 = requiredValue(noteK1(requiredValue(result.change).url))
expect((await fetchNoteInfo(noteUrl(instance, partK1))).maxWithdrawable).toBe(5_000)
expect((await fetchNoteInfo(noteUrl(instance, changeK1))).maxWithdrawable).toBe(16_000)
})
});
expect(result.note.amount).toBe(5_000);
expect(result.note.verified).toBe(true);
expect(result.change?.amount).toBe(16_000);
expect(result.consumed.map((entry) => entry.id)).toEqual([bearer.id]);
expect(instance.state.noteState(k1)).toBe('burned');
const partK1 = requiredValue(noteK1(result.note.url));
const changeK1 = requiredValue(noteK1(requiredValue(result.change).url));
expect((await fetchNoteInfo(noteUrl(instance, partK1))).maxWithdrawable).toBe(5_000);
expect((await fetchNoteInfo(noteUrl(instance, changeK1))).maxWithdrawable).toBe(16_000);
});
it('merge path: combines notes summing exactly to the target', async () => {
const instance = await mint()
const first = await makeBearer(instance, secret('03'), 3_000)
const second = await makeBearer(instance, secret('04'), 4_000)
const result = await ensureExactAmount([first, second], 7_000, {onCarve: () => undefined, allocateOutputSecrets})
expect(result.note.amount).toBe(7_000)
expect(result.change).toBeUndefined()
expect(result.consumed).toHaveLength(2)
expect(instance.state.noteState(requiredValue(noteK1(first.url)))).toBe('burned')
expect(instance.state.noteState(requiredValue(noteK1(second.url)))).toBe('burned')
const mergedK1 = requiredValue(noteK1(result.note.url))
expect((await fetchNoteInfo(noteUrl(instance, mergedK1))).maxWithdrawable).toBe(7_000)
})
const instance = await mint();
const first = await makeBearer(instance, secret('03'), 3_000);
const second = await makeBearer(instance, secret('04'), 4_000);
const result = await ensureExactAmount([first, second], 7_000, {
onCarve: () => undefined,
allocateOutputSecrets,
});
expect(result.note.amount).toBe(7_000);
expect(result.change).toBeUndefined();
expect(result.consumed).toHaveLength(2);
expect(instance.state.noteState(requiredValue(noteK1(first.url)))).toBe('burned');
expect(instance.state.noteState(requiredValue(noteK1(second.url)))).toBe('burned');
const mergedK1 = requiredValue(noteK1(result.note.url));
expect((await fetchNoteInfo(noteUrl(instance, mergedK1))).maxWithdrawable).toBe(7_000);
});
it('merge+split path: splits the target off several notes in one request', async () => {
const instance = await mint()
const first = await makeBearer(instance, secret('05'), 3_000)
const second = await makeBearer(instance, secret('06'), 4_000)
const result = await ensureExactAmount([first, second], 5_000, {onCarve: () => undefined, allocateOutputSecrets})
expect(result.note.amount).toBe(5_000)
expect(result.change?.amount).toBe(2_000)
expect(result.consumed).toHaveLength(2)
const partK1 = requiredValue(noteK1(result.note.url))
const changeK1 = requiredValue(noteK1(requiredValue(result.change).url))
expect((await fetchNoteInfo(noteUrl(instance, partK1))).maxWithdrawable).toBe(5_000)
expect((await fetchNoteInfo(noteUrl(instance, changeK1))).maxWithdrawable).toBe(2_000)
})
const instance = await mint();
const first = await makeBearer(instance, secret('05'), 3_000);
const second = await makeBearer(instance, secret('06'), 4_000);
const result = await ensureExactAmount([first, second], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets,
});
expect(result.note.amount).toBe(5_000);
expect(result.change?.amount).toBe(2_000);
expect(result.consumed).toHaveLength(2);
const partK1 = requiredValue(noteK1(result.note.url));
const changeK1 = requiredValue(noteK1(requiredValue(result.change).url));
expect((await fetchNoteInfo(noteUrl(instance, partK1))).maxWithdrawable).toBe(5_000);
expect((await fetchNoteInfo(noteUrl(instance, changeK1))).maxWithdrawable).toBe(2_000);
});
it('excludes spent and unverified notes from selection', async () => {
const instance = await mint()
const spentBearer = await makeBearer(instance, secret('07'), 50_000)
const instance = await mint();
const spentBearer = await makeBearer(instance, secret('07'), 50_000);
const unverified: Bearer = {
...(await makeBearer(instance, secret('08'), 50_000)),
verified: false,
}
};
await expect(
ensureExactAmount([{...spentBearer, spent: true}, unverified], 5_000),
).rejects.toThrow(/enough/)
})
ensureExactAmount([{ ...spentBearer, spent: true }, unverified], 5_000),
).rejects.toThrow(/enough/);
});
it('refuses an amount no mint can cover', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('09'), 5_000)
await expect(ensureExactAmount([bearer], 50_000)).rejects.toThrow(/enough/)
})
const instance = await mint();
const bearer = await makeBearer(instance, secret('09'), 5_000);
await expect(ensureExactAmount([bearer], 50_000)).rejects.toThrow(/enough/);
});
it("rescues the fresh secrets when a split's answer is lost (probe: gone)", async () => {
const instance = await mint({dropAfterMutation: true})
const k1 = secret('10')
const bearer = await makeBearer(instance, k1, 21_000)
const result = await ensureExactAmount([bearer], 5_000, {onCarve: () => undefined, allocateOutputSecrets})
const partK1 = requiredValue(noteK1(result.note.url))
const changeK1 = requiredValue(noteK1(requiredValue(result.change).url))
expect(partK1).not.toBe(k1)
expect(instance.state.noteState(k1)).toBe('burned')
expect((await fetchNoteInfo(noteUrl(instance, partK1))).maxWithdrawable).toBe(5_000)
expect((await fetchNoteInfo(noteUrl(instance, changeK1))).maxWithdrawable).toBe(16_000)
})
const instance = await mint({ dropAfterMutation: true });
const k1 = secret('10');
const bearer = await makeBearer(instance, k1, 21_000);
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets,
});
const partK1 = requiredValue(noteK1(result.note.url));
const changeK1 = requiredValue(noteK1(requiredValue(result.change).url));
expect(partK1).not.toBe(k1);
expect(instance.state.noteState(k1)).toBe('burned');
expect((await fetchNoteInfo(noteUrl(instance, partK1))).maxWithdrawable).toBe(5_000);
expect((await fetchNoteInfo(noteUrl(instance, changeK1))).maxWithdrawable).toBe(16_000);
});
it('surfaces the possible outputs when neither mutation nor probe can be confirmed', async () => {
const instance = await mint()
const k1 = secret('11')
const bearer = await makeBearer(instance, k1, 21_000)
const instance = await mint();
const k1 = secret('11');
const bearer = await makeBearer(instance, k1, 21_000);
// every mutation answer is lost - the first attempt's AND the forced
// byte-identical replay's (the mint executed both; the replay is the
// recorded success served again, then dropped by the wrapper) - and
// every informational probe is unreachable, so neither the mutation
// nor the probe can be confirmed
const everythingDyingFetch: typeof fetch = async (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) {
const response = await fetch(input, init)
await response.arrayBuffer()
throw new Error('mutation response lost')
const response = await fetch(input, init);
await response.arrayBuffer();
throw new Error('mutation response lost');
}
return Promise.reject(new Error('probe unreachable'))
}
const checkpoints: CarveResult[] = []
return Promise.reject(new Error('probe unreachable'));
};
const checkpoints: CarveResult[] = [];
const failure = await ensureExactAmount([bearer], 5_000, {
fetch: everythingDyingFetch,
allocateOutputSecrets,
onCarve: (carve) => {
checkpoints.push(carve)
checkpoints.push(carve);
},
}).catch((error: unknown) => error)
expect(failure).toBeInstanceOf(UncertainOutcomeError)
if (!(failure instanceof UncertainOutcomeError)) throw failure
expect(failure.possibleOutputs).toEqual([])
expect(checkpoints).toHaveLength(1)
expect(checkpoints[0]?.consumed).toEqual([])
expect(checkpoints[0]?.note.amount).toBe(5_000)
expect(checkpoints[0]?.change?.amount).toBe(16_000)
})
}).catch((error: unknown) => error);
expect(failure).toBeInstanceOf(UncertainOutcomeError);
if (!(failure instanceof UncertainOutcomeError)) throw failure;
expect(failure.possibleOutputs).toEqual([]);
expect(checkpoints).toHaveLength(1);
expect(checkpoints[0]?.consumed).toEqual([]);
expect(checkpoints[0]?.note.amount).toBe(5_000);
expect(checkpoints[0]?.change?.amount).toBe(16_000);
});
it('stages outputs before wire and retires inputs only after the mutation lands', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('12'), 21_000)
const seen: CarveResult[] = []
const instance = await mint();
const bearer = await makeBearer(instance, secret('12'), 21_000);
const seen: CarveResult[] = [];
const result = await ensureExactAmount([bearer], 5_000, {
allocateOutputSecrets,
onCarve: (carve) => {
seen.push(carve)
seen.push(carve);
},
mintSignatureKeys: signatureKeysFor(instance),
})
expect(seen).toHaveLength(2)
expect(seen[0]?.note.verified).toBe(false)
expect(seen[0]?.consumed).toEqual([])
expect(seen[0]?.change).toBeDefined()
expect(noteK1(requiredValue(seen[0]).note.url)).toBe(noteK1(result.note.url))
});
expect(seen).toHaveLength(2);
expect(seen[0]?.note.verified).toBe(false);
expect(seen[0]?.consumed).toEqual([]);
expect(seen[0]?.change).toBeDefined();
expect(noteK1(requiredValue(seen[0]).note.url)).toBe(noteK1(result.note.url));
expect(noteK1(requiredValue(requiredValue(seen[0]).change).url)).toBe(
noteK1(requiredValue(result.change).url),
)
);
// the landed checkpoint re-reports the SAME staged output (same secret)
// - its URL has since gained the mint's signature
expect(noteK1(requiredValue(seen[1]).note.url)).toBe(noteK1(requiredValue(seen[0]).note.url))
expect(noteSignature(requiredValue(seen[1]).note.url)).not.toBeNull()
expect(seen[1]?.note.verified).toBe(true)
expect(seen[1]?.change).toBeUndefined()
expect(seen[1]?.consumed).toEqual(result.consumed)
expect(result.consumed).toHaveLength(1)
})
expect(noteK1(requiredValue(seen[1]).note.url)).toBe(noteK1(requiredValue(seen[0]).note.url));
expect(noteSignature(requiredValue(seen[1]).note.url)).not.toBeNull();
expect(seen[1]?.note.verified).toBe(true);
expect(seen[1]?.change).toBeUndefined();
expect(seen[1]?.consumed).toEqual(result.consumed);
expect(result.consumed).toHaveLength(1);
});
it('does not stage the split change again during the landed checkpoint', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('17'), 21_000)
const trackedSecrets = new Set<string>()
const retiredIds = new Set<string>()
const instance = await mint();
const bearer = await makeBearer(instance, secret('17'), 21_000);
const trackedSecrets = new Set<string>();
const retiredIds = new Set<string>();
const result = await ensureExactAmount([bearer], 5_000, {
allocateOutputSecrets,
onCarve: (carve) => {
// checkpoints identify an output by its secret: the landed phase's
// URL has gained a signature the staged phase could not have had
const k1 = noteK1(carve.note.url)
if (k1) trackedSecrets.add(k1)
const changeK1 = carve.change ? noteK1(carve.change.url) : null
if (changeK1) trackedSecrets.add(changeK1)
for (const consumed of carve.consumed) retiredIds.add(consumed.id)
const k1 = noteK1(carve.note.url);
if (k1) trackedSecrets.add(k1);
const changeK1 = carve.change ? noteK1(carve.change.url) : null;
if (changeK1) trackedSecrets.add(changeK1);
for (const consumed of carve.consumed) retiredIds.add(consumed.id);
},
})
});
expect(trackedSecrets).toEqual(
new Set([
requiredValue(noteK1(result.note.url)),
requiredValue(noteK1(requiredValue(result.change).url)),
]),
)
expect(retiredIds).toEqual(new Set([bearer.id]))
})
);
expect(retiredIds).toEqual(new Set([bearer.id]));
});
it('keeps staged outputs recoverable when the landed checkpoint fails', async () => {
const instance = await mint()
const sourceSecret = secret('15')
const bearer = await makeBearer(instance, sourceSecret, 21_000)
const seen: CarveResult[] = []
const instance = await mint();
const sourceSecret = secret('15');
const bearer = await makeBearer(instance, sourceSecret, 21_000);
const seen: CarveResult[] = [];
await expect(
ensureExactAmount([bearer], 5_000, {
allocateOutputSecrets,
onCarve: (carve) => {
seen.push(carve)
if (carve.consumed.length > 0) throw new Error('final commit failed')
seen.push(carve);
if (carve.consumed.length > 0) throw new Error('final commit failed');
},
}),
).rejects.toThrow(/final commit failed/)
).rejects.toThrow(/final commit failed/);
expect(seen).toHaveLength(2)
expect(seen[0]?.consumed).toEqual([])
expect(seen[0]?.change).toBeDefined()
expect(instance.state.noteState(sourceSecret)).toBe('burned')
expect(seen).toHaveLength(2);
expect(seen[0]?.consumed).toEqual([]);
expect(seen[0]?.change).toBeDefined();
expect(instance.state.noteState(sourceSecret)).toBe('burned');
expect(instance.state.noteState(requiredValue(noteK1(requiredValue(seen[0]).note.url)))).toBe(
'outstanding',
)
);
expect(
instance.state.noteState(
requiredValue(noteK1(requiredValue(requiredValue(seen[0]).change).url)),
),
).toBe('outstanding')
})
).toBe('outstanding');
});
it('never fires onCarve for an already-exact note - nothing was burned', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('13'), 21_000)
let called = false
const instance = await mint();
const bearer = await makeBearer(instance, secret('13'), 21_000);
let called = false;
const result = await ensureExactAmount([bearer], 21_000, {
onCarve: () => {
called = true
called = true;
},
})
expect(called).toBe(false)
expect(result.consumed).toEqual([])
})
});
expect(called).toBe(false);
expect(result.consumed).toEqual([]);
});
it('requires a typed durable checkpoint before a mutating carve', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('16'), 21_000)
const instance = await mint();
const bearer = await makeBearer(instance, secret('16'), 21_000);
await expect(ensureExactAmount([bearer], 5_000)).rejects.toBeInstanceOf(
CarveCheckpointRequiredError,
)
expect(instance.state.noteState(secret('16'))).toBe('outstanding')
})
);
expect(instance.state.noteState(secret('16'))).toBe('outstanding');
});
it('propagates an onCarve failure before the carve reaches the mint', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('14'), 21_000)
const instance = await mint();
const bearer = await makeBearer(instance, secret('14'), 21_000);
await expect(
ensureExactAmount([bearer], 5_000, {
allocateOutputSecrets,
onCarve: () => {
throw new Error('commit failed')
throw new Error('commit failed');
},
}),
).rejects.toThrow(/commit failed/)
expect(instance.state.noteState(secret('14'))).toBe('outstanding')
})
).rejects.toThrow(/commit failed/);
expect(instance.state.noteState(secret('14'))).toBe('outstanding');
});
it('draws the split outputs from the caller allocation path, exactly two', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('80'), 21_000)
const allocations: Array<{server: string; count: number}> = []
const allocated = [secret('81'), secret('82')]
const instance = await mint();
const bearer = await makeBearer(instance, secret('80'), 21_000);
const allocations: Array<{ server: string; count: number }> = [];
const allocated = [secret('81'), secret('82')];
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets: (server, count) => {
allocations.push({server, count})
return Promise.resolve(allocated.slice(0, count))
allocations.push({ server, count });
return Promise.resolve(allocated.slice(0, count));
},
})
});
expect(allocations).toEqual([{server: `127.0.0.1:${instance.port}`, count: 2}])
expect(noteK1(result.note.url)).toBe(allocated[0])
expect(noteK1(requiredValue(result.change).url)).toBe(allocated[1])
})
expect(allocations).toEqual([{ server: `127.0.0.1:${instance.port}`, count: 2 }]);
expect(noteK1(result.note.url)).toBe(allocated[0]);
expect(noteK1(requiredValue(result.change).url)).toBe(allocated[1]);
});
it('draws the merge output from the caller allocation path, exactly one', async () => {
const instance = await mint()
const first = await makeBearer(instance, secret('83'), 3_000)
const second = await makeBearer(instance, secret('84'), 4_000)
const allocations: Array<{server: string; count: number}> = []
const allocated = [secret('85')]
const instance = await mint();
const first = await makeBearer(instance, secret('83'), 3_000);
const second = await makeBearer(instance, secret('84'), 4_000);
const allocations: Array<{ server: string; count: number }> = [];
const allocated = [secret('85')];
const result = await ensureExactAmount([first, second], 7_000, {
onCarve: () => undefined,
allocateOutputSecrets: (server, count) => {
allocations.push({server, count})
return Promise.resolve(allocated.slice(0, count))
allocations.push({ server, count });
return Promise.resolve(allocated.slice(0, count));
},
})
});
expect(allocations).toEqual([{server: `127.0.0.1:${instance.port}`, count: 1}])
expect(noteK1(result.note.url)).toBe(allocated[0])
})
expect(allocations).toEqual([{ server: `127.0.0.1:${instance.port}`, count: 1 }]);
expect(noteK1(result.note.url)).toBe(allocated[0]);
});
it('allocates nothing when one note already holds the exact amount', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('86'), 21_000)
let allocations = 0
const instance = await mint();
const bearer = await makeBearer(instance, secret('86'), 21_000);
let allocations = 0;
await ensureExactAmount([bearer], 21_000, {
allocateOutputSecrets: () => {
allocations += 1
return Promise.resolve([])
allocations += 1;
return Promise.resolve([]);
},
})
});
expect(allocations).toBe(0)
})
expect(allocations).toBe(0);
});
it('refuses a mutating carve without an allocation path, before any staging', async () => {
const instance = await mint()
const split = await makeBearer(instance, secret('87'), 21_000)
const mergeA = await makeBearer(instance, secret('88'), 3_000)
const mergeB = await makeBearer(instance, secret('89'), 4_000)
let mutations = 0
const instance = await mint();
const split = await makeBearer(instance, secret('87'), 21_000);
const mergeA = await makeBearer(instance, secret('88'), 3_000);
const mergeB = await makeBearer(instance, secret('89'), 4_000);
let mutations = 0;
const countingFetch: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
if (url.includes('/w/cb')) mutations += 1
return fetch(input, init)
}
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) mutations += 1;
return fetch(input, init);
};
await expect(
ensureExactAmount([split], 5_000, {fetch: countingFetch, onCarve: () => undefined}),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError)
ensureExactAmount([split], 5_000, { fetch: countingFetch, onCarve: () => undefined }),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError);
await expect(
ensureExactAmount([mergeA, mergeB], 7_000, {fetch: countingFetch, onCarve: () => undefined}),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError)
ensureExactAmount([mergeA, mergeB], 7_000, {
fetch: countingFetch,
onCarve: () => undefined,
}),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError);
expect(mutations).toBe(0)
expect(instance.state.noteState(secret('87'))).toBe('outstanding')
expect(instance.state.noteState(secret('88'))).toBe('outstanding')
expect(instance.state.noteState(secret('89'))).toBe('outstanding')
})
})
expect(mutations).toBe(0);
expect(instance.state.noteState(secret('87'))).toBe('outstanding');
expect(instance.state.noteState(secret('88'))).toBe('outstanding');
expect(instance.state.noteState(secret('89'))).toBe('outstanding');
});
});
src/lnurlcash/ops.mint-named.cases.ts
+61 -55
View File
@@ -1,106 +1,112 @@
import {describe, expect, it} from 'vitest'
import {hashK1, noteK1} from 'lnurlcash-kit'
import { describe, expect, it } from 'vitest';
import { hashK1, noteK1 } from 'lnurlcash-kit';
import {claimMintedNote, OutputSecretAllocationRequiredError, prepareMint} from './ops'
import {requiredValue} from './test-utils'
import type {Mint} from './ops.testHarness'
import {allocateOutputSecrets, mint, persistOutput, secret, settleLastInvoice} from './ops.testHarness'
import { claimMintedNote, OutputSecretAllocationRequiredError, prepareMint } from './ops';
import { requiredValue } from './test-utils';
import type { Mint } from './ops.testHarness';
import {
allocateOutputSecrets,
mint,
persistOutput,
secret,
settleLastInvoice,
} from './ops.testHarness';
const HEX32 = /^[0-9a-f]{64}$/
const HEX32 = /^[0-9a-f]{64}$/;
const boundInvoice = (instance: Mint) =>
[...instance.state.invoices.values()].find((invoice) => invoice.boundTo)
[...instance.state.invoices.values()].find((invoice) => invoice.boundTo);
describe('mint -> claim, comment-bound output', () => {
it('names the quote with the hash of a wallet-chosen secret', async () => {
const instance = await mint({testHooks: true})
const instance = await mint({ testHooks: true });
const prepared = await prepareMint(`mint@127.0.0.1:${instance.port}`, 21_000, {
persistOutput,
allocateOutputSecrets,
})
expect(prepared.noteSecret).toMatch(HEX32)
expect(boundInvoice(instance)?.boundTo).toBe(hashK1(prepared.noteSecret))
})
});
expect(prepared.noteSecret).toMatch(HEX32);
expect(boundInvoice(instance)?.boundTo).toBe(hashK1(prepared.noteSecret));
});
it('claims the output at the wallet secret without rotating it', async () => {
const instance = await mint({testHooks: true})
const instance = await mint({ testHooks: true });
const prepared = await prepareMint(`mint@127.0.0.1:${instance.port}`, 21_000, {
persistOutput,
allocateOutputSecrets,
})
const preimage = await settleLastInvoice(instance)
});
const preimage = await settleLastInvoice(instance);
const claimed = await claimMintedNote(prepared, {
intervalMs: 10,
intervalCapMs: 50,
maxWaitMs: 5_000,
})
expect(claimed.note.verified).toBe(true)
expect(claimed.note.amount).toBe(21_000)
expect(claimed.note.callback).toBe(`${instance.url}/w/cb`)
expect(noteK1(claimed.note.url)).toBe(prepared.noteSecret)
expect(instance.state.noteState(prepared.noteSecret)).toBe('outstanding')
expect(instance.state.noteState(preimage)).toBeNull()
})
});
expect(claimed.note.verified).toBe(true);
expect(claimed.note.amount).toBe(21_000);
expect(claimed.note.callback).toBe(`${instance.url}/w/cb`);
expect(noteK1(claimed.note.url)).toBe(prepared.noteSecret);
expect(instance.state.noteState(prepared.noteSecret)).toBe('outstanding');
expect(instance.state.noteState(preimage)).toBeNull();
});
it('times out cleanly when the invoice is never paid', async () => {
const instance = await mint({testHooks: true})
const instance = await mint({ testHooks: true });
const prepared = await prepareMint(`mint@127.0.0.1:${instance.port}`, 21_000, {
persistOutput,
allocateOutputSecrets,
})
});
await expect(
claimMintedNote(prepared, {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 100}),
).rejects.toThrow(/not confirmed/i)
})
claimMintedNote(prepared, { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 100 }),
).rejects.toThrow(/not confirmed/i);
});
it('uses the required comment even when the optional h extension is advertised', async () => {
const instance = await mint({mintToHash: true, testHooks: true})
const instance = await mint({ mintToHash: true, testHooks: true });
const prepared = await prepareMint(`mint@127.0.0.1:${instance.port}`, 21_000, {
persistOutput,
allocateOutputSecrets,
})
expect(boundInvoice(instance)?.boundTo).toBe(hashK1(prepared.noteSecret))
await settleLastInvoice(instance)
});
expect(boundInvoice(instance)?.boundTo).toBe(hashK1(prepared.noteSecret));
await settleLastInvoice(instance);
const claimed = await claimMintedNote(prepared, {
intervalMs: 10,
intervalCapMs: 50,
maxWaitMs: 5_000,
})
expect(noteK1(claimed.note.url)).toBe(prepared.noteSecret)
expect(requiredValue(noteK1(claimed.note.url))).toMatch(HEX32)
})
});
expect(noteK1(claimed.note.url)).toBe(prepared.noteSecret);
expect(requiredValue(noteK1(claimed.note.url))).toMatch(HEX32);
});
it('draws the staged note secret from the caller allocation path', async () => {
const instance = await mint({testHooks: true})
const allocations: Array<{server: string; count: number}> = []
const allocated = [secret('90')]
const instance = await mint({ testHooks: true });
const allocations: Array<{ server: string; count: number }> = [];
const allocated = [secret('90')];
const prepared = await prepareMint(`mint@127.0.0.1:${instance.port}`, 21_000, {
persistOutput,
allocateOutputSecrets: (server, count) => {
allocations.push({server, count})
return Promise.resolve(allocated.slice(0, count))
allocations.push({ server, count });
return Promise.resolve(allocated.slice(0, count));
},
})
});
expect(allocations).toEqual([{server: `127.0.0.1:${instance.port}`, count: 1}])
expect(prepared.noteSecret).toBe(allocated[0])
expect(boundInvoice(instance)?.boundTo).toBe(hashK1(requiredValue(allocated[0])))
})
expect(allocations).toEqual([{ server: `127.0.0.1:${instance.port}`, count: 1 }]);
expect(prepared.noteSecret).toBe(allocated[0]);
expect(boundInvoice(instance)?.boundTo).toBe(hashK1(requiredValue(allocated[0])));
});
it('refuses to prepare without an allocation path - nothing staged, no invoice', async () => {
const instance = await mint({testHooks: true})
let persisted = 0
const instance = await mint({ testHooks: true });
let persisted = 0;
await expect(
prepareMint(`mint@127.0.0.1:${instance.port}`, 21_000, {
persistOutput: () => {
persisted += 1
persisted += 1;
},
}),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError)
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError);
expect(persisted).toBe(0)
expect(instance.state.invoices.size).toBe(0)
})
})
expect(persisted).toBe(0);
expect(instance.state.invoices.size).toBe(0);
});
});
src/lnurlcash/ops.mint-receive.cases.ts
+100 -100
View File
@@ -1,4 +1,4 @@
import {describe, expect, it} from 'vitest'
import { describe, expect, it } from 'vitest';
import {
NoteSpentError,
PendingNoteError,
@@ -6,7 +6,7 @@ import {
meltNote,
noteK1,
rotateNote,
} from 'lnurlcash-kit'
} from 'lnurlcash-kit';
import {
claimMintedNote,
@@ -14,9 +14,9 @@ import {
prepareMint,
receiveBearer,
ReceiveRotationStagingRequiredError,
} from './ops'
import {requiredValue} from './test-utils'
import type {NewBearer} from './types'
} from './ops';
import { requiredValue } from './test-utils';
import type { NewBearer } from './types';
import {
allocateOutputSecrets,
makeBearer,
@@ -26,161 +26,161 @@ import {
secret,
settleLastInvoice,
stageRotation,
} from './ops.testHarness'
} from './ops.testHarness';
describe('mint fee', () => {
it('grosses the invoice up for an advertised mint fee', async () => {
const instance = await mint({testHooks: true, baseFeeMsat: 1_000, feePpm: 2_000})
const instance = await mint({ testHooks: true, baseFeeMsat: 1_000, feePpm: 2_000 });
const prepared = await prepareMint(`mint@127.0.0.1:${instance.port}`, 100_000, {
persistOutput,
allocateOutputSecrets,
})
expect(prepared.grossMsat).toBeGreaterThan(100_000)
await settleLastInvoice(instance)
});
expect(prepared.grossMsat).toBeGreaterThan(100_000);
await settleLastInvoice(instance);
const claimed = await claimMintedNote(prepared, {
intervalMs: 10,
intervalCapMs: 20,
maxWaitMs: 5_000,
})
});
// the service's maxWithdrawable is authoritative: the fee is withheld
// from the gross, so the note nets between the asked value and the gross
expect(claimed.note.amount).toBeGreaterThanOrEqual(99_000)
expect(claimed.note.amount).toBeLessThanOrEqual(prepared.grossMsat)
})
})
expect(claimed.note.amount).toBeGreaterThanOrEqual(99_000);
expect(claimed.note.amount).toBeLessThanOrEqual(prepared.grossMsat);
});
});
describe('receiveBearer', () => {
it('stages the rotation output before the rotate can reach the mint', async () => {
const instance = await mint()
const senderK1 = secret('94')
instance.state.creditNote(senderK1, 21_000)
const rotationSecret = secret('95')
let staged: NewBearer | undefined
const instance = await mint();
const senderK1 = secret('94');
instance.state.creditNote(senderK1, 21_000);
const rotationSecret = secret('95');
let staged: NewBearer | undefined;
const observingFetch: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
if (url.includes('/w/cb')) expect(staged).toBeDefined()
return fetch(input, init)
}
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) expect(staged).toBeDefined();
return fetch(input, init);
};
const received = await receiveBearer(noteUrl(instance, senderK1, 21_000), [], {
fetch: observingFetch,
allocateOutputSecrets: () => Promise.resolve([rotationSecret]),
stageRotation: (note) => {
staged = note
staged = note;
},
})
});
expect(received.stage).toBe('finalize')
expect(received.rotated).toBe(true)
expect(noteK1(received.note.url)).toBe(rotationSecret)
expect(noteK1(requiredValue(staged).url)).toBe(rotationSecret)
expect(requiredValue(staged).verified).toBe(false)
expect(requiredValue(staged).pendingMint?.sourceRecoverySecret).toBe(senderK1)
expect(instance.state.noteState(senderK1)).toBe('burned')
expect(instance.state.noteState(rotationSecret)).toBe('outstanding')
})
expect(received.stage).toBe('finalize');
expect(received.rotated).toBe(true);
expect(noteK1(received.note.url)).toBe(rotationSecret);
expect(noteK1(requiredValue(staged).url)).toBe(rotationSecret);
expect(requiredValue(staged).verified).toBe(false);
expect(requiredValue(staged).pendingMint?.sourceRecoverySecret).toBe(senderK1);
expect(instance.state.noteState(senderK1)).toBe('burned');
expect(instance.state.noteState(rotationSecret)).toBe('outstanding');
});
it('reports discard when the rotate provably never landed', async () => {
const instance = await mint()
const senderK1 = secret('96')
instance.state.creditNote(senderK1, 21_000)
const rotationSecret = secret('97')
let staged: NewBearer | undefined
const instance = await mint();
const senderK1 = secret('96');
instance.state.creditNote(senderK1, 21_000);
const rotationSecret = secret('97');
let staged: NewBearer | undefined;
const failingFetch: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
if (url.includes('/w/cb')) return Promise.reject(new Error('connection reset'))
return fetch(input, init)
}
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) return Promise.reject(new Error('connection reset'));
return fetch(input, init);
};
const received = await receiveBearer(noteUrl(instance, senderK1, 21_000), [], {
fetch: failingFetch,
allocateOutputSecrets: () => Promise.resolve([rotationSecret]),
stageRotation: (note) => {
staged = note
staged = note;
},
})
});
expect(received.stage).toBe('discard')
expect(received.rotated).toBe(false)
expect(received.note.verified).toBe(true)
expect(received.rotationError).toBeDefined()
expect(received.stage).toBe('discard');
expect(received.rotated).toBe(false);
expect(received.note.verified).toBe(true);
expect(received.rotationError).toBeDefined();
// nothing landed: both the sender's copy and the would-be output live on
expect(instance.state.noteState(senderK1)).toBe('outstanding')
expect(instance.state.noteState(rotationSecret)).toBeNull()
expect(staged).toBeDefined()
})
expect(instance.state.noteState(senderK1)).toBe('outstanding');
expect(instance.state.noteState(rotationSecret)).toBeNull();
expect(staged).toBeDefined();
});
it("verifies an incoming note and rotates it, burning the sender's copy", async () => {
const instance = await mint()
const senderK1 = secret('20')
instance.state.creditNote(senderK1, 21_000)
const instance = await mint();
const senderK1 = secret('20');
instance.state.creditNote(senderK1, 21_000);
const received = await receiveBearer(noteUrl(instance, senderK1, 21_000), [], {
allocateOutputSecrets,
stageRotation,
})
expect(received.rotated).toBe(true)
expect(received.stage).toBe('finalize')
expect(received.note.amount).toBe(21_000)
expect(received.note.verified).toBe(true)
const newK1 = requiredValue(noteK1(received.note.url))
expect(newK1).not.toBe(senderK1)
expect(instance.state.noteState(senderK1)).toBe('burned')
expect(instance.state.noteState(newK1)).toBe('outstanding')
})
});
expect(received.rotated).toBe(true);
expect(received.stage).toBe('finalize');
expect(received.note.amount).toBe(21_000);
expect(received.note.verified).toBe(true);
const newK1 = requiredValue(noteK1(received.note.url));
expect(newK1).not.toBe(senderK1);
expect(instance.state.noteState(senderK1)).toBe('burned');
expect(instance.state.noteState(newK1)).toBe('outstanding');
});
it('refuses a note the wallet already holds', async () => {
const instance = await mint()
const senderK1 = secret('21')
const existing = await makeBearer(instance, senderK1, 21_000)
const instance = await mint();
const senderK1 = secret('21');
const existing = await makeBearer(instance, senderK1, 21_000);
await expect(receiveBearer(noteUrl(instance, senderK1, 21_000), [existing])).rejects.toThrow(
/already/,
)
})
);
});
it('surfaces a spent note as definitively spent', async () => {
const instance = await mint()
const k1 = secret('22')
const bearer = await makeBearer(instance, k1, 21_000)
const info = await fetchNoteInfo(bearer.url)
await rotateNote(info.callback, k1)
const instance = await mint();
const k1 = secret('22');
const bearer = await makeBearer(instance, k1, 21_000);
const info = await fetchNoteInfo(bearer.url);
await rotateNote(info.callback, k1);
await expect(receiveBearer(noteUrl(instance, k1, 21_000), [])).rejects.toBeInstanceOf(
NoteSpentError,
)
})
);
});
it('surfaces a note locked mid-melt as pending, not as unverified', async () => {
const instance = await mint({meltNeverSettles: true})
const k1 = secret('23')
const bearer = await makeBearer(instance, k1, 21_000)
await meltNote(bearer.callback, k1, 'lnbc21n1pjqrstuvwxyz')
const instance = await mint({ meltNeverSettles: true });
const k1 = secret('23');
const bearer = await makeBearer(instance, k1, 21_000);
await meltNote(bearer.callback, k1, 'lnbc21n1pjqrstuvwxyz');
await expect(
receiveBearer(noteUrl(instance, k1, 21_000), [], {
allocateOutputSecrets,
stageRotation,
}),
).rejects.toBeInstanceOf(PendingNoteError)
})
).rejects.toBeInstanceOf(PendingNoteError);
});
it('refuses to rotate without a durable staging checkpoint', async () => {
const instance = await mint()
const senderK1 = secret('9a')
instance.state.creditNote(senderK1, 21_000)
const instance = await mint();
const senderK1 = secret('9a');
instance.state.creditNote(senderK1, 21_000);
await expect(
receiveBearer(noteUrl(instance, senderK1, 21_000), [], {allocateOutputSecrets}),
).rejects.toBeInstanceOf(ReceiveRotationStagingRequiredError)
receiveBearer(noteUrl(instance, senderK1, 21_000), [], { allocateOutputSecrets }),
).rejects.toBeInstanceOf(ReceiveRotationStagingRequiredError);
// the sender's copy is untouched - no rotation was attempted
expect(instance.state.noteState(senderK1)).toBe('outstanding')
})
expect(instance.state.noteState(senderK1)).toBe('outstanding');
});
it('refuses to rotate without an allocation path', async () => {
const instance = await mint()
const senderK1 = secret('9b')
instance.state.creditNote(senderK1, 21_000)
const instance = await mint();
const senderK1 = secret('9b');
instance.state.creditNote(senderK1, 21_000);
await expect(
receiveBearer(noteUrl(instance, senderK1, 21_000), [], {stageRotation}),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError)
expect(instance.state.noteState(senderK1)).toBe('outstanding')
})
})
receiveBearer(noteUrl(instance, senderK1, 21_000), [], { stageRotation }),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError);
expect(instance.state.noteState(senderK1)).toBe('outstanding');
});
});
src/lnurlcash/ops.pay.cases.ts
+122 -122
View File
@@ -1,30 +1,30 @@
import {describe, expect, it} from 'vitest'
import {noteK1} from 'lnurlcash-kit'
import { describe, expect, it } from 'vitest';
import { noteK1 } from 'lnurlcash-kit';
import {
OutputSecretAllocationRequiredError,
PayReturnCheckpointRequiredError,
payWithBearers,
} from './ops'
import {requiredValue} from './test-utils'
import {allocateOutputSecrets, makeBearer, mint, secret} from './ops.testHarness'
} from './ops';
import { requiredValue } from './test-utils';
import { allocateOutputSecrets, makeBearer, mint, secret } from './ops.testHarness';
describe('payWithBearers', () => {
it('pays a bolt11 invoice by melting an exact note (settled)', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('30'), 21_000)
const instance = await mint();
const bearer = await makeBearer(instance, secret('30'), 21_000);
const result = await payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000},
})
expect(result.outcome).toBe('settled')
expect(instance.state.noteState(secret('30'))).toBe('burned')
})
poll: { intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000 },
});
expect(result.outcome).toBe('settled');
expect(instance.state.noteState(secret('30'))).toBe('burned');
});
it('pays a Lightning Address by requesting an invoice first', async () => {
const payer = await mint()
const bearer = await makeBearer(payer, secret('31'), 21_000)
const payer = await mint();
const bearer = await makeBearer(payer, secret('31'), 21_000);
const payeeFetch: typeof fetch = (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.startsWith('https://payee.example/.well-known/lnurlp/alice')) {
return Promise.resolve(
Response.json({
@@ -34,184 +34,184 @@ describe('payWithBearers', () => {
maxSendable: 100_000_000,
metadata: '[]',
}),
)
);
}
if (url.startsWith('https://payee.example/invoice')) {
return Promise.resolve(Response.json({pr: 'lnbc210n1pjqrstuvwxyz'}))
return Promise.resolve(Response.json({ pr: 'lnbc210n1pjqrstuvwxyz' }));
}
return fetch(input, init)
}
return fetch(input, init);
};
const result = await payWithBearers([bearer], 'alice@payee.example', {
amountMsat: 21_000,
kit: {fetch: payeeFetch},
poll: {intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000},
})
expect(result.outcome).toBe('settled')
expect(result.invoice).toMatch(/^lnbc/)
expect(payer.state.noteState(secret('31'))).toBe('burned')
})
kit: { fetch: payeeFetch },
poll: { intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000 },
});
expect(result.outcome).toBe('settled');
expect(result.invoice).toMatch(/^lnbc/);
expect(payer.state.noteState(secret('31'))).toBe('burned');
});
it('carves the exact amount out of a larger note before melting', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('32'), 50_000)
const instance = await mint();
const bearer = await makeBearer(instance, secret('32'), 50_000);
const result = await payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000},
poll: { intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000 },
allocateOutputSecrets,
onCarve: () => undefined,
})
expect(result.outcome).toBe('settled')
expect(instance.state.noteState(secret('32'))).toBe('burned')
expect(result.carve.consumed.map((entry) => entry.id)).toEqual([bearer.id])
expect(result.carve.change?.amount).toBe(29_000)
const change = requiredValue(result.carve.change)
expect(instance.state.noteState(requiredValue(noteK1(change.url)))).toBe('outstanding')
})
});
expect(result.outcome).toBe('settled');
expect(instance.state.noteState(secret('32'))).toBe('burned');
expect(result.carve.consumed.map((entry) => entry.id)).toEqual([bearer.id]);
expect(result.carve.change?.amount).toBe(29_000);
const change = requiredValue(result.carve.change);
expect(instance.state.noteState(requiredValue(noteK1(change.url)))).toBe('outstanding');
});
it('classifies a failed melt as funds-returned once the note is spendable again', async () => {
const instance = await mint({meltAlwaysFails: true})
const bearer = await makeBearer(instance, secret('33'), 21_000)
const instance = await mint({ meltAlwaysFails: true });
const bearer = await makeBearer(instance, secret('33'), 21_000);
const result = await payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
allocateOutputSecrets,
onReturnReady: () => undefined,
})
expect(result.outcome).toBe('failed-funds-returned')
expect(instance.state.noteState(secret('33'))).toBe('burned')
const rotatedNote = requiredValue(result.rotatedNote)
expect(rotatedNote.verified).toBe(true)
expect(instance.state.noteState(requiredValue(noteK1(rotatedNote.url)))).toBe('outstanding')
})
});
expect(result.outcome).toBe('failed-funds-returned');
expect(instance.state.noteState(secret('33'))).toBe('burned');
const rotatedNote = requiredValue(result.rotatedNote);
expect(rotatedNote.verified).toBe(true);
expect(instance.state.noteState(requiredValue(noteK1(rotatedNote.url)))).toBe('outstanding');
});
it('waits for durable recovery-secret staging before rotating returned funds', async () => {
const instance = await mint({meltAlwaysFails: true})
const bearer = await makeBearer(instance, secret('39'), 21_000)
let releaseStage: (() => void) | undefined
const instance = await mint({ meltAlwaysFails: true });
const bearer = await makeBearer(instance, secret('39'), 21_000);
let releaseStage: (() => void) | undefined;
const stageGate = new Promise<void>((resolve) => {
releaseStage = resolve
})
let stageStarted: (() => void) | undefined
releaseStage = resolve;
});
let stageStarted: (() => void) | undefined;
const stageEntered = new Promise<void>((resolve) => {
stageStarted = resolve
})
stageStarted = resolve;
});
const payment = payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
allocateOutputSecrets,
onReturnReady: async () => {
stageStarted?.()
await stageGate
stageStarted?.();
await stageGate;
},
})
});
await stageEntered
expect(instance.state.noteState(secret('39'))).toBe('outstanding')
releaseStage?.()
expect((await payment).outcome).toBe('failed-funds-returned')
expect(instance.state.noteState(secret('39'))).toBe('burned')
})
await stageEntered;
expect(instance.state.noteState(secret('39'))).toBe('outstanding');
releaseStage?.();
expect((await payment).outcome).toBe('failed-funds-returned');
expect(instance.state.noteState(secret('39'))).toBe('burned');
});
it('classifies a never-settling melt as unknown-still-pending', async () => {
const instance = await mint({meltNeverSettles: true})
const bearer = await makeBearer(instance, secret('34'), 21_000)
const instance = await mint({ meltNeverSettles: true });
const bearer = await makeBearer(instance, secret('34'), 21_000);
const result = await payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
allocateOutputSecrets,
onReturnReady: () => undefined,
})
expect(result.outcome).toBe('unknown-still-pending')
expect(instance.state.noteState(secret('34'))).toBe('pending')
})
});
expect(result.outcome).toBe('unknown-still-pending');
expect(instance.state.noteState(secret('34'))).toBe('pending');
});
it('rejects an amountless or unreadable invoice instead of guessing', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('35'), 21_000)
await expect(payWithBearers([bearer], 'lnbc1pjqrstuvwxyz')).rejects.toThrow(/amount/)
await expect(payWithBearers([bearer], 'not-an-invoice')).rejects.toThrow(/not a valid/i)
})
const instance = await mint();
const bearer = await makeBearer(instance, secret('35'), 21_000);
await expect(payWithBearers([bearer], 'lnbc1pjqrstuvwxyz')).rejects.toThrow(/amount/);
await expect(payWithBearers([bearer], 'not-an-invoice')).rejects.toThrow(/not a valid/i);
});
it('aborts before the melt when the carve commit hook fails', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('36'), 21_000)
const instance = await mint();
const bearer = await makeBearer(instance, secret('36'), 21_000);
// paying 10_500 off a 21_000 note forces a split, which must commit
// through the hook before the melt may start
await expect(
payWithBearers([bearer], 'lnbc105n1pjqrstuvwxyz', {
allocateOutputSecrets,
onCarve: () => {
throw new Error('commit failed')
throw new Error('commit failed');
},
}),
).rejects.toThrow(/commit failed/)
).rejects.toThrow(/commit failed/);
// The checkpoint failed before either split or melt reached the mint.
expect(instance.state.noteState(secret('36'))).toBe('outstanding')
expect([...instance.state.notes.values()].every((note) => note.state !== 'pending')).toBe(true)
})
expect(instance.state.noteState(secret('36'))).toBe('outstanding');
expect([...instance.state.notes.values()].every((note) => note.state !== 'pending')).toBe(true);
});
it('draws the return recovery secret from the caller allocation path', async () => {
const instance = await mint({meltAlwaysFails: true})
const bearer = await makeBearer(instance, secret('8a'), 21_000)
const allocations: Array<{server: string; count: number}> = []
const allocated = [secret('8b')]
const stagedSecrets: string[] = []
const instance = await mint({ meltAlwaysFails: true });
const bearer = await makeBearer(instance, secret('8a'), 21_000);
const allocations: Array<{ server: string; count: number }> = [];
const allocated = [secret('8b')];
const stagedSecrets: string[] = [];
const result = await payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
allocateOutputSecrets: (server, count) => {
allocations.push({server, count})
return Promise.resolve(allocated.slice(0, count))
allocations.push({ server, count });
return Promise.resolve(allocated.slice(0, count));
},
onReturnReady: (_carve, recoverySecret) => {
stagedSecrets.push(recoverySecret)
stagedSecrets.push(recoverySecret);
},
})
});
expect(result.outcome).toBe('failed-funds-returned')
expect(allocations).toEqual([{server: `127.0.0.1:${instance.port}`, count: 1}])
expect(stagedSecrets).toEqual(allocated)
expect(noteK1(requiredValue(result.rotatedNote).url)).toBe(allocated[0])
})
expect(result.outcome).toBe('failed-funds-returned');
expect(allocations).toEqual([{ server: `127.0.0.1:${instance.port}`, count: 1 }]);
expect(stagedSecrets).toEqual(allocated);
expect(noteK1(requiredValue(result.rotatedNote).url)).toBe(allocated[0]);
});
it('allocates nothing while the melt settles cleanly', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('8c'), 21_000)
let allocations = 0
const instance = await mint();
const bearer = await makeBearer(instance, secret('8c'), 21_000);
let allocations = 0;
const result = await payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000},
poll: { intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000 },
allocateOutputSecrets: () => {
allocations += 1
return Promise.resolve([])
allocations += 1;
return Promise.resolve([]);
},
})
});
expect(result.outcome).toBe('settled')
expect(allocations).toBe(0)
})
expect(result.outcome).toBe('settled');
expect(allocations).toBe(0);
});
it('refuses the return classification without its durable checkpoint', async () => {
const instance = await mint({meltAlwaysFails: true})
const bearer = await makeBearer(instance, secret('8d'), 21_000)
const instance = await mint({ meltAlwaysFails: true });
const bearer = await makeBearer(instance, secret('8d'), 21_000);
await expect(
payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
allocateOutputSecrets,
}),
).rejects.toBeInstanceOf(PayReturnCheckpointRequiredError)
).rejects.toBeInstanceOf(PayReturnCheckpointRequiredError);
// the payment failed and the mint restored the note; the refusal came
// before the classification rotate, so nothing else moved
expect(instance.state.noteState(secret('8d'))).toBe('outstanding')
})
expect(instance.state.noteState(secret('8d'))).toBe('outstanding');
});
it('refuses the return classification without an allocation path', async () => {
const instance = await mint({meltAlwaysFails: true})
const bearer = await makeBearer(instance, secret('8e'), 21_000)
const instance = await mint({ meltAlwaysFails: true });
const bearer = await makeBearer(instance, secret('8e'), 21_000);
await expect(
payWithBearers([bearer], 'lnbc210n1pjqrstuvwxyz', {
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
onReturnReady: () => undefined,
}),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError)
expect(instance.state.noteState(secret('8e'))).toBe('outstanding')
})
})
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError);
expect(instance.state.noteState(secret('8e'))).toBe('outstanding');
});
});
src/lnurlcash/ops.retry-refusal.cases.ts
+52 -52
View File
@@ -1,9 +1,9 @@
import {describe, expect, it} from 'vitest'
import {noteK1} from 'lnurlcash-kit'
import { describe, expect, it } from 'vitest';
import { noteK1 } from 'lnurlcash-kit';
import type {CarveResult} from './ops'
import {ensureExactAmount, receiveBearer} from './ops'
import {requiredValue} from './test-utils'
import type { CarveResult } from './ops';
import { ensureExactAmount, receiveBearer } from './ops';
import { requiredValue } from './test-utils';
import {
allocateOutputSecrets,
makeBearer,
@@ -12,7 +12,7 @@ import {
retryingCbFetch,
secret,
stageRotation,
} from './ops.testHarness'
} from './ops.testHarness';
// The redeem callback is a GET, and HTTP stacks retry GETs - so a mint
// can execute the first attempt of a mutation and refuse the byte-identical
@@ -22,76 +22,76 @@ import {
// carried secrets are the only money left.
describe('mutation retry refusals', () => {
it('rescues the outputs when the split answer is a retry refusal', async () => {
const instance = await mint()
const k1 = secret('60')
const bearer = await makeBearer(instance, k1, 50_000)
const instance = await mint();
const k1 = secret('60');
const bearer = await makeBearer(instance, k1, 50_000);
const result = await ensureExactAmount([bearer], 25_000, {
fetch: retryingCbFetch(),
allocateOutputSecrets,
onCarve: () => undefined,
})
});
// the split landed on the first (unseen) attempt: the input is burned
// and both outputs are live under the secrets the wallet carried
expect(instance.state.noteState(k1)).toBe('burned')
expect(result.consumed).toHaveLength(1)
const partK1 = requiredValue(noteK1(result.note.url))
expect(partK1).not.toBe(k1)
expect(result.note.amount).toBe(25_000)
expect(instance.state.noteState(partK1)).toBe('outstanding')
const changeK1 = requiredValue(noteK1(requiredValue(result.change).url))
expect(instance.state.noteState(changeK1)).toBe('outstanding')
})
expect(instance.state.noteState(k1)).toBe('burned');
expect(result.consumed).toHaveLength(1);
const partK1 = requiredValue(noteK1(result.note.url));
expect(partK1).not.toBe(k1);
expect(result.note.amount).toBe(25_000);
expect(instance.state.noteState(partK1)).toBe('outstanding');
const changeK1 = requiredValue(noteK1(requiredValue(result.change).url));
expect(instance.state.noteState(changeK1)).toBe('outstanding');
});
it('rescues the combined note when the merge answer is a retry refusal', async () => {
const instance = await mint()
const a = await makeBearer(instance, secret('61'), 20_000)
const b = await makeBearer(instance, secret('62'), 5_000)
const instance = await mint();
const a = await makeBearer(instance, secret('61'), 20_000);
const b = await makeBearer(instance, secret('62'), 5_000);
const result = await ensureExactAmount([a, b], 25_000, {
fetch: retryingCbFetch(),
allocateOutputSecrets,
onCarve: () => undefined,
})
expect(result.consumed).toHaveLength(2)
expect(instance.state.noteState(secret('61'))).toBe('burned')
expect(instance.state.noteState(secret('62'))).toBe('burned')
const mergedK1 = requiredValue(noteK1(result.note.url))
expect(result.note.amount).toBe(25_000)
expect(instance.state.noteState(mergedK1)).toBe('outstanding')
})
});
expect(result.consumed).toHaveLength(2);
expect(instance.state.noteState(secret('61'))).toBe('burned');
expect(instance.state.noteState(secret('62'))).toBe('burned');
const mergedK1 = requiredValue(noteK1(result.note.url));
expect(result.note.amount).toBe(25_000);
expect(instance.state.noteState(mergedK1)).toBe('outstanding');
});
it('adopts the fresh secret when the receive rotate answer is a retry refusal', async () => {
const instance = await mint()
const senderK1 = secret('63')
instance.state.creditNote(senderK1, 21_000)
const instance = await mint();
const senderK1 = secret('63');
instance.state.creditNote(senderK1, 21_000);
const received = await receiveBearer(noteUrl(instance, senderK1, 21_000), [], {
fetch: retryingCbFetch(),
allocateOutputSecrets,
stageRotation,
})
expect(received.rotated).toBe(true)
expect(received.note.amount).toBe(21_000)
expect(instance.state.noteState(senderK1)).toBe('burned')
const k1 = requiredValue(noteK1(received.note.url))
expect(k1).not.toBe(senderK1)
expect(instance.state.noteState(k1)).toBe('outstanding')
})
});
expect(received.rotated).toBe(true);
expect(received.note.amount).toBe(21_000);
expect(instance.state.noteState(senderK1)).toBe('burned');
const k1 = requiredValue(noteK1(received.note.url));
expect(k1).not.toBe(senderK1);
expect(instance.state.noteState(k1)).toBe('outstanding');
});
it('still fails a genuine refusal - a note spent before the split', async () => {
const instance = await mint()
const k1 = secret('64')
const bearer = await makeBearer(instance, k1, 50_000)
instance.state.settleMelt(k1) // burned elsewhere, before we ever asked
const checkpoints: CarveResult[] = []
const instance = await mint();
const k1 = secret('64');
const bearer = await makeBearer(instance, k1, 50_000);
instance.state.settleMelt(k1); // burned elsewhere, before we ever asked
const checkpoints: CarveResult[] = [];
await expect(
ensureExactAmount([bearer], 25_000, {
fetch: retryingCbFetch(),
allocateOutputSecrets,
onCarve: (carve) => {
checkpoints.push(carve)
checkpoints.push(carve);
},
}),
).rejects.toThrow(/spent/i)
expect(checkpoints).toHaveLength(1)
expect(checkpoints[0]?.consumed).toEqual([])
})
})
).rejects.toThrow(/spent/i);
expect(checkpoints).toHaveLength(1);
expect(checkpoints[0]?.consumed).toEqual([]);
});
});
src/lnurlcash/ops.signature.cases.ts
+67 -71
View File
@@ -1,8 +1,8 @@
import {describe, expect, it} from 'vitest'
import {noteK1, noteSignature} from 'lnurlcash-kit'
import { describe, expect, it } from 'vitest';
import { noteK1, noteSignature } from 'lnurlcash-kit';
import {ensureExactAmount} from './ops'
import {requiredValue} from './test-utils'
import { ensureExactAmount } from './ops';
import { requiredValue } from './test-utils';
import {
allocateOutputSecrets,
makeBearer,
@@ -10,8 +10,8 @@ import {
noteUrl,
secret,
signatureKeysFor,
} from './ops.testHarness'
import {fetchNoteInfo} from 'lnurlcash-kit'
} from './ops.testHarness';
import { fetchNoteInfo } from 'lnurlcash-kit';
// Landed split/merge outputs carry the mint's signature in their URL (sig
// param), and earn verified:true only when that signature checks against a
@@ -21,38 +21,38 @@ import {fetchNoteInfo} from 'lnurlcash-kit'
// exist at the mint), only the offline-verifiable badge is withheld.
describe('landed mutation signature verification', () => {
it('verifies a landed split against the current key and preserves its signature', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('a0'), 21_000)
const instance = await mint();
const bearer = await makeBearer(instance, secret('a0'), 21_000);
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets,
mintSignatureKeys: signatureKeysFor(instance),
})
});
expect(result.note.verified).toBe(true)
const signature = noteSignature(result.note.url)
expect(signature).not.toBeNull()
expect(noteSignature(requiredValue(result.change).url)).not.toBeNull()
expect(result.note.verified).toBe(true);
const signature = noteSignature(result.note.url);
expect(signature).not.toBeNull();
expect(noteSignature(requiredValue(result.change).url)).not.toBeNull();
// change stays unverified (its true post-fee value is unknown until a
// refresh) even though its signature is preserved
expect(result.change?.verified).toBe(false)
})
expect(result.change?.verified).toBe(false);
});
it('verifies a landed merge against the current key and preserves its signature', async () => {
const instance = await mint()
const first = await makeBearer(instance, secret('a1'), 3_000)
const second = await makeBearer(instance, secret('a2'), 4_000)
const instance = await mint();
const first = await makeBearer(instance, secret('a1'), 3_000);
const second = await makeBearer(instance, secret('a2'), 4_000);
const result = await ensureExactAmount([first, second], 7_000, {
onCarve: () => undefined,
allocateOutputSecrets,
mintSignatureKeys: signatureKeysFor(instance),
})
});
expect(result.note.verified).toBe(true)
expect(noteSignature(result.note.url)).not.toBeNull()
})
expect(result.note.verified).toBe(true);
expect(noteSignature(result.note.url)).not.toBeNull();
});
it('verifies against the previous key after the mint rotated its signing key', async () => {
// the mint signs every output under its RETIRED key while advertising
@@ -60,26 +60,26 @@ describe('landed mutation signature verification', () => {
const instance = await mint({
previousPrivateKey: '22'.repeat(32),
signWithPreviousKey: true,
})
const bearer = await makeBearer(instance, secret('a3'), 21_000)
});
const bearer = await makeBearer(instance, secret('a3'), 21_000);
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets,
mintSignatureKeys: signatureKeysFor(instance),
})
});
expect(instance.state.previousPubkeys).toHaveLength(1)
expect(result.note.verified).toBe(true)
expect(noteSignature(result.note.url)).not.toBeNull()
})
expect(instance.state.previousPubkeys).toHaveLength(1);
expect(result.note.verified).toBe(true);
expect(noteSignature(result.note.url)).not.toBeNull();
});
it('rejects verification when the previous key is not trusted', async () => {
const instance = await mint({
previousPrivateKey: '22'.repeat(32),
signWithPreviousKey: true,
})
const bearer = await makeBearer(instance, secret('a4'), 21_000)
});
const bearer = await makeBearer(instance, secret('a4'), 21_000);
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
@@ -87,73 +87,69 @@ describe('landed mutation signature verification', () => {
// only the current key is trusted - the signature under the retired
// key must not verify
mintSignatureKeys: () => [instance.state.pubkey],
})
});
expect(result.note.verified).toBe(false)
expect(result.note.verified).toBe(false);
// the note and its signature are still tracked, recoverable by refresh
expect(noteSignature(result.note.url)).not.toBeNull()
const partK1 = requiredValue(noteK1(result.note.url))
expect(instance.state.noteState(partK1)).toBe('outstanding')
expect(instance.state.noteState(secret('a4'))).toBe('burned')
})
expect(noteSignature(result.note.url)).not.toBeNull();
const partK1 = requiredValue(noteK1(result.note.url));
expect(instance.state.noteState(partK1)).toBe('outstanding');
expect(instance.state.noteState(secret('a4'))).toBe('burned');
});
it('keeps a wrong-key signature staged unverified', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('a5'), 21_000)
const stranger = await mint({privateKey: '33'.repeat(32)})
const instance = await mint();
const bearer = await makeBearer(instance, secret('a5'), 21_000);
const stranger = await mint({ privateKey: '33'.repeat(32) });
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets,
// the only trusted key on file belongs to a DIFFERENT mint
mintSignatureKeys: () => [stranger.state.pubkey],
})
});
expect(result.note.verified).toBe(false)
expect(noteSignature(result.note.url)).not.toBeNull()
expect(instance.state.noteState(secret('a5'))).toBe('burned')
expect(
instance.state.noteState(requiredValue(noteK1(result.note.url))),
).toBe('outstanding')
})
expect(result.note.verified).toBe(false);
expect(noteSignature(result.note.url)).not.toBeNull();
expect(instance.state.noteState(secret('a5'))).toBe('burned');
expect(instance.state.noteState(requiredValue(noteK1(result.note.url)))).toBe('outstanding');
});
it('keeps a landed split unsigned by the mint staged unverified and consumed', async () => {
const instance = await mint({signatures: false})
const k1 = secret('a6')
const bearer = await makeBearer(instance, k1, 21_000)
const instance = await mint({ signatures: false });
const k1 = secret('a6');
const bearer = await makeBearer(instance, k1, 21_000);
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets,
mintSignatureKeys: signatureKeysFor(instance),
})
});
// the mutation landed (the kit refused the missing signature, the
// rescue probe proved the burn): the inputs are retired, the staged
// outputs are tracked at exactly their staged secrets, unverified
expect(result.consumed.map((entry) => entry.id)).toEqual([bearer.id])
expect(result.note.verified).toBe(false)
expect(noteSignature(result.note.url)).toBeNull()
expect(instance.state.noteState(k1)).toBe('burned')
const partK1 = requiredValue(noteK1(result.note.url))
expect(instance.state.noteState(partK1)).toBe('outstanding')
expect((await fetchNoteInfo(noteUrl(instance, partK1))).maxWithdrawable).toBe(5_000)
})
expect(result.consumed.map((entry) => entry.id)).toEqual([bearer.id]);
expect(result.note.verified).toBe(false);
expect(noteSignature(result.note.url)).toBeNull();
expect(instance.state.noteState(k1)).toBe('burned');
const partK1 = requiredValue(noteK1(result.note.url));
expect(instance.state.noteState(partK1)).toBe('outstanding');
expect((await fetchNoteInfo(noteUrl(instance, partK1))).maxWithdrawable).toBe(5_000);
});
it('never verifies a landed mutation without any trusted keys on file', async () => {
const instance = await mint()
const bearer = await makeBearer(instance, secret('a7'), 21_000)
const instance = await mint();
const bearer = await makeBearer(instance, secret('a7'), 21_000);
const result = await ensureExactAmount([bearer], 5_000, {
onCarve: () => undefined,
allocateOutputSecrets,
// no key source at all: nothing may be trusted blindly
})
});
expect(result.note.verified).toBe(false)
expect(noteSignature(result.note.url)).not.toBeNull()
expect(
instance.state.noteState(requiredValue(noteK1(result.note.url))),
).toBe('outstanding')
})
})
expect(result.note.verified).toBe(false);
expect(noteSignature(result.note.url)).not.toBeNull();
expect(instance.state.noteState(requiredValue(noteK1(result.note.url)))).toBe('outstanding');
});
});
src/lnurlcash/ops.test.ts
+8 -8
View File
@@ -1,8 +1,8 @@
import './ops.carve.cases'
import './ops.carve-crash.cases'
import './ops.signature.cases'
import './ops.mint-named.cases'
import './ops.mint-receive.cases'
import './ops.pay.cases'
import './ops.retry-refusal.cases'
import './ops.transfer.cases'
import './ops.carve.cases';
import './ops.carve-crash.cases';
import './ops.signature.cases';
import './ops.mint-named.cases';
import './ops.mint-receive.cases';
import './ops.pay.cases';
import './ops.retry-refusal.cases';
import './ops.transfer.cases';
src/lnurlcash/ops.testHarness.ts
+56 -56
View File
@@ -1,69 +1,69 @@
import {afterEach, expect} from 'vitest'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
import {sha256} from '@noble/hashes/sha2.js'
import {buildNoteUrl, fetchNoteInfo} from 'lnurlcash-kit'
import { afterEach, expect } from 'vitest';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { buildNoteUrl, fetchNoteInfo } from 'lnurlcash-kit';
import type {Bearer} from './types'
import {requiredValue} from './test-utils'
import type { Bearer } from './types';
import { requiredValue } from './test-utils';
export type Mint = Awaited<ReturnType<typeof createMockMint>>
export type Mint = Awaited<ReturnType<typeof createMockMint>>;
const mints: Mint[] = []
const mints: Mint[] = [];
export const mint = async (options: Parameters<typeof createMockMint>[0] = {}): Promise<Mint> => {
const instance = await createMockMint(options)
mints.push(instance)
return instance
}
const instance = await createMockMint(options);
mints.push(instance);
return instance;
};
afterEach(async () => {
await Promise.all(mints.splice(0).map((instance) => instance.close()))
})
await Promise.all(mints.splice(0).map((instance) => instance.close()));
});
export const secret = (seed: string): string =>
bytesToHex(sha256(hexToBytes('00'.repeat(31) + seed)))
bytesToHex(sha256(hexToBytes('00'.repeat(31) + seed)));
export const persistOutput = async (): Promise<void> => undefined
export const persistOutput = async (): Promise<void> => undefined;
// deterministic stand-in for the wallet's BIP-32 allocation path: answers
// every reservation with fresh unique secrets, never reusing one
let allocatedSecretCounter = 0
let allocatedSecretCounter = 0;
export const allocateOutputSecrets = (
_server: string,
count: number,
): Promise<readonly string[]> => {
const secrets = Array.from({length: count}, () => {
allocatedSecretCounter += 1
return bytesToHex(sha256(utf8ToBytes(`allocated-${allocatedSecretCounter}`)))
})
return Promise.resolve(secrets)
}
const secrets = Array.from({ length: count }, () => {
allocatedSecretCounter += 1;
return bytesToHex(sha256(utf8ToBytes(`allocated-${allocatedSecretCounter}`)));
});
return Promise.resolve(secrets);
};
// the receive-rotation staging checkpoint - engine tests keep no wallet,
// so staging is a recorded no-op for them
export const stageRotation = async (): Promise<void> => undefined
export const stageRotation = async (): Promise<void> => undefined;
// the trusted signing keys a production caller would serve from the
// trusted-mint registry: the mock mint's current key plus any it retired
export const signatureKeysFor =
(instance: Mint) =>
(): readonly string[] =>
[instance.state.pubkey, ...instance.state.previousPubkeys]
export const signatureKeysFor = (instance: Mint) => (): readonly string[] => [
instance.state.pubkey,
...instance.state.previousPubkeys,
];
export const noteUrl = (instance: Mint, k1: string, amountMsat?: number): string =>
buildNoteUrl(`${instance.url}/w`, k1, amountMsat)
buildNoteUrl(`${instance.url}/w`, k1, amountMsat);
let fixtureCounter = 0
let fixtureCounter = 0;
export const makeBearer = async (
instance: Mint,
k1: string,
amountMsat: number,
): Promise<Bearer> => {
instance.state.creditNote(k1, amountMsat)
const url = noteUrl(instance, k1, amountMsat)
const info = await fetchNoteInfo(url)
fixtureCounter += 1
instance.state.creditNote(k1, amountMsat);
const url = noteUrl(instance, k1, amountMsat);
const info = await fetchNoteInfo(url);
fixtureCounter += 1;
return {
id: `fixture-${fixtureCounter}`,
url,
@@ -73,29 +73,29 @@ export const makeBearer = async (
mintPubkey: instance.state.pubkey,
createdAt: Date.now(),
updatedAt: Date.now(),
}
}
};
};
export const settleLastInvoice = async (instance: Mint): Promise<string> => {
const paymentHash = requiredValue([...instance.state.invoices.keys()].at(-1))
const response = await fetch(`${instance.url}/_test/settle?payment_hash=${paymentHash}`)
if (!response.ok) throw new Error(`settle hook failed: ${response.status}`)
return requiredValue(instance.state.invoices.get(paymentHash)).preimage
}
const paymentHash = requiredValue([...instance.state.invoices.keys()].at(-1));
const response = await fetch(`${instance.url}/_test/settle?payment_hash=${paymentHash}`);
if (!response.ok) throw new Error(`settle hook failed: ${response.status}`);
return requiredValue(instance.state.invoices.get(paymentHash)).preimage;
};
export const settleWhenRequested = async (instance: Mint): Promise<string> => {
for (let attempt = 0; attempt < 200 && instance.state.invoices.size === 0; attempt++) {
await new Promise((resolve) => setTimeout(resolve, 10))
await new Promise((resolve) => setTimeout(resolve, 10));
}
return settleLastInvoice(instance)
}
return settleLastInvoice(instance);
};
export const expectBurned = async (instance: Mint, k1: string): Promise<void> => {
for (let attempt = 0; attempt < 200 && instance.state.noteState(k1) !== 'burned'; attempt++) {
await new Promise((resolve) => setTimeout(resolve, 10))
await new Promise((resolve) => setTimeout(resolve, 10));
}
expect(instance.state.noteState(k1)).toBe('burned')
}
expect(instance.state.noteState(k1)).toBe('burned');
};
// a fetch wrapper that answers every /w/cb request with the response to
// its SECOND, byte-identical send - the HTTP-stack GET retry a real client
@@ -105,13 +105,13 @@ export const expectBurned = async (instance: Mint, k1: string): Promise<void> =>
// ever sees
export const retryingCbFetch = (): typeof fetch => {
const impl: typeof fetch = async (input, init) => {
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url
const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
if (url.includes('/w/cb')) {
const first = await fetch(input, init)
await first.arrayBuffer()
return fetch(input, init)
const first = await fetch(input, init);
await first.arrayBuffer();
return fetch(input, init);
}
return fetch(input, init)
}
return impl
}
return fetch(input, init);
};
return impl;
};
src/lnurlcash/ops.transfer.cases.ts
+199 -206
View File
@@ -1,15 +1,12 @@
import {describe, expect, it} from 'vitest'
import {createMockMint} from 'lnurlcash-conformance/mock-mint'
import {hashK1, noteK1} from 'lnurlcash-kit'
import { describe, expect, it } from 'vitest';
import { createMockMint } from 'lnurlcash-conformance/mock-mint';
import { hashK1, noteK1 } from 'lnurlcash-kit';
import {transferBetweenMints as transferBetweenMintsEngine} from './ops'
import {
OutputSecretAllocationRequiredError,
TransferMeltCheckpointRequiredError,
} from './ops'
import type {CarveResult, TransferOptions} from './ops'
import type {Bearer} from './types'
import {requiredValue} from './test-utils'
import { transferBetweenMints as transferBetweenMintsEngine } from './ops';
import { OutputSecretAllocationRequiredError, TransferMeltCheckpointRequiredError } from './ops';
import type { CarveResult, TransferOptions } from './ops';
import type { Bearer } from './types';
import { requiredValue } from './test-utils';
import {
allocateOutputSecrets,
expectBurned,
@@ -18,7 +15,7 @@ import {
persistOutput,
secret,
settleWhenRequested,
} from './ops.testHarness'
} from './ops.testHarness';
const transferBetweenMints = (
bearers: Bearer[],
@@ -31,313 +28,309 @@ const transferBetweenMints = (
onMeltReady: () => undefined,
...options,
persistOutput,
})
});
describe('transferBetweenMints', () => {
const fastPoll = {intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000}
const fastPoll = { intervalMs: 10, intervalCapMs: 50, maxWaitMs: 5_000 };
it('draws the target and source secrets from the caller allocation path', async () => {
const source = await mint()
const target = await mint({testHooks: true})
const bearer = await makeBearer(source, secret('91'), 21_000)
const targetSecret = secret('92')
const sourceRecoverySecret = secret('93')
const allocations: Array<{server: string; count: number}> = []
const meltReadiness: string[] = []
const source = await mint();
const target = await mint({ testHooks: true });
const bearer = await makeBearer(source, secret('91'), 21_000);
const targetSecret = secret('92');
const sourceRecoverySecret = secret('93');
const allocations: Array<{ server: string; count: number }> = [];
const meltReadiness: string[] = [];
const pending = transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
poll: fastPoll,
allocateOutputSecrets: (server, count) => {
allocations.push({server, count})
const secrets = allocations.length === 1 ? [targetSecret] : [sourceRecoverySecret]
return Promise.resolve(secrets.slice(0, count))
allocations.push({ server, count });
const secrets = allocations.length === 1 ? [targetSecret] : [sourceRecoverySecret];
return Promise.resolve(secrets.slice(0, count));
},
onMeltReady: (_carve, recovery) => {
meltReadiness.push(recovery)
meltReadiness.push(recovery);
},
})
await settleWhenRequested(target)
const result = await pending
});
await settleWhenRequested(target);
const result = await pending;
expect(result.outcome).toBe('settled')
expect(result.outcome).toBe('settled');
// the staged target note first, then the source recovery secret - an
// exact source carve allocates nothing
expect(allocations).toEqual([
{server: `127.0.0.1:${target.port}`, count: 1},
{server: `127.0.0.1:${source.port}`, count: 1},
])
expect(meltReadiness).toEqual([sourceRecoverySecret])
expect(noteK1(requiredValue(result.mintedAtTarget).note.url)).toBe(targetSecret)
})
{ server: `127.0.0.1:${target.port}`, count: 1 },
{ server: `127.0.0.1:${source.port}`, count: 1 },
]);
expect(meltReadiness).toEqual([sourceRecoverySecret]);
expect(noteK1(requiredValue(result.mintedAtTarget).note.url)).toBe(targetSecret);
});
it('refuses the source melt without its durable checkpoint', async () => {
const source = await mint()
const target = await mint({testHooks: true})
const bearer = await makeBearer(source, secret('98'), 21_000)
const source = await mint();
const target = await mint({ testHooks: true });
const bearer = await makeBearer(source, secret('98'), 21_000);
await expect(
transferBetweenMintsEngine([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
allocateOutputSecrets,
persistOutput,
}),
).rejects.toBeInstanceOf(TransferMeltCheckpointRequiredError)
).rejects.toBeInstanceOf(TransferMeltCheckpointRequiredError);
// the target stage happened (invoice exists) but the source note is
// untouched and nothing melted
expect(source.state.noteState(secret('98'))).toBe('outstanding')
})
expect(source.state.noteState(secret('98'))).toBe('outstanding');
});
it('refuses at target staging without an allocation path', async () => {
const source = await mint()
const target = await mint({testHooks: true})
const bearer = await makeBearer(source, secret('99'), 21_000)
const source = await mint();
const target = await mint({ testHooks: true });
const bearer = await makeBearer(source, secret('99'), 21_000);
await expect(
transferBetweenMintsEngine([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
onMeltReady: () => undefined,
persistOutput,
}),
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError)
expect(source.state.noteState(secret('99'))).toBe('outstanding')
})
).rejects.toBeInstanceOf(OutputSecretAllocationRequiredError);
expect(source.state.noteState(secret('99'))).toBe('outstanding');
});
it('moves value to another mint at a wallet-chosen target secret', async () => {
const source = await mint()
const target = await mint({testHooks: true})
const k1 = secret('40')
const bearer = await makeBearer(source, k1, 21_000)
const source = await mint();
const target = await mint({ testHooks: true });
const k1 = secret('40');
const bearer = await makeBearer(source, k1, 21_000);
const pending = transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
poll: fastPoll,
})
const preimage = await settleWhenRequested(target)
const result = await pending
expect(result.outcome).toBe('settled')
expect(result.invoice).toMatch(/^lnbc/)
});
const preimage = await settleWhenRequested(target);
const result = await pending;
expect(result.outcome).toBe('settled');
expect(result.invoice).toMatch(/^lnbc/);
expect(result.quote).toEqual({
requestedMsat: 21_000,
grossMsat: 21_000,
targetMintFeeMsat: 0,
sourceMeltFeeReserveMsat: 0,
})
expect(result.sourceServer).not.toBe(result.targetServer)
await expectBurned(source, k1)
const claimed = requiredValue(result.mintedAtTarget)
expect(claimed.note.amount).toBe(21_000)
expect(claimed.note.verified).toBe(true)
expect(target.state.noteState(preimage)).toBeNull()
const newK1 = requiredValue(noteK1(claimed.note.url))
expect(newK1).not.toBe(preimage)
expect(target.state.noteState(newK1)).toBe('outstanding')
})
});
expect(result.sourceServer).not.toBe(result.targetServer);
await expectBurned(source, k1);
const claimed = requiredValue(result.mintedAtTarget);
expect(claimed.note.amount).toBe(21_000);
expect(claimed.note.verified).toBe(true);
expect(target.state.noteState(preimage)).toBeNull();
const newK1 = requiredValue(noteK1(claimed.note.url));
expect(newK1).not.toBe(preimage);
expect(target.state.noteState(newK1)).toBe('outstanding');
});
it('refuses an amount no source mint can cover', async () => {
const source = await mint()
const target = await mint()
const k1 = secret('41')
const bearer = await makeBearer(source, k1, 5_000)
let persisted = false
const source = await mint();
const target = await mint();
const k1 = secret('41');
const bearer = await makeBearer(source, k1, 5_000);
let persisted = false;
await expect(
transferBetweenMintsEngine([bearer], 50_000, `mint@127.0.0.1:${target.port}`, {
persistOutput: () => {
persisted = true
persisted = true;
},
}),
).rejects.toThrow(/enough/)
expect(persisted).toBe(false)
expect(source.state.noteState(k1)).toBe('outstanding')
})
).rejects.toThrow(/enough/);
expect(persisted).toBe(false);
expect(source.state.noteState(k1)).toBe('outstanding');
});
it('rejects a transfer onto the mint the notes are already on', async () => {
const instance = await mint()
const k1 = secret('42')
const bearer = await makeBearer(instance, k1, 21_000)
const instance = await mint();
const k1 = secret('42');
const bearer = await makeBearer(instance, k1, 21_000);
await expect(
transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${instance.port}`),
).rejects.toThrow(/different target/)
expect(instance.state.noteState(k1)).toBe('outstanding')
})
).rejects.toThrow(/different target/);
expect(instance.state.noteState(k1)).toBe('outstanding');
});
it('moves nothing when the target mint is unreachable', async () => {
const source = await mint()
const dead = await createMockMint()
const deadAddress = `mint@127.0.0.1:${dead.port}`
await dead.close()
const k1 = secret('43')
const bearer = await makeBearer(source, k1, 50_000)
await expect(transferBetweenMints([bearer], 21_000, deadAddress)).rejects.toThrow()
expect(source.state.noteState(k1)).toBe('outstanding')
})
const source = await mint();
const dead = await createMockMint();
const deadAddress = `mint@127.0.0.1:${dead.port}`;
await dead.close();
const k1 = secret('43');
const bearer = await makeBearer(source, k1, 50_000);
await expect(transferBetweenMints([bearer], 21_000, deadAddress)).rejects.toThrow();
expect(source.state.noteState(k1)).toBe('outstanding');
});
it('reports a definitively spent source before waiting on the target', async () => {
const source = await mint()
const target = await mint()
const k1 = secret('54')
const bearer = await makeBearer(source, k1, 21_000)
source.state.settleMelt(k1)
const source = await mint();
const target = await mint();
const k1 = secret('54');
const bearer = await makeBearer(source, k1, 21_000);
source.state.settleMelt(k1);
const result = await transferBetweenMints(
[bearer],
21_000,
`mint@127.0.0.1:${target.port}`,
)
const result = await transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${target.port}`);
expect(result.outcome).toBe('note-already-spent')
})
expect(result.outcome).toBe('note-already-spent');
});
it('recovers from a melt whose answer was lost once the target invoice settles', async () => {
const source = await mint({unconfirmedMutation: true})
const target = await mint({testHooks: true})
const k1 = secret('44')
const bearer = await makeBearer(source, k1, 21_000)
const source = await mint({ unconfirmedMutation: true });
const target = await mint({ testHooks: true });
const k1 = secret('44');
const bearer = await makeBearer(source, k1, 21_000);
const pending = transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
poll: fastPoll,
})
await settleWhenRequested(target)
const result = await pending
expect(result.outcome).toBe('settled')
await expectBurned(source, k1)
expect(result.mintedAtTarget?.note.amount).toBe(21_000)
})
});
await settleWhenRequested(target);
const result = await pending;
expect(result.outcome).toBe('settled');
await expectBurned(source, k1);
expect(result.mintedAtTarget?.note.amount).toBe(21_000);
});
it('grosses the carve up for the target mint fee, refusing when only the net is covered', async () => {
const source = await mint()
const target = await mint({baseFeeMsat: 1_000, feePpm: 2_000})
const k1 = secret('46')
const bearer = await makeBearer(source, k1, 100_000)
const source = await mint();
const target = await mint({ baseFeeMsat: 1_000, feePpm: 2_000 });
const k1 = secret('46');
const bearer = await makeBearer(source, k1, 100_000);
await expect(
transferBetweenMints([bearer], 100_000, `mint@127.0.0.1:${target.port}`),
).rejects.toThrow(/enough/)
expect(source.state.noteState(k1)).toBe('outstanding')
})
).rejects.toThrow(/enough/);
expect(source.state.noteState(k1)).toBe('outstanding');
});
it('restores the source note, re-secured, when the melt fails', async () => {
const source = await mint({meltAlwaysFails: true})
const target = await mint({testHooks: true})
const k1 = secret('47')
const bearer = await makeBearer(source, k1, 21_000)
const source = await mint({ meltAlwaysFails: true });
const target = await mint({ testHooks: true });
const k1 = secret('47');
const bearer = await makeBearer(source, k1, 21_000);
const result = await transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
})
expect(result.outcome).toBe('failed-funds-returned')
expect(result.mintedAtTarget).toBeUndefined()
expect(source.state.noteState(k1)).toBe('burned')
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
});
expect(result.outcome).toBe('failed-funds-returned');
expect(result.mintedAtTarget).toBeUndefined();
expect(source.state.noteState(k1)).toBe('burned');
// the returned funds come back re-secured at the source-probe rotate's
// fresh secret - carried as rotatedNote, NOT folded into the carve
// (which an onCarve checkpoint may already have committed)
const rotatedNote = requiredValue(result.rotatedNote)
expect(rotatedNote.verified).toBe(true)
const returnedK1 = requiredValue(noteK1(rotatedNote.url))
expect(returnedK1).not.toBe(k1)
expect(source.state.noteState(returnedK1)).toBe('outstanding')
expect(rotatedNote.amount).toBe(21_000)
})
const rotatedNote = requiredValue(result.rotatedNote);
expect(rotatedNote.verified).toBe(true);
const returnedK1 = requiredValue(noteK1(rotatedNote.url));
expect(returnedK1).not.toBe(k1);
expect(source.state.noteState(returnedK1)).toBe('outstanding');
expect(rotatedNote.amount).toBe(21_000);
});
it('lands the target note at the staged wallet secret without rotating', async () => {
const source = await mint()
const target = await mint({testHooks: true})
const k1 = secret('48')
const bearer = await makeBearer(source, k1, 21_000)
const source = await mint();
const target = await mint({ testHooks: true });
const k1 = secret('48');
const bearer = await makeBearer(source, k1, 21_000);
const pending = transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
poll: fastPoll,
})
const preimage = await settleWhenRequested(target)
const result = await pending
expect(result.outcome).toBe('settled')
await expectBurned(source, k1)
const claimed = requiredValue(result.mintedAtTarget)
expect(claimed.note.amount).toBe(21_000)
expect(claimed.note.verified).toBe(true)
const newK1 = requiredValue(noteK1(claimed.note.url))
});
const preimage = await settleWhenRequested(target);
const result = await pending;
expect(result.outcome).toBe('settled');
await expectBurned(source, k1);
const claimed = requiredValue(result.mintedAtTarget);
expect(claimed.note.amount).toBe(21_000);
expect(claimed.note.verified).toBe(true);
const newK1 = requiredValue(noteK1(claimed.note.url));
// the note stands at the wallet's own secret - the quote was bound to
// its hash, and the payment preimage keys nothing at the target
expect([...target.state.invoices.values()].at(-1)?.boundTo).toBe(hashK1(newK1))
expect(target.state.noteState(newK1)).toBe('outstanding')
expect(target.state.noteState(preimage)).toBeNull()
})
expect([...target.state.invoices.values()].at(-1)?.boundTo).toBe(hashK1(newK1));
expect(target.state.noteState(newK1)).toBe('outstanding');
expect(target.state.noteState(preimage)).toBeNull();
});
it('keeps the named claim material when the target never credits the note', async () => {
const source = await mint({meltNeverSettles: true})
const target = await mint({testHooks: true})
const k1 = secret('49')
const bearer = await makeBearer(source, k1, 21_000)
const source = await mint({ meltNeverSettles: true });
const target = await mint({ testHooks: true });
const k1 = secret('49');
const bearer = await makeBearer(source, k1, 21_000);
const pending = transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
poll: {intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300},
})
poll: { intervalMs: 10, intervalCapMs: 20, maxWaitMs: 300 },
});
// the target invoice exists (the quote is bound) but the source melt
// never lands, so nothing is ever credited at the wallet's secret
while (target.state.invoices.size === 0) {
await new Promise((resolve) => setTimeout(resolve, 10))
await new Promise((resolve) => setTimeout(resolve, 10));
}
const result = await pending
expect(result.outcome).toBe('unknown-still-pending')
expect(result.mintedAtTarget).toBeUndefined()
const result = await pending;
expect(result.outcome).toBe('unknown-still-pending');
expect(result.mintedAtTarget).toBeUndefined();
// the wallet's secret is the way back to the money if the melt's
// payment arrives later - and the note at that secret is tracked
// unverified, so a late settlement is never a lost note
const noteSecret = requiredValue(result.claimMaterial?.noteSecret)
expect(noteSecret).toMatch(/^[0-9a-f]{64}$/)
const material = requiredValue(result.claimMaterial?.note)
expect(material.verified).toBe(false)
expect(noteK1(material.url)).toBe(noteSecret)
})
const noteSecret = requiredValue(result.claimMaterial?.noteSecret);
expect(noteSecret).toMatch(/^[0-9a-f]{64}$/);
const material = requiredValue(result.claimMaterial?.note);
expect(material.verified).toBe(false);
expect(noteK1(material.url)).toBe(noteSecret);
});
it('fires onCarve before the carve or melt reaches the mint', async () => {
const source = await mint()
const target = await mint({testHooks: true})
const bearer = await makeBearer(source, secret('51'), 21_000)
const seen: CarveResult[] = []
const source = await mint();
const target = await mint({ testHooks: true });
const bearer = await makeBearer(source, secret('51'), 21_000);
const seen: CarveResult[] = [];
const pending = transferBetweenMints([bearer], 10_000, `mint@127.0.0.1:${target.port}`, {
poll: fastPoll,
onCarve: (carve) => {
seen.push(carve)
seen.push(carve);
if (carve.consumed.length === 0) {
expect(source.state.noteState(requiredValue(noteK1(carve.note.url)))).toBeNull()
expect(source.state.noteState(requiredValue(noteK1(bearer.url)))).toBe('outstanding')
expect(source.state.noteState(requiredValue(noteK1(carve.note.url)))).toBeNull();
expect(source.state.noteState(requiredValue(noteK1(bearer.url)))).toBe('outstanding');
} else {
expect(source.state.noteState(requiredValue(noteK1(carve.note.url)))).toBe('outstanding')
expect(source.state.noteState(requiredValue(noteK1(bearer.url)))).toBe('burned')
expect(source.state.noteState(requiredValue(noteK1(carve.note.url)))).toBe('outstanding');
expect(source.state.noteState(requiredValue(noteK1(bearer.url)))).toBe('burned');
}
},
})
await settleWhenRequested(target)
const result = await pending
expect(result.outcome).toBe('settled')
expect(seen).toHaveLength(2)
expect(seen[0]?.consumed).toEqual([])
expect(seen[1]?.consumed.map((entry) => entry.id)).toEqual([bearer.id])
})
});
await settleWhenRequested(target);
const result = await pending;
expect(result.outcome).toBe('settled');
expect(seen).toHaveLength(2);
expect(seen[0]?.consumed).toEqual([]);
expect(seen[1]?.consumed.map((entry) => entry.id)).toEqual([bearer.id]);
});
it('aborts before the melt when the carve commit hook fails', async () => {
const source = await mint()
const target = await mint({testHooks: true})
const k1 = secret('52')
const bearer = await makeBearer(source, k1, 21_000)
const source = await mint();
const target = await mint({ testHooks: true });
const k1 = secret('52');
const bearer = await makeBearer(source, k1, 21_000);
await expect(
transferBetweenMints([bearer], 10_000, `mint@127.0.0.1:${target.port}`, {
onCarve: () => {
throw new Error('commit failed')
throw new Error('commit failed');
},
}),
).rejects.toThrow(/commit failed/)
).rejects.toThrow(/commit failed/);
// The checkpoint failed before either split or melt reached the source.
expect(source.state.noteState(k1)).toBe('outstanding')
expect([...source.state.notes.values()].every((note) => note.state !== 'pending')).toBe(true)
})
expect(source.state.noteState(k1)).toBe('outstanding');
expect([...source.state.notes.values()].every((note) => note.state !== 'pending')).toBe(true);
});
it('aborts before an exact-note melt when the final checkpoint fails', async () => {
const source = await mint()
const target = await mint()
const k1 = secret('53')
const bearer = await makeBearer(source, k1, 21_000)
const source = await mint();
const target = await mint();
const k1 = secret('53');
const bearer = await makeBearer(source, k1, 21_000);
await expect(
transferBetweenMints([bearer], 21_000, `mint@127.0.0.1:${target.port}`, {
onMeltReady: () => {
throw new Error('source link commit failed')
throw new Error('source link commit failed');
},
}),
).rejects.toThrow(/source link commit failed/)
).rejects.toThrow(/source link commit failed/);
expect(source.state.noteState(k1)).toBe('outstanding')
})
})
expect(source.state.noteState(k1)).toBe('outstanding');
});
});
src/lnurlcash/ops.ts
+14 -19
View File
@@ -25,41 +25,36 @@
// source, mint + claim at target)
// ops/shared.ts - bounded polling, UncertainOutcomeError
export {UncertainOutcomeError} from './ops/shared'
export type {FundOperationOptions, PollOptions} from './ops/shared'
export {OutputSecretAllocationRequiredError} from './ops/allocation'
export type {OutputSecretAllocator} from './ops/allocation'
export { UncertainOutcomeError } from './ops/shared';
export type { FundOperationOptions, PollOptions } from './ops/shared';
export { OutputSecretAllocationRequiredError } from './ops/allocation';
export type { OutputSecretAllocator } from './ops/allocation';
export {
CarveCheckpointRequiredError,
ensureExactAmount,
UnsupportedMultiBatchMergeError,
} from './ops/carve'
export type {CarveOptions, CarveResult} from './ops/carve'
} from './ops/carve';
export type { CarveOptions, CarveResult } from './ops/carve';
export {
MintedNoteSpentError,
prepareMint,
claimMintedNote,
recoverStagedMintOutput,
} from './ops/mint'
export type {
PreparedMint,
PrepareMintOptions,
ClaimedNote,
StagedMintRecovery,
} from './ops/mint'
export {receiveBearer, ReceiveRotationStagingRequiredError} from './ops/receiveBearer'
export type {ReceiveBearerOptions, ReceivedNote} from './ops/receiveBearer'
export {payWithBearers, PayReturnCheckpointRequiredError} from './ops/pay'
export type {PayOutcome, PayResult, PayOptions} from './ops/pay'
} from './ops/mint';
export type { PreparedMint, PrepareMintOptions, ClaimedNote, StagedMintRecovery } from './ops/mint';
export { receiveBearer, ReceiveRotationStagingRequiredError } from './ops/receiveBearer';
export type { ReceiveBearerOptions, ReceivedNote } from './ops/receiveBearer';
export { payWithBearers, PayReturnCheckpointRequiredError } from './ops/pay';
export type { PayOutcome, PayResult, PayOptions } from './ops/pay';
export {
recoverPendingTransferSource,
transferBetweenMints,
TransferMeltCheckpointRequiredError,
} from './ops/transfer'
} from './ops/transfer';
export type {
TransferClaimMaterial,
TransferOptions,
TransferOutcome,
TransferQuote,
TransferResult,
} from './ops/transfer'
} from './ops/transfer';
src/lnurlcash/ops/allocation.ts
+8 -8
View File
@@ -12,13 +12,13 @@
// point-of-use requirement. Tests inject deterministic allocators;
// production callers serve reserveCashIndices-backed secrets.
export type OutputSecretAllocator = (server: string, count: number) => Promise<readonly string[]>
export type OutputSecretAllocator = (server: string, count: number) => Promise<readonly string[]>;
export class OutputSecretAllocationRequiredError extends Error {
override readonly name = 'OutputSecretAllocationRequiredError'
override readonly name = 'OutputSecretAllocationRequiredError';
constructor() {
super('This operation requires durably allocated output secrets.')
super('This operation requires durably allocated output secrets.');
}
}
@@ -31,13 +31,13 @@ export const requireOutputSecrets = async (
server: string,
count: number,
): Promise<readonly string[]> => {
if (!allocate) throw new OutputSecretAllocationRequiredError()
const secrets = await allocate(server, count)
if (!allocate) throw new OutputSecretAllocationRequiredError();
const secrets = await allocate(server, count);
if (
secrets.length !== count ||
secrets.some((secret) => typeof secret !== 'string' || !/^[0-9a-f]{64}$/.test(secret))
) {
throw new Error('The output secret allocation did not match the request.')
throw new Error('The output secret allocation did not match the request.');
}
return secrets
}
return secrets;
};
src/lnurlcash/ops/carve.ts
+99 -100
View File
@@ -17,46 +17,46 @@ import {
serverOf,
splitNote,
withNewK1,
} from 'lnurlcash-kit'
import type {Bearer, NewBearer} from '../types'
import type {OutputSecretAllocator} from './allocation'
import {requireOutputSecrets} from './allocation'
import {mergeAmbiguitySafe} from './carveRecovery'
import type {FundOperationOptions} from './shared'
} from 'lnurlcash-kit';
import type { Bearer, NewBearer } from '../types';
import type { OutputSecretAllocator } from './allocation';
import { requireOutputSecrets } from './allocation';
import { mergeAmbiguitySafe } from './carveRecovery';
import type { FundOperationOptions } from './shared';
import {
assertFundOwner,
landedNoteVerifies,
probeMutationOutput,
UncertainOutcomeError,
withMutationSafety,
} from './shared'
} from './shared';
// The same shape serves both checkpoint phases: the pre-wire phase carries
// note/change with an empty consumed list, and the landed phase carries the
// already-staged note plus the inputs the caller can now retire.
export type CarveResult = {
// the exact-amount note, ready to hand over or melt
note: NewBearer
note: NewBearer;
// the remainder note, when the carve split a larger input
change?: NewBearer
change?: NewBearer;
// the input notes burned server-side by the carve (empty when a single
// note already held exactly the target amount)
consumed: Bearer[]
}
consumed: Bearer[];
};
export class UnsupportedMultiBatchMergeError extends Error {
override readonly name = 'UnsupportedMultiBatchMergeError'
override readonly name = 'UnsupportedMultiBatchMergeError';
constructor() {
super('This carve would require multiple merge requests and cannot be performed safely.')
super('This carve would require multiple merge requests and cannot be performed safely.');
}
}
export class CarveCheckpointRequiredError extends Error {
override readonly name = 'CarveCheckpointRequiredError'
override readonly name = 'CarveCheckpointRequiredError';
constructor() {
super('A mutating carve requires a durable onCarve checkpoint.')
super('A mutating carve requires a durable onCarve checkpoint.');
}
}
@@ -65,8 +65,8 @@ export type CarveOptions = FundOperationOptions & {
// (split: target + change; merge: the combined note). Required for any
// mutating carve: the secrets come from the wallet's reserved BIP-32
// indices so a restart can never reuse or lose them.
readonly allocateOutputSecrets?: OutputSecretAllocator
}
readonly allocateOutputSecrets?: OutputSecretAllocator;
};
// Selection: only notes that can actually take part - verified (callback
// known), not locally spent, holding a real k1 (device-backed mirrors are
@@ -89,48 +89,47 @@ export const ensureExactAmount = async (
options: CarveOptions = {},
): Promise<CarveResult> => {
if (!Number.isInteger(amountMsat) || amountMsat <= 0) {
throw new Error('Amount must be a positive whole number of msat.')
throw new Error('Amount must be a positive whole number of msat.');
}
// the forced mutation policy (signatures required, one byte-identical
// replay) applies to every mint call below regardless of caller options
const mutationOptions = withMutationSafety(options)
const mutationOptions = withMutationSafety(options);
const eligible = bearers.filter(
(b) => b.verified && !b.spent && b.callback !== '' && !b.deviceId && noteK1(b.url),
)
);
// per-server greedy pick: smallest notes first until the target is
// covered (an exact single-note match short-circuits - no mutation at
// all is always better than carving)
const byServer = new Map<string, Bearer[]>()
const byServer = new Map<string, Bearer[]>();
for (const b of eligible) {
const server = serverOf(b.url)
byServer.set(server, [...(byServer.get(server) ?? []), b])
const server = serverOf(b.url);
byServer.set(server, [...(byServer.get(server) ?? []), b]);
}
let pick: Bearer[] | null = null
let pick: Bearer[] | null = null;
for (const group of byServer.values()) {
const sorted = [...group].sort((a, b) => a.amount - b.amount)
const exact = sorted.find((b) => b.amount === amountMsat)
const candidate = exact ? [exact] : accumulate(sorted, amountMsat)
if (!candidate) continue
if (!pick || better(candidate, pick, amountMsat)) pick = candidate
const sorted = [...group].sort((a, b) => a.amount - b.amount);
const exact = sorted.find((b) => b.amount === amountMsat);
const candidate = exact ? [exact] : accumulate(sorted, amountMsat);
if (!candidate) continue;
if (!pick || better(candidate, pick, amountMsat)) pick = candidate;
}
if (!pick) {
throw new Error('No mint holds enough verified, unspent balance to cover that amount.')
throw new Error('No mint holds enough verified, unspent balance to cover that amount.');
}
const base = pick[0]
const total = pick.reduce((sum, b) => sum + b.amount, 0)
const k1s = pick.map((b) => requireNoteK1(b.url))
const base = pick[0];
const total = pick.reduce((sum, b) => sum + b.amount, 0);
const k1s = pick.map((b) => requireNoteK1(b.url));
const checkpoint = async (result: CarveResult): Promise<void> => {
if (!options.onCarve) {
throw new CarveCheckpointRequiredError()
throw new CarveCheckpointRequiredError();
}
assertFundOwner(options)
await options.onCarve(result)
assertFundOwner(options)
}
const stage = (result: CarveResult): Promise<void> =>
checkpoint({...result, consumed: []})
const retire = (note: NewBearer): Promise<void> => checkpoint({note, consumed: pick})
assertFundOwner(options);
await options.onCarve(result);
assertFundOwner(options);
};
const stage = (result: CarveResult): Promise<void> => checkpoint({ ...result, consumed: [] });
const retire = (note: NewBearer): Promise<void> => checkpoint({ note, consumed: pick });
if (pick.length === 1 && total === amountMsat) {
// already exact - hand over the note itself, untouched
@@ -143,41 +142,41 @@ export const ensureExactAmount = async (
mintPubkey: base.mintPubkey,
},
consumed: [],
}
};
}
if (total === amountMsat) {
if (mergeBatches(base.callback, k1s).length !== 1) {
throw new UnsupportedMultiBatchMergeError()
throw new UnsupportedMultiBatchMergeError();
}
if (!options.onCarve) {
throw new CarveCheckpointRequiredError()
throw new CarveCheckpointRequiredError();
}
const [mergeSecret] = await requireOutputSecrets(
options.allocateOutputSecrets,
serverOf(base.url),
1,
)
);
const staged: NewBearer = {
url: withNewK1(base.url, mergeSecret, total),
callback: base.callback,
amount: total,
verified: false,
mintPubkey: base.mintPubkey,
}
await stage({note: staged, consumed: pick})
assertFundOwner(options)
};
await stage({ note: staged, consumed: pick });
assertFundOwner(options);
const merged = await mergeAmbiguitySafe(base, k1s, {
...mutationOptions,
randomSecret: () => mergeSecret,
})
});
// a landed merge reports its signature (carried in the URL's sig param)
// and earns verified only when that signature checks against a trusted
// current or previous key; a rescued merge saw no answer, so its note
// stays exactly as staged - unverified, same URL
const landedUrl = withNewK1(base.url, mergeSecret, total, merged.signature)
const landedUrl = withNewK1(base.url, mergeSecret, total, merged.signature);
const result: CarveResult = merged.rescued
? {note: staged, consumed: pick}
? { note: staged, consumed: pick }
: {
note: {
...staged,
@@ -185,66 +184,66 @@ export const ensureExactAmount = async (
verified: landedNoteVerifies(landedUrl, options.mintSignatureKeys),
},
consumed: pick,
}
await retire(result.note)
return result
};
await retire(result.note);
return result;
}
// split path: total above target - one split request across all picked
// k1s, carving the target off and leaving the change as a fresh note
if (!options.onCarve) {
throw new CarveCheckpointRequiredError()
throw new CarveCheckpointRequiredError();
}
const [partK1, changeK1] = await requireOutputSecrets(
options.allocateOutputSecrets,
serverOf(base.url),
2,
)
let partSignature: string | undefined
let changeSignature: string | undefined
);
let partSignature: string | undefined;
let changeSignature: string | undefined;
const stagedNote: NewBearer = {
url: withNewK1(base.url, partK1, amountMsat),
callback: base.callback,
amount: amountMsat,
verified: false,
mintPubkey: base.mintPubkey,
}
};
const stagedChange: NewBearer = {
url: withNewK1(base.url, changeK1, total - amountMsat),
callback: base.callback,
amount: total - amountMsat,
verified: false,
mintPubkey: base.mintPubkey,
}
await stage({note: stagedNote, change: stagedChange, consumed: pick})
let secretIndex = 0
};
await stage({ note: stagedNote, change: stagedChange, consumed: pick });
let secretIndex = 0;
const preparedSecret = (): string => {
secretIndex += 1
if (secretIndex === 1) return partK1
if (secretIndex === 2) return changeK1
throw new Error('The split requested more output secrets than were staged.')
}
assertFundOwner(options)
secretIndex += 1;
if (secretIndex === 1) return partK1;
if (secretIndex === 2) return changeK1;
throw new Error('The split requested more output secrets than were staged.');
};
assertFundOwner(options);
try {
const parts = await splitNote(base.callback, k1s, amountMsat, {
...mutationOptions,
randomSecret: preparedSecret,
})
partSignature = parts.signature
changeSignature = parts.changeSignature
});
partSignature = parts.signature;
changeSignature = parts.changeSignature;
} catch (err) {
if (err instanceof AmbiguousMutationError) {
// the split request may have landed despite the failure - probe one
// input before deciding what the carried secrets are worth
const outcome = await probeBurnedNote(base.url, mutationOptions)
if (outcome === 'live') throw err // nothing burned - a plain failure
const outcome = await probeBurnedNote(base.url, mutationOptions);
if (outcome === 'live') throw err; // nothing burned - a plain failure
if (outcome === 'unknown') {
// can't tell: surface both possible outputs unverified WITHOUT
// consuming the inputs, and stop here rather than spend from limbo
throw new UncertainOutcomeError(
'The split may have gone through but could not be confirmed - its possible outputs were already staged unverified alongside the originals.',
[],
)
);
}
// 'gone': the burn landed - the carried secrets are the only money
} else {
@@ -253,10 +252,10 @@ export const ensureExactAmount = async (
// the first attempt and refused this one as an already-spent input.
// The kit attaches the fresh output secrets to every refusal - probe
// one output before deciding they are worthless.
const carried = newSecretsOf(err)
if (carried.length !== 2) throw err
const outcome = await probeMutationOutput(base.url, carried[0], mutationOptions)
if (outcome === 'absent') throw err // never landed - a plain refusal
const carried = newSecretsOf(err);
if (carried.length !== 2) throw err;
const outcome = await probeMutationOutput(base.url, carried[0], mutationOptions);
if (outcome === 'absent') throw err; // never landed - a plain refusal
if (outcome === 'unknown') {
// can't tell whether the refusal named a retry - same limbo as
// the ambiguous case above: track the possible outputs, consume
@@ -264,7 +263,7 @@ export const ensureExactAmount = async (
throw new UncertainOutcomeError(
'The split was refused, but the refusal may have named a retry that already landed - its possible outputs were already staged unverified alongside the originals.',
[],
)
);
}
// 'live': the split landed and this answer was its retried twin -
// the carried secrets are the only money left
@@ -277,51 +276,51 @@ export const ensureExactAmount = async (
const noteUrl =
partSignature === undefined
? stagedNote.url
: withNewK1(base.url, partK1, amountMsat, partSignature)
: withNewK1(base.url, partK1, amountMsat, partSignature);
const note: NewBearer = {
url: noteUrl,
callback: base.callback,
amount: amountMsat,
verified: landedNoteVerifies(noteUrl, options.mintSignatureKeys),
mintPubkey: base.mintPubkey,
}
};
// The change may be worth less than total - amount when the mint charges
// split fees. It remains unverified at that upper bound until refresh;
// settling it here would rotate to an unstaged secret in a second request.
const changeUrl =
changeSignature === undefined
? stagedChange.url
: withNewK1(base.url, changeK1, total - amountMsat, changeSignature)
: withNewK1(base.url, changeK1, total - amountMsat, changeSignature);
const change: NewBearer = {
url: changeUrl,
callback: base.callback,
amount: total - amountMsat,
verified: false,
mintPubkey: base.mintPubkey,
}
const result = {note, change, consumed: pick}
await retire(note)
return result
}
};
const result = { note, change, consumed: pick };
await retire(note);
return result;
};
// smallest-first accumulation until the target is covered; null when the
// whole group can't reach it
const accumulate = (sorted: Bearer[], amountMsat: number): Bearer[] | null => {
const picked: Bearer[] = []
let total = 0
const picked: Bearer[] = [];
let total = 0;
for (const b of sorted) {
picked.push(b)
total += b.amount
if (total >= amountMsat) return picked
picked.push(b);
total += b.amount;
if (total >= amountMsat) return picked;
}
return null
}
return null;
};
// the better carve plan: less waste first, then fewer notes burned
const better = (a: Bearer[], b: Bearer[], target: number): boolean => {
const sum = (notes: Bearer[]) => notes.reduce((s, n) => s + n.amount, 0)
const wasteA = sum(a) - target
const wasteB = sum(b) - target
if (wasteA !== wasteB) return wasteA < wasteB
return a.length < b.length
}
const sum = (notes: Bearer[]) => notes.reduce((s, n) => s + n.amount, 0);
const wasteA = sum(a) - target;
const wasteB = sum(b) - target;
if (wasteA !== wasteB) return wasteA < wasteB;
return a.length < b.length;
};
src/lnurlcash/ops/carveRecovery.ts
+20 -20
View File
@@ -2,18 +2,18 @@
// retried below the engine. This module owns the probes that distinguish a
// plain refusal from a live or still-uncertain wallet-chosen output.
import {AmbiguousMutationError, mergeNotes, newSecretsOf, probeBurnedNote} from 'lnurlcash-kit'
import type {Bearer} from '../types'
import type {FundOperationOptions} from './shared'
import {probeMutationOutput, UncertainOutcomeError} from './shared'
import { AmbiguousMutationError, mergeNotes, newSecretsOf, probeBurnedNote } from 'lnurlcash-kit';
import type { Bearer } from '../types';
import type { FundOperationOptions } from './shared';
import { probeMutationOutput, UncertainOutcomeError } from './shared';
export type MergeOutcome = {
readonly rescued: boolean
readonly rescued: boolean;
// the mint's signature over the combined note - present only when the
// merge's own answer was seen; a rescued merge (lost answer, retried
// twin) has none to offer
readonly signature?: string
}
readonly signature?: string;
};
export const mergeAmbiguitySafe = async (
base: Bearer,
@@ -21,30 +21,30 @@ export const mergeAmbiguitySafe = async (
options: FundOperationOptions,
): Promise<MergeOutcome> => {
try {
const merged = await mergeNotes(base.callback, k1s, options)
return {rescued: false, signature: merged.signature}
const merged = await mergeNotes(base.callback, k1s, options);
return { rescued: false, signature: merged.signature };
} catch (error) {
if (error instanceof AmbiguousMutationError) {
const outcome = await probeBurnedNote(base.url, options)
if (outcome === 'live') throw error
const outcome = await probeBurnedNote(base.url, options);
if (outcome === 'live') throw error;
if (outcome === 'unknown') {
throw new UncertainOutcomeError(
'The merge may have gone through but could not be confirmed - its possible combined note was already staged unverified alongside the originals.',
[],
)
);
}
return {rescued: true}
return { rescued: true };
}
const carried = newSecretsOf(error)
if (carried.length !== 1) throw error
const outcome = await probeMutationOutput(base.url, carried[0], options)
if (outcome === 'absent') throw error
const carried = newSecretsOf(error);
if (carried.length !== 1) throw error;
const outcome = await probeMutationOutput(base.url, carried[0], options);
if (outcome === 'absent') throw error;
if (outcome === 'unknown') {
throw new UncertainOutcomeError(
'The merge was refused, but the refusal may have named a retry that already landed - its possible combined note was already staged unverified alongside the originals.',
[],
)
);
}
return {rescued: true}
return { rescued: true };
}
}
};
src/lnurlcash/ops/mint.ts
+102 -102
View File
@@ -18,48 +18,48 @@ import {
noteK1,
resolveMintInput,
serverOf,
} from 'lnurlcash-kit'
import type {MintAddressInfo, MintClaim} from 'lnurlcash-kit'
import type {Bearer, NewBearer} from '../types'
import {ceilMsatToSat} from '../units'
import type {OutputSecretAllocator} from './allocation'
import {requireOutputSecrets} from './allocation'
import type {PollOptions} from './shared'
import type {FundOperationOptions} from './shared'
import {assertFundOwner, pollUntil, withMutationSafety} from './shared'
} from 'lnurlcash-kit';
import type { MintAddressInfo, MintClaim } from 'lnurlcash-kit';
import type { Bearer, NewBearer } from '../types';
import { ceilMsatToSat } from '../units';
import type { OutputSecretAllocator } from './allocation';
import { requireOutputSecrets } from './allocation';
import type { PollOptions } from './shared';
import type { FundOperationOptions } from './shared';
import { assertFundOwner, pollUntil, withMutationSafety } from './shared';
export type PreparedMint = {
invoice: string
verifyUrl: string | null
invoice: string;
verifyUrl: string | null;
// The wallet-chosen secret the minted note lands at. Its unverified note
// is persisted before the invoice request can put this secret's hash on
// the wire.
noteSecret: string
noteSecret: string;
// the net note value asked for - the claim cross-checks the service's
// authoritative maxWithdrawable against it
expectedNoteValueMsat: number
expectedNoteValueMsat: number;
// the gross amount actually invoiced (net + mint fee, rounded up to a
// whole sat - sub-sat invoices aren't reliably payable)
grossMsat: number
mintUrl: string
withdrawLink: string
mintPubkey?: string
server: string
username: string | null
nodeInfo: MintAddressInfo | null
}
grossMsat: number;
mintUrl: string;
withdrawLink: string;
mintPubkey?: string;
server: string;
username: string | null;
nodeInfo: MintAddressInfo | null;
};
export type PrepareMintOptions = FundOperationOptions & {
readonly persistOutput: (note: NewBearer) => void | Promise<void>
readonly persistOutput: (note: NewBearer) => void | Promise<void>;
readonly beforePersist?: (quote: {
readonly grossMsat: number
readonly server: string
}) => void | Promise<void>
readonly grossMsat: number;
readonly server: string;
}) => void | Promise<void>;
// the caller's durable allocation path for the staged note's secret -
// required: the wallet's reserved BIP-32 indices are the only source a
// restart can never reuse or lose
readonly allocateOutputSecrets?: OutputSecretAllocator
}
readonly allocateOutputSecrets?: OutputSecretAllocator;
};
// Resolve a mint (Lightning Address, bare domain, bech32 LNURL), discover
// its mint address (best-effort LUD-25 experimental endpoint), read its
@@ -71,43 +71,43 @@ export const prepareMint = async (
amountMsat: number,
options: PrepareMintOptions,
): Promise<PreparedMint> => {
const {beforePersist, persistOutput, ...rest} = options
const { beforePersist, persistOutput, ...rest } = options;
// the forced mutation policy (see shared.ts) covers the invoice request
const kitOptions = withMutationSafety(rest)
const kitOptions = withMutationSafety(rest);
if (!Number.isInteger(amountMsat) || amountMsat <= 0) {
throw new Error('Amount must be a positive whole number of msat.')
throw new Error('Amount must be a positive whole number of msat.');
}
const url = resolveMintInput(mintInput)
if (!url) throw new Error('Enter a mint LNURL or Lightning Address.')
const url = resolveMintInput(mintInput);
if (!url) throw new Error('Enter a mint LNURL or Lightning Address.');
// best-effort mint-address discovery - derived from `url`'s own
// .well-known/lnurlp/{name} path; when it succeeds, its payLink is the
// authoritative place to fetch the payRequest from
const addressUrl = mintAddressUrl(url)
let nodeInfo: MintAddressInfo | null = null
let payUrl = url
const addressUrl = mintAddressUrl(url);
let nodeInfo: MintAddressInfo | null = null;
let payUrl = url;
if (addressUrl) {
try {
nodeInfo = await fetchMintAddress(addressUrl, kitOptions)
payUrl = nodeInfo.payLink
nodeInfo = await fetchMintAddress(addressUrl, kitOptions);
payUrl = nodeInfo.payLink;
} catch (error) {
// no mint-address support here - proceed with just the guess
if (!(error instanceof Error)) throw error
if (!(error instanceof Error)) throw error;
}
}
const info = await fetchPayRequest(payUrl, kitOptions)
const info = await fetchPayRequest(payUrl, kitOptions);
if (!info.withdrawLink) {
throw new Error('This payRequest does not advertise lnurlcash minting (no withdrawLink).')
throw new Error('This payRequest does not advertise lnurlcash minting (no withdrawLink).');
}
const grossMsat = ceilMsatToSat(
info.mintFee ? grossUpForMintFee(amountMsat, info.mintFee) : amountMsat,
)
);
if (grossMsat < info.minSendable || grossMsat > info.maxSendable) {
throw new Error("Amount is outside this mint's sendable range.")
throw new Error("Amount is outside this mint's sendable range.");
}
const server = serverOf(payUrl)
await beforePersist?.({grossMsat, server})
const [noteSecret] = await requireOutputSecrets(options.allocateOutputSecrets, server, 1)
const mintPubkey = nodeInfo ? nodeInfo.mintPubkey : info.mintPubkey
const server = serverOf(payUrl);
await beforePersist?.({ grossMsat, server });
const [noteSecret] = await requireOutputSecrets(options.allocateOutputSecrets, server, 1);
const mintPubkey = nodeInfo ? nodeInfo.mintPubkey : info.mintPubkey;
const staged: NewBearer = {
url: buildNoteUrl(info.withdrawLink, noteSecret, amountMsat),
callback: '',
@@ -115,15 +115,15 @@ export const prepareMint = async (
// balance stays at zero until the mint confirms the authoritative value.
amount: 0,
verified: false,
pendingMint: mintPubkey ? {mintPubkey} : {},
}
assertFundOwner(options)
await persistOutput(staged)
assertFundOwner(options)
pendingMint: mintPubkey ? { mintPubkey } : {},
};
assertFundOwner(options);
await persistOutput(staged);
assertFundOwner(options);
const invoice = await requestInvoice(info.callback, grossMsat, {
...kitOptions,
h: hashK1(noteSecret),
})
});
const prepared: PreparedMint = {
invoice: invoice.pr,
verifyUrl: invoice.verify ?? null,
@@ -135,23 +135,23 @@ export const prepareMint = async (
server,
username: lightningAddressUsername(payUrl),
nodeInfo,
}
if (mintPubkey) prepared.mintPubkey = mintPubkey
return prepared
}
};
if (mintPubkey) prepared.mintPubkey = mintPubkey;
return prepared;
};
export type ClaimedNote = {
note: NewBearer
rotated: boolean
possibleCopy?: NewBearer
rotationError?: string
}
note: NewBearer;
rotated: boolean;
possibleCopy?: NewBearer;
rotationError?: string;
};
export class MintedNoteSpentError extends Error {
override readonly name = 'MintedNoteSpentError'
override readonly name = 'MintedNoteSpentError';
constructor() {
super('The mint reports the freshly minted note as already spent.')
super('The mint reports the freshly minted note as already spent.');
}
}
@@ -168,22 +168,22 @@ export const pollMintClaim = async (
): Promise<MintClaim> =>
pollUntil(
async (fetchOptions) => {
const claim = await fetchMintClaim(withdrawLink, noteSecret, fetchOptions)
return claim.state === 'minted' || claim.state === 'spent' ? claim : null
const claim = await fetchMintClaim(withdrawLink, noteSecret, fetchOptions);
return claim.state === 'minted' || claim.state === 'spent' ? claim : null;
},
'Minted note not confirmed',
poll,
options,
)
);
export type ClaimTarget = {
withdrawLink: string
noteSecret: string
withdrawLink: string;
noteSecret: string;
// the net note value asked for - a claim, cross-checked against the
// service's authoritative maxWithdrawable
expectedNoteValueMsat: number
mintPubkey?: string
}
expectedNoteValueMsat: number;
mintPubkey?: string;
};
// The note was credited to the wallet's own secret, which rode to the mint
// only as a hash inside the invoice request. The payment preimage opens
@@ -193,73 +193,73 @@ export const claimFromSecret = async (
poll: PollOptions = {},
options: FundOperationOptions = {},
): Promise<ClaimedNote> => {
assertFundOwner(options)
const claim = await pollMintClaim(target.withdrawLink, target.noteSecret, poll, options)
assertFundOwner(options);
const claim = await pollMintClaim(target.withdrawLink, target.noteSecret, poll, options);
if (claim.state === 'spent') {
throw new MintedNoteSpentError()
throw new MintedNoteSpentError();
}
if (claim.k1 !== target.noteSecret) {
// belt and suspenders: the kit's claimMintedNote returns the queried
// secret by construction and fetchNoteInfo rejects a mismatched echo,
// so this cannot trip through the kit - if it ever does, building a
// note from the answer would track the wrong secret
throw new Error('The mint answered the claim for a different note secret.')
throw new Error('The mint answered the claim for a different note secret.');
}
if (claim.amountMsat === null || !claim.callback) {
throw new Error('The mint did not return the minted note details.')
throw new Error('The mint did not return the minted note details.');
}
const note: NewBearer = {
url: buildNoteUrl(target.withdrawLink, claim.k1, claim.amountMsat),
callback: claim.callback,
amount: claim.amountMsat,
verified: true,
}
if (target.mintPubkey) note.mintPubkey = target.mintPubkey
return {note, rotated: true}
}
};
if (target.mintPubkey) note.mintPubkey = target.mintPubkey;
return { note, rotated: true };
};
// Polls until the minted note is claimable at the wallet's staged secret.
export const claimMintedNote = async (
prepared: PreparedMint,
poll: PollOptions = {},
options: FundOperationOptions = {},
): Promise<ClaimedNote> => claimFromSecret(prepared, poll, options)
): Promise<ClaimedNote> => claimFromSecret(prepared, poll, options);
// One bounded observation for durable recovery. An unpaid invoice is normal:
// keep the staged output and try again at the next wallet/service activation.
export type StagedMintRecovery =
| {readonly state: 'unminted'}
| {readonly state: 'pending'}
| {readonly state: 'spent'}
| {readonly state: 'minted'; readonly note: NewBearer}
| { readonly state: 'unminted' }
| { readonly state: 'pending' }
| { readonly state: 'spent' }
| { readonly state: 'minted'; readonly note: NewBearer };
export const recoverStagedMintOutput = async (
staged: Bearer,
options: FundOperationOptions = {},
): Promise<StagedMintRecovery> => {
const noteSecret = noteK1(staged.url)
const expectedNoteValueMsat = noteDeclaredAmount(staged.url)
const noteSecret = noteK1(staged.url);
const expectedNoteValueMsat = noteDeclaredAmount(staged.url);
if (!staged.pendingMint || !noteSecret || expectedNoteValueMsat === null) {
throw new Error('The pending mint output is malformed.')
throw new Error('The pending mint output is malformed.');
}
const withdrawLink = new URL(staged.url)
withdrawLink.searchParams.delete('k1')
withdrawLink.searchParams.delete('amount')
withdrawLink.searchParams.delete('sig')
assertFundOwner(options)
const claim = await fetchMintClaim(withdrawLink.href, noteSecret, withMutationSafety(options))
if (claim.state === 'unminted') return {state: 'unminted'}
if (claim.state === 'pending') return {state: 'pending'}
if (claim.state === 'spent') return {state: 'spent'}
const withdrawLink = new URL(staged.url);
withdrawLink.searchParams.delete('k1');
withdrawLink.searchParams.delete('amount');
withdrawLink.searchParams.delete('sig');
assertFundOwner(options);
const claim = await fetchMintClaim(withdrawLink.href, noteSecret, withMutationSafety(options));
if (claim.state === 'unminted') return { state: 'unminted' };
if (claim.state === 'pending') return { state: 'pending' };
if (claim.state === 'spent') return { state: 'spent' };
if (claim.k1 !== noteSecret || claim.amountMsat === null || !claim.callback) {
throw new Error('The mint did not return the pending output details.')
throw new Error('The mint did not return the pending output details.');
}
const note: NewBearer = {
url: buildNoteUrl(withdrawLink.href, noteSecret, claim.amountMsat),
callback: claim.callback,
amount: claim.amountMsat,
verified: true,
}
if (staged.pendingMint.mintPubkey) note.mintPubkey = staged.pendingMint.mintPubkey
return {state: 'minted', note}
}
};
if (staged.pendingMint.mintPubkey) note.mintPubkey = staged.pendingMint.mintPubkey;
return { state: 'minted', note };
};
src/lnurlcash/ops/pay.ts
+92 -77
View File
@@ -18,16 +18,16 @@ import {
sameInvoice,
serverOf,
withNewK1,
} from 'lnurlcash-kit'
import type {LnurlcashOptions, MeltResult} from 'lnurlcash-kit'
import type {Bearer, NewBearer} from '../types'
import type {OutputSecretAllocator} from './allocation'
import {requireOutputSecrets} from './allocation'
import type {CarveResult} from './carve'
import {ensureExactAmount} from './carve'
import type {PollOptions} from './shared'
import type {FundOperationOptions, MintSignatureKeys} from './shared'
import {assertFundOwner, pollVerifyUntilSettled, withMutationSafety} from './shared'
} from 'lnurlcash-kit';
import type { LnurlcashOptions, MeltResult } from 'lnurlcash-kit';
import type { Bearer, NewBearer } from '../types';
import type { OutputSecretAllocator } from './allocation';
import { requireOutputSecrets } from './allocation';
import type { CarveResult } from './carve';
import { ensureExactAmount } from './carve';
import type { PollOptions } from './shared';
import type { FundOperationOptions, MintSignatureKeys } from './shared';
import { assertFundOwner, pollVerifyUntilSettled, withMutationSafety } from './shared';
export type PayOutcome =
| 'settled'
@@ -35,51 +35,51 @@ export type PayOutcome =
| 'unknown-still-pending'
// the service reports the carved note as already spent before the melt
// even started - nothing was paid, and the note is definitively gone
| 'note-already-spent'
| 'note-already-spent';
export type PayResult = {
outcome: PayOutcome
carve: CarveResult
outcome: PayOutcome;
carve: CarveResult;
// the invoice that was (attempted to be) paid
invoice: string
amountMsat: number
verifyUrl: string | null
rotatedNote?: NewBearer
rescuedNote?: NewBearer
}
invoice: string;
amountMsat: number;
verifyUrl: string | null;
rotatedNote?: NewBearer;
rescuedNote?: NewBearer;
};
export class PayReturnCheckpointRequiredError extends Error {
override readonly name = 'PayReturnCheckpointRequiredError'
override readonly name = 'PayReturnCheckpointRequiredError';
constructor() {
super('A pay-return classification requires a durable onReturnReady checkpoint.')
super('A pay-return classification requires a durable onReturnReady checkpoint.');
}
}
export type PayOptions = {
// required when `input` is a Lightning Address / LNURL-pay (a bolt11
// carries its own amount)
amountMsat?: number
amountMsat?: number;
// verify-poll budget - tests shrink this
poll?: PollOptions
poll?: PollOptions;
// kit transport overrides (fetch injection, timeouts)
kit?: LnurlcashOptions
assertOwner?: () => void
kit?: LnurlcashOptions;
assertOwner?: () => void;
// carve checkpoint - committed before the melt and the settlement wait,
// so an abort mid-wait never strands the carve (see
// FundOperationOptions.onCarve)
onCarve?: FundOperationOptions['onCarve']
onCarve?: FundOperationOptions['onCarve'];
// the caller's durable allocation path: the carve's output secrets and -
// only when the return classification actually needs one - the recovery
// secret. Required for any mutating carve or return classification.
allocateOutputSecrets?: OutputSecretAllocator
allocateOutputSecrets?: OutputSecretAllocator;
// trusted signing keys the carve's landed outputs verify against (see
// FundOperationOptions.mintSignatureKeys)
mintSignatureKeys?: MintSignatureKeys
mintSignatureKeys?: MintSignatureKeys;
// Called before the classification rotate puts its chosen output secret
// on the wire. Production callers durably link it to the carved source.
onReturnReady?: (carve: CarveResult, recoverySecret: string) => void | Promise<void>
}
onReturnReady?: (carve: CarveResult, recoverySecret: string) => void | Promise<void>;
};
// A melt's resolved promise only means the payment is in flight; the
// outcome is classified by polling the melt's LUD-25 verify URL, then - if
@@ -94,75 +94,90 @@ export type PayOptions = {
export const payWithBearers = async (
bearers: Bearer[],
input: string,
{amountMsat, poll = {}, kit = {}, assertOwner, onCarve, allocateOutputSecrets, mintSignatureKeys, onReturnReady}: PayOptions = {},
{
amountMsat,
poll = {},
kit = {},
assertOwner,
onCarve,
allocateOutputSecrets,
mintSignatureKeys,
onReturnReady,
}: PayOptions = {},
): Promise<PayResult> => {
// the forced mutation policy (see shared.ts) covers the carve, the melt,
// and the classification rotate regardless of caller kit options
const options: FundOperationOptions = withMutationSafety({
...kit,
...(assertOwner ? {assertOwner} : {}),
...(onCarve ? {onCarve} : {}),
...(mintSignatureKeys ? {mintSignatureKeys} : {}),
})
let invoice: string
let amount: number
const trimmed = input.trim()
...(assertOwner ? { assertOwner } : {}),
...(onCarve ? { onCarve } : {}),
...(mintSignatureKeys ? { mintSignatureKeys } : {}),
});
let invoice: string;
let amount: number;
const trimmed = input.trim();
if (isBolt11Invoice(trimmed)) {
const decoded = decodeBolt11AmountMsat(trimmed)
const decoded = decodeBolt11AmountMsat(trimmed);
if (decoded === null || decoded <= 0) {
throw new Error(
"Could not read this invoice's amount - amount-less invoices are not supported.",
)
);
}
invoice = trimmed
amount = decoded
invoice = trimmed;
amount = decoded;
} else {
// a Lightning Address (or LNURL-pay) has no invoice of its own yet -
// resolving it gets a payRequest, and an amount is needed before an
// actual invoice exists
const url = resolveLnurlInput(trimmed)
const url = resolveLnurlInput(trimmed);
if (!url) {
throw new Error('Not a valid bolt11 invoice or Lightning Address.')
throw new Error('Not a valid bolt11 invoice or Lightning Address.');
}
if (amountMsat === undefined || !Number.isInteger(amountMsat) || amountMsat <= 0) {
throw new Error('Enter an amount to pay to this address.')
throw new Error('Enter an amount to pay to this address.');
}
const info = await fetchPayRequest(url, options)
const info = await fetchPayRequest(url, options);
if (amountMsat < info.minSendable || amountMsat > info.maxSendable) {
throw new Error("Amount is outside the payee's sendable range.")
throw new Error("Amount is outside the payee's sendable range.");
}
const result = await requestInvoice(info.callback, amountMsat, options)
invoice = result.pr
amount = amountMsat
const result = await requestInvoice(info.callback, amountMsat, options);
invoice = result.pr;
amount = amountMsat;
}
const carve = await ensureExactAmount(bearers, amount, {
...options,
...(allocateOutputSecrets ? {allocateOutputSecrets} : {}),
})
const k1 = requireNoteK1(carve.note.url)
if (carve.consumed.length === 0) assertFundOwner(options)
let melt: MeltResult
...(allocateOutputSecrets ? { allocateOutputSecrets } : {}),
});
const k1 = requireNoteK1(carve.note.url);
if (carve.consumed.length === 0) assertFundOwner(options);
let melt: MeltResult;
try {
melt = await meltNote(carve.note.callback, k1, invoice, options)
melt = await meltNote(carve.note.callback, k1, invoice, options);
} catch (err) {
// this melt names a single note, so a NoteSpentError here is
// unambiguous - it's already gone, and gets locked spent the same way
// a successful melt would have locked it
if (err instanceof NoteSpentError) {
return {outcome: 'note-already-spent', carve, invoice, amountMsat: amount, verifyUrl: null}
return { outcome: 'note-already-spent', carve, invoice, amountMsat: amount, verifyUrl: null };
}
throw err
throw err;
}
if (!melt.verify) {
// no melt proof to poll - the note locking as spent locally is all the
// confirmation there is
return {outcome: 'unknown-still-pending', carve, invoice, amountMsat: amount, verifyUrl: null}
return {
outcome: 'unknown-still-pending',
carve,
invoice,
amountMsat: amount,
verifyUrl: null,
};
}
const verifyUrl = melt.verify
const verifyUrl = melt.verify;
try {
const proof = await pollVerifyUntilSettled(verifyUrl, poll, options)
const proof = await pollVerifyUntilSettled(verifyUrl, poll, options);
// a settled report is only this payment's proof when it's for the
// invoice this melt actually paid - a mint that mixes up proofs must
// not confirm the wrong payment. The verify URL is already scoped to
@@ -171,27 +186,27 @@ export const payWithBearers = async (
// belongs to another payment, while an undecodable one says nothing
// either way (a service regenerating synthetic prs in proofs) and is
// tolerated.
const proofAmount = decodeBolt11AmountMsat(proof.pr)
const proofAmount = decodeBolt11AmountMsat(proof.pr);
if (!sameInvoice(proof.pr, invoice) && proofAmount !== null && proofAmount !== amount) {
return {outcome: 'unknown-still-pending', carve, invoice, amountMsat: amount, verifyUrl}
return { outcome: 'unknown-still-pending', carve, invoice, amountMsat: amount, verifyUrl };
}
return {outcome: 'settled', carve, invoice, amountMsat: amount, verifyUrl}
return { outcome: 'settled', carve, invoice, amountMsat: amount, verifyUrl };
} catch {
// The verify budget ran out. Journal the exact output secret before the
// classification rotate reaches the mint, so a crash can recover either
// the returned source or the rotated replacement.
if (!onReturnReady) throw new PayReturnCheckpointRequiredError()
if (!onReturnReady) throw new PayReturnCheckpointRequiredError();
const [recoverySecret] = await requireOutputSecrets(
allocateOutputSecrets,
serverOf(carve.note.url),
1,
)
await onReturnReady(carve, recoverySecret)
);
await onReturnReady(carve, recoverySecret);
try {
const rotated = await rotateNote(carve.note.callback, k1, {
...options,
randomSecret: () => recoverySecret,
})
});
return {
outcome: 'failed-funds-returned',
carve,
@@ -200,18 +215,18 @@ export const payWithBearers = async (
callback: carve.note.callback,
amount,
verified: true,
...(carve.note.mintPubkey ? {mintPubkey: carve.note.mintPubkey} : {}),
...(carve.note.mintPubkey ? { mintPubkey: carve.note.mintPubkey } : {}),
},
invoice,
amountMsat: amount,
verifyUrl,
}
};
} catch (err) {
if (err instanceof PendingNoteError) {
return {outcome: 'unknown-still-pending', carve, invoice, amountMsat: amount, verifyUrl}
return { outcome: 'unknown-still-pending', carve, invoice, amountMsat: amount, verifyUrl };
}
if (err instanceof NoteSpentError) {
return {outcome: 'settled', carve, invoice, amountMsat: amount, verifyUrl}
return { outcome: 'settled', carve, invoice, amountMsat: amount, verifyUrl };
}
if (err instanceof AmbiguousMutationError) {
const rescuedNote: NewBearer = {
@@ -219,8 +234,8 @@ export const payWithBearers = async (
callback: carve.note.callback,
amount,
verified: false,
}
if (carve.note.mintPubkey) rescuedNote.mintPubkey = carve.note.mintPubkey
};
if (carve.note.mintPubkey) rescuedNote.mintPubkey = carve.note.mintPubkey;
return {
outcome: 'failed-funds-returned',
carve,
@@ -228,9 +243,9 @@ export const payWithBearers = async (
amountMsat: amount,
verifyUrl,
rescuedNote,
}
};
}
return {outcome: 'unknown-still-pending', carve, invoice, amountMsat: amount, verifyUrl}
return { outcome: 'unknown-still-pending', carve, invoice, amountMsat: amount, verifyUrl };
}
}
}
};
src/lnurlcash/ops/receiveBearer.ts
+45 -45
View File
@@ -22,37 +22,37 @@ import {
requireNoteK1,
serverOf,
withNewK1,
} from 'lnurlcash-kit'
import type {Bearer, NewBearer} from '../types'
import {receiveNote, secureReceivedNote} from '../receive'
import type {OutputSecretAllocator} from './allocation'
import {requireOutputSecrets} from './allocation'
import type {FundOperationOptions} from './shared'
import {assertFundOwner, probeMutationOutput, withMutationSafety} from './shared'
} from 'lnurlcash-kit';
import type { Bearer, NewBearer } from '../types';
import { receiveNote, secureReceivedNote } from '../receive';
import type { OutputSecretAllocator } from './allocation';
import { requireOutputSecrets } from './allocation';
import type { FundOperationOptions } from './shared';
import { assertFundOwner, probeMutationOutput, withMutationSafety } from './shared';
export class ReceiveRotationStagingRequiredError extends Error {
override readonly name = 'ReceiveRotationStagingRequiredError'
override readonly name = 'ReceiveRotationStagingRequiredError';
constructor() {
super('A receive rotation requires a durable stageRotation checkpoint.')
super('A receive rotation requires a durable stageRotation checkpoint.');
}
}
export type ReceiveBearerOptions = FundOperationOptions & {
// the caller's durable allocation path for the rotation's fresh secret -
// required when stageRotation is present
readonly allocateOutputSecrets?: OutputSecretAllocator
readonly allocateOutputSecrets?: OutputSecretAllocator;
// durably persist the future rotated note (unverified, pendingMint
// carrying the original k1 as sourceRecoverySecret) before the rotate
// reaches the mint. The record's fate is decided by the result's
// `stage` disposition.
readonly stageRotation?: (staged: NewBearer) => void | Promise<void>
}
readonly stageRotation?: (staged: NewBearer) => void | Promise<void>;
};
export type ReceivedNote = {
readonly note: NewBearer
readonly rotated: boolean
readonly rotationError?: string
readonly note: NewBearer;
readonly rotated: boolean;
readonly rotationError?: string;
// how the caller disposes the staged rotation output:
// - 'finalize': the rotate landed - replace the staged record with `note`
// - 'keep': the outcome is genuinely ambiguous - the staged record IS
@@ -62,8 +62,8 @@ export type ReceivedNote = {
// record; `note` is the original, still verified as received
// - 'none': no rotate was attempted (the note could not be verified) -
// nothing was staged
readonly stage: 'finalize' | 'keep' | 'discard' | 'none'
}
readonly stage: 'finalize' | 'keep' | 'discard' | 'none';
};
// NoteSpentError / NoteUnknownError / PendingNoteError from the service are
// definitive and propagate; an unreachable service still yields the note,
@@ -74,20 +74,20 @@ export const receiveBearer = async (
options: ReceiveBearerOptions = {},
): Promise<ReceivedNote> => {
// the forced mutation policy (see shared.ts) covers the rotate below
const mutationOptions = withMutationSafety(options)
const note = await receiveNote(input, existing)
const mutationOptions = withMutationSafety(options);
const note = await receiveNote(input, existing);
if (!note.verified || !note.callback) {
return {note, rotated: false, stage: 'none'}
return { note, rotated: false, stage: 'none' };
}
// the rotate burns the sender's secret at a fresh one: stage that future
// note durably before the mutation can land, or a crash strands the money
const staging = options.stageRotation
if (!staging) throw new ReceiveRotationStagingRequiredError()
const staging = options.stageRotation;
if (!staging) throw new ReceiveRotationStagingRequiredError();
const [rotationSecret] = await requireOutputSecrets(
options.allocateOutputSecrets,
serverOf(note.url),
1,
)
);
const staged: NewBearer = {
url: withNewK1(note.url, rotationSecret, note.amount),
callback: note.callback,
@@ -95,20 +95,20 @@ export const receiveBearer = async (
verified: false,
pendingMint: {
sourceRecoverySecret: requireNoteK1(note.url),
...(note.mintPubkey ? {mintPubkey: note.mintPubkey} : {}),
...(note.mintPubkey ? { mintPubkey: note.mintPubkey } : {}),
},
}
await staging(staged)
const rotateOptions = {...mutationOptions, randomSecret: () => rotationSecret}
};
await staging(staged);
const rotateOptions = { ...mutationOptions, randomSecret: () => rotationSecret };
// the disposition the caller applies to its staged record
const disposition = (rotated: boolean, ambiguous: boolean): ReceivedNote['stage'] => {
if (rotated) return 'finalize'
return ambiguous ? 'keep' : 'discard'
}
if (rotated) return 'finalize';
return ambiguous ? 'keep' : 'discard';
};
try {
assertFundOwner(options)
const rotatedUrl = await secureReceivedNote(note, rotateOptions)
return {note: {...note, url: rotatedUrl}, rotated: true, stage: disposition(true, false)}
assertFundOwner(options);
const rotatedUrl = await secureReceivedNote(note, rotateOptions);
return { note: { ...note, url: rotatedUrl }, rotated: true, stage: disposition(true, false) };
} catch (err) {
// A classified rotate refusal can still be a LANDED rotate: the
// callback is a GET and HTTP stacks retry GETs, so the service may
@@ -116,25 +116,25 @@ export const receiveBearer = async (
// already-spent input. The refusal then proves the sender's copy is
// burned and the carried fresh secret is the only money left - probe
// it before believing the refusal.
const carried = newSecretsOf(err)
const carried = newSecretsOf(err);
if (carried.length === 1 && !(err instanceof AmbiguousMutationError)) {
const outcome = await probeMutationOutput(note.url, carried[0], mutationOptions)
const outcome = await probeMutationOutput(note.url, carried[0], mutationOptions);
if (outcome === 'live') {
return {
note: {...note, url: withNewK1(note.url, carried[0], note.amount)},
note: { ...note, url: withNewK1(note.url, carried[0], note.amount) },
rotated: true,
stage: disposition(true, false),
}
};
}
if (outcome === 'unknown') {
return {
// the sender's copy may be burned - it cannot stay verified; the
// staged record is the possible rotated copy
note: {...note, verified: false},
note: { ...note, verified: false },
rotated: false,
stage: disposition(false, true),
rotationError: `${err instanceof Error ? err.message : String(err)} The refusal may have named a retry of a rotation that already landed - the possible rotated copy is tracked unverified alongside this one.`,
}
};
}
// 'absent': the refusal is genuine - fall through to the distinct
// handling below
@@ -147,10 +147,10 @@ export const receiveBearer = async (
err instanceof PendingNoteError ||
err instanceof NoteUnknownError
) {
throw err
throw err;
}
if (err instanceof AmbiguousMutationError) {
const outcome = await probeBurnedNote(note.url, mutationOptions)
const outcome = await probeBurnedNote(note.url, mutationOptions);
if (outcome === 'gone') {
return {
note: {
@@ -159,7 +159,7 @@ export const receiveBearer = async (
},
rotated: true,
stage: disposition(true, false),
}
};
}
if (outcome === 'unknown') {
return {
@@ -167,7 +167,7 @@ export const receiveBearer = async (
rotated: false,
stage: disposition(false, true),
rotationError: `${err.message} The rotation may still have gone through - the possible rotated copy is tracked unverified alongside this one.`,
}
};
}
}
// a failed rotate never fails the receive - the note is money as it
@@ -178,6 +178,6 @@ export const receiveBearer = async (
rotated: false,
rotationError: err instanceof Error ? err.message : String(err),
stage: disposition(false, false),
}
};
}
}
};
src/lnurlcash/ops/shared.ts
+77 -75
View File
@@ -10,11 +10,11 @@ import {
serverOf,
verifyNoteSignature,
withNewK1,
} from 'lnurlcash-kit'
import type {LnurlcashOptions, VerifyResult} from 'lnurlcash-kit'
import {NoteSpentError, NoteUnknownError, noteDeclaredAmount} from 'lnurlcash-kit'
import type {NewBearer} from '../types'
import type {CarveResult} from './carve'
} from 'lnurlcash-kit';
import type { LnurlcashOptions, VerifyResult } from 'lnurlcash-kit';
import { NoteSpentError, NoteUnknownError, noteDeclaredAmount } from 'lnurlcash-kit';
import type { NewBearer } from '../types';
import type { CarveResult } from './carve';
// a mutation's answer was lost AND the probe could not tell whether it
// landed - the possible outputs the fresh secrets would control, for the
@@ -22,11 +22,11 @@ import type {CarveResult} from './carve'
// checkpoint may already have persisted them, in which case this list is
// empty so callers do not add duplicate records.
export class UncertainOutcomeError extends Error {
readonly possibleOutputs: NewBearer[]
readonly possibleOutputs: NewBearer[];
constructor(message: string, possibleOutputs: NewBearer[]) {
super(message)
this.name = 'UncertainOutcomeError'
this.possibleOutputs = possibleOutputs
super(message);
this.name = 'UncertainOutcomeError';
this.possibleOutputs = possibleOutputs;
}
}
@@ -34,30 +34,30 @@ export class UncertainOutcomeError extends Error {
// from budget exhaustion so the caller can treat it as normal teardown
export class PollAbortedError extends Error {
constructor() {
super('The wait was interrupted by shutdown.')
this.name = 'PollAbortedError'
super('The wait was interrupted by shutdown.');
this.name = 'PollAbortedError';
}
}
export type FundOperationOptions = LnurlcashOptions & {
readonly assertOwner?: () => void
readonly assertOwner?: () => void;
// Two durable phases for a mutating carve. Before wire use, unverified
// outputs are reported with `consumed: []`. After the mint mutation is
// known to have landed, the already-staged note is reported again with
// the inputs that can now be retired. A rejection in either phase stops
// the flow; exact-note carves call neither phase.
readonly onCarve?: (carve: CarveResult) => void | Promise<void>
readonly onCarve?: (carve: CarveResult) => void | Promise<void>;
// the trusted signing keys a landed mutation output's signature is
// checked against before it may report verified: the mint's pinned
// current key AND its previous one (a just-rotated mint's last notes
// stay verifiable). Production supplies the trusted-mint registry's
// keys; an absent source (or empty list) keeps every landed output
// staged unverified rather than trusting it blindly.
readonly mintSignatureKeys?: MintSignatureKeys
}
readonly mintSignatureKeys?: MintSignatureKeys;
};
// the trusted signing keys available for one mint server
export type MintSignatureKeys = (server: string) => readonly string[]
export type MintSignatureKeys = (server: string) => readonly string[];
// The mutation safety policy, forced where the engine talks to a mint:
// every mutation must come back signed (the signature is the only offline
@@ -66,11 +66,13 @@ export type MintSignatureKeys = (server: string) => readonly string[]
// safe). Both are lnurlcash-kit's own defaults - restating them AFTER the
// caller spread means no caller's options object can quietly strip either
// guarantee.
export const withMutationSafety = <Options extends LnurlcashOptions>(options: Options): Options => ({
export const withMutationSafety = <Options extends LnurlcashOptions>(
options: Options,
): Options => ({
...options,
requireSignatures: true,
mutationRetries: 1,
})
});
// A landed mutation output earns verified:true only when its signature
// (carried as the URL's sig param) verifies against a trusted key for its
@@ -82,21 +84,21 @@ export const landedNoteVerifies = (
noteUrl: string,
keysFor: MintSignatureKeys | undefined,
): boolean => {
if (!keysFor) return false
const k1 = noteK1(noteUrl)
const amountMsat = noteDeclaredAmount(noteUrl)
const signature = noteSignature(noteUrl)
if (!k1 || amountMsat === null || !signature) return false
const keys = keysFor(serverOf(noteUrl))
return keys.length > 0 && verifyNoteSignature(k1, amountMsat, signature, [...keys])
}
if (!keysFor) return false;
const k1 = noteK1(noteUrl);
const amountMsat = noteDeclaredAmount(noteUrl);
const signature = noteSignature(noteUrl);
if (!k1 || amountMsat === null || !signature) return false;
const keys = keysFor(serverOf(noteUrl));
return keys.length > 0 && verifyNoteSignature(k1, amountMsat, signature, [...keys]);
};
export const assertFundOwner = (options: FundOperationOptions): void => {
options.assertOwner?.()
}
options.assertOwner?.();
};
// what probing a would-be mutation output can tell
export type OutputProbe = 'live' | 'absent' | 'unknown'
export type OutputProbe = 'live' | 'absent' | 'unknown';
// A refused mutation can still have LANDED: the redeem callback is a GET
// and HTTP stacks retry GETs, so the service may have executed the first
@@ -113,53 +115,53 @@ export const probeMutationOutput = async (
options: LnurlcashOptions = {},
): Promise<OutputProbe> => {
try {
await fetchNoteInfo(withNewK1(noteUrl, secret, noteDeclaredAmount(noteUrl) ?? 0), options)
return 'live'
await fetchNoteInfo(withNewK1(noteUrl, secret, noteDeclaredAmount(noteUrl) ?? 0), options);
return 'live';
} catch (err) {
if (err instanceof NoteSpentError || err instanceof NoteUnknownError) return 'absent'
return 'unknown'
if (err instanceof NoteSpentError || err instanceof NoteUnknownError) return 'absent';
return 'unknown';
}
}
};
export type PollOptions = {
// first delay between checks (doubles each round up to intervalCapMs)
intervalMs?: number
intervalCapMs?: number
intervalMs?: number;
intervalCapMs?: number;
// total budget before giving up
maxWaitMs?: number
maxWaitMs?: number;
// aborts the wait promptly (shutdown). Only the WAIT is interruptible:
// callers pass this for work whose observation phase may outlive the
// caller - once pollVerifyUntilSettled has returned, the signal no
// longer reaches anything
signal?: AbortSignal
}
signal?: AbortSignal;
};
const DEFAULT_POLL: Required<Omit<PollOptions, 'signal'>> = {
intervalMs: 1000,
intervalCapMs: 5000,
maxWaitMs: 120_000,
}
};
const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
// a sleep that ends immediately on abort instead of riding out its timer
const abortableSleep = (ms: number, signal: AbortSignal): Promise<void> =>
new Promise((resolve, reject) => {
const onAbort = (): void => {
clearTimeout(timer)
reject(new PollAbortedError())
}
clearTimeout(timer);
reject(new PollAbortedError());
};
const timer = setTimeout(() => {
signal.removeEventListener('abort', onAbort)
resolve()
}, ms)
signal.removeEventListener('abort', onAbort);
resolve();
}, ms);
if (signal.aborted) {
clearTimeout(timer)
reject(new PollAbortedError())
return
clearTimeout(timer);
reject(new PollAbortedError());
return;
}
signal.addEventListener('abort', onAbort, {once: true})
})
signal.addEventListener('abort', onAbort, { once: true });
});
// polls `check` until it yields a value, with backoff, inside a total
// time budget. A single failed check isn't fatal - the next round tries
@@ -172,42 +174,42 @@ export const pollUntil = async <T>(
poll: PollOptions,
options: LnurlcashOptions,
): Promise<T> => {
const {intervalMs, intervalCapMs, maxWaitMs, signal} = {
const { intervalMs, intervalCapMs, maxWaitMs, signal } = {
...DEFAULT_POLL,
...poll,
}
};
const fetchOptions: LnurlcashOptions = signal
? {
...options,
fetch: (input, init) => {
const base = options.fetch ?? globalThis.fetch
return base(input, {...init, signal})
const base = options.fetch ?? globalThis.fetch;
return base(input, { ...init, signal });
},
}
: options
const deadline = Date.now() + maxWaitMs
let delay = intervalMs
let lastError: unknown = null
: options;
const deadline = Date.now() + maxWaitMs;
let delay = intervalMs;
let lastError: unknown = null;
while (Date.now() < deadline) {
if (signal?.aborted) throw new PollAbortedError()
if (signal?.aborted) throw new PollAbortedError();
try {
const result = await check(fetchOptions)
if (result !== null) return result
lastError = null
const result = await check(fetchOptions);
if (result !== null) return result;
lastError = null;
} catch (err) {
// the signal's own AbortError lands here on an interrupted fetch
if (signal?.aborted) throw new PollAbortedError()
lastError = err
if (signal?.aborted) throw new PollAbortedError();
lastError = err;
}
if (signal) await abortableSleep(Math.min(delay, Math.max(0, deadline - Date.now())), signal)
else await sleep(Math.min(delay, Math.max(0, deadline - Date.now())))
delay = Math.min(delay * 2, intervalCapMs)
if (signal) await abortableSleep(Math.min(delay, Math.max(0, deadline - Date.now())), signal);
else await sleep(Math.min(delay, Math.max(0, deadline - Date.now())));
delay = Math.min(delay * 2, intervalCapMs);
}
if (lastError instanceof Error) {
throw new Error(`${exhausted}: ${lastError.message}`)
throw new Error(`${exhausted}: ${lastError.message}`);
}
throw new Error(`${exhausted} within the time budget.`)
}
throw new Error(`${exhausted} within the time budget.`);
};
// polls a LUD-21/LUD-25 verify endpoint until it reports settled, with
// backoff, inside a total time budget. A single failed check isn't fatal -
@@ -221,10 +223,10 @@ export const pollVerifyUntilSettled = (
): Promise<VerifyResult> =>
pollUntil(
async (fetchOptions) => {
const result = await fetchInvoiceVerification(verifyUrl, fetchOptions)
return result.settled ? result : null
const result = await fetchInvoiceVerification(verifyUrl, fetchOptions);
return result.settled ? result : null;
},
'Payment not confirmed',
poll,
options,
)
);
src/lnurlcash/ops/transfer.ts
+133 -124
View File
@@ -25,18 +25,18 @@ import {
rotateNote,
serverOf,
withNewK1,
} from 'lnurlcash-kit'
import type {LnurlcashOptions} from 'lnurlcash-kit'
import type {Bearer, NewBearer} from '../types'
import type {OutputSecretAllocator} from './allocation'
import {requireOutputSecrets} from './allocation'
import type {CarveResult} from './carve'
import {ensureExactAmount} from './carve'
import type {ClaimedNote, PreparedMint, PrepareMintOptions} from './mint'
import {MintedNoteSpentError, claimFromSecret, prepareMint} from './mint'
import type {PollOptions} from './shared'
import type {FundOperationOptions, MintSignatureKeys} from './shared'
import {assertFundOwner, withMutationSafety} from './shared'
} from 'lnurlcash-kit';
import type { LnurlcashOptions } from 'lnurlcash-kit';
import type { Bearer, NewBearer } from '../types';
import type { OutputSecretAllocator } from './allocation';
import { requireOutputSecrets } from './allocation';
import type { CarveResult } from './carve';
import { ensureExactAmount } from './carve';
import type { ClaimedNote, PreparedMint, PrepareMintOptions } from './mint';
import { MintedNoteSpentError, claimFromSecret, prepareMint } from './mint';
import type { PollOptions } from './shared';
import type { FundOperationOptions, MintSignatureKeys } from './shared';
import { assertFundOwner, withMutationSafety } from './shared';
export type TransferOutcome =
// the melt settled and the target note was claimed (and rotated)
@@ -51,95 +51,95 @@ export type TransferOutcome =
| 'note-already-spent'
// the target invoice settled (the money arrived) but the claim could
// not complete - claimMaterial carries everything needed to retry it
| 'settled-claim-failed'
| 'settled-claim-failed';
export type TransferQuote = {
// the net value the user wants to land on the target mint
requestedMsat: number
requestedMsat: number;
// what the source side must cover - the target invoice, grossed up for
// the target's advertised mint fee and rounded to a whole sat
grossMsat: number
grossMsat: number;
// the target mint's receive fee as estimated by the gross-up (the
// service's own fee math is authoritative - the claimed note's amount
// is what it actually withheld)
targetMintFeeMsat: number
targetMintFeeMsat: number;
// LUD-25 melt has no fee field - the melted note must equal the invoice
// exactly, so no source-side reserve is even expressible
sourceMeltFeeReserveMsat: number
}
sourceMeltFeeReserveMsat: number;
};
// everything a caller needs to retry (or log) the target claim when the
// transfer could not complete it - once the melt has settled this
// material IS the money, so it is never dropped
export type TransferClaimMaterial = {
invoice: string
withdrawLink: string
expectedNoteValueMsat: number
note: NewBearer
invoice: string;
withdrawLink: string;
expectedNoteValueMsat: number;
note: NewBearer;
// the wallet-chosen secret the target note lands at.
// The note exists at this secret from the moment the invoice settles -
// the caller can rebuild the note URL from it and retry the claim
noteSecret: string
}
noteSecret: string;
};
export type TransferResult = {
outcome: TransferOutcome
outcome: TransferOutcome;
// the source-side changeset: consumed inputs and any change note
carve: CarveResult
quote: TransferQuote
carve: CarveResult;
quote: TransferQuote;
// the invoice the source note was melted to pay
invoice: string
invoice: string;
// the target invoice's optional verify URL (used for a payment receipt;
// the staged note itself is the settlement observation)
verifyUrl: string | null
sourceServer: string
targetServer: string
verifyUrl: string | null;
sourceServer: string;
targetServer: string;
// the fresh target note, on 'settled'
mintedAtTarget?: ClaimedNote
mintedAtTarget?: ClaimedNote;
// on failed-funds-returned, when the source-probe rotate succeeded: the
// returned funds re-secured at a fresh secret. Kept OUT of `carve`
// (which always describes the carve as committed by the onCarve
// checkpoint) so an early-committed carve and a post-wait rotation can
// both be persisted - the carved note the rotate burned must be marked
// spent, this note added
rotatedNote?: NewBearer
rotatedNote?: NewBearer;
// present whenever the claim could still complete later
claimMaterial?: TransferClaimMaterial
claimMaterial?: TransferClaimMaterial;
// a fresh secret rescued from an ambiguous rotate while classifying the
// melt - the caller must track it unverified (same semantics as pay.ts)
rescuedNote?: NewBearer
}
rescuedNote?: NewBearer;
};
export class TransferMeltCheckpointRequiredError extends Error {
override readonly name = 'TransferMeltCheckpointRequiredError'
override readonly name = 'TransferMeltCheckpointRequiredError';
constructor() {
super('A source melt requires a durable onMeltReady checkpoint.')
super('A source melt requires a durable onMeltReady checkpoint.');
}
}
export type TransferOptions = {
// verify-poll budget - tests shrink this
poll?: PollOptions
poll?: PollOptions;
// kit transport overrides (fetch injection, timeouts)
kit?: LnurlcashOptions
assertOwner?: () => void
kit?: LnurlcashOptions;
assertOwner?: () => void;
// carve checkpoint - committed before the melt and the target
// settlement wait, so an abort mid-wait can never strand the carve (see
// FundOperationOptions.onCarve)
onCarve?: FundOperationOptions['onCarve']
onCarve?: FundOperationOptions['onCarve'];
// persists the target note before its hash reaches the invoice callback
persistOutput: PrepareMintOptions['persistOutput']
persistOutput: PrepareMintOptions['persistOutput'];
// the caller's durable allocation path: the staged target note's secret,
// the source carve's outputs, and the source recovery secret. Required:
// the wallet's reserved BIP-32 indices are the only source a restart can
// never reuse or lose.
allocateOutputSecrets?: OutputSecretAllocator
allocateOutputSecrets?: OutputSecretAllocator;
// trusted signing keys the source carve's landed outputs verify against
mintSignatureKeys?: MintSignatureKeys
mintSignatureKeys?: MintSignatureKeys;
// Last durable checkpoint before the source melt can become irreversible.
onMeltReady?: (carve: CarveResult, sourceRecoverySecret: string) => void | Promise<void>
}
onMeltReady?: (carve: CarveResult, sourceRecoverySecret: string) => void | Promise<void>;
};
// the claim retry material for a named target: the note at the wallet's
// own secret, unverified until a claim succeeds
@@ -149,34 +149,34 @@ const namedClaimNote = (prepared: PreparedMint, noteSecret: string): NewBearer =
callback: '',
amount: prepared.expectedNoteValueMsat,
verified: false,
}
if (prepared.mintPubkey) note.mintPubkey = prepared.mintPubkey
return note
}
};
if (prepared.mintPubkey) note.mintPubkey = prepared.mintPubkey;
return note;
};
const transferSources = (bearers: Bearer[], targetServer: string, grossMsat: number): Bearer[] => {
const eligible = bearers.filter(
(bearer) => !bearer.spent && bearer.callback !== '' && !bearer.deviceId && noteK1(bearer.url),
)
const candidates = eligible.filter((bearer) => serverOf(bearer.url) !== targetServer)
);
const candidates = eligible.filter((bearer) => serverOf(bearer.url) !== targetServer);
if (eligible.length > 0 && candidates.length === 0) {
throw new Error("That's the mint these notes are already on - pick a different target.")
throw new Error("That's the mint these notes are already on - pick a different target.");
}
const totals = new Map<string, number>()
const totals = new Map<string, number>();
for (const bearer of candidates) {
const server = serverOf(bearer.url)
totals.set(server, (totals.get(server) ?? 0) + bearer.amount)
const server = serverOf(bearer.url);
totals.set(server, (totals.get(server) ?? 0) + bearer.amount);
}
if (![...totals.values()].some((total) => total >= grossMsat)) {
throw new Error('No mint holds enough verified, unspent balance to cover that amount.')
throw new Error('No mint holds enough verified, unspent balance to cover that amount.');
}
return candidates
}
return candidates;
};
export type PendingTransferSourceRecovery =
| {readonly state: 'pending'}
| {readonly state: 'spent'}
| {readonly state: 'returned'; readonly note: NewBearer}
| { readonly state: 'pending' }
| { readonly state: 'spent' }
| { readonly state: 'returned'; readonly note: NewBearer };
export const recoverPendingTransferSource = async (
staged: Bearer,
@@ -185,39 +185,39 @@ export const recoverPendingTransferSource = async (
): Promise<PendingTransferSourceRecovery> => {
// a recovery only ever PROBES the melt outcome and rotates - it never
// replays the melt itself; the forced policy pins signature/retry safety
const mutationOptions = withMutationSafety(options)
const recoverySecret = staged.pendingMint?.sourceRecoverySecret
if (!recoverySecret) throw new Error('The pending transfer source recovery secret is missing.')
const recoveredUrl = withNewK1(source.url, recoverySecret, source.amount)
assertFundOwner(options)
const mutationOptions = withMutationSafety(options);
const recoverySecret = staged.pendingMint?.sourceRecoverySecret;
if (!recoverySecret) throw new Error('The pending transfer source recovery secret is missing.');
const recoveredUrl = withNewK1(source.url, recoverySecret, source.amount);
assertFundOwner(options);
try {
const recovered = await fetchNoteInfo(recoveredUrl, mutationOptions)
const recovered = await fetchNoteInfo(recoveredUrl, mutationOptions);
const note: NewBearer = {
url: withNewK1(source.url, recoverySecret, recovered.maxWithdrawable),
callback: recovered.callback,
amount: recovered.maxWithdrawable,
verified: true,
}
if (source.mintPubkey) note.mintPubkey = source.mintPubkey
return {state: 'returned', note}
};
if (source.mintPubkey) note.mintPubkey = source.mintPubkey;
return { state: 'returned', note };
} catch (error) {
if (error instanceof NoteSpentError) return {state: 'spent'}
if (!(error instanceof NoteUnknownError)) throw error
if (error instanceof NoteSpentError) return { state: 'spent' };
if (!(error instanceof NoteUnknownError)) throw error;
}
assertFundOwner(options)
assertFundOwner(options);
try {
const rotated = await rotateNote(source.callback, requireNoteK1(source.url), {
...mutationOptions,
randomSecret: () => recoverySecret,
})
});
const note: NewBearer = {
url: withNewK1(source.url, recoverySecret, source.amount, rotated.signature),
callback: source.callback,
amount: source.amount,
verified: true,
}
if (source.mintPubkey) note.mintPubkey = source.mintPubkey
return {state: 'returned', note}
};
if (source.mintPubkey) note.mintPubkey = source.mintPubkey;
return { state: 'returned', note };
} catch (error) {
if (
error instanceof PendingNoteError ||
@@ -225,26 +225,35 @@ export const recoverPendingTransferSource = async (
error instanceof AmbiguousMutationError ||
newSecretsOf(error).includes(recoverySecret)
) {
return {state: 'pending'}
return { state: 'pending' };
}
throw error
throw error;
}
}
};
export const transferBetweenMints = async (
bearers: Bearer[],
amountMsat: number,
targetMint: string,
{poll = {}, kit = {}, assertOwner, onCarve, persistOutput, allocateOutputSecrets, mintSignatureKeys, onMeltReady}: TransferOptions,
{
poll = {},
kit = {},
assertOwner,
onCarve,
persistOutput,
allocateOutputSecrets,
mintSignatureKeys,
onMeltReady,
}: TransferOptions,
): Promise<TransferResult> => {
const options: FundOperationOptions = withMutationSafety({
...kit,
...(assertOwner ? {assertOwner} : {}),
...(onCarve ? {onCarve} : {}),
...(mintSignatureKeys ? {mintSignatureKeys} : {}),
})
...(assertOwner ? { assertOwner } : {}),
...(onCarve ? { onCarve } : {}),
...(mintSignatureKeys ? { mintSignatureKeys } : {}),
});
if (!Number.isInteger(amountMsat) || amountMsat <= 0) {
throw new Error('Amount must be a positive whole number of msat.')
throw new Error('Amount must be a positive whole number of msat.');
}
// resolving the target and requesting its invoice touches only the
// TARGET mint - a failure here (unreachable, no minting support, amount
@@ -252,57 +261,57 @@ export const transferBetweenMints = async (
const prepared = await prepareMint(targetMint, amountMsat, {
...options,
persistOutput,
...(allocateOutputSecrets ? {allocateOutputSecrets} : {}),
beforePersist: ({grossMsat, server}) => {
transferSources(bearers, server, grossMsat)
...(allocateOutputSecrets ? { allocateOutputSecrets } : {}),
beforePersist: ({ grossMsat, server }) => {
transferSources(bearers, server, grossMsat);
},
})
const verifyUrl = prepared.verifyUrl
const targetServer = prepared.server
});
const verifyUrl = prepared.verifyUrl;
const targetServer = prepared.server;
// the source must be a DIFFERENT mint - value "moved" within one mint
// goes nowhere (melt pays an invoice; the same mint's invoice just
// re-mints into itself, paying fees for nothing)
const offTarget = transferSources(bearers, targetServer, prepared.grossMsat)
const offTarget = transferSources(bearers, targetServer, prepared.grossMsat);
const quote: TransferQuote = {
requestedMsat: amountMsat,
grossMsat: prepared.grossMsat,
targetMintFeeMsat: prepared.grossMsat - amountMsat,
sourceMeltFeeReserveMsat: 0,
}
};
// carving burns its inputs server-side, so it happens only once the
// target is known good and the invoice exists
const carve = await ensureExactAmount(offTarget, prepared.grossMsat, {
...options,
...(allocateOutputSecrets ? {allocateOutputSecrets} : {}),
})
const sourceServer = serverOf(carve.note.url)
const invoice = prepared.invoice
...(allocateOutputSecrets ? { allocateOutputSecrets } : {}),
});
const sourceServer = serverOf(carve.note.url);
const invoice = prepared.invoice;
const claimMaterial: TransferClaimMaterial = {
invoice,
withdrawLink: prepared.withdrawLink,
expectedNoteValueMsat: prepared.expectedNoteValueMsat,
noteSecret: prepared.noteSecret,
note: namedClaimNote(prepared, prepared.noteSecret),
}
};
// from here on the carve's fresh secrets exist only in this result - the
// flow never throws again; every outcome carries them
const base = {carve, quote, invoice, verifyUrl, sourceServer, targetServer}
const k1 = requireNoteK1(carve.note.url)
if (!onMeltReady) throw new TransferMeltCheckpointRequiredError()
const base = { carve, quote, invoice, verifyUrl, sourceServer, targetServer };
const k1 = requireNoteK1(carve.note.url);
if (!onMeltReady) throw new TransferMeltCheckpointRequiredError();
const [sourceRecoverySecret] = await requireOutputSecrets(
allocateOutputSecrets,
serverOf(carve.note.url),
1,
)
if (carve.consumed.length === 0) assertFundOwner(options)
await onMeltReady(carve, sourceRecoverySecret)
assertFundOwner(options)
);
if (carve.consumed.length === 0) assertFundOwner(options);
await onMeltReady(carve, sourceRecoverySecret);
assertFundOwner(options);
try {
await meltNote(carve.note.callback, k1, invoice, options)
await meltNote(carve.note.callback, k1, invoice, options);
} catch (error) {
if (!(error instanceof Error)) throw error
if (!(error instanceof Error)) throw error;
if (error instanceof NoteSpentError) {
return {...base, outcome: 'note-already-spent'}
return { ...base, outcome: 'note-already-spent' };
}
// anything else - a clean refusal, a dropped response, a lost answer -
// is resolved below: the target invoice settles only if this melt's
@@ -310,15 +319,15 @@ export const transferBetweenMints = async (
}
try {
try {
const claimed = await claimFromSecret(prepared, poll, options)
return {...base, outcome: 'settled', mintedAtTarget: claimed}
const claimed = await claimFromSecret(prepared, poll, options);
return { ...base, outcome: 'settled', mintedAtTarget: claimed };
} catch (error) {
if (error instanceof MintedNoteSpentError) {
return {...base, outcome: 'settled-claim-failed', claimMaterial}
return { ...base, outcome: 'settled-claim-failed', claimMaterial };
}
throw new Error('The target note could not be confirmed at its staged secret.', {
cause: error,
})
});
}
} catch {
// the target invoice never settled within budget - the source note is
@@ -331,7 +340,7 @@ export const transferBetweenMints = async (
const rotated = await rotateNote(carve.note.callback, k1, {
...options,
randomSecret: () => sourceRecoverySecret,
})
});
// the rotate succeeded: the melt provably never landed, and the
// funds are back - re-secured, since the melt attempt put k1 on the
// wire. Reported separately from `carve` (see rotatedNote): the
@@ -345,12 +354,12 @@ export const transferBetweenMints = async (
callback: carve.note.callback,
amount: carve.note.amount,
verified: true,
...(carve.note.mintPubkey ? {mintPubkey: carve.note.mintPubkey} : {}),
...(carve.note.mintPubkey ? { mintPubkey: carve.note.mintPubkey } : {}),
},
}
};
} catch (err) {
if (err instanceof PendingNoteError || err instanceof NoteSpentError) {
return {...base, outcome: 'unknown-still-pending', claimMaterial}
return { ...base, outcome: 'unknown-still-pending', claimMaterial };
}
if (err instanceof AmbiguousMutationError) {
// The rotate's answer was lost. Keep the transfer journal until
@@ -360,11 +369,11 @@ export const transferBetweenMints = async (
callback: carve.note.callback,
amount: carve.note.amount,
verified: false,
}
if (carve.note.mintPubkey) rescuedNote.mintPubkey = carve.note.mintPubkey
return {...base, outcome: 'unknown-still-pending', claimMaterial, rescuedNote}
};
if (carve.note.mintPubkey) rescuedNote.mintPubkey = carve.note.mintPubkey;
return { ...base, outcome: 'unknown-still-pending', claimMaterial, rescuedNote };
}
return {...base, outcome: 'unknown-still-pending', claimMaterial}
return { ...base, outcome: 'unknown-still-pending', claimMaterial };
}
}
}
};
src/lnurlcash/passkeyOwnership.ts
+8 -8
View File
@@ -4,15 +4,15 @@
// The proven marker lives on the v2 wallet-material record; adoption itself
// additionally requires the slot to commit to the exact saved material.
import {linkingPubKeyHex} from './keys'
import {adoptLegacyPasskeySlots, PASSKEY_SLOTS_STORAGE_KEY} from './storage/passkeySlots'
import {withStorageLock} from './storageLock'
import {savedWalletMaterialOwnerId} from './walletMaterialStorage'
import { linkingPubKeyHex } from './keys';
import { adoptLegacyPasskeySlots, PASSKEY_SLOTS_STORAGE_KEY } from './storage/passkeySlots';
import { withStorageLock } from './storageLock';
import { savedWalletMaterialOwnerId } from './walletMaterialStorage';
export const migrateLegacyPasskeySlots = async (linkingKey: Uint8Array): Promise<number> => {
const ownerId = savedWalletMaterialOwnerId()
const ownerId = savedWalletMaterialOwnerId();
if (ownerId === null || linkingPubKeyHex(linkingKey) !== ownerId) {
throw new Error('Legacy passkey migration requires a proven owner.')
throw new Error('Legacy passkey migration requires a proven owner.');
}
return withStorageLock(PASSKEY_SLOTS_STORAGE_KEY, () => adoptLegacyPasskeySlots(ownerId))
}
return withStorageLock(PASSKEY_SLOTS_STORAGE_KEY, () => adoptLegacyPasskeySlots(ownerId));
};
src/lnurlcash/passkeyRewrap.ts
+31 -31
View File
@@ -2,65 +2,65 @@
// is therefore both authority for the old wrap and input for its fresh wrap;
// one wrong credential aborts the complete in-memory batch before persistence.
import type {WalletMaterialV2} from './storage/storedSecret'
import {serializeWalletMaterial, walletMaterialHash} from './storage/storedSecret'
import type {PasskeySlot} from './storage/passkeySlots'
import type { WalletMaterialV2 } from './storage/storedSecret';
import { serializeWalletMaterial, walletMaterialHash } from './storage/storedSecret';
import type { PasskeySlot } from './storage/passkeySlots';
import {
PASSKEY_SLOTS_STORAGE_KEY,
passkeySlotsEqual,
readPasskeySlots,
requireCurrentPasskeyMaterialOwner,
writePasskeySlots,
} from './storage/passkeySlots'
import {withStorageLock} from './storageLock'
import {unwrapWalletMaterialWithPrf, wrapWalletMaterialWithPrf} from './passkeyWrap'
} from './storage/passkeySlots';
import { withStorageLock } from './storageLock';
import { unwrapWalletMaterialWithPrf, wrapWalletMaterialWithPrf } from './passkeyWrap';
type ProvenSlot = {
readonly slot: PasskeySlot
readonly prfOutput: Uint8Array
}
readonly slot: PasskeySlot;
readonly prfOutput: Uint8Array;
};
export const rewrapAllSlots = async (
material: WalletMaterialV2,
prfOutputs: ReadonlyMap<string, Uint8Array>,
): Promise<void> => {
const ownerId = requireCurrentPasskeyMaterialOwner(material)
const materialHash = walletMaterialHash(material)
const serialized = serializeWalletMaterial(material)
const ownerId = requireCurrentPasskeyMaterialOwner(material);
const materialHash = walletMaterialHash(material);
const serialized = serializeWalletMaterial(material);
await withStorageLock(PASSKEY_SLOTS_STORAGE_KEY, async () => {
const provenSlots: ProvenSlot[] = readPasskeySlots().map((slot) => {
const prfOutput = prfOutputs.get(slot.credentialId)
const prfOutput = prfOutputs.get(slot.credentialId);
if (!prfOutput) {
throw new Error('Missing old PRF output for a passkey slot - refusing a partial re-wrap.')
throw new Error('Missing old PRF output for a passkey slot - refusing a partial re-wrap.');
}
return {slot, prfOutput}
})
for (const {slot, prfOutput} of provenSlots) {
return { slot, prfOutput };
});
for (const { slot, prfOutput } of provenSlots) {
if (slot.materialHash !== materialHash) {
throw new Error('Passkey slot does not match the saved wallet material.')
throw new Error('Passkey slot does not match the saved wallet material.');
}
const current = await unwrapWalletMaterialWithPrf(prfOutput, slot)
const current = await unwrapWalletMaterialWithPrf(prfOutput, slot);
if (serializeWalletMaterial(current) !== serialized) {
throw new Error('Passkey slot contains different wallet material.')
throw new Error('Passkey slot contains different wallet material.');
}
}
const rewrapped: PasskeySlot[] = []
for (const {slot, prfOutput} of provenSlots) {
rewrapped.push({...slot, ...(await wrapWalletMaterialWithPrf(prfOutput, material))})
const rewrapped: PasskeySlot[] = [];
for (const { slot, prfOutput } of provenSlots) {
rewrapped.push({ ...slot, ...(await wrapWalletMaterialWithPrf(prfOutput, material)) });
}
if (requireCurrentPasskeyMaterialOwner(material) !== ownerId) {
throw new Error('Saved wallet material changed during passkey re-wrap.')
throw new Error('Saved wallet material changed during passkey re-wrap.');
}
const currentSlots = readPasskeySlots()
const currentSlots = readPasskeySlots();
if (
currentSlots.length !== provenSlots.length ||
currentSlots.some((current, index) => {
const original = provenSlots[index]?.slot
return original === undefined || !passkeySlotsEqual(original, current)
const original = provenSlots[index]?.slot;
return original === undefined || !passkeySlotsEqual(original, current);
})
) {
throw new Error('Passkey slots changed during re-wrap.')
throw new Error('Passkey slots changed during re-wrap.');
}
writePasskeySlots(ownerId, rewrapped)
})
}
writePasskeySlots(ownerId, rewrapped);
});
};
src/lnurlcash/passkeyWrap.ts
+30 -30
View File
@@ -8,20 +8,20 @@
// info string domain-separates these keys from any other key ever derived
// from the same PRF output.
import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
import type {PasskeyWrap} from './storage/passkeySlots'
import {parseWalletMaterial, serializeWalletMaterial} from './storage/storedSecret'
import type {WalletMaterialV2} from './storage/storedSecret'
import {serializedWalletMaterialHash, walletMaterialHash} from './storage/walletMaterial'
import type { PasskeyWrap } from './storage/passkeySlots';
import { parseWalletMaterial, serializeWalletMaterial } from './storage/storedSecret';
import type { WalletMaterialV2 } from './storage/storedSecret';
import { serializedWalletMaterialHash, walletMaterialHash } from './storage/walletMaterial';
const WRAP_KEY_HKDF_INFO = 'sattle-passkey-wrap-v2'
const WRAP_KEY_HKDF_INFO = 'sattle-passkey-wrap-v2';
export class InvalidPasskeyMaterialError extends Error {
override readonly name = 'InvalidPasskeyMaterialError'
override readonly name = 'InvalidPasskeyMaterialError';
constructor() {
super('Passkey payload is not canonical v2 wallet material.')
super('Passkey payload is not canonical v2 wallet material.');
}
}
@@ -31,7 +31,7 @@ export const derivePasskeyWrapKey = async (
): Promise<CryptoKey> => {
const baseKey = await crypto.subtle.importKey('raw', new Uint8Array(prfOutput), 'HKDF', false, [
'deriveKey',
])
]);
return crypto.subtle.deriveKey(
// the copies pin the TS type to Uint8Array<ArrayBuffer> - hexToBytes
// returns Uint8Array<ArrayBufferLike>, which BufferSource rejects
@@ -42,31 +42,31 @@ export const derivePasskeyWrapKey = async (
info: new Uint8Array(utf8ToBytes(WRAP_KEY_HKDF_INFO)),
},
baseKey,
{name: 'AES-GCM', length: 256},
{ name: 'AES-GCM', length: 256 },
false,
['encrypt', 'decrypt'],
)
}
);
};
export const wrapWalletMaterialWithPrf = async (
prfOutput: Uint8Array,
material: WalletMaterialV2,
): Promise<PasskeyWrap> => {
const hkdfSalt = crypto.getRandomValues(new Uint8Array(16))
const iv = crypto.getRandomValues(new Uint8Array(12))
const wrapKey = await derivePasskeyWrapKey(prfOutput, hkdfSalt)
const serialized = serializeWalletMaterial(material)
if (parseWalletMaterial(serialized) === null) throw new InvalidPasskeyMaterialError()
const hkdfSalt = crypto.getRandomValues(new Uint8Array(16));
const iv = crypto.getRandomValues(new Uint8Array(12));
const wrapKey = await derivePasskeyWrapKey(prfOutput, hkdfSalt);
const serialized = serializeWalletMaterial(material);
if (parseWalletMaterial(serialized) === null) throw new InvalidPasskeyMaterialError();
const ciphertext = new Uint8Array(
await crypto.subtle.encrypt({name: 'AES-GCM', iv}, wrapKey, utf8ToBytes(serialized)),
)
await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, wrapKey, utf8ToBytes(serialized)),
);
return {
hkdfSalt: bytesToHex(hkdfSalt),
iv: bytesToHex(iv),
materialHash: walletMaterialHash(material),
wrappedMaterial: bytesToHex(ciphertext),
}
}
};
};
// rejects (WebCrypto's own auth-tag check) if the PRF output is wrong -
// i.e. a different passkey than the one that created the slot
@@ -74,17 +74,17 @@ export const unwrapWalletMaterialWithPrf = async (
prfOutput: Uint8Array,
wrap: PasskeyWrap,
): Promise<WalletMaterialV2> => {
const wrapKey = await derivePasskeyWrapKey(prfOutput, hexToBytes(wrap.hkdfSalt))
const wrapKey = await derivePasskeyWrapKey(prfOutput, hexToBytes(wrap.hkdfSalt));
const plaintext = await crypto.subtle.decrypt(
{name: 'AES-GCM', iv: new Uint8Array(hexToBytes(wrap.iv))},
{ name: 'AES-GCM', iv: new Uint8Array(hexToBytes(wrap.iv)) },
wrapKey,
new Uint8Array(hexToBytes(wrap.wrappedMaterial)),
)
const serialized = new TextDecoder().decode(plaintext)
);
const serialized = new TextDecoder().decode(plaintext);
if (serializedWalletMaterialHash(serialized) !== wrap.materialHash) {
throw new InvalidPasskeyMaterialError()
throw new InvalidPasskeyMaterialError();
}
const material = parseWalletMaterial(serialized)
if (material === null) throw new InvalidPasskeyMaterialError()
return material
}
const material = parseWalletMaterial(serialized);
if (material === null) throw new InvalidPasskeyMaterialError();
return material;
};
src/lnurlcash/passkeys.commitment.cases.ts
+75 -70
View File
@@ -1,129 +1,134 @@
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import {beforeEach, describe, expect, it} from 'vitest'
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import { beforeEach, describe, expect, it } from 'vitest';
import {deriveWalletMaterial, saveWalletMaterial} from './keys'
import { deriveWalletMaterial, saveWalletMaterial } from './keys';
import {
getPasskeyPrfOutput,
registerPasskey,
rewrapAllSlots,
unlockWalletMaterialWithPasskey,
} from './passkeys'
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import {stubLocalStorage} from './test-utils'
} from './passkeys';
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import { stubLocalStorage } from './test-utils';
const MNEMONIC = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
const OTHER_MNEMONIC = 'legal winner thank year wave sausage worth useful legal winner thank yellow'
const MATERIAL = {...deriveWalletMaterial(MNEMONIC), linkingKeyHex: '07'.repeat(32)}
const OTHER_MATERIAL = deriveWalletMaterial(OTHER_MNEMONIC)
const ALTERED_ROOT = {...MATERIAL, cashRootHex: OTHER_MATERIAL.cashRootHex}
const SLOT_STORAGE_KEY = 'sattle_passkey_slots'
const MNEMONIC =
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
const OTHER_MNEMONIC =
'legal winner thank year wave sausage worth useful legal winner thank yellow';
const MATERIAL = { ...deriveWalletMaterial(MNEMONIC), linkingKeyHex: '07'.repeat(32) };
const OTHER_MATERIAL = deriveWalletMaterial(OTHER_MNEMONIC);
const ALTERED_ROOT = { ...MATERIAL, cashRootHex: OTHER_MATERIAL.cashRootHex };
const SLOT_STORAGE_KEY = 'sattle_passkey_slots';
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
class FakeAuthenticator implements PasskeyCredentials {
private readonly credentialId = new Uint8Array(16).fill(12)
private readonly secret = new Uint8Array(32).fill(13)
onCreate?: () => Promise<void>
onGet?: () => Promise<void>
private readonly credentialId = new Uint8Array(16).fill(12);
private readonly secret = new Uint8Array(32).fill(13);
onCreate?: () => Promise<void>;
onGet?: () => Promise<void>;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential> => {
await this.onCreate?.()
return this.credential(options?.publicKey?.extensions?.prf?.eval?.first)
}
await this.onCreate?.();
return this.credential(options?.publicKey?.extensions?.prf?.eval?.first);
};
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
await this.onGet?.()
const allowed = options?.publicKey?.allowCredentials ?? []
await this.onGet?.();
const allowed = options?.publicKey?.allowCredentials ?? [];
return allowed.some(
(descriptor) => bytesToHex(toBytes(descriptor.id)) === bytesToHex(this.credentialId),
)
? this.credential(options?.publicKey?.extensions?.prf?.eval?.first)
: null
}
: null;
};
private credential = (salt: BufferSource | undefined): CeremonyCredential => ({
type: 'public-key',
rawId: this.credentialId,
getClientExtensionResults: () => ({
prf: salt
? {enabled: true, results: {first: new Uint8Array(hmac(sha256, this.secret, toBytes(salt)))}}
? {
enabled: true,
results: { first: new Uint8Array(hmac(sha256, this.secret, toBytes(salt))) },
}
: {},
}),
})
});
}
const rawSlots = (): string => localStorage.getItem(SLOT_STORAGE_KEY) ?? ''
const rawSlots = (): string => localStorage.getItem(SLOT_STORAGE_KEY) ?? '';
beforeEach(async () => {
stubLocalStorage()
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveWalletMaterial(MATERIAL);
});
describe('exact wallet material passkey commitment', () => {
it('rejects a wrong old PRF before changing any slot bytes', async () => {
const authenticator = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: authenticator})
const before = rawSlots()
const wrongPrf = new Uint8Array(32).fill(99)
const authenticator = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: authenticator });
const before = rawSlots();
const wrongPrf = new Uint8Array(32).fill(99);
await expect(
rewrapAllSlots(MATERIAL, new Map([[slot.credentialId, wrongPrf]])),
).rejects.toThrow()
expect(rawSlots()).toBe(before)
})
).rejects.toThrow();
expect(rawSlots()).toBe(before);
});
it('rejects same-owner altered-root registration against encrypted saved material', async () => {
const authenticator = new FakeAuthenticator()
await saveWalletMaterial(MATERIAL, 'password')
const authenticator = new FakeAuthenticator();
await saveWalletMaterial(MATERIAL, 'password');
await expect(registerPasskey(ALTERED_ROOT, {credentials: authenticator})).rejects.toThrow(
await expect(registerPasskey(ALTERED_ROOT, { credentials: authenticator })).rejects.toThrow(
'saved wallet material',
)
expect(rawSlots()).toBe('')
})
);
expect(rawSlots()).toBe('');
});
it('rejects registration when same-owner saved material changes during the ceremony', async () => {
const authenticator = new FakeAuthenticator()
authenticator.onCreate = () => saveWalletMaterial(ALTERED_ROOT)
const authenticator = new FakeAuthenticator();
authenticator.onCreate = () => saveWalletMaterial(ALTERED_ROOT);
await expect(registerPasskey(MATERIAL, {credentials: authenticator})).rejects.toThrow(
await expect(registerPasskey(MATERIAL, { credentials: authenticator })).rejects.toThrow(
'saved wallet material',
)
expect(rawSlots()).toBe('')
})
);
expect(rawSlots()).toBe('');
});
it('rejects unlock after same-owner saved material was replaced', async () => {
const authenticator = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: authenticator})
await saveWalletMaterial(ALTERED_ROOT, 'password')
const authenticator = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: authenticator });
await saveWalletMaterial(ALTERED_ROOT, 'password');
await expect(unlockWalletMaterialWithPasskey({credentials: authenticator})).rejects.toThrow()
})
await expect(unlockWalletMaterialWithPasskey({ credentials: authenticator })).rejects.toThrow();
});
it('rejects same-owner saved-material replacement during the unlock ceremony', async () => {
const authenticator = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: authenticator})
authenticator.onGet = () => saveWalletMaterial(ALTERED_ROOT)
const authenticator = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: authenticator });
authenticator.onGet = () => saveWalletMaterial(ALTERED_ROOT);
await expect(unlockWalletMaterialWithPasskey({credentials: authenticator})).rejects.toThrow(
await expect(unlockWalletMaterialWithPasskey({ credentials: authenticator })).rejects.toThrow(
'changed',
)
})
);
});
it('keeps a valid slot usable when its old PRF proves the existing wrap', async () => {
const authenticator = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: authenticator})
const oldPrf = await getPasskeyPrfOutput(slot.credentialId, {credentials: authenticator})
const authenticator = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: authenticator });
const oldPrf = await getPasskeyPrfOutput(slot.credentialId, { credentials: authenticator });
await rewrapAllSlots(MATERIAL, new Map([[slot.credentialId, oldPrf]]))
await rewrapAllSlots(MATERIAL, new Map([[slot.credentialId, oldPrf]]));
await expect(unlockWalletMaterialWithPasskey({credentials: authenticator})).resolves.toEqual(
await expect(unlockWalletMaterialWithPasskey({ credentials: authenticator })).resolves.toEqual(
MATERIAL,
)
})
})
);
});
});
src/lnurlcash/passkeys.crypto.cases.ts
+80 -80
View File
@@ -4,12 +4,12 @@
// unguessable without the authenticator. Everything except a real
// authenticator's touch is covered here.
import {beforeEach, describe, expect, it} from 'vitest'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -22,7 +22,7 @@ import {
rewrapAllSlots,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
} from './passkeys';
import {
decryptRecord,
decryptSavedLinkingKey,
@@ -34,43 +34,43 @@ import {
savedKeyOwnerId,
saveLinkingKey,
saveWalletMaterial,
} from './keys'
import {parseJsonObject, parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, parseJsonObjectArray, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// Fake platform authenticator: holds credentials (id -> secret), evaluates
// PRF as HMAC-SHA256(secret, salt). Flags emulate the authenticator quirks
// found in the wild: PRF unsupported, results only on get, results never.
class FakeAuthenticator implements PasskeyCredentials {
// id typed Uint8Array<ArrayBuffer>: rawId must satisfy BufferSource
private held = new Map<string, {id: Uint8Array<ArrayBuffer>; secret: Uint8Array}>()
supportsPrf = true
prfResultsOnCreate = true
prfResultsOnGet = true
createCalls = 0
getCalls = 0
private held = new Map<string, { id: Uint8Array<ArrayBuffer>; secret: Uint8Array }>();
supportsPrf = true;
prfResultsOnCreate = true;
prfResultsOnGet = true;
createCalls = 0;
getCalls = 0;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
this.createCalls += 1
const salt = options?.publicKey?.extensions?.prf?.eval?.first
const id = crypto.getRandomValues(new Uint8Array(16))
const secret = crypto.getRandomValues(new Uint8Array(32))
this.held.set(bytesToHex(id), {id, secret})
this.createCalls += 1;
const salt = options?.publicKey?.extensions?.prf?.eval?.first;
const id = crypto.getRandomValues(new Uint8Array(16));
const secret = crypto.getRandomValues(new Uint8Array(32));
this.held.set(bytesToHex(id), { id, secret });
return {
type: 'public-key',
rawId: id,
@@ -79,103 +79,103 @@ class FakeAuthenticator implements PasskeyCredentials {
this.supportsPrf && salt
? {
enabled: true,
...(this.prfResultsOnCreate ? {results: {first: this.prf(secret, salt)}} : {}),
...(this.prfResultsOnCreate ? { results: { first: this.prf(secret, salt) } } : {}),
}
: {},
}),
}
}
};
};
// answers with the first allowed credential it holds, like a real
// authenticator picking among allowCredentials; null when it holds none
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
this.getCalls += 1
const pk = options?.publicKey
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)))
const match = allowed.find((hex) => this.held.has(hex))
const held = match ? this.held.get(match) : undefined
if (!held) return null
const salt = pk?.extensions?.prf?.eval?.first
this.getCalls += 1;
const pk = options?.publicKey;
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)));
const match = allowed.find((hex) => this.held.has(hex));
const held = match ? this.held.get(match) : undefined;
if (!held) return null;
const salt = pk?.extensions?.prf?.eval?.first;
return {
type: 'public-key',
rawId: held.id,
getClientExtensionResults: () => ({
prf:
salt && this.prfResultsOnGet
? {enabled: true, results: {first: this.prf(held.secret, salt)}}
? { enabled: true, results: { first: this.prf(held.secret, salt) } }
: {},
}),
}
}
};
};
// simulates the passkey's secret changing underneath a slot (credential
// re-created on the authenticator while the slot stayed behind)
rotateSecret = (credentialId: string): void => {
const held = this.held.get(credentialId)
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32))
}
const held = this.held.get(credentialId);
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32));
};
private prf = (secret: Uint8Array, salt: BufferSource): Uint8Array<ArrayBuffer> => {
// set into a fresh array: hmac returns Uint8Array<ArrayBufferLike>,
// which BufferSource rejects
const out = new Uint8Array(32)
out.set(hmac(sha256, secret, toBytes(salt)))
return out
}
const out = new Uint8Array(32);
out.set(hmac(sha256, secret, toBytes(salt)));
return out;
};
}
const readRawSlots = (): Array<Record<string, unknown>> =>
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
const writeRawSlots = (slots: Array<Record<string, unknown>>): void => {
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots))
}
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots));
};
const removeSavedOwnerMarker = (): void => {
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}')
delete stored.ownerId
delete stored.version
localStorage.setItem('sattle_linking_key', JSON.stringify(stored))
}
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}');
delete stored.ownerId;
delete stored.version;
localStorage.setItem('sattle_linking_key', JSON.stringify(stored));
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
await saveWalletMaterial(MATERIAL);
});
describe('pure wrap crypto', () => {
it('round-trips a linking key through a PRF-derived wrap', async () => {
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL)
const unwrapped = await unwrapWalletMaterialWithPrf(PRF_OUTPUT, wrap)
expect(unwrapped).toEqual(MATERIAL)
})
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL);
const unwrapped = await unwrapWalletMaterialWithPrf(PRF_OUTPUT, wrap);
expect(unwrapped).toEqual(MATERIAL);
});
it('rejects unwrap with a different PRF output', async () => {
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL)
await expect(unwrapWalletMaterialWithPrf(OTHER_PRF_OUTPUT, wrap)).rejects.toThrow()
})
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL);
await expect(unwrapWalletMaterialWithPrf(OTHER_PRF_OUTPUT, wrap)).rejects.toThrow();
});
it('rejects unwrap with a tampered HKDF salt', async () => {
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL)
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL);
await expect(
unwrapWalletMaterialWithPrf(PRF_OUTPUT, {...wrap, hkdfSalt: 'ab'.repeat(16)}),
).rejects.toThrow()
})
unwrapWalletMaterialWithPrf(PRF_OUTPUT, { ...wrap, hkdfSalt: 'ab'.repeat(16) }),
).rejects.toThrow();
});
it('rejects unwrap with a tampered ciphertext', async () => {
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL)
const flipped = `${wrap.wrappedMaterial.slice(0, -2)}${wrap.wrappedMaterial.endsWith('00') ? '01' : '00'}`
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL);
const flipped = `${wrap.wrappedMaterial.slice(0, -2)}${wrap.wrappedMaterial.endsWith('00') ? '01' : '00'}`;
await expect(
unwrapWalletMaterialWithPrf(PRF_OUTPUT, {...wrap, wrappedMaterial: flipped}),
).rejects.toThrow()
})
unwrapWalletMaterialWithPrf(PRF_OUTPUT, { ...wrap, wrappedMaterial: flipped }),
).rejects.toThrow();
});
it('derives wrap keys deterministically from the same PRF output and salt', async () => {
const salt = new Uint8Array(16).fill(1)
const a = await derivePasskeyWrapKey(PRF_OUTPUT, salt)
const b = await derivePasskeyWrapKey(PRF_OUTPUT, salt)
const record = await encryptRecord(a, {v: 1})
await expect(decryptRecord(b, record)).resolves.toEqual({v: 1})
})
})
const salt = new Uint8Array(16).fill(1);
const a = await derivePasskeyWrapKey(PRF_OUTPUT, salt);
const b = await derivePasskeyWrapKey(PRF_OUTPUT, salt);
const record = await encryptRecord(a, { v: 1 });
await expect(decryptRecord(b, record)).resolves.toEqual({ v: 1 });
});
});
src/lnurlcash/passkeys.material.cases.ts
+160 -155
View File
@@ -2,15 +2,12 @@
// material in assertions or diagnostics. The fake authenticator models only
// WebAuthn credential selection and deterministic PRF evaluation.
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex, utf8ToBytes} from '@noble/hashes/utils.js'
import {beforeEach, describe, expect, it} from 'vitest'
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js';
import { beforeEach, describe, expect, it } from 'vitest';
import {
deriveWalletMaterial,
saveWalletMaterial,
} from './keys'
import { deriveWalletMaterial, saveWalletMaterial } from './keys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -20,252 +17,260 @@ import {
unlockWalletMaterialWithPasskey,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
import type {CeremonyCredential, PasskeyCredentials, PasskeyWrap} from './passkeys'
import {stubLocalStorage} from './test-utils'
} from './passkeys';
import type { CeremonyCredential, PasskeyCredentials, PasskeyWrap } from './passkeys';
import { stubLocalStorage } from './test-utils';
const MNEMONIC = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
const OTHER_MNEMONIC = 'legal winner thank year wave sausage worth useful legal winner thank yellow'
const MATERIAL = {...deriveWalletMaterial(MNEMONIC), linkingKeyHex: '07'.repeat(32)}
const OTHER_MATERIAL = deriveWalletMaterial(OTHER_MNEMONIC)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const SLOT_STORAGE_KEY = 'sattle_passkey_slots'
const MNEMONIC =
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
const OTHER_MNEMONIC =
'legal winner thank year wave sausage worth useful legal winner thank yellow';
const MATERIAL = { ...deriveWalletMaterial(MNEMONIC), linkingKeyHex: '07'.repeat(32) };
const OTHER_MATERIAL = deriveWalletMaterial(OTHER_MNEMONIC);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const SLOT_STORAGE_KEY = 'sattle_passkey_slots';
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
class FakeAuthenticator implements PasskeyCredentials {
private readonly credentialId = new Uint8Array(16).fill(5)
private secret = new Uint8Array(32).fill(6)
onGet?: () => Promise<void>
cancelCreate = false
private readonly credentialId = new Uint8Array(16).fill(5);
private secret = new Uint8Array(32).fill(6);
onGet?: () => Promise<void>;
cancelCreate = false;
rotateSecret = (): void => {
this.secret = new Uint8Array(32).fill(7)
}
this.secret = new Uint8Array(32).fill(7);
};
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
if (this.cancelCreate) return null
return this.credential(options?.publicKey?.extensions?.prf?.eval?.first)
}
if (this.cancelCreate) return null;
return this.credential(options?.publicKey?.extensions?.prf?.eval?.first);
};
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
await this.onGet?.()
const allowed = options?.publicKey?.allowCredentials ?? []
await this.onGet?.();
const allowed = options?.publicKey?.allowCredentials ?? [];
const selected = allowed.some(
(descriptor) => bytesToHex(toBytes(descriptor.id)) === bytesToHex(this.credentialId),
)
return selected
? this.credential(options?.publicKey?.extensions?.prf?.eval?.first)
: null
}
);
return selected ? this.credential(options?.publicKey?.extensions?.prf?.eval?.first) : null;
};
private credential = (salt: BufferSource | undefined): CeremonyCredential => ({
type: 'public-key',
rawId: this.credentialId,
getClientExtensionResults: () => ({
prf: salt
? {enabled: true, results: {first: new Uint8Array(hmac(sha256, this.secret, toBytes(salt)))}}
? {
enabled: true,
results: { first: new Uint8Array(hmac(sha256, this.secret, toBytes(salt))) },
}
: {},
}),
})
});
}
const rawSlots = (): string => localStorage.getItem(SLOT_STORAGE_KEY) ?? ''
const rawSlots = (): string => localStorage.getItem(SLOT_STORAGE_KEY) ?? '';
const alterLastByte = (hex: string): string =>
`${hex.slice(0, -2)}${hex.endsWith('00') ? '01' : '00'}`
`${hex.slice(0, -2)}${hex.endsWith('00') ? '01' : '00'}`;
const encryptPayload = async (
prfOutput: Uint8Array,
payload: string,
materialHash: string,
): Promise<PasskeyWrap> => {
const hkdfSalt = new Uint8Array(16).fill(8)
const iv = new Uint8Array(12).fill(9)
const wrapKey = await derivePasskeyWrapKey(prfOutput, hkdfSalt)
const hkdfSalt = new Uint8Array(16).fill(8);
const iv = new Uint8Array(12).fill(9);
const wrapKey = await derivePasskeyWrapKey(prfOutput, hkdfSalt);
const ciphertext = await crypto.subtle.encrypt(
{name: 'AES-GCM', iv},
{ name: 'AES-GCM', iv },
wrapKey,
utf8ToBytes(payload),
)
);
return {
hkdfSalt: bytesToHex(hkdfSalt),
iv: bytesToHex(iv),
materialHash,
wrappedMaterial: bytesToHex(new Uint8Array(ciphertext)),
}
}
};
};
beforeEach(async () => {
stubLocalStorage()
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveWalletMaterial(MATERIAL);
});
describe('v2 passkey material', () => {
it('round-trips canonical material bytes through the PRF wrap', async () => {
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL)
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL);
await expect(unwrapWalletMaterialWithPrf(PRF_OUTPUT, wrap)).resolves.toEqual(MATERIAL)
})
await expect(unwrapWalletMaterialWithPrf(PRF_OUTPUT, wrap)).resolves.toEqual(MATERIAL);
});
it('rejects wrong PRF and altered ciphertext without changing the wrap', async () => {
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL)
const before = JSON.stringify(wrap)
const wrap = await wrapWalletMaterialWithPrf(PRF_OUTPUT, MATERIAL);
const before = JSON.stringify(wrap);
const altered = {
...wrap,
wrappedMaterial: alterLastByte(wrap.wrappedMaterial),
}
};
await expect(unwrapWalletMaterialWithPrf(OTHER_PRF_OUTPUT, wrap)).rejects.toThrow()
await expect(unwrapWalletMaterialWithPrf(PRF_OUTPUT, altered)).rejects.toThrow()
expect(JSON.stringify(wrap)).toBe(before)
})
await expect(unwrapWalletMaterialWithPrf(OTHER_PRF_OUTPUT, wrap)).rejects.toThrow();
await expect(unwrapWalletMaterialWithPrf(PRF_OUTPUT, altered)).rejects.toThrow();
expect(JSON.stringify(wrap)).toBe(before);
});
it.each([
['legacy key-only payload', MATERIAL.linkingKeyHex],
[
'malformed root',
JSON.stringify({...MATERIAL, cashRootHex: `${MATERIAL.cashRootHex.slice(0, -2)}00`}),
JSON.stringify({ ...MATERIAL, cashRootHex: `${MATERIAL.cashRootHex.slice(0, -2)}00` }),
],
])('rejects authenticated %s without changing slots or activation', async (_name, payload) => {
const authenticator = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: authenticator})
const prfOutput = await getPasskeyPrfOutput(slot.credentialId, {credentials: authenticator})
const materialHash = bytesToHex(sha256(utf8ToBytes(payload)))
const wrap = await encryptPayload(prfOutput, payload, materialHash)
localStorage.setItem(SLOT_STORAGE_KEY, JSON.stringify([{...slot, ...wrap}]))
const before = rawSlots()
let activated = false
const authenticator = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: authenticator });
const prfOutput = await getPasskeyPrfOutput(slot.credentialId, { credentials: authenticator });
const materialHash = bytesToHex(sha256(utf8ToBytes(payload)));
const wrap = await encryptPayload(prfOutput, payload, materialHash);
localStorage.setItem(SLOT_STORAGE_KEY, JSON.stringify([{ ...slot, ...wrap }]));
const before = rawSlots();
let activated = false;
await expect(
unlockWalletMaterialWithPasskey({credentials: authenticator}).then(() => {
activated = true
unlockWalletMaterialWithPasskey({ credentials: authenticator }).then(() => {
activated = true;
}),
).rejects.toThrow()
expect(activated).toBe(false)
expect(rawSlots()).toBe(before)
})
).rejects.toThrow();
expect(activated).toBe(false);
expect(rawSlots()).toBe(before);
});
it('rejects a wrong runtime PRF without changing slots or activation', async () => {
const authenticator = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: authenticator})
const before = rawSlots()
let activated = false
authenticator.rotateSecret()
const authenticator = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: authenticator });
const before = rawSlots();
let activated = false;
authenticator.rotateSecret();
await expect(
unlockWalletMaterialWithPasskey({credentials: authenticator}).then(() => {
activated = true
unlockWalletMaterialWithPasskey({ credentials: authenticator }).then(() => {
activated = true;
}),
).rejects.toThrow()
expect(activated).toBe(false)
expect(rawSlots()).toBe(before)
})
).rejects.toThrow();
expect(activated).toBe(false);
expect(rawSlots()).toBe(before);
});
it('rejects altered stored ciphertext without rewriting it or activating', async () => {
const authenticator = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: authenticator})
const authenticator = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: authenticator });
const altered = {
...slot,
wrappedMaterial: alterLastByte(slot.wrappedMaterial),
}
localStorage.setItem(SLOT_STORAGE_KEY, JSON.stringify([altered]))
const before = rawSlots()
let activated = false
};
localStorage.setItem(SLOT_STORAGE_KEY, JSON.stringify([altered]));
const before = rawSlots();
let activated = false;
await expect(
unlockWalletMaterialWithPasskey({credentials: authenticator}).then(() => {
activated = true
unlockWalletMaterialWithPasskey({ credentials: authenticator }).then(() => {
activated = true;
}),
).rejects.toThrow()
expect(activated).toBe(false)
expect(rawSlots()).toBe(before)
})
).rejects.toThrow();
expect(activated).toBe(false);
expect(rawSlots()).toBe(before);
});
it('rejects same-owner altered root at registration without a ceremony or slot write', async () => {
const authenticator = new FakeAuthenticator()
const alteredRoot = {...MATERIAL, cashRootHex: OTHER_MATERIAL.cashRootHex}
const authenticator = new FakeAuthenticator();
const alteredRoot = { ...MATERIAL, cashRootHex: OTHER_MATERIAL.cashRootHex };
await expect(registerPasskey(alteredRoot, {credentials: authenticator})).rejects.toThrow(
await expect(registerPasskey(alteredRoot, { credentials: authenticator })).rejects.toThrow(
'saved wallet material',
)
expect(rawSlots()).toBe('')
})
);
expect(rawSlots()).toBe('');
});
it('registers and unlocks complete material without plaintext slot leakage', async () => {
const authenticator = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: authenticator})
const authenticator = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: authenticator });
const unlocked = await unlockWalletMaterialWithPasskey({credentials: authenticator})
const unlocked = await unlockWalletMaterialWithPasskey({ credentials: authenticator });
expect(unlocked).toEqual(MATERIAL)
expect(slot.ownerId).not.toContain(MATERIAL.linkingKeyHex)
expect(rawSlots()).not.toContain(MATERIAL.linkingKeyHex)
expect(rawSlots()).not.toContain(MATERIAL.cashRootHex)
})
expect(unlocked).toEqual(MATERIAL);
expect(slot.ownerId).not.toContain(MATERIAL.linkingKeyHex);
expect(rawSlots()).not.toContain(MATERIAL.linkingKeyHex);
expect(rawSlots()).not.toContain(MATERIAL.cashRootHex);
});
it('rejects authenticated foreign-owner material without changing slots or activation', async () => {
const authenticator = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: authenticator})
const prfOutput = await getPasskeyPrfOutput(slot.credentialId, {credentials: authenticator})
const foreignWrap = await wrapWalletMaterialWithPrf(prfOutput, OTHER_MATERIAL)
localStorage.setItem(SLOT_STORAGE_KEY, JSON.stringify([{...slot, ...foreignWrap}]))
const before = rawSlots()
let activated = false
const authenticator = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: authenticator });
const prfOutput = await getPasskeyPrfOutput(slot.credentialId, { credentials: authenticator });
const foreignWrap = await wrapWalletMaterialWithPrf(prfOutput, OTHER_MATERIAL);
localStorage.setItem(SLOT_STORAGE_KEY, JSON.stringify([{ ...slot, ...foreignWrap }]));
const before = rawSlots();
let activated = false;
await expect(
unlockWalletMaterialWithPasskey({credentials: authenticator}).then(() => {
activated = true
unlockWalletMaterialWithPasskey({ credentials: authenticator }).then(() => {
activated = true;
}),
).rejects.toThrow('different wallet')
expect(activated).toBe(false)
expect(rawSlots()).toBe(before)
})
).rejects.toThrow('different wallet');
expect(activated).toBe(false);
expect(rawSlots()).toBe(before);
});
it('rejects a slot changed during its ceremony without changing storage or activation', async () => {
const authenticator = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: authenticator})
let changed = ''
const authenticator = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: authenticator });
let changed = '';
authenticator.onGet = async () => {
const slot = readPasskeySlots()[0]
if (slot === undefined) throw new Error('expected registered slot')
localStorage.setItem(SLOT_STORAGE_KEY, JSON.stringify([{...slot, createdAt: slot.createdAt + 1}]))
changed = rawSlots()
}
let activated = false
const slot = readPasskeySlots()[0];
if (slot === undefined) throw new Error('expected registered slot');
localStorage.setItem(
SLOT_STORAGE_KEY,
JSON.stringify([{ ...slot, createdAt: slot.createdAt + 1 }]),
);
changed = rawSlots();
};
let activated = false;
await expect(
unlockWalletMaterialWithPasskey({credentials: authenticator}).then(() => {
activated = true
unlockWalletMaterialWithPasskey({ credentials: authenticator }).then(() => {
activated = true;
}),
).rejects.toThrow('changed')
expect(activated).toBe(false)
expect(rawSlots()).toBe(changed)
})
).rejects.toThrow('changed');
expect(activated).toBe(false);
expect(rawSlots()).toBe(changed);
});
it('rewraps every slot around byte-identical material or writes nothing', async () => {
const authenticator = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: authenticator})
const before = rawSlots()
const authenticator = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: authenticator });
const before = rawSlots();
await expect(rewrapAllSlots(MATERIAL, new Map())).rejects.toThrow('partial re-wrap')
expect(rawSlots()).toBe(before)
await expect(rewrapAllSlots(MATERIAL, new Map())).rejects.toThrow('partial re-wrap');
expect(rawSlots()).toBe(before);
const prfOutput = await getPasskeyPrfOutput(slot.credentialId, {credentials: authenticator})
await rewrapAllSlots(MATERIAL, new Map([[slot.credentialId, prfOutput]]))
await expect(unlockWalletMaterialWithPasskey({credentials: authenticator})).resolves.toEqual(
const prfOutput = await getPasskeyPrfOutput(slot.credentialId, { credentials: authenticator });
await rewrapAllSlots(MATERIAL, new Map([[slot.credentialId, prfOutput]]));
await expect(unlockWalletMaterialWithPasskey({ credentials: authenticator })).resolves.toEqual(
MATERIAL,
)
})
);
});
it('does not create a slot when registration is cancelled', async () => {
const authenticator = new FakeAuthenticator()
authenticator.cancelCreate = true
const authenticator = new FakeAuthenticator();
authenticator.cancelCreate = true;
await expect(registerPasskey(MATERIAL, {credentials: authenticator})).rejects.toThrow('cancelled')
expect(rawSlots()).toBe('')
})
})
await expect(registerPasskey(MATERIAL, { credentials: authenticator })).rejects.toThrow(
'cancelled',
);
expect(rawSlots()).toBe('');
});
});
src/lnurlcash/passkeys.multiple.cases.ts
+80 -78
View File
@@ -4,12 +4,12 @@
// unguessable without the authenticator. Everything except a real
// authenticator's touch is covered here.
import {beforeEach, describe, expect, it} from 'vitest'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -23,7 +23,7 @@ import {
unlockWalletMaterialWithPasskey,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
} from './passkeys';
import {
decryptRecord,
decryptSavedLinkingKey,
@@ -35,43 +35,43 @@ import {
savedKeyOwnerId,
saveLinkingKey,
saveWalletMaterial,
} from './keys'
import {parseJsonObject, parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, parseJsonObjectArray, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// Fake platform authenticator: holds credentials (id -> secret), evaluates
// PRF as HMAC-SHA256(secret, salt). Flags emulate the authenticator quirks
// found in the wild: PRF unsupported, results only on get, results never.
class FakeAuthenticator implements PasskeyCredentials {
// id typed Uint8Array<ArrayBuffer>: rawId must satisfy BufferSource
private held = new Map<string, {id: Uint8Array<ArrayBuffer>; secret: Uint8Array}>()
supportsPrf = true
prfResultsOnCreate = true
prfResultsOnGet = true
createCalls = 0
getCalls = 0
private held = new Map<string, { id: Uint8Array<ArrayBuffer>; secret: Uint8Array }>();
supportsPrf = true;
prfResultsOnCreate = true;
prfResultsOnGet = true;
createCalls = 0;
getCalls = 0;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
this.createCalls += 1
const salt = options?.publicKey?.extensions?.prf?.eval?.first
const id = crypto.getRandomValues(new Uint8Array(16))
const secret = crypto.getRandomValues(new Uint8Array(32))
this.held.set(bytesToHex(id), {id, secret})
this.createCalls += 1;
const salt = options?.publicKey?.extensions?.prf?.eval?.first;
const id = crypto.getRandomValues(new Uint8Array(16));
const secret = crypto.getRandomValues(new Uint8Array(32));
this.held.set(bytesToHex(id), { id, secret });
return {
type: 'public-key',
rawId: id,
@@ -80,108 +80,110 @@ class FakeAuthenticator implements PasskeyCredentials {
this.supportsPrf && salt
? {
enabled: true,
...(this.prfResultsOnCreate ? {results: {first: this.prf(secret, salt)}} : {}),
...(this.prfResultsOnCreate ? { results: { first: this.prf(secret, salt) } } : {}),
}
: {},
}),
}
}
};
};
// answers with the first allowed credential it holds, like a real
// authenticator picking among allowCredentials; null when it holds none
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
this.getCalls += 1
const pk = options?.publicKey
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)))
const match = allowed.find((hex) => this.held.has(hex))
const held = match ? this.held.get(match) : undefined
if (!held) return null
const salt = pk?.extensions?.prf?.eval?.first
this.getCalls += 1;
const pk = options?.publicKey;
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)));
const match = allowed.find((hex) => this.held.has(hex));
const held = match ? this.held.get(match) : undefined;
if (!held) return null;
const salt = pk?.extensions?.prf?.eval?.first;
return {
type: 'public-key',
rawId: held.id,
getClientExtensionResults: () => ({
prf:
salt && this.prfResultsOnGet
? {enabled: true, results: {first: this.prf(held.secret, salt)}}
? { enabled: true, results: { first: this.prf(held.secret, salt) } }
: {},
}),
}
}
};
};
// simulates the passkey's secret changing underneath a slot (credential
// re-created on the authenticator while the slot stayed behind)
rotateSecret = (credentialId: string): void => {
const held = this.held.get(credentialId)
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32))
}
const held = this.held.get(credentialId);
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32));
};
private prf = (secret: Uint8Array, salt: BufferSource): Uint8Array<ArrayBuffer> => {
// set into a fresh array: hmac returns Uint8Array<ArrayBufferLike>,
// which BufferSource rejects
const out = new Uint8Array(32)
out.set(hmac(sha256, secret, toBytes(salt)))
return out
}
const out = new Uint8Array(32);
out.set(hmac(sha256, secret, toBytes(salt)));
return out;
};
}
const readRawSlots = (): Array<Record<string, unknown>> =>
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
const writeRawSlots = (slots: Array<Record<string, unknown>>): void => {
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots))
}
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots));
};
const removeSavedOwnerMarker = (): void => {
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}')
delete stored.ownerId
delete stored.version
localStorage.setItem('sattle_linking_key', JSON.stringify(stored))
}
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}');
delete stored.ownerId;
delete stored.version;
localStorage.setItem('sattle_linking_key', JSON.stringify(stored));
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
await saveWalletMaterial(MATERIAL);
});
describe('multiple passkeys', () => {
it('keeps slots independent: each passkey unlocks the same key', async () => {
const laptop = new FakeAuthenticator()
const phone = new FakeAuthenticator()
const laptop = new FakeAuthenticator();
const phone = new FakeAuthenticator();
const laptopSlot = await registerPasskey(MATERIAL, {
credentials: laptop,
name: 'laptop',
})
});
const phoneSlot = await registerPasskey(MATERIAL, {
credentials: phone,
name: 'phone',
})
expect(readPasskeySlots()).toHaveLength(2)
});
expect(readPasskeySlots()).toHaveLength(2);
// independent wrap keys: same plaintext, different salts and ciphertexts
expect(laptopSlot.hkdfSalt).not.toBe(phoneSlot.hkdfSalt)
expect(laptopSlot.wrappedMaterial).not.toBe(phoneSlot.wrappedMaterial)
expect(laptopSlot.hkdfSalt).not.toBe(phoneSlot.hkdfSalt);
expect(laptopSlot.wrappedMaterial).not.toBe(phoneSlot.wrappedMaterial);
expect(await unlockWalletMaterialWithPasskey({credentials: laptop})).toEqual(MATERIAL)
expect(await unlockWalletMaterialWithPasskey({credentials: phone})).toEqual(MATERIAL)
})
expect(await unlockWalletMaterialWithPasskey({ credentials: laptop })).toEqual(MATERIAL);
expect(await unlockWalletMaterialWithPasskey({ credentials: phone })).toEqual(MATERIAL);
});
it('removePasskey drops exactly one slot and leaves the rest working', async () => {
const laptop = new FakeAuthenticator()
const phone = new FakeAuthenticator()
const laptop = new FakeAuthenticator();
const phone = new FakeAuthenticator();
const laptopSlot = await registerPasskey(MATERIAL, {
credentials: laptop,
})
await registerPasskey(MATERIAL, {credentials: phone})
});
await registerPasskey(MATERIAL, { credentials: phone });
await expect(removePasskey(laptopSlot.credentialId)).resolves.toBe(true)
expect(readPasskeySlots()).toHaveLength(1)
await expect(removePasskey(laptopSlot.credentialId)).resolves.toBe(true);
expect(readPasskeySlots()).toHaveLength(1);
// the removed passkey no longer matches any offered credential
await expect(unlockWalletMaterialWithPasskey({credentials: laptop})).rejects.toThrow('cancelled')
await expect(unlockWalletMaterialWithPasskey({ credentials: laptop })).rejects.toThrow(
'cancelled',
);
// the survivor is unaffected
expect(await unlockWalletMaterialWithPasskey({credentials: phone})).toEqual(MATERIAL)
expect(await unlockWalletMaterialWithPasskey({ credentials: phone })).toEqual(MATERIAL);
// removing again is a no-op
await expect(removePasskey(laptopSlot.credentialId)).resolves.toBe(false)
})
})
await expect(removePasskey(laptopSlot.credentialId)).resolves.toBe(false);
});
});
src/lnurlcash/passkeys.ownership-a.cases.ts
+114 -114
View File
@@ -4,12 +4,12 @@
// unguessable without the authenticator. Everything except a real
// authenticator's touch is covered here.
import {beforeEach, describe, expect, it} from 'vitest'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -23,7 +23,7 @@ import {
unlockWalletMaterialWithPasskey,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
} from './passkeys';
import {
decryptRecord,
decryptSavedWalletMaterial,
@@ -36,43 +36,43 @@ import {
saveLinkingKey,
saveWalletMaterial,
walletMaterialLinkingKey,
} from './keys'
import {parseJsonObject, parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, parseJsonObjectArray, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// Fake platform authenticator: holds credentials (id -> secret), evaluates
// PRF as HMAC-SHA256(secret, salt). Flags emulate the authenticator quirks
// found in the wild: PRF unsupported, results only on get, results never.
class FakeAuthenticator implements PasskeyCredentials {
// id typed Uint8Array<ArrayBuffer>: rawId must satisfy BufferSource
private held = new Map<string, {id: Uint8Array<ArrayBuffer>; secret: Uint8Array}>()
supportsPrf = true
prfResultsOnCreate = true
prfResultsOnGet = true
createCalls = 0
getCalls = 0
private held = new Map<string, { id: Uint8Array<ArrayBuffer>; secret: Uint8Array }>();
supportsPrf = true;
prfResultsOnCreate = true;
prfResultsOnGet = true;
createCalls = 0;
getCalls = 0;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
this.createCalls += 1
const salt = options?.publicKey?.extensions?.prf?.eval?.first
const id = crypto.getRandomValues(new Uint8Array(16))
const secret = crypto.getRandomValues(new Uint8Array(32))
this.held.set(bytesToHex(id), {id, secret})
this.createCalls += 1;
const salt = options?.publicKey?.extensions?.prf?.eval?.first;
const id = crypto.getRandomValues(new Uint8Array(16));
const secret = crypto.getRandomValues(new Uint8Array(32));
this.held.set(bytesToHex(id), { id, secret });
return {
type: 'public-key',
rawId: id,
@@ -81,98 +81,98 @@ class FakeAuthenticator implements PasskeyCredentials {
this.supportsPrf && salt
? {
enabled: true,
...(this.prfResultsOnCreate ? {results: {first: this.prf(secret, salt)}} : {}),
...(this.prfResultsOnCreate ? { results: { first: this.prf(secret, salt) } } : {}),
}
: {},
}),
}
}
};
};
// answers with the first allowed credential it holds, like a real
// authenticator picking among allowCredentials; null when it holds none
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
this.getCalls += 1
const pk = options?.publicKey
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)))
const match = allowed.find((hex) => this.held.has(hex))
const held = match ? this.held.get(match) : undefined
if (!held) return null
const salt = pk?.extensions?.prf?.eval?.first
this.getCalls += 1;
const pk = options?.publicKey;
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)));
const match = allowed.find((hex) => this.held.has(hex));
const held = match ? this.held.get(match) : undefined;
if (!held) return null;
const salt = pk?.extensions?.prf?.eval?.first;
return {
type: 'public-key',
rawId: held.id,
getClientExtensionResults: () => ({
prf:
salt && this.prfResultsOnGet
? {enabled: true, results: {first: this.prf(held.secret, salt)}}
? { enabled: true, results: { first: this.prf(held.secret, salt) } }
: {},
}),
}
}
};
};
// simulates the passkey's secret changing underneath a slot (credential
// re-created on the authenticator while the slot stayed behind)
rotateSecret = (credentialId: string): void => {
const held = this.held.get(credentialId)
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32))
}
const held = this.held.get(credentialId);
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32));
};
private prf = (secret: Uint8Array, salt: BufferSource): Uint8Array<ArrayBuffer> => {
// set into a fresh array: hmac returns Uint8Array<ArrayBufferLike>,
// which BufferSource rejects
const out = new Uint8Array(32)
out.set(hmac(sha256, secret, toBytes(salt)))
return out
}
const out = new Uint8Array(32);
out.set(hmac(sha256, secret, toBytes(salt)));
return out;
};
}
const readRawSlots = (): Array<Record<string, unknown>> =>
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
const writeRawSlots = (slots: Array<Record<string, unknown>>): void => {
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots))
}
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots));
};
const removeSavedOwnerMarker = (): void => {
const stored = parseJsonObject(localStorage.getItem('sattle_wallet_material_v2') ?? '{}')
delete stored.ownerId
delete stored.version
localStorage.setItem('sattle_wallet_material_v2', JSON.stringify(stored))
}
const stored = parseJsonObject(localStorage.getItem('sattle_wallet_material_v2') ?? '{}');
delete stored.ownerId;
delete stored.version;
localStorage.setItem('sattle_wallet_material_v2', JSON.stringify(stored));
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
await saveWalletMaterial(MATERIAL);
});
describe('slot ownership', () => {
it('binds a new slot to the proven saved wallet owner', async () => {
// Given the saved wallet has a canonical owner marker
const auth = new FakeAuthenticator()
const auth = new FakeAuthenticator();
// When its linking key registers a passkey
const slot = await registerPasskey(MATERIAL, {credentials: auth})
const slot = await registerPasskey(MATERIAL, { credentials: auth });
// Then the slot carries that same canonical owner
expect(slot.ownerId).toBe(linkingPubKeyHex(LINKING_KEY))
expect(readPasskeySlots()).toEqual([slot])
})
expect(slot.ownerId).toBe(linkingPubKeyHex(LINKING_KEY));
expect(readPasskeySlots()).toEqual([slot]);
});
it('filters foreign, malformed, and unowned slots from reads and availability', async () => {
// Given one valid current-owner slot plus copies with untrusted owners
const auth = new FakeAuthenticator()
const current = await registerPasskey(MATERIAL, {credentials: auth})
const auth = new FakeAuthenticator();
const current = await registerPasskey(MATERIAL, { credentials: auth });
const foreign = {
...current,
credentialId: '11'.repeat(16),
ownerId: linkingPubKeyHex(OTHER_LINKING_KEY),
}
};
const malformed = {
...current,
credentialId: '22'.repeat(16),
ownerId: 'not-an-owner',
}
};
const unowned = {
credentialId: '33'.repeat(16),
hkdfSalt: current.hkdfSalt,
@@ -180,76 +180,76 @@ describe('slot ownership', () => {
materialHash: current.materialHash,
wrappedMaterial: current.wrappedMaterial,
createdAt: current.createdAt,
}
writeRawSlots([foreign, malformed, unowned])
};
writeRawSlots([foreign, malformed, unowned]);
// When the current wallet asks for its slots
const slots = readPasskeySlots()
const slots = readPasskeySlots();
// Then no foreign or unproven slot is exposed
expect(slots).toEqual([])
expect(hasPasskeySlots()).toBe(false)
})
expect(slots).toEqual([]);
expect(hasPasskeySlots()).toBe(false);
});
it('does not offer markerless slots for passkey-first unlock', async () => {
// Given a legacy slot and a saved wallet with no proven owner marker
const auth = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: auth})
const legacy = readRawSlots()
delete legacy[0]?.ownerId
delete legacy[0]?.version
writeRawSlots(legacy)
removeSavedOwnerMarker()
const auth = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: auth });
const legacy = readRawSlots();
delete legacy[0]?.ownerId;
delete legacy[0]?.version;
writeRawSlots(legacy);
removeSavedOwnerMarker();
// When passkey unlock is attempted before another proof path
const attempt = unlockWalletMaterialWithPasskey({credentials: auth})
const attempt = unlockWalletMaterialWithPasskey({ credentials: auth });
// Then it fails before asking the authenticator
await expect(attempt).rejects.toThrow('No passkeys')
expect(auth.getCalls).toBe(0)
expect(hasPasskeySlots()).toBe(false)
})
await expect(attempt).rejects.toThrow('No passkeys');
expect(auth.getCalls).toBe(0);
expect(hasPasskeySlots()).toBe(false);
});
it('does not auto-adopt legacy slots when a foreign wallet is saved', async () => {
// Given markerless residue from the old wallet
const auth = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: auth})
const legacy = readRawSlots()
delete legacy[0]?.ownerId
delete legacy[0]?.version
writeRawSlots(legacy)
const auth = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: auth });
const legacy = readRawSlots();
delete legacy[0]?.ownerId;
delete legacy[0]?.version;
writeRawSlots(legacy);
// When a different wallet is installed with its canonical owner
await saveLinkingKey(OTHER_LINKING_KEY)
await saveWalletMaterial({...MATERIAL, linkingKeyHex: bytesToHex(OTHER_LINKING_KEY)})
await saveLinkingKey(OTHER_LINKING_KEY);
await saveWalletMaterial({ ...MATERIAL, linkingKeyHex: bytesToHex(OTHER_LINKING_KEY) });
// Then the residue stays unowned and unavailable to the new wallet
expect(readPasskeySlots()).toEqual([])
expect(hasPasskeySlots()).toBe(false)
expect(readRawSlots()).toEqual(legacy)
})
expect(readPasskeySlots()).toEqual([]);
expect(hasPasskeySlots()).toBe(false);
expect(readRawSlots()).toEqual(legacy);
});
it('adopts legacy slots only after the saved wallet owner is proven', async () => {
// Given a legacy encrypted wallet and its markerless passkey slot
const auth = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: auth})
const legacy = readRawSlots()
delete legacy[0]?.ownerId
delete legacy[0]?.version
writeRawSlots(legacy)
await saveWalletMaterial(MATERIAL, 'correct horse')
removeSavedOwnerMarker()
const auth = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: auth });
const legacy = readRawSlots();
delete legacy[0]?.ownerId;
delete legacy[0]?.version;
writeRawSlots(legacy);
await saveWalletMaterial(MATERIAL, 'correct horse');
removeSavedOwnerMarker();
// When migration is attempted before and then after password proof
await expect(migrateLegacyPasskeySlots(LINKING_KEY)).rejects.toThrow('proven owner')
const provenMaterial = await decryptSavedWalletMaterial('correct horse')
ensureSavedWalletMaterialOwner(provenMaterial)
await migrateLegacyPasskeySlots(walletMaterialLinkingKey(provenMaterial))
await expect(migrateLegacyPasskeySlots(LINKING_KEY)).rejects.toThrow('proven owner');
const provenMaterial = await decryptSavedWalletMaterial('correct horse');
ensureSavedWalletMaterialOwner(provenMaterial);
await migrateLegacyPasskeySlots(walletMaterialLinkingKey(provenMaterial));
// Then the same slot is stamped once for that proven owner and unlocks
expect(savedWalletMaterialOwnerId()).toBe(linkingPubKeyHex(LINKING_KEY))
expect(readPasskeySlots()).toHaveLength(1)
expect(readPasskeySlots()[0]?.ownerId).toBe(linkingPubKeyHex(LINKING_KEY))
await expect(unlockWalletMaterialWithPasskey({credentials: auth})).resolves.toEqual(MATERIAL)
})
})
expect(savedWalletMaterialOwnerId()).toBe(linkingPubKeyHex(LINKING_KEY));
expect(readPasskeySlots()).toHaveLength(1);
expect(readPasskeySlots()[0]?.ownerId).toBe(linkingPubKeyHex(LINKING_KEY));
await expect(unlockWalletMaterialWithPasskey({ credentials: auth })).resolves.toEqual(MATERIAL);
});
});
src/lnurlcash/passkeys.ownership-b.cases.ts
+101 -101
View File
@@ -4,12 +4,12 @@
// unguessable without the authenticator. Everything except a real
// authenticator's touch is covered here.
import {beforeEach, describe, expect, it} from 'vitest'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -23,7 +23,7 @@ import {
unlockWalletMaterialWithPasskey,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
} from './passkeys';
import {
decryptRecord,
decryptSavedLinkingKey,
@@ -35,44 +35,44 @@ import {
savedKeyOwnerId,
saveLinkingKey,
saveWalletMaterial,
} from './keys'
import {parseJsonObject, parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, parseJsonObjectArray, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
const OTHER_MATERIAL = {...MATERIAL, linkingKeyHex: bytesToHex(OTHER_LINKING_KEY)}
};
const OTHER_MATERIAL = { ...MATERIAL, linkingKeyHex: bytesToHex(OTHER_LINKING_KEY) };
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// Fake platform authenticator: holds credentials (id -> secret), evaluates
// PRF as HMAC-SHA256(secret, salt). Flags emulate the authenticator quirks
// found in the wild: PRF unsupported, results only on get, results never.
class FakeAuthenticator implements PasskeyCredentials {
// id typed Uint8Array<ArrayBuffer>: rawId must satisfy BufferSource
private held = new Map<string, {id: Uint8Array<ArrayBuffer>; secret: Uint8Array}>()
supportsPrf = true
prfResultsOnCreate = true
prfResultsOnGet = true
createCalls = 0
getCalls = 0
private held = new Map<string, { id: Uint8Array<ArrayBuffer>; secret: Uint8Array }>();
supportsPrf = true;
prfResultsOnCreate = true;
prfResultsOnGet = true;
createCalls = 0;
getCalls = 0;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
this.createCalls += 1
const salt = options?.publicKey?.extensions?.prf?.eval?.first
const id = crypto.getRandomValues(new Uint8Array(16))
const secret = crypto.getRandomValues(new Uint8Array(32))
this.held.set(bytesToHex(id), {id, secret})
this.createCalls += 1;
const salt = options?.publicKey?.extensions?.prf?.eval?.first;
const id = crypto.getRandomValues(new Uint8Array(16));
const secret = crypto.getRandomValues(new Uint8Array(32));
this.held.set(bytesToHex(id), { id, secret });
return {
type: 'public-key',
rawId: id,
@@ -81,159 +81,159 @@ class FakeAuthenticator implements PasskeyCredentials {
this.supportsPrf && salt
? {
enabled: true,
...(this.prfResultsOnCreate ? {results: {first: this.prf(secret, salt)}} : {}),
...(this.prfResultsOnCreate ? { results: { first: this.prf(secret, salt) } } : {}),
}
: {},
}),
}
}
};
};
// answers with the first allowed credential it holds, like a real
// authenticator picking among allowCredentials; null when it holds none
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
this.getCalls += 1
const pk = options?.publicKey
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)))
const match = allowed.find((hex) => this.held.has(hex))
const held = match ? this.held.get(match) : undefined
if (!held) return null
const salt = pk?.extensions?.prf?.eval?.first
this.getCalls += 1;
const pk = options?.publicKey;
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)));
const match = allowed.find((hex) => this.held.has(hex));
const held = match ? this.held.get(match) : undefined;
if (!held) return null;
const salt = pk?.extensions?.prf?.eval?.first;
return {
type: 'public-key',
rawId: held.id,
getClientExtensionResults: () => ({
prf:
salt && this.prfResultsOnGet
? {enabled: true, results: {first: this.prf(held.secret, salt)}}
? { enabled: true, results: { first: this.prf(held.secret, salt) } }
: {},
}),
}
}
};
};
// simulates the passkey's secret changing underneath a slot (credential
// re-created on the authenticator while the slot stayed behind)
rotateSecret = (credentialId: string): void => {
const held = this.held.get(credentialId)
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32))
}
const held = this.held.get(credentialId);
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32));
};
private prf = (secret: Uint8Array, salt: BufferSource): Uint8Array<ArrayBuffer> => {
// set into a fresh array: hmac returns Uint8Array<ArrayBufferLike>,
// which BufferSource rejects
const out = new Uint8Array(32)
out.set(hmac(sha256, secret, toBytes(salt)))
return out
}
const out = new Uint8Array(32);
out.set(hmac(sha256, secret, toBytes(salt)));
return out;
};
}
const readRawSlots = (): Array<Record<string, unknown>> =>
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
const writeRawSlots = (slots: Array<Record<string, unknown>>): void => {
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots))
}
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots));
};
const removeSavedOwnerMarker = (): void => {
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}')
delete stored.ownerId
delete stored.version
localStorage.setItem('sattle_linking_key', JSON.stringify(stored))
}
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}');
delete stored.ownerId;
delete stored.version;
localStorage.setItem('sattle_linking_key', JSON.stringify(stored));
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
await saveWalletMaterial(MATERIAL);
});
describe('slot ownership (continued)', () => {
it('rejects an unwrapped key that does not match the saved proven owner', async () => {
// Given a current-owner slot whose authenticated wrap was replaced with
// a valid wrap of another wallet key
const auth = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: auth})
const auth = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: auth });
const prfOutput = await getPasskeyPrfOutput(slot.credentialId, {
credentials: auth,
})
const foreignWrap = await wrapWalletMaterialWithPrf(prfOutput, OTHER_MATERIAL)
writeRawSlots([{...slot, ...foreignWrap}])
});
const foreignWrap = await wrapWalletMaterialWithPrf(prfOutput, OTHER_MATERIAL);
writeRawSlots([{ ...slot, ...foreignWrap }]);
// When the authenticator successfully unwraps that foreign key
const attempt = unlockWalletMaterialWithPasskey({credentials: auth})
const attempt = unlockWalletMaterialWithPasskey({ credentials: auth });
// Then owner validation rejects it before activation can receive it
await expect(attempt).rejects.toThrow('different wallet')
})
await expect(attempt).rejects.toThrow('different wallet');
});
it('rejects a stale unlock when the saved owner changes during the ceremony', async () => {
// Given an authenticator that replaces the saved wallet before returning
const auth = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: auth})
const auth = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: auth });
const stale: PasskeyCredentials = {
create: auth.create,
get: async (options) => {
const credential = await auth.get(options)
await saveLinkingKey(OTHER_LINKING_KEY)
await saveWalletMaterial(OTHER_MATERIAL)
return credential
const credential = await auth.get(options);
await saveLinkingKey(OTHER_LINKING_KEY);
await saveWalletMaterial(OTHER_MATERIAL);
return credential;
},
}
};
// When the old wallet's ceremony completes after replacement
const attempt = unlockWalletMaterialWithPasskey({credentials: stale})
const attempt = unlockWalletMaterialWithPasskey({ credentials: stale });
// Then the old linking key is never returned for activation
await expect(attempt).rejects.toThrow('different wallet')
})
await expect(attempt).rejects.toThrow('different wallet');
});
it('does not adopt a slot carrying a malformed owner marker', async () => {
// Given an otherwise valid slot whose owner claim is malformed
const auth = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: auth})
const malformed = {...slot, ownerId: 'not-an-owner'}
writeRawSlots([malformed])
const auth = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: auth });
const malformed = { ...slot, ownerId: 'not-an-owner' };
writeRawSlots([malformed]);
// When the current owner performs the legacy migration
await migrateLegacyPasskeySlots(LINKING_KEY)
await migrateLegacyPasskeySlots(LINKING_KEY);
// Then only truly markerless legacy slots are eligible
expect(readPasskeySlots()).toEqual([])
expect(readRawSlots()).toEqual([malformed])
})
expect(readPasskeySlots()).toEqual([]);
expect(readRawSlots()).toEqual([malformed]);
});
it('cannot remove a foreign-owner slot', async () => {
// Given a slot owned by another wallet remains in shared storage
const auth = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: auth})
const foreign = {...slot, ownerId: linkingPubKeyHex(OTHER_LINKING_KEY)}
writeRawSlots([foreign])
const auth = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: auth });
const foreign = { ...slot, ownerId: linkingPubKeyHex(OTHER_LINKING_KEY) };
writeRawSlots([foreign]);
// When the current owner asks to remove that credential id
const removed = await removePasskey(slot.credentialId)
const removed = await removePasskey(slot.credentialId);
// Then the foreign record is untouched
expect(removed).toBe(false)
expect(readRawSlots()).toEqual([foreign])
})
expect(removed).toBe(false);
expect(readRawSlots()).toEqual([foreign]);
});
it('rewraps only current-owner slots and preserves foreign slots', async () => {
// Given current and foreign slots share storage
const auth = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: auth})
const auth = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: auth });
const foreign = {
...slot,
credentialId: '44'.repeat(16),
ownerId: linkingPubKeyHex(OTHER_LINKING_KEY),
}
writeRawSlots([slot, foreign])
};
writeRawSlots([slot, foreign]);
const prfOutput = await getPasskeyPrfOutput(slot.credentialId, {
credentials: auth,
})
});
// When the current wallet rewraps its slots
await rewrapAllSlots(MATERIAL, new Map([[slot.credentialId, prfOutput]]))
await rewrapAllSlots(MATERIAL, new Map([[slot.credentialId, prfOutput]]));
// Then the foreign slot did not require output and remains byte-identical
expect(readRawSlots()).toContainEqual(foreign)
})
})
expect(readRawSlots()).toContainEqual(foreign);
});
});
src/lnurlcash/passkeys.registration.cases.ts
+124 -124
View File
@@ -4,12 +4,12 @@
// unguessable without the authenticator. Everything except a real
// authenticator's touch is covered here.
import {beforeEach, describe, expect, it} from 'vitest'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -23,7 +23,7 @@ import {
unlockWalletMaterialWithPasskey,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
} from './passkeys';
import {
decryptRecord,
decryptSavedWalletMaterial,
@@ -36,43 +36,43 @@ import {
saveLinkingKey,
saveWalletMaterial,
walletMaterialLinkingKey,
} from './keys'
import {parseJsonObject, parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, parseJsonObjectArray, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// Fake platform authenticator: holds credentials (id -> secret), evaluates
// PRF as HMAC-SHA256(secret, salt). Flags emulate the authenticator quirks
// found in the wild: PRF unsupported, results only on get, results never.
class FakeAuthenticator implements PasskeyCredentials {
// id typed Uint8Array<ArrayBuffer>: rawId must satisfy BufferSource
private held = new Map<string, {id: Uint8Array<ArrayBuffer>; secret: Uint8Array}>()
supportsPrf = true
prfResultsOnCreate = true
prfResultsOnGet = true
createCalls = 0
getCalls = 0
private held = new Map<string, { id: Uint8Array<ArrayBuffer>; secret: Uint8Array }>();
supportsPrf = true;
prfResultsOnCreate = true;
prfResultsOnGet = true;
createCalls = 0;
getCalls = 0;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
this.createCalls += 1
const salt = options?.publicKey?.extensions?.prf?.eval?.first
const id = crypto.getRandomValues(new Uint8Array(16))
const secret = crypto.getRandomValues(new Uint8Array(32))
this.held.set(bytesToHex(id), {id, secret})
this.createCalls += 1;
const salt = options?.publicKey?.extensions?.prf?.eval?.first;
const id = crypto.getRandomValues(new Uint8Array(16));
const secret = crypto.getRandomValues(new Uint8Array(32));
this.held.set(bytesToHex(id), { id, secret });
return {
type: 'public-key',
rawId: id,
@@ -81,180 +81,180 @@ class FakeAuthenticator implements PasskeyCredentials {
this.supportsPrf && salt
? {
enabled: true,
...(this.prfResultsOnCreate ? {results: {first: this.prf(secret, salt)}} : {}),
...(this.prfResultsOnCreate ? { results: { first: this.prf(secret, salt) } } : {}),
}
: {},
}),
}
}
};
};
// answers with the first allowed credential it holds, like a real
// authenticator picking among allowCredentials; null when it holds none
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
this.getCalls += 1
const pk = options?.publicKey
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)))
const match = allowed.find((hex) => this.held.has(hex))
const held = match ? this.held.get(match) : undefined
if (!held) return null
const salt = pk?.extensions?.prf?.eval?.first
this.getCalls += 1;
const pk = options?.publicKey;
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)));
const match = allowed.find((hex) => this.held.has(hex));
const held = match ? this.held.get(match) : undefined;
if (!held) return null;
const salt = pk?.extensions?.prf?.eval?.first;
return {
type: 'public-key',
rawId: held.id,
getClientExtensionResults: () => ({
prf:
salt && this.prfResultsOnGet
? {enabled: true, results: {first: this.prf(held.secret, salt)}}
? { enabled: true, results: { first: this.prf(held.secret, salt) } }
: {},
}),
}
}
};
};
// simulates the passkey's secret changing underneath a slot (credential
// re-created on the authenticator while the slot stayed behind)
rotateSecret = (credentialId: string): void => {
const held = this.held.get(credentialId)
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32))
}
const held = this.held.get(credentialId);
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32));
};
private prf = (secret: Uint8Array, salt: BufferSource): Uint8Array<ArrayBuffer> => {
// set into a fresh array: hmac returns Uint8Array<ArrayBufferLike>,
// which BufferSource rejects
const out = new Uint8Array(32)
out.set(hmac(sha256, secret, toBytes(salt)))
return out
}
const out = new Uint8Array(32);
out.set(hmac(sha256, secret, toBytes(salt)));
return out;
};
}
const readRawSlots = (): Array<Record<string, unknown>> =>
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
const writeRawSlots = (slots: Array<Record<string, unknown>>): void => {
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots))
}
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots));
};
const removeSavedOwnerMarker = (): void => {
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}')
delete stored.ownerId
delete stored.version
localStorage.setItem('sattle_linking_key', JSON.stringify(stored))
}
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}');
delete stored.ownerId;
delete stored.version;
localStorage.setItem('sattle_linking_key', JSON.stringify(stored));
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
await saveWalletMaterial(MATERIAL);
});
describe('registration and unlock', () => {
it('registers a passkey and unlocks the same complete material', async () => {
const auth = new FakeAuthenticator()
const auth = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, {
credentials: auth,
name: 'laptop',
})
expect(slot.name).toBe('laptop')
expect(readPasskeySlots()).toEqual([slot])
expect(hasPasskeySlots()).toBe(true)
});
expect(slot.name).toBe('laptop');
expect(readPasskeySlots()).toEqual([slot]);
expect(hasPasskeySlots()).toBe(true);
const unwrapped = await unlockWalletMaterialWithPasskey({credentials: auth})
expect(unwrapped).toEqual(MATERIAL)
})
const unwrapped = await unlockWalletMaterialWithPasskey({ credentials: auth });
expect(unwrapped).toEqual(MATERIAL);
});
it('never stores the linking key in the clear', async () => {
const auth = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: auth})
const raw = localStorage.getItem('sattle_passkey_slots')
expect(raw).toBeTruthy()
expect(raw).not.toContain(bytesToHex(LINKING_KEY))
})
const auth = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: auth });
const raw = localStorage.getItem('sattle_passkey_slots');
expect(raw).toBeTruthy();
expect(raw).not.toContain(bytesToHex(LINKING_KEY));
});
it('yields the same wallet material unlock(password) yields', async () => {
await saveWalletMaterial(MATERIAL, 'correct horse')
const auth = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: auth})
await saveWalletMaterial(MATERIAL, 'correct horse');
const auth = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: auth });
const viaPassword = await decryptSavedWalletMaterial('correct horse')
const viaPasskey = await unlockWalletMaterialWithPasskey({credentials: auth})
expect(viaPasskey).toEqual(viaPassword)
const viaPassword = await decryptSavedWalletMaterial('correct horse');
const viaPasskey = await unlockWalletMaterialWithPasskey({ credentials: auth });
expect(viaPasskey).toEqual(viaPassword);
// and the practical consequence: a bearer record encrypted after a
// password unlock decrypts after a passkey unlock
const passwordAes = await deriveBearerAesKey(walletMaterialLinkingKey(viaPassword))
const record = await encryptRecord(passwordAes, {note: 'still readable'})
const passkeyAes = await deriveBearerAesKey(walletMaterialLinkingKey(viaPasskey))
const passwordAes = await deriveBearerAesKey(walletMaterialLinkingKey(viaPassword));
const record = await encryptRecord(passwordAes, { note: 'still readable' });
const passkeyAes = await deriveBearerAesKey(walletMaterialLinkingKey(viaPasskey));
await expect(decryptRecord(passkeyAes, record)).resolves.toEqual({
note: 'still readable',
})
})
});
});
it('falls back to a get ceremony when create only reports prf.enabled', async () => {
const auth = new FakeAuthenticator()
auth.prfResultsOnCreate = false
const slot = await registerPasskey(MATERIAL, {credentials: auth})
expect(auth.getCalls).toBe(1)
const unwrapped = await unlockWalletMaterialWithPasskey({credentials: auth})
expect(unwrapped).toEqual(MATERIAL)
expect(readPasskeySlots()[0]?.credentialId).toBe(slot.credentialId)
})
const auth = new FakeAuthenticator();
auth.prfResultsOnCreate = false;
const slot = await registerPasskey(MATERIAL, { credentials: auth });
expect(auth.getCalls).toBe(1);
const unwrapped = await unlockWalletMaterialWithPasskey({ credentials: auth });
expect(unwrapped).toEqual(MATERIAL);
expect(readPasskeySlots()[0]?.credentialId).toBe(slot.credentialId);
});
it('refuses registration when the authenticator has no PRF support', async () => {
const auth = new FakeAuthenticator()
auth.supportsPrf = false
await expect(registerPasskey(MATERIAL, {credentials: auth})).rejects.toThrow('PRF')
expect(hasPasskeySlots()).toBe(false)
})
const auth = new FakeAuthenticator();
auth.supportsPrf = false;
await expect(registerPasskey(MATERIAL, { credentials: auth })).rejects.toThrow('PRF');
expect(hasPasskeySlots()).toBe(false);
});
it('throws on a cancelled registration ceremony', async () => {
const cancelled: PasskeyCredentials = {
create: async () => null,
get: async () => null,
}
await expect(registerPasskey(MATERIAL, {credentials: cancelled})).rejects.toThrow(
};
await expect(registerPasskey(MATERIAL, { credentials: cancelled })).rejects.toThrow(
'cancelled',
)
expect(hasPasskeySlots()).toBe(false)
})
);
expect(hasPasskeySlots()).toBe(false);
});
it('throws before any ceremony when no passkeys are registered', async () => {
const auth = new FakeAuthenticator()
await expect(unlockWalletMaterialWithPasskey({credentials: auth})).rejects.toThrow(
const auth = new FakeAuthenticator();
await expect(unlockWalletMaterialWithPasskey({ credentials: auth })).rejects.toThrow(
'No passkeys',
)
expect(auth.getCalls).toBe(0)
})
);
expect(auth.getCalls).toBe(0);
});
it('rejects unlock when the passkey returns no PRF secret', async () => {
const auth = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: auth})
auth.prfResultsOnGet = false
await expect(unlockWalletMaterialWithPasskey({credentials: auth})).rejects.toThrow(
const auth = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: auth });
auth.prfResultsOnGet = false;
await expect(unlockWalletMaterialWithPasskey({ credentials: auth })).rejects.toThrow(
'PRF secret',
)
})
);
});
it('rejects unlock when the ceremony yields an unregistered credential', async () => {
const auth = new FakeAuthenticator()
await registerPasskey(MATERIAL, {credentials: auth})
const auth = new FakeAuthenticator();
await registerPasskey(MATERIAL, { credentials: auth });
const rogue: PasskeyCredentials = {
create: async () => null,
get: async () => ({
type: 'public-key',
rawId: crypto.getRandomValues(new Uint8Array(16)),
getClientExtensionResults: () => ({
prf: {enabled: true, results: {first: new Uint8Array(32)}},
prf: { enabled: true, results: { first: new Uint8Array(32) } },
}),
}),
}
await expect(unlockWalletMaterialWithPasskey({credentials: rogue})).rejects.toThrow(
};
await expect(unlockWalletMaterialWithPasskey({ credentials: rogue })).rejects.toThrow(
'not registered',
)
})
);
});
it('rejects unlock after the authenticator secret changed underneath the slot', async () => {
const auth = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: auth})
auth.rotateSecret(slot.credentialId)
await expect(unlockWalletMaterialWithPasskey({credentials: auth})).rejects.toThrow()
})
})
const auth = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: auth });
auth.rotateSecret(slot.credentialId);
await expect(unlockWalletMaterialWithPasskey({ credentials: auth })).rejects.toThrow();
});
});
src/lnurlcash/passkeys.reverify.cases.ts
+99 -94
View File
@@ -1,156 +1,161 @@
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import {beforeEach, describe, expect, it} from 'vitest'
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import { beforeEach, describe, expect, it } from 'vitest';
import {deriveWalletMaterial, saveWalletMaterial} from './keys'
import {registerPasskey, rewrapAllSlots, unlockWalletMaterialWithPasskey} from './passkeys'
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import {stubLocalStorage} from './test-utils'
import { deriveWalletMaterial, saveWalletMaterial } from './keys';
import { registerPasskey, rewrapAllSlots, unlockWalletMaterialWithPasskey } from './passkeys';
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import { stubLocalStorage } from './test-utils';
const MNEMONIC = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
const OTHER_MNEMONIC = 'legal winner thank year wave sausage worth useful legal winner thank yellow'
const MATERIAL = deriveWalletMaterial(MNEMONIC)
const OTHER_MATERIAL = deriveWalletMaterial(OTHER_MNEMONIC)
const MNEMONIC =
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
const OTHER_MNEMONIC =
'legal winner thank year wave sausage worth useful legal winner thank yellow';
const MATERIAL = deriveWalletMaterial(MNEMONIC);
const OTHER_MATERIAL = deriveWalletMaterial(OTHER_MNEMONIC);
// same linking key (same owner) as MATERIAL, but a different, VALID cash root
const ALTERED_ROOT = {...MATERIAL, cashRootHex: OTHER_MATERIAL.cashRootHex}
const SLOT_STORAGE_KEY = 'sattle_passkey_slots'
const MATERIAL_STORAGE_KEY = 'sattle_wallet_material_v2'
const ALTERED_ROOT = { ...MATERIAL, cashRootHex: OTHER_MATERIAL.cashRootHex };
const SLOT_STORAGE_KEY = 'sattle_passkey_slots';
const MATERIAL_STORAGE_KEY = 'sattle_wallet_material_v2';
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
class FakeAuthenticator implements PasskeyCredentials {
private readonly credentialId = new Uint8Array(16).fill(12)
private readonly secret = new Uint8Array(32).fill(13)
onCreate?: () => Promise<void>
onGet?: () => Promise<void>
private readonly credentialId = new Uint8Array(16).fill(12);
private readonly secret = new Uint8Array(32).fill(13);
onCreate?: () => Promise<void>;
onGet?: () => Promise<void>;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential> => {
await this.onCreate?.()
return this.credential(options?.publicKey?.extensions?.prf?.eval?.first)
}
await this.onCreate?.();
return this.credential(options?.publicKey?.extensions?.prf?.eval?.first);
};
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
await this.onGet?.()
const allowed = options?.publicKey?.allowCredentials ?? []
await this.onGet?.();
const allowed = options?.publicKey?.allowCredentials ?? [];
return allowed.some(
(descriptor) => bytesToHex(toBytes(descriptor.id)) === bytesToHex(this.credentialId),
)
? this.credential(options?.publicKey?.extensions?.prf?.eval?.first)
: null
}
: null;
};
private credential = (salt: BufferSource | undefined): CeremonyCredential => ({
type: 'public-key',
rawId: this.credentialId,
getClientExtensionResults: () => ({
prf: salt
? {enabled: true, results: {first: new Uint8Array(hmac(sha256, this.secret, toBytes(salt)))}}
? {
enabled: true,
results: { first: new Uint8Array(hmac(sha256, this.secret, toBytes(salt))) },
}
: {},
}),
})
});
}
const storageState = (): {slots: string | null; material: string | null} => ({
const storageState = (): { slots: string | null; material: string | null } => ({
slots: localStorage.getItem(SLOT_STORAGE_KEY),
material: localStorage.getItem(MATERIAL_STORAGE_KEY),
})
});
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
describe('passkey exact-material commitment re-verification', () => {
it('rejects same-owner altered-root registration with byte-identical storage', async () => {
const authenticator = new FakeAuthenticator()
await saveWalletMaterial(MATERIAL)
const before = storageState()
const authenticator = new FakeAuthenticator();
await saveWalletMaterial(MATERIAL);
const before = storageState();
await expect(registerPasskey(ALTERED_ROOT, {credentials: authenticator})).rejects.toThrow(
await expect(registerPasskey(ALTERED_ROOT, { credentials: authenticator })).rejects.toThrow(
'saved wallet material',
)
expect(storageState()).toEqual(before)
})
);
expect(storageState()).toEqual(before);
});
it('rejects same-owner altered-root registration against encrypted saved material', async () => {
const authenticator = new FakeAuthenticator()
await saveWalletMaterial(MATERIAL, 'password')
const before = storageState()
const authenticator = new FakeAuthenticator();
await saveWalletMaterial(MATERIAL, 'password');
const before = storageState();
await expect(registerPasskey(ALTERED_ROOT, {credentials: authenticator})).rejects.toThrow(
await expect(registerPasskey(ALTERED_ROOT, { credentials: authenticator })).rejects.toThrow(
'saved wallet material',
)
expect(storageState()).toEqual(before)
})
);
expect(storageState()).toEqual(before);
});
it('writes nothing when same-owner saved material changes during registration', async () => {
const authenticator = new FakeAuthenticator()
await saveWalletMaterial(MATERIAL)
let swapped: {slots: string | null; material: string | null} | null = null
const authenticator = new FakeAuthenticator();
await saveWalletMaterial(MATERIAL);
let swapped: { slots: string | null; material: string | null } | null = null;
authenticator.onCreate = async () => {
await saveWalletMaterial(ALTERED_ROOT)
swapped = storageState()
}
await saveWalletMaterial(ALTERED_ROOT);
swapped = storageState();
};
await expect(registerPasskey(MATERIAL, {credentials: authenticator})).rejects.toThrow(
await expect(registerPasskey(MATERIAL, { credentials: authenticator })).rejects.toThrow(
'saved wallet material',
)
expect(swapped).not.toBeNull()
expect(storageState()).toEqual(swapped)
})
);
expect(swapped).not.toBeNull();
expect(storageState()).toEqual(swapped);
});
it('rejects unlock after same-owner saved replacement with byte-identical storage', async () => {
const authenticator = new FakeAuthenticator()
await saveWalletMaterial(MATERIAL)
await registerPasskey(MATERIAL, {credentials: authenticator})
await saveWalletMaterial(ALTERED_ROOT, 'password')
const before = storageState()
const authenticator = new FakeAuthenticator();
await saveWalletMaterial(MATERIAL);
await registerPasskey(MATERIAL, { credentials: authenticator });
await saveWalletMaterial(ALTERED_ROOT, 'password');
const before = storageState();
await expect(unlockWalletMaterialWithPasskey({credentials: authenticator})).rejects.toThrow()
expect(storageState()).toEqual(before)
})
await expect(unlockWalletMaterialWithPasskey({ credentials: authenticator })).rejects.toThrow();
expect(storageState()).toEqual(before);
});
it('writes nothing when same-owner saved material changes during the unlock ceremony', async () => {
const authenticator = new FakeAuthenticator()
await saveWalletMaterial(MATERIAL)
await registerPasskey(MATERIAL, {credentials: authenticator})
let swapped: {slots: string | null; material: string | null} | null = null
const authenticator = new FakeAuthenticator();
await saveWalletMaterial(MATERIAL);
await registerPasskey(MATERIAL, { credentials: authenticator });
let swapped: { slots: string | null; material: string | null } | null = null;
authenticator.onGet = async () => {
await saveWalletMaterial(ALTERED_ROOT)
swapped = storageState()
}
await saveWalletMaterial(ALTERED_ROOT);
swapped = storageState();
};
await expect(unlockWalletMaterialWithPasskey({credentials: authenticator})).rejects.toThrow(
await expect(unlockWalletMaterialWithPasskey({ credentials: authenticator })).rejects.toThrow(
'changed',
)
expect(swapped).not.toBeNull()
expect(storageState()).toEqual(swapped)
})
);
expect(swapped).not.toBeNull();
expect(storageState()).toEqual(swapped);
});
it('rejects a same-owner altered-root re-wrap before changing any bytes', async () => {
const authenticator = new FakeAuthenticator()
await saveWalletMaterial(MATERIAL)
const slot = await registerPasskey(MATERIAL, {credentials: authenticator})
const before = storageState()
const authenticator = new FakeAuthenticator();
await saveWalletMaterial(MATERIAL);
const slot = await registerPasskey(MATERIAL, { credentials: authenticator });
const before = storageState();
await expect(
rewrapAllSlots(ALTERED_ROOT, new Map([[slot.credentialId, new Uint8Array(32).fill(13)]])),
).rejects.toThrow('saved wallet material')
expect(storageState()).toEqual(before)
})
).rejects.toThrow('saved wallet material');
expect(storageState()).toEqual(before);
});
it('returns the exact saved material on a committed unlock', async () => {
const authenticator = new FakeAuthenticator()
await saveWalletMaterial(MATERIAL)
await registerPasskey(MATERIAL, {credentials: authenticator})
const before = storageState()
const authenticator = new FakeAuthenticator();
await saveWalletMaterial(MATERIAL);
await registerPasskey(MATERIAL, { credentials: authenticator });
const before = storageState();
await expect(unlockWalletMaterialWithPasskey({credentials: authenticator})).resolves.toEqual(
await expect(unlockWalletMaterialWithPasskey({ credentials: authenticator })).resolves.toEqual(
MATERIAL,
)
expect(storageState()).toEqual(before)
})
})
);
expect(storageState()).toEqual(before);
});
});
src/lnurlcash/passkeys.rewrap.cases.ts
+72 -72
View File
@@ -4,12 +4,12 @@
// unguessable without the authenticator. Everything except a real
// authenticator's touch is covered here.
import {beforeEach, describe, expect, it} from 'vitest'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -23,7 +23,7 @@ import {
unlockWalletMaterialWithPasskey,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
} from './passkeys';
import {
decryptRecord,
decryptSavedLinkingKey,
@@ -35,43 +35,43 @@ import {
savedKeyOwnerId,
saveLinkingKey,
saveWalletMaterial,
} from './keys'
import {parseJsonObject, parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, parseJsonObjectArray, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// Fake platform authenticator: holds credentials (id -> secret), evaluates
// PRF as HMAC-SHA256(secret, salt). Flags emulate the authenticator quirks
// found in the wild: PRF unsupported, results only on get, results never.
class FakeAuthenticator implements PasskeyCredentials {
// id typed Uint8Array<ArrayBuffer>: rawId must satisfy BufferSource
private held = new Map<string, {id: Uint8Array<ArrayBuffer>; secret: Uint8Array}>()
supportsPrf = true
prfResultsOnCreate = true
prfResultsOnGet = true
createCalls = 0
getCalls = 0
private held = new Map<string, { id: Uint8Array<ArrayBuffer>; secret: Uint8Array }>();
supportsPrf = true;
prfResultsOnCreate = true;
prfResultsOnGet = true;
createCalls = 0;
getCalls = 0;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
this.createCalls += 1
const salt = options?.publicKey?.extensions?.prf?.eval?.first
const id = crypto.getRandomValues(new Uint8Array(16))
const secret = crypto.getRandomValues(new Uint8Array(32))
this.held.set(bytesToHex(id), {id, secret})
this.createCalls += 1;
const salt = options?.publicKey?.extensions?.prf?.eval?.first;
const id = crypto.getRandomValues(new Uint8Array(16));
const secret = crypto.getRandomValues(new Uint8Array(32));
this.held.set(bytesToHex(id), { id, secret });
return {
type: 'public-key',
rawId: id,
@@ -80,81 +80,81 @@ class FakeAuthenticator implements PasskeyCredentials {
this.supportsPrf && salt
? {
enabled: true,
...(this.prfResultsOnCreate ? {results: {first: this.prf(secret, salt)}} : {}),
...(this.prfResultsOnCreate ? { results: { first: this.prf(secret, salt) } } : {}),
}
: {},
}),
}
}
};
};
// answers with the first allowed credential it holds, like a real
// authenticator picking among allowCredentials; null when it holds none
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
this.getCalls += 1
const pk = options?.publicKey
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)))
const match = allowed.find((hex) => this.held.has(hex))
const held = match ? this.held.get(match) : undefined
if (!held) return null
const salt = pk?.extensions?.prf?.eval?.first
this.getCalls += 1;
const pk = options?.publicKey;
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)));
const match = allowed.find((hex) => this.held.has(hex));
const held = match ? this.held.get(match) : undefined;
if (!held) return null;
const salt = pk?.extensions?.prf?.eval?.first;
return {
type: 'public-key',
rawId: held.id,
getClientExtensionResults: () => ({
prf:
salt && this.prfResultsOnGet
? {enabled: true, results: {first: this.prf(held.secret, salt)}}
? { enabled: true, results: { first: this.prf(held.secret, salt) } }
: {},
}),
}
}
};
};
// simulates the passkey's secret changing underneath a slot (credential
// re-created on the authenticator while the slot stayed behind)
rotateSecret = (credentialId: string): void => {
const held = this.held.get(credentialId)
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32))
}
const held = this.held.get(credentialId);
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32));
};
private prf = (secret: Uint8Array, salt: BufferSource): Uint8Array<ArrayBuffer> => {
// set into a fresh array: hmac returns Uint8Array<ArrayBufferLike>,
// which BufferSource rejects
const out = new Uint8Array(32)
out.set(hmac(sha256, secret, toBytes(salt)))
return out
}
const out = new Uint8Array(32);
out.set(hmac(sha256, secret, toBytes(salt)));
return out;
};
}
const readRawSlots = (): Array<Record<string, unknown>> =>
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
const writeRawSlots = (slots: Array<Record<string, unknown>>): void => {
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots))
}
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots));
};
const removeSavedOwnerMarker = (): void => {
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}')
delete stored.ownerId
delete stored.version
localStorage.setItem('sattle_linking_key', JSON.stringify(stored))
}
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}');
delete stored.ownerId;
delete stored.version;
localStorage.setItem('sattle_linking_key', JSON.stringify(stored));
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
await saveWalletMaterial(MATERIAL);
});
describe('rewrap for the current owner', () => {
it('refreshes every current-owner wrap all-or-nothing', async () => {
const laptop = new FakeAuthenticator()
const phone = new FakeAuthenticator()
const laptop = new FakeAuthenticator();
const phone = new FakeAuthenticator();
const laptopSlot = await registerPasskey(MATERIAL, {
credentials: laptop,
})
});
const phoneSlot = await registerPasskey(MATERIAL, {
credentials: phone,
})
});
// partial coverage aborts before writing
const partial = new Map([
@@ -164,9 +164,9 @@ describe('rewrap for the current owner', () => {
credentials: laptop,
}),
],
])
await expect(rewrapAllSlots(MATERIAL, partial)).rejects.toThrow('partial re-wrap')
expect(await unlockWalletMaterialWithPasskey({credentials: laptop})).toEqual(MATERIAL)
]);
await expect(rewrapAllSlots(MATERIAL, partial)).rejects.toThrow('partial re-wrap');
expect(await unlockWalletMaterialWithPasskey({ credentials: laptop })).toEqual(MATERIAL);
// full coverage refreshes both wraps around the same proven owner key
const fresh = new Map([
@@ -182,16 +182,16 @@ describe('rewrap for the current owner', () => {
credentials: phone,
}),
],
])
await rewrapAllSlots(MATERIAL, fresh)
expect(await unlockWalletMaterialWithPasskey({credentials: laptop})).toEqual(MATERIAL)
expect(await unlockWalletMaterialWithPasskey({credentials: phone})).toEqual(MATERIAL)
expect(readPasskeySlots()[0]?.wrappedMaterial).not.toBe(laptopSlot.wrappedMaterial)
]);
await rewrapAllSlots(MATERIAL, fresh);
expect(await unlockWalletMaterialWithPasskey({ credentials: laptop })).toEqual(MATERIAL);
expect(await unlockWalletMaterialWithPasskey({ credentials: phone })).toEqual(MATERIAL);
expect(readPasskeySlots()[0]?.wrappedMaterial).not.toBe(laptopSlot.wrappedMaterial);
// credential ids and labels survive the re-wrap
expect(
readPasskeySlots()
.map((s) => s.credentialId)
.sort(),
).toEqual([laptopSlot.credentialId, phoneSlot.credentialId].sort())
})
})
).toEqual([laptopSlot.credentialId, phoneSlot.credentialId].sort());
});
});
src/lnurlcash/passkeys.storage.cases.ts
+74 -69
View File
@@ -4,12 +4,12 @@
// unguessable without the authenticator. Everything except a real
// authenticator's touch is covered here.
import {beforeEach, describe, expect, it} from 'vitest'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -22,7 +22,7 @@ import {
rewrapAllSlots,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
} from './passkeys';
import {
decryptRecord,
decryptSavedLinkingKey,
@@ -34,43 +34,48 @@ import {
savedKeyOwnerId,
saveLinkingKey,
saveWalletMaterial,
} from './keys'
import {parseJsonArray, parseJsonObject, parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import {
parseJsonArray,
parseJsonObject,
parseJsonObjectArray,
stubLocalStorage,
} from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// Fake platform authenticator: holds credentials (id -> secret), evaluates
// PRF as HMAC-SHA256(secret, salt). Flags emulate the authenticator quirks
// found in the wild: PRF unsupported, results only on get, results never.
class FakeAuthenticator implements PasskeyCredentials {
// id typed Uint8Array<ArrayBuffer>: rawId must satisfy BufferSource
private held = new Map<string, {id: Uint8Array<ArrayBuffer>; secret: Uint8Array}>()
supportsPrf = true
prfResultsOnCreate = true
prfResultsOnGet = true
createCalls = 0
getCalls = 0
private held = new Map<string, { id: Uint8Array<ArrayBuffer>; secret: Uint8Array }>();
supportsPrf = true;
prfResultsOnCreate = true;
prfResultsOnGet = true;
createCalls = 0;
getCalls = 0;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
this.createCalls += 1
const salt = options?.publicKey?.extensions?.prf?.eval?.first
const id = crypto.getRandomValues(new Uint8Array(16))
const secret = crypto.getRandomValues(new Uint8Array(32))
this.held.set(bytesToHex(id), {id, secret})
this.createCalls += 1;
const salt = options?.publicKey?.extensions?.prf?.eval?.first;
const id = crypto.getRandomValues(new Uint8Array(16));
const secret = crypto.getRandomValues(new Uint8Array(32));
this.held.set(bytesToHex(id), { id, secret });
return {
type: 'public-key',
rawId: id,
@@ -79,86 +84,86 @@ class FakeAuthenticator implements PasskeyCredentials {
this.supportsPrf && salt
? {
enabled: true,
...(this.prfResultsOnCreate ? {results: {first: this.prf(secret, salt)}} : {}),
...(this.prfResultsOnCreate ? { results: { first: this.prf(secret, salt) } } : {}),
}
: {},
}),
}
}
};
};
// answers with the first allowed credential it holds, like a real
// authenticator picking among allowCredentials; null when it holds none
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
this.getCalls += 1
const pk = options?.publicKey
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)))
const match = allowed.find((hex) => this.held.has(hex))
const held = match ? this.held.get(match) : undefined
if (!held) return null
const salt = pk?.extensions?.prf?.eval?.first
this.getCalls += 1;
const pk = options?.publicKey;
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)));
const match = allowed.find((hex) => this.held.has(hex));
const held = match ? this.held.get(match) : undefined;
if (!held) return null;
const salt = pk?.extensions?.prf?.eval?.first;
return {
type: 'public-key',
rawId: held.id,
getClientExtensionResults: () => ({
prf:
salt && this.prfResultsOnGet
? {enabled: true, results: {first: this.prf(held.secret, salt)}}
? { enabled: true, results: { first: this.prf(held.secret, salt) } }
: {},
}),
}
}
};
};
// simulates the passkey's secret changing underneath a slot (credential
// re-created on the authenticator while the slot stayed behind)
rotateSecret = (credentialId: string): void => {
const held = this.held.get(credentialId)
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32))
}
const held = this.held.get(credentialId);
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32));
};
private prf = (secret: Uint8Array, salt: BufferSource): Uint8Array<ArrayBuffer> => {
// set into a fresh array: hmac returns Uint8Array<ArrayBufferLike>,
// which BufferSource rejects
const out = new Uint8Array(32)
out.set(hmac(sha256, secret, toBytes(salt)))
return out
}
const out = new Uint8Array(32);
out.set(hmac(sha256, secret, toBytes(salt)));
return out;
};
}
const readRawSlots = (): Array<Record<string, unknown>> =>
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
const writeRawSlots = (slots: Array<Record<string, unknown>>): void => {
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots))
}
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots));
};
const removeSavedOwnerMarker = (): void => {
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}')
delete stored.ownerId
delete stored.version
localStorage.setItem('sattle_linking_key', JSON.stringify(stored))
}
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}');
delete stored.ownerId;
delete stored.version;
localStorage.setItem('sattle_linking_key', JSON.stringify(stored));
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
await saveWalletMaterial(MATERIAL);
});
describe('slot storage hygiene', () => {
it('drops malformed entries instead of throwing', async () => {
const auth = new FakeAuthenticator()
const slot = await registerPasskey(MATERIAL, {credentials: auth})
const stored = parseJsonArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
const auth = new FakeAuthenticator();
const slot = await registerPasskey(MATERIAL, { credentials: auth });
const stored = parseJsonArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
localStorage.setItem(
'sattle_passkey_slots',
JSON.stringify([...stored, {credentialId: 'zz', hkdfSalt: 1}, 'garbage', null]),
)
expect(readPasskeySlots()).toEqual([slot])
})
JSON.stringify([...stored, { credentialId: 'zz', hkdfSalt: 1 }, 'garbage', null]),
);
expect(readPasskeySlots()).toEqual([slot]);
});
it('treats unparseable storage as empty', () => {
localStorage.setItem('sattle_passkey_slots', '{not json')
expect(readPasskeySlots()).toEqual([])
expect(hasPasskeySlots()).toBe(false)
})
})
localStorage.setItem('sattle_passkey_slots', '{not json');
expect(readPasskeySlots()).toEqual([]);
expect(hasPasskeySlots()).toBe(false);
});
});
src/lnurlcash/passkeys.support.cases.ts
+71 -71
View File
@@ -4,12 +4,12 @@
// unguessable without the authenticator. Everything except a real
// authenticator's touch is covered here.
import {beforeEach, describe, expect, it} from 'vitest'
import {hmac} from '@noble/hashes/hmac.js'
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { hmac } from '@noble/hashes/hmac.js';
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex } from '@noble/hashes/utils.js';
import type {CeremonyCredential, PasskeyCredentials} from './passkeys'
import type { CeremonyCredential, PasskeyCredentials } from './passkeys';
import {
derivePasskeyWrapKey,
getPasskeyPrfOutput,
@@ -22,7 +22,7 @@ import {
rewrapAllSlots,
unwrapWalletMaterialWithPrf,
wrapWalletMaterialWithPrf,
} from './passkeys'
} from './passkeys';
import {
decryptRecord,
decryptSavedLinkingKey,
@@ -34,43 +34,43 @@ import {
savedKeyOwnerId,
saveLinkingKey,
saveWalletMaterial,
} from './keys'
import {parseJsonObject, parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import { parseJsonObject, parseJsonObjectArray, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const PRF_OUTPUT = new Uint8Array(32).fill(3)
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const PRF_OUTPUT = new Uint8Array(32).fill(3);
const OTHER_PRF_OUTPUT = new Uint8Array(32).fill(4);
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// Fake platform authenticator: holds credentials (id -> secret), evaluates
// PRF as HMAC-SHA256(secret, salt). Flags emulate the authenticator quirks
// found in the wild: PRF unsupported, results only on get, results never.
class FakeAuthenticator implements PasskeyCredentials {
// id typed Uint8Array<ArrayBuffer>: rawId must satisfy BufferSource
private held = new Map<string, {id: Uint8Array<ArrayBuffer>; secret: Uint8Array}>()
supportsPrf = true
prfResultsOnCreate = true
prfResultsOnGet = true
createCalls = 0
getCalls = 0
private held = new Map<string, { id: Uint8Array<ArrayBuffer>; secret: Uint8Array }>();
supportsPrf = true;
prfResultsOnCreate = true;
prfResultsOnGet = true;
createCalls = 0;
getCalls = 0;
create = async (options?: CredentialCreationOptions): Promise<CeremonyCredential | null> => {
this.createCalls += 1
const salt = options?.publicKey?.extensions?.prf?.eval?.first
const id = crypto.getRandomValues(new Uint8Array(16))
const secret = crypto.getRandomValues(new Uint8Array(32))
this.held.set(bytesToHex(id), {id, secret})
this.createCalls += 1;
const salt = options?.publicKey?.extensions?.prf?.eval?.first;
const id = crypto.getRandomValues(new Uint8Array(16));
const secret = crypto.getRandomValues(new Uint8Array(32));
this.held.set(bytesToHex(id), { id, secret });
return {
type: 'public-key',
rawId: id,
@@ -79,110 +79,110 @@ class FakeAuthenticator implements PasskeyCredentials {
this.supportsPrf && salt
? {
enabled: true,
...(this.prfResultsOnCreate ? {results: {first: this.prf(secret, salt)}} : {}),
...(this.prfResultsOnCreate ? { results: { first: this.prf(secret, salt) } } : {}),
}
: {},
}),
}
}
};
};
// answers with the first allowed credential it holds, like a real
// authenticator picking among allowCredentials; null when it holds none
get = async (options?: CredentialRequestOptions): Promise<CeremonyCredential | null> => {
this.getCalls += 1
const pk = options?.publicKey
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)))
const match = allowed.find((hex) => this.held.has(hex))
const held = match ? this.held.get(match) : undefined
if (!held) return null
const salt = pk?.extensions?.prf?.eval?.first
this.getCalls += 1;
const pk = options?.publicKey;
const allowed = (pk?.allowCredentials ?? []).map((d) => bytesToHex(toBytes(d.id)));
const match = allowed.find((hex) => this.held.has(hex));
const held = match ? this.held.get(match) : undefined;
if (!held) return null;
const salt = pk?.extensions?.prf?.eval?.first;
return {
type: 'public-key',
rawId: held.id,
getClientExtensionResults: () => ({
prf:
salt && this.prfResultsOnGet
? {enabled: true, results: {first: this.prf(held.secret, salt)}}
? { enabled: true, results: { first: this.prf(held.secret, salt) } }
: {},
}),
}
}
};
};
// simulates the passkey's secret changing underneath a slot (credential
// re-created on the authenticator while the slot stayed behind)
rotateSecret = (credentialId: string): void => {
const held = this.held.get(credentialId)
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32))
}
const held = this.held.get(credentialId);
if (held) held.secret = crypto.getRandomValues(new Uint8Array(32));
};
private prf = (secret: Uint8Array, salt: BufferSource): Uint8Array<ArrayBuffer> => {
// set into a fresh array: hmac returns Uint8Array<ArrayBufferLike>,
// which BufferSource rejects
const out = new Uint8Array(32)
out.set(hmac(sha256, secret, toBytes(salt)))
return out
}
const out = new Uint8Array(32);
out.set(hmac(sha256, secret, toBytes(salt)));
return out;
};
}
const readRawSlots = (): Array<Record<string, unknown>> =>
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]')
parseJsonObjectArray(localStorage.getItem('sattle_passkey_slots') ?? '[]');
const writeRawSlots = (slots: Array<Record<string, unknown>>): void => {
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots))
}
localStorage.setItem('sattle_passkey_slots', JSON.stringify(slots));
};
const removeSavedOwnerMarker = (): void => {
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}')
delete stored.ownerId
delete stored.version
localStorage.setItem('sattle_linking_key', JSON.stringify(stored))
}
const stored = parseJsonObject(localStorage.getItem('sattle_linking_key') ?? '{}');
delete stored.ownerId;
delete stored.version;
localStorage.setItem('sattle_linking_key', JSON.stringify(stored));
};
beforeEach(async () => {
stubLocalStorage()
await saveLinkingKey(LINKING_KEY)
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveLinkingKey(LINKING_KEY);
await saveWalletMaterial(MATERIAL);
});
describe('passkeySupported', () => {
it('is false without a PublicKeyCredential probe', async () => {
// node test env has no PublicKeyCredential global: the default lookup
// finds nothing
await expect(passkeySupported()).resolves.toBe(false)
})
await expect(passkeySupported()).resolves.toBe(false);
});
it('is false without a user-verifying platform authenticator', async () => {
await expect(
passkeySupported({
isUserVerifyingPlatformAuthenticatorAvailable: async () => false,
getClientCapabilities: async () => ({'extension:prf': true}),
getClientCapabilities: async () => ({ 'extension:prf': true }),
}),
).resolves.toBe(false)
})
).resolves.toBe(false);
});
it('checks extension:prf when client capabilities are available', async () => {
const platform = {
isUserVerifyingPlatformAuthenticatorAvailable: async () => true,
}
};
await expect(
passkeySupported({
...platform,
getClientCapabilities: async () => ({'extension:prf': true}),
getClientCapabilities: async () => ({ 'extension:prf': true }),
}),
).resolves.toBe(true)
).resolves.toBe(true);
await expect(
passkeySupported({
...platform,
getClientCapabilities: async () => ({'extension:prf': false}),
getClientCapabilities: async () => ({ 'extension:prf': false }),
}),
).resolves.toBe(false)
})
).resolves.toBe(false);
});
it('is optimistic when capabilities cannot be pre-detected', async () => {
await expect(
passkeySupported({
isUserVerifyingPlatformAuthenticatorAvailable: async () => true,
}),
).resolves.toBe(true)
})
})
).resolves.toBe(true);
});
});
src/lnurlcash/passkeys.test.ts
+12 -12
View File
@@ -1,12 +1,12 @@
import './passkeys.crypto.cases'
import './passkeys.commitment.cases'
import './passkeys.reverify.cases'
import './passkeys.material.cases'
import './passkeys.registration.cases'
import './passkeys.ownership-a.cases'
import './passkeys.ownership-b.cases'
import './passkeys.multiple.cases'
import './passkeys.rewrap.cases'
import './passkeys.storage.cases'
import './passkeys.support.cases'
import './passkeys.version.cases'
import './passkeys.crypto.cases';
import './passkeys.commitment.cases';
import './passkeys.reverify.cases';
import './passkeys.material.cases';
import './passkeys.registration.cases';
import './passkeys.ownership-a.cases';
import './passkeys.ownership-b.cases';
import './passkeys.multiple.cases';
import './passkeys.rewrap.cases';
import './passkeys.storage.cases';
import './passkeys.support.cases';
import './passkeys.version.cases';
src/lnurlcash/passkeys.ts
+115 -113
View File
@@ -21,11 +21,11 @@
// an independent, unguessable wrap secret. A per-slot random HKDF salt then
// separates the actual wrap keys.
import {sha256} from '@noble/hashes/sha2.js'
import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
import { sha256 } from '@noble/hashes/sha2.js';
import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
import {withStorageLock} from './storageLock'
import type {PasskeySlot} from './storage/passkeySlots'
import { withStorageLock } from './storageLock';
import type { PasskeySlot } from './storage/passkeySlots';
import {
PASSKEY_SLOTS_STORAGE_KEY,
PASSKEY_SLOT_VERSION,
@@ -33,67 +33,67 @@ import {
readPasskeySlots,
requireCurrentPasskeyMaterialOwner,
writePasskeySlots,
} from './storage/passkeySlots'
import type {WalletMaterialV2} from './storage/storedSecret'
import {walletMaterialHash, walletMaterialOwnerId} from './storage/storedSecret'
import {savedWalletMaterialHash, savedWalletMaterialOwnerId} from './walletMaterialStorage'
import {unwrapWalletMaterialWithPrf, wrapWalletMaterialWithPrf} from './passkeyWrap'
} from './storage/passkeySlots';
import type { WalletMaterialV2 } from './storage/storedSecret';
import { walletMaterialHash, walletMaterialOwnerId } from './storage/storedSecret';
import { savedWalletMaterialHash, savedWalletMaterialOwnerId } from './walletMaterialStorage';
import { unwrapWalletMaterialWithPrf, wrapWalletMaterialWithPrf } from './passkeyWrap';
export type {PasskeySlot, PasskeyWrap} from './storage/passkeySlots'
export {readPasskeySlots, hasPasskeySlots} from './storage/passkeySlots'
export {migrateLegacyPasskeySlots} from './passkeyOwnership'
export {rewrapAllSlots} from './passkeyRewrap'
export type { PasskeySlot, PasskeyWrap } from './storage/passkeySlots';
export { readPasskeySlots, hasPasskeySlots } from './storage/passkeySlots';
export { migrateLegacyPasskeySlots } from './passkeyOwnership';
export { rewrapAllSlots } from './passkeyRewrap';
export {
derivePasskeyWrapKey,
InvalidPasskeyMaterialError,
wrapWalletMaterialWithPrf,
unwrapWalletMaterialWithPrf,
} from './passkeyWrap'
} from './passkeyWrap';
// 32 bytes, fixed - the authenticator requires exactly 32
const PASSKEY_PRF_SALT = sha256(utf8ToBytes('sattle-passkey-prf-v1'))
const PASSKEY_PRF_SALT = sha256(utf8ToBytes('sattle-passkey-prf-v1'));
// ---- WebAuthn glue (browser-only; credentials container injected) ----
// the structural slice of a PublicKeyCredential the engine consumes - a
// fake authenticator in tests implements exactly this
export type CeremonyCredential = {
type: string
rawId: BufferSource
getClientExtensionResults(): AuthenticationExtensionsClientOutputs
}
type: string;
rawId: BufferSource;
getClientExtensionResults(): AuthenticationExtensionsClientOutputs;
};
// the slice of navigator.credentials the ceremonies need
export type PasskeyCredentials = {
create(options?: CredentialCreationOptions): Promise<CeremonyCredential | null>
get(options?: CredentialRequestOptions): Promise<CeremonyCredential | null>
}
create(options?: CredentialCreationOptions): Promise<CeremonyCredential | null>;
get(options?: CredentialRequestOptions): Promise<CeremonyCredential | null>;
};
export type PasskeySupportProbe = {
isUserVerifyingPlatformAuthenticatorAvailable(): Promise<boolean>
getClientCapabilities?(): Promise<Record<string, boolean>>
}
isUserVerifyingPlatformAuthenticatorAvailable(): Promise<boolean>;
getClientCapabilities?(): Promise<Record<string, boolean>>;
};
// the one runtime narrow at the browser boundary: navigator.credentials
// resolves to the Credential supertype, but a publicKey ceremony always
// produces a PublicKeyCredential
const asCeremonyCredential = (credential: Credential | null): CeremonyCredential | null => {
if (typeof PublicKeyCredential === 'undefined' || !(credential instanceof PublicKeyCredential)) {
return null
return null;
}
return credential
}
return credential;
};
const defaultCredentials = (): PasskeyCredentials => {
if (typeof navigator === 'undefined' || !navigator.credentials) {
throw new Error('WebAuthn is not available in this environment.')
throw new Error('WebAuthn is not available in this environment.');
}
const container = navigator.credentials
const container = navigator.credentials;
return {
create: (options) => container.create(options).then(asCeremonyCredential),
get: (options) => container.get(options).then(asCeremonyCredential),
}
}
};
};
// Feature detection: a user-verifying platform authenticator (Touch ID,
// Windows Hello, Android biometrics) plus the PRF extension. PRF has no
@@ -101,56 +101,56 @@ const defaultCredentials = (): PasskeyCredentials => {
// exists we can ask for it, elsewhere this returns true optimistically and
// registration itself fails with a clear error.
export const passkeySupported = async (probe?: PasskeySupportProbe): Promise<boolean> => {
const p = probe ?? (typeof PublicKeyCredential !== 'undefined' ? PublicKeyCredential : undefined)
if (!p) return false
if (!(await p.isUserVerifyingPlatformAuthenticatorAvailable())) return false
const p = probe ?? (typeof PublicKeyCredential !== 'undefined' ? PublicKeyCredential : undefined);
if (!p) return false;
if (!(await p.isUserVerifyingPlatformAuthenticatorAvailable())) return false;
if (p.getClientCapabilities) {
const capabilities = await p.getClientCapabilities()
return capabilities['extension:prf'] === true
const capabilities = await p.getClientCapabilities();
return capabilities['extension:prf'] === true;
}
return true
}
return true;
};
const toBytes = (source: BufferSource): Uint8Array =>
source instanceof ArrayBuffer
? new Uint8Array(source)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
: new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
// pulls the evaluated PRF secret out of a ceremony result; null when the
// authenticator did not evaluate the extension (no hmac-secret support)
const prfOutputOf = (credential: CeremonyCredential): Uint8Array | null => {
const first = credential.getClientExtensionResults().prf?.results?.first
return first ? toBytes(first) : null
}
const first = credential.getClientExtensionResults().prf?.results?.first;
return first ? toBytes(first) : null;
};
// one get() ceremony against a single known credential, returning its fresh
// PRF output - the building block for complete-material re-wrap ceremonies
export const getPasskeyPrfOutput = async (
credentialId: string,
options: {credentials?: PasskeyCredentials} = {},
options: { credentials?: PasskeyCredentials } = {},
): Promise<Uint8Array> => {
const credentials = options.credentials ?? defaultCredentials()
const credentials = options.credentials ?? defaultCredentials();
const assertion = await credentials.get({
publicKey: {
challenge: crypto.getRandomValues(new Uint8Array(32)),
allowCredentials: [{type: 'public-key', id: new Uint8Array(hexToBytes(credentialId))}],
allowCredentials: [{ type: 'public-key', id: new Uint8Array(hexToBytes(credentialId)) }],
userVerification: 'required',
extensions: {prf: {eval: {first: PASSKEY_PRF_SALT}}},
extensions: { prf: { eval: { first: PASSKEY_PRF_SALT } } },
},
})
if (!assertion) throw new Error('Passkey ceremony was cancelled.')
const prfOutput = prfOutputOf(assertion)
});
if (!assertion) throw new Error('Passkey ceremony was cancelled.');
const prfOutput = prfOutputOf(assertion);
if (!prfOutput) {
throw new Error('This passkey did not return a PRF secret - it cannot unlock this wallet.')
throw new Error('This passkey did not return a PRF secret - it cannot unlock this wallet.');
}
return prfOutput
}
return prfOutput;
};
export type RegisterPasskeyOptions = {
credentials?: PasskeyCredentials
name?: string
authenticatorAttachment?: AuthenticatorAttachment
}
credentials?: PasskeyCredentials;
name?: string;
authenticatorAttachment?: AuthenticatorAttachment;
};
// Registers a new passkey and persists a slot wrapping the complete material.
// The ceremony is navigator.credentials.create with the PRF
@@ -161,12 +161,12 @@ export const registerPasskey = async (
material: WalletMaterialV2,
options: RegisterPasskeyOptions = {},
): Promise<PasskeySlot> => {
const ownerId = requireCurrentPasskeyMaterialOwner(material)
const credentials = options.credentials ?? defaultCredentials()
const ownerId = requireCurrentPasskeyMaterialOwner(material);
const credentials = options.credentials ?? defaultCredentials();
const credential = await credentials.create({
publicKey: {
challenge: crypto.getRandomValues(new Uint8Array(32)),
rp: {name: 'sattle'},
rp: { name: 'sattle' },
user: {
// random per registration: slots address credentials by id, no
// discoverable-credential login is used
@@ -175,8 +175,8 @@ export const registerPasskey = async (
displayName: 'sattle wallet',
},
pubKeyCredParams: [
{type: 'public-key', alg: -7}, // ES256
{type: 'public-key', alg: -257}, // RS256
{ type: 'public-key', alg: -7 }, // ES256
{ type: 'public-key', alg: -257 }, // RS256
],
authenticatorSelection: {
authenticatorAttachment: options.authenticatorAttachment ?? 'platform',
@@ -184,54 +184,54 @@ export const registerPasskey = async (
userVerification: 'required',
},
attestation: 'none',
extensions: {prf: {eval: {first: PASSKEY_PRF_SALT}}},
extensions: { prf: { eval: { first: PASSKEY_PRF_SALT } } },
},
})
if (!credential) throw new Error('Passkey registration was cancelled.')
const credentialId = bytesToHex(toBytes(credential.rawId))
let prfOutput = prfOutputOf(credential)
});
if (!credential) throw new Error('Passkey registration was cancelled.');
const credentialId = bytesToHex(toBytes(credential.rawId));
let prfOutput = prfOutputOf(credential);
if (!prfOutput) {
if (credential.getClientExtensionResults().prf?.enabled !== true) {
throw new Error('This authenticator does not support the WebAuthn PRF extension.')
throw new Error('This authenticator does not support the WebAuthn PRF extension.');
}
prfOutput = await getPasskeyPrfOutput(credentialId, {credentials})
prfOutput = await getPasskeyPrfOutput(credentialId, { credentials });
}
const wrap = await wrapWalletMaterialWithPrf(prfOutput, material)
const wrap = await wrapWalletMaterialWithPrf(prfOutput, material);
const slot: PasskeySlot = {
credentialId,
...wrap,
createdAt: Date.now(),
...(options.name !== undefined ? {name: options.name} : {}),
...(options.name !== undefined ? { name: options.name } : {}),
ownerId,
version: PASSKEY_SLOT_VERSION,
}
};
await withStorageLock(PASSKEY_SLOTS_STORAGE_KEY, () => {
if (requireCurrentPasskeyMaterialOwner(material) !== ownerId) {
throw new Error('Saved wallet material changed during passkey registration.')
throw new Error('Saved wallet material changed during passkey registration.');
}
const slots = readPasskeySlots().filter((s) => s.credentialId !== credentialId)
slots.push(slot)
writePasskeySlots(ownerId, slots)
})
return slot
}
const slots = readPasskeySlots().filter((s) => s.credentialId !== credentialId);
slots.push(slot);
writePasskeySlots(ownerId, slots);
});
return slot;
};
// Unlocks complete material via one get() ceremony offering every current
// slot. The selected slot is re-read after the ceremony before any plaintext
// reaches the caller, rejecting owner or storage changes during user presence.
export const unlockWalletMaterialWithPasskey = async (
options: {credentials?: PasskeyCredentials} = {},
options: { credentials?: PasskeyCredentials } = {},
): Promise<WalletMaterialV2> => {
const ownerId = savedWalletMaterialOwnerId()
const materialHash = savedWalletMaterialHash()
const slots = readPasskeySlots()
const ownerId = savedWalletMaterialOwnerId();
const materialHash = savedWalletMaterialHash();
const slots = readPasskeySlots();
if (ownerId === null || materialHash === null || slots.length === 0) {
throw new Error('No passkeys registered on this device.')
throw new Error('No passkeys registered on this device.');
}
if (slots.some((slot) => slot.materialHash !== materialHash)) {
throw new Error('Passkey slot belongs to different wallet material.')
throw new Error('Passkey slot belongs to different wallet material.');
}
const credentials = options.credentials ?? defaultCredentials()
const credentials = options.credentials ?? defaultCredentials();
const assertion = await credentials.get({
publicKey: {
challenge: crypto.getRandomValues(new Uint8Array(32)),
@@ -240,51 +240,53 @@ export const unlockWalletMaterialWithPasskey = async (
id: new Uint8Array(hexToBytes(slot.credentialId)),
})),
userVerification: 'required',
extensions: {prf: {eval: {first: PASSKEY_PRF_SALT}}},
extensions: { prf: { eval: { first: PASSKEY_PRF_SALT } } },
},
})
if (!assertion) throw new Error('Passkey ceremony was cancelled.')
const credentialId = bytesToHex(toBytes(assertion.rawId))
const slot = slots.find((s) => s.credentialId === credentialId)
});
if (!assertion) throw new Error('Passkey ceremony was cancelled.');
const credentialId = bytesToHex(toBytes(assertion.rawId));
const slot = slots.find((s) => s.credentialId === credentialId);
if (!slot) {
throw new Error('The passkey used is not registered with this wallet.')
throw new Error('The passkey used is not registered with this wallet.');
}
const prfOutput = prfOutputOf(assertion)
const prfOutput = prfOutputOf(assertion);
if (!prfOutput) {
throw new Error('This passkey did not return a PRF secret - it cannot unlock this wallet.')
throw new Error('This passkey did not return a PRF secret - it cannot unlock this wallet.');
}
if (savedWalletMaterialOwnerId() !== ownerId) {
throw new Error('This passkey belongs to a different wallet.')
throw new Error('This passkey belongs to a different wallet.');
}
if (savedWalletMaterialHash() !== materialHash) {
throw new Error('Saved wallet material changed during the unlock ceremony.')
throw new Error('Saved wallet material changed during the unlock ceremony.');
}
const currentSlot = readPasskeySlots().find((candidate) => candidate.credentialId === credentialId)
const currentSlot = readPasskeySlots().find(
(candidate) => candidate.credentialId === credentialId,
);
if (currentSlot === undefined || !passkeySlotsEqual(slot, currentSlot)) {
throw new Error('The passkey slot changed during the unlock ceremony.')
throw new Error('The passkey slot changed during the unlock ceremony.');
}
const material = await unwrapWalletMaterialWithPrf(prfOutput, currentSlot)
const material = await unwrapWalletMaterialWithPrf(prfOutput, currentSlot);
if (savedWalletMaterialOwnerId() !== ownerId || walletMaterialOwnerId(material) !== ownerId) {
throw new Error('This passkey belongs to a different wallet.')
throw new Error('This passkey belongs to a different wallet.');
}
if (savedWalletMaterialHash() !== materialHash || walletMaterialHash(material) !== materialHash) {
throw new Error('Saved wallet material changed during the unlock ceremony.')
throw new Error('Saved wallet material changed during the unlock ceremony.');
}
return material
}
return material;
};
// Removes the slot only: WebAuthn has no API to delete the credential from
// the authenticator - an orphaned passkey simply finds nothing to unwrap.
// Returns whether a slot was actually removed.
export const removePasskey = async (credentialId: string): Promise<boolean> => {
const ownerId = savedWalletMaterialOwnerId()
if (ownerId === null) return false
let removed = false
const ownerId = savedWalletMaterialOwnerId();
if (ownerId === null) return false;
let removed = false;
await withStorageLock(PASSKEY_SLOTS_STORAGE_KEY, () => {
const slots = readPasskeySlots()
const kept = slots.filter((s) => s.credentialId !== credentialId)
removed = kept.length !== slots.length
if (removed) writePasskeySlots(ownerId, kept)
})
return removed
}
const slots = readPasskeySlots();
const kept = slots.filter((s) => s.credentialId !== credentialId);
removed = kept.length !== slots.length;
if (removed) writePasskeySlots(ownerId, kept);
});
return removed;
};
src/lnurlcash/passkeys.version.cases.ts
+50 -50
View File
@@ -1,5 +1,5 @@
import {beforeEach, describe, expect, it} from 'vitest'
import {bytesToHex} from '@noble/hashes/utils.js'
import { beforeEach, describe, expect, it } from 'vitest';
import { bytesToHex } from '@noble/hashes/utils.js';
import {
deriveWalletMaterial,
@@ -9,21 +9,21 @@ import {
savedWalletMaterialOwnerId,
saveWalletMaterial,
walletMaterialHash,
} from './keys'
import {migrateLegacyPasskeySlots, readPasskeySlots} from './passkeys'
import type {PasskeySlot} from './passkeys'
import {parseJsonObjectArray, stubLocalStorage} from './test-utils'
} from './keys';
import { migrateLegacyPasskeySlots, readPasskeySlots } from './passkeys';
import type { PasskeySlot } from './passkeys';
import { parseJsonObjectArray, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9)
const MATERIAL_STORAGE = 'sattle_wallet_material_v2'
const SLOT_STORAGE = 'sattle_passkey_slots'
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_LINKING_KEY = new Uint8Array(32).fill(9);
const MATERIAL_STORAGE = 'sattle_wallet_material_v2';
const SLOT_STORAGE = 'sattle_passkey_slots';
const MATERIAL = {
...deriveWalletMaterial(
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
const SLOT_BASE = {
credentialId: '11'.repeat(16),
@@ -32,76 +32,76 @@ const SLOT_BASE = {
materialHash: walletMaterialHash(MATERIAL),
wrappedMaterial: '55'.repeat(128),
createdAt: 1,
} as const
} as const;
const writeRawSlots = (slots: readonly Record<string, unknown>[]): void => {
localStorage.setItem(SLOT_STORAGE, JSON.stringify(slots))
}
localStorage.setItem(SLOT_STORAGE, JSON.stringify(slots));
};
// strips the v2 record's owner marker back to the unproven post-restore form
const removeSavedOwnerMarker = (): void => {
const stored: unknown = JSON.parse(localStorage.getItem(MATERIAL_STORAGE) ?? '{}')
if (typeof stored !== 'object' || stored === null) throw new TypeError('expected a record')
const stripped: Record<string, unknown> = {...stored}
delete stripped.ownerId
delete stripped.version
localStorage.setItem(MATERIAL_STORAGE, JSON.stringify(stripped))
}
const stored: unknown = JSON.parse(localStorage.getItem(MATERIAL_STORAGE) ?? '{}');
if (typeof stored !== 'object' || stored === null) throw new TypeError('expected a record');
const stripped: Record<string, unknown> = { ...stored };
delete stripped.ownerId;
delete stripped.version;
localStorage.setItem(MATERIAL_STORAGE, JSON.stringify(stripped));
};
describe('passkey-slot schema version', () => {
beforeEach(async () => {
stubLocalStorage()
await saveWalletMaterial(MATERIAL)
})
stubLocalStorage();
await saveWalletMaterial(MATERIAL);
});
it('reads a current version 2 slot for the exact saved owner', () => {
// Given a current saved-material owner marker and passkey record
const ownerId = linkingPubKeyHex(LINKING_KEY)
const slot: PasskeySlot = {...SLOT_BASE, ownerId, version: 2}
writeRawSlots([slot])
const ownerId = linkingPubKeyHex(LINKING_KEY);
const slot: PasskeySlot = { ...SLOT_BASE, ownerId, version: 2 };
writeRawSlots([slot]);
// When current-owner slots are read
// Then the recognized version is exposed unchanged
expect(readPasskeySlots()).toEqual([slot])
})
expect(readPasskeySlots()).toEqual([slot]);
});
it('upgrades markerless and unversioned same-owner slots only after saved-material proof', async () => {
// Given records written before schema versioning and a saved material
// whose owner marker was never proven (the post-restore form)
const ownerId = linkingPubKeyHex(LINKING_KEY)
removeSavedOwnerMarker()
writeRawSlots([SLOT_BASE, {...SLOT_BASE, credentialId: '55'.repeat(16), ownerId}])
const ownerId = linkingPubKeyHex(LINKING_KEY);
removeSavedOwnerMarker();
writeRawSlots([SLOT_BASE, { ...SLOT_BASE, credentialId: '55'.repeat(16), ownerId }]);
// When migration is attempted before and after the saved material proves ownership
await expect(migrateLegacyPasskeySlots(LINKING_KEY)).rejects.toThrow('proven owner')
const provenMaterial = getPlainWalletMaterial()
if (provenMaterial === null) throw new Error('expected the compatible plaintext material')
ensureSavedWalletMaterialOwner(provenMaterial)
await migrateLegacyPasskeySlots(LINKING_KEY)
await expect(migrateLegacyPasskeySlots(LINKING_KEY)).rejects.toThrow('proven owner');
const provenMaterial = getPlainWalletMaterial();
if (provenMaterial === null) throw new Error('expected the compatible plaintext material');
ensureSavedWalletMaterialOwner(provenMaterial);
await migrateLegacyPasskeySlots(LINKING_KEY);
// Then both compatible legacy forms become current records
expect(savedWalletMaterialOwnerId()).toBe(ownerId)
expect(savedWalletMaterialOwnerId()).toBe(ownerId);
expect(parseJsonObjectArray(localStorage.getItem(SLOT_STORAGE) ?? '[]')).toEqual([
{...SLOT_BASE, ownerId, version: 2},
{...SLOT_BASE, credentialId: '55'.repeat(16), ownerId, version: 2},
])
})
{ ...SLOT_BASE, ownerId, version: 2 },
{ ...SLOT_BASE, credentialId: '55'.repeat(16), ownerId, version: 2 },
]);
});
it.each([1, 3, '2', null])('hides unsupported or malformed version %j', (version) => {
// Given an otherwise valid slot carrying unrecognized metadata
const ownerId = linkingPubKeyHex(LINKING_KEY)
writeRawSlots([{...SLOT_BASE, ownerId, version}])
const ownerId = linkingPubKeyHex(LINKING_KEY);
writeRawSlots([{ ...SLOT_BASE, ownerId, version }]);
// When slots are parsed
// Then future or malformed records are unavailable and not downgraded to legacy
expect(readPasskeySlots()).toEqual([])
})
expect(readPasskeySlots()).toEqual([]);
});
it('hides a foreign version 1 slot from the current owner', () => {
// Given the saved owner and slot owner differ
writeRawSlots([{...SLOT_BASE, ownerId: linkingPubKeyHex(OTHER_LINKING_KEY), version: 2}])
writeRawSlots([{ ...SLOT_BASE, ownerId: linkingPubKeyHex(OTHER_LINKING_KEY), version: 2 }]);
// When the current wallet reads passkeys
// Then the foreign credential is unavailable
expect(readPasskeySlots()).toEqual([])
})
})
expect(readPasskeySlots()).toEqual([]);
});
});
src/lnurlcash/passwordWrap.ts
+22 -22
View File
@@ -2,9 +2,9 @@
// PBKDF2 parameters and wire fields stay centralized so legacy linking-key and
// v2 wallet-material records remain interoperable with their own readers.
import {bytesToHex, hexToBytes, utf8ToBytes} from '@noble/hashes/utils.js'
import { bytesToHex, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
const PBKDF2_ITERATIONS = 210_000
const PBKDF2_ITERATIONS = 210_000;
const deriveAesKeyFromPassword = (password: string, salt: Uint8Array): Promise<CryptoKey> =>
crypto.subtle
@@ -18,46 +18,46 @@ const deriveAesKeyFromPassword = (password: string, salt: Uint8Array): Promise<C
hash: 'SHA-256',
},
baseKey,
{name: 'AES-GCM', length: 256},
{ name: 'AES-GCM', length: 256 },
false,
['encrypt', 'decrypt'],
),
)
);
export type EncryptedSecretParts = {
readonly salt: string
readonly iv: string
readonly ciphertext: string
}
readonly salt: string;
readonly iv: string;
readonly ciphertext: string;
};
export const encryptSecretParts = async (
value: string,
password: string,
): Promise<EncryptedSecretParts> => {
const salt = crypto.getRandomValues(new Uint8Array(16))
const iv = crypto.getRandomValues(new Uint8Array(12))
const aesKey = await deriveAesKeyFromPassword(password, salt)
const salt = crypto.getRandomValues(new Uint8Array(16));
const iv = crypto.getRandomValues(new Uint8Array(12));
const aesKey = await deriveAesKeyFromPassword(password, salt);
const ciphertext = new Uint8Array(
await crypto.subtle.encrypt({name: 'AES-GCM', iv}, aesKey, utf8ToBytes(value)),
)
await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, aesKey, utf8ToBytes(value)),
);
return {
salt: bytesToHex(salt),
iv: bytesToHex(iv),
ciphertext: bytesToHex(ciphertext),
}
}
};
};
export const decryptSecretParts = async (
parts: EncryptedSecretParts,
password: string,
): Promise<string> => {
const salt = hexToBytes(parts.salt)
const iv = hexToBytes(parts.iv)
const aesKey = await deriveAesKeyFromPassword(password, salt)
const salt = hexToBytes(parts.salt);
const iv = hexToBytes(parts.iv);
const aesKey = await deriveAesKeyFromPassword(password, salt);
const plaintext = await crypto.subtle.decrypt(
{name: 'AES-GCM', iv},
{ name: 'AES-GCM', iv },
aesKey,
hexToBytes(parts.ciphertext),
)
return new TextDecoder().decode(plaintext)
}
);
return new TextDecoder().decode(plaintext);
};
src/lnurlcash/receive.ts
+20 -20
View File
@@ -9,9 +9,9 @@ import {
NoteSpentError,
NoteUnknownError,
PendingNoteError,
} from 'lnurlcash-kit'
import type {LnurlcashOptions} from 'lnurlcash-kit'
import type {Bearer, NewBearer} from './types'
} from 'lnurlcash-kit';
import type { LnurlcashOptions } from 'lnurlcash-kit';
import type { Bearer, NewBearer } from './types';
// shared by Scan and Paste: resolve whatever came in to a note URL, ask the
// issuing service what it is worth (an informational GET - per spec this
@@ -19,23 +19,23 @@ import type {Bearer, NewBearer} from './types'
// after, see secureReceivedNote). Returns the note even when the info fetch
// fails - a bearer is better stored unverified than dropped.
export const receiveNote = async (input: string, existing: Bearer[]): Promise<NewBearer> => {
const url = resolveNoteInput(input)
const url = resolveNoteInput(input);
if (!url) {
throw new Error('Not an LNURLcash bearer note (needs a k1).')
throw new Error('Not an LNURLcash bearer note (needs a k1).');
}
const k1 = noteK1(url)
const k1 = noteK1(url);
if (existing.some((b) => noteK1(b.url) === k1 && serverOf(b.url) === serverOf(url))) {
throw new Error('This note is already in your wallet.')
throw new Error('This note is already in your wallet.');
}
try {
const info = await fetchNoteInfo(url)
const info = await fetchNoteInfo(url);
return {
url,
callback: info.callback,
amount: info.maxWithdrawable,
verified: true,
mintPubkey: info.mintPubkey,
}
};
} catch (err) {
// the service positively told us this k1 is dead, unknown, or locked
// mid-melt (pending) - all definitive states the caller must surface
@@ -47,7 +47,7 @@ export const receiveNote = async (input: string, existing: Bearer[]): Promise<Ne
err instanceof NoteUnknownError ||
err instanceof PendingNoteError
) {
throw err
throw err;
}
// service unreachable (or some other non-definitive failure) - fall
// back to the sender's own (unverified) declared amount so the note
@@ -57,9 +57,9 @@ export const receiveNote = async (input: string, existing: Bearer[]): Promise<Ne
callback: '',
amount: noteDeclaredAmount(url) ?? 0,
verified: false,
}
};
}
}
};
// After receiving a note, rotate it: the previous holder (and anything that
// logged the URL in transit, since the informational GET above already put
@@ -71,16 +71,16 @@ export const receiveNote = async (input: string, existing: Bearer[]): Promise<Ne
// rescue a rotate that landed despite its refusal.
export const secureReceivedNote = async (
note: {
url: string
callback: string
amount: number
url: string;
callback: string;
amount: number;
},
options: LnurlcashOptions = {},
): Promise<string> => {
const k1 = noteK1(note.url)
const k1 = noteK1(note.url);
if (!k1 || !note.callback) {
throw new Error('Note has no callback to rotate against yet.')
throw new Error('Note has no callback to rotate against yet.');
}
const result = await rotateNote(note.callback, k1, options)
return withNewK1(note.url, result.k1, note.amount, result.signature)
}
const result = await rotateNote(note.callback, k1, options);
return withNewK1(note.url, result.k1, note.amount, result.signature);
};
src/lnurlcash/storage.backup.test.ts
+101 -101
View File
@@ -4,20 +4,20 @@
// restore merges upward-only, and pending journal state never leaves the
// device.
import {beforeEach, describe, expect, it, vi} from 'vitest'
import { beforeEach, describe, expect, it, vi } from 'vitest';
import {bytesToHex} from '@noble/hashes/utils.js'
import { bytesToHex } from '@noble/hashes/utils.js';
import {deriveWalletMaterial, linkingPubKeyHex, saveWalletMaterial} from './keys'
import {applyBackup, buildBackup, parseBackupFile} from './storage'
import {readFundsDocument, writeFundsDocument} from './storage/bearers'
import {addTrustedMint, readTrustedMints} from './trustedMints'
import {requiredValue, stubLocalStorage} from './test-utils'
import { deriveWalletMaterial, linkingPubKeyHex, saveWalletMaterial } from './keys';
import { applyBackup, buildBackup, parseBackupFile } from './storage';
import { readFundsDocument, writeFundsDocument } from './storage/bearers';
import { addTrustedMint, readTrustedMints } from './trustedMints';
import { requiredValue, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OWNER_ID = linkingPubKeyHex(LINKING_KEY)
const KEY_A = '02' + 'aa'.repeat(32)
const KEY_B = '03' + 'bb'.repeat(32)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OWNER_ID = linkingPubKeyHex(LINKING_KEY);
const KEY_A = '02' + 'aa'.repeat(32);
const KEY_B = '03' + 'bb'.repeat(32);
// full v2 material for this harness's fixed linking key (real BIP-32 cash
// root, same construction as the lifecycle test harness)
const MATERIAL = {
@@ -25,29 +25,29 @@ const MATERIAL = {
'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about',
),
linkingKeyHex: bytesToHex(LINKING_KEY),
}
};
type LockRequest = {
readonly callback: () => unknown
readonly resolve: (value: unknown) => void
readonly reject: (reason: unknown) => void
}
readonly callback: () => unknown;
readonly resolve: (value: unknown) => void;
readonly reject: (reason: unknown) => void;
};
class DeferredLocks {
readonly requests: LockRequest[] = []
readonly requests: LockRequest[] = [];
readonly request = (_name: string, callback: () => unknown): Promise<unknown> =>
new Promise((resolve, reject) => {
this.requests.push({callback, resolve, reject})
})
this.requests.push({ callback, resolve, reject });
});
async releaseNext(): Promise<void> {
const request = this.requests.shift()
if (!request) throw new Error('Expected a queued lock request.')
const request = this.requests.shift();
if (!request) throw new Error('Expected a queued lock request.');
try {
request.resolve(await request.callback())
request.resolve(await request.callback());
} catch (error) {
request.reject(error instanceof Error ? error : new Error(String(error)))
request.reject(error instanceof Error ? error : new Error(String(error)));
}
}
}
@@ -67,65 +67,65 @@ const backup = (server: string, mintPubkey: string) => ({
pendingMintPubkey: KEY_B,
},
],
})
});
const installProvenOwner = (): Promise<void> => saveWalletMaterial(MATERIAL)
const installProvenOwner = (): Promise<void> => saveWalletMaterial(MATERIAL);
beforeEach(() => {
vi.unstubAllGlobals()
stubLocalStorage()
})
vi.unstubAllGlobals();
stubLocalStorage();
});
describe('owner-bound backup restore', () => {
it('exports only the active owner trusted-mint registry', async () => {
await installProvenOwner()
await addTrustedMint('backup-mint.example', KEY_A, {ownerId: OWNER_ID})
await installProvenOwner();
await addTrustedMint('backup-mint.example', KEY_A, { ownerId: OWNER_ID });
expect(buildBackup(OWNER_ID).trustedMints).toEqual([
expect.objectContaining({server: 'backup-mint.example', mintPubkey: KEY_A}),
])
expect(buildBackup(OWNER_ID).ownerId).toBe(OWNER_ID)
expect(buildBackup().trustedMints).toEqual([])
})
expect.objectContaining({ server: 'backup-mint.example', mintPubkey: KEY_A }),
]);
expect(buildBackup(OWNER_ID).ownerId).toBe(OWNER_ID);
expect(buildBackup().trustedMints).toEqual([]);
});
it('drops fresh-device mint trust instead of using a valid file owner marker', async () => {
const result = await applyBackup({
...backup('file-mint.example', KEY_A),
ownerId: OWNER_ID,
})
});
expect(result.trustedMintsAdded).toBe(0)
expect(readTrustedMints(OWNER_ID)).toEqual([])
expect(localStorage.getItem('sattle_trusted_mints')).toBeNull()
})
expect(result.trustedMintsAdded).toBe(0);
expect(readTrustedMints(OWNER_ID)).toEqual([]);
expect(localStorage.getItem('sattle_trusted_mints')).toBeNull();
});
it('does not attach file mints to a malformed owner marker', async () => {
const result = await applyBackup({
...backup('file-mint.example', KEY_A),
ownerId: 'malformed-owner',
})
});
expect(result.trustedMintsAdded).toBe(0)
expect(readTrustedMints(OWNER_ID)).toEqual([])
})
expect(result.trustedMintsAdded).toBe(0);
expect(readTrustedMints(OWNER_ID)).toEqual([]);
});
it('does not resolve before the trusted-mint merge commits', async () => {
await installProvenOwner()
const locks = new DeferredLocks()
vi.stubGlobal('navigator', {locks})
await installProvenOwner();
const locks = new DeferredLocks();
vi.stubGlobal('navigator', { locks });
let settled = false
let settled = false;
const restoring = applyBackup(backup('backup-mint.example', KEY_A), OWNER_ID).then((result) => {
settled = true
return result
})
await vi.waitFor(() => expect(locks.requests).toHaveLength(1))
settled = true;
return result;
});
await vi.waitFor(() => expect(locks.requests).toHaveLength(1));
expect(settled).toBe(false)
await locks.releaseNext()
expect(settled).toBe(false);
await locks.releaseNext();
expect((await restoring).trustedMintsAdded).toBe(1)
const restored = readTrustedMints(OWNER_ID)
expect((await restoring).trustedMintsAdded).toBe(1);
const restored = readTrustedMints(OWNER_ID);
expect(restored).toEqual([
expect.objectContaining({
server: 'backup-mint.example',
@@ -133,12 +133,12 @@ describe('owner-bound backup restore', () => {
locked: false,
unconfirmed: true,
}),
])
expect(restored[0]?.pendingMintPubkey).toBeUndefined()
})
]);
expect(restored[0]?.pendingMintPubkey).toBeUndefined();
});
it('keeps a local locked pin and pending rekey authoritative', async () => {
await installProvenOwner()
await installProvenOwner();
localStorage.setItem(
'sattle_trusted_mints',
JSON.stringify({
@@ -154,72 +154,72 @@ describe('owner-bound backup restore', () => {
},
],
}),
)
);
const result = await applyBackup(backup('local.example', KEY_B), OWNER_ID)
const result = await applyBackup(backup('local.example', KEY_B), OWNER_ID);
expect(result.trustedMintsAdded).toBe(0)
expect(result.trustedMintsAdded).toBe(0);
expect(readTrustedMints(OWNER_ID)).toEqual([
expect.objectContaining({
mintPubkey: KEY_A,
locked: true,
pendingMintPubkey: KEY_B,
}),
])
})
})
]);
});
});
describe('backup counter projection', () => {
const fundsDoc = (nextByHost: Record<string, number>) => ({
version: 2 as const,
bearers: [] as {id: string; iv: string; ciphertext: string}[],
pending: [] as {id: string; kind: string; phase: string; iv: string; ciphertext: string}[],
bearers: [] as { id: string; iv: string; ciphertext: string }[],
pending: [] as { id: string; kind: string; phase: string; iv: string; ciphertext: string }[],
nextByHost,
revision: 1,
})
});
it('exports the counters and never the pending journal', () => {
const doc = fundsDoc({'mint.example': 5})
const doc = fundsDoc({ 'mint.example': 5 });
doc.pending.push({
id: 'pending-sentinel-never-exported',
kind: 'cash-allocation',
phase: 'reserved',
iv: '00',
ciphertext: '00',
})
writeFundsDocument(doc)
});
writeFundsDocument(doc);
const built = buildBackup(OWNER_ID)
const built = buildBackup(OWNER_ID);
expect(built.version).toBe(2)
expect(built.nextByHost).toEqual({'mint.example': 5})
expect('pending' in built).toBe(false)
expect(JSON.stringify(built)).not.toContain('pending-sentinel-never-exported')
})
expect(built.version).toBe(2);
expect(built.nextByHost).toEqual({ 'mint.example': 5 });
expect('pending' in built).toBe(false);
expect(JSON.stringify(built)).not.toContain('pending-sentinel-never-exported');
});
it('round-trips counters through a restore and merges upward-only', async () => {
writeFundsDocument(fundsDoc({'mint.example': 5, 'other.example': 2}))
writeFundsDocument(fundsDoc({ 'mint.example': 5, 'other.example': 2 }));
const result = await applyBackup({
type: 'sattle-backup',
version: 2,
createdAt: 1,
bearers: [],
nextByHost: {'mint.example': 3, 'other.example': 9, 'new.example': 4},
})
nextByHost: { 'mint.example': 3, 'other.example': 9, 'new.example': 4 },
});
expect(result.added).toBe(0)
expect(result.added).toBe(0);
// lower incoming values never rewind a counter; higher ones advance it;
// unknown hosts adopt the backup's value
expect(readFundsDocument().nextByHost).toEqual({
'mint.example': 5,
'other.example': 9,
'new.example': 4,
})
})
});
});
it('skips out-of-bounds counter entries instead of rejecting the restore', async () => {
writeFundsDocument(fundsDoc({'mint.example': 5}))
writeFundsDocument(fundsDoc({ 'mint.example': 5 }));
await applyBackup({
type: 'sattle-backup',
@@ -233,14 +233,14 @@ describe('backup counter projection', () => {
'fractional.example': 1.5,
'valid.example': 7,
},
})
});
expect(readFundsDocument().nextByHost).toEqual({'mint.example': 5, 'valid.example': 7})
})
expect(readFundsDocument().nextByHost).toEqual({ 'mint.example': 5, 'valid.example': 7 });
});
it('never grows the counter map beyond ten hosts on restore', async () => {
const incoming: Record<string, number> = {}
for (let i = 0; i < 12; i += 1) incoming[`mint-${i}.example`] = i + 1
const incoming: Record<string, number> = {};
for (let i = 0; i < 12; i += 1) incoming[`mint-${i}.example`] = i + 1;
await applyBackup({
type: 'sattle-backup',
@@ -248,21 +248,21 @@ describe('backup counter projection', () => {
createdAt: 1,
bearers: [],
nextByHost: incoming,
})
});
const merged = readFundsDocument().nextByHost
expect(Object.keys(merged)).toHaveLength(10)
})
const merged = readFundsDocument().nextByHost;
expect(Object.keys(merged)).toHaveLength(10);
});
it('rejects a legacy version-1 backup file', () => {
expect(() =>
parseBackupFile({type: 'sattle-backup', version: 1, createdAt: 1, bearers: []}),
).toThrow('Not a valid sattle backup file.')
})
parseBackupFile({ type: 'sattle-backup', version: 1, createdAt: 1, bearers: [] }),
).toThrow('Not a valid sattle backup file.');
});
it('rejects a v2 file without a counter map', () => {
expect(() =>
parseBackupFile({type: 'sattle-backup', version: 2, createdAt: 1, bearers: []}),
).toThrow('Not a valid sattle backup file.')
})
})
parseBackupFile({ type: 'sattle-backup', version: 2, createdAt: 1, bearers: [] }),
).toThrow('Not a valid sattle backup file.');
});
});
src/lnurlcash/storage.changeset.cases.ts
+118 -118
View File
@@ -2,10 +2,10 @@
// fund-critical changeset boundary without mixing it into unrelated storage
// round-trip and backup cases.
import {describe, expect, it, vi} from 'vitest'
import {buildNoteUrl} from 'lnurlcash-kit'
import { describe, expect, it, vi } from 'vitest';
import { buildNoteUrl } from 'lnurlcash-kit';
import {deriveBearerAesKey, encryptRecord} from './keys'
import { deriveBearerAesKey, encryptRecord } from './keys';
import {
applyBearerChangeset,
deleteBearerRecord,
@@ -13,25 +13,25 @@ import {
newBearerId,
persistBearer,
readEncryptedBearers,
} from './storage'
import type {BearerChangeset} from './storage'
import type {Bearer, NewBearer} from './types'
import {FUNDS_STORAGE_KEY, readFundsDocument, writeFundsDocument} from './storage/bearers'
} from './storage';
import type { BearerChangeset } from './storage';
import type { Bearer, NewBearer } from './types';
import { FUNDS_STORAGE_KEY, readFundsDocument, writeFundsDocument } from './storage/bearers';
// mutations of the funds document require Web Locks; tests that don't care
// about lock timing install a present-but-non-serializing fake
const stubPassthroughLocks = (): void => {
vi.stubGlobal('navigator', {
locks: {request: (_name: string, fn: () => unknown) => Promise.resolve().then(fn)},
})
}
locks: { request: (_name: string, fn: () => unknown) => Promise.resolve().then(fn) },
});
};
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_KEY = new Uint8Array(32).fill(9)
const K1_A = 'aa'.repeat(32)
const K1_B = 'bb'.repeat(32)
const K1_C = 'cc'.repeat(32)
const K1_D = 'dd'.repeat(32)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_KEY = new Uint8Array(32).fill(9);
const K1_A = 'aa'.repeat(32);
const K1_B = 'bb'.repeat(32);
const K1_C = 'cc'.repeat(32);
const K1_D = 'dd'.repeat(32);
const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
id: newBearerId(),
@@ -42,7 +42,7 @@ const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
createdAt: 1000,
updatedAt: 1000,
...overrides,
})
});
const newBearerFixture = (overrides: Partial<NewBearer> = {}): NewBearer => ({
url: buildNoteUrl('https://mint.example/w', K1_C, 3_000),
@@ -50,37 +50,37 @@ const newBearerFixture = (overrides: Partial<NewBearer> = {}): NewBearer => ({
amount: 3_000,
verified: true,
...overrides,
})
});
describe('baseline: per-record bearer persistence', () => {
it('writes once for every persist or delete call', async () => {
stubPassthroughLocks()
const key = await deriveBearerAesKey(LINKING_KEY)
const writes = vi.spyOn(localStorage, 'setItem')
stubPassthroughLocks();
const key = await deriveBearerAesKey(LINKING_KEY);
const writes = vi.spyOn(localStorage, 'setItem');
await persistBearer(key, bearerFixture({id: 'a'}))
await persistBearer(key, bearerFixture({id: 'b'}))
await deleteBearerRecord('a')
await persistBearer(key, bearerFixture({ id: 'a' }));
await persistBearer(key, bearerFixture({ id: 'b' }));
await deleteBearerRecord('a');
expect(
writes.mock.calls.filter(([storageKey]) => storageKey === FUNDS_STORAGE_KEY),
).toHaveLength(3)
})
})
).toHaveLength(3);
});
});
describe('applyBearerChangeset', () => {
it('commits additions and spent replacements with exactly one write', async () => {
stubPassthroughLocks()
const key = await deriveBearerAesKey(LINKING_KEY)
const oldA = bearerFixture({id: 'old-a'})
stubPassthroughLocks();
const key = await deriveBearerAesKey(LINKING_KEY);
const oldA = bearerFixture({ id: 'old-a' });
const oldB = bearerFixture({
id: 'old-b',
url: buildNoteUrl('https://mint.example/w', K1_B, 5_000),
amount: 5_000,
})
await persistBearer(key, oldA)
await persistBearer(key, oldB)
const snapshot = [oldA, oldB]
});
await persistBearer(key, oldA);
await persistBearer(key, oldB);
const snapshot = [oldA, oldB];
const changeset: BearerChangeset = {
add: [
newBearerFixture(),
@@ -90,37 +90,37 @@ describe('applyBearerChangeset', () => {
}),
],
markSpent: ['old-a', 'old-b'],
}
const writes = vi.spyOn(localStorage, 'setItem')
};
const writes = vi.spyOn(localStorage, 'setItem');
const result = await applyBearerChangeset(key, snapshot, changeset)
const result = await applyBearerChangeset(key, snapshot, changeset);
expect(
writes.mock.calls.filter(([storageKey]) => storageKey === FUNDS_STORAGE_KEY),
).toHaveLength(1)
expect(result).toHaveLength(4)
expect(result.slice(2).map((bearer) => bearer.spent)).toEqual([true, true])
expect(result[0]?.id).not.toBe(result[1]?.id)
expect(snapshot.map((bearer) => bearer.spent)).toEqual([undefined, undefined])
expect(changeset.markSpent).toEqual(['old-a', 'old-b'])
expect(changeset.add.some((note) => 'id' in note)).toBe(false)
).toHaveLength(1);
expect(result).toHaveLength(4);
expect(result.slice(2).map((bearer) => bearer.spent)).toEqual([true, true]);
expect(result[0]?.id).not.toBe(result[1]?.id);
expect(snapshot.map((bearer) => bearer.spent)).toEqual([undefined, undefined]);
expect(changeset.markSpent).toEqual(['old-a', 'old-b']);
expect(changeset.add.some((note) => 'id' in note)).toBe(false);
expect((await loadBearers(key)).map((bearer) => bearer.id).sort()).toEqual(
result.map((bearer) => bearer.id).sort(),
)
const raw = localStorage.getItem(FUNDS_STORAGE_KEY) ?? ''
expect(raw).not.toContain(K1_C)
expect(raw).not.toContain(K1_D)
})
);
const raw = localStorage.getItem(FUNDS_STORAGE_KEY) ?? '';
expect(raw).not.toContain(K1_C);
expect(raw).not.toContain(K1_D);
});
it('writes nothing when the second record encryption fails', async () => {
stubPassthroughLocks()
const key = await deriveBearerAesKey(LINKING_KEY)
await persistBearer(key, bearerFixture({id: 'kept'}))
const writes = vi.spyOn(localStorage, 'setItem')
const encrypt = vi.spyOn(crypto.subtle, 'encrypt')
stubPassthroughLocks();
const key = await deriveBearerAesKey(LINKING_KEY);
await persistBearer(key, bearerFixture({ id: 'kept' }));
const writes = vi.spyOn(localStorage, 'setItem');
const encrypt = vi.spyOn(crypto.subtle, 'encrypt');
encrypt
.mockResolvedValueOnce(new ArrayBuffer(32))
.mockRejectedValueOnce(new Error('second encryption failed'))
.mockRejectedValueOnce(new Error('second encryption failed'));
try {
await expect(
@@ -133,26 +133,26 @@ describe('applyBearerChangeset', () => {
],
markSpent: [],
}),
).rejects.toThrow('second encryption failed')
expect(encrypt).toHaveBeenCalledTimes(2)
).rejects.toThrow('second encryption failed');
expect(encrypt).toHaveBeenCalledTimes(2);
expect(
writes.mock.calls.filter(([storageKey]) => storageKey === FUNDS_STORAGE_KEY),
).toHaveLength(0)
expect(readEncryptedBearers().map((record) => record.id)).toEqual(['kept'])
).toHaveLength(0);
expect(readEncryptedBearers().map((record) => record.id)).toEqual(['kept']);
} finally {
encrypt.mockRestore()
encrypt.mockRestore();
}
})
});
it('rejects a failed storage write without changing persisted state', async () => {
stubPassthroughLocks()
const key = await deriveBearerAesKey(LINKING_KEY)
const kept = bearerFixture({id: 'kept'})
await persistBearer(key, kept)
const before = localStorage.getItem(FUNDS_STORAGE_KEY)
stubPassthroughLocks();
const key = await deriveBearerAesKey(LINKING_KEY);
const kept = bearerFixture({ id: 'kept' });
await persistBearer(key, kept);
const before = localStorage.getItem(FUNDS_STORAGE_KEY);
const write = vi.spyOn(localStorage, 'setItem').mockImplementation(() => {
throw new Error('QuotaExceededError')
})
throw new Error('QuotaExceededError');
});
try {
await expect(
@@ -160,43 +160,43 @@ describe('applyBearerChangeset', () => {
add: [newBearerFixture()],
markSpent: ['kept'],
}),
).rejects.toThrow('QuotaExceededError')
expect(localStorage.getItem(FUNDS_STORAGE_KEY)).toBe(before)
).rejects.toThrow('QuotaExceededError');
expect(localStorage.getItem(FUNDS_STORAGE_KEY)).toBe(before);
} finally {
write.mockRestore()
vi.unstubAllGlobals()
write.mockRestore();
vi.unstubAllGlobals();
}
})
});
it('deduplicates repeated spent ids into one stored replacement', async () => {
stubPassthroughLocks()
const key = await deriveBearerAesKey(LINKING_KEY)
const bearer = bearerFixture({id: 'duplicate'})
await persistBearer(key, bearer)
stubPassthroughLocks();
const key = await deriveBearerAesKey(LINKING_KEY);
const bearer = bearerFixture({ id: 'duplicate' });
await persistBearer(key, bearer);
const result = await applyBearerChangeset(key, [bearer], {
add: [],
markSpent: ['duplicate', 'duplicate'],
})
});
expect(readEncryptedBearers().filter((record) => record.id === 'duplicate')).toHaveLength(1)
expect(result[0]?.spent).toBe(true)
expect((await loadBearers(key))[0]?.spent).toBe(true)
})
expect(readEncryptedBearers().filter((record) => record.id === 'duplicate')).toHaveLength(1);
expect(result[0]?.spent).toBe(true);
expect((await loadBearers(key))[0]?.spent).toBe(true);
});
it('fresh-reads inside the lock and preserves a fresh unrelated record', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
const other = await deriveBearerAesKey(OTHER_KEY)
const mine = bearerFixture({id: 'mine'})
const key = await deriveBearerAesKey(LINKING_KEY);
const other = await deriveBearerAesKey(OTHER_KEY);
const mine = bearerFixture({ id: 'mine' });
const foreign = bearerFixture({
id: 'fresh-tab',
url: buildNoteUrl('https://mint.example/w', K1_B, 9_000),
})
await persistBearer(key, mine)
const {id: foreignId, ...foreignPlain} = foreign
const foreignParts = await encryptRecord(other, foreignPlain)
const encrypted = vi.spyOn(crypto.subtle, 'encrypt')
const queue: {release: () => Promise<void>}[] = []
});
await persistBearer(key, mine);
const { id: foreignId, ...foreignPlain } = foreign;
const foreignParts = await encryptRecord(other, foreignPlain);
const encrypted = vi.spyOn(crypto.subtle, 'encrypt');
const queue: { release: () => Promise<void> }[] = [];
vi.stubGlobal('navigator', {
locks: {
request: (_name: string, fn: () => unknown): Promise<unknown> =>
@@ -205,59 +205,59 @@ describe('applyBearerChangeset', () => {
release: async () => {
await Promise.resolve(fn)
.then((callback) => callback())
.then(resolve, reject)
.then(resolve, reject);
},
})
});
}),
},
})
});
try {
const commit = applyBearerChangeset(key, [mine], {
add: [newBearerFixture()],
markSpent: [],
})
await vi.waitFor(() => expect(queue).toHaveLength(1))
});
await vi.waitFor(() => expect(queue).toHaveLength(1));
// nothing is encrypted before the lock: the document is re-read fresh
// inside it, so a record another tab commits in the meantime survives
expect(encrypted).toHaveBeenCalledTimes(0)
const doc = readFundsDocument()
doc.bearers.push({id: foreignId, ...foreignParts})
writeFundsDocument(doc)
const pendingLock = queue.at(0)
if (pendingLock === undefined) throw new Error('Expected pending lock')
expect(encrypted).toHaveBeenCalledTimes(0);
const doc = readFundsDocument();
doc.bearers.push({ id: foreignId, ...foreignParts });
writeFundsDocument(doc);
const pendingLock = queue.at(0);
if (pendingLock === undefined) throw new Error('Expected pending lock');
await pendingLock.release()
const result = await commit
await pendingLock.release();
const result = await commit;
expect(
readEncryptedBearers()
.map((record) => record.id)
.sort(),
).toEqual(['fresh-tab', 'mine', result[0]?.id].sort())
expect((await loadBearers(other)).map((bearer) => bearer.id)).toEqual(['fresh-tab'])
).toEqual(['fresh-tab', 'mine', result[0]?.id].sort());
expect((await loadBearers(other)).map((bearer) => bearer.id)).toEqual(['fresh-tab']);
} finally {
encrypted.mockRestore()
vi.unstubAllGlobals()
encrypted.mockRestore();
vi.unstubAllGlobals();
}
})
});
it('replaces corrupt JSON with the single committed changeset write', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
localStorage.setItem(FUNDS_STORAGE_KEY, 'not json {{{')
const writes = vi.spyOn(localStorage, 'setItem')
const key = await deriveBearerAesKey(LINKING_KEY);
localStorage.setItem(FUNDS_STORAGE_KEY, 'not json {{{');
const writes = vi.spyOn(localStorage, 'setItem');
const result = await applyBearerChangeset(key, [], {
add: [newBearerFixture()],
markSpent: ['missing'],
})
});
expect(result).toHaveLength(1)
expect(result).toHaveLength(1);
expect(
writes.mock.calls.filter(([storageKey]) => storageKey === FUNDS_STORAGE_KEY),
).toHaveLength(1)
).toHaveLength(1);
expect((await loadBearers(key)).map((bearer) => bearer.id)).toEqual(
result.map((bearer) => bearer.id),
)
})
})
);
});
});
src/lnurlcash/storage.test.ts
+135 -135
View File
@@ -1,12 +1,12 @@
// Storage round-trips and backup merge semantics. Runs in Node against an
// in-memory localStorage stub; WebCrypto (crypto.subtle) is native.
import {beforeEach, describe, expect, it} from 'vitest'
import {buildNoteUrl} from 'lnurlcash-kit'
import { beforeEach, describe, expect, it } from 'vitest';
import { buildNoteUrl } from 'lnurlcash-kit';
import './storage.changeset.cases'
import type {Bearer} from './types'
import {deriveBearerAesKey} from './keys'
import './storage.changeset.cases';
import type { Bearer } from './types';
import { deriveBearerAesKey } from './keys';
import {
applyBackup,
buildBackup,
@@ -20,16 +20,16 @@ import {
persistBearer,
readEncryptedBearers,
MAX_ACTIVITY_ENTRIES,
} from './storage'
import {saveLinkingKey} from './keys'
import {FUNDS_STORAGE_KEY} from './storage/bearers'
import {requiredValue, stubLocalStorage} from './test-utils'
} from './storage';
import { saveLinkingKey } from './keys';
import { FUNDS_STORAGE_KEY } from './storage/bearers';
import { requiredValue, stubLocalStorage } from './test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const OTHER_KEY = new Uint8Array(32).fill(9)
const LINKING_KEY = new Uint8Array(32).fill(7);
const OTHER_KEY = new Uint8Array(32).fill(9);
const K1_A = 'aa'.repeat(32)
const K1_B = 'bb'.repeat(32)
const K1_A = 'aa'.repeat(32);
const K1_B = 'bb'.repeat(32);
const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
id: newBearerId(),
@@ -40,204 +40,204 @@ const bearerFixture = (overrides: Partial<Bearer> = {}): Bearer => ({
createdAt: 1000,
updatedAt: 1000,
...overrides,
})
});
beforeEach(() => {
stubLocalStorage()
})
stubLocalStorage();
});
describe('encrypted bearer records', () => {
it('round-trips a bearer through AES-GCM storage', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
const bearer = bearerFixture()
await persistBearer(key, bearer)
const key = await deriveBearerAesKey(LINKING_KEY);
const bearer = bearerFixture();
await persistBearer(key, bearer);
// at rest, nothing plaintext leaks: no k1, no amounts
const raw = requiredValue(localStorage.getItem(FUNDS_STORAGE_KEY))
expect(raw).not.toContain(K1_A)
expect(raw).not.toContain('21000')
const raw = requiredValue(localStorage.getItem(FUNDS_STORAGE_KEY));
expect(raw).not.toContain(K1_A);
expect(raw).not.toContain('21000');
const loaded = await loadBearers(key)
expect(loaded).toEqual([bearer])
})
const loaded = await loadBearers(key);
expect(loaded).toEqual([bearer]);
});
it('skips records written under a different seed without destroying them', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
const other = await deriveBearerAesKey(OTHER_KEY)
await persistBearer(key, bearerFixture({id: 'mine'}))
const key = await deriveBearerAesKey(LINKING_KEY);
const other = await deriveBearerAesKey(OTHER_KEY);
await persistBearer(key, bearerFixture({ id: 'mine' }));
await persistBearer(
other,
bearerFixture({id: 'foreign', url: buildNoteUrl('https://mint.example/w', K1_B, 5_000)}),
)
bearerFixture({ id: 'foreign', url: buildNoteUrl('https://mint.example/w', K1_B, 5_000) }),
);
const loaded = await loadBearers(key)
expect(loaded.map((b) => b.id)).toEqual(['mine'])
const loaded = await loadBearers(key);
expect(loaded.map((b) => b.id)).toEqual(['mine']);
// the foreign ciphertext is still there, untouched
expect(
readEncryptedBearers()
.map((r) => r.id)
.sort(),
).toEqual(['foreign', 'mine'])
})
).toEqual(['foreign', 'mine']);
});
it('overwrites a record when the same id is persisted again', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
const bearer = bearerFixture()
await persistBearer(key, bearer)
await persistBearer(key, {...bearer, spent: true, updatedAt: 2000})
const key = await deriveBearerAesKey(LINKING_KEY);
const bearer = bearerFixture();
await persistBearer(key, bearer);
await persistBearer(key, { ...bearer, spent: true, updatedAt: 2000 });
const loaded = await loadBearers(key)
expect(loaded).toHaveLength(1)
expect(requiredValue(loaded[0]).spent).toBe(true)
})
const loaded = await loadBearers(key);
expect(loaded).toHaveLength(1);
expect(requiredValue(loaded[0]).spent).toBe(true);
});
it('deletes a record by id and clears all', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
const a = bearerFixture({id: 'a'})
const b = bearerFixture({id: 'b', url: buildNoteUrl('https://mint.example/w', K1_B, 5_000)})
await persistBearer(key, a)
await persistBearer(key, b)
const key = await deriveBearerAesKey(LINKING_KEY);
const a = bearerFixture({ id: 'a' });
const b = bearerFixture({ id: 'b', url: buildNoteUrl('https://mint.example/w', K1_B, 5_000) });
await persistBearer(key, a);
await persistBearer(key, b);
await deleteBearerRecord('a')
expect((await loadBearers(key)).map((x) => x.id)).toEqual(['b'])
await deleteBearerRecord('a');
expect((await loadBearers(key)).map((x) => x.id)).toEqual(['b']);
clearAllBearers()
expect(readEncryptedBearers()).toEqual([])
})
})
clearAllBearers();
expect(readEncryptedBearers()).toEqual([]);
});
});
describe('activity log', () => {
it('round-trips events newest-first', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
await persistActivityEvent(key, {id: '1', kind: 'mint', message: 'a', createdAt: 1000})
await persistActivityEvent(key, {id: '2', kind: 'melt', message: 'b', createdAt: 2000})
const key = await deriveBearerAesKey(LINKING_KEY);
await persistActivityEvent(key, { id: '1', kind: 'mint', message: 'a', createdAt: 1000 });
await persistActivityEvent(key, { id: '2', kind: 'melt', message: 'b', createdAt: 2000 });
const loaded = await loadActivity(key)
expect(loaded.map((e) => e.id)).toEqual(['2', '1'])
})
const loaded = await loadActivity(key);
expect(loaded.map((e) => e.id)).toEqual(['2', '1']);
});
it('caps the log, rolling the oldest entries off', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
const key = await deriveBearerAesKey(LINKING_KEY);
for (let i = 0; i < MAX_ACTIVITY_ENTRIES + 5; i++) {
await persistActivityEvent(key, {
id: `ev-${i}`,
kind: 'receive',
message: `event ${i}`,
createdAt: i,
})
});
}
const loaded = await loadActivity(key)
expect(loaded).toHaveLength(MAX_ACTIVITY_ENTRIES)
const loaded = await loadActivity(key);
expect(loaded).toHaveLength(MAX_ACTIVITY_ENTRIES);
// the five oldest rolled off; the newest is first
expect(requiredValue(loaded[0]).id).toBe(`ev-${MAX_ACTIVITY_ENTRIES + 4}`)
expect(requiredValue(loaded.at(-1)).id).toBe('ev-5')
}, 30_000)
})
expect(requiredValue(loaded[0]).id).toBe(`ev-${MAX_ACTIVITY_ENTRIES + 4}`);
expect(requiredValue(loaded.at(-1)).id).toBe('ev-5');
}, 30_000);
});
describe('mergeBearers (union by note id, spent-wins)', () => {
it('unions notes with distinct secrets', () => {
const a = bearerFixture({id: 'a'})
const b = bearerFixture({id: 'b', url: buildNoteUrl('https://mint.example/w', K1_B, 5_000)})
const merged = mergeBearers([a], [b])
expect(merged.map((x) => x.id).sort()).toEqual(['a', 'b'])
})
const a = bearerFixture({ id: 'a' });
const b = bearerFixture({ id: 'b', url: buildNoteUrl('https://mint.example/w', K1_B, 5_000) });
const merged = mergeBearers([a], [b]);
expect(merged.map((x) => x.id).sort()).toEqual(['a', 'b']);
});
it('lets the spent copy of a note win over a still-spendable one', () => {
const spendable = bearerFixture({id: 'old-copy', updatedAt: 3000})
const spent = bearerFixture({id: 'new-copy', spent: true, updatedAt: 1000})
const spendable = bearerFixture({ id: 'old-copy', updatedAt: 3000 });
const spent = bearerFixture({ id: 'new-copy', spent: true, updatedAt: 1000 });
// same note (same server + k1), different record ids, and the spent
// copy is even the STALER one - spent still wins, or a restored backup
// would resurrect burned money
const merged = mergeBearers([spendable], [spent])
expect(merged).toHaveLength(1)
expect(requiredValue(merged[0]).id).toBe('new-copy')
expect(requiredValue(merged[0]).spent).toBe(true)
})
const merged = mergeBearers([spendable], [spent]);
expect(merged).toHaveLength(1);
expect(requiredValue(merged[0]).id).toBe('new-copy');
expect(requiredValue(merged[0]).spent).toBe(true);
});
it('keeps the newer copy when both agree on spent state', () => {
const stale = bearerFixture({id: 'stale', updatedAt: 1000, amount: 1})
const fresh = bearerFixture({id: 'fresh', updatedAt: 2000, amount: 2})
const merged = mergeBearers([stale], [fresh])
expect(merged).toHaveLength(1)
expect(requiredValue(merged[0]).id).toBe('fresh')
})
const stale = bearerFixture({ id: 'stale', updatedAt: 1000, amount: 1 });
const fresh = bearerFixture({ id: 'fresh', updatedAt: 2000, amount: 2 });
const merged = mergeBearers([stale], [fresh]);
expect(merged).toHaveLength(1);
expect(requiredValue(merged[0]).id).toBe('fresh');
});
it('treats the same secret on different servers as different notes', () => {
const here = bearerFixture({id: 'here'})
const here = bearerFixture({ id: 'here' });
const there = bearerFixture({
id: 'there',
url: buildNoteUrl('https://other.example/w', K1_A, 21_000),
})
expect(mergeBearers([here], [there])).toHaveLength(2)
})
})
});
expect(mergeBearers([here], [there])).toHaveLength(2);
});
});
describe('backup', () => {
it('never exports a plaintext linking key', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
await saveLinkingKey(LINKING_KEY) // no password: stored plaintext
await persistBearer(key, bearerFixture())
const key = await deriveBearerAesKey(LINKING_KEY);
await saveLinkingKey(LINKING_KEY); // no password: stored plaintext
await persistBearer(key, bearerFixture());
const backup = buildBackup()
expect(backup.type).toBe('sattle-backup')
expect(backup.linkingKey).toBeUndefined()
expect(backup.bearers).toHaveLength(1)
})
const backup = buildBackup();
expect(backup.type).toBe('sattle-backup');
expect(backup.linkingKey).toBeUndefined();
expect(backup.bearers).toHaveLength(1);
});
it('exports the linking key when it is itself password-encrypted', async () => {
await saveLinkingKey(LINKING_KEY, 'hunter2')
const backup = buildBackup()
expect(backup.linkingKey?.enc).toBe(true)
})
await saveLinkingKey(LINKING_KEY, 'hunter2');
const backup = buildBackup();
expect(backup.linkingKey?.enc).toBe(true);
});
it('merges a backup by record id - union, never overwrite', async () => {
const key = await deriveBearerAesKey(LINKING_KEY)
await persistBearer(key, bearerFixture({id: 'existing'}))
const key = await deriveBearerAesKey(LINKING_KEY);
await persistBearer(key, bearerFixture({ id: 'existing' }));
// a backup holding the same record id plus a new one
const backup = buildBackup()
const backup = buildBackup();
const incoming = {
...backup,
bearers: [
...backup.bearers,
{id: 'from-backup', iv: '00'.repeat(12), ciphertext: 'ab'.repeat(40)},
{ id: 'from-backup', iv: '00'.repeat(12), ciphertext: 'ab'.repeat(40) },
],
}
const result = await applyBackup(incoming)
expect(result.added).toBe(1)
expect(result.skipped).toBe(1)
};
const result = await applyBackup(incoming);
expect(result.added).toBe(1);
expect(result.skipped).toBe(1);
expect(
readEncryptedBearers()
.map((r) => r.id)
.sort(),
).toEqual(['existing', 'from-backup'])
})
).toEqual(['existing', 'from-backup']);
});
it('restores the linking key only onto a device that has none', async () => {
await saveLinkingKey(LINKING_KEY, 'hunter2')
const backup = buildBackup()
await saveLinkingKey(LINKING_KEY, 'hunter2');
const backup = buildBackup();
// same device: a key already exists, so the backup's key is skipped
const here = await applyBackup(backup)
expect(here.linkingKeySkipped).toBe(true)
expect(here.linkingKeyRestored).toBe(false)
const here = await applyBackup(backup);
expect(here.linkingKeySkipped).toBe(true);
expect(here.linkingKeyRestored).toBe(false);
// fresh device: the key installs
stubLocalStorage()
const fresh = await applyBackup(backup)
expect(fresh.linkingKeyRestored).toBe(true)
expect(fresh.linkingKeySkipped).toBe(false)
})
stubLocalStorage();
const fresh = await applyBackup(backup);
expect(fresh.linkingKeyRestored).toBe(true);
expect(fresh.linkingKeySkipped).toBe(false);
});
it('rejects a file that is not a sattle backup', async () => {
await expect(
applyBackup({type: 'lnurlwallet-backup', version: 1, bearers: []}),
).rejects.toThrow()
await expect(applyBackup(null)).rejects.toThrow()
await expect(applyBackup({type: 'sattle-backup', version: 1, bearers: []})).rejects.toThrow()
applyBackup({ type: 'lnurlwallet-backup', version: 1, bearers: [] }),
).rejects.toThrow();
await expect(applyBackup(null)).rejects.toThrow();
await expect(applyBackup({ type: 'sattle-backup', version: 1, bearers: [] })).rejects.toThrow();
// a v2 file without the counter map is not a valid backup either
await expect(applyBackup({type: 'sattle-backup', version: 2, bearers: []})).rejects.toThrow()
})
await expect(applyBackup({ type: 'sattle-backup', version: 2, bearers: [] })).rejects.toThrow();
});
it('skips malformed records instead of failing the whole restore', async () => {
const result = await applyBackup({
@@ -245,13 +245,13 @@ describe('backup', () => {
version: 2,
createdAt: 1,
bearers: [
{id: 'ok', iv: '00'.repeat(12), ciphertext: 'ab'.repeat(40)},
{id: 42, iv: null, ciphertext: 'xx'},
{ id: 'ok', iv: '00'.repeat(12), ciphertext: 'ab'.repeat(40) },
{ id: 42, iv: null, ciphertext: 'xx' },
'garbage',
],
nextByHost: {},
})
expect(result.added).toBe(1)
expect(result.skipped).toBe(2)
})
})
});
expect(result.added).toBe(1);
expect(result.skipped).toBe(2);
});
});
src/lnurlcash/storage.ts
+9 -9
View File
@@ -12,7 +12,7 @@
// storage/settings.ts - plaintext wallet settings
// storage/backup.ts - buildBackup / applyBackup
export type {Bearer, NewBearer} from './types'
export type { Bearer, NewBearer } from './types';
export {
compareBearerOrder,
@@ -31,7 +31,7 @@ export {
clearAllBearers,
mergeBearers,
FUNDS_STORAGE_KEY,
} from './storage/bearers'
} from './storage/bearers';
export type {
BearerChangeset,
EncryptedBearerRecord,
@@ -41,7 +41,7 @@ export type {
PendingStaging,
ReservedCashRange,
StoredFundsV2,
} from './storage/bearers'
} from './storage/bearers';
export {
newActivityId,
@@ -50,11 +50,11 @@ export {
persistActivityEvent,
clearAllActivity,
MAX_ACTIVITY_ENTRIES,
} from './storage/activityLog'
export type {ActivityKind, ActivityEvent, EncryptedActivityRecord} from './storage/activityLog'
} from './storage/activityLog';
export type { ActivityKind, ActivityEvent, EncryptedActivityRecord } from './storage/activityLog';
export {loadSettings, persistSettings, clearSettings} from './storage/settings'
export type {WalletSettings} from './storage/settings'
export { loadSettings, persistSettings, clearSettings } from './storage/settings';
export type { WalletSettings } from './storage/settings';
export {buildBackup, applyBackup, parseBackupFile, MAX_BACKUP_FILE_BYTES} from './storage/backup'
export type {BackupFile, RestoreResult} from './storage/backup'
export { buildBackup, applyBackup, parseBackupFile, MAX_BACKUP_FILE_BYTES } from './storage/backup';
export type { BackupFile, RestoreResult } from './storage/backup';
src/lnurlcash/storage/activityLog.ts
+43 -43
View File
@@ -2,10 +2,10 @@
// AES-GCM under the same bearer key, append-only, capped so a wallet used
// for years doesn't grow localStorage without limit.
import type {EncryptedRecordParts} from '../keys'
import {encryptRecord, decryptRecord} from '../keys'
import {isJsonObject} from '../jsonParsing'
import {withStorageLock} from '../storageLock'
import type { EncryptedRecordParts } from '../keys';
import { encryptRecord, decryptRecord } from '../keys';
import { isJsonObject } from '../jsonParsing';
import { withStorageLock } from '../storageLock';
// `message` is the full human-readable sentence rather than structured
// fields the UI reassembles, so the log stays simple to read and to extend
@@ -20,16 +20,16 @@ export type ActivityKind =
| 'spent'
| 'deleted'
// a payment or mint initiated by a Nostr Wallet Connect client (M5)
| 'nwc'
| 'nwc';
export type ActivityEvent = {
id: string
kind: ActivityKind
message: string
createdAt: number
}
id: string;
kind: ActivityKind;
message: string;
createdAt: number;
};
export type EncryptedActivityRecord = {id: string} & EncryptedRecordParts
export type EncryptedActivityRecord = { id: string } & EncryptedRecordParts;
const isActivityKind = (value: unknown): value is ActivityKind => {
switch (value) {
@@ -42,65 +42,65 @@ const isActivityKind = (value: unknown): value is ActivityKind => {
case 'spent':
case 'deleted':
case 'nwc':
return true
return true;
default:
return false
return false;
}
}
};
const isEncryptedActivityRecord = (value: unknown): value is EncryptedActivityRecord =>
isJsonObject(value) &&
typeof value.id === 'string' &&
typeof value.iv === 'string' &&
typeof value.ciphertext === 'string'
typeof value.ciphertext === 'string';
const isStoredActivity = (value: unknown): value is Omit<ActivityEvent, 'id'> =>
isJsonObject(value) &&
isActivityKind(value.kind) &&
typeof value.message === 'string' &&
typeof value.createdAt === 'number'
typeof value.createdAt === 'number';
const ACTIVITY_STORAGE_KEY = 'sattle_activity'
const ACTIVITY_STORAGE_KEY = 'sattle_activity';
// bounds how far back the log ever reaches - the oldest entries simply
// roll off once this many are kept
export const MAX_ACTIVITY_ENTRIES = 500
export const MAX_ACTIVITY_ENTRIES = 500;
export const newActivityId = (): string =>
Array.from(crypto.getRandomValues(new Uint8Array(8)))
.map((b) => b.toString(16).padStart(2, '0'))
.join('')
.join('');
export const readEncryptedActivity = (): EncryptedActivityRecord[] => {
const raw = localStorage.getItem(ACTIVITY_STORAGE_KEY)
if (!raw) return []
const raw = localStorage.getItem(ACTIVITY_STORAGE_KEY);
if (!raw) return [];
try {
const parsed: unknown = JSON.parse(raw)
return Array.isArray(parsed) ? parsed.filter(isEncryptedActivityRecord) : []
const parsed: unknown = JSON.parse(raw);
return Array.isArray(parsed) ? parsed.filter(isEncryptedActivityRecord) : [];
} catch {
return []
return [];
}
}
};
const writeEncryptedActivity = (records: EncryptedActivityRecord[]): void => {
localStorage.setItem(ACTIVITY_STORAGE_KEY, JSON.stringify(records))
}
localStorage.setItem(ACTIVITY_STORAGE_KEY, JSON.stringify(records));
};
// same tolerance as loadBearers - an entry that fails to decrypt with this
// key (written by a different seed) is skipped, not destroyed
export const loadActivity = async (aesKey: CryptoKey): Promise<ActivityEvent[]> => {
const events: ActivityEvent[] = []
const events: ActivityEvent[] = [];
for (const record of readEncryptedActivity()) {
try {
const event = await decryptRecord(aesKey, record)
if (!isStoredActivity(event)) throw new Error('Malformed encrypted activity record.')
events.push({...event, id: record.id})
const event = await decryptRecord(aesKey, record);
if (!isStoredActivity(event)) throw new Error('Malformed encrypted activity record.');
events.push({ ...event, id: record.id });
} catch (error) {
// undecryptable with this key - leave it in place
if (!(error instanceof Error)) throw error
if (!(error instanceof Error)) throw error;
}
}
return events.sort((a, b) => b.createdAt - a.createdAt)
}
return events.sort((a, b) => b.createdAt - a.createdAt);
};
// append-only (the log never edits or removes a single entry, only clears
// outright - see clearAllActivity) - records are stored oldest-first so
@@ -109,15 +109,15 @@ export const persistActivityEvent = async (
aesKey: CryptoKey,
event: ActivityEvent,
): Promise<void> => {
const {id, ...plain} = event
const parts = await encryptRecord(aesKey, plain)
const { id, ...plain } = event;
const parts = await encryptRecord(aesKey, plain);
await withStorageLock(ACTIVITY_STORAGE_KEY, () => {
const records = readEncryptedActivity()
records.push({id, ...parts})
writeEncryptedActivity(records.slice(-MAX_ACTIVITY_ENTRIES))
})
}
const records = readEncryptedActivity();
records.push({ id, ...parts });
writeEncryptedActivity(records.slice(-MAX_ACTIVITY_ENTRIES));
});
};
export const clearAllActivity = (): void => {
localStorage.removeItem(ACTIVITY_STORAGE_KEY)
}
localStorage.removeItem(ACTIVITY_STORAGE_KEY);
};
src/lnurlcash/storage/backup.ts
+82 -82
View File
@@ -10,51 +10,51 @@
// atomic unit, so the backup projects both from the same single read -
// they can never disagree about which generation they came from.
import type {StoredSecret} from '../keys'
import type { StoredSecret } from '../keys';
import {
getSavedLinkingKeyStored,
savedKeyExists,
savedKeyIsEncrypted,
restoreLinkingKeyStored,
isValidStoredSecret,
} from '../keys'
import type {TrustedMint} from '../trustedMints'
import {readTrustedMints, mergeTrustedMints} from '../trustedMints'
import {isWalletOwnerId} from './walletOwner'
import type {EncryptedBearerRecord} from './bearers'
import {commitFundsRestore, readFundsDocument} from './bearers'
import type {WalletSettings} from './settings'
import {loadSettings, persistSettings} from './settings'
import {isJsonObject} from '../jsonParsing'
} from '../keys';
import type { TrustedMint } from '../trustedMints';
import { readTrustedMints, mergeTrustedMints } from '../trustedMints';
import { isWalletOwnerId } from './walletOwner';
import type { EncryptedBearerRecord } from './bearers';
import { commitFundsRestore, readFundsDocument } from './bearers';
import type { WalletSettings } from './settings';
import { loadSettings, persistSettings } from './settings';
import { isJsonObject } from '../jsonParsing';
export type BackupFile = {
type: 'sattle-backup'
version: 2
createdAt: number
ownerId?: unknown
linkingKey?: StoredSecret
bearers: EncryptedBearerRecord[]
nextByHost: Record<string, number>
trustedMints?: TrustedMint[]
settings?: WalletSettings
}
type: 'sattle-backup';
version: 2;
createdAt: number;
ownerId?: unknown;
linkingKey?: StoredSecret;
bearers: EncryptedBearerRecord[];
nextByHost: Record<string, number>;
trustedMints?: TrustedMint[];
settings?: WalletSettings;
};
type ParsedBackupFile = {
type: 'sattle-backup'
version: 2
createdAt?: unknown
ownerId?: unknown
linkingKey?: unknown
bearers: unknown[]
nextByHost: Record<string, unknown>
trustedMints?: unknown
settings?: unknown
}
type: 'sattle-backup';
version: 2;
createdAt?: unknown;
ownerId?: unknown;
linkingKey?: unknown;
bearers: unknown[];
nextByHost: Record<string, unknown>;
trustedMints?: unknown;
settings?: unknown;
};
export const buildBackup = (ownerId?: string): BackupFile => {
// one document, one getItem: bearers and counters are snapshot-consistent
// by construction; pending journal records are never read here
const funds = readFundsDocument()
const funds = readFundsDocument();
const backup: BackupFile = {
type: 'sattle-backup',
version: 2,
@@ -63,19 +63,19 @@ export const buildBackup = (ownerId?: string): BackupFile => {
nextByHost: funds.nextByHost,
trustedMints: readTrustedMints(ownerId),
settings: loadSettings(),
}
if (isWalletOwnerId(ownerId)) backup.ownerId = ownerId
const storedKey = getSavedLinkingKeyStored()
};
if (isWalletOwnerId(ownerId)) backup.ownerId = ownerId;
const storedKey = getSavedLinkingKeyStored();
if (savedKeyIsEncrypted() && storedKey) {
backup.linkingKey = storedKey
backup.linkingKey = storedKey;
}
return backup
}
return backup;
};
export type RestoreResult = {
added: number
skipped: number
linkingKeyRestored: boolean
added: number;
skipped: number;
linkingKeyRestored: boolean;
// true when the backup carried a linking key but this device already had
// one, so it was deliberately NOT installed (see below) - distinct from
// "no key in this backup at all". The bearer records above still merged
@@ -83,36 +83,36 @@ export type RestoreResult = {
// whatever wallet is active on this device - unless that's the exact same
// seed, they won't decrypt here, and the caller should say so rather than
// let that read as a silent no-op.
linkingKeySkipped: boolean
trustedMintsAdded: number
linkingKeySkipped: boolean;
trustedMintsAdded: number;
// true when the backup's settings filled in a field this device had never
// set - never when it would overwrite one, same merge direction as the
// trusted mints (the device's own current state always wins)
settingsRestored: boolean
}
settingsRestored: boolean;
};
// restore-time bounds - a crafted or corrupt file must not be able to fill
// localStorage with junk records that never decrypt (quota exhaustion turns
// every later write into a failure, which can strand a just-rotated note),
// nor hang the tab in JSON.parse. A real backup holds a handful of notes,
// each well under a kilobyte encrypted, so these are generous
export const MAX_BACKUP_FILE_BYTES = 10 * 1024 * 1024
const MAX_BACKUP_RECORDS = 10_000
const MAX_BACKUP_FIELD_LENGTH = 64 * 1024
export const MAX_BACKUP_FILE_BYTES = 10 * 1024 * 1024;
const MAX_BACKUP_RECORDS = 10_000;
const MAX_BACKUP_FIELD_LENGTH = 64 * 1024;
const isBackupFile = (data: unknown): data is ParsedBackupFile =>
isJsonObject(data) &&
data.type === 'sattle-backup' &&
data.version === 2 &&
Array.isArray(data.bearers) &&
isJsonObject(data.nextByHost)
isJsonObject(data.nextByHost);
export const parseBackupFile = (data: unknown): ParsedBackupFile => {
if (!isBackupFile(data)) {
throw new Error('Not a valid sattle backup file.')
throw new Error('Not a valid sattle backup file.');
}
return data
}
return data;
};
// merges a backup into localStorage: bearer records are added by id
// (already present ids are left as-is - union, never overwrite) and counter
@@ -129,14 +129,14 @@ export const parseBackupFile = (data: unknown): ParsedBackupFile => {
// note arriving under a different record id, spent-wins) happens after
// decrypt, in bearers.ts's mergeBearers.
export const applyBackup = async (data: unknown, ownerId?: string): Promise<RestoreResult> => {
const backup = parseBackupFile(data)
const backup = parseBackupFile(data);
if (backup.bearers.length > MAX_BACKUP_RECORDS) {
throw new Error(
`Backup holds ${backup.bearers.length} records - more than the ${MAX_BACKUP_RECORDS} a real wallet could produce.`,
)
);
}
const incomingBearers: EncryptedBearerRecord[] = []
let skipped = 0
const incomingBearers: EncryptedBearerRecord[] = [];
let skipped = 0;
for (const record of backup.bearers) {
if (
!isJsonObject(record) ||
@@ -147,44 +147,44 @@ export const applyBackup = async (data: unknown, ownerId?: string): Promise<Rest
record.iv.length > MAX_BACKUP_FIELD_LENGTH ||
record.ciphertext.length > MAX_BACKUP_FIELD_LENGTH
) {
skipped++
continue
skipped++;
continue;
}
incomingBearers.push({id: record.id, iv: record.iv, ciphertext: record.ciphertext})
incomingBearers.push({ id: record.id, iv: record.iv, ciphertext: record.ciphertext });
}
// candidate counters: validity (host length, safe range, host cap) is
// enforced by commitFundsRestore; here we only keep the raw shape honest
const incomingCounters: Record<string, number> = {}
const incomingCounters: Record<string, number> = {};
for (const [host, next] of Object.entries(backup.nextByHost)) {
if (typeof next === 'number') incomingCounters[host] = next
if (typeof next === 'number') incomingCounters[host] = next;
}
let added: number
let added: number;
try {
const merged = await commitFundsRestore(incomingBearers, incomingCounters)
added = merged.added
skipped += merged.skipped
const merged = await commitFundsRestore(incomingBearers, incomingCounters);
added = merged.added;
skipped += merged.skipped;
} catch (error) {
const name = error instanceof Error ? error.name : ''
const message = error instanceof Error ? error.message : ''
const name = error instanceof Error ? error.name : '';
const message = error instanceof Error ? error.message : '';
if (name === 'QuotaExceededError' || /quota|full/i.test(message)) {
throw new Error(
'Local storage is full - the backup could not be written. Free up space (or forget unused wallets) and try again.',
{cause: error},
)
{ cause: error },
);
}
throw error
throw error;
}
let linkingKeyRestored = false
let linkingKeySkipped = false
let linkingKeyRestored = false;
let linkingKeySkipped = false;
// an invalid key record reads as "no key in this backup", never as skipped
if (isValidStoredSecret(backup.linkingKey)) {
if (savedKeyExists()) {
linkingKeySkipped = true
linkingKeySkipped = true;
} else {
restoreLinkingKeyStored(backup.linkingKey)
linkingKeyRestored = true
restoreLinkingKeyStored(backup.linkingKey);
linkingKeyRestored = true;
}
}
@@ -194,22 +194,22 @@ export const applyBackup = async (data: unknown, ownerId?: string): Promise<Rest
const trustedMintsAdded =
ownerId && Array.isArray(backup.trustedMints)
? await mergeTrustedMints(backup.trustedMints, ownerId)
: 0
: 0;
// settings merge: fill only fields this device has never set. Flat
// optional fields (see settings.ts), so the merge is field by field -
// today that is just defaultMint
let settingsRestored = false
let settingsRestored = false;
if (isJsonObject(backup.settings)) {
const incoming = backup.settings.defaultMint
const local = loadSettings()
const incoming = backup.settings.defaultMint;
const local = loadSettings();
if (
local.defaultMint === undefined &&
typeof incoming === 'string' &&
incoming.length <= MAX_BACKUP_FIELD_LENGTH
) {
persistSettings({...local, defaultMint: incoming})
settingsRestored = true
persistSettings({ ...local, defaultMint: incoming });
settingsRestored = true;
}
}
@@ -220,5 +220,5 @@ export const applyBackup = async (data: unknown, ownerId?: string): Promise<Rest
linkingKeySkipped,
trustedMintsAdded,
settingsRestored,
}
}
};
};
src/lnurlcash/storage/bearers.baseline.cases.ts
+21 -21
View File
@@ -1,13 +1,13 @@
import {describe, expect, it, vi} from 'vitest'
import {buildNoteUrl} from 'lnurlcash-kit'
import type {Bearer} from '../types'
import {deriveBearerAesKey} from '../keys'
import {deleteBearerRecord, newBearerId, persistBearer} from '../storage'
import {FUNDS_STORAGE_KEY} from './bearers'
import {stubLocalStorage} from '../test-utils'
import { describe, expect, it, vi } from 'vitest';
import { buildNoteUrl } from 'lnurlcash-kit';
import type { Bearer } from '../types';
import { deriveBearerAesKey } from '../keys';
import { deleteBearerRecord, newBearerId, persistBearer } from '../storage';
import { FUNDS_STORAGE_KEY } from './bearers';
import { stubLocalStorage } from '../test-utils';
const LINKING_KEY = new Uint8Array(32).fill(7)
const K1 = 'aa'.repeat(32)
const LINKING_KEY = new Uint8Array(32).fill(7);
const K1 = 'aa'.repeat(32);
const bearerFixture = (): Bearer => ({
id: newBearerId(),
url: buildNoteUrl('https://mint.example/w', K1, 21_000),
@@ -16,18 +16,18 @@ const bearerFixture = (): Bearer => ({
verified: true,
createdAt: 1000,
updatedAt: 1000,
})
});
describe('baseline: per-record bearer persistence', () => {
it('persistBearer/deleteBearerRecord perform one write per call', async () => {
const storage = stubLocalStorage()
const storage = stubLocalStorage();
vi.stubGlobal('navigator', {
locks: {request: (_name: string, fn: () => unknown) => Promise.resolve().then(fn)},
})
const key = await deriveBearerAesKey(LINKING_KEY)
const writes = vi.spyOn(storage, 'setItem')
await persistBearer(key, {...bearerFixture(), id: 'a'})
await persistBearer(key, {...bearerFixture(), id: 'b'})
await deleteBearerRecord('a')
expect(writes.mock.calls.filter(([keyName]) => keyName === FUNDS_STORAGE_KEY)).toHaveLength(3)
})
})
locks: { request: (_name: string, fn: () => unknown) => Promise.resolve().then(fn) },
});
const key = await deriveBearerAesKey(LINKING_KEY);
const writes = vi.spyOn(storage, 'setItem');
await persistBearer(key, { ...bearerFixture(), id: 'a' });
await persistBearer(key, { ...bearerFixture(), id: 'b' });
await deleteBearerRecord('a');
expect(writes.mock.calls.filter(([keyName]) => keyName === FUNDS_STORAGE_KEY)).toHaveLength(3);
});
});

Some files were not shown because too many files have changed in this diff Show More