Security posture
This page is the security posture: what this server defends against, every hard limit with the reason for its number, and the attacks that were measured rather than imagined. It also names the limits that were wrong, and what each one cost.
The threat model, in one sentence
Every byte from the socket is hostile.
There is no authentication, no CORS and no TLS anywhere in OpenEnv.
NOT-THE-PROTOCOL.md
establishes that absence from the captured header set rather than asserting it.
So anyone who can reach the port can reach the parser, with no credential and
no warm-up. Isolation is the container's job. Refusing to crash is ours.
What is explicitly not in the model: confidentiality, integrity against a man-in-the-middle, and multi-tenancy. This server has no secrets to leak and no way to tell one peer from another. If those matter to you, they are somebody else's layer: a proxy, a mesh, a network policy. Pretending otherwise here would be the most dangerous thing this document could do.
Two of those sentences acquired a condition when tools arrived, and the
condition is the environment author. "No secrets to leak" means none of ours:
a tool handler's failure message is published to an unauthenticated peer
verbatim, so what it says is that environment's choice. And "refusing to crash
is ours" is still ours. But oe_tool.call is the first peer-reachable function
pointer in the program, and what runs behind it is not code this project wrote.
The long form is
the tool surface, and whose job it is.
The one principle
A length field is a claim, not a fact.
Every claimed length is checked against a constant in
../src/wire/limits.h ↗ on the line after it is
parsed. The check is by subtraction (claimed > limit - have), so the
comparison cannot itself overflow. A wire-derived length is named claimed_*
until it has been checked, and the prefix is dropped the moment it is:
grep -rn claimed_ src/ # every point at which attacker arithmetic enters
A claimed_len that survives to the bottom of a function is a review finding.
All narrowing goes through one audited oe_size_from_u64().
Some checks exist because the input is hostile, as opposed to because a
format requires them. The complete index of those is the SAFETY: table at the
end of BOUNDARY.md, generated from
the source. Fifty-one of them, each with its own sentence. The count is the
number of rows in that table, not a number retyped here: awk '/^## The other boundary/,0' docs/BOUNDARY.md | grep -c '^| '`.
The caps, and why each number
None is settable at runtime. A limit you can raise from outside is a limit an attacker can raise from outside, and OpenEnv has no authentication to protect a control channel with. Changing one is a recompile, which is the only permission model available here.
src/wire/limits.h carries the full argument at each #define; this table is
the index.
The wire
| Constant | Value | Why that number |
|---|---|---|
OE_WS_MAX_FRAME | 256 KiB | inbound at a server. Chosen against its product with OE_MAX_CONNECTIONS: 64 × 16 MiB is a gigabyte of attacker-directed residency on a single-threaded process. Diverges from the reference, and the cost is measured against a live upstream client — NOT-THE-PROTOCOL.md divergence 3 |
OE_WS_MAX_FRAME_CLIENT | 512 KiB | inbound at a client, 2× larger on purpose and no larger. A client does not choose what it is sent — uvicorn sends a response as one unfragmented frame and one shipped upstream environment ships 100,800 integers (403,316 bytes, measured) in a single message — but it can only promise what it can afford to parse, so the number is OE_CLIENT_MSG_ARENA_MAX / OE_JSON_ARENA_PER_BYTE. It was 16 MiB and delivered between 1.05 MB and 4.19 MB depending on the payload's shape; a static assertion in src/client/client.c now refuses to compile if the two ever disagree |
OE_WS_MAX_MESSAGE | 512 KiB | the reassembled total at a client. A per-frame cap alone lets 1,000 maximal continuation frames accumulate half a gigabyte — and this is the number the parse budget is really derived from, because reassembly finishes before the parser sees anything |
OE_WS_MAX_MESSAGE_SERVER | 1 MiB | the same, at a server, and deliberately equal to OE_HTTP_MAX_BODY: the same action document meets the same ceiling whichever transport carries it. It used to not exist |
OE_WS_MAX_CONTROL_PAYLOAD | 125 | RFC 6455 §5.5. Not our choice |
OE_HTTP_MAX_HEADER_BYTES | 32 KiB | over → 431. The largest header block observed against the reference is under 400 bytes |
OE_HTTP_MAX_HEADERS | 64 | over → 431. A header block can be small in bytes and still be thousands of fields |
OE_HTTP_MAX_TARGET | 2 KiB | over → 414. The longest legitimate target here is a two-segment path |
OE_HTTP_MAX_BODY | 1 MiB | over → 413. The largest legitimate body is one JSON document describing one call |
OE_JSON_MAX_DEPTH | 64 | a frame of nothing but [ is one level of recursion per byte — half a million at the client's 512 KiB message cap and a million at the server's 1 MiB one, a quarter of a million in any single server frame: a remote SIGSEGV from one unauthenticated frame. The deepest payload observed against the reference is 5 |
OE_JSON_ECHO_HEADROOM | 8 | the writer gets more levels than the parser, because a validation failure echoes the offending value inside four levels of our own envelope. Arithmetic, not generosity |
OE_JSON_MAX_STRING | 4 MiB | a single string value, bounded separately because an escaped string decodes to fewer bytes than it occupies, never more. No longer reachable through either transport — every message this program will read is smaller — which is deliberate: it used to be the cap a client met first for string-shaped payloads, and "which of three caps bites first depends on the shape of your document" is exactly what the 512 KiB above was chosen to remove |
OE_JSON_ARENA_PER_BYTE | 256 | measured, not chosen: bytes of arena one byte of JSON source can cost. A node is 56 bytes rounded to 64, its slot in the parent is 24 in a vector that doubles and abandons its copies, and the arena's own chunks double on top. Swept across shape families at the 512 KiB cap: dense integers 59.00, empty arrays 48.33, short strings 29.25, flat objects 22.39, object chains 43.77–48.14, and the expensive family — an array of [ chains, which climbs with depth: 93.25 at d=1, 109.00 at d=2, 121.33 at d=8, 126.83 at d=32, 128.23 at d=62, 127.85 at d=63. 256 is the next power of two above that maximum. It was 128, from a sweep that varied one family's inner length and never its depth, and 128 is below the true worst case — measured over a real socket, the old pair accepted 523,774 bytes of the deep shape and refused 523,775 with OE_ENOMEM. It is the denominator that turns a byte cap into a promise, and tests/t_client.c now parses a maximal document of the deep shape, through the same copy-then-parse sequence a real call makes, rather than trusting the arithmetic |
Concurrency and time
| Constant | Value | Why that number |
|---|---|---|
OE_MAX_CONNECTIONS | 64 | deliberately distinct from and larger than the session cap: an idle socket that has not spoken is not a session and costs an attacker nothing, so the two resources are budgeted separately. Over the cap: accept-then-close, so the kernel backlog drains instead of filling |
OE_MAX_SESSIONS | 8 | the number that appears inside a capacity refusal frame. That is why this program does not fork: a per-worker cap reported as a whole-server cap is the server lying about itself on the wire |
OE_HANDSHAKE_TIMEOUT_MS | 5000 | a connection that has neither completed a request nor upgraded is closed |
OE_WS_IDLE_MS | 20000 | and this one used to be infinite. See below |
OE_WS_ASSEMBLY_MS | 5000 | a peer part-way through a fragmented message is not idle — it is holding a reassembly buffer — so it gets the handshake's window, not the idle one |
OE_CONN_LINGER_MS | 1000 | closing a socket with unread bytes in its receive queue sends a reset, and a reset can discard data already written. Also bounds the closing handshake |
OE_SHUTDOWN_MS | 2000 | docker stop allows ten seconds before SIGKILL. Exiting in two is the difference between a clean stop and a container that is always killed |
The 65th connection is accepted, then closed — deliberately. At the cap, a
new connection that cannot be given a slot is taken off the kernel's accept
queue and hung up on in the same iteration (src/server/serve.c:723). It is
not left queued, and it is not silently dropped. This is a security choice, not
only a courtesy to the peer: refusing to accept would leave the listening
socket readable and the poll loop spinning at the speed of the kernel's
readiness reports. That is a self-inflicted busy-loop an attacker obtains for
free by holding the table full. Accepting and closing drains the backlog,
so the loop goes back to sleep. As a bonus, the honest peer gets a clean EOF
instead of a hang it must time out. The slot is unavailable only once all 64
are held by peers that have completed a request. A connection that opened and
never spoke is evicted first — the slow-loris rule, named for the attack that
holds sockets open by sending almost nothing. An idle socket that has said
nothing is the cheapest thing an attacker can hold, so it has no claim on a
slot a talker wants. The behaviour a peer sees is written up in
ERRORS.md.
Memory
Three arenas, strictly nested, each with a mandatory hard byte budget supplied
at construction. That budget is the single choke point where an
attacker-derived size is refused, which is why no individual call site needs a
guard of its own. OE_PERM_ARENA_MAX and OE_SESSION_ARENA_MAX are 1 MiB each.
The per-message budget is a flat ceiling: OE_CONN_MSG_MAX = 8 × (32 KiB + 1 MiB) + 64 KiB = 8.31 MiB, the largest request a server will accept times a
factor, once. That ceiling is what bounds node amplification. A legal 1 MiB
array of small integers is hundreds of thousands of JSON nodes, and without a
ceiling one frame demands its whole value be resident. Deriving each message's
budget from that message's length instead was built, measured and rejected;
MEMORY.md has the numbers, and
MEMORY.md is the model.
A client gets a different number for a different promise.
OE_CLIENT_MSG_ARENA_MAX is 128 MiB, and it is the numerator of the client's
advertised cap rather than a figure chosen for itself: 128 MiB / 256 = 512 KiB.
It doubled from 64 MiB when OE_JSON_ARENA_PER_BYTE was re-measured; see
below. It is a ceiling and
not a reservation, and an ordinary exchange costs a few kilobytes — but an
embedder budgeting worst case should use it.
Four limits that were wrong, and what they cost
All four were found after the code was written and working, which is the honest reason they are in this document rather than in the design.
OE_WS_IDLE_MS — the deadline that used to be disarmed at the 101
An earlier version dropped the handshake deadline at the upgrade, on the
reasoning that an idle WebSocket is a client between calls. That is true of
/ws, which is bounded by max_sessions. It is false of /mcp, which holds
no session and so was bounded by nothing at all.
Measured: 64 plain GET /mcp upgrades that then sent nothing held every
connection slot permanently, and GET /health stopped answering for the life of
the process. Twenty seconds is websockets' own ping interval, which is where
the reference's equivalent protection comes from. We do not send the ping,
because a server that heartbeats is a server with a timer per connection. So
this deadline is the whole mechanism rather than half of it.
And it was re-armed by every inbound frame, a Ping included, which was the
second half of the same mistake. A heartbeat is exactly what a peer holding a
resource for nothing wants to send. Eight /ws sockets pinging every fifteen
seconds held all eight session slots indefinitely, and every honest client got
CAPACITY_REACHED. Only a DATA frame re-arms it now. The cost is stated in the
attack table above and again at the #define: a client must call something
inside twenty seconds. An agent whose think time is longer must raise the
constant.
OE_WS_MAX_MESSAGE_SERVER — the per-frame cap that did not bound a server
A peer that opens a fragmented message and never sends FIN keeps the reassembly
buffer live for as long as the socket does. Before this constant existed, a
server read the CLIENT's cap, and one silent socket could park it. That was
16 MiB at the time (doubled to ~32 MiB by the growth of the buffer it
accumulates in), times OE_MAX_CONNECTIONS. (The client's cap is 512 KiB
today. That would have made the attack smaller, not absent: the defect was
reading the wrong side's budget.)
Measured on envs/echo: 40 sockets sending 8 MB of continuation frames each
and then going quiet held 620 MB, indefinitely. A cap bounds the size of a
hold; only a clock bounds its duration, which is why OE_WS_ASSEMBLY_MS
exists beside it.
OE_JSON_ARENA_PER_BYTE — the measurement that swept one shape family
This constant is the denominator that turns a client's byte cap into a promise,
and it was 128: the maximum of a sweep over [[1],[1],…] at every inner
length from 1 to 4097. The sweep was real and its conclusion was wrong, because
it never varied depth. The same argument that makes [[1],…] more expensive
than [1,…] — four source bytes buying two nodes and a slot in each of two
vectors — applies again at every further level. So an array of [ chains costs
93.25 bytes of arena per source byte at depth 1 and 128.23 at depth 62.
The failure was silent by construction. OE_CLIENT_MSG_ARENA_MAX was 64 MiB,
and 64 MiB / 128 is exactly 524,288. So the static assertion that exists to
keep the cap and the arena in step passed with zero slack while the cap
itself was undeliverable. Measured over a real socket, one unfragmented frame per step: a
maximal observation of the deep shape was accepted to 523,774 bytes and refused
at 523,775 with OE_ENOMEM. That is this program's own constant, named to a
caller who had been shown a different one — precisely the defect the division
was introduced to remove.
Corrected to 256, with the arena raised to 128 MiB so the advertised 512 KiB
survives. Lowering the cap instead would have refused the motivating case
(atari_env's 403,316 bytes). Re-bisected over the same socket, all five shape
families — long string, dense 1-digit, dense 3-digit, [[1],…], and depth-59
chains — now stop at 524,288 bytes and answer OE_ETOOBIG. The cost is a real
doubling of the per-handle ceiling, and README.md's limitations section says
so.
The defined refusal that was never sent
wire/limits.h justifies the flat per-connection parse ceiling with a sentence:
"a server owes a stranger no parse, only a defined refusal (500 on HTTP, 1011 on
the WebSocket)". That sentence was false for as long as it had been written.
c->out is built on c->msg, the arena a parse tree exhausts, and
oe_buf_clear clears a length rather than the ok latch. So the 500 that
src/proto/errors.c holds ready for an exhausted arena, and the 1011 that
oe_ws_send_close exists to write, were both composed into a buffer that was
already refusing, and both came out as nothing. MEASURED against
build/rel/bin/counter over a real socket, with four bodies of legal JSON:
87,037, 100,037 and 500,037 bytes of [-chains, and 200,039 of dense integers.
Every one of them got zero bytes back and a closed socket. The log said
no response could be composed: OE_ENOMEM; the peer was told nothing. The
WebSocket half is measured in tests/t_conn.c rather than over a socket; that
is the same code with the two system calls removed. Revert rearm_for_refusal
and a_message_over_the_parse_budget_is_refused_in_words_on_ws fails on its
first assertion, which is oe_buf_len(&c->out) > 0.
The fix is one helper, rearm_for_refusal in src/server/conn.c. It resets
the message arena and re-initialises the output buffer on it, before composing
a refusal made only of constants. The request bytes survive because c->in lives
in the connection arena, which is what lets the HTTP refusal still see which
method it is answering. Re-measured after: the same requests get
HTTP/1.1 500 Internal Server Error and CLOSE 1011 "internal error".
tests/t_conn.c asserts that bytes came out before it asserts which bytes,
because that is the half that was missing.
The attacks this design answers, and how
The interesting half of a threat model is the attacks that a plausible implementation would have been open to. Each row below is a design decision whose absence is a vulnerability.
| Attack | The mitigation, and where it lives |
|---|---|
| Poisoned-arena heap overflow. An allocator that hands back a small scratch page on exhaustion while callers write the size they asked for is a remote heap-corruption primitive with attacker-controlled length and contents | The arena returns NULL and latches ok = false; every builder tests the latch first and writes nothing. No scratch region exists. src/wire/arena.h |
| Slow loris, part 1: blocking. One byte, then stall, so a blocking parser holds a single-threaded server for the whole deadline | Parsers never touch a socket. Non-blocking reads fill a per-connection buffer; a cheap framing predicate gates the parser, which then sees a complete resident unit with no partial-read cases at all. src/server/conn.c |
Slow loris, part 2: slot exhaustion. The same 64 sockets, sending GET /hea and reconnecting every 5.2 s, do not block anything — they simply hold every connection slot. MEASURED before this row had an answer: legitimate GET /health over 12 s: ok=0 fail=12 | A peer that has said something outranks a peer that has not. When the table is full, free_slot in src/server/serve.c evicts the OLDEST connection still in OE_CONN_READING_REQUEST — one that has never completed a request — instead of refusing the newcomer. There is no arrow back to that state, so a peer that has finished even one exchange is never the victim. The same attack, re-measured after: ok=12 fail=0. Honest limit: this makes a slot obtainable by a peer that talks; it does not make one reservable, and there is still no per-peer limit |
A heartbeat that holds a session slot. Eight /ws sockets and one 6-byte Ping every 15 s held all eight of OE_MAX_SESSIONS indefinitely at ~3 bytes/second each, and every honest client got CAPACITY_REACHED | A control frame does not re-arm the idle deadline; only a data frame does (src/server/conn.c, advance_ws). Re-measured after, against build/rel/bin/counter with eight websockets clients pinging: an honest client is still refused at t=0 and t=15 s — the holders' twenty seconds have not run out — and at t=30 s it gets type=observation. Indefinite became bounded. The cost, stated: a client must now send a data frame inside OE_WS_IDLE_MS — 20 s — and an agent that thinks for longer must raise that constant. A cap a heartbeat can hold open is not a cap |
Write-side stall. Send reset, never read; the server blocks in the kernel send path | Per-connection outbound buffer drained on POLLOUT. send() is never blocking |
| SIGPIPE kill. Connect, send, RST — the default disposition terminates the process, so one packet kills every concurrent session | MSG_NOSIGNAL / SO_NOSIGPIPE per send, in one helper. Never a process-global signal() behind an embedder's back |
EMFILE accept-spin. At the fd limit the listener stays readable and accept() fails instantly forever — permanent 100% CPU | A spare /dev/null fd opened at startup: on EMFILE/ENFILE, close it, accept, close the accepted socket, reopen |
The same spin with no spare to sell. /dev/null exists in a scratch image only because the runtime bind-mounts /dev, and a seccomp profile that denies open has the same effect. MEASURED with the open denied: 398 CPU ticks over 4 s — one full core — and zero bytes of log | Two answers, because one was not enough. The failure is now logged at startup (no descriptor reserve), and oe_net_accept reports out_backoff for every errno that dequeues nothing, on which serve.c stops polling the listener for OE_ACCEPT_BACKOFF_MS |
An accept errno that dequeues nothing at all. ENOBUFS, ENOMEM and EPERM leave the connection on the queue, so a loop that retries never returns. MEASURED with an LD_PRELOAD shim: 103% of a core, GET /health answered nothing whatsoever (the loop never reaches poll(), so live WebSocket sessions freeze too), and the once-per-iteration log line grew stderr 560.9 MB in 4 s — 4.1 GB/minute | The same back-off, plus two bounds that do not depend on getting the errno list right: do_accept returns after at most max_conns + 1 iterations whatever happens, and the diagnostic is rate-limited to one line per second |
JSON recursion. 1 MiB of [ — the largest thing a server will read — is a remote SIGSEGV | OE_JSON_MAX_DEPTH, threaded through the parser and mirrored in the writer and in oe_json_dup |
Unbounded length claims. A 64-bit RFC 6455 length up to 2⁶⁴−1; non-minimal 126/127 forms; size_t truncation on 32-bit | Subtraction check before any narrowing; non-minimal forms and the MSB-set form rejected; one audited narrowing function |
Node amplification. A dense [1,1,1,…] costs ~59 arena bytes per source byte and an array of deep [ chains 128.23, times max_sessions | The message arena's mandatory hard ceiling, OE_CONN_MSG_MAX. Measured by bisection against it: a dense integer array stops at 131,074 bytes of source, [[1],[1],…] at 87,244, and the worst shape found — chains at depth 62 — at 67,536. The shape-independent floor is 8,716,288 / 256 = 34,048, which is the number to budget against. Exhaustion is a defined refusal — 500 on HTTP, 1011 on the WebSocket — and tests/t_conn.c pins that bytes actually come out, because for a while none did |
Injection into our own error frames. extra_forbidden's loc is the attacker's key; a %s there lets them forge "code":"CAPACITY_REACHED" into our frame, and clients branch on code | See Reflection, below |
| UTF-8 truncation as a session kill. A buffer that truncates mid-code-point emits an invalid text frame, and RFC 6455 §8.1 obliges the peer to close 1007 | oe_utf8_truncate on a code-point boundary |
Lone surrogates. "\ud800" encoded as WTF-8 and echoed is a one-frame session kill | Unpaired surrogates rejected at parse time. GAP-12 |
Interior NUL. {"cmd":"safe ; rm -rf /"} — a const char * accessor shows safe while the validator saw the whole thing | oe_str carries length end to end; oe_as_str returns the caller's fallback, never a truncated string. GAP-11 |
Request smuggling. Duplicate or conflicting Content-Length; Transfer-Encoding ignored while CL is honoured; -1; overflow; obs-fold; NUL in a header | THE SMUGGLING RULES, the complete table, at the top of src/wire/http.h. tests/t_http.c is a smuggling corpus and fuzz_http.c seeds from it |
| Use-after-free from a growing reader buffer. Header slices dangle when the body read reallocates | Fixed-capacity-per-message invariant, stated at the top of src/server/conn.h |
| Cross-arena retention. An environment stores a message-arena pointer in session state; the attacker controls the bytes it is refilled with | Generation tag asserted on every accessor in debug builds, ASan poisoning on reset, and OE_ARENA_DEBUG_MALLOC=1 as a second full pass of make test |
Weak randomness. rand()/time() for the client's Sec-WebSocket-Key and mask keys | One oe_net_random() reading /dev/urandom, with a hard failure if unavailable — never a fallback. rand/random/srand are banned and make check enforces it |
snprintf-convention overread. A size_t f(v, char *out, size_t cap) returning the needed size invites send(fd, buf, n) with n > cap | No fixed-buffer serialiser exists in the public API. Serialisation writes into an oe_buf, which owns its growth |
Malformed json_default literals. Copying an author's literal into the output as bytes and trusting it produces a 200 with broken JSON at GET /schema — the worst failure shape available, because it looks like success | Every literal goes through our own parser and back out. A bad one is OE_SCHEMA_FAULT_BAD_DEFAULT, which carries the field name and the byte offset inside the literal. Checked at BIND time, in check_schema in src/server/serve.c, before the port is taken: oe_server_new builds the whole document into a throwaway arena, logs the fault and returns NULL. This row previously recorded the opposite as an honest limitation — the only caller was do_schema, so a typo survived startup and produced a 500 on every GET /schema while GET /health answered 200, which is the one failure shape a scheduler cannot see. Should the check ever be removed, the request-time answer is still WART-19's 500 and never a broken 200 |
Reflection — where an attacker writes into our output
Five sentences echo a peer's own bytes back, out of four call sites:
| what is echoed | where |
|---|---|
an extra_forbidden key | the validator's diagnostics |
an unknown message type | src/proto/errors.c, the UNKNOWN_TYPE detail |
| the Task API's reflected path segment | src/server/http_const.c |
a JSON-RPC session id, an unknown method, and the agent door's Tool not found: <name> | src/proto/jsonrpc.c, put_reflected — one site, three sentences |
the trainer door's Unknown tool: '<name>' | src/proto/tool.c:297 |
The last two arrived with the tool vocabulary and are the ones an attacker reaches most cheaply, because a tool name is a string a peer picks outright rather than a field it has to guess. Every one of them is bounded twice:
OE_REFLECT_MAX(64 bytes) caps how much is echoed, cut on a UTF-8 character boundary, and marks the cut so a peer can tell sixty-four bytes from a truncation of six hundred.- Nothing attacker-derived ever reaches an output buffer except as a JSON
string node handed to the writer, which escapes it and refuses it if it is
not UTF-8.
oe_diagholdsoe_str, never a pre-formattedchar *, and there is no public raw-splice setter. No function that writes to a wire buffer takes a format string. The onlyprintf-family call anywhere undersrc/wire/orsrc/proto/is onesnprintf(buf, sizeof buf, "%.*e", prec, d)in the double formatter, whose arguments are anintand adouble. Everything else in theprintffamily lives insrc/server/main.candserve.c, writing tostderr. The reflectedenv_namegoes out throughoe_http_res_write, which re-checks the alphabet at the reflection site and refuses the whole response rather than sanitising a field.
The one large reflection is POST /reset's body echo, capped at
OE_REFLECT_ECHO_MAX (1 KiB) on the input rather than the output.
Escaping is an amplifier: a body of 0x01 bytes becomes six characters per
byte, and a 900 KB request measured a 5.4 MB response before that cap existed.
The reference echoes the whole body and is exactly as faithful and exactly as
amplifiable; the SAFETY: note at src/proto/decode.c makes that trade
explicit.
The tool surface, and whose job it is
This is the newest surface in the program, and the largest one this document
has had to describe. An unauthenticated peer now reaches an environment
author's C function, on five doors — five distinct wire entry points — with
an arbitrary JSON arguments value. Three statements, each with its citation.
1. arguments is unvalidated by design, and the published inputSchema is
advertisement. Nothing between the socket and oe_tool.call compares the two.
A tool declaring {"amount":{"type":"integer"}} is called with
{"amount":"seven"} and runs. That is GAP-21, argued at src/server/mcp.c
where the call is made, and it is the reference's own behaviour on the branch
whose tool shape we emit. One difference runs in our direction: the reference
reaches its handler through f(**arguments), so CPython refuses a non-mapping
arguments and any keyword the tool does not declare. C has no such convention,
so we accept four input classes a conforming server rejects. The four rows
are measured and tabulated at GAP-21; corpus case 90 holds one of them.
What follows for an author: arguments is peer input, in full. Every getter in
section 3 of <openenv/openenv.h> takes a fallback and answers for any node
shape, so reading it is safe — but believing it is not.
2. An oe_tool_fail message is published to an unauthenticated peer,
verbatim. oe__rpc_fail_tool_error (src/proto/jsonrpc.c) writes the
environment's own sentence with no cap and no filter, deliberately, because the
reference does. That is how _bump() got an unexpected keyword argument 'nope'
reaches a peer there. So the failure message is not the place for a
filesystem path, a query, a key, or anything else the peer should not have. It
is the one string in the program an author can put on the wire without any part
of this library looking at it, and the sentence at that function says so.
This is the one place "This server has no secrets to leak" at the top of this
page becomes conditional: it has none of ours. What an environment chooses to
say in a failure is that environment's business, and it is published.
3. A tool handler runs against LIVE session state on one door of five.
Reached through {"type":"mcp"} on /ws (src/server/session.c), the handler
gets the connection's own state block — the same one the session's steps have
been mutating. On the other four doors (POST /step, POST /mcp, WS /mcp,
and {"type":"step"} on /ws when the transport is stateless) it gets an
instance built for that one message and destroyed after it. So an author who
assumes reset ran first is wrong on four of five doors, and an author who
assumes the state is private to this call is wrong on the fifth. The dual-door
table in NOT-THE-PROTOCOL.md has the shapes; this
section is what they cost.
What the library still guarantees is the same guarantee as everywhere else
on this page. A peer's tool name reaches a linear scan of a const table and,
when it misses, one bounded sentence. The lookup is
length-based, so echo_message\0evil is not found rather than truncated into
a match. tests/fuzz/fuzz_tool.c points mutated bytes at all five doors,
including the one that builds and destroys an environment per message.
What points strangers' bytes at this on purpose
make fuzz-run | six fuzz targets with invariant oracles — not "does it crash" but "does any cut of this byte stream change the answer", "does writing a parsed document twice produce the same bytes", "does an oe_json_dup copy survive its source arena being released" |
make autobahn | the specification's own 517-case RFC 6455 conformance suite, against tests/autobahn/echo.c, which is src/wire/ws.c with a socket and nothing in between |
make test | every binary twice: as built, then a second pass under ASan + UBSan with OE_ARENA_DEBUG_MALLOC=1, which turns every arena allocation into a separately-poisoned malloc so a retained pointer is a diagnosed use-after-free rather than a value that happens to still be there |
They found two real bugs, both fixed, both now carrying a unit test and a
regression input under tests/fuzz/corpus/: an (int64_t) conversion of an out-of-range
double, which is undefined behaviour one POST /step {"action":{"amount":1e400}}
away; and oe_json_dup refusing, by one level, a document oe_json_parse
accepts. FUZZING.md is both, with the Autobahn results case by
case and the three places the oracle was wrong and the code was right.
Honest residual risk
Five, stated here rather than discovered.
- A slow environment
step()blocks every other session, including/health. The environment runs inside thepoll()loop. This matches the reference under a synchronous environment, andtimeout_sis validated and then never enforced (GAP-06), so no protocol obligation is broken. But it makes this server the wrong host for an environment whose step makes a network call of its own. OpenEnv's own answer to parallelism is one container per environment. - No TLS, in the server or the client.
wss://is refused atoe_client_openwith a sentence naming the problem, rather than attempted and failed. The reference's own Spaces provider answers this by running a local plaintext proxy, which is the same answer. tour/01_minimal.cis not hardened and says so in a mandatory banner. It has no length caps, no timeouts and no depth limit, because it exists to show the protocol's shape. It binds127.0.0.1where the library defaults to0.0.0.0, and nothing fromtour/is installed bymake install— the packaging test asserts that.- There is no per-peer limit anywhere. The eviction rule above makes a connection slot obtainable by a peer that talks; it does not make one reservable, and the same is true of the eight session slots. One peer that completes requests can still take every slot, because nothing here can tell one peer from another — there is no authentication in OpenEnv to tell them apart with. Isolation is the container's job; this is a case of the threat model's first sentence, not an oversight inside it.
- The accept path is fuzzed by nothing. A running server IS driven over
real sockets:
tests/t_conform.cforks one and answers all six official criteria throughoe_server_fds+oe_server_tick;tests/t_client.cpart 6 runs a whole episode — a reset, then steps, untildone— against another throughoe_server_poll; andmake autobahnputs 517 RFC 6455 cases through the framing.tests/t_conn.cdrives the state machine byte for byte with no socket at all. What none of those do is generate hostile accept-time conditions. The livelocks fixed in this phase were found with a hand-written network fuzzer and anLD_PRELOADerrno shim, neither of which is in this tree.FUZZING.mdcarries the same gap from the other side.
Reporting
This is a teaching repository, not a deployed service. If you find something
here that is wrong, the most useful form for it is a failing test in tests/
or a seed in tests/fuzz/corpus/, because that is the form that cannot regress.
See also
../src/wire/limits.h↗ — every cap, one#defineper line, each with its full argument../src/wire/http.h↗ — THE SMUGGLING RULES, and the status code each construct earns../src/wire/ws.c↗ —validate_frame: one numbered block per RFC 6455 rule, with its close code../src/wire/arena.h↗ — why an exhausted allocator returns NULL rather than a scratch bufferBOUNDARY.md— the generated index of everySAFETY:siteFUZZING.md— what the fuzzers and Autobahn foundMEMORY.md,ERRORS.md— the two models this posture rests on