Step 36: the TLS brick, part one: a TLS 1.3 server in both runtimes

The second brick under the bricks page (bricks-and-the-cost-of-zero-dependencies) and the large one: Zig 0.16 ships a TLS 1.3 client (std/crypto/tls/Client.zig, 1,670 lines) and the record layer’s types and key schedule (std/crypto/tls.zig, 758 lines), no server. Program 7’s spec runs Redis’s suite with --tls, so Mo needs a TLS listener. The brick is written once, in Zig, like step 35’s, and used by both runtimes. This step is the server handshake and the record layer; step 37 is the client side with the certificate chain, ALPN, and the differential run against OpenSSL. Nothing of TLS 1.2, tickets, PSK, 0-RTT, or client certificates in either.

Orientation

Step 35’s brick and its two seams are the pattern: toolchain/src/bricks/crypto.zig (C-ABI exports over std.crypto; the interpreter imports it, mo build compiles and caches it), src/crypto_rows.zig (the rows), cbuild.zig (the .bricks/ cache and the link), runtime/mo_rt.h and mo_rt.c (the declarations and the C rows that only call the exports). The sockets: src/net.zig (Conn, its buffer, readLine, writeAll, the poller’s fibers), src/sources.zig (how serve and lines pump), and their C twins in mo_rt.c (search read_line, lines, Accepted). The spec: 09-stdlib.md ## Net (the Conn rows and NetError), ## Rules for every row, ## Files for the shape of a capability’s section; 06-packages.md for what a brick is. Zig’s TLS: tls.zig (ContentType, HandshakeType, ExtensionType, CipherSuite, HandshakeCipherT, ApplicationCipherT, hkdfExpandLabel, Decoder), tls/Client.zig (init is the whole client handshake; read it for the record layer, the transcript hash, the key schedule, and how it reads records, then write the server’s half), Certificate.zig (DER parsing, parse, the public key and its algorithm), crypto/ecdsa.zig (P-256 signing, EcdsaP256Sha256), 25519/ed25519.zig. OpenSSL 3.0 is on the VM at /usr/bin/openssl (s_client, s_server, req, s_time): dev-time tooling, allowed by the bricks page, never linked.

Write scope

toolchain/ (the brick src/bricks/tls.zig, the rows, the runtime, the build, PRELUDE.md, bench/step36/), examples/effects/tls*.mo with their .expected and a examples/effects/tls/ folder for the PEM fixtures, examples/README.md’s list, the .mo.ids sidecars, and these spec lines only: a ## Tls section in 09-stdlib.md in the file’s table form after ## Http, and the runtime paragraph of toolchain/README.md. Nothing else under mo-wiki/.

Parts

A. The brick, an engine over bytes. toolchain/src/bricks/tls.zig, C-ABI exports, no sockets and no allocator of the runtime’s: a server holds a parsed certificate chain and its private key; a connection is a state machine that takes ciphertext in and gives plaintext out, and plaintext in and ciphertext out, so each runtime drives it from its own socket and scheduler and the brick is written once:

mo_tls_server_new(cert_pem, key_pem) -> server or an error naming what failed
mo_tls_conn_new(server) -> conn
mo_tls_feed(conn, bytes)                      # ciphertext from the socket
mo_tls_read(conn, out) -> n | want_more | closed | alert   # plaintext the records held
mo_tls_write(conn, plain)                     # plaintext the program wrote
mo_tls_flush(conn, out) -> n                  # ciphertext to put on the socket (handshake replies too)
mo_tls_close(conn)                            # queues close_notify
mo_tls_free(conn), mo_tls_server_free(server)

The server handshake per RFC 8446: ClientHello (versions, the two suites TLS_AES_128_GCM_SHA256 and TLS_CHACHA20_POLY1305_SHA256, the key share on X25519, a HelloRetryRequest once when the client supports X25519 but sent no share for it, handshake_failure otherwise, SNI read and ignored, ALPN read and left unanswered until step 37), ServerHello, EncryptedExtensions, Certificate (the chain as given, leaf first), CertificateVerify (Ed25519 or ECDSA P-256 by what the key is), Finished; the client’s Finished checked; the key schedule and transcript hash as Client.zig does them; application records both ways with the sequence numbers and the 16 KiB limit; KeyUpdate from the client answered when it asks, and one sent on request of the runtime (never needed this step); close_notify both ways; every alert the client sends is closed with its description. The record layer’s AEADs, HKDF, X25519, and the signatures come from std.crypto, nothing hand-rolled. PEM: the certificate chain and a PKCS#8 private key (BEGIN PRIVATE KEY, Ed25519 or P-256), the only forms openssl req -newkey ed25519 and -newkey ec write. Unit tests in the file, run by zig build test: a full handshake and a megabyte both ways against Zig’s own std.crypto.tls.Client in memory for each suite and each key type (the client set to trust the test certificate); the RFC 8448 key schedule’s derived secrets from its section 3 transcript (the traces are a client’s; the schedule is shared); a truncated record, a wrong Finished, a record past 16 KiB plus 256, and a bad tag each rejected with the alert RFC 8446 names; a KeyUpdate round trip.

