From 5f764cb77796b295be97bc480f1878821b5d5257 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 17:48:10 +0000 Subject: [PATCH] Keep the last good hosted verification list on disk for chat names When the hosted verified list is stale or unreachable, the chat relay now uses the last good list (in memory, or loaded from hosted_verified_cache.json at boot) to attach the author's Discord name, instead of sending plain text. The cache is display only: get(), the verified collection and every access, admin and authority check still require a fresh hosted list. A missing or invalid cache file is ignored and never blocks startup; save failures are logged, never thrown. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016WTP2UbZ584w2CXPdx7Vin --- src/Civ13/GameServer.php | 14 +++-- src/Civ13/Verifier.php | 63 ++++++++++++++++++++++ tests/local/admin-verification-refresh.php | 31 +++++++++++ tests/local/chat-moderation.php | 14 +++++ 4 files changed, 117 insertions(+), 5 deletions(-) diff --git a/src/Civ13/GameServer.php b/src/Civ13/GameServer.php index 5cd75261..ec112658 100644 --- a/src/Civ13/GameServer.php +++ b/src/Civ13/GameServer.php @@ -671,18 +671,22 @@ private function __gameChatRelay(Channel|Thread|string $channel, array $array, ? $this->civ13->moderator->moderate($this, $array['ckey'], $array['message'], $this->civ13->ic_badwords, $this->civ13->ic_badwords_warnings, 'ic_badwords_warnings.json'); } } + $ckey = Civ13::sanitizeInput($array['ckey']); try { - $item = $this->civ13->verifier->get('ss13', Civ13::sanitizeInput($array['ckey'])); + $item = $this->civ13->verifier->get('ss13', $ckey); $this->relayIdentityUnavailable = false; } catch (VerifierException) { - // The hosted list is not a current identity proof. Keep chat visible - // as plain text without using retained or stale verification data. + // The live hosted list is stale or unreachable. Chat names are display only, + // so use the last good list (memory or disk); with no cache, send plain text. // Warn once per outage instead of once per chat line. + $cached = $this->civ13->verifier->hasDisplayCache(); + $item = $cached ? $this->civ13->verifier->cachedDisplayItem('ss13', $ckey) : null; if (! $this->relayIdentityUnavailable) { $this->relayIdentityUnavailable = true; - $this->logger->warning('Chat relay identity lookup unavailable; sending unverified display text until hosted verification refreshes'); + $this->logger->warning($cached + ? 'Hosted verification unavailable; chat relay is using the cached verified list' + : 'Chat relay identity lookup unavailable and no cached list; sending unverified display text until hosted verification refreshes'); } - $item = null; } if (! $item) { return $this->civ13->sendMessage($channel, $array['message'], 'relay.txt', true); diff --git a/src/Civ13/Verifier.php b/src/Civ13/Verifier.php index 704ec7f8..2b823bdc 100644 --- a/src/Civ13/Verifier.php +++ b/src/Civ13/Verifier.php @@ -47,6 +47,11 @@ class Verifier /** Backoff after a failed hosted refresh, so one failed fetch (often at boot) does not leave the list unavailable until the next period. */ public const HOSTED_RETRY_SECONDS = [30, 60, 120, 300]; private int $hostedRetryAttempt = 0; + /** Last successful hosted list, kept on disk so chat names survive an unreachable host or a failed fetch at boot. */ + public const DISPLAY_CACHE_FILE = 'hosted_verified_cache.json'; + /** Display-only copy of the last good hosted list. Never consulted for access, admin or authority decisions. */ + private ?CollectionInterface $displayCache = null; + private ?string $displayCacheHash = null; private const READ_ONLY_MESSAGE = 'Desktop uses the hosted Civilizationbot verification source. Complete verification with the primary bot.'; public CollectionInterface $verified; // This probably needs a default value for Collection, maybe make it a Repository instead? public CollectionInterface $pending; @@ -78,6 +83,7 @@ public function __construct(Civ13 &$civ13, array $options = []) $this->hosted = new HostedVerificationSnapshot(); $this->provisional = new Collection([], 'ss13'); $this->verified = new Collection([], 'discord'); + $this->loadDisplayCache(); $this->afterConstruct(); return; } @@ -1368,6 +1374,7 @@ public function refreshHosted(): PromiseInterface : HostedVerificationSource::fetch($this->civ13->browser))->then(function (array $status): array { $this->verified = new Collection($this->hosted->records(), 'discord'); $this->civ13->verifier_online = $status['available']; + if ($status['available'] === true) { $this->saveDisplayCache($this->hosted->records()); } // Existing successful refresh only. Coalesced callers must not duplicate the notification. if ($status['available'] === true && ($status['coalesced'] ?? true) === false) { try { $this->civ13->hostedVerificationRefreshed($this); } @@ -1389,6 +1396,62 @@ public function refreshHosted(): PromiseInterface }); } + /** + * Identity lookup for display only (chat relay names, mentions). Uses the live list when it is + * fresh, otherwise the last good hosted list kept in memory and on disk. Never use it to grant access. + */ + public function getDisplayItem(string $discrim, $key): ?array + { + try { return $this->get($discrim, $key); } + catch (VerifierException $e) { + if ($this->displayCache === null) { throw $e; } + return $this->cachedDisplayItem($discrim, $key); + } + } + + /** Reads only the display cache (no live lookup); null when there is no cache or no match. */ + public function cachedDisplayItem(string $discrim, $key): ?array + { + $item = $this->displayCache?->get($discrim, $key); + return is_array($item) ? $item : null; + } + + /** Whether a display-only cached list is available while the live hosted list is not. */ + public function hasDisplayCache(): bool + { + return $this->displayCache !== null; + } + + /** Loads the last good hosted list from disk; a missing or invalid file leaves no cache and never blocks startup. */ + private function loadDisplayCache(): void + { + try { + $path = $this->civ13->filecache_path ?? null; + if (!is_string($path) || !is_file($path.self::DISPLAY_CACHE_FILE)) { return; } + $saved = $this->civ13->VarLoad(self::DISPLAY_CACHE_FILE); + if (!is_array($saved)) { return; } + $records = HostedVerificationSource::validate(json_encode(array_values($saved), JSON_THROW_ON_ERROR)); + $this->displayCache = new Collection($records, 'discord'); + $this->displayCacheHash = hash('sha256', json_encode($records, JSON_THROW_ON_ERROR)); + } catch (\Throwable) { + $this->displayCache = null; + try { $this->logger->warning('Cached hosted verification list could not be loaded; waiting for the hosted list'); } catch (\Throwable) {} + } + } + + /** Keeps the last good hosted list in memory and writes it to disk when it changed. Failures are logged, never thrown. */ + private function saveDisplayCache(array $records): void + { + try { + $this->displayCache = new Collection($records, 'discord'); + $hash = hash('sha256', json_encode($records, JSON_THROW_ON_ERROR)); + if ($hash === $this->displayCacheHash) { return; } + if ($this->civ13->VarSave(self::DISPLAY_CACHE_FILE, $records)) { $this->displayCacheHash = $hash; } + } catch (\Throwable) { + try { $this->logger->warning('Hosted verification cache could not be saved'); } catch (\Throwable) {} + } + } + /** Schedules one bounded retry after a failed hosted refresh; never throws into the loop. */ private function scheduleHostedRetry(): void { diff --git a/tests/local/admin-verification-refresh.php b/tests/local/admin-verification-refresh.php index 343d7d10..dc526010 100644 --- a/tests/local/admin-verification-refresh.php +++ b/tests/local/admin-verification-refresh.php @@ -73,11 +73,14 @@ public function warning(string|\Stringable $message,array $context=[]): void { $owner=(new \ReflectionClass(RefreshObserver::class))->newInstanceWithoutConstructor(); $owner->browser=(new \ReflectionClass(\React\Http\Browser::class))->newInstanceWithoutConstructor(); $owner->loop=new \React\EventLoop\StreamSelectLoop(); // Failed refreshes schedule a retry timer; this loop never runs. + $owner->filecache_path=$cacheDir=sys_get_temp_dir().DIRECTORY_SEPARATOR.'civbot-hosted-cache-'.bin2hex(random_bytes(6)).DIRECTORY_SEPARATOR; + mkdir($cacheDir,0700,true); $verifier=(new \ReflectionClass(Verifier::class))->newInstanceWithoutConstructor(); $verifier->civ13=$owner; $owner->verifier=$verifier; (new \ReflectionProperty($verifier,'verify_url'))->setValue($verifier,'http://civ13.com:55555/verified'); (new \ReflectionProperty($verifier,'readOnly'))->setValue($verifier,true); $verifier->logger=$logger=new RefreshLogger('offline-verifier'); + $owner->logger=$logger; // VarSave for the display cache logs through the owner. $verifier->verified=new Collection([], 'discord'); $snapshot=new HostedVerificationSnapshot(static fn()=>$f->now); (new \ReflectionProperty(Verifier::class,'hosted'))->setValue($verifier,$snapshot); @@ -167,6 +170,34 @@ public function warning(string|\Stringable $message,array $context=[]): void { refreshCheck($retry->timers['hosted_retry']->getInterval()===30.0,'Backoff was not reset after recovery'); $owner->loop->cancelTimer($retry->timers['hosted_retry']); + // The last good list is kept on disk and serves display-only lookups while the live list is unavailable. + $cacheFile=$cacheDir.Verifier::DISPLAY_CACHE_FILE; + $f->now+=20;$f->reply=['http_status'=>200,'json'=>json_encode($records,JSON_THROW_ON_ERROR)]; + refreshResult($verifier->refreshHosted()); + refreshCheck(is_file($cacheFile) && json_decode((string)file_get_contents($cacheFile),true)===$records,'Successful refresh did not save the display cache'); + $mtime=filemtime($cacheFile);clearstatcache(); + $f->now+=20;$f->reply=['http_status'=>503,'json'=>'[]'];refreshResult($verifier->refreshHosted()); + $unavailable=false;try{$verifier->get('ss13','fakebeta');}catch(\Civ13\Exceptions\VerifierException){$unavailable=true;} + refreshCheck($unavailable,'Stale list still answered authority lookups'); + refreshCheck(($verifier->getDisplayItem('ss13','fakebeta')['discord']??null)==='990000000000000001','Display lookup did not fall back to the retained list'); + // A fresh process (boot with the host unreachable) loads the disk cache for display only. + $boot=(new \ReflectionClass(Verifier::class))->newInstanceWithoutConstructor(); + $boot->civ13=$owner;$boot->logger=$logger;$boot->verified=new Collection([], 'discord'); + (new \ReflectionProperty($boot,'readOnly'))->setValue($boot,true); + (new \ReflectionProperty(Verifier::class,'hosted'))->setValue($boot,new HostedVerificationSnapshot(static fn()=>$f->now)); + (new \ReflectionMethod(Verifier::class,'loadDisplayCache'))->invoke($boot); + refreshCheck($boot->hasDisplayCache() && ($boot->getDisplayItem('ss13','fakebeta')['discord']??null)==='990000000000000001' + && iterator_to_array($boot->verified,false)===[],'Boot cache missing, or leaked into the authoritative list'); + file_put_contents($cacheFile,'{"not":"records"'); + $bad=(new \ReflectionClass(Verifier::class))->newInstanceWithoutConstructor(); + $bad->civ13=$owner;$bad->logger=$logger;$bad->verified=new Collection([], 'discord'); + (new \ReflectionProperty($bad,'readOnly'))->setValue($bad,true); + (new \ReflectionProperty(Verifier::class,'hosted'))->setValue($bad,new HostedVerificationSnapshot(static fn()=>$f->now)); + (new \ReflectionMethod(Verifier::class,'loadDisplayCache'))->invoke($bad); + $threw=false;try{$bad->getDisplayItem('ss13','fakebeta');}catch(\Civ13\Exceptions\VerifierException){$threw=true;} + refreshCheck(!$bad->hasDisplayCache() && $threw,'Corrupt cache file was used or broke startup'); + @unlink($cacheFile);@rmdir($cacheDir); + // Real owner bridge is inert when default-disabled/unattached and does not autoload the feature. $plain=(new \ReflectionClass(Civ13::class))->newInstanceWithoutConstructor(); $plain->verifier=$verifier; $autoloads=0; diff --git a/tests/local/chat-moderation.php b/tests/local/chat-moderation.php index 7a5722e7..47e3da4c 100644 --- a/tests/local/chat-moderation.php +++ b/tests/local/chat-moderation.php @@ -22,6 +22,7 @@ set_error_handler(static function (int $severity, string $message, string $file, int $line): bool { throw new ErrorException($message, 0, $severity, $file, $line); }, E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED); function check(bool $ok, string $why): void { if (!$ok) { throw new RuntimeException($why); } } function inert(string $class): object { return (new ReflectionClass($class))->newInstanceWithoutConstructor(); } +final class IdentityEmbedSentinel extends RuntimeException {} final class ModerationGuilds { public function get(string $key, mixed $value): mixed { return null; } } final class ModerationDiscord extends \Discord\Discord { public function __construct() {} @@ -36,7 +37,10 @@ public function get(string $discrim, $key): mixed { if ($this->unavailable) { th } final class ModerationBot extends Civ13 { public array $sent = []; + public int $embeds = 0; public array $banned = []; + /** Counts the identity-embed path; the inert Discord client cannot build a real Embed. */ + public function createEmbed(?bool $footer = true, int $color = 0xE1452D): \Discord\Parts\Embed\Embed { ++$this->embeds; throw new IdentityEmbedSentinel(); } public array $players = []; public function sendMessage(Channel|Thread|string $channel, MessageBuilder|string $content, string $file_name = 'message.txt', bool $prevent_mentions = false): PromiseInterface { $this->sent[] = $content; return resolve(null); } public function ban(array $array, ?string $admin = null, string|int|null $server = null, bool $permanent = false): string { $this->banned[] = $array; return 'banned'; } @@ -121,6 +125,16 @@ public function react($emoticon): PromiseInterface { $this->reactions[] = $emoti $bot->verifier->unavailable = true; $say('speaker', 'hello five', true); check($identityWarnings() === 2, 'A new outage after recovery did not warn again'); + check(count($bot->sent) === $sentBefore + 5, 'Outage without a cache did not send plain text'); + // With a cached list the relay keeps the author's name instead of plain text. + $bot->verifier->unavailable = false; + $say('speaker', 'hello six', true); + (new ReflectionProperty(\Civ13\Verifier::class, 'displayCache'))->setValue($bot->verifier, new Collection([['ss13' => 'speaker', 'discord' => '990000000000000001']], 'discord')); + $bot->verifier->unavailable = true; + $plainBefore = count($bot->sent); + try { $relay->invoke($server, inert(ModerationChannel::class), ['ckey' => 'speaker', 'message' => 'hello seven', 'server' => 'fixture'], true, true); } catch (IdentityEmbedSentinel) {} + check(count($bot->sent) === $plainBefore && $bot->embeds === 1, 'Cached identity was not used for the chat relay'); + check(count(array_filter($log->getRecords(), static fn ($r) => str_contains((string) $r['message'], 'using the cached verified list'))) === 1, 'Cached outage was not logged once'); $bot->verifier->unavailable = false; // Without a file the counters still update in memory (callers outside the relay).