@hybrd/channels 2.0.0

package/src/adapters/xmtp/adapter.test.ts

@@ -0,0 +1,167 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+
+const TEST_DIR = join("/tmp", "hybrid-xmtp-acl-test", Date.now().toString())
+
+beforeEach(() => {
+	if (existsSync(TEST_DIR)) {
+		rmSync(TEST_DIR, { recursive: true })
+	}
+	mkdirSync(TEST_DIR, { recursive: true })
+})
+
+afterEach(() => {
+	if (existsSync(TEST_DIR)) {
+		rmSync(TEST_DIR, { recursive: true })
+	}
+})
+
+describe("ACL Filtering Logic", () => {
+	describe("allowlist reading", () => {
+		it("returns empty array when file doesn't exist", async () => {
+			const { readACLAllowFrom } = await import("@hybrid/memory")
+			const allowFrom = await readACLAllowFrom(TEST_DIR)
+			expect(allowFrom).toEqual([])
+		})
+
+		it("returns allowlist from file", async () => {
+			const credentialsDir = join(TEST_DIR, "credentials")
+			mkdirSync(credentialsDir, { recursive: true })
+
+			writeFileSync(
+				join(credentialsDir, "xmtp-allowFrom.json"),
+				JSON.stringify({
+					version: 1,
+					allowFrom: ["0xallowed1", "0xallowed2"]
+				})
+			)
+
+			const { readACLAllowFrom } = await import("@hybrid/memory")
+			const allowFrom = await readACLAllowFrom(TEST_DIR)
+			expect(allowFrom).toEqual(["0xallowed1", "0xallowed2"])
+		})
+	})
+
+	describe("allowlist checking", () => {
+		it("allows all when allowlist is empty", async () => {
+			const credentialsDir = join(TEST_DIR, "credentials")
+			mkdirSync(credentialsDir, { recursive: true })
+
+			writeFileSync(
+				join(credentialsDir, "xmtp-allowFrom.json"),
+				JSON.stringify({ version: 1, allowFrom: [] })
+			)
+
+			const { readACLAllowFrom } = await import("@hybrid/memory")
+			const allowFrom = await readACLAllowFrom(TEST_DIR)
+
+			// Empty allowlist = open to all
+			expect(allowFrom.length).toBe(0)
+		})
+
+		it("allows addresses on the list", async () => {
+			const credentialsDir = join(TEST_DIR, "credentials")
+			mkdirSync(credentialsDir, { recursive: true })
+
+			writeFileSync(
+				join(credentialsDir, "xmtp-allowFrom.json"),
+				JSON.stringify({
+					version: 1,
+					allowFrom: ["0xabc", "0xdef"]
+				})
+			)
+
+			const { readACLAllowFrom } = await import("@hybrid/memory")
+			const allowFrom = await readACLAllowFrom(TEST_DIR)
+
+			// Check membership
+			expect(allowFrom.includes("0xabc")).toBe(true)
+			expect(allowFrom.includes("0xdef")).toBe(true)
+			expect(allowFrom.includes("0xxyz")).toBe(false)
+		})
+
+		it("normalizes addresses to lowercase", async () => {
+			const credentialsDir = join(TEST_DIR, "credentials")
+			mkdirSync(credentialsDir, { recursive: true })
+
+			writeFileSync(
+				join(credentialsDir, "xmtp-allowFrom.json"),
+				JSON.stringify({
+					version: 1,
+					allowFrom: ["0xABC123"]
+				})
+			)
+
+			const { readACLAllowFrom } = await import("@hybrid/memory")
+			const allowFrom = await readACLAllowFrom(TEST_DIR)
+
+			// Should be normalized to lowercase
+			expect(allowFrom).toContain("0xabc123")
+			expect(allowFrom).not.toContain("0xABC123")
+		})
+	})
+})
+
+describe("XMTP Adapter Integration", () => {
+	it("blocks message from non-allowed sender", async () => {
+		const credentialsDir = join(TEST_DIR, "credentials")
+		mkdirSync(credentialsDir, { recursive: true })
+
+		writeFileSync(
+			join(credentialsDir, "xmtp-allowFrom.json"),
+			JSON.stringify({
+				version: 1,
+				allowFrom: ["0xallowed"]
+			})
+		)
+
+		const { readACLAllowFrom } = await import("@hybrid/memory")
+		const allowFrom = await readACLAllowFrom(TEST_DIR)
+
+		// Simulate the check the adapter would do
+		const senderAddress = "0xblocked"
+		const isAllowed =
+			allowFrom.length === 0 || allowFrom.includes(senderAddress.toLowerCase())
+
+		expect(isAllowed).toBe(false)
+	})
+
+	it("allows message from allowed sender", async () => {
+		const credentialsDir = join(TEST_DIR, "credentials")
+		mkdirSync(credentialsDir, { recursive: true })
+
+		writeFileSync(
+			join(credentialsDir, "xmtp-allowFrom.json"),
+			JSON.stringify({
+				version: 1,
+				allowFrom: ["0xallowed"]
+			})
+		)
+
+		const { readACLAllowFrom } = await import("@hybrid/memory")
+		const allowFrom = await readACLAllowFrom(TEST_DIR)
+
+		// Simulate the check the adapter would do
+		const senderAddress = "0xallowed"
+		const isAllowed =
+			allowFrom.length === 0 || allowFrom.includes(senderAddress.toLowerCase())
+
+		expect(isAllowed).toBe(true)
+	})
+
+	it("allows all messages when no allowlist configured", async () => {
+		const { readACLAllowFrom } = await import("@hybrid/memory")
+		const allowFrom = await readACLAllowFrom(TEST_DIR)
+
+		// No allowlist file = open
+		expect(allowFrom.length).toBe(0)
+
+		// Any sender should be allowed
+		const senderAddress = "0xanyone"
+		const isAllowed =
+			allowFrom.length === 0 || allowFrom.includes(senderAddress.toLowerCase())
+
+		expect(isAllowed).toBe(true)
+	})
+})

