Processing model

Encoders create the safe base first, seal each original crop independently, shuffle the encrypted entities, encode deterministic CBOR, then bind the same JUMBF superbox to the chosen carrier.

Viewers always paint the safe base first. They trial-open region wraps, paint every authenticated region, then paint an intersection only when every participating key share is available. BBP v1 supports intersections between two or more regions.

Crypto profile

KEM

xwing-draft08

Content

XSalsa20-Poly1305 with a fresh 32-byte key and 24-byte nonce

Wrap KDF

HKDF-SHA-256, salted by the complete X-Wing ciphertext

Recipients

Anonymous trial decryption; no key identifiers or stable hints

Decoder behaviour

No BBP box means an ordinary image. Malformed metadata and unsupported versions are errors, while a wrap that does not open is an expected recipient mismatch. Inaccessible regions remain safely pixelated.

Implementations must bound carrier sizes, CBOR nesting, entity counts, crop sizes, and trial-decryption work before processing untrusted files.

Safe by construction

Non-compliant viewers render the base and ignore the ancillary payload. Losing the BBP payload loses reveal capability; it never exposes a hidden original.

The base still reveals the scene and mosaic geometry. A downloaded file is a frozen grant, and BBP does not survive recompression or metadata stripping.

Implement the draft

The complete draft defines carrier framing, deterministic CBOR, body coordinates, envelope byte layouts, rendering order, error handling, and producer/viewer conformance requirements.

Read the complete specification ↗

Draft boundary

The wire format is explicit enough for independent implementations, but BBP v1 is not frozen. Recipient anonymity and robustness still need independent cryptographic review, followed by frozen carrier and end-to-end fixtures.

URL or File source

URLs work declaratively when the response is same-origin or CORS-enabled. Browser files and byte buffers use the src property.

<bbp-viewer
  id="viewer"
  src="/photo.bbp.jpg">
</bbp-viewer>

input.onchange = () => {
  const file = input.files?.[0];
  viewer.src = file ?? null;
};

One keyring per page

Shared keys update every current viewer and become the default for viewers connected later. An explicit instance value remains an override.

import {
  setBbpViewerPrivateKeys
} from '@brightblur/bbp-viewer';

setBbpViewerPrivateKeys([
  privateKey
]);

viewer.privateKeys = [overrideKey];
viewer.useSharedPrivateKeys();

Encode and view

import { bbpEncode } from '@brightblur/bbp';
import '@brightblur/bbp-viewer';

const bytes = await bbpEncode({
  base: redactedImageBytes,
  regions: [{
    bbox,
    epoch: 0,
    pixels: crop,
    recipientPublicKey
  }],
  intersections: []
});

viewer.src = bytes;
viewer.privateKeys = [privateKey];

Adapter contract

To add a carrier, preserve the same payload and implement the four boundary operations below. Then add the carrier to detection and the public dispatch. Keep the binding ancillary so ordinary decoders still render the safe base.

type CarrierAdapter = {
  detect(bytes): boolean;
  embed(base, jumbf): Uint8Array;
  extract(file): Uint8Array | null;
  strip(file): Uint8Array;
};

Where to look

packages/bbp/src/container.ts contains the carrier dispatch and the WebP, JPEG, PNG, and HEIF bindings. packages/bbp/src/encoder.ts assembles the CBOR payload; packages/bbp-viewer/src/index.ts performs local trial-decryption and composition.

Conformance direction

The format document is the normative starting point. The current implementation is a reference for the draft, not a claim that the draft has completed its independent security audit or final test-vector freeze.