fb-messenger-e2ee 0.1.0

package/src/e2ee/media/media-upload.ts

@@ -0,0 +1,90 @@
+import type { MediaUploadConfig, MediaUploadResult, MmsTypeStr } from "../../models/media.ts";
+export type { MediaUploadConfig, MediaUploadResult, MmsTypeStr };
+
+export function toMediaUploadToken(fileEncSHA256: Buffer): string {
+  return fileEncSHA256.toString("base64").replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+/**
+ * Callback to refresh media upload config (e.g., re-query media_conn).
+ */
+export type RefreshUploadConfigFn = () => Promise<MediaUploadConfig>;
+
+export interface UploadMediaOptions {
+  /** Optional callback to refresh auth config on 401. */
+  refreshConfig?: RefreshUploadConfigFn;
+  /** Max retry attempts after refresh (default 1). */
+  maxRetries?: number;
+}
+
+/**
+ * Upload encrypted media bytes to Facebook's upload CDN.
+ * Supports retry on 401 by refreshing the upload config.
+ */
+export async function uploadMedia(
+  config: MediaUploadConfig,
+  data: Buffer,
+  fileEncSHA256: Buffer,
+  mmsType: MmsTypeStr,
+  options?: UploadMediaOptions,
+): Promise<MediaUploadResult> {
+  if (!config.auth) {
+    throw new Error("Missing media upload auth token; query media_conn before uploading E2EE media");
+  }
+
+  const token = toMediaUploadToken(fileEncSHA256);
+  const maxRetries = options?.maxRetries ?? 1;
+  let currentConfig = config;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const uploadUrl = `https://${currentConfig.host}/wa-msgr/mms/${mmsType}/${token}?auth=${encodeURIComponent(currentConfig.auth)}&token=${encodeURIComponent(token)}`;
+
+    const resp = await fetch(uploadUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/octet-stream",
+        "Content-Length": String(data.length),
+        "Origin": "https://www.facebook.com",
+        "Referer": "https://www.facebook.com/",
+      },
+      body: data,
+    });
+
+    if (resp.ok) {
+      const json = await resp.json() as Record<string, unknown>;
+      const stringField = (...keys: string[]): string => {
+        for (const key of keys) {
+          const value = json[key];
+          if (typeof value === "string") return value;
+          if (typeof value === "number") return String(value);
+        }
+        return "";
+      };
+
+      return {
+        url: stringField("url"),
+        directPath: stringField("direct_path", "directPath"),
+        handle: stringField("handle"),
+        objectId: stringField("object_id", "objectID", "objectId"),
+      };
+    }
+
+    // On 401, try to refresh config and retry
+    if (resp.status === 401 && attempt < maxRetries && options?.refreshConfig) {
+      const body = await resp.text().catch(() => "");
+      console.warn(`Media upload 401 (attempt ${attempt + 1}), refreshing config...`, body.slice(0, 200));
+      currentConfig = await options.refreshConfig();
+      if (!currentConfig.auth) {
+        throw new Error("Media upload refresh returned empty auth token");
+      }
+      continue;
+    }
+
+    // Non-401 or max retries exceeded
+    const body = await resp.text().catch(() => "");
+    throw new Error(`Media upload failed: HTTP ${resp.status} - ${body}`);
+  }
+
+  // Should not reach here, but just in case
+  throw new Error("Media upload failed after retries");
+}

package/src/e2ee/message/builders/client-payload.ts

