@happyvertical/smrt-vault-relay 0.0.0-stage → 0.60.16
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/AGENTS.md +51 -0
- package/CLAUDE.md +1 -0
- package/LICENSE +7 -0
- package/README.md +361 -2
- package/dist/auth.d.ts +66 -0
- package/dist/auth.d.ts.map +1 -0
- package/dist/chunks/server-0ITpMTMD.js +2358 -0
- package/dist/chunks/server-0ITpMTMD.js.map +1 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +43 -0
- package/dist/cli.js.map +1 -0
- package/dist/config.d.ts +86 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/encoding.d.ts +20 -0
- package/dist/encoding.d.ts.map +1 -0
- package/dist/index.d.ts +11 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +2 -0
- package/dist/lease-store.d.ts +108 -0
- package/dist/lease-store.d.ts.map +1 -0
- package/dist/lease.d.ts +60 -0
- package/dist/lease.d.ts.map +1 -0
- package/dist/manifest.json +15 -0
- package/dist/metadata-store.d.ts +212 -0
- package/dist/metadata-store.d.ts.map +1 -0
- package/dist/node-server.d.ts +14 -0
- package/dist/node-server.d.ts.map +1 -0
- package/dist/object-store.d.ts +60 -0
- package/dist/object-store.d.ts.map +1 -0
- package/dist/relay.d.ts +268 -0
- package/dist/relay.d.ts.map +1 -0
- package/dist/server.d.ts +46 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/smrt-knowledge.json +73 -0
- package/dist/smrt-knowledge.okf.md +56 -0
- package/package.json +54 -3
package/AGENTS.md
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# SMRT Vault Relay
|
|
2
|
+
|
|
3
|
+
Blind snapshot relay for the vault tier (#4799, epic #4668): a deployable
|
|
4
|
+
service storing encrypted snapshot blobs per account. See
|
|
5
|
+
[README.md](README.md) for the protocol, configuration, and deployment.
|
|
6
|
+
|
|
7
|
+
- **Blind by construction.** Never parse, decrypt, or validate blob content,
|
|
8
|
+
never accept or store key material, and never log bodies, signatures,
|
|
9
|
+
nonces, or account ids (log `accountHandle()` instead). Do not import the CLI
|
|
10
|
+
snapshot framing; blobs are opaque bytes.
|
|
11
|
+
- **Order of checks** on every `/v1` route: route match, signature (shape,
|
|
12
|
+
skew, active device of that account, Ed25519, then nonce), `backup.vault`
|
|
13
|
+
entitlement via `requireFeature`, then the body digest and handler. Keep
|
|
14
|
+
authentication failures a single uniform `401`.
|
|
15
|
+
- **Lapsed entitlement** (#4819, `gateEntitlement`): only the write routes
|
|
16
|
+
(`isWriteRoute`: begin, chunk upload, commit, device delete) are refused,
|
|
17
|
+
`402 entitlement_lapsed`; list, latest, download, abort and the lease routes
|
|
18
|
+
stay open until `lapseRetentionDays` (default 90) after the lapse the relay
|
|
19
|
+
first recorded (`vault_relay_lapses`), then `410 retention_expired`. Lapsed
|
|
20
|
+
means upgrade-required denial of an account with committed snapshots; never
|
|
21
|
+
entitled or operator-disabled stays `403`. Deletion is only the admin
|
|
22
|
+
`lapse-sweep` (`sweepLapsedAccounts`), audited in the append-only
|
|
23
|
+
`vault_relay_audit`; no device route deletes lapsed data. Do not slide the
|
|
24
|
+
recorded time.
|
|
25
|
+
- **Security properties are single conditional SQL statements** in
|
|
26
|
+
`metadata-store.ts` (quota reservation, high-water advance, publish, nonce
|
|
27
|
+
insert), portable across SQLite and PostgreSQL. Do not split them into
|
|
28
|
+
read-then-write. Counter drift may only over-count. The high-water advance
|
|
29
|
+
also carries the `maxSequenceJump` bound; the admin reset is the only way
|
|
30
|
+
down.
|
|
31
|
+
- **Primary-writer lease** (#4805, `lease-store.ts`, `lease.ts`): one row per
|
|
32
|
+
account; acquire, renew, release, revoke and the commit-time head advance
|
|
33
|
+
are single conditional statements on it. Publishing needs the holder's
|
|
34
|
+
fencing token; the head never moves back (only the operator's high-water
|
|
35
|
+
reset lowers it, to the latest remaining committed snapshot, clearing the
|
|
36
|
+
holder), and the head and latest committed snapshot are never deleted by a
|
|
37
|
+
device (a missing head row means an abandoned upload). A device delete of the
|
|
38
|
+
sole committed snapshot is `409 last_snapshot`, of the newest of several
|
|
39
|
+
`409 head_snapshot`; both are audited as `snapshot_delete_refused`.
|
|
40
|
+
- **Object keys** are derived (`v1/<account hash>/<upload uuid>/<index>.<object
|
|
41
|
+
id>`, a fresh object id per write) and checked by `assertObjectKey`; never
|
|
42
|
+
build one from a client string or overwrite a recorded object. Removal of a
|
|
43
|
+
pending upload is conditional on `status = 'pending'`.
|
|
44
|
+
- **Schema** (including the lapse and audit tables) comes from `migrateVaultRelayV1` and `migrateVaultRelayLeasesV1` in the deployment migration
|
|
45
|
+
step; request handling only checks table existence. No `@smrt()` models, so
|
|
46
|
+
nothing gains generated REST, CLI, or MCP surfaces.
|
|
47
|
+
- **Owner inputs** (quotas, retention, bucket, databases, domain, namespace)
|
|
48
|
+
have no defaults. Do not invent values; do not edit `happyvertical/iac`.
|
|
49
|
+
|
|
50
|
+
Tests run in-process on SQLite with the filesystem store;
|
|
51
|
+
`src/__tests__/postgres.optional.test.ts` runs under `pnpm test:postgres`.
|
package/CLAUDE.md
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
@AGENTS.md
|
package/LICENSE
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
Copyright <2025> <Happy Vertical Corporation>
|
|
2
|
+
|
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
4
|
+
|
|
5
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
6
|
+
|
|
7
|
+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,362 @@
|
|
|
1
|
-
#
|
|
1
|
+
# s-m-r-t Vault Relay
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`@happyvertical/smrt-vault-relay` is the server side of the vault tier: a blind
|
|
4
|
+
snapshot relay. It stores encrypted snapshots per account, in a monotonic
|
|
5
|
+
sequence, and can never read or validate their content. Devices encrypt with a
|
|
6
|
+
user-held key before upload (see the encrypted snapshot format in
|
|
7
|
+
`smrt app backup --encrypted`); the relay sees sizes, dates, sequences, and
|
|
8
|
+
SHA-256 digests of ciphertext only, and holds no key material.
|
|
9
|
+
|
|
10
|
+
Every device route is authenticated by an Ed25519 device signature and then
|
|
11
|
+
gated by the `backup.vault` feature (`requireFeature` from
|
|
12
|
+
`@happyvertical/smrt-features`), resolved server-side from the account's plan
|
|
13
|
+
grants and overrides. A client cannot claim the entitlement. When the
|
|
14
|
+
entitlement lapses, writes stop at once but restores stay open for a
|
|
15
|
+
retention window; see [Lapsed subscriptions](#lapsed-subscriptions).
|
|
16
|
+
|
|
17
|
+
This package deploys as a container. It is not deployed by this repository:
|
|
18
|
+
hosting is configured in `happyvertical/iac` from the inputs listed under
|
|
19
|
+
[Required configuration](#required-configuration).
|
|
20
|
+
|
|
21
|
+
## Device API
|
|
22
|
+
|
|
23
|
+
All `/v1` routes need the signature headers below. Bodies are JSON or raw
|
|
24
|
+
ciphertext; responses are JSON unless noted.
|
|
25
|
+
|
|
26
|
+
| Route | Purpose |
|
|
27
|
+
| --- | --- |
|
|
28
|
+
| `GET /v1/lease` | Primary-writer lease state: `{ holder, expiresAt, headSequence, latestCommittedSequence, headIsHole }`. Never the token. |
|
|
29
|
+
| `POST /v1/lease/acquire` | `{ baseSequence, ttlSeconds? }`. Grants `{ fencingToken, expiresAt, ttlMs, headSequence }`, or `409 must_restore_first`, `lease_held`, `publish_in_progress`. |
|
|
30
|
+
| `POST /v1/lease/renew` | `{ fencingToken, ttlSeconds? }`. Extends an unexpired lease; `409 lease_lost` otherwise. |
|
|
31
|
+
| `POST /v1/lease/release` | `{ fencingToken }`. `204`; a wrong token changes nothing. |
|
|
32
|
+
| `POST /v1/uploads` | Begin an upload: `{ fencingToken, sequence, byteSize, chunkSize, sha256 }`. Needs the lease. Reserves quota. Returns `uploadId`, `chunkCount`, `expiresAt`. |
|
|
33
|
+
| `PUT /v1/uploads/:uploadId/chunks/:index` | Upload one chunk. Every chunk except the last is exactly `chunkSize` bytes; the request must carry that exact `Content-Length`. A stored chunk is never replaced: an identical retry answers 200, different bytes `409 chunk_exists`. |
|
|
34
|
+
| `POST /v1/uploads/:uploadId/commit` | Publish. The relay checks every chunk is present and the SHA-256 of the whole ciphertext matches the declared digest, then atomically makes it the newest snapshot. |
|
|
35
|
+
| `DELETE /v1/uploads/:uploadId` | Abort a pending upload and release its quota. |
|
|
36
|
+
| `GET /v1/snapshots` | Committed snapshots, newest first. |
|
|
37
|
+
| `GET /v1/snapshots/latest` | The newest committed snapshot. |
|
|
38
|
+
| `GET /v1/snapshots/:sequence` | Metadata of one committed snapshot. |
|
|
39
|
+
| `GET /v1/snapshots/:sequence/chunks/:index` | Chunk bytes (`application/octet-stream`, `x-vault-chunk-sha256`). |
|
|
40
|
+
| `DELETE /v1/snapshots/:sequence` | Delete a committed snapshot. The sequence stays used. The account's last committed snapshot is refused with `409 last_snapshot`; delete only while another committed snapshot remains. The head (an in-flight or latest publish position) is refused with `409 head_snapshot`; delete only below both. |
|
|
41
|
+
| `GET /healthz`, `GET /readyz` | Liveness, and readiness (schema present, object store reachable). No authentication. |
|
|
42
|
+
|
|
43
|
+
Rules the relay enforces:
|
|
44
|
+
|
|
45
|
+
- **Sequences are monotonic.** A new upload must use a sequence above every
|
|
46
|
+
sequence ever published for the account, including deleted ones. A commit
|
|
47
|
+
fails with `409 stale_sequence` if a higher sequence was published first, and
|
|
48
|
+
that upload is discarded. Two uploads cannot share a sequence.
|
|
49
|
+
- **Sequences cannot jump far.** The device picks its sequence and a commit
|
|
50
|
+
raises the high-water mark for good, so a begin or commit more than
|
|
51
|
+
`maxSequenceJump` above the current mark (default **1000**, a safe default
|
|
52
|
+
chosen here, not an owner input; set `VAULT_RELAY_MAX_SEQUENCE_JUMP`) is
|
|
53
|
+
`400 sequence_too_far` with `highWaterSequence` and `maxSequenceJump`. A
|
|
54
|
+
brand-new account starts from a mark of 0, so its first sequence is at most
|
|
55
|
+
the cap. One commit at the largest safe integer can therefore no longer
|
|
56
|
+
make every later upload `stale_sequence`.
|
|
57
|
+
- **One primary writer per account** (#4805). Publishing needs the lease,
|
|
58
|
+
and the lease is granted only to a device whose `baseSequence` is the
|
|
59
|
+
account's head, so a device that is behind must restore first; there is no
|
|
60
|
+
merge. See [Primary-writer lease](#primary-writer-lease).
|
|
61
|
+
- **Publish is atomic.** Pending uploads are never listed, never `latest`, and
|
|
62
|
+
never downloadable. Abandoned uploads expire after the upload TTL.
|
|
63
|
+
- **Quotas count pending uploads.** Bytes and snapshot count are reserved when
|
|
64
|
+
an upload begins (`413 quota_exceeded`) and released on abort, expiry,
|
|
65
|
+
deletion, and retention.
|
|
66
|
+
- **The last snapshot stays.** A device cannot delete the only committed
|
|
67
|
+
snapshot of its account (`409 last_snapshot`), so a compromised or mistaken
|
|
68
|
+
device cannot erase the one restorable copy. Both the refusal
|
|
69
|
+
(`snapshot_delete_refused`) and every successful device delete
|
|
70
|
+
(`snapshot_deleted`) are logged with the hashed account handle, the device id
|
|
71
|
+
and the sequence. The operator can still remove snapshots through the admin
|
|
72
|
+
high-water reset. Two devices deleting the final two snapshots in the same
|
|
73
|
+
instant can both pass on PostgreSQL (each sees the other); retention always
|
|
74
|
+
keeps at least one.
|
|
75
|
+
- **Retention** runs after each commit: the newest `keepLast` committed
|
|
76
|
+
snapshots are kept, plus any committed within the age window. Snapshots
|
|
77
|
+
inside the window count against the snapshot quota, so choose
|
|
78
|
+
`maxSnapshots` above the number of backups an account makes per window plus
|
|
79
|
+
one, or new uploads are refused until older snapshots age out.
|
|
80
|
+
- **Bounded requests.** Chunk size is capped (default 8 MiB plus 64 KiB, hard
|
|
81
|
+
ceiling 64 MiB), JSON bodies at 4 KiB. A body without `Content-Length`, or
|
|
82
|
+
with the wrong one, is refused before it is buffered.
|
|
83
|
+
|
|
84
|
+
### Primary-writer lease
|
|
85
|
+
|
|
86
|
+
One lease row per account names the holder device, a fencing token, an
|
|
87
|
+
expiry on the relay clock, and `headSequence`, the sequence the account's
|
|
88
|
+
data line is at. Every decision is one conditional statement on that row.
|
|
89
|
+
|
|
90
|
+
- **Acquire** succeeds when the lease is free, expired, or already the
|
|
91
|
+
caller's, and `baseSequence` is the head with no upload pending at the head,
|
|
92
|
+
or, when the head's upload was abandoned (a *hole*), the latest committed
|
|
93
|
+
sequence. Every grant, including a re-acquire by the same device,
|
|
94
|
+
increments the fencing token, which fences an earlier process of that
|
|
95
|
+
device too. Refusals: `must_restore_first { headSequence, latestSequence }`,
|
|
96
|
+
`lease_held { holder, expiresAt }`, `publish_in_progress { headSequence }`.
|
|
97
|
+
- **Renew** needs the holder, the current token, and an unexpired lease.
|
|
98
|
+
**Release** needs the holder and the current token. Revoking a device clears
|
|
99
|
+
any lease it holds and bumps the token.
|
|
100
|
+
- **Publish.** Begin records the caller's token with the upload and refuses
|
|
101
|
+
(`must_restore_first`) a caller that is not the unexpired holder with that
|
|
102
|
+
token or whose sequence is not above the head. That begin check is
|
|
103
|
+
advisory; commit enforces: after the digest check it advances the head
|
|
104
|
+
only for the holder with the recorded token, while the upload is still
|
|
105
|
+
pending, forward under an unexpired lease (or, for a retried commit, a head
|
|
106
|
+
already at that sequence). A refused commit discards the upload and answers
|
|
107
|
+
`409 must_restore_first`.
|
|
108
|
+
- **Deletes** never remove the head or the latest committed snapshot, so a
|
|
109
|
+
head without a row is always an abandoned upload, never deleted data.
|
|
110
|
+
|
|
111
|
+
The lifetime is `VAULT_RELAY_LEASE_TTL_SECONDS` (default 300, 30 to 3600); a
|
|
112
|
+
client may ask for less with `ttlSeconds`. Clients judge expiry from `ttlMs`
|
|
113
|
+
on their own monotonic clock, never by comparing `expiresAt` with local time.
|
|
114
|
+
|
|
115
|
+
### Account supersession
|
|
116
|
+
|
|
117
|
+
After a family restarts its vault because the recovery secret is lost
|
|
118
|
+
(`@happyvertical/smrt-app-runtime`, vault key lifecycle `restartAccount`), the
|
|
119
|
+
account layer creates a new account and replaces the old one. The relay
|
|
120
|
+
records only the replacement; it still cannot read anything.
|
|
121
|
+
|
|
122
|
+
A replaced account answers `409 account_superseded` (no other detail, and
|
|
123
|
+
never the new account's id: a client does not follow the relay to another
|
|
124
|
+
account) to every device route that writes or offers a snapshot: lease
|
|
125
|
+
acquire and renew, begin, chunk upload, commit, snapshot delete, list,
|
|
126
|
+
latest and lease status (the refusal on lease status is how a device proves,
|
|
127
|
+
before it follows the new account, that the old one was replaced). Lease
|
|
128
|
+
release, aborting an upload, and a snapshot's metadata and chunks by explicit
|
|
129
|
+
sequence stay available, so state can be cleaned up and a snapshot rescued by
|
|
130
|
+
hand. A stale device on the old account
|
|
131
|
+
therefore stops publishing into a line nobody follows, and restore-latest is
|
|
132
|
+
never handed the old vault. The new account is unaffected.
|
|
133
|
+
|
|
134
|
+
Only the admin listener sets or clears it, so a stolen device key cannot
|
|
135
|
+
silence or redirect an account. The account layer must re-authenticate the
|
|
136
|
+
human owner first. The `DELETE` is for an operator mistake or a restart that
|
|
137
|
+
never reached the working device; it does not undo a device that already ran
|
|
138
|
+
`restartAccount`, which has no local undo. The replacement must already hold an active
|
|
139
|
+
device and must not be replaced itself, so there are no chains or loops.
|
|
140
|
+
Existing snapshots stay until an operator deletes them.
|
|
141
|
+
|
|
142
|
+
### Request signing
|
|
143
|
+
|
|
144
|
+
Each request carries `x-vault-account`, `x-vault-device`, `x-vault-timestamp`
|
|
145
|
+
(unix milliseconds), `x-vault-nonce` (16 to 64 base64url characters, single
|
|
146
|
+
use), `x-vault-content-sha256` (hex SHA-256 of the exact body; the empty-body
|
|
147
|
+
digest for bodiless requests), and `x-vault-signature`: the base64url Ed25519
|
|
148
|
+
signature over
|
|
149
|
+
|
|
150
|
+
```text
|
|
151
|
+
smrt-vault-relay-v1
|
|
152
|
+
<METHOD>
|
|
153
|
+
<path and query, as the server parses it>
|
|
154
|
+
<account id>
|
|
155
|
+
<device id>
|
|
156
|
+
<timestamp>
|
|
157
|
+
<nonce>
|
|
158
|
+
<body sha256>
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
`signRelayRequest()` builds these headers. Requests are rejected with one
|
|
162
|
+
uniform `401 unauthorized` when a header is missing or malformed, the
|
|
163
|
+
timestamp is outside the clock-skew window (default 5 minutes), the device is
|
|
164
|
+
unknown, revoked, or registered to another account, the signature does not
|
|
165
|
+
verify, or the nonce was used before. A body whose digest differs from the
|
|
166
|
+
signed digest is rejected with `400 content_digest_mismatch`. Account and
|
|
167
|
+
device ids match `[A-Za-z0-9][A-Za-z0-9_-]{0,127}`.
|
|
168
|
+
|
|
169
|
+
Entitlement denials answer `403` with the structured body from
|
|
170
|
+
`smrt-features` (`feature_upgrade_required` naming the granting plan, or
|
|
171
|
+
`feature_disabled`). If the entitlement lookup itself fails, the relay answers
|
|
172
|
+
`503 entitlement_unavailable`: it fails closed. An account that never held the
|
|
173
|
+
entitlement, or whose entitlement an operator disabled, is refused on every
|
|
174
|
+
route. An account that held it and stored snapshots is *lapsed*:
|
|
175
|
+
|
|
176
|
+
### Lapsed subscriptions
|
|
177
|
+
|
|
178
|
+
Owner decision #4819. When `backup.vault` lapses for an account that holds
|
|
179
|
+
committed snapshots:
|
|
180
|
+
|
|
181
|
+
- The relay records the lapse time the first time it observes it (a device
|
|
182
|
+
request, or the operator sweep's discovery pass). The time is kept, never
|
|
183
|
+
moved, and cleared when the entitlement is active again.
|
|
184
|
+
- **Writes are refused** (`begin`, chunk upload, commit, device snapshot
|
|
185
|
+
delete) with `402 entitlement_lapsed` and `{ lapsedAt, restoreAvailableUntil }`.
|
|
186
|
+
This code differs from the `403` upgrade/disabled denials and from the `401`
|
|
187
|
+
authentication failure.
|
|
188
|
+
- **Reads stay open** for authenticated devices of the account: list,
|
|
189
|
+
`latest`, snapshot metadata and chunk download, aborting an upload, and the
|
|
190
|
+
lease routes (restore-latest holds the lease while it downloads).
|
|
191
|
+
- After `lapseRetentionDays` (default **90**, `VAULT_RELAY_LAPSE_RETENTION_DAYS`,
|
|
192
|
+
1 to 3650) reads answer `410 retention_expired` and the account is eligible
|
|
193
|
+
for the sweep. Writes keep answering `402 entitlement_lapsed`.
|
|
194
|
+
- **The sweep is an operator action, not a device action.**
|
|
195
|
+
`POST /admin/v1/lapse-sweep` (admin token) with `{ dryRun?, limit?, cursor? }`
|
|
196
|
+
and an optional `x-vault-operator` label header. Per run it handles at most
|
|
197
|
+
`limit` accounts (default 10, at most 100) in two phases: a discovery pass
|
|
198
|
+
over accounts with snapshots but no lapse record (resume with the returned
|
|
199
|
+
`nextCursor`), which starts the window for lapses no device reported; and a
|
|
200
|
+
deletion pass over lapses whose window has elapsed. Each account is
|
|
201
|
+
re-checked first: one that is entitled again keeps its data and has its
|
|
202
|
+
lapse cleared. Deletion uses the normal removal path (rows, counters,
|
|
203
|
+
objects). Every deleted account writes a `lapse_sweep_started` and a
|
|
204
|
+
`lapse_sweep_completed` record to the append-only `vault_relay_audit` table:
|
|
205
|
+
time, operator (label plus a fingerprint of the admin token, never the
|
|
206
|
+
token), hashed account handle, snapshot count and bytes. Re-running is
|
|
207
|
+
idempotent; a run that crashed mid-account is finished by the next one. A
|
|
208
|
+
dry run reports the same result and changes and audits nothing. A sweep
|
|
209
|
+
leaves the account's high-water mark and lease head as they were.
|
|
210
|
+
|
|
211
|
+
## Admin API (account layer and operator)
|
|
212
|
+
|
|
213
|
+
Served on a separate listener, which must stay cluster-internal, and only when
|
|
214
|
+
`VAULT_RELAY_ADMIN_TOKEN` is set. Requests use `Authorization: Bearer <token>`.
|
|
215
|
+
|
|
216
|
+
| Route | Purpose |
|
|
217
|
+
| --- | --- |
|
|
218
|
+
| `PUT /admin/v1/accounts/:account/devices/:device` | Register a device key: `{ publicKey }` (raw 32-byte Ed25519 key, base64url). Idempotent for the same key. A revoked id, or a different key under an existing id, is `409`. |
|
|
219
|
+
| `DELETE /admin/v1/accounts/:account/devices/:device` | Revoke a device. Effective on its next request. |
|
|
220
|
+
| `GET /admin/v1/accounts/:account` | Usage, snapshot sizes and dates, device states. Never content. |
|
|
221
|
+
| `POST /admin/v1/accounts/:account/high-water` | Reset the sequence high-water mark of an account whose mark was pushed out of reach: `{ highWaterSequence, removeSnapshotsAbove? }`. The new mark may not exceed the current one. A snapshot or pending upload above it is refused (`409 snapshots_above_high_water`, sequences listed) unless `removeSnapshotsAbove` is `true`, which deletes those rows and their objects first. Logged as `high_water_reset` (hashed account handle, previous and new mark, removed sequences). |
|
|
222
|
+
| `PUT /admin/v1/accounts/:account/superseded-by` | Replace an account (#4817): `{ supersededBy }`. For the account layer at the start of a vault restart, as soon as the new account exists with an active device (before the first backup into it): from then on a stale device cannot publish into the old line. `201` set, `200` repeated, `404 no_account`, `409 target_not_ready` (no active device), `409 target_superseded` or `409 account_is_target` (no chains or loops), `409 already_superseded` (another target). See [Account supersession](#account-supersession). |
|
|
223
|
+
| `DELETE /admin/v1/accounts/:account/superseded-by` | Undo it, for an operator mistake. `204`, or `404 no_supersession`. |
|
|
224
|
+
| `POST /admin/v1/accounts/:account/reconcile` | Recompute quota counters from snapshot rows. Run it while the account is quiet: a reconcile racing an upload can under-count until the next reconcile. |
|
|
225
|
+
| `POST /admin/v1/sweep` | Expire abandoned uploads and old nonces (also runs every minute). |
|
|
226
|
+
| `POST /admin/v1/lapse-sweep` | Audited deletion of lapsed accounts' snapshots after the retention window (#4819). `{ dryRun?, limit?, cursor? }`; see [Lapsed subscriptions](#lapsed-subscriptions). |
|
|
227
|
+
|
|
228
|
+
The same hooks are available in-process: `relay.registerDevice()`,
|
|
229
|
+
`relay.revokeDevice()`, `relay.operatorView()`.
|
|
230
|
+
|
|
231
|
+
## Storage
|
|
232
|
+
|
|
233
|
+
Chunk bytes live in an object store under relay-derived keys,
|
|
234
|
+
`v1/<sha256 account handle>/<upload uuid>/<index>.<random object id>`; no
|
|
235
|
+
client string becomes part of a key. Each write attempt gets its own object,
|
|
236
|
+
and a chunk row is recorded only while its upload is still pending, so a write
|
|
237
|
+
that lands after an abort, expiry, or publish is deleted instead of counted. `FilesystemObjectStore` (atomic temp-and-rename writes) serves
|
|
238
|
+
tests and single-node development. `createS3ObjectStore()` uses the
|
|
239
|
+
`@happyvertical/files` S3 provider with path-style addressing for Garage.
|
|
240
|
+
|
|
241
|
+
Metadata lives in the service database (SQLite or PostgreSQL) in ten
|
|
242
|
+
`vault_relay_*` tables. `migrateVaultRelayV1(db)` and
|
|
243
|
+
`migrateVaultRelayLeasesV1(db)` create them idempotently.
|
|
244
|
+
Run it as the deployment's migration step (`node dist/cli.js migrate`); the
|
|
245
|
+
server checks the tables exist at readiness and never creates schema while
|
|
246
|
+
serving.
|
|
247
|
+
|
|
248
|
+
**Upgrading to account supersession (#4817).** `migrateVaultRelayV1` now also
|
|
249
|
+
creates `vault_relay_supersessions`. Re-run the migration job (it is
|
|
250
|
+
idempotent) **before** deploying this version: until the table exists,
|
|
251
|
+
`/readyz` reports `schema_missing` and the relay is not ready, and every
|
|
252
|
+
device route that checks supersession (backup, restore, lease acquire and
|
|
253
|
+
renew) fails.
|
|
254
|
+
|
|
255
|
+
**Upgrading to the lapse window (#4819).** `migrateVaultRelayV1` also creates
|
|
256
|
+
`vault_relay_lapses` and `vault_relay_audit` (plain `CREATE TABLE IF NOT
|
|
257
|
+
EXISTS`, no change to existing tables). Re-run the migration job before
|
|
258
|
+
deploying this version; until then `/readyz` reports `schema_missing`.
|
|
259
|
+
|
|
260
|
+
## Required configuration
|
|
261
|
+
|
|
262
|
+
These are owner inputs. The relay has no defaults for them and refuses to start
|
|
263
|
+
without them (except the admin token, see its row). Values are not chosen here.
|
|
264
|
+
|
|
265
|
+
| Variable | Meaning |
|
|
266
|
+
| --- | --- |
|
|
267
|
+
| `VAULT_RELAY_DATABASE_URL` | Relay metadata database (`postgres://…`, or a SQLite path). Secret. |
|
|
268
|
+
| `VAULT_RELAY_ENTITLEMENTS_DATABASE_URL` | Database holding the platform's feature and subscription tables, read for `backup.vault`. May equal the relay database. Secret; read-only access suffices. |
|
|
269
|
+
| `VAULT_RELAY_STORAGE` | `s3` in deployment (`filesystem` for development). |
|
|
270
|
+
| `VAULT_RELAY_S3_BUCKET` | Garage bucket for ciphertext. |
|
|
271
|
+
| `VAULT_RELAY_S3_ENDPOINT` | Garage S3 endpoint URL. |
|
|
272
|
+
| `VAULT_RELAY_S3_REGION` | Region name the Garage cluster is configured with. |
|
|
273
|
+
| `VAULT_RELAY_S3_ACCESS_KEY_ID`, `VAULT_RELAY_S3_SECRET_ACCESS_KEY` | Bucket-scoped Garage key. Secret. |
|
|
274
|
+
| `VAULT_RELAY_QUOTA_MAX_BYTES` | Per-account byte quota (committed plus pending). |
|
|
275
|
+
| `VAULT_RELAY_QUOTA_MAX_SNAPSHOTS` | Per-account snapshot quota (committed plus pending). Must exceed `KEEP_LAST`. |
|
|
276
|
+
| `VAULT_RELAY_RETENTION_KEEP_LAST` | Newest committed snapshots always kept (at least 1). |
|
|
277
|
+
| `VAULT_RELAY_RETENTION_KEEP_WITHIN_DAYS` | Also keep snapshots committed within this many days (0 for none). |
|
|
278
|
+
| `VAULT_RELAY_ADMIN_TOKEN` | Admin bearer token, at least 32 characters. Secret. Optional to the process: without it the admin listener does not start, so the account layer cannot register devices. |
|
|
279
|
+
|
|
280
|
+
Optional technical settings: `VAULT_RELAY_PORT` (8080), `VAULT_RELAY_ADMIN_PORT`
|
|
281
|
+
(8081), `VAULT_RELAY_MAX_CHUNK_BYTES` (8454144), `VAULT_RELAY_UPLOAD_TTL_SECONDS`
|
|
282
|
+
(86400), `VAULT_RELAY_MAX_CLOCK_SKEW_SECONDS` (300), `VAULT_RELAY_MAX_SEQUENCE_JUMP` (1000),
|
|
283
|
+
`VAULT_RELAY_LEASE_TTL_SECONDS` (300), `VAULT_RELAY_LAPSE_RETENTION_DAYS` (90, 1 to
|
|
284
|
+
3650). With `VAULT_RELAY_STORAGE=filesystem`,
|
|
285
|
+
`VAULT_RELAY_STORAGE_PATH` is required.
|
|
286
|
+
|
|
287
|
+
The deployment also needs, from the owner: the namespace, the public domain and
|
|
288
|
+
TLS for the device API, the image registry and digest, and network policy that
|
|
289
|
+
keeps the admin port private. The device Ingress must accept request bodies of
|
|
290
|
+
at least the maximum chunk size plus headroom: with the default 8 MiB + 64 KiB
|
|
291
|
+
chunks, set the ingress body limit to at least `9m` (`10m` in the `smrt-app`
|
|
292
|
+
chart's allowed set; ingress-nginx defaults to `1m`). Keep
|
|
293
|
+
`VAULT_RELAY_MAX_CHUNK_BYTES` below the ingress limit the chart permits.
|
|
294
|
+
|
|
295
|
+
## Deployment
|
|
296
|
+
|
|
297
|
+
`packages/vault-relay/Dockerfile` builds the image from the repository root:
|
|
298
|
+
|
|
299
|
+
```sh
|
|
300
|
+
docker build -f packages/vault-relay/Dockerfile -t <registry>/smrt-vault-relay:<version> .
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
The image runs as `node`, listens on 8080 (device API) and 8081 (admin API),
|
|
304
|
+
and takes `serve` (default) or `migrate` as its command. For the `smrt-app`
|
|
305
|
+
chart (see the [deployment guide](../../docs/content/deployment.md)), model it
|
|
306
|
+
as:
|
|
307
|
+
|
|
308
|
+
- one `web` workload, `writer: true`, command `["node", "dist/cli.js", "serve"]`,
|
|
309
|
+
port 8080, `readinessProbe` `GET /readyz`, `livenessProbe` `GET /healthz`,
|
|
310
|
+
every variable above from named, immutable Secret keys, and a pod and
|
|
311
|
+
container security context that is non-root with a read-only root
|
|
312
|
+
filesystem (the relay writes nothing locally with S3 storage);
|
|
313
|
+
- the migration job with command `["node", "dist/cli.js", "migrate"]` and only
|
|
314
|
+
`VAULT_RELAY_DATABASE_URL`. The DDL is idempotent; the chart's
|
|
315
|
+
`smrt-release-v1` wrapper requirements still apply and are an adoption task;
|
|
316
|
+
- the admin port exposed only through a cluster-internal Service, never the
|
|
317
|
+
Ingress.
|
|
318
|
+
|
|
319
|
+
The relay keeps no state on local disk with S3 storage, so replicas can scale
|
|
320
|
+
horizontally: every security check is a conditional database statement.
|
|
321
|
+
|
|
322
|
+
## Security model
|
|
323
|
+
|
|
324
|
+
| Threat | Control | Test |
|
|
325
|
+
| --- | --- | --- |
|
|
326
|
+
| Unauthenticated or replayed request | Ed25519 signature over method, path, account, device, timestamp, nonce, body digest; skew window; primary-key nonce table | `relay.test.ts` authentication |
|
|
327
|
+
| Revoked device, or another account's device | Device lookup by (account, device), active only; ids never reused | `relay.test.ts` authentication |
|
|
328
|
+
| Cross-account access | Every query scoped by the authenticated account; uploads looked up by (account, upload) | `relay.test.ts` cross-account isolation |
|
|
329
|
+
| Quota or size abuse | Atomic conditional reservation; declared length checked before buffering; chunk cap | `relay.test.ts` quotas and request bounds |
|
|
330
|
+
| A device erasing the only restorable snapshot | Conditional delete only while another committed snapshot exists; refusal and removals audited by device and sequence | `relay.test.ts` device deletes |
|
|
331
|
+
| Partial upload becoming latest | Pending status; commit verifies every chunk and the whole digest | `relay.test.ts` atomic publish |
|
|
332
|
+
| Sequence rollback or overwrite | Account high-water mark advanced conditionally; unique (account, sequence) | `relay.test.ts` atomic publish |
|
|
333
|
+
| One commit pins the high-water mark out of reach, so every later upload is stale | Step cap at begin and inside the advance statement; operator reset on the admin listener, audited | `relay.test.ts` sequence step cap and high-water reset |
|
|
334
|
+
| Entitlement bypass, off plan | `requireFeature('backup.vault')` per request from server-side grants; fails closed | `entitlements.test.ts` |
|
|
335
|
+
| Writing after the plan lapsed; data lingering forever, or a family locked out of its own data (#4819) | Writes `402 entitlement_lapsed`; reads open for `lapseRetentionDays` from the first observed lapse, then `410`; audited operator sweep deletes | `lapse.test.ts` |
|
|
336
|
+
| Leakage through logs, listings, or storage | Logs carry route, status, and a hashed account handle only; operator view is sizes and dates | `blind-operator.test.ts` |
|
|
337
|
+
| Two devices publishing divergent lines | Lease row: one holder, base must be the head, head advanced at commit only by the holder's recorded fencing token | `lease.test.ts` |
|
|
338
|
+
| Lease theft or reuse after expiry; stale fencing token | Holder and token must both match; relay-clock expiry; token bumped on every grant and on revocation | `lease.test.ts` expiry and takeover, re-acquire fencing |
|
|
339
|
+
| Replayed acquire | Signed nonce and timestamp | `lease.test.ts` replay |
|
|
340
|
+
| A stale device keeps publishing into a replaced account, or restore-latest is offered the old vault (#4817) | Admin-set supersession; writes, list and latest refuse with `409 account_superseded` | `supersession.test.ts`, `restore-e2e.test.ts` restarted account |
|
|
341
|
+
| A stolen device silences or redirects an account | Supersession exists only on the admin listener; the refusal names no other account | `supersession.test.ts` set by the account layer only |
|
|
342
|
+
| Supersession chains or loops | Target must have an active device and must not be replaced | `supersession.test.ts` target checks |
|
|
343
|
+
| Path traversal in object keys | Keys derived from hash, server UUID, and index; regex and containment checks | `storage-and-config.test.ts` |
|
|
344
|
+
|
|
345
|
+
Residual risks: a publish whose head advanced but whose commit was never
|
|
346
|
+
retried blocks other devices' acquire (`publish_in_progress`) until the
|
|
347
|
+
upload TTL expires; the relay is trusted to name the latest snapshot to a
|
|
348
|
+
device with no local history (a device with history refuses anything below
|
|
349
|
+
the highest sequence it has seen). An operator can see ciphertext sizes, timing, and device ids
|
|
350
|
+
(an HVSF snapshot also carries its producing device id, key id, generation, and
|
|
351
|
+
length in a clear file header that the relay stores but never parses);
|
|
352
|
+
quota counters can over-count after a crash between steps (`reconcile`
|
|
353
|
+
repairs it); a crash between storing a chunk object and recording it can leave
|
|
354
|
+
one unreferenced ciphertext object.
|
|
355
|
+
|
|
356
|
+
## Development
|
|
357
|
+
|
|
358
|
+
```sh
|
|
359
|
+
pnpm --filter @happyvertical/smrt-vault-relay test
|
|
360
|
+
pnpm --filter @happyvertical/smrt-vault-relay typecheck
|
|
361
|
+
pnpm --filter @happyvertical/smrt-vault-relay test:postgres # needs a CI PostgreSQL URL
|
|
362
|
+
```
|
package/dist/auth.d.ts
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Device-signature request authentication (protocol `smrt-vault-relay-v1`).
|
|
3
|
+
*
|
|
4
|
+
* A device signs every request with its Ed25519 key. The signed string binds
|
|
5
|
+
* the method, path and query, the claimed account and device, a timestamp, a
|
|
6
|
+
* single-use nonce, and the SHA-256 of the exact request body:
|
|
7
|
+
*
|
|
8
|
+
* ```text
|
|
9
|
+
* smrt-vault-relay-v1
|
|
10
|
+
* <METHOD>
|
|
11
|
+
* <path and query, exactly as sent>
|
|
12
|
+
* <account id>
|
|
13
|
+
* <device id>
|
|
14
|
+
* <timestamp, unix milliseconds>
|
|
15
|
+
* <nonce>
|
|
16
|
+
* <body sha256, lowercase hex>
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* The relay accepts the signature only from a key registered and active for
|
|
20
|
+
* that account and device, within the clock-skew window, with a nonce it has
|
|
21
|
+
* not seen, and with a body whose digest matches. It derives nothing about
|
|
22
|
+
* identity from blob content.
|
|
23
|
+
*/
|
|
24
|
+
import { type KeyObject } from 'node:crypto';
|
|
25
|
+
export declare const SIGNATURE_PROTOCOL = "smrt-vault-relay-v1";
|
|
26
|
+
export declare const HEADER_ACCOUNT = "x-vault-account";
|
|
27
|
+
export declare const HEADER_DEVICE = "x-vault-device";
|
|
28
|
+
export declare const HEADER_TIMESTAMP = "x-vault-timestamp";
|
|
29
|
+
export declare const HEADER_NONCE = "x-vault-nonce";
|
|
30
|
+
export declare const HEADER_CONTENT_SHA256 = "x-vault-content-sha256";
|
|
31
|
+
export declare const HEADER_SIGNATURE = "x-vault-signature";
|
|
32
|
+
export interface SignedRequestFields {
|
|
33
|
+
method: string;
|
|
34
|
+
/** Path plus query string exactly as sent, e.g. `/v1/snapshots?x=1`. */
|
|
35
|
+
pathAndQuery: string;
|
|
36
|
+
accountId: string;
|
|
37
|
+
deviceId: string;
|
|
38
|
+
timestamp: number;
|
|
39
|
+
nonce: string;
|
|
40
|
+
contentSha256: string;
|
|
41
|
+
}
|
|
42
|
+
/** The exact byte string a device signs. */
|
|
43
|
+
export declare function canonicalRequest(fields: SignedRequestFields): Buffer;
|
|
44
|
+
/** Import a raw 32-byte Ed25519 public key (base64url). */
|
|
45
|
+
export declare function importDevicePublicKey(encoded: string): KeyObject | null;
|
|
46
|
+
/** Raw 32-byte public key of an Ed25519 key object, base64url. */
|
|
47
|
+
export declare function exportDevicePublicKey(key: KeyObject): string;
|
|
48
|
+
/** Build an Ed25519 private key object from a raw 32-byte seed. */
|
|
49
|
+
export declare function importDevicePrivateKey(seed: Uint8Array): KeyObject;
|
|
50
|
+
/**
|
|
51
|
+
* Client helper: the headers that authenticate one request. The caller
|
|
52
|
+
* supplies a fresh random nonce and the SHA-256 of the exact body it sends.
|
|
53
|
+
*/
|
|
54
|
+
export declare function signRelayRequest(fields: SignedRequestFields, privateKey: KeyObject): Record<string, string>;
|
|
55
|
+
export interface ParsedSignature {
|
|
56
|
+
fields: SignedRequestFields;
|
|
57
|
+
signature: Uint8Array;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Read and shape-check the signature headers; `null` when any is missing or
|
|
61
|
+
* malformed. Does not verify the signature.
|
|
62
|
+
*/
|
|
63
|
+
export declare function parseSignatureHeaders(method: string, pathAndQuery: string, headers: Headers): ParsedSignature | null;
|
|
64
|
+
/** Verify an Ed25519 signature over the canonical request. */
|
|
65
|
+
export declare function verifySignature(parsed: ParsedSignature, publicKey: KeyObject): boolean;
|
|
66
|
+
//# sourceMappingURL=auth.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,aAAa,CAAC;AAUrB,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAChD,eAAO,MAAM,aAAa,mBAAmB,CAAC;AAC9C,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AACpD,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAC5C,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAC9D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAQpD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,4CAA4C;AAC5C,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAcpE;AAED,2DAA2D;AAC3D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAYvE;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAG5D;AAED,mEAAmE;AACnE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CASlE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,mBAAmB,EAC3B,UAAU,EAAE,SAAS,GACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,UAAU,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,GACf,eAAe,GAAG,IAAI,CAmCxB;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,SAAS,GACnB,OAAO,CAWT"}
|