# BitChat Courier Envelopes Trust Tiers: Access Control Explained

> Understand BitChat courier envelopes trust tiers. Learn how access control protects your messages, requiring trusted peers for storage and forwarding.

- Repository: [permissionlesstech/bitchat](https://github.com/permissionlesstech/bitchat)
- Tags: deep-dive
- Published: 2026-08-21

---

**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`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/CourierStore.swift) and [`BLEService.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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:

```swift
// 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`](https://github.com/permissionlesstech/bitchat/blob/main/CourierStore.swift) implementation validates the depositor's trust tier before processing. The [`SyncTypeFlags.swift`](https://github.com/permissionlesstech/bitchat/blob/main/SyncTypeFlags.swift) file marks courier envelopes as sync-types requiring trusted handling, while [`BLEService.swift`](https://github.com/permissionlesstech/bitchat/blob/main/BLEService.swift) routes these envelopes through the BLE layer only after passing trust validation:

```swift
// 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:

```swift
// 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`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/CourierStore.swift) and [`BLEService.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/CourierStore.swift) and enforced during BLE routing in [`BLEService.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/bitchat/Services/Courier/CourierStore.swift) for storage operations and [`bitchat/Services/BLE/BLEService.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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`](https://github.com/permissionlesstech/bitchat/blob/main/MessageType.swift)).

### How are trust tiers defined in the BitChat source code?

The `TrustLevel` enum in [`bitchat/Identity/IdentityModels.swift`](https://github.com/permissionlesstech/bitchat/blob/main/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.