Encrypted media
Groups can share files (photos, voice notes, documents) as encrypted attachments. Files are encrypted with keys derived from the group's MLS state, uploaded to a Blossom server, and referenced from a kind 9 message by imeta tags. Only group members can decrypt them.
Enable media when creating a group
Media is opt-in per group. Pass an encrypted media policy listing the Blossom servers members should upload to:
import { encryptedMediaBlossomDefault } from "@internet-privacy/marmot-ts";
const group = await client.groups.create("Photos", {
relays: ["wss://relay.example.com"],
encryptedMedia: encryptedMediaBlossomDefault(["https://blossom.example.com"]),
});Every member must support encrypted media; key packages created by this library advertise it (call client.keyPackages.ensurePublished at startup so your published package is current). An admin can add, replace, or remove the policy on an existing group by committing Proposals.proposeSetEncryptedMediaPolicy(policyOrNull); see combining proposals.
Upload and send
Create a Blossom transport once, then use prepareMediaMessage to encrypt and upload the files and build the message. Send the returned intent like any other message:
import {
createBlossomMediaTransport,
prepareMediaMessage,
} from "@internet-privacy/marmot-ts";
const transport = createBlossomMediaTransport({ signer: client.signer });
const prepared = await prepareMediaMessage(
group,
[{ blob: file, metadata: { filename: "photo.jpg", type: "image/jpeg" } }],
{ transport, caption: "Our trip" },
);
await client.groups.send(group.id, prepared.intent);You can attach several files to one message. Uploads default to a 32 MiB limit and a 30 second timeout per file; override with maxBytes, timeoutMs, and signal.
Re-prepare after a stale error
Attachments are encrypted against the group's current state. If the group changes (for example, a commit lands) between preparing and sending, client.groups.send throws StaleMediaPreparationError. Call prepareMediaMessage again to re-encrypt and re-upload; never reuse the old intent.
The default transport only contacts HTTPS servers on public hosts. For local development, pass allowDestination: (url) => url.hostname === "localhost". To use non-Blossom storage, implement the MediaBlobTransport interface (upload and fetch) yourself.
Receive and download
Attachments are decrypted with the exact group state the message was sent under. For a message from history, look that state up with group.session.mediaSourceForRumor, then download every attachment with downloadMessageMedia:
import { downloadMessageMedia } from "@internet-privacy/marmot-ts";
const sourceParent = await group.session.mediaSourceForRumor(rumor.id);
if (sourceParent) {
const attachments = await downloadMessageMedia(
group,
rumor.tags,
sourceParent,
{ transport },
);
for (const attachment of attachments) {
if (attachment.status === "ready") {
// attachment.attachment has filename, mediaType, dim, ...
showFile(attachment.data, attachment.attachment.mediaType);
} else {
showPlaceholder(attachment.attachment); // download or decryption failed
}
}
}When you handle results from the ingestResult event, a processed application message carries the same value as result.sourceParent.
One failing attachment never hides the caption or the other attachments. Always render rumor.content even when media is unavailable.
Keep placeholders for malformed attachments
downloadMessageMedia skips imeta tags that don't parse. To show a placeholder in their place, use getMediaAttachmentOutcomes, which returns one outcome per imeta tag in order:
import { getMediaAttachmentOutcomes } from "@internet-privacy/marmot-ts";
for (const outcome of getMediaAttachmentOutcomes(rumor.tags)) {
if (outcome.kind === "rejected") {
showBrokenAttachment(outcome.attachmentIndex, outcome.rejection.kind);
} else {
queueDownload(outcome.attachment);
}
}Download a single accepted attachment with downloadMediaAttachment(group, attachment, sourceParent, { transport }).
When media is unavailable
- No source state:
mediaSourceForRumorreturnsundefinedonce the group no longer retains the state the message was sent under (it has moved too many epochs past it, or the stores weren't persisted across a restart). The files can no longer be decrypted. - Download failed: every listed server and the group's current default servers were tried; the blob is missing, the server refused, or the request timed out.
- Decryption failed: the downloaded bytes don't match the attachment's hash or keys. The library never returns unverified plaintext.
- Rejected reference: the
imetatag is malformed (invalid_structure,unsupported_format,missing_field,duplicate_field, ormalformed_field). - Media disabled: downloading and sending throw if the group has no encrypted media policy.
Decrypt and cache files promptly if your app needs them long term. Configure a mediaFactory on the client for a persistent media cache; see the API reference.