also looking at this
feat: observe verified metadata before persistence
#1
8 files
+807
-21
| @@ -7,6 +7,7 @@ import { Config, defaultConfig } from './config'; | ||
| 7 | 7 | import { |
| 8 | 8 | DownloadHTTPError, |
| 9 | 9 | EqualVersionError, |
| 10 | MetadataVerificationError, | |
| 10 | 11 | PersistError, |
| 11 | 12 | RuntimeError, |
| 12 | 13 | ValueError, |
| @@ -23,6 +24,10 @@ export interface UpdaterOptions { | ||
| 23 | 24 | fetcher?: Fetcher; |
| 24 | 25 | forceCache?: boolean; |
| 25 | 26 | 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; | |
| 26 | 31 | } |
| 27 | 32 | |
| 28 | 33 | const log = debug('tuf:cache'); |
| @@ -41,6 +46,7 @@ export class Updater { | ||
| 41 | 46 | private trustedSet: TrustedMetadataStore; |
| 42 | 47 | private config: Config; |
| 43 | 48 | private fetcher: Fetcher; |
| 49 | private onVerifiedMetadata?: UpdaterOptions['onVerifiedMetadata']; | |
| 44 | 50 | |
| 45 | 51 | constructor(options: UpdaterOptions) { |
| 46 | 52 | const { |
| @@ -59,9 +65,26 @@ export class Updater { | ||
| 59 | 65 | this.targetBaseUrl = targetBaseUrl; |
| 60 | 66 | this.forceCache = options.forceCache ?? false; |
| 61 | 67 | |
| 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; | |
| 62 | 82 | const data = this.loadLocalMetadata(MetadataKind.Root); |
| 63 | 83 | |
| 64 | this.trustedSet = new TrustedMetadataStore(data); | |
| 84 | this.trustedSet = new TrustedMetadataStore( | |
| 85 | data, | |
| 86 | new Date(referenceTime.getTime()) | |
| 87 | ); | |
| 65 | 88 | this.config = { ...defaultConfig, ...config }; |
| 66 | 89 | const userAgent = config?.userAgent |
| 67 | 90 | ? `${config.userAgent} tuf-js/${version}` |
| @@ -89,6 +112,10 @@ export class Updater { | ||
| 89 | 112 | try { |
| 90 | 113 | await this.loadTimestamp({ checkRemote: false }); |
| 91 | 114 | } catch (error) { |
| 115 | // A failed observer or cache write is not a cache miss. | |
| 116 | if (error instanceof PersistError) { | |
| 117 | throw error; | |
| 118 | } | |
| 92 | 119 | await this.loadRoot(); |
| 93 | 120 | await this.loadTimestamp(); |
| 94 | 121 | } |
| @@ -202,10 +229,12 @@ export class Updater { | ||
| 202 | 229 | ); |
| 203 | 230 | |
| 204 | 231 | // Client workflow 5.3.4 - 5.4.7 |
| 205 | this.trustedSet.updateRoot(bytesData); | |
| 232 | this.verifyMetadata(MetadataKind.Root, () => | |
| 233 | this.trustedSet.updateRoot(bytesData) | |
| 234 | ); | |
| 206 | 235 | |
| 207 | 236 | // Client workflow 5.3.8: persist root metadata file |
| 208 | this.persistMetadata(MetadataKind.Root, bytesData); | |
| 237 | await this.persistMetadata(MetadataKind.Root, bytesData); | |
| 209 | 238 | } catch (error) { |
| 210 | 239 | if (error instanceof DownloadHTTPError) { |
| 211 | 240 | // 404/403 means current root is newest available |
| @@ -249,7 +278,9 @@ export class Updater { | ||
| 249 | 278 | |
| 250 | 279 | try { |
| 251 | 280 | // Client workflow 5.4.2 - 5.4.4 |
| 252 | this.trustedSet.updateTimestamp(bytesData); | |
| 281 | this.verifyMetadata(MetadataKind.Timestamp, () => | |
| 282 | this.trustedSet.updateTimestamp(bytesData) | |
| 283 | ); | |
| 253 | 284 | } catch (error) { |
| 254 | 285 | // If new timestamp version is same as current, discardd the new one. |
| 255 | 286 | // This is normal and should NOT raise an error. |
| @@ -262,7 +293,7 @@ export class Updater { | ||
| 262 | 293 | } |
| 263 | 294 | |
| 264 | 295 | // Client workflow 5.4.5: persist timestamp metadata |
| 265 | this.persistMetadata(MetadataKind.Timestamp, bytesData); | |
| 296 | await this.persistMetadata(MetadataKind.Timestamp, bytesData); | |
| 266 | 297 | } |
| 267 | 298 | |
| 268 | 299 | // Load local and remote snapshot metadata. |
| @@ -297,14 +328,16 @@ export class Updater { | ||
| 297 | 328 | ); |
| 298 | 329 | |
| 299 | 330 | // Client workflow 5.5.2 - 5.5.6 |
| 300 | this.trustedSet.updateSnapshot(bytesData); | |
| 331 | this.verifyMetadata(MetadataKind.Snapshot, () => | |
| 332 | this.trustedSet.updateSnapshot(bytesData) | |
| 333 | ); | |
| 301 | 334 | |
| 302 | 335 | // Client workflow 5.5.7: persist snapshot metadata file |
| 303 | this.persistMetadata(MetadataKind.Snapshot, bytesData); | |
| 336 | await this.persistMetadata(MetadataKind.Snapshot, bytesData); | |
| 304 | 337 | } 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 | }); | |
| 308 | 341 | } |
| 309 | 342 | } |
| 310 | 343 | } |
| @@ -351,12 +384,16 @@ export class Updater { | ||
| 351 | 384 | ); |
| 352 | 385 | |
| 353 | 386 | // 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 | ); | |
| 355 | 390 | |
| 356 | 391 | // Client workflow 5.6.7: persist targets metadata file |
| 357 | this.persistMetadata(role, bytesData); | |
| 392 | await this.persistMetadata(role, bytesData); | |
| 358 | 393 | } 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 | }); | |
| 360 | 397 | } |
| 361 | 398 | } |
| 362 | 399 | return this.trustedSet.getRole(role); |
| @@ -445,16 +482,34 @@ export class Updater { | ||
| 445 | 482 | return path.join(this.targetDir, filePath); |
| 446 | 483 | } |
| 447 | 484 | |
| 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) { | |
| 449 | 501 | const encodedName = encodeURIComponent(metaDataName); |
| 450 | 502 | try { |
| 503 | if (this.onVerifiedMetadata) { | |
| 504 | await this.onVerifiedMetadata(metaDataName, Buffer.from(bytesData)); | |
| 505 | } | |
| 451 | 506 | const filePath = path.join(this.dir, `${encodedName}.json`); |
| 452 | 507 | log('WRITE %s', filePath); |
| 453 | 508 | fs.writeFileSync(filePath, bytesData.toString('utf8')); |
| 454 | 509 | } 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 | }); | |
| 458 | 513 | } |
| 459 | 514 | } |
| 460 | 515 | } |