ReviewOS

also looking at this

stacks/tuf-js

feat: observe verified metadata before persistence

#1
Merged chris wants to merge codex/verified-metadata-source into main
8 files +807 -21
packages/client/tests/observer.test.tsadded+521-0
Changes to packages/client/tests/observer.test.ts
@@ -0,0 +1,521 @@
1import assert from 'node:assert/strict';
2import { existsSync, readFileSync } from 'node:fs';
3import { createServer, type Server } from 'node:http';
4import {
5 copyFile,
6 mkdir,
7 mkdtemp,
8 readFile,
9 readdir,
10 rm,
11 writeFile,
12} from 'node:fs/promises';
13import { tmpdir } from 'node:os';
14import { basename, join } from 'node:path';
15import { Updater, type UpdaterOptions } from '../src/index';
16import * as Tuf from '../src/index';
17import { repository } from './fixtures/observer-repository';
18
19const roots: string[] = [];
20const servers: Server[] = [];
21afterEach(async () => {
22 for (const server of servers.splice(0)) {
23 server.closeAllConnections();
24 await new Promise<void>((resolve, reject) => {
25 server.close((error) => (error ? reject(error) : resolve()));
26 });
27 }
28 for (const root of roots.splice(0))
29 await rm(root, { recursive: true, force: true });
30});
31
32async function setup(
33 options: Parameters<typeof repository>[1] = { rotate: true },
34 missing?: string
35) {
36 const root = await mkdtemp(join(tmpdir(), 'drone-sdk-test-'));
37 roots.push(root);
38 const repo = join(root, 'repo'),
39 cache = join(root, 'cache'),
40 requests: string[] = [];
41 const fixture = await repository(repo, options);
42 await mkdir(cache, { mode: 0o700 });
43 await copyFile(fixture.rootPath, join(cache, 'root.json'));
44 const server = createServer((request, response) => {
45 const path = new URL(request.url ?? '/', 'http://127.0.0.1').pathname;
46 requests.push(path);
47 const filePath = join(repo, 'metadata', basename(path));
48 if (
49 !/^\/metadata\/(?:[0-9]+\.)?(?:root|timestamp|snapshot|targets)\.json$/.test(
50 path
51 ) ||
52 basename(path) === missing ||
53 !existsSync(filePath)
54 ) {
55 response.writeHead(404).end();
56 return;
57 }
58 response.end(readFileSync(filePath));
59 });
60 await new Promise<void>((resolve, reject) => {
61 server.once('error', reject);
62 server.listen(0, '127.0.0.1', () => {
63 server.off('error', reject);
64 resolve();
65 });
66 });
67 servers.push(server);
68 const address = server.address();
69 if (!address || typeof address === 'string')
70 throw new Error('Fixture server did not bind TCP');
71 const input = {
72 metadataDir: cache,
73 metadataBaseUrl: `http://127.0.0.1:${address.port}/metadata`,
74 config: { fetchRetries: 0, fetchTimeout: 1000 },
75 } satisfies UpdaterOptions;
76 return { root, repo, cache, fixture, requests, input };
77}
78
79async function failureOf(pending: Promise<unknown>): Promise<Error> {
80 try {
81 await pending;
82 } catch (error) {
83 assert(error instanceof Error);
84 return error;
85 }
86 throw new Error('Expected refresh to reject');
87}
88
89function rootVersion(bytes: string): number {
90 const metadata: unknown = JSON.parse(bytes);
91 assert(metadata && typeof metadata === 'object' && 'signed' in metadata);
92 const signed = metadata.signed;
93 assert(signed && typeof signed === 'object' && 'version' in signed);
94 assert(typeof signed.version === 'number');
95 return signed.version;
96}
97
98const roles = ['root', 'timestamp', 'snapshot', 'targets'] as const;
99
100test('the maintained SDK observer receives exact verified bytes before each cache write', async () => {
101 const item = await setup(),
102 seen: string[] = [];
103 const updater = new Updater({
104 ...item.input,
105 async onVerifiedMetadata(role, bytes) {
106 seen.push(role);
107 if (role === 'root')
108 expect(
109 rootVersion(await readFile(join(item.cache, 'root.json'), 'utf8'))
110 ).toBe(1);
111 else expect(existsSync(join(item.cache, `${role}.json`))).toBe(false);
112 const file =
113 role === 'root'
114 ? '2.root.json'
115 : role === 'timestamp'
116 ? 'timestamp.json'
117 : `1.${role}.json`;
118 expect(bytes).toEqual(await readFile(join(item.repo, 'metadata', file)));
119 },
120 });
121 await updater.refresh();
122 expect(seen).toEqual([...roles]);
123 expect((await readdir(item.cache)).sort()).toEqual([
124 'root.json',
125 'snapshot.json',
126 'targets.json',
127 'timestamp.json',
128 ]);
129});
130
131test('a pending observer prevents the cache write and the next metadata request', async () => {
132 const item = await setup();
133 let release!: () => void, entered!: () => void;
134 const gate = new Promise<void>((resolve) => {
135 release = resolve;
136 });
137 const seen = new Promise<void>((resolve) => {
138 entered = resolve;
139 });
140 const pending = new Updater({
141 ...item.input,
142 async onVerifiedMetadata(role) {
143 if (role === 'root') {
144 entered();
145 await gate;
146 }
147 },
148 }).refresh();
149 try {
150 await seen;
151 expect(
152 rootVersion(await readFile(join(item.cache, 'root.json'), 'utf8'))
153 ).toBe(1);
154 expect(item.requests).toEqual(['/metadata/2.root.json']);
155 } finally {
156 release();
157 await pending;
158 }
159});
160
161for (const failedRole of roles) {
162 test(`an observer rejection for ${failedRole} aborts before that cache or a later role advances`, async () => {
163 const item = await setup(),
164 seen: string[] = [],
165 cause = new Error('protected persistence rejected');
166 const updater = new Updater({
167 ...item.input,
168 async onVerifiedMetadata(role) {
169 await Promise.resolve();
170 seen.push(role);
171 if (role === failedRole) throw cause;
172 },
173 });
174 const failure = await failureOf(updater.refresh());
175 const persistence =
176 failedRole === 'snapshot' || failedRole === 'targets'
177 ? failure.cause
178 : failure;
179 expect(persistence).toBeInstanceOf(Tuf.PersistError);
180 assert(persistence instanceof Tuf.PersistError);
181 expect(persistence.message).toBe(
182 `Failed to persist metadata ${failedRole}`
183 );
184 expect(persistence.cause).toBe(cause);
185 expect(seen).toEqual(roles.slice(0, roles.indexOf(failedRole) + 1));
186 if (failedRole === 'root')
187 expect(
188 rootVersion(await readFile(join(item.cache, 'root.json'), 'utf8'))
189 ).toBe(1);
190 else expect(existsSync(join(item.cache, `${failedRole}.json`))).toBe(false);
191 });
192}
193
194test('a genuine SDK HTTP404 thrown by the observer cannot be mistaken for the end of root rotation', async () => {
195 const source = await setup({ rotate: false }, 'timestamp.json');
196 const downloadFailure = await failureOf(new Updater(source.input).refresh());
197 assert(downloadFailure instanceof Tuf.DownloadHTTPError);
198 expect(downloadFailure.statusCode).toBe(404);
199 const item = await setup(),
200 seen: string[] = [];
201 await expect(
202 new Updater({
203 ...item.input,
204 onVerifiedMetadata(role) {
205 seen.push(role);
206 throw downloadFailure;
207 },
208 }).refresh()
209 ).rejects.toThrow('Failed to persist metadata root');
210 expect(seen).toEqual(['root']);
211 expect(
212 rootVersion(await readFile(join(item.cache, 'root.json'), 'utf8'))
213 ).toBe(1);
214});
215
216test('the observer owns a byte copy and cannot mutate SDK verification or cache bytes', async () => {
217 const item = await setup(),
218 observed: Record<string, Buffer> = {};
219 await new Updater({
220 ...item.input,
221 onVerifiedMetadata(role, bytes) {
222 observed[role] = Buffer.from(bytes);
223 bytes.fill(0);
224 },
225 }).refresh();
226 for (const role of roles)
227 expect(
228 (await readFile(join(item.cache, `${role}.json`))).equals(observed[role])
229 ).toBe(true);
230});
231
232test('an unauthorized root never reaches the observer and leaves the initial cache intact', async () => {
233 const item = await setup({ rotate: true, badRotation: true }),
234 seen: string[] = [];
235 await expect(
236 new Updater({
237 ...item.input,
238 onVerifiedMetadata(role) {
239 seen.push(role);
240 },
241 }).refresh()
242 ).rejects.toThrow();
243 expect(seen).toEqual([]);
244 expect(
245 rootVersion(await readFile(join(item.cache, 'root.json'), 'utf8'))
246 ).toBe(1);
247});
248
249test('a later invalid target signature preserves only the earlier verified metadata observations', async () => {
250 const item = await setup({ rotate: true, badTargetsSignature: true }),
251 seen: string[] = [];
252 await expect(
253 new Updater({
254 ...item.input,
255 onVerifiedMetadata(role) {
256 seen.push(role);
257 },
258 }).refresh()
259 ).rejects.toThrow();
260 expect(seen).toEqual(['root', 'timestamp', 'snapshot']);
261 expect(existsSync(join(item.cache, 'targets.json'))).toBe(false);
262});
263
264test('snapshot-bound tampering is rejected before it reaches the observer', async () => {
265 const item = await setup(),
266 seen: string[] = [];
267 await writeFile(join(item.repo, 'metadata/1.targets.json'), '{}');
268 await expect(
269 new Updater({
270 ...item.input,
271 onVerifiedMetadata(role) {
272 seen.push(role);
273 },
274 }).refresh()
275 ).rejects.toThrow();
276 expect(seen).toEqual(['root', 'timestamp', 'snapshot']);
277});
278
279test('the supplied fixed start time is owned before callers can mutate it', async () => {
280 const item = await setup(),
281 time = new Date('2030-01-01T00:00:00Z');
282 const updater = new Updater({ ...item.input, referenceTime: time });
283 time.setUTCFullYear(2040);
284 await updater.refresh();
285 expect(
286 rootVersion(await readFile(join(item.cache, 'root.json'), 'utf8'))
287 ).toBe(2);
288});
289
290test('fixed-time recovery replay is distinct from current-time authorization', async () => {
291 const past = await setup({ expires: '2025-01-01T00:00:00Z' });
292 await new Updater({
293 ...past.input,
294 referenceTime: new Date('2024-01-01T00:00:00Z'),
295 }).refresh();
296 const current = await setup({ expires: '2025-01-01T00:00:00Z' });
297 const failure = await failureOf(new Updater(current.input).refresh());
298 expect(failure).toBeInstanceOf(Tuf.MetadataVerificationError);
299 assert(failure instanceof Tuf.MetadataVerificationError);
300 expect(failure.role).toBe('timestamp');
301 expect(failure.cause).toBeInstanceOf(Error);
302 assert(failure.cause instanceof Error);
303 expect(failure.cause.message).toContain('expired');
304});
305
306test('invalid fixed time is rejected before loading even a missing bootstrap root', () => {
307 expect(
308 () =>
309 new Updater({
310 metadataDir: '/missing-drone-sdk-bootstrap',
311 metadataBaseUrl: 'http://127.0.0.1:1',
312 referenceTime: new Date(Number.NaN),
313 })
314 ).toThrow('Invalid fixed update reference time');
315});
316
317test('a fully cached trusted refresh does not emit observations for cache bytes', async () => {
318 const item = await setup();
319 await new Updater(item.input).refresh();
320 const seen: string[] = [];
321 await new Updater({
322 ...item.input,
323 onVerifiedMetadata(role) {
324 seen.push(role);
325 },
326 }).refresh();
327 expect(seen).toEqual([]);
328});
329
330test('an authenticated intermediate root is observed before final-root expiry rejects the refresh', async () => {
331 const item = await setup({
332 rotate: true,
333 metadataFields: { rotatedRoot: { expires: '2020-01-01T00:00:00Z' } },
334 }),
335 seen: string[] = [];
336 const failure = await failureOf(
337 new Updater({
338 ...item.input,
339 onVerifiedMetadata(role) {
340 seen.push(role);
341 },
342 }).refresh()
343 );
344 expect(failure).toBeInstanceOf(Tuf.MetadataVerificationError);
345 assert(failure instanceof Tuf.MetadataVerificationError);
346 expect(failure.role).toBe('timestamp');
347 expect(failure.cause).toBeInstanceOf(Error);
348 assert(failure.cause instanceof Error);
349 expect(failure.cause.message).toContain('expired');
350 expect(seen).toEqual(['root']);
351 expect(
352 rootVersion(await readFile(join(item.cache, 'root.json'), 'utf8'))
353 ).toBe(2);
354});
355
356test('forceCache cannot swallow a rejected remote timestamp observer when its local cache is missing', async () => {
357 const item = await setup({ rotate: false }),
358 seen: string[] = [];
359 await expect(
360 new Updater({
361 ...item.input,
362 forceCache: true,
363 onVerifiedMetadata(role) {
364 seen.push(role);
365 if (role === 'timestamp')
366 throw new Error('protected timestamp persistence rejected');
367 },
368 }).refresh()
369 ).rejects.toThrow('Failed to persist metadata timestamp');
370 expect(seen).toEqual(['timestamp']);
371 expect(item.requests).toEqual(['/metadata/timestamp.json']);
372 expect((await readdir(item.cache)).sort()).toEqual(['root.json']);
373});
374
375test('a signed metadata rejection retains its original typed cause through the SDK wrapper', async () => {
376 const item = await setup({ badTargetsSignature: true });
377 const failure = await failureOf(new Updater(item.input).refresh());
378 expect(failure).toBeInstanceOf(Error);
379 expect(failure.cause).toBeInstanceOf(Error);
380});
381
382test('recovery can identify a remote metadata rejection through a public typed cause', async () => {
383 const item = await setup({ badTargetsSignature: true });
384 const failure = await failureOf(new Updater(item.input).refresh());
385 expect(Tuf.MetadataVerificationError).toEqual(expect.any(Function));
386 expect(failure.cause).toBeInstanceOf(Tuf.MetadataVerificationError);
387 assert(failure.cause instanceof Tuf.MetadataVerificationError);
388 expect(failure.cause.role).toBe('targets');
389});
390
391for (const role of roles) {
392 test(`remote ${role} verification failure has a typed role and original cause`, async () => {
393 const options: Parameters<typeof repository>[1] =
394 role === 'root'
395 ? { rotate: true, badRotation: true }
396 : { metadataFields: { [role]: { expires: '2020-01-01T00:00:00Z' } } };
397 const item = await setup(options);
398 const failure = await failureOf(new Updater(item.input).refresh());
399 const verification =
400 failure instanceof Tuf.MetadataVerificationError
401 ? failure
402 : failure.cause;
403 expect(verification).toBeInstanceOf(Tuf.MetadataVerificationError);
404 assert(verification instanceof Tuf.MetadataVerificationError);
405 expect(verification.role).toBe(role);
406 expect(verification.cause).toBeInstanceOf(Error);
407 });
408}
409
410test('observer failure stays a persistence failure and preserves its exact cause', async () => {
411 const item = await setup(),
412 cause = new Error('protected storage failure');
413 const failure = await failureOf(
414 new Updater({
415 ...item.input,
416 onVerifiedMetadata() {
417 throw cause;
418 },
419 }).refresh()
420 );
421 expect(failure).toBeInstanceOf(Tuf.PersistError);
422 expect(failure).not.toBeInstanceOf(Tuf.MetadataVerificationError);
423 expect(failure.cause).toBe(cause);
424 expect(item.requests).toEqual(['/metadata/2.root.json']);
425});
426
427test('an observer-supplied verification error is still classified as failed persistence first', async () => {
428 const item = await setup({ rotate: false }),
429 cause = new Tuf.MetadataVerificationError(
430 'timestamp',
431 'caller error, not an SDK verification verdict'
432 );
433 const failure = await failureOf(
434 new Updater({
435 ...item.input,
436 forceCache: true,
437 onVerifiedMetadata() {
438 throw cause;
439 },
440 }).refresh()
441 );
442 expect(failure).toBeInstanceOf(Tuf.PersistError);
443 expect(failure.cause).toBe(cause);
444 expect(item.requests).toEqual(['/metadata/timestamp.json']);
445});
446
447test('the public HTTP failure class matches actual missing-metadata failures', async () => {
448 const item = await setup({ rotate: false }, 'timestamp.json');
449 const failure = await failureOf(new Updater(item.input).refresh());
450 expect(failure).toBeInstanceOf(Tuf.DownloadHTTPError);
451 assert(failure instanceof Tuf.DownloadHTTPError);
452 expect(failure).toBeInstanceOf(Tuf.DownloadError);
453 expect(failure.statusCode).toBe(404);
454 expect(failure).not.toBeInstanceOf(Tuf.MetadataVerificationError);
455});
456
457test('a Symbol observer rejection remains a persistence failure under forceCache', async () => {
458 const item = await setup({ rotate: false }),
459 seen: string[] = [],
460 cause = Symbol('opaque storage failure');
461 const failure = await failureOf(
462 new Updater({
463 ...item.input,
464 forceCache: true,
465 onVerifiedMetadata(role) {
466 seen.push(role);
467 if (role === 'timestamp') {
468 // Deliberately exercise a legal opaque observer rejection.
469 // eslint-disable-next-line @typescript-eslint/only-throw-error
470 throw cause;
471 }
472 },
473 }).refresh()
474 );
475 expect(failure).toBeInstanceOf(Tuf.PersistError);
476 expect(failure.cause).toBe(cause);
477 expect(seen).toEqual(['timestamp']);
478 expect(item.requests).toEqual(['/metadata/timestamp.json']);
479 expect((await readdir(item.cache)).sort()).toEqual(['root.json']);
480});
481
482test('observer failures are never coerced while wrapping any metadata role', async () => {
483 for (const failedRole of roles) {
484 const item = await setup(),
485 seen: string[] = [];
486 let coercions = 0;
487 const cause = {
488 toString() {
489 coercions++;
490 throw new Error('Cause coercion must not run');
491 },
492 };
493 const failure = await failureOf(
494 new Updater({
495 ...item.input,
496 onVerifiedMetadata(role) {
497 seen.push(role);
498 if (role === failedRole) {
499 // Deliberately reject with an object whose coercion must never run.
500 // eslint-disable-next-line @typescript-eslint/only-throw-error
501 throw cause;
502 }
503 },
504 }).refresh()
505 );
506 const persistence =
507 failedRole === 'snapshot' || failedRole === 'targets'
508 ? failure.cause
509 : failure;
510 expect(persistence).toBeInstanceOf(Tuf.PersistError);
511 assert(persistence instanceof Tuf.PersistError);
512 expect(persistence.cause).toBe(cause);
513 expect(coercions).toBe(0);
514 expect(seen).toEqual(roles.slice(0, roles.indexOf(failedRole) + 1));
515 if (failedRole === 'root')
516 expect(
517 rootVersion(await readFile(join(item.cache, 'root.json'), 'utf8'))
518 ).toBe(1);
519 else expect(existsSync(join(item.cache, `${failedRole}.json`))).toBe(false);
520 }
521});