This document describes BitChat's identity management system, which maintains secure mappings between ephemeral peer IDs, cryptographic fingerprints, and social relationships. The system provides encrypted storage of identity data, trust level tracking, verification management, and social relationship persistence (favorites/blocking) through the SecureIdentityStateManager.
For cryptographic handshake mechanics, see 4.1 Noise Protocol Framework For per-geohash identity derivation and privacy, see 4.5 Nostr Identity Bridge and Per-Geohash Privacy For secure key storage primitives, see 4.4 Keychain and Secure Storage
The identity management system operates as a three-layer architecture: ephemeral session tracking for active connections, persistent cryptographic identity storage for fingerprint verification, and social identity management for user-assigned relationships bitchat/Identity/IdentityModels.swift16-22
Sources: bitchat/Identity/SecureIdentityStateManager.swift154-167 bitchat/Identity/IdentityModels.swift161-184 bitchat/Services/NoiseEncryptionService.swift165-168
BitChat maintains three distinct identity models, defined in IdentityModels.swift, each serving a specific purpose in the identity lifecycle bitchat/Identity/IdentityModels.swift12-22
| Model | Purpose | Key | Persistence |
|---|---|---|---|
EphemeralIdentity | Track active session state | PeerID (8-byte routing ID) | In-memory only bitchat/Identity/IdentityModels.swift26-30 |
CryptographicIdentity | Store public keys and fingerprints | Fingerprint (SHA-256 hex) | Optional (encrypted) bitchat/Identity/IdentityModels.swift32-36 |
SocialIdentity | User-assigned relationships | Fingerprint (SHA-256 hex) | Optional (encrypted) bitchat/Identity/IdentityModels.swift38-42 |
Tracks temporary session state for currently connected or recently seen peers. The PeerID is the primary identifier at the network layer bitchat/Identity/IdentityModels.swift88-92
Key methods in SecureIdentityStateManager:
registerEphemeralSession(peerID:handshakeState:) bitchat/Identity/SecureIdentityStateManager.swift123removeEphemeralSession(peerID:) bitchat/Identity/SecureIdentityStateManager.swift127Sources: bitchat/Identity/IdentityModels.swift90-99 bitchat/Identity/SecureIdentityStateManager.swift123-127
Stores the cryptographic public keys and fingerprints derived from Noise handshakes. Fingerprints are derived from the SHA-256 hash of the static public key bitchat/Identity/IdentityModels.swift104-110
Key methods in SecureIdentityStateManager:
upsertCryptographicIdentity(fingerprint:noisePublicKey:signingPublicKey:claimedNickname:) bitchat/Identity/SecureIdentityStateManager.swift106getCryptoIdentitiesByPeerIDPrefix(_:) bitchat/Identity/SecureIdentityStateManager.swift107Sources: bitchat/Identity/IdentityModels.swift104-110 bitchat/Identity/SecureIdentityStateManager.swift106-107
Maintains user-assigned social metadata and trust relationships. This data is strictly local and never transmitted bitchat/Identity/IdentityModels.swift115-123
Key methods in SecureIdentityStateManager:
getSocialIdentity(for:) bitchat/Identity/SecureIdentityStateManager.swift103updateSocialIdentity(_:) bitchat/Identity/SecureIdentityStateManager.swift108setBlocked(_:isBlocked:) bitchat/Identity/SecureIdentityStateManager.swift115Sources: bitchat/Identity/IdentityModels.swift115-142 bitchat/Identity/SecureIdentityStateManager.swift103-115
The SecureIdentityStateManager is the central singleton that orchestrates all identity storage and retrieval operations with thread-safe access and encrypted persistence bitchat/Identity/SecureIdentityStateManager.swift148-152
Sources: bitchat/Identity/SecureIdentityStateManager.swift154-167 bitchat/Identity/IdentityModels.swift161-184
The manager initializes with a device-unique AES-256 encryption key for protecting the identity cache bitchat/Identity/SecureIdentityStateManager.swift33-36 It handles transient failures (e.g., device locked) by using an ephemeral key to prevent data loss bitchat/Identity/SecureIdentityStateManager.swift171-175
Sources: bitchat/Identity/SecureIdentityStateManager.swift177-210 bitchat/Services/KeychainManager.swift112-122
BitChat implements a progressive trust ladder: unknown → casual → vouched → trusted → verified bitchat/Identity/IdentityModels.swift134-142
The vouched tier represents peers that have been verified by a peer that the user has already verified. Validity is recomputed on read—a record only counts while its voucher remains in verifiedFingerprints bitchat/Identity/IdentityModels.swift146-154
Key methods in SecureIdentityStateManager:
recordVouch(voucheeFingerprint:voucherFingerprint:timestamp:) bitchat/Identity/SecureIdentityStateManager.swift136validVouchers(for:) bitchat/Identity/SecureIdentityStateManager.swift137isVouched(fingerprint:) bitchat/Identity/SecureIdentityStateManager.swift138Sources: bitchat/Identity/SecureIdentityStateManager.swift134-143 bitchat/Identity/IdentityModels.swift146-154
While SecureIdentityStateManager stores the raw social state, the FavoritesPersistenceService provides a @MainActor observable interface for the UI to manage favorite relationships, including mutual favorite detection bitchat/Services/FavoritesPersistenceService.swift7-14
A relationship is mutual if both the user has favorited the peer AND the peer has favorited the user (detected via incoming favorite notifications) bitchat/Services/FavoritesPersistenceService.swift21-24
Key methods in FavoritesPersistenceService:
addFavorite(peerNoisePublicKey:peerNostrPublicKey:peerNickname:) bitchat/Services/FavoritesPersistenceService.swift50-54updatePeerFavoritedUs(peerNoisePublicKey:favorited:peerNickname:peerNostrPublicKey:) bitchat/Services/FavoritesPersistenceService.swift121-126Sources: bitchat/Services/FavoritesPersistenceService.swift50-169
The identity management system implements several privacy-preserving design principles:
clearAllIdentityData() bitchat/Identity/SecureIdentityStateManager.swift126Sources: bitchat/Identity/SecureIdentityStateManager.swift32-49 bitchat/Identity/SecureIdentityStateManager.swift126
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.