Step 35: the crypto brick, written once for both runtimes

The first brick under the bricks page (bricks-and-the-cost-of-zero-dependencies), and the first thing program 7 needs (SHA-256 for Redis’s ACL passwords; the TLS brick of step 36 needs the rest). Two things are new at once: the rows, and the rule that a brick is written once, in Zig over std.crypto, and used by both runtimes, so it is audited once. The C runtime gets no crypto of its own.

Orientation

toolchain/src/prelude.zig (the stdlib’s types and rows, Platform’s capabilities: http at line 423 is the pattern), caps.zig (what a capability may reach), check.zig (row typing), bytecode.zig and vm.zig (the interpreter’s row bodies), emit_c.zig (the binary’s), cbuild.zig (how mo build runs zig cc on the emitted C and the embedded mo_rt.c; the brick joins that link), sim.zig (the seed, for Random.fixture), spec/design-v0/09-stdlib.md (## Rules for every row; ## Files for the shape of a capability’s rows), examples/effects/ (capability examples with .expected), the bricks page’s cut for crypto. Zig 0.16’s std.crypto (on the VM through mise; zig env gives std_dir): sha2.zig, hmac.zig, hkdf.zig, aes_gcm.zig, chacha20.zig, 25519/, argon2.zig, phc_encoding.zig, timing_safe.zig, std.crypto.random.

Write scope

toolchain/, examples/effects/crypto*.mo and examples/basics/hash*.mo with their .expected, examples/README.md’s list, and these spec lines only: a ## Crypto section and a ## Random section in 09-stdlib.md in the table form the file uses, one line in 07-toolchain.md’s build order if the link step changes it, and the runtime paragraph of toolchain/README.md. Nothing else under mo-wiki/.

Parts

A. The brick. One file, toolchain/src/bricks/crypto.zig, with C-ABI exports (export fn mo_crypto_sha256(...) and so on) over std.crypto, nothing hand-rolled: SHA-256, SHA-512, HMAC-SHA256, HKDF-SHA256, AES-256-GCM seal and open, ChaCha20-Poly1305 seal and open, X25519 (a public key from a secret, a shared secret), Ed25519 (a public key from a seed, sign, verify), Argon2id (hash to a PHC string with given salt and the parameters m=65536,t=3,p=1; verify a PHC string), constant-time equality, and bytes from the OS CSPRNG. Its unit tests are the standards’ vectors, in the file, run by zig build test: FIPS 180-4 for SHA-2, RFC 4231 for HMAC, RFC 5869 for HKDF, RFC 7748 for X25519, RFC 8032 for Ed25519, RFC 8439 for ChaCha20-Poly1305, the NIST GCM vectors, RFC 9106’s Argon2id vector. A wrong key or nonce size is a crash at the row (rule 3 of chapter 9: the caller broke a rule); a failed open or verify is a value.

B. The rows, both runtimes. Pure rows on types, since hashing, sealing, and signing are deterministic (chapter 9’s first rule), and one capability, Random, for the only thing that is not:

Hash.sha256(bytes: List(UInt8)) : List(UInt8)          # 32 bytes
Hash.sha512(bytes: List(UInt8)) : List(UInt8)          # 64
Hash.hmac_sha256(key: List(UInt8), bytes: List(UInt8)) : List(UInt8)
Hash.hkdf_sha256(ikm: List(UInt8), salt: List(UInt8), info: List(UInt8), size: UInt64) : List(UInt8)
Hash.hex(bytes: List(UInt8)) : String                  # lowercase
Hash.from_hex(text: String) : Option(List(UInt8))
Hash.equal?(a: List(UInt8), b: List(UInt8)) : Bool     # constant time
AesGcm.seal(key: List(UInt8), nonce: List(UInt8), plain: List(UInt8), aad: List(UInt8)) : List(UInt8)   # ciphertext then the 16-byte tag
AesGcm.open(key, nonce, sealed, aad) : Option(List(UInt8))
ChaCha.seal(...), ChaCha.open(...)                     # the same shape, ChaCha20-Poly1305
X25519.public(secret: List(UInt8)) : List(UInt8)
X25519.shared(secret: List(UInt8), public: List(UInt8)) : Option(List(UInt8))   # None on a low-order point
Ed25519.public(seed: List(UInt8)) : List(UInt8)
Ed25519.sign(seed: List(UInt8), bytes: List(UInt8)) : List(UInt8)               # 64 bytes
Ed25519.verify?(public: List(UInt8), bytes: List(UInt8), signature: List(UInt8)) : Bool
Password.hash(password: String, salt: List(UInt8)) : String                     # Argon2id, a PHC string; salt 16 bytes
Password.verify?(password: String, phc: String) : Bool                          # a malformed PHC string is false
random.bytes(size: UInt64) : List(UInt8)               # Random, from platform.random
Random.fixture() : Random                              # tests only; bytes from the simulator's seed, so a test replays

Key sizes: AES-GCM 32, ChaCha 32, nonces 12, X25519 32 and 32, Ed25519 seeds 32 and public keys 32, signatures 64; anything else is a crash whose message names the row and the size it got. Random is a capability like Fs: platform.random, passed as a parameter, never captured in an anonymous function, and a process holds it only if started with it. Under mo run it is the OS CSPRNG; under mo test --sim and in a test binary Random.fixture() is a deterministic stream from the run’s seed, so a test that draws a key replays.

Both runtimes call the same exports: the interpreter imports bricks/crypto.zig directly; mo build compiles the brick for the target (zig build-obj or zig build-lib on the embedded source, -OReleaseFast, -target as the C is) and links the object beside mo_rt.c, caching the object under zig-out/mo-build/.bricks/ by the source’s hash and the target so a warm build does not rebuild it. mo_rt.c declares the exports in mo_rt.h and calls them; it implements none of them. A binary built for --target Linux from the Mac still links (the brick has no libc needs beyond what std.crypto.random uses; if a target needs getrandom say so).

C. The audit items on the page. The rows in 09-stdlib.md as chapter 9 writes them, with each row’s crash rule. The vectors from part A also in the corpus as Mo: examples/basics/hash-vectors.mo (SHA-2, HMAC, HKDF, hex), examples/basics/aead-vectors.mo, examples/basics/sign-vectors.mo, examples/effects/password.mo (a hash with a fixed salt, verify true and false, a malformed string), examples/effects/random-fixture.mo (two runs of a test draw the same bytes), each with .expected and green under mo run and as a binary. The differential run: toolchain/bench/step35/diff.py, a uv project with cryptography as its only dependency (dev-time tooling, allowed by the bricks page), 1,000 random inputs per primitive at random lengths from 0 to 4,096 bytes, driven through a small Mo program under both runtimes, reporting the mismatch count per primitive (done when every count is 0). The fuzz harness: toolchain/bench/step35/fuzz.py, mutating PHC strings and hex text into Password.verify? and Hash.from_hex for ten minutes at a fixed seed under a binary, crash count on the page (the lead runs the hour).

Numbers

Best of five, both runtimes, on the VM (Robert, 17 Sep: this step runs on the VM, not the Mac): SHA-256 of 1 MiB (MB/s); HMAC-SHA256 of 64 bytes, 100,000 times; AES-256-GCM seal of 64 KiB (MB/s); Ed25519 sign and verify, 10,000 each; Password.hash once (ms); mo build warm on examples/programs/jobq before and after (s) and the binary’s size before and after (bytes); the List(UInt8) overhead on the 1 MiB hash against the brick’s own Zig test of the same bytes. Say where List(UInt8) costs more than 2× the raw call; that is a row for a later step, not this one.

Done when

zig build test green with the vectors in it, the corpus green under both runtimes, mo fmt clean, the differential run at 0 mismatches for every primitive, the ten-minute fuzz at 0 crashes, the spec lines and the README paragraph written, the numbers table, and a numbered list “Decisions the brief did not cover”. One commit per part, subject Step 35 part X, pushed after each.

Result (17 Sep 2026, 18:16 UTC; one Opus session on the VM, 15:50 to 17:56; accepted by Fable)

Three commits, Step 35 part A (ead3f81), B (18c6457), C (9092565), zig build test green at each, verified by the worker in a clean worktree per commit. The brick is toolchain/src/bricks/crypto.zig, C-ABI exports over std.crypto, its unit tests the standards’ vectors (FIPS 180-4, RFC 4231, 5869, 7748, 8032, 8439, 9106, NIST GCM 13, 14, 16). The rows are on seven new prelude names that hold no values (Hash, AesGcm, ChaCha, X25519, Ed25519, Password, and the capability Random), the interpreter imports the file and mo build compiles it once per source, target, CPU, and zig into zig-out/mo-build/.bricks/<hash>/crypto.o (about 7 s cold, nothing warm). Five corpus files with .expected, the two spec sections, the README paragraph, PRELUDE.md, and bench/step35 (a uv project with cryptography as its only dependency: diff.py, fuzz.py, measure.py, driver.mo, bench.mo, raw.zig, RESULTS.md).

Numbers (best of five, the VM’s four cores, bench/step35/RESULTS.md):

measuremo runbinary
SHA-256 of 1 MiB245.1 MB/s531.9 MB/s
HMAC-SHA256 of 64 bytes, 100,000 times68 ms35 ms
AES-256-GCM seal of 64 KiB328.9 MB/s595.2 MB/s
Ed25519 sign, 10,0001,727 ms1,059 ms
Ed25519 verify, 10,0001,125 ms704 ms
Password.hash once171 ms145 ms
the brick’s SHA-256 of 1 MiB called straight from Zig1,548 MB/s
mo build examples/programs/jobq warm, before and after0.08 s, 0.08 s4,622,832 and 5,028,800 bytes (+406 KiB)

List(UInt8) costs more than the brief’s 2× on the 1 MiB hash under both runtimes: 6.3× under mo run (a 32-byte Value per byte in and out) and 2.9× in a binary (a MoValue per byte, copied to a buffer and back). A byte-string value is a row for a later step. The first binary numbers (33 MB/s AES-GCM, 203 MB/s SHA-256) came from a brick compiled for baseline x86-64 without AES-NI and SHA-NI; a build with no --target now compiles the brick with -mcpu native, a --target build keeps the triple’s baseline and stays portable.

Audit items. The differential run (diff.py --n 1000 --seed 35): 18 rows, 1,000 inputs each, 0 mismatches under both runtimes (the Argon2id rows 130 to 183 s each, the rest under a second). The worker’s fuzz (fuzz.py --minutes 10 --seed 35, a binary): 659,600 inputs, 0 crashes. The lead’s hour (--minutes 60 --seed 1701, 18:13 to 19:13 utc, pane w7:pk): 3,855,200 inputs in 9,638 batches, 2,037 verified true, 0 crashes.

Fable’s verification (17:58 to 18:16 UTC). zig build && zig build test on main at part C: green in 5 min 48 s. Its own probe (scratchpad/probe/gen.py, seed 11: python’s cryptography generating a 32-byte key, a 12-byte nonce, up to 100 bytes of aad, a plaintext of up to 70,000 bytes, 150,000 bytes for the hash, an Ed25519 seed and message, two X25519 secrets, and an 8,160-byte HKDF, emitted as a 326 KB Mo program) printed 29 lines, checked outside: SHA-256, SHA-512, HMAC, HKDF at its 8,160 ceiling, AES-GCM and ChaCha sealed bytes, the Ed25519 public key and signature, the X25519 public key and shared secret all equal to python’s under mo run and as a binary, and the two runtimes’ outputs identical byte for byte; a flipped last tag byte, a sealed text cut to 15 bytes, and a changed aad open to None; an empty plaintext seals to 16 bytes; a 150,000-byte ChaCha round trip returns its input; a wrong message and a 32-byte non-point key verify false without a crash; the all-zero X25519 point is None; from_hex takes upper case, refuses an odd length and a non-digit, and reads "" as []; Hash.equal? is false across sizes; Password.hash of a non-ASCII password verifies true and a prefix of it false, and its tag was rederived independently by python’s Argon2id from the PHC string’s salt (equal). A 3-byte key to AesGcm.seal crashes with AesGcm.seal takes a key of 32 bytes, not 3 and exit 70 under both runtimes. An anonymous function that captures platform.random is MO0409 at check time. random-fixture.mo under mo test --sim 200 --seed 9: 3 passed, the process test held under 5% faults. mo fmt --check clean on the seven new Mo files. Peak resident memory of the probe: 105 MB under mo run, 78 MB as a binary. Two of Fable’s own mistakes cost three reruns (a 1 MiB constant made a 2 MB source past the reader’s 1 MiB limit; there is no ^ or ++ in Mo); neither is a defect.

Decisions the brief did not cover, fourteen from the worker, read and ratified as rows of 17 Sep in the decision-log: the rows-only type kind and the seven hideable names; Password.verify? taking only the exact string Password.hash writes, so a stored string cannot cost more than one hash (it also closed a trailing-$ acceptance in std’s PHC parser); Argon2 parameters the brick’s, not the caller’s; entropy from getrandom(2) on Linux and arc4random_buf on macOS, no other target compiling, since Zig 0.16 moved std.crypto.random behind Io; the fixture as ChaCha20 keyed by SHA-256 of the run’s seed, the same bytes under mo test and in a test binary; -mcpu native without --target; HKDF past 8,160 bytes and Random.bytes past 1 GiB crash; the brick’s answers a small enum, sizes checked before the call; the object cached by content and renamed into place; the .mo.ids sidecars and PRELUDE.md updated outside the brief’s write scope (right, and the scope rule is amended); two extra bench tools; the fixture stream outside the differential run; a clean worktree per part.

Carried. A byte-string value for List(UInt8)’s 6.3× and 2.9×; a Random for tests that is not the fixture (none asked); a target other than Linux and macOS (none asked).