@@ -0,0 +1,54 @@
+import { ProtoWriter } from "../proto/proto-writer.ts";
+
+export interface ClientPayloadOptions {
+  username: bigint;
+  deviceId: number;
+  fbCat?: Buffer;
+  fbUserAgent?: Buffer;
+  fbAppID?: bigint;
+  fbDeviceID?: Buffer;
+  fbCatBase64?: string;
+}
+
+// ClientPayload encoding (Handshake Step 3)
+
+export function encodeClientPayload(opts: ClientPayloadOptions): Buffer {
+  // AppVersion: 301.0.2
+  const appVersion = new ProtoWriter()
+    .varint(1, 301)
+    .varint(2, 0)
+    .varint(3, 2)
+    .build();
+
+  // UserAgent
+  const userAgent = new ProtoWriter()
+    .varint(1, 32) // Platform = BLUE_WEB (32)
+    .bytes(2, appVersion)
+    .string(3, "000") // mcc
+    .string(4, "000") // mnc
+    .string(5, "") // osVersion
+    .string(6, "Linux") // manufacturer (OSName)
+    .string(7, "Chrome") // device (BrowserName)
+    .string(8, "") // osBuildNumber
+    .varint(10, 3)    // releaseChannel = DEBUG
+    .string(11, "en") // localeLanguage
+    .string(12, "en") // localeCountry
+    .build();
+
+  const UserAgentStr = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36";
+
+  // ClientPayload
+  let w = new ProtoWriter()
+    .uint64_varint(1, opts.username) // field 1
+    .bool(3, false) // field 3: passive
+    .bytes(5, userAgent) // field 5
+    .varint(12, 1) // field 12: connectType (WIFI_UNKNOWN)
+    .varint(13, 1) // field 13: connectReason (USER_ACTIVATED)
+    .varint(18, opts.deviceId) // field 18: device
+    .varint(20, 1) // field 20: product (MESSENGER)
+    .bytes(21, opts.fbCatBase64 ? Buffer.from(opts.fbCatBase64) : Buffer.alloc(0)) // field 21: fbCat (as base64 string bytes)
+    .bytes(22, opts.fbUserAgent ?? Buffer.from(UserAgentStr)) // field 22: fbUserAgent
+    .bool(33, true); // field 33: pull
+
+  return w.build();
+}

package/src/e2ee/message/builders/consumer-application.ts

