homecubbie-server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/LICENSE +75 -0
  2. package/README.md +241 -0
  3. package/dist/crypto.js +135 -0
  4. package/dist/home-network.js +103 -0
  5. package/dist/household.js +912 -0
  6. package/dist/http-server.js +604 -0
  7. package/dist/https-listener.js +92 -0
  8. package/dist/main.js +11 -0
  9. package/dist/quiet-warnings.js +34 -0
  10. package/dist/start.js +104 -0
  11. package/dist/store.js +400 -0
  12. package/dist/web-app.js +138 -0
  13. package/package.json +30 -0
  14. package/web/(now)/index.html +474 -0
  15. package/web/(now)/month.html +474 -0
  16. package/web/+not-found.html +474 -0
  17. package/web/_expo/.routes.json +3 -0
  18. package/web/_expo/static/css/global-31a95f46f0d26533c432758949249e15.css +1 -0
  19. package/web/_expo/static/js/web/entry-0f771d01e242dad2ff9cf31c003ad963.js +2839 -0
  20. package/web/_expo/static/js/web/worker-d922322f88a7f1ead9d277776b9d9ebb.js +22 -0
  21. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/arrow_down.017bc6ba3fc25503e5eb5e53826d48a8.png +0 -0
  22. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/error.d1ea1496f9057eb392d5bbf3732a61b7.png +0 -0
  23. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/file.19eeb73b9593a38f8e9f418337fc7d10.png +0 -0
  24. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/forward.d8b800c443b8972542883e0b9de2bdc6.png +0 -0
  25. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/pkg.ab19f4cbc543357183a20571f68380a3.png +0 -0
  26. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/back-icon-mask.0a328cd9c1afd0afe8e3b1ec5165b1b4.png +0 -0
  27. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/back-icon.35ba0eaec5a4f5ed12ca16fabeae451d.png +0 -0
  28. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55.png +0 -0
  29. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@2x.png +0 -0
  30. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@3x.png +0 -0
  31. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@4x.png +0 -0
  32. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/close-icon.808e1b1b9b53114ec2838071a7e6daa7.png +0 -0
  33. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/close-icon.808e1b1b9b53114ec2838071a7e6daa7@2x.png +0 -0
  34. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/close-icon.808e1b1b9b53114ec2838071a7e6daa7@3x.png +0 -0
  35. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/close-icon.808e1b1b9b53114ec2838071a7e6daa7@4x.png +0 -0
  36. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/search-icon.286d67d3f74808a60a78d3ebf1a5fb57.png +0 -0
  37. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/sitemap.412dd9275b6b48ad28f5e3d81bb1f626.png +0 -0
  38. package/web/assets/__HomeCubbie/node_modules/expo-router/assets/unmatched.20e71bdf79e3a97bf55fd9e164041578.png +0 -0
  39. package/web/assets/__HomeCubbie/node_modules/expo-sqlite/web/wa-sqlite/wa-sqlite.7ca566fbbc2ec2a172c5aefa63a20f4b.wasm +0 -0
  40. package/web/assets/assets/fonts/BricolageGrotesque_600SemiBold.e5b5fc505484ff3ca24da73cba67c660.ttf +0 -0
  41. package/web/assets/assets/images/icon.51a3d296cef4a538e85170017fc2f169.png +0 -0
  42. package/web/costs/[year].html +474 -0
  43. package/web/costs/index.html +474 -0
  44. package/web/favicon.ico +0 -0
  45. package/web/first-run.html +474 -0
  46. package/web/form/account/bill/edit/[id].html +474 -0
  47. package/web/form/account/bill/new.html +474 -0
  48. package/web/form/account/edit/[id].html +474 -0
  49. package/web/form/account/new.html +474 -0
  50. package/web/form/activity/new.html +474 -0
  51. package/web/form/event/edit/[id].html +474 -0
  52. package/web/form/event/new.html +474 -0
  53. package/web/form/note/edit/[id].html +474 -0
  54. package/web/form/note/new.html +474 -0
  55. package/web/form/person/edit/[id].html +474 -0
  56. package/web/form/person/new.html +474 -0
  57. package/web/form/place/edit/[id].html +474 -0
  58. package/web/form/place/new.html +474 -0
  59. package/web/form/policy/correct/[id].html +474 -0
  60. package/web/form/policy/new.html +474 -0
  61. package/web/form/policy/renew/[id].html +474 -0
  62. package/web/form/policy/term/[id].html +474 -0
  63. package/web/form/schedule/edit/[id].html +474 -0
  64. package/web/form/schedule/new.html +474 -0
  65. package/web/form/task/edit/[id].html +474 -0
  66. package/web/form/task/new.html +474 -0
  67. package/web/form/thing/edit/[id].html +474 -0
  68. package/web/form/thing/new.html +474 -0
  69. package/web/home/about/[category].html +474 -0
  70. package/web/home/about/index.html +474 -0
  71. package/web/home/arrange.html +474 -0
  72. package/web/home/index.html +474 -0
  73. package/web/home/place/[id].html +474 -0
  74. package/web/home/thing/[id].html +474 -0
  75. package/web/homecubbie-web.json +5 -0
  76. package/web/index.html +474 -0
  77. package/web/month.html +474 -0
  78. package/web/records/account/[id].html +474 -0
  79. package/web/records/accounts.html +474 -0
  80. package/web/records/document/[id].html +474 -0
  81. package/web/records/documents.html +474 -0
  82. package/web/records/events.html +474 -0
  83. package/web/records/history.html +474 -0
  84. package/web/records/index.html +474 -0
  85. package/web/records/people.html +474 -0
  86. package/web/records/person/[id].html +474 -0
  87. package/web/records/policies.html +474 -0
  88. package/web/records/policy/[id].html +474 -0
  89. package/web/records/supplies.html +474 -0
  90. package/web/records/year/[year].html +474 -0
  91. package/web/scan/[id].html +474 -0
  92. package/web/scan/index.html +474 -0
  93. package/web/search.html +474 -0
  94. package/web/settings/app-lock.html +474 -0
  95. package/web/settings/backup.html +474 -0
  96. package/web/settings/categories.html +474 -0
  97. package/web/settings/index.html +474 -0
  98. package/web/settings/open-source.html +474 -0
  99. package/web/settings/privacy.html +474 -0
  100. package/web/settings/property.html +474 -0
  101. package/web/settings/recently-deleted.html +474 -0
  102. package/web/settings/reminders.html +474 -0
  103. package/web/settings/restore.html +474 -0
  104. package/web/settings/sharing-guide.html +474 -0
  105. package/web/settings/sharing.html +474 -0
  106. package/web/settings/start-over.html +474 -0
  107. package/web/settings/storage.html +474 -0
  108. package/web/settings/tags.html +474 -0
  109. package/web/settings/who-uses-this-phone.html +474 -0
  110. package/web/tasks/[id].html +474 -0
  111. package/web/tasks/index.html +474 -0
package/LICENSE ADDED
@@ -0,0 +1,75 @@
1
+ Required Notice: Copyright 2026 HomeCubbie (https://homecubbie.com)
2
+
3
+ # PolyForm Noncommercial License 1.0.0
4
+
5
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
6
+
7
+ ## Acceptance
8
+
9
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
10
+
11
+ ## Copyright License
12
+
13
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
14
+
15
+ ## Distribution License
16
+
17
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
18
+
19
+ ## Notices
20
+
21
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
22
+
23
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
24
+
25
+ ## Changes and New Works License
26
+
27
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
28
+
29
+ ## Patent License
30
+
31
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
32
+
33
+ ## Noncommercial Purposes
34
+
35
+ Any noncommercial purpose is a permitted purpose.
36
+
37
+ ## Personal Uses
38
+
39
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
40
+
41
+ ## Noncommercial Organizations
42
+
43
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
44
+
45
+ ## Fair Use
46
+
47
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
48
+
49
+ ## No Other Rights
50
+
51
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
52
+
53
+ ## Patent Defense
54
+
55
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
56
+
57
+ ## Violations
58
+
59
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
60
+
61
+ ## No Liability
62
+
63
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
64
+
65
+ ## Definitions
66
+
67
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
68
+
69
+ **You** refers to the individual or entity agreeing to these terms.
70
+
71
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
72
+
73
+ **Your licenses** are all the licenses granted to you for the software under these terms.
74
+
75
+ **Use** means anything you do with the software requiring one of your licenses.
package/README.md ADDED
@@ -0,0 +1,241 @@
1
+ # HomeCubbie household server
2
+
3
+ A small program a household runs on a computer that's always on at home, so
4
+ everyone's phones see the same house (board #291, #293).
5
+
6
+ - **It can't read the house.** Every change, copy, file and phone name arrives
7
+ encrypted on the phone, under a key the server never holds
8
+ (`docs/open/sharing-key-scheme.md`). **One exception: a browser.** A
9
+ browser that joins runs the web app this server serves it, so someone who
10
+ takes over this computer could change that page, and read the house the
11
+ next time the browser opens it. Phones aren't exposed to this, because
12
+ their app comes from the store. (Actual's server has the same property.)
13
+ - **It never contacts anyone.** No update check, no telemetry, no time server.
14
+ `__tests__/no-outgoing-calls.test.ts` fails the build if that changes.
15
+ - **It depends on nothing outside Node.** No `npm install`, nothing to trust but
16
+ Node itself. The same test fails if a dependency is added.
17
+ - **It isn't ours.** It runs on the household's computer, and nothing about it
18
+ is known to HomeCubbie.
19
+
20
+ ## Getting it
21
+
22
+ It's published in three places, none of them run by HomeCubbie. The app's own
23
+ guide, Settings › Sharing › How to set up a server, gives the same commands.
24
+
25
+ - **npm**, for a Mac or a PC with Node 22.18 or later:
26
+
27
+ ```sh
28
+ npx homecubbie-server@0.1.0
29
+ ```
30
+
31
+ - **GitHub's container registry**, for a NAS, a Raspberry Pi, or another Linux
32
+ computer with Docker. The image is built for amd64 and arm64:
33
+
34
+ ```sh
35
+ docker run -d --name homecubbie --restart unless-stopped --network host -v homecubbie:/data ghcr.io/homecubbie/homecubbie-server:0.1.0
36
+ ```
37
+
38
+ - **The code**, at <https://github.com/homecubbie/homecubbie-server>, beside
39
+ the two documents it names: `docs/open/sharing-key-scheme.md` and
40
+ `docs/reference/sharing-security.md`. It's copied there by hand at each
41
+ server release. Board numbers (#…) and decisions (§…) refer to the app's own
42
+ repository, which isn't public.
43
+
44
+ It is source available, not open source: the PolyForm Noncommercial License
45
+ 1.0.0, in `LICENSE`. The licence's own text says what it allows.
46
+
47
+ ## Running it from the source
48
+
49
+ Node 22.18 or later, or Docker.
50
+
51
+ ```sh
52
+ # From this folder, with Node:
53
+ npm start
54
+
55
+ # With Docker:
56
+ docker build -t homecubbie-server .
57
+ docker run -d --name homecubbie --restart unless-stopped --network host -v homecubbie:/data homecubbie-server
58
+ ```
59
+
60
+ | Setting | Default | |
61
+ |---|---|---|
62
+ | `HOMECUBBIE_DATA` | `./homecubbie-data` (`/data` in Docker) | the folder that holds everything |
63
+ | `HOMECUBBIE_PORT` | `5007` | |
64
+ | `HOMECUBBIE_HOSTS` | none | comma-separated names it may be reached by, such as `mac-mini.local`. It always answers to IP addresses and `localhost` |
65
+ | `HOMECUBBIE_HTTPS_CERT`, `HOMECUBBIE_HTTPS_KEY` | none | a certificate and key: given both, it also listens over HTTPS on port 5008 (below) |
66
+ | `HOMECUBBIE_ALLOW_ANY_ADDRESS` | off | `1` to answer any address. Otherwise it closes a connection from anything but this computer and a home network's address ranges: `10.x`, `172.16`–`172.31`, `192.168.x`, link-local, `100.64/10` (Tailscale's), and IPv6's private and link-local ranges |
67
+
68
+ **It answers only the home network, even if a router would let the internet
69
+ in.** A computer's IPv6 address is often public, and not every router blocks
70
+ strangers from it. A café's Wi-Fi uses home ranges too, so stop the server
71
+ when its laptop leaves home.
72
+
73
+ **In Docker, run it on the host's network** (`--network host`, or "host" in a
74
+ NAS's container app), never behind a published port. Docker publishes `-p` on
75
+ the computer's IPv6 addresses too, and hands those connections to the
76
+ container from its own bridge, a private address, so the server can't tell a
77
+ stranger from a phone at home. On the host's network it sees the real address.
78
+ Host networking is for Linux: a NAS or a Pi. On a Mac or a PC, run it with
79
+ Node instead.
80
+
81
+ ## The web app
82
+
83
+ The server also serves HomeCubbie itself, for a laptop's browser (board #376),
84
+ as Actual Budget's server serves Actual.
85
+
86
+ - **On the server's own computer,** open `http://localhost:5007`. There is
87
+ nothing to set up: browsers trust `localhost`, and nothing sent to it crosses
88
+ the Wi-Fi. `http://127.0.0.1:5007` is sent to `localhost`, so the computer
89
+ joins once, not twice.
90
+ - **On any other computer it needs HTTPS.** A browser won't run the web app
91
+ from a plain `http://` address on the Wi-Fi, and it wouldn't be safe if it
92
+ did: someone on the Wi-Fi could swap the page. The household supplies it,
93
+ as with Actual Budget, by one of the two ways below.
94
+ - **A browser joins like a phone:** with an invite code typed from a phone that
95
+ has already joined.
96
+
97
+ The web app is the files in `web/`, beside `src/`. They are written from the
98
+ app's own folder by `npm run export:server-web`, which runs when the package
99
+ is packed, and must be there before `docker build`. The npm package and the
100
+ image carry them; the public repository doesn't, because they're built from
101
+ the app's code. Without `web/`, the server
102
+ answers phones only, and says so when it starts. It reads the folder once, at
103
+ start, and serves only the files it found there: a request is looked up in that
104
+ list, never turned into a path on disk.
105
+
106
+ ### HTTPS for another computer
107
+
108
+ **A reverse proxy in front of the server,** which holds the certificate.
109
+ `tailscale serve` is one: on the server's computer, with Tailscale set up, it
110
+ gives the server an https name inside the household's own private network and
111
+ makes the certificate itself.
112
+
113
+ ```sh
114
+ tailscale serve 5007
115
+ ```
116
+
117
+ - Put the name the browser uses in `HOMECUBBIE_HOSTS`, and start the server
118
+ again.
119
+ - Serve it at the root of a name, never under a path: every request's proof
120
+ covers its path.
121
+ - Pass on the name the browser used. nginx sends its own address unless
122
+ told otherwise (its default is `proxy_set_header Host $proxy_host;`), and
123
+ the server then takes the page for one asked of it at `127.0.0.1`, which it
124
+ sends to `localhost`: the browser's own computer, not this one. Set
125
+ `proxy_set_header Host $host;`.
126
+ - Raise the proxy's upload limit. nginx allows 1 MB unless told otherwise
127
+ (`client_max_body_size`), and a full copy of a house is far more:
128
+ `client_max_body_size 300m;`.
129
+ - A private network such as Tailscale also makes the server reachable away
130
+ from home. That is the household's own choice (board #421).
131
+
132
+ **A certificate and key the server is given,** for a household that has one
133
+ for a name it owns:
134
+
135
+ | Setting | |
136
+ |---|---|
137
+ | `HOMECUBBIE_HTTPS_CERT` | the certificate file, PEM |
138
+ | `HOMECUBBIE_HTTPS_KEY` | its private key, PEM |
139
+
140
+ Given both, the server also listens over HTTPS on port 5008; the phones keep
141
+ 5007. Given one without the other, it doesn't start. It says the certificate's
142
+ last day when it starts, reads both files again when they change (a renewal
143
+ needs no restart), and sends no HSTS, which would hold for the name on every
144
+ port and break other things on that computer. Put the name in
145
+ `HOMECUBBIE_HOSTS`. With Docker, mount the files and add `-p 5008:5008`.
146
+
147
+ **Never:**
148
+
149
+ - forward a router port to reach it from outside;
150
+ - click through a certificate warning. Someone on the Wi-Fi can show the same
151
+ warning. Install the certificate's authority on the computer instead;
152
+ - make a certificate authority of your own for this. mkcert's own README says
153
+ it "should not be used on end users' machines". Whoever uses one anyway
154
+ keeps its root key off the server's computer.
155
+
156
+ **Before retiring the server,** sign out of HomeCubbie in each browser, so
157
+ nothing that answers at that address later can read what the browser kept.
158
+
159
+ ## Setting it up
160
+
161
+ The first time it starts, the server prints a **setup code** in its own log:
162
+ the terminal it was started from, or `docker logs homecubbie`, or the Logs tab
163
+ in Docker Desktop. The code is never shown over the network.
164
+
165
+ In HomeCubbie on the phone that has the house, go to Settings › Sharing ›
166
+ Share this house, and type the server's address and the code. That phone takes
167
+ the server, and the code stops working. Five wrong codes print a new one.
168
+
169
+ Other phones join with an invite from a phone that has already joined. There is
170
+ no password.
171
+
172
+ On the host's network, the address the server prints is the computer's own.
173
+ If it prints one starting `172.`, the container isn't on the host's network:
174
+ start it again with `--network host`.
175
+
176
+ ## Keeping it safe
177
+
178
+ - **Never forward a router port to it, and never put it on a public address.**
179
+ It's meant to be reached on the home Wi-Fi only. Reaching it from away is
180
+ board #421, over a private network.
181
+ - **Back up the data folder.** Stop the server and copy the folder, or the
182
+ Docker volume. The phones notice a restored folder that is missing changes,
183
+ and "Reset sharing from this phone", on the phone whose house is right,
184
+ puts it back (`docs/decisions.md` §355).
185
+ - **The folder holds the server's private key** (`server-key`). Someone who
186
+ copies it could pose as the server, or refuse and delete data. They still
187
+ couldn't read anything, or add a change any phone would accept.
188
+
189
+ ## Starting again
190
+
191
+ Stop the server and delete its data folder. It makes a new key and a new setup
192
+ code on the next start, and the phone that has the house sets it up again.
193
+
194
+ A folder set up before every key change was signed (protocol 2, board #442,
195
+ `docs/decisions.md` §367) has phones no member can trace. Start again in a new
196
+ folder: sharing hadn't shipped before it.
197
+
198
+ ## Moving to a new server
199
+
200
+ When the server's computer dies or its folder is lost, start a new server in a
201
+ new folder, and on the phone that synced last use Settings › Sharing › Move to
202
+ a new server, with the new server's setup code (board #419,
203
+ `docs/decisions.md` §364). The household keeps its id and takes a new key,
204
+ and every other phone joins the new server again with an invite.
205
+
206
+ - **Delete the old folder, and never start the old server again.** Phones
207
+ that haven't joined the new one would carry on with the old one, and lose
208
+ what they did there when they join the new one.
209
+ - **Destroy the old recovery code,** printed or saved. The phone that moved
210
+ the household makes a new one. A phone that held the household's key
211
+ refuses a server no member it knew moved the household to (#442), but the
212
+ old server started again with the old code would still take a phone that
213
+ never heard of the move (`docs/reference/sharing-security.md`).
214
+ - **Clear the site's data in any browser that used the old server**, in the
215
+ browser's own settings for its address. Its page no longer loads, so its
216
+ Sign out can't run, and what it stored stays until then.
217
+
218
+ ## What it keeps
219
+
220
+ `household.db`, plus `copies/` and `files/`, all in the data folder:
221
+
222
+ | | In clear | Encrypted on the phone |
223
+ |---|---|---|
224
+ | Phones | a random id, public key, signing key, the door it came in by with its maker's vouch and its arrival's signatures (#442), when joined and last seen, whether removed | the phone's name |
225
+ | Key changes | epoch, which phone made it, its proof, and its statement as signed: the new key's hash, its kind, the phone it removed, and the roster's public keys | the new key, wrapped for each phone |
226
+ | Changes | arrival number, which phone, its batch number, key epoch, schema version | the change itself |
227
+ | Full copies | key epoch, schema version, which change it runs to, size | the house |
228
+ | Files | a random id, how many pieces | every piece |
229
+ | Invites | a random id, expiry | the household key, sealed under the invite's secret |
230
+
231
+ ## Its tests
232
+
233
+ ```sh
234
+ npm run typecheck
235
+ npm test
236
+ ```
237
+
238
+ Both run in the app's `npm run verify` as `test:server`. The tests start real
239
+ servers on a spare port and talk to them with stand-in phones
240
+ (`__tests__/phone.ts`), which implement the phone's half of the protocol with
241
+ `node:crypto`. The app's own client must agree with that file byte for byte.
package/dist/crypto.js ADDED
@@ -0,0 +1,135 @@
1
+ /**
2
+ * The server's half of the household key scheme
3
+ * (`docs/open/sharing-key-scheme.md`, board #419), using `node:crypto` only.
4
+ *
5
+ * The server never holds the household key. What it does with cryptography is
6
+ * narrow: it keeps its own X25519 key pair, works out each phone's link key from
7
+ * that phone's public key, checks the proof on every request, signs every
8
+ * reply, and opens the one secret a phone ever sends it (an invite's join
9
+ * verifier), which arrives sealed under that phone's link key.
10
+ */
11
+ import { createCipheriv, createDecipheriv, createHash, createHmac, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, timingSafeEqual, } from "node:crypto";
12
+ /** HKDF labels. Each must match the phone's, byte for byte. */
13
+ export const LABEL = {
14
+ link: "hc link v1",
15
+ claim: "hc claim v1",
16
+ transport: "hc transport v1",
17
+ };
18
+ /** The fixed DER prefix of an X25519 SubjectPublicKeyInfo, before the 32 raw bytes. */
19
+ const X25519_SPKI_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
20
+ export function generateServerKeyPair() {
21
+ const { privateKey, publicKey } = generateKeyPairSync("x25519");
22
+ return { privateKey, publicKey: rawPublicKey(publicKey) };
23
+ }
24
+ export function exportPrivateKey(key) {
25
+ return key.export({ type: "pkcs8", format: "der" });
26
+ }
27
+ export function importServerKeyPair(pkcs8) {
28
+ const privateKey = createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" });
29
+ return { privateKey, publicKey: rawPublicKey(createPublicKey(privateKey)) };
30
+ }
31
+ function rawPublicKey(key) {
32
+ const der = key.export({ type: "spki", format: "der" });
33
+ return der.subarray(der.length - 32);
34
+ }
35
+ /** Throws if `raw` is not a usable X25519 public key. */
36
+ export function importPhoneKey(raw) {
37
+ if (raw.length !== 32)
38
+ throw new Error("A phone key is 32 bytes.");
39
+ return createPublicKey({
40
+ key: Buffer.concat([X25519_SPKI_PREFIX, raw]),
41
+ format: "der",
42
+ type: "spki",
43
+ });
44
+ }
45
+ export function hkdf(secret, salt, info) {
46
+ return Buffer.from(hkdfSync("sha256", secret, Buffer.from(salt, "utf8"), info, 32));
47
+ }
48
+ /**
49
+ * The link key one phone shares with this server: neither side ever sends it.
50
+ * X25519 refuses a small-order public key by throwing, so a hostile key fails
51
+ * here rather than producing a predictable secret.
52
+ */
53
+ export function linkKey(server, phoneKey, householdId) {
54
+ const shared = diffieHellman({ privateKey: server.privateKey, publicKey: importPhoneKey(phoneKey) });
55
+ return hkdf(shared, householdId, LABEL.link);
56
+ }
57
+ export function hmac(key, message) {
58
+ return createHmac("sha256", key).update(message, "utf8").digest();
59
+ }
60
+ export function sha256Hex(bytes) {
61
+ return createHash("sha256").update(bytes).digest("hex");
62
+ }
63
+ export function sameBytes(a, b) {
64
+ return a.length === b.length && timingSafeEqual(a, b);
65
+ }
66
+ /** AES-256-GCM, laid out as nonce (12) · ciphertext · tag (16). */
67
+ export function seal(key, plaintext, associatedData) {
68
+ const nonce = randomBytes(12);
69
+ const cipher = createCipheriv("aes-256-gcm", key, nonce);
70
+ cipher.setAAD(Buffer.from(associatedData, "utf8"));
71
+ const body = Buffer.concat([cipher.update(plaintext), cipher.final()]);
72
+ return Buffer.concat([nonce, body, cipher.getAuthTag()]);
73
+ }
74
+ /** Throws if the sealed bytes were altered, or sealed under another key or label. */
75
+ export function open(key, sealed, associatedData) {
76
+ if (sealed.length < 28)
77
+ throw new Error("Too short to be sealed.");
78
+ const decipher = createDecipheriv("aes-256-gcm", key, sealed.subarray(0, 12));
79
+ decipher.setAAD(Buffer.from(associatedData, "utf8"));
80
+ decipher.setAuthTag(sealed.subarray(sealed.length - 16));
81
+ return Buffer.concat([decipher.update(sealed.subarray(12, sealed.length - 16)), decipher.final()]);
82
+ }
83
+ /** The key a phone seals secrets under when it sends them to this server. */
84
+ export function transportKey(link) {
85
+ return hkdf(link, "", LABEL.transport);
86
+ }
87
+ const BASE32 = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
88
+ /**
89
+ * A setup code: 10 random bytes as 16 characters, from an alphabet with no 0/O
90
+ * or 1/I to misread. It only has to stand up to guessing at the door, which
91
+ * `MAX_CLAIM_FAILURES` limits; nothing is ever encrypted under it.
92
+ */
93
+ export function newSetupCode() {
94
+ const bytes = randomBytes(10);
95
+ let bits = 0;
96
+ let value = 0;
97
+ let out = "";
98
+ for (const byte of bytes) {
99
+ value = (value << 8) | byte;
100
+ bits += 8;
101
+ while (bits >= 5) {
102
+ out += BASE32[(value >>> (bits - 5)) & 31];
103
+ bits -= 5;
104
+ }
105
+ }
106
+ return out;
107
+ }
108
+ /** Spaces and dashes are for reading aloud; case doesn't matter. */
109
+ export function normaliseSetupCode(typed) {
110
+ return typed.toUpperCase().replace(/[\s-]/g, "");
111
+ }
112
+ export function claimKey(setupCode) {
113
+ return hkdf(Buffer.from(normaliseSetupCode(setupCode), "utf8"), "", LABEL.claim);
114
+ }
115
+ /**
116
+ * What a claim's reply is proven with: the link key and the setup code
117
+ * together. The link key alone would let whoever answered `/api/hello` on the
118
+ * way, with a key of their own, prove the reply too; only the real server also
119
+ * knows the code (#420). The app builds the same key (`household-crypto.ts`).
120
+ */
121
+ export function claimReplyKey(claim, link) {
122
+ return hmac(claim, `hc claim reply v1\n${link.toString("base64url")}`);
123
+ }
124
+ export function fromBase64Url(text, bytes) {
125
+ if (typeof text !== "string" || !/^[A-Za-z0-9_-]*$/.test(text)) {
126
+ throw new Error("Not base64url.");
127
+ }
128
+ const buffer = Buffer.from(text, "base64url");
129
+ if (bytes !== undefined && buffer.length !== bytes)
130
+ throw new Error(`Expected ${bytes} bytes.`);
131
+ return buffer;
132
+ }
133
+ export function toBase64Url(bytes) {
134
+ return bytes.toString("base64url");
135
+ }
@@ -0,0 +1,103 @@
1
+ /**
2
+ * Which addresses the server answers (the audit's S-5, #420): this computer,
3
+ * and the address ranges a home network uses. Started with
4
+ * `HOMECUBBIE_ALLOW_ANY_ADDRESS=1`, it answers any.
5
+ *
6
+ * It listens on every network its computer is on, because it can't know
7
+ * which one is home. Most home routers stop strangers on the internet
8
+ * reaching it, but not all, above all for IPv6, where a computer's own
9
+ * address is often public. The Mac's own firewall is off by default. So a
10
+ * connection from any other address is closed before a byte of it is read:
11
+ * the internet can't reach the server even where a router would let it.
12
+ *
13
+ * What it doesn't stop:
14
+ * - Another network that uses the same ranges, a café's Wi-Fi say. That stays
15
+ * under "Not closed in this version" in `docs/reference/sharing-security.md`.
16
+ * - Anything behind Docker's port mapping. A published port (`-p`) hands its
17
+ * IPv6 connections to the container from Docker's own bridge, a private
18
+ * address, so this check would pass them. That's why every guide starts
19
+ * the container on the host's network (`--network host`), where it sees
20
+ * the real address (#553's security check, finding 1).
21
+ */
22
+ import { isIP } from "node:net";
23
+ /**
24
+ * True for this computer and the private ranges, false for anything else:
25
+ * - IPv4: `127/8`, `10/8`, `172.16/12`, `192.168/16`, link-local `169.254/16`,
26
+ * and `100.64/10`, which is never routed on the internet (Tailscale's
27
+ * addresses are in it, for #421).
28
+ * - IPv6: `::1`, link-local `fe80::/10`, unique-local `fc00::/7` (Tailscale's
29
+ * too), and an IPv4 address written as IPv6 by the IPv4 rules.
30
+ */
31
+ export function isHomeAddress(address) {
32
+ if (address === undefined)
33
+ return false;
34
+ const bare = address.replace(/%.*$/, "");
35
+ const kind = isIP(bare);
36
+ if (kind === 4)
37
+ return homeIpv4(ipv4Parts(bare));
38
+ if (kind !== 6)
39
+ return false;
40
+ const groups = ipv6Groups(bare);
41
+ const group = (at) => groups[at] ?? 0;
42
+ const mapped = groups.slice(0, 5).every((value) => value === 0) && group(5) === 0xffff;
43
+ if (mapped)
44
+ return homeIpv4([group(6) >> 8, group(6) & 0xff, group(7) >> 8, group(7) & 0xff]);
45
+ if (groups.slice(0, 7).every((value) => value === 0) && group(7) === 1)
46
+ return true;
47
+ return (group(0) & 0xffc0) === 0xfe80 || (group(0) & 0xfe00) === 0xfc00;
48
+ }
49
+ /**
50
+ * Closes, before anything is read, every connection from outside the home
51
+ * ranges. It goes first among the server's connection listeners, so the
52
+ * HTTP or TLS side never sees one. The first refusal is logged, with how to
53
+ * allow any address; the ones after aren't, so a scan can't fill the log.
54
+ */
55
+ export function answerHomeOnly(server, rule) {
56
+ if (rule.anyAddress === true)
57
+ return;
58
+ let told = false;
59
+ server.prependListener("connection", function refuseOutsideHome(socket) {
60
+ if (isHomeAddress(socket.remoteAddress))
61
+ return;
62
+ socket.destroy();
63
+ if (told)
64
+ return;
65
+ told = true;
66
+ rule.log?.info(`refused a connection from ${socket.remoteAddress ?? "an unknown address"}, which isn't this computer or a home network's address. ` +
67
+ "To answer any address, start the server with HOMECUBBIE_ALLOW_ANY_ADDRESS=1.");
68
+ });
69
+ }
70
+ function ipv4Parts(address) {
71
+ const [a = 0, b = 0, c = 0, d = 0] = address.split(".").map(Number);
72
+ return [a, b, c, d];
73
+ }
74
+ function homeIpv4([a, b]) {
75
+ return (a === 127 ||
76
+ a === 10 ||
77
+ (a === 172 && b >= 16 && b <= 31) ||
78
+ (a === 192 && b === 168) ||
79
+ (a === 169 && b === 254) ||
80
+ (a === 100 && b >= 64 && b <= 127));
81
+ }
82
+ /** An IPv6 address, already checked by `isIP`, as its eight 16-bit groups. */
83
+ function ipv6Groups(address) {
84
+ let text = address;
85
+ let tail = [];
86
+ const dotted = /(\d+\.\d+\.\d+\.\d+)$/.exec(text);
87
+ if (dotted !== null) {
88
+ const quad = dotted[1] ?? "";
89
+ const [a, b, c, d] = ipv4Parts(quad);
90
+ tail = [(a << 8) | b, (c << 8) | d];
91
+ text = text.slice(0, text.length - quad.length);
92
+ if (!text.endsWith("::"))
93
+ text = text.slice(0, -1);
94
+ }
95
+ const groupsOf = (part) => (part === "" ? [] : part.split(":").map((group) => parseInt(group, 16)));
96
+ const gap = text.indexOf("::");
97
+ if (gap === -1)
98
+ return [...groupsOf(text), ...tail];
99
+ const head = groupsOf(text.slice(0, gap));
100
+ const rest = groupsOf(text.slice(gap + 2));
101
+ const zeros = new Array(8 - tail.length - head.length - rest.length).fill(0);
102
+ return [...head, ...zeros, ...rest, ...tail];
103
+ }