@essentialai/cogent-server 2.0.0

package/dist/middleware/request-logger.d.ts

@@ -0,0 +1,17 @@
+import type { ServerEnv } from "../types.js";
+/**
+ * Request/response logger middleware.
+ *
+ * In production mode (NODE_ENV=production):
+ *   - Outputs a single JSON line per request for log aggregation
+ *   - Skips debug-level header logging entirely (security: avoid header leakage)
+ *
+ * In non-production mode:
+ *   - Uses human-readable format with optional debug header logging
+ *   - CRITICAL (AUTH-04): Authorization header values are ALWAYS replaced
+ *     with [REDACTED] in log output to prevent bearer token leakage.
+ *
+ * Uses console.error (stderr) matching the existing project convention.
+ */
+export declare function requestLogger(): import("hono").MiddlewareHandler<ServerEnv, string, {}, Response>;
+//# sourceMappingURL=request-logger.d.ts.map

package/dist/middleware/request-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-logger.d.ts","sourceRoot":"","sources":["../../src/middleware/request-logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAe7C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,sEA2C5B"}

package/dist/middleware/request-logger.js

@@ -0,0 +1,65 @@
+import { createMiddleware } from "hono/factory";
+/**
+ * Write a structured JSON log entry to stderr.
+ * Used in production mode for machine-parseable log aggregation.
+ */
+function logJson(entry) {
+    console.error(JSON.stringify(entry));
+}
+/**
+ * Request/response logger middleware.
+ *
+ * In production mode (NODE_ENV=production):
+ *   - Outputs a single JSON line per request for log aggregation
+ *   - Skips debug-level header logging entirely (security: avoid header leakage)
+ *
+ * In non-production mode:
+ *   - Uses human-readable format with optional debug header logging
+ *   - CRITICAL (AUTH-04): Authorization header values are ALWAYS replaced
+ *     with [REDACTED] in log output to prevent bearer token leakage.
+ *
+ * Uses console.error (stderr) matching the existing project convention.
+ */
+export function requestLogger() {
+    return createMiddleware(async (c, next) => {
+        const method = c.req.method;
+        const path = c.req.path;
+        const start = Date.now();
+        const isProduction = process.env.NODE_ENV === "production";
+        // In non-production mode, log request headers at debug level
+        if (!isProduction && process.env.COGENT_SERVER_LOG_LEVEL === "debug") {
+            // Sanitize headers for debug logging
+            const headers = {};
+            c.req.raw.headers.forEach((value, key) => {
+                headers[key] =
+                    key.toLowerCase() === "authorization" ? "[REDACTED]" : value;
+            });
+            console.error(`--> ${method} ${path}`, JSON.stringify(headers));
+        }
+        await next();
+        const duration = Date.now() - start;
+        const status = c.res.status;
+        if (isProduction) {
+            // JSON structured logging for production log aggregation
+            logJson({
+                timestamp: new Date().toISOString(),
+                level: status >= 400 ? "error" : "info",
+                message: "http_request",
+                method,
+                path,
+                status,
+                duration,
+            });
+        }
+        else {
+            // Human-readable format for development
+            if (status >= 400) {
+                console.error(`<-- ${method} ${path} ${status} ${duration}ms`);
+            }
+            else if (process.env.COGENT_SERVER_LOG_LEVEL === "debug") {
+                console.error(`<-- ${method} ${path} ${status} ${duration}ms`);
+            }
+        }
+    });
+}
+//# sourceMappingURL=request-logger.js.map