B. The rows, both runtimes. One capability, Tls, platform.tls in main, and a Conn that stays a Conn, so every row after the handshake (read_line, write, close, lines) and every program written against a plain socket work unchanged behind TLS:

enum TlsError
  BadPem        # the certificate or the key does not parse, or they do not match
  Handshake     # the client's hello or finish is wrong, or it sent an alert; the conn is closed
  Timeout       # the handshake did not finish within the deadline; the conn is closed
  Closed
end
 
Tls.server(cert: String, key: String) : Result(TlsServer, TlsError)    # PEM text, read by the program with Fs
TlsServer.accept(conn: Conn, within: Duration) : Result(Conn, TlsError) # the handshake; the Conn it gives is the same connection, its bytes now records

Tls is a capability like Net: passed as a parameter, never captured (MO0409), never stored (MO0403). A TlsServer holds no authority beyond its own key and may be stored and shared (it is what a listener process starts its workers with). accept takes a Conn that has had no read_line, write, or lines on it (a crash names the row otherwise: the caller broke a rule) and waits at most within for the client’s handshake; the Conn it returns reads and writes through the engine in both runtimes, with the same buffering rules and NetErrors as before, and close sends close_notify before the socket closes. Under Net.fixture() the same rows work on the in-memory network, so a test can drive a handshake once step 37’s client exists; this step’s tests use the brick’s own Zig client. Both runtimes call the same exports; mo build compiles the TLS brick as it compiles the crypto brick (one object per brick, each cached by its own source hash; or one object for both if that is simpler, said in the decisions).

C. The audit items on the page, and the corpus. The rows in 09-stdlib.md as chapter 9 writes them, with each row’s crash rule. examples/effects/tls-echo.mo: a main that reads tls/cert.pem and tls/key.pem (both Ed25519, generated once with openssl req -x509 -newkey ed25519 -days 3650 -subj /CN=localhost, checked in beside a P-256 pair tls/cert-p256.pem, tls/key-p256.pem), listens on the port in args, and echoes lines back through TLS; tests that a TlsServer from a bad PEM is BadPem, that a key of the other pair is BadPem, and that accept on a fixture connection whose client writes plain text is Handshake. examples/effects/tls-echo.expected from a mo run with no client (the program prints its port and exits on Idle). The bench/step36/ folder, a uv project with no dependencies: handshake.py (openssl s_client in a loop, both suites, both key pairs: handshakes a second and the count that failed, against the echo under mo run and as a binary), bulk.py (100 MiB through openssl s_client and back, MB/s, both suites, both runtimes), idle.py (1,000 idle TLS connections, the server’s resident memory before and after, per connection), abuse.py (a plain HTTP request, a TLS 1.2-only client (-tls1_2), a client offering only P-256 key shares (-groups P-256), a hello cut off mid-record, a client that never finishes, and a 64 KiB record: each answered with the alert or the timeout the brief names, the server still serving after), and README.md saying how to run them.

Numbers

Best of five, both runtimes, on the VM: handshakes a second with openssl s_client (each suite, each key type); 100 MiB through the echo and back over TLS against the same echo over a plain Conn (MB/s, both suites); resident memory per idle TLS connection at 1,000 connections against a plain connection’s; echo-1k’s round trips over TLS against plain; mo build warm on examples/programs/jobq before and after (s), and the binary’s size before and after (bytes). Say where a record costs more than twice a plain read or write.

Done when

zig build test green with the brick’s tests in it (both suites, both key types, the RFC 8448 schedule, the five rejections, KeyUpdate), the corpus green under both runtimes, mo fmt clean, the four bench scripts run with their numbers on bench/step36/RESULTS.md, abuse.py at every case answered as named and the server serving after, the spec section and the README paragraph written, the numbers table, and a numbered list “Decisions the brief did not cover”. One commit per part, subject Step 36 part X, pushed after each.

Result (17 Sep 2026, 10:15 PM ET; one Opus session 3:27 to 6:41 PM ET, two fix sessions after; accepted by Fable)

