@rikaidev/yomi 0.2.6

package/dist/mcp/media.js

@@ -0,0 +1,228 @@
+/**
+ * LINE E2EE media resolution for the `get_message_media` (and legacy
+ * `get_message_image`) MCP tools.
+ *
+ * Mirrors the descriptor-parsing logic the original (excluded) media-asset
+ * pipeline used, adapted for the MCP surface: given a chat + message id,
+ * locate the message's OBS object metadata and E2EE key material, download
+ * the encrypted bytes, and decrypt them. The obs-download + AES-256-CTR
+ * decrypt path is identical across LINE content types (image/video/audio/
+ * file) — only the resolved MIME type and MCP content shape differ.
+ *
+ * Never fabricates a fallback — if key material or OBS metadata is
+ * missing, or the message's content type is not a downloadable media type,
+ * callers get an honest error naming the reason.
+ */
+import { downloadLineObsMediaObject } from '../line/client/obs-media-client.js';
+import { CONTENT_TYPE } from '../line/core/constants.js';
+import { decryptLineMediaBytes } from '../line/core/media-decrypt.js';
+/** LINE content types this server can download and decrypt via the OBS path. */
+const DOWNLOADABLE_CONTENT_TYPES = new Set([
+    CONTENT_TYPE.IMAGE,
+    CONTENT_TYPE.VIDEO,
+    CONTENT_TYPE.AUDIO,
+    CONTENT_TYPE.FILE,
+]);
+/** Short media-kind label per LINE content type, for MCP content shaping. */
+const MEDIA_TYPE_BY_CONTENT_TYPE = {
+    [CONTENT_TYPE.IMAGE]: 'image',
+    [CONTENT_TYPE.VIDEO]: 'video',
+    [CONTENT_TYPE.AUDIO]: 'audio',
+    [CONTENT_TYPE.FILE]: 'file',
+};
+/** Fallback MIME type per content type when no file extension is known. */
+const DEFAULT_MIME_BY_CONTENT_TYPE = {
+    [CONTENT_TYPE.IMAGE]: 'image/jpeg',
+    [CONTENT_TYPE.VIDEO]: 'video/mp4',
+    [CONTENT_TYPE.AUDIO]: 'audio/mp4',
+    [CONTENT_TYPE.FILE]: 'application/octet-stream',
+};
+/** MIME type per known file extension, across all downloadable media kinds. */
+const MIME_BY_EXTENSION = {
+    '3gp': 'video/3gpp',
+    aac: 'audio/aac',
+    gif: 'image/gif',
+    jpeg: 'image/jpeg',
+    jpg: 'image/jpeg',
+    m4a: 'audio/mp4',
+    m4v: 'video/x-m4v',
+    mov: 'video/quicktime',
+    mp3: 'audio/mpeg',
+    mp4: 'video/mp4',
+    ogg: 'audio/ogg',
+    pdf: 'application/pdf',
+    png: 'image/png',
+    txt: 'text/plain',
+    wav: 'audio/wav',
+    webp: 'image/webp',
+    zip: 'application/zip',
+};
+/**
+ * Resolve the short media-kind label for a LINE content type.
+ *
+ * @param contentType - LINE contentType numeric value.
+ * @returns 'image' | 'video' | 'audio' | 'file', or null when not downloadable media.
+ */
+export function resolveLineMediaType(contentType) {
+    return MEDIA_TYPE_BY_CONTENT_TYPE[contentType] || null;
+}
+/**
+ * Parse JSON safely with a fallback.
+ *
+ * @param value - Raw JSON value.
+ * @param fallback - Fallback value.
+ * @returns Parsed JSON or fallback.
+ */
+function parseJson(value, fallback) {
+    if (typeof value !== 'string' || !value) {
+        return fallback;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Resolve a MIME type from LINE media metadata.
+ *
+ * @param extension - File extension from MEDIA_CONTENT_INFO.
+ * @param contentType - LINE content type.
+ * @returns MIME type, or null when unknown.
+ */
+function resolveMimeType(extension, contentType) {
+    const normalized = extension?.toLowerCase() || '';
+    if (MIME_BY_EXTENSION[normalized]) {
+        return MIME_BY_EXTENSION[normalized];
+    }
+    return DEFAULT_MIME_BY_CONTENT_TYPE[contentType] || null;
+}
+/**
+ * Build a LINE media descriptor from a decrypted message.
+ *
+ * Image messages carry the E2EE `keyMaterial` inside their decrypted
+ * `text` field as JSON, and the OBS object id/service-namespace inside
+ * `contentMetadata.OID` / `contentMetadata.SID`.
+ *
+ * @param message - Decrypted LINE message (from getRecentMessages).
+ * @returns Media descriptor, or null when the message has no OBS object.
+ */
+export function resolveLineMediaDescriptor(message) {
+    const contentMetadata = message?.contentMetadata || {};
+    if (!contentMetadata.OID || !contentMetadata.SID) {
+        return null;
+    }
+    const dataPayload = parseJson(message?.text, {});
+    const mediaInfo = parseJson(contentMetadata.MEDIA_CONTENT_INFO, {});
+    return {
+        fileName: dataPayload.fileName || null,
+        keyMaterial: dataPayload.keyMaterial || null,
+        mimeType: resolveMimeType(mediaInfo.extension || null, Number(message?.contentType || 0)),
+        oid: String(contentMetadata.OID),
+        sid: String(contentMetadata.SID),
+    };
+}
+/** Base class for honest "could not produce media bytes" errors — never caught to fabricate a fallback. */
+export class LineMediaAccessError extends Error {
+}
+/** Thrown when the message body is missing the OBS/E2EE material required to decrypt its media. */
+export class MissingDecryptMaterialError extends LineMediaAccessError {
+    code = 'missing_decrypt_material';
+    constructor(reason) {
+        super(`missing_decrypt_material: ${reason}`);
+    }
+}
+/** Thrown when the message's content type is not a downloadable media type (e.g. plain text, sticker ref). */
+export class UnsupportedMediaTypeError extends LineMediaAccessError {
+    code = 'unsupported_media_type';
+    constructor(contentType, messageId) {
+        const label = resolveLineMediaType(contentType) ?? `contentType=${contentType}`;
+        super(`unsupported_media_type: message ${messageId} (${label}) is not downloadable media`);
+    }
+}
+/**
+ * Fetch and decrypt one LINE media attachment (image, video, audio, or file).
+ *
+ * The obs-media-client download and AES-256-CTR decrypt are content-type
+ * agnostic — only descriptor resolution (MIME/filename) and the downstream
+ * MCP content shape differ per media kind.
+ *
+ * @param service - Active LineProtocolService (must already have a resumed session).
+ * @param chatId - LINE chat MID the message belongs to.
+ * @param messageId - LINE message id.
+ * @param preview - Whether to fetch the smaller preview object instead of the original.
+ * @returns Decrypted media bytes, resolved MIME type, filename, and content type.
+ */
+export async function fetchLineMessageMedia(service, chatId, messageId, preview) {
+    const messages = await service.getRecentMessages(chatId, 100);
+    const message = messages.find((candidate) => candidate.id === messageId);
+    if (!message) {
+        throw new MissingDecryptMaterialError(`message ${messageId} not found in recent history of ${chatId}`);
+    }
+    const contentType = Number(message.contentType);
+    if (!DOWNLOADABLE_CONTENT_TYPES.has(contentType)) {
+        throw new UnsupportedMediaTypeError(contentType, messageId);
+    }
+    const descriptor = resolveLineMediaDescriptor(message);
+    if (!descriptor) {
+        throw new MissingDecryptMaterialError(`message ${messageId} is missing OBS object metadata (OID/SID)`);
+    }
+    const encryptedBytes = await downloadLineObsMediaObject(service.client, {
+        messageId,
+        oid: descriptor.oid,
+        preview,
+        sid: descriptor.sid,
+    });
+    if (encryptedBytes.length === 0) {
+        throw new Error('LINE media download returned empty bytes');
+    }
+    const fallbackMimeType = descriptor.mimeType ||
+        DEFAULT_MIME_BY_CONTENT_TYPE[contentType] ||
+        'application/octet-stream';
+    if (!descriptor.keyMaterial) {
+        // Not all media messages are E2EE-wrapped (e.g. some group content is
+        // plaintext) — but when contentMetadata carries no keyMaterial we
+        // cannot tell the difference between "unencrypted" and "decrypt
+        // context missing", so we surface the honest bytes as-is rather than
+        // guessing. Callers can inspect mimeType/bytes to decide.
+        return {
+            bytes: encryptedBytes,
+            contentType,
+            fileName: descriptor.fileName,
+            mimeType: fallbackMimeType,
+        };
+    }
+    // Which MAC construction applies is decided by the OBS object, not by
+    // contentType alone: a video's main body is MACed over its per-128KB chunk
+    // hashes, but that same video's `__ud-preview` poster is a whole-file image
+    // and is MACed like one. Confirmed against real media of each shape.
+    const mediaBytes = await decryptLineMediaBytes(encryptedBytes, descriptor.keyMaterial, { chunkHashMac: contentType === CONTENT_TYPE.VIDEO && !preview });
+    if (mediaBytes.length === 0) {
+        throw new Error('LINE media decrypt returned empty bytes');
+    }
+    return {
+        bytes: mediaBytes,
+        contentType,
+        fileName: descriptor.fileName,
+        mimeType: fallbackMimeType,
+    };
+}
+/**
+ * Fetch and decrypt one LINE image attachment. Thin `get_message_image`
+ * back-compat wrapper over {@link fetchLineMessageMedia} that rejects
+ * non-image content types with an honest error.
+ *
+ * @param service - Active LineProtocolService (must already have a resumed session).
+ * @param chatId - LINE chat MID the message belongs to.
+ * @param messageId - LINE message id.
+ * @param preview - Whether to fetch the smaller preview object instead of the original.
+ * @returns Decrypted image bytes and resolved MIME type.
+ */
+export async function fetchLineMessageImage(service, chatId, messageId, preview) {
+    const result = await fetchLineMessageMedia(service, chatId, messageId, preview);
+    if (result.contentType !== CONTENT_TYPE.IMAGE) {
+        throw new UnsupportedMediaTypeError(result.contentType, messageId);
+    }
+    return { bytes: result.bytes, mimeType: result.mimeType };
+}

package/dist/mcp/names.js

@@ -0,0 +1,133 @@
+/**
+ * Yomi MCP name resolution — turns opaque LINE MIDs into display names.
+ *
+ * LINE MIDs are prefixed by conversation kind (u = 1:1 user, c = group,
+ * r = room). For a 1:1 chat the chat id IS the other party's contact MID,
+ * so it resolves through the same user-contact path as message senders.
+ * Group/room titles resolve through TalkService getChats' chatName field.
+ *
+ * Every resolver batches unique MIDs into a single TalkService call and
+ * reads/writes through LineProtocolService's existing nameCache /
+ * chatCache, so a name is fetched over the network at most once per
+ * process lifetime. Unresolvable MIDs are never given a fabricated
+ * placeholder — callers get `null` and may fall back to the raw MID.
+ */
+/**
+ * Resolve display names for LINE user (contact) MIDs.
+ *
+ * @param service - Resumed LineProtocolService.
+ * @param mids - User MIDs to resolve (duplicates and falsy values ignored).
+ * @returns Map of MID to resolved display name (unresolved MIDs are omitted).
+ */
+export async function resolveUserNames(service, mids) {
+    const unique = Array.from(new Set(mids.filter(Boolean)));
+    const resolved = new Map();
+    const missing = [];
+    for (const mid of unique) {
+        const cached = service.nameCache.get(mid);
+        if (cached) {
+            resolved.set(mid, cached);
+        }
+        else {
+            missing.push(mid);
+        }
+    }
+    if (missing.length > 0) {
+        const contacts = await service.client.getContacts(missing);
+        for (const contact of contacts) {
+            if (contact?.mid && contact.displayName) {
+                service.nameCache.set(contact.mid, contact.displayName);
+                resolved.set(contact.mid, contact.displayName);
+            }
+        }
+    }
+    return resolved;
+}
+/**
+ * Resolve display names for message senders, short-circuiting the
+ * authenticated user's own MID from the already-known profile instead of
+ * spending a network call on it.
+ *
+ * @param service - Resumed LineProtocolService.
+ * @param mids - Sender MIDs to resolve (duplicates and falsy values ignored).
+ * @returns Map of MID to resolved display name (unresolved MIDs are omitted).
+ */
+export async function resolveSenderNames(service, mids) {
+    const unique = Array.from(new Set(mids.filter(Boolean)));
+    const selfMid = service.profile?.mid;
+    const selfName = service.profile?.displayName;
+    const remaining = [];
+    const resolved = new Map();
+    for (const mid of unique) {
+        if (mid === selfMid && selfName) {
+            resolved.set(mid, selfName);
+            service.nameCache.set(mid, selfName);
+        }
+        else {
+            remaining.push(mid);
+        }
+    }
+    const fetched = await resolveUserNames(service, remaining);
+    for (const [mid, name] of fetched) {
+        resolved.set(mid, name);
+    }
+    return resolved;
+}
+/**
+ * Resolve titles for group/room chat MIDs via getChats' chatName field.
+ *
+ * @param service - Resumed LineProtocolService.
+ * @param chatIds - Group/room chat MIDs to resolve.
+ * @returns Map of chat MID to resolved chat title (unresolved MIDs are omitted).
+ */
+export async function resolveGroupNames(service, chatIds) {
+    const unique = Array.from(new Set(chatIds.filter(Boolean)));
+    const resolved = new Map();
+    const missing = [];
+    for (const id of unique) {
+        const cached = service.chatCache.get(id);
+        if (cached?.chatName) {
+            resolved.set(id, cached.chatName);
+        }
+        else if (cached === undefined) {
+            missing.push(id);
+        }
+    }
+    if (missing.length > 0) {
+        const chats = await service.client.getChats(missing, false);
+        for (const chat of chats) {
+            if (chat?.chatMid) {
+                service.chatCache.set(chat.chatMid, chat);
+                if (chat.chatName) {
+                    resolved.set(chat.chatMid, chat.chatName);
+                }
+            }
+        }
+    }
+    return resolved;
+}
+/**
+ * Resolve a human-readable name for each conversation id, dispatching by
+ * LINE's MID prefix convention (u = 1:1 user, c = group, r = room).
+ *
+ * @param service - Resumed LineProtocolService.
+ * @param chatIds - Conversation MIDs, as returned by getMessageBoxes.
+ * @returns Map of chat MID to resolved name, or null when unresolvable.
+ */
+export async function resolveConversationNames(service, chatIds) {
+    const userIds = chatIds.filter((id) => id?.startsWith('u'));
+    const groupIds = chatIds.filter((id) => id?.startsWith('c') || id?.startsWith('r'));
+    const [userNames, groupNames] = await Promise.all([
+        userIds.length > 0
+            ? resolveUserNames(service, userIds)
+            : Promise.resolve(new Map()),
+        groupIds.length > 0
+            ? resolveGroupNames(service, groupIds)
+            : Promise.resolve(new Map()),
+    ]);
+    const result = new Map();
+    for (const id of chatIds) {
+        result.set(id, userNames.get(id) ?? groupNames.get(id) ?? null);
+    }
+    return result;
+}

package/dist/mcp/phi-guard.js

@@ -0,0 +1,105 @@
+/**
+ * Yomi PHI/PII output guard — masks high-sensitivity values in message text
+ * at the MCP tool-return boundary, right before the text leaves the local
+ * machine for the cloud model.
+ *
+ * Deliberately narrow: only high-confidence, high-sensitivity types (national
+ * ID, Luhn-valid payment card, email, mobile phone) are masked, NOT every
+ * number — masking too much would strip context the assistant legitimately
+ * needs (e.g. "the Taitung meeting is at 3pm"). Detection is regex-only for
+ * now; a local semantic (MLX) layer and per-conversation exemptions are
+ * deliberately deferred, not silently dropped.
+ *
+ * Honesty: masking is never silent. Callers surface `phiNote(acc)` as an
+ * extra response content block reporting how many values were masked and of
+ * what types, so the redaction is visible rather than a quiet rewrite.
+ */
+/** Middle-redaction marker used in masked values (Q12〇〇9 style). */
+const MASK_MIDDLE = '〇〇';
+/**
+ * Luhn check for candidate payment-card digit strings.
+ * @param digits - Digits only (no separators).
+ * @returns True when the digits satisfy the Luhn checksum.
+ */
+function passesLuhn(digits) {
+    let sum = 0;
+    let double = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let d = digits.charCodeAt(i) - 48;
+        if (double) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+        double = !double;
+    }
+    return digits.length >= 13 && digits.length <= 19 && sum % 10 === 0;
+}
+/**
+ * Mask one matched value, preserving a little edge context (Q12〇〇9): the
+ * first few characters and, for longer values, the last one.
+ * @param value - The raw matched substring.
+ * @returns The masked substring.
+ */
+function maskValue(value) {
+    const trimmed = value.trim();
+    const head = trimmed.slice(0, Math.min(3, trimmed.length));
+    const tail = trimmed.length > 4 ? trimmed.slice(-1) : '';
+    return `${head}${MASK_MIDDLE}${tail}`;
+}
+// Order matters: email and phone are matched before the broad card pattern so
+// their digits are not re-consumed. Each RegExp MUST have the global flag.
+const PATTERNS = [
+    { type: 'email', re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+    { type: 'id', re: /\b[A-Z][12]\d{8}\b/g },
+    { type: 'phone', re: /\+886[\s-]?\d(?:[\s-]?\d){7,}/g },
+    { type: 'phone', re: /\b09\d{8}\b/g },
+    { type: 'card', re: /\b(?:\d[ -]?){13,19}\b/g, validateDigits: passesLuhn },
+];
+/**
+ * Create a fresh accumulator for one tool response.
+ * @returns A zeroed PhiAccumulator.
+ */
+export function createPhiAccumulator() {
+    return { count: 0, types: new Set() };
+}
+/**
+ * Mask all high-sensitivity spans in one string, tallying into `acc`. Returns
+ * the input unchanged (and untallied) for null/empty/non-string input.
+ * @param acc - Accumulator to record masked count and types into.
+ * @param value - Text to mask.
+ * @returns The masked text (or the original value when nothing to mask).
+ */
+export function maskInto(acc, value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        return value;
+    }
+    let text = value;
+    for (const { type, re, validateDigits } of PATTERNS) {
+        text = text.replace(re, (match) => {
+            if (validateDigits && !validateDigits(match.replace(/\D/g, ''))) {
+                return match;
+            }
+            acc.count += 1;
+            acc.types.add(type);
+            return maskValue(match);
+        });
+    }
+    return text;
+}
+/**
+ * Build the honesty note for a tool response, or null when nothing was masked.
+ * @param acc - Accumulator populated by maskInto.
+ * @returns An MCP text content block reporting the redaction, or null.
+ */
+export function phiNote(acc) {
+    if (acc.count === 0) {
+        return null;
+    }
+    const types = [...acc.types].sort().join(', ');
+    return {
+        type: 'text',
+        text: `[phi-guard] Masked ${acc.count} high-sensitivity value(s) (${types}) before returning them. These are redacted for privacy; if the raw value is genuinely needed, ask the user explicitly.`,
+    };
+}

package/dist/mcp/policy.js

@@ -0,0 +1,34 @@
+/**
+ * Yomi privacy-policy loader — the single source of truth for the
+ * data-capture disclosure is the repo-root `PRIVACY.md` file, NOT any
+ * string literal in code. Both the MCP server `instructions` (surfaced to
+ * the client/model on connect) and the `get_scope_policy` tool read the
+ * policy prose from here, so the disclosure never drifts between the two.
+ *
+ * The file is read synchronously (so it is available at Server construction
+ * time) and memoized for the process lifetime.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Resolve PRIVACY.md relative to this module (src/mcp/ -> <repo>/PRIVACY.md),
+// NOT process.cwd(): an MCP client may spawn the server from any working
+// directory, so a cwd-relative path would miss the file. Same REPO_ROOT
+// derivation pattern as src/search/store.ts.
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const PRIVACY_PATH = join(REPO_ROOT, 'PRIVACY.md');
+let cachedPolicy = null;
+/**
+ * Read and memoize the canonical privacy-policy text from the repo-root
+ * PRIVACY.md. The prose lives only in that file — this is how both the
+ * server `instructions` and `get_scope_policy` stay in lockstep with a
+ * single edit.
+ *
+ * @returns The full PRIVACY.md contents.
+ */
+export function getPrivacyPolicyText() {
+    if (cachedPolicy === null) {
+        cachedPolicy = readFileSync(PRIVACY_PATH, 'utf8');
+    }
+    return cachedPolicy;
+}