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/src/updater.tsmodified+72-17
Changes to packages/client/src/updater.ts
@@ -7,6 +7,7 @@ import { Config, defaultConfig } from './config';
77import {
88 DownloadHTTPError,
99 EqualVersionError,
10 MetadataVerificationError,
1011 PersistError,
1112 RuntimeError,
1213 ValueError,
@@ -23,6 +24,10 @@ export interface UpdaterOptions {
2324 fetcher?: Fetcher;
2425 forceCache?: boolean;
2526 config?: Partial<Config>;
27 /** Awaited after verification and before cache persistence. Receives an owned copy. */
28 onVerifiedMetadata?: (role: string, bytes: Buffer) => void | Promise<void>;
29 /** Copied fixed start time for recovery replay, not a trusted clock source. */
30 referenceTime?: Date;
2631}
2732
2833const log = debug('tuf:cache');
@@ -41,6 +46,7 @@ export class Updater {
4146 private trustedSet: TrustedMetadataStore;
4247 private config: Config;
4348 private fetcher: Fetcher;
49 private onVerifiedMetadata?: UpdaterOptions['onVerifiedMetadata'];
4450
4551 constructor(options: UpdaterOptions) {
4652 const {
@@ -59,9 +65,26 @@ export class Updater {
5965 this.targetBaseUrl = targetBaseUrl;
6066 this.forceCache = options.forceCache ?? false;
6167
68 const referenceTime = options.referenceTime ?? new Date();
69 if (
70 !(referenceTime instanceof Date) ||
71 !Number.isFinite(referenceTime.getTime())
72 ) {
73 throw new ValueError('Invalid fixed update reference time');
74 }
75 if (
76 options.onVerifiedMetadata !== undefined &&
77 typeof options.onVerifiedMetadata !== 'function'
78 ) {
79 throw new ValueError('Invalid verified metadata observer');
80 }
81 this.onVerifiedMetadata = options.onVerifiedMetadata;
6282 const data = this.loadLocalMetadata(MetadataKind.Root);
6383
64 this.trustedSet = new TrustedMetadataStore(data);
84 this.trustedSet = new TrustedMetadataStore(
85 data,
86 new Date(referenceTime.getTime())
87 );
6588 this.config = { ...defaultConfig, ...config };
6689 const userAgent = config?.userAgent
6790 ? `${config.userAgent} tuf-js/${version}`
@@ -89,6 +112,10 @@ export class Updater {
89112 try {
90113 await this.loadTimestamp({ checkRemote: false });
91114 } catch (error) {
115 // A failed observer or cache write is not a cache miss.
116 if (error instanceof PersistError) {
117 throw error;
118 }
92119 await this.loadRoot();
93120 await this.loadTimestamp();
94121 }
@@ -202,10 +229,12 @@ export class Updater {
202229 );
203230
204231 // Client workflow 5.3.4 - 5.4.7
205 this.trustedSet.updateRoot(bytesData);
232 this.verifyMetadata(MetadataKind.Root, () =>
233 this.trustedSet.updateRoot(bytesData)
234 );
206235
207236 // Client workflow 5.3.8: persist root metadata file
208 this.persistMetadata(MetadataKind.Root, bytesData);
237 await this.persistMetadata(MetadataKind.Root, bytesData);
209238 } catch (error) {
210239 if (error instanceof DownloadHTTPError) {
211240 // 404/403 means current root is newest available
@@ -249,7 +278,9 @@ export class Updater {
249278
250279 try {
251280 // Client workflow 5.4.2 - 5.4.4
252 this.trustedSet.updateTimestamp(bytesData);
281 this.verifyMetadata(MetadataKind.Timestamp, () =>
282 this.trustedSet.updateTimestamp(bytesData)
283 );
253284 } catch (error) {
254285 // If new timestamp version is same as current, discardd the new one.
255286 // This is normal and should NOT raise an error.
@@ -262,7 +293,7 @@ export class Updater {
262293 }
263294
264295 // Client workflow 5.4.5: persist timestamp metadata
265 this.persistMetadata(MetadataKind.Timestamp, bytesData);
296 await this.persistMetadata(MetadataKind.Timestamp, bytesData);
266297 }
267298
268299 // Load local and remote snapshot metadata.
@@ -297,14 +328,16 @@ export class Updater {
297328 );
298329
299330 // Client workflow 5.5.2 - 5.5.6
300 this.trustedSet.updateSnapshot(bytesData);
331 this.verifyMetadata(MetadataKind.Snapshot, () =>
332 this.trustedSet.updateSnapshot(bytesData)
333 );
301334
302335 // Client workflow 5.5.7: persist snapshot metadata file
303 this.persistMetadata(MetadataKind.Snapshot, bytesData);
336 await this.persistMetadata(MetadataKind.Snapshot, bytesData);
304337 } catch (error) {
305 throw new RuntimeError(
306 `Unable to load snapshot metadata error ${error}`
307 );
338 throw new RuntimeError('Unable to load snapshot metadata', {
339 cause: error,
340 });
308341 }
309342 }
310343 }
@@ -351,12 +384,16 @@ export class Updater {
351384 );
352385
353386 // Client workflow 5.6.2 - 5.6.6
354 this.trustedSet.updateDelegatedTargets(bytesData, role, parentRole);
387 this.verifyMetadata(role, () =>
388 this.trustedSet.updateDelegatedTargets(bytesData, role, parentRole)
389 );
355390
356391 // Client workflow 5.6.7: persist targets metadata file
357 this.persistMetadata(role, bytesData);
392 await this.persistMetadata(role, bytesData);
358393 } catch (error) {
359 throw new RuntimeError(`Unable to load targets error ${error}`);
394 throw new RuntimeError('Unable to load targets metadata', {
395 cause: error,
396 });
360397 }
361398 }
362399 return this.trustedSet.getRole(role);
@@ -445,16 +482,34 @@ export class Updater {
445482 return path.join(this.targetDir, filePath);
446483 }
447484
448 private persistMetadata(metaDataName: string, bytesData: Buffer) {
485 private verifyMetadata<T>(role: string, operation: () => T): T {
486 try {
487 return operation();
488 } catch (error) {
489 if (error instanceof EqualVersionError) {
490 throw error;
491 }
492 throw new MetadataVerificationError(
493 role,
494 `Failed to verify metadata ${encodeURIComponent(role)}`,
495 { cause: error }
496 );
497 }
498 }
499
500 private async persistMetadata(metaDataName: string, bytesData: Buffer) {
449501 const encodedName = encodeURIComponent(metaDataName);
450502 try {
503 if (this.onVerifiedMetadata) {
504 await this.onVerifiedMetadata(metaDataName, Buffer.from(bytesData));
505 }
451506 const filePath = path.join(this.dir, `${encodedName}.json`);
452507 log('WRITE %s', filePath);
453508 fs.writeFileSync(filePath, bytesData.toString('utf8'));
454509 } catch (error) {
455 throw new PersistError(
456 `Failed to persist metadata ${encodedName} error: ${error}`
457 );
510 throw new PersistError(`Failed to persist metadata ${encodedName}`, {
511 cause: error,
512 });
458513 }
459514 }
460515}