@@ -0,0 +1,362 @@
+import type { MediaFields } from "../../../models/e2ee.ts";
+import { ProtoWriter } from "../proto/proto-writer.ts";
+
+export type { MediaFields };
+
+// ConsumerApplication encoding
+
+
+// MessageBuilder (Pattern 3: Builder Pattern with Type Safety)
+
+type ContentType =
+  | { type: "text"; text: string }
+  | { type: "image"; media: MediaFields }
+  | { type: "video"; media: MediaFields }
+  | { type: "audio"; media: MediaFields }
+  | { type: "document"; media: MediaFields }
+  | { type: "sticker"; media: MediaFields }
+  | { type: "reaction"; emoji: string; targetId: string }
+  | { type: "edit"; text: string; targetId: string }
+  | { type: "revoke"; targetId: string; fromMe: boolean };
+
+export class MessageBuilder {
+  private content?: ContentType;
+  private replyTo?: { id: string; senderJid: string };
+
+  setReply(id: string, senderJid: string): this {
+    this.replyTo = { id, senderJid };
+    return this;
+  }
+
+  getReply() {
+    return this.replyTo;
+  }
+
+  setText(text: string): this {
+    this.content = { type: "text", text };
+    return this;
+  }
+
+  setImage(media: MediaFields): this {
+    this.content = { type: "image", media };
+    return this;
+  }
+
+  setVideo(media: MediaFields): this {
+    this.content = { type: "video", media };
+    return this;
+  }
+
+  setAudio(media: MediaFields): this {
+    this.content = { type: "audio", media };
+    return this;
+  }
+
+  setDocument(media: MediaFields): this {
+    this.content = { type: "document", media };
+    return this;
+  }
+
+  setSticker(media: MediaFields): this {
+    this.content = { type: "sticker", media };
+    return this;
+  }
+
+  setReaction(emoji: string, targetId: string): this {
+    this.content = { type: "reaction", emoji, targetId };
+    return this;
+  }
+
+  setEdit(text: string, targetId: string): this {
+    this.content = { type: "edit", text, targetId };
+    return this;
+  }
+
+  setRevoke(targetId: string, fromMe: boolean): this {
+    this.content = { type: "revoke", targetId, fromMe };
+    return this;
+  }
+
+  build(): Buffer {
+    if (!this.content) throw new Error("Message content not set");
+
+    switch (this.content.type) {
+      case "text":
+        return encodeTextMessage(this.content.text);
+      case "image":
+        return encodeImageMessage(this.content.media);
+      case "video":
+        return encodeVideoMessage(this.content.media);
+      case "audio":
+        return encodeAudioMessage(this.content.media);
+      case "document":
+        return encodeDocumentMessage(this.content.media);
+      case "sticker":
+        return encodeStickerMessage(this.content.media);
+      case "reaction":
+        return encodeReactionMessage(this.content.targetId, this.content.emoji);
+      case "edit":
+        return encodeEditMessage(this.content.targetId, this.content.text);
+      case "revoke":
+        return encodeRevokeMessage(this.content.targetId, this.content.fromMe);
+      default:
+        throw new Error("Unknown content type");
+    }
+  }
+}
+
+/**
+ * Encode a ConsumerApplication text message.
+ * Field 1 = Payload { field 1 = Content { field 1 = MessageText { field 1 = text } } }
+ */
+export function encodeTextMessage(text: string): Buffer {
+  const msgText = encodeMessageText(text);
+  const content = new ProtoWriter().bytes(1, msgText).build(); // oneof content field 1 = messageText
+  const payload = new ProtoWriter().bytes(1, content).build(); // oneof payload field 1 = Content
+  return new ProtoWriter().bytes(1, payload).build(); // ConsumerApplication { payload }
+}
+
+function encodeMessageText(text: string): Buffer {
+  return new ProtoWriter().string(1, text).build();
+}
+
+const MEDIA_TRANSPORT_VERSION = 1;
+
+function encodeMediaSubProtocol(payload: Buffer): Buffer {
+  return new ProtoWriter()
+    .bytes(1, payload)
+    .varint(2, MEDIA_TRANSPORT_VERSION)
+    .build();
+}
+
+function mediaKeyTimestampSeconds(m: MediaFields): bigint {
+  const seconds = m.mediaKeyTimestamp ?? Math.floor(Date.now() / 1000);
+  return BigInt(Math.max(0, Math.trunc(seconds)));
+}
+
+function optionalDimension(value: number | undefined): number | undefined {
+  return value === undefined ? undefined : Math.max(0, Math.trunc(value));
+}
+
+function encodeDownloadableThumbnailMetadata(m: MediaFields): Buffer | undefined {
+  const width = optionalDimension(m.width);
+  const height = optionalDimension(m.height);
+  if (width === undefined && height === undefined) return undefined;
+
+  let thumbnail = new ProtoWriter();
+  if (width !== undefined) thumbnail = thumbnail.varint(3, width);
+  if (height !== undefined) thumbnail = thumbnail.varint(4, height);
+  return thumbnail.build();
+}
+
+/**
+ * Encode WAMediaTransport.WAMediaTransport.
+ *
+ * Modern Messenger media messages no longer carry a flat media payload directly in
+ * ImageMessage/VideoMessage/etc. They carry a WACommon.SubProtocol whose payload
+ * is a concrete media transport (ImageTransport, VideoTransport, ...). Each media
+ * transport then nests this common WAMediaTransport with the encrypted-file
+ * checksums, key, direct path, mimetype, file length and upload object ID.
+ */
+function encodeCommonMediaTransport(m: MediaFields, includeThumbnailMetadata: boolean): Buffer {
+  const integral = new ProtoWriter()
+    .bytes(1, m.fileSHA256)
+    .bytes(2, m.mediaKey)
+    .bytes(3, m.fileEncSHA256)
+    .string(4, m.directPath)
+    .uint64_varint(5, mediaKeyTimestampSeconds(m))
+    .build();
+
+  let ancillary = new ProtoWriter()
+    .uint64_varint(1, BigInt(Math.max(0, Math.trunc(m.fileLength))))
+    .string(2, m.mimeType);
+
+  const thumbnail = includeThumbnailMetadata ? encodeDownloadableThumbnailMetadata(m) : undefined;
+  if (thumbnail) ancillary = ancillary.bytes(3, thumbnail);
+  if (m.objectId) ancillary = ancillary.string(4, m.objectId);
+
+  return new ProtoWriter()
+    .bytes(1, integral)
+    .bytes(2, ancillary.build())
+    .build();
+}
+
+function encodeMediaTransportIntegral(commonTransport: Buffer): Buffer {
+  return new ProtoWriter().bytes(1, commonTransport).build();
+}
+
+function encodeImageTransportPayload(m: MediaFields): Buffer {
+  const width = optionalDimension(m.width);
+  const height = optionalDimension(m.height);
+  const transport = encodeCommonMediaTransport(m, true);
+
+  let ancillary = new ProtoWriter();
+  if (height !== undefined) ancillary = ancillary.varint(1, height);
+  if (width !== undefined) ancillary = ancillary.varint(2, width);
+
+  return new ProtoWriter()
+    .bytes(1, encodeMediaTransportIntegral(transport))
+    .bytes(2, ancillary.build())
+    .build();
+}
+
+function encodeVideoTransportPayload(m: MediaFields): Buffer {
+  const width = optionalDimension(m.width);
+  const height = optionalDimension(m.height);
+  const seconds = optionalDimension(m.seconds);
+  const transport = encodeCommonMediaTransport(m, true);
+
+  let ancillary = new ProtoWriter();
+  if (seconds !== undefined) ancillary = ancillary.varint(1, seconds);
+  // Native Messenger sends gifPlayback explicitly as false for normal videos.
+  ancillary = ancillary.bool(3, false);
+  if (height !== undefined) ancillary = ancillary.varint(4, height);
+  if (width !== undefined) ancillary = ancillary.varint(5, width);
+
+  return new ProtoWriter()
+    .bytes(1, encodeMediaTransportIntegral(transport))
+    .bytes(2, ancillary.build())
+    .build();
+}
+
+function encodeAudioTransportPayload(m: MediaFields): Buffer {
+  const seconds = optionalDimension(m.seconds);
+  const transport = encodeCommonMediaTransport(m, false);
+
+  let ancillary = new ProtoWriter();
+  if (seconds !== undefined) ancillary = ancillary.varint(1, seconds);
+
+  return new ProtoWriter()
+    .bytes(1, encodeMediaTransportIntegral(transport))
+    .bytes(2, ancillary.build())
+    .build();
+}
+
+function encodeDocumentTransportPayload(m: MediaFields): Buffer {
+  const transport = encodeCommonMediaTransport(m, false);
+  return new ProtoWriter()
+    .bytes(1, encodeMediaTransportIntegral(transport))
+    .bytes(2, Buffer.alloc(0))
+    .build();
+}
+
+function encodeStickerTransportPayload(m: MediaFields): Buffer {
+  const width = optionalDimension(m.width);
+  const height = optionalDimension(m.height);
+  const transport = encodeCommonMediaTransport(m, true);
+
+  const integral = new ProtoWriter()
+    .bytes(1, transport)
+    .build();
+
+  let ancillary = new ProtoWriter();
+  if (height !== undefined) ancillary = ancillary.varint(2, height);
+  if (width !== undefined) ancillary = ancillary.varint(3, width);
+
+  return new ProtoWriter()
+    .bytes(1, integral)
+    .bytes(2, ancillary.build())
+    .build();
+}
+
+/** Encode a ConsumerApplication image message. */
+export function encodeImageMessage(m: MediaFields): Buffer {
+  let w = new ProtoWriter().bytes(1, encodeMediaSubProtocol(encodeImageTransportPayload(m)));
+  if (m.caption) w = w.bytes(2, encodeMessageText(m.caption));
+  const content = new ProtoWriter().bytes(2, w.build()).build();
+  const payload = new ProtoWriter().bytes(1, content).build();
+  return new ProtoWriter().bytes(1, payload).build();
+}
+
+/** Encode a ConsumerApplication video message. */
+export function encodeVideoMessage(m: MediaFields): Buffer {
+  let w = new ProtoWriter().bytes(1, encodeMediaSubProtocol(encodeVideoTransportPayload(m)));
+  if (m.caption) w = w.bytes(2, encodeMessageText(m.caption));
+  const content = new ProtoWriter().bytes(9, w.build()).build();
+  const payload = new ProtoWriter().bytes(1, content).build();
+  return new ProtoWriter().bytes(1, payload).build();
+}
+
+/** Encode a ConsumerApplication audio/voice message. */
+export function encodeAudioMessage(m: MediaFields): Buffer {
+  let w = new ProtoWriter().bytes(1, encodeMediaSubProtocol(encodeAudioTransportPayload(m)));
+  if (m.ptt) w = w.bool(2, true);
+  const content = new ProtoWriter().bytes(8, w.build()).build();
+  const payload = new ProtoWriter().bytes(1, content).build();
+  return new ProtoWriter().bytes(1, payload).build();
+}
+
+/** Encode a ConsumerApplication document message. */
+export function encodeDocumentMessage(m: MediaFields): Buffer {
+  let w = new ProtoWriter().bytes(1, encodeMediaSubProtocol(encodeDocumentTransportPayload(m)));
+  if (m.fileName) w = w.string(2, m.fileName);
+  const content = new ProtoWriter().bytes(7, w.build()).build();
+  const payload = new ProtoWriter().bytes(1, content).build();
+  return new ProtoWriter().bytes(1, payload).build();
+}
+
+/** Encode a ConsumerApplication sticker message. */
+export function encodeStickerMessage(m: MediaFields): Buffer {
+  const stickerMsg = new ProtoWriter()
+    .bytes(1, encodeMediaSubProtocol(encodeStickerTransportPayload(m)))
+    .build();
+  const content = new ProtoWriter().bytes(12, stickerMsg).build();
+  const payload = new ProtoWriter().bytes(1, content).build();
+  return new ProtoWriter().bytes(1, payload).build();
+}
+
+export interface MessageKeyOptions {
+  remoteJid?: string;
+  fromMe?: boolean;
+  participant?: string;
+}
+
+export interface ReactionMessageKeyOptions extends MessageKeyOptions {
+  senderTimestampMs?: number;
+}
+
+function encodeMessageKey(messageId: string, keyOpts: MessageKeyOptions = {}): Buffer {
+  let key = new ProtoWriter();
+  if (keyOpts.remoteJid) key = key.string(1, keyOpts.remoteJid);
+  if (typeof keyOpts.fromMe === "boolean") key = key.bool(2, keyOpts.fromMe);
+  key = key.string(3, messageId);
+  if (keyOpts.participant) key = key.string(4, keyOpts.participant);
+  return key.build();
+}
+
+/** Encode a reaction message. */
+export function encodeReactionMessage(targetMessageId: string, emoji: string, keyOpts: ReactionMessageKeyOptions = {}): Buffer {
+  const reaction = new ProtoWriter()
+    .bytes(1, encodeMessageKey(targetMessageId, keyOpts))
+    .string(2, emoji)
+    .uint64_varint(4, BigInt(keyOpts.senderTimestampMs ?? Date.now()))
+    .build();
+  const content = new ProtoWriter().bytes(16, reaction).build();
+  const payload = new ProtoWriter().bytes(1, content).build();
+  return new ProtoWriter().bytes(1, payload).build();
+}
+
+/** Encode a message edit. */
+export function encodeEditMessage(targetMessageId: string, newText: string): Buffer {
+  const key = new ProtoWriter().string(3, targetMessageId).build();
+  const msgText = new ProtoWriter().string(1, newText).build();
+  const edit = new ProtoWriter()
+    .bytes(1, key)
+    .bytes(2, msgText)
+    .uint64_varint(3, BigInt(Date.now()))
+    .build();
+  const content = new ProtoWriter().bytes(19, edit).build();
+  const payload = new ProtoWriter().bytes(1, content).build();
+  return new ProtoWriter().bytes(1, payload).build();
+}
+
+/** Encode a revoke (unsend) message. */
+export function encodeRevokeMessage(messageId: string, keyOptsOrFromMe: MessageKeyOptions | boolean = true): Buffer {
+  const keyOpts = typeof keyOptsOrFromMe === "boolean"
+    ? { fromMe: keyOptsOrFromMe }
+    : keyOptsOrFromMe;
+  const revoke = new ProtoWriter().bytes(1, encodeMessageKey(messageId, keyOpts)).build();
+  const applicationData = new ProtoWriter().bytes(1, revoke).build();
+  const payload = new ProtoWriter().bytes(2, applicationData).build();
+  return new ProtoWriter().bytes(1, payload).build();
+}

