E2EE Clipboard Protocol (ECP)

A serverless, pure-frontend web implementation of the End-to-End Encrypted Clipboard Protocol (ECP). ECP enables secure, peer-to-peer encrypted messaging and clipboard content sharing across untrusted transport channels without requiring a backend server or central authority.

• Zero-Backend Processing: Operates strictly on the client side. Messages are exchanged out-of-band via user-selected transport channels, such as instant messengers, email, shared documents, social media, QR codes, or physical notes.
• Local Persistence: Encrypted session states, keys, and identity profiles reside entirely within client-side IndexedDB storage.
• Post-Quantum Cryptography (PQC): Combines classical cryptography with NIST PQC standards via @noble libraries (@noble/ciphers, @noble/curves, @noble/hashes, @noble/post-quantum).
• Zeroization & Memory Hygiene: Ephemeral key material undergoes explicit zeroization immediately following cryptographic operations.

• Transport Confidentiality & Integrity: All ciphertexts copied to the clipboard remain secure even when transmitted over unencrypted or compromised communication channels.
• Post-Quantum Forward Secrecy: Future quantum adversaries capturing current transport payloads cannot decrypt historical sessions due to hybrid X25519/ML-KEM-1024 key encapsulation and Double Ratchet state advancement.
• Authenticity & Non-Repudiation: Initial handshake signatures using ML-DSA-87 prevent active person-in-the-middle (PITM) identity spoofing.

• Host Environment Integrity: Malware, malicious browser extensions, or OS-level keyloggers/clipboard monitors running on the user's host machine.
• Side-Channel Attacks: Execution timing or memory access side-channels native to the JavaScript engine runtime environment.

1. Identity Generation: Automatically generates a persistent cryptographic identity upon initial application boot.
2. Peer Registration: Users exchange out-of-band public identity bundles to add contacts.
3. Session Initialization: The initiator generates an INIT payload packet and transmits it to the peer to establish a Double Ratchet session.
4. Encrypted Exchange: Ciphertexts are copied directly to the clipboard, transmitted across any third-party app, and pasted by the recipient to decrypt.

The application is written in standard TypeScript and styled with Tailwind CSS v4. To maintain verifiable build outputs, the project intentionally omits complex bundlers in favor of explicit CLI toolchains (tsc, Tailwind CLI, and static serving).

• Installation: Clone the repository and install locked dependencies.

  npm install

• Local Development: Starts the file watcher and static development server.

  npm run dev

• Production Build: Compiles static JavaScript assets directly to root distribution files.

  npm run build

All serialized wire payloads enforce a 5 MB limit and begin with a mandatory 12-byte binary header.

Establishes the session, performs hybrid key agreement, and verifies mutual identity. To prevent parsing faults, the receiver enforces a strict minimum structural integrity size of 14,639 bytes.

Acknowledges initialization. The protocol drops RESP payloads shorter than 60 bytes (12-byte header + 48-byte payload).

Carries active Double Ratchet session payloads. Any MSG packet shorter than 84 bytes is dropped as truncated.

To maintain synchronization and prevent abuse, ECP dictates specific constraints on MSG frame validation.

• Sequence Progression & Replay Drop: The protocol demands strict forward progression. During DecryptMessage, the parsed sequence number ($N$) is compared against the expected receive sequence ($N_r$). If $N < N_r$, the message is dropped immediately, throwing a "Message frame out of order or replayed" error.

• Gap Limitation & Skipped Keys: ECP handles dropped packets by advancing the receiving chain up to the target sequence $N$. To prevent CPU exhaustion or memory starvation attacks via continuous HMAC chaining, ECP enforces a strict limit: if $N - N_r > 2000$, it throws an "Excessive message gap" exception.

• Ephemeral Zeroization: During skipped frame advancement ($N_r < N$), intermediate receiving chain keys ($CK_r$) are wiped from RAM using .fill(0) immediately after generating the next step.

The initial Shared Key ($SK$) combines classical ECDH key agreement with post-quantum key encapsulation using HKDF-SHA256:

$$SK = \text{HKDF-SHA256}\left(\mathtt{"ECP-INIT-v1"} \parallel DH_1 \parallel KEM_{SS}\right)$$

Handshake integrity and authenticity are asserted by signing the concatenated parameter block using the sender's ML-DSA-87 private key:

$$Sig = \text{Sign}_{\text{ML-DSA}}\left(\mathtt{"ECP-INIT-v1"} \parallel SenderID \parallel ReceiverID \parallel Ek_{pk} \parallel KEM_{CT}\right)$$

Chain Keys ($CK$) and Message Keys ($MK$) advance via HMAC-SHA256 step derivation:

$$ \begin{aligned} MK &= \text{HMAC-SHA256}(CK, \text{0x01}) \\ CK_{\text{next}} &= \text{HMAC-SHA256}(CK, \text{0x02}) \end{aligned} $$