> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuro-tech.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Peer-to-peer and end-to-end security

> Establish optional direct XMPP channels and protect stanzas across brokers and intermediaries

Transport TLS protects one hop. End-to-end encryption protects stanza content between the two entity clients, and optional peer-to-peer (P2P) communication can bypass broker data paths for privacy or bandwidth reasons.

| Capability          | Namespace             | Advertised in            |
| ------------------- | --------------------- | ------------------------ |
| P2P connection data | `urn:nfi:iot:p2p:1.0` | Presence `<p2p>` element |
| End-to-end keys     | `urn:nfi:iot:e2e:1.0` | Presence `<e2e>` element |

## Publish direct connection data

A device behind an Internet gateway first obtains a local address/port and an externally reachable address/port using an operator-selected mechanism such as UPnP. It publishes both to approved presence subscribers:

```xml theme={null}
<presence>
  <p2p xmlns='urn:nfi:iot:p2p:1.0'
       extIp='198.51.100.8' extPort='64152'
       locIp='192.168.1.20' locPort='64152'/>
</presence>
```

Peers sharing the same external address connect to the local endpoint; otherwise they use the external endpoint. Refresh presence whenever the mapping changes.

## Authenticate the P2P peer

Network location is only a first check. The receiver verifies that the claimed full JID is an approved, present roster contact whose published endpoint matches the incoming address. All P2P stanzas then use E2E protection; the sender's signature binds the stream claim to its published key.

Reject the connection if any check fails. Do not use local-network location as an authentication substitute.

## End-to-end encryption

E2E uses a hybrid cipher:

* an asymmetric endpoint publishes a short-lived public key, derives or transports a per-stanza secret, and signs plaintext;
* a symmetric algorithm encrypts the message or complete IQ payload;
* the receiver decrypts with its private key and validates the sender signature.

The namespace defines AES-256, ChaCha20, and AEAD ChaCha20-Poly1305 stanza wrappers. Asymmetric families can include RSA, elliptic curves, and supported post-quantum mechanisms. Algorithms are feature-negotiated; implementations must not assume that every peer shares the same set.

```xml theme={null}
<presence>
  <e2e xmlns='urn:nfi:iot:e2e:1.0'>
    <x25519 pub='BASE64_PUBLIC_KEY'/>
    <ed25519 pub='BASE64_PUBLIC_KEY'/>
  </e2e>
</presence>
```

Publishing keys in presence avoids a separate handshake before the first encrypted stanza. Keep the current and immediately previous private key during rotation so in-flight messages encrypted to the prior presence can still be processed.

## Security requirements

* Generate keys and nonces with a cryptographically secure random source.
* Rotate asymmetric keys according to data sensitivity and after a session/compromise.
* Authenticate associated stanza metadata; reject altered sender, recipient, type, or request ID.
* Reject algorithm downgrade and unadvertised keys.
* Never reuse a per-stanza symmetric key or nonce.
* Bound retention of the previous private key.
* Treat decryption, signature, replay, and recipient failures as hard failures without exposing an oracle.