BrightBlur Protocol

An open image format for safe-by-default, per-region privacy.

BBP stores a normal redacted image together with an additive JUMBF payload. Standard image viewers render the safe base. Compliant viewers use private keys to reveal only the encrypted regions they can open.

This repository contains the draft format, its TypeScript reference implementation, a framework-neutral web component, a static landing/reference app, and a native macOS preview shell.

Install from npm

The current public release is an alpha, published under the next tag. For the complete browser viewer:

npm install @brightblur/bbp-viewer@next

The viewer installs the BBP decoder, compositor, and Rust/WASM cryptographic core as dependencies. Applications that provide their own interface can install the lower-level packages directly:

npm install @brightblur/bbp@next
npm install @brightblur/bbp-compositor@next
npm install @brightblur/crypto@next

See the web component guide for image sources, private keys, events, and framework examples.

Run the reference site

Requirements: Node.js 22+ and pnpm 10.

pnpm install
pnpm dev

Open the printed http://localhost:5173/ URL. The source page must be served; opening index.html with file:// will prevent the TypeScript module from loading.

Workspace

• packages/bbp — BBP CBOR, encoder, decoder, and WebP/JPEG/PNG/HEIF carrier bindings.
• packages/bbp-compositor — deterministic, DOM-free RGBA composition shared by viewers and applications.
• packages/bbp-viewer — <bbp-viewer>, a framework-neutral custom element.
• packages/crypto — X-Wing and envelope primitives used by the reference implementation.
• apps/bbp-preview — landing site and client-only encrypt/view example.
• apps/bbp-preview-macos — SwiftUI/AppKit preview clone with a bundled local WebKit bridge.
• docs/format.md — draft format specification and adapter contract.
• docs/implementation.md — implementation architecture notes.
• docs/deployment.md — npm release, Cloudflare Pages, and native package notes.

Checks

pnpm check
pnpm test
pnpm build
pnpm build:macos

The format is still draft and requires an independent security audit. BBP v1 currently freezes the cryptographic profile as xwing-draft08; future cryptographic profiles must be versioned explicitly rather than silently changing how existing envelopes are opened.

Licensing

Source code is licensed under Apache License 2.0, including the TypeScript packages, web component, landing app, and Swift reference app.

The specification and documentation under docs/ are licensed under CC BY 4.0. BrightBlur names and marks are covered separately by the trademark policy.

See CONTRIBUTING.md before submitting changes.