<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>naftpink - websockets</title>
    <link>https://naft.pink</link>
    <description>Notes tagged websockets on naftpink.</description>
    <language>en</language>
    <atom:link href="https://naft.pink/blog/tags/websockets/feed.xml" rel="self" type="application/xml" />
    <item>
      <title>in an encrypted app, the wire schema is the threat model</title>
      <link>https://naft.pink/blog/schema-is-the-threat-model</link>
      <guid isPermaLink="true">https://naft.pink/blog/schema-is-the-threat-model</guid>
      <pubDate>Sun, 26 Jul 2026 00:00:00 GMT</pubDate>
      <description>I&apos;m rewriting my chat app instead of resuming it. The reason isn&apos;t the encryption - it&apos;s that there was never a written-down shape for a message, and in an end-to-end encrypted system that&apos;s not untidiness, it&apos;s an unauditable security boundary.</description>
      <content:encoded><![CDATA[

<p>I&#x27;m restarting my <a href="https://naft.pink/projects/encrypted-chat">self-hosted chat app</a> in 2026
rather than picking it up where it stopped. It ran through 2025, worked, and
never went public.</p>
<p>The interesting part isn&#x27;t that I&#x27;m rewriting it. It&#x27;s that the thing forcing
the rewrite isn&#x27;t the encryption, the realtime layer, or the mobile client. It&#x27;s
that a message never had a written-down shape.</p>
<h2 id="the-tool-that-was-actually-a-bug-report">the tool that was actually a bug report</h2>
<p>At some point I built a logger for my own WebSocket traffic, because I couldn&#x27;t
tell what was going over the wire. This is the line that matters:</p>
<figure data-rehype-pretty-code-figure=""><pre tabindex="0" data-language="ts" data-theme="rose-pine-moon"><code data-language="ts" data-theme="rose-pine-moon"><span data-line=""><span style="color:#EA9A97">type</span><span style="color:#908CAA">:</span><span style="color:#E0DEF4;font-style:italic"> data</span><span style="color:#3E8FB0">.</span><span style="color:#E0DEF4;font-style:italic">type</span><span style="color:#3E8FB0"> ??</span><span style="color:#F6C177"> &quot;unknown&quot;</span><span style="color:#908CAA">,</span></span></code></pre></figure>
<p>I wrote that, shipped it, used it for months, and read it as tooling. It isn&#x27;t.
It&#x27;s a defect report about the system it&#x27;s pointed at.</p>
<p>That <code>??</code> exists because the logger cannot know which shapes are legal. It&#x27;s
reaching for a field that might not be there, on an object it parsed out of a
string that might not have been JSON. Every hedge in that expression is
describing something the protocol declined to guarantee.</p>
<p>Here&#x27;s the test I wish I&#x27;d applied: <strong>if you need to build an instrument to
discover the shape of your own messages, the shape doesn&#x27;t exist.</strong> Not &quot;isn&#x27;t
documented&quot; - doesn&#x27;t exist. There was no artefact anywhere in that codebase
that could answer &quot;what is a legal message&quot;, because the answer lived
distributed across every handler that had ever been written, in the heads of
nobody but me, and only for as long as I remembered.</p>
<p>Building the instrument felt like rigour. It was avoidance with a nice console
prefix.</p>
<h2 id="why-this-is-worse-than-untidy-when-its-encrypted">why this is worse than untidy when it&#x27;s encrypted</h2>
<p>If it were an ordinary chat app, no schema is a maintenance problem. Handlers
drift, a field gets renamed in three places and not the fourth, you fix bugs for
a while. Unpleasant, survivable, fixable incrementally.</p>
<p>End-to-end encryption changes the category, because every message is now a
negotiation about what the server is allowed to know.</p>
<p>Some of a message has to be readable by the server - you cannot route what you
cannot read. The recipient, the channel, roughly when: that&#x27;s metadata, and it&#x27;s
load-bearing infrastructure. The rest is ciphertext the server must never be
able to open. The line between those two sets is not an implementation detail.
<strong>It is the security model.</strong> It&#x27;s the entire answer to &quot;what does someone who
seizes this box learn?&quot;</p>
<p>Now: where was that line written down in my system?</p>
<p>Nowhere. It was wherever a given handler happened to put a field. Adding a
feature meant adding a property to an object, and nothing anywhere would tell me
whether I&#x27;d just quietly moved something from the encrypted side to the plaintext
side. No type error. No failing test. No review comment, because it was only me.
The system would keep working perfectly while its security properties changed
underneath it.</p>
<p>You cannot audit a boundary that was never drawn. That&#x27;s the sentence the whole
project turns on, and I didn&#x27;t have it at the time.</p>
<p><a href="https://naft.pink/projects/yunoa">Yunoa</a> dodges this by being single-user - one reader, one
writer, same person, so almost everything can be ciphertext and the question
barely comes up. Put a second participant in the room and the question is the
entire design.</p>
<h2 id="this-is-also-why-its-a-rewrite">this is also why it&#x27;s a rewrite</h2>
<p>The usual advice is that rewrites are a trap, and it&#x27;s usually right. I&#x27;d defend
this one on a narrow ground: <strong>a schema is not a layer you can add later.</strong></p>
<p>Most things are addable. You can bolt on logging, caching, rate limiting, even
authentication, and the existing code mostly doesn&#x27;t need to know. A schema
isn&#x27;t like that, because every handler, every stored message and every
encryption decision was already written against its absence. Introducing one
means touching all of them simultaneously, and there is no intermediate state
where half the system has a contract and the other half doesn&#x27;t - that state is
strictly worse than either end, because now you have a guarantee that&#x27;s only
sometimes true, which is the same as no guarantee plus false confidence.</p>
<p>&quot;Retrofit the schema&quot; and &quot;rewrite it&quot; describe the same amount of work. One of
them is honest about it.</p>
<h2 id="what-im-doing-differently">what I&#x27;m doing differently</h2>
<p>Schema first, before any transport code exists. Every message type declared in
one place, with the encrypted fields and the routable fields separated <em>in the
declaration itself</em>, so that moving something across that line is a visible
change to a file whose only job is to describe the boundary.</p>
<p>Then the protocol on top of the socket that I skipped last time - message IDs,
acknowledgements, an explicit reconnect handshake - instead of calling <code>send</code>
and hoping. And a client that cannot send a message the schema doesn&#x27;t describe,
which is the property that makes all of the above stay true rather than being
true on the day I wrote it.</p>
<h2 id="still-unsolved">still unsolved</h2>
<ul>
<li>Multi-device history. A new device has to read messages it wasn&#x27;t present for, and every clean answer to that is some flavour of &quot;trust something new&quot;.</li>
<li>Group membership changes. What someone who joins today can read of yesterday, and what someone removed can still read tomorrow.</li>
<li>Notifications that are useful without leaking who a message is from.</li>
</ul>
<p>None of these are new problems and none of them are things I&#x27;ll solve better
than the people who already have. The difference is that this time I&#x27;ll be
answering them against a schema that says what a message is - rather than
discovering the answers I&#x27;d accidentally already committed to by reading my own
logs.</p>]]></content:encoded>
      <category>websockets</category>
      <category>encryption</category>
      <category>architecture</category>
    </item>
  </channel>
</rss>
