<?php
/**
 * Verification of a run of sealed rows against the key, the recorded cuts and
 * the head.
 *
 * @package ActivityLog404
 */

namespace ActivityLog404\Chain;

defined( 'ABSPATH' ) || exit;

/**
 * The verifier's logic with the database taken out: it is handed rows (in id
 * order, in as many batches as the caller likes) and a resumable state, and
 * says what it found. Verifier owns the reading and the persistence; this
 * class owns every judgement, so each one is driven at its edges with
 * hand-built rows in tests/Unit/Chain/WalkTest.php.
 *
 * What it can and cannot see is stated rather than implied:
 *
 *  - a row edited in place: `edited` (its content digest no longer matches),
 *    unless the row is marked redacted -- a privacy erasure blanks personal
 *    data on purpose, so a redacted row's content is not compared, only its
 *    place in the chain;
 *  - a row whose seal columns were rewritten, or one forged without the key:
 *    `forged`;
 *  - rows deleted, inserted or reordered: `gap`, at the first row after the
 *    break, unless a recorded cut bridges exactly that gap;
 *  - the newest rows deleted: `tail`, because the signed head names a row
 *    that is no longer there (unless a recorded cut removed it);
 *  - a row inserted without the chain columns: `unsealed`. Counted and
 *    shown, but a warning rather than a verdict: a database error during an
 *    insert makes the plugin store the event unsealed rather than lose it.
 *
 * It cannot see an edit to a redacted row (that flag is not itself sealed:
 * docs/tamper-evident-chain.md names it), an attacker who holds the key, or
 * anything before the first sealed row.
 */
final class Walk {

	public const FORGED   = 'forged';
	public const EDITED   = 'edited';
	public const GAP      = 'gap';
	public const TAIL     = 'tail';
	public const UNSEALED = 'unsealed';
	public const HEAD     = 'head';
	public const LEDGER   = 'ledger';

	/** Findings kept in full; the counts keep counting past it. */
	public const FINDINGS_LIMIT = 100;

	/**
	 * The state a walk starts from.
	 *
	 * @param string $key   Signing key.
	 * @param int    $epoch The chain's floor (Seal::genesis()).
	 * @return array<string, mixed>
	 */
	public static function start( string $key, int $epoch = 0 ): array {
		return array(
			'expected'  => Seal::genesis( $key, $epoch ),
			'last_id'   => 0,
			'rows'      => 0,
			'sealed'    => 0,
			'redacted'  => 0,
			'unsealed'  => 0,
			'imported'  => 0,
			'head_seen' => false,
			'counts'    => array(),
			'findings'  => array(),
		);
	}

	/**
	 * Check a batch of rows, in id order, after the state's last row.
	 *
	 * @param string                             $key        Signing key.
	 * @param array<string, mixed>               $state      A start() or earlier step() state.
	 * @param array<int, array<string, mixed>>   $rows       Rows as the database returns them.
	 * @param array<int, array{from: string, to: string}> $cuts Recorded cuts.
	 * @param array{id: int, hash: string}|null  $head       The verified head, when there is one.
	 * @param bool                               $four_bytes Whether the table stores four-byte characters.
	 * @return array<string, mixed> The new state.
	 */
	public static function step( string $key, array $state, array $rows, array $cuts, ?array $head, bool $four_bytes = true ): array {
		foreach ( $rows as $row ) {
			$id               = (int) ( $row['id'] ?? 0 );
			$state['last_id'] = max( (int) $state['last_id'], $id );
			++$state['rows'];

			if ( isset( $row['import_source'] ) && '' !== (string) $row['import_source'] ) {
				// Another plugin's claim, brought in by the importer: never
				// sealed, and said so rather than counted as missing.
				++$state['imported'];
				continue;
			}

			$hash = $row['chain_hash'] ?? null;
			if ( null === $hash ) {
				++$state['unsealed'];
				$state = self::note( $state, self::UNSEALED, $id );
				continue;
			}

			++$state['sealed'];

			$prev    = $row['chain_prev'] ?? null;
			$content = $row['chain_content'] ?? null;

			if ( ! Seal::is_digest( $hash ) || ! Seal::is_digest( $prev ) || ! Seal::is_digest( $content )
				|| ! Seal::same( Seal::link( $key, $prev, $content ), $hash ) ) {
				$state = self::note( $state, self::FORGED, $id );
				continue;
			}

			if ( ! empty( $row['chain_redacted'] ) ) {
				++$state['redacted'];
			} elseif ( ! Seal::same( Seal::content( $key, Seal::normalise( $row, $four_bytes ) ), $content ) ) {
				$state = self::note( $state, self::EDITED, $id );
			}

			if ( $prev !== $state['expected'] && ! isset( Cuts::reachable( $cuts, (string) $state['expected'] )[ $prev ] ) ) {
				$state = self::note( $state, self::GAP, $id );
			}

			if ( null !== $head && Seal::same( $head['hash'], $hash ) ) {
				$state['head_seen'] = true;
			}

			$state['expected'] = $hash;
		}

		return $state;
	}

	/**
	 * Close a walk that has seen every row: the checks that need the whole
	 * run, and the verdict.
	 *
	 * @param array<string, mixed>                       $state A step() state.
	 * @param array{id: int, hash: string}|null           $head  The verified head, or null when absent or unsigned.
	 * @param array<int, array{from: string, to: string}> $cuts  Recorded cuts.
	 * @return array<string, mixed> The state with `findings` completed.
	 */
	public static function finish( array $state, ?array $head, array $cuts ): array {
		if ( null === $head ) {
			// A chain that has sealed rows has written a head after each; one
			// missing is the first thing someone shortening the log removes.
			if ( (int) $state['sealed'] > 0 ) {
				$state = self::note( $state, self::HEAD, 0 );
			}

			return $state;
		}

		if ( $state['head_seen'] ) {
			return $state;
		}

		foreach ( $cuts as $cut ) {
			if ( $cut['to'] === $head['hash'] ) {
				// The plugin's own retention removed the newest row.
				return $state;
			}
		}

		return self::note( $state, self::TAIL, (int) $head['id'] );
	}

	/**
	 * The verdict for a finished state.
	 *
	 * @param array<string, mixed> $state A finish() state.
	 * @return string `intact`, `warning` (unsealed rows only), `tampered`, or `empty` (nothing sealed yet).
	 */
	public static function verdict( array $state ): string {
		$counts = (array) $state['counts'];

		foreach ( array( self::FORGED, self::EDITED, self::GAP, self::TAIL, self::HEAD, self::LEDGER ) as $kind ) {
			if ( ! empty( $counts[ $kind ] ) ) {
				return 'tampered';
			}
		}

		if ( ! empty( $counts[ self::UNSEALED ] ) ) {
			return 'warning';
		}

		return (int) $state['sealed'] > 0 ? 'intact' : 'empty';
	}

	/**
	 * Record one finding: always counted, kept in full up to the limit.
	 *
	 * @param array<string, mixed> $state State.
	 * @param string               $kind  A finding kind.
	 * @param int                  $id    The row it concerns (0: none).
	 * @return array<string, mixed>
	 */
	public static function note( array $state, string $kind, int $id ): array {
		$state['counts'][ $kind ] = (int) ( $state['counts'][ $kind ] ?? 0 ) + 1;

		if ( count( $state['findings'] ) < self::FINDINGS_LIMIT ) {
			$state['findings'][] = array(
				'kind' => $kind,
				'id'   => $id,
			);
		}

		return $state;
	}
}