package/dist/middleware/request-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-logger.js","sourceRoot":"","sources":["../../src/middleware/request-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD;;;GAGG;AACH,SAAS,OAAO,CAAC,KAKhB;IACC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,gBAAgB,CAAY,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACnD,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QAC5B,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;QAE3D,6DAA6D;QAC7D,IAAI,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,OAAO,EAAE,CAAC;YACrE,qCAAqC;YACrC,MAAM,OAAO,GAA2B,EAAE,CAAC;YAC3C,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;gBACvC,OAAO,CAAC,GAAG,CAAC;oBACV,GAAG,CAAC,WAAW,EAAE,KAAK,eAAe,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC;YACjE,CAAC,CAAC,CAAC;YACH,OAAO,CAAC,KAAK,CAAC,OAAO,MAAM,IAAI,IAAI,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAClE,CAAC;QAED,MAAM,IAAI,EAAE,CAAC;QAEb,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QACpC,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;QAE5B,IAAI,YAAY,EAAE,CAAC;YACjB,yDAAyD;YACzD,OAAO,CAAC;gBACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,KAAK,EAAE,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;gBACvC,OAAO,EAAE,cAAc;gBACvB,MAAM;gBACN,IAAI;gBACJ,MAAM;gBACN,QAAQ;aACT,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,wCAAwC;YACxC,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;gBAClB,OAAO,CAAC,KAAK,CAAC,OAAO,MAAM,IAAI,IAAI,IAAI,MAAM,IAAI,QAAQ,IAAI,CAAC,CAAC;YACjE,CAAC;iBAAM,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,OAAO,EAAE,CAAC;gBAC3D,OAAO,CAAC,KAAK,CAAC,OAAO,MAAM,IAAI,IAAI,IAAI,MAAM,IAAI,QAAQ,IAAI,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/middleware/ws-auth.d.ts

@@ -0,0 +1,21 @@
+import type { SessionStore } from "../services/session-store.js";
+import type { AuthService } from "../services/auth-service.js";
+import type { ServerEnv } from "../types.js";
+/**
+ * Create WebSocket-specific auth middleware.
+ *
+ * Unlike the standard bearer auth middleware (which reads the Authorization
+ * header), this middleware reads the token from the `token` query parameter.
+ * WebSocket clients pass auth via query params because browser WebSocket APIs
+ * cannot set custom HTTP headers. Our CLI clients use query params for
+ * consistency with the standard WebSocket authentication pattern.
+ *
+ * This middleware runs BEFORE `upgradeWebSocket`, so auth failures return
+ * HTTP error responses (never establish a WebSocket connection).
+ *
+ * Additionally validates that the `peerId` query parameter is present and
+ * that the peer is registered in the session -- preventing unregistered
+ * peers from establishing WebSocket connections.
+ */
+export declare function createWsAuthMiddleware(sessionStore: SessionStore, authService: AuthService): import("hono").MiddlewareHandler<ServerEnv, string, {}, Response>;
+//# sourceMappingURL=ws-auth.d.ts.map

package/dist/middleware/ws-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-auth.d.ts","sourceRoot":"","sources":["../../src/middleware/ws-auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,WAAW,qEA0EzB"}

package/dist/middleware/ws-auth.js

@@ -0,0 +1,59 @@
+import { createMiddleware } from "hono/factory";
+import { BridgeError, ErrorCode } from "@essentialai/cogent";
+/**
+ * Create WebSocket-specific auth middleware.
+ *
+ * Unlike the standard bearer auth middleware (which reads the Authorization
+ * header), this middleware reads the token from the `token` query parameter.
+ * WebSocket clients pass auth via query params because browser WebSocket APIs
+ * cannot set custom HTTP headers. Our CLI clients use query params for
+ * consistency with the standard WebSocket authentication pattern.
+ *
+ * This middleware runs BEFORE `upgradeWebSocket`, so auth failures return
+ * HTTP error responses (never establish a WebSocket connection).
+ *
+ * Additionally validates that the `peerId` query parameter is present and
+ * that the peer is registered in the session -- preventing unregistered
+ * peers from establishing WebSocket connections.
+ */
+export function createWsAuthMiddleware(sessionStore, authService) {
+    return createMiddleware(async (c, next) => {
+        // 1. Extract token from query parameter
+        const token = c.req.query("token");
+        if (!token) {
+            throw new BridgeError(ErrorCode.AUTH_MISSING_TOKEN, "Token query parameter required for WebSocket connection", "Include '?token=<bearer-token>' in the WebSocket URL");
+        }
+        // 2. Hash the token with SHA-256 for index lookup
+        const tokenHash = authService.hashToken(token);
+        // 3. Look up session by token hash
+        const result = await sessionStore.getSessionByTokenHash(tokenHash);
+        if (!result) {
+            throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Invalid or expired token");
+        }
+        // 4. Defense-in-depth: timing-safe comparison of the token hash
+        const storedTokenHash = result.state.tokens.find((t) => t.tokenHash === tokenHash)?.tokenHash;
+        if (!storedTokenHash ||
+            !authService.timingSafeCompare(tokenHash, storedTokenHash)) {
+            throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Invalid or expired token");
+        }
+        // 5. Verify path sessionId matches the authenticated session
+        const pathSessionId = c.req.param("sessionId");
+        if (pathSessionId !== result.sessionId) {
+            throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Token does not match the requested session");
+        }
+        // 6. Validate peerId query parameter is present and registered
+        const peerId = c.req.query("peerId");
+        if (!peerId) {
+            throw new BridgeError(ErrorCode.PEER_NOT_FOUND, "peerId query parameter required for WebSocket connection", "Include '&peerId=<peer-id>' in the WebSocket URL");
+        }
+        const peer = result.state.peers[peerId];
+        if (!peer) {
+            throw new BridgeError(ErrorCode.PEER_NOT_FOUND, `Peer '${peerId}' is not registered in this session`, "Register the peer via POST /api/sessions/:sessionId/peers first");
+        }
+        // 7. Set session context for downstream handlers
+        c.set("sessionId", result.sessionId);
+        c.set("session", result.state);
+        await next();
+    });
+}
+//# sourceMappingURL=ws-auth.js.map

