glypha 2.0.0__py3-none-any.whl

glypha-2.0.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: glypha
+Version: 2.0.0
+Summary: P2P encrypted chat from raw Python sockets: E2E encryption, persistent identities, fingerprint verification, peer discovery, NAT traversal with relay fallback
+Author: Adarsh Mishra
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/<your-github-username>/<repo-name>
+Keywords: p2p,encryption,chat,sockets,nacl,networking,e2e
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pynacl>=1.5
+
+# P2P Encrypted Chat
+
+An educational peer-to-peer encrypted messaging system built from raw Python TCP sockets — custom message framing, persistent cryptographic identities, fingerprint-based peer authentication, encrypted local history, peer discovery via a cloud rendezvous server, and a measured NAT traversal experiment.
+
+This is **not** a WebRTC/PeerJS wrapper. Every layer — framing, encryption, identity, storage, discovery — is built and understood from the socket up.
+
+> ⚠️ **Educational project. Not Signal-grade security. Do not use for sensitive communications.** See [Security Model](#security-model) below.
+
+## Table of Contents
+
+- [What It Does](#what-it-does)
+- [Architecture](#architecture)
+- [Usage](#usage)
+- [The NAT Traversal Experiment](#the-nat-traversal-experiment)
+- [Security Model](#security-model)
+- [Repository Layout](#repository-layout)
+- [Testing](#testing)
+- [Bugs Found (and Fixed) Along the Way](#bugs-found-and-fixed-along-the-way)
+- [Infrastructure Notes](#infrastructure-notes)
+- [Roadmap (V2)](#roadmap-v2)
+
+## What It Does
+
+| Capability | Proof |
+|---|---|
+| Two peers chat E2E-encrypted | Verified on two physical laptops over LAN, recorded on video |
+| Identity survives restarts | Same fingerprint (`c849:a2b7...`) across every session of the build |
+| History persists, encrypted at rest | Restart → history reloads and decrypts; raw SQL shows only ciphertext |
+| Peer discovery by name | `find aadarsh` → endpoint + fingerprint, worked across two Indian carrier networks + Azure |
+| Cross-network discovery over the real Internet | Rendezvous hosted on an Azure VM; peers on home Wi-Fi (Delhi) + mobile hotspot registered and looked each other up |
+| Fingerprint verification | Both sides display fingerprints; out-of-band comparison; pre-connect verification via the registry |
+
+## Demo
+
+🎥 Two physical laptops chatting over LAN, disconnect → reconnect → history reloads.
+
+| Fingerprint verification across two screens | Rendezvous log: two peers, two public NAT IPs | Punch verdict on CGNAT |
+|---|---|---|
+| The out-of-band fingerprint check, side by side | The registry holding two different public NAT mappings (home Wi-Fi + mobile hotspot) — discovery across the real Internet | Control pass on loopback vs. failure on real CGNAT |
+
+*(Screenshots live in `screenshots/`.)*
+
+## Architecture
+
+```text
+              ┌──────────────────────┐
+              │  Rendezvous Server   │
+              │ Discovery/Signaling  │   (Azure VM, port 7000)
+              └──────────┬───────────┘
+                         │ endpoint + fingerprint
+                   ↙          ↘
+              ┌────────┐   ┌────────┐
+              │ Peer A │◄─►│ Peer B │   direct P2P chat (port 9999)
+              └────────┘   └────────┘
+```
+
+Every layer of the transport stack is implemented, not imported:
+
+```text
+Application (chat, history)
+ ↓
+Peer management (listen / connect / find / punch modes)
+ ↓
+Cryptographic identity (persistent keypairs, fingerprints)
+ ↓
+PyNaCl Box (X25519 key exchange + XSalsa20-Poly1305 AEAD)
+ ↓
+Custom framing ([4-byte big-endian length][payload])
+ ↓
+TCP sockets (blocking, threaded receive)
+ ↓
+IP / NAT / firewall
+```
+
+Local storage is a separate concern from transport: every message is passed through `SecretBox.encrypt` before being written to a SQLite `BLOB`, using a storage key that is distinct from the transport identity key.
+
+## Usage
+
+```bash
+git clone <repo> && cd p2p-chat
+pip install pynacl
+
+# terminal 1 — rendezvous server (or point at the deployed one)
+python rendezvous_server.py                 # port 7000
+
+# terminal 2 — peer A, discoverable by name
+python peer.py listen 9999 aadarsh <rv_ip>
+
+# terminal 3 — peer B finds and connects
+python peer.py find aadarsh <rv_ip>
+python peer.py connect <aadarsh-ip> 9999 ishu
+
+# NAT traversal attempt (coordinated simultaneous open)
+python peer.py punch <my_id> <peer_id> <my_port> <rv_ip>
+```
+
+Once connected, both sides display their fingerprints. Compare them out-of-band (e.g. a phone call) before trusting the session. Type `quit` to exit — history reloads automatically the next time you connect to the same peer.
+
+## The NAT Traversal Experiment
+
+This is the centerpiece of the V1 build: a real, measured attempt at direct P2P connectivity across the open Internet — not a simulated or hand-waved result.
+
+**Setup:** Rendezvous server on an Azure VM (Central India). Peer A on home Wi-Fi (`192.168.1.8` local, NAT public `122.162.151.183`). Peer B on a phone hotspot (`10.197.183.135` local behind carrier-grade NAT, NAT public `157.49.119.123`).
+
+| Test | Result |
+|---|---|
+| Baseline: uncoordinated direct dial across the Internet | ❌ `WinError 10060` timeout (~20s) — NAT drops the unsolicited inbound SYN |
+| Control: simultaneous open on loopback | ✅ Punched through — hole-punching mechanics proven correct |
+| Simultaneous open, home NAT ↔ Airtel CGNAT, 60s | ❌ Neither NAT delivered the peer's SYNs |
+
+**Conclusion:** the code is correct (the loopback control passes); the network refuses. Carrier-grade NAT shares one public IP across thousands of subscribers with endpoint-dependent mapping, which direct TCP hole punching cannot reliably defeat. This is a measured failure, explained at the NAT level, not a bug.
+
+**Fallback strategy (documented, V2):** a relay forwards already-encrypted traffic. The rendezvous/relay server never holds keys — by construction, it doesn't even have PyNaCl installed, so the "phone book" literally cannot read messages even if it wanted to.
+
+## Security Model
+
+**Protects against:**
+- Passive network observers (end-to-end AEAD encryption)
+- Peer impersonation across reconnects (persistent identities + fingerprint verification)
+- Plaintext history on disk (SQLite holds only ciphertext)
+- IP changes redefining identity (history is keyed by fingerprint, not IP)
+
+**Does NOT protect against:**
+- **No forward secrecy** — static-static ECDH means a later key compromise exposes previously recorded traffic; there is no ratchet
+- Unencrypted key files at rest
+- Replay attacks (no counters or nonces yet)
+- A malicious rendezvous server serving the wrong endpoint (fingerprint comparison mitigates this, but Trust-On-First-Use doesn't eliminate it)
+- Traffic analysis / metadata leakage
+- Machine compromise
+- `peer_id` squatting — names aren't yet bound to keys (V2 pins names to the first-registered key)
+- Implementation bugs not yet found
+
+This is an educational project. **Do not use it for sensitive real-world communications.**
+
+## Repository Layout
+
+```text
+p2p-chat/
+├── peer.py               # unified peer: listen | connect | find | punch
+├── protocol.py           # length-prefixed framing (OSError-as-EOF contract)
+├── identity.py           # persistent transport + storage keys
+├── storage.py            # encrypted SQLite history
+├── rendezvous_server.py  # discovery/signaling (port 7000, TTL 90s)
+├── crypto_test.py        # manual crypto sanity check
+├── tests/                # 19 pytest tests
+├── project.md            # living engineering doc (milestones, threat model)
+├── README.md             # this file
+└── .gitignore            # *.bin *.db *.pem __pycache__/ .pytest_cache/
+```
+
+## Testing
+
+19 automated tests across 3 files, running in ~0.53s:
+
+- **`test_protocol.py` (8 tests):** roundtrips (small/empty/binary-256), back-to-back frames in one burst, fragmented delivery (header split mid-stream), 1 MiB through a threaded reader, clean-FIN → `None`, RST → `None` (regression for the M13 shutdown bug, reproduced via `SO_LINGER(0)`)
+- **`test_storage.py` (6 tests):** roundtrip, insertion order (locks `ORDER BY id`), per-fingerprint isolation, message direction, ciphertext-at-rest (reads the raw SQL like an attacker would), wrong key → `CryptoError` (regression for the M12 key-orphaning incident)
+- **`test_identity.py` (5 tests):** key persistence, distinct identities, fingerprint stability across reloads, fingerprint format contract (16×4 hex groups; stripping colons = raw SHA-256), `SecretBox` key size
+
+```bash
+python -m pytest tests/ -v
+# 19 passed in ~0.5s
+```
+
+## Bugs Found (and Fixed) Along the Way
+
+Each of these was caught by the test suite or a real run, and each is now guarded against:
+
+- **`Peer.py` vs `peer.py`** — Windows case-insensitivity masked this; caught on the first test run and would have broken on Linux/macOS
+- **Windows `Ctrl+C` sends RST, not FIN** — the receive thread crashed with `ConnectionResetError`; fixed by treating `OSError` as EOF everywhere in `recv_message`, giving one consistent failure convention
+- **Daemon thread killed mid-print at shutdown** (`Fatal Python error: _enter_buffered_busy`) — fixed by joining the receiver thread with a 2s timeout before exit
+- **Phantom "Peer disconnected" on your own `quit`** — fixed with an `if connected:` guard
+- **Storage-key rename orphaned encrypted history** — surfaces as a loud `CryptoError` by design; now locked by a regression test
+- **`ORDER BY timestamp` scrambled messages at second-granularity** — switched to `ORDER BY id`
+- **Fingerprint gate was exact-match and rejected `"y"`** — fixed with an explicit allowlist (`yes`/`y`); anything else still fails closed
+- **Punch-mode split-brain connections** — fixed with identity-proof at accept: a connection must present the public key matching the registry fingerprint, or it's dropped
+- **Windows failed-socket reuse** — fixed by using a fresh socket per punch attempt
+- **`get_lan_ip()` originally used a TCP socket** — it would open a real connection to `8.8.8.8:80` (hanging ~20s when unreachable) instead of doing a route lookup — replaced with a UDP socket, which never sends a packet
+- **Rendezvous lookup race** — fixed with a 20s retry loop so start order no longer matters
+- **Python block-buffers stdout when redirected**, causing empty logs on an otherwise healthy server — fixed by running with `python3 -u`
+
+## Infrastructure Notes
+
+Real cloud/ops lessons from deploying the rendezvous server:
+
+- **Azure for Students** has region allowlist restrictions (`RequestDisallowedByAzure`) and a B-series vCPU quota of 0 in some regions; worked around with a `B2ats_v2` instance (~$0.0062/hr). No auto-shutdown was available in-region, so a manual portal-stop discipline plus a $15 budget alert was used instead.
+- Two independent firewall layers must both be opened for the server to be reachable: the cloud Network Security Group **and** the OS-level `ufw`.
+- A VM restart kills running processes but not files, so the server is started with `nohup python3 -u rendezvous_server.py &` every time; `pgrep` is checked first to avoid stale double instances (which caused a confusing false failure once).
+- MinTTY/Git Bash swallows `Ctrl+C` for console-less programs — use `winpty`.
+- The VM's public IP can change on deallocate, so it's always re-read from the Azure portal rather than assumed.
+- The rendezvous server records the **observed** source IP of a connecting peer (which can't be lied to) alongside the **peer-advertised** listen port (which it has no way to independently verify). Registering via `127.0.0.1` poisons the registry — the same observed-vs-advertised mechanism is what later reveals real NAT public mappings.
+
+## Roadmap (V2)
+
+- **Relay implementation** — the fallback for when punching fails; already-encrypted traffic is relayed, and the rendezvous server is upgraded to hand out relay info. This is what makes cross-Internet chat work reliably, not just when NAT cooperates.
+- **Packaging** — a `pyproject.toml` and a PyPI release, so usage becomes `pip install <name>` followed by `p2pchat listen --name aadarsh` / `p2pchat connect aadarsh`, with no files, ports, or internals exposed to the end user.
+- **Auto-fallback chain** — direct → punch → relay, orchestrated by a connection state machine.
+- **Name pinning** — first registration binds a `peer_id` to a public key, closing the squatting gap.
+- **Hardening** — `MAX_MESSAGE_SIZE`, replay counters, heartbeats/timeouts, and key-file permissions.
+
+---
+
+*Stack: Python 3.13, stdlib `socket`/`threading`/`struct`/`sqlite3`/`json`, PyNaCl (libsodium bindings), pytest. No frameworks. ~5 core modules + rendezvous server, 19 automated tests, 15 milestones, ~4 weeks of build time.*

glypha-2.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+identity.py,sha256=harESp118v8-3CEc2r5bXqfffJ4P5i0js5fNHzJJnTo,733
+peer.py,sha256=IwQRcx0F9yL0spqjQjZTwIG7JAQ8sLdRGVk1eIzyDto,25642
+protocol.py,sha256=uPNzyuO0paH9_IXnvEqTLuXYRRHpQdLv1nZ5aj9k29g,1111
+relay_server.py,sha256=9ThbZLjFcyrmcHUVK2hzk6TrfHahM6Olg7tT_e9iDvE,3538
+rendezvous_server.py,sha256=EbD8LTFeo1uP4X5GSdRQPNCUDfRlOVYgR1xpOWEU17U,3241
+storage.py,sha256=1ePEHII16LOWGC8IyjqhU5QRQGcAGoUSuYq7UrOtmuQ,1857
+glypha-2.0.0.dist-info/METADATA,sha256=4t0biKOD_oDeyjEq2wkzvrKneQtXtcv8BMT6EjtGMTY,13428
+glypha-2.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+glypha-2.0.0.dist-info/entry_points.txt,sha256=ENdd3OVmQlfAXnTYJpib9HmJW18ouD7yvtwasmnYRBo,113
+glypha-2.0.0.dist-info/top_level.txt,sha256=KoM1JsBdoBDFpuAMhoUmGeny9twuq0drOoP846bT-vM,62
+glypha-2.0.0.dist-info/RECORD,,

glypha-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

glypha-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+glypha = peer:main
+glypha-relay = relay_server:main
+glypha-rendezvous = rendezvous_server:main

glypha-2.0.0.dist-info/top_level.txt

@@ -0,0 +1,6 @@
+identity
+peer
+protocol
+relay_server
+rendezvous_server
+storage

identity.py

@@ -0,0 +1,31 @@
+import os
+
+from nacl.public import PrivateKey
+from nacl.secret import SecretBox
+from nacl.utils import random
+
+def load_or_create_key(filename):
+    if os.path.exists(filename):
+        with open(filename, "rb") as file:
+            key_bytes = file.read()
+
+        return PrivateKey(key_bytes)
+
+    privateKey = PrivateKey.generate() 
+
+    with open(filename, "wb") as file:
+        file.write(bytes(privateKey))
+
+    return privateKey
+
+def load_or_create_secret_key(filename):
+    if os.path.exists(filename):
+        with open(filename, "rb") as file:
+            return file.read()
+
+    key = random(SecretBox.KEY_SIZE)
+
+    with open(filename, "wb") as file:
+        file.write(key)
+
+    return key

peer.py

@@ -0,0 +1,652 @@
+# peer.py — unified P2P encrypted chat peer.
+# Modes: listen | connect | find | punch | relay | chat
+# "chat" is the product command: direct -> punch -> relay, automatic.
+
+import socket
+import threading
+import sys
+import hashlib
+import json
+import base64
+import time
+
+from nacl.public import PrivateKey, PublicKey, Box
+from nacl.secret import SecretBox
+from protocol import recv_message, send_message
+from identity import load_or_create_key, load_or_create_secret_key
+from storage import init_db, save_message, load_messages
+
+RENDEZVOUS_PORT = 7000
+RENDEZVOUS_REFRESH = 30   # server TTL is 90s; refresh at 1/3 of TTL
+RELAY_PORT = 7001
+
+
+# ───────────────────────── helpers ─────────────────────────
+
+def get_lan_ip():
+    """Our LAN IP via a UDP route lookup — no packet is ever sent.
+    (A TCP socket here would open a real connection to 8.8.8.8:80.)"""
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.connect(("8.8.8.8", 80))
+        ip = s.getsockname()[0]
+    except OSError:
+        ip = "127.0.0.1"
+    finally:
+        s.close()
+    return ip
+
+
+def format_fingerprint(public_bytes):
+    """SHA-256 of a public key, grouped 4-hex-chunks — the string
+    two humans compare out-of-band to authenticate each other."""
+    fp = hashlib.sha256(public_bytes).hexdigest()
+    return ":".join(fp[i:i + 4] for i in range(0, len(fp), 4))
+
+
+def punch_port_for(name):
+    """Deterministic per-name port (20000-39999): two peers on one machine
+    never collide, and an identity always punches from the same port."""
+    h = int(hashlib.sha256(name.encode()).hexdigest(), 16)
+    return 20000 + (h % 20000)
+
+
+def handshake(sock, private_key, initiator):
+    """Exchange public keys and build the Box.
+    initiator=True  -> send ours first, then receive theirs
+    initiator=False -> receive theirs first, then send ours
+    Returns (box, peer_fingerprint) or (None, None) on disconnect."""
+    own_public = bytes(private_key.public_key)
+    if initiator:
+        send_message(sock, own_public)
+        peer_bytes = recv_message(sock)
+    else:
+        peer_bytes = recv_message(sock)
+        send_message(sock, own_public)
+    if peer_bytes is None:
+        return None, None
+    box = Box(private_key, PublicKey(peer_bytes))
+    return box, format_fingerprint(peer_bytes)
+
+
+def verify_fingerprints(own_fp, peer_fp):
+    """Manual out-of-band verification (TOFU): the human compares the
+    two fingerprints (e.g. on a phone call) and confirms."""
+    print("Your fingerprint:", own_fp)
+    print("Peer fingerprint:", peer_fp)
+    answer = input("Confirm peer fingerprint matches out-of-band (yes/no): ")
+    return answer.lower() in ("yes", "y")
+
+
+KNOWN_PEERS_FILE = "known_peers.json"   # local trust pins — gitignored
+
+def load_known_peers():
+    try:
+        with open(KNOWN_PEERS_FILE) as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def pin_peer(name, fingerprint):
+    known = load_known_peers()
+    known[name] = fingerprint
+    with open(KNOWN_PEERS_FILE, "w") as f:
+        json.dump(known, f, indent=2)
+
+def verify_or_reject(own_fp, peer_fp, expected_fp, peer_name=None):
+    """Trust model (SSH known_hosts style):
+    - pinned before?  auto-verify against the PIN, not the registry.
+      A changed key = loud warning + reject (possible impersonation).
+    - first contact?  the human verifies out-of-band — the real TOFU
+      moment — then we pin for all future contacts.
+    expected_fp (registry) is only a cross-check, never a trust source."""
+    clean = peer_fp.replace(":", "")
+    pinned = load_known_peers().get(peer_name) if peer_name else None
+
+    if pinned:
+        if clean == pinned.replace(":", ""):
+            print(f"[chat] '{peer_name}' verified against pinned key")
+            return True
+        print(f"[chat] KEY CHANGE for '{peer_name}'!")
+        print(f"       pinned: {pinned}")
+        print(f"       got:    {peer_fp}")
+        print("[chat] possible impersonation — rejecting.")
+        return False
+
+    # first contact: the human decides, then we pin
+    if verify_fingerprints(own_fp, peer_fp):
+        if peer_name:
+            pin_peer(peer_name, clean)
+            print(f"[chat] pinned '{peer_name}' for future auto-verification")
+        return True
+    return False
+
+
+# ───────────────────────── chat (shared by every mode) ─────────────────────────
+
+def chat(sock, box, peer_fp, name):
+    """The conversation loop: load history, run a receive thread and an
+    input/send loop, store every message encrypted, exit cleanly."""
+    storage_key = load_or_create_secret_key(f"{name}_storage_key.bin")
+    secret_box = SecretBox(storage_key)
+    db_filename = f"{name}_history.db"
+
+    init_db(db_filename)
+
+    for direction, text, timestamp in load_messages(db_filename, peer_fp, secret_box):
+        print(f"{'You' if direction == 'sent' else 'Them'}: {text}")
+
+    print("Secure connection established!")
+
+    connected = True
+
+    def receive_loop():
+        nonlocal connected
+        while True:
+            data = recv_message(sock)
+            if data is None:
+                if connected:   # announce only if WE didn't initiate the close
+                    print("\nPeer disconnected.")
+                connected = False
+                break
+            try:
+                message = box.decrypt(data).decode()
+            except Exception:
+                print("\nReceived an undecryptable frame — ignored.")
+                continue
+            save_message(db_filename, peer_fp, "received", message, secret_box)
+            print("Them:", message)
+
+    receiver = threading.Thread(target=receive_loop, daemon=True)
+    receiver.start()
+
+    while connected:
+        try:
+            message = input(f"{name}: ")
+        except KeyboardInterrupt:
+            break
+        if not connected:
+            print("Peer is gone.")
+            break
+        if message == "quit":
+            break
+        if not message.strip():    # bare Enter / whitespace: send nothing
+            continue
+        try:
+            send_message(sock, box.encrypt(message.encode()))
+        except OSError:
+            print("Peer is gone.")
+            break
+        save_message(db_filename, peer_fp, "sent", message, secret_box)
+
+    # Mark closed before closing the socket (no phantom "Peer disconnected."
+    # from our own close), then join the receiver: a daemon thread killed
+    # mid-print at shutdown can deadlock stdout (_enter_buffered_busy).
+    connected = False
+    sock.close()
+    receiver.join(timeout=2)
+
+
+# ───────────────────────── rendezvous client ─────────────────────────
+
+def rendezvous_register(private_key, name, listen_port, rv_host):
+    """Publish our name + listen port + public key. The socket is bound
+    to our listen port so the server observes the NAT mapping for it.
+    Returns the response dict, or None if unreachable."""
+    request = {
+        "type": "register",
+        "id": name,
+        "listen_port": listen_port,
+        "public_key": base64.b64encode(bytes(private_key.public_key)).decode(),
+    }
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind(("0.0.0.0", listen_port))
+        sock.settimeout(5)
+        sock.connect((rv_host, RENDEZVOUS_PORT))
+        send_message(sock, json.dumps(request).encode())
+        resp = recv_message(sock)
+        sock.close()
+        return json.loads(resp.decode()) if resp else None
+    except OSError:
+        return None
+
+
+def rendezvous_lookup(peer_id, rv_host):
+    """Ask the rendezvous where a peer is. Returns response dict or None."""
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(5)
+        sock.connect((rv_host, RENDEZVOUS_PORT))
+        send_message(sock, json.dumps({"type": "lookup", "id": peer_id}).encode())
+        resp = recv_message(sock)
+        sock.close()
+        return json.loads(resp.decode()) if resp else None
+    except OSError:
+        return None
+
+
+def rendezvous_refresh_loop(private_key, name, listen_port, rv_host):
+    """Re-register every 30s so the 90s TTL never expires while we run."""
+    while True:
+        time.sleep(RENDEZVOUS_REFRESH)
+        if rendezvous_register(private_key, name, listen_port, rv_host) is None:
+            print("[rendezvous] refresh failed — will retry")
+
+
+# ───────────────────────── explicit modes (internals) ─────────────────────────
+
+def listen_mode(port, name, rv_host=None):
+    """Wait for one inbound peer, then chat. Optional rendezvous
+    registration makes us discoverable by name."""
+    private_key = load_or_create_key(f"{name}_key.bin")
+    own_fp = format_fingerprint(bytes(private_key.public_key))
+
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.bind(("0.0.0.0", port))
+    server.listen()
+
+    print("Your fingerprint:", own_fp)
+    print(f"Listening on 0.0.0.0:{port}")
+    print(f"Other peer connects with: glypha connect {get_lan_ip()} {port} <their-name>")
+
+    if rv_host:
+        # discovery is optional infrastructure: if it's down, chat still works
+        resp = rendezvous_register(private_key, name, port, rv_host)
+        print(f"[rendezvous] registered — discoverable as '{name}'") if resp \
+            else print("[rendezvous] registration failed (continuing without discovery)")
+        threading.Thread(
+            target=rendezvous_refresh_loop,
+            args=(private_key, name, port, rv_host),
+            daemon=True,
+        ).start()
+
+    sock, address = server.accept()
+    server.close()   # one session per run; multi-session accept loop is future work
+    print("Peer connected:", address)
+
+    box, peer_fp = handshake(sock, private_key, initiator=False)
+    if box is None:
+        print("Peer disconnected during handshake.")
+        return
+    if not verify_fingerprints(own_fp, peer_fp):
+        print("Fingerprint not verified — closing.")
+        sock.close()
+        return
+    chat(sock, box, peer_fp, name)
+
+
+def connect_mode(host, port, name):
+    """Dial a known host:port directly, then chat."""
+    private_key = load_or_create_key(f"{name}_key.bin")
+    own_fp = format_fingerprint(bytes(private_key.public_key))
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.connect((host, port))
+    print(f"Connected to {host}:{port}")
+
+    box, peer_fp = handshake(sock, private_key, initiator=True)
+    if box is None:
+        print("Peer disconnected during handshake.")
+        return
+    if not verify_fingerprints(own_fp, peer_fp):
+        print("Fingerprint not verified — closing.")
+        sock.close()
+        return
+    chat(sock, box, peer_fp, name)
+
+
+def find_mode(peer_id, rv_host):
+    """One-shot discovery: print where a peer is + its fingerprint."""
+    result = rendezvous_lookup(peer_id, rv_host)
+    if result is None:
+        print(f"Rendezvous server at {rv_host}:{RENDEZVOUS_PORT} unreachable")
+        return
+    if result.get("status") == "found":
+        print(f"Peer '{peer_id}' is at {result['ip']}:{result['port']}")
+        print(f"Fingerprint: {result['fingerprint']}")
+        print("Verify this fingerprint with the peer out-of-band, then:")
+        print(f"  glypha connect {result['ip']} {result['port']} <your-name>")
+    else:
+        print(f"'{peer_id}' not found (never registered, or entry expired)")
+
+
+def punch_mode(my_id, peer_id, my_port, rv_host):
+    """Manual NAT-traversal attempt (debug/teaching mode): register,
+    find the peer, run the simultaneous open, chat on success."""
+    private_key = load_or_create_key(f"{my_id}_key.bin")
+    own_public = bytes(private_key.public_key)
+    own_fp = format_fingerprint(own_public)
+
+    if rendezvous_register(private_key, my_id, my_port, rv_host) is None:
+        print("Rendezvous unreachable — cannot punch")
+        return
+
+    target = None
+    dl = time.time() + 20   # peer may still be registering
+    while time.time() < dl:
+        target = rendezvous_lookup(peer_id, rv_host)
+        if target and target.get("status") == "found":
+            break
+        time.sleep(1)
+    if target is None or target.get("status") != "found":
+        print(f"'{peer_id}' never registered within 20s")
+        return
+
+    t_ip = target["ip"]
+    t_port = target.get("punch_port") or target["port"]
+    peer_fp_clean = target["fingerprint"].replace(":", "")
+    i_am_connector = own_fp.replace(":", "") < peer_fp_clean   # deterministic roles
+
+    print(f"Punching {t_ip}:{t_port} for 60s — start the other side too!")
+    print("My role:", "connector (I dial)" if i_am_connector else "accepter (I wait)")
+
+    result = _punch_socket(private_key, own_public, t_ip, t_port,
+                           peer_fp_clean, i_am_connector, my_port, 60)
+    if result is None:
+        print("Punch failed after 60s — that is the measured result. Screenshot it.")
+        return
+
+    winner, peer_public = result
+    print("PUNCHED THROUGH!", winner.getsockname(), "->", winner.getpeername())
+    chat(winner, Box(private_key, PublicKey(peer_public)),
+         format_fingerprint(peer_public), my_id)
+
+
+def _punch_socket(private_key, own_public, t_ip, t_port, peer_fp_clean,
+                  i_am_connector, my_port, window_s):
+    """Simultaneous-open core. Connector repeatedly dials the peer's public
+    punch endpoint FROM our punch port; accepter waits for inbound on it.
+    Identity-proof at accept: a connection must present the public key
+    matching the registry fingerprint, or it is dropped. Returns
+    (sock, peer_public_bytes) or None."""
+    verified = []
+    listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    listener.bind(("0.0.0.0", my_port))
+    listener.listen()
+
+    deadline = time.time() + window_s
+
+    def try_accept():
+        while time.time() < deadline and not verified:
+            try:
+                conn, _ = listener.accept()
+            except OSError:
+                return
+            proof = recv_message(conn)
+            if proof is not None and hashlib.sha256(proof).hexdigest() == peer_fp_clean:
+                verified.append((conn, proof))
+            else:
+                conn.close()   # junk, stale attempt, or duplicate process
+
+    threading.Thread(target=try_accept, daemon=True).start()
+
+    winner = None
+    while time.time() < deadline and winner is None:
+        if i_am_connector:
+            # fresh socket per attempt: Windows retires a socket after a
+            # failed connect, and retrying on it would fail forever
+            s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            s.bind(("0.0.0.0", my_port))   # THE punch: same local port every attempt
+            s.settimeout(2)
+            try:
+                s.connect((t_ip, t_port))
+                send_message(s, own_public)   # identify ourselves IMMEDIATELY
+                winner = s
+            except OSError:
+                pass
+        elif verified:
+            winner = verified[0][0]
+            break
+        time.sleep(0.5)
+
+    listener.close()
+    if winner is None:
+        return None
+
+    winner.settimeout(None)   # chat sockets must block, not time out
+
+    if i_am_connector:
+        peer_bytes = recv_message(winner)   # accepter answers with its key
+        if peer_bytes is None or hashlib.sha256(peer_bytes).hexdigest() != peer_fp_clean:
+            winner.close()
+            return None
+        peer_public = peer_bytes
+    else:
+        send_message(winner, own_public)    # answer the proof
+        peer_public = verified[0][1]        # already verified at accept
+
+    return winner, peer_public
+
+
+def relay_mode(my_name, peer_name, relay_host):
+    """Manual relay chat (debug/teaching mode)."""
+    result = _relay_socket(my_name, peer_name, relay_host)
+    if result is None:
+        return
+    sock, box, peer_fp = result
+    private_key = load_or_create_key(f"{my_name}_key.bin")
+    if not verify_fingerprints(format_fingerprint(bytes(private_key.public_key)), peer_fp):
+        print("Fingerprint not verified — closing.")
+        sock.close()
+        return
+    chat(sock, box, peer_fp, my_name)
+
+
+def _relay_socket(my_name, peer_name, relay_host):
+    """Join the relay and handshake through the pipe. Join protocol:
+    both peers send {id, target}; when they name each other mutually the
+    relay splices the sockets. Only the SECOND joiner gets a 'matched'
+    reply — the first joiner's very next bytes are the peer's handshake
+    key through the pipe (transparent from splice onward).
+    Returns (sock, box, peer_fp) or None."""
+    private_key = load_or_create_key(f"{my_name}_key.bin")
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(15)
+    try:
+        sock.connect((relay_host, RELAY_PORT))
+    except OSError:
+        return None
+
+    send_message(sock, json.dumps(
+        {"type": "relay_join", "id": my_name, "target": peer_name}).encode())
+
+    resp_raw = recv_message(sock)
+    if resp_raw is None:
+        sock.close()
+        return None
+    status = json.loads(resp_raw.decode()).get("status")
+    if status not in ("waiting", "matched"):
+        sock.close()
+        return None
+
+    # waiting -> joined first  -> handshake responder
+    # matched -> joined second -> handshake initiator
+    sock.settimeout(120)   # bounded wait for the peer; not forever
+    box, peer_fp = handshake(sock, private_key, initiator=(status == "matched"))
+    if box is None:
+        sock.close()
+        return None
+    sock.settimeout(None)  # chat must block again
+    return sock, box, peer_fp
+
+
+# ───────────────────── V2.3: chat mode (the product command) ─────────────────────
+
+def try_direct(host, port, private_key, own_fp, expected_fp, peer_name):
+    """Ladder rung 1: dial the rendezvous-published endpoint directly
+    (works on LAN / public endpoints). Returns (sock, box, peer_fp) or None."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(8)   # fast fail — a dead NAT path must not stall the ladder
+    try:
+        sock.connect((host, port))
+    except OSError:
+        return None
+    sock.settimeout(None)
+
+    box, peer_fp = handshake(sock, private_key, initiator=True)
+    if box is None:
+        return None
+    if not verify_or_reject(own_fp, peer_fp, expected_fp, peer_name):
+        sock.close()
+        return None
+    return sock, box, peer_fp
+
+
+def try_punch(my_name, peer_name, private_key, own_fp, rv_host, expected_fp):
+    """Ladder rung 2: coordinated simultaneous open with shortened windows
+    so hostile NATs reach the relay quickly. Returns (sock, box, peer_fp) or None."""
+    my_port = punch_port_for(my_name)
+    own_public = bytes(private_key.public_key)
+
+    if rendezvous_register(private_key, my_name, my_port, rv_host) is None:
+        return None
+
+    target = None
+    dl = time.time() + 10   # peer is walking the same ladder; give them time to register
+    while time.time() < dl:
+        target = rendezvous_lookup(peer_name, rv_host)
+        if target and target.get("status") == "found":
+            break
+        time.sleep(1)
+    if target is None or target.get("status") != "found":
+        return None
+
+    t_ip = target["ip"]
+    t_port = target.get("punch_port") or target["port"]
+    peer_fp_clean = target["fingerprint"].replace(":", "")
+    i_am_connector = own_fp.replace(":", "") < peer_fp_clean
+
+    result = _punch_socket(private_key, own_public, t_ip, t_port,
+                           peer_fp_clean, i_am_connector, my_port, 15)
+    if result is None:
+        return None
+
+    winner, peer_public = result
+    peer_fp = format_fingerprint(peer_public)
+    if not verify_or_reject(own_fp, peer_fp, expected_fp, peer_name):
+        winner.close()
+        return None
+    return winner, Box(private_key, PublicKey(peer_public)), peer_fp
+
+
+def try_relay(my_name, peer_name, private_key, own_fp, rv_host, expected_fp):
+    """Ladder rung 3: the always-works path (V2.1). Returns (sock, box, peer_fp) or None."""
+    result = _relay_socket(my_name, peer_name, rv_host)
+    if result is None:
+        return None
+    sock, box, peer_fp = result
+    if not verify_or_reject(own_fp, peer_fp, expected_fp, peer_name):
+        sock.close()
+        return None
+    return sock, box, peer_fp
+
+
+def chat_mode(my_name, peer_name, rv_host):
+    """The product command: one command in, a verified encrypted chat out.
+    Ladder: direct -> punch -> relay. The user never chooses a transport
+    and never sees a traceback."""
+    private_key = load_or_create_key(f"{my_name}_key.bin")
+    own_fp = format_fingerprint(bytes(private_key.public_key))
+
+    print(f"[chat] reaching '{peer_name}' via {rv_host}...")
+
+    # ONE lookup up front: drives rung 1 AND rendezvous-assisted verification
+    info = rendezvous_lookup(peer_name, rv_host)
+    expected_fp = None
+    result = None
+
+    if info is not None and info.get("status") == "found":
+        expected_fp = info.get("fingerprint")
+        print(f"[chat] trying direct connection to {info['ip']}:{info['port']}...")
+        result = try_direct(info["ip"], info["port"], private_key, own_fp, expected_fp, peer_name)
+        if result is None:
+            print("[chat] direct failed — trying NAT traversal...")
+    else:
+        print(f"[chat] '{peer_name}' not in rendezvous — skipping direct, trying traversal...")
+
+    if result is None:
+        result = try_punch(my_name, peer_name, private_key, own_fp, rv_host, expected_fp)
+        if result is None:
+            print("[chat] traversal failed — falling back to relay...")
+
+    if result is None:
+        result = try_relay(my_name, peer_name, private_key, own_fp, rv_host, expected_fp)
+        if result is None:
+            print(f"[chat] could not reach '{peer_name}'.")
+            print(f"       Are they running:  glypha chat{peer_name} {my_name} {rv_host}")
+            return
+
+    sock, box, peer_fp = result
+    print("[chat] connected!")
+    chat(sock, box, peer_fp, my_name)
+
+
+# ───────────────────────── dispatch ─────────────────────────
+
+def main():
+    if len(sys.argv) < 2:
+        print("usage:")
+        print("  glypha chat <my_name> <peer_name> [rv_host]   # product command")
+        print("  glypha listen [port] [name] [rv_host]")
+        print("  glypha connect <host> [port] [name]")
+        print("  glypha find <peer_id> [rv_host]")
+        print("  glypha punch <my_id> <peer_id> [my_port] [rv_host]")
+        print("  glypha relay <my_id> <peer_id> <relay_host>")
+        sys.exit(1)
+
+    mode = sys.argv[1]
+
+    if mode == "listen":
+        port = int(sys.argv[2]) if len(sys.argv) > 2 else 9999
+        name = sys.argv[3] if len(sys.argv) > 3 else "peer"
+        rv_host = sys.argv[4] if len(sys.argv) > 4 else None
+        listen_mode(port, name, rv_host)
+
+    elif mode == "connect":
+        if len(sys.argv) < 3:
+            print("connect requires a host"); sys.exit(1)
+        host = sys.argv[2]
+        port = int(sys.argv[3]) if len(sys.argv) > 3 else 9999
+        name = sys.argv[4] if len(sys.argv) > 4 else "peer"
+        connect_mode(host, port, name)
+
+    elif mode == "find":
+        if len(sys.argv) < 3:
+            print("find requires a peer id"); sys.exit(1)
+        find_mode(sys.argv[2], sys.argv[3] if len(sys.argv) > 3 else "127.0.0.1")
+
+    elif mode == "punch":
+        if len(sys.argv) < 4:
+            print("usage: glypha punch <my_id> <peer_id> [my_port] [rv_host]")
+            sys.exit(1)
+        my_id, peer_id = sys.argv[2], sys.argv[3]
+        my_port = int(sys.argv[4]) if len(sys.argv) > 4 else 9999
+        rv = sys.argv[5] if len(sys.argv) > 5 else "127.0.0.1"
+        punch_mode(my_id, peer_id, my_port, rv)
+
+    elif mode == "relay":
+        if len(sys.argv) < 5:
+            print("usage: glypha relay <my_id> <peer_id> <relay_host>")
+            sys.exit(1)
+        relay_mode(sys.argv[2], sys.argv[3], sys.argv[4])
+
+    elif mode == "chat":
+        if len(sys.argv) < 4:
+            print("usage: glypha chat <my_name> <peer_name> [rv_host]")
+            sys.exit(1)
+        rv = sys.argv[4] if len(sys.argv) > 4 else "127.0.0.1"
+        chat_mode(sys.argv[2], sys.argv[3], rv)
+
+    else:
+        print("unknown mode:", mode)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

protocol.py

@@ -0,0 +1,42 @@
+import struct
+
+def send_message(sock, data):
+
+    #get no of length of data
+    length = len(data)
+
+    #convert length in 4 bytes
+    header = struct.pack("!I", length)
+
+    #send header first
+    sock.sendall(header)    #!sendall() keeps sending until all the provided data has been sent, or an error occurs.
+
+    #send the real meaasge
+    sock.sendall(data)
+
+
+def recv_message(sock):
+    try:
+        header = b""
+        while len(header) < 4:
+            chunk = sock.recv(4 - len(header))
+            if not chunk:
+                return None
+            header += chunk
+
+        length = struct.unpack("!I", header)[0]
+
+        data = b""
+        while len(data) < length:
+            chunk = sock.recv(length - len(data))
+            if not chunk:
+                return None
+            data += chunk
+
+        return data
+
+    except OSError:
+        # ConnectionResetError (WinError 10054), BrokenPipeError,
+        # timeouts — connection is dead or unusable. Report it
+        # exactly like a clean EOF so callers have ONE convention.
+        return None

relay_server.py

@@ -0,0 +1,106 @@
+# Relay server: splices two peers' outbound connections into a pipe.
+# Copies opaque bytes. No parsing, no decryption, no keys — the VM
+# doesn't even have PyNaCl installed. Port 7001 (rendezvous is 7000).
+# Known limitation (V2 hardening): a waiting entry whose peer never
+# joins stays in memory until the relay restarts.
+
+import socket
+import threading
+import json
+
+from protocol import send_message, recv_message
+
+HOST = "0.0.0.0"
+PORT = 7001
+
+waiting = {}          # id -> (socket, target_they_are_waiting_for)
+lock = threading.Lock()
+
+
+def pump(src, dst):
+    """Copy raw bytes src -> dst until either side dies."""
+    try:
+        while True:
+            data = src.recv(4096)
+            if not data:
+                break
+            dst.sendall(data)
+    except OSError:
+        pass
+    finally:
+        try: src.close()
+        except OSError: pass
+        try: dst.close()
+        except OSError: pass
+
+
+def handle(conn, addr):
+    spliced = False
+    registered = False
+    try:
+        data = recv_message(conn)
+        if data is None:
+            return
+        req = json.loads(data.decode())
+        if req.get("type") != "relay_join" or not req.get("id") or not req.get("target"):
+            send_message(conn, json.dumps({"status": "bad_request"}).encode())
+            return
+
+        my_id, target = req["id"], req["target"]
+
+        with lock:
+            rec = waiting.get(target)
+            if rec and rec[1] == my_id:
+                # mutual match: they were waiting for ME by name
+                waiting.pop(target)
+                peer_conn = rec[0]
+            else:
+                # no match yet — register and wait (keeps socket open)
+                waiting[my_id] = (conn, target)
+                registered = True
+                peer_conn = None
+
+        if peer_conn is not None:
+            spliced = True
+            # tell ONLY the second joiner; the first joiner's next bytes
+            # are the second's handshake key (transparent pipe from here)
+            send_message(conn, json.dumps({"status": "matched"}).encode())
+            print(f"[relay] spliced {target} <-> {my_id}")
+            threading.Thread(target=pump, args=(peer_conn, conn), daemon=True).start()
+            threading.Thread(target=pump, args=(conn, peer_conn), daemon=True).start()
+        else:
+            send_message(conn, json.dumps({"status": "waiting"}).encode())
+            print(f"[relay] {my_id} waiting for {target}")
+
+    except (json.JSONDecodeError, UnicodeDecodeError, OSError):
+        try:
+            send_message(conn, json.dumps({"status": "bad_request"}).encode())
+        except OSError:
+            pass
+    finally:
+        # close ONLY sockets we never handed off. Waiting sockets belong
+        # to the registry; spliced sockets belong to the pump threads.
+        if not (spliced or registered):
+            try:
+                conn.close()
+            except OSError:
+                pass
+
+
+def main():
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    server.bind((HOST, PORT))
+    server.listen()
+    print(f"Relay server on {HOST}:{PORT}")
+
+    while True:
+        conn, addr = server.accept()
+        threading.Thread(target=handle, args=(conn, addr), daemon=True).start()
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\nRelay stopped.")

rendezvous_server.py

@@ -0,0 +1,99 @@
+import socket
+import threading
+import json
+import time
+import hashlib
+import base64
+
+from protocol import send_message, recv_message
+
+HOST = "0.0.0.0"
+PORT = 7000
+TTL = 90  # seconds — peers refresh every 30s
+
+peers = {}  # peer_id -> record
+registry_lock = threading.Lock()
+
+
+def prune_expired():
+    now = time.time()
+    for pid in [p for p, r in peers.items() if now - r["last_seen"] > TTL]:
+        del peers[pid]
+        print(f"[expiry] {pid} removed (stale > {TTL}s)")
+
+
+def handle(conn, addr):
+    try:
+        data = recv_message(conn)
+        if data is None:
+            return
+
+        try:
+            request = json.loads(data.decode())
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            send_message(conn, json.dumps({"status": "bad_request"}).encode())
+            return
+
+        rtype = request.get("type")
+
+        if rtype == "register":
+            peer_id = request.get("id")
+            listen_port = request.get("listen_port")
+            public_key_b64 = request.get("public_key")
+
+            if not peer_id or not listen_port or not public_key_b64:
+                send_message(conn, json.dumps({"status": "bad_request"}).encode())
+                return
+
+            fp = hashlib.sha256(base64.b64decode(public_key_b64)).hexdigest()
+            fingerprint = ":".join(fp[i:i + 4] for i in range(0, len(fp), 4))
+
+            with registry_lock:
+                peers[peer_id] = {
+                    "ip": addr[0],
+                    "listen_port": listen_port,
+                    "observed_port": addr[1],    # NEW: NAT's external port for THIS peer's listen port
+                    "public_key": public_key_b64,
+                    "fingerprint": fingerprint,
+                    "last_seen": time.time(),
+                }
+            print(f"[register] {peer_id} {addr[0]}:{listen_port} fp={fingerprint[:19]}...")
+            send_message(conn, json.dumps({"status": "registered", "ttl": TTL}).encode())
+
+        elif rtype == "lookup":
+            with registry_lock:
+                prune_expired()
+                rec = peers.get(request.get("id"))
+            if rec:
+                response = {
+                    "status": "found",
+                    "ip": rec["ip"],
+                    "port": rec["listen_port"],
+                    "punch_port": rec["observed_port"],   # NEW
+                    "fingerprint": rec["fingerprint"],
+                }
+            else:
+                response = {"status": "not_found"}
+            send_message(conn, json.dumps(response).encode())
+
+        else:
+            send_message(conn, json.dumps({"status": "unknown_type"}).encode())
+
+    finally:
+        conn.close()
+
+
+def main():
+    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)  # restart without TIME_WAIT errors
+    server.bind((HOST, PORT))
+    server.listen()
+    print(f"Rendezvous server on {HOST}:{PORT} (TTL {TTL}s)")
+
+    while True:
+        conn, addr = server.accept()
+        threading.Thread(target=handle, args=(conn, addr), daemon=True).start()
+
+
+if __name__ == "__main__":
+    main()

storage.py

@@ -0,0 +1,80 @@
+import sqlite3
+
+def init_db(filename):
+    connection = sqlite3.connect(filename)
+
+    connection.execute("""
+        CREATE TABLE IF NOT EXISTS messages(
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        fingerprint TEXT NOT NULL,
+        direction TEXT NOT NULL,
+        text TEXT NOT NULL,
+        timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
+        )
+    """)
+    connection.commit()
+    connection.close()
+
+def save_message(filename, fingerprint, direction, text, box):
+    connection = sqlite3.connect(filename)
+
+    encrypted = box.encrypt(text.encode())
+
+    connection.execute(
+        """
+        INSERT INTO messages (fingerprint, direction, text)
+        VALUES(?, ?, ?)
+        """,
+        (fingerprint, direction, encrypted)
+    )
+    connection.commit()
+    connection.close()
+
+def load_messages(filename, fingerprint, box):
+    connection = sqlite3.connect(filename)
+
+    cursor = connection.execute(
+        """
+        SELECT direction, text, timestamp
+        FROM messages
+        WHERE fingerprint = ?
+        ORDER BY id
+        """,
+        (fingerprint,)
+    )
+    rows = cursor.fetchall()
+    connection.close()
+    messages = []
+
+    for direction, encrypted_text, timestamp in rows:
+        text = box.decrypt(encrypted_text).decode()
+
+        messages.append(
+            (direction, text, timestamp)
+        )
+
+
+    return messages
+
+
+
+
+
+
+# ! for test
+
+# if __name__ == "__main__":
+#     db = "test_history.db"
+
+#     fingerprint = "A1B2:C3D4:E5F6"
+
+#     init_db(db)
+
+#     save_message(db, fingerprint, "sent", "Hello!")
+#     save_message(db, fingerprint, "received", "Hey!")
+#     save_message(db, fingerprint, "sent", "How are you?")
+
+#     messages = load_messages(db, fingerprint)
+
+#     for message in messages:
+#         print(message)