@imenam/mcp-messenger 1.0.32 → 1.0.34

package/dist/src/mcp/start.js

@@ -1,7 +1,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { loadAgentConfig } from "../config.js";
+import { ConfigError, loadAgentConfig } from "../config.js";
 import { MessengerClient, MessengerClientError } from "../client/messenger-client.js";
 import { removeOwnHandoffs } from "../cli/watch-handoff.js";
 import { newId } from "../core/ids.js";
@@ -18,31 +18,31 @@ import { TOOLS, callTool } from "./tools.js";
  * recopier une adresse dans le corps d'un message (le serveur la pose déjà, la copie ment
  * dès qu'elle vieillit). Les dire ici, c'est les dire avant l'erreur.
  */
-const INSTRUCTIONS = `mcp-messenger gives this session a mailbox and lets it exchange messages with other agent sessions.
-
-Two words, two different things, used consistently by every tool here:
-- a **mailbox** is an address (\`box_…\`). It identifies exactly one session, and it is what you write to.
-- an **agent name** is the project a session works for. It is a label, never an address, and every session of that project carries it.
-
-Who you are, and who the others are — read this before writing to anyone:
-- A session is identified by its mailbox address, and by nothing else. \`whoami\` gives you yours.
-- The agent name (e.g. "Ai Corrector Dev") comes from the configuration and says which project the agent works on. It is NOT unique: every session started from that configuration carries it.
-- \`list_agents\` groups mailboxes under their agent name: one group per project, one line per session. A group holding several lines is several live sessions of that project, each with its own address — pick one of those addresses, never the group name.
-- One of those groups may carry the same agent name as yours. Recognising your own agent name there does not mean you are looking at yourself — those are other sessions of the same project, each a different agent with its own mailbox. Compare addresses, never names.
-- Your own mailbox is never listed in \`list_agents\`: every address you see there belongs to someone else.
-
-Resuming earlier work:
-- A resumed session usually keeps the mailbox it had: the address, the threads and the unread messages come back on their own. \`whoami\` says so when it happens.
-- When it cannot be decided automatically, \`whoami\` lists the mailboxes left by a stopped session of this project. If you are continuing that work, call \`attach_to_mailbox\` with the right address.
-- If a \`box_…\` address appears earlier in your own context, from a previous part of this conversation, that is your mailbox from before: attach to it rather than writing from a fresh one, so your correspondents keep reaching you at the address they know.
-
-Linked mailboxes:
-- The user can link this mailbox to others from the web console: those are the correspondents you are meant to work with. \`whoami\` and \`list_links\` list them, and the notification watcher announces each new link as it arrives.
-
-Writing:
-- One message goes to exactly one mailbox, and never to your own. To reach several correspondents, send each one its own message.
-- Never write a mailbox address in the body of a message. The server attaches the sender and the recipient to every message, and the reader sees them: an address copied by hand adds nothing and misleads as soon as it is stale or mistaken.
-- Call \`enable_notifications\` once at the start of the session and arm the watcher it hands you. Until then, no incoming message reaches you.
+const INSTRUCTIONS = `mcp-messenger gives this session a mailbox and lets it exchange messages with other agent sessions.
+
+Two words, two different things, used consistently by every tool here:
+- a **mailbox** is an address (\`box_…\`). It identifies exactly one session, and it is what you write to.
+- an **agent name** is the project a session works for. It is a label, never an address, and every session of that project carries it.
+
+Who you are, and who the others are — read this before writing to anyone:
+- A session is identified by its mailbox address, and by nothing else. \`whoami\` gives you yours.
+- The agent name (e.g. "Ai Corrector Dev") comes from the configuration and says which project the agent works on. It is NOT unique: every session started from that configuration carries it.
+- \`list_agents\` groups mailboxes under their agent name: one group per project, one line per session. A group holding several lines is several live sessions of that project, each with its own address — pick one of those addresses, never the group name.
+- One of those groups may carry the same agent name as yours. Recognising your own agent name there does not mean you are looking at yourself — those are other sessions of the same project, each a different agent with its own mailbox. Compare addresses, never names.
+- Your own mailbox is never listed in \`list_agents\`: every address you see there belongs to someone else.
+
+Resuming earlier work:
+- A resumed session usually keeps the mailbox it had: the address, the threads and the unread messages come back on their own. \`whoami\` says so when it happens.
+- When it cannot be decided automatically, \`whoami\` lists the mailboxes left by a stopped session of this project. If you are continuing that work, call \`attach_to_mailbox\` with the right address.
+- If a \`box_…\` address appears earlier in your own context, from a previous part of this conversation, that is your mailbox from before: attach to it rather than writing from a fresh one, so your correspondents keep reaching you at the address they know.
+
+Linked mailboxes:
+- The user can link this mailbox to others from the web console: those are the correspondents you are meant to work with. \`whoami\` and \`list_links\` list them, and the notification watcher announces each new link as it arrives.
+
+Writing:
+- One message goes to exactly one mailbox, and never to your own. To reach several correspondents, send each one its own message.
+- Never write a mailbox address in the body of a message. The server attaches the sender and the recipient to every message, and the reader sees them: an address copied by hand adds nothing and misleads as soon as it is stale or mistaken.
+- Call \`enable_notifications\` once at the start of the session and arm the watcher it hands you. Until then, no incoming message reaches you.
 - The host stops that watcher after 30 minutes at most. Each time it tells you the watcher expired, re-arm it at once with the same Monitor call; otherwise notifications stop for good.`;
 /** Serveur MCP prêt à être branché sur n'importe quel transport (stdio en production, mémoire en test). */
 export function createMcpServer(client) {
@@ -190,18 +190,28 @@ export async function runMcpMode() {
     const config = loadAgentConfig();
     const client = new MessengerClient(config);
     // Un serveur momentanément injoignable ne doit pas empêcher la session MCP de démarrer :
-    // l'agent verra l'erreur au premier outil appelé, et pourra réessayer.
+    // l'agent verra l'erreur au premier outil appelé, et pourra réessayer. Un refus du
+    // serveur, lui, ne passera pas en réessayant : la clé ou la configuration est à corriger,
+    // et le démarrage s'arrête en le disant.
     try {
         const identity = await resolveIdentity(client, config);
         logger.info(`mailbox \`${identity.mailbox}\` ready on ${config.serverUrl}${describeIdentity(identity, config)}`);
     }
     catch (error) {
-        logger.warn(`could not reach ${config.serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        if (error instanceof MessengerClientError && (error.status === 401 || error.status === 403)) {
+            throw new ConfigError(`the messenger server at ${config.serverUrl} refused this configuration: ${error.message}`);
+        }
+        if (error instanceof MessengerClientError && error.status !== undefined) {
+            logger.warn(`mailbox registration failed on ${config.serverUrl} (HTTP ${error.status}): ${error.message}`);
+        }
+        else {
+            logger.warn(`could not reach ${config.serverUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     // Tant que ce battement continue, la boîte de cette session n'est reprise par personne.
     // `unref` : c'est une trace, pas une raison de garder le processus en vie.
     setInterval(heartbeat, HEARTBEAT_MS).unref();
-    // Le relais vers le veilleur porte le jeton de la session : il ne survit pas à la
+    // Le relais vers le veilleur porte la clé API de la session : il ne survit pas à la
     // session. Un arrêt brutal le laisse en place, la purge par ancienneté le rattrape.
     // L'entrée du registre suit le même sort, à ceci près qu'elle est close et non effacée :
     // c'est elle qui rendra sa boîte à la session suivante.

package/dist/src/mcp/tools.js

@@ -410,7 +410,7 @@ export async function callTool(client, name, rawArgs) {
                 "    messages you send them — tell it to the user if asked, never inside a message body.",
                 self?.agent_name
                     ? `Agent: ${self.agent_name}`
-                    : "Agent: unnamed (set MESSENGER_AGENT_NAME in the MCP configuration)",
+                    : "Agent: unnamed (bind the API key to an agent in the web console, or set MESSENGER_AGENT_NAME)",
                 // Le nom vient de la configuration : toutes les sessions du projet le portent. Le
                 // dire ici évite qu'un agent prenne une session homonyme pour la sienne.
                 "  ↳ this name is shared with every session of the same project; only the address above identifies you.",
@@ -632,7 +632,7 @@ export async function callTool(client, name, rawArgs) {
         }
         case "enable_notifications": {
             const mailbox = client.agentId;
-            writeHandoff({ mailbox, serverUrl: client.serverUrl, token: client.tokenForHandoff });
+            writeHandoff({ mailbox, serverUrl: client.serverUrl, apiKey: client.apiKeyForHandoff });
             const stats = await client.stats().catch(() => null);
             const pending = stats?.folders.find((f) => f.name === "inbox")?.unread ?? 0;
             // Un veilleur déjà en place suffit : en armer un second doublerait chaque

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

@@ -1,15 +1,24 @@
 import express from "express";
 import type { ServerConfig } from "../config.js";
+import type { ApiKey, ConsoleSession, User } from "../core/access-store.js";
 import { MessageStore } from "../core/store.js";
+import { SetupGate } from "./console-session.js";
 declare global {
     namespace Express {
         interface Request {
             agentId?: string;
+            /** Clé API présentée par un agent, une fois vérifiée. */
+            apiKey?: ApiKey;
+            /** Compte et session de la console, une fois la session vérifiée. */
+            consoleUser?: User;
+            consoleSession?: ConsoleSession;
         }
     }
 }
 export interface AppOptions {
     store: MessageStore;
     config: ServerConfig;
+    /** Garde de la création du premier compte ; créée ici quand l'appelant n'en fournit pas. */
+    setup?: SetupGate;
 }
-export declare function createApp({ store, config }: AppOptions): express.Express;
+export declare function createApp({ store, config, setup }: AppOptions): express.Express;

package/dist/src/server/app.js

@@ -2,17 +2,19 @@ import express from "express";
 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 { MAX_ATTACHMENTS, MAX_ATTACHMENTS_TOTAL_BYTES, contentDisposition } from "../core/attachments.js";
+import { PASSWORD_MIN_LENGTH, generateApiKey, generateSessionSecret, hashPassword, verifyPassword, } from "../core/credentials.js";
 import { MessengerError, normalizeAgentId } from "../core/store.js";
 import { PRIORITIES } from "../core/types.js";
 import { WatcherRegistry } from "./watchers.js";
-import { CONSOLE_COOKIE, ConsoleSessions, consoleSessionId } from "./console-session.js";
+import { CONSOLE_COOKIE, PERSISTENT_SESSION_TTL_MS, SESSION_TTL_MS, SetupGate, consoleSessionId, } from "./console-session.js";
 import { APP_VERSION } from "../version.js";
 import { logger } from "../logger.js";
 const UI_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "ui");
+/** Délai pendant lequel une clé remplacée reste acceptée, le temps de mettre le client à jour. */
+const ROTATION_GRACE_MS = 24 * 60 * 60 * 1000;
 const JSON_TYPES = ["application/json", "application/*+json"];
 /** Corps d'un envoi : le texte, plus les pièces jointes encodées en base64 (4 octets pour 3). */
 const SEND_BODY_LIMIT = Math.ceil((MAX_ATTACHMENTS_TOTAL_BYTES * 4) / 3) + 1024 * 1024;
@@ -90,7 +92,60 @@ const waitQuerySchema = z.object({
     // attente longue, mais seul le premier prouve que l'agent est joignable en continu.
     watcher: z.enum(["true", "1"]).optional(),
 });
-const loginSchema = z.object({ token: z.string().min(1).max(1024) });
+const usernameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(100)
+    .regex(/^\S+$/, "a username has no spaces");
+const newPasswordSchema = z
+    .string()
+    .min(PASSWORD_MIN_LENGTH, `at least ${PASSWORD_MIN_LENGTH} characters`)
+    .max(1024);
+const loginSchema = z.object({
+    username: z.string().trim().min(1).max(100),
+    password: z.string().min(1).max(1024),
+    remember: z.boolean().optional(),
+});
+const setupSchema = z.object({
+    code: z.string().trim().min(1).max(64),
+    username: usernameSchema,
+    password: newPasswordSchema,
+});
+const accountSchema = z.object({ username: usernameSchema });
+const passwordChangeSchema = z.object({
+    current_password: z.string().min(1).max(1024),
+    new_password: newPasswordSchema,
+});
+/** Durée de validité d'une clé, en jours ; null = sans échéance. */
+const lifetimeSchema = z.number().int().min(1).max(3650).nullable();
+/** Description de l'agent portée par une clé : une chaîne vide l'efface. */
+const agentDescriptionSchema = z
+    .string()
+    .trim()
+    .max(2000)
+    .nullable()
+    .transform((value) => value || null);
+const keyCreateSchema = z
+    .object({
+    name: z.string().trim().min(1).max(200),
+    /** Agent dont la clé ouvre les boîtes ; null = tous les agents. */
+    agent_name: z.string().trim().min(1).max(200).nullable(),
+    agent_description: agentDescriptionSchema.optional(),
+    lifetime_days: lifetimeSchema,
+})
+    .refine((input) => input.agent_name !== null || !input.agent_description, {
+    message: "only a key bound to an agent carries an agent description",
+});
+const keyPatchSchema = z
+    .object({
+    name: z.string().trim().min(1).max(200).optional(),
+    agent_description: agentDescriptionSchema.optional(),
+})
+    .refine((input) => input.name !== undefined || input.agent_description !== undefined, {
+    message: "provide `name` and/or `agent_description`",
+});
+const keyExtendSchema = z.object({ days: lifetimeSchema });
 const adminThreadsSchema = z.object({
     search: z.string().trim().min(1).optional(),
     // Une ou plusieurs adresses, séparées par des virgules : un agent tient une boîte par
@@ -148,7 +203,8 @@ const adminListSchema = z.object({
     limit: z.coerce.number().int().min(1).max(100).optional(),
     offset: z.coerce.number().int().min(0).optional(),
 });
-export function createApp({ store, config }) {
+export function createApp({ store, config, setup = new SetupGate(store.access) }) {
+    const access = store.access;
     const app = express();
     // Présence des veilleurs : état de connexion, donc en mémoire du processus.
     const watchers = new WatcherRegistry();
@@ -183,9 +239,8 @@ export function createApp({ store, config }) {
     }));
     // --- Console web ----------------------------------------------------------
     // La page et ses fichiers ne contiennent aucun secret : ils sont servis à tous. Ce sont
-    // les données (`/admin`) qui sont protégées, par une session ouverte contre le jeton
-    // admin. Voir `console-session.ts` pour le raisonnement.
-    const sessions = new ConsoleSessions();
+    // les données (`/admin`) qui sont protégées, par une session ouverte avec le compte de
+    // la console. Voir `console-session.ts` pour le raisonnement.
     const cookieOptions = (req) => ({
         httpOnly: true,
         sameSite: "strict",
@@ -195,19 +250,62 @@ export function createApp({ store, config }) {
         secure: req.secure,
         path: "/",
     });
-    // Limite propre au formulaire : le jeton fait 256 bits, mais autant fermer la porte.
-    const loginLimiter = rateLimit({ windowMs: 15 * 60_000, limit: 10, standardHeaders: "draft-8", legacyHeaders: false });
-    app.post("/ui/login", loginLimiter, (req, res) => {
+    /**
+     * Ouvre une session et pose son cookie. Sans « rester connecté », le cookie meurt avec
+     * le navigateur et la session au bout de 12 h ; avec, les deux tiennent 30 jours.
+     */
+    const openSession = (req, res, user, persistent) => {
+        const secret = generateSessionSecret();
+        const ttlMs = persistent ? PERSISTENT_SESSION_TTL_MS : SESSION_TTL_MS;
+        access.createSession({
+            userId: user.id,
+            secret,
+            ttlMs,
+            persistent,
+            userAgent: req.header("user-agent") ?? null,
+            ip: req.ip ?? null,
+        });
+        res.cookie(CONSOLE_COOKIE, secret, persistent ? { ...cookieOptions(req), maxAge: ttlMs } : cookieOptions(req));
+    };
+    // Limite propre aux formulaires : un mot de passe se devine, autant ralentir qui essaie.
+    const formLimiter = credentialsLimiter();
+    // Ce que la console doit afficher en arrivant : la création du compte, la connexion,
+    // ou directement ses données.
+    app.get("/ui/session", (req, res) => {
+        const found = access.findSession(consoleSessionId(req), { ip: req.ip ?? null });
+        res.json({
+            authenticated: Boolean(found),
+            setup_required: setup.required,
+            user: found ? found.user : null,
+        });
+    });
+    app.post("/ui/setup", formLimiter, async (req, res) => {
+        const input = setupSchema.parse(req.body ?? {});
+        if (!setup.required)
+            throw new MessengerError("the console account already exists", 409);
+        if (!setup.accepts(input.code))
+            throw new MessengerError("wrong setup code", 403);
+        const user = access.createUser(input.username, await hashPassword(input.password));
+        setup.consume();
+        logger.info(`console account created: ${user.username}`);
+        openSession(req, res, user, false);
+        res.status(201).json({ user });
+    });
+    app.post("/ui/login", formLimiter, async (req, res) => {
         const input = loginSchema.parse(req.body ?? {});
-        if (!safeEqual(input.token, config.adminToken)) {
-            res.status(401).json({ error: "invalid admin token" });
+        const found = access.findUserByName(input.username);
+        // Un nom inconnu coûte le même calcul qu'un mot de passe faux : la durée de la réponse
+        // ne dit pas si le compte existe.
+        const valid = await verifyPassword(input.password, found?.password_hash ?? (await decoyHash()));
+        if (!found || !valid) {
+            res.status(401).json({ error: "invalid username or password" });
             return;
         }
-        res.cookie(CONSOLE_COOKIE, sessions.create(), { ...cookieOptions(req), maxAge: sessions.ttlMs });
+        openSession(req, res, access.getUser(found.id), input.remember ?? false);
         res.status(204).end();
     });
     app.post("/ui/logout", (req, res) => {
-        sessions.revoke(consoleSessionId(req));
+        access.revokeSessionBySecret(consoleSessionId(req));
         res.clearCookie(CONSOLE_COOKIE, cookieOptions(req));
         res.status(204).end();
     });
@@ -218,10 +316,10 @@ export function createApp({ store, config }) {
         res.redirect("/ui/");
     });
     // --- Supervision (lecture, liaisons et nettoyages de boîtes) -------------
-    // Montée avant la porte d'entrée : son contrôle est au moins aussi strict (session de
-    // console ou jeton admin), et la session par cookie n'est reconnue nulle part ailleurs.
+    // Montée avant la porte d'entrée des agents : `/admin` ne s'ouvre qu'avec une session de
+    // la console, et la session par cookie n'est reconnue nulle part ailleurs.
     const admin = express.Router();
-    admin.use(authenticateAdmin(config, sessions));
+    admin.use(authenticateConsole(store));
     admin.get("/overview", (_req, res) => {
         res.json(store.overview());
     });
@@ -362,10 +460,98 @@ export function createApp({ store, config }) {
         logger.info(`admin unlink ${linkId}`);
         res.json({ link_id: linkId });
     });
+    // --- Compte de la console -------------------------------------------------
+    admin.get("/account", (req, res) => {
+        const user = req.consoleUser;
+        res.json({
+            user,
+            sessions: access.listSessions(user.id).map((session) => ({
+                ...session,
+                current: session.id === req.consoleSession.id,
+            })),
+        });
+    });
+    admin.patch("/account", (req, res) => {
+        const input = accountSchema.parse(req.body ?? {});
+        const user = access.renameUser(req.consoleUser.id, input.username);
+        logger.info(`console account renamed: ${req.consoleUser.username} -> ${user.username}`);
+        res.json({ user });
+    });
+    /** Changer de mot de passe ferme toutes les autres sessions : c'est souvent la raison du changement. */
+    admin.post("/account/password", formLimiter, async (req, res) => {
+        const input = passwordChangeSchema.parse(req.body ?? {});
+        const user = req.consoleUser;
+        if (!(await verifyPassword(input.current_password, access.getPasswordHash(user.id) ?? ""))) {
+            throw new MessengerError("the current password is wrong", 403);
+        }
+        access.setPassword(user.id, await hashPassword(input.new_password));
+        const closed = access.revokeOtherSessions(user.id, req.consoleSession.id);
+        logger.info(`console password changed for ${user.username}, ${closed} other session(s) closed`);
+        res.json({ closed_sessions: closed });
+    });
+    admin.delete("/account/sessions/:id", (req, res) => {
+        const id = String(req.params.id);
+        access.revokeSession(req.consoleUser.id, id);
+        res.json({ session_id: id });
+    });
+    admin.post("/account/sessions/revoke-others", (req, res) => {
+        res.json({ closed_sessions: access.revokeOtherSessions(req.consoleUser.id, req.consoleSession.id) });
+    });
+    // --- Clés API -------------------------------------------------------------
+    admin.get("/keys", (_req, res) => {
+        res.json({ keys: access.listApiKeys() });
+    });
+    /** La clé en clair ne sort qu'ici, une fois : le serveur n'en garde que l'empreinte. */
+    admin.post("/keys", (req, res) => {
+        const input = keyCreateSchema.parse(req.body ?? {});
+        const secret = generateApiKey();
+        const key = access.createApiKey({
+            name: input.name,
+            agentName: input.agent_name,
+            agentDescription: input.agent_description ?? null,
+            lifetimeDays: input.lifetime_days,
+            createdBy: req.consoleUser.username,
+            secret,
+        });
+        logger.info(`API key ${key.id} created (${key.name}, ${key.agent_name ?? "all agents"})`);
+        res.status(201).json({ key, secret });
+    });
+    admin.get("/keys/:id", (req, res) => {
+        const id = String(req.params.id);
+        const key = access.getApiKey(id);
+        if (!key)
+            throw new MessengerError(`API key not found: ${id}`, 404);
+        res.json({ key, mailboxes: access.mailboxesForKey(id) });
+    });
+    admin.patch("/keys/:id", (req, res) => {
+        const input = keyPatchSchema.parse(req.body ?? {});
+        const id = String(req.params.id);
+        let key = input.name !== undefined ? access.renameApiKey(id, input.name) : null;
+        if (input.agent_description !== undefined)
+            key = access.setApiKeyAgentDescription(id, input.agent_description);
+        res.json({ key });
+    });
+    admin.post("/keys/:id/extend", (req, res) => {
+        const input = keyExtendSchema.parse(req.body ?? {});
+        const key = access.extendApiKey(String(req.params.id), input.days);
+        logger.info(`API key ${key.id} extended until ${key.expires_at ?? "no expiry"}`);
+        res.json({ key });
+    });
+    admin.post("/keys/:id/rotate", (req, res) => {
+        const secret = generateApiKey();
+        const { key, replaced } = access.rotateApiKey(String(req.params.id), secret, req.consoleUser.username, ROTATION_GRACE_MS);
+        logger.info(`API key ${replaced.id} replaced by ${key.id}, old one valid until ${replaced.expires_at}`);
+        res.status(201).json({ key, secret, replaced });
+    });
+    admin.post("/keys/:id/revoke", (req, res) => {
+        const key = access.revokeApiKey(String(req.params.id));
+        logger.warn(`API key ${key.id} revoked (${key.name})`);
+        res.json({ key });
+    });
     app.use("/admin", admin);
-    // Porte d'entrée de tout le reste : aucune requête n'est servie sans jeton valide. Le
-    // contrôle par route (identité de l'agent) vient ensuite.
-    app.use(requireAnyToken(config));
+    // Porte d'entrée de tout le reste : aucune requête n'est servie sans clé API valide. Le
+    // contrôle par route (boîtes que la clé ouvre) vient ensuite.
+    app.use(requireApiKey(store));
     // --- État du service ------------------------------------------------------
     app.get("/health", (_req, res) => {
         const overview = store.overview();
@@ -375,27 +561,42 @@ export function createApp({ store, config }) {
             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.
+            // Toujours vrai : cette route, comme toute l'API, exige une clé.
             auth_required: true,
         });
     });
     // --- API agents -----------------------------------------------------------
     const api = express.Router();
-    api.use(authenticateAgent(config));
+    api.use(authenticateAgent(store));
     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);
         }
+        // Une clé liée à un agent donne son nom et sa description à la boîte. Une autre valeur
+        // venue de la configuration du client est une erreur de réglage, signalée plutôt que
+        // corrigée.
+        const key = req.apiKey;
+        if (key.agent_name) {
+            if (input.agent_name && input.agent_name !== key.agent_name) {
+                throw new MessengerError(`this API key is bound to agent "${key.agent_name}": remove MESSENGER_AGENT_NAME from the client ` +
+                    `configuration, or set it to "${key.agent_name}"`, 403);
+            }
+            if (input.agent_description && input.agent_description !== key.agent_description) {
+                throw new MessengerError(`this API key carries the description of agent "${key.agent_name}": remove MESSENGER_AGENT_DESCRIPTION ` +
+                    "from the client configuration, and edit the description in the web console", 403);
+            }
+        }
         const agent = store.ensureAgent(req.agentId, {
             registered: true,
-            agent_name: input.agent_name ?? null,
-            agent_description: input.agent_description ?? null,
+            agent_name: key.agent_name ?? input.agent_name ?? null,
+            agent_description: key.agent_name ? key.agent_description : (input.agent_description ?? null),
             // Un client antérieur à la séparation agent / boîte n'envoie que ces deux-là.
             display_name: input.display_name ?? null,
             description: input.description ?? null,
         });
+        access.recordMailboxKey(agent.id, key.id);
         res.json({ agent });
     });
     // L'agent ne se voit pas dans son propre annuaire : sa boîte est la seule interdite d'envoi.
@@ -581,25 +782,53 @@ function sendAttachment(res, attachment) {
     res.end(attachment.data);
 }
 /**
- * Exige un jeton connu du serveur sur toute requête entrante.
+ * Limite des formulaires d'identifiants : dix essais par quart d'heure et par adresse. Le
+ * refus dit dans combien de secondes réessayer, pour que la console puisse l'afficher.
+ */
+function credentialsLimiter() {
+    return rateLimit({
+        windowMs: 15 * 60_000,
+        limit: 10,
+        standardHeaders: "draft-8",
+        legacyHeaders: false,
+        handler: (req, res) => {
+            const reset = req.rateLimit?.resetTime?.getTime();
+            const retryAfter = reset ? Math.max(1, Math.ceil((reset - Date.now()) / 1000)) : 15 * 60;
+            res.status(429).json({ error: "too many attempts", retry_after_seconds: retryAfter });
+        },
+    });
+}
+let decoy = null;
+/** Empreinte jetable, vérifiée quand le compte demandé n'existe pas. */
+function decoyHash() {
+    decoy ??= hashPassword(generateSessionSecret());
+    return decoy;
+}
+/**
+ * Exige une clé API active 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.
+ * C'est le filtre grossier : il dit que l'appelant est un agent connu. Ce que la clé
+ * l'autorise à ouvrir est vérifié juste après, par `authenticateAgent`.
  */
-function requireAnyToken(config) {
-    const accepted = [config.token, config.adminToken, ...config.agentTokens.values()].filter((value) => Boolean(value));
+function requireApiKey(store) {
     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" });
+        const key = store.access.authenticateApiKey(presentedKey(req), req.ip ?? null);
+        if (!key) {
+            res.status(401).json({ error: "invalid, expired or revoked API key" });
             return;
         }
+        req.apiKey = key;
         next();
     };
 }
-/** Identité de l'agent (en-tête `X-Agent-Id`) + jeton, selon la configuration du serveur. */
-function authenticateAgent(config) {
+/**
+ * Boîte visée (en-tête `X-Agent-Id`), et droit de la clé sur elle.
+ *
+ * Une clé liée à un agent n'ouvre que les boîtes de cet agent, plus celles qui n'ont encore
+ * jamais été ouvertes. Une clé valable pour tous les agents les ouvre toutes, comme la
+ * console l'annonce en la créant.
+ */
+function authenticateAgent(store) {
     return (req, res, next) => {
         const agentId = normalizeAgentId(String(req.header("x-agent-id") ?? ""));
         if (!agentId) {
@@ -610,59 +839,39 @@ function authenticateAgent(config) {
             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" });
+        const key = req.apiKey;
+        if (key.agent_name) {
+            const mailbox = store.getAgent(agentId);
+            if (mailbox?.registered && mailbox.agent_name !== key.agent_name) {
+                res.status(403).json({ error: `this API key only opens mailboxes of agent "${key.agent_name}"` });
                 return;
             }
-            // Le jeton partagé atteste l'appartenance à la flotte, pas une adresse : `X-Agent-Id`
-            // n'est adossé à rien ici, et rien ne cloisonne les boîtes entre elles. C'est le mode
-            // « cercle de confiance », annoncé comme tel au démarrage et dans le README ;
-            // MESSENGER_AGENT_TOKENS est ce qui lie une adresse à un jeton.
         }
         req.agentId = agentId;
         next();
     };
 }
-/** Session de console (navigateur) ou jeton admin (script, `curl`). */
-function authenticateAdmin(config, sessions) {
+/** Session de la console, ouverte avec le compte. Rien d'autre n'ouvre `/admin`. */
+function authenticateConsole(store) {
     return (req, res, next) => {
-        if (sessions.has(consoleSessionId(req))) {
-            next();
-            return;
-        }
-        const presented = presentedToken(req);
-        if (!presented || !safeEqual(presented, config.adminToken)) {
-            res.status(401).json({ error: "invalid or missing admin token" });
+        const found = store.access.findSession(consoleSessionId(req), { ip: req.ip ?? null });
+        if (!found) {
+            res.status(401).json({ error: "console session required" });
             return;
         }
+        req.consoleUser = found.user;
+        req.consoleSession = found.session;
         next();
     };
 }
 /**
- * Jeton présenté par l'appelant : en-tête `Authorization`, sinon `X-Messenger-Token`.
- * Jamais l'URL : un jeton en query string finit dans les journaux d'accès du proxy.
+ * Clé présentée par l'appelant : en-tête `Authorization`, sinon `X-Messenger-Token`.
+ * Jamais l'URL : une clé en query string finit dans les journaux d'accès du proxy.
  */
-function presentedToken(req) {
+function presentedKey(req) {
     const header = req.header("authorization");
     if (header?.toLowerCase().startsWith("bearer "))
         return header.slice(7).trim() || null;
     const alt = req.header("x-messenger-token");
     return alt?.trim() ? alt.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);
-}