mcp-coordinator 0.6.0 → 0.7.0

package/dist/src/introspection.js

@@ -1,28 +1,51 @@
 import { randomUUID } from "crypto";
 import { getDb } from "./database.js";
 export class IntrospectionManager {
-    create(params) {
+    create(orgId, params) {
         const db = getDb();
         const id = randomUUID();
-        db.prepare(`INSERT INTO introspections (id, thread_id, agent_id, score, reasons)
-       VALUES (?, ?, ?, ?, ?)`).run(id, params.thread_id, params.agent_id, params.score, JSON.stringify(params.reasons));
+        const reasons = params.reasons == null
+            ? null
+            : Array.isArray(params.reasons)
+                ? JSON.stringify(params.reasons)
+                : params.reasons;
+        db.prepare(`INSERT INTO introspections (id, org_id, thread_id, agent_id, score, reasons)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(id, orgId, params.thread_id, params.agent_id, params.score, reasons);
         return this.get(id);
     }
-    respond(id, concerned, response) {
+    respond(orgId, id, response) {
         const db = getDb();
-        db.prepare(`UPDATE introspections SET status = ?, concerned = ?, response = ?, responded_at = ? WHERE id = ?`).run(concerned ? "concerned" : "not_concerned", concerned ? 1 : 0, response, new Date().toISOString(), id);
-        return this.get(id);
+        db.prepare(`UPDATE introspections SET response = ?, status = 'responded', responded_at = ? WHERE org_id = ? AND id = ?`).run(response, new Date().toISOString(), orgId, id);
+        return this.getScoped(orgId, id);
     }
+    /** Retrieve a single record by id (unscoped — internal helper only). */
     get(id) {
         const db = getDb();
-        return db.prepare("SELECT * FROM introspections WHERE id = ?").get(id) || null;
+        return (db
+            .prepare("SELECT * FROM introspections WHERE id = ?")
+            .get(id) || null);
+    }
+    /** Retrieve a single record scoped to an org. */
+    getScoped(orgId, id) {
+        const db = getDb();
+        return (db
+            .prepare("SELECT * FROM introspections WHERE org_id = ? AND id = ?")
+            .get(orgId, id) || null);
     }
-    getPending(agentId) {
+    getPending(orgId, agentId) {
         const db = getDb();
-        return db.prepare("SELECT * FROM introspections WHERE agent_id = ? AND status = 'pending' ORDER BY created_at").all(agentId);
+        return db
+            .prepare("SELECT * FROM introspections WHERE org_id = ? AND agent_id = ? AND status = 'pending' ORDER BY created_at")
+            .all(orgId, agentId);
     }
-    getByThread(threadId) {
+    list(orgId, threadId) {
         const db = getDb();
-        return db.prepare("SELECT * FROM introspections WHERE thread_id = ? ORDER BY created_at").all(threadId);
+        return db
+            .prepare("SELECT * FROM introspections WHERE org_id = ? AND thread_id = ? ORDER BY created_at")
+            .all(orgId, threadId);
+    }
+    /** @deprecated Use list(orgId, threadId) instead. Kept for backward compat. */
+    getByThread(orgId, threadId) {
+        return this.list(orgId, threadId);
     }
 }

package/dist/src/metrics.js

@@ -145,7 +145,8 @@ export class Metrics {
      */
     gaugeSnapshot(services) {
         try {
-            this.agentsOnline.set(services.registry.listOnline().length);
+            // TODO(Task 23.5): thread real org_id from MCP session claims; for now MCP uses 'default' (cross-org leak window — single-tenant only)
+            this.agentsOnline.set(services.registry.listOnline("default").length);
         }
         catch {
             // Registry not initialised yet (test bootstrap race) — leave gauge at 0.

package/dist/src/mqtt-bridge.d.ts

@@ -5,6 +5,7 @@ interface QueuedMessage {
     timestamp: number;
 }
 export declare class MqttBridge {
+    private orgId;
     private client;
     private connected;
     private onOfflineHandler;
@@ -12,13 +13,13 @@ export declare class MqttBridge {
     private log;
     private agentId;
     /**
-     * P1: track the last threadId we retained on `coordinator/consultations/new`.
+     * P1: track the last threadId we retained on `coordinator/<orgId>/consultations/new`.
      * The topic is fixed (not per-thread), so retain holds only the LAST event.
      * `clearRetainedConsultation(threadId)` only clears when it matches, so a
      * later consultation isn't accidentally wiped by a stale resolve callback.
      */
     private lastRetainedConsultationThreadId;
-    constructor(logger?: Logger);
+    constructor(orgId: string, logger?: Logger);
     connect(config: {
         url: string;
         username?: string;

package/dist/src/mqtt-bridge.js

@@ -1,6 +1,7 @@
 import mqtt from "mqtt";
 import { silentLogger } from "./logger.js";
 export class MqttBridge {
+    orgId;
     client = null;
     connected = false;
     onOfflineHandler = null;
@@ -8,14 +9,15 @@ export class MqttBridge {
     log;
     agentId = "coordinator-internal";
     /**
-     * P1: track the last threadId we retained on `coordinator/consultations/new`.
+     * P1: track the last threadId we retained on `coordinator/<orgId>/consultations/new`.
      * The topic is fixed (not per-thread), so retain holds only the LAST event.
      * `clearRetainedConsultation(threadId)` only clears when it matches, so a
      * later consultation isn't accidentally wiped by a stale resolve callback.
      */
     lastRetainedConsultationThreadId = null;
-    constructor(logger) {
-        this.log = logger || silentLogger;
+    constructor(orgId, logger) {
+        this.orgId = orgId;
+        this.log = logger ?? silentLogger;
     }
     async connect(config) {
         return new Promise((resolve, reject) => {
@@ -35,7 +37,7 @@ export class MqttBridge {
                 // bridge automatically broadcasts offline status. Without this the
                 // agent appears online indefinitely after an unexpected disconnect.
                 will: {
-                    topic: `coordinator/agents/${this.agentId}/status`,
+                    topic: `coordinator/${this.orgId}/agents/${this.agentId}/status`,
                     payload: Buffer.from(JSON.stringify({ status: "offline", reason: "lwt_unexpected" })),
                     qos: 1,
                     retain: false,
@@ -45,24 +47,27 @@ export class MqttBridge {
                 clearTimeout(timeout);
                 this.connected = true;
                 this.log.info({ url: config.url }, "MQTT connected");
-                // Subscribe to agent status for LWT detection
-                this.client.subscribe("coordinator/agents/+/status");
+                // All SUBSCRIBE packets must be sent AFTER CONNACK or the broker may
+                // silently drop them under clean:true sessions. Keep the three
+                // subscribes co-located inside this handler.
+                this.client.subscribe(`coordinator/${this.orgId}/agents/+/status`);
+                this.client.subscribe(`coordinator/${this.orgId}/consultations/#`);
+                this.client.subscribe(`coordinator/${this.orgId}/broadcast`);
                 resolve();
             });
-            // Subscribe to consultation topics for agent listeners
-            this.client.subscribe("coordinator/consultations/#");
-            this.client.subscribe("coordinator/broadcast");
             this.client.on("message", (topic, message) => {
                 const parts = topic.split("/");
-                if (parts[1] === "agents" && parts[3] === "status") {
-                    const agentId = parts[2];
+                // Topic: coordinator/<orgId>/agents/<agentId>/status → parts[2]="agents", parts[3]=agentId, parts[4]="status"
+                if (parts[2] === "agents" && parts[4] === "status") {
+                    const agentId = parts[3];
                     const status = message.toString();
                     if (status === "offline" && this.onOfflineHandler) {
                         this.onOfflineHandler(agentId);
                     }
                 }
                 // Route consultation messages to agent listeners
-                if (parts[1] === "consultations" || parts[1] === "broadcast") {
+                // Topic: coordinator/<orgId>/consultations/... or coordinator/<orgId>/broadcast
+                if (parts[2] === "consultations" || parts[2] === "broadcast") {
                     try {
                         const payload = JSON.parse(message.toString());
                         const msg = { topic, payload, timestamp: Date.now() };
@@ -96,7 +101,7 @@ export class MqttBridge {
     registerAgent(agentId, name) {
         if (!this.client || !this.connected)
             return;
-        this.client.publish(`coordinator/agents/${agentId}/status`, JSON.stringify({ status: "online", name }), { retain: true });
+        this.client.publish(`coordinator/${this.orgId}/agents/${agentId}/status`, JSON.stringify({ status: "online", name }), { retain: true });
     }
     publishConsultation(threadId, agentId, subject, targetModules) {
         if (!this.client || !this.connected)
@@ -105,7 +110,7 @@ export class MqttBridge {
         // disconnects. retain=true so a coordinator/subscriber restart can rebuild
         // the active state without an event-history replay.
         this.lastRetainedConsultationThreadId = threadId;
-        this.client.publish("coordinator/consultations/new", JSON.stringify({ thread_id: threadId, agent_id: agentId, subject, target_modules: targetModules }), { qos: 1, retain: true });
+        this.client.publish(`coordinator/${this.orgId}/consultations/new`, JSON.stringify({ thread_id: threadId, agent_id: agentId, subject, target_modules: targetModules }), { qos: 1, retain: true });
     }
     /**
      * P1 fix: clear the retained `coordinator/consultations/new` event when the
@@ -121,43 +126,43 @@ export class MqttBridge {
             return;
         if (this.lastRetainedConsultationThreadId !== threadId)
             return;
-        this.client.publish("coordinator/consultations/new", "", { qos: 1, retain: true });
+        this.client.publish(`coordinator/${this.orgId}/consultations/new`, "", { qos: 1, retain: true });
         this.lastRetainedConsultationThreadId = null;
     }
     publishMessage(threadId, agentId, type, content) {
         if (!this.client || !this.connected)
             return;
         // QoS 0: high-frequency chat-style traffic, lossy-OK.
-        this.client.publish(`coordinator/consultations/${threadId}/messages`, JSON.stringify({ agent_id: agentId, type, content }));
+        this.client.publish(`coordinator/${this.orgId}/consultations/${threadId}/messages`, JSON.stringify({ agent_id: agentId, type, content }));
     }
     publishResolution(threadId, status, summary) {
         if (!this.client || !this.connected)
             return;
         // P1 fix: QoS 1 (at-least-once) — resolution is a state-change event.
-        this.client.publish(`coordinator/consultations/${threadId}/status`, JSON.stringify({ status, summary }), { qos: 1, retain: true });
+        this.client.publish(`coordinator/${this.orgId}/consultations/${threadId}/status`, JSON.stringify({ status, summary }), { qos: 1, retain: true });
     }
     publishBroadcast(agentId, message) {
         if (!this.client || !this.connected)
             return;
-        this.client.publish("coordinator/broadcast", JSON.stringify({ agent_id: agentId, message }));
+        this.client.publish(`coordinator/${this.orgId}/broadcast`, JSON.stringify({ agent_id: agentId, message }));
     }
     publishAgentOffline(agentId) {
         if (!this.client || !this.connected)
             return;
-        this.client.publish(`coordinator/agents/${agentId}/status`, JSON.stringify({ status: "offline" }), { retain: true });
+        this.client.publish(`coordinator/${this.orgId}/agents/${agentId}/status`, JSON.stringify({ status: "offline" }), { retain: true });
     }
     publishTaskClaimed(threadId, claimedBy) {
         if (!this.client || !this.connected)
             return;
         // P1 fix: QoS 1 — claim is a coordination state-change. Loss would mean
         // multiple agents think a task is unclaimed.
-        this.client.publish(`coordinator/consultations/${threadId}/claimed`, JSON.stringify({ agent_id: claimedBy, claimed_by: claimedBy, claimed_at: new Date().toISOString() }), { qos: 1 });
+        this.client.publish(`coordinator/${this.orgId}/consultations/${threadId}/claimed`, JSON.stringify({ agent_id: claimedBy, claimed_by: claimedBy, claimed_at: new Date().toISOString() }), { qos: 1 });
     }
     publishTaskCompleted(threadId, completedBy, summary) {
         if (!this.client || !this.connected)
             return;
         // P1 fix: QoS 1 — completion is a coordination state-change.
-        this.client.publish(`coordinator/consultations/${threadId}/completed`, JSON.stringify({ agent_id: completedBy, completed_by: completedBy, summary }), { qos: 1 });
+        this.client.publish(`coordinator/${this.orgId}/consultations/${threadId}/completed`, JSON.stringify({ agent_id: completedBy, completed_by: completedBy, summary }), { qos: 1 });
     }
     /**
      * Fanout a refreshed QuotaInfo to live subscribers (dashboard widget,
@@ -168,7 +173,7 @@ export class MqttBridge {
         if (!this.client || !this.connected)
             return;
         // QoS 0: high-frequency telemetry, lossy-OK (the next refresh overwrites).
-        this.client.publish("coordinator/quota/update", JSON.stringify(info));
+        this.client.publish(`coordinator/${this.orgId}/quota/update`, JSON.stringify(info));
     }
     // ── Agent listener methods (for integrated MCP tools) ──
     registerListener(agentId) {
@@ -210,7 +215,12 @@ export class MqttBridge {
     }
     mqttPublish(topic, payload) {
         if (this.client && this.connected) {
-            this.client.publish(topic, payload);
+            // Ensure all outbound topics are org-scoped. If caller passes an unscoped
+            // topic, prepend the org prefix; if already prefixed, pass through.
+            const scopedTopic = topic.startsWith(`coordinator/${this.orgId}/`)
+                ? topic
+                : `coordinator/${this.orgId}/${topic.replace(/^coordinator\//, "")}`;
+            this.client.publish(scopedTopic, payload);
         }
     }
     async disconnect() {

package/dist/src/mqtt-broker.d.ts

@@ -7,23 +7,32 @@ export interface EmbeddedMqttBroker {
 }
 /**
  * B3 fix: opt-in MQTT authentication. When provided, every CONNECT packet's
- * password field is passed to authenticate(). Returning false rejects the
- * client. When omitted (default), the broker accepts anonymous connections —
- * preserving the existing behavior so essaim and other clients without auth
- * keep working unchanged.
+ * password field is passed to authenticate(). Returns `{ ok: true, org }` on
+ * success — the org is attached to the Aedes client and used by the ACL hooks.
+ * Returns `{ ok: false }` to reject the CONNECT.
+ * When omitted (default), the broker accepts anonymous connections — preserving
+ * the existing behavior so essaim and other clients without auth keep working.
  *
  * The internal coordinator client (MqttBridge) bypasses this by passing an
  * internal admin token when AUTH_ENABLED is true.
  */
-export type MqttAuthVerifier = (username: string | undefined, password: Buffer | undefined) => Promise<boolean>;
+export type MqttAuthResult = {
+    ok: false;
+} | {
+    ok: true;
+    org: string;
+};
+export type MqttAuthVerifier = (username: string | undefined, password: Buffer | undefined) => Promise<MqttAuthResult>;
 export interface EmbeddedMqttOptions {
     tcpPort?: number;
     httpServer?: HttpServer;
     wsPath?: string;
     logger: Logger;
     /**
-     * Per-CONNECT auth verifier. Omit to allow anonymous (default — backwards
-     * compatible with essaim and any client not using auth).
+     * Per-CONNECT auth verifier. Returns `{ ok: true, org }` on success — the org is
+     * attached to the Aedes client and used by authorizeSubscribe/authorizePublish.
+     * Returning `{ ok: false }` rejects the CONNECT.
+     * Omit to allow anonymous (default — Phase 1 backward compat).
      */
     authenticate?: MqttAuthVerifier;
 }

package/dist/src/mqtt-broker.js

@@ -39,22 +39,57 @@ function wsToDuplex(ws) {
  */
 export async function startEmbeddedMqttBroker(opts) {
     const { tcpPort, httpServer, wsPath = "/mqtt", logger, authenticate } = opts;
-    const broker = await Aedes.createBroker();
+    // Build Aedes options. Hooks are passed at construction time to guarantee
+    // they are set before the broker accepts any connections.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const aedesOpts = {};
     if (authenticate) {
         // B3 fix: when AUTH_ENABLED, every CONNECT must present a valid token.
-        broker.authenticate =
-            (client, username, password, cb) => {
-                Promise.resolve(authenticate(username, password)).then((ok) => {
-                    if (!ok)
-                        logger.warn({ client_id: client?.id, username }, "MQTT auth rejected");
-                    cb(null, ok);
-                }, (err) => {
-                    logger.warn({ client_id: client?.id, err: err.message }, "MQTT auth error");
+        aedesOpts.authenticate = (client, username, password, cb) => {
+            Promise.resolve(authenticate(username, password)).then((result) => {
+                if (!result.ok) {
+                    logger.warn({ client_id: client?.id, username }, "MQTT auth rejected");
                     cb(null, false);
-                });
-            };
+                    return;
+                }
+                // Attach org to the Aedes client object — survives the connection lifetime.
+                client.org = result.org;
+                cb(null, true);
+            }, (err) => {
+                logger.warn({ client_id: client?.id, err: err.message }, "MQTT auth error");
+                cb(null, false);
+            });
+        };
+        // ACL: subscriptions must match coordinator/<org>/...
+        // cb(null, null) → granted=128 (subscription failure per MQTT 3.1.1)
+        aedesOpts.authorizeSubscribe = (client, sub, cb) => {
+            const org = client.org;
+            if (!org)
+                return cb(new Error("MQTT client missing org"), null);
+            const prefix = `coordinator/${org}/`;
+            if (!sub.topic.startsWith(prefix)) {
+                logger.warn({ client_id: client?.id, org, topic: sub.topic }, "MQTT subscribe denied (cross-org)");
+                return cb(null, null);
+            }
+            cb(null, sub);
+        };
+        // ACL: publishes must match coordinator/<org>/...
+        // Passing an Error to cb causes Aedes to disconnect the client (intended:
+        // cross-org publish is treated as a protocol violation, not silently dropped).
+        aedesOpts.authorizePublish = (client, packet, cb) => {
+            const org = client.org;
+            if (!org)
+                return cb(new Error("MQTT client missing org"));
+            const prefix = `coordinator/${org}/`;
+            if (!packet.topic.startsWith(prefix)) {
+                logger.warn({ client_id: client?.id, org, topic: packet.topic }, "MQTT publish denied (cross-org) — client will be disconnected");
+                return cb(new Error("Cross-org publish denied"));
+            }
+            cb(null);
+        };
         logger.info("MQTT auth enabled (token in CONNECT password)");
     }
+    const broker = await Aedes.createBroker(aedesOpts);
     broker.on("client", (client) => {
         logger.debug({ client_id: client?.id }, "MQTT client connected");
     });
@@ -66,7 +101,8 @@ export async function startEmbeddedMqttBroker(opts) {
     });
     let tcpServerClose = null;
     let wsServerClose = null;
-    if (tcpPort && tcpPort > 0) {
+    let resolvedTcpPort = null;
+    if (tcpPort !== undefined && tcpPort >= 0) {
         const tcpServer = createTcpServer((socket) => {
             broker.handle(socket);
         });
@@ -76,12 +112,18 @@ export async function startEmbeddedMqttBroker(opts) {
             tcpServer.once("error", reject);
             tcpServer.listen(tcpPort, "127.0.0.1", () => {
                 tcpServer.off("error", reject);
-                logger.info({ port: tcpPort, transport: "tcp" }, "Embedded MQTT broker listening");
+                const addr = tcpServer.address();
+                // TS narrowing doesn't flow into this callback. `tcpPort` is typed
+                // `number | undefined` here even though the outer guard rules out
+                // undefined. Use `?? null` to keep the assignment compatible with
+                // `number | null`.
+                resolvedTcpPort = typeof addr === "object" && addr ? addr.port : (tcpPort ?? null);
+                logger.info({ port: resolvedTcpPort, transport: "tcp" }, "Embedded MQTT broker listening");
                 resolve();
             });
         });
         tcpServer.on("error", (err) => {
-            logger.error({ err, port: tcpPort }, "Embedded MQTT TCP server error");
+            logger.error({ err, port: resolvedTcpPort }, "Embedded MQTT TCP server error");
         });
         tcpServerClose = () => new Promise((resolve) => tcpServer.close(() => resolve()));
     }
@@ -101,7 +143,7 @@ export async function startEmbeddedMqttBroker(opts) {
         wsServerClose = () => new Promise((resolve) => wss.close(() => resolve()));
     }
     return {
-        tcpPort: tcpPort && tcpPort > 0 ? tcpPort : null,
+        tcpPort: resolvedTcpPort,
         wsPath: httpServer ? wsPath : null,
         close: async () => {
             if (tcpServerClose)

package/dist/src/security/audit.d.ts

@@ -0,0 +1,11 @@
+export interface AuditEvent {
+    user_id?: string | null;
+    /** Nullable: unauthenticated actions (e.g. failed login before identity established). */
+    org_id?: string | null;
+    action: string;
+    target?: string;
+    ip?: string;
+    user_agent?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare function auditLog(ev: AuditEvent): void;

package/dist/src/security/audit.js

@@ -0,0 +1,7 @@
+import { getDb } from "../database.js";
+export function auditLog(ev) {
+    getDb()
+        .prepare(`INSERT INTO audit_log (user_id, org_id, action, target, ip, user_agent, metadata)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .run(ev.user_id ?? null, ev.org_id ?? null, ev.action, ev.target ?? null, ev.ip ?? null, ev.user_agent ?? null, ev.metadata ? JSON.stringify(ev.metadata) : null);
+}

package/dist/src/security/encryption.d.ts

@@ -0,0 +1,17 @@
+export interface EncryptionContext {
+    org_id: string;
+    column: string;
+}
+export interface EncryptionProvider {
+    /** Encrypt a value for storage. Returns base64 ciphertext in real impls. */
+    encrypt(plaintext: string, context: EncryptionContext): string;
+    /** Decrypt a base64 ciphertext. Throws on wrong key / corruption. */
+    decrypt(ciphertext: string, context: EncryptionContext): string;
+    /** Stable HMAC for indexing on encrypted columns without leaking plaintext. */
+    hmac(value: string, context: EncryptionContext): string;
+}
+export declare class PassthroughEncryption implements EncryptionProvider {
+    encrypt(p: string, _context: EncryptionContext): string;
+    decrypt(c: string, _context: EncryptionContext): string;
+    hmac(v: string, _context: EncryptionContext): string;
+}

package/dist/src/security/encryption.js

@@ -0,0 +1,5 @@
+export class PassthroughEncryption {
+    encrypt(p, _context) { return p; }
+    decrypt(c, _context) { return c; }
+    hmac(v, _context) { return v; }
+}