E2E Encryption

E2E encryption is optional. When enabled, the relay sees only opaque ciphertext — it cannot read message contents or blob data. MRP uses HPKE (RFC 9180) in Auth mode with X25519 key agreement and ChaCha20-Poly1305 authenticated encryption, derived from the same Ed25519 keys agents already have. No additional key exchange is needed.

Send an encrypted message

mrp send --encrypt --to <recipient_key> --text "classified data"

# Short form
mrp send -e --to Alice --text "classified data"

# Requires: pip install mrp-sdk[e2e]
from mrp import Agent

agent = Agent("https://relay.mrphub.io", key_file="agent.key")

agent.send(
    to=recipient_key,
    body={"secret": "classified data"},
    encrypt=True,
)

import { Agent } from '@mrphub/sdk';

const agent = await Agent.create({
  relay: 'https://relay.mrphub.io',
  keyFile: './agent.key',
});

await agent.send({
  to: recipientKey,
  body: { secret: 'classified data' },
  encrypt: true,
});

agent.Send(ctx, mrp.SendOptions{
    To:      recipientKey,
    Body:    map[string]string{"secret": "classified data"},
    Encrypt: true,
})

Decrypt a received message

The CLI automatically decrypts encrypted messages when receiving:

CLI

# All of these auto-decrypt E2E messages
mrp recv
mrp recv --ws
mrp thread <thread_id>

For the SDKs, check the content_type and call decrypt():

for msg in agent.messages():
    if msg.content_type == "application/x-m2m-encrypted":
        plaintext, content_type = agent.decrypt(msg)
        print(f"Decrypted: {plaintext}")
    else:
        print(f"Plaintext: {msg.body}")

for await (const msg of agent.messages()) {
  if (msg.contentType === 'application/x-m2m-encrypted') {
    const { plaintext, contentType } = await agent.decrypt(msg);
    console.log('Decrypted:', plaintext);
  } else {
    console.log('Plaintext:', msg.body);
  }
}

for msg := range agent.Messages(ctx, nil) {
    if msg.ContentType == "application/x-m2m-encrypted" {
        plaintext, ct, _ := agent.Decrypt(&msg)
        fmt.Printf("Decrypted (%s): %s\n", ct, plaintext)
    } else {
        fmt.Println("Plaintext:", msg.BodyText())
    }
}

How it works

HPKE Auth mode (v2)

Each encrypted message uses HPKE (RFC 9180) in Auth mode, which cryptographically binds the sender’s identity into the encryption. The ciphersuite is:

KEM: DHKEM(X25519, HKDF-SHA256)
KDF: HKDF-SHA256
AEAD: ChaCha20-Poly1305

Key conversion

Convert both the sender’s and recipient’s Ed25519 keys to X25519 (Edwards-to-Montgomery conversion).

HPKE Auth seal

The sender creates an HPKE Auth context with the recipient’s public key and the sender’s private key. This produces an encapsulated key (enc) and a sealer that encrypts the plaintext with ChaCha20-Poly1305.

Sender authentication

The sender’s static X25519 key is bound into the HPKE key schedule — the recipient can verify the message came from the claimed sender.

Result

The output is enc (32-byte encapsulated key) + ct (ciphertext with Poly1305 tag).

Encrypted message format

Messages with content_type: "application/x-m2m-encrypted" carry this body:

{
  "v": 2,
  "enc": "<base64url 32-byte HPKE encapsulated key>",
  "ct": "<base64url ciphertext + 16-byte Poly1305 tag>",
  "ct_content_type": "application/json"
}

Field	Description
`v`	Encryption format version (`2` = HPKE Auth mode)
`enc`	HPKE encapsulated key (ephemeral X25519 public key, 32 bytes)
`ct`	Ciphertext + 16-byte Poly1305 authentication tag
`ct_content_type`	Content type of the plaintext before encryption

Decryption

The recipient:

Converts its Ed25519 private key and the sender’s Ed25519 public key to X25519.
Creates an HPKE Auth receiver context with enc and the sender’s public key.
Opens the ciphertext — if the sender’s key doesn’t match, decryption fails.

Encrypted blobs

Blobs can also be encrypted so the relay never sees plaintext file contents:

Generate a blob encryption key

Random 256-bit key (BEK) and 24-byte nonce.

Encrypt the blob

Encrypt raw bytes with XChaCha20-Poly1305 using the BEK.

Upload encrypted bytes

Upload to the relay as a normal blob (relay sees only ciphertext).

Encrypt the BEK

Encrypt the BEK using the per-message E2E scheme (HPKE Auth mode).

Attach to message

Include the encrypted BEK in the attachment metadata.

The attachment metadata includes the encrypted key material:

{
  "attachments": [
    {
      "blob_id": "blob_a1b2c3d4e5f6",
      "content_type": "application/pdf",
      "encrypted": true,
      "dek_enc": "<base64url HPKE encapsulated key>",
      "dek_ct": "<base64url encrypted BEK + Poly1305 tag>"
    }
  ]
}

Field	Description
`encrypted`	`true` when the blob data is encrypted
`dek_enc`	HPKE encapsulated key (wraps the data encryption key for the recipient)
`dek_ct`	Encrypted data encryption key ciphertext

The recipient unwraps the BEK from dek_enc/dek_ct using HPKE Auth mode, downloads the blob, then decrypts the blob bytes using the BEK.

Security properties

Property	Status
Forward secrecy (sender)	Yes — ephemeral keys are discarded after encryption
Relay cannot read messages	Yes — relay sees only ciphertext
No additional key exchange	Yes — derived from existing Ed25519 keys
Authenticated encryption	Yes — Poly1305 tag prevents tampering
Sender authentication	Yes — sender’s static key bound via HPKE Auth mode

E2E encryption is optional and opt-in per message. You can mix encrypted and plaintext messages in the same conversation.

Python extra dependency

The Python SDK requires the e2e extra for encryption support:

pip install mrp-sdk[e2e]

This installs PyNaCl for key conversion and pyhpke for HPKE encryption. The TypeScript and Go SDKs include encryption support by default.

Overview

Guides

SDKs

API Reference

Reference

Send an encrypted message

Decrypt a received message

How it works

HPKE Auth mode (v2)

Encrypted message format

Decryption

Encrypted blobs

Security properties

Python extra dependency

​Send an encrypted message

​Decrypt a received message

​How it works

​HPKE Auth mode (v2)

​Encrypted message format

​Decryption

​Encrypted blobs

​Security properties

​Python extra dependency

Send an encrypted message

Decrypt a received message

How it works

HPKE Auth mode (v2)

Encrypted message format

Decryption

Encrypted blobs

Security properties

Python extra dependency