Protocol Overview

Technical architecture of the current developer-preview repository.

This page describes implementation status. It should not be read as a launch-ready product claim: contact discovery, session establishment, message receipt, decryption, persistence, and backup restore persistence still have blockers.

Architecture

Harbor consists of four main components:

1. Identity Layer — Cryptographic key management
2. Encryption Layer — Message encryption and key exchange
3. Messaging Layer — Message formatting and session management
4. Storage Layer — On-chain delivery and local storage

Identity Layer

Each Harbor identity consists of:

Keys are generated locally using cryptographically secure random number generation. The wallet address serves as a public identifier but is not used for encryption.

Encryption Layer

Harbor uses the following cryptographic primitives:

Session keys are intended to use the Double Ratchet protocol for forward secrecy. Current ratchet serialization still has a launch blocker.

Messaging Layer

The messaging layer is intended to handle:

• Session establishment — X3DH-style key agreement for initial contact
• Message encryption — Per-message keys from Double Ratchet
• Message formatting — Structured message payloads with metadata
• Padding — Message padding to hide content length

Message Flow

This is the target flow. The current web implementation does not complete it end to end.

1. Sender composes plaintext message
2. Message is padded to standard bucket size
3. Session key is derived from ratchet state
4. Message is encrypted with XChaCha20-Poly1305
5. Recipient commitment is computed
6. Encrypted payload is submitted on-chain

Storage Layer

Harbor uses or plans to use two storage mechanisms:

On-Chain Storage (Base L2)

The deployed contracts support encrypted message events on Base Sepolia:

• KeyRegistry — Stores device public keys and identity commitments
• OnchainMailbox — Emits encrypted message events

On-chain storage can provide censorship resistance and availability after the client send and receive paths are fully wired.

Local Storage

Private web identity data is stored locally in encrypted IndexedDB. Some stores exist but are not fully wired:

• Private keys (encrypted with derived key)
• Session state schema exists, but session storage initialization is incomplete
• Message history stores exist, but no product persistence path writes to them

Local storage is encrypted using keys derived from your identity. If someone accesses your browser storage, they cannot read your messages without your identity keys.

Security Properties

The protocol is designed to provide these properties after the launch blockers are fixed:

• Confidentiality — Only intended recipients can read messages
• Authenticity — Messages are signed by the sender
• Forward Secrecy — Past messages remain secure if keys are compromised
• Replay Protection — On-chain nullifiers prevent replay attacks

Learn More

• Identity Model — Detailed key management
• Encryption — Cryptographic details
• Threat Model — Security analysis