package/dist/middleware/ws-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-auth.js","sourceRoot":"","sources":["../../src/middleware/ws-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAK7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CACpC,YAA0B,EAC1B,WAAwB;IAExB,OAAO,gBAAgB,CAAY,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACnD,wCAAwC;QACxC,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,kBAAkB,EAC5B,yDAAyD,EACzD,sDAAsD,CACvD,CAAC;QACJ,CAAC;QAED,kDAAkD;QAClD,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAE/C,mCAAmC;QACnC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,kBAAkB,EAC5B,0BAA0B,CAC3B,CAAC;QACJ,CAAC;QAED,gEAAgE;QAChE,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAC9C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CACjC,EAAE,SAAS,CAAC;QAEb,IACE,CAAC,eAAe;YAChB,CAAC,WAAW,CAAC,iBAAiB,CAAC,SAAS,EAAE,eAAe,CAAC,EAC1D,CAAC;YACD,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,kBAAkB,EAC5B,0BAA0B,CAC3B,CAAC;QACJ,CAAC;QAED,6DAA6D;QAC7D,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAC/C,IAAI,aAAa,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;YACvC,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,kBAAkB,EAC5B,4CAA4C,CAC7C,CAAC;QACJ,CAAC;QAED,+DAA+D;QAC/D,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,cAAc,EACxB,0DAA0D,EAC1D,kDAAkD,CACnD,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,WAAW,CACnB,SAAS,CAAC,cAAc,EACxB,SAAS,MAAM,qCAAqC,EACpD,iEAAiE,CAClE,CAAC;QACJ,CAAC;QAED,iDAAiD;QACjD,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;QACrC,CAAC,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAE/B,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/routes/health.d.ts

@@ -0,0 +1,11 @@
+import { Hono } from "hono";
+import type { SessionStore } from "../services/session-store.js";
+import type { ConnectionManager } from "../services/connection-manager.js";
+import type { ServerEnv } from "../types.js";
+/**
+ * Create health check routes sub-router.
+ *
+ * GET / -> Server health status (maps to /api/health via app.route)
+ */
+export declare function createHealthRoutes(sessionStore: SessionStore, startTime: number, connectionManager?: ConnectionManager): Hono<ServerEnv>;
+//# sourceMappingURL=health.d.ts.map

package/dist/routes/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/routes/health.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,MAAM,EACjB,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,IAAI,CAAC,SAAS,CAAC,CAuBjB"}

package/dist/routes/health.js

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Hono } from "hono";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
+const SERVER_VERSION = pkg.version;
+/**
+ * Create health check routes sub-router.
+ *
+ * GET / -> Server health status (maps to /api/health via app.route)
+ */
+export function createHealthRoutes(sessionStore, startTime, connectionManager) {
+    const health = new Hono();
+    /**
+     * GET / - Server health check.
+     *
+     * Returns server status, uptime, version, active session count,
+     * and connected peer count from the WebSocket connection manager.
+     */
+    health.get("/", async (c) => {
+        const uptimeSeconds = (Date.now() - startTime) / 1000;
+        const sessions = await sessionStore.listSessions();
+        return c.json({
+            status: "ok",
+            uptime: uptimeSeconds,
+            version: SERVER_VERSION,
+            activeSessions: sessions.length,
+            connectedPeers: connectionManager?.getTotalConnectedPeers() ?? 0,
+        });
+    });
+    return health;
+}
+//# sourceMappingURL=health.js.map

