@tavrn/e2ee 0.0.0-stage → 0.2.1

package/src/content.ts

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Encrypted attachments (ENCRYPTION.md §6) and validation of decrypted content objects. The node only
+ * sees the ciphertext of a file; name, type, size and the file key travel inside the encrypted message.
+ *
+ * Attachments are one-shot AES-256-GCM under a random file key with the AAD `"tavrn file v1"`, done with WebCrypto
+ * (native AES, no copy of the file through the WebAssembly memory, which never shrinks); the bytes are those of the
+ * crypto core's `encryptFile` (the `file` test vector).
+ */
+import { b64urlDecode, b64urlEncode, type Attachment } from "@tavrn/sdk";
+
+/** One entry of `content.attachments` in an encrypted message. */
+export interface ContentAttachment {
+  id: string;
+  name: string;
+  mime: string;
+  /** Plaintext size in bytes. */
+  size: number;
+  key: string;
+  nonce: string;
+  /** base64url SHA-256 of the uploaded ciphertext. */
+  sha256: string;
+  /** Shown blurred until clicked (design note 4.13); absent = false. */
+  spoiler?: boolean;
+}
+
+const ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+const MIME = /^[a-z0-9][a-z0-9.+-]*\/[a-z0-9][a-z0-9.+-]*$/;
+
+/** File name for display and download: no control characters or path separators, at most 255 characters. */
+export function safeFileName(name: string): string {
+  const cleaned = Array.from(name)
+    .filter((c) => c.charCodeAt(0) >= 0x20 && c.charCodeAt(0) !== 0x7f)
+    .map((c) => (c === "/" || c === "\\" ? "_" : c))
+    .join("")
+    .trim()
+    .replace(/^\.+/, "")
+    .slice(0, 255);
+  return cleaned || "file";
+}
+
+function isB64(s: unknown, bytes: number): s is string {
+  if (typeof s !== "string") return false;
+  try {
+    return b64urlDecode(s).length === bytes;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The attachments of a decrypted content object that match the envelope: same blob id and ciphertext
+ * hash, well-formed key and nonce. Anything else is dropped (a member cannot point others at blobs
+ * that are not part of the message).
+ */
+export function contentAttachments(content: Record<string, unknown>, envelope: Attachment[] | undefined): ContentAttachment[] {
+  const list = Array.isArray(content.attachments) ? content.attachments : [];
+  const out: ContentAttachment[] = [];
+  for (const raw of list.slice(0, 10)) {
+    if (!raw || typeof raw !== "object") continue;
+    const a = raw as Record<string, unknown>;
+    if (typeof a.id !== "string" || !ULID.test(a.id)) continue;
+    const env = envelope?.find((e) => e.id === a.id);
+    if (!env || env.sha256 !== a.sha256) continue;
+    if (!isB64(a.key, 32) || !isB64(a.nonce, 12) || !isB64(a.sha256, 32)) continue;
+    const mime = typeof a.mime === "string" && MIME.test(a.mime.toLowerCase()) ? a.mime.toLowerCase() : "application/octet-stream";
+    const size = typeof a.size === "number" && Number.isSafeInteger(a.size) && a.size >= 0 ? a.size : 0;
+    const entry: ContentAttachment = { id: a.id, name: safeFileName(typeof a.name === "string" ? a.name : ""), mime, size, key: a.key, nonce: a.nonce, sha256: a.sha256 };
+    if (a.spoiler === true) entry.spoiler = true;
+    out.push(entry);
+  }
+  return out;
+}
+
+/** AAD of every attachment ciphertext (ENCRYPTION.md §6). */
+const FILE_AAD = new TextEncoder().encode("tavrn file v1");
+
+function cryptoError(name: "invalid_input" | "decryption_failed", message: string): Error {
+  const e = new Error(message);
+  e.name = name;
+  return e;
+}
+
+async function fileKey(key: Uint8Array, use: KeyUsage): Promise<CryptoKey> {
+  if (key.length !== 32) throw cryptoError("invalid_input", "file key");
+  return crypto.subtle.importKey("raw", key as Uint8Array<ArrayBuffer>, "AES-GCM", false, [use]);
+}
+
+/**
+ * Encrypts attachment bytes under `key` and `nonce` (ENCRYPTION.md §6): the ciphertext with its tag and the SHA-256 of
+ * the ciphertext. {@link encryptAttachment} draws both at random; a nonce must never repeat under a key.
+ */
+export async function encryptAttachmentBytes(plain: Uint8Array, key: Uint8Array, nonce: Uint8Array): Promise<{ ciphertext: Uint8Array; sha256: Uint8Array }> {
+  if (nonce.length !== 12) throw cryptoError("invalid_input", "nonce");
+  const k = await fileKey(key, "encrypt");
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce as Uint8Array<ArrayBuffer>, additionalData: FILE_AAD, tagLength: 128 }, k, plain as Uint8Array<ArrayBuffer>));
+  const sha256 = new Uint8Array(await crypto.subtle.digest("SHA-256", ciphertext));
+  return { ciphertext, sha256 };
+}
+
+/** Encrypts a file for upload: the ciphertext blob and the metadata for the content (without the blob id). */
+export async function encryptAttachment(file: File): Promise<{ blob: Blob; meta: Omit<ContentAttachment, "id"> }> {
+  const plain = new Uint8Array(await file.arrayBuffer());
+  const key = crypto.getRandomValues(new Uint8Array(32));
+  const nonce = crypto.getRandomValues(new Uint8Array(12));
+  try {
+    const { ciphertext, sha256 } = await encryptAttachmentBytes(plain, key, nonce);
+    const meta = { name: safeFileName(file.name), mime: file.type || "application/octet-stream", size: file.size, key: b64urlEncode(key), nonce: b64urlEncode(nonce), sha256: b64urlEncode(sha256) };
+    return { blob: new Blob([ciphertext as Uint8Array<ArrayBuffer>], { type: "application/octet-stream" }), meta };
+  } finally {
+    plain.fill(0);
+    key.fill(0);
+  }
+}
+
+export class AttachmentIntegrityError extends Error {
+  constructor() {
+    super("attachment hash mismatch");
+    this.name = "AttachmentIntegrityError";
+  }
+}
+
+/**
+ * Checks the bytes of a plaintext attachment against its `sha256` (base64url), which a signed plaintext message covers
+ * (FEDERATION.md §10.3): throws {@link AttachmentIntegrityError} when the node served other bytes.
+ */
+export async function verifyPlainAttachment(bytes: Uint8Array, sha256: string): Promise<void> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes as Uint8Array<ArrayBuffer>));
+  if (b64urlEncode(digest) !== sha256) throw new AttachmentIntegrityError();
+}
+
+/**
+ * Checks the SHA-256 of the downloaded ciphertext (§6 step 4), then decrypts it. Throws
+ * {@link AttachmentIntegrityError} for other bytes, an `Error` named `decryption_failed` for a wrong key or nonce.
+ */
+export async function decryptAttachment(ciphertext: Uint8Array, a: Pick<ContentAttachment, "key" | "nonce" | "sha256">): Promise<Uint8Array> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", ciphertext as Uint8Array<ArrayBuffer>));
+  if (b64urlEncode(digest) !== a.sha256) throw new AttachmentIntegrityError();
+  const key = b64urlDecode(a.key);
+  const nonce = b64urlDecode(a.nonce);
+  try {
+    if (nonce.length !== 12) throw cryptoError("invalid_input", "nonce");
+    const k = await fileKey(key, "decrypt");
+    try {
+      return new Uint8Array(await crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce as Uint8Array<ArrayBuffer>, additionalData: FILE_AAD, tagLength: 128 }, k, ciphertext as Uint8Array<ArrayBuffer>));
+    } catch {
+      throw cryptoError("decryption_failed", "attachment does not decrypt");
+    }
+  } finally {
+    key.fill(0);
+  }
+}

