From 313f13955ad9c72895b0914ac828c61b3e469715 Mon Sep 17 00:00:00 2001 From: Agando Date: Fri, 23 Oct 2026 19:29:31 +0200 Subject: feat(chat): token-scoped chat endpoints, contract, host CLI, old POST retired (v4.6.71 phase B) - api/chat/{lib,post,poll}.php: thread = sha256(token)[0:16]; flock read-modify-write; tmp+rename; ms epoch cursor; per-thread + per-IP windows with retry_after_ms; 401/413/507/405 carry a machine code, only rate_limited is retryable - _docs/chat-contract.md: frozen shapes, incl. why the cursor is ms and not ts - scripts/chat.py: list/show/reply, UTC, locked, atomic replace - api/debug/agent-replies.php POST -> 410 Gone with pointers (one write path) Measured: 401 no-token, 201+id, poll 1 msg, poll>since 1 new, data/chat 403, 4001 chars 413 (codepoints), 429 with Retry-After 576, round trip via chat.py. --- api/chat/lib.php | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ api/chat/poll.php | 27 ++++++++++ api/chat/post.php | 57 ++++++++++++++++++++ 3 files changed, 241 insertions(+) create mode 100644 api/chat/lib.php create mode 100644 api/chat/poll.php create mode 100644 api/chat/post.php (limited to 'api/chat') diff --git a/api/chat/lib.php b/api/chat/lib.php new file mode 100644 index 0000000..6a0f923 --- /dev/null +++ b/api/chat/lib.php @@ -0,0 +1,157 @@ + Hermes channel. +// One file per thread: data/chat/.json, written atomically (tmp + rename). +declare(strict_types=1); + +require_once __DIR__ . '/../debug/config.php'; // error_response() / json_response() / load_json() + +define('CHAT_DIR', __DIR__ . '/../../data/chat'); +define('CHAT_MAX_MESSAGES', 200); +define('CHAT_MAX_TEXT', 4000); +define('CHAT_RATE_MAX', 20); // messages per thread … +define('CHAT_RATE_WINDOW', 600); // … per 10 minutes +define('CHAT_IP_MAX', 40); // a token is mintable, an IP is not +define('CHAT_MAX_THREADS', 500); // hard ceiling on disk growth + +if (!is_dir(CHAT_DIR)) { + @mkdir(CHAT_DIR, 0775, true); + @chgrp(CHAT_DIR, 'www-data'); +} + +// Machine-readable failure: the sender must be able to tell "try again" from +// "your text is wrong" without parsing prose. 401/413/507 are permanent for that +// payload; 429 is the only one worth retrying. +function chat_error(string $msg, int $status, string $code, array $extra = []): void { + if (!headers_sent()) { + http_response_code($status); + header('Content-Type: application/json'); + } + $body = array_merge(['success' => false, 'code' => $code, 'error' => $msg], $extra); + echo json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); + exit; +} + +function chat_token(): string { + $t = $_SERVER['HTTP_X_CHAT_TOKEN'] ?? ''; + if (!preg_match('/^[a-f0-9]{64}$/', $t)) { + chat_error('missing or malformed X-Chat-Token', 401, 'bad_token'); + } + return $t; +} + +function chat_thread(string $token): string { + return substr(hash('sha256', $token), 0, 16); +} + +function chat_path(string $thread): string { + if (!preg_match('/^[a-f0-9]{16}$/', $thread)) { + error_response('invalid thread', 400); + } + return CHAT_DIR . '/' . $thread . '.json'; +} + +function chat_read(string $thread): array { + $all = load_json(chat_path($thread)); + return is_array($all) ? $all : []; +} + +// Atomic replace: a reader sees the old file or the new one, never a truncated one. +function chat_write(string $thread, array $messages): bool { + $path = chat_path($thread); + $tmp = $path . '.tmp-' . bin2hex(random_bytes(4)); + $json = json_encode(array_values($messages), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); + if ($json === false) return false; + $fp = fopen($tmp, 'wb'); + if (!$fp) return false; + $ok = (fwrite($fp, $json) === strlen($json)); + fflush($fp); + fclose($fp); + if (!$ok) { @unlink($tmp); return false; } + @chmod($tmp, 0664); + return @rename($tmp, $path); +} + +// Append under a real lock: read-modify-write on one handle so two concurrent +// POSTs cannot each write back a stale copy (lost update). +function chat_append(string $thread, string $author, string $text): array { + $lock = fopen(CHAT_DIR . '/.lock-' . $thread, 'c'); + // FPM creates as www-data 0644; the host-side CLI (darkbot, group www-data) must be + // able to open the same lock, so group gets write too. + if ($lock) @chmod(CHAT_DIR . '/.lock-' . $thread, 0664); + if (!$lock || !flock($lock, LOCK_EX)) { + if ($lock) fclose($lock); + error_response('failed to lock thread', 500); + } + $msg = []; + try { + $messages = chat_read($thread); + $msg = [ + 'id' => 'MSG-' . gmdate('Ymd-His') . '-' . bin2hex(random_bytes(3)), + 'ts' => gmdate('c'), // UTC, always — never a local offset + 'epoch' => (int)round(microtime(true) * 1000), // ms — second precision drops same-second messages + 'author' => $author, + 'text' => $text, + ]; + $messages[] = $msg; + $cutoff = (time() - 30 * 86400) * 1000; + $messages = array_values(array_filter( + $messages, + fn($m) => (int)($m['epoch'] ?? (strtotime((string)($m['ts'] ?? '')) * 1000)) >= $cutoff + )); + if (count($messages) > CHAT_MAX_MESSAGES) { + $messages = array_slice($messages, -CHAT_MAX_MESSAGES); + } + if (!chat_write($thread, $messages)) { + error_response('failed to persist message', 500); + } + } finally { + flock($lock, LOCK_UN); + fclose($lock); + } + return $msg; +} + +// Two windows: per thread (the conversation) and per IP (a token is mintable, so the +// thread window alone is bypassable by rotating tokens). Returns the reason and the +// wait, so the caller can send Retry-After instead of an unparseable sentence. +function chat_rate_check(string $thread): array { + $ip = $_SERVER['REMOTE_ADDR'] ?? '0.0.0.0'; + $t = chat_window_check('t-' . $thread, CHAT_RATE_MAX); + if (!$t['ok']) return ['ok' => false, 'scope' => 'thread'] + $t; + $i = chat_window_check('i-' . hash('sha256', $ip), CHAT_IP_MAX); + if (!$i['ok']) return ['ok' => false, 'scope' => 'ip'] + $i; + return ['ok' => true, 'scope' => '', 'retry_after_ms' => 0]; +} + +// Sliding window. The wait is the time until the oldest hit leaves the window, +// which is the shortest time after which a retry can succeed. +function chat_window_check(string $key, int $max): array { + $file = CHAT_DIR . '/.rate-' . $key . '.json'; + $fp = fopen($file, 'c+'); + if (!$fp) return ['ok' => true, 'retry_after_ms' => 0]; // never drop a message over a stats file + if (!flock($fp, LOCK_EX)) { fclose($fp); return ['ok' => true, 'retry_after_ms' => 0]; } + $raw = stream_get_contents($fp); + $hits = json_decode($raw ?: '[]', true); + if (!is_array($hits)) $hits = []; + $now = time(); + $hits = array_values(array_filter($hits, fn($t) => (int)$t > $now - CHAT_RATE_WINDOW)); + sort($hits); + $ok = count($hits) < $max; + if ($ok) $hits[] = $now; + ftruncate($fp, 0); + rewind($fp); + fwrite($fp, json_encode($hits)); + fflush($fp); + flock($fp, LOCK_UN); + fclose($fp); + @chmod($file, 0664); + if ($ok) return ['ok' => true, 'retry_after_ms' => 0]; + $oldest = (int)($hits[0] ?? $now); + $wait = max(0, ($oldest + CHAT_RATE_WINDOW) - $now) * 1000; + return ['ok' => false, 'retry_after_ms' => $wait]; +} + +function chat_thread_count(): int { + $g = glob(CHAT_DIR . '/*.json'); + return $g ? count($g) : 0; +} diff --git a/api/chat/poll.php b/api/chat/poll.php new file mode 100644 index 0000000..601beca --- /dev/null +++ b/api/chat/poll.php @@ -0,0 +1,27 @@ + 0 + ? array_values(array_filter($all, fn($m) => (int)($m['epoch'] ?? 0) > $since)) + : $all; +$lastAll = $all ? end($all) : null; + +json_response([ + 'success' => true, + 'thread' => $thread, + 'messages' => array_slice($messages, -50), + // `awaiting` replaces `unread`: the server keeps no read state, so an unread + // counter could never clear. Who spoke last is knowable. + 'awaiting' => (bool)($lastAll && ($lastAll['author'] ?? '') !== 'hermes'), + 'cursor' => $lastAll ? (int)($lastAll['epoch'] ?? 0) : 0, +]); diff --git a/api/chat/post.php b/api/chat/post.php new file mode 100644 index 0000000..07cee65 --- /dev/null +++ b/api/chat/post.php @@ -0,0 +1,57 @@ + 32 * 1024) chat_error('payload too large (max 32KB)', 413, 'too_large'); + +$payload = json_decode($raw, true); +if (!is_array($payload)) chat_error('invalid JSON', 400, 'bad_json'); + +$text = trim((string)($payload['text'] ?? '')); +if ($text === '') chat_error('text is required', 400, 'text_required'); +// Reject rather than truncate: a shortened question earns a wrongly scoped answer. +// mb_strlen = codepoints, not bytes: 4000 emoji are 4000 chars and 16 KB. +if (mb_strlen($text) > CHAT_MAX_TEXT) { + chat_error('text too long (max ' . CHAT_MAX_TEXT . ' chars)', 413, 'too_long', + ['limit' => CHAT_MAX_TEXT, 'unit' => 'codepoints', 'actual' => mb_strlen($text)]); +} + +$kind = (string)($payload['kind'] ?? 'operator'); +if (!in_array($kind, ['operator', 'agent'], true)) $kind = 'operator'; + +if (!is_file(chat_path($thread)) && chat_thread_count() >= CHAT_MAX_THREADS) { + chat_error('thread limit reached', 507, 'thread_limit', ['limit' => CHAT_MAX_THREADS]); +} +$rate = chat_rate_check($thread); +if (!$rate['ok']) { + // The only retryable failure. Everything else (401/413/507) is permanent for this payload. + header('Retry-After: ' . (int)ceil($rate['retry_after_ms'] / 1000)); + chat_error( + 'rate limit: ' . ($rate['scope'] === 'thread' ? CHAT_RATE_MAX . ' per thread' : CHAT_IP_MAX . ' per IP') . ' per 10 min', + 429, 'rate_limited', + ['scope' => $rate['scope'], + 'retry_after_ms' => $rate['retry_after_ms'], + 'limit' => $rate['scope'] === 'thread' ? CHAT_RATE_MAX : CHAT_IP_MAX, + 'window_s' => CHAT_RATE_WINDOW] + ); +} + +$msg = chat_append($thread, $kind, $text); +json_response([ + 'success' => true, + 'id' => $msg['id'], + 'ts' => $msg['ts'], + 'epoch' => $msg['epoch'], + 'thread' => $thread, +], 201); -- cgit v1.2.3