package/dist/routes/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/routes/health.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAK5B,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;AACrF,MAAM,cAAc,GAAW,GAAG,CAAC,OAAO,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAA0B,EAC1B,SAAiB,EACjB,iBAAqC;IAErC,MAAM,MAAM,GAAG,IAAI,IAAI,EAAa,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QAC1B,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;QACtD,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,YAAY,EAAE,CAAC;QAEnD,OAAO,CAAC,CAAC,IAAI,CAAC;YACZ,MAAM,EAAE,IAAa;YACrB,MAAM,EAAE,aAAa;YACrB,OAAO,EAAE,cAAc;YACvB,cAAc,EAAE,QAAQ,CAAC,MAAM;YAC/B,cAAc,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,IAAI,CAAC;SACjE,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/routes/messages.d.ts

@@ -0,0 +1,19 @@
+import { Hono } from "hono";
+import type { SessionStore } from "../services/session-store.js";
+import type { AuthService } from "../services/auth-service.js";
+import type { ConnectionManager } from "../services/connection-manager.js";
+import type { MessageQueueService } from "../services/message-queue.js";
+import type { ServerEnv } from "../types.js";
+/**
+ * Create message routes sub-router.
+ *
+ * POST /:sessionId/messages -> Send a message (direct or broadcast)
+ * GET  /:sessionId/messages -> Retrieve message history with filtering/pagination
+ *
+ * All routes require bearer token auth. The auth middleware sets
+ * sessionId and session on the Hono context.
+ *
+ * @param maxMessages - Maximum messages to retain per session (oldest trimmed on write)
+ */
+export declare function createMessageRoutes(sessionStore: SessionStore, authService: AuthService, maxMessages: number, connectionManager?: ConnectionManager, messageQueue?: MessageQueueService): Hono<ServerEnv>;
+//# sourceMappingURL=messages.d.ts.map

package/dist/routes/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/routes/messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAU5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAK7C;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,MAAM,EACnB,iBAAiB,CAAC,EAAE,iBAAiB,EACrC,YAAY,CAAC,EAAE,mBAAmB,GACjC,IAAI,CAAC,SAAS,CAAC,CA8LjB"}

package/dist/routes/messages.js