package/src/embeds.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Embeds in `text` content (protocol/APPLICATIONS.md §6.4): the client half of the shared content codec. The node
+ * checks plaintext content with the same rules (`server/src/embeds.rs`); encrypted content is invisible to it, so
+ * senders check before encrypting ({@link assertEmbeds}) and receivers drop invalid embeds after decrypting
+ * ({@link withValidEmbeds}). {@link readEmbeds} gives a renderer the checked embeds of any content object.
+ *
+ * Embeds carry text, one `https://` link and a colour, never images: clients never load anything from foreign
+ * hosts for them.
+ */
+
+export const MAX_EMBEDS = 10;
+export const MAX_EMBED_CHARS = 6000;
+export const MAX_EMBED_TITLE = 256;
+export const MAX_EMBED_DESCRIPTION = 4096;
+export const MAX_EMBED_URL = 2048;
+export const MAX_EMBED_FIELDS = 25;
+export const MAX_EMBED_FIELD_NAME = 256;
+export const MAX_EMBED_FIELD_VALUE = 1024;
+export const MAX_EMBED_FOOTER = 2048;
+export const MAX_EMBED_COLOR = 0xffffff;
+
+export interface EmbedField {
+  name: string;
+  value: string;
+  inline?: boolean;
+}
+
+/** A checked embed. */
+export interface MessageEmbed {
+  title?: string;
+  /** Markdown subset, rendered through the same sanitizer as message bodies. */
+  description?: string;
+  /** `https://` only. */
+  url?: string;
+  /** 0–16777215 (`0xRRGGBB`). */
+  color?: number;
+  fields?: EmbedField[];
+  footer?: string;
+  /** RFC 3339. */
+  timestamp?: string;
+}
+
+/** Thrown by {@link assertEmbeds} (the node answers `400 message.embeds_invalid` for plaintext). */
+export class EmbedsInvalidError extends Error {
+  readonly code = "message.embeds_invalid";
+  constructor(detail: string) {
+    super(detail);
+    this.name = "EmbedsInvalidError";
+  }
+}
+
+/** Characters as the node counts them (Unicode scalar values). */
+const chars = (s: string) => Array.from(s).length;
+
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/i;
+
+/** `https://` with a host, without credentials or whitespace, at most 2048 characters. */
+export function validEmbedUrl(url: unknown): url is string {
+  if (typeof url !== "string" || url.length > MAX_EMBED_URL || !url.startsWith("https://") || /\s/.test(url)) return false;
+  try {
+    const u = new URL(url);
+    return u.protocol === "https:" && !!u.hostname && !u.username && !u.password;
+  } catch {
+    return false;
+  }
+}
+
+/** Why `embeds` is invalid, or `null` when it follows §6.4. */
+export function embedsProblem(embeds: unknown): string | null {
+  if (!Array.isArray(embeds)) return "embeds must be an array";
+  if (embeds.length > MAX_EMBEDS) return `at most ${MAX_EMBEDS} embeds`;
+  let total = 0;
+  for (const raw of embeds) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return "every embed is an object";
+    const e = raw as Record<string, unknown>;
+    const text = (key: string, max: number): number | string => {
+      const v = e[key];
+      if (v === undefined || v === null) return 0;
+      if (typeof v !== "string") return `${key} must be a string`;
+      const n = chars(v);
+      return n > max ? `${key} has at most ${max} characters` : n;
+    };
+    const title = text("title", MAX_EMBED_TITLE);
+    const description = text("description", MAX_EMBED_DESCRIPTION);
+    const footer = text("footer", MAX_EMBED_FOOTER);
+    for (const t of [title, description, footer]) if (typeof t === "string") return t;
+    total += (title as number) + (description as number) + (footer as number);
+    if (e.url !== undefined && e.url !== null && !validEmbedUrl(e.url)) return "url must be an https:// URL without credentials";
+    if (e.color !== undefined && e.color !== null && !(Number.isInteger(e.color) && (e.color as number) >= 0 && (e.color as number) <= MAX_EMBED_COLOR)) return "color is an integer from 0 to 16777215";
+    if (e.timestamp !== undefined && e.timestamp !== null && !(typeof e.timestamp === "string" && e.timestamp.length <= 64 && RFC3339.test(e.timestamp) && !Number.isNaN(Date.parse(e.timestamp)))) return "timestamp must be an RFC 3339 time";
+    let hasFields = false;
+    if (e.fields !== undefined && e.fields !== null) {
+      if (!Array.isArray(e.fields)) return "fields must be an array";
+      if (e.fields.length > MAX_EMBED_FIELDS) return `at most ${MAX_EMBED_FIELDS} fields`;
+      for (const f of e.fields) {
+        if (!f || typeof f !== "object" || Array.isArray(f)) return "every field is an object";
+        const field = f as Record<string, unknown>;
+        if (typeof field.name !== "string" || typeof field.value !== "string") return "fields need a name and a value";
+        const [n, v] = [chars(field.name), chars(field.value)];
+        if (n === 0 || v === 0) return "fields need a name and a value";
+        if (n > MAX_EMBED_FIELD_NAME || v > MAX_EMBED_FIELD_VALUE) return "field too long";
+        if (field.inline !== undefined && field.inline !== null && typeof field.inline !== "boolean") return "inline must be a boolean";
+        total += n + v;
+      }
+      hasFields = e.fields.length > 0;
+    }
+    if ((title as number) + (description as number) + (footer as number) === 0 && !hasFields) return "an embed needs a title, a description, fields or a footer";
+  }
+  return total > MAX_EMBED_CHARS ? `at most ${MAX_EMBED_CHARS} characters in total` : null;
+}
+
+/**
+ * Sender side: throws {@link EmbedsInvalidError} when a `text` content object carries invalid embeds (or another
+ * type carries any). Content without `embeds` passes.
+ */
+export function assertEmbeds(content: Record<string, unknown>): void {
+  if (content.embeds === undefined || content.embeds === null) return;
+  if (content.type !== "text") throw new EmbedsInvalidError("only text content carries embeds");
+  const problem = embedsProblem(content.embeds);
+  if (problem) throw new EmbedsInvalidError(problem);
+}
+
+/** Receiver side: the content without its `embeds` when they are invalid (they are then never shown). */
+export function withValidEmbeds<T extends Record<string, unknown>>(content: T): T {
+  if (content.embeds === undefined) return content;
+  if (content.type === "text" && embedsProblem(content.embeds) === null) return content;
+  const { embeds: _dropped, ...rest } = content;
+  return rest as T;
+}
+
+/** The checked embeds of a content object for rendering (none when invalid); only known fields are kept. */
+export function readEmbeds(content: unknown): MessageEmbed[] {
+  if (!content || typeof content !== "object") return [];
+  const c = content as Record<string, unknown>;
+  if (c.type !== "text" || !Array.isArray(c.embeds) || c.embeds.length === 0 || embedsProblem(c.embeds) !== null) return [];
+  return (c.embeds as Record<string, unknown>[]).map((e) => {
+    const out: MessageEmbed = {};
+    if (typeof e.title === "string" && e.title) out.title = e.title;
+    if (typeof e.description === "string" && e.description) out.description = e.description;
+    if (typeof e.url === "string") out.url = e.url;
+    if (typeof e.color === "number") out.color = e.color;
+    if (Array.isArray(e.fields)) out.fields = (e.fields as Record<string, unknown>[]).map((f) => ({ name: f.name as string, value: f.value as string, ...(f.inline === true ? { inline: true } : {}) }));
+    if (typeof e.footer === "string" && e.footer) out.footer = e.footer;
+    if (typeof e.timestamp === "string") out.timestamp = e.timestamp;
+    return out;
+  });
+}

