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.
- package/LICENSE +75 -0
- package/README.md +241 -0
- package/dist/crypto.js +135 -0
- package/dist/home-network.js +103 -0
- package/dist/household.js +912 -0
- package/dist/http-server.js +604 -0
- package/dist/https-listener.js +92 -0
- package/dist/main.js +11 -0
- package/dist/quiet-warnings.js +34 -0
- package/dist/start.js +104 -0
- package/dist/store.js +400 -0
- package/dist/web-app.js +138 -0
- package/package.json +30 -0
- package/web/(now)/index.html +474 -0
- package/web/(now)/month.html +474 -0
- package/web/+not-found.html +474 -0
- package/web/_expo/.routes.json +3 -0
- package/web/_expo/static/css/global-31a95f46f0d26533c432758949249e15.css +1 -0
- package/web/_expo/static/js/web/entry-0f771d01e242dad2ff9cf31c003ad963.js +2839 -0
- package/web/_expo/static/js/web/worker-d922322f88a7f1ead9d277776b9d9ebb.js +22 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/arrow_down.017bc6ba3fc25503e5eb5e53826d48a8.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/error.d1ea1496f9057eb392d5bbf3732a61b7.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/file.19eeb73b9593a38f8e9f418337fc7d10.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/forward.d8b800c443b8972542883e0b9de2bdc6.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/pkg.ab19f4cbc543357183a20571f68380a3.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/back-icon-mask.0a328cd9c1afd0afe8e3b1ec5165b1b4.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/back-icon.35ba0eaec5a4f5ed12ca16fabeae451d.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@2x.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@3x.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/clear-icon.c94f6478e7ae0cdd9f15de1fcb9e5e55@4x.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/close-icon.808e1b1b9b53114ec2838071a7e6daa7.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/close-icon.808e1b1b9b53114ec2838071a7e6daa7@2x.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/close-icon.808e1b1b9b53114ec2838071a7e6daa7@3x.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/close-icon.808e1b1b9b53114ec2838071a7e6daa7@4x.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/react-navigation/elements/search-icon.286d67d3f74808a60a78d3ebf1a5fb57.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/sitemap.412dd9275b6b48ad28f5e3d81bb1f626.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-router/assets/unmatched.20e71bdf79e3a97bf55fd9e164041578.png +0 -0
- package/web/assets/__HomeCubbie/node_modules/expo-sqlite/web/wa-sqlite/wa-sqlite.7ca566fbbc2ec2a172c5aefa63a20f4b.wasm +0 -0
- package/web/assets/assets/fonts/BricolageGrotesque_600SemiBold.e5b5fc505484ff3ca24da73cba67c660.ttf +0 -0
- package/web/assets/assets/images/icon.51a3d296cef4a538e85170017fc2f169.png +0 -0
- package/web/costs/[year].html +474 -0
- package/web/costs/index.html +474 -0
- package/web/favicon.ico +0 -0
- package/web/first-run.html +474 -0
- package/web/form/account/bill/edit/[id].html +474 -0
- package/web/form/account/bill/new.html +474 -0
- package/web/form/account/edit/[id].html +474 -0
- package/web/form/account/new.html +474 -0
- package/web/form/activity/new.html +474 -0
- package/web/form/event/edit/[id].html +474 -0
- package/web/form/event/new.html +474 -0
- package/web/form/note/edit/[id].html +474 -0
- package/web/form/note/new.html +474 -0
- package/web/form/person/edit/[id].html +474 -0
- package/web/form/person/new.html +474 -0
- package/web/form/place/edit/[id].html +474 -0
- package/web/form/place/new.html +474 -0
- package/web/form/policy/correct/[id].html +474 -0
- package/web/form/policy/new.html +474 -0
- package/web/form/policy/renew/[id].html +474 -0
- package/web/form/policy/term/[id].html +474 -0
- package/web/form/schedule/edit/[id].html +474 -0
- package/web/form/schedule/new.html +474 -0
- package/web/form/task/edit/[id].html +474 -0
- package/web/form/task/new.html +474 -0
- package/web/form/thing/edit/[id].html +474 -0
- package/web/form/thing/new.html +474 -0
- package/web/home/about/[category].html +474 -0
- package/web/home/about/index.html +474 -0
- package/web/home/arrange.html +474 -0
- package/web/home/index.html +474 -0
- package/web/home/place/[id].html +474 -0
- package/web/home/thing/[id].html +474 -0
- package/web/homecubbie-web.json +5 -0
- package/web/index.html +474 -0
- package/web/month.html +474 -0
- package/web/records/account/[id].html +474 -0
- package/web/records/accounts.html +474 -0
- package/web/records/document/[id].html +474 -0
- package/web/records/documents.html +474 -0
- package/web/records/events.html +474 -0
- package/web/records/history.html +474 -0
- package/web/records/index.html +474 -0
- package/web/records/people.html +474 -0
- package/web/records/person/[id].html +474 -0
- package/web/records/policies.html +474 -0
- package/web/records/policy/[id].html +474 -0
- package/web/records/supplies.html +474 -0
- package/web/records/year/[year].html +474 -0
- package/web/scan/[id].html +474 -0
- package/web/scan/index.html +474 -0
- package/web/search.html +474 -0
- package/web/settings/app-lock.html +474 -0
- package/web/settings/backup.html +474 -0
- package/web/settings/categories.html +474 -0
- package/web/settings/index.html +474 -0
- package/web/settings/open-source.html +474 -0
- package/web/settings/privacy.html +474 -0
- package/web/settings/property.html +474 -0
- package/web/settings/recently-deleted.html +474 -0
- package/web/settings/reminders.html +474 -0
- package/web/settings/restore.html +474 -0
- package/web/settings/sharing-guide.html +474 -0
- package/web/settings/sharing.html +474 -0
- package/web/settings/start-over.html +474 -0
- package/web/settings/storage.html +474 -0
- package/web/settings/tags.html +474 -0
- package/web/settings/who-uses-this-phone.html +474 -0
- package/web/tasks/[id].html +474 -0
- 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
|
+
}
|