package/src/e2ee/message/builders/message-application.ts

@@ -0,0 +1,64 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { FB_CONSUMER_MESSAGE_VERSION } from "../constants.ts";
+import { ProtoWriter } from "../proto/proto-writer.ts";
+
+// MessageApplication encoding
+
+/**
+ * Wrap a ConsumerApplication payload into a MessageApplication.
+ * Returns (messageApp bytes, frankingKey, frankingTag).
+ */
+export function encodeMessageApplication(
+  consumerAppBytes: Buffer,
+  replyTo?: { id: string; senderJid: string }
+): {
+  messageApp: Buffer;
+  frankingKey: Buffer;
+  frankingTag: Buffer;
+} {
+  const frankingKey = randomBytes(32);
+
+  // SubProtocol { payload=consumerAppBytes, version=FB_CONSUMER_MESSAGE_VERSION }
+  const subProtocol = new ProtoWriter()
+    .bytes(1, consumerAppBytes)
+    .varint(2, FB_CONSUMER_MESSAGE_VERSION)
+    .build();
+
+  // MessageApplication.SubProtocolPayload {
+  //   futureProof = PLACEHOLDER (field 1)
+  //   consumerMessage = WACommon.SubProtocol (field 2)
+  // }
+  const payloadSubProto = new ProtoWriter()
+    .varint(1, 0)
+    .bytes(2, subProtocol)
+    .build();
+
+  // MessageApplication.Payload { subProtocol = payloadSubProto } (field 4)
+  const appPayload = new ProtoWriter().bytes(4, payloadSubProto).build();
+
+  // MessageApplication_Metadata { frankingKey=8, frankingVersion=9, quotedMessage=10 }
+  let metadataWriter = new ProtoWriter()
+    .bytes(8, frankingKey)
+    .varint(9, 0); // frankingVersion
+
+  if (replyTo) {
+    const quoted = new ProtoWriter()
+      .string(1, replyTo.id)
+      .string(2, replyTo.senderJid)
+      .build();
+    metadataWriter = metadataWriter.bytes(10, quoted);
+  }
+
+  const metadata = metadataWriter.build();
+
+  // MessageApplication { payload, metadata }
+  const messageApp = new ProtoWriter()
+    .bytes(1, appPayload)
+    .bytes(2, metadata)
+    .build();
+
+  // frankingTag = HMAC-SHA256(frankingKey, messageApp)
+  const frankingTag = createHmac("sha256", frankingKey).update(messageApp).digest();
+
+  return { messageApp, frankingKey, frankingTag };
+}

