WIP: Add pnet support with PSK-based connection wrapping

[lla-dane]

This PR introduces support for libp2p Private Networks (pnet) in py-libp2p.

Reference: https://github.com/libp2p/go-libp2p/tree/master/p2p/net/pnet

pnet is lightweight encryption layer used to isolate a libp2p network using a shared Pre-Shared Key (PSK).
Nodes that don't have the correct PSK simply can't establish connections - enforcing network-level access control before any libp2p handshake happens.

What's implemented:

• Added a new PskConn class that wraps a RawConnection.
• When a PSK is provided, all reads/writes on the connection are transparently encrypted/decrypted using the Salsa20 stream cipher.
• The PSK itself is derived from a 32-byte hex key shared among all peers in the private network.

How it works:

• On the first write, the connection generates a random 8-byte nonce and sends it to the peer.
• The nonce initializes the Salsa20 cipher, which is then used to encrypt outgoing data.
• On the receiving side, the PskConn reads this nonce and creates a matching decryptor, ensuring both peers are synchronized.
• All further communication flows through this encrypted stream.

Cipher: Crypto.Cipher.Salsa20 (key= 32 bytes, nonce= 8 bytes)

[seetadev]

Excellent work, @lla-dane! 👏

This is a very valuable addition to py-libp2p, and the implementation is both clean and thoughtfully aligned with the existing go-libp2p/pnet design.

This feature will be especially important for enabling isolated, permissioned libp2p deployments and for use cases where network-level access control is essential (e.g., consortium networks or research environments).

Great work bringing this to life in py-libp2p — this significantly improves the library’s parity with the Go and JS implementations. Looking forward to seeing this PR head towards final review + merge.

[lla-dane]

@seetadev @pacrob: The implementation is effective with TCP and WS. Please have a review. Will include the docs folder shortly.

Here's a ping-demo over tcp and ws with pnet-enabled, with logs showing that we use the read/write functions of PskConn:

Screencast.From.2025-10-23.18-50-49.mp4

And pnet-enabled peer rejecting non pnet-enabled over tcp:

Screencast.From.2025-10-23.19-03-08.mp4

[seetadev]

@lla-dane : HI Abhinav. Appreciate your efforts.

Wish if you could resolve CI/CD issues.

[lla-dane]

@pacrob @seetadev: Fixed the merge conflicts, and CI/CD issues. Please take a look in the code, and suggest changes.

[seetadev]

Excellent update, @lla-dane — really solid work here 👏

Great to see the CI/CD issues and merge conflicts all resolved, and the code + documentation now in place. The new PskConn implementation looks clean, idiomatic, and well integrated into the existing connection stack. The use of the Salsa20 cipher with a shared PSK is straightforward yet effective, and aligns perfectly with the design principles outlined in pnet implementation in go-libp2p.

The additional test suite and the ping demo over both TCP and WS are particularly valuable — they make it easy to verify that the private network handshake and message encryption flow behave as expected. The rejection behavior for peers without the correct PSK also demonstrates that network-level isolation is working exactly as intended.

This contribution really enhances py-libp2p by enabling permissioned and isolated deployments — something that’s been a long-missing capability compared to the Go and JS implementations. It will be especially useful for research clusters, enterprise consortium setups, and testnets that need strict network access control.

Once again, excellent work bringing this feature to completion. 🎉

Doing a final review. This PR should be ready to merge soon.

[seetadev]

@pacrob : Hi Paul. As discussed in the maintainer's call, this PR is indeed ready for final review + merge.

Wish to have your pointers and feedback. Appreciate your support.

[pacrob]

lgtm!

[seetadev]

@pacrob : Thank you Paul for your feedback. Appreciate it.

@lla-dane : Please do include an example in a new PR that explains the usage and implementation of building with pnet module in py-libp2p.

[lla-dane]

@seetadev: The ping example has been updated in this PR to use a psk flag for identifying the use PNet module, over the TCP/WebTransport (TCP in default).