package/src/adapters/xmtp/adapter.ts

@@ -0,0 +1,307 @@
+import { randomUUID } from "node:crypto"
+import type { Server } from "node:http"
+import type {
+	ChannelAdapter,
+	ChannelId,
+	TriggerRequest,
+	TriggerResponse
+} from "@hybrd/types"
+import { readACLAllowFrom } from "@hybrid/memory"
+import { Agent } from "@xmtp/agent-sdk"
+import type { Conversation } from "@xmtp/node-sdk"
+import express from "express"
+import pc from "picocolors"
+
+const log = {
+	info: (msg: string) => console.log(`${pc.magenta("[xmtp]")} ${msg}`),
+	error: (msg: string) => console.error(`${pc.red("[xmtp]")} ${msg}`),
+	warn: (msg: string) => console.log(`${pc.yellow("[xmtp]")} ${msg}`),
+	success: (msg: string) => console.log(`${pc.green("[xmtp]")} ${msg}`)
+}
+
+export interface XMTPAdapterConfig {
+	port: number
+	agentUrl: string
+	xmtpEnv?: "dev" | "production"
+	walletKey: `0x${string}`
+	dbEncryptionKey: Uint8Array
+	dbPath: string
+	workspaceDir?: string
+}
+
+interface TextMessage {
+	id: string
+	content: string
+	senderInboxId: string
+}
+
+export class XMTPAdapter implements ChannelAdapter {
+	readonly channel: ChannelId = "xmtp"
+	readonly port: number
+
+	private config: XMTPAdapterConfig
+	private agent: Agent | null = null
+	private server: Server | null = null
+	private app: express.Application
+	private botInboxId: string | null = null
+	private processedMessages: Set<string> = new Set()
+	private addressCache: Map<string, string> = new Map()
+
+	constructor(config: XMTPAdapterConfig) {
+		this.port = config.port
+		this.config = config
+		this.app = express()
+		this.app.use(express.json())
+	}
+
+	async start(): Promise<void> {
+		await this.startXMTPClient()
+		this.startTriggerServer()
+	}
+
+	async stop(): Promise<void> {
+		this.server?.close()
+	}
+
+	private async startXMTPClient(): Promise<void> {
+		const { createUser } = await import("@xmtp/agent-sdk")
+		const { toBytes } = await import("viem")
+
+		const user = createUser(this.config.walletKey)
+		const identifier = {
+			identifier: user.account.address.toLowerCase(),
+			identifierKind: 0
+		}
+
+		const signer = {
+			type: "EOA" as const,
+			getIdentifier: () => identifier,
+			getChainId: async () => BigInt(1),
+			signMessage: async (message: string) => {
+				const sig = await user.account.signMessage({ message })
+				return toBytes(sig)
+			}
+		}
+
+		this.agent = await Agent.create(
+			signer as unknown as Parameters<typeof Agent.create>[0],
+			{
+				env: this.config.xmtpEnv ?? "dev",
+				dbEncryptionKey: this.config.dbEncryptionKey,
+				dbPath: this.config.dbPath
+			}
+		)
+
+		log.success("connected to XMTP network")
+
+		this.botInboxId = this.agent.client.inboxId
+
+		this.agent.on("text", async (ctx) => {
+			const { conversation, message } = ctx
+			await this.handleInbound(conversation, message as TextMessage)
+		})
+
+		await this.agent.start()
+		log.success("listening for XMTP messages")
+	}
+
+	private startTriggerServer(): void {
+		this.app.post("/api/trigger", async (req, res) => {
+			const result = await this.handleTrigger(req.body)
+			res.json(result)
+		})
+
+		this.server = this.app.listen(this.port, "127.0.0.1", () => {
+			log.success(`trigger server listening on 127.0.0.1:${this.port}`)
+		})
+	}
+
+	private async resolveSenderAddress(
+		inboxId: string,
+		conversation: Conversation
+	): Promise<string> {
+		const cached = this.addressCache.get(inboxId)
+		if (cached) return cached
+
+		try {
+			const members = await conversation.members()
+			const sender = members.find(
+				(m: any) => m.inboxId.toLowerCase() === inboxId.toLowerCase()
+			)
+
+			if (sender) {
+				const ethIdentifier = sender.accountIdentifiers.find(
+					(id: any) => id.identifierKind === 0
+				)
+				if (ethIdentifier) {
+					const address = ethIdentifier.identifier.toLowerCase()
+					this.addressCache.set(inboxId, address)
+					return address
+				}
+			}
+
+			const inboxState =
+				await this.agent?.client.preferences.inboxStateFromInboxIds([inboxId])
+			const firstState = inboxState?.[0]
+			if (firstState?.identifiers?.[0]?.identifier) {
+				const address = firstState.identifiers[0].identifier.toLowerCase()
+				this.addressCache.set(inboxId, address)
+				return address
+			}
+		} catch (err) {
+			log.warn(`failed to resolve address for ${inboxId.slice(0, 16)}...`)
+		}
+
+		return inboxId
+	}
+
+	private async isSenderAllowed(senderAddress: string): Promise<boolean> {
+		if (!this.config.workspaceDir) {
+			return true
+		}
+
+		try {
+			const allowFrom = await readACLAllowFrom(this.config.workspaceDir)
+			if (allowFrom.length === 0) {
+				return true
+			}
+			const normalized = senderAddress.toLowerCase()
+			return allowFrom.includes(normalized)
+		} catch (err) {
+			log.warn(`failed to read ACL, allowing sender: ${(err as Error).message}`)
+			return true
+		}
+	}
+
+	private async handleInbound(
+		conversation: Conversation,
+		message: TextMessage
+	): Promise<void> {
+		log.info(`message ${pc.gray(message.id.slice(0, 8))}`)
+
+		if (this.processedMessages.has(message.id)) {
+			log.warn(`skipping duplicate: ${message.id.slice(0, 8)}`)
+			return
+		}
+		this.processedMessages.add(message.id)
+
+		if (this.processedMessages.size > 1000) {
+			const arr = Array.from(this.processedMessages)
+			arr.slice(0, 500).forEach((id) => this.processedMessages.delete(id))
+		}
+
+		// Check if sender is on the allowlist
+		const senderAddress = await this.resolveSenderAddress(
+			message.senderInboxId,
+			conversation
+		)
+		const isAllowed = await this.isSenderAllowed(senderAddress)
+
+		if (!isAllowed) {
+			log.warn(
+				`blocked message from ${senderAddress.slice(0, 10)}... (not on allowlist)`
+			)
+			return
+		}
+
+		await this.runAgentAndReply({
+			conversationId: conversation.id,
+			message: message.content,
+			conversation
+		})
+	}
+
+	async trigger(req: TriggerRequest): Promise<TriggerResponse> {
+		return this.handleTrigger(req)
+	}
+
+	private async handleTrigger(req: TriggerRequest): Promise<TriggerResponse> {
+		if (!this.agent) {
+			return { delivered: false, error: "XMTP client not initialized" }
+		}
+
+		const conversations = await this.agent.client.conversations.list()
+		const conversation = conversations.find(
+			(c: Conversation) => c.id === req.to
+		)
+
+		if (!conversation) {
+			return { delivered: false, error: "Conversation not found" }
+		}
+
+		return this.runAgentAndReply({
+			conversationId: req.to,
+			message: req.message,
+			conversation
+		})
+	}
+
+	private async runAgentAndReply(params: {
+		conversationId: string
+		message: string
+		conversation: Conversation
+	}): Promise<TriggerResponse> {
+		const { conversation, message, conversationId } = params
+
+		try {
+			const res = await fetch(`${this.config.agentUrl}/api/chat`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-Request-ID": randomUUID(),
+					"X-Source": "xmtp-adapter"
+				},
+				body: JSON.stringify({
+					messages: [{ id: randomUUID(), role: "user", content: message }],
+					chatId: conversationId
+				})
+			})
+
+			if (!res.ok) {
+				log.error(`HTTP ${res.status}`)
+				return { delivered: false, error: `HTTP ${res.status}` }
+			}
+
+			const reader = res.body?.getReader()
+			if (!reader) {
+				return { delivered: false, error: "No response body" }
+			}
+
+			const decoder = new TextDecoder()
+			let reply = ""
+
+			while (true) {
+				const { done, value } = await reader.read()
+				if (done) break
+
+				for (const line of decoder.decode(value).split("\n")) {
+					if (line.startsWith("data: ") && line !== "data: [DONE]") {
+						try {
+							const p = JSON.parse(line.slice(6))
+							if (p.type === "text" && p.content) reply += p.content
+						} catch {}
+					}
+				}
+			}
+
+			if (reply) {
+				await conversation.send(reply)
+				log.success(`replied (${reply.length} chars)`)
+				return { delivered: true }
+			}
+
+			return { delivered: false, error: "No reply generated" }
+		} catch (err) {
+			log.error((err as Error).message)
+			return { delivered: false, error: (err as Error).message }
+		}
+	}
+}
+
+export async function createXMTPAdapter(
+	config: XMTPAdapterConfig
+): Promise<XMTPAdapter> {
+	const adapter = new XMTPAdapter(config)
+	await adapter.start()
+	return adapter
+}

