@nodefony/realtime 10.0.0-beta.5 → 10.0.0-beta.7

package/dist/nodefony/src/backplane/envelope.js

@@ -1,4 +1,5 @@
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { ownField } from "nodefony";
+import { createHmac, createSecretKey, timingSafeEqual } from "node:crypto";
 // nodefony/src/backplane/envelope.ts
 /**
 * **Sceau d'enveloppe backplane** — authenticité des messages transportés sur un
@@ -25,25 +26,211 @@ import { createHmac, timingSafeEqual } from "node:crypto";
 * canal (`chat:` → `nodefony:audit`), ni substitution de charge.
 *
 * Hors portée (assumé, cf sémantique at-most-once du port) : le **rejeu**. Un
-* tiers qui lit le bus peut re-publier un message scellé intact ; l'effet se
-* limite à re-diffuser une charge déjà diffusée sur un canal déjà broadcast, que
-* le client realtime re-synchronise. Un anti-rejeu (horodatage + fenêtre) exigerait
-* des horloges alignées entre pods pour un gain nul face à ce modèle de menace.
+* tiers qui lit le bus peut re-publier un message scellé intact. Pour une
+* publication, l'effet se limite à re-diffuser une charge déjà diffusée sur un
+* canal déjà broadcast. Pour un **ordre** (fermer, éjecter), le rejeu RECOUPE —
+* l'effet reste soustractif, jamais une admission (ADR-0022 §6 d4). Une fin vise
+* un canal qui porte son instance (`room:42:<partie>`) : rejouée, elle ne désigne
+* plus rien de vivant. Une éjection vise `(canal, compte)` : rejouée sur un canal
+* DURABLE, elle recoupe le compte à chaque réadmission — risque accepté en 10.0,
+* borné (écrire sur le bus est requis ; changer le secret rend caducs les ordres
+* captés), parade réservée par le champ optionnel `generation` de l'ordre. Un
+* anti-rejeu par horodatage exigerait des horloges alignées entre pods.
+*
+* **Aucune reconversion de la charge** (ADR-0021 S6) : à l'envoi, la charge est
+* encodée UNE fois et l'enveloppe assemblée par fragments ; à la réception, le
+* sceau se vérifie sur la TRANCHE reçue de la charge, et l'écho d'un pod se
+* reconnaît à la fin du message, sans le décoder. Une forme différente (producteur
+* tiers : clés dans un autre ordre, espaces, nombres non canoniques) retombe sur la
+* vérification par re-sérialisation : on accepte strictement plus qu'avant, jamais
+* moins.
+*
+* Pourquoi lire la tranche reçue est sûr : le sceau valide un triplet (origine,
+* canal, texte de la charge) émis par un pair ; la forme vérifiée autour de la
+* tranche est exactement celle qu'il écrit, donc le message reçu EST ce message
+* émis, octet pour octet — et son décodage, déterministe, rend la charge signée.
 */
 /** Nom du champ portant le sceau dans l'enveloppe sérialisée. */
 const SEAL_FIELD = "sig";
