bitchat/docs/PRIVATE-MEDIA-MIGRATION.md

# Private-media wire migration

Private files use the `BitchatFilePacket` TLV shared by iOS and Android. The
preferred direct-message wire form encrypts that complete TLV inside the
peer's Noise session before BLE fragmentation.

## Wire values and capability

- `NoisePayloadType.privateFile` is `0x20`, the value already deployed by the
  Android client. New sends must use this value.
- iOS temporarily accepts `0x09`, which appeared in prerelease builds of the
  private-media change. Decoders canonicalize it to `privateFile`; they never
  emit it.
- `NoisePayloadType.authenticatedPeerState` is permanently assigned `0x21`.
  It is emitted after every completed/rekeyed Noise XX session and echoed at
  most once when the remote state arrives, so message-3/proof reordering over
  different mesh links converges. This type is part of the protocol security
  boundary and is not removed when the media migration ends.
- The `0x21` payload starts with version `0x01`, followed by one-byte
  type/length/value fields. Version 1 requires canonical TLV `0x01` (the
  minimal little-endian `PeerCapabilities` bitfield, 1-8 bytes) and TLV `0x02`
  (the 32-byte Ed25519 announcement signing key). Duplicate required fields,
  non-minimal capabilities, malformed lengths, missing fields, and unknown
  versions are ignored without changing state. Unknown TLVs are skipped.
- The public `PeerCapabilities.privateMedia` announce bit is a discovery hint:
  it starts a Noise handshake, but never selects encrypted sending or creates
  a pin. A private transfer waits boundedly for the exact session's encrypted
  `0x21`. A valid bit-8 proof selects Noise `0x20`; a valid no-bit proof or a
  no-proof timeout reaches the explicit legacy-consent path for an unpinned
  peer. No timeout automatically sends raw bytes.
- An unpinned peer with a stable Noise key but without that capability is
  eligible for one signed, directed
  `fileTransfer`, matching the pre-migration wire form used by older iOS and
  accepted by current Android clients, only after the sender confirms a
  per-send warning that the file is not end-to-end encrypted and mesh relays
  can see it. The
  consent is consumed by that invocation and is never remembered.
- A signed announce never creates a pin by itself: an attacker can copy a
  victim's public Noise key, supply its own Ed25519 key and capability bits,
  and self-sign an internally consistent announce. Only successfully
  decrypted `0x21` state pins the authenticated Noise fingerprint and binds
  the Ed25519 key used by later announces/public messages. A later valid
  no-bit `0x21` is treated as a downgrade, and raw fallback is blocked even if
  a caller presents legacy consent. Public no-bit announces cannot overwrite
  current session-authenticated state.
- During migration, both an absent capabilities TLV and an explicit TLV
  without `privateMedia` are legacy-eligible when that stable fingerprint is
  not pinned. This supports clients that added capability advertisement before
  encrypted media. Neither shape bypasses a previously authenticated pin.

Older clients decrypt and ignore unknown inner type `0x21`; they do not need to
understand it to continue using text or the warned legacy media path. They are
never inferred capable merely because the handshake succeeded.

Removal gates are independent and must not share an arbitrary calendar date:

- Remove the `0x09` receive alias only after every TestFlight/internal build
  that emitted it has expired and minimum-supported-client policy excludes it.
- Remove the signed directed raw `0x22` fallback only after minimum-supported
  iOS and Android clients emit authenticated bit-8 `0x21` state and the legacy
  population has aged out.
- Nostr kind `1059` compatibility is a separate envelope migration. Its dual
  publish/removal gate is not evidence that either BLE compatibility shape can
  be removed.

## Security boundary

The encrypted form provides Noise confidentiality and peer authentication.
The fallback is signed and its signature is required on receive, so relays
cannot forge its sender or contents. It is not confidential: relays can see
the raw file TLV. The UI says this explicitly and asks on every send. A peer
without a stable Noise key from a verified registry entry cannot use the
fallback. Keep it only for the mixed-version migration, and remove it only
after minimum-supported Android and iOS releases emit authenticated bit-8
`0x21` state and the legacy population has aged out. Never replace it with an
unsigned fallback, persist blanket consent, or send both forms.

Incoming clients accept all three migration-era shapes:

| Sender | Inbound form | Result |
| --- | --- | --- |
| Current Android | Noise `0x20` | Decrypt and deliver |
| Prerelease iOS | Noise `0x09` | Decrypt, canonicalize, and deliver |
| Older client | Signed directed `fileTransfer` | Verify signature and deliver |
| Forged/unsigned raw sender | Directed `fileTransfer` | Reject |

Panic wipe clears the persistent capability pins together with the rest of
the encrypted identity cache.

This migration path is mesh-Noise-only (BLE and compatible direct mesh links).
Nostr private-media transport is unchanged and remains a follow-up. Nostr
inbound paths explicitly ignore `0x21`; do not infer the mesh consent fallback
or capability-pin semantics for Nostr delivery.

## Size interoperability

iOS bounds inbound file content at 1 MiB and applies the expanded allocation
budget only after a large Noise ciphertext authenticates to `0x20` or the
temporary `0x09` alias. Ordinary Noise messages retain their 64 KiB limit.

Current Android builds cap each reassembly at 256 fragments. Depending on the
negotiated BLE packet size and routing overhead, that is roughly 110-120 KiB,
well below iOS's absolute inbound ceiling. Private-media v1 therefore runs the
actual route-aware BLE fragment planner before both encrypted and consented
legacy sends and rejects any plan above 256 fragments with a visible failure.
This fragment-count contract, rather than a guessed byte threshold, stays
correct as route overhead changes.