package/src/e2ee/message/builders/message-transport.ts

@@ -0,0 +1,84 @@
+import { randomBytes } from "node:crypto";
+import type { MessageTransportOptions } from "../../../models/e2ee.ts";
+import { FB_MESSAGE_APPLICATION_VERSION } from "../constants.ts";
+import { ProtoWriter } from "../proto/proto-writer.ts";
+
+export type { MessageTransportOptions };
+
+// MessageTransport encoding (plaintext before Signal encryption)
+
+
+/**
+ * Encode the MessageTransport protobuf that will be fed into Signal cipher.
+ */
+export function encodeMessageTransport(opts: MessageTransportOptions): Buffer {
+  const padding = opts.padding ?? generatePadding();
+
+  let payload: Buffer | undefined;
+  if (opts.messageApp) {
+    // Payload.ApplicationPayload (SubProtocol)
+    const appPayload = new ProtoWriter()
+      .bytes(1, opts.messageApp)
+      .varint(2, FB_MESSAGE_APPLICATION_VERSION)
+      .build();
+
+    // Payload
+    payload = new ProtoWriter()
+      .bytes(1, appPayload)
+      .varint(3, 0) // futureProof PLACEHOLDER
+      .build();
+  }
+
+  // Protocol.Integral
+  let integral = new ProtoWriter().bytes(1, padding);
+  if (opts.dsm) {
+    const dsmMsg = new ProtoWriter()
+      .string(1, opts.dsm.destinationJid)
+      .string(2, opts.dsm.phash)
+      .build();
+    integral = integral.bytes(2, dsmMsg);
+  }
+
+  // Protocol.Ancillary
+  let ancillary = new ProtoWriter();
+  if (opts.skdm) {
+    const skdmMsg = new ProtoWriter()
+      .string(1, opts.skdm.groupId)
+      .bytes(2, opts.skdm.skdmBytes)
+      .build();
+    ancillary = ancillary.bytes(2, skdmMsg);
+  }
+  if (opts.backupDirective) {
+    const actionType = opts.backupDirective.actionType === "REMOVE" ? 2 : 1;
+    const backupDirectiveMsg = new ProtoWriter()
+      .string(1, opts.backupDirective.messageId)
+      .varint(2, actionType)
+      .build();
+    ancillary = ancillary.bytes(5, backupDirectiveMsg);
+  }
+  // Protocol
+  const protocol = new ProtoWriter()
+    .bytes(1, integral.build())
+    .bytes(2, ancillary.build())
+    .build();
+
+  // MessageTransport
+  const transport = new ProtoWriter();
+  if (payload) transport.bytes(1, payload);
+  return transport
+    .bytes(2, protocol)
+    .build();
+}
+
+// Helpers
+
+/**
+ * Generate a random padding buffer.
+ * Uses random length 1–255 and stores the padding length in the final byte.
+ */
+function generatePadding(): Buffer {
+  const len = (randomBytes(1)[0]! & 0xff) || 1;
+  const pad = randomBytes(len);
+  pad[len - 1] = len; // last byte = length (PKCS7-style)
+  return pad;
+}