@gryt/core 0.10.0 → 0.12.0

package/README.md

@@ -51,8 +51,13 @@ goes missing **and** when one appears that nobody listed.
   topped up, opens a DM group, joins from a Welcome, sends, and reads the group
   log in order. Each app hands it the socket, the storage and the pins through
   the interfaces in `src/mls/interfaces.ts`. `mlsPinsFromPeerPins` builds the
-  pins from the peer pins `@gryt/crypto` already keeps. It's the one module with
-  a dependency, `@gryt/crypto`, pinned exactly the way the apps pin it.
+  pins from the peer pins `@gryt/crypto` already keeps.
+  `encodeMlsDmContent` and `decodeMlsDmContent` write and read what goes inside
+  each message, so both apps use the same JSON: a message, an edit, a delete or
+  a reaction. `readMlsDmContent` also says when something came from a newer app,
+  so it can be skipped quietly rather than counted as broken. `applyMlsReaction` puts a reaction on a message in the archive,
+  since the server never sees one. It's the one module with a
+  dependency, `@gryt/crypto`, pinned exactly the way the apps pin it.
 
 ## What deliberately isn't
 

package/dist/index.d.ts

@@ -12,4 +12,6 @@ export { describeFolderRules, folderFollowNote, folderPhrase, } from "./permissi
 export { agreementAt, createTermsGate, GUIDELINES_URL, TERMS_STORAGE_KEY, TERMS_URL, TERMS_VERSION, } from "./terms/termsAgreement.js";
 export { createMlsDmDriver, MlsDriverError, type MlsDriverErrorCode } from "./mls/dmDriver.js";
 export { mlsPinsFromPeerPins } from "./mls/pins.js";
+export { decodeMlsDmContent, encodeMlsDmContent, MLS_DM_CONTENT_VERSION, type MlsDmContent, readMlsDmContent, } from "./mls/content.js";
+export { applyMlsReaction, mlsReactionAction, type MlsReaction } from "./mls/reactions.js";
 export type { DmSealingMode, MlsClaimedKeyPackage, MlsDecryptedMessage, MlsDeviceRecord, MlsDeviceRef, MlsDmDriver, MlsDmDriverOptions, MlsDmEvents, MlsGroupRecord, MlsGroupView, MlsKeyPackageRecord, MlsLogEntry, MlsPins, MlsRefusal, MlsReply, MlsServerCapability, MlsStateStore, MlsTransport, MlsWelcomeDelivery, } from "./mls/interfaces.js";

package/dist/index.js

@@ -14,3 +14,5 @@ export { describeFolderRules, folderFollowNote, folderPhrase, } from "./permissi
 export { agreementAt, createTermsGate, GUIDELINES_URL, TERMS_STORAGE_KEY, TERMS_URL, TERMS_VERSION, } from "./terms/termsAgreement.js";
 export { createMlsDmDriver, MlsDriverError } from "./mls/dmDriver.js";
 export { mlsPinsFromPeerPins } from "./mls/pins.js";
+export { decodeMlsDmContent, encodeMlsDmContent, MLS_DM_CONTENT_VERSION, readMlsDmContent, } from "./mls/content.js";
+export { applyMlsReaction, mlsReactionAction } from "./mls/reactions.js";

package/dist/mls/content.d.ts

@@ -0,0 +1,35 @@
+import { type SealedAttachmentKey } from "@gryt/crypto";
+export type MlsDmContent = {
+    type: "message";
+    /** Made by the sender, a UUID. Edits and deletes name it. */
+    id: string;
+    text: string;
+    replyTo?: string;
+    /** Upload id to what `sealAttachment` returned; `openAttachment` takes it as `meta`. */
+    attachments?: Record<string, SealedAttachmentKey>;
+} | {
+    type: "edit";
+    id: string;
+    text: string;
+} | {
+    type: "delete";
+    id: string;
+} | {
+    type: "reaction";
+    /** The message reacted to, the way edits and deletes name theirs. */
+    id: string;
+    /** A Unicode emoji, or a server emoji as `:name:`, the same string `chat:react` carries. */
+    emoji: string;
+    /** Explicit rather than a toggle, so a repeat or a reorder lands the same on every device. */
+    action: "add" | "remove";
+};
+export declare const MLS_DM_CONTENT_VERSION = 1;
+/** The same bytes the phone writes: `v` first, then the content's fields in this order. */
+export declare function encodeMlsDmContent(content: MlsDmContent): Uint8Array;
+/** Null for anything this version can't read: a newer version, a new type, or junk. */
+export declare function decodeMlsDmContent(bytes: Uint8Array): MlsDmContent | null;
+/**
+ * Like `decodeMlsDmContent`, but tells content from a newer app ("newer", skip it quietly)
+ * apart from junk (null, which is worth counting). A known type with a bad field is junk.
+ */
+export declare function readMlsDmContent(bytes: Uint8Array): MlsDmContent | "newer" | null;

