|null */ private $ok_cache = null; /** * Index of the loaded approved shard. * * @var int */ private $ok_cache_i = -1; /** * Working directory for this check. * * @var string */ private $dir; /** * Constructor. * * @param string $dir Working directory (inside the protected job dir). */ public function __construct( string $dir ) { if ( ! is_dir( $dir ) && ! wp_mkdir_p( $dir ) ) { throw new State_Exception( esc_html( State_Files::io_message( __( 'Unable to create validation working directory', '007aj-backup-restore-verifier' ), $dir ) ) ); } $this->dir = $dir; } /** * Path of the extracted checksums list (valid after the meta stage). */ public function sums_path(): string { return $this->dir . '/sums.txt'; } /** * Advance validation. * * @param string $zip Archive path. * @param array $st State (empty to start). Optional 'sha256' to check the whole file. * @param float $deadline Deadline. * @return array New state: 'done' => true when valid; throws on failure. * @throws State_Exception With a clear reason when the archive is invalid. */ public function step( string $zip, array $st, float $deadline ): array { if ( '' === $zip || ! is_readable( $zip ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: path */ __( 'Artifact zip is missing or unreadable: %s', '007aj-backup-restore-verifier' ), $zip ) ) ); } if ( empty( $st['stage'] ) ) { $st['stage'] = ! empty( $st['sha256'] ) ? 'filehash' : 'scan'; } while ( microtime( true ) < $deadline ) { $stage = (string) $st['stage']; if ( 'filehash' === $stage ) { $hash = \BRVerify\Backup\Backup_Driver::hash_file_resumable( $zip, $st, $deadline ); if ( '' === $hash ) { return $st; } unset( $st['fo'], $st['fh'], $st['rh'] ); if ( ! hash_equals( strtolower( (string) $st['sha256'] ), $hash ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: file name */ __( 'Archive file checksum does not match the stored record: %s', '007aj-backup-restore-verifier' ), basename( $zip ) ) ) ); } $st['stage'] = 'scan'; continue; } if ( 'scan' === $stage ) { if ( ! $this->scan( $zip, $st, $deadline ) ) { return $st; } $st['stage'] = 'meta'; continue; } if ( 'meta' === $stage ) { $this->meta( $zip, $st ); $st['stage'] = 'split'; continue; } if ( 'split' === $stage ) { if ( ! $this->split( $st, $deadline ) ) { return $st; } $st['stage'] = 'match'; $st['mh'] = 0; $st['mm'] = 0; continue; } if ( 'match' === $stage ) { if ( ! $this->match( $st, $deadline ) ) { return $st; } $st['stage'] = 'verify'; $st['sh'] = 0; $st['so'] = 0; continue; } if ( 'verify' === $stage ) { if ( ! $this->verify( $zip, $st, $deadline ) ) { return $st; } clearstatcache( true, $zip ); State_Files::write_atomic( $this->dir . '/validated.json', State_Files::encode_row( array( 'size' => (int) filesize( $zip ), 'mtime' => (int) filemtime( $zip ), 'n' => (int) ( $st['ok'] ?? 0 ), ) ) ); $st['stage'] = 'done'; $st['done'] = 1; $this->cleanup_shards(); return $st; } if ( 'done' === $stage ) { $st['done'] = 1; return $st; } throw new State_Exception( esc_html( 'Unknown validation stage: ' . $stage ) ); } return $st; } /** * Decoded manifest (after the meta stage). * * @return array */ public function manifest(): array { $m = json_decode( (string) @file_get_contents( $this->dir . '/manifest.json' ), true ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents, WordPress.PHP.NoSilencedErrors.Discouraged return is_array( $m ) ? $m : array(); } /** * Central directory walk. * * @param string $zip Archive. * @param array $st State (by reference). * @param float $deadline Deadline. * @return bool Done. */ private function scan( string $zip, array &$st, float $deadline ): bool { $sizes = isset( $st['sz'] ) && is_array( $st['sz'] ) ? $st['sz'] : array_fill( 0, self::SHARDS, 0 ); for ( $i = 0; $i < self::SHARDS; $i++ ) { State_Files::truncate( $this->shard( 'cd', $i ), (int) $sizes[ $i ] ); } $reader = new Zip_Reader( $zip ); $pos = (int) ( $st['cd'] ?? 0 ); $bufs = array(); $done = false; try { $st['n'] = (int) ( $st['n'] ?? 0 ); while ( microtime( true ) < $deadline ) { $r = $reader->entries( $pos, 2048, $deadline ); foreach ( $r['entries'] as $e ) { $name = (string) $e['name']; if ( ! Validator::is_safe_zip_entry( $name ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: entry */ __( 'Zip-slip / unsafe archive path rejected: %s', '007aj-backup-restore-verifier' ), $name ) ) ); } if ( in_array( $name, array( 'manifest.json', 'checksums.sha256', 'database/dump.sql', 'database/dump.sql.rpenc' ), true ) ) { if ( isset( $st['sp'][ $name ] ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: archive member path */ __( 'Duplicate archive path rejected: %s', '007aj-backup-restore-verifier' ), $name ) ) ); } $st['sp'][ $name ] = $e; } $k = $this->shard_of( self::key( $name ) ); $bufs[ $k ] = ( $bufs[ $k ] ?? '' ) . State_Files::encode_row( $e ) . "\n"; ++$st['n']; } $pos = $r['pos']; foreach ( $bufs as $k => $b ) { State_Files::append( $this->shard( 'cd', (int) $k ), $b ); $sizes[ $k ] = (int) $sizes[ $k ] + strlen( $b ); } $bufs = array(); if ( $r['eof'] || empty( $r['entries'] ) ) { $done = true; break; } } } finally { $reader->close(); } $st['cd'] = $pos; $st['sz'] = $sizes; if ( $done ) { unset( $st['sz'], $st['cd'] ); } return $done; } /** * Manifest + checksums.sha256 extraction and payload hash check. * * @param string $zip Archive. * @param array $st State (by reference). */ private function meta( string $zip, array &$st ): void { $sp = isset( $st['sp'] ) && is_array( $st['sp'] ) ? $st['sp'] : array(); if ( empty( $sp['manifest.json'] ) ) { throw new State_Exception( esc_html( __( 'manifest.json missing from artifact.', '007aj-backup-restore-verifier' ) ) ); } if ( empty( $sp['checksums.sha256'] ) ) { throw new State_Exception( esc_html( __( 'checksums.sha256 missing from artifact.', '007aj-backup-restore-verifier' ) ) ); } $reader = new Zip_Reader( $zip ); try { $raw = $reader->read_small( $sp['manifest.json'], 4194304 ); $manifest = json_decode( $raw, true ); if ( ! is_array( $manifest ) ) { throw new State_Exception( esc_html( __( 'manifest.json is not valid JSON.', '007aj-backup-restore-verifier' ) ) ); } $format = isset( $manifest['format'] ) ? (string) $manifest['format'] : ''; if ( ! Manifest::is_supported_format( $format ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: format string */ __( 'Unsupported archive format: %s', '007aj-backup-restore-verifier' ), '' !== $format ? $format : '(empty)' ) ) ); } State_Files::write_atomic( $this->dir . '/manifest.json', $raw ); $sums = $this->sums_path(); State_Files::truncate( $sums, 0 ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen $out = fopen( $sums, 'wb' ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen if ( false === $out ) { throw new State_Exception( esc_html( State_Files::io_message( __( 'Unable to write working file', '007aj-backup-restore-verifier' ), $sums ) ) ); } $res = $reader->stream( $sp['checksums.sha256'], static function ( string $b ) use ( $out, $sums ): void { // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fwrite if ( strlen( $b ) !== fwrite( $out, $b ) ) { // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fwrite throw new State_Exception( esc_html( State_Files::io_message( __( 'Short write to working file (disk full?)', '007aj-backup-restore-verifier' ), $sums ) ) ); } } ); fclose( $out ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose } finally { $reader->close(); } $expected = (string) ( $manifest['integrity']['manifest_hash_of_payload_list'] ?? '' ); $mode = (string) ( $manifest['integrity']['payload_list'] ?? '' ); if ( 'body' === $mode ) { $actual = (string) $res['sha256']; } else { // Archives from earlier versions hash the sorted list (always small enough to sort in memory). $body = (string) file_get_contents( $sums ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents $actual = Checksums::payload_list_hash( Validator::parse_checksum_lines( $body ) ); unset( $body ); } if ( '' !== $expected && ! hash_equals( $expected, $actual ) ) { throw new State_Exception( esc_html( __( 'Manifest integrity hash does not match checksums.sha256 payload list.', '007aj-backup-restore-verifier' ) ) ); } $st['so'] = 0; } /** * Split checksum lines into shards. * * @param array $st State (by reference). * @param float $deadline Deadline. * @return bool Done. */ private function split( array &$st, float $deadline ): bool { $sizes = isset( $st['sz'] ) && is_array( $st['sz'] ) ? $st['sz'] : array_fill( 0, self::SHARDS, 0 ); for ( $i = 0; $i < self::SHARDS; $i++ ) { State_Files::truncate( $this->shard( 'sum', $i ), (int) $sizes[ $i ] ); } $off = (int) ( $st['so'] ?? 0 ); $lines = (int) ( $st['ln'] ?? 0 ); $done = false; while ( microtime( true ) < $deadline ) { $r = State_Files::read_rows_text( $this->sums_path(), $off, 5000 ); $bufs = array(); foreach ( $r['lines'] as $line ) { $line = trim( $line ); if ( '' === $line ) { continue; } if ( ! preg_match( '/^([a-f0-9]{64})\s+(.+)$/', $line, $m ) ) { throw new State_Exception( esc_html( __( 'Malformed checksum line.', '007aj-backup-restore-verifier' ) ) ); } $k = $this->shard_of( self::key( $m[2] ) ); $bufs[ $k ] = ( $bufs[ $k ] ?? '' ) . $m[1] . ' ' . $m[2] . "\n"; ++$lines; } foreach ( $bufs as $k => $b ) { State_Files::append( $this->shard( 'sum', (int) $k ), $b ); $sizes[ $k ] = (int) $sizes[ $k ] + strlen( $b ); } $off = $r['offset']; if ( $r['eof'] ) { $done = true; break; } } $st['so'] = $off; $st['sz'] = $sizes; $st['ln'] = $lines; if ( $done ) { if ( 0 === $lines ) { throw new State_Exception( esc_html( __( 'checksums.sha256 has no valid entries.', '007aj-backup-restore-verifier' ) ) ); } unset( $st['sz'] ); } return $done; } /** * Strict one-to-one join of archive members and checksum lines, shard by shard. * * Writes the approved list ok-XX.ndjson (rows {"e": entry, "h": sha256}). * * @param array $st State (by reference). * @param float $deadline Deadline. * @return bool Done. * @throws State_Exception On any mismatch. */ private function match( array &$st, float $deadline ): bool { while ( (int) $st['mh'] < self::SHARDS ) { $sh = (int) $st['mh']; $map = array(); $cd = State_Files::read_rows( $this->shard( 'cd', $sh ), 0, PHP_INT_MAX ); foreach ( $cd['rows'] as $e ) { $key = self::key( (string) $e['name'] ); if ( isset( $map[ $key ] ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: archive member path */ __( 'Duplicate archive path rejected: %s', '007aj-backup-restore-verifier' ), (string) $e['name'] ) ) ); } $map[ $key ] = $e; } unset( $cd ); $used = array(); $rows = ''; $off = 0; do { $r = State_Files::read_rows_text( $this->shard( 'sum', $sh ), $off, 4096 ); foreach ( $r['lines'] as $line ) { if ( '' === $line ) { continue; } $hash = substr( $line, 0, 64 ); $name = (string) substr( $line, 66 ); $key = self::key( $name ); if ( 'checksums.sha256' === $key ) { throw new State_Exception( esc_html( __( 'checksums.sha256 lists itself; the checksum list is not valid.', '007aj-backup-restore-verifier' ) ) ); } if ( isset( $used[ $key ] ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: archive member path */ __( 'Duplicate checksum entry rejected: %s', '007aj-backup-restore-verifier' ), $name ) ) ); } if ( ! isset( $map[ $key ] ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: archive member path */ __( 'Missing archive member for checksum: %s', '007aj-backup-restore-verifier' ), $name ) ) ); } $used[ $key ] = true; $rows .= State_Files::encode_row( array( 'e' => $map[ $key ], 'h' => $hash, ) ) . "\n"; } $off = (int) $r['offset']; } while ( ! $r['eof'] && ! empty( $r['lines'] ) ); foreach ( $map as $key => $e ) { if ( ! isset( $used[ $key ] ) && ! in_array( (string) $key, self::CONTROL, true ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: archive member path */ __( 'Archive member has no checksum entry: %s', '007aj-backup-restore-verifier' ), (string) $e['name'] ) ) ); } } State_Files::write_atomic( $this->shard( 'ok', $sh ), $rows ); $st['mm'] = (int) $st['mm'] + count( $used ); $st['mh'] = $sh + 1; unset( $map, $used, $rows ); if ( microtime( true ) >= $deadline ) { return (int) $st['mh'] >= self::SHARDS; } } if ( (int) $st['mm'] !== (int) ( $st['ln'] ?? -1 ) ) { throw new State_Exception( esc_html( __( 'The checksum list and the archive members do not match one to one.', '007aj-backup-restore-verifier' ) ) ); } return true; } /** * Re-hash every approved member, shard by shard. * * @param string $zip Archive. * @param array $st State (by reference). * @param float $deadline Deadline. * @return bool Done. * @throws State_Exception On a mismatch. */ private function verify( string $zip, array &$st, float $deadline ): bool { $reader = new Zip_Reader( $zip ); $st['ok'] = (int) ( $st['ok'] ?? 0 ); try { while ( (int) $st['sh'] < self::SHARDS ) { $sh = (int) $st['sh']; while ( true ) { $r = State_Files::read_rows( $this->shard( 'ok', $sh ), (int) $st['so'], 256 ); if ( empty( $r['rows'] ) ) { break; } foreach ( $r['rows'] as $k => $row ) { $entry = (array) $row['e']; $res = $reader->stream( $entry, static function ( string $b ): void { unset( $b ); }, isset( $st['rs'] ) && is_array( $st['rs'] ) ? $st['rs'] : array(), $deadline ); if ( empty( $res['done'] ) ) { $st['rs'] = $res['resume']; return false; } unset( $st['rs'] ); if ( ! hash_equals( (string) $row['h'], (string) $res['sha256'] ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: archive member path */ __( 'Checksum mismatch: %s', '007aj-backup-restore-verifier' ), (string) $entry['name'] ) ) ); } ++$st['ok']; $st['so'] = (int) $r['ends'][ $k ]; if ( microtime( true ) >= $deadline ) { return false; } } if ( $r['eof'] ) { break; } } $st['sh'] = $sh + 1; $st['so'] = 0; if ( microtime( true ) >= $deadline ) { return (int) $st['sh'] >= self::SHARDS; } } } finally { $reader->close(); } return true; } /** * Throw unless this check completed for $zip and the file is unchanged since. * * @param string $zip Archive. * @throws State_Exception When not validated or changed. */ public function assert_unchanged( string $zip ): void { $v = json_decode( (string) @file_get_contents( $this->dir . '/validated.json' ), true ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents, WordPress.PHP.NoSilencedErrors.Discouraged if ( ! is_array( $v ) ) { throw new State_Exception( esc_html( sprintf( /* translators: %s: file name */ __( 'Archive was not validated before restore: %s', '007aj-backup-restore-verifier' ), basename( $zip ) ) ) ); } clearstatcache( true, $zip ); if ( (int) @filesize( $zip ) !== (int) $v['size'] || (int) @filemtime( $zip ) !== (int) $v['mtime'] ) { // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged throw new State_Exception( esc_html( sprintf( /* translators: %s: file name */ __( 'Archive changed after validation; restore stopped: %s', '007aj-backup-restore-verifier' ), basename( $zip ) ) ) ); } } /** * Read approved rows ({"e": entry, "h": sha256}) of one shard. * * @param int $shard Shard index. * @param int $offset Byte offset. * @param int $max Max rows. * @return array{rows:list>,ends:list,offset:int,eof:bool} */ public function approved( int $shard, int $offset, int $max ): array { return State_Files::read_rows( $this->shard( 'ok', $shard ), $offset, $max ); } /** * Expected SHA-256 of an approved member, or null when the member was not approved. * * @param string $name Member name. */ public function expected( string $name ): ?string { $key = self::key( $name ); $sh = $this->shard_of( $key ); if ( $sh !== $this->ok_cache_i ) { $this->ok_cache = array(); $this->ok_cache_i = $sh; $r = State_Files::read_rows( $this->shard( 'ok', $sh ), 0, PHP_INT_MAX ); foreach ( $r['rows'] as $row ) { $this->ok_cache[ self::key( (string) ( $row['e']['name'] ?? '' ) ) ] = (string) $row['h']; } } return $this->ok_cache[ $key ] ?? null; } /** * Join key for a member path (backslashes count as separators, as on extract). * * @param string $name Name. */ private static function key( string $name ): string { return str_replace( '\\', '/', $name ); } /** * Remove the working shards (not the approved list). */ private function cleanup_shards(): void { for ( $i = 0; $i < self::SHARDS; $i++ ) { wp_delete_file( $this->shard( 'cd', $i ) ); wp_delete_file( $this->shard( 'sum', $i ) ); } // The approved list (ok-XX) stays: restore applies members from it only. } /** * Shard path. * * @param string $kind cd|sum|ok. * @param int $i Index. */ private function shard( string $kind, int $i ): string { return $this->dir . '/' . $kind . '-' . sprintf( '%02d', $i ) . ( 'sum' === $kind ? '.txt' : '.ndjson' ); } /** * Shard index for a name. * * @param string $name Name. */ private function shard_of( string $name ): int { return (int) ( hexdec( substr( md5( $name ), 0, 4 ) ) % self::SHARDS ); } }