@@ -0,0 +1,154 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import { BridgeError, ErrorCode, SendMessageRequestSchema, GetHistoryQuerySchema, generateMessageId, } from "@essentialai/cogent";
+import { createAuthMiddleware } from "../middleware/auth.js";
+import { validationHook } from "./validation-hook.js";
+import { createMessageFrame } from "../ws/frames.js";
+/**
+ * Create message routes sub-router.
+ *
+ * POST /:sessionId/messages -> Send a message (direct or broadcast)
+ * GET  /:sessionId/messages -> Retrieve message history with filtering/pagination
+ *
+ * All routes require bearer token auth. The auth middleware sets
+ * sessionId and session on the Hono context.
+ *
+ * @param maxMessages - Maximum messages to retain per session (oldest trimmed on write)
+ */
+export function createMessageRoutes(sessionStore, authService, maxMessages, connectionManager, messageQueue) {
+    const messages = new Hono();
+    // Auth middleware applied per-route (not wildcard) to avoid intercepting
+    // unauthenticated session routes mounted at the same /api/sessions prefix.
+    const auth = createAuthMiddleware(sessionStore, authService);
+    /**
+     * POST /:sessionId/messages - Send a message (direct or broadcast).
+     *
+     * Direct: toPeerId is a specific peer ID (must exist in session).
+     * Broadcast: toPeerId is "*" (delivered to all peers, stored as-is).
+     *
+     * Updates sender's lastSeenAt as a heartbeat on activity.
+     * Enforces per-session message cap by trimming oldest messages.
+     */
+    messages.post("/:sessionId/messages", auth, zValidator("json", SendMessageRequestSchema, validationHook), async (c) => {
+        const authSessionId = c.get("sessionId");
+        const pathSessionId = c.req.param("sessionId");
+        // Verify path param matches authenticated session
+        if (pathSessionId !== authSessionId) {
+            throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Token does not belong to this session");
+        }
+        const { fromPeerId, toPeerId, message } = c.req.valid("json");
+        // Variables to capture for the response (set inside updateSession callback)
+        let messageId;
+        let timestamp;
+        let record;
+        await sessionStore.updateSession(authSessionId, (state) => {
+            // Verify sender is a registered peer in this session
+            if (!state.peers[fromPeerId]) {
+                throw new BridgeError(ErrorCode.PEER_NOT_FOUND, "Sender peer not registered in session", `Register peer '${fromPeerId}' before sending messages`);
+            }
+            // For direct messages, verify recipient exists (skip for broadcast)
+            if (toPeerId !== "*" && !state.peers[toPeerId]) {
+                throw new BridgeError(ErrorCode.PEER_NOT_FOUND, "Recipient peer not found in session", `Check that peer '${toPeerId}' is registered in the session`);
+            }
+            // Update sender's lastSeenAt (heartbeat on activity)
+            const now = new Date().toISOString();
+            state.peers[fromPeerId].lastSeenAt = now;
+            // Generate message ID and create the record
+            messageId = generateMessageId();
+            timestamp = now;
+            record = {
+                id: messageId,
+                fromPeerId,
+                toPeerId,
+                message,
+                response: null,
+                timestamp,
+                durationMs: null,
+                success: true,
+                error: null,
+            };
+            state.messages.push(record);
+            // Enforce message cap (session store also does this, belt-and-suspenders)
+            if (state.messages.length > maxMessages) {
+                state.messages = state.messages.slice(-maxMessages);
+            }
+            return state;
+        });
+        // Push message to connected WebSocket peers (fire-and-forget)
+        if (connectionManager) {
+            try {
+                const frame = createMessageFrame(record);
+                const data = JSON.stringify(frame);
+                if (toPeerId === "*") {
+                    // Broadcast: send to all connected peers except the sender
+                    connectionManager.broadcastToSession(authSessionId, data, fromPeerId);
+                }
+                else {
+                    // Direct message: push to recipient if connected, else queue for offline
+                    if (connectionManager.isConnected(authSessionId, toPeerId)) {
+                        connectionManager.sendToPeer(authSessionId, toPeerId, data);
+                    }
+                    else if (messageQueue) {
+                        await messageQueue.enqueue(authSessionId, toPeerId, record);
+                    }
+                }
+            }
+            catch (err) {
+                // WS push is best-effort -- log but don't fail the REST response
+                console.error("WebSocket push failed:", err);
+            }
+        }
+        return c.json({
+            id: messageId,
+            success: true,
+            timestamp: timestamp,
+        }, 201);
+    });
+    /**
+     * GET /:sessionId/messages - Retrieve message history.
+     *
+     * Supports optional filtering by peerId and pagination via limit/offset.
+     * When peerId is provided, returns messages where the peer is sender,
+     * recipient, or the message is a broadcast (toPeerId: "*").
+     */
+    messages.get("/:sessionId/messages", auth, zValidator("query", GetHistoryQuerySchema, validationHook), async (c) => {
+        const authSessionId = c.get("sessionId");
+        const pathSessionId = c.req.param("sessionId");
+        // Verify path param matches authenticated session
+        if (pathSessionId !== authSessionId) {
+            throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Token does not belong to this session");
+        }
+        const query = c.req.valid("query");
+        const peerId = query.peerId;
+        // Zod schema provides defaults but the type annotation includes undefined
+        const limit = query.limit ?? 300;
+        const offset = query.offset ?? 0;
+        // Fresh read from store (not cached from auth middleware)
+        const session = await sessionStore.getSession(authSessionId);
+        if (!session) {
+            throw new BridgeError(ErrorCode.SESSION_NOT_FOUND, `Session ${authSessionId} not found`);
+        }
+        // Filter messages by peer if specified
+        let filtered = session.messages;
+        if (peerId) {
+            filtered = filtered.filter((msg) => msg.fromPeerId === peerId ||
+                msg.toPeerId === peerId ||
+                msg.toPeerId === "*");
+        }
+        // Compute total before pagination
+        const total = filtered.length;
+        // Apply pagination (newest-first: offset counts back from the end)
+        // offset=0, limit=20 → last 20 messages (most recent)
+        // offset=20, limit=20 → messages 20-40 from the end (next page back)
+        // Returned slice is still chronological (oldest-first within the page).
+        const endPos = Math.max(0, filtered.length - offset);
+        const startPos = Math.max(0, endPos - limit);
+        const paginated = filtered.slice(startPos, endPos);
+        return c.json({
+            messages: paginated,
+            total,
+        });
+    });
+    return messages;
+}
+//# sourceMappingURL=messages.js.map

