BBP v1 format specification

01 / model

Invariants

• A BBP file is a valid ordinary image whose visible pixels are a safe base.
• Removing the BBP payload leaves that same decodable safe base.
• Protected content is divided into independently encrypted regions and explicit intersections.
• Recipients are anonymous on the wire: outer entities contain no identity, key ID, bounding box, epoch, or stable hint.
• A downloaded BBP file is a frozen capability grant. BBP does not claim revocation after distribution.

02 / structure

Container

BBP uses one JUMBF superbox with the fixed UUID 6262702d-4242-5031-9c1d-4e7aa5330001 and label brightblur.bbp. Its CBOR child contains the payload.

jumb
├── jumd
│   └── UUID || 0x03 || "brightblur.bbp" || 0x00
└── cbor
    └── deterministic Payload bytes

An unrelated JUMBF box MUST NOT be interpreted as BBP or removed by a BBP stripper.

03 / wire shape

Payload

Payload = {
  v:        uint,          // 1 for this draft
  entities: [Entity, ...]
}

Entity = {
  kind:  "region" | "intersection",
  body:  bytes,            // encrypted body envelope
  wraps: [bytes, ...]      // anonymous recipient envelopes
}

The payload uses deterministic, definite-length CBOR. Entity order has no meaning and producers cryptographically shuffle it after sealing. Decoders reject duplicate keys, invalid UTF-8, trailing bytes, indefinite lengths, and unsupported payload versions.

04 / protected content

Entities

Regions

A decrypted region body contains a normalised top-left bounding box, one group-key epoch, an encoded raster crop, and optional opaque landmark bytes.

RegionBody = {
  bbox: { x, y, width, height },
  epoch: uint,
  pixels: bytes,
  landmarks: bytes?
}

A conforming published region has two ordered wraps: the tagged group key, followed by the uploader account key.

Intersections

An intersection represents pixels protected by multiple regions. Its body records one epoch per wrap in matching order.

IntersectionBody = {
  bbox: { x, y, width, height },
  epochs: [uint, uint, ...],
  pixels: bytes
}

05 / N-party access

Intersections of two or more regions

Intersections are N-party entities. For N ≥ 2, the content key is the XOR of N independent random 32-byte shares. Each share is wrapped to one participating group; a viewer MUST open every wrap before it can derive the key.

K = share[0] XOR share[1] XOR ... XOR share[N - 1]

Encoders supply intersection geometry explicitly and SHOULD partition overlaps by exact membership. With regions A, B, and C:

• pixels covered only by A and B form an A+B intersection;
• pixels covered by all three form a separate A+B+C intersection;
• triple-covered pixels MUST NOT appear in the A+B crop, because A and B alone must not reveal pixels also protected by C.

Subtracting a third region can split an A+B overlap into disconnected pieces. Each piece SHOULD be encoded as a separate intersection entity. Pixels inside its rectangular crop that belong to other membership layers MAY require masking, transparency, or another safe treatment. The crop MUST NOT reveal pixels outside the entity's exact participant set. Several entities may have the same participant set. Arity is implicit: the number of wraps MUST equal the number of epochs.

06 / cryptography

Cryptographic profile

The Rust core is compiled for WASM and native Darwin targets. BBP v1 remains a draft pending independent review.

07 / composition

Rendering order

A compliant viewer MUST compose an image in this order:

1. Decode and paint the ordinary safe base.
2. Trial-open region entities and paint every authenticated region crop.
3. Open an intersection only when every wrapped share is available.
4. Paint successful intersections after all regions.

Bounding boxes are fractions of decoded base dimensions, with the origin at the displayed image's top-left. Inaccessible entities remain as safe-base pixels. Shuffled entity order MUST NOT change the region-before-intersection rule.

08 / bindings

Carrier adapters

The complete JUMBF superbox is unchanged across carriers. Only its ancillary binding differs.

Carrier detection MUST inspect bytes rather than filenames or MIME headers. Embedding MUST preserve unrelated metadata, while stripping MUST remove only a validated BBP binding.

Implementations MAY insert .bbp before the normal carrier extension to help distinguish BBP-capable files, for example filename.bbp.jpg. This filename convention is optional and informative only. Decoders MUST NOT require the suffix or treat it as evidence of a valid BBP payload.

09 / untrusted input

Decoder behaviour

No BBP binding means an ordinary image, not an error. Invalid framing, deterministic CBOR, schema, or versions fail BBP decoding without replacing the safe base. Failure to open a wrap is an expected recipient mismatch and decoding continues with other entities.

Implementations MUST bound carrier sizes, CBOR strings and nesting, entity counts, crop sizes, and trial-decryption work. Authenticated body fields MUST be validated before any pixels or metadata are exposed.

10 / status

Conformance and draft boundary

A producer conforms by emitting a valid safe-base carrier, the specified UUID and payload, correctly ordered wraps, fresh randomness, shuffled entities, and a removable ancillary payload. A viewer conforms by rendering ordinary files and safe bases safely, implementing the pinned crypto profile, authenticating before exposure, following composition order, and bounding work on untrusted input.

This web page is an implementation-oriented guide. The repository specification is canonical and includes the exact envelope byte layouts, deterministic CBOR rules, threat model, and normative references. Before final v1, the project still needs an independent security review, frozen carrier and end-to-end vectors, strict extended-WebP output, and documented resource budgets.