""" WebSocket protocol for nekohash imageboard engine (awoo.cf). Reverse-engineered from client bundles (app-AGKBSCUS.js, chunk-NRU3NIKF.js, chunk-XX362ZFD.js, chunk-XMMHRB6S.js, chunk-JTTGKNWN.js, chunk-PVG4O4YS.js) and network captures on November 16, 2026. """ import json import struct from enum import IntEnum from dataclasses import dataclass from typing import Any, Optional, Union class MessageType(IntEnum): """ WebSocket message types (client-to-server and server-to-client). Text messages: <2-digit-type> Binary messages: <8-byte float64 post_id><1-byte type> """ # Post state & Keystroke streaming ERROR = 0 INSERT_POST = 1 APPEND = 2 # Binary: [post_id (8B), utf-8 text, 0x02] BACKSPACE = 3 # Binary: [post_id (8B), 0x03] SPLICE = 4 # Binary: [post_id (8B), start (2B), len (2B), utf-8 text, 0x04] CLOSE_POST = 5 INSERT_IMAGE = 6 SPOILER_IMAGE = 7 APPLY_MODERATION = 8 REMOVE_IMAGE = 9 REPLACE_IMAGE = 10 # Generative AI Streaming: Claude / LLM CLAUDE_APPEND = 11 # Binary: Claude streamed text CLAUDE_DONE = 12 # Binary CLAUDE_ERROR = 13 # Binary # Generative AI: Imagen (Text-to-Image) IMAGEN_APPEND = 14 # Binary IMAGEN_DONE = 15 # Binary IMAGEN_ERROR = 16 # Binary # Generative AI: Videogen VIDEOGEN_APPEND = 17 # Binary VIDEOGEN_DONE = 18 # Binary VIDEOGEN_ERROR = 19 # Binary # Generative AI: Editgen (Image Editing) EDITGEN_APPEND = 20 # Binary EDITGEN_DONE = 21 # Binary EDITGEN_ERROR = 22 # Binary # Generative AI: Imgtovid (Image-to-Video) IMGTOVID_APPEND = 23 # Binary IMGTOVID_DONE = 24 # Binary IMGTOVID_ERROR = 25 # Binary # Generative AI: Img2veo (Google Veo Video) IMG2VEO_APPEND = 26 # Binary IMG2VEO_DONE = 27 # Binary IMG2VEO_ERROR = 28 # Binary # Generative AI: Grok Video (xAI Grok) GROKVID_APPEND = 29 # Binary GROKVID_DONE = 30 # Binary GROKVID_ERROR = 31 # Binary GROKVID_APPEND_ALT = 32 # Binary GROKVID_DONE_ALT = 33 # Binary GROKVID_ERROR_ALT = 34 # Binary # Embeds TIKTOK_PENDING = 36 # TikTok embed state # Session / Crypto / Control FP_TOKEN_RECEIVE = 43 # Binary SYNCHRONISE = 44 # Board / Thread state sync POST_PASSWORD = 45 # Reclaim draft with password RECEIVE_ID = 46 # Allocation post ID assignment BATCH_EVENTS = 47 # Batched streaming events NOOP_PING = 48 # Periodic keepalive ping PRESENCE = 49 # Active site/thread/NekoTV viewer counts SERVER_TIME = 50 # Millisecond server timestamp REDIRECT = 51 # URL redirect command NOTIFICATION = 52 # Browser notification trigger CAPTCHA_TRIGGER = 53 # Trigger captcha challenge NEKO_TV_SYNC = 54 # NekoTV shared watch-party sync BOARD_CONFIG = 55 # Dynamic board feature flags (NSFW, games, webRTC) SESSION_CONFIG = 56 # Captcha session and token updates SESSION_KEY = 57 # 16-byte session key rotation (Binary) SYNC_COUNT = 58 # Synced client counter POLL_UPDATE = 59 # In-thread poll definition POLL_VOTE = 60 # Poll vote cast/counts THREAD_CREATED = 62 # New thread created broadcast WEBRTC_SIGNAL = 63 # WebRTC peer discovery, SDP, and ICE signaling # Generative AI: Venice Video (Venice AI) VENICEVID_APPEND = 64 # Binary VENICEVID_DONE = 65 # Binary VENICEVID_ERROR = 66 # Binary # Generative AI: Atlas Video (ByteDance Atlas) ATLASVID_APPEND = 67 # Binary ATLASVID_DONE = 68 # Binary ATLASVID_ERROR = 69 # Binary # Audio & 3D Assets AUDIO_ALERT = 70 # Ding / audio notification THREED_APPEND = 71 # Binary: Three.js 3D GLTF asset streaming THREED_DONE = 72 # Binary THREED_ERROR = 73 # Binary # Reports, Reactions, Appeals, Edits REPORT_EVENT = 74 # Meguca report event REACTIONS = 75 # Post emoji reaction events FP_TOKEN_DELIVERY = 76 # Post-handshake fingerprint token delivery APPEAL_EVENT = 77 # Meguca appeal event CLOSED_EDIT = 78 # Post editing after submission # The Arcade & Extended Pipelines ARCADE_EVENT = 80 # In-thread multiplayer games & clock updates CLAUDE_THINKING = 81 # Binary: Claude / LLM internal reasoning stream BYTEPLUSVID_APPEND = 82 # Binary: ByteDance BytePlus video streaming BYTEPLUSVID_DONE = 83 # Binary BYTEPLUSVID_ERROR = 84 # Binary X_EMBED = 85 # Twitter / X embed card @dataclass class NekohashSyncRequest: """Nekohash synchronization payload (type 44).""" board: str thread: Optional[int] = None protocolVersion: int = 1 loginData: Optional[dict] = None seal: str = "noWASM" fp: str = "" meta_pass: str = "" @dataclass class BinaryStreamChunk: """Decoded binary stream chunk (keystroke append, AI streaming, etc.).""" post_id: float text: str msg_type: MessageType @dataclass class SpliceEvent: """Decoded binary splice event (type 04).""" post_id: float start: int length: int text: str @dataclass class ArcadeAction: """Arcade client-to-server action (type 80).""" t: str id: Optional[str] = None m: Optional[dict] = None e: Optional[int] = None def encode_message(msg_type: MessageType | int, payload: Any = None) -> str: """ Encode a text message for sending over WebSocket. Format: "<2-digit-type>" (or "" if payload is None). """ type_val = msg_type.value if isinstance(msg_type, MessageType) else int(msg_type) type_str = f"{type_val:02d}" if payload is None: return type_str if isinstance(payload, str): return type_str + payload return type_str + json.dumps(payload, separators=(",", ":")) def decode_binary_message(data: bytes | bytearray) -> tuple[int, Any]: """ Decode a binary message frame from WebSocket. Structure: - Last byte (len-1): opcode uint8 - Byte 0..7: post ID (double / float64 little-endian) - Byte 8..len-2: payload """ if len(data) == 0: raise ValueError("Empty binary frame") opcode = data[-1] # Type 3: BACKSPACE -> [post_id (8B), 0x03] if opcode == MessageType.BACKSPACE: if len(data) < 9: return opcode, None post_id = struct.unpack(" [post_id (8B), start (2B), len (2B), text, 0x04] if opcode == MessageType.SPLICE: if len(data) < 13: return opcode, None post_id = struct.unpack("= 9: post_id = struct.unpack(" tuple[int, Any]: """ Decode a message received from WebSocket (supports both text and binary frames). Returns: (type_code, parsed_payload) """ if isinstance(data, (bytes, bytearray)): return decode_binary_message(data) if len(data) < 2: raise ValueError(f"Message too short: {data}") type_code = int(data[:2]) if len(data) == 2: return type_code, None payload_str = data[2:] # Handle batched events (type 47) if type_code == MessageType.BATCH_EVENTS: try: batch = json.loads(payload_str) parsed_batch = [] for item in batch: if isinstance(item, str): parsed_batch.append(decode_message(item)) return type_code, parsed_batch except json.JSONDecodeError: return type_code, payload_str try: payload = json.loads(payload_str) except json.JSONDecodeError: payload = payload_str return type_code, payload def build_synchronise(board: str = "all", thread: Optional[int] = None, fp_token: str = "", meta_pass: str = "") -> str: """Build type 44 synchronise message.""" req = NekohashSyncRequest( board=board, thread=thread, fp=fp_token, meta_pass=meta_pass, ) return encode_message(MessageType.SYNCHRONISE, req.__dict__) def build_noop() -> str: """Build type 48 NOOP keepalive ping.""" return encode_message(MessageType.NOOP_PING) def build_arcade_action(action: str, game_id: Optional[str] = None, move_data: Optional[dict] = None) -> str: """Build type 80 Arcade action message.""" payload = {"t": action} if game_id: payload["id"] = game_id if move_data: payload["m"] = move_data return encode_message(MessageType.ARCADE_EVENT, payload) def build_nekotv_sync() -> str: """Build type 54 NekoTV synchronization request.""" return encode_message(MessageType.NEKO_TV_SYNC, None)