Skip to content
clazelPublic

About

An experiment in making a formally verified web browser, using AI

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Clazel

A web browser built from the bottom up by AI, using formal verification instead of trust.

  • Memory safe: 100% safe Rust except clazel-sys: 343 unsafe blocks (929 lines) that enter the OS sandbox, machine-checked and audited. Of those, 40 are "C-unwind" casts of objc_msgSend to a typed function pointer, one per Objective-C message signature that Metal drawing (21) and the macOS window (19) use. Vulkan drawing on Linux adds 55 (51 direct calls and 4 blocks of declarations), and Direct3D 12 drawing and the GPU process's start on Windows add 56, of which 40 are COM method calls through hand-written vtables. Shipped dependencies are libc and libcrux.
  • Verified where it matters: the kernel's security policy and every parser of untrusted input carry machine-checked proofs (Verus, Kani).
  • Stated, not implied: each crate declares its verification tier, and the trusted computing base is listed in docs/VERIFICATION.md.

Recheck every proof yourself, on Linux x86-64, with:

docker build --platform linux/amd64 -t clazel-verify .
docker run --rm --platform linux/amd64 clazel-verify

Verification status

Verification status: crates proven correct, proof obligations, mutants caught, conformance cases, unsafe blocks and axioms, and each component's crates by tier

Every crate, where it runs and the full table, with every conformance suite: docs/STATUS.md. CI redraws both after every push to main whose full verification passes, so they can lag behind main.

What it does today

  • Browses, in a window. clazel URL opens a window and draws the page: HTML parsed, style sheets (linked ones included) cascaded, text laid out in the system's fonts, and the result drawn by a sandboxed GPU process, under an address bar that is always the kernel's committed URL. It draws with Metal on macOS, Vulkan on Linux and Direct3D 12 on Windows.
  • Renders without a window. clazel --headless OUT URL writes the page as a PNG, and clazel --text URL is a text-mode browser in the style of Lynx, which is also what runs where there is no window.
  • Fetches. clazel fetch URL is a curl clone over http: and https:, on our own DNS client, HTTP/1.1 parser and TLS 1.3 client, with redirects and cookies.
  • Not yet: images, forms and JavaScript. Pages in the seven legacy multi-byte encodings (Shift_JIS, GBK, Big5 and others) are not rendered: the page says "encoding <name> is not supported".

What comes next, and in what order, is in docs/ROADMAP.md.

How it is put together

Clazel runs as several processes. The proofs follow the untrusted bytes: the kernel that makes every security decision is proven, and so are the parsers, in whichever process they run. What is not proven (layout, drawing, the window, the I/O shells) is memory safe, sandboxed where it handles page content, and makes no security decisions. The status table gives each crate's tier.

  • The kernel (clazel-kernel) is a proven state machine. Tabs, origins, connections, cookies and storage are its state, and every navigation, request, redirect and cookie is its decision. Its theorems say, among other things, that what a renderer displays is shown for its own tab, under the URL the kernel committed there (theorem_show_only_own_tab, theorem_address_bar_integrity), and that a renderer receives the fetched body whole (theorem_body_is_the_response).
  • Renderers (clazel-renderer) parse and lay out pages, one process per origin, inside the OS sandbox: namespaces, seccomp and Landlock on Linux, Seatbelt on macOS, an AppContainer on Windows. The HTML tokenizer, the tree builder and the DOM are proven correct; layout is memory safe and tested, not proven. A renderer talks only to the kernel, over a proven message codec (clazel-ipc).
  • GPU processes (clazel-gpu) draw, one per tab, in a sandbox of their own. A renderer sends its GPU process display lists, which are decoded and validated before anything is drawn, and the host shows the pixels in the window (clazel-window) only when the kernel says to paint them.
  • Parsers of untrusted bytes are ours, in every process, and are proven against a transcription of their standard: URLs, encodings, IDNA, MIME sniffing, HTTP, DNS, cookies, DER and signature checking, HTML and more.
  • Shells carry bytes. The host (clazel), the network shell (clazel-net) and the store's shell (clazel-store-shell) do the I/O and make no protocol decisions: those belong to the proven crates they call.
  • clazel-sys holds every unsafe block: single calls into the OS, with no policy of their own.

How it is verified

Each crate declares a tier in its Cargo.toml, and cargo xtask verify rejects a claim that is not backed:

Tier Guarantee Checked by
0 Memory safe Safe Rust, Miri, deny-lints
1 Never panics on any input Kani harnesses
2 Functionally correct against an executable spec Verus proofs

A proof only shows that code matches its spec. That the spec matches the standard is shown by evidence that machines check too: official test suites (Web Platform Tests, html5lib-tests and others) run through the proven code, differential tests against independent engines, deliberately broken specs that a theorem must reject, and a second, independent transcription proven equivalent to the first. No step depends on a person approving something. The policy, the tools and the trusted computing base are in docs/VERIFICATION.md.