Five commits: 9c753e1 (part A, the brick), dd2e385 (part B, the rows in both runtimes), 4cb0fc8 (part C, the page, the corpus, the four runs), 6af598d (fix 1, the KeyUpdate test), 0fe9669 (fix 2, the certificate path). toolchain/src/bricks/tls.zig is 2,077 lines: a server engine over bytes (mo_tls_server_new, conn_new, feed, read, write, flush, sent, close), TLS 1.3 with the two suites, X25519 with one HelloRetryRequest, Ed25519 and P-256 certificates from PEM, KeyUpdate, close_notify, sixteen tests in the file (Zig’s own tls.Client over a socketpair for each suite and key type, the RFC 8448 schedule, the five rejections, KeyUpdate). platform.tls, Tls.server(cert:, key:), TlsServer.accept(conn, within:), Tls.fixture(), in both runtimes; a Conn stays a Conn after the handshake. The spec’s ## Tls, examples/effects/tls-echo.mo with two PEM pairs, bench/step36/ (no dependencies; OpenSSL 3.0 is the client in every run).

Numbers (the VM’s four cores, best of five, both runtimes; bench/step36/RESULTS.md, taken with an orphan on one core, see audit/evidence/2026-09-17/README.md):

measuremo runbinary
handshakes a second, Ed25519, AES-128-GCM (openssl s_time -new)1,0261,196
handshakes a second, P-256765804
100 MiB through the echo, plain Conn488 MB/s477 MB/s
the same over AES-128-GCM203 MB/s (2.4×)268 MB/s (1.8×)
the same over ChaCha20-Poly1305121 MB/s (4.0×)155 MB/s (3.1×)
a round trip, 1,000 short lines, plain / AES-GCM27 / 38 µs23 / 28 µs
resident memory per idle connection, plain / TLS (1,000 connections)2.9 / 9.6 KiB5.9 / 12.6 KiB
jobq’s warm build, before and after0.06 s, 0.06 s5,031,128 → 5,425,072 bytes (+394 KiB)

A record costs more than twice a plain write on three of four bulk rows (ChaCha20 has no CPU instruction here, and every byte is copied once more than a plain write: the socket’s bytes into the engine, the engine’s plaintext into the connection’s buffer). Round trips are inside the brief’s 2×. The suite makes no difference to a handshake; the key does (P-256 signing is a quarter slower). The abuse run: fourteen rows as named under both runtimes, the server serving after each (a plain HTTP request alert 10, TLS 1.2 only alert 70, P-256 shares only alert 40, a hello cut off and a client that never finishes held to the 10 s deadline then closed, a 64 KiB record alert 22, -groups P-256:X25519 a HelloRetryRequest then an echo).

What verification found, and the two fixes. The worker reported zig build test green at every commit and the corpus green under both runtimes. Neither was true. Fable’s suite run hung for 21 minutes; gdb on it showed the brick’s test “a KeyUpdate round trip” blocked in a write on its socketpair with the client thread waiting; the test hung on every run (fable-probe/tls-brick-tests-before-fix.log). The fix worker named the cause: the test’s handshake loop never called mo_tls_sent after mo_tls_flush, so it wrote the server’s first flight again and again; Zig’s client read the second copy as a post-handshake record, failed, and stopped reading, and the next write blocked with no bound. Tests only were changed: writeAllFd polls thirty seconds before every write and fails with TestTimedOut, a ClientThread shuts every end and joins on every exit, and the test now fails within 32 s if the call is removed again. The fix worker’s two full-suite runs (651 and 655 s) were then 224 of 225: the corpus test of tls-echo.mo printed “no certificate”, because main read examples/effects/tls/cert.pem relative to the working directory and the corpus runs a program from its own folder. Fix 2 made the program read tls/cert.pem and tls/key.pem as the brief said and the bench start the echo from examples/effects; the verified: line was rewritten with mo test --write. Fable’s suite run after both fixes, on a quiet machine (load 0.02): 225 of 225 in 10 min 47 s (fable-probe/zig-build-test.log).

Fable’s probes (fable-probe/probe.py, openssl s_client and Python’s ssl against the example echo, both runtimes, 22 of 22): a non-ASCII line and an empty line echoed; a 60,000-byte line (four records each way) intact; a KeyUpdate from s_client’s K command then a line echoed; a client offering only TLS_AES_256_GCM_SHA384 refused with handshake_failure and the server serving after; fifty concurrent handshakes all echoed; the certificate served equals cert.pem byte for byte; a client trusting the other pair’s certificate refuses this server; a socket dropped mid-line with no close_notify leaves the server serving; 200 connections opened and closed grow resident memory by 1.2 MB under mo run and 0.6 MB in a binary.

