@abraca/resend 2.16.0

package/src/bootstrap.ts

@@ -0,0 +1,182 @@
+/**
+ * Find or create the Inbox + Outbox documents under the bound Space.
+ *
+ * Idempotent: any existing top-level doc labelled "Inbox" or "Outbox" is reused
+ * as-is — the user is allowed to rename, recolor, or restructure these docs
+ * after they're created. Missing columns under the Outbox kanban are filled in.
+ */
+import { makeEntryMap, toPlain } from "@abraca/dabra";
+import * as Y from "yjs";
+import type { AbracadabraResendServer } from "./server.ts";
+
+export const INBOX_LABEL = "Inbox";
+export const OUTBOX_LABEL = "Outbox";
+
+export const OUTBOX_COLUMNS = ["Draft", "Ready", "Sent", "Failed"] as const;
+export type OutboxColumn = (typeof OUTBOX_COLUMNS)[number];
+
+export interface BootstrapResult {
+	inboxId: string;
+	outboxId: string;
+	columns: Record<OutboxColumn, string>;
+}
+
+interface TreeEntry {
+	id: string;
+	label: string;
+	parentId: string | null;
+	order: number;
+	type?: string;
+}
+
+function readEntries(
+	treeMap: Y.Map<any>,
+	selfId: string | null,
+): TreeEntry[] {
+	const entries: TreeEntry[] = [];
+	treeMap.forEach((raw: any, id: string) => {
+		if (selfId && id === selfId) return;
+		const value = toPlain(raw) as any;
+		if (typeof value !== "object" || value === null) return;
+		entries.push({
+			id,
+			label: typeof value.label === "string" ? value.label : "Untitled",
+			parentId: value.parentId ?? null,
+			order: typeof value.order === "number" ? value.order : 0,
+			type: typeof value.type === "string" ? value.type : undefined,
+		});
+	});
+	return entries;
+}
+
+async function createDoc(
+	server: AbracadabraResendServer,
+	opts: {
+		parentTreeId: string | null;
+		restParentId: string;
+		label: string;
+		type?: string;
+		meta?: Record<string, unknown>;
+		order?: number;
+	},
+): Promise<string> {
+	const treeMap = server.getTreeMap();
+	const rootDoc = server.rootDocument;
+	if (!treeMap || !rootDoc) {
+		throw new Error("Cannot create doc — server is not connected.");
+	}
+	const id = crypto.randomUUID();
+	const now = Date.now();
+
+	// Register the SQL row first so RBAC inheritance can walk
+	// `documents.parent_id` (matches @abraca/mcp's create_document path).
+	await server.client.createChild(opts.restParentId, {
+		child_id: id,
+		label: opts.label,
+		doc_type: opts.type,
+		kind: "page",
+	});
+
+	rootDoc.transact(() => {
+		treeMap.set(
+			id,
+			makeEntryMap({
+				label: opts.label,
+				parentId: opts.parentTreeId,
+				order: opts.order ?? now,
+				type: opts.type,
+				meta: opts.meta as any,
+				createdAt: now,
+				updatedAt: now,
+			}),
+		);
+	});
+
+	return id;
+}
+
+export async function bootstrap(
+	server: AbracadabraResendServer,
+): Promise<BootstrapResult> {
+	const treeMap = server.getTreeMap();
+	const spaceDocId = server.spaceDocId;
+	if (!treeMap || !spaceDocId) {
+		throw new Error("Cannot bootstrap — server is not connected.");
+	}
+	const entries = readEntries(treeMap, spaceDocId);
+
+	const topLevel = entries.filter((e) => e.parentId === null);
+	const existingInbox = topLevel.find(
+		(e) => e.label.trim().toLowerCase() === INBOX_LABEL.toLowerCase(),
+	);
+	const existingOutbox = topLevel.find(
+		(e) => e.label.trim().toLowerCase() === OUTBOX_LABEL.toLowerCase(),
+	);
+
+	// ── Inbox ──────────────────────────────────────────────────────────────
+	let inboxId: string;
+	if (existingInbox) {
+		inboxId = existingInbox.id;
+		console.error(
+			`[abracadabra-resend] Inbox found: ${inboxId} (${existingInbox.label})`,
+		);
+	} else {
+		inboxId = await createDoc(server, {
+			parentTreeId: null,
+			restParentId: spaceDocId,
+			label: INBOX_LABEL,
+			type: "gallery",
+			meta: { icon: "inbox" },
+		});
+		console.error(`[abracadabra-resend] Inbox created: ${inboxId}`);
+	}
+
+	// ── Outbox ─────────────────────────────────────────────────────────────
+	let outboxId: string;
+	if (existingOutbox) {
+		outboxId = existingOutbox.id;
+		console.error(
+			`[abracadabra-resend] Outbox found: ${outboxId} (${existingOutbox.label})`,
+		);
+	} else {
+		outboxId = await createDoc(server, {
+			parentTreeId: null,
+			restParentId: spaceDocId,
+			label: OUTBOX_LABEL,
+			type: "kanban",
+			meta: { icon: "send" },
+		});
+		console.error(`[abracadabra-resend] Outbox created: ${outboxId}`);
+	}
+
+	// ── Outbox columns ─────────────────────────────────────────────────────
+	// Re-read entries — we may have just created Inbox/Outbox.
+	const refreshedEntries = readEntries(treeMap, spaceDocId);
+	const existingColumns = refreshedEntries.filter(
+		(e) => e.parentId === outboxId,
+	);
+
+	const columns = {} as Record<OutboxColumn, string>;
+	for (const colLabel of OUTBOX_COLUMNS) {
+		const match = existingColumns.find(
+			(e) => e.label.trim().toLowerCase() === colLabel.toLowerCase(),
+		);
+		if (match) {
+			columns[colLabel] = match.id;
+			continue;
+		}
+		const id = await createDoc(server, {
+			parentTreeId: outboxId,
+			restParentId: outboxId,
+			label: colLabel,
+			// Kanban columns inherit view from the parent kanban — no type.
+			order: Date.now() + OUTBOX_COLUMNS.indexOf(colLabel),
+		});
+		columns[colLabel] = id;
+		console.error(
+			`[abracadabra-resend] Outbox column "${colLabel}" created: ${id}`,
+		);
+	}
+
+	return { inboxId, outboxId, columns };
+}

package/src/crypto.ts

@@ -0,0 +1,72 @@
+/**
+ * Ed25519 key generation, persistence, and challenge signing for the Resend bridge.
+ * Same shape as @abraca/mcp's crypto module; intentionally vendored so this package
+ * doesn't depend on @abraca/mcp.
+ */
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+ed.hashes.sha512 = sha512;
+ed.hashes.sha512Async = (m: Uint8Array) => Promise.resolve(sha512(m));
+
+const DEFAULT_KEY_PATH = join(homedir(), ".abracadabra", "resend.key");
+
+function toBase64url(bytes: Uint8Array): string {
+	return Buffer.from(bytes).toString("base64url");
+}
+
+function fromBase64url(b64: string): Uint8Array {
+	return new Uint8Array(Buffer.from(b64, "base64url"));
+}
+
+export interface AgentKeypair {
+	privateKey: Uint8Array;
+	publicKeyB64: string;
+}
+
+export async function loadOrCreateKeypair(
+	keyPath?: string,
+): Promise<AgentKeypair> {
+	const path = keyPath || DEFAULT_KEY_PATH;
+
+	if (existsSync(path)) {
+		const seed = await readFile(path);
+		if (seed.length !== 32) {
+			throw new Error(
+				`Invalid key file at ${path}: expected 32 bytes, got ${seed.length}`,
+			);
+		}
+		const privateKey = new Uint8Array(seed);
+		const publicKey = ed.getPublicKey(privateKey);
+		return { privateKey, publicKeyB64: toBase64url(publicKey) };
+	}
+
+	const privateKey = ed.utils.randomSecretKey();
+	const publicKey = ed.getPublicKey(privateKey);
+
+	const dir = dirname(path);
+	if (!existsSync(dir)) {
+		await mkdir(dir, { recursive: true, mode: 0o700 });
+	}
+	await writeFile(path, Buffer.from(privateKey), { mode: 0o600 });
+
+	console.error(`[abracadabra-resend] Generated new agent keypair at ${path}`);
+	console.error(
+		`[abracadabra-resend] Public key: ${toBase64url(publicKey)}`,
+	);
+
+	return { privateKey, publicKeyB64: toBase64url(publicKey) };
+}
+
+export function signChallenge(
+	challengeB64: string,
+	privateKey: Uint8Array,
+): string {
+	const challenge = fromBase64url(challengeB64);
+	const sig = ed.sign(challenge, privateKey);
+	return toBase64url(sig);
+}

package/src/inbound-server.ts

@@ -0,0 +1,413 @@
+/**
+ * Inbound webhook HTTP server.
+ *
+ * Single POST route: `/inbound`. Verifies Svix signature, parses Resend Inbound
+ * payload, creates a child doc under the Inbox, uploads attachments. Operator
+ * is responsible for exposing the port publicly (tunnel / reverse proxy) and
+ * configuring Resend Inbound to deliver here.
+ */
+import { makeEntryMap } from "@abraca/dabra";
+import { populateYDocFromMarkdown as populateBody } from "@abraca/convert";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import {
+	createServer,
+	type IncomingMessage,
+	type Server,
+	type ServerResponse,
+} from "node:http";
+import type { BootstrapResult } from "./bootstrap.ts";
+import type { AbracadabraResendServer } from "./server.ts";
+import { waitForSync } from "./utils.ts";
+
+export interface InboundServerOptions {
+	server: AbracadabraResendServer;
+	bootstrap: BootstrapResult;
+	secret: string;
+	port?: number;
+	host?: string;
+	/** Reject deliveries whose timestamp is older than this many seconds. */
+	toleranceSeconds?: number;
+}
+
+interface ResendInboundAttachment {
+	filename?: string;
+	contentType?: string;
+	content?: string; // base64
+}
+
+interface ResendInboundData {
+	id?: string;
+	from?: string | { email?: string; name?: string };
+	to?: Array<string | { email?: string; name?: string }> | string;
+	cc?: Array<string | { email?: string; name?: string }> | string;
+	subject?: string;
+	text?: string;
+	html?: string;
+	headers?: Array<{ name: string; value: string }>;
+	attachments?: ResendInboundAttachment[];
+	created_at?: string;
+}
+
+interface ResendInboundEnvelope {
+	type?: string;
+	data?: ResendInboundData;
+}
+
+function addr(v: unknown): string | undefined {
+	if (typeof v === "string") return v.trim() || undefined;
+	if (v && typeof v === "object") {
+		const obj = v as { email?: string; name?: string };
+		if (typeof obj.email === "string") return obj.email.trim() || undefined;
+	}
+	return undefined;
+}
+
+function addrList(v: unknown): string[] {
+	if (Array.isArray(v))
+		return v.map(addr).filter((s): s is string => !!s);
+	const one = addr(v);
+	return one ? [one] : [];
+}
+
+function pickHeader(
+	headers: Array<{ name: string; value: string }> | undefined,
+	name: string,
+): string | undefined {
+	if (!headers) return undefined;
+	const lower = name.toLowerCase();
+	for (const h of headers) {
+		if (typeof h?.name === "string" && h.name.toLowerCase() === lower) {
+			return h.value;
+		}
+	}
+	return undefined;
+}
+
+function decodeSecret(secret: string): Buffer {
+	// Resend / Svix webhook secrets are `whsec_<base64>`. The HMAC key is the
+	// base64-decoded bytes after the prefix. Accept raw secrets too so the
+	// operator can supply a hex/base64 key directly if their plan differs.
+	const stripped = secret.startsWith("whsec_") ? secret.slice(6) : secret;
+	try {
+		return Buffer.from(stripped, "base64");
+	} catch {
+		return Buffer.from(stripped);
+	}
+}
+
+function constantTimeEquals(a: Buffer, b: Buffer): boolean {
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+
+/**
+ * Verify Svix-style signature. Headers carry `svix-id`, `svix-timestamp`,
+ * `svix-signature` (space-separated `v1,<base64>` pairs). The signing input
+ * is `${id}.${timestamp}.${body}` HMAC-SHA256 with the decoded secret.
+ */
+function verifySignature(
+	body: string,
+	headers: IncomingMessage["headers"],
+	secret: Buffer,
+	toleranceSeconds: number,
+): { ok: true } | { ok: false; reason: string } {
+	const id = headers["svix-id"];
+	const ts = headers["svix-timestamp"];
+	const sig = headers["svix-signature"];
+	if (typeof id !== "string" || typeof ts !== "string" || typeof sig !== "string") {
+		return { ok: false, reason: "missing Svix headers" };
+	}
+	const tsNum = Number(ts);
+	if (!Number.isFinite(tsNum)) {
+		return { ok: false, reason: "invalid svix-timestamp" };
+	}
+	const ageSec = Math.abs(Math.floor(Date.now() / 1000) - tsNum);
+	if (ageSec > toleranceSeconds) {
+		return { ok: false, reason: `delivery too old (${ageSec}s)` };
+	}
+
+	const toSign = `${id}.${ts}.${body}`;
+	const expected = createHmac("sha256", secret).update(toSign).digest();
+
+	const candidates = sig.split(" ").map((s) => s.trim()).filter(Boolean);
+	for (const candidate of candidates) {
+		const [version, value] = candidate.split(",");
+		if (version !== "v1" || !value) continue;
+		let provided: Buffer;
+		try {
+			provided = Buffer.from(value, "base64");
+		} catch {
+			continue;
+		}
+		if (constantTimeEquals(expected, provided)) return { ok: true };
+	}
+	return { ok: false, reason: "signature mismatch" };
+}
+
+function readBody(req: IncomingMessage, maxBytes = 25 * 1024 * 1024): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+		let size = 0;
+		req.on("data", (chunk: Buffer) => {
+			size += chunk.length;
+			if (size > maxBytes) {
+				reject(new Error(`payload too large (>${maxBytes} bytes)`));
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		req.on("error", reject);
+	});
+}
+
+export class InboundServer {
+	private readonly server: AbracadabraResendServer;
+	private readonly bootstrap: BootstrapResult;
+	private readonly secret: Buffer;
+	private readonly toleranceSeconds: number;
+	private readonly port: number;
+	private readonly host: string;
+	private httpServer: Server | null = null;
+	/** De-dupes redelivered webhooks. Svix may retry on transient failures. */
+	private readonly seenSvixIds = new Set<string>();
+
+	constructor(opts: InboundServerOptions) {
+		this.server = opts.server;
+		this.bootstrap = opts.bootstrap;
+		this.secret = decodeSecret(opts.secret);
+		this.toleranceSeconds = opts.toleranceSeconds ?? 5 * 60;
+		this.port = opts.port ?? 0;
+		this.host = opts.host ?? "0.0.0.0";
+	}
+
+	async start(): Promise<number> {
+		this.httpServer = createServer((req, res) => {
+			void this.handle(req, res);
+		});
+		await new Promise<void>((resolve, reject) => {
+			this.httpServer!.once("error", reject);
+			this.httpServer!.listen(this.port, this.host, () => resolve());
+		});
+		const address = this.httpServer.address();
+		const boundPort =
+			typeof address === "object" && address ? address.port : this.port;
+		console.error(
+			`[abracadabra-resend] Inbound server listening on http://${this.host}:${boundPort}/inbound`,
+		);
+		return boundPort;
+	}
+
+	async stop(): Promise<void> {
+		if (!this.httpServer) return;
+		await new Promise<void>((resolve, reject) => {
+			this.httpServer!.close((err) => (err ? reject(err) : resolve()));
+		});
+		this.httpServer = null;
+	}
+
+	private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+		try {
+			if (req.method === "GET" && (req.url === "/health" || req.url === "/")) {
+				res.writeHead(200, { "content-type": "text/plain" });
+				res.end("ok");
+				return;
+			}
+			if (req.method !== "POST" || req.url !== "/inbound") {
+				res.writeHead(404, { "content-type": "text/plain" });
+				res.end("not found");
+				return;
+			}
+			const body = await readBody(req);
+			const check = verifySignature(
+				body,
+				req.headers,
+				this.secret,
+				this.toleranceSeconds,
+			);
+			if (!check.ok) {
+				console.error(`[abracadabra-resend] inbound rejected: ${check.reason}`);
+				res.writeHead(401, { "content-type": "text/plain" });
+				res.end("unauthorized");
+				return;
+			}
+
+			const svixId =
+				typeof req.headers["svix-id"] === "string"
+					? (req.headers["svix-id"] as string)
+					: null;
+			if (svixId && this.seenSvixIds.has(svixId)) {
+				res.writeHead(200, { "content-type": "text/plain" });
+				res.end("duplicate");
+				return;
+			}
+			if (svixId) {
+				this.seenSvixIds.add(svixId);
+				if (this.seenSvixIds.size > 5000) {
+					const first = this.seenSvixIds.values().next().value;
+					if (first) this.seenSvixIds.delete(first);
+				}
+			}
+
+			let env: ResendInboundEnvelope;
+			try {
+				env = JSON.parse(body);
+			} catch {
+				res.writeHead(400, { "content-type": "text/plain" });
+				res.end("invalid json");
+				return;
+			}
+
+			const data = env?.data ?? (env as unknown as ResendInboundData);
+			await this.ingest(data);
+
+			res.writeHead(200, { "content-type": "text/plain" });
+			res.end("ok");
+		} catch (err: any) {
+			console.error(
+				`[abracadabra-resend] inbound handler error: ${err?.message ?? err}`,
+			);
+			res.writeHead(500, { "content-type": "text/plain" });
+			res.end("error");
+		}
+	}
+
+	private async ingest(data: ResendInboundData): Promise<void> {
+		await this.server.ensureConnected();
+		const treeMap = this.server.getTreeMap();
+		const rootDoc = this.server.rootDocument;
+		if (!treeMap || !rootDoc) {
+			throw new Error("Cannot ingest — server is not connected.");
+		}
+
+		const subjectRaw = typeof data.subject === "string" ? data.subject.trim() : "";
+		const subject = subjectRaw.length > 0 ? subjectRaw : "(no subject)";
+		const from = addr(data.from) ?? "(unknown)";
+		const to = addrList(data.to);
+		const cc = addrList(data.cc);
+		const inReplyTo = pickHeader(data.headers, "In-Reply-To");
+		const messageId =
+			pickHeader(data.headers, "Message-ID") ?? data.id ?? null;
+
+		const inboxId = this.bootstrap.inboxId;
+		const id = crypto.randomUUID();
+		const now = Date.now();
+
+		const meta: Record<string, unknown> = {
+			icon: "mail",
+			from,
+			to,
+			cc: cc.length ? cc : undefined,
+			subject,
+			receivedAt: now,
+			messageId,
+			inReplyTo,
+		};
+		if (typeof data.html === "string" && data.html.length > 0) {
+			meta.html = data.html;
+		}
+
+		// SQL row first, then Yjs entry — RBAC cascade depends on it.
+		await this.server.client.createChild(inboxId, {
+			child_id: id,
+			label: subject,
+			doc_type: "doc",
+			kind: "page",
+		});
+
+		rootDoc.transact(() => {
+			treeMap.set(
+				id,
+				makeEntryMap({
+					label: subject,
+					parentId: inboxId,
+					order: now,
+					type: "doc",
+					meta: meta as any,
+					createdAt: now,
+					updatedAt: now,
+				}),
+			);
+		});
+
+		// Populate the body with the plain-text version (Resend always provides
+		// one). Falls back to a notice when neither text nor html is present.
+		const provider = await this.server.getChildProvider(id);
+		await waitForSync(provider);
+		const fragment = provider.document.getXmlFragment("default");
+		const body =
+			(typeof data.text === "string" && data.text.length > 0
+				? data.text
+				: typeof data.html === "string" && data.html.length > 0
+					? `<details><summary>HTML email (no text part)</summary>\n\n\`\`\`html\n${data.html}\n\`\`\`\n</details>`
+					: "(empty body)");
+		populateBody(fragment, body, subject);
+
+		// Attachments — base64 → Blob → REST upload. Store upload metadata back
+		// on the doc so consumers can render previews / download.
+		const attached: Array<{
+			id: string;
+			filename: string;
+			contentType?: string;
+			size: number;
+		}> = [];
+		const attachments = Array.isArray(data.attachments) ? data.attachments : [];
+		for (const att of attachments) {
+			if (typeof att?.content !== "string") continue;
+			const filename =
+				typeof att.filename === "string" && att.filename.length > 0
+					? att.filename
+					: "attachment";
+			try {
+				const bytes = Buffer.from(att.content, "base64");
+				const blob = new Blob([bytes], {
+					type: att.contentType ?? "application/octet-stream",
+				});
+				const uploaded = await this.server.client.upload(id, blob, filename);
+				const uploadedId =
+					(uploaded as { id?: string; uploadId?: string })?.id ??
+					(uploaded as { uploadId?: string })?.uploadId ??
+					"";
+				attached.push({
+					id: uploadedId,
+					filename,
+					contentType: att.contentType,
+					size: bytes.length,
+				});
+			} catch (err: any) {
+				console.error(
+					`[abracadabra-resend] attachment upload failed (${filename}): ${err?.message ?? err}`,
+				);
+			}
+		}
+		if (attached.length > 0) {
+			const existingRaw = treeMap.get(id);
+			if (existingRaw) {
+				const existingMeta =
+					(typeof (existingRaw as any).toJSON === "function"
+						? (existingRaw as any).toJSON()?.meta
+						: (existingRaw as any).meta) ?? {};
+				rootDoc.transact(() => {
+					treeMap.set(
+						id,
+						makeEntryMap({
+							label: subject,
+							parentId: inboxId,
+							order: now,
+							type: "doc",
+							meta: { ...existingMeta, attachments: attached },
+							createdAt: now,
+							updatedAt: Date.now(),
+						}),
+					);
+				});
+			}
+		}
+
+		console.error(
+			`[abracadabra-resend] inbound stored: "${subject}" from ${from} → doc ${id}`,
+		);
+	}
+}
+