tortalk 1.0.2__tar.gz

tortalk-1.0.2/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  pypi-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tortalk-1.0.2/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.env
+.idea/
+.vscode/
+.DS_Store

tortalk-1.0.2/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.5
+Name: tortalk
+Version: 1.0.2
+Summary: Secure, peer-to-peer terminal chat over Tor v3 onion services with E2EE
+Author: Mohammad Saleh Abbasi
+License: MIT
+Keywords: chat,e2ee,onion,p2p,privacy,terminal,tor,tui
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: python-socks[asyncio]>=2.5.0
+Requires-Dist: stem>=1.8.2
+Requires-Dist: textual>=0.70.0
+Description-Content-Type: text/markdown
+
+# Tork
+
+Secure, peer-to-peer terminal chat over Tor v3 onion services with End-to-End Encryption (E2EE).
+
+## Prerequisites
+
+- Python >= 3.10
+- Tor daemon running locally with SOCKS5 proxy enabled (default `127.0.0.1:9050`) and ControlPort enabled (default `127.0.0.1:9051`).
+
+## Quick Start
+
+```bash
+pip install .
+tork
+```

tortalk-1.0.2/README.md

@@ -0,0 +1,15 @@
+# Tork
+
+Secure, peer-to-peer terminal chat over Tor v3 onion services with End-to-End Encryption (E2EE).
+
+## Prerequisites
+
+- Python >= 3.10
+- Tor daemon running locally with SOCKS5 proxy enabled (default `127.0.0.1:9050`) and ControlPort enabled (default `127.0.0.1:9051`).
+
+## Quick Start
+
+```bash
+pip install .
+tork
+```

tortalk-1.0.2/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tortalk"
+version = "1.0.2"
+description = "Secure, peer-to-peer terminal chat over Tor v3 onion services with E2EE"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Mohammad Saleh Abbasi" }
+]
+keywords = ["tor", "onion", "p2p", "chat", "terminal", "tui", "e2ee", "privacy"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Communications :: Chat",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "stem>=1.8.2",
+    "python-socks[asyncio]>=2.5.0",
+    "cryptography>=42.0.0",
+    "textual>=0.70.0",
+    "pyperclip>=1.8.2"
+]
+
+[project.scripts]
+tork = "tortalk.cli:main"

tortalk-1.0.2/requirements.txt

@@ -0,0 +1,16 @@
+cffi==2.1.1
+cryptography==50.0.2
+linkify-it-py==2.2.0
+markdown-it-py==4.2.0
+mdit-py-plugins==0.6.1
+mdurl==0.1.2
+platformdirs==4.13.3
+pycparser==3.11
+Pygments==2.21.0
+pyperclip==1.11.0
+python-socks==3.1.1
+rich==15.0.0
+stem==1.8.2
+textual==8.2.8
+-e git+https://github.com/packetlost-ir/tork.git@a576064df91e5141161bc564d8135dce1efb69f3#egg=tork
+typing_extensions==4.16.0

tortalk-1.0.2/tortalk/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

tortalk-1.0.2/tortalk/__main__.py

@@ -0,0 +1,4 @@
+from tork.cli import main
+
+if __name__ == "__main__":
+    main()

tortalk-1.0.2/tortalk/cli.py