+/** Longueur d'un sceau : HMAC-SHA256 (32 octets) en base64url, sans remplissage. */
+const SEAL_CHARS = 43;
+const TEXT_HEAD = "{\"channel\":";
+const TEXT_PAYLOAD_KEY = ",\"payload\":";
+const TEXT_ORIGIN_KEY = ",\"originId\":";
+const TEXT_SEAL_KEY = `,"${SEAL_FIELD}":"`;
+const TEXT_SEAL_END = "\"}";
+/**
+* Guillemet fermant du canal suivi de la clé de charge. Cette suite ne peut
+* apparaître DANS une chaîne JSON — un `"` y est toujours échappé — donc sa
+* première occurrence après l'ouverture du canal en marque la fin.
+*/
+const TEXT_CHANNEL_CLOSE = `"${TEXT_PAYLOAD_KEY}`;
+const TEXT_HEAD_LEN = 11;
+const TEXT_PAYLOAD_KEY_LEN = 11;
+const TEXT_ORIGIN_KEY_LEN = 12;
+const TEXT_SEAL_KEY_LEN = TEXT_SEAL_KEY.length;
+const TEXT_SEAL_END_LEN = 2;
+const TEXT_CHANNEL_CLOSE_LEN = TEXT_CHANNEL_CLOSE.length;
+/** `"` — ouvre la chaîne JSON du canal. */
+const QUOTE = 34;
+/** En-tête d'une map CBOR de 3 entrées (enveloppe nue). */
+const CBOR_MAP_3 = 163;
+/** En-tête d'une map CBOR de 4 entrées (enveloppe scellée). */
+const CBOR_MAP_4 = 164;
+/** Type majeur 3 (chaîne de texte), longueur dans l'octet initial (< 24). */
+const CBOR_TEXT = 96;
+/** Chaîne de texte, longueur sur 1 / 2 / 4 octets qui suivent. */
+const CBOR_TEXT_1 = 120;
+const CBOR_TEXT_2 = 121;
+const CBOR_TEXT_4 = 122;
+/** Taille de l'en-tête CBOR d'une chaîne de texte de `len` octets (forme la plus courte). */
+function cborTextHeadSize(len) {
+	if (len < 24) return 1;
+	if (len < 256) return 2;
+	if (len < 65536) return 3;
+	return 5;
+}
+/** Écrit l'en-tête CBOR d'une chaîne de `len` octets ; rend la position suivante. */
+function writeCborTextHead(out, at, len) {
+	if (len < 24) {
+		out[at] = CBOR_TEXT + len;
+		return at + 1;
+	}
+	if (len < 256) {
+		out[at] = CBOR_TEXT_1;
+		out[at + 1] = len;
+		return at + 2;
+	}
+	if (len < 65536) {
+		out[at] = CBOR_TEXT_2;
+		out[at + 1] = len >>> 8;
+		out[at + 2] = len & 255;
+		return at + 3;
+	}
+	out[at] = CBOR_TEXT_4;
+	out[at + 1] = len >>> 24;
+	out[at + 2] = len >>> 16 & 255;
+	out[at + 3] = len >>> 8 & 255;
+	out[at + 4] = len & 255;
+	return at + 5;
+}
+/** L'en-tête CBOR d'une chaîne de `len` octets se trouve-t-il à `at` (forme la plus courte) ? */
+function cborTextHeadAt(raw, at, len) {
+	if (len < 24) return raw[at] === CBOR_TEXT + len;
+	if (len < 256) return raw[at] === CBOR_TEXT_1 && raw[at + 1] === len;
+	if (len < 65536) return raw[at] === CBOR_TEXT_2 && raw[at + 1] === len >>> 8 && raw[at + 2] === (len & 255);
+	return raw[at] === CBOR_TEXT_4 && raw[at + 1] === len >>> 24 && raw[at + 2] === (len >>> 16 & 255) && raw[at + 3] === (len >>> 8 & 255) && raw[at + 4] === (len & 255);
+}
+/**
+* Longueur de la chaîne CBOR dont l'en-tête est à `at`, et taille de cet en-tête,
+* écrites dans `into` (`[longueur, taille]`) ; `false` si ce n'est pas une chaîne
+* de texte à longueur définie.
+*/
+function readCborTextHead(raw, at, into) {
+	const b = raw[at];
+	if (b === void 0) return false;
+	if (b >= CBOR_TEXT && b < CBOR_TEXT_1) {
+		into[0] = b - CBOR_TEXT;
+		into[1] = 1;
+		return true;
+	}
+	if (b === CBOR_TEXT_1 && at + 1 < raw.length) {
+		into[0] = raw[at + 1] ?? 0;
+		into[1] = 2;
+		return true;
+	}
+	if (b === CBOR_TEXT_2 && at + 2 < raw.length) {
+		into[0] = (raw[at + 1] ?? 0) << 8 | (raw[at + 2] ?? 0);
+		into[1] = 3;
+		return true;
+	}
+	if (b === CBOR_TEXT_4 && at + 4 < raw.length) {
+		into[0] = ((raw[at + 1] ?? 0) << 24 >>> 0) + ((raw[at + 2] ?? 0) << 16 | (raw[at + 3] ?? 0) << 8 | (raw[at + 4] ?? 0));
+		into[1] = 5;
+		return true;
+	}
+	return false;
+}
+/** Chaîne CBOR complète (en-tête + octets UTF-8) — pour les fragments fixes. */
+function cborText(value) {
+	const len = Buffer.byteLength(value, "utf8");
+	const out = new Uint8Array(cborTextHeadSize(len) + len);
+	Buffer.from(out.buffer, out.byteOffset, out.byteLength).write(value, writeCborTextHead(out, 0, len), "utf8");
+	return out;
+}
+const CBOR_KEY_CHANNEL = cborText("channel");
+const CBOR_KEY_PAYLOAD = cborText("payload");
+const CBOR_KEY_ORIGIN = cborText("originId");
+const CBOR_KEY_SEAL = cborText(SEAL_FIELD);
+/** En-tête de la chaîne du sceau : 43 caractères ASCII. */
+const CBOR_SEAL_HEAD = Uint8Array.of(CBOR_TEXT_1, SEAL_CHARS);
+/** Octets fixes de la queue scellée, après la chaîne de l'origine. */
+const CBOR_SEAL_TAIL_LEN = CBOR_KEY_SEAL.length + CBOR_SEAL_HEAD.length + SEAL_CHARS;
+/** `frag` est-il présent tel quel dans `raw` à la position `at` ? Aucune allocation. */
+function bytesAt(raw, at, frag) {
+	if (at < 0 || at + frag.length > raw.length) return false;
+	for (let i = 0; i < frag.length; i += 1) if (raw[at + i] !== frag[i]) return false;
+	return true;
+}
+/** Vue `Buffer` sur les mêmes octets (aucune copie) — pour les lectures de chaînes. */
+function asBuffer(raw) {
+	return Buffer.isBuffer(raw) ? raw : Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength);
+}
 /**
-* Sceau HMAC-SHA256 (base64url) d'un triplet **déjà sérialisé**. Le `\n` sépare
-* trois fragments JSON : les deux premiers sont des chaînes échappées, donc
-* aucun décalage de frontière n'est possible entre les parties.
+* Début de la chaîne canonique : `originId\nchannel\n`, fragments JSON. Les deux
+* premiers sont des chaînes échappées : aucun décalage de frontière n'est
+* possible, et la charge, en dernier, n'a pas de frontière à garder.
+*/
+function sealHead(originIdJson, channelJson) {
+	return `${originIdJson}\n${channelJson}\n`;
+}
+/** Dernière clé préparée et son secret (un serveur n'en a qu'un : la case unique suffit). */
+let preparedSecret = null;
+let preparedKey = null;
+/**
+* Clé HMAC préparée UNE fois par secret : une chaîne passée à `createHmac` est
+* réencodée à chaque appel (mesuré : ~150 ns par sceau). Mêmes octets de clé — le
+* secret en UTF-8, comme `createHmac` l'aurait fait.
+*/
+function keyOf(secret) {
+	if (secret !== preparedSecret || preparedKey === null) {
+		preparedKey = createSecretKey(Buffer.from(secret, "utf8"));
+		preparedSecret = secret;
+	}
+	return preparedKey;
+}
+/**
+* Sceau (HMAC-SHA256 en base64url) de la chaîne canonique — un seul calcul.
 *
-* Prend les fragments et non le message : la charge n'est sérialisée **qu'une
-* fois** par publication (elle sert et au sceau et à l'enveloppe finale) — sur
-* un canal de fan-out, une seconde sérialisation par message se paierait à
-* chaque diffusion.
+* Une charge TEXTE est concaténée à l'en-tête : un seul passage vers le moteur de
+* hachage coûte moins qu'une concaténation (mesuré : ~250 ns de moins) ; des
+* OCTETS s'ajoutent tels quels, sans copie. Rendu en base64url, jamais en
+* `Buffer` brut : allouer le `Buffer` du résultat coûte plus que de l'encoder
+* (mesuré : ~900 ns).
 */
