CLI Usage (Receiver)

The DeadLetter receiver CLI is a native Rust binary.
It runs without any runtime dependencies once installed.

⚠️ Prebuilt binaries are not yet published. They will be made available for download soon. Until then, this document describes the intended workflow.

Overview

The receiver CLI is used by the message recipient to:

• Initialize a local identity (keys + handle)
• Fetch and verify trust anchors from the registry
• Download, decrypt and manage inbox messages
• Save attached files
• Acknowledge and delete messages securely

All cryptography and trust validation happens locally.

Planned Installation

Soon you will be able to download a platform-specific binary:

Example (macOS / Linux):

curl http://<download-host>/deadletter -o deadletter
chmod +x deadletter
sudo mv deadletter /usr/local/bin/

Initialize Identity

Each receiver has a handle and a local keypair stored in:

~/.deadletter/<handle>/

Create a new identity:

deadletter init alice

This generates:

• enc_private.key – encryption private key
• enc_public.key – encryption public key
• sig_private.key – signing key

These never leave your machine.

Fetch Inbox

To fetch and decrypt messages:

deadletter inbox alice

Flow:

1. Fetch trust anchor from registry /keys/
2. Fetch and verify certificate for alice
3. Fetch inbox from backend
4. Display message list
5. Decrypt selected message locally
6. Optionally delete message from server

Trust & Verification

The receiver can manually inspect and verify the current trust anchor (root signing key) used by the registry.

deadletter trust

This command will:

1. Fetch the current root signing key from the registry /keys/
2. Display the root public key fingerprint
3. Warn if the trust anchor has changed since last verification

Example output (example only — your fingerprint will be different):

Root Trust Fingerprint: aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99

⚠️ This fingerprint is only an example.

The sender (ESP32 device) and the receiver (CLI user) must exchange and verify their displayed fingerprints using a trusted out‑of‑band channel (e.g. in person, secure chat, phone call).

Never trust the registry blindly — always confirm that both sides see the same root trust fingerprint to detect any possible man‑in‑the‑middle attack.

Reading Messages

After running inbox you will see:

📬 2 message(s)

  1 770c6253-a430-4e 2025-12-30T12:24:37Z
  2 a6120b86-57e3-43 2025-12-30T12:18:01Z

Select msg (q=quit):

Select a number to decrypt.

File Attachments

If the message contains a file payload, it will be written to the current working directory:

📎 File saved: ./report.jpg (image/jpeg, 34812 bytes)

Deleting Messages

After viewing a message:

Delete message? (y/n):

If confirmed, the CLI signs a deletion request using your signing key and sends it to the backend.

Deletion is idempotent – even if the backend already purged the message, your local inbox will stay consistent.

Important Notes

• The CLI is offline-safe – all cryptography happens locally.
• No plaintext ever reaches the backend.
• Messages cannot be decrypted without the recipient private key.
• This tool is strictly for receivers, not ESP devices.

Coming Soon

• Public binary downloads
• Checksum verification instructions
• Automated installers for macOS, Linux and Windows