package/dist/routes/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/routes/messages.ts"],"names":[],"mappings":"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"}

package/dist/routes/peers.d.ts

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+import type { SessionStore } from "../services/session-store.js";
+import type { AuthService } from "../services/auth-service.js";
+import type { ConnectionManager } from "../services/connection-manager.js";
+import type { ServerEnv } from "../types.js";
+/**
+ * Create peer management routes sub-router.
+ *
+ * POST /:sessionId/peers         -> Register a peer in a session
+ * GET  /:sessionId/peers         -> List all peers in a session
+ * DELETE /:sessionId/peers/:peerId -> Deregister a peer
+ *
+ * All routes require valid Bearer token authentication.
+ * The sub-router is mounted at /api/sessions via app.route().
+ */
+export declare function createPeerRoutes(sessionStore: SessionStore, authService: AuthService, connectionManager?: ConnectionManager): Hono<ServerEnv>;
+//# sourceMappingURL=peers.d.ts.map

package/dist/routes/peers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peers.d.ts","sourceRoot":"","sources":["../../src/routes/peers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAS5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAsB7C;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,WAAW,EACxB,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,IAAI,CAAC,SAAS,CAAC,CA6LjB"}

package/dist/routes/peers.js

@@ -0,0 +1,169 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import { BridgeError, ErrorCode, RegisterPeerRequestSchema, DeregisterPeerRequestSchema, } from "@essentialai/cogent";
+import { createAuthMiddleware } from "../middleware/auth.js";
+import { validationHook } from "./validation-hook.js";
+import { createPeerConnectedFrame, createPeerDisconnectedFrame, } from "../ws/frames.js";
+/**
+ * Verify that the path parameter sessionId matches the auth context sessionId.
+ * Prevents token misuse across sessions.
+ */
+function verifySessionMatch(pathSessionId, authSessionId) {
+    if (pathSessionId !== authSessionId) {
+        throw new BridgeError(ErrorCode.AUTH_INVALID_TOKEN, "Token does not belong to this session", "Use a token issued for this session");
+    }
+}
+/**
+ * Create peer management routes sub-router.
+ *
+ * POST /:sessionId/peers         -> Register a peer in a session
+ * GET  /:sessionId/peers         -> List all peers in a session
+ * DELETE /:sessionId/peers/:peerId -> Deregister a peer
+ *
+ * All routes require valid Bearer token authentication.
+ * The sub-router is mounted at /api/sessions via app.route().
+ */
+export function createPeerRoutes(sessionStore, authService, connectionManager) {
+    const peers = new Hono();
+    // Auth middleware applied per-route (not wildcard) to avoid intercepting
+    // unauthenticated session routes mounted at the same /api/sessions prefix.
+    const auth = createAuthMiddleware(sessionStore, authService);
+    /**
+     * POST /:sessionId/peers - Register a new peer in a session.
+     *
+     * Validates the request body against RegisterPeerRequestSchema,
+     * creates a PeerInfo record, adds it to the session state, and
+     * records a peer_connected event.
+     *
+     * Returns 201 with the PeerInfo object.
+     */
+    peers.post("/:sessionId/peers", auth, zValidator("json", RegisterPeerRequestSchema, validationHook), async (c) => {
+        const pathSessionId = c.req.param("sessionId");
+        const authSessionId = c.get("sessionId");
+        verifySessionMatch(pathSessionId, authSessionId);
+        const { peerId, cwd, label } = c.req.valid("json");
+        const now = new Date().toISOString();
+        const peerInfo = {
+            peerId,
+            sessionId: authSessionId,
+            cwd,
+            label,
+            registeredAt: now,
+            lastSeenAt: now,
+        };
+        await sessionStore.updateSession(authSessionId, (state) => {
+            // Add peer to session
+            state.peers[peerId] = peerInfo;
+            // Record peer_connected event
+            const event = {
+                type: "peer_connected",
+                peerId,
+                timestamp: now,
+            };
+            state.peerEvents.push(event);
+            return state;
+        });
+        // Broadcast peer_connected event to connected WebSocket peers (fire-and-forget)
+        if (connectionManager) {
+            try {
+                const frame = createPeerConnectedFrame({
+                    peerId,
+                    name: label || peerId,
+                    project: cwd,
+                });
+                const data = JSON.stringify(frame);
+                // Exclude the registering peer (not yet connected via WS at registration time)
+                connectionManager.broadcastToSession(authSessionId, data, peerId);
+            }
+            catch (err) {
+                console.error("WebSocket peer_connected broadcast failed:", err);
+            }
+        }
+        return c.json(peerInfo, 201);
+    });
+    /**
+     * GET /:sessionId/peers - List all peers in a session.
+     *
+     * Returns the full list of currently registered peers.
+     * Stale peers are cleaned up by the background PeerCleanup service,
+     * so this endpoint simply returns whatever is in the session state.
+     */
+    peers.get("/:sessionId/peers", auth, async (c) => {
+        const pathSessionId = c.req.param("sessionId");
+        const authSessionId = c.get("sessionId");
+        verifySessionMatch(pathSessionId, authSessionId);
+        // Re-read from store for maximum freshness
+        const session = await sessionStore.getSession(authSessionId);
+        if (!session) {
+            throw new BridgeError(ErrorCode.SESSION_NOT_FOUND, `Session ${authSessionId} not found`, "Check the session ID or create a new session");
+        }
+        const peerList = Object.values(session.peers);
+        return c.json({ peers: peerList });
+    });
+    /**
+     * DELETE /:sessionId/peers/:peerId - Deregister a peer from a session.
+     *
+     * Removes the peer from the session state and records a
+     * peer_disconnected event. Returns 204 (no body).
+     */
+    peers.delete("/:sessionId/peers/:peerId", auth, zValidator("json", DeregisterPeerRequestSchema, validationHook), async (c) => {
+        const pathSessionId = c.req.param("sessionId");
+        const authSessionId = c.get("sessionId");
+        verifySessionMatch(pathSessionId, authSessionId);
+        const peerId = c.req.param("peerId");
+        const now = new Date().toISOString();
+        await sessionStore.updateSession(authSessionId, (state) => {
+            // Verify peer exists
+            if (!state.peers[peerId]) {
+                throw new BridgeError(ErrorCode.PEER_NOT_FOUND, `Peer ${peerId} not found in session ${authSessionId}`, "Check the peer ID or register the peer first");
+            }
+            // Remove the peer
+            delete state.peers[peerId];
+            // Record peer_disconnected event
+            const event = {
+                type: "peer_disconnected",
+                peerId,
+                timestamp: now,
+            };
+            state.peerEvents.push(event);
+            return state;
+        });
+        // Broadcast peer_disconnected event to connected WebSocket peers (fire-and-forget)
+        if (connectionManager) {
+            try {
+                const frame = createPeerDisconnectedFrame(peerId);
+                const data = JSON.stringify(frame);
+                // Exclude the deregistering peer from the broadcast
+                connectionManager.broadcastToSession(authSessionId, data, peerId);
+            }
+            catch (err) {
+                console.error("WebSocket peer_disconnected broadcast failed:", err);
+            }
+        }
+        return c.body(null, 204);
+    });
+    /**
+     * POST /:sessionId/heartbeat - Lightweight keepalive for a registered peer.
+     *
+     * Updates the peer's lastSeenAt timestamp. Returns 204 with no body.
+     * Designed for periodic client heartbeats to prevent stale peer cleanup.
+     */
+    peers.post("/:sessionId/heartbeat", auth, async (c) => {
+        const pathSessionId = c.req.param("sessionId");
+        const authSessionId = c.get("sessionId");
+        verifySessionMatch(pathSessionId, authSessionId);
+        const { peerId } = await c.req.json();
+        if (!peerId || typeof peerId !== "string") {
+            throw new BridgeError(ErrorCode.INVALID_INPUT, "peerId is required", "Include { peerId: 'your-peer-id' } in the request body");
+        }
+        await sessionStore.updateSession(authSessionId, (state) => {
+            if (state.peers[peerId]) {
+                state.peers[peerId].lastSeenAt = new Date().toISOString();
+            }
+            return state;
+        });
+        return c.body(null, 204);
+    });
+    return peers;
+}
+//# sourceMappingURL=peers.js.map

package/dist/routes/peers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peers.js","sourceRoot":"","sources":["../../src/routes/peers.ts"],"names":[],"mappings":"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"}