@happyvertical/smrt-vault-relay 0.0.0-stage → 0.60.17

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 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,365 @@
1
- # Temporary Holding Version
1
+ # s-m-r-t Vault Relay
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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`). It holds no key material, but observes public
8
+ framing, sizes, sequences, account/device identifiers and traffic activity.
9
+ The complete [metadata visibility contract](../cli/agents/encrypted-snapshots.md#relay-visible-metadata)
10
+ distinguishes this from content encryption; the relay's SHA-256 digests cover
11
+ ciphertext.
12
+
13
+ Every device route is authenticated by an Ed25519 device signature and then
14
+ gated by the `backup.vault` feature (`requireFeature` from
15
+ `@happyvertical/smrt-features`), resolved server-side from the account's plan
16
+ grants and overrides. A client cannot claim the entitlement. When the
17
+ entitlement lapses, writes stop at once but restores stay open for a
18
+ retention window; see [Lapsed subscriptions](#lapsed-subscriptions).
19
+
20
+ This package deploys as a container. It is not deployed by this repository:
21
+ hosting is configured in `happyvertical/iac` from the inputs listed under
22
+ [Required configuration](#required-configuration).
23
+
24
+ ## Device API
25
+
26
+ All `/v1` routes need the signature headers below. Bodies are JSON or raw
27
+ ciphertext; responses are JSON unless noted.
28
+
29
+ | Route | Purpose |
30
+ | --- | --- |
31
+ | `GET /v1/lease` | Primary-writer lease state: `{ holder, expiresAt, headSequence, latestCommittedSequence, headIsHole }`. Never the token. |
32
+ | `POST /v1/lease/acquire` | `{ baseSequence, ttlSeconds? }`. Grants `{ fencingToken, expiresAt, ttlMs, headSequence }`, or `409 must_restore_first`, `lease_held`, `publish_in_progress`. |
33
+ | `POST /v1/lease/renew` | `{ fencingToken, ttlSeconds? }`. Extends an unexpired lease; `409 lease_lost` otherwise. |
34
+ | `POST /v1/lease/release` | `{ fencingToken }`. `204`; a wrong token changes nothing. |
35
+ | `POST /v1/uploads` | Begin an upload: `{ fencingToken, sequence, byteSize, chunkSize, sha256 }`. Needs the lease. Reserves quota. Returns `uploadId`, `chunkCount`, `expiresAt`. |
36
+ | `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`. |
37
+ | `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. |
38
+ | `DELETE /v1/uploads/:uploadId` | Abort a pending upload and release its quota. |
39
+ | `GET /v1/snapshots` | Committed snapshots, newest first. |
40
+ | `GET /v1/snapshots/latest` | The newest committed snapshot. |
41
+ | `GET /v1/snapshots/:sequence` | Metadata of one committed snapshot. |
42
+ | `GET /v1/snapshots/:sequence/chunks/:index` | Chunk bytes (`application/octet-stream`, `x-vault-chunk-sha256`). |
43
+ | `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. |
44
+ | `GET /healthz`, `GET /readyz` | Liveness, and readiness (schema present, object store reachable). No authentication. |
45
+
46
+ Rules the relay enforces:
47
+
48
+ - **Sequences are monotonic.** A new upload must use a sequence above every
49
+ sequence ever published for the account, including deleted ones. A commit
50
+ fails with `409 stale_sequence` if a higher sequence was published first, and
51
+ that upload is discarded. Two uploads cannot share a sequence.
52
+ - **Sequences cannot jump far.** The device picks its sequence and a commit
53
+ raises the high-water mark for good, so a begin or commit more than
54
+ `maxSequenceJump` above the current mark (default **1000**, a safe default
55
+ chosen here, not an owner input; set `VAULT_RELAY_MAX_SEQUENCE_JUMP`) is
56
+ `400 sequence_too_far` with `highWaterSequence` and `maxSequenceJump`. A
57
+ brand-new account starts from a mark of 0, so its first sequence is at most
58
+ the cap. One commit at the largest safe integer can therefore no longer
59
+ make every later upload `stale_sequence`.
60
+ - **One primary writer per account** (#4805). Publishing needs the lease,
61
+ and the lease is granted only to a device whose `baseSequence` is the
62
+ account's head, so a device that is behind must restore first; there is no
63
+ merge. See [Primary-writer lease](#primary-writer-lease).
64
+ - **Publish is atomic.** Pending uploads are never listed, never `latest`, and
65
+ never downloadable. Abandoned uploads expire after the upload TTL.
66
+ - **Quotas count pending uploads.** Bytes and snapshot count are reserved when
67
+ an upload begins (`413 quota_exceeded`) and released on abort, expiry,
68
+ deletion, and retention.
69
+ - **The last snapshot stays.** A device cannot delete the only committed
70
+ snapshot of its account (`409 last_snapshot`), so a compromised or mistaken
71
+ device cannot erase the one restorable copy. Both the refusal
72
+ (`snapshot_delete_refused`) and every successful device delete
73
+ (`snapshot_deleted`) are logged with the hashed account handle, the device id
74
+ and the sequence. The operator can still remove snapshots through the admin
75
+ high-water reset. Two devices deleting the final two snapshots in the same
76
+ instant can both pass on PostgreSQL (each sees the other); retention always
77
+ keeps at least one.
78
+ - **Retention** runs after each commit: the newest `keepLast` committed
79
+ snapshots are kept, plus any committed within the age window. Snapshots
80
+ inside the window count against the snapshot quota, so choose
81
+ `maxSnapshots` above the number of backups an account makes per window plus
82
+ one, or new uploads are refused until older snapshots age out.
83
+ - **Bounded requests.** Chunk size is capped (default 8 MiB plus 64 KiB, hard
84
+ ceiling 64 MiB), JSON bodies at 4 KiB. A body without `Content-Length`, or
85
+ with the wrong one, is refused before it is buffered.
86
+
87
+ ### Primary-writer lease
88
+
89
+ One lease row per account names the holder device, a fencing token, an
90
+ expiry on the relay clock, and `headSequence`, the sequence the account's
91
+ data line is at. Every decision is one conditional statement on that row.
92
+
93
+ - **Acquire** succeeds when the lease is free, expired, or already the
94
+ caller's, and `baseSequence` is the head with no upload pending at the head,
95
+ or, when the head's upload was abandoned (a *hole*), the latest committed
96
+ sequence. Every grant, including a re-acquire by the same device,
97
+ increments the fencing token, which fences an earlier process of that
98
+ device too. Refusals: `must_restore_first { headSequence, latestSequence }`,
99
+ `lease_held { holder, expiresAt }`, `publish_in_progress { headSequence }`.
100
+ - **Renew** needs the holder, the current token, and an unexpired lease.
101
+ **Release** needs the holder and the current token. Revoking a device clears
102
+ any lease it holds and bumps the token.
103
+ - **Publish.** Begin records the caller's token with the upload and refuses
104
+ (`must_restore_first`) a caller that is not the unexpired holder with that
105
+ token or whose sequence is not above the head. That begin check is
106
+ advisory; commit enforces: after the digest check it advances the head
107
+ only for the holder with the recorded token, while the upload is still
108
+ pending, forward under an unexpired lease (or, for a retried commit, a head
109
+ already at that sequence). A refused commit discards the upload and answers
110
+ `409 must_restore_first`.
111
+ - **Deletes** never remove the head or the latest committed snapshot, so a
112
+ head without a row is always an abandoned upload, never deleted data.
113
+
114
+ The lifetime is `VAULT_RELAY_LEASE_TTL_SECONDS` (default 300, 30 to 3600); a
115
+ client may ask for less with `ttlSeconds`. Clients judge expiry from `ttlMs`
116
+ on their own monotonic clock, never by comparing `expiresAt` with local time.
117
+
118
+ ### Account supersession
119
+
120
+ After a family restarts its vault because the recovery secret is lost
121
+ (`@happyvertical/smrt-app-runtime`, vault key lifecycle `restartAccount`), the
122
+ account layer creates a new account and replaces the old one. The relay
123
+ records only the replacement; it still cannot read anything.
124
+
125
+ A replaced account answers `409 account_superseded` (no other detail, and
126
+ never the new account's id: a client does not follow the relay to another
127
+ account) to every device route that writes or offers a snapshot: lease
128
+ acquire and renew, begin, chunk upload, commit, snapshot delete, list,
129
+ latest and lease status (the refusal on lease status is how a device proves,
130
+ before it follows the new account, that the old one was replaced). Lease
131
+ release, aborting an upload, and a snapshot's metadata and chunks by explicit
132
+ sequence stay available, so state can be cleaned up and a snapshot rescued by
133
+ hand. A stale device on the old account
134
+ therefore stops publishing into a line nobody follows, and restore-latest is
135
+ never handed the old vault. The new account is unaffected.
136
+
137
+ Only the admin listener sets or clears it, so a stolen device key cannot
138
+ silence or redirect an account. The account layer must re-authenticate the
139
+ human owner first. The `DELETE` is for an operator mistake or a restart that
140
+ never reached the working device; it does not undo a device that already ran
141
+ `restartAccount`, which has no local undo. The replacement must already hold an active
142
+ device and must not be replaced itself, so there are no chains or loops.
143
+ Existing snapshots stay until an operator deletes them.
144
+
145
+ ### Request signing
146
+
147
+ Each request carries `x-vault-account`, `x-vault-device`, `x-vault-timestamp`
148
+ (unix milliseconds), `x-vault-nonce` (16 to 64 base64url characters, single
149
+ use), `x-vault-content-sha256` (hex SHA-256 of the exact body; the empty-body
150
+ digest for bodiless requests), and `x-vault-signature`: the base64url Ed25519
151
+ signature over
152
+
153
+ ```text
154
+ smrt-vault-relay-v1
155
+ <METHOD>
156
+ <path and query, as the server parses it>
157
+ <account id>
158
+ <device id>
159
+ <timestamp>
160
+ <nonce>
161
+ <body sha256>
162
+ ```
163
+
164
+ `signRelayRequest()` builds these headers. Requests are rejected with one
165
+ uniform `401 unauthorized` when a header is missing or malformed, the
166
+ timestamp is outside the clock-skew window (default 5 minutes), the device is
167
+ unknown, revoked, or registered to another account, the signature does not
168
+ verify, or the nonce was used before. A body whose digest differs from the
169
+ signed digest is rejected with `400 content_digest_mismatch`. Account and
170
+ device ids match `[A-Za-z0-9][A-Za-z0-9_-]{0,127}`.
171
+
172
+ Entitlement denials answer `403` with the structured body from
173
+ `smrt-features` (`feature_upgrade_required` naming the granting plan, or
174
+ `feature_disabled`). If the entitlement lookup itself fails, the relay answers
175
+ `503 entitlement_unavailable`: it fails closed. An account that never held the
176
+ entitlement, or whose entitlement an operator disabled, is refused on every
177
+ route. An account that held it and stored snapshots is *lapsed*:
178
+
179
+ ### Lapsed subscriptions
180
+
181
+ Owner decision #4819. When `backup.vault` lapses for an account that holds
182
+ committed snapshots:
183
+
184
+ - The relay records the lapse time the first time it observes it (a device
185
+ request, or the operator sweep's discovery pass). The time is kept, never
186
+ moved, and cleared when the entitlement is active again.
187
+ - **Writes are refused** (`begin`, chunk upload, commit, device snapshot
188
+ delete) with `402 entitlement_lapsed` and `{ lapsedAt, restoreAvailableUntil }`.
189
+ This code differs from the `403` upgrade/disabled denials and from the `401`
190
+ authentication failure.
191
+ - **Reads stay open** for authenticated devices of the account: list,
192
+ `latest`, snapshot metadata and chunk download, aborting an upload, and the
193
+ lease routes (restore-latest holds the lease while it downloads).
194
+ - After `lapseRetentionDays` (default **90**, `VAULT_RELAY_LAPSE_RETENTION_DAYS`,
195
+ 1 to 3650) reads answer `410 retention_expired` and the account is eligible
196
+ for the sweep. Writes keep answering `402 entitlement_lapsed`.
197
+ - **The sweep is an operator action, not a device action.**
198
+ `POST /admin/v1/lapse-sweep` (admin token) with `{ dryRun?, limit?, cursor? }`
199
+ and an optional `x-vault-operator` label header. Per run it handles at most
200
+ `limit` accounts (default 10, at most 100) in two phases: a discovery pass
201
+ over accounts with snapshots but no lapse record (resume with the returned
202
+ `nextCursor`), which starts the window for lapses no device reported; and a
203
+ deletion pass over lapses whose window has elapsed. Each account is
204
+ re-checked first: one that is entitled again keeps its data and has its
205
+ lapse cleared. Deletion uses the normal removal path (rows, counters,
206
+ objects). Every deleted account writes a `lapse_sweep_started` and a
207
+ `lapse_sweep_completed` record to the append-only `vault_relay_audit` table:
208
+ time, operator (label plus a fingerprint of the admin token, never the
209
+ token), hashed account handle, snapshot count and bytes. Re-running is
210
+ idempotent; a run that crashed mid-account is finished by the next one. A
211
+ dry run reports the same result and changes and audits nothing. A sweep
212
+ leaves the account's high-water mark and lease head as they were.
213
+
214
+ ## Admin API (account layer and operator)
215
+
216
+ Served on a separate listener, which must stay cluster-internal, and only when
217
+ `VAULT_RELAY_ADMIN_TOKEN` is set. Requests use `Authorization: Bearer <token>`.
218
+
219
+ | Route | Purpose |
220
+ | --- | --- |
221
+ | `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`. |
222
+ | `DELETE /admin/v1/accounts/:account/devices/:device` | Revoke a device. Effective on its next request. |
223
+ | `GET /admin/v1/accounts/:account` | Usage, snapshot sizes and dates, device states. Never content. |
224
+ | `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). |
225
+ | `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). |
226
+ | `DELETE /admin/v1/accounts/:account/superseded-by` | Undo it, for an operator mistake. `204`, or `404 no_supersession`. |
227
+ | `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. |
228
+ | `POST /admin/v1/sweep` | Expire abandoned uploads and old nonces (also runs every minute). |
229
+ | `POST /admin/v1/lapse-sweep` | Audited deletion of lapsed accounts' snapshots after the retention window (#4819). `{ dryRun?, limit?, cursor? }`; see [Lapsed subscriptions](#lapsed-subscriptions). |
230
+
231
+ The same hooks are available in-process: `relay.registerDevice()`,
232
+ `relay.revokeDevice()`, `relay.operatorView()`.
233
+
234
+ ## Storage
235
+
236
+ Chunk bytes live in an object store under relay-derived keys,
237
+ `v1/<sha256 account handle>/<upload uuid>/<index>.<random object id>`; no
238
+ client string becomes part of a key. Each write attempt gets its own object,
239
+ and a chunk row is recorded only while its upload is still pending, so a write
240
+ that lands after an abort, expiry, or publish is deleted instead of counted. `FilesystemObjectStore` (atomic temp-and-rename writes) serves
241
+ tests and single-node development. `createS3ObjectStore()` uses the
242
+ `@happyvertical/files` S3 provider with path-style addressing for Garage.
243
+
244
+ Metadata lives in the service database (SQLite or PostgreSQL) in ten
245
+ `vault_relay_*` tables. `migrateVaultRelayV1(db)` and
246
+ `migrateVaultRelayLeasesV1(db)` create them idempotently.
247
+ Run it as the deployment's migration step (`node dist/cli.js migrate`); the
248
+ server checks the tables exist at readiness and never creates schema while
249
+ serving.
250
+
251
+ **Upgrading to account supersession (#4817).** `migrateVaultRelayV1` now also
252
+ creates `vault_relay_supersessions`. Re-run the migration job (it is
253
+ idempotent) **before** deploying this version: until the table exists,
254
+ `/readyz` reports `schema_missing` and the relay is not ready, and every
255
+ device route that checks supersession (backup, restore, lease acquire and
256
+ renew) fails.
257
+
258
+ **Upgrading to the lapse window (#4819).** `migrateVaultRelayV1` also creates
259
+ `vault_relay_lapses` and `vault_relay_audit` (plain `CREATE TABLE IF NOT
260
+ EXISTS`, no change to existing tables). Re-run the migration job before
261
+ deploying this version; until then `/readyz` reports `schema_missing`.
262
+
263
+ ## Required configuration
264
+
265
+ These are owner inputs. The relay has no defaults for them and refuses to start
266
+ without them (except the admin token, see its row). Values are not chosen here.
267
+
268
+ | Variable | Meaning |
269
+ | --- | --- |
270
+ | `VAULT_RELAY_DATABASE_URL` | Relay metadata database (`postgres://…`, or a SQLite path). Secret. |
271
+ | `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. |
272
+ | `VAULT_RELAY_STORAGE` | `s3` in deployment (`filesystem` for development). |
273
+ | `VAULT_RELAY_S3_BUCKET` | Garage bucket for ciphertext. |
274
+ | `VAULT_RELAY_S3_ENDPOINT` | Garage S3 endpoint URL. |
275
+ | `VAULT_RELAY_S3_REGION` | Region name the Garage cluster is configured with. |
276
+ | `VAULT_RELAY_S3_ACCESS_KEY_ID`, `VAULT_RELAY_S3_SECRET_ACCESS_KEY` | Bucket-scoped Garage key. Secret. |
277
+ | `VAULT_RELAY_QUOTA_MAX_BYTES` | Per-account byte quota (committed plus pending). |
278
+ | `VAULT_RELAY_QUOTA_MAX_SNAPSHOTS` | Per-account snapshot quota (committed plus pending). Must exceed `KEEP_LAST`. |
279
+ | `VAULT_RELAY_RETENTION_KEEP_LAST` | Newest committed snapshots always kept (at least 1). |
280
+ | `VAULT_RELAY_RETENTION_KEEP_WITHIN_DAYS` | Also keep snapshots committed within this many days (0 for none). |
281
+ | `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. |
282
+
283
+ Optional technical settings: `VAULT_RELAY_PORT` (8080), `VAULT_RELAY_ADMIN_PORT`
284
+ (8081), `VAULT_RELAY_MAX_CHUNK_BYTES` (8454144), `VAULT_RELAY_UPLOAD_TTL_SECONDS`
285
+ (86400), `VAULT_RELAY_MAX_CLOCK_SKEW_SECONDS` (300), `VAULT_RELAY_MAX_SEQUENCE_JUMP` (1000),
286
+ `VAULT_RELAY_LEASE_TTL_SECONDS` (300), `VAULT_RELAY_LAPSE_RETENTION_DAYS` (90, 1 to
287
+ 3650). With `VAULT_RELAY_STORAGE=filesystem`,
288
+ `VAULT_RELAY_STORAGE_PATH` is required.
289
+
290
+ The deployment also needs, from the owner: the namespace, the public domain and
291
+ TLS for the device API, the image registry and digest, and network policy that
292
+ keeps the admin port private. The device Ingress must accept request bodies of
293
+ at least the maximum chunk size plus headroom: with the default 8 MiB + 64 KiB
294
+ chunks, set the ingress body limit to at least `9m` (`10m` in the `smrt-app`
295
+ chart's allowed set; ingress-nginx defaults to `1m`). Keep
296
+ `VAULT_RELAY_MAX_CHUNK_BYTES` below the ingress limit the chart permits.
297
+
298
+ ## Deployment
299
+
300
+ `packages/vault-relay/Dockerfile` builds the image from the repository root:
301
+
302
+ ```sh
303
+ docker build -f packages/vault-relay/Dockerfile -t <registry>/smrt-vault-relay:<version> .
304
+ ```
305
+
306
+ The image runs as `node`, listens on 8080 (device API) and 8081 (admin API),
307
+ and takes `serve` (default) or `migrate` as its command. For the `smrt-app`
308
+ chart (see the [deployment guide](../../docs/content/deployment.md)), model it
309
+ as:
310
+
311
+ - one `web` workload, `writer: true`, command `["node", "dist/cli.js", "serve"]`,
312
+ port 8080, `readinessProbe` `GET /readyz`, `livenessProbe` `GET /healthz`,
313
+ every variable above from named, immutable Secret keys, and a pod and
314
+ container security context that is non-root with a read-only root
315
+ filesystem (the relay writes nothing locally with S3 storage);
316
+ - the migration job with command `["node", "dist/cli.js", "migrate"]` and only
317
+ `VAULT_RELAY_DATABASE_URL`. The DDL is idempotent; the chart's
318
+ `smrt-release-v1` wrapper requirements still apply and are an adoption task;
319
+ - the admin port exposed only through a cluster-internal Service, never the
320
+ Ingress.
321
+
322
+ The relay keeps no state on local disk with S3 storage, so replicas can scale
323
+ horizontally: every security check is a conditional database statement.
324
+
325
+ ## Security model
326
+
327
+ | Threat | Control | Test |
328
+ | --- | --- | --- |
329
+ | 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 |
330
+ | Revoked device, or another account's device | Device lookup by (account, device), active only; ids never reused | `relay.test.ts` authentication |
331
+ | Cross-account access | Every query scoped by the authenticated account; uploads looked up by (account, upload) | `relay.test.ts` cross-account isolation |
332
+ | Quota or size abuse | Atomic conditional reservation; declared length checked before buffering; chunk cap | `relay.test.ts` quotas and request bounds |
333
+ | 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 |
334
+ | Partial upload becoming latest | Pending status; commit verifies every chunk and the whole digest | `relay.test.ts` atomic publish |
335
+ | Sequence rollback or overwrite | Account high-water mark advanced conditionally; unique (account, sequence) | `relay.test.ts` atomic publish |
336
+ | 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 |
337
+ | Entitlement bypass, off plan | `requireFeature('backup.vault')` per request from server-side grants; fails closed | `entitlements.test.ts` |
338
+ | 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` |
339
+ | 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` |
340
+ | 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` |
341
+ | 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 |
342
+ | Replayed acquire | Signed nonce and timestamp | `lease.test.ts` replay |
343
+ | 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 |
344
+ | 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 |
345
+ | Supersession chains or loops | Target must have an active device and must not be replaced | `supersession.test.ts` target checks |
346
+ | Path traversal in object keys | Keys derived from hash, server UUID, and index; regex and containment checks | `storage-and-config.test.ts` |
347
+
348
+ Residual risks: a publish whose head advanced but whose commit was never
349
+ retried blocks other devices' acquire (`publish_in_progress`) until the
350
+ upload TTL expires; the relay is trusted to name the latest snapshot to a
351
+ device with no local history (a device with history refuses anything below
352
+ the highest sequence it has seen). An operator can see ciphertext sizes, timing, and device ids
353
+ (an HVSF snapshot also carries its producing device id, key id, generation, and
354
+ length in a clear file header that the relay stores but never parses);
355
+ quota counters can over-count after a crash between steps (`reconcile`
356
+ repairs it); a crash between storing a chunk object and recording it can leave
357
+ one unreferenced ciphertext object.
358
+
359
+ ## Development
360
+
361
+ ```sh
362
+ pnpm --filter @happyvertical/smrt-vault-relay test
363
+ pnpm --filter @happyvertical/smrt-vault-relay typecheck
364
+ pnpm --filter @happyvertical/smrt-vault-relay test:postgres # needs a CI PostgreSQL URL
365
+ ```
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"}