Duplex overlay (L0 occupancy pipe + application JSON)

Duplex is two layers:

1. L0 (SI) — exclusive occupancy pipe: l0_listen (or mining + listenKind: "l0") plus l0_connect. After the first connect occupies an idle L0 SSE, SI pipes remaining TCP bytes onto that SSE, marks the channel occupied, relinquishes control, and 409s later inflows to that listen.
2. Application (conet-l0d) — duplex_offer / duplex_accept / duplex_reject / duplex_frame. Offer stays user-PGP Chat gossip so it cannot occupy the exclusive L0 listen. Accept, reject, and IPv4 frames are AES-256-GCM blobs on the occupied pipe.

SI does not implement duplex_* commands and does not maintain a duplex pool. Do not add duplexForward.ts or SI duplex_* cases. Do not document a live SI command named p2p_stream_* or listenKind: "l1p2p". Do not send command: "mining" with listenKind: "duplex".

Public site: https://gitbook.conet.network/l0/duplex-forward.html

conet-l0d is the first product that uses this composition for overlay geth / beacon IPv4.

Why two own L0 listens (not a guest SSE)

HTTP SSE is server → listener only. One occupied pipe is one direction. Duplex therefore uses two unidirectional occupied pairs:

I’s W_I L0 SSE  ←  R’s l0_connect (first PGP occupy, then AES)
R’s W_R L0 SSE  ←  I’s l0_connect (then AES)

A client must not attach a second listen for someone else's routing EOA on their mailbox B. Each end owns its L0 listen wallet.

conet-l0d crate MVP uses the already-registered per-port channel EOA as W_I / W_R (same EOA may hold Chat SSE and l0_listen in different pools). The wire still names listenWallet / listenUserPgp so a later cut can mint a fresh EOA without changing SI.

Idle L0 may still receive user-PGP gossip (offers) without occupying. After occupy, all later inflows (gossip and connects) are 409. Occupied gossip is write-to-SSE only on idle; never APNs / saveLocal onto an occupied L0 SSE.

What it is

Each duplex session uses two keys. Do not mix them.

Each request uses a healthy entry different from B. Occupancy of connect is by targetWallet after decrypt, not by B route key ID (do not 409 every B-route packet when one L0 listen is occupied — Chat / mining on the same node must continue).

Encryption and route matrix

The key rule is strict: overlay AES must never appear in a B-decryptable listen or l0_connect command. SI never parses command: "duplex_offer".

After occupy, SI must not response200Html (that ends inbound TCP). Extra bytes after Content-Length are unshifted by getDataPOST and piped as SSE lines.

Capability probe (application, not HTTP 404)

SI 404 is not the duplex probe. SI 409 occupied means that L0 listen already has a pipe.

HTTP 2xx on duplex_offer is not proof that the peer attached. An SSE handshake is transport, not duplex ready.

How it works

Both ends: long-lived Chat listen (channel EOA) — receives duplex_offer
Both ends: exclusive l0_listen on session wallet (crate MVP: channel EOA)

Initiator I (own_eoa < peer_eoa):
  1. sessionId = keccak256(utf8("l0d-duplex-v1|" || min(eoa_I,eoa_R) || "|" || max(...) || "|" || port_be16))
  2. generate 32-byte AES-256-GCM key (memory only)
  3. duplex_offer { Securitykey, listenWallet: W_I, listenUserPgp } → R long-lived user PGP → POST A ≠ B_R

If R never answers → overlay stays P1 gossip.

If R does not support this session:
  l0_connect target=W_I; first AES blob = duplex_reject
  I keeps P1 gossip

If R accepts:
  store overlay key; keep l0_listen W_R
  l0_connect target=W_I; first AES blob = duplex_accept { Securitykey echo, listenWallet: W_R }
  I sees accept on occupied W_I SSE → peer_attached; remembers W_R
  I l0_connect occupies W_R (no required first app JSON)

Data (both directions) — two occupied L0 pipes:
  I → R: AES( duplex_frame JSON ) on I’s l0_connect TCP to W_R
  R → I: AES( duplex_frame JSON ) on R’s l0_connect TCP to W_I
  duplex_frame.payload = standard base64( L0D1 || IPv4 )

