Building End-to-End Encrypted Terminal Sharing | ThinkNCollab Engineering ThinkNCollab Blog

How ThinkNCollab engineered Zero-Knowledge, End-to-End Encrypted (E2EE) live terminal sharing using X25519 ECDH, HKDF key derivation, and AES-256-GCM so relay servers never see plaintext keystrokes or production credentials.

<p class="lead" style="font-size: 1.15rem; line-height: 1.8; color: var(--text2);">
At <strong>ThinkNCollab</strong>, <code>thinknsh</code> lets a team share a live terminal session — pair debugging, running builds together, walking a teammate through a server issue — without screen-sharing overhead or handing out SSH keys. But the moment you stream a terminal session over the network, you're streaming everything that touches it: source code, API keys typed by mistake, <code>.env</code> files someone <code>cat</code>s out of habit, and production credentials.
</p>

<p style="font-size: 1.05rem; line-height: 1.8;">
That's not a feature you can bolt security onto later. So terminal sharing in TNC is <strong>end-to-end encrypted by design</strong> — the relay server that routes traffic between collaborators never sees plaintext keystrokes or output. It sees encrypted bytes and nothing else.
</p>

<h2>The Threat Model</h2>
<p>Before designing the protocol, we defined what we were actually defending against:</p>
<ul>
  <li><strong>Compromised Relay Server:</strong> A compromised or curious relay server should learn nothing about session content.</li>
  <li><strong>Man-in-the-Middle (MITM):</strong> A network attacker should not be able to read or tamper with the stream, even if they control the network path.</li>
  <li><strong>Replay Protection:</strong> A replayed old session should never be accepted as live.</li>
  <li><strong>Forward Secrecy:</strong> A leaked long-term key should not compromise past sessions.</li>
</ul>

<div style="background: rgba(124, 77, 255, 0.08); border-left: 4px solid #7c4dff; padding: 18px 24px; border-radius: 6px; margin: 24px 0;">
  <p style="margin: 0; font-weight: 600; color: #7c4dff;">🔒 Security Philosophy:</p>
  <p style="margin: 4px 0 0 0; color: var(--text);">Anything less than this, and "encrypted" is just marketing.</p>
</div>