package/dist/mls/content.js

@@ -0,0 +1,160 @@
+import { base64UrlDecode } from "@gryt/crypto";
+export const MLS_DM_CONTENT_VERSION = 1;
+const MAX_ID = 64;
+/** Well past the composer's limit, and under what one `mls:send` can carry. */
+const MAX_TEXT = 32_000;
+const MAX_ATTACHMENTS = 10;
+const MAX_LABEL = 255;
+const UPLOAD_ID = /^[A-Za-z0-9_-]{1,128}$/;
+/** The server's own rule for an emoji's name, in `emojiShared.ts`. */
+const CUSTOM_EMOJI = /^:[A-Za-z0-9_]{2,32}:$/;
+/** The longest RGI emoji, a kiss with two skin tones, is ten code points. */
+const MAX_EMOJI_CODE_POINTS = 12;
+const EMOJI_PART = /^(?:\p{Extended_Pictographic}|\p{Emoji_Component}|\uFE0E)$/u;
+const EMOJI_BASE = /^(?:\p{Extended_Pictographic}|\p{Regional_Indicator}|\u20E3)$/u;
+const isId = (v) => typeof v === "string" && v.length > 0 && v.length <= MAX_ID;
+const isText = (v) => typeof v === "string" && v.length <= MAX_TEXT;
+const isCount = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const isLabel = (v) => typeof v === "string" && v.length <= MAX_LABEL;
+/** One emoji's worth of emoji characters, so a peer can't put a sentence on a message as a reaction. */
+function isReactionEmoji(v) {
+    if (typeof v !== "string")
+        return false;
+    if (CUSTOM_EMOJI.test(v))
+        return true;
+    const points = Array.from(v);
+    if (points.length === 0 || points.length > MAX_EMOJI_CODE_POINTS)
+        return false;
+    return points.every((p) => EMOJI_PART.test(p)) && points.some((p) => EMOJI_BASE.test(p));
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function decodesTo(v, bytes) {
+    if (typeof v !== "string")
+        return false;
+    try {
+        return base64UrlDecode(v).length === bytes;
+    }
+    catch {
+        return false;
+    }
+}
+/** Only the fields a reader uses, each checked; null for anything off. */
+function readAttachmentKey(v) {
+    if (!isObject(v) || !isId(v.id) || !decodesTo(v.key, 32) || !decodesTo(v.iv, 12))
+        return null;
+    const out = { id: v.id, key: v.key, iv: v.iv };
+    for (const field of ["name", "mime"]) {
+        if (v[field] === undefined)
+            continue;
+        if (!isLabel(v[field]))
+            return null;
+        out[field] = v[field];
+    }
+    for (const field of ["size", "width", "height"]) {
+        if (v[field] === undefined)
+            continue;
+        if (!isCount(v[field]))
+            return null;
+        out[field] = v[field];
+    }
+    return out;
+}
+function readAttachments(v) {
+    if (!isObject(v))
+        return null;
+    const entries = Object.entries(v);
+    if (entries.length === 0 || entries.length > MAX_ATTACHMENTS)
+        return null;
+    const out = {};
+    for (const [uploadId, meta] of entries) {
+        const key = readAttachmentKey(meta);
+        if (!UPLOAD_ID.test(uploadId) || !key)
+            return null;
+        out[uploadId] = key;
+    }
+    return out;
+}
+/** The same bytes the phone writes: `v` first, then the content's fields in this order. */
+export function encodeMlsDmContent(content) {
+    let body;
+    if (content.type === "message") {
+        body = { type: content.type, id: content.id, text: content.text };
+        if (content.replyTo !== undefined)
+            body.replyTo = content.replyTo;
+        if (content.attachments && Object.keys(content.attachments).length > 0)
+            body.attachments = content.attachments;
+    }
+    else if (content.type === "edit") {
+        body = { type: content.type, id: content.id, text: content.text };
+    }
+    else if (content.type === "reaction") {
+        body = { type: content.type, id: content.id, emoji: content.emoji, action: content.action };
+    }
+    else {
+        body = { type: content.type, id: content.id };
+    }
+    const bytes = new TextEncoder().encode(JSON.stringify({ v: MLS_DM_CONTENT_VERSION, ...body }));
+    if (!decodeMlsDmContent(bytes))
+        throw new Error("That content wouldn't read back, so it isn't sent.");
+    return bytes;
+}
+/** Null for anything this version can't read: a newer version, a new type, or junk. */
+export function decodeMlsDmContent(bytes) {
+    return fromRaw(parse(bytes));
+}
+/**
+ * Like `decodeMlsDmContent`, but tells content from a newer app ("newer", skip it quietly)
+ * apart from junk (null, which is worth counting). A known type with a bad field is junk.
+ */
+export function readMlsDmContent(bytes) {
+    const raw = parse(bytes);
+    return fromRaw(raw) ?? (isNewer(raw) ? "newer" : null);
+}
+const KNOWN_TYPES = new Set(["message", "edit", "delete", "reaction"]);
+const TYPE_NAME = /^[a-z][a-z0-9_]{0,31}$/;
+/** A later version, or a type this one doesn't know that names its message the way ours do. */
+function isNewer(raw) {
+    if (!isObject(raw) || typeof raw.type !== "string" || !TYPE_NAME.test(raw.type))
+        return false;
+    if (raw.v === MLS_DM_CONTENT_VERSION)
+        return !KNOWN_TYPES.has(raw.type) && isId(raw.id);
+    return typeof raw.v === "number" && Number.isSafeInteger(raw.v) && raw.v > MLS_DM_CONTENT_VERSION;
+}
+function parse(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return null;
+    }
+}
+function fromRaw(raw) {
+    if (!isObject(raw) || raw.v !== MLS_DM_CONTENT_VERSION || !isId(raw.id))
+        return null;
+    const { type, id, text } = raw;
+    if (type === "message" && isText(text)) {
+        const out = { type, id, text };
+        if (raw.replyTo !== undefined) {
+            if (!isId(raw.replyTo))
+                return null;
+            out.replyTo = raw.replyTo;
+        }
+        if (raw.attachments !== undefined) {
+            const attachments = readAttachments(raw.attachments);
+            if (!attachments)
+                return null;
+            out.attachments = attachments;
+        }
+        return out;
+    }
+    if (type === "edit" && isText(text))
+        return { type, id, text };
+    if (type === "delete")
+        return { type, id };
+    if (type === "reaction" && isReactionEmoji(raw.emoji) && (raw.action === "add" || raw.action === "remove")) {
+        return { type, id, emoji: raw.emoji, action: raw.action };
+    }
+    return null;
+}