@@ -0,0 +1,283 @@
+import asyncio
+import argparse
+import sys
+import traceback
+import pyperclip
+from tork.config import DEFAULT_LOCAL_PORT, SOCKS_PORT, CONTROL_PORT, CONNECT_TIMEOUT, normalize_and_validate_onion, clean_hash
+from tork.network.tor import get_controller, create_onion_service, destroy_onion_service
+from tork.network.server import PeerServer
+from tork.network.client import connect_peer
+from tork.network.protocol import (
+    send_frame, receive_frame, perform_protocol_handshake,
+    encode_payload, decode_payload, OP_CHAT,
+)
+from tork.crypto import encrypt_message, decrypt_message
+from tork.storage import StorageManager
+from tork.ui.app import TorkApp
+
+async def async_listen(local_port: int, control_port: int, timeout: float):
+    print(f"Connecting to Tor daemon (control port {control_port})...")
+    storage = StorageManager(config_dir=getattr(args_global, "config_dir", None), profile=getattr(args_global, "profile", None))
+    identity = storage.load_identity()
+
+    try:
+        controller = get_controller(control_port=control_port)
+    except Exception as e:
+        print(f"Failed to connect to Tor control port: {e}", file=sys.stderr)
+        return
+
+    try:
+        if identity:
+            print("Loading persistent identity...")
+            onion_hash, _, _ = create_onion_service(
+                controller,
+                local_port,
+                key_type=identity["key_type"],
+                key_content=identity["private_key"]
+            )
+        else:
+            print("Generating new persistent identity...")
+            onion_hash, key_type, private_key = create_onion_service(controller, local_port)
+            storage.save_identity(onion_hash, key_type, private_key)
+    except Exception as e:
+        print(f"Failed to configure ephemeral/persistent onion service: {e}", file=sys.stderr)
+        controller.close()
+        return
+
+    h = clean_hash(onion_hash)
+    print(f"Onion service created (hash): {h}")
+    print(f"Listening on 127.0.0.1:{local_port}...")
+
+    display_name = getattr(args_global, "profile", None) or f"peer-{h[:6]}"
+
+    async def handle_connection(reader, writer):
+        try:
+            shared_key, peer_hash, peer_name = await perform_protocol_handshake(
+                reader, writer, h, display_name, False, timeout=timeout
+            )
+            print("[i] Receiving encrypted frame...")
+            encrypted_payload = await receive_frame(reader)
+            print("[i] Decrypting incoming payload...")
+            plaintext_bytes = decrypt_message(shared_key, encrypted_payload)
+            msg_type, name, sender_onion, msg = decode_payload(plaintext_bytes)
+            
+            # Nickname sync & Auto-save fallback
+            sender_onion = sender_onion or peer_hash
+            name = name or peer_name
+            
+            if sender_onion and sender_onion != h:
+                alias = storage.find_alias_by_onion(sender_onion)
+                if alias:
+                    if name and alias != name:
+                        if storage.update_alias(alias, name):
+                            print(f"[i] Nickname synced: {alias} -> {name}", flush=True)
+                else:
+                    new_alias = name or f"peer-{sender_onion[:6]}"
+                    storage.add_contact(new_alias, sender_onion)
+                    print(f"[i] Discovered and saved contact: {new_alias} ({sender_onion[:8]}...)", flush=True)
+
+            who = name or (clean_hash(sender_onion)[:8] if sender_onion else "Peer")
+            print(f"[Incoming - Decrypted E2EE] [{who}] {msg}", flush=True)
+        except Exception as e:
+            print(f"[!] Error processing incoming message: {e}", file=sys.stderr, flush=True)
+            traceback.print_exc()
+
+    server = PeerServer("127.0.0.1", local_port, h, display_name, handle_connection)
+    await server.start()
+
+    stop_event = asyncio.Event()
+
+    try:
+        while not stop_event.is_set():
+            await asyncio.sleep(0.5)
+    except asyncio.CancelledError:
+        pass
+    finally:
+        print("\nShutting down server and removing onion service...")
+        await server.stop()
+        try:
+            destroy_onion_service(controller, h)
+        except Exception as e:
+            print(f"Error removing onion service: {e}", file=sys.stderr)
+        try:
+            controller.close()
+        except Exception:
+            pass
+        print("Done.")
+
+async def async_send(target_arg: str, message: str, socks_port: int, timeout: float, config_dir=None, profile=None):
+    storage = StorageManager(config_dir=config_dir, profile=profile)
+    resolved_onion = storage.get_contact(target_arg) or target_arg
+
+    is_valid, normalized_addr, err_msg = normalize_and_validate_onion(resolved_onion)
+    if not is_valid:
+        print(f"Error: Invalid onion address or unknown contact '{target_arg}': {err_msg}", file=sys.stderr)
+        sys.exit(1)
+
+    h = clean_hash(normalized_addr)
+    print(f"Connecting to {h} via Tor SOCKS5 (port {socks_port})...")
+    try:
+        reader, writer = await connect_peer(normalized_addr, socks_port=socks_port, timeout=timeout)
+    except Exception as e:
+        print(f"Error connecting to peer: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        identity = storage.load_identity()
+        self_hash = clean_hash(identity["service_id"]) if identity else ""
+        display_name = profile or (f"peer-{self_hash[:6]}" if self_hash else "")
+
+        shared_key, peer_hash, peer_name = await perform_protocol_handshake(
+            reader, writer, self_hash, display_name, True, timeout=timeout
+        )
+        print("[i] Encrypting message with ChaCha20-Poly1305...")
+        payload = encode_payload(display_name, self_hash, message)
+        # Prepend OP_CHAT opcode for compatibility with PeerSession
+        encrypted_payload = encrypt_message(shared_key, bytes([OP_CHAT]) + payload)
+        print("[i] Sending encrypted frame...")
+        await send_frame(writer, encrypted_payload)
+        print("Message encrypted with ChaCha20-Poly1305 and delivered securely.")
+    except Exception as e:
+        print(f"Error sending message: {e}", file=sys.stderr)
+        traceback.print_exc()
+        sys.exit(1)
+    finally:
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except Exception:
+            pass
+
+def handle_id(copy_to_clip: bool, control_port: int, config_dir=None, profile=None):
+    storage = StorageManager(config_dir=config_dir, profile=profile)
+    identity = storage.load_identity()
+    if not identity:
+        print("No identity found. Generating identity...")
+        try:
+            controller = get_controller(control_port=control_port)
+            onion_hash, key_type, private_key = create_onion_service(controller, DEFAULT_LOCAL_PORT, await_publication=False)
+            storage.save_identity(onion_hash, key_type, private_key)
+            controller.close()
+            identity = storage.load_identity()
+        except Exception as e:
+            print(f"Error generating identity via Tor daemon: {e}", file=sys.stderr)
+            sys.exit(1)
+
+    h = clean_hash(identity["service_id"])
+    print(f"Your persistent Tor Onion Address (hash): {h}")
+    if copy_to_clip:
+        try:
+            pyperclip.copy(h)
+            print("Copied 56-character hash to clipboard.")
+        except Exception as e:
+            print(f"Could not copy to clipboard: {e}", file=sys.stderr)
+
+def handle_contact(args):
+    storage = StorageManager(config_dir=args.config_dir, profile=args.profile)
+    subaction = args.contact_action
+
+    if subaction == "add":
+        success, res = storage.add_contact(args.alias, args.onion)
+        if success:
+            h = clean_hash(res)
+            print(f"Contact '{args.alias}' added: {h}")
+        else:
+            print(f"Error adding contact: {res}", file=sys.stderr)
+            sys.exit(1)
+    elif subaction == "list":
+        contacts = storage.list_contacts()
+        if not contacts:
+            print("No contacts saved.")
+        else:
+            print("Saved Contacts:")
+            for alias, data in contacts.items():
+                print(f"  {alias} -> {clean_hash(data['onion'])}")
+    elif subaction == "remove":
+        removed = storage.remove_contact(args.alias)
+        if removed:
+            print(f"Contact '{args.alias}' removed.")
+        else:
+            print(f"Contact '{args.alias}' not found.", file=sys.stderr)
+            sys.exit(1)
+    else:
+        print("Invalid contact action.", file=sys.stderr)
+        sys.exit(1)
+
+args_global = None
+
+def main():
+    global args_global
+    parser = argparse.ArgumentParser(description="Tork P2P Terminal Chat over Tor")
+    
+    # Global arguments
+    parser.add_argument("--config-dir", type=str, default=None, help="Custom configuration directory")
+    parser.add_argument("--profile", type=str, default=None, help="Profile name shorthand")
+    parser.add_argument("-p", "--local-port", type=int, default=DEFAULT_LOCAL_PORT, help="Local TCP listen port")
+    parser.add_argument("--socks-port", type=int, default=SOCKS_PORT, help="Tor SOCKS5 proxy port")
+    parser.add_argument("--control-port", type=int, default=CONTROL_PORT, help="Tor ControlPort")
+    parser.add_argument("--timeout", type=float, default=CONNECT_TIMEOUT, help="Connection / handshake timeout")
+
+    subparsers = parser.add_subparsers(dest="command", required=False)
+
+    listen_parser = subparsers.add_parser("listen", help="Listen for incoming peer connections")
+    
+    send_parser = subparsers.add_parser("send", help="Send a message to a peer onion address or contact alias")
+    send_parser.add_argument("onion_address", type=str, help="Target peer onion address or contact alias")
+    send_parser.add_argument("message", type=str, help="Message text to send")
+
+    id_parser = subparsers.add_parser("id", help="Display local persistent 56-char onion hash")
+    id_parser.add_argument("--copy", action="store_true", help="Copy hash to clipboard")
+
+    chat_parser = subparsers.add_parser("chat", help="Launch Textual TUI chat interface")
+    chat_parser.add_argument("target", nargs="?", default=None, help="Optional initial target contact or onion hash")
+
+    contact_parser = subparsers.add_parser("contact", help="Manage saved contacts")
+    contact_subparsers = contact_parser.add_subparsers(dest="contact_action", required=True)
+
+    add_p = contact_subparsers.add_parser("add", help="Add a new contact")
+    add_p.add_argument("alias", type=str, help="Contact alias")
+    add_p.add_argument("onion", type=str, help="Peer onion address")
+
+    contact_subparsers.add_parser("list", help="List all contacts")
+
+    remove_p = contact_subparsers.add_parser("remove", help="Remove a contact")
+    remove_p.add_argument("alias", type=str, help="Contact alias to remove")
+
+    args, unknown = parser.parse_known_args()
+    args_global = args
+
+    command = args.command if args.command else "chat"
+    target = getattr(args, "target", None)
+
+    if command == "listen":
+        try:
+            asyncio.run(async_listen(args.local_port, args.control_port, args.timeout))
+        except KeyboardInterrupt:
+            pass
+    elif command == "send":
+        try:
+            asyncio.run(async_send(args.onion_address, args.message, args.socks_port, args.timeout, config_dir=args.config_dir, profile=args.profile))
+        except KeyboardInterrupt:
+            pass
+    elif command == "id":
+        handle_id(args.copy, args.control_port, config_dir=args.config_dir, profile=args.profile)
+    elif command == "contact":
+        handle_contact(args)
+    elif command == "chat":
+        storage = StorageManager(config_dir=args.config_dir, profile=args.profile)
+        resolved_target = None
+        if target:
+            resolved_target = storage.get_contact(target) or target
+        app = TorkApp(
+            initial_target=resolved_target,
+            config_dir=args.config_dir,
+            profile=args.profile,
+            local_port=args.local_port,
+            socks_port=args.socks_port,
+            control_port=args.control_port,
+            timeout=args.timeout
+        )
+        app.run()
+
+if __name__ == "__main__":
+    main()

tortalk-1.0.2/tortalk/config.py

@@ -0,0 +1,60 @@
+import re
+from pathlib import Path
+
+SOCKS_HOST: str = "127.0.0.1"
+SOCKS_PORT: int = 9050
+CONTROL_PORT: int = 9051
+DEFAULT_LOCAL_PORT: int = 5666
+CONNECT_TIMEOUT: float = 120.0
+
+ONION_REGEX = re.compile(r"^[a-z2-7]{56}\.onion$")
+
+def normalize_and_validate_onion(raw_input: str) -> tuple[bool, str, str]:
+    if not isinstance(raw_input, str):
+        return False, "", "Input must be a string."
+    
+    val = raw_input.strip().lower()
+    for proto in ("http://", "https://", "socks5://", "socks://"):
+        if val.startswith(proto):
+            val = val[len(proto):]
+            break
+            
+    val = val.split("/")[0]
+    
+    if len(val) == 56 and re.match(r"^[a-z2-7]{56}$", val):
+        val = f"{val}.onion"
+        
+    if ONION_REGEX.match(val):
+        return True, val, ""
+        
+    return False, raw_input, "Invalid .onion address format."
+
+def clean_hash(onion: object) -> str:
+    if not onion:
+        return ""
+    
+    # Handle schema variance (list of dicts, flat dicts, or strings)
+    if isinstance(onion, dict):
+        onion = onion.get("onion", "")
+    elif isinstance(onion, list) and len(onion) > 0:
+        first = onion[0]
+        onion = first.get("onion", "") if isinstance(first, dict) else str(first)
+    elif not isinstance(onion, str):
+        onion = str(onion)
+    
+    val = onion.strip().lower()
+    for proto in ("http://", "https://", "socks5://", "socks://"):
+        if val.startswith(proto):
+            val = val[len(proto):]
+            break
+    val = val.split("/")[0]
+    if val.endswith(".onion"):
+        val = val[:-6]
+    return val
+
+def resolve_config_dir(config_dir: str | Path | None = None, profile: str | None = None) -> Path:
+    if config_dir:
+        return Path(config_dir).expanduser().resolve()
+    if profile:
+        return (Path.home() / ".config" / "tork" / "profiles" / profile).resolve()
+    return (Path.home() / ".config" / "tork").resolve()

tortalk-1.0.2/tortalk/crypto.py

@@ -0,0 +1,36 @@
+import os
+import traceback
+from cryptography.hazmat.primitives.asymmetric import x25519
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+
+def generate_ephemeral_keypair() -> tuple[x25519.X25519PrivateKey, bytes]:
+    private_key = x25519.X25519PrivateKey.generate()
+    public_bytes = private_key.public_key().public_bytes_raw()
+    return private_key, public_bytes
+
+def derive_shared_key(private_key: x25519.X25519PrivateKey, peer_public_bytes: bytes) -> bytes:
+    peer_pub_key = x25519.X25519PublicKey.from_public_bytes(peer_public_bytes)
+    shared_secret = private_key.exchange(peer_pub_key)
+    derived_key = HKDF(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=b"tork-e2ee-salt-v1",
+        info=b"tork-handshake",
+    ).derive(shared_secret)
+    return derived_key
+
+def encrypt_message(key: bytes, plaintext: bytes) -> bytes:
+    nonce = os.urandom(12)
+    cipher = ChaCha20Poly1305(key)
+    ciphertext = cipher.encrypt(nonce, plaintext, None)
+    return nonce + ciphertext
+
+def decrypt_message(key: bytes, payload: bytes) -> bytes:
+    if len(payload) < 12:
+        raise ValueError("Payload too short for nonce and ciphertext.")
+    nonce = payload[:12]
+    ciphertext = payload[12:]
+    cipher = ChaCha20Poly1305(key)
+    return cipher.decrypt(nonce, ciphertext, None)

tortalk-1.0.2/tortalk/network/client.py

@@ -0,0 +1,18 @@
+import asyncio
+from python_socks import ProxyType, ProxyError
+from python_socks.async_.asyncio import Proxy
+from tork.config import normalize_and_validate_onion, SOCKS_HOST, SOCKS_PORT, CONNECT_TIMEOUT
+
+async def connect_peer(target_onion, socks_host=SOCKS_HOST, socks_port=SOCKS_PORT, timeout=CONNECT_TIMEOUT):
+    is_valid, normalized_addr, err = normalize_and_validate_onion(target_onion)
+    if not is_valid: raise ValueError(f"Invalid address: {err}")
+    
+    proxy = Proxy.create(proxy_type=ProxyType.SOCKS5, host=socks_host, port=socks_port, rdns=True)
+    
+    for attempt in range(6):
+        try:
+            sock = await asyncio.wait_for(proxy.connect(dest_host=normalized_addr, dest_port=80), timeout=30)
+            return await asyncio.open_connection(sock=sock)
+        except (ProxyError, OSError, asyncio.TimeoutError) as e:
+            if attempt == 5: raise ConnectionError(f"Target unreachable: {e}")
+            await asyncio.sleep(15)

tortalk-1.0.2/tortalk/network/protocol.py

@@ -0,0 +1,149 @@
+import asyncio
+import struct
+import json
+import time
+from tork.crypto import generate_ephemeral_keypair, derive_shared_key, encrypt_message, decrypt_message
+
+# Opcodes
+OP_HANDSHAKE_INIT = 1
+OP_HANDSHAKE_ACK = 2
+OP_CHAT = 3
+OP_PING = 4
+OP_PONG = 5
+
+async def send_frame(writer: asyncio.StreamWriter, data: bytes) -> None:
+    writer.write(struct.pack("!I", len(data)) + data)
+    await writer.drain()
+
+async def receive_frame(reader: asyncio.StreamReader) -> bytes:
+    header = await reader.readexactly(4)
+    length = struct.unpack("!I", header)[0]
+    return await reader.readexactly(length)
+
+class PeerSession:
+    def __init__(self, reader, writer, shared_key, peer_hash, peer_name, is_initiator, app_callback):
+        self.reader = reader
+        self.writer = writer
+        self.shared_key = shared_key
+        self.peer_hash = peer_hash
+        self.peer_name = peer_name
+        self.is_initiator = is_initiator
+        self.app_callback = app_callback
+        self.last_seen = time.time()
+        self.active = True
+        self._read_task = None
+        self._keepalive_task = None
+
+    def start(self):
+        self._read_task = asyncio.create_task(self._reader_loop())
+        self._keepalive_task = asyncio.create_task(self._keepalive_loop())
+
+    async def send_op(self, opcode: int, payload_dict: dict = None):
+        if not self.active: return
+        data = json.dumps(payload_dict or {}).encode("utf-8")
+        encrypted = encrypt_message(self.shared_key, bytes([opcode]) + data)
+        try:
+            await send_frame(self.writer, encrypted)
+        except Exception:
+            await self.close()
+
+    async def _reader_loop(self):
+        try:
+            while self.active:
+                encrypted = await receive_frame(self.reader)
+                decrypted = decrypt_message(self.shared_key, encrypted)
+                opcode = decrypted[0]
+                payload = json.loads(decrypted[1:].decode("utf-8"))
+                self.last_seen = time.time()
+
+                if opcode == OP_CHAT:
+                    await self.app_callback("chat", self.peer_hash, payload)
+                elif opcode == OP_PING:
+                    await self.send_op(OP_PONG)
+                elif opcode == OP_PONG:
+                    pass
+        except Exception:
+            pass
+        finally:
+            await self.close()
+
+    async def _keepalive_loop(self):
+        try:
+            while self.active:
+                await asyncio.sleep(20)
+                if time.time() - self.last_seen > 60:
+                    break
+                await self.send_op(OP_PING)
+        except Exception:
+            pass
+        finally:
+            await self.close()
+
+    async def close(self):
+        if not self.active: return
+        self.active = False
+        if self._read_task: self._read_task.cancel()
+        if self._keepalive_task: self._keepalive_task.cancel()
+        try:
+            self.writer.close()
+            # Non-blocking wait_closed to avoid hang on exit
+            await asyncio.wait_for(self.writer.wait_closed(), timeout=0.5)
+        except Exception: pass
+        await self.app_callback("closed", self.peer_hash, None)
+
+async def perform_protocol_handshake(reader, writer, local_hash, local_name, is_initiator, timeout=30):
+    priv_key, pub_bytes = generate_ephemeral_keypair()
+    if is_initiator:
+        await send_frame(writer, pub_bytes)
+        peer_pub = await asyncio.wait_for(receive_frame(reader), timeout)
+    else:
+        peer_pub = await asyncio.wait_for(receive_frame(reader), timeout)
+        await send_frame(writer, pub_bytes)
+    
+    shared_key = derive_shared_key(priv_key, peer_pub)
+    
+    # Secure Identity Exchange
+    if is_initiator:
+        init_data = json.dumps({"o": local_hash, "n": local_name}).encode("utf-8")
+        await send_frame(writer, encrypt_message(shared_key, bytes([OP_HANDSHAKE_INIT]) + init_data))
+        resp = decrypt_message(shared_key, await asyncio.wait_for(receive_frame(reader), timeout))
+        if resp[0] != OP_HANDSHAKE_ACK: raise ValueError("Invalid ack")
+        peer_info = json.loads(resp[1:].decode("utf-8"))
+    else:
+        req = decrypt_message(shared_key, await asyncio.wait_for(receive_frame(reader), timeout))
+        if req[0] != OP_HANDSHAKE_INIT: raise ValueError("Invalid init")
+        peer_info = json.loads(req[1:].decode("utf-8"))
+        ack_data = json.dumps({"o": local_hash, "n": local_name}).encode("utf-8")
+        await send_frame(writer, encrypt_message(shared_key, bytes([OP_HANDSHAKE_ACK]) + ack_data))
+        
+    return shared_key, peer_info["o"], peer_info["n"]
+
+def encode_payload(display_name: str, sender_onion: str, message: str, msg_type: str = "chat") -> bytes:
+    envelope = {
+        "t": msg_type,
+        "n": display_name or "",
+        "o": (sender_onion or "").removesuffix(".onion"),
+        "m": message,
+    }
+    # For cli compatibility with opcode-based protocol, we prepend OP_CHAT if it's a chat message
+    # But wait, cli listen/send currently don't use PeerSession.
+    # To keep it simple, let's make decode_payload handle both raw envelope and opcode+envelope.
+    return json.dumps(envelope, ensure_ascii=False).encode("utf-8")
+
+def decode_payload(data: bytes) -> tuple[str, str, str, str]:
+    # Returns (type, display_name, sender_onion_hash, message).
+    # Handle optional opcode prefix (1 byte)
+    offset = 0
+    if len(data) > 0 and data[0] in (OP_HANDSHAKE_INIT, OP_HANDSHAKE_ACK, OP_CHAT, OP_PING, OP_PONG):
+        offset = 1
+    
+    try:
+        obj = json.loads(data[offset:].decode("utf-8"))
+        if isinstance(obj, dict):
+            # If it's a PeerSession style chat packet {"m": ..., "ts": ...}
+            if "m" in obj and "t" not in obj:
+                return "chat", "", "", obj.get("m", "")
+            return str(obj.get("t", "chat")), str(obj.get("n", "")), str(obj.get("o", "")), str(obj.get("m", ""))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        pass
+    return "chat", "", "", data.decode("utf-8", errors="replace")

tortalk-1.0.2/tortalk/network/server.py

@@ -0,0 +1,31 @@
+import asyncio
+import traceback
+from tork.network.protocol import perform_protocol_handshake
+
+class PeerServer:
+    def __init__(self, host, port, local_hash, local_name, session_callback):
+        self.host = host
+        self.port = port
+        self.local_hash = local_hash
+        self.local_name = local_name
+        self.session_callback = session_callback
+        self.server = None
+
+    async def _handle_connection(self, reader, writer):
+        try:
+            shared_key, peer_hash, peer_name = await perform_protocol_handshake(
+                reader, writer, self.local_hash, self.local_name, False
+            )
+            await self.session_callback(reader, writer, shared_key, peer_hash, peer_name, False)
+        except Exception as e:
+            writer.close()
+            try: await writer.wait_closed()
+            except Exception: pass
+
+    async def start(self):
+        self.server = await asyncio.start_server(self._handle_connection, self.host, self.port)
+
+    async def stop(self):
+        if self.server:
+            self.server.close()
+            await self.server.wait_closed()

tortalk-1.0.2/tortalk/network/tor.py

@@ -0,0 +1,35 @@
+from stem.control import Controller
+from tork.config import CONTROL_PORT
+
+def get_controller(control_port: int = CONTROL_PORT) -> Controller:
+    controller = Controller.from_port(port=control_port)
+    controller.authenticate()
+    return controller
+
+def create_onion_service(
+    controller: Controller,
+    local_port: int,
+    key_type: str = "NEW",
+    key_content: str = "ED25519-V3",
+    await_publication: bool = True
+) -> tuple[str, str, str]:
+    response = controller.create_ephemeral_hidden_service(
+        {80: local_port},
+        await_publication=await_publication,
+        key_type=key_type,
+        key_content=key_content,
+        discard_key=False
+    )
+    service_id = response.service_id
+    if service_id.endswith(".onion"):
+        service_id = service_id[:-6]
+    return service_id, response.private_key_type, response.private_key
+
+def destroy_onion_service(controller: Controller, onion_address: str) -> None:
+    service_id = onion_address
+    if service_id.endswith(".onion"):
+        service_id = service_id[:-6]
+    try:
+        controller.remove_ephemeral_hidden_service(service_id)
+    except Exception:
+        pass

tortalk-1.0.2/tortalk/storage.py

@@ -0,0 +1,131 @@
+import os
+import json
+from pathlib import Path
+from tork.config import normalize_and_validate_onion, resolve_config_dir
+
+class StorageManager:
+    def __init__(self, config_dir: str | Path | None = None, profile: str | None = None):
+        self.config_dir = resolve_config_dir(config_dir, profile)
+        self.config_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.identity_file = self.config_dir / "identity.json"
+        self.contacts_file = self.config_dir / "contacts.json"
+
+    def load_identity(self) -> dict | None:
+        if self.identity_file.exists():
+            try:
+                with open(self.identity_file, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except Exception:
+                return None
+        return None
+
+    def save_identity(self, service_id: str, key_type: str, private_key: str) -> None:
+        data = {
+            "service_id": service_id,
+            "key_type": key_type,
+            "private_key": private_key
+        }
+        with open(self.identity_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        os.chmod(self.identity_file, 0o600)
+
+    def _load_contacts_raw(self) -> dict:
+        if not self.contacts_file.exists():
+            return {}
+        try:
+            with open(self.contacts_file, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                if isinstance(data, list):
+                    # Flatten list of objects to dict indexed by alias/nickname
+                    return {item.get("nickname") or item.get("alias") or f"peer-{str(item.get('onion'))[:6]}": item for item in data if isinstance(item, dict)}
+                return data if isinstance(data, dict) else {}
+        except Exception:
+            return {}
+
+    def _save_contacts_raw(self, contacts: dict) -> None:
+        with open(self.contacts_file, "w", encoding="utf-8") as f:
+            json.dump(contacts, f, indent=2)
+        os.chmod(self.contacts_file, 0o600)
+
+    def list_contacts(self) -> dict[str, dict]:
+        """Returns normalized contacts: { alias: { nickname, onion, last_seen } }"""
+        raw = self._load_contacts_raw()
+        normalized = {}
+        for key, val in raw.items():
+            if isinstance(val, str):
+                normalized[key] = {"nickname": key, "onion": val, "last_seen": None}
+            elif isinstance(val, list):
+                # Handle nested list quirk mentioned in issue
+                onion_str = val[0].get("onion", "") if val and isinstance(val[0], dict) else ""
+                normalized[key] = {"nickname": key, "onion": onion_str, "last_seen": None}
+            elif isinstance(val, dict):
+                normalized[key] = {
+                    "nickname": val.get("nickname") or val.get("alias") or key,
+                    "onion": val.get("onion", ""),
+                    "last_seen": val.get("last_seen")
+                }
+        return normalized
+
+    def add_contact(self, alias: str, onion: str) -> tuple[bool, str]:
+        is_valid, normalized_onion, err = normalize_and_validate_onion(onion)
+        if not is_valid:
+            return False, f"Invalid onion address: {err}"
+        
+        target_hash = normalized_onion.removesuffix(".onion")
+        contacts = self._load_contacts_raw()
+        
+        # Deduplicate by onion hash
+        existing_alias = self.find_alias_by_onion(target_hash)
+        if existing_alias:
+            if existing_alias != alias:
+                # Rename the contact key to the new alias
+                data = contacts.pop(existing_alias)
+                if isinstance(data, dict):
+                    data["nickname"] = alias
+                else:
+                    data = {"nickname": alias, "onion": target_hash}
+                contacts[alias] = data
+            else:
+                if isinstance(contacts[alias], dict):
+                    contacts[alias]["nickname"] = alias
+            self._save_contacts_raw(contacts)
+            return True, target_hash
+
+        contacts[alias] = {
+            "nickname": alias,
+            "onion": target_hash,
+            "last_seen": None
+        }
+        self._save_contacts_raw(contacts)
+        return True, target_hash
+
+    def get_contact(self, alias: str) -> str | None:
+        """Returns clean 56-char onion string for an alias."""
+        contacts = self.list_contacts()
+        data = contacts.get(alias)
+        if data:
+            return data.get("onion")
+        return None
+
+    def find_alias_by_onion(self, onion: str) -> str | None:
+        target = onion.removesuffix(".onion")
+        for alias, data in self.list_contacts().items():
+            if data.get("onion") == target:
+                return alias
+        return None
+
+    def update_alias(self, old_alias: str, new_alias: str) -> bool:
+        new_alias = (new_alias or "").strip()
+        if not new_alias or new_alias == old_alias:
+            return False
+        
+        contacts = self._load_contacts_raw()
+        if old_alias not in contacts or new_alias in contacts:
+            return False
+        
+        data = contacts.pop(old_alias)
+        if isinstance(data, dict):
+            data["nickname"] = new_alias
+        contacts[new_alias] = data
+        self._save_contacts_raw(contacts)
+        return True

tortalk-1.0.2/tortalk/ui/app.py

@@ -0,0 +1,311 @@
+import asyncio
+import time
+from textual.app import App, ComposeResult
+from textual.widgets import Header, Footer, Static, Input, RichLog, ListItem, ListView, Label
+from textual.containers import Horizontal, Vertical
+from textual.message import Message
+from textual import work
+from rich.panel import Panel
+
+from tork.config import DEFAULT_LOCAL_PORT, SOCKS_PORT, CONTROL_PORT, CONNECT_TIMEOUT, clean_hash, normalize_and_validate_onion
+from tork.storage import StorageManager
+from tork.network.tor import get_controller, create_onion_service, destroy_onion_service
+from tork.network.server import PeerServer
+from tork.network.client import connect_peer
+from tork.network.protocol import PeerSession, OP_CHAT, perform_protocol_handshake
+from tork.ui.commands import TorkCommandProvider
+from tork.ui.modals import AddContactModal
+
+class PeerEvent(Message):
+    def __init__(self, type, peer_hash, data=None):
+        self.type = type
+        self.peer_hash = peer_hash
+        self.data = data
+        super().__init__()
+
+class TorkApp(App):
+    CSS = """
+    Screen { background: $surface; color: $text; }
+    #main { layout: horizontal; }
+    #sidebar { width: 35; background: $boost; border-right: solid $primary-background; }
+    #chat { layout: vertical; }
+    #chat-header { height: 3; background: $panel; padding: 1; color: $accent; }
+    #chat-log { height: 1fr; background: $surface; }
+    #input-box { height: 3; }
+    .online { color: $success; }
+    .offline { color: $text-muted; }
+    .unread { color: $error; text-style: bold; }
+    """
+
+    COMMANDS = App.COMMANDS | {TorkCommandProvider}
+    BINDINGS = [("q", "quit", "Quit"), ("a", "prompt_add_contact", "Add Contact")]
+
+    def __init__(self, initial_target=None, config_dir=None, profile=None, local_port=DEFAULT_LOCAL_PORT, socks_port=SOCKS_PORT, control_port=CONTROL_PORT, timeout=CONNECT_TIMEOUT):
+        super().__init__()
+        self.storage = StorageManager(config_dir=config_dir, profile=profile)
+        self.local_port, self.socks_port, self.control_port, self.timeout = local_port, socks_port, control_port, timeout
+        self.profile = profile
+        self.sessions = {} # hash -> PeerSession
+        self.chat_buffers = {} # hash -> list
+        self.unread_counts = {} # hash -> int
+        self.active_peer_hash = None
+        self.local_onion_hash = ""
+        self.display_name = profile or ""
+
+    def action_copy_onion_id(self) -> None:
+        if self.local_onion_hash:
+            try:
+                import pyperclip
+                pyperclip.copy(self.local_onion_hash)
+                self.notify(f"Onion ID copied to clipboard: {self.local_onion_hash[:8]}...", title="Tork Identity")
+            except Exception as e:
+                self.notify(f"Copy failed: {e}", severity="error")
+
+    def action_prompt_add_contact(self) -> None:
+        async def _add_contact():
+            h = await self.push_screen_wait(AddContactModal())
+            if not h or h == self.local_onion_hash: return
+            
+            alias = self.storage.find_alias_by_onion(h) or f"peer-{h[:6]}"
+            self.storage.add_contact(alias, h)
+            self.refresh_contacts()
+            
+            # Switch focus to the contact
+            self.active_peer_hash = h
+            self.unread_counts[h] = 0
+            self.refresh_contacts()
+            
+            # Select in ListView
+            try:
+                lv = self.query_one("#contacts-list", ListView)
+                for i, item in enumerate(lv.children):
+                    if isinstance(item, ListItem) and item.name == h:
+                        lv.index = i
+                        break
+            except Exception: pass
+            
+            if h not in self.sessions:
+                self.run_worker(self._connect_to_peer(h, alias))
+        
+        self.run_worker(_add_contact())
+
+    async def _connect_to_peer(self, h: str, alias: str):
+        self.query_one("#chat-header", Static).update(f"Connecting to {alias} via Tor...")
+        try:
+            r, w = await connect_peer(h, socks_port=self.socks_port)
+            key, ph, pn = await perform_protocol_handshake(r, w, self.local_onion_hash, self.display_name, True)
+            await self.register_session(r, w, key, ph, pn, True)
+            if h == self.active_peer_hash:
+                self.query_one("#chat-header", Static).update(f"Chat: {alias} [E2EE Secured]")
+        except Exception as e:
+            if h == self.active_peer_hash:
+                self.query_one("#chat-header", Static).update(f"Chat: {alias} (Offline)")
+            self.notify(f"Failed to connect to {alias}: {e}", severity="error")
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Horizontal(id="main"):
+            with Vertical(id="sidebar"):
+                yield Label(" CONTACTS", classes="section-title")
+                yield ListView(id="contacts-list")
+            with Vertical(id="chat"):
+                yield Static("Select a contact", id="chat-header")
+                yield RichLog(id="chat-log", markup=True)
+                yield Input(placeholder="Type message...", id="msg-input")
+        yield Footer()
+
+    async def on_mount(self):
+        await self.start_services()
+        self.refresh_contacts()
+
+    async def start_services(self):
+        try:
+            self.controller = await asyncio.to_thread(get_controller, self.control_port)
+            id = self.storage.load_identity()
+            if id:
+                h, _, _ = await asyncio.to_thread(
+                    create_onion_service, 
+                    self.controller, 
+                    self.local_port, 
+                    id["key_type"], 
+                    id["private_key"]
+                )
+            else:
+                h, t, k = await asyncio.to_thread(create_onion_service, self.controller, self.local_port)
+                self.storage.save_identity(h, t, k)
+            self.local_onion_hash = clean_hash(h)
+            if not self.display_name: self.display_name = f"peer-{self.local_onion_hash[:6]}"
+            
+            self.server = PeerServer("127.0.0.1", self.local_port, self.local_onion_hash, self.display_name, self.register_session)
+            await self.server.start()
+        except Exception as e:
+            self.notify(f"Init error: {e}", severity="error")
+
+    async def register_session(self, r, w, key, h, n, init):
+        h = clean_hash(h)
+        if h == self.local_onion_hash: return
+        
+        # Mutual Discovery
+        if not self.storage.find_alias_by_onion(h):
+            self.storage.add_contact(n or f"peer-{h[:6]}", h)
+        elif n:
+            alias = self.storage.find_alias_by_onion(h)
+            if alias != n: self.storage.update_alias(alias, n)
+            
+        session = PeerSession(r, w, key, h, n, init, self.protocol_callback)
+        self.sessions[h] = session
+        session.start()
+        self.post_message(PeerEvent("status", h))
+
+    async def protocol_callback(self, type, h, data):
+        self.post_message(PeerEvent(type, h, data))
+
+    def write_message_to_log(self, sender: str, text: str, ts: str, h: str):
+        log = self.query_one("#chat-log", RichLog)
+        is_me = (sender == "me")
+        
+        if is_me:
+            who = self.display_name or "You"
+            bg_color = "on #2b5278"
+            align_tag = "right"
+        else:
+            who = self.storage.find_alias_by_onion(h) or f"peer-{h[:6]}"
+            bg_color = "on #182533"
+            align_tag = "left"
+
+        max_w = max(20, log.size.width - 10) if log.size.width > 15 else 50
+        wrapped_lines = []
+        for paragraph in text.splitlines():
+            if not paragraph:
+                wrapped_lines.append("")
+            else:
+                while len(paragraph) > max_w:
+                    wrapped_lines.append(paragraph[:max_w])
+                    paragraph = paragraph[max_w:]
+                wrapped_lines.append(paragraph)
+
+        lines = wrapped_lines if wrapped_lines else [""]
+        max_content_len = max(len(l) for l in lines) if lines else 0
+        width = max(len(who) + 2, max_content_len + 2)
+
+        content_lines = []
+        for l in lines:
+            content_lines.append(f" {l.ljust(width - 1)}")
+        box_str = "\n".join(content_lines)
+        rendered = f"[{bg_color}]{box_str}[/]"
+        
+        log.write("")
+        log.write(f"[{align_tag}][dim] {who} [/][/{align_tag}]")
+        log.write(f"[{align_tag}]{rendered}[/{align_tag}]")
+        log.write(f"[{align_tag}][dim] {ts} [/][/{align_tag}]")
+        log.write("")
+
+    def on_peer_event(self, event: PeerEvent):
+        if self._closing or not self.is_mounted: return
+        h = event.peer_hash
+        if event.type == "chat":
+            msg = {"sender": "peer", "text": event.data["m"], "ts": time.strftime("%H:%M")}
+            if h not in self.chat_buffers: self.chat_buffers[h] = []
+            self.chat_buffers[h].append(msg)
+            
+            if h == self.active_peer_hash:
+                self.write_message_to_log("peer", msg["text"], msg["ts"], h)
+            else:
+                self.unread_counts[h] = self.unread_counts.get(h, 0) + 1
+                self.notify(f"New message from {h[:6]}")
+                self.refresh_contacts()
+        elif event.type in ("status", "closed"):
+            if event.type == "closed": self.sessions.pop(h, None)
+            self.refresh_contacts()
+
+    def refresh_contacts(self) -> None:
+        if not self.is_mounted or self._closing or getattr(self, "_pruning", False):
+            return
+
+        try:
+            lv = self.query_one("#contacts-list", ListView)
+        except Exception:
+            return
+
+        if not lv.is_mounted or not lv.is_attached:
+            return
+
+        lv.clear()
+        items = []
+        seen_hashes = set()
+        for alias, data in self.storage.list_contacts().items():
+            if isinstance(data, dict):
+                h = clean_hash(data.get("onion", ""))
+                name = data.get("nickname") or alias
+            else:
+                h = clean_hash(data)
+                name = alias
+
+            if not h or h == self.local_onion_hash or h in seen_hashes:
+                continue
+            seen_hashes.add(h)
+
+            cls = "online" if h in self.sessions else "offline"
+            status = "●" if cls == "online" else "○"
+            unread_cnt = self.unread_counts.get(h, 0)
+            unread = f" [{unread_cnt}]" if unread_cnt > 0 else ""
+            label = f"[{cls}]{status}[/] {name}{unread}"
+            items.append(ListItem(Label(label), name=h))
+
+        if items:
+            lv.extend(items)
+
+    def on_list_view_selected(self, event: ListView.Selected):
+        h = event.item.name
+        alias = self.storage.find_alias_by_onion(h) or f"peer-{h[:6]}"
+        self.active_peer_hash = h
+        self.unread_counts[h] = 0
+        
+        status_text = "[E2EE Secured]" if h in self.sessions else "(Offline)"
+        self.query_one("#chat-header", Static).update(f"Chat: {alias} {status_text}")
+        
+        log = self.query_one("#chat-log", RichLog)
+        log.clear()
+        for m in self.chat_buffers.get(h, []):
+            self.write_message_to_log(m["sender"], m["text"], m["ts"], h)
+            
+        if h not in self.sessions:
+            self.run_worker(self._connect_to_peer(h, alias))
+            
+        self.refresh_contacts()
+
+    async def on_input_submitted(self, event: Input.Submitted):
+        text = event.value.strip()
+        h = self.active_peer_hash
+        if not text or not h or h not in self.sessions: return
+        event.input.value = ""
+        ts = time.strftime("%H:%M")
+        await self.sessions[h].send_op(OP_CHAT, {"m": text, "ts": ts})
+        msg = {"sender": "me", "text": text, "ts": ts}
+        if h not in self.chat_buffers: self.chat_buffers[h] = []
+        self.chat_buffers[h].append(msg)
+        self.write_message_to_log("me", text, ts, h)
+
+    async def on_unmount(self):
+        self._closing = True
+        for s in list(self.sessions.values()):
+            try: await s.close()
+            except Exception: pass
+        self.sessions.clear()
+        
+        if hasattr(self, 'server') and self.server and self.server.server:
+            try:
+                self.server.server.close()
+                await self.server.server.wait_closed()
+            except Exception: pass
+            
+        if hasattr(self, 'controller') and self.controller:
+            try:
+                await asyncio.to_thread(self.controller.close)
+            except Exception: pass
+
+    async def action_quit(self):
+        import os, sys
+        os._exit(0)
+
+

tortalk-1.0.2/tortalk/ui/commands.py

@@ -0,0 +1,25 @@
+from textual.command import Provider, Hit, Hits
+
+class TorkCommandProvider(Provider):
+    async def search(self, query: str) -> Hits:
+        matcher = self.matcher(query)
+
+        title_copy = "Copy My Onion ID"
+        score_copy = matcher.match(title_copy) if query else 0
+        if not query or score_copy > 0:
+            yield Hit(
+                score_copy if query else 1.0,
+                matcher.highlight(title_copy) if query else title_copy,
+                self.app.action_copy_onion_id,
+                help="Copy your 56-character Onion ID (without .onion suffix) to system clipboard",
+            )
+
+        title_add = "Add Contact"
+        score_add = matcher.match(title_add) if query else 0
+        if not query or score_add > 0:
+            yield Hit(
+                score_add if query else 1.0,
+                matcher.highlight(title_add) if query else title_add,
+                self.app.action_prompt_add_contact,
+                help="Add a contact by pasting their 56-character onion hash (nickname auto-syncs)",
+            )

tortalk-1.0.2/tortalk/ui/modals.py

@@ -0,0 +1,75 @@
+from textual.app import ComposeResult
+from textual.screen import ModalScreen
+from textual.widgets import Input, Static
+from textual.containers import Container
+from textual import events
+from tork.config import normalize_and_validate_onion
+
+class AddContactModal(ModalScreen[str | None]):
+    """Command-palette-styled input for pasting a 56-char onion hash."""
+
+    CSS = """
+    AddContactModal {
+        align: center top;
+    }
+    AddContactModal > #palette-box {
+        width: 70%;
+        max-width: 90;
+        height: auto;
+        margin-top: 3;
+        border: thick $accent;
+        background: $surface;
+        padding: 0 0;
+    }
+    AddContactModal #onion-input {
+        border: none;
+        background: $surface;
+        width: 100%;
+        height: 3;
+    }
+    AddContactModal #hint-error {
+        color: $error;
+        background: $surface;
+        width: 100%;
+        height: auto;
+        padding: 0 1;
+        display: none;
+    }
+    AddContactModal #hint-error.visible {
+        display: block;
+    }
+    """
+
+    BINDINGS = [("escape", "cancel", "Cancel")]
+
+    def compose(self) -> ComposeResult:
+        with Container(id="palette-box"):
+            yield Input(
+                placeholder="Paste 56-character Onion ID and press Enter... (Esc to cancel)",
+                id="onion-input",
+            )
+            yield Static("Invalid Onion ID: expected 56-character base32 hash.", id="hint-error")
+
+    def on_mount(self) -> None:
+        self.query_one("#onion-input", Input).focus()
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)
+
+    def _show_error(self) -> None:
+        err = self.query_one("#hint-error", Static)
+        err.add_class("visible")
+        inp = self.query_one("#onion-input", Input)
+        inp.value = ""
+        self.set_timer(0.4, lambda: err.remove_class("visible"))
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        raw = event.value.strip()
+        if not raw:
+            self.dismiss(None)
+            return
+        is_valid, normalized, err = normalize_and_validate_onion(raw)
+        if not is_valid or len(normalized.removesuffix(".onion")) != 56:
+            self._show_error()
+            return
+        self.dismiss(normalized.removesuffix(".onion"))