package/src/errors.ts

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MPL-2.0
+/** Errors of the account flows (ENCRYPTION.md §2.4, §9, §9a) with stable codes for the UI. */
+
+export type E2eeErrorCode =
+  | "recovery_key_invalid"
+  | "recovery_key_wrong"
+  | "passkey_wrong"
+  | "no_recovery_entry"
+  | "no_passkey_entry"
+  | "identity_mismatch"
+  | "rotation_devices"
+  | "locked"
+  /** Setup refused: this device holds the account's master secret, or the node has its recovery entry (unlock). */
+  | "already_set_up"
+  /**
+   * The session's device has a key on the node that this device no longer holds (its local key store was lost):
+   * a device key is immutable (ENCRYPTION.md §3.1), so encryption needs a new device, i.e. signing in again.
+   */
+  | "device_key_lost"
+  /**
+   * A local secret that must not be reset silently (the key pins, the verified contacts) decrypts but cannot be read:
+   * the manager does not start over with empty pins (that would trust every changed key again). The blob stays stored.
+   */
+  | "state_unreadable";
+
+export class E2eeError extends Error {
+  constructor(readonly code: E2eeErrorCode) {
+    super(code);
+    this.name = "E2eeError";
+  }
+}

package/src/files.ts

@@ -0,0 +1,346 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * End-to-end encrypted files channels (FILES.md §8, ENCRYPTION.md §5c).
+ *
+ * Content: every file gets a random 32-byte file key; its content (part `content`) and its client-made thumbnail
+ * (part `thumbnail`) are encrypted in chunks of 1 MiB with AES-256-GCM under
+ * `part_key = HKDF-SHA256(file_key, salt = 32 zero bytes, info = "tavrn file chunk v1" || 0x00 || part)`, nonce
+ * `u32(0) || u64(index)` and `aad = "tavrn file chunk v1" || 0x00 || u8(last)`. Everything here is WebCrypto, so it
+ * runs in browsers, workers and Node.js without the WebAssembly module; chunks are processed one at a time
+ * (bounded memory: a Blob of encrypted chunks for uploads, a TransformStream for downloads).
+ *
+ * Records: the name, type and file key travel in an entry record, content format 1 (ENCRYPTION.md §5.2) of
+ * `{ type: "files.entry", v: 1, entry, kind, name, mime?, size?, key?, thumbnail? }` under the channel's current
+ * epoch. Encrypting goes through {@link MlsManager.encrypt} (forwarded to the tab that owns the MLS state);
+ * decrypting stays local ({@link MlsManager.decrypt}).
+ */
+import { b64urlDecode, b64urlEncode } from "@tavrn/sdk";
+import type { DecryptFailure, MlsManager } from "./mls";
+
+export const FILE_CHUNK = 1 << 20;
+export const FILE_TAG = 16;
+export const FILE_CHUNK_LABEL = "tavrn file chunk v1";
+export type FilePart = "content" | "thumbnail";
+export const FILE_RECORD_TYPE = "files.entry";
+/** Longest name in characters (FILES.md §2). */
+export const MAX_ENTRY_NAME = 255;
+
+const enc = new TextEncoder();
+const subtle = (): SubtleCrypto => globalThis.crypto.subtle;
+const buf = (b: Uint8Array): Uint8Array<ArrayBuffer> => (b.buffer instanceof ArrayBuffer && b.byteOffset === 0 && b.byteLength === b.buffer.byteLength ? (b as Uint8Array<ArrayBuffer>) : new Uint8Array(b));
+
+/** A fresh random file key. */
+export function newFileKey(): Uint8Array {
+  return globalThis.crypto.getRandomValues(new Uint8Array(32));
+}
+
+/** The AES-256-GCM key of one part of a file. */
+export async function filePartKey(fileKey: Uint8Array, part: FilePart): Promise<CryptoKey> {
+  if (fileKey.length !== 32) throw new RangeError("file keys have 32 bytes");
+  const ikm = await subtle().importKey("raw", buf(fileKey), "HKDF", false, ["deriveKey"]);
+  const info = new Uint8Array([...enc.encode(FILE_CHUNK_LABEL), 0, ...enc.encode(part)]);
+  return subtle().deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(32), info }, ikm, { name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
+}
+
+/** `u32(0) || u64(index)`. */
+export function chunkNonce(index: number): Uint8Array {
+  if (!Number.isSafeInteger(index) || index < 0) throw new RangeError("chunk index");
+  const n = new Uint8Array(12);
+  new DataView(n.buffer).setBigUint64(4, BigInt(index));
+  return n;
+}
+
+/** `"tavrn file chunk v1" || 0x00 || u8(last)`. */
+export function chunkAad(last: boolean): Uint8Array {
+  return new Uint8Array([...enc.encode(FILE_CHUNK_LABEL), 0, last ? 1 : 0]);
+}
+
+/** Number of chunks of a part with `n` plaintext bytes (an empty part is one empty chunk). */
+export function chunkCount(n: number): number {
+  return Math.max(1, Math.ceil(n / FILE_CHUNK));
+}
+
+/** Stored (ciphertext) size of a part with `n` plaintext bytes. */
+export function encryptedSize(n: number): number {
+  return n + FILE_TAG * chunkCount(n);
+}
+
+/** Plaintext size of a stored part, or null when no plaintext size encrypts to `stored` bytes. */
+export function plaintextSize(stored: number): number | null {
+  if (!Number.isSafeInteger(stored) || stored < FILE_TAG) return null;
+  const chunks = Math.max(1, Math.ceil(stored / (FILE_CHUNK + FILE_TAG)));
+  const n = stored - FILE_TAG * chunks;
+  if (n < 0 || (chunks > 1 && n <= (chunks - 1) * FILE_CHUNK)) return null;
+  return n;
+}
+
+export async function encryptChunk(key: CryptoKey, index: number, last: boolean, data: Uint8Array): Promise<Uint8Array> {
+  return new Uint8Array(await subtle().encrypt({ name: "AES-GCM", iv: buf(chunkNonce(index)), additionalData: buf(chunkAad(last)), tagLength: 128 }, key, buf(data)));
+}
+
+export class FileDecryptError extends Error {
+  constructor(message = "file chunk does not decrypt") {
+    super(message);
+    this.name = "FileDecryptError";
+  }
+}
+
+export async function decryptChunk(key: CryptoKey, index: number, last: boolean, data: Uint8Array): Promise<Uint8Array> {
+  try {
+    return new Uint8Array(await subtle().decrypt({ name: "AES-GCM", iv: buf(chunkNonce(index)), additionalData: buf(chunkAad(last)), tagLength: 128 }, key, buf(data)));
+  } catch {
+    throw new FileDecryptError();
+  }
+}
+
+/** Encrypts a whole part held in memory (thumbnails, tests). */
+export async function encryptFileBytes(fileKey: Uint8Array, part: FilePart, plain: Uint8Array): Promise<Uint8Array> {
+  const key = await filePartKey(fileKey, part);
+  const chunks = chunkCount(plain.length);
+  const out = new Uint8Array(encryptedSize(plain.length));
+  for (let i = 0; i < chunks; i++) {
+    const c = await encryptChunk(key, i, i === chunks - 1, plain.subarray(i * FILE_CHUNK, (i + 1) * FILE_CHUNK));
+    out.set(c, i * (FILE_CHUNK + FILE_TAG));
+  }
+  return out;
+}
+
+/** Decrypts a whole part held in memory. */
+export async function decryptFileBytes(fileKey: Uint8Array, part: FilePart, stored: Uint8Array): Promise<Uint8Array> {
+  const n = plaintextSize(stored.length);
+  if (n === null) throw new FileDecryptError("invalid ciphertext size");
+  const key = await filePartKey(fileKey, part);
+  const chunks = chunkCount(n);
+  const out = new Uint8Array(n);
+  for (let i = 0; i < chunks; i++) {
+    const from = i * (FILE_CHUNK + FILE_TAG);
+    const p = await decryptChunk(key, i, i === chunks - 1, stored.subarray(from, Math.min(from + FILE_CHUNK + FILE_TAG, stored.length)));
+    out.set(p, i * FILE_CHUNK);
+  }
+  return out;
+}
+
+/**
+ * Encrypts a file for upload chunk by chunk (one chunk in memory at a time): the ciphertext as a Blob of encrypted
+ * chunks, the file key (caller zeroes it after writing the record) and the plaintext size.
+ */
+export async function encryptFileStream(file: Blob, opts: { fileKey?: Uint8Array; part?: FilePart; onProgress?: (fraction: number) => void; signal?: AbortSignal } = {}): Promise<{ blob: Blob; key: Uint8Array; size: number }> {
+  const fileKey = opts.fileKey ?? newFileKey();
+  const key = await filePartKey(fileKey, opts.part ?? "content");
+  const chunks = chunkCount(file.size);
+  const parts: BlobPart[] = [];
+  for (let i = 0; i < chunks; i++) {
+    if (opts.signal?.aborted) throw new DOMException("aborted", "AbortError");
+    const plain = new Uint8Array(await file.slice(i * FILE_CHUNK, (i + 1) * FILE_CHUNK).arrayBuffer());
+    parts.push(buf(await encryptChunk(key, i, i === chunks - 1, plain)));
+    plain.fill(0);
+    opts.onProgress?.((i + 1) / chunks);
+  }
+  return { blob: new Blob(parts, { type: "application/octet-stream" }), key: fileKey, size: file.size };
+}
+
+/**
+ * A stream that decrypts the stored chunks `firstChunk … endChunk` (default: to the end) of a part with `storedSize`
+ * ciphertext bytes, whatever the network's chunking. The input starts at the first byte of `firstChunk` (a range
+ * request, see {@link ciphertextRange}); a stream that ends early or carries a damaged chunk errors with
+ * {@link FileDecryptError}.
+ */
+export function decryptFileChunks(fileKey: Uint8Array, part: FilePart, storedSize: number, firstChunk = 0, endChunk?: number): TransformStream<Uint8Array, Uint8Array> {
+  const n = plaintextSize(storedSize);
+  const lastIndex = n === null ? -1 : chunkCount(n) - 1;
+  const stopAt = Math.min(endChunk ?? lastIndex, lastIndex);
+  const keyP = filePartKey(fileKey, part);
+  // Received bytes not decrypted yet, as a list (no quadratic copying of small network pieces).
+  let parts: Uint8Array[] = [];
+  let buffered = 0;
+  let index = firstChunk;
+  const sizeOf = (i: number) => (i === lastIndex ? storedSize - i * (FILE_CHUNK + FILE_TAG) : FILE_CHUNK + FILE_TAG);
+  const take = (size: number): Uint8Array => {
+    const out = new Uint8Array(size);
+    let at = 0;
+    while (at < size) {
+      const head = parts[0]!;
+      const n = Math.min(head.length, size - at);
+      out.set(head.subarray(0, n), at);
+      at += n;
+      if (n === head.length) parts.shift();
+      else parts[0] = head.subarray(n);
+    }
+    buffered -= size;
+    return out;
+  };
+  const drain = async (controller: TransformStreamDefaultController<Uint8Array>, flush: boolean) => {
+    const key = await keyP;
+    while (index <= stopAt && buffered >= sizeOf(index)) {
+      const size = sizeOf(index);
+      controller.enqueue(await decryptChunk(key, index, index === lastIndex, take(size)));
+      index++;
+    }
+    if (flush && buffered > 0) throw new FileDecryptError("trailing bytes");
+  };
+  return new TransformStream<Uint8Array, Uint8Array>({
+    start() {
+      if (n === null) throw new FileDecryptError("invalid ciphertext size");
+    },
+    async transform(chunk, controller) {
+      if (chunk.length === 0) return;
+      parts.push(chunk);
+      buffered += chunk.length;
+      await drain(controller, false);
+      // Bytes after the last expected chunk are refused at once, not buffered until the stream ends.
+      if (index > stopAt && buffered > 0) throw new FileDecryptError("trailing bytes");
+    },
+    async flush(controller) {
+      await drain(controller, true);
+      parts = [];
+      if (firstChunk <= stopAt && index !== stopAt + 1) throw new FileDecryptError("the file ends early");
+    },
+  });
+}
+
+/**
+ * The stored byte range (inclusive) that holds the plaintext bytes `[from, to]` of a part, the first and last chunk
+ * index and how many plaintext bytes to skip in the first chunk. `null` when the range is outside the part.
+ */
+export function ciphertextRange(from: number, to: number, storedSize: number): { start: number; end: number; firstChunk: number; lastChunk: number; skip: number } | null {
+  const n = plaintextSize(storedSize);
+  if (n === null || from < 0 || to < from || from >= n) return null;
+  const last = Math.min(to, n - 1);
+  const firstChunk = Math.floor(from / FILE_CHUNK);
+  const lastChunk = Math.floor(last / FILE_CHUNK);
+  return {
+    start: firstChunk * (FILE_CHUNK + FILE_TAG),
+    end: Math.min((lastChunk + 1) * (FILE_CHUNK + FILE_TAG), storedSize) - 1,
+    firstChunk,
+    lastChunk,
+    skip: from - firstChunk * FILE_CHUNK,
+  };
+}
+
+// ---- Entry records (FILES.md §8.4) --------------------------------------------------------------
+
+export interface FileThumbnailMeta {
+  mime: string;
+  width: number;
+  height: number;
+}
+
+/** A checked record. Files carry `mime`, `size` (plaintext bytes) and `key`; folders only the name. */
+export interface FileRecord {
+  entry: string;
+  kind: "file" | "folder";
+  name: string;
+  mime: string;
+  size: number;
+  key: string;
+  thumbnail?: FileThumbnailMeta;
+}
+
+/** What a record is checked against: the entry as the node lists it. */
+export interface RecordEntry {
+  id: string;
+  kind: string;
+  /** Stored (ciphertext) size. */
+  size: number;
+  record?: string | null;
+  record_epoch?: number | null;
+  record_author?: string | null;
+  record_device_id?: string | null;
+  record_at?: string | null;
+}
+
+const MIME = /^[a-z0-9][a-z0-9.+-]*\/[a-z0-9][a-z0-9.+-]*$/;
+const RASTER = /^image\/(png|jpeg|gif|webp|avif|bmp)$/;
+// Bidirectional controls that can disguise an extension (FILES.md §2).
+const BIDI = /[‎‏‪-‮⁦-⁩؜]/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+/** The rules of FILES.md §2 for a name: NFC, trimmed, 1–255 characters, no `/`, `\`, controls or bidi controls, not `.`/`..`. */
+export function validEntryName(name: unknown): name is string {
+  if (typeof name !== "string") return false;
+  const n = name.normalize("NFC").trim();
+  if (n !== name || !n || Array.from(n).length > MAX_ENTRY_NAME) return false;
+  if (n.includes("/") || n.includes("\\") || CONTROL.test(n) || BIDI.test(n)) return false;
+  return n !== "." && n !== "..";
+}
+
+/** Normalises a name for a record (NFC, trimmed) and checks it; null when it breaks FILES.md §2. */
+export function entryName(raw: string): string | null {
+  const n = raw.normalize("NFC").trim();
+  return validEntryName(n) ? n : null;
+}
+
+/** The JSON object of a record (written by the uploader or a renaming member). */
+export function fileRecordContent(r: FileRecord): Record<string, unknown> {
+  if (!validEntryName(r.name)) throw new RangeError("invalid entry name");
+  if (r.kind === "folder") return { type: FILE_RECORD_TYPE, v: 1, entry: r.entry, kind: "folder", name: r.name };
+  const out: Record<string, unknown> = { type: FILE_RECORD_TYPE, v: 1, entry: r.entry, kind: "file", name: r.name, mime: MIME.test(r.mime) ? r.mime : "application/octet-stream", size: r.size, key: r.key };
+  if (r.thumbnail) out.thumbnail = { mime: r.thumbnail.mime, width: r.thumbnail.width, height: r.thumbnail.height };
+  return out;
+}
+
+/** Checks a decrypted record against its entry (FILES.md §8.4); null when the record must be refused. */
+export function parseFileRecord(content: Record<string, unknown>, entry: Pick<RecordEntry, "id" | "kind" | "size">): FileRecord | null {
+  if (content.type !== FILE_RECORD_TYPE || content.v !== 1) return null;
+  if (content.entry !== entry.id || content.kind !== entry.kind) return null;
+  if (!validEntryName(content.name)) return null;
+  if (content.kind === "folder") return { entry: entry.id, kind: "folder", name: content.name, mime: "", size: 0, key: "" };
+  if (content.kind !== "file") return null;
+  const size = content.size;
+  if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || encryptedSize(size) !== entry.size) return null;
+  if (typeof content.key !== "string") return null;
+  try {
+    if (b64urlDecode(content.key).length !== 32) return null;
+  } catch {
+    return null;
+  }
+  const mime = typeof content.mime === "string" && MIME.test(content.mime) ? content.mime : "application/octet-stream";
+  const out: FileRecord = { entry: entry.id, kind: "file", name: content.name, mime, size, key: content.key };
+  const t = content.thumbnail as Record<string, unknown> | undefined;
+  if (t && typeof t === "object" && typeof t.mime === "string" && RASTER.test(t.mime)) {
+    const w = Number(t.width);
+    const h = Number(t.height);
+    if (Number.isSafeInteger(w) && Number.isSafeInteger(h) && w > 0 && h > 0 && w <= 4096 && h <= 4096) out.thumbnail = { mime: t.mime, width: w, height: h };
+  }
+  return out;
+}
+
+/** Encrypts a record under the channel's current epoch (forwarded to the owning tab like every state change). */
+export async function encryptFileRecord(mls: Pick<MlsManager, "encrypt">, conversationId: string, r: FileRecord): Promise<{ record: string; record_epoch: number }> {
+  const { content, epoch } = await mls.encrypt(conversationId, fileRecordContent(r));
+  return { record: content, record_epoch: epoch };
+}
+
+export type FileRecordResult = { ok: true; record: FileRecord } | { ok: false; reason: DecryptFailure | "withheld" };
+
+/**
+ * Decrypts and checks the record of an entry (local). `withheld`: the node serves no record (outside the history
+ * window or none written); the other reasons are those of message content.
+ */
+export async function decryptFileRecord(mls: Pick<MlsManager, "decrypt">, conversationId: string, e: RecordEntry): Promise<FileRecordResult> {
+  if (!e.record || !e.record_author || !e.record_device_id || typeof e.record_epoch !== "number") return { ok: false, reason: "withheld" };
+  const r = await mls.decrypt(conversationId, { id: `files-entry:${e.id}`, author: e.record_author, device_id: e.record_device_id, epoch: e.record_epoch, content: e.record, created_at: e.record_at ?? null });
+  if (!r.ok) return r;
+  const record = parseFileRecord(r.content, e);
+  return record ? { ok: true, record } : { ok: false, reason: "invalid" };
+}
+
+/**
+ * Entries with records as the message samples of history key checks (ENCRYPTION.md §7b, FILES.md §8.7): a files
+ * channel has no messages, a shared epoch key is checked against an entry record of that epoch instead.
+ */
+export function recordSamples(entries: RecordEntry[]): { author: string; device_id: string; epoch: number; content: string; encrypted: true }[] {
+  const out: { author: string; device_id: string; epoch: number; content: string; encrypted: true }[] = [];
+  for (const e of entries) {
+    if (e.record && e.record_author && e.record_device_id && typeof e.record_epoch === "number") out.push({ author: e.record_author, device_id: e.record_device_id, epoch: e.record_epoch, content: e.record, encrypted: true });
+  }
+  return out;
+}
+
+/** The file key of a record as bytes (caller zeroes it). */
+export function recordKey(r: FileRecord): Uint8Array {
+  return b64urlDecode(r.key);
+}
+
+export { b64urlEncode as fileKeyText };