package/dist/mls/dmDriver.d.ts

@@ -1,5 +1,5 @@
 import type { MlsDmDriver, MlsDmDriverOptions, MlsRefusal } from "./interfaces.js";
-export type MlsDriverErrorCode = "refused" | "no_device" | "waiting_for_welcome" | "not_in_group" | "unexpected_member" | "peer_unverified" | "commit_retries";
+export type MlsDriverErrorCode = "refused" | "no_device" | "waiting_for_welcome" | "not_in_group" | "unexpected_member" | "peer_unverified" | "too_many_attachments" | "commit_retries";
 export declare class MlsDriverError extends Error {
     code: MlsDriverErrorCode;
     /** The server's refusal, when there was one. */

package/dist/mls/dmDriver.js

@@ -2,7 +2,12 @@ import { addMlsMembers, asIdentityScope, base64UrlDecode, createMlsGroup, decode
 /** Five devices per person per server (design, section 1). The server holds the same line. */
 const MLS_MAX_DEVICES_PER_PERSON = 5;
 const COMMIT_ATTEMPTS = 5;
-const LOG_PAGE = 200;
+/** socket.io closes the connection on a packet with more than 10 binary parts (GRYT-1522). */
+const MAX_BINARY_PARTS = 10;
+const LOG_PAGE = MAX_BINARY_PARTS;
+const PUBLISH_BATCH = MAX_BINARY_PARTS - 1;
+/** The server's cap on files in one message. */
+const MAX_ATTACHMENT_IDS = 10;
 const WELCOME_WAIT_MS = 10_000;
 /** The server keeps Welcomes 30 days; a last-resort package is replaced with a week to go. */
 const WELCOME_KEEP_S = 30 * 86_400;
@@ -131,14 +136,20 @@ export function createMlsDmDriver(options) {
         const last = needLastResort ? await make(true) : undefined;
         // The private halves are stored first, so a Welcome can never name one this device lost.
         await store.putKeyPackages(last ? [...fresh, last] : fresh);
-        const r = await transport.publishKeyPackages({
-            deviceId: d.deviceId,
-            keyPackages: fresh.map((k) => k.keyPackage),
-            lastResort: last?.keyPackage,
-        });
-        if (!r.ok)
-            throw refused("Publishing KeyPackages", r);
-        registered = true;
+        // Nine at a time, and the last-resort one rides with the last batch.
+        const all = fresh.map((k) => k.keyPackage);
+        for (let i = 0; i === 0 || i < all.length; i += PUBLISH_BATCH) {
+            const keyPackages = all.slice(i, i + PUBLISH_BATCH);
+            const final = i + PUBLISH_BATCH >= all.length;
+            const r = await transport.publishKeyPackages({
+                deviceId: d.deviceId,
+                keyPackages,
+                lastResort: final ? last?.keyPackage : undefined,
+            });
+            if (!r.ok)
+                throw refused("Publishing KeyPackages", r);
+            registered = true;
+        }
     }
     async function syncAndTopUp(forceLastResort = false) {
         const d = await ownDevice();
@@ -411,8 +422,7 @@ export function createMlsDmDriver(options) {
     async function ensureOpen(conversationId) {
         if ((await run(conversationId, () => openGroup(conversationId))) === "open")
             return;
-        for (const w of await syncAndTopUp())
-            await handleWelcome(w);
+        await takeWaitingWelcomes();
         if (!(await store.loadGroup(conversationId)))
             await waitForWelcome(conversationId);
     }
@@ -457,27 +467,56 @@ export function createMlsDmDriver(options) {
         await catchUp(open);
         return { result: "joined", usedLastResort: kp.lastResort };
     }
-    async function handleWelcome(w) {
+    /** "retry" when it's kept for later, else whether it used a last-resort package. */
+    async function takeWelcome(w) {
         const d = await ownDevice();
         if (w.deviceId !== d.deviceId || !w.conversationId)
-            return;
+            return "retry";
         const conversationId = w.conversationId;
         const { result, usedLastResort } = await run(conversationId, () => joinFrom(w));
         if (result === "retry")
-            return;
+            return "retry";
         await transport.ackWelcomes({ deviceId: d.deviceId, welcomeIds: [w.welcomeId] });
         if (result !== "joined")
-            return;
+            return "done";
         reconciled.delete(conversationId);
         events.onJoined?.({ conversationId, groupId: w.groupId });
         for (const done of welcomeWaiters.get(conversationId) ?? [])
             done();
         welcomeWaiters.delete(conversationId);
+        return usedLastResort ? "used_last_resort" : "done";
+    }
+    async function handleWelcome(w) {
         // One package was used up, and a used last-resort one gets replaced.
-        await syncAndTopUp(usedLastResort);
+        const outcome = await takeWelcome(w);
+        if (outcome !== "retry")
+            await syncAndTopUp(outcome === "used_last_resort");
+    }
+    /* Sync until nothing waiting can be acted on: a server may hand out ten Welcomes a time,
+       and each one taken is acked, so the next sync brings the rest (GRYT-1528). */
+    async function takeWaitingWelcomes() {
+        let lastResortUsed = false;
+        for (let round = 0; round < 20; round++) {
+            const welcomes = await syncAndTopUp(lastResortUsed);
+            lastResortUsed = false;
+            let taken = 0;
+            for (const w of welcomes) {
+                const outcome = await takeWelcome(w);
+                if (outcome !== "retry")
+                    taken += 1;
+                if (outcome === "used_last_resort")
+                    lastResortUsed = true;
+            }
+            if (taken === 0)
+                return;
+        }
     }
     // ── What the app calls ──────────────────────────────────────────────
-    async function send(conversationId, peer, plaintext) {
+    async function send(conversationId, peer, plaintext, options = {}) {
+        const attachmentIds = options.attachmentIds?.length ? [...options.attachmentIds] : undefined;
+        if (attachmentIds && attachmentIds.length > MAX_ATTACHMENT_IDS) {
+            throw new MlsDriverError("too_many_attachments", `At most ${MAX_ATTACHMENT_IDS} files go with one message.`);
+        }
         if (!registered)
             throw new MlsDriverError("no_device", "This device isn't registered for MLS here. Call start() first.");
         await ensureOpen(conversationId);
@@ -500,7 +539,7 @@ export function createMlsDmDriver(options) {
             open.state = out.state;
             // The generation is used up whether or not the send arrives, so the state is saved first.
             await save(open);
-            const r = await transport.send({ conversationId, deviceId: d.deviceId, message: out.message });
+            const r = await transport.send({ conversationId, deviceId: d.deviceId, message: out.message, attachmentIds });
             if (!r.ok)
                 throw refused("Sending", r);
             return { seq: r.seq };
@@ -559,8 +598,7 @@ export function createMlsDmDriver(options) {
             await ownDevice();
             if (!capability)
                 return;
-            for (const w of await syncAndTopUp())
-                await handleWelcome(w);
+            await takeWaitingWelcomes();
             reconciled.clear();
             for (const rec of await store.listGroups()) {
                 await run(rec.conversationId, async () => {

package/dist/mls/interfaces.d.ts

@@ -93,10 +93,12 @@ export interface MlsTransport {
         seq: number;
         epoch: number;
     }>>;
+    /** `attachmentIds` are the uploads the message carries, so the server can tie them to it. */
     send(req: {
         conversationId: string;
         deviceId: string;
         message: Uint8Array;
+        attachmentIds?: string[];
     }): Promise<MlsReply<{
         seq: number;
     }>>;
@@ -260,7 +262,9 @@ export interface MlsDmDriver {
     start(): Promise<void>;
     modeFor(conversationId: string, peerServerUserId: string): Promise<DmSealingMode>;
     /** Opens the group if need be, adds or removes devices that changed, then sends. */
-    send(conversationId: string, peerServerUserId: string, plaintext: Uint8Array): Promise<{
+    send(conversationId: string, peerServerUserId: string, plaintext: Uint8Array, options?: {
+        attachmentIds?: readonly string[];
+    }): Promise<{
         seq: number;
     }>;
     handleMessage(entry: MlsLogEntry): Promise<void>;

package/dist/mls/reactions.d.ts

@@ -0,0 +1,13 @@
+export interface MlsReaction {
+    src: string;
+    amount: number;
+    users: string[];
+}
+/** Adding twice or removing what isn't there changes nothing, so replays and reorders are safe. */
+export declare function applyMlsReaction(reactions: readonly MlsReaction[] | null | undefined, change: {
+    emoji: string;
+    userId: string;
+    action: "add" | "remove";
+}): MlsReaction[];
+/** What a tap on a reaction chip means for this person: take theirs off, or put it on. */
+export declare function mlsReactionAction(reactions: readonly MlsReaction[] | null | undefined, emoji: string, userId: string): "add" | "remove";

package/dist/mls/reactions.js

@@ -0,0 +1,26 @@
+/* Reactions on an MLS message live only in each device's archive. One reducer for both apps,
+   in the `{ src, amount, users }` shape the server sends for every other message. */
+/** Adding twice or removing what isn't there changes nothing, so replays and reorders are safe. */
+export function applyMlsReaction(reactions, change) {
+    const { emoji, userId, action } = change;
+    const list = (reactions ?? []).map((r) => ({ src: r.src, amount: r.users.length, users: [...r.users] }));
+    const existing = list.find((r) => r.src === emoji);
+    if (action === "add") {
+        if (!existing)
+            list.push({ src: emoji, amount: 1, users: [userId] });
+        else if (!existing.users.includes(userId)) {
+            existing.users.push(userId);
+            existing.amount = existing.users.length;
+        }
+        return list;
+    }
+    if (existing) {
+        existing.users = existing.users.filter((u) => u !== userId);
+        existing.amount = existing.users.length;
+    }
+    return list.filter((r) => r.amount > 0);
+}
+/** What a tap on a reaction chip means for this person: take theirs off, or put it on. */
+export function mlsReactionAction(reactions, emoji, userId) {
+    return reactions?.some((r) => r.src === emoji && r.users.includes(userId)) ? "remove" : "add";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gryt/core",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Gryt's shared application logic: one implementation of the things the desktop and mobile apps both do.",
   "license": "AGPL-3.0-only",
   "repository": {