@c9up/goldstone 0.0.0-stage → 0.1.0

package/src/inbound/context.ts

@@ -0,0 +1,92 @@
+/**
+ * What an inbound handler needs from the HTTP request, structurally — a
+ * Ream `HttpContext` fits, and so does a plain object in a test.
+ */
+
+import { GoldstoneError } from "../errors.js";
+
+export interface InboundResponse {
+	status(code: number): InboundResponse;
+	json(data: unknown): void;
+}
+
+export interface InboundHttpContext {
+	request: {
+		/**
+		 * The parsed BODY only — never merged with the query string, where a
+		 * caller could set a field the provider did not sign.
+		 */
+		body(): unknown;
+	};
+	response: InboundResponse;
+}
+
+/**
+ * Remembers the tokens of deliveries already handled, so a captured
+ * request cannot be replayed. The in-memory default covers one process;
+ * several instances need a shared store (Redis…) behind this interface.
+ */
+export interface ReplayGuard {
+	/**
+	 * Take the token for `ttlSeconds`. `false` when it is already taken — a
+	 * delivery handled, or being handled right now. Must be atomic: two
+	 * requests racing with the same token must not both get `true`.
+	 */
+	claim(token: string, ttlSeconds: number): boolean | Promise<boolean>;
+	/** Give a token back, so a delivery whose handling failed can be retried. */
+	release(token: string): void | Promise<void>;
+}
+
+/** One process's tokens, each kept for its TTL, at most `capacity` of them. */
+export class MemoryReplayGuard implements ReplayGuard {
+	readonly #capacity: number;
+	readonly #tokens = new Map<string, number>();
+
+	constructor(capacity = 100_000) {
+		this.#capacity = capacity;
+	}
+
+	claim(token: string, ttlSeconds: number): boolean {
+		// NaN would store a time no comparison is ever true of: the token
+		// would be claimable again at once.
+		if (!(Number.isFinite(ttlSeconds) && ttlSeconds > 0)) {
+			throw new GoldstoneError(
+				"E_GOLDSTONE_INVALID_OPTIONS",
+				`MemoryReplayGuard: the TTL must be a positive number of seconds, got ${String(ttlSeconds)}`,
+			);
+		}
+		const until = this.#tokens.get(token);
+		if (until !== undefined && until > Date.now()) return false;
+		this.#store(token, ttlSeconds);
+		return true;
+	}
+
+	release(token: string): void {
+		this.#tokens.delete(token);
+	}
+
+	#store(token: string, ttlSeconds: number): void {
+		if (this.#tokens.size >= this.#capacity) {
+			const now = Date.now();
+			for (const [key, until] of this.#tokens) {
+				if (until <= now) this.#tokens.delete(key);
+			}
+			// Still full: drop the oldest. Map keeps insertion order.
+			while (this.#tokens.size >= this.#capacity) {
+				const oldest = this.#tokens.keys().next();
+				if (oldest.done) break;
+				this.#tokens.delete(oldest.value);
+			}
+		}
+		this.#tokens.set(token, Date.now() + ttlSeconds * 1000);
+	}
+}
+
+/** A body field as a single string, or `undefined`. */
+export function field(body: unknown, name: string): string | undefined {
+	if (typeof body !== "object" || body === null) return undefined;
+	const value: unknown = Reflect.get(body, name);
+	if (typeof value === "string") return value;
+	// A field sent twice arrives as a list: ambiguous, refused.
+	return undefined;
+}

package/src/inbound/mailgun.ts

@@ -0,0 +1,201 @@
+/**
+ * Mailgun inbound: a route that forwards to the application receives every
+ * mail as a form POST — the raw message in `body-mime`.
+ *
+ *   router.post('/inbound/mailgun/mime', createMailgunInboundHandler({
+ *     signingKey: env.get('MAILGUN_SIGNING_KEY'),
+ *     async onMessage(message, { recipient }) { … },
+ *   }))
+ *
+ * Configure the Mailgun route to forward to a URL ending in `mime`: that is
+ * what makes Mailgun send `body-mime`, the message as received.
+ *
+ * The fields are read from `ctx.request.body()`, which holds them only once
+ * Ream's body parser has read the form Mailgun posts (multipart/form-data or
+ * urlencoded): the route must run behind `BodyParserMiddleware`, with form
+ * and multipart limits above the largest message accepted. Without it every
+ * delivery is answered 401, its fields missing.
+ *
+ * Mailgun signs `timestamp` + `token` with the webhook signing key — and
+ * nothing else: the signature does not cover the message. So a signature is
+ * only worth what its freshness and uniqueness are worth, and both are
+ * enforced: a timestamp older than `maxAgeSeconds` is refused, and a token is
+ * handled once — claimed before handling, so two requests racing with it
+ * cannot both get through. A delivery whose handling failed gives its token
+ * back, so Mailgun's retry is handled; one already handled is acknowledged
+ * and not handled again.
+ */
+
+import { Buffer } from "node:buffer";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { AuthenticateOptions } from "../authenticity.js";
+import { GoldstoneError } from "../errors.js";
+import {
+	type Limits,
+	type ParseOptions,
+	type ReceivedMessage,
+	readMessage,
+} from "../ReceivedMessage.js";
+import {
+	field,
+	type InboundHttpContext,
+	MemoryReplayGuard,
+	type ReplayGuard,
+} from "./context.js";
+
+export interface InboundMeta {
+	/** The SMTP envelope recipient Mailgun received it for. */
+	recipient?: string;
+	/** The SMTP envelope sender (return path). */
+	sender?: string;
+}
+
+export interface MailgunInboundOptions {
+	/** The webhook signing key (Mailgun → Settings → Webhooks). */
+	signingKey: string;
+	onMessage: (message: ReceivedMessage, meta: InboundMeta) => unknown;
+	/**
+	 * A signed request older than this is refused. An integer from 1 to
+	 * 86 400; default 120 (Mailgun's own guidance).
+	 */
+	maxAgeSeconds?: number;
+	/** Default: tokens kept in this process's memory. */
+	replayGuard?: ReplayGuard;
+	limits?: Limits;
+	/** DKIM / DMARC on each message (`message.authenticity`). Default `true`. */
+	authenticate?: boolean | Omit<AuthenticateOptions, "ip" | "helo">;
+	/** Remote content in `message.html`; see {@link ParseOptions}. Default `"block"`. */
+	remoteContent?: ParseOptions["remoteContent"];
+}
+
+type Handler = (
+	ctx: InboundHttpContext,
+	next?: () => Promise<void>,
+) => Promise<void>;
+
+function expectedSignature(
+	signingKey: string,
+	timestamp: string,
+	token: string,
+): Buffer {
+	return createHmac("sha256", signingKey)
+		.update(timestamp + token)
+		.digest();
+}
+
+/** Constant time; a malformed hex string is simply not equal. */
+function sameSignature(expected: Buffer, given: string): boolean {
+	if (!/^[0-9a-f]{64}$/i.test(given)) return false;
+	return timingSafeEqual(expected, Buffer.from(given, "hex"));
+}
+
+/** A day: a signature older than that is not a delivery, it is a replay. */
+const MAX_AGE_LIMIT = 86_400;
+
+export function createMailgunInboundHandler(
+	options: MailgunInboundOptions,
+): Handler {
+	if (!options.signingKey) {
+		throw new GoldstoneError(
+			"E_GOLDSTONE_INVALID_CONFIG",
+			"createMailgunInboundHandler: signingKey is required to verify Mailgun's signature",
+		);
+	}
+	const { signingKey, onMessage } = options;
+	const maxAge = options.maxAgeSeconds ?? 120;
+	// The freshness window is a security switch: NaN or Infinity would turn
+	// the timestamp check and the replay guard off without a word.
+	if (!(Number.isInteger(maxAge) && maxAge >= 1 && maxAge <= MAX_AGE_LIMIT)) {
+		throw new GoldstoneError(
+			"E_GOLDSTONE_INVALID_CONFIG",
+			`createMailgunInboundHandler: maxAgeSeconds must be an integer from 1 to ${MAX_AGE_LIMIT}, got ${String(maxAge)}`,
+		);
+	}
+	const guard = options.replayGuard ?? new MemoryReplayGuard();
+
+	return async (ctx) => {
+		const body = ctx.request.body();
+		const timestamp = field(body, "timestamp");
+		const token = field(body, "token");
+		const signature = field(body, "signature");
+		// One answer for every way a signature can be wrong, so the response
+		// does not say which check refused it.
+		const refuse = () =>
+			ctx.response.status(401).json({ error: "invalid_signature" });
+		if (!timestamp || !token || !signature) return refuse();
+
+		const seconds = Number(timestamp);
+		if (
+			!Number.isFinite(seconds) ||
+			Math.abs(Date.now() / 1000 - seconds) > maxAge
+		) {
+			return refuse();
+		}
+		if (
+			!sameSignature(expectedSignature(signingKey, timestamp, token), signature)
+		) {
+			return refuse();
+		}
+
+		const mime = field(body, "body-mime");
+		if (mime === undefined) {
+			ctx.response.status(422).json({ error: "missing_body_mime" });
+			return;
+		}
+
+		// Twice the window: a token older than that is refused on its
+		// timestamp anyway. Taken before handling, so a request racing with
+		// the same token is acknowledged instead of handled twice.
+		if (!(await guard.claim(token, maxAge * 2))) {
+			ctx.response.status(204).json({});
+			return;
+		}
+		try {
+			await handle(body, mime, ctx);
+		} catch (error) {
+			// Not handled: give the token back so Mailgun's retry gets through.
+			await guard.release(token);
+			throw error;
+		}
+	};
+
+	async function handle(
+		body: unknown,
+		mime: string,
+		ctx: InboundHttpContext,
+	): Promise<void> {
+		let message: ReceivedMessage;
+		try {
+			const authenticate =
+				options.authenticate === false
+					? false
+					: {
+							...(options.authenticate === true ||
+							options.authenticate === undefined
+								? {}
+								: options.authenticate),
+							mailFrom: field(body, "sender"),
+						};
+			message = await readMessage(Buffer.from(mime, "utf8"), {
+				limits: options.limits,
+				authenticate,
+				remoteContent: options.remoteContent,
+			});
+		} catch (error) {
+			if (error instanceof GoldstoneError) {
+				// 406 tells Mailgun not to retry: the same bytes would be refused
+				// again. The token stays taken.
+				ctx.response.status(406).json({ error: error.code });
+				return;
+			}
+			throw error;
+		}
+
+		// A handler that throws answers 500: Mailgun retries.
+		await onMessage(message, {
+			recipient: field(body, "recipient"),
+			sender: field(body, "sender"),
+		});
+		ctx.response.status(204).json({});
+	}
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+import "./augmentations.js";
+
+export {
+	type AuthenticateOptions,
+	type Authenticity,
+	type AuthResult,
+	authenticate,
+	type DkimVerdict,
+	type DmarcPolicy,
+} from "./authenticity.js";
+export {
+	defineConfig,
+	type InboxConfig,
+	type MailboxConfig,
+	type PasswordAuth,
+	type TokenAuth,
+} from "./config.js";
+export {
+	fromEngine,
+	GoldstoneError,
+	GoldstoneNativeRequiredError,
+} from "./errors.js";
+export { InboxManager } from "./InboxManager.js";
+export {
+	type InboundHttpContext,
+	type InboundResponse,
+	MemoryReplayGuard,
+	type ReplayGuard,
+} from "./inbound/context.js";
+export {
+	createMailgunInboundHandler,
+	type InboundMeta,
+	type MailgunInboundOptions,
+} from "./inbound/mailgun.js";
+export {
+	Mailbox,
+	type MailboxOptions,
+	reconnectDelay,
+	type SearchCriteria,
+	type WatchOptions,
+} from "./Mailbox.js";
+export { isNativeAvailable } from "./native.js";
+export {
+	type Attachment,
+	type Header,
+	type Limits,
+	type Mailbox as Address,
+	type ParseOptions,
+	parseMessage,
+	type ReadOptions,
+	ReceivedMessage,
+	readMessage,
+} from "./ReceivedMessage.js";

package/src/native/generated.ts

@@ -0,0 +1,141 @@
+// GENERATED FROM THE RUST — do not edit.
+//
+// Produced by scripts/generate-napi-types.mjs from napi-derive's type-def
+// output. Editing this file by hand puts it back where it started: a
+// description that can disagree with the code it describes.
+
+/** Bounds on one message; an absent field keeps the engine's default. */
+
+export interface JsLimits {
+	maxBytes?: number;
+	maxParts?: number;
+	maxDepth?: number;
+	maxHeaders?: number;
+	maxHeaderBytes?: number;
+	maxAttachments?: number;
+	maxAttachmentBytes?: number;
+	maxHtmlBytes?: number;
+}
+
+/** What the sanitized HTML may load by itself. */
+
+export interface JsHtmlOptions {
+	/**
+	 * Keep remote images and other URLs a browser loads unasked. Default
+	 * false.
+	 */
+	remoteContent?: boolean;
+}
+
+export interface JsMailbox {
+	name?: string;
+	address?: string;
+}
+
+export interface JsHeader {
+	name: string;
+	value: string;
+}
+
+export interface JsAttachment {
+	fileName: string;
+	originalName?: string;
+	contentType: string;
+	content: Buffer;
+	contentId?: string;
+	inline: boolean;
+}
+
+export interface JsMessage {
+	messageId?: string;
+	subject?: string;
+	date?: string;
+	from: Array<JsMailbox>;
+	to: Array<JsMailbox>;
+	cc: Array<JsMailbox>;
+	bcc: Array<JsMailbox>;
+	replyTo: Array<JsMailbox>;
+	inReplyTo: Array<string>;
+	references: Array<string>;
+	headers: Array<JsHeader>;
+	text?: string;
+	html?: string;
+	/** `E_GOLDSTONE_HTML_*: …` when the HTML body was not sanitized. */
+	htmlError?: string;
+	unsanitizedHtml?: string;
+	attachments: Array<JsAttachment>;
+}
+
+/** The envelope SPF checks, and the bounds on the whole check. */
+
+export interface JsAuthOptions {
+	ip?: string;
+	helo?: string;
+	mailFrom?: string;
+	maxDkimSignatures?: number;
+	timeoutMs?: number;
+	maxBytes?: number;
+}
+
+export interface JsDkimVerdict {
+	result: string;
+	domain?: string;
+	selector?: string;
+	reason?: string;
+}
+
+export interface JsVerdict {
+	dkim: Array<JsDkimVerdict>;
+	spf: string;
+	dmarc: string;
+	dmarcPolicy: string;
+	dmarcDomain?: string;
+	fromDomain?: string;
+	arc: string;
+	summary: string;
+}
+
+export interface JsReadMessage {
+	message: JsMessage;
+	authenticity: JsVerdict;
+}
+
+/**
+ * Parse one received message, off the JavaScript thread: parsing and
+ * sanitizing are CPU work on bytes a stranger sent. Rejects with
+ * `E_GOLDSTONE_*: …` on a message that breaks a limit or is not a message.
+ *
+ * `raw`, here and in the two calls below, is read on a runtime thread while
+ * JavaScript runs on: it must be memory nothing writes to meanwhile, which
+ * the TypeScript side ensures by handing a copy (`snapshot` in native.ts).
+ * A copy made here would be made on the runtime thread, too late.
+ */
+
+export declare function parseMessage(
+	raw: Buffer,
+	limits?: JsLimits | undefined | null,
+	html?: JsHtmlOptions | undefined | null,
+): Promise<JsMessage>;
+
+/**
+ * DKIM, SPF (when the envelope is given), DMARC and ARC for one received
+ * message. Resolves with `temperror` verdicts when DNS cannot answer in
+ * time — never with a pass.
+ */
+
+export declare function authenticateMessage(
+	raw: Buffer,
+	options?: JsAuthOptions | undefined | null,
+): Promise<JsVerdict>;
+
+/**
+ * Parse one received message and check who sent it, from the same parse:
+ * the From the verdict speaks for is the From the message shows.
+ */
+
+export declare function readMessage(
+	raw: Buffer,
+	limits?: JsLimits | undefined | null,
+	options?: JsAuthOptions | undefined | null,
+	html?: JsHtmlOptions | undefined | null,
+): Promise<JsReadMessage>;

package/src/native.ts

@@ -0,0 +1,62 @@
+/**
+ * Loader for the Rust mail engine.
+ *
+ * The engine is not optional: received mail is hostile input, and its parser
+ * is the one place this package will not fall back to JavaScript. A missing
+ * binary is a hard failure with an actionable message.
+ */
+
+import { GoldstoneNativeRequiredError } from "./errors.js";
+import {
+	hasFunctions,
+	loadNativeBinary,
+	unavailableReason as vendorUnavailableReason,
+} from "./vendor/nativeBinary.js";
+
+/** What this package calls, as the Rust declares it (`pnpm build:napi-types`). */
+const NATIVE_CALLS = [
+	"parseMessage",
+	"readMessage",
+	"authenticateMessage",
+] as const;
+
+type NativeGoldstone = Pick<
+	typeof import("./native/generated.js"),
+	(typeof NATIVE_CALLS)[number]
+>;
+
+/** The same three calls, checked at load: a stale binary loads just as well. */
+function isNativeGoldstone(value: unknown): value is NativeGoldstone {
+	return hasFunctions(value, NATIVE_CALLS);
+}
+
+const attempt = loadNativeBinary(isNativeGoldstone, NATIVE_CALLS);
+const native = attempt.loaded ? attempt.binary : undefined;
+const loadError = attempt.loaded ? undefined : attempt.cause;
+
+export function isNativeAvailable(): boolean {
+	return native !== undefined;
+}
+
+/**
+ * The bytes handed to the engine: a copy, taken here on the JavaScript
+ * thread. The engine reads them later, off this thread, more than once (the
+ * walk that bounds the structure, then the parse); on a view of the caller's
+ * memory, a buffer reused or written meanwhile would make it bound one
+ * message and parse another.
+ */
+export function snapshot(raw: Uint8Array): Buffer {
+	return Buffer.from(raw);
+}
+
+/** The engine, or a refusal explaining how to get one. */
+export function engine(): NativeGoldstone {
+	if (native === undefined) {
+		throw new GoldstoneNativeRequiredError(
+			loadError === undefined
+				? vendorUnavailableReason()
+				: `failed to load (${loadError instanceof Error ? loadError.message : String(loadError)})`,
+		);
+	}
+	return native;
+}

package/src/services/main.ts

@@ -0,0 +1,51 @@
+/**
+ * The {@link InboxManager}, reachable without threading it through every
+ * call site — mirroring `@c9up/quasar/services/main`.
+ *
+ *   import inbox from "@c9up/goldstone/services/main"
+ *
+ *   const unread = await inbox.mailbox().search({ seen: false })
+ *
+ * Importing this module loads nothing: the instance is resolved on the first
+ * member access, so a unit test that pulls it in transitively needs no booted
+ * provider.
+ */
+
+import type { InboxManager } from "../InboxManager.js";
+
+let instance: InboxManager | undefined;
+
+/** Seat the instance — called by GoldstoneProvider, or by an app wiring its own. */
+export function setInbox(inbox: InboxManager): void {
+	instance = inbox;
+}
+
+/** The seated instance, if there is one. */
+export function getInbox(): InboxManager | undefined {
+	return instance;
+}
+
+/** Drop the instance IF it is still the one passed in (ownership guard). */
+export function clearInbox(inbox: InboxManager): void {
+	if (instance === inbox) instance = undefined;
+}
+
+const inbox: InboxManager = new Proxy(Object.create(null), {
+	get(_target, property) {
+		// A module loader reads `then` and various symbols off what it imports
+		// before anyone uses it. They are not members, so answer undefined and
+		// let a genuine access be the one that reports.
+		if (typeof property === "symbol" || property === "then") {
+			return undefined;
+		}
+		if (!instance) {
+			throw new Error(
+				"[inbox] accessed before initialization — register GoldstoneProvider, or call setInbox() yourself.",
+			);
+		}
+		const value = Reflect.get(instance, property, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default inbox;