@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 +51 -0
- package/CLAUDE.md +1 -0
- package/LICENSE +7 -0
- package/README.md +364 -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
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import type { FilesystemInterface } from '@happyvertical/files';
|
|
2
|
+
/** Build the object key of one stored attempt of one chunk of one upload. */
|
|
3
|
+
export declare function chunkObjectKey(accountHandle: string, uploadId: string, index: number, objectId: string): string;
|
|
4
|
+
/** Throw unless `key` is a relay-derived chunk key. */
|
|
5
|
+
export declare function assertObjectKey(key: string): void;
|
|
6
|
+
/** Storage for opaque ciphertext chunks. */
|
|
7
|
+
export interface VaultObjectStore {
|
|
8
|
+
/** Store `data` under `key`, replacing any previous object atomically. */
|
|
9
|
+
put(key: string, data: Uint8Array): Promise<void>;
|
|
10
|
+
/** The stored bytes, or `null` when the object does not exist. */
|
|
11
|
+
get(key: string): Promise<Uint8Array | null>;
|
|
12
|
+
/** Remove one object; a missing object is not an error. */
|
|
13
|
+
delete(key: string): Promise<void>;
|
|
14
|
+
/** Readiness probe: resolves when the store is reachable. */
|
|
15
|
+
check(): Promise<void>;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Filesystem store for tests and single-node development. Writes go to a
|
|
19
|
+
* temporary sibling and are renamed into place, so a reader never sees a
|
|
20
|
+
* partially written chunk.
|
|
21
|
+
*/
|
|
22
|
+
export declare class FilesystemObjectStore implements VaultObjectStore {
|
|
23
|
+
private readonly root;
|
|
24
|
+
constructor(root: string);
|
|
25
|
+
private pathFor;
|
|
26
|
+
put(key: string, data: Uint8Array): Promise<void>;
|
|
27
|
+
get(key: string): Promise<Uint8Array | null>;
|
|
28
|
+
delete(key: string): Promise<void>;
|
|
29
|
+
check(): Promise<void>;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Adapter over an `@happyvertical/files` filesystem. With the S3 provider it
|
|
33
|
+
* stores chunks in an S3-compatible bucket such as Garage.
|
|
34
|
+
*/
|
|
35
|
+
export declare class FilesObjectStore implements VaultObjectStore {
|
|
36
|
+
private readonly filesystem;
|
|
37
|
+
private readonly isNotFound;
|
|
38
|
+
constructor(filesystem: FilesystemInterface, isNotFound?: (error: unknown) => boolean);
|
|
39
|
+
put(key: string, data: Uint8Array): Promise<void>;
|
|
40
|
+
get(key: string): Promise<Uint8Array | null>;
|
|
41
|
+
delete(key: string): Promise<void>;
|
|
42
|
+
check(): Promise<void>;
|
|
43
|
+
}
|
|
44
|
+
/** S3-compatible bucket settings; credentials come from the environment. */
|
|
45
|
+
export interface S3ObjectStoreOptions {
|
|
46
|
+
bucket: string;
|
|
47
|
+
region: string;
|
|
48
|
+
endpoint: string;
|
|
49
|
+
accessKeyId: string;
|
|
50
|
+
secretAccessKey: string;
|
|
51
|
+
/** Garage needs path-style addressing; defaults to `true`. */
|
|
52
|
+
forcePathStyle?: boolean;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Open an S3-compatible store (Garage in deployment). The files SDK is loaded
|
|
56
|
+
* on demand so library consumers that only use the filesystem store never
|
|
57
|
+
* import the AWS client.
|
|
58
|
+
*/
|
|
59
|
+
export declare function createS3ObjectStore(options: S3ObjectStoreOptions): Promise<FilesObjectStore>;
|
|
60
|
+
//# sourceMappingURL=object-store.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"object-store.d.ts","sourceRoot":"","sources":["../src/object-store.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,mBAAmB,EAEpB,MAAM,sBAAsB,CAAC;AAI9B,6EAA6E;AAC7E,wBAAgB,cAAc,CAC5B,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,MAAM,CAIR;AAED,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAIjD;AAED,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,kEAAkE;IAClE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC7C,2DAA2D;IAC3D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,6DAA6D;IAC7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAC5D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,EAAE,MAAM;IAIxB,OAAO,CAAC,OAAO;IAUT,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAajD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAS5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,gBAAgB;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;gBAGvD,UAAU,EAAE,mBAAmB,EAC/B,UAAU,GAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAA2B;IAMvD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAa5C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B;AAMD,4EAA4E;AAC5E,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAgB3B"}
|
package/dist/relay.d.ts
ADDED
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
import { type FeatureGrantSource, type FeatureResolver } from '@happyvertical/smrt-features';
|
|
2
|
+
import { type VaultRelayPolicy, type VaultRelayPolicyInput } from './config.js';
|
|
3
|
+
import { VaultRelayLeaseStore } from './lease-store.js';
|
|
4
|
+
import type { AccountUsage, DeviceRecord, SnapshotRecord, VaultRelayStore } from './metadata-store.js';
|
|
5
|
+
import { type VaultObjectStore } from './object-store.js';
|
|
6
|
+
/** Structured log sink. Fields never carry blob bytes or secrets. */
|
|
7
|
+
export interface VaultRelayLogger {
|
|
8
|
+
info(event: string, fields?: Record<string, string | number | boolean>): void;
|
|
9
|
+
warn(event: string, fields?: Record<string, string | number | boolean>): void;
|
|
10
|
+
error(event: string, fields?: Record<string, string | number | boolean>): void;
|
|
11
|
+
}
|
|
12
|
+
/** JSON-lines logger on stdout/stderr. */
|
|
13
|
+
export declare const jsonLineLogger: VaultRelayLogger;
|
|
14
|
+
/** How the relay resolves an account's `backup.vault` entitlement. */
|
|
15
|
+
export interface VaultRelayEntitlements {
|
|
16
|
+
/** Feature resolver over the platform's feature and subscription data. */
|
|
17
|
+
resolver: Pick<FeatureResolver, 'explain' | 'findGrantingPlan'>;
|
|
18
|
+
/**
|
|
19
|
+
* Request-scoped plan grant source (for example a fresh
|
|
20
|
+
* `SubscriptionFeatureSource`). Omitted means the resolver's own source.
|
|
21
|
+
*/
|
|
22
|
+
grantSource?: () => FeatureGrantSource | null | undefined | Promise<FeatureGrantSource | null | undefined>;
|
|
23
|
+
/**
|
|
24
|
+
* Tenant whose entitlements govern the account. Defaults to the account id
|
|
25
|
+
* itself: a relay account is a hosted SMRT tenant.
|
|
26
|
+
*/
|
|
27
|
+
tenantForAccount?: (accountId: string) => string;
|
|
28
|
+
}
|
|
29
|
+
export interface VaultRelayOptions {
|
|
30
|
+
store: VaultRelayStore;
|
|
31
|
+
/** Primary-writer lease store; defaults to one over `store.db`. */
|
|
32
|
+
leaseStore?: VaultRelayLeaseStore;
|
|
33
|
+
objects: VaultObjectStore;
|
|
34
|
+
entitlements: VaultRelayEntitlements;
|
|
35
|
+
policy: VaultRelayPolicyInput;
|
|
36
|
+
/**
|
|
37
|
+
* Operator bearer token for {@link VaultRelay.handleAdmin}. Only its hash is
|
|
38
|
+
* retained. Without it every admin route answers 404.
|
|
39
|
+
*/
|
|
40
|
+
adminToken?: string;
|
|
41
|
+
logger?: VaultRelayLogger;
|
|
42
|
+
now?: () => number;
|
|
43
|
+
}
|
|
44
|
+
/** Operator view of one account: sizes, dates, and device state, no content. */
|
|
45
|
+
export interface OperatorAccountView {
|
|
46
|
+
usage: AccountUsage | null;
|
|
47
|
+
snapshots: Array<{
|
|
48
|
+
sequence: number;
|
|
49
|
+
status: SnapshotRecord['status'];
|
|
50
|
+
byteSize: number;
|
|
51
|
+
chunkCount: number;
|
|
52
|
+
sha256: string;
|
|
53
|
+
createdAt: string;
|
|
54
|
+
committedAt: string | null;
|
|
55
|
+
}>;
|
|
56
|
+
devices: Array<{
|
|
57
|
+
deviceId: string;
|
|
58
|
+
status: DeviceRecord['status'];
|
|
59
|
+
registeredAt: string;
|
|
60
|
+
revokedAt: string | null;
|
|
61
|
+
}>;
|
|
62
|
+
/** The account that replaced this one (#4817), if the account layer set it. */
|
|
63
|
+
supersededBy: string | null;
|
|
64
|
+
/** When the lapse was first observed (#4819); null while entitled. */
|
|
65
|
+
lapsedAt: string | null;
|
|
66
|
+
/** End of the post-lapse restore window; the sweep may delete after it. */
|
|
67
|
+
lapseRetentionEndsAt: string | null;
|
|
68
|
+
}
|
|
69
|
+
/** Options of {@link VaultRelay.sweepLapsedAccounts}. */
|
|
70
|
+
export interface LapseSweepOptions {
|
|
71
|
+
/** Operator identity recorded in the audit trail (required). */
|
|
72
|
+
operator: string;
|
|
73
|
+
/** Report what would be deleted; change and audit nothing. */
|
|
74
|
+
dryRun?: boolean;
|
|
75
|
+
/** Accounts handled per phase in this run (default 10, at most 100). */
|
|
76
|
+
limit?: number;
|
|
77
|
+
/** `nextCursor` of the previous run, to continue the discovery pass. */
|
|
78
|
+
cursor?: string;
|
|
79
|
+
now?: number;
|
|
80
|
+
}
|
|
81
|
+
/** One account a lapse sweep deleted (or, in a dry run, would delete). */
|
|
82
|
+
export interface LapseSweepAccount {
|
|
83
|
+
/** Hashed handle, never the account id. */
|
|
84
|
+
account: string;
|
|
85
|
+
lapsedAt: string;
|
|
86
|
+
retentionEndedAt: string;
|
|
87
|
+
snapshots: number;
|
|
88
|
+
bytes: number;
|
|
89
|
+
}
|
|
90
|
+
export interface LapseSweepResult {
|
|
91
|
+
dryRun: boolean;
|
|
92
|
+
operator: string;
|
|
93
|
+
/** Accounts newly found lapsed by the discovery pass. */
|
|
94
|
+
discovered: number;
|
|
95
|
+
swept: LapseSweepAccount[];
|
|
96
|
+
skipped: Array<{
|
|
97
|
+
account: string;
|
|
98
|
+
reason: string;
|
|
99
|
+
}>;
|
|
100
|
+
/** Pass as `cursor` to continue the discovery pass; null when finished. */
|
|
101
|
+
nextCursor: string | null;
|
|
102
|
+
/** More accounts were due than `limit`; run again. */
|
|
103
|
+
more: boolean;
|
|
104
|
+
}
|
|
105
|
+
export declare class VaultRelay {
|
|
106
|
+
readonly policy: VaultRelayPolicy;
|
|
107
|
+
private readonly store;
|
|
108
|
+
private readonly leaseStore;
|
|
109
|
+
private readonly leases;
|
|
110
|
+
private readonly objects;
|
|
111
|
+
private readonly entitlements;
|
|
112
|
+
private readonly adminTokenHash;
|
|
113
|
+
private readonly logger;
|
|
114
|
+
private readonly now;
|
|
115
|
+
private lastNoncePrune;
|
|
116
|
+
constructor(options: VaultRelayOptions);
|
|
117
|
+
/** Readiness: schema migrated and object store reachable. */
|
|
118
|
+
ready(): Promise<{
|
|
119
|
+
ready: boolean;
|
|
120
|
+
reason?: string;
|
|
121
|
+
}>;
|
|
122
|
+
private health;
|
|
123
|
+
/** Device-facing handler (public listener). */
|
|
124
|
+
handle(request: Request): Promise<Response>;
|
|
125
|
+
private toErrorResponse;
|
|
126
|
+
private authenticate;
|
|
127
|
+
/**
|
|
128
|
+
* An account the account layer replaced (#4817) takes no new writes and
|
|
129
|
+
* offers no snapshot to restore-latest: its devices would publish into a
|
|
130
|
+
* data line nobody follows, and a restore would hand back the old vault.
|
|
131
|
+
* Lease status answers it too: that refusal is how a device proves, before
|
|
132
|
+
* it follows the new account, that the old one was replaced. What only
|
|
133
|
+
* removes state (lease release, aborting an upload) and reads by explicit
|
|
134
|
+
* sequence stay open. The refusal names no other
|
|
135
|
+
* account: the client never follows the relay to a new account.
|
|
136
|
+
*/
|
|
137
|
+
private refuseSuperseded;
|
|
138
|
+
private pruneNoncesIfDue;
|
|
139
|
+
/**
|
|
140
|
+
* The `backup.vault` check, resolved server-side for the account's tenant:
|
|
141
|
+
* `null` when granted, the structured denial otherwise. A lookup that
|
|
142
|
+
* cannot complete fails closed (`503`).
|
|
143
|
+
*/
|
|
144
|
+
private checkEntitlement;
|
|
145
|
+
/**
|
|
146
|
+
* Gate a device route on `backup.vault` (#4819). An entitled account clears
|
|
147
|
+
* any recorded lapse. A denied account that holds committed snapshots is
|
|
148
|
+
* *lapsed*: the relay records when it first saw that, refuses the write
|
|
149
|
+
* routes with `402 entitlement_lapsed`, and keeps the read routes open
|
|
150
|
+
* until the retention window after the lapse has passed, then answers
|
|
151
|
+
* `410 retention_expired`. Any other denial (never entitled, operator
|
|
152
|
+
* disabled) is the original `403`.
|
|
153
|
+
*/
|
|
154
|
+
private gateEntitlement;
|
|
155
|
+
/**
|
|
156
|
+
* The lapse record of a denied account, created on first observation. Only
|
|
157
|
+
* an upgrade-required denial of an account with data counts as a lapse.
|
|
158
|
+
*/
|
|
159
|
+
private observeLapse;
|
|
160
|
+
private lapseDetail;
|
|
161
|
+
/** Reject a body on a route that takes none, and bind the empty digest. */
|
|
162
|
+
private requireEmptyBody;
|
|
163
|
+
/** A bounded JSON body whose digest is the signed one. */
|
|
164
|
+
private readJson;
|
|
165
|
+
private dispatchLease;
|
|
166
|
+
private dispatch;
|
|
167
|
+
private beginUpload;
|
|
168
|
+
/**
|
|
169
|
+
* A sequence may not jump more than `maxSequenceJump` above the account's
|
|
170
|
+
* high-water mark. Without the bound, one commit at the largest safe
|
|
171
|
+
* integer would make every later upload `stale_sequence` with no way back
|
|
172
|
+
* short of editing the database.
|
|
173
|
+
*/
|
|
174
|
+
private assertSequenceStep;
|
|
175
|
+
private pendingUpload;
|
|
176
|
+
private uploadChunk;
|
|
177
|
+
private commitUpload;
|
|
178
|
+
/**
|
|
179
|
+
* Device-initiated delete. The account's last committed snapshot is never
|
|
180
|
+
* removable from the device API: a compromised or mistaken device would
|
|
181
|
+
* otherwise erase the only restorable copy. The refusal and every removal
|
|
182
|
+
* are audited by device and sequence; the operator can still act through
|
|
183
|
+
* the admin listener.
|
|
184
|
+
*/
|
|
185
|
+
private deleteSnapshotForDevice;
|
|
186
|
+
private downloadChunk;
|
|
187
|
+
/**
|
|
188
|
+
* Remove a snapshot or upload while it still has `status`: the row first (so
|
|
189
|
+
* it can never be listed or served half-deleted, and a concurrent publish
|
|
190
|
+
* or abort cannot be undone), then counters, then chunk rows and objects.
|
|
191
|
+
*/
|
|
192
|
+
private removeSnapshot;
|
|
193
|
+
/** Counters, fence, chunk rows and objects of a snapshot row already deleted. */
|
|
194
|
+
private discardRemoved;
|
|
195
|
+
private deleteObject;
|
|
196
|
+
/** Keep the newest `keepLast` committed snapshots plus any within the window. */
|
|
197
|
+
private applyRetention;
|
|
198
|
+
/** Abort pending uploads older than the upload TTL; returns how many. */
|
|
199
|
+
sweepExpired(now?: number): Promise<number>;
|
|
200
|
+
/**
|
|
201
|
+
* Operator sweep of lapsed accounts. Two bounded phases per run:
|
|
202
|
+
*
|
|
203
|
+
* 1. *Discovery* walks accounts that hold committed snapshots but have no
|
|
204
|
+
* lapse record (`cursor`/`nextCursor` resume it) and records those whose
|
|
205
|
+
* entitlement is lapsed, so an account whose devices never call again
|
|
206
|
+
* still starts its window.
|
|
207
|
+
* 2. *Deletion* takes lapses whose window (`lapseRetentionDays` from the
|
|
208
|
+
* first observation) has elapsed, re-checks the entitlement, and deletes
|
|
209
|
+
* the account's snapshots through the normal removal path. An account
|
|
210
|
+
* that is entitled again has its lapse cleared and keeps its data.
|
|
211
|
+
*
|
|
212
|
+
* Every account deleted gets a `lapse_sweep_started` audit record (what is
|
|
213
|
+
* about to go) before anything is removed and a `lapse_sweep_completed`
|
|
214
|
+
* record (what went) after, so a crash leaves the intent on record and the
|
|
215
|
+
* next run finishes the job. A dry run changes and audits nothing.
|
|
216
|
+
*/
|
|
217
|
+
sweepLapsedAccounts(options: LapseSweepOptions): Promise<LapseSweepResult>;
|
|
218
|
+
private audit;
|
|
219
|
+
/**
|
|
220
|
+
* Register a device's Ed25519 public key (raw 32 bytes, base64url) for an
|
|
221
|
+
* account. Idempotent for the same key; a revoked device id or a different
|
|
222
|
+
* key under an existing id is a conflict.
|
|
223
|
+
*/
|
|
224
|
+
registerDevice(accountId: string, deviceId: string, publicKey: string): Promise<'registered' | 'unchanged' | 'conflict'>;
|
|
225
|
+
/** Revoke a device; its signatures fail from the next request on. */
|
|
226
|
+
revokeDevice(accountId: string, deviceId: string): Promise<boolean>;
|
|
227
|
+
/**
|
|
228
|
+
* Operator reset of an account's sequence high-water mark, for an account
|
|
229
|
+
* whose mark was pushed out of reach (every later upload is
|
|
230
|
+
* `stale_sequence`). The new mark must not be above the current one. Any
|
|
231
|
+
* snapshot or pending upload above it is refused with its sequence listed,
|
|
232
|
+
* unless `removeSnapshotsAbove` is set, in which case those rows and their
|
|
233
|
+
* objects are deleted first. Every call that changes anything is logged with
|
|
234
|
+
* the previous mark, the new mark, and the removed sequences.
|
|
235
|
+
*/
|
|
236
|
+
resetHighWater(accountId: string, highWaterSequence: number, options?: {
|
|
237
|
+
removeSnapshotsAbove?: boolean;
|
|
238
|
+
}): Promise<{
|
|
239
|
+
previous: number;
|
|
240
|
+
highWaterSequence: number;
|
|
241
|
+
removed: number[];
|
|
242
|
+
}>;
|
|
243
|
+
/**
|
|
244
|
+
* Mark `accountId` replaced by `supersededBy` (#4817), for the account
|
|
245
|
+
* layer once it has provisioned the new account and registered a device in
|
|
246
|
+
* it. Admin only: no device route can set or clear it, so a stolen device
|
|
247
|
+
* cannot silence or redirect an account. The old account's snapshots stay
|
|
248
|
+
* in place (readable by explicit sequence); it takes no new writes and
|
|
249
|
+
* offers nothing to restore-latest. Idempotent for the same target.
|
|
250
|
+
*/
|
|
251
|
+
supersedeAccount(accountId: string, supersededBy: string): Promise<'superseded' | 'unchanged'>;
|
|
252
|
+
/** Undo {@link supersedeAccount}, for an operator mistake. */
|
|
253
|
+
clearSupersession(accountId: string): Promise<boolean>;
|
|
254
|
+
/** Sizes, dates, and device state for one account; never content. */
|
|
255
|
+
operatorView(accountId: string): Promise<OperatorAccountView>;
|
|
256
|
+
private adminAuthorized;
|
|
257
|
+
/** Operator and account-layer handler (private listener). */
|
|
258
|
+
handleAdmin(request: Request): Promise<Response>;
|
|
259
|
+
/**
|
|
260
|
+
* Operator identity for the audit trail: the optional `x-vault-operator`
|
|
261
|
+
* label the caller states, plus a fingerprint of the admin token that
|
|
262
|
+
* authenticated the request (a hash prefix, never the token).
|
|
263
|
+
*/
|
|
264
|
+
private operatorIdentity;
|
|
265
|
+
private adminLapseSweep;
|
|
266
|
+
private dispatchAdmin;
|
|
267
|
+
}
|
|
268
|
+
//# sourceMappingURL=relay.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"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"}
|
package/dist/server.d.ts
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deployment entry: environment configuration, database and object-store
|
|
3
|
+
* wiring, and the two listeners. Quotas, retention, bucket, and database
|
|
4
|
+
* locations are owner inputs with no defaults; a missing value stops startup.
|
|
5
|
+
*/
|
|
6
|
+
import type { Server } from 'node:http';
|
|
7
|
+
import { type DatabaseInterface } from '@happyvertical/sql';
|
|
8
|
+
import type { VaultRelayPolicyInput } from './config.js';
|
|
9
|
+
import { type S3ObjectStoreOptions } from './object-store.js';
|
|
10
|
+
import { VaultRelay } from './relay.js';
|
|
11
|
+
export type VaultRelayStorageConfig = {
|
|
12
|
+
kind: 'filesystem';
|
|
13
|
+
path: string;
|
|
14
|
+
} | ({
|
|
15
|
+
kind: 's3';
|
|
16
|
+
} & S3ObjectStoreOptions);
|
|
17
|
+
export interface VaultRelayServerConfig {
|
|
18
|
+
databaseUrl: string;
|
|
19
|
+
entitlementsDatabaseUrl: string;
|
|
20
|
+
storage: VaultRelayStorageConfig;
|
|
21
|
+
policy: VaultRelayPolicyInput;
|
|
22
|
+
port: number;
|
|
23
|
+
adminPort: number;
|
|
24
|
+
adminToken?: string;
|
|
25
|
+
}
|
|
26
|
+
/** Thrown for configuration errors; the message names variables, not values. */
|
|
27
|
+
export declare class VaultRelayConfigError extends Error {
|
|
28
|
+
constructor(message: string);
|
|
29
|
+
}
|
|
30
|
+
type Env = Record<string, string | undefined>;
|
|
31
|
+
/** Read the server configuration from environment variables. */
|
|
32
|
+
export declare function loadServerConfig(env?: Env): VaultRelayServerConfig;
|
|
33
|
+
/** Open a database from a `postgres://`/`postgresql://` URL or a SQLite path. */
|
|
34
|
+
export declare function openRelayDatabase(url: string): Promise<DatabaseInterface>;
|
|
35
|
+
/** Apply the relay schema (the deployment migration step). */
|
|
36
|
+
export declare function runMigrations(config: Pick<VaultRelayServerConfig, 'databaseUrl'>): Promise<void>;
|
|
37
|
+
export interface RunningVaultRelay {
|
|
38
|
+
relay: VaultRelay;
|
|
39
|
+
server: Server;
|
|
40
|
+
adminServer: Server | null;
|
|
41
|
+
close(): Promise<void>;
|
|
42
|
+
}
|
|
43
|
+
/** Build the relay from configuration and start both listeners. */
|
|
44
|
+
export declare function startVaultRelayServer(config: VaultRelayServerConfig): Promise<RunningVaultRelay>;
|
|
45
|
+
export {};
|
|
46
|
+
//# sourceMappingURL=server.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC,OAAO,EAAE,KAAK,iBAAiB,EAAe,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAkB,UAAU,EAAE,MAAM,YAAY,CAAC;AAIxD,MAAM,MAAM,uBAAuB,GAC/B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,oBAAoB,CAAC,CAAC;AAE5C,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB,EAAE,MAAM,CAAC;IAChC,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gFAAgF;AAChF,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAsB9C,gEAAgE;AAChE,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,GAAiB,GACrB,sBAAsB,CA2ExB;AAED,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,iBAAiB,CAAC,CAK5B;AAYD,8DAA8D;AAC9D,wBAAsB,aAAa,CACjC,MAAM,EAAE,IAAI,CAAC,sBAAsB,EAAE,aAAa,CAAC,GAClD,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,mEAAmE;AACnE,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CA8D5B"}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": 1,
|
|
3
|
+
"sensitiveFieldsExcluded": true,
|
|
4
|
+
"generatedAt": "1970-01-01T00:00:00.000Z",
|
|
5
|
+
"packageName": "@happyvertical/smrt-vault-relay",
|
|
6
|
+
"packageVersion": "0.60.17",
|
|
7
|
+
"sourceManifestPath": "dist/manifest.json",
|
|
8
|
+
"agentDocPath": "AGENTS.md",
|
|
9
|
+
"sourceHashes": {
|
|
10
|
+
"manifest": "a37d8f39dbed5f4d56e38f3fa83619c609d4eb28cb9abc3af03a7499c8fda34d",
|
|
11
|
+
"packageJson": "4d67bb56d9d2ddf54e4a465484a7b844ff1bbed360cc421d896b875fab720eaa",
|
|
12
|
+
"agents": "8482c05c2458849362b869117d160dc914e94b1d0a95dee7804171b1f451c4dd",
|
|
13
|
+
"moduleDoc:README.md": "09ab3d9dc3855858521c64a254e7c07b1cdeb3d34633c5f985961a4351b9ac58"
|
|
14
|
+
},
|
|
15
|
+
"exports": [
|
|
16
|
+
"."
|
|
17
|
+
],
|
|
18
|
+
"dependencies": {
|
|
19
|
+
"@happyvertical/files": "catalog:",
|
|
20
|
+
"@happyvertical/smrt-features": "workspace:*",
|
|
21
|
+
"@happyvertical/smrt-subscriptions": "workspace:*",
|
|
22
|
+
"@happyvertical/sql": "catalog:",
|
|
23
|
+
"@happyvertical/encryption": "catalog:",
|
|
24
|
+
"@happyvertical/smrt-app-runtime": "workspace:*",
|
|
25
|
+
"@happyvertical/smrt-cli": "workspace:*",
|
|
26
|
+
"@happyvertical/smrt-config": "workspace:*",
|
|
27
|
+
"@happyvertical/smrt-core": "workspace:*",
|
|
28
|
+
"@happyvertical/smrt-vitest": "workspace:*",
|
|
29
|
+
"@types/node": "24.13.6",
|
|
30
|
+
"typescript": "6.0.3",
|
|
31
|
+
"vite": "8.1.6",
|
|
32
|
+
"vitest": "4.1.10"
|
|
33
|
+
},
|
|
34
|
+
"smrtDependencies": [
|
|
35
|
+
"@happyvertical/smrt-app-runtime",
|
|
36
|
+
"@happyvertical/smrt-cli",
|
|
37
|
+
"@happyvertical/smrt-config",
|
|
38
|
+
"@happyvertical/smrt-core",
|
|
39
|
+
"@happyvertical/smrt-features",
|
|
40
|
+
"@happyvertical/smrt-subscriptions",
|
|
41
|
+
"@happyvertical/smrt-vitest"
|
|
42
|
+
],
|
|
43
|
+
"sdkDependencies": [
|
|
44
|
+
"@happyvertical/encryption",
|
|
45
|
+
"@happyvertical/files",
|
|
46
|
+
"@happyvertical/sql"
|
|
47
|
+
],
|
|
48
|
+
"tags": [
|
|
49
|
+
"cross-package"
|
|
50
|
+
],
|
|
51
|
+
"risks": [
|
|
52
|
+
"sensitive-fields-excluded"
|
|
53
|
+
],
|
|
54
|
+
"objects": [],
|
|
55
|
+
"surfaces": [],
|
|
56
|
+
"prompts": [],
|
|
57
|
+
"relationshipsV2": {
|
|
58
|
+
"foreignKeyFields": 0,
|
|
59
|
+
"crossPackageRefFields": 0,
|
|
60
|
+
"junctionCollections": 0,
|
|
61
|
+
"hierarchicalObjects": 0,
|
|
62
|
+
"polymorphicAssociations": 0,
|
|
63
|
+
"uuidColumns": 0
|
|
64
|
+
},
|
|
65
|
+
"agentDoc": "# SMRT Vault Relay\n\nBlind snapshot relay for the vault tier (#4799, epic #4668): a deployable\nservice storing encrypted snapshot blobs per account. See\n[README.md](README.md) for the protocol, configuration, and deployment.\n\n- **Blind by construction.** Never parse, decrypt, or validate blob content,\n never accept or store key material, and never log bodies, signatures,\n nonces, or account ids (log `accountHandle()` instead). Do not import the CLI\n snapshot framing; blobs are opaque bytes.\n- **Order of checks** on every `/v1` route: route match, signature (shape,\n skew, active device of that account, Ed25519, then nonce), `backup.vault`\n entitlement via `requireFeature`, then the body digest and handler. Keep\n authentication failures a single uniform `401`.\n- **Lapsed entitlement** (#4819, `gateEntitlement`): only the write routes\n (`isWriteRoute`: begin, chunk upload, commit, device delete) are refused,\n `402 entitlement_lapsed`; list, latest, download, abort and the lease routes\n stay open until `lapseRetentionDays` (default 90) after the lapse the relay\n first recorded (`vault_relay_lapses`), then `410 retention_expired`. Lapsed\n means upgrade-required denial of an account with committed snapshots; never\n entitled or operator-disabled stays `403`. Deletion is only the admin\n `lapse-sweep` (`sweepLapsedAccounts`), audited in the append-only\n `vault_relay_audit`; no device route deletes lapsed data. Do not slide the\n recorded time.\n- **Security properties are single conditional SQL statements** in\n `metadata-store.ts` (quota reservation, high-water advance, publish, nonce\n insert), portable across SQLite and PostgreSQL. Do not split them into\n read-then-write. Counter drift may only over-count. The high-water advance\n also carries the `maxSequenceJump` bound; the admin reset is the only way\n down.\n- **Primary-writer lease** (#4805, `lease-store.ts`, `lease.ts`): one row per\n account; acquire, renew, release, revoke and the commit-time head advance\n are single conditional statements on it. Publishing needs the holder's\n fencing token; the head never moves back (only the operator's high-water\n reset lowers it, to the latest remaining committed snapshot, clearing the\n holder), and the head and latest committed snapshot are never deleted by a\n device (a missing head row means an abandoned upload). A device delete of the\n sole committed snapshot is `409 last_snapshot`, of the newest of several\n `409 head_snapshot`; both are audited as `snapshot_delete_refused`.\n- **Object keys** are derived (`v1/<account hash>/<upload uuid>/<index>.<object\n id>`, a fresh object id per write) and checked by `assertObjectKey`; never\n build one from a client string or overwrite a recorded object. Removal of a\n pending upload is conditional on `status = 'pending'`.\n- **Schema** (including the lapse and audit tables) comes from `migrateVaultRelayV1` and `migrateVaultRelayLeasesV1` in the deployment migration\n step; request handling only checks table existence. No `@smrt()` models, so\n nothing gains generated REST, CLI, or MCP surfaces.\n- **Owner inputs** (quotas, retention, bucket, databases, domain, namespace)\n have no defaults. Do not invent values; do not edit `happyvertical/iac`.\n\nTests run in-process on SQLite with the filesystem store;\n`src/__tests__/postgres.optional.test.ts` runs under `pnpm test:postgres`.\n",
|
|
66
|
+
"moduleDocs": [
|
|
67
|
+
{
|
|
68
|
+
"path": "README.md",
|
|
69
|
+
"module": "README",
|
|
70
|
+
"content": "# s-m-r-t Vault Relay\n\n`@happyvertical/smrt-vault-relay` is the server side of the vault tier: a blind\nsnapshot relay. It stores encrypted snapshots per account, in a monotonic\nsequence, and can never read or validate their content. Devices encrypt with a\nuser-held key before upload (see the encrypted snapshot format in\n`smrt app backup --encrypted`). It holds no key material, but observes public\nframing, sizes, sequences, account/device identifiers and traffic activity.\nThe complete [metadata visibility contract](../cli/agents/encrypted-snapshots.md#relay-visible-metadata)\ndistinguishes this from content encryption; the relay's SHA-256 digests cover\nciphertext.\n\nEvery device route is authenticated by an Ed25519 device signature and then\ngated by the `backup.vault` feature (`requireFeature` from\n`@happyvertical/smrt-features`), resolved server-side from the account's plan\ngrants and overrides. A client cannot claim the entitlement. When the\nentitlement lapses, writes stop at once but restores stay open for a\nretention window; see [Lapsed subscriptions](#lapsed-subscriptions).\n\nThis package deploys as a container. It is not deployed by this repository:\nhosting is configured in `happyvertical/iac` from the inputs listed under\n[Required configuration](#required-configuration).\n\n## Device API\n\nAll `/v1` routes need the signature headers below. Bodies are JSON or raw\nciphertext; responses are JSON unless noted.\n\n| Route | Purpose |\n| --- | --- |\n| `GET /v1/lease` | Primary-writer lease state: `{ holder, expiresAt, headSequence, latestCommittedSequence, headIsHole }`. Never the token. |\n| `POST /v1/lease/acquire` | `{ baseSequence, ttlSeconds? }`. Grants `{ fencingToken, expiresAt, ttlMs, headSequence }`, or `409 must_restore_first`, `lease_held`, `publish_in_progress`. |\n| `POST /v1/lease/renew` | `{ fencingToken, ttlSeconds? }`. Extends an unexpired lease; `409 lease_lost` otherwise. |\n| `POST /v1/lease/release` | `{ fencingToken }`. `204`; a wrong token changes nothing. |\n| `POST /v1/uploads` | Begin an upload: `{ fencingToken, sequence, byteSize, chunkSize, sha256 }`. Needs the lease. Reserves quota. Returns `uploadId`, `chunkCount`, `expiresAt`. |\n| `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`. |\n| `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. |\n| `DELETE /v1/uploads/:uploadId` | Abort a pending upload and release its quota. |\n| `GET /v1/snapshots` | Committed snapshots, newest first. |\n| `GET /v1/snapshots/latest` | The newest committed snapshot. |\n| `GET /v1/snapshots/:sequence` | Metadata of one committed snapshot. |\n| `GET /v1/snapshots/:sequence/chunks/:index` | Chunk bytes (`application/octet-stream`, `x-vault-chunk-sha256`). |\n| `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. |\n| `GET /healthz`, `GET /readyz` | Liveness, and readiness (schema present, object store reachable). No authentication. |\n\nRules the relay enforces:\n\n- **Sequences are monotonic.** A new upload must use a sequence above every\n sequence ever published for the account, including deleted ones. A commit\n fails with `409 stale_sequence` if a higher sequence was published first, and\n that upload is discarded. Two uploads cannot share a sequence.\n- **Sequences cannot jump far.** The device picks its sequence and a commit\n raises the high-water mark for good, so a begin or commit more than\n `maxSequenceJump` above the current mark (default **1000**, a safe default\n chosen here, not an owner input; set `VAULT_RELAY_MAX_SEQUENCE_JUMP`) is\n `400 sequence_too_far` with `highWaterSequence` and `maxSequenceJump`. A\n brand-new account starts from a mark of 0, so its first sequence is at most\n the cap. One commit at the largest safe integer can therefore no longer\n make every later upload `stale_sequence`.\n- **One primary writer per account** (#4805). Publishing needs the lease,\n and the lease is granted only to a device whose `baseSequence` is the\n account's head, so a device that is behind must restore first; there is no\n merge. See [Primary-writer lease](#primary-writer-lease).\n- **Publish is atomic.** Pending uploads are never listed, never `latest`, and\n never downloadable. Abandoned uploads expire after the upload TTL.\n- **Quotas count pending uploads.** Bytes and snapshot count are reserved when\n an upload begins (`413 quota_exceeded`) and released on abort, expiry,\n deletion, and retention.\n- **The last snapshot stays.** A device cannot delete the only committed\n snapshot of its account (`409 last_snapshot`), so a compromised or mistaken\n device cannot erase the one restorable copy. Both the refusal\n (`snapshot_delete_refused`) and every successful device delete\n (`snapshot_deleted`) are logged with the hashed account handle, the device id\n and the sequence. The operator can still remove snapshots through the admin\n high-water reset. Two devices deleting the final two snapshots in the same\n instant can both pass on PostgreSQL (each sees the other); retention always\n keeps at least one.\n- **Retention** runs after each commit: the newest `keepLast` committed\n snapshots are kept, plus any committed within the age window. Snapshots\n inside the window count against the snapshot quota, so choose\n `maxSnapshots` above the number of backups an account makes per window plus\n one, or new uploads are refused until older snapshots age out.\n- **Bounded requests.** Chunk size is capped (default 8 MiB plus 64 KiB, hard\n ceiling 64 MiB), JSON bodies at 4 KiB. A body without `Content-Length`, or\n with the wrong one, is refused before it is buffered.\n\n### Primary-writer lease\n\nOne lease row per account names the holder device, a fencing token, an\nexpiry on the relay clock, and `headSequence`, the sequence the account's\ndata line is at. Every decision is one conditional statement on that row.\n\n- **Acquire** succeeds when the lease is free, expired, or already the\n caller's, and `baseSequence` is the head with no upload pending at the head,\n or, when the head's upload was abandoned (a *hole*), the latest committed\n sequence. Every grant, including a re-acquire by the same device,\n increments the fencing token, which fences an earlier process of that\n device too. Refusals: `must_restore_first { headSequence, latestSequence }`,\n `lease_held { holder, expiresAt }`, `publish_in_progress { headSequence }`.\n- **Renew** needs the holder, the current token, and an unexpired lease.\n **Release** needs the holder and the current token. Revoking a device clears\n any lease it holds and bumps the token.\n- **Publish.** Begin records the caller's token with the upload and refuses\n (`must_restore_first`) a caller that is not the unexpired holder with that\n token or whose sequence is not above the head. That begin check is\n advisory; commit enforces: after the digest check it advances the head\n only for the holder with the recorded token, while the upload is still\n pending, forward under an unexpired lease (or, for a retried commit, a head\n already at that sequence). A refused commit discards the upload and answers\n `409 must_restore_first`.\n- **Deletes** never remove the head or the latest committed snapshot, so a\n head without a row is always an abandoned upload, never deleted data.\n\nThe lifetime is `VAULT_RELAY_LEASE_TTL_SECONDS` (default 300, 30 to 3600); a\nclient may ask for less with `ttlSeconds`. Clients judge expiry from `ttlMs`\non their own monotonic clock, never by comparing `expiresAt` with local time.\n\n### Account supersession\n\nAfter a family restarts its vault because the recovery secret is lost\n(`@happyvertical/smrt-app-runtime`, vault key lifecycle `restartAccount`), the\naccount layer creates a new account and replaces the old one. The relay\nrecords only the replacement; it still cannot read anything.\n\nA replaced account answers `409 account_superseded` (no other detail, and\nnever the new account's id: a client does not follow the relay to another\naccount) to every device route that writes or offers a snapshot: lease\nacquire and renew, begin, chunk upload, commit, snapshot delete, list,\nlatest and lease status (the refusal on lease status is how a device proves,\nbefore it follows the new account, that the old one was replaced). Lease\nrelease, aborting an upload, and a snapshot's metadata and chunks by explicit\nsequence stay available, so state can be cleaned up and a snapshot rescued by\nhand. A stale device on the old account\ntherefore stops publishing into a line nobody follows, and restore-latest is\nnever handed the old vault. The new account is unaffected.\n\nOnly the admin listener sets or clears it, so a stolen device key cannot\nsilence or redirect an account. The account layer must re-authenticate the\nhuman owner first. The `DELETE` is for an operator mistake or a restart that\nnever reached the working device; it does not undo a device that already ran\n`restartAccount`, which has no local undo. The replacement must already hold an active\ndevice and must not be replaced itself, so there are no chains or loops.\nExisting snapshots stay until an operator deletes them.\n\n### Request signing\n\nEach request carries `x-vault-account`, `x-vault-device`, `x-vault-timestamp`\n(unix milliseconds), `x-vault-nonce` (16 to 64 base64url characters, single\nuse), `x-vault-content-sha256` (hex SHA-256 of the exact body; the empty-body\ndigest for bodiless requests), and `x-vault-signature`: the base64url Ed25519\nsignature over\n\n```text\nsmrt-vault-relay-v1\n<METHOD>\n<path and query, as the server parses it>\n<account id>\n<device id>\n<timestamp>\n<nonce>\n<body sha256>\n```\n\n`signRelayRequest()` builds these headers. Requests are rejected with one\nuniform `401 unauthorized` when a header is missing or malformed, the\ntimestamp is outside the clock-skew window (default 5 minutes), the device is\nunknown, revoked, or registered to another account, the signature does not\nverify, or the nonce was used before. A body whose digest differs from the\nsigned digest is rejected with `400 content_digest_mismatch`. Account and\ndevice ids match `[A-Za-z0-9][A-Za-z0-9_-]{0,127}`.\n\nEntitlement denials answer `403` with the structured body from\n`smrt-features` (`feature_upgrade_required` naming the granting plan, or\n`feature_disabled`). If the entitlement lookup itself fails, the relay answers\n`503 entitlement_unavailable`: it fails closed. An account that never held the\nentitlement, or whose entitlement an operator disabled, is refused on every\nroute. An account that held it and stored snapshots is *lapsed*:\n\n### Lapsed subscriptions\n\nOwner decision #4819. When `backup.vault` lapses for an account that holds\ncommitted snapshots:\n\n- The relay records the lapse time the first time it observes it (a device\n request, or the operator sweep's discovery pass). The time is kept, never\n moved, and cleared when the entitlement is active again.\n- **Writes are refused** (`begin`, chunk upload, commit, device snapshot\n delete) with `402 entitlement_lapsed` and `{ lapsedAt, restoreAvailableUntil }`.\n This code differs from the `403` upgrade/disabled denials and from the `401`\n authentication failure.\n- **Reads stay open** for authenticated devices of the account: list,\n `latest`, snapshot metadata and chunk download, aborting an upload, and the\n lease routes (restore-latest holds the lease while it downloads).\n- After `lapseRetentionDays` (default **90**, `VAULT_RELAY_LAPSE_RETENTION_DAYS`,\n 1 to 3650) reads answer `410 retention_expired` and the account is eligible\n for the sweep. Writes keep answering `402 entitlement_lapsed`.\n- **The sweep is an operator action, not a device action.**\n `POST /admin/v1/lapse-sweep` (admin token) with `{ dryRun?, limit?, cursor? }`\n and an optional `x-vault-operator` label header. Per run it handles at most\n `limit` accounts (default 10, at most 100) in two phases: a discovery pass\n over accounts with snapshots but no lapse record (resume with the returned\n `nextCursor`), which starts the window for lapses no device reported; and a\n deletion pass over lapses whose window has elapsed. Each account is\n re-checked first: one that is entitled again keeps its data and has its\n lapse cleared. Deletion uses the normal removal path (rows, counters,\n objects). Every deleted account writes a `lapse_sweep_started` and a\n `lapse_sweep_completed` record to the append-only `vault_relay_audit` table:\n time, operator (label plus a fingerprint of the admin token, never the\n token), hashed account handle, snapshot count and bytes. Re-running is\n idempotent; a run that crashed mid-account is finished by the next one. A\n dry run reports the same result and changes and audits nothing. A sweep\n leaves the account's high-water mark and lease head as they were.\n\n## Admin API (account layer and operator)\n\nServed on a separate listener, which must stay cluster-internal, and only when\n`VAULT_RELAY_ADMIN_TOKEN` is set. Requests use `Authorization: Bearer <token>`.\n\n| Route | Purpose |\n| --- | --- |\n| `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`. |\n| `DELETE /admin/v1/accounts/:account/devices/:device` | Revoke a device. Effective on its next request. |\n| `GET /admin/v1/accounts/:account` | Usage, snapshot sizes and dates, device states. Never content. |\n| `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). |\n| `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). |\n| `DELETE /admin/v1/accounts/:account/superseded-by` | Undo it, for an operator mistake. `204`, or `404 no_supersession`. |\n| `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. |\n| `POST /admin/v1/sweep` | Expire abandoned uploads and old nonces (also runs every minute). |\n| `POST /admin/v1/lapse-sweep` | Audited deletion of lapsed accounts' snapshots after the retention window (#4819). `{ dryRun?, limit?, cursor? }`; see [Lapsed subscriptions](#lapsed-subscriptions). |\n\nThe same hooks are available in-process: `relay.registerDevice()`,\n`relay.revokeDevice()`, `relay.operatorView()`.\n\n## Storage\n\nChunk bytes live in an object store under relay-derived keys,\n`v1/<sha256 account handle>/<upload uuid>/<index>.<random object id>`; no\nclient string becomes part of a key. Each write attempt gets its own object,\nand a chunk row is recorded only while its upload is still pending, so a write\nthat lands after an abort, expiry, or publish is deleted instead of counted. `FilesystemObjectStore` (atomic temp-and-rename writes) serves\ntests and single-node development. `createS3ObjectStore()` uses the\n`@happyvertical/files` S3 provider with path-style addressing for Garage.\n\nMetadata lives in the service database (SQLite or PostgreSQL) in ten\n`vault_relay_*` tables. `migrateVaultRelayV1(db)` and\n`migrateVaultRelayLeasesV1(db)` create them idempotently.\nRun it as the deployment's migration step (`node dist/cli.js migrate`); the\nserver checks the tables exist at readiness and never creates schema while\nserving.\n\n**Upgrading to account supersession (#4817).** `migrateVaultRelayV1` now also\ncreates `vault_relay_supersessions`. Re-run the migration job (it is\nidempotent) **before** deploying this version: until the table exists,\n`/readyz` reports `schema_missing` and the relay is not ready, and every\ndevice route that checks supersession (backup, restore, lease acquire and\nrenew) fails.\n\n**Upgrading to the lapse window (#4819).** `migrateVaultRelayV1` also creates\n`vault_relay_lapses` and `vault_relay_audit` (plain `CREATE TABLE IF NOT\nEXISTS`, no change to existing tables). Re-run the migration job before\ndeploying this version; until then `/readyz` reports `schema_missing`.\n\n## Required configuration\n\nThese are owner inputs. The relay has no defaults for them and refuses to start\nwithout them (except the admin token, see its row). Values are not chosen here.\n\n| Variable | Meaning |\n| --- | --- |\n| `VAULT_RELAY_DATABASE_URL` | Relay metadata database (`postgres://…`, or a SQLite path). Secret. |\n| `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. |\n| `VAULT_RELAY_STORAGE` | `s3` in deployment (`filesystem` for development). |\n| `VAULT_RELAY_S3_BUCKET` | Garage bucket for ciphertext. |\n| `VAULT_RELAY_S3_ENDPOINT` | Garage S3 endpoint URL. |\n| `VAULT_RELAY_S3_REGION` | Region name the Garage cluster is configured with. |\n| `VAULT_RELAY_S3_ACCESS_KEY_ID`, `VAULT_RELAY_S3_SECRET_ACCESS_KEY` | Bucket-scoped Garage key. Secret. |\n| `VAULT_RELAY_QUOTA_MAX_BYTES` | Per-account byte quota (committed plus pending). |\n| `VAULT_RELAY_QUOTA_MAX_SNAPSHOTS` | Per-account snapshot quota (committed plus pending). Must exceed `KEEP_LAST`. |\n| `VAULT_RELAY_RETENTION_KEEP_LAST` | Newest committed snapshots always kept (at least 1). |\n| `VAULT_RELAY_RETENTION_KEEP_WITHIN_DAYS` | Also keep snapshots committed within this many days (0 for none). |\n| `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. |\n\nOptional technical settings: `VAULT_RELAY_PORT` (8080), `VAULT_RELAY_ADMIN_PORT`\n(8081), `VAULT_RELAY_MAX_CHUNK_BYTES` (8454144), `VAULT_RELAY_UPLOAD_TTL_SECONDS`\n(86400), `VAULT_RELAY_MAX_CLOCK_SKEW_SECONDS` (300), `VAULT_RELAY_MAX_SEQUENCE_JUMP` (1000),\n`VAULT_RELAY_LEASE_TTL_SECONDS` (300), `VAULT_RELAY_LAPSE_RETENTION_DAYS` (90, 1 to\n3650). With `VAULT_RELAY_STORAGE=filesystem`,\n`VAULT_RELAY_STORAGE_PATH` is required.\n\nThe deployment also needs, from the owner: the namespace, the public domain and\nTLS for the device API, the image registry and digest, and network policy that\nkeeps the admin port private. The device Ingress must accept request bodies of\nat least the maximum chunk size plus headroom: with the default 8 MiB + 64 KiB\nchunks, set the ingress body limit to at least `9m` (`10m` in the `smrt-app`\nchart's allowed set; ingress-nginx defaults to `1m`). Keep\n`VAULT_RELAY_MAX_CHUNK_BYTES` below the ingress limit the chart permits.\n\n## Deployment\n\n`packages/vault-relay/Dockerfile` builds the image from the repository root:\n\n```sh\ndocker build -f packages/vault-relay/Dockerfile -t <registry>/smrt-vault-relay:<version> .\n```\n\nThe image runs as `node`, listens on 8080 (device API) and 8081 (admin API),\nand takes `serve` (default) or `migrate` as its command. For the `smrt-app`\nchart (see the [deployment guide](../../docs/content/deployment.md)), model it\nas:\n\n- one `web` workload, `writer: true`, command `[\"node\", \"dist/cli.js\", \"serve\"]`,\n port 8080, `readinessProbe` `GET /readyz`, `livenessProbe` `GET /healthz`,\n every variable above from named, immutable Secret keys, and a pod and\n container security context that is non-root with a read-only root\n filesystem (the relay writes nothing locally with S3 storage);\n- the migration job with command `[\"node\", \"dist/cli.js\", \"migrate\"]` and only\n `VAULT_RELAY_DATABASE_URL`. The DDL is idempotent; the chart's\n `smrt-release-v1` wrapper requirements still apply and are an adoption task;\n- the admin port exposed only through a cluster-internal Service, never the\n Ingress.\n\nThe relay keeps no state on local disk with S3 storage, so replicas can scale\nhorizontally: every security check is a conditional database statement.\n\n## Security model\n\n| Threat | Control | Test |\n| --- | --- | --- |\n| 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 |\n| Revoked device, or another account's device | Device lookup by (account, device), active only; ids never reused | `relay.test.ts` authentication |\n| Cross-account access | Every query scoped by the authenticated account; uploads looked up by (account, upload) | `relay.test.ts` cross-account isolation |\n| Quota or size abuse | Atomic conditional reservation; declared length checked before buffering; chunk cap | `relay.test.ts` quotas and request bounds |\n| 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 |\n| Partial upload becoming latest | Pending status; commit verifies every chunk and the whole digest | `relay.test.ts` atomic publish |\n| Sequence rollback or overwrite | Account high-water mark advanced conditionally; unique (account, sequence) | `relay.test.ts` atomic publish |\n| 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 |\n| Entitlement bypass, off plan | `requireFeature('backup.vault')` per request from server-side grants; fails closed | `entitlements.test.ts` |\n| 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` |\n| 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` |\n| 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` |\n| 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 |\n| Replayed acquire | Signed nonce and timestamp | `lease.test.ts` replay |\n| 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 |\n| 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 |\n| Supersession chains or loops | Target must have an active device and must not be replaced | `supersession.test.ts` target checks |\n| Path traversal in object keys | Keys derived from hash, server UUID, and index; regex and containment checks | `storage-and-config.test.ts` |\n\nResidual risks: a publish whose head advanced but whose commit was never\nretried blocks other devices' acquire (`publish_in_progress`) until the\nupload TTL expires; the relay is trusted to name the latest snapshot to a\ndevice with no local history (a device with history refuses anything below\nthe highest sequence it has seen). An operator can see ciphertext sizes, timing, and device ids\n(an HVSF snapshot also carries its producing device id, key id, generation, and\nlength in a clear file header that the relay stores but never parses);\nquota counters can over-count after a crash between steps (`reconcile`\nrepairs it); a crash between storing a chunk object and recording it can leave\none unreferenced ciphertext object.\n\n## Development\n\n```sh\npnpm --filter @happyvertical/smrt-vault-relay test\npnpm --filter @happyvertical/smrt-vault-relay typecheck\npnpm --filter @happyvertical/smrt-vault-relay test:postgres # needs a CI PostgreSQL URL\n```\n"
|
|
71
|
+
}
|
|
72
|
+
]
|
|
73
|
+
}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: "Component"
|
|
3
|
+
title: "@happyvertical/smrt-vault-relay"
|
|
4
|
+
description: "Blind snapshot relay: device-signed, per-account encrypted blob store gated by backup.vault"
|
|
5
|
+
status: "stable"
|
|
6
|
+
generated:
|
|
7
|
+
by: "smrt/scripts/generate-knowledge-okf.ts"
|
|
8
|
+
at: "2026-11-12T01:50:56Z"
|
|
9
|
+
audience: "internal"
|
|
10
|
+
evidence_level: "manifest-described"
|
|
11
|
+
source_revision: "sha256:e4b921ef0fc657ff6425c2fb37efef5ed4cd03954e430ec60a232b225ba59e2c"
|
|
12
|
+
sources:
|
|
13
|
+
- id: "manifest"
|
|
14
|
+
resource: "https://github.com/happyvertical/smrt/blob/main/packages/vault-relay/package.json"
|
|
15
|
+
title: "@happyvertical/smrt-vault-relay package manifest"
|
|
16
|
+
- id: "agents"
|
|
17
|
+
resource: "https://github.com/happyvertical/smrt/blob/main/packages/vault-relay/AGENTS.md"
|
|
18
|
+
title: "@happyvertical/smrt-vault-relay packages/vault-relay/AGENTS.md"
|
|
19
|
+
- id: "agents-2"
|
|
20
|
+
resource: "https://github.com/happyvertical/smrt/blob/main/packages/vault-relay/README.md"
|
|
21
|
+
title: "@happyvertical/smrt-vault-relay packages/vault-relay/README.md"
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
# @happyvertical/smrt-vault-relay
|
|
25
|
+
|
|
26
|
+
## Package
|
|
27
|
+
|
|
28
|
+
- Directory: `packages/vault-relay`
|
|
29
|
+
- Private: no
|
|
30
|
+
- Object source: `domain-artifact`
|
|
31
|
+
- Evidence level: `manifest-described`
|
|
32
|
+
|
|
33
|
+
## Documentation
|
|
34
|
+
|
|
35
|
+
- `packages/vault-relay/AGENTS.md`
|
|
36
|
+
- `packages/vault-relay/README.md`
|
|
37
|
+
|
|
38
|
+
## Framework dependencies
|
|
39
|
+
|
|
40
|
+
- [smrt-app-runtime](/components/smrt-app-runtime.md)
|
|
41
|
+
- [smrt-cli](/components/smrt-cli.md)
|
|
42
|
+
- [smrt-config](/components/smrt-config.md)
|
|
43
|
+
- [smrt-core](/components/smrt-core.md)
|
|
44
|
+
- [smrt-features](/components/smrt-features.md)
|
|
45
|
+
- [smrt-subscriptions](/components/smrt-subscriptions.md)
|
|
46
|
+
- [smrt-vitest](/components/smrt-vitest.md)
|
|
47
|
+
|
|
48
|
+
## SDK dependencies
|
|
49
|
+
|
|
50
|
+
- `@happyvertical/encryption`
|
|
51
|
+
- `@happyvertical/files`
|
|
52
|
+
- `@happyvertical/sql`
|
|
53
|
+
|
|
54
|
+
## Exports
|
|
55
|
+
|
|
56
|
+
- `.`
|
package/package.json
CHANGED
|
@@ -1,6 +1,57 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@happyvertical/smrt-vault-relay",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.60.17",
|
|
4
|
+
"description": "Blind snapshot relay: device-signed, per-account encrypted blob store gated by backup.vault",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"author": "HappyVertical",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"main": "./dist/index.js",
|
|
9
|
+
"types": "./dist/index.d.ts",
|
|
10
|
+
"exports": {
|
|
11
|
+
".": {
|
|
12
|
+
"types": "./dist/index.d.ts",
|
|
13
|
+
"import": "./dist/index.js"
|
|
14
|
+
}
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"AGENTS.md",
|
|
19
|
+
"CLAUDE.md"
|
|
20
|
+
],
|
|
21
|
+
"dependencies": {
|
|
22
|
+
"@happyvertical/files": "^0.112.2",
|
|
23
|
+
"@happyvertical/smrt-features": "0.60.17",
|
|
24
|
+
"@happyvertical/smrt-subscriptions": "0.60.17",
|
|
25
|
+
"@happyvertical/sql": "^0.112.2"
|
|
26
|
+
},
|
|
27
|
+
"devDependencies": {
|
|
28
|
+
"@happyvertical/encryption": "^0.112.2",
|
|
29
|
+
"@happyvertical/smrt-app-runtime": "0.60.17",
|
|
30
|
+
"@happyvertical/smrt-cli": "0.60.17",
|
|
31
|
+
"@happyvertical/smrt-config": "0.60.17",
|
|
32
|
+
"@happyvertical/smrt-core": "0.60.17",
|
|
33
|
+
"@happyvertical/smrt-vitest": "0.60.17",
|
|
34
|
+
"@types/node": "24.13.6",
|
|
35
|
+
"typescript": "6.0.3",
|
|
36
|
+
"vite": "8.1.6",
|
|
37
|
+
"vitest": "4.1.10"
|
|
38
|
+
},
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"registry": "https://registry.npmjs.org",
|
|
41
|
+
"access": "public"
|
|
42
|
+
},
|
|
43
|
+
"repository": {
|
|
44
|
+
"type": "git",
|
|
45
|
+
"url": "https://github.com/happyvertical/smrt.git",
|
|
46
|
+
"directory": "packages/vault-relay"
|
|
47
|
+
},
|
|
48
|
+
"scripts": {
|
|
49
|
+
"build": "vite build --mode library",
|
|
50
|
+
"clean": "rm -rf dist",
|
|
51
|
+
"start": "node dist/cli.js serve",
|
|
52
|
+
"test": "vitest run",
|
|
53
|
+
"test:postgres": "node ../../scripts/run-with-ci-postgres.mjs -- pnpm exec vitest run postgres.optional.test.ts",
|
|
54
|
+
"typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
|
|
55
|
+
"verify:pack": "node ../../scripts/verify-package-types-exports.js ."
|
|
56
|
+
}
|
|
6
57
|
}
|