Formalising the standards has found places where they are wrong as written: see docs/ERRATA.md.

Building

scripts/setup.sh         # install the pinned, checksummed toolchain (needs rustup)
scripts/verify.sh        # every check, fresh proof runs (same as `cargo xtask verify`; CI runs this)
cargo xtask verify --changed   # every check, but proofs and tests only for crates changed since origin/main
cargo xtask check        # fast static checks only

The browser, clazel, and the sandboxed renderer and GPU process it starts for each tab:

cargo build --release --bin clazel --bin clazel-renderer --bin clazel-gpu   # all land in target/release/
target/release/clazel https://news.ycombinator.com/       # open a window on the page
target/release/clazel                                      # or on no page, with the address bar ready

In the window, click the address bar (or press Command-L on macOS, Control-L elsewhere), type a URL and press Return to go there, click a link to follow it, and scroll with the wheel, Space, Page Up and Page Down or the Up and Down arrows. The back button (Command-[) goes back, and Command-R reloads (Control on Linux and Windows). The kernel fetches every page and its style sheets, the page is parsed and laid out in a sandboxed renderer, one per origin, and drawn by a sandboxed GPU process; the address bar is the kernel's, whatever the page says. A window needs macOS on Apple silicon, Windows, or Linux with a local X display and the Vulkan loader (libvulkan-dev to build). On Windows the browser's window and Direct3D 12 drawing have been run by hand; CI there runs the sandbox and the host's tests and opens a test window, but never draws with Direct3D 12.

target/release/clazel --headless page.png https://example.com/   # draw one page to a PNG (or a .ppm)
target/release/clazel --text http://info.cern.ch/                # text mode: title, text, numbered links

--headless takes --size WxH (1024x768 if not given). --text shows a page as text, with its links numbered: type a number to follow a link, g URL to go elsewhere, b to go back, q to quit. It is also what clazel URL runs where no window can be opened. With a window or --headless, --gpu=software starts every GPU process on the software driver (lavapipe on Linux; macOS has none, so nothing is drawn there), and --gpu=hardware ignores the driver blocklist, with a warning.

target/release/clazel fetch http://example.com/           # GET, redirects followed, response printed

fetch resolves the host with our own DNS client and drives the proven fetch client: it builds each request, frames each response with the proven HTTP/1.1 parser, follows redirects and keeps the cookies they set for the rest of the run. It needs the Internet. An https:// URL goes over our TLS 1.3 client with Mozilla's roots as the trust store.

Each GitHub release has a Linux x86-64 tarball with both binaries and an installer: unpack it and run sudo ./install.sh (or PREFIX=... ./install.sh). On Ubuntu 23.10 and later, which restrict unprivileged user namespaces, the installer also adds an AppArmor profile that lets clazel-renderer create the one its sandbox needs, and nothing else; without it the renderer refuses to start, by design. Built from source, run the same script once:

sudo packaging/apparmor/allow-userns.sh clazel-renderer "$PWD/target/release/clazel-renderer"

How to get involved

The code is written by AI agents under rules (CLAUDE.md) designed so that nobody has to trust them. That leaves a lot of useful work for people, and much of it is work only a person can do.

  • Check our work. Rerun every proof on your own machine with the Docker command above, or scripts/verify.sh. If anything does not match the verification status table, open an issue: a claim nobody can reproduce is a bug.
  • Review a spec against its standard. Each spec.rs transcribes a standard step by step, with its modelling choices listed at the top (docs/SPEC-STYLE.md). Reviews gate nothing, and only people may record one, so a reviewed file means a person read it. See docs/SPEC-REVIEWS.md for how. contract.rs files are the shortest route to what each crate actually promises.
  • Take errata upstream. Agents never file issues with standards bodies; the entries marked "Reported upstream: not yet" in docs/ERRATA.md are waiting for a person to check them and report them.
  • Try to break it. Feed the parsers hostile input, look for a spec bug the proofs would not catch (each crate's mutations.json lists the known gaps, marked survives), or close one of those gaps with a lemma or a Kani harness.
  • Add test suites. Every Tier 2 crate is tested against official suites and independent engines (tests/conformance*.rs). Point us at suites we have not vendored, or at engines worth differential testing against.
  • Run it on your machine. Build it, browse with it, and open an issue for what breaks. The sandbox tests run in CI on ubuntu-24.04, macOS arm64 and windows-2025 only; other Linux distributions and kernels are untested.
  • Read clazel-sys. It is the only crate with unsafe. Every change is audited by a second model (docs/SYS-AUDITS.md); a person reading it too is welcome.
  • Build what is missing. The plan is in docs/ROADMAP.md. Contributions go through the same machine checks as everything else, whoever (or whatever) wrote them: read CLAUDE.md first, and expect cargo xtask verify --changed and CI's full verification to be the bar.

License

MIT. See LICENSE.

About

An experiment in making a formally verified web browser, using AI

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages