Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

IPFS storage: benefits to users

The Introduction mentions that mail bodies are stored on the Interplanetary File System (IPFS) rather than on-chain or on a provider’s servers. This page goes into why that choice matters to you as a user, not just as an implementation detail.

What is a CID?

You will see the term CID a few times below and in your client, so it is worth a plain explanation first. A CID — a content identifier — is like a fingerprint of a message: a short code that is computed from the exact bytes of the content, not a name someone assigns to it. Feed the same content in and you always get the same fingerprint back; change even a single character and you get a completely different one.

Two things follow from that, and both are load-bearing:

  • Identical content always has the identical CID. So the CID works as an address: to fetch a message, you ask the network for that fingerprint, and whatever comes back must be exactly the content it names.
  • Any change produces a different CID. So the CID also works as a tamper check: if a stored message had been altered by even one byte, its fingerprint would no longer match the CID you asked for, and you would know at once.

SithBit uses the modern CIDv1 form of these fingerprints exclusively, and it computes them byte-for-byte the same way the standard IPFS tool (Kubo) does — so any IPFS client anywhere can fetch a SithBit message just by its CID. (For the exact ingredients that go into a CID, the technical reader can see the glossary.)

What does pinning mean?

The other term you will meet throughout these docs is pinning. IPFS has no central server deciding what stays available. Instead, each computer in the network keeps the content it has been explicitly asked to keep — and is free to clean away anything else during its routine housekeeping. Asking a computer to keep a piece of content is called pinning it: a pinned message body is held on that machine and stays fetchable by its CID for as long as the pin remains. Unpinning is the reverse — telling the machine it no longer needs to hold the copy, which frees the space to be reclaimed.

The practical consequences:

  • A pin is a promise made by one keeper, not by “the network”. Content on IPFS stays retrievable only while at least one computer somewhere pins it. When a message is delivered, the receiving mail operator pins the sealed body — that operator is the keeper you start with.
  • Anyone can add their own pin. Pins are independent: any number of parties — including you — can pin the same CID at once, and each pin keeps the content available on its own. That is what Pinning mail does: it puts a copy under a keeper you control, so your mail no longer depends on the operator’s pin.
  • Unpinning is not deletion everywhere. Removing a pin only releases that one keeper’s copy; every other pin of the same CID is unaffected.

(For the technical reader: the glossary states the same in storage terms under Pin / unpin.)

Why not just store mail on a server?

Traditional email storage is single-source: your provider’s servers hold the only copy your client ever talks to. If that provider goes down, changes its terms, or decides to suspend your account, your mail history goes with it — and the suspension is usually automated, with no human to appeal to for days or months. IPFS removes that single point of failure and control:

  • Content-addressed integrity. Every piece of mail is fetched by a content identifier (CID) — a hash of the content itself — rather than by location. If even one byte of a message changed, its CID would change too, so a CID is a built-in tamper check: what you fetch is cryptographically guaranteed to be what was originally pinned.
  • No single company holds your mail. Content on IPFS can be pinned by any number of independent nodes, including ones you run yourself. Nobody needs to trust one operator’s servers to keep a message retrievable.
  • You can run the storage layer too. SithBit’s IPFS support is self-hostable, not a hosted-only service tied to one provider — see sithbit-ipfsd: the IPFS pin daemon for running your own node, and the shared-bucket cluster model in Scaling out for pooling several nodes’ worth of resilience.
  • Retrieval isn’t locked to a vendor’s API. Because IPFS is an open protocol, any compatible node — SithBit’s embedded implementation or any other IPFS client — can fetch a pinned message by its CID. Your mail isn’t trapped behind one company’s private storage format.

Encryption still does the privacy work

IPFS content is addressed by its hash, not access-controlled — a CID that leaks is fetchable by anyone who has it. SithBit accounts for this: mail bodies are encrypted by the sender (see Mailbox Keys) before they’re ever pinned, so what actually lives on IPFS is ciphertext. IPFS supplies decentralized, integrity-checked availability; encryption supplies confidentiality. Neither one substitutes for the other.

Opting out of IPFS storage

Everything above is why IPFS is the default. Some recipients, though, would rather their mail bodies never touch a public network at all — even as ciphertext — and accept a narrower availability guarantee in exchange. For them a mailbox can carry a no_ipfs opt-out, set with mailbox create --no-ipfs or mailbox update --no-ipfs true. When it is set, the delivery path keeps the sealed body in the operator’s own store and stamps the on-chain message with a local-only marker (a b3: blake3 tag) instead of a fetchable CID.

This is a deliberate, per-user re-centralization, and it costs you exactly the benefits listed above:

  • The decentralized clients can no longer read it. The trustless viewer and other IPFS-native clients fetch bodies from IPFS by CID. An opted-out message has no public CID to fetch, so those clients cannot open it — they show it as body-unavailable. Only clients that go through your operator’s store (IMAP/POP against your server) can retrieve the body.
  • Availability depends entirely on one operator. Nobody else can pin or mirror a body that was never published, so if that operator’s store is unavailable — or the account is suspended — the body is simply gone. You have re-created the single-source risk IPFS was chosen to remove.
  • mail get and mail pin degrade honestly. Point either command at an opted-out message and, rather than a confusing gateway 404, it reports that the body is not on public IPFS (the recipient opted out) and lives only in the operator’s store. There is nothing on a gateway to fetch, hash-verify, or re-pin.
  • Direct CLI mail send refuses an opted-out recipient. sithbit mail send only content-addresses the body — --path hashes a local file, --cid takes an identifier you already hold — and commits that identifier on chain. It uploads nothing and pins nothing itself, and no operator store stands behind it, so the only way that message ever becomes readable is for the body to be published to public IPFS: exactly what the recipient opted out of. The command therefore cannot honor the opt-out. It refuses up front and points you at SMTP delivery, where the recipient’s operator stores the copy privately. See Sending mail.

Confidentiality is unchanged either way — the body was already encrypted before storage. What the opt-out trades away is decentralized availability and readability, in return for keeping ciphertext off public infrastructure. Leave it off unless you specifically want that trade.

Further reading