package/src/adapters/xmtp/index.ts

@@ -0,0 +1,138 @@
+import fs from "node:fs"
+import path from "node:path"
+import { resolveAgentSecret } from "@hybrd/xmtp"
+import { readACLAllowFrom } from "@hybrid/memory"
+import { createUser } from "@xmtp/agent-sdk"
+import pc from "picocolors"
+import { type XMTPAdapterConfig } from "./adapter.js"
+
+const log = {
+	info: (msg: string) => console.log(`${pc.magenta("[xmtp]")} ${msg}`),
+	error: (msg: string) => console.error(`${pc.red("[xmtp]")} ${msg}`),
+	warn: (msg: string) => console.log(`${pc.yellow("[xmtp]")} ${msg}`),
+	success: (msg: string) => console.log(`${pc.green("[xmtp]")} ${msg}`)
+}
+
+const AGENT_PORT = process.env.AGENT_PORT || "8454"
+const XMTP_ENV = (process.env.XMTP_ENV || "dev") as "dev" | "production"
+const XMTP_ADAPTER_PORT = Number.parseInt(
+	process.env.XMTP_ADAPTER_PORT || "8455",
+	10
+)
+
+process.on("uncaughtException", (err) => {
+	log.error(`FATAL: ${err.message}`)
+	process.exit(1)
+})
+
+process.on("unhandledRejection", (reason) => {
+	log.error(`FATAL: ${reason}`)
+	process.exit(1)
+})
+
+function printBanner(walletAddress?: string, aclCount?: number) {
+	const isHotReload = process.env.TSX_WATCH === "true"
+
+	console.log("")
+	console.log(
+		pc.magenta("  ╭───────────────────────────────────────────────────╮")
+	)
+	console.log(
+		pc.magenta("  │") +
+			pc.bold(pc.white("      XMTP Channel Adapter")) +
+			pc.magenta("                       │")
+	)
+	console.log(
+		pc.magenta("  ╰───────────────────────────────────────────────────╯")
+	)
+	console.log("")
+	console.log(
+		`  ${pc.bold("Network")}    ${XMTP_ENV === "production" ? pc.green("production") : pc.cyan("dev")}`
+	)
+	console.log(
+		`  ${pc.bold("Wallet")}     ${walletAddress ? pc.cyan(walletAddress) : pc.gray("(not configured)")}`
+	)
+	console.log(`  ${pc.bold("Agent")}      http://localhost:${AGENT_PORT}`)
+	console.log(
+		`  ${pc.bold("Trigger")}    http://127.0.0.1:${XMTP_ADAPTER_PORT}/api/trigger`
+	)
+	if (aclCount !== undefined) {
+		const aclStatus =
+			aclCount > 0
+				? pc.green(`${aclCount} allowed`)
+				: pc.yellow("open (no allowlist)")
+		console.log(`  ${pc.bold("ACL")}        ${aclStatus}`)
+	}
+	console.log("")
+
+	if (isHotReload) {
+		console.log(
+			`  ${pc.yellow("⚡")} Hot reload enabled - watching for changes...`
+		)
+	} else {
+		console.log(`  ${pc.green("✓")} Listening for messages...`)
+	}
+	console.log("")
+}
+
+async function start() {
+	const key = process.env.AGENT_WALLET_KEY
+
+	if (!key) {
+		log.warn("AGENT_WALLET_KEY not set")
+		printBanner()
+		await new Promise(() => {})
+		return
+	}
+
+	const user = createUser(key as `0x${string}`)
+
+	// Read ACL count for banner
+	let aclCount: number | undefined
+	try {
+		const allowFrom = await readACLAllowFrom(process.cwd())
+		aclCount = allowFrom.length
+	} catch {
+		// ACL doesn't exist yet, that's fine
+		aclCount = 0
+	}
+
+	printBanner(user.account.address, aclCount)
+
+	const secret = resolveAgentSecret(key)
+	const dbEncryptionKey = new Uint8Array(Buffer.from(secret, "hex"))
+
+	const dbDir = path.join(process.cwd(), ".hybrid", ".xmtp")
+	if (!fs.existsSync(dbDir)) {
+		fs.mkdirSync(dbDir, { recursive: true })
+	}
+	const dbPath = path.join(
+		dbDir,
+		`xmtp-${XMTP_ENV}-${user.account.address.toLowerCase().slice(0, 8)}.db3`
+	)
+
+	const config: XMTPAdapterConfig = {
+		port: XMTP_ADAPTER_PORT,
+		agentUrl: `http://localhost:${AGENT_PORT}`,
+		xmtpEnv: XMTP_ENV,
+		walletKey: key as `0x${string}`,
+		dbEncryptionKey,
+		dbPath,
+		workspaceDir: process.cwd()
+	}
+
+	await import("./adapter.js").then(({ createXMTPAdapter }) =>
+		createXMTPAdapter(config)
+	)
+}
+
+start().catch((e) => {
+	log.error(e.message)
+	process.exit(1)
+})
+
+export {
+	XMTPAdapter,
+	type XMTPAdapterConfig,
+	createXMTPAdapter
+} from "./adapter.js"

