BitChat Courier Envelopes Trust Tiers: Access Control Explained

BitChat courier envelopes can only be stored and forwarded by peers with a trust level of trusted or higher, as defined in the TrustLevel enum in IdentityModels.swift.

The permissionlesstech/bitchat repository implements a hierarchical trust ladder to secure its store-and-forward messaging system. Understanding these BitChat courier envelopes trust tiers is essential for developers integrating with the protocol or auditing its security model. The system uses five discrete trust levels to determine which peers may act as courier carriers for offline message delivery.

The Five Trust Tiers in BitChat

The trust hierarchy is defined by the TrustLevel enum located at lines 146-154 in bitchat/Identity/IdentityModels.swift. This enum establishes a progression from untrusted to cryptographically verified states, with each tier represented by an integer raw value for comparison operations.

Unknown and Casual Tiers

Peers marked as unknown represent new or never-verified contacts with no interaction history. The casual tier indicates basic interaction history but does not grant courier privileges. Both tiers are explicitly blocked from handling courier envelopes, as their raw values (0 and 1) fall below the minimum threshold.

Vouched, Trusted, and Verified Tiers

The vouched tier represents transitive trust derived from verified vouchers, yet remains insufficient for courier operations with a raw value of 2. Only peers at the trusted tier—explicitly trusted by the user—or the verified tier—cryptographically verified via signed proofs—qualify as courier carriers. These top tiers hold raw values of 3 and 4 respectively, enabling the comparison trust >= .trusted used throughout the codebase.

Courier Carrier Requirements

According to the source code in CourierStore.swift and BLEService.swift, the system enforces a strict minimum requirement: only peers with trust levels ≥ trusted may carry courier envelopes. Lower tiers (unknown, casual, vouched) are prohibited from forwarding or retaining these envelopes regardless of network availability.

Message Type Definition

The courier envelope message type is declared in localPackages/BitFoundation/Sources/BitFoundation/MessageType.swift at line 17 as case courierEnvelope = 0x04. This constant identifies packets requiring trusted handling throughout the stack, distinguishing them from standard direct messages that may traverse untrusted paths.

Trust Verification Logic

The enforcement logic typically appears as a guard statement checking the peer's trust level against the minimum threshold:

// From IdentityModels.swift - TrustLevel enum definition (lines 146-154)
enum TrustLevel: Int, Comparable {
    case unknown = 0
    case casual = 1
    case vouched = 2
    case trusted = 3
    case verified = 4
    
    static func < (lhs: TrustLevel, rhs: TrustLevel) -> Bool {
        return lhs.rawValue < rhs.rawValue
    }
}

// Trust comparison implementation used in CourierStore.swift
func canCarryCourier(_ trust: TrustLevel) -> Bool {
    return trust >= .trusted  // Only trusted (3) and verified (4) qualify
}

Practical Implementation Examples

When storing a courier envelope, the CourierStore.swift implementation validates the depositor's trust tier before processing. The SyncTypeFlags.swift file marks courier envelopes as sync-types requiring trusted handling, while BLEService.swift routes these envelopes through the BLE layer only after passing trust validation:

// Simplified extraction from CourierStore.swift logic
func storeCourierEnvelope(from peer: Peer, envelope: CourierEnvelope) {
    guard canCarryCourier(peer.trustLevel) else {
        // Reject: untrusted peers cannot deposit courier envelopes
        logSecurityEvent("Rejecting courier from \(peer.id) - trust tier too low")
        return
    }
    // Proceed with envelope storage for trusted peers only
    persistEnvelope(envelope, source: peer.fingerprint)
}

To create a social identity eligible for courier operations, developers must set the trustLevel parameter to .trusted or .verified during initialization:

// Creating a trusted identity eligible for courier delegation
let trustedPeer = SocialIdentity(
    fingerprint: "SHA256:ABCD1234...",
    localPetname: "Alice",
    claimedNickname: "alice42",
    trustLevel: .trusted,          // Enables courier envelope carriage
    isFavorite: true,
    isBlocked: false,
    notes: "Verified at conference"
)

Summary

• Five-tier hierarchy: BitChat uses unknown, casual, vouched, trusted, and verified levels defined in IdentityModels.swift with raw values 0-4.
• Minimum threshold: Only peers at trusted (level 3) or verified (level 4) may act as courier carriers for store-and-forward operations.
• Strict enforcement: CourierStore.swift and BLEService.swift reject courier envelopes from lower-tier peers before storage or transmission.
• Message typing: Courier envelopes use type 0x04 as defined in MessageType.swift, distinguishing them as privileged sync-types.
• Comparative checks: The system leverages Swift's Comparable protocol to enforce trust >= .trusted guards efficiently across the codebase.

Frequently Asked Questions

What is the minimum trust level required to carry BitChat courier envelopes?

Peers must hold a trust level of trusted or verified to store and forward courier envelopes. The unknown, casual, and vouched tiers are explicitly prohibited from courier operations according to the validation logic implemented in CourierStore.swift and enforced during BLE routing in BLEService.swift.

How does the vouched tier differ from trusted in BitChat's system?

While vouched represents transitive trust derived from verified vouchers, it ranks below trusted (raw value 2 vs. 3). Only trusted and verified tiers grant courier privileges because they require explicit user confirmation or cryptographic verification rather than indirect association through a voucher chain.

Where is the trust level enforcement implemented for courier envelopes?

The primary enforcement occurs in bitchat/Services/Courier/CourierStore.swift for storage operations and bitchat/Services/BLE/BLEService.swift for transport routing. Both locations implement guard statements comparing the peer's trust level against .trusted before processing courierEnvelope messages (type 0x04 defined in MessageType.swift).

How are trust tiers defined in the BitChat source code?

The TrustLevel enum in bitchat/Identity/IdentityModels.swift (lines 146-154) defines five integer-backed cases ranging from unknown (0) to verified (4). The enum conforms to Comparable, enabling intuitive comparison operators for access control decisions throughout the codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}