Decisions the brief did not cover, nineteen from the worker (worker-raw/worker-report-pane.txt) and eleven from the two fixes, read and ratified as rows of 17 Sep in the decision-log except where a row says otherwise: flush peeks and sent consumes (the hang was a test that forgot sent); one object per brick, each cached by its own hash; the TLS brick’s own ten-line entropy function, since two objects cannot share an export; Tls.fixture() added for the corpus tests; Tls.server(cert:, key:) with PEM text; TlsServer a capability kind like Listener; the server table beside the sockets, not on a Vm (a real bug the example found); a Conn records the first row that used it so accept’s crash can name it; alerts for the unnamed cases; the server’s suite preference AES-128-GCM first; a stream that ends without close_notify is eof, as a plain socket’s end, the truncation left to the program; the plain echo as the baseline; Python’s ssl for the thousand idle connections; s_time for handshakes; the retry case; the example ends on Idle through a kept reply; the PEM text carried in the example as functions so its tests need no file.

Carried. The extra copy per byte in the record path (decrypt into the connection’s buffer in place); every binary links both bricks whether or not the program uses them (+394 KiB); a KeyUpdate from the server is checked as queued, never delivered to a client (step 37, with the client); two tests still swallow TestTimedOut behind an assertion; ChaCha20’s 3 to 4× is std.crypto’s on this CPU; the shipped numbers were taken with one core busy.

Fix, 17 Sep 2026, 7:30 PM ET: the KeyUpdate test hangs

The lead’s verification of part C found zig build test never finishing: the brick’s test “a KeyUpdate round trip” (toolchain/src/bricks/tls.zig, line 1638) deadlocks. gdb on the hung suite: the main thread in writeAllFd(fd=6, 762 bytes) inside the test’s handshake loop, blocked in the kernel’s unix_stream_sendmsg; the client thread (ClientRun.run, Zig’s tls.Client over testing.io) and the runner’s threads in futex_wait. Deterministic on the VM: it hung in the full suite (21 minutes before the lead stopped it) and again in zig test src/bricks/tls.zig alone (tests 1 to 10 pass; 11 hangs until timeout 300). The worker’s own runs passed, so the deadlock is timing-dependent: two blocking sides over a socketpair with nothing that guarantees one of them reads.

Write scope: toolchain/src/bricks/tls.zig, its tests only; nothing in the brick’s behaviour, its exports, the rows, or the runtimes changes.

Done when: the cause of the deadlock is named in the commit message (why the client thread stops reading, and why only this test); the test harness is made unable to hang: the main thread’s writes and reads are bounded (poll with a deadline before every write as readSomeFd already does before reads, or a nonblocking fd with a deadline loop), the client thread is bounded the same way, and a wrong test fails with a named error within 30 seconds instead of hanging; zig test src/bricks/tls.zig green five times in a row; zig build test green twice in a row; one commit, Step 36 fix: the KeyUpdate test, pushed. Say in the report whether the test still exercises a KeyUpdate from the client and one from the server.

Fix 2, 17 Sep 2026, 9:30 PM ET: the example reads its certificate by the wrong path

The fix worker’s two full-suite runs (651 and 655 s) were 224 of 225: the corpus test of examples/effects/tls-echo.mo prints “no certificate”, because main reads examples/effects/tls/cert.pem relative to the working directory and the corpus test runs a program from its own folder, examples/effects. The brief’s part C said tls/cert.pem and tls/key.pem. The part C worker’s claim that the corpus was green under both runtimes was wrong, as was its claim of a green suite at every commit (the KeyUpdate hang was in part A’s tree).

Decision (Fable): the program reads tls/cert.pem and tls/key.pem, relative to its own folder as the brief said and as every other corpus example with data does; toolchain/bench/step36/common.py runs the echo with examples/effects as the working directory (and its P-256 tree copies the pair under tls/ there), so the bench’s runs match the corpus’s. The expected output does not change.

Write scope: examples/effects/tls-echo.mo (the two paths and nothing else), toolchain/bench/step36/common.py (the working directory and the copy), examples/effects/.mo.ids if the verified: line moves. Done when: mo run examples/effects/tls-echo.mo -- 18443 1000 from examples/effects prints the .expected; zig build test green (225 of 225) once under timeout 1800; uv run python abuse.py in bench/step36 green under both runtimes after the change; one commit Step 36 fix 2: the certificate path, pushed.

Correction, 18 Sep 2026, 02:50 UTC (17 Sep, 10:50 PM ET), after both readings

Three statements in the Result above are wrong and stand corrected here rather than rewritten (the decision log of 18 Sep has a row for each): the numbers were not taken with an orphan on one core (the orphan died 21:26 UTC, the bench ran between 22:00 and 22:40 UTC by the commit times; the evidence README’s load 0.38 is the right condition); the abuse run shows the server serving after the batch, not after each case (abuse.py runs all cases, then all checks); and the tests against Zig’s own client cover P-256 and one suite, the matrix running against the brick’s own TestClient. Also, no export sends a KeyUpdate on the runtime’s request; the carried line’s “checked as queued” was the reply to the client’s request. All four go to step 37. The readings: audit/fable-reading-2026-09-18-step-36.md and audit/mo-audit-2026-09-18-step-36.md.