@imenam/mcp-messenger 1.0.1

package/dist/src/server/app.js

@@ -0,0 +1,375 @@
+import express from "express";
+import fs from "node:fs";
+import helmet from "helmet";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { timingSafeEqual } from "node:crypto";
+import { rateLimit } from "express-rate-limit";
+import { z } from "zod";
+import { MessengerError, normalizeAgentId } from "../core/store.js";
+import { PRIORITIES } from "../core/types.js";
+import { APP_VERSION } from "../version.js";
+import { logger } from "../logger.js";
+const UI_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "ui");
+const agentIdSchema = z.string().trim().min(1).max(128);
+const idListSchema = z.array(z.string().trim().min(1)).min(1).max(200);
+const registerSchema = z.object({
+    display_name: z.string().trim().max(200).nullish(),
+    description: z.string().trim().max(2000).nullish(),
+    /** true = l'adresse doit être inconnue du serveur (allocation d'une boîte neuve). */
+    fresh: z.boolean().optional(),
+});
+const sendSchema = z.object({
+    to: z.union([agentIdSchema, z.array(agentIdSchema).min(1)]),
+    cc: z.union([agentIdSchema, z.array(agentIdSchema)]).optional(),
+    subject: z.string().min(1).max(500),
+    body: z.string().min(1).max(200_000),
+    priority: z.enum(PRIORITIES).optional(),
+    reply_to: z.string().trim().min(1).nullish(),
+});
+const listQuerySchema = z.object({
+    folder: z.string().trim().min(1).optional(),
+    unread_only: z.coerce.boolean().optional(),
+    thread_id: z.string().trim().min(1).optional(),
+    from: z.string().trim().min(1).optional(),
+    search: z.string().trim().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    offset: z.coerce.number().int().min(0).optional(),
+});
+const markSchema = z
+    .object({
+    message_ids: idListSchema,
+    read: z.boolean().optional(),
+    starred: z.boolean().optional(),
+})
+    .refine((v) => v.read !== undefined || v.starred !== undefined, {
+    message: "provide `read` and/or `starred`",
+});
+const moveSchema = z.object({ message_ids: idListSchema, folder: z.string().trim().min(1) });
+const deleteSchema = z.object({ message_ids: idListSchema, permanent: z.boolean().optional() });
+const folderSchema = z.object({ name: z.string().trim().min(1).max(40) });
+const waitQuerySchema = z.object({
+    timeout_seconds: z.coerce.number().int().min(1).optional(),
+    folder: z.string().trim().min(1).optional(),
+});
+const adminListSchema = z.object({
+    search: z.string().trim().min(1).optional(),
+    agent: z.string().trim().min(1).optional(),
+    thread_id: z.string().trim().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    offset: z.coerce.number().int().min(0).optional(),
+});
+export function createApp({ store, config }) {
+    const app = express();
+    app.disable("x-powered-by");
+    app.set("trust proxy", false);
+    app.use(helmet({
+        contentSecurityPolicy: {
+            directives: {
+                defaultSrc: ["'self'"],
+                scriptSrc: ["'self'"],
+                styleSrc: ["'self'"],
+                imgSrc: ["'self'", "data:"],
+                connectSrc: ["'self'"],
+                objectSrc: ["'none'"],
+                frameAncestors: ["'none'"],
+            },
+        },
+        crossOriginEmbedderPolicy: false,
+    }));
+    app.use(express.json({ type: ["application/json", "application/*+json"], limit: "2mb" }));
+    app.use(rateLimit({
+        windowMs: config.rateLimit.windowMs,
+        limit: config.rateLimit.max,
+        standardHeaders: "draft-8",
+        legacyHeaders: false,
+    }));
+    // Porte d'entrée unique : aucune requête, quelle qu'elle soit, n'est servie sans
+    // jeton valide. Les contrôles par route (identité de l'agent, console) viennent ensuite.
+    app.use(requireAnyToken(config));
+    // --- État du service ------------------------------------------------------
+    app.get("/health", (_req, res) => {
+        const overview = store.overview();
+        res.json({
+            status: "ok",
+            service: "mcp-messenger",
+            version: APP_VERSION,
+            agents: overview.agents.length,
+            messages: overview.messages,
+            // Toujours vrai : le serveur ne démarre pas sans jeton, et cette route en exige un.
+            auth_required: true,
+        });
+    });
+    // --- API agents -----------------------------------------------------------
+    const api = express.Router();
+    api.use(authenticateAgent(config));
+    api.post("/agents/register", (req, res) => {
+        const input = registerSchema.parse(req.body ?? {});
+        // Une session qui alloue sa propre boîte ne doit jamais tomber sur celle d'une autre.
+        if (input.fresh && store.getAgent(req.agentId)) {
+            throw new MessengerError(`mailbox already exists: ${req.agentId}`, 409);
+        }
+        const agent = store.ensureAgent(req.agentId, {
+            registered: true,
+            display_name: input.display_name ?? null,
+            description: input.description ?? null,
+        });
+        res.json({ agent });
+    });
+    api.get("/agents", (_req, res) => {
+        res.json({ agents: store.listAgents() });
+    });
+    api.patch("/agents/me", (req, res) => {
+        const input = registerSchema.parse(req.body ?? {});
+        res.json({
+            agent: store.ensureAgent(req.agentId, {
+                registered: true,
+                display_name: input.display_name ?? null,
+                description: input.description ?? null,
+            }),
+        });
+    });
+    api.get("/agents/:id", (req, res) => {
+        const agent = store.getAgent(String(req.params.id));
+        if (!agent)
+            throw new MessengerError(`mailbox not found: ${req.params.id}`, 404);
+        res.json({ agent });
+    });
+    api.get("/mailbox", (req, res) => {
+        res.json(store.stats(req.agentId));
+    });
+    api.post("/messages", (req, res) => {
+        const input = sendSchema.parse(req.body ?? {});
+        const result = store.sendMessage({
+            from: req.agentId,
+            to: toArray(input.to),
+            cc: toArray(input.cc),
+            subject: input.subject,
+            body: input.body,
+            priority: input.priority,
+            reply_to: input.reply_to ?? null,
+        });
+        logger.info(`message ${result.message_id}: ${req.agentId} -> ${result.delivered_to.join(", ")}`);
+        res.status(201).json(result);
+    });
+    api.get("/messages", (req, res) => {
+        const query = listQuerySchema.parse(req.query);
+        res.json({ messages: store.listMessages(req.agentId, query) });
+    });
+    api.post("/messages/mark", (req, res) => {
+        const input = markSchema.parse(req.body ?? {});
+        const updated = store.markMessages(req.agentId, input.message_ids, { read: input.read, starred: input.starred });
+        res.json({ updated });
+    });
+    api.post("/messages/move", (req, res) => {
+        const input = moveSchema.parse(req.body ?? {});
+        res.json({ updated: store.moveMessages(req.agentId, input.message_ids, input.folder.toLowerCase()) });
+    });
+    api.post("/messages/delete", (req, res) => {
+        const input = deleteSchema.parse(req.body ?? {});
+        res.json({ deleted: store.deleteMessages(req.agentId, input.message_ids, input.permanent ?? false) });
+    });
+    api.get("/messages/:id", (req, res) => {
+        const markRead = req.query.mark_read !== "false";
+        res.json(store.getMessage(req.agentId, String(req.params.id), markRead));
+    });
+    api.get("/threads/:id", (req, res) => {
+        res.json({ thread_id: req.params.id, messages: store.getThread(req.agentId, String(req.params.id)) });
+    });
+    api.get("/folders", (req, res) => {
+        res.json({ folders: store.listFolders(req.agentId) });
+    });
+    api.post("/folders", (req, res) => {
+        const input = folderSchema.parse(req.body ?? {});
+        res.status(201).json({ folder: store.createFolder(req.agentId, input.name) });
+    });
+    api.delete("/folders/:name", (req, res) => {
+        res.json({ moved: store.deleteFolder(req.agentId, String(req.params.name)) });
+    });
+    // Attente longue : la réponse part dès qu'un message arrive, sinon au bout du délai.
+    api.get("/wait", (req, res) => {
+        const { timeout_seconds, folder } = waitQuerySchema.parse(req.query);
+        const agentId = req.agentId;
+        const timeoutSeconds = Math.min(timeout_seconds ?? 30, config.maxWaitSeconds);
+        const pending = store.listMessages(agentId, { folder: folder ?? "inbox", unread_only: true, limit: 1 });
+        const first = pending[0];
+        if (first) {
+            res.json({ timed_out: false, message: store.getMessage(agentId, first.message_id, false) });
+            return;
+        }
+        const done = (payload) => {
+            clearTimeout(timer);
+            store.off("message", onMessage);
+            req.off("close", onClose);
+            if (!res.headersSent)
+                res.json(payload);
+        };
+        const onMessage = (event) => {
+            if (event.agent_id !== agentId)
+                return;
+            if (folder && event.folder !== folder)
+                return;
+            if (!folder && event.folder !== "inbox")
+                return;
+            done({ timed_out: false, message: store.getMessage(agentId, event.message_id, false) });
+        };
+        const onClose = () => {
+            clearTimeout(timer);
+            store.off("message", onMessage);
+        };
+        const timer = setTimeout(() => done({ timed_out: true, message: null }), timeoutSeconds * 1000);
+        store.on("message", onMessage);
+        req.once("close", onClose);
+    });
+    app.use("/api", api);
+    // --- Supervision (lecture seule) -----------------------------------------
+    const admin = express.Router();
+    admin.use(authenticateAdmin(config));
+    admin.get("/overview", (_req, res) => {
+        res.json(store.overview());
+    });
+    admin.get("/messages", (req, res) => {
+        const query = adminListSchema.parse(req.query);
+        res.json({ messages: store.listAllMessages(query) });
+    });
+    admin.get("/messages/:id", (req, res) => {
+        res.json(store.getMessageAdmin(String(req.params.id)));
+    });
+    admin.get("/threads/:id", (req, res) => {
+        const messages = store.listAllMessages({ thread_id: String(req.params.id), limit: 100 });
+        if (messages.length === 0)
+            throw new MessengerError(`thread not found: ${req.params.id}`, 404);
+        res.json({ thread_id: req.params.id, messages: messages.slice().reverse() });
+    });
+    app.use("/admin", admin);
+    // --- Interface web --------------------------------------------------------
+    // Un navigateur ne peut pas poser d'en-tête sur une navigation : la console s'ouvre
+    // donc avec `?token=`. La page est servie avec ce jeton propagé sur ses ressources,
+    // sans quoi le CSS et le script seraient refusés par la porte d'entrée.
+    app.get(["/ui", "/ui/", "/ui/index.html"], (req, res, next) => {
+        const token = presentedToken(req);
+        if (!token) {
+            next();
+            return;
+        }
+        fs.readFile(path.join(UI_DIR, "index.html"), "utf-8", (error, html) => {
+            if (error) {
+                next(error);
+                return;
+            }
+            const suffix = `?token=${encodeURIComponent(token)}`;
+            res.type("html").send(html.replaceAll("./styles.css", `./styles.css${suffix}`).replaceAll("./app.js", `./app.js${suffix}`));
+        });
+    });
+    // `maxAge: 0` + ETag : la console reflète immédiatement une mise à jour du paquet,
+    // sans laisser un navigateur servir l'ancienne version depuis son cache.
+    app.use("/ui", express.static(UI_DIR, { index: false, maxAge: 0, etag: true }));
+    app.get("/", (req, res) => {
+        const token = presentedToken(req);
+        res.redirect(token ? `/ui/?token=${encodeURIComponent(token)}` : "/ui/");
+    });
+    // --- Erreurs --------------------------------------------------------------
+    app.use((_req, res) => {
+        res.status(404).json({ error: "not found" });
+    });
+    app.use((err, _req, res, _next) => {
+        if (err instanceof MessengerError) {
+            res.status(err.status).json({ error: err.message });
+            return;
+        }
+        if (err instanceof z.ZodError) {
+            res.status(400).json({ error: "invalid request", details: z.treeifyError(err) });
+            return;
+        }
+        logger.error("unhandled error", err);
+        // Le détail reste dans les logs : la réponse ne doit rien révéler de l'hôte.
+        res.status(500).json({ error: "internal server error" });
+    });
+    return app;
+}
+function toArray(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Exige un jeton connu du serveur sur toute requête entrante.
+ *
+ * Accepte le jeton partagé, le jeton de la console, ou celui de n'importe quel agent :
+ * c'est le filtre grossier. La correspondance jeton ↔ agent est vérifiée juste après,
+ * route par route.
+ */
+function requireAnyToken(config) {
+    const accepted = [config.token, config.adminToken, ...config.agentTokens.values()].filter((value) => Boolean(value));
+    return (req, res, next) => {
+        const presented = presentedToken(req);
+        if (!presented || !accepted.some((candidate) => safeEqual(presented, candidate))) {
+            res.status(401).json({ error: "invalid or missing token" });
+            return;
+        }
+        next();
+    };
+}
+/** Identité de l'agent (en-tête `X-Agent-Id`) + jeton, selon la configuration du serveur. */
+function authenticateAgent(config) {
+    return (req, res, next) => {
+        const agentId = normalizeAgentId(String(req.header("x-agent-id") ?? ""));
+        if (!agentId) {
+            res.status(401).json({ error: "missing X-Agent-Id header" });
+            return;
+        }
+        if (agentId.length > 128) {
+            res.status(400).json({ error: "agent id too long (max 128 chars)" });
+            return;
+        }
+        const presented = presentedToken(req);
+        if (config.agentTokens.size > 0) {
+            const expected = config.agentTokens.get(agentId);
+            if (!expected || !presented || !safeEqual(presented, expected)) {
+                res.status(401).json({ error: "invalid credentials for this agent" });
+                return;
+            }
+        }
+        else if (config.token) {
+            if (!presented || !safeEqual(presented, config.token)) {
+                res.status(401).json({ error: "invalid or missing bearer token" });
+                return;
+            }
+        }
+        req.agentId = agentId;
+        next();
+    };
+}
+function authenticateAdmin(config) {
+    return (req, res, next) => {
+        const presented = presentedToken(req);
+        if (!presented || !safeEqual(presented, config.adminToken)) {
+            res.status(401).json({ error: "invalid or missing admin token" });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Jeton présenté par l'appelant, dans l'ordre de préférence : en-tête `Authorization`,
+ * en-tête `X-Messenger-Token`, puis paramètre `?token=` — ce dernier existe pour la
+ * navigation navigateur vers la console, qui ne peut pas poser d'en-tête.
+ */
+function presentedToken(req) {
+    const header = req.header("authorization");
+    if (header?.toLowerCase().startsWith("bearer "))
+        return header.slice(7).trim() || null;
+    const alt = req.header("x-messenger-token");
+    if (alt?.trim())
+        return alt.trim();
+    const query = req.query.token;
+    return typeof query === "string" && query.trim() ? query.trim() : null;
+}
+/** Comparaison à temps constant : évite de laisser fuiter le jeton octet par octet. */
+function safeEqual(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}

package/dist/src/server/start.d.ts

@@ -0,0 +1,14 @@
+import type { Server } from "node:http";
+import { type ServerConfig } from "../config.js";
+import { MessageStore } from "../core/store.js";
+export interface RunningServer {
+    server: Server;
+    store: MessageStore;
+    config: ServerConfig;
+    url: string;
+    close: () => Promise<void>;
+}
+/** Démarre la boîte aux lettres. `port: 0` laisse l'OS choisir (utilisé par les tests). */
+export declare function startServer(config?: ServerConfig): Promise<RunningServer>;
+/** Point d'entrée du mode serveur (`mcp-messenger --server`). */
+export declare function runServerMode(): Promise<void>;

package/dist/src/server/start.js

@@ -0,0 +1,64 @@
+import { createApp } from "./app.js";
+import { loadServerConfig } from "../config.js";
+import { MessageStore } from "../core/store.js";
+import { logger } from "../logger.js";
+import { APP_VERSION } from "../version.js";
+/** Démarre la boîte aux lettres. `port: 0` laisse l'OS choisir (utilisé par les tests). */
+export async function startServer(config = loadServerConfig()) {
+    const store = new MessageStore(config.dbPath);
+    const app = createApp({ store, config });
+    const server = await new Promise((resolve, reject) => {
+        const httpServer = app.listen(config.port, config.host, () => resolve(httpServer));
+        httpServer.once("error", reject);
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : config.port;
+    const url = `http://${config.host}:${port}`;
+    // Purge quotidienne de la corbeille ; `unref` pour ne pas retenir le process.
+    const purgeTimer = setInterval(() => {
+        try {
+            const removed = store.purgeTrash(config.trashRetentionDays);
+            if (removed > 0)
+                logger.info(`purged ${removed} trashed deliveries`);
+        }
+        catch (error) {
+            logger.error("trash purge failed", error);
+        }
+    }, 24 * 3600_000);
+    purgeTimer.unref();
+    const close = async () => {
+        clearInterval(purgeTimer);
+        await new Promise((resolve) => server.close(() => resolve()));
+        store.close();
+    };
+    return { server, store, config, url, close };
+}
+/** Point d'entrée du mode serveur (`mcp-messenger --server`). */
+export async function runServerMode() {
+    const config = loadServerConfig();
+    const running = await startServer(config);
+    const authMode = config.agentTokens.size > 0
+        ? `per-agent tokens (${config.agentTokens.size})${config.token ? " + shared token" : ""}`
+        : "shared token";
+    logger.info(`mcp-messenger v${APP_VERSION} listening on ${running.url} (loopback only)`);
+    logger.info(`database: ${config.dbPath}`);
+    logger.info(`auth: ${authMode} — required on every request`);
+    // Le jeton n'est pas écrit dans les logs : seule sa provenance est rappelée.
+    logger.info(`web console: ${running.url}/ui/?token=<MESSENGER_ADMIN_TOKEN>`);
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger.info(`${signal} received, shutting down`);
+        running
+            .close()
+            .then(() => process.exit(0))
+            .catch((error) => {
+            logger.error("shutdown failed", error);
+            process.exit(1);
+        });
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+}