@hybrd/xmtp 1.2.8 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hybrd/xmtp",
-  "version": "1.2.8",
+  "version": "1.3.1",
   "type": "module",
   "exports": {
     ".": {
@@ -17,6 +17,7 @@
     "@xmtp/content-type-transaction-reference": "2.0.2",
     "@xmtp/content-type-wallet-send-calls": "2.0.0",
     "@xmtp/node-sdk": "^4.0.1",
+    "hono": "^4.7.4",
     "jsonwebtoken": "^9.0.2",
     "uint8arrays": "^5.1.0",
     "viem": "^2.22.17"
@@ -26,8 +27,8 @@
     "@types/node": "22.8.6",
     "tsup": "^8.5.0",
     "vitest": "^3.2.4",
-    "@config/tsconfig": "0.0.0",
-    "@config/biome": "0.0.0"
+    "@config/biome": "0.0.0",
+    "@config/tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "tsup",

package/src/endpoints.ts

@@ -0,0 +1,306 @@
+import { ContentTypeReaction } from "@xmtp/content-type-reaction"
+import { ContentTypeReply, Reply } from "@xmtp/content-type-reply"
+import { ContentTypeText } from "@xmtp/content-type-text"
+import { ContentTypeWalletSendCalls, WalletSendCallsParams } from "@xmtp/content-type-wallet-send-calls"
+import { Hono } from "hono"
+import { getValidatedPayload, validateXMTPToolsToken } from "./lib/jwt"
+import type { HonoVariables, SendMessageParams, SendReactionParams, SendReplyParams, SendTransactionParams } from "./types"
+
+const app = new Hono<{ Variables: HonoVariables }>()
+
+app.get("/messages/:messageId", async (c) => {
+	const xmtpClient = c.get("xmtpClient")
+
+	if (!xmtpClient) {
+		return c.json({ error: "XMTP client not initialized" }, 500)
+	}
+
+	const token = c.req.query("token")
+
+	if (!token) {
+		return c.json({ error: "Token required" }, 401)
+	}
+
+	const payload = validateXMTPToolsToken(token)
+	if (!payload) {
+		return c.json({ error: "Invalid or expired token" }, 401)
+	}
+
+	const messageId = c.req.param("messageId")
+
+	try {
+		const message = await xmtpClient.conversations.getMessageById(messageId)
+		if (!message) {
+			return c.json({ error: "Message not found" }, 404)
+		}
+
+		console.log(`✅ Retrieved message ${messageId}`)
+
+		const transformedMessage = {
+			id: message.id,
+			senderInboxId: message.senderInboxId,
+			sentAt: message.sentAt.toISOString(),
+			content:
+				typeof message.content === "object"
+					? JSON.stringify(message.content)
+					: message.content,
+			contentType: message.contentType?.typeId || "text",
+			conversationId: message.conversationId,
+			parameters: (message.contentType as any)?.parameters || {}
+		}
+
+		return c.json(transformedMessage)
+	} catch (error) {
+		console.error("❌ Error fetching message:", error)
+		return c.json({ error: "Failed to fetch message" }, 500)
+	}
+})
+
+// XMTP Tools endpoints
+app.post("/send", async (c) => {
+	const xmtpClient = c.get("xmtpClient")
+
+	if (!xmtpClient) {
+		return c.json({ error: "XMTP client not initialized" }, 500)
+	}
+
+	const payload = getValidatedPayload(c)
+	if (!payload) {
+		return c.json({ error: "Invalid or expired token" }, 401)
+	}
+
+	// Get request body data
+	const body = await c.req.json<SendMessageParams>()
+
+	// Content can come from JWT payload or request body
+	const content = body.content || payload.content
+	if (!content) {
+		return c.json({ error: "Content required for send action" }, 400)
+	}
+
+	const conversationId = payload.conversationId
+
+	// Conversation ID can come from JWT payload or request body (for API key auth)
+	// const conversationId = payload.conversationId || body.conversationId
+	if (!conversationId) {
+		return c.json({ error: "Conversation ID required" }, 400)
+	}
+
+	try {
+		const conversation =
+			await xmtpClient.conversations.getConversationById(conversationId)
+		if (!conversation) {
+			return c.json({ error: "Conversation not found" }, 404)
+		}
+
+		await conversation.send(content)
+		console.log(`➡ Sent message to conversation ${conversationId}`)
+
+		return c.json({
+			success: true,
+			action: "send",
+			conversationId: payload.conversationId
+		})
+	} catch (error) {
+		console.error("❌ Error sending message:", error)
+		return c.json({ error: "Failed to send message" }, 500)
+	}
+})
+
+app.post("/reply", async (c) => {
+	const xmtpClient = c.get("xmtpClient")
+
+	if (!xmtpClient) {
+		return c.json({ error: "XMTP client not initialized" }, 500)
+	}
+
+	const payload = getValidatedPayload(c)
+	if (!payload) {
+		return c.json({ error: "Invalid or expired token" }, 401)
+	}
+
+	// Get request body data
+	const body = await c.req.json<SendReplyParams>()
+
+	// Content can come from JWT payload or request body
+	const content = body.content || payload.content
+	if (!content) {
+		return c.json({ error: "Content required for reply action" }, 400)
+	}
+
+	// Reference message ID can come from JWT payload or request body
+	const messageId = body.messageId
+
+	if (!messageId) {
+		return c.json(
+			{ error: "Reference message ID required for reply action" },
+			400
+		)
+	}
+
+	try {
+		const conversation = await xmtpClient.conversations.getConversationById(
+			payload.conversationId
+		)
+		if (!conversation) {
+			return c.json({ error: "Conversation not found" }, 404)
+		}
+
+		// Create proper XMTP reply structure
+		const reply: Reply = {
+			reference: messageId,
+			contentType: ContentTypeText,
+			content: content
+		}
+
+		// Send as a proper threaded reply
+		await conversation.send(reply, ContentTypeReply)
+		console.log(
+			`➡ Sent reply "${content}" to conversation ${payload.conversationId}`
+		)
+
+		return c.json({
+			success: true,
+			action: "reply",
+			conversationId: payload.conversationId
+		})
+	} catch (error) {
+		console.error("❌ Error sending reply:", error)
+		return c.json({ error: "Failed to send reply" }, 500)
+	}
+})
+
+app.post("/react", async (c) => {
+	const xmtpClient = c.get("xmtpClient")
+
+	if (!xmtpClient) {
+		return c.json({ error: "XMTP client not initialized" }, 500)
+	}
+
+	const payload = getValidatedPayload(c)
+	if (!payload) {
+		return c.json({ error: "Invalid or expired token" }, 401)
+	}
+
+	// Get request body data
+	const body = await c.req.json<SendReactionParams>()
+
+	if (!body.emoji) {
+		return c.json({ error: "Emoji required for react action" }, 400)
+	}
+
+	try {
+		const conversation = await xmtpClient.conversations.getConversationById(
+			payload.conversationId
+		)
+		if (!conversation) {
+			return c.json({ error: "Conversation not found" }, 404)
+		}
+
+		const reaction = {
+			schema: "unicode",
+			reference: body.messageId,
+			action: body.action,
+			contentType: ContentTypeReaction,
+			content: body.emoji
+		}
+
+		// For now, send the reaction content as a simple text message
+		// This will send "eyes" as text content to indicate message was seen
+		await conversation.send(reaction, ContentTypeReaction)
+
+		console.log(
+			`➡ Sent reaction ${body.emoji} to message ${body.messageId} in conversation ${payload.conversationId}`
+		)
+
+		return c.json({
+			success: true,
+			action: "react",
+			conversationId: payload.conversationId
+		})
+	} catch (error) {
+		console.error("❌ Error sending reaction:", error)
+		return c.json({ error: "Failed to send reaction" }, 500)
+	}
+})
+
+app.post("/transaction", async (c) => {
+	const xmtpClient = c.get("xmtpClient")
+
+	if (!xmtpClient) {
+		return c.json({ error: "XMTP client not initialized" }, 500)
+	}
+
+	const payload = getValidatedPayload(c)
+	if (!payload) {
+		return c.json({ error: "Invalid or expired token" }, 401)
+	}
+
+	// Get request body data for backward compatibility
+	let body: any = {}
+	try {
+		body = await c.req.json<SendTransactionParams>()
+	} catch (error) {
+		body = {}
+	}
+
+	// Transaction data can come from JWT payload (preferred) or request body (fallback)
+	const fromAddress = payload.fromAddress || body.fromAddress
+	const chainId = payload.chainId || body.chainId
+	const calls = payload.calls || body.calls
+
+	if (!calls || !fromAddress || !chainId) {
+		return c.json(
+			{ error: "Transaction data required for transaction action" },
+			400
+		)
+	}
+
+	// CRITICAL: Detect data truncation that can cause transaction failures
+	calls.forEach((call: any, index: number) => {
+		if (call.data && typeof call.data === "string") {
+			const actualStart = call.data.substring(0, 10)
+
+			if (actualStart === "0x010f2e2e") {
+				console.error("🚨 CRITICAL: Transaction data truncation detected!")
+				console.error("   Function selector corrupted - transaction will fail")
+				console.error(
+					"   This indicates a bug in wallet software or XMTP transmission"
+				)
+			}
+		}
+	})
+
+	try {
+		const conversation = await xmtpClient.conversations.getConversationById(
+			payload.conversationId
+		)
+		if (!conversation) {
+			return c.json({ error: "Conversation not found" }, 404)
+		}
+
+		const params: WalletSendCallsParams = {
+			version: "1",
+			chainId,
+			from: fromAddress,
+			calls
+		}
+
+		await conversation.send(params, ContentTypeWalletSendCalls)
+
+		console.log(
+			`✅ Sent transaction request to conversation ${payload.conversationId}`
+		)
+
+		return c.json({
+			success: true,
+			action: "transaction",
+			conversationId: payload.conversationId
+		})
+	} catch (error) {
+		console.error("❌ Error sending transaction:", error)
+		return c.json({ error: "Failed to send transaction" }, 500)
+	}
+})
+
+export default app

package/src/index.ts

@@ -15,13 +15,25 @@ export * from "./resolver/xmtp-resolver"
 export * from "./service-client"
 export * from "./types"
 
+// ===================================================================
+// XMTP Plugin for Agent Integration
+// ===================================================================
+export { XMTPPlugin } from "./plugin"
+export type { Plugin, XMTPPluginContext } from "./plugin"
+
+// ===================================================================
+// JWT Utilities for XMTP Tools
+// ===================================================================
+export { generateXMTPToolsToken } from "./lib/jwt"
+export type { XMTPToolsPayload } from "./lib/jwt"
+
 // ===================================================================
 // Enhanced XMTP Client & Connection Management
 // ===================================================================
 export {
-	createXMTPConnectionManager,
 	// Enhanced connection management
 	XMTPConnectionManager,
+	createXMTPConnectionManager,
 	type XMTPConnectionConfig,
 	type XMTPConnectionHealth
 } from "./client"
@@ -30,8 +42,8 @@ export {
 // XMTP Service Client (for external service communication)
 // ===================================================================
 export {
-	createXmtpServiceClient,
-	XmtpServiceClient
+	XmtpServiceClient,
+	createXmtpServiceClient
 } from "./service-client"
 
 // Service Client Types

package/src/lib/jwt.ts

@@ -0,0 +1,220 @@
+import { Context } from "hono"
+import jwt from "jsonwebtoken"
+
+export interface XMTPToolsPayload {
+	action: "send" | "reply" | "react" | "transaction" | "blockchain-event"
+	conversationId: string
+	// Action-specific data
+	content?: string
+	referenceMessageId?: string
+	emoji?: string
+	actionType?: "added" | "removed"
+	fromAddress?: string
+	chainId?: string
+	calls?: Array<{
+		to: string
+		data: string
+		metadata?: {
+			description: string
+			transactionType: string
+		}
+	}>
+	// Metadata
+	issued: number
+	expires: number
+}
+
+/**
+ * Validates token and returns payload for both GET and POST endpoints
+ *
+ * @param {Context} c - Hono context object containing request information
+ * @returns {XMTPToolsPayload | null} The validated payload or null if invalid
+ *
+ * @description
+ * Supports two authentication methods:
+ * - Authorization header with Bearer token (for POST endpoints)
+ * - Query parameter token (for GET endpoints)
+ *
+ * @example
+ * ```typescript
+ * app.post("/api/endpoint", async (c) => {
+ *   const payload = getValidatedPayload(c);
+ *   if (!payload) {
+ *     return c.json({ error: "Invalid token" }, 401);
+ *   }
+ *   // Use payload data
+ * });
+ * ```
+ */
+export function getValidatedPayload(c: Context): XMTPToolsPayload | null {
+	// Try Authorization header first (for POST endpoints)
+	const authHeader = c.req.header("Authorization")
+	if (authHeader?.startsWith("Bearer ")) {
+		const token = authHeader.substring(7) // Remove "Bearer " prefix
+		return validateXMTPToolsToken(token)
+	}
+
+	// Fall back to query parameter (for GET endpoints)
+	const token = c.req.query("token")
+	if (!token) {
+		return null
+	}
+
+	return validateXMTPToolsToken(token)
+}
+
+/**
+ * JWT secret key used for signing and verifying tokens
+ * Uses XMTP_ENCRYPTION_KEY environment variable for consistency
+ * Only falls back to development secret in development/test environments
+ */
+const JWT_SECRET = (() => {
+	const secret = process.env.XMTP_ENCRYPTION_KEY
+	const nodeEnv = process.env.NODE_ENV || "development"
+
+	// In production, require a real JWT secret
+	if (nodeEnv === "production" && !secret) {
+		throw new Error(
+			"XMTP_ENCRYPTION_KEY environment variable is required in production. " +
+				"Generate a secure random secret for JWT token signing."
+		)
+	}
+
+	// In development/test, allow fallback but warn
+	if (!secret) {
+		console.warn(
+			"⚠️  [SECURITY] Using fallback JWT secret for development. " +
+				"Set XMTP_ENCRYPTION_KEY environment variable for production."
+		)
+		return "fallback-secret-for-dev-only"
+	}
+
+	return secret
+})()
+
+/**
+ * API key used for simple authentication bypass
+ * Requires XMTP_API_KEY environment variable in production
+ * Only falls back to development key in development/test environments
+ */
+const API_KEY = (() => {
+	const apiKey = process.env.XMTP_API_KEY
+	const nodeEnv = process.env.NODE_ENV || "development"
+
+	// In production, require a real API key
+	if (nodeEnv === "production" && !apiKey) {
+		throw new Error(
+			"XMTP_API_KEY environment variable is required in production. " +
+				"Generate a secure random API key for authentication."
+		)
+	}
+
+	// In development/test, allow fallback but warn
+	if (!apiKey) {
+		console.warn(
+			"⚠️  [SECURITY] Using fallback API key for development. " +
+				"Set XMTP_API_KEY environment variable for production."
+		)
+		return "fallback-api-key-for-dev-only"
+	}
+
+	return apiKey
+})()
+
+/**
+ * JWT token expiry time in seconds (5 minutes)
+ */
+const JWT_EXPIRY = 5 * 60 // 5 minutes in seconds
+
+/**
+ * Generates a signed JWT token for XMTP tools authentication
+ *
+ * @param {Omit<XMTPToolsPayload, "issued" | "expires">} payload - Token payload without timestamp fields
+ * @returns {string} Signed JWT token
+ *
+ * @description
+ * Creates a JWT token with automatic timestamp fields:
+ * - issued: Current timestamp
+ * - expires: Current timestamp + JWT_EXPIRY
+ *
+ * @example
+ * ```typescript
+ * const token = generateXMTPToolsToken({
+ *   action: "send",
+ *   conversationId: "0x123..."
+ * });
+ * ```
+ */
+export function generateXMTPToolsToken(
+	payload: Omit<XMTPToolsPayload, "issued" | "expires">
+): string {
+	const now = Math.floor(Date.now() / 1000)
+	const fullPayload: XMTPToolsPayload = {
+		...payload,
+		issued: now,
+		expires: now + JWT_EXPIRY
+	}
+
+	return jwt.sign(fullPayload, JWT_SECRET, {
+		expiresIn: JWT_EXPIRY
+	})
+}
+
+/**
+ * Validates an XMTP tools token using either API key or JWT verification
+ *
+ * @param {string} token - Token to validate (either API key or JWT)
+ * @returns {XMTPToolsPayload | null} Validated payload or null if invalid
+ *
+ * @description
+ * Supports two authentication methods in order of precedence:
+ * 1. API key authentication - Direct comparison with XMTP_API_KEY
+ * 2. JWT token authentication - Signature verification and expiry check
+ *
+ * For API key authentication, returns a default payload with 1-hour expiry.
+ * For JWT authentication, validates signature and checks expiry timestamp.
+ *
+ * @example
+ * ```typescript
+ * const payload = validateXMTPToolsToken(userToken);
+ * if (payload) {
+ *   console.log(`Action: ${payload.action}`);
+ *   console.log(`Conversation: ${payload.conversationId}`);
+ * }
+ * ```
+ */
+export function validateXMTPToolsToken(token: string): XMTPToolsPayload | null {
+	// First try API key authentication
+	if (token === API_KEY) {
+		console.log("🔑 [Auth] Using API key authentication")
+		// Return a valid payload for API key auth
+		const now = Math.floor(Date.now() / 1000)
+		return {
+			action: "send", // Default action
+			conversationId: "", // Will be filled by endpoint
+			issued: now,
+			expires: now + 3600 // API keys are valid for 1 hour
+		}
+	}
+
+	// Then try JWT token authentication
+	try {
+		const decoded = jwt.verify(token, JWT_SECRET) as XMTPToolsPayload
+		console.log("🔑 [Auth] Using JWT token authentication")
+
+		// Additional expiry check
+		const now = Math.floor(Date.now() / 1000)
+		if (decoded.expires < now) {
+			console.warn("🔒 XMTP tools token has expired")
+			return null
+		}
+
+		return decoded
+	} catch (error) {
+		console.error(
+			"🔒 Invalid XMTP tools token and not matching API key:",
+			error
+		)
+		return null
+	}
+}

package/src/plugin.ts

@@ -0,0 +1,39 @@
+import { Hono } from "hono"
+import xmtpEndpoints from "./endpoints"
+import type { MessageListenerConfig } from "./lib/message-listener"
+import type { HonoVariables } from "./types"
+
+export interface Plugin<TContext = unknown> {
+	name: string
+	description?: string
+	apply: (
+		app: Hono<{ Variables: HonoVariables }>,
+		context?: TContext
+	) => void | Promise<void>
+}
+
+export interface XMTPPluginContext {
+	agent: unknown
+}
+
+/**
+ * XMTP Plugin that provides XMTP functionality to the agent
+ *
+ * @description
+ * This plugin integrates XMTP messaging capabilities into the agent's
+ * HTTP server. It mounts the XMTP endpoints for handling XMTP tools requests.
+ */
+export function XMTPPlugin({
+	filter
+}: {
+	filter?: MessageListenerConfig["filter"]
+} = {}): Plugin<XMTPPluginContext> {
+	return {
+		name: "xmtp",
+		description: "Provides XMTP messaging functionality",
+		apply: (app, context) => {
+			// Mount the XMTP endpoints at /xmtp-tools
+			app.route("/xmtp-tools", xmtpEndpoints)
+		}
+	}
+}