<h2>Architecture at a Glance</h2>
<p>A terminal session in <code>thinknsh</code> has three logical parties: the <strong>host</strong> (whose PTY is being shared), one or more <strong>viewers/collaborators</strong>, and the <strong>relay</strong> (TNC's server, which only ever forwards ciphertext).</p>

<pre style="background: #0d0d18; border: 1px solid var(--border2); padding: 18px; border-radius: 8px; font-family: var(--mono); color: #00ff88; overflow-x: auto;">
Host PTY  ──►  Local encryption layer  ──►  Relay (ciphertext only)  ──►  Peer decryption layer  ──►  Viewer terminal
</pre>

<p>The relay's job is reduced to routing and session bookkeeping — who's in the room, connection health, reconnection state. It is architecturally incapable of reading session content because it never holds the decryption keys.</p>

<h2>Key Exchange: X25519 ECDH</h2>
<p>When a session starts, host and each viewer perform an <strong>X25519 elliptic-curve Diffie-Hellman (ECDH)</strong> exchange. Each side generates an ephemeral keypair for that session — not a long-term identity key — and exchanges public keys through the relay (which can see public keys but cannot derive the shared secret from them).</p>

<p>Both sides independently compute the same shared secret. This secret never travels over the wire. It's derived locally by each party from their own private key and the other party's public key.</p>

<p>Because keypairs are ephemeral (generated fresh per session and discarded after), even if a private key were somehow recovered later, it wouldn't unlock any past session — that's <strong>forward secrecy</strong> in practice, not just in theory.</p>

<h2>Deriving Session Keys: HKDF</h2>
<p>The raw ECDH output isn't used directly as an encryption key. It's passed through <strong>HKDF (HMAC-based Key Derivation Function)</strong> with a session-specific salt (session ID + timestamp) to derive:</p>
<ol>
  <li>A symmetric encryption key</li>
  <li>A separate MAC / authentication key</li>
</ol>
<p>This separation matters — it means a weakness in one derived key doesn't cascade into the other, and it binds derived keys to that specific session, closing the door on cross-session key reuse.</p>

<h2>Encrypting the Stream: AES-256-GCM</h2>
<p>Every chunk of PTY output (and every keystroke going back from viewer to host) is encrypted with <strong>AES-256-GCM</strong> before it leaves the process:</p>
<ul>
  <li><strong>Confidentiality:</strong> No one without the key reads the bytes.</li>
  <li><strong>Authentication:</strong> GCM's built-in tag means tampered ciphertext is rejected outright, not silently corrupted into garbage on-screen.</li>
  <li><strong>Per-packet nonces:</strong> Each encrypted frame gets a unique nonce (session ID + monotonic counter), ensuring no two packets ever reuse the same nonce under the same key.</li>
</ul>

<p>The PTY stream is chunked and encrypted frame-by-frame rather than as one continuous blob — keeping latency sub-millisecond while ensuring every frame is independently authenticated.</p>

<h2>Stopping Replay Attacks</h2>
<p>Each encrypted frame carries a monotonically increasing sequence number, bound into the AEAD's associated data. The receiving side tracks the last accepted sequence number per session and rejects anything out of order or repeated. Combined with session-scoped ephemeral keys, a captured frame from an old session is cryptographically inert.</p>

<h2>What the Relay Actually Sees</h2>

<table style="width: 100%; border-collapse: collapse; margin: 24px 0; border: 1px solid var(--border);">
  <thead>
    <tr style="background: rgba(255,255,255,0.05); text-align: left;">
      <th style="padding: 12px; border: 1px solid var(--border);">Data Type</th>
      <th style="padding: 12px; border: 1px solid var(--border);">Visible to Relay Server?</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="padding: 12px; border: 1px solid var(--border);">Terminal output & keystrokes</td>
      <td style="padding: 12px; border: 1px solid var(--border); color: #00ff88; font-weight: 700;">❌ No — Ciphertext only</td>
    </tr>
    <tr>
      <td style="padding: 12px; border: 1px solid var(--border);">Session participant list</td>
      <td style="padding: 12px; border: 1px solid var(--border); color: #ff8c42;">✓ Yes (Needed for routing)</td>
    </tr>
    <tr>
      <td style="padding: 12px; border: 1px solid var(--border);">Connection metadata & health</td>
      <td style="padding: 12px; border: 1px solid var(--border); color: #ff8c42;">✓ Yes (Needed for reconnection)</td>
    </tr>
    <tr>
      <td style="padding: 12px; border: 1px solid var(--border);">Encryption & Session Keys</td>
      <td style="padding: 12px; border: 1px solid var(--border); color: #ff4d4d; font-weight: 800;">🚫 Never — Held Client-side Only</td>
    </tr>
  </tbody>
</table>

<p>This is the practical difference between "encrypted in transit" (TLS to our server, then plaintext inside infrastructure) and true <strong>End-to-End Encrypted</strong> (plaintext exists only on host's and viewer's machines).</p>

<h2>Where This Fits in ThinkNCollab</h2>
<p>Terminal sharing sits alongside ThinkNCollab's other collaboration primitives — real-time chat, automated verification, GitHub-triggered workflows — all under the same <code>1 Room = 1 Project = 1 Repo</code> model. The encryption layer means engineering teams can pair-debug against a real production shell without TNC becoming a liability.</p>

<p>Security isn't a checkbox feature here — for a dev-first tool that's routinely going to have production access flowing through it, it's the baseline you have to earn before anyone should trust the product with real infrastructure.</p>

<hr style="margin: 32px 0; border: none; border-top: 1px solid var(--border);" />
<p style="font-style: italic; color: var(--text2);">ThinkNCollab is a terminal-native project management and collaboration platform for dev teams. Learn more at <a href="https://thinkncollab.com" style="color: #00ff88;">thinkncollab.com</a>.</p>