-function seal(originIdJson, channelJson, payloadJson, secret) {
-	return createHmac("sha256", secret).update(`${originIdJson}\n${channelJson}\n${payloadJson}`).digest("base64url");
+function sealText(head, payload, secret) {
+	const hmac = createHmac("sha256", keyOf(secret));
+	return (typeof payload === "string" ? hmac.update(head + payload) : hmac.update(head).update(payload)).digest("base64url");
+}
+/**
+* Le sceau fourni correspond-il au sceau calculé ? À temps constant.
+*
+* Voie courante : les deux chaînes base64url comparées caractère par caractère,
+* SANS sortie anticipée (le OU accumulé ne dépend que de la longueur, publique :
+* celle de SHA-256) et sans allocation. Repli : un sceau écrit sous une autre forme
+* base64 (remplissage, alphabet standard) est décodé et comparé par
+* `timingSafeEqual` — on accepte ce qu'on acceptait avant. Le repli ne se prend
+* que si la voie courante échoue : il ne révèle rien du secret.
+*/
+function sealMatches(provided, expected) {
+	if (provided.length === expected.length) {
+		let diff = 0;
+		for (let i = 0; i < expected.length; i += 1) diff |= provided.charCodeAt(i) ^ expected.charCodeAt(i);
+		if (diff === 0) return true;
+	}
+	const a = Buffer.from(provided, "base64url");
+	const b = Buffer.from(expected, "base64url");
+	return a.length === b.length && timingSafeEqual(a, b);
 }
 /**
 * Sérialise un message backplane, scellé si un secret est fourni.
@@ -61,14 +248,24 @@ function sealBackplaneEnvelope(msg, secret) {
 	const channelJson = JSON.stringify(msg.channel);
 	const originIdJson = JSON.stringify(msg.originId);
 	const payloadJson = JSON.stringify(msg.payload) ?? "null";
-	const sig = seal(originIdJson, channelJson, payloadJson, secret);
-	return `{"channel":${channelJson},"payload":${payloadJson},"originId":${originIdJson},"${SEAL_FIELD}":"${sig}"}`;
+	const sig = sealText(sealHead(originIdJson, channelJson), payloadJson, secret);
+	return TEXT_HEAD + channelJson + TEXT_PAYLOAD_KEY + payloadJson + TEXT_ORIGIN_KEY + originIdJson + TEXT_SEAL_KEY + sig + TEXT_SEAL_END;
 }
 /** Type-guard d'enveloppe — narrowing sûr d'un message brut venu du bus. */
 function isEnvelope(m) {
-	if (typeof m !== "object" || m === null) return false;
-	const e = m;
-	return typeof e.channel === "string" && typeof e.originId === "string";
+	return typeof ownField(m, "channel") === "string" && typeof ownField(m, "originId") === "string";
+}
+/**
+* Tranche de la charge dans une enveloppe texte reçue, si elle a EXACTEMENT la
+* forme qu'écrit {@link sealBackplaneEnvelope} pour ce canal, cette origine et ce
+* sceau ; `null` sinon (forme tierce → repli).
+*/
+function receivedPayloadText(raw, channelJson, originIdJson, provided) {
+	const start = TEXT_HEAD_LEN + channelJson.length + TEXT_PAYLOAD_KEY_LEN;
+	const originAt = raw.length - TEXT_SEAL_END_LEN - provided.length - TEXT_SEAL_KEY_LEN - originIdJson.length - TEXT_ORIGIN_KEY_LEN;
+	if (originAt <= start) return null;
+	const sealAt = originAt + TEXT_ORIGIN_KEY_LEN + originIdJson.length + TEXT_SEAL_KEY_LEN;
+	return raw.startsWith(TEXT_HEAD) && raw.startsWith(channelJson, TEXT_HEAD_LEN) && raw.startsWith(TEXT_PAYLOAD_KEY, start - TEXT_PAYLOAD_KEY_LEN) && raw.startsWith(TEXT_ORIGIN_KEY, originAt) && raw.startsWith(originIdJson, originAt + TEXT_ORIGIN_KEY_LEN) && raw.startsWith(TEXT_SEAL_KEY, sealAt - TEXT_SEAL_KEY_LEN) && raw.startsWith(provided, sealAt) && raw.startsWith(TEXT_SEAL_END, sealAt + provided.length) ? raw.slice(start, originAt) : null;
 }
 /**
 * Parse et **vérifie** une enveloppe reçue du bus partagé.
@@ -78,6 +275,10 @@ function isEnvelope(m) {
 * `sig`. Sans secret, l'enveloppe nue est acceptée (compat ; l'alerte de boot qui
 * signale ce mode non authentifié est portée par le wiring du driver).
 *
+* Le sceau se vérifie sur la tranche REÇUE de la charge quand l'enveloppe a la
+* forme qu'écrit {@link sealBackplaneEnvelope} — aucune re-sérialisation ; une
+* autre forme retombe sur la re-sérialisation de la charge lue.
+*
 * @param raw - message brut lu sur le bus.
 * @param secret - secret partagé attendu, ou `null`/`undefined` si aucun.
 * @returns le message vérifié, ou `null` s'il doit être ignoré (malformé, non
@@ -93,17 +294,294 @@ function openBackplaneEnvelope(raw, secret) {
 	if (!isEnvelope(parsed)) return null;
 	const msg = {
 		channel: parsed.channel,
-		payload: parsed.payload,
+		payload: parsed.payload === null ? void 0 : parsed.payload,
 		originId: parsed.originId
 	};
 	if (!secret) return msg;
 	const provided = parsed[SEAL_FIELD];
 	if (typeof provided !== "string") return null;
-	const payloadText = JSON.stringify(msg.payload);
-	const expected = seal(JSON.stringify(msg.originId), JSON.stringify(msg.channel), payloadText ?? "null", secret);
-	const a = Buffer.from(provided, "base64url");
-	const b = Buffer.from(expected, "base64url");
-	if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
-	return msg;
+	const channelJson = JSON.stringify(msg.channel);
+	const originIdJson = JSON.stringify(msg.originId);
+	const head = sealHead(originIdJson, channelJson);
+	const slice = receivedPayloadText(raw, channelJson, originIdJson, provided);
+	if (slice !== null && sealMatches(provided, sealText(head, slice, secret))) return msg;
+	return sealMatches(provided, sealText(head, JSON.stringify(msg.payload) ?? "null", secret)) ? msg : null;
+}
+/** Encode par le codec, et refuse un codec texte : le sujet binaire porte des octets. */
+function encodeBytes(codec, value) {
+	const out = codec.encode(value);
+	if (typeof out === "string") throw new TypeError(`backplane : le codec « ${codec.protocol} » rend du texte — le sujet binaire du bus exige un codec binaire`);
+	return out;
+}
+/**
+* Assemble l'enveloppe binaire scellée par fragments : la charge, déjà encodée,
+* est recopiée telle quelle — jamais ré-encodée. Une seule zone mémoire.
+*
+* Zone PROPRE (`new Uint8Array`), jamais le pool partagé de `Buffer.allocUnsafe` :
+* une charge décodée de ces octets rend des vues, qui retiendraient tout le bloc du
+* pool. Un `Uint8Array`, comme le codec : un `Buffer` y ferait décoder des
+* `Buffer`. Les chaînes ASCII (le cas courant : canal, origine, sceau) s'écrivent
+* par une boucle, sans objet intermédiaire.
+*/
+function frameSealedBytes(channel, originId, payloadBytes, sig) {
+	const channelLen = Buffer.byteLength(channel, "utf8");
+	const originLen = Buffer.byteLength(originId, "utf8");
+	const out = new Uint8Array(1 + CBOR_KEY_CHANNEL.length + cborTextHeadSize(channelLen) + channelLen + CBOR_KEY_PAYLOAD.length + payloadBytes.byteLength + CBOR_KEY_ORIGIN.length + cborTextHeadSize(originLen) + originLen + CBOR_SEAL_TAIL_LEN);
+	out[0] = CBOR_MAP_4;
+	let at = 1;
+	out.set(CBOR_KEY_CHANNEL, at);
+	at = writeCborTextHead(out, at + CBOR_KEY_CHANNEL.length, channelLen);
+	at = writeUtf8(out, at, channel, channelLen);
+	out.set(CBOR_KEY_PAYLOAD, at);
+	at += CBOR_KEY_PAYLOAD.length;
+	out.set(payloadBytes, at);
+	at += payloadBytes.byteLength;
+	out.set(CBOR_KEY_ORIGIN, at);
+	at = writeCborTextHead(out, at + CBOR_KEY_ORIGIN.length, originLen);
+	at = writeUtf8(out, at, originId, originLen);
+	out.set(CBOR_KEY_SEAL, at);
+	at += CBOR_KEY_SEAL.length;
+	out.set(CBOR_SEAL_HEAD, at);
+	writeUtf8(out, at + CBOR_SEAL_HEAD.length, sig, SEAL_CHARS);
+	return out;
+}
+/** Encodeur UTF-8 partagé, pour les chaînes non ASCII. */
+const UTF8 = new TextEncoder();
+/**
+* Écrit `value` en UTF-8 à `at` ; rend la position suivante. `byteLen` égal au
+* nombre de caractères = chaîne ASCII : boucle directe, sans vue intermédiaire.
+*/
+function writeUtf8(out, at, value, byteLen) {
+	if (byteLen === value.length) for (let i = 0; i < byteLen; i += 1) out[at + i] = value.charCodeAt(i);
+	else UTF8.encodeInto(value, out.subarray(at, at + byteLen));
+	return at + byteLen;
 }
-export { openBackplaneEnvelope, sealBackplaneEnvelope };
+/** Verdicts déjà CONSTATÉS, par codec (un serveur n'en a qu'un : la case unique suffit). */
+let framedCodec = null;
+let framedVerdict = false;
+const framedVerdicts = /* @__PURE__ */ new WeakMap();
+/**
+* Le codec écrit-il le CBOR le plus court, celui que {@link frameSealedBytes}
+* assemble ? CONSTATÉ, jamais déduit de son nom : une enveloppe d'épreuve est
+* encodée par le codec et comparée à l'assemblage par fragments, une fois par
+* codec. Faux → le codec garde la voie générique (double encodage), qui reste
+* correcte pour n'importe quel format.
+*/
+function framesAsCbor(codec) {
+	if (codec === framedCodec) return framedVerdict;
+	let verdict = framedVerdicts.get(codec);
+	if (verdict === void 0) {
+		verdict = probeFraming(codec);
+		framedVerdicts.set(codec, verdict);
+	}
+	framedCodec = codec;
+	framedVerdict = verdict;
+	return verdict;
+}
+/** Épreuve de {@link framesAsCbor} : chaque longueur d'en-tête utile, octets compris. */
+function probeFraming(codec) {
+	const channel = "é".repeat(20);
+	const originId = "pod";
+	const payload = {
+		seq: 7,
+		list: [
+			1,
+			-2.5,
+			null,
+			"x"
+		],
+		raw: new Uint8Array([0, 255])
+	};
+	const sig = "A".repeat(SEAL_CHARS);
+	try {
+		return asBuffer(encodeBytes(codec, {
+			channel,
+			payload,
+			originId,
+			sig
+		})).equals(asBuffer(frameSealedBytes(channel, originId, encodeBytes(codec, payload), sig)));
+	} catch {
+		return false;
+	}
+}
+/**
+* Encode un message backplane pour le **sujet binaire** du bus (ADR-0021 S6) :
+* la MÊME enveloppe `{ channel, payload, originId }`, encodée par le codec
+* binaire du serveur, octets natifs dans `payload`, scellée si un secret est
+* fourni.
+*
+* Scellée, la charge est encodée UNE fois : le sceau se calcule sur ses octets,
+* et l'enveloppe s'assemble autour d'eux. Un codec qui n'écrit pas le CBOR le plus
+* court (constaté, cf {@link framesAsCbor}) encode l'enveloppe entière une seconde
+* fois — correct pour tout format, plus coûteux.
+*
+* @param msg - message à transporter (canal, charge, origine).
+* @param codec - le codec binaire du serveur (`CBOR_FRAME_CODEC` de `nodefony/cbor`).
+* @param secret - secret partagé entre pods ; `null`/`undefined` → enveloppe nue.
+* @returns les octets à publier sur le sujet binaire.
+* @throws TypeError si le codec rend du texte.
+*/
+function sealBackplaneEnvelopeBytes(msg, codec, secret) {
+	const payload = msg.payload ?? null;
+	if (!secret) return encodeBytes(codec, {
+		channel: msg.channel,
+		payload,
+		originId: msg.originId
+	});
+	const payloadBytes = encodeBytes(codec, payload);
+	const sig = sealText(sealHead(JSON.stringify(msg.originId), JSON.stringify(msg.channel)), payloadBytes, secret);
+	if (framesAsCbor(codec)) return frameSealedBytes(msg.channel, msg.originId, payloadBytes, sig);
+	return encodeBytes(codec, {
+		channel: msg.channel,
+		payload,
+		originId: msg.originId,
+		[SEAL_FIELD]: sig
+	});
+}
+/**
+* Tranche de la charge dans une enveloppe binaire reçue, si elle a EXACTEMENT la
+* forme qu'assemble {@link frameSealedBytes} pour ce canal, cette origine et ce
+* sceau ; `null` sinon (forme tierce → repli). Aucune copie : une vue.
+*/
+function receivedPayloadBytes(raw, channel, originId, provided) {
+	if (provided.length !== SEAL_CHARS || raw[0] !== CBOR_MAP_4) return null;
+	const channelLen = Buffer.byteLength(channel, "utf8");
+	const originLen = Buffer.byteLength(originId, "utf8");
+	const channelHeadAt = 1 + CBOR_KEY_CHANNEL.length;
+	const payloadKeyAt = channelHeadAt + cborTextHeadSize(channelLen) + channelLen;
+	const start = payloadKeyAt + CBOR_KEY_PAYLOAD.length;
+	const originAt = raw.length - CBOR_SEAL_TAIL_LEN - originLen - cborTextHeadSize(originLen) - CBOR_KEY_ORIGIN.length;
+	if (originAt <= start) return null;
+	const originHeadAt = originAt + CBOR_KEY_ORIGIN.length;
+	const sealKeyAt = originHeadAt + cborTextHeadSize(originLen) + originLen;
+	return bytesAt(raw, 1, CBOR_KEY_CHANNEL) && cborTextHeadAt(raw, channelHeadAt, channelLen) && bytesAt(raw, payloadKeyAt, CBOR_KEY_PAYLOAD) && bytesAt(raw, originAt, CBOR_KEY_ORIGIN) && cborTextHeadAt(raw, originHeadAt, originLen) && bytesAt(raw, sealKeyAt, CBOR_KEY_SEAL) && bytesAt(raw, sealKeyAt + CBOR_KEY_SEAL.length, CBOR_SEAL_HEAD) ? raw.subarray(start, originAt) : null;
+}
+/**
+* Décode et **vérifie** une enveloppe reçue sur le sujet binaire du bus — même
+* règle que {@link openBackplaneEnvelope} : fail-closed strict sous un secret,
+* aucun downgrade en retirant `sig`.
+*
+* Le sceau se vérifie sur la tranche REÇUE de la charge quand l'enveloppe a la
+* forme qu'assemble l'émetteur — aucun ré-encodage ; une autre forme retombe sur
+* le ré-encodage de la charge décodée (le codec CBOR du cœur rend la forme la plus
+* courte de chaque valeur, donc émetteur et récepteur signent les mêmes octets).
+*
+* @param raw - octets lus sur le sujet binaire.
+* @param codec - le codec binaire du serveur.
+* @param secret - secret partagé attendu, ou `null`/`undefined` si aucun.
+* @returns le message vérifié, ou `null` s'il doit être ignoré.
+*/
+function openBackplaneEnvelopeBytes(raw, codec, secret) {
+	let parsed;
+	try {
+		parsed = codec.decode(raw);
+	} catch {
+		return null;
+	}
+	if (!isEnvelope(parsed)) return null;
+	const msg = {
+		channel: parsed.channel,
+		payload: parsed.payload === null ? void 0 : parsed.payload,
+		originId: parsed.originId
+	};
+	if (!secret) return msg;
+	const provided = parsed[SEAL_FIELD];
+	if (typeof provided !== "string") return null;
+	const head = sealHead(JSON.stringify(msg.originId), JSON.stringify(msg.channel));
+	if (framesAsCbor(codec)) {
+		const slice = receivedPayloadBytes(raw, msg.channel, msg.originId, provided);
+		if (slice !== null && sealMatches(provided, sealText(head, slice, secret))) return msg;
+	}
+	let payloadBytes;
+	try {
+		payloadBytes = encodeBytes(codec, parsed.payload ?? null);
+	} catch {
+		return null;
+	}
+	return sealMatches(provided, sealText(head, payloadBytes, secret)) ? msg : null;
+}
+/**
+* Reconnaît l'**écho** d'un pod — ce que le bus lui renvoie de ses propres
+* publications — à la FIN du message, sans le décoder (ADR-0021 S6, ADR-0025).
+*
+* Un bus pub/sub comme Redis rend à l'émetteur chacune de ses publications : sur un
+* pod chargé, c'est un message reçu sur deux, et la présence répartie en fait un
+* signal (le bus est vivant tant que l'écho revient). Le reconnaître coûte, sous un
+* secret, UN HMAC sur la tranche de la charge : ni `JSON.parse`, ni décodage CBOR.
+*
+* Sous un secret, l'écho est VÉRIFIÉ avant d'être compté : un tiers qui forgerait
+* l'origine de ce pod pour simuler un bus vivant échoue au sceau. Sans secret, rien
+* ne peut l'être — le bus est ouvert, et le wiring l'annonce au démarrage.
+*
+* Un message que ce lecteur ne reconnaît pas (forme tierce, sceau faux) n'est PAS
+* jeté : il suit la voie ordinaire, qui le vérifie en entier.
+*/
+var BackplaneEcho = class {
+	#secret;
+	/** `originId\n` en JSON : début de la chaîne canonique de CE pod. */
+	#sealHeadStart;
+	/** Texte, scellé : `,"originId":<origine>,"sig":"`. */
+	#textTail;
+	/** Texte, nu : `,"originId":<origine>}`. */
+	#textBareTail;
+	/** CBOR : clé `originId` puis la chaîne de l'origine. */
+	#bytesOrigin;
+	/** Lecture d'un en-tête de chaîne CBOR, réutilisée (aucune allocation par message). */
+	#head = [0, 0];
+	/**
+	* @param originId - identité de CE pod sur le bus.
+	* @param secret - secret partagé, ou `null` sur un bus non scellé.
+	*/
+	constructor(originId, secret) {
+		this.#secret = secret;
+		const originIdJson = JSON.stringify(originId);
+		this.#sealHeadStart = `${originIdJson}\n`;
+		this.#textTail = TEXT_ORIGIN_KEY + originIdJson + TEXT_SEAL_KEY;
+		this.#textBareTail = `${TEXT_ORIGIN_KEY}${originIdJson}}`;
+		const origin = cborText(originId);
+		this.#bytesOrigin = new Uint8Array(CBOR_KEY_ORIGIN.length + origin.length);
+		this.#bytesOrigin.set(CBOR_KEY_ORIGIN, 0);
+		this.#bytesOrigin.set(origin, CBOR_KEY_ORIGIN.length);
+	}
+	/**
+	* Ce message texte est-il l'écho de ce pod (sceau vérifié sous un secret) ?
+	*
+	* @param raw - message brut lu sur le sujet texte.
+	*/
+	text(raw) {
+		const secret = this.#secret;
+		if (secret === null) return raw.endsWith(this.#textBareTail);
+		const tail = this.#textTail;
+		const tailAt = raw.length - TEXT_SEAL_END_LEN - SEAL_CHARS - tail.length;
+		if (tailAt <= TEXT_HEAD_LEN || !raw.startsWith(tail, tailAt) || !raw.endsWith(TEXT_SEAL_END) || !raw.startsWith(TEXT_HEAD) || raw.charCodeAt(TEXT_HEAD_LEN) !== QUOTE) return false;
+		const close = raw.indexOf(TEXT_CHANNEL_CLOSE, 12);
+		const start = close + TEXT_CHANNEL_CLOSE_LEN;
+		if (close < 0 || start >= tailAt) return false;
+		const sealAt = tailAt + tail.length;
+		return sealMatches(raw.slice(sealAt, sealAt + SEAL_CHARS), sealText(`${this.#sealHeadStart}${raw.slice(TEXT_HEAD_LEN, close + 1)}\n`, raw.slice(start, tailAt), secret));
+	}
+	/**
+	* Ce message binaire est-il l'écho de ce pod (sceau vérifié sous un secret) ?
+	*
+	* @param raw - octets lus sur le sujet binaire.
+	* @param codec - le codec binaire du serveur ; un codec qui n'écrit pas le CBOR
+	*   attendu (cf {@link framesAsCbor}) laisse tout message à la voie ordinaire.
+	*/
+	bytes(raw, codec) {
+		if (!framesAsCbor(codec)) return false;
+		const origin = this.#bytesOrigin;
+		const secret = this.#secret;
+		if (secret === null) return raw[0] === CBOR_MAP_3 && bytesAt(raw, raw.length - origin.length, origin);
+		const originAt = raw.length - CBOR_SEAL_TAIL_LEN - origin.length;
+		const sealKeyAt = originAt + origin.length;
+		const head = this.#head;
+		if (raw[0] !== CBOR_MAP_4 || !bytesAt(raw, originAt, origin) || !bytesAt(raw, sealKeyAt, CBOR_KEY_SEAL) || !bytesAt(raw, sealKeyAt + CBOR_KEY_SEAL.length, CBOR_SEAL_HEAD) || !bytesAt(raw, 1, CBOR_KEY_CHANNEL) || !readCborTextHead(raw, 1 + CBOR_KEY_CHANNEL.length, head)) return false;
+		const channelAt = 1 + CBOR_KEY_CHANNEL.length + head[1];
+		const channelEnd = channelAt + head[0];
+		const start = channelEnd + CBOR_KEY_PAYLOAD.length;
+		if (start >= originAt || !bytesAt(raw, channelEnd, CBOR_KEY_PAYLOAD)) return false;
+		const view = asBuffer(raw);
+		return sealMatches(view.toString("latin1", raw.length - SEAL_CHARS, raw.length), sealText(`${this.#sealHeadStart}${JSON.stringify(view.toString("utf8", channelAt, channelEnd))}\n`, raw.subarray(start, originAt), secret));
+	}
+};
+export { BackplaneEcho, openBackplaneEnvelope, openBackplaneEnvelopeBytes, sealBackplaneEnvelope, sealBackplaneEnvelopeBytes };

package/dist/nodefony/src/backplane/ingress.js

@@ -0,0 +1,93 @@
+import { BackplaneEcho, openBackplaneEnvelope, openBackplaneEnvelopeBytes } from "./envelope.js";
+// nodefony/src/backplane/ingress.ts
+/**
+* **Entrée d'un bus partagé** — le tri de ce qu'un pilote reçoit, mutualisé pour
+* que tout pilote à transport réseau (Redis aujourd'hui ; Kafka, NATS, RabbitMQ…
+* demain) l'hérite sans le réécrire : écho de ce pod reconnu et compté, sceau
+* vérifié, refus comptés et annoncés.
+*
+* Le pilote ne garde que son transport : il passe chaque message reçu à
+* {@link text} ou {@link bytes} et remet au hub ce qui en sort.
+*
+* Ordre du tri, du moins cher au plus cher :
+*  1. l'ÉCHO de ce pod se reconnaît à la fin du message, sans le décoder — un HMAC
+*     sous un secret (cf {@link BackplaneEcho}) ;
+*  2. sinon, l'enveloppe est ouverte et son sceau vérifié sur la tranche reçue ;
+*  3. un message ouvert qui porte l'origine de ce pod sous une autre forme est
+*     encore un écho — compté, jamais réinjecté (anti-boucle).
+*/
+var BackplaneIngress = class {
+	#originId;
+	#secret;
+	#echo;
+	#notice;
+	#echoTotal = 0;
+	#sealRejectedTotal = 0;
+	/**
+	* @param originId - identité de CE pod sur le bus.
+	* @param secret - secret partagé, ou `null` sur un bus non scellé.
+	* @param notice - annonce des sceaux refusés ; omis = silencieux (tests).
+	*/
+	constructor(originId, secret, notice = null) {
+		this.#originId = originId;
+		this.#secret = secret;
+		this.#echo = new BackplaneEcho(originId, secret);
+		this.#notice = notice;
+	}
+	/**
+	* Trie un message reçu sur le sujet TEXTE du bus.
+	*
+	* @param raw - message brut tel que lu sur le transport.
+	* @returns le message à remettre au hub, ou `null` s'il est jeté (écho de ce
+	*   pod, malformé, sceau refusé — chacun compté).
+	*/
+	text(raw) {
+		if (this.#echo.text(raw)) {
+			this.#echoTotal += 1;
+			return null;
+		}
+		return this.#admit(openBackplaneEnvelope(raw, this.#secret));
+	}
+	/**
+	* Trie un message reçu sur le sujet BINAIRE du bus (ADR-0021 S6).
+	*
+	* @param raw - octets tels que lus sur le transport.
+	* @param codec - le codec binaire du serveur.
+	* @returns le message à remettre au hub, ou `null` s'il est jeté.
+	*/
+	bytes(raw, codec) {
+		if (this.#echo.bytes(raw, codec)) {
+			this.#echoTotal += 1;
+			return null;
+		}
+		return this.#admit(openBackplaneEnvelopeBytes(raw, codec, this.#secret));
+	}
+	/** Échos de ce pod reçus du bus (monotone) — le bus rend ce qu'on y publie. */
+	get echoTotal() {
+		return this.#echoTotal;
+	}
+	/** Messages jetés au sceau refusé, sous un secret (monotone). */
+	get sealRejectedTotal() {
+		return this.#sealRejectedTotal;
+	}
+	/** Fin du tri commune aux deux sujets : refus compté, écho tardif, ou message admis. */
+	#admit(msg) {
+		if (msg === null) {
+			if (this.#secret !== null) this.#sealRejected();
+			return null;
+		}
+		if (msg.originId === this.#originId) {
+			this.#echoTotal += 1;
+			return null;
+		}
+		return msg;
+	}
+	/** Compte un sceau refusé ; annonce le premier, puis un sur cent (pas d'inondation du journal). */
+	#sealRejected() {
+		this.#sealRejectedTotal += 1;
+		const n = this.#sealRejectedTotal;
+		if (n !== 1 && n % 100 !== 0) return;
+		this.#notice?.(`backplane : ${n} message(s) reçu(s) au sceau refusé, JETÉS. Causes : rotation du secret en cours (des exemplaires n'ont pas le même NF_REALTIME_BACKPLANE_SECRET), producteur mal configuré, ou écriture tierce dans le bus. Compteur : sealRejectedTotal.`, "WARNING");
+	}
+};
+export { BackplaneIngress };