package/src/dispatcher.ts

@@ -0,0 +1,51 @@
+import type { ChannelId, TriggerRequest, TriggerResponse } from "@hybrd/types"
+
+export const DEFAULT_ADAPTER_PORTS: Record<string, number> = {
+	xmtp: 8455
+	// telegram: 8456,  // future
+	// slack: 8457,     // future
+}
+
+export async function dispatchToChannel(params: {
+	channel: ChannelId
+	to: string
+	message: string
+	metadata?: TriggerRequest["metadata"]
+}): Promise<TriggerResponse> {
+	const port = DEFAULT_ADAPTER_PORTS[params.channel]
+
+	if (!port) {
+		return { delivered: false, error: `Unknown channel: ${params.channel}` }
+	}
+
+	const url = `http://127.0.0.1:${port}/api/trigger`
+
+	try {
+		const res = await fetch(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				to: params.to,
+				message: params.message,
+				metadata: params.metadata
+			})
+		})
+
+		if (!res.ok) {
+			return {
+				delivered: false,
+				error: `Channel adapter returned ${res.status}: ${res.statusText}`
+			}
+		}
+
+		return (await res.json()) as TriggerResponse
+	} catch (err) {
+		return {
+			delivered: false,
+			error:
+				err instanceof Error
+					? err.message
+					: "Failed to connect to channel adapter"
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export type {
+	ChannelId,
+	CronDeliveryMode,
+	CronDelivery,
+	TriggerRequest,
+	TriggerResponse,
+	ChannelAdapter,
+	ChannelDispatcher
+} from "@hybrd/types"
+
+export { dispatchToChannel, DEFAULT_ADAPTER_PORTS } from "./dispatcher.js"