Documentation

Identity Model

How the current V1 implementation manages cryptographic identity.

Key Hierarchy

Each Harbor identity uses a hierarchical key structure:

Ethereum Wallet (external signer)
    │
    └── Identity Keys (per-user, replicated in V1 enrollment)
            ├── Ed25519 Identity Key (signing)
            └── X25519 Identity Key (key agreement)
                    │
                    └── Device Keys (per-device)
                            ├── Ed25519 Device Signing Key
                            └── X25519 Device Prekey

Identity Keys

Your identity consists of two key pairs:

Ed25519 Identity Key

A long-term signing key used to:

  • Sign device enrollment requests
  • Authenticate identity across devices
  • Verify message authenticity

X25519 Identity Key

A key agreement key used to:

  • Establish initial session keys with new contacts
  • Enable multi-device message delivery

Key Generation

Keys are generated locally using the Web Crypto API with cryptographically secure random number generation:

// Simplified key generation
const ed25519Identity = generateEd25519KeyPair();
const x25519Identity = generateX25519KeyPair();
const deviceSigningKey = generateEd25519KeyPair();
const devicePrekey = generateX25519KeyPair();

Keys are generated independently — they are not derived from your wallet private key. Your wallet is used for on-chain identity verification but cannot be used to recover your Harbor keys.

Wallet Binding

Your identity is linked to your Ethereum wallet address. This binding serves several purposes:

  • Public identifier — Others can message you at your wallet address
  • On-chain operations — Intended key registration and message submission
  • Device enrollment — Verifying new device additions

The wallet binding is established by signing a message with your wallet during identity creation. This proves you control the wallet without exposing any private key material.

Device Keys

Each device has its own key pair:

  • Device signing key — Signs messages from this device
  • Device prekey — Used for session establishment on this device

The KeyRegistry contract can store device key records, but current web onboarding does not register device keys on-chain.

Multi-Device Support

V1 contains local device-enrollment functions, but complete product multi-device support is not launch-ready:

  1. Each device can generate its own device keys
  2. Enrollment approval encrypts and transfers the identity private keys to the new device
  3. There is no device-certificate system in code
  4. Sender-side multi-device delivery is not complete

Privacy Note: The number of devices you have is visible on-chain via the KeyRegistry. This is a known limitation documented in the Privacy Limitations.

Device Revocation

The codebase contains local revocation signatures and the contract supports revoking a key record by index:

  1. Local revocation data can be signed with the identity key
  2. The KeyRegistry can mark a key record as revoked
  3. The web product UI is not wired to a complete revocation workflow
  4. V2 atomic device-certificate revocation is not implemented

The stronger V2 revocation model remains future work.

Identity Backup

Your identity keys can be exported as an encrypted backup file:

  • Backup is encrypted with a password you choose
  • Uses PBKDF2 for key derivation
  • Encrypted with XChaCha20-Poly1305

The backup cipher round trip works, but current web import persistence after reload has a known blocker.

Security Considerations

  • Key isolation — Current V1 devices store identity keys locally. A compromised device can expose the identity keys available on that device.
  • No key escrow — No server holds copies of your keys. Loss of all devices and backups means permanent loss.
  • Forward secrecy — Double Ratchet is the intended session model, but the integrated ratchet path is not launch-validated.

Learn More