conet-l0d sends AES duplex_frame only when it has the overlay key AND peer_attached AND an occupied pipe_tx AND not rejected.
Missing pipe keeps P1 gossip until the pipe is rebuilt — not forever after a transient occupy failure.

Initiator election for a given overlay port: own_eoa < peer_eoa (lowercase 0x hex). Both ends compute the same sessionId.

Pipe durability (normative)

A one-time session EOA must be regiestChatRoute on mailbox B before its L0 listen is useful. Until the daemon registers ephemeral wallets itself, the crate reuses the registered channel EOA.

Canonical application fields

duplex_offer remains signed Chat gossip (user PGP):

signMessage = personal_sign(message)
literal = base64(UTF8(JSON.stringify({ message, signMessage })))
armored = OpenPGP_encrypt(literal, target user PGP)
HTTP POST { "data": armored }

duplex_offer (encrypt to peer long-lived user PGP):

{
  "command": "duplex_offer",
  "walletAddress": "<initiator EOA>",
  "peerWallet": "<responder routing EOA>",
  "listenWallet": "<initiator session listen EOA>",
  "listenUserPgp": "<armored OpenPGP public cert for listenWallet>",
  "sessionId": "<64 hex, no 0x>",
  "algorithm": "aes-256-gcm",
  "Securitykey": "<standard base64 of 32 bytes>",
  "timestamp": 1710000000
}

duplex_accept / duplex_reject / duplex_frame after occupy are not OpenPGP. Outer wire is standard base64 of nonce(12) || AES-GCM(utf8(JSON)) || tag(16).

duplex_accept (must echo Securitykey):

{
  "command": "duplex_accept",
  "walletAddress": "<responder EOA>",
  "listenWallet": "<responder session listen EOA>",
  "listenUserPgp": "<armored OpenPGP public cert for listenWallet>",
  "sessionId": "<64 hex, no 0x>",
  "algorithm": "aes-256-gcm",
  "Securitykey": "<same 32-byte key as the offer>",
  "timestamp": 1710000000
}

duplex_reject (must not contain Securitykey):

{
  "command": "duplex_reject",
  "walletAddress": "<responder EOA>",
  "sessionId": "<64 hex, no 0x>",
  "reason": "unsupported",
  "timestamp": 1710000000
}

duplex_frame:

{
  "type": "duplex_frame",
  "sessionId": "<64 hex>",
  "payload": "<standard base64 of L0D1||IPv4>"
}

SI occupy notice (not application JSON; ignore on the client):

{ "type": "l0_occupied", "wallet": "<listen EOA>", "connector": "<connector EOA>" }

Frame format and runtime bounds

A receive-only SSE socket can remain writable after its request body has ended. SI therefore does not classify readableEnded alone as stale. Peer 'end' (half-close) must not drop the L0 pool. Do not inject mining epoch gossip onto an occupied L0 SSE. Do not share chat APNs / wall-clock expire with occupied L0.

Guarantees and non-guarantees

If duplex_offer is encrypted to the peer user key, Chat listen omits the overlay AES key, and l0_listen / l0_connect omit it too, mailbox B can route and occupy without learning overlay plaintext or the AES key.

After occupy, SI pipes opaque lines. It does not provide raw TCP semantics, congestion control, or proof that geth consumed a datagram. SI HTTP 200 on Chat gossip means the entry accepted armor, not that the peer app attached. SI 409 on l0_connect means that listen is already taken.

It also does not hide a client's IP from its entry, defeat a global timing observer, or implement padding. Those are listed as upgrades in security limits.

Implementation anchors

• Overlay AES + L0D1 + offer / accept / reject / frame + occupied pipe: src/conet-l0d/src/l0/{aes,frame,duplex,client,pipe,listen}.rs
• SI exclusive pool: src/CoNET-SI/src/util/l0Exclusive.ts (l0_listen / l0_connect)
• Do not add src/CoNET-SI/src/util/duplexForward.ts
• Operator / crate: Applications — conet-l0d, Developers — conet-l0d

Related

• UDP frame forwarding — SI does implement udp_* (separate pools). Occupied L0 is a different exclusive pipe
• Zero-trust mailbox routing
• SI developer guide — l0_listen / l0_connect rows; no duplex_* command row
• Security limits