@vex-chat/libvex 6.6.4 → 6.7.0

package/src/Client.ts

@@ -606,6 +606,8 @@ export interface Message {
     decrypted: boolean;
     /** Whether this message was received or sent by the current client. */
     direction: "incoming" | "outgoing";
+    /** Optional encrypted client metadata attached to this message. */
+    extra?: null | string | undefined;
     /** `true` when this message was forwarded to another owned device. */
     forward: boolean;
     /** Channel ID for group messages; `null` for direct messages. */
@@ -625,7 +627,7 @@ export interface Message {
      * with {@link ClientOptions.localMessageRetentionDays} to pick the
      * shorter local retention window. Ignored when absent.
      */
-    retentionHintDays?: number;
+    retentionHintDays?: number | undefined;
     /** Sender device ID. */
     sender: string;
     /** Time the message was created/received. */
@@ -850,6 +852,7 @@ const messageSchema: z.ZodType<Message> = z.object({
     authorID: z.string(),
     decrypted: z.boolean(),
     direction: z.enum(["incoming", "outgoing"]),
+    extra: z.string().nullable().optional(),
     forward: z.boolean(),
     group: z.string().nullable(),
     mailID: z.string(),
@@ -857,10 +860,94 @@ const messageSchema: z.ZodType<Message> = z.object({
     nonce: z.string(),
     readerID: z.string(),
     recipient: z.string(),
+    retentionHintDays: z.number().optional(),
     sender: z.string(),
     timestamp: z.string(),
 });
 
+const MESSAGE_BLOB_PREFIX = "vex-message:1\n";
+
+interface DecodedMessagePlaintext {
+    extra?: null | string | undefined;
+    message: string;
+    retentionHintDays?: number | undefined;
+}
+
+function decodeMessageBlob(body: string): DecodedMessagePlaintext {
+    if (!body.startsWith(MESSAGE_BLOB_PREFIX)) {
+        return { message: body };
+    }
+
+    try {
+        const raw = JSON.parse(
+            body.slice(MESSAGE_BLOB_PREFIX.length),
+        ) as unknown;
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            return { message: body };
+        }
+        const message = Reflect.get(raw, "message");
+        if (typeof message !== "string") {
+            return { message: body };
+        }
+        const extra = Reflect.get(raw, "extra");
+        return {
+            ...(extra === null || typeof extra === "string" ? { extra } : {}),
+            message,
+        };
+    } catch {
+        return { message: body };
+    }
+}
+
+function decodeMessagePlaintext(plaintext: string): DecodedMessagePlaintext {
+    const stripped = stripVexRetentionEnvelope(plaintext);
+    const blob = decodeMessageBlob(stripped.body);
+    return stripped.retentionHintDays !== undefined
+        ? {
+              ...blob,
+              retentionHintDays: stripped.retentionHintDays,
+          }
+        : blob;
+}
+
+function encodeMessagePlaintext(
+    message: string,
+    opts?: MessageSendOptions,
+): string {
+    const body =
+        opts?.extra === undefined
+            ? message
+            : MESSAGE_BLOB_PREFIX +
+              JSON.stringify({
+                  extra: opts.extra,
+                  message,
+              });
+    return formatVexRetentionEnvelope(body, opts?.retentionHintDays);
+}
+
+function messageFromDecodedPlaintext(
+    decoded: DecodedMessagePlaintext,
+): Pick<Message, "extra" | "message" | "retentionHintDays"> {
+    return {
+        ...(decoded.extra !== undefined ? { extra: decoded.extra } : {}),
+        message: decoded.message,
+        ...(decoded.retentionHintDays !== undefined
+            ? { retentionHintDays: decoded.retentionHintDays }
+            : {}),
+    };
+}
+
+function normalizeForwardedMessage(message: Message): Message {
+    const decoded = decodeMessagePlaintext(message.message);
+    return {
+        ...message,
+        ...messageFromDecodedPlaintext({
+            ...decoded,
+            extra: decoded.extra !== undefined ? decoded.extra : message.extra,
+        }),
+    };
+}
+
 /** Zod schema for a single inbox entry from getMail: [header, mailBody, timestamp]. */
 const mailInboxEntry = z.tuple([
     z.custom<Uint8Array>((val) => val instanceof Uint8Array),
@@ -929,7 +1016,7 @@ export interface Messages {
     group: (
         channelID: string,
         message: string,
-        opts?: { retentionHintDays?: number },
+        opts?: MessageSendOptions,
     ) => Promise<void>;
     /** Deletes all locally stored message history. */
     purge: () => Promise<void>;
@@ -941,10 +1028,17 @@ export interface Messages {
     send: (
         userID: string,
         message: string,
-        opts?: { retentionHintDays?: number },
+        opts?: MessageSendOptions,
     ) => Promise<void>;
 }
 
+export interface MessageSendOptions {
+    /** Optional encrypted client metadata for message-level features. */
+    extra?: null | string | undefined;
+    /** Optional peer hint (1-30 days) for local history retention. */
+    retentionHintDays?: number | undefined;
+}
+
 /**
  * @ignore
  */
@@ -1275,7 +1369,7 @@ export class Client {
         group: (
             channelID: string,
             message: string,
-            opts?: { retentionHintDays?: number },
+            opts?: MessageSendOptions,
         ) => this.sendGroupMessage(channelID, message, opts),
         purge: this.purgeHistory.bind(this),
         /**
@@ -1297,11 +1391,8 @@ export class Client {
          * @param userID - The user to send a message to.
          * @param message - The message to send.
          */
-        send: (
-            userID: string,
-            message: string,
-            opts?: { retentionHintDays?: number },
-        ) => this.sendMessage(userID, message, opts),
+        send: (userID: string, message: string, opts?: MessageSendOptions) =>
+            this.sendMessage(userID, message, opts),
     };
     /**
      * Server moderation helper methods.
@@ -2704,7 +2795,7 @@ export class Client {
                 : null;
             const shouldEmitHandshakeMessage = forward || message.length > 0;
             const emitMsg: Message = forwardedMsg
-                ? { ...forwardedMsg, forward: true }
+                ? { ...normalizeForwardedMessage(forwardedMsg), forward: true }
                 : {
                       authorID: mail.authorID,
                       decrypted: true,
@@ -2712,7 +2803,9 @@ export class Client {
                       forward: mail.forward,
                       group: mail.group ? uuid.stringify(mail.group) : null,
                       mailID: mail.mailID,
-                      message: XUtils.encodeUTF8(message),
+                      ...messageFromDecodedPlaintext(
+                          decodeMessagePlaintext(XUtils.encodeUTF8(message)),
+                      ),
                       nonce: XUtils.encodeHex(new Uint8Array(mail.nonce)),
                       readerID: mail.readerID,
                       recipient: mail.recipient,
@@ -4098,39 +4191,19 @@ export class Client {
                             if (!mail.forward) {
                                 plaintext = XUtils.encodeUTF8(unsealed);
                             }
-                            let incomingPlain = plaintext;
-                            let hintFromEnvelope: number | undefined;
-                            if (!mail.forward && plaintext.length > 0) {
-                                const stripped =
-                                    stripVexRetentionEnvelope(plaintext);
-                                incomingPlain = stripped.body;
-                                hintFromEnvelope = stripped.retentionHintDays;
-                            }
+                            const decodedPlaintext = mail.forward
+                                ? null
+                                : decodeMessagePlaintext(plaintext);
 
                             // emit the message
                             const fwdMsg1 = mail.forward
                                 ? messageSchema.parse(msgpack.decode(unsealed))
                                 : null;
                             const message: Message = fwdMsg1
-                                ? (() => {
-                                      const stripped =
-                                          stripVexRetentionEnvelope(
-                                              fwdMsg1.message,
-                                          );
-                                      const base: Message = {
-                                          ...fwdMsg1,
-                                          forward: true,
-                                          message: stripped.body,
-                                      };
-                                      return stripped.retentionHintDays !==
-                                          undefined
-                                          ? {
-                                                ...base,
-                                                retentionHintDays:
-                                                    stripped.retentionHintDays,
-                                            }
-                                          : base;
-                                  })()
+                                ? {
+                                      ...normalizeForwardedMessage(fwdMsg1),
+                                      forward: true,
+                                  }
                                 : {
                                       authorID: mail.authorID,
                                       decrypted: true,
@@ -4140,18 +4213,16 @@ export class Client {
                                           ? uuid.stringify(mail.group)
                                           : null,
                                       mailID: mail.mailID,
-                                      message: incomingPlain,
+                                      ...messageFromDecodedPlaintext(
+                                          decodedPlaintext ?? {
+                                              message: plaintext,
+                                          },
+                                      ),
                                       nonce: XUtils.encodeHex(
                                           new Uint8Array(mail.nonce),
                                       ),
                                       readerID: mail.readerID,
                                       recipient: mail.recipient,
-                                      ...(hintFromEnvelope !== undefined
-                                          ? {
-                                                retentionHintDays:
-                                                    hintFromEnvelope,
-                                            }
-                                          : {}),
                                       sender: mail.sender,
                                       timestamp: timestamp,
                                   };
@@ -4391,34 +4462,14 @@ export class Client {
                                 ? messageSchema.parse(msgpack.decode(decrypted))
                                 : null;
                             const rawIncoming = XUtils.encodeUTF8(decrypted);
-                            let bodyIncoming = rawIncoming;
-                            let hintIncoming: number | undefined;
-                            if (!mail.forward) {
-                                const stripped =
-                                    stripVexRetentionEnvelope(rawIncoming);
-                                bodyIncoming = stripped.body;
-                                hintIncoming = stripped.retentionHintDays;
-                            }
+                            const decodedPlaintext = mail.forward
+                                ? null
+                                : decodeMessagePlaintext(rawIncoming);
                             const message: Message = fwdMsg2
-                                ? (() => {
-                                      const stripped =
-                                          stripVexRetentionEnvelope(
-                                              fwdMsg2.message,
-                                          );
-                                      const base: Message = {
-                                          ...fwdMsg2,
-                                          forward: true,
-                                          message: stripped.body,
-                                      };
-                                      return stripped.retentionHintDays !==
-                                          undefined
-                                          ? {
-                                                ...base,
-                                                retentionHintDays:
-                                                    stripped.retentionHintDays,
-                                            }
-                                          : base;
-                                  })()
+                                ? {
+                                      ...normalizeForwardedMessage(fwdMsg2),
+                                      forward: true,
+                                  }
                                 : {
                                       authorID: mail.authorID,
                                       decrypted: true,
@@ -4428,15 +4479,16 @@ export class Client {
                                           ? uuid.stringify(mail.group)
                                           : null,
                                       mailID: mail.mailID,
-                                      message: bodyIncoming,
+                                      ...messageFromDecodedPlaintext(
+                                          decodedPlaintext ?? {
+                                              message: rawIncoming,
+                                          },
+                                      ),
                                       nonce: XUtils.encodeHex(
                                           new Uint8Array(mail.nonce),
                                       ),
                                       readerID: mail.readerID,
                                       recipient: mail.recipient,
-                                      ...(hintIncoming !== undefined
-                                          ? { retentionHintDays: hintIncoming }
-                                          : {}),
                                       sender: mail.sender,
                                       timestamp: timestamp,
                                   };
@@ -4848,7 +4900,7 @@ export class Client {
     private async sendGroupMessage(
         channelID: string,
         message: string,
-        opts?: { retentionHintDays?: number },
+        opts?: MessageSendOptions,
     ): Promise<void> {
         const userList = await this.getUserList(channelID);
         for (const user of userList) {
@@ -4856,10 +4908,7 @@ export class Client {
         }
 
         const mailID = uuid.v4();
-        const payload = formatVexRetentionEnvelope(
-            message,
-            opts?.retentionHintDays,
-        );
+        const payload = encodeMessagePlaintext(message, opts);
         const msgBytes = XUtils.decodeUTF8(payload);
         const myUserID = this.getUser().userID;
         const peerUserIDs = [...new Set(userList.map((u) => u.userID))].filter(
@@ -4890,6 +4939,7 @@ export class Client {
         if (targetDevices.size === 0) {
             const dev = this.getDevice();
             const nonce = xMakeNonce();
+            const decodedPlaintext = decodeMessagePlaintext(payload);
             this.emitter.emit("message", {
                 authorID: myUserID,
                 decrypted: true,
@@ -4897,7 +4947,7 @@ export class Client {
                 forward: false,
                 group: channelID,
                 mailID,
-                message,
+                ...messageFromDecodedPlaintext(decodedPlaintext),
                 nonce: XUtils.encodeHex(nonce),
                 readerID: myUserID,
                 recipient: dev.deviceID,
@@ -5043,25 +5093,8 @@ export class Client {
             const fwdOut = forward
                 ? messageSchema.parse(msgpack.decode(msg))
                 : null;
-            const rawUtf8 = XUtils.encodeUTF8(msg);
-            const strippedOut = stripVexRetentionEnvelope(rawUtf8);
             const outMsg: Message = fwdOut
-                ? (() => {
-                      const stripped = stripVexRetentionEnvelope(
-                          fwdOut.message,
-                      );
-                      const base: Message = {
-                          ...fwdOut,
-                          forward: true,
-                          message: stripped.body,
-                      };
-                      return stripped.retentionHintDays !== undefined
-                          ? {
-                                ...base,
-                                retentionHintDays: stripped.retentionHintDays,
-                            }
-                          : base;
-                  })()
+                ? { ...normalizeForwardedMessage(fwdOut), forward: true }
                 : {
                       authorID: mail.authorID,
                       decrypted: true,
@@ -5069,16 +5102,12 @@ export class Client {
                       forward: mail.forward,
                       group: mail.group ? uuid.stringify(mail.group) : null,
                       mailID: mail.mailID,
-                      message: strippedOut.body,
+                      ...messageFromDecodedPlaintext(
+                          decodeMessagePlaintext(XUtils.encodeUTF8(msg)),
+                      ),
                       nonce: XUtils.encodeHex(new Uint8Array(mail.nonce)),
                       readerID: mail.readerID,
                       recipient: mail.recipient,
-                      ...(strippedOut.retentionHintDays !== undefined
-                          ? {
-                                retentionHintDays:
-                                    strippedOut.retentionHintDays,
-                            }
-                          : {}),
                       sender: mail.sender,
                       timestamp: new Date().toISOString(),
                   };
@@ -5172,12 +5201,9 @@ export class Client {
     private async sendMessage(
         userID: string,
         message: string,
-        opts?: { retentionHintDays?: number },
+        opts?: MessageSendOptions,
     ): Promise<void> {
-        const payload = formatVexRetentionEnvelope(
-            message,
-            opts?.retentionHintDays,
-        );
+        const payload = encodeMessagePlaintext(message, opts);
         try {
             const [userEntry, err] = await this.fetchUser(userID);
             if (err) {

package/src/__tests__/harness/shared-suite.ts

@@ -91,6 +91,32 @@ export function platformSuite(
             expect(msg.message).toBe("platform-test");
         });
 
+        test("send and receive DM with encrypted extra", async () => {
+            const me = client.me.user();
+            const extra = JSON.stringify({
+                reactionEvent: {
+                    action: "toggle",
+                    emoji: { kind: "unicode", value: "👍" },
+                    targetMailID: "mail-target",
+                },
+                version: 1,
+            });
+            const msgPromise = waitForMessage(
+                client,
+                (m) =>
+                    m.direction === "incoming" &&
+                    m.decrypted &&
+                    m.extra === extra,
+                `[${platformName}] self-DM extra`,
+            );
+
+            await client.messages.send(me.userID, "", { extra });
+            const msg = await msgPromise;
+
+            expect(msg.message).toBe("");
+            expect(msg.extra).toBe(extra);
+        });
+
         test("message history retrieve + delete", async () => {
             const me = client.me.user();
             const body = "history-test";
@@ -265,6 +291,14 @@ export function platformSuite(
                 );
 
                 // user1 sends group message, user2 receives it
+                const extra = JSON.stringify({
+                    reactionEvent: {
+                        action: "toggle",
+                        emoji: { kind: "unicode", value: "🎉" },
+                        targetMailID: "group-mail-target",
+                    },
+                    version: 1,
+                });
                 const msgPromise = waitForMessage(
                     client2,
                     (m) =>
@@ -275,10 +309,13 @@ export function platformSuite(
                     15_000,
                 );
                 await withTransientRetry(() =>
-                    client.messages.group(channel.channelID, "hello channel"),
+                    client.messages.group(channel.channelID, "hello channel", {
+                        extra,
+                    }),
                 );
                 const msg = await msgPromise;
                 expect(msg.message).toBe("hello channel");
+                expect(msg.extra).toBe(extra);
 
                 // Cleanup
                 await client.servers.delete(server.serverID);

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
     Me,
     Message,
     Messages,
+    MessageSendOptions,
     Moderation,
     NotificationSubscription,
     NotificationSubscriptionInput,

package/src/storage/schema.ts

@@ -58,6 +58,7 @@ interface MessagesTable {
     authorID: string;
     decrypted: number;
     direction: string;
+    extra: null | string;
     forward: number;
     group: null | string;
     mailID: string;

package/src/storage/sqlite.ts

@@ -54,6 +54,8 @@ import { type Kysely, sql } from "kysely";
 import { effectiveMessageRetentionHintDays } from "../retention.js";
 import { parseSkippedKeysStrict } from "../utils/ratchet.js";
 
+const STORAGE_MESSAGE_BLOB_PREFIX = "vex-storage-message:1\n";
+
 export class SqliteStorage extends EventEmitter implements Storage {
     public ready = false;
     /** 32-byte AES-256 (or nacl) key for local at-rest `secretbox` (see `XUtils.deriveLocalAtRestAesKey`). */
@@ -323,6 +325,7 @@ export class SqliteStorage extends EventEmitter implements Storage {
                     .addColumn("sender", "text")
                     .addColumn("recipient", "text")
                     .addColumn("group", "text")
+                    .addColumn("extra", "text")
                     .addColumn("mailID", "text")
                     .addColumn("message", "text")
                     .addColumn("direction", "text")
@@ -370,6 +373,7 @@ export class SqliteStorage extends EventEmitter implements Storage {
                     )
                     .execute();
                 await this.ensureSessionRatchetColumns();
+                await this.ensureMessageExtraColumn();
                 await this.ensureRetentionHintColumn();
                 await this.ensureMessageMailIdIndex();
 
@@ -534,16 +538,17 @@ export class SqliteStorage extends EventEmitter implements Storage {
             return;
         }
 
-        // Encrypt plaintext with at-rest key before saving to disk
+        // Encrypt plaintext with at-rest key before saving to disk.
+        const storedPlaintext = encodeStoredMessagePlaintext(message);
         const fips = getCryptoProfile() === "fips";
         const ct = fips
             ? await xSecretboxAsync(
-                  XUtils.decodeUTF8(message.message),
+                  XUtils.decodeUTF8(storedPlaintext),
                   XUtils.decodeHex(message.nonce),
                   this.atRestAesKey,
               )
             : xSecretbox(
-                  XUtils.decodeUTF8(message.message),
+                  XUtils.decodeUTF8(storedPlaintext),
                   XUtils.decodeHex(message.nonce),
                   this.atRestAesKey,
               );
@@ -559,6 +564,7 @@ export class SqliteStorage extends EventEmitter implements Storage {
                     authorID: message.authorID,
                     decrypted: message.decrypted ? 1 : 0,
                     direction: message.direction,
+                    extra: null,
                     forward: message.forward ? 1 : 0,
                     group: message.group ?? null,
                     mailID: message.mailID,
@@ -733,6 +739,10 @@ export class SqliteStorage extends EventEmitter implements Storage {
             }
             const direction =
                 msg.direction === "incoming" ? "incoming" : "outgoing";
+            const storedPlaintext = decodeStoredMessagePlaintext(
+                plaintext,
+                msg.extra,
+            );
             const rowMessage: Message = {
                 authorID: msg.authorID,
                 decrypted: decryptedFlag,
@@ -740,7 +750,7 @@ export class SqliteStorage extends EventEmitter implements Storage {
                 forward: msg.forward !== 0,
                 group: msg.group,
                 mailID: msg.mailID,
-                message: plaintext,
+                ...storedPlaintext,
                 nonce: msg.nonce,
                 readerID: msg.readerID,
                 recipient: msg.recipient,
@@ -773,6 +783,16 @@ export class SqliteStorage extends EventEmitter implements Storage {
         };
     }
 
+    private async ensureMessageExtraColumn(): Promise<void> {
+        try {
+            await sql
+                .raw("ALTER TABLE messages ADD COLUMN extra text")
+                .execute(this.db);
+        } catch {
+            // Existing databases may already have this column.
+        }
+    }
+
     /** Speeds up mailID existence checks for saveMessage deduplication. */
     private async ensureMessageMailIdIndex(): Promise<void> {
         try {
@@ -965,3 +985,61 @@ export class SqliteStorage extends EventEmitter implements Storage {
         });
     }
 }
+
+function decodeStoredMessagePlaintext(
+    plaintext: string,
+    rowExtra: null | string,
+): Pick<Message, "extra" | "message"> {
+    if (!plaintext.startsWith(STORAGE_MESSAGE_BLOB_PREFIX)) {
+        return {
+            ...(rowExtra !== null ? { extra: rowExtra } : {}),
+            message: plaintext,
+        };
+    }
+
+    try {
+        const raw = JSON.parse(
+            plaintext.slice(STORAGE_MESSAGE_BLOB_PREFIX.length),
+        ) as unknown;
+        if (!isJsonRecord(raw)) {
+            return {
+                ...(rowExtra !== null ? { extra: rowExtra } : {}),
+                message: plaintext,
+            };
+        }
+        const message = raw["message"];
+        if (typeof message !== "string") {
+            return {
+                ...(rowExtra !== null ? { extra: rowExtra } : {}),
+                message: plaintext,
+            };
+        }
+        const extra = raw["extra"];
+        return {
+            ...(extra === null || typeof extra === "string" ? { extra } : {}),
+            message,
+        };
+    } catch {
+        return {
+            ...(rowExtra !== null ? { extra: rowExtra } : {}),
+            message: plaintext,
+        };
+    }
+}
+
+function encodeStoredMessagePlaintext(message: Message): string {
+    if (message.extra === undefined) {
+        return message.message;
+    }
+    return (
+        STORAGE_MESSAGE_BLOB_PREFIX +
+        JSON.stringify({
+            extra: message.extra,
+            message: message.message,
+        })
+    );
+}
+
+function isJsonRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}