Resources/Views/spec.leaf

@@ -3,7 +3,7 @@
 <!-- GENERATED by Scripts/build-doc-pages.sh from flamenet-e2e/docs/SPEC.md.
      Edits made HERE are deleted the next time that script runs.
      Change the markdown source and re-run it.
-     source-sha256: e44d6dd348139078 -->
+     source-sha256: 13aa934f35a182ec -->
 <article class="band doc doc-generated">
   <div class="wrap wrap-narrow">
 <h1 id="flamenet-messenger--end-to-end-encryption-spec">Flamenet
@@ -707,6 +707,63 @@ connection and rings from its own foreground service, so an Android
 client MAY set the flag for interop but gains nothing from it. The
 asymmetry is Apple's process model, not a design choice, and it belongs
 on the privacy page for the same reason the push dependency does.</p>
+<h3 id="618-mentions">6.18 Mentions</h3>
+<p>A group message MAY name the members it is addressed to, in
+<code>ment</code>:</p>
+<pre class="json"><code>{ &quot;fnc&quot;: 1, &quot;kind&quot;: &quot;text&quot;, &quot;gid&quot;: &quot;&lt;group&gt;&quot;, &quot;ment&quot;: [12, 34], &quot;caption&quot;: &quot;@Ada @Adam thoughts?&quot; }</code></pre>
+<p><strong>A mention decides whether the receiver is notified, and
+nothing else.</strong> It confers no permission, changes no state, and
+is not evidence of anything. This matters because <code>ment</code> is a
+claim by the sender like every other field in the envelope: the worst a
+dishonest one can achieve is a notification the reader is able to turn
+off.</p>
+<p><strong>Which is the rule that makes mentions safe to have.</strong>
+A mention that always broke through a mute would hand every member of a
+group a way to interrupt somebody whenever they liked — which is how
+mentions become the thing people leave a group over. A mention that
+never broke through would make muting a busy group mean missing the one
+message that was actually for you. So the responsibility splits:</p>
+<ul>
+<li>the <strong>sender</strong> decides that a message is addressed to
+somebody;</li>
+<li>the <strong>receiver</strong> decides whether being addressed is
+worth a notification.</li>
+</ul>
+<p>A client MUST make the second half a setting the receiving person
+controls, and MUST NOT let anything in an envelope override it.
+Defaulting that setting to "a mention breaks a mute" is reasonable and
+is what the reference implementation does; defaulting it to "always,
+with no way off" is not.</p>
+<p>Further requirements:</p>
+<ul>
+<li>A receiving client MUST resolve names against the group's roster and
+MUST NOT treat <code>ment</code> as naming anyone who is not a
+member.</li>
+<li><code>ment</code> MUST be bounded and deduplicated on receipt. A
+sender can name ten thousand ids in one envelope, and the cost of that
+lands on every recipient's device rather than theirs. The reference
+implementation caps at 256, far above any real roster.</li>
+<li>A client MUST NOT notify for a mention of somebody else, and SHOULD
+NOT let a person mention themselves — the only thing that achieves is
+making your own phone buzz.</li>
+<li>Reading the conversation beats a mention. A banner about a message
+already on screen is no less absurd for naming you.</li>
+<li>Omitted entirely when there are no mentions, which is nearly every
+message.</li>
+</ul>
+<p>⚠️ <strong>Muting is per conversation, not per author.</strong>
+Stated here because getting it wrong makes this section unimplementable:
+if a mute is keyed on whoever sent an arriving message, a group cannot
+be muted at all — silencing it means muting every member one at a time,
+and anyone who joins later is not covered. There is then no mute for a
+mention to break.</p>
+<p><strong>What the relay learns: nothing.</strong> <code>ment</code> is
+inside the ratchet like the rest of the content envelope. A relay cannot
+tell an addressed message from any other, and in particular cannot tell
+who in a group is being singled out.</p>
+<p><strong>Status.</strong> In progress. The iOS client implements this
+section. The Kotlin engine implements the codec; the Android app does
+not compose or act on mentions yet.</p>
 <h2 id="7-safety-numbers-verification">7. Safety numbers
 (verification)</h2>
 <p>For a local identity <code>IK_sig_local_pub</code> and remote