@rikaidev/yomi 0.2.6

package/dist/line/core/e2ee/keys/peer-key.js

@@ -0,0 +1,191 @@
+import { Buffer } from 'node:buffer';
+import { normalizeGroupPublicKeys, normalizeNegotiatedPublicKey, } from './key-payload.js';
+/**
+ * Resolve and cache a peer public key by MID and key ID.
+ * @param ctx - KeyManager context
+ * @param mid - Peer LINE MID
+ * @param keyId - Expected peer key ID
+ * @returns Peer public key bytes
+ */
+export async function getPeerPublicKey(ctx, mid, keyId) {
+    const cacheKey = `peer:${keyId}`;
+    if (ctx.peerPublicKeys.has(cacheKey)) {
+        ctx.logGroupKeyEvent('e2ee.peer_key.cache_hit', {
+            mid,
+            key_id: keyId,
+            source: 'memory',
+        });
+        return ctx.peerPublicKeys.get(cacheKey);
+    }
+    const store = ctx.getStore();
+    const persisted = await store?.get?.(`line_e2ee_public_by_keyid:${keyId}`);
+    if (persisted) {
+        const parsed = JSON.parse(persisted);
+        const data = Buffer.from(parsed.keyData, 'base64');
+        ctx.peerPublicKeys.set(cacheKey, data);
+        ctx.logGroupKeyEvent('e2ee.peer_key.cache_hit', {
+            mid,
+            key_id: keyId,
+            source: 'persisted',
+        });
+        return data;
+    }
+    const client = ctx.getClient();
+    const publicKey = normalizeNegotiatedPublicKey(await client?.negotiateE2EEPublicKey?.(mid));
+    const negotiatedKeyId = publicKey?.keyId;
+    const keyData = publicKey?.keyData;
+    if (!keyData || String(negotiatedKeyId) !== String(keyId)) {
+        ctx.logGroupKeyEvent('e2ee.peer_key.fetch_failed', {
+            mid,
+            key_id: keyId,
+            negotiated_key_id: negotiatedKeyId ?? null,
+        });
+        throw new Error(`Peer E2EE key mismatch for ${mid}: expected=${keyId}, actual=${String(negotiatedKeyId)}`);
+    }
+    ctx.peerPublicKeys.set(cacheKey, keyData);
+    ctx.logGroupKeyEvent('e2ee.peer_key.resolved', {
+        mid,
+        key_id: keyId,
+        source: 'server_fetch',
+    });
+    await persistPeerPublicKey(ctx, mid, String(keyId), keyData);
+    return keyData;
+}
+/**
+ * Persist one peer public key by key id and append it to the sender history.
+ *
+ * @param ctx - KeyManager context
+ * @param mid - Sender MID
+ * @param keyId - Public key id
+ * @param data - 32-byte public key
+ */
+export async function persistPeerPublicKey(ctx, mid, keyId, data) {
+    const store = ctx.getStore();
+    const record = JSON.stringify({
+        mid,
+        keyId,
+        keyData: data.toString('base64'),
+    });
+    const existing = await store?.get?.(`line_e2ee_public_by_keyid:${keyId}`);
+    if (existing !== record) {
+        await store?.set?.(`line_e2ee_public_by_keyid:${keyId}`, record);
+    }
+    const historyKey = `line_e2ee_public_history_by_mid:${mid}`;
+    const rawHistory = await store?.get?.(historyKey);
+    let history = [];
+    if (rawHistory) {
+        try {
+            const parsed = JSON.parse(rawHistory);
+            if (Array.isArray(parsed)) {
+                history = parsed.filter(Boolean);
+            }
+        }
+        catch {
+            history = [];
+        }
+    }
+    const nextHistory = [
+        { mid, keyId, keyData: data.toString('base64') },
+        ...history.filter((entry) => String(entry?.keyId) !== keyId),
+    ].slice(0, 8);
+    await store?.set?.(historyKey, JSON.stringify(nextHistory));
+}
+/**
+ * Append the live group-member-map key as the first sender candidate.
+ *
+ * @param ctx - KeyManager context.
+ * @param chatMid - Group chat MID.
+ * @param senderMid - Sender MID.
+ * @param senderKey - Sender key from LINE group-member map.
+ * @param candidates - Mutable candidate collection.
+ */
+async function appendLiveSenderCandidate(ctx, chatMid, senderMid, senderKey, candidates) {
+    if (!senderKey) {
+        return;
+    }
+    const data = senderKey.keyData;
+    ctx.peerPublicKeys.set(`peer:${senderKey.keyId}`, data);
+    await persistPeerPublicKey(ctx, senderMid, String(senderKey.keyId), data);
+    ctx.logGroupKeyEvent('e2ee.peer_key.resolved', {
+        mid: senderMid,
+        key_id: senderKey.keyId,
+        source: 'group_member_key_map',
+        chat: chatMid,
+    });
+    candidates.push({
+        keyId: String(senderKey.keyId),
+        keyData: data,
+        source: 'group_member_key_map',
+    });
+}
+/**
+ * Append persisted sender history keys that are not duplicates.
+ *
+ * @param ctx - KeyManager context.
+ * @param senderMid - Sender MID.
+ * @param candidates - Mutable candidate collection.
+ */
+async function appendHistoricalSenderCandidates(ctx, senderMid, candidates) {
+    const store = ctx.getStore();
+    const rawHistory = await store?.get?.(`line_e2ee_public_history_by_mid:${senderMid}`);
+    const parsed = rawHistory ? JSON.parse(rawHistory) : null;
+    const entries = Array.isArray(parsed) ? parsed : [];
+    for (const entry of entries) {
+        const keyData = entry?.keyData;
+        if (typeof keyData !== 'string') {
+            continue;
+        }
+        const buffer = Buffer.from(keyData, 'base64');
+        const historyKeyId = String(entry?.keyId || '');
+        if (!historyKeyId) {
+            continue;
+        }
+        if (!candidates.some((candidate) => candidate.keyId === historyKeyId || candidate.keyData.equals(buffer))) {
+            candidates.push({
+                keyId: historyKeyId,
+                keyData: buffer,
+                source: 'history',
+            });
+        }
+    }
+}
+/**
+ * Resolve sender public key candidates for a group message.
+ *
+ * Prefers an explicit sender key from the group member key map.
+ * Falls back to the persisted sender key history when that field is absent.
+ *
+ * @param ctx - KeyManager context
+ * @param chatMid - Group or room MID
+ * @param senderMid - Sender MID
+ * @returns Candidate sender public key buffers
+ */
+export async function getGroupSenderPublicKeyCandidates(ctx, chatMid, senderMid) {
+    ctx.logGroupKeyEvent('e2ee.message.sender_key_id_fallback', {
+        chat: chatMid,
+        sender: senderMid,
+        strategy: 'group_member_key_map_then_history',
+    });
+    const client = ctx.getClient();
+    const keyMap = normalizeGroupPublicKeys(await client?.getLastE2EEPublicKeys?.(chatMid));
+    const senderKey = keyMap.get(senderMid);
+    const candidates = [];
+    await appendLiveSenderCandidate(ctx, chatMid, senderMid, senderKey, candidates);
+    try {
+        await appendHistoricalSenderCandidates(ctx, senderMid, candidates);
+    }
+    catch {
+        // Ignore malformed history and continue with currently known keys only.
+    }
+    if (candidates.length === 0) {
+        ctx.logGroupKeyEvent('e2ee.message.missing_sender_key_id', {
+            chat: chatMid,
+            sender: senderMid,
+            sender_key_id: null,
+            receiver_key_id: null,
+            strategy: 'group_member_key_map_miss',
+        });
+        throw new Error(`Missing group sender key for ${senderMid} in ${chatMid}`);
+    }
+    return candidates;
+}

package/dist/line/core/e2ee/recovery/bootstrap-keys.js

@@ -0,0 +1,161 @@
+import { Buffer } from 'node:buffer';
+import { decryptKeyChain } from '../index.js';
+/**
+ * Attempt to rebuild persisted LINE self keys from the original login bootstrap.
+ *
+ * When `line_e2ee_keys` is missing but the login-time encrypted keychain and
+ * the device secret key are still present in the credential store, we can
+ * deterministically reconstruct the same self key material without logging in
+ * again. This is strictly a local recovery step: it does not refresh tokens,
+ * open new auth sessions, or mutate the remote LINE session.
+ *
+ * @param service - LineProtocolService-like object
+ * @returns Recovered key list, or null when bootstrap material is unavailable
+ */
+export async function recoverBootstrapKeys(service) {
+    const bootstrapInput = await readBootstrapRecoveryInput(service);
+    if (!bootstrapInput) {
+        return null;
+    }
+    const keys = rebuildBootstrapKeys(bootstrapInput);
+    if (!keys) {
+        return null;
+    }
+    await persistRecoveredKeys(service, keys, bootstrapInput.mid);
+    return keys;
+}
+/**
+ * Load and validate the persisted bootstrap inputs required for local E2EE recovery.
+ *
+ * @param service - LineProtocolService-like object.
+ * @returns Decoded bootstrap inputs or null.
+ */
+async function readBootstrapRecoveryInput(service) {
+    const bootstrapRaw = await service?.credentialStore?.get?.('line_e2ee_bootstrap');
+    const bootstrap = parseBootstrapPayload(bootstrapRaw);
+    const secretKeyBase64 = await readPersistedSecretKey(service, bootstrap);
+    const decodedBuffers = decodeBootstrapBuffers(bootstrap, secretKeyBase64);
+    if (!decodedBuffers) {
+        return null;
+    }
+    return {
+        ...decodedBuffers,
+        mid: await readPersistedMid(service),
+    };
+}
+/**
+ * Read the local device secret used to decrypt LINE's login keychain.
+ *
+ * @param service - LineProtocolService-like object.
+ * @param bootstrap - Parsed bootstrap payload.
+ * @returns Base64 secret key or null.
+ */
+async function readPersistedSecretKey(service, bootstrap) {
+    if (bootstrap?.secretKey) {
+        return bootstrap.secretKey;
+    }
+    return (await service?.credentialStore?.get?.('line_nacl_secret_key')) || null;
+}
+/**
+ * Read the active LINE self MID.
+ *
+ * @param service - LineProtocolService-like object.
+ * @returns Persisted MID or null.
+ */
+async function readPersistedMid(service) {
+    if (service?.profile?.mid) {
+        return service.profile.mid;
+    }
+    return (await service?.credentialStore?.get?.('line_mid')) || null;
+}
+/**
+ * Parse the stored bootstrap JSON payload.
+ *
+ * @param bootstrapRaw - Raw bootstrap JSON.
+ * @returns Parsed payload or null.
+ */
+function parseBootstrapPayload(bootstrapRaw) {
+    if (!bootstrapRaw) {
+        return null;
+    }
+    try {
+        return JSON.parse(bootstrapRaw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decode the persisted bootstrap buffers needed for key recovery.
+ *
+ * @param bootstrap - Parsed bootstrap payload.
+ * @param secretKeyBase64 - Persisted secret key in base64.
+ * @returns Decoded buffers or null.
+ */
+function decodeBootstrapBuffers(bootstrap, secretKeyBase64) {
+    const encryptedKeyChain = decodeBase64Buffer(bootstrap?.encryptedKeyChain);
+    const serverPublicKey = decodeBase64Buffer(bootstrap?.serverPublicKey);
+    const secretKey = decodeBase64Buffer(secretKeyBase64);
+    if (!encryptedKeyChain || !serverPublicKey || !secretKey) {
+        return null;
+    }
+    return {
+        encryptedKeyChain,
+        serverPublicKey,
+        secretKey,
+    };
+}
+/**
+ * Rebuild persisted self keys from decoded bootstrap inputs.
+ *
+ * @param input - Decoded bootstrap inputs.
+ * @param input.encryptedKeyChain - Encrypted key chain from login bootstrap.
+ * @param input.serverPublicKey - Server public key from login bootstrap.
+ * @param input.secretKey - Persisted local secret key.
+ * @param input.mid - Optional self MID.
+ * @returns Recovered key list or null.
+ */
+function rebuildBootstrapKeys(input) {
+    const keys = decryptKeyChain(input.encryptedKeyChain, input.serverPublicKey, input.secretKey).map((key) => ({
+        ...key,
+        mid: input.mid,
+    }));
+    return Array.isArray(keys) && keys.length > 0 ? keys : null;
+}
+/**
+ * Persist recovered keys into the in-memory manager and session state.
+ *
+ * @param service - LineProtocolService-like object.
+ * @param keys - Recovered key list.
+ * @param mid - Optional self MID.
+ */
+async function persistRecoveredKeys(service, keys, mid) {
+    service.e2eeManager.importKeys(keys);
+    if (mid) {
+        service.e2eeManager.bindSelfKeysToMid(mid);
+    }
+    await service.sessionState.saveE2EEKeys(keys);
+}
+/**
+ * Decode a base64-encoded string into a Buffer when possible.
+ *
+ * @param value - Stored base64 string or Buffer-like value
+ * @returns Decoded Buffer or null
+ */
+function decodeBase64Buffer(value) {
+    if (!value) {
+        return null;
+    }
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+        return null;
+    }
+    try {
+        return Buffer.from(value, 'base64');
+    }
+    catch {
+        return null;
+    }
+}

package/dist/line/core/e2ee/types.js

@@ -0,0 +1,4 @@
+/**
+ * LINE E2EE types
+ */
+export {};

package/dist/line/core/group-query-service.js

@@ -0,0 +1,20 @@
+import { requireLineClient } from './client-runtime.js';
+/**
+ * Build the LINE group query boundary for a connected runtime.
+ *
+ * @param getClient - Deferred LINE client accessor
+ * @returns Group query methods
+ */
+export function createGroupQueryService(getClient) {
+    return {
+        /**
+         * Fetch a LINE group profile.
+         *
+         * @param groupId - LINE group MID
+         * @returns LINE group profile
+         */
+        async getGroup(groupId) {
+            return requireLineClient(getClient).getGroup(groupId);
+        },
+    };
+}

package/dist/line/core/media-decrypt.js

@@ -0,0 +1,78 @@
+import crypto from 'node:crypto';
+import { buildLineVideoChunkHashes } from './media-encrypt.js';
+/**
+ * Derive LINE E2EE media keys from decrypted key material.
+ *
+ * @param keyMaterial - Base64 LINE media key material.
+ * @returns Encryption key, MAC key, and CTR nonce.
+ */
+async function deriveLineMediaKeyMaterial(keyMaterial) {
+    const material = Buffer.from(keyMaterial, 'base64');
+    const derived = await new Promise((resolve, reject) => {
+        crypto.hkdf('sha256', material, new Uint8Array(0), 'FileEncryption', 76, (error, key) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(Buffer.from(key));
+        });
+    });
+    return {
+        encKey: derived.subarray(0, 32),
+        macKey: derived.subarray(32, 64),
+        nonce: Buffer.concat([derived.subarray(64, 76), Buffer.alloc(4)]),
+    };
+}
+/** Thrown when a media object's MAC does not match its ciphertext. */
+export class MediaMacVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MediaMacVerificationError';
+    }
+}
+/**
+ * Decrypt LINE E2EE media bytes, verifying the trailing MAC first.
+ *
+ * LINE appends a 32-byte MAC, in the clear, after the AES-256-CTR ciphertext.
+ * It is keyed with the HKDF's macKey and comes in two constructions, selected
+ * by which OBS object is being read — NOT by contentType alone:
+ *
+ *   - whole-file  : HMAC-SHA256(macKey, ciphertext)
+ *                   images, audio, files, AND a video's `__ud-preview` poster
+ *   - chunked     : HMAC-SHA256(macKey, ‖ SHA-256(128 KB chunk of ciphertext))
+ *                   a video's main body only
+ *
+ * Both constructions were confirmed against real received media (image, audio,
+ * video body, and that same video's preview) rather than inferred from the send
+ * path — the send path could not settle it, because nothing verified these MACs
+ * in either direction, so a wrong construction would have gone unnoticed.
+ *
+ * Verification is not optional hardening. AES-CTR is malleable: without it, any
+ * party able to alter the downloaded bytes — starting with LINE's own OBS
+ * servers, which is precisely who E2EE exists to defend against — can flip
+ * chosen bits of the decrypted plaintext undetected.
+ *
+ * @param encryptedBytes - Downloaded encrypted media bytes (ciphertext ‖ MAC).
+ * @param keyMaterial - Base64 key material from the E2EE data message.
+ * @param options - Which MAC construction applies.
+ * @param options.chunkHashMac - True only for a video's main body.
+ * @returns Decrypted media bytes.
+ * @throws MediaMacVerificationError when the MAC does not match.
+ */
+export async function decryptLineMediaBytes(encryptedBytes, keyMaterial, options = {}) {
+    const keys = await deriveLineMediaKeyMaterial(keyMaterial);
+    if (encryptedBytes.length < 32) {
+        throw new MediaMacVerificationError(`media object is ${encryptedBytes.length} bytes — too short to carry a 32-byte MAC`);
+    }
+    const ciphertext = encryptedBytes.subarray(0, encryptedBytes.length - 32);
+    const mac = encryptedBytes.subarray(encryptedBytes.length - 32);
+    const expected = crypto
+        .createHmac('sha256', keys.macKey)
+        .update(options.chunkHashMac ? buildLineVideoChunkHashes(ciphertext) : ciphertext)
+        .digest();
+    if (!crypto.timingSafeEqual(expected, mac)) {
+        throw new MediaMacVerificationError(`media MAC mismatch (${options.chunkHashMac ? 'chunked' : 'whole-file'} construction, ${ciphertext.length}B ciphertext) — the object was altered in transit or is not the object this key belongs to`);
+    }
+    const decipher = crypto.createDecipheriv('aes-256-ctr', keys.encKey, keys.nonce);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}

package/dist/line/core/media-encrypt.js

@@ -0,0 +1,97 @@
+import crypto from 'node:crypto';
+/**
+ * Derive LINE E2EE media keys from key material, mirroring the derivation
+ * in media-decrypt.ts exactly (same HKDF params, same key/nonce layout) so
+ * ciphertext produced here is decryptable by decryptLineMediaBytes.
+ *
+ * @param keyMaterial - Base64 LINE media key material.
+ * @returns Encryption key, MAC key, and CTR nonce.
+ */
+async function deriveLineMediaKeyMaterial(keyMaterial) {
+    const material = Buffer.from(keyMaterial, 'base64');
+    const derived = await new Promise((resolve, reject) => {
+        crypto.hkdf('sha256', material, new Uint8Array(0), 'FileEncryption', 76, (error, key) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(Buffer.from(key));
+        });
+    });
+    return {
+        encKey: derived.subarray(0, 32),
+        macKey: derived.subarray(32, 64),
+        nonce: Buffer.concat([derived.subarray(64, 76), Buffer.alloc(4)]),
+    };
+}
+/**
+ * Encrypt LINE E2EE media bytes for outbound upload.
+ *
+ * Mirrors decryptLineMediaBytes in reverse: AES-256-CTR encrypt with the
+ * derived key/nonce, then append an HMAC-SHA256 MAC (computed over the
+ * ciphertext only) as the trailing 32 bytes — the exact layout
+ * decryptLineMediaBytes expects to strip.
+ *
+ * @param raw - Plaintext media bytes to encrypt.
+ * @param keyMaterial - Base64 key material (caller-generated, 32 random bytes).
+ * @returns Ciphertext with the trailing 32-byte MAC appended.
+ */
+export async function encryptLineMediaBytes(raw, keyMaterial) {
+    const keys = await deriveLineMediaKeyMaterial(keyMaterial);
+    const cipher = crypto.createCipheriv('aes-256-ctr', keys.encKey, keys.nonce);
+    const ciphertext = Buffer.concat([cipher.update(raw), cipher.final()]);
+    const mac = crypto
+        .createHmac('sha256', keys.macKey)
+        .update(ciphertext)
+        .digest();
+    return Buffer.concat([ciphertext, mac]);
+}
+/** LINE video E2EE chunk size — the ciphertext is hashed in 128 KB pieces. */
+const LINE_VIDEO_CHUNK_SIZE = 131072;
+/**
+ * Concatenate the SHA-256 hash of each 128 KB chunk of a video ciphertext.
+ *
+ * Video E2EE lets the receiver verify integrity while streaming, so instead of
+ * one MAC over the whole ciphertext (image/audio/file), the ciphertext is split
+ * into 128 KB chunks, each hashed with SHA-256, and those hashes are what the
+ * MAC covers. Pass the ciphertext WITHOUT any trailing MAC — the hashes must
+ * match the bytes a receiver actually downloads and re-hashes per chunk.
+ *
+ * @param ciphertext - AES-256-CTR video ciphertext (no trailing MAC).
+ * @returns The N chunk hashes concatenated (N × 32 bytes).
+ */
+export function buildLineVideoChunkHashes(ciphertext) {
+    const hashes = [];
+    for (let offset = 0; offset < ciphertext.length; offset += LINE_VIDEO_CHUNK_SIZE) {
+        hashes.push(crypto
+            .createHash('sha256')
+            .update(ciphertext.subarray(offset, offset + LINE_VIDEO_CHUNK_SIZE))
+            .digest());
+    }
+    return Buffer.concat(hashes);
+}
+/**
+ * Encrypt LINE E2EE video bytes for outbound upload.
+ *
+ * The ciphertext is byte-for-byte identical to {@link encryptLineMediaBytes}
+ * (same whole-file AES-256-CTR stream — the whitepaper's per-chunk decryption
+ * IV `IV‖(i*8192)` is exactly the same CTR state continued at each 128 KB
+ * boundary). Only the MAC differs: it is computed over the concatenation of the
+ * per-chunk SHA-256 hashes rather than over the raw ciphertext, then appended
+ * as the trailing 32 bytes. The separate chunk-hash manifest object the
+ * receiver needs is produced by {@link buildLineVideoChunkHashes}.
+ *
+ * @param raw - Plaintext video bytes to encrypt.
+ * @param keyMaterial - Base64 key material (caller-generated, 32 random bytes).
+ * @returns Ciphertext with the trailing 32-byte chunk-hash MAC appended.
+ */
+export async function encryptLineVideoBytes(raw, keyMaterial) {
+    const keys = await deriveLineMediaKeyMaterial(keyMaterial);
+    const cipher = crypto.createCipheriv('aes-256-ctr', keys.encKey, keys.nonce);
+    const ciphertext = Buffer.concat([cipher.update(raw), cipher.final()]);
+    const mac = crypto
+        .createHmac('sha256', keys.macKey)
+        .update(buildLineVideoChunkHashes(ciphertext))
+        .digest();
+    return Buffer.concat([ciphertext, mac]);
+}

package/dist/line/core/mention.js

@@ -0,0 +1,89 @@
+/**
+ * LINE outbound @mention wire format — `contentMetadata.MENTION`.
+ *
+ * Reverse-engineered from two real inbound group messages captured by the
+ * operator (see the task ground truth, not restated here). Established
+ * facts, and nothing beyond them:
+ *
+ * - `contentMetadata.MENTION` is a JSON *string* whose parsed shape is
+ *   `{ MENTIONEES: [{ M, S, E }, ...] }`.
+ * - `M` is the mentioned user's MID; `S`/`E` are the start/end offsets as
+ *   *strings*, not numbers.
+ * - The range is half-open `[S, E)`, measured in UTF-16 code units — i.e.
+ *   plain JS string indices (`"@鄭富源".length === 4` matched `S:"0", E:"4"`).
+ * - Key order inside a mentionee object is not significant.
+ * - MENTION rides in `contentMetadata`, which is never part of an E2EE
+ *   ciphertext payload — it was observed in the clear on a real message.
+ *
+ * This module only builds and validates that wire shape. It does not
+ * resolve display names to MIDs (that guess is out of scope — see
+ * `find_contact`/`get_group_members`), and it does not extend the format
+ * with anything not listed above.
+ */
+/**
+ * Validate a set of outbound mentions against the text they annotate.
+ * Throws a descriptive `Error` on the first violation found. Every check
+ * here exists because a malformed mention does not fail loudly on LINE's
+ * side — it silently degrades to a plain, non-notifying `@name` string,
+ * which is exactly the failure this module exists to prevent.
+ *
+ * @param text - The message body the mentions index into.
+ * @param mentions - Proposed mentions.
+ * @throws Error describing the first invalid mention or overlap found.
+ */
+export function validateMentions(text, mentions) {
+    const sorted = [...mentions].sort((a, b) => a.start - b.start);
+    for (const mention of sorted) {
+        const { mid, start, end } = mention;
+        if (typeof mid !== 'string' || mid.length === 0) {
+            throw new Error(`Mention mid must be a non-empty string (got: ${JSON.stringify(mid)}).`);
+        }
+        if (!Number.isInteger(start) || !Number.isInteger(end)) {
+            throw new Error(`Mention start/end must be integers (got start=${start}, end=${end}, mid=${mid}).`);
+        }
+        if (!(start >= 0 && start < end)) {
+            throw new Error(`Mention range must satisfy 0 <= start < end (got start=${start}, end=${end}, mid=${mid}).`);
+        }
+        if (end > text.length) {
+            throw new Error(`Mention end (${end}) exceeds text length (${text.length}) for mid=${mid}.`);
+        }
+        // Heuristic guard derived from observed data, not a documented LINE
+        // protocol requirement: every real mention we have seen starts at the
+        // visible "@" of the "@name" run. A range that does not is almost
+        // certainly an off-by-one that would render as a broken/misaligned
+        // highlight rather than a real notification.
+        if (text[start] !== '@') {
+            throw new Error(`Mention range [${start}, ${end}) for mid=${mid} must start at "@" (the "@name" run in text), ` +
+                `but text[${start}] is ${JSON.stringify(text[start])}. `);
+        }
+    }
+    for (let i = 1; i < sorted.length; i++) {
+        const prev = sorted[i - 1];
+        const cur = sorted[i];
+        if (cur.start < prev.end) {
+            throw new Error(`Mention ranges overlap: [${prev.start}, ${prev.end}) (mid=${prev.mid}) ` +
+                `and [${cur.start}, ${cur.end}) (mid=${cur.mid}).`);
+        }
+    }
+}
+/**
+ * Build the `contentMetadata.MENTION` wire value for a set of outbound
+ * mentions, validating them against `text` first. It is not possible to
+ * obtain a built metadata string without passing validation — the two are
+ * deliberately not separable at the call site.
+ *
+ * @param text - The message body the mentions index into.
+ * @param mentions - Mentions to encode.
+ * @returns The JSON string LINE expects at `contentMetadata.MENTION`.
+ * @throws Error - see `validateMentions`.
+ */
+export function buildMentionMetadata(text, mentions) {
+    validateMentions(text, mentions);
+    return JSON.stringify({
+        MENTIONEES: mentions.map((m) => ({
+            S: String(m.start),
+            E: String(m.end),
+            M: m.mid,
+        })),
+    });
+}