Envelope Encryption

Envelope encryption is the core security model in MeshKit. Plaintext enters the MeshKit client, not the provider. Core creates an encrypted envelope, writes encrypted bytes, and records enough metadata for authorized identities to open the object later.

Why It Matters

Providers are storage and workflow boundaries. They should not need plaintext access to store, retrieve, pin, persist, or audit application content. MeshKit keeps plaintext handling inside the client and stores encrypted envelopes with provider metadata.

Envelope Flow

At a high level:

MeshKit receives plaintext bytes.
Core creates a fresh data encryption key for the object.
Core encrypts the bytes with an authenticated encryption mode.
Core wraps the data key for the owner and any recipients.
Core writes the encrypted envelope to the provider.
The provider records proof metadata and returns a CID.

What Is Authenticated

Envelope metadata is part of the security boundary. Names, content type, selected metadata, recipient wrapping context, and algorithm identifiers are treated as data that must match the encrypted object. If a provider returns mismatched bytes or metadata, MeshKit rejects the read before returning plaintext.

What The Provider Sees

The provider can see operational metadata such as:

CID
byte size
provider name
envelope version
content type, if you set it
application metadata, if you include it
capsule IDs, mailbox records, sync records, logs, or proof summaries

The provider should not see:

plaintext file contents
plaintext record values
private identity keys
unwrapped data keys
capability token secrets

Do not put secrets in application metadata.

Opening An Envelope

To open content, MeshKit needs:

the encrypted bytes for the CID
the matching proof and metadata boundary
a local identity or share capsule that can unwrap the data key
any policy, vault, or capability checks required by the capsule

If those requirements do not match, opening fails closed with a MeshKitError.

Security Boundaries

MeshKit protects content before provider storage.
MeshKit cannot protect plaintext after your application decrypts and exposes it.
Revocation blocks future opens through MeshKit checks; it cannot erase already copied plaintext.
Runtime key storage depends on the selected environment and bridge.
Current public claims should stay narrow: WebCrypto-compatible primitives, not FIPS certification, HPKE, or post-quantum guarantees unless a future release explicitly adds them.