@molecule/api-emails-inbound-mailgun 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-emails-inbound-mailgun` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-emails-inbound-mailgun is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,+GAA+G;QAC7G,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Mailgun Routes inbound-email provider for molecule.dev.
+ *
+ * Implements `@molecule/api-emails-inbound`'s `InboundEmailProvider`
+ * interface against Mailgun's parsed-email POST format. Verifies the
+ * `timestamp`/`token`/`signature` triple via HMAC-SHA256 against
+ * `MAILGUN_API_KEY`, rejecting payloads older than the configured replay
+ * window.
+ *
+ * Outbound replies compose onto the bonded `@molecule/api-emails`
+ * transport (typically `@molecule/api-emails-mailgun`) — this package does
+ * not reimplement the SMTP path.
+ *
+ * @remarks
+ * `verifySignature` THROWS the tagged `config.notConfigured` error (→ 503
+ * via the API error middleware) when `MAILGUN_API_KEY` is unset, instead of
+ * returning `false` like every other verification failure. Wire your
+ * webhook handler to let that throw propagate to the error middleware —
+ * catching it and mapping to the same 401 as a forged/stale webhook
+ * re-introduces the "every failure looks the same" ambiguity this was
+ * fixed to remove.
+ *
+ * When an inbound message has no `Message-Id`, `id` is a deterministic
+ * hash of the sender/original-Date-header/subject (NOT the per-request
+ * Mailgun signing token, which changes on every retry) — so retries of an
+ * id-less message still dedupe to the same id.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider } from '@molecule/api-emails-inbound'
+ * import { provider as mailgunRoutes } from '@molecule/api-emails-inbound-mailgun'
+ *
+ * setProvider(mailgunRoutes)
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * Mailgun Routes inbound-email provider for molecule.dev.
+ *
+ * Implements `@molecule/api-emails-inbound`'s `InboundEmailProvider`
+ * interface against Mailgun's parsed-email POST format. Verifies the
+ * `timestamp`/`token`/`signature` triple via HMAC-SHA256 against
+ * `MAILGUN_API_KEY`, rejecting payloads older than the configured replay
+ * window.
+ *
+ * Outbound replies compose onto the bonded `@molecule/api-emails`
+ * transport (typically `@molecule/api-emails-mailgun`) — this package does
+ * not reimplement the SMTP path.
+ *
+ * @remarks
+ * `verifySignature` THROWS the tagged `config.notConfigured` error (→ 503
+ * via the API error middleware) when `MAILGUN_API_KEY` is unset, instead of
+ * returning `false` like every other verification failure. Wire your
+ * webhook handler to let that throw propagate to the error middleware —
+ * catching it and mapping to the same 401 as a forged/stale webhook
+ * re-introduces the "every failure looks the same" ambiguity this was
+ * fixed to remove.
+ *
+ * When an inbound message has no `Message-Id`, `id` is a deterministic
+ * hash of the sender/original-Date-header/subject (NOT the per-request
+ * Mailgun signing token, which changes on every retry) — so retries of an
+ * id-less message still dedupe to the same id.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider } from '@molecule/api-emails-inbound'
+ * import { provider as mailgunRoutes } from '@molecule/api-emails-inbound-mailgun'
+ *
+ * setProvider(mailgunRoutes)
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Mailgun Routes inbound-email provider implementation.
+ *
+ * Mailgun parses inbound mail upstream and POSTs the result to a configured
+ * Route as `application/x-www-form-urlencoded`. Each request also carries
+ * three signing fields — `timestamp`, `token`, `signature` — that this
+ * module verifies via HMAC-SHA256 against the account's API key.
+ *
+ * Reply dispatch is composed onto the outbound `@molecule/api-emails` bond
+ * (the standard `EmailTransport`); we never reimplement the SMTP path here.
+ *
+ * @see https://documentation.mailgun.com/en/latest/user_manual.html#routes
+ *
+ * @module
+ */
+import { Buffer } from 'node:buffer';
+import './secrets.js';
+import type { InboundEmail, InboundEmailProvider, InboundEmailReply, InboundEmailReplyResult } from '@molecule/api-emails-inbound';
+/**
+ * Verifies a Mailgun inbound webhook signature. Mailgun computes the
+ * signature as `HMAC-SHA256(key=api_key, msg=timestamp + token)`, where
+ * `+` is string concatenation (no separator). Implementations MUST be
+ * constant-time and MUST reject stale timestamps.
+ *
+ * The `body` parameter is the raw form-encoded body that carries the
+ * signing fields. Header-only signing schemes are not supported by Mailgun
+ * Routes.
+ *
+ * Distinguishes SERVER MISCONFIGURATION from a genuinely invalid webhook:
+ * an unset `MAILGUN_API_KEY` THROWS the tagged `config.notConfigured` error
+ * (mapped by the API error middleware to a clean 503) instead of returning
+ * `false`. Stale timestamps, missing signing fields, and a tampered
+ * signature all still resolve to `false` (401) — those ARE the "this
+ * request is not from Mailgun" class. Collapsing every failure mode into
+ * the same `false` made a misconfigured server indistinguishable from
+ * active forgery, with no trace either way (see
+ * integration-audit-findings.md → [email] ambiguous-failure).
+ *
+ * @param _headers - HTTP headers (unused — Mailgun signs via form fields).
+ * @param body - Raw HTTP request body (form-encoded).
+ * @returns `true` when the signature verifies and the timestamp is fresh;
+ *   `false` for a malformed/stale/forged webhook.
+ * @throws {Error} The tagged `config.notConfigured` error when
+ *   `MAILGUN_API_KEY` is unset — a caller MUST NOT treat this as `false`
+ *   (that would 401-with-no-trace every inbound webhook instead of
+ *   surfacing the actionable 503).
+ */
+export declare const verifySignature: (_headers: Record<string, string | string[] | undefined>, body: Buffer | string) => Promise<boolean>;
+/**
+ * Parses a Mailgun Routes inbound webhook payload into a normalized
+ * {@link InboundEmail}.
+ *
+ * Mailgun POSTs `application/x-www-form-urlencoded` data with keys such as
+ * `From`, `To`, `Cc`, `subject`, `body-plain`, `body-html`, `Message-Id`,
+ * `In-Reply-To`, `References`, `attachment-count`, `attachment-N`, plus
+ * the signing triple. We only extract domain-relevant fields here;
+ * verification is done separately by {@link verifySignature}.
+ *
+ * When `Message-Id` is absent, `id` falls back to
+ * {@link deriveStableFallbackId} rather than the per-request signing
+ * `token` — see that function's docs for why.
+ *
+ * @param _headers - HTTP headers (unused — Mailgun puts everything in the body).
+ * @param body - The raw form-encoded body, a string, or an already-parsed object.
+ * @returns The normalized inbound email.
+ */
+export declare const parseWebhookPayload: (_headers: Record<string, string | string[] | undefined>, body: Buffer | string | Record<string, unknown>) => Promise<InboundEmail>;
+/**
+ * Dispatches an outbound reply through the bonded `@molecule/api-emails`
+ * transport. Mailgun's outbound API is already exposed via
+ * `@molecule/api-emails-mailgun`, so we compose rather than reimplement.
+ *
+ * The reply's `In-Reply-To` and `References` headers are populated from
+ * the original message when present, so threading works in the recipient's
+ * mail client.
+ *
+ * @param email - The original inbound email being replied to.
+ * @param reply - The reply payload.
+ * @returns The reply dispatch result.
+ */
+export declare const replyTo: (email: InboundEmail, reply: InboundEmailReply) => Promise<InboundEmailReplyResult>;
+/**
+ * Indicates that this provider supports outbound reply dispatch via
+ * {@link replyTo}. The reply path requires the outbound
+ * `@molecule/api-emails` bond to be wired with a transport — typically
+ * `@molecule/api-emails-mailgun`.
+ *
+ * @returns Always `true`.
+ */
+export declare const supportsReply: () => boolean;
+/**
+ * The Mailgun Routes inbound-email provider implementing the
+ * {@link InboundEmailProvider} interface.
+ */
+export declare const provider: InboundEmailProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAMpC,OAAO,cAAc,CAAA;AAGrB,OAAO,KAAK,EACV,YAAY,EAEZ,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACxB,MAAM,8BAA8B,CAAA;AA4DrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACvD,MAAM,MAAM,GAAG,MAAM,KACpB,OAAO,CAAC,OAAO,CA0BjB,CAAA;AA8FD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACvD,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9C,OAAO,CAAC,YAAY,CAiDtB,CAAA;AAWD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,OAAO,GAClB,OAAO,YAAY,EACnB,OAAO,iBAAiB,KACvB,OAAO,CAAC,uBAAuB,CAoDjC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,QAAO,OAAe,CAAA;AAEhD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,oBAKtB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,360 @@
+/**
+ * Mailgun Routes inbound-email provider implementation.
+ *
+ * Mailgun parses inbound mail upstream and POSTs the result to a configured
+ * Route as `application/x-www-form-urlencoded`. Each request also carries
+ * three signing fields — `timestamp`, `token`, `signature` — that this
+ * module verifies via HMAC-SHA256 against the account's API key.
+ *
+ * Reply dispatch is composed onto the outbound `@molecule/api-emails` bond
+ * (the standard `EmailTransport`); we never reimplement the SMTP path here.
+ *
+ * @see https://documentation.mailgun.com/en/latest/user_manual.html#routes
+ *
+ * @module
+ */
+import { Buffer } from 'node:buffer';
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+// Side-effect import: registers this bond's secret definitions so the
+// runtime registry is populated even when provider.js is imported directly
+// (not through the package barrel).
+import './secrets.js';
+import { sendMail } from '@molecule/api-emails';
+import { configNotConfiguredError } from '@molecule/api-secrets';
+import { DEFAULT_REPLAY_WINDOW_SECONDS, parseFormBody, parseMailgunMessageHeaders, splitAddressList, splitReferences, unwrapMessageId, } from './utilities.js';
+/**
+ * Reads the Mailgun API key from the environment, throwing a generic
+ * configuration error (without revealing any value) when it is unset.
+ *
+ * @returns The Mailgun API key string.
+ */
+const getApiKey = () => {
+    const apiKey = process.env.MAILGUN_API_KEY;
+    if (!apiKey) {
+        // Tagged config-missing error → clean 503 + 'config.notConfigured', with the
+        // registered definition's description + setup URL (see classifyTaggedError).
+        throw configNotConfiguredError('MAILGUN_API_KEY', 'inbound email');
+    }
+    return apiKey;
+};
+/**
+ * Reads the configured replay window (seconds) for inbound webhooks. Falls
+ * back to {@link DEFAULT_REPLAY_WINDOW_SECONDS} when unset or invalid.
+ *
+ * @returns The replay window in seconds.
+ */
+const getReplayWindowSeconds = () => {
+    const raw = process.env.MAILGUN_INBOUND_REPLAY_WINDOW_SECONDS;
+    if (!raw)
+        return DEFAULT_REPLAY_WINDOW_SECONDS;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_REPLAY_WINDOW_SECONDS;
+};
+/**
+ * Constant-time comparison of two equal-length hex digests.
+ *
+ * @param a - The first digest.
+ * @param b - The second digest.
+ * @returns `true` when the digests are byte-equal.
+ */
+const safeEqualHex = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+    }
+    catch (_error) {
+        // timingSafeEqual throws if the two Buffers have different byte lengths,
+        // which cannot happen here after the length guard above. Any other failure
+        // (e.g. invalid hex encoding) also means the signature is invalid.
+        return false;
+    }
+};
+/**
+ * Verifies a Mailgun inbound webhook signature. Mailgun computes the
+ * signature as `HMAC-SHA256(key=api_key, msg=timestamp + token)`, where
+ * `+` is string concatenation (no separator). Implementations MUST be
+ * constant-time and MUST reject stale timestamps.
+ *
+ * The `body` parameter is the raw form-encoded body that carries the
+ * signing fields. Header-only signing schemes are not supported by Mailgun
+ * Routes.
+ *
+ * Distinguishes SERVER MISCONFIGURATION from a genuinely invalid webhook:
+ * an unset `MAILGUN_API_KEY` THROWS the tagged `config.notConfigured` error
+ * (mapped by the API error middleware to a clean 503) instead of returning
+ * `false`. Stale timestamps, missing signing fields, and a tampered
+ * signature all still resolve to `false` (401) — those ARE the "this
+ * request is not from Mailgun" class. Collapsing every failure mode into
+ * the same `false` made a misconfigured server indistinguishable from
+ * active forgery, with no trace either way (see
+ * integration-audit-findings.md → [email] ambiguous-failure).
+ *
+ * @param _headers - HTTP headers (unused — Mailgun signs via form fields).
+ * @param body - Raw HTTP request body (form-encoded).
+ * @returns `true` when the signature verifies and the timestamp is fresh;
+ *   `false` for a malformed/stale/forged webhook.
+ * @throws {Error} The tagged `config.notConfigured` error when
+ *   `MAILGUN_API_KEY` is unset — a caller MUST NOT treat this as `false`
+ *   (that would 401-with-no-trace every inbound webhook instead of
+ *   surfacing the actionable 503).
+ */
+export const verifySignature = async (_headers, body) => {
+    // Deliberately NOT caught here: an unconfigured key is a server
+    // misconfiguration, not "signature invalid," and must propagate as the
+    // tagged config error so the caller (the API error middleware) can 503
+    // instead of silently 401ing every webhook. See @throws above.
+    const apiKey = getApiKey();
+    const fields = parseFormBody(body);
+    const timestamp = fields.timestamp;
+    const token = fields.token;
+    const signature = fields.signature;
+    if (!timestamp || !token || !signature)
+        return false;
+    // Reject stale timestamps to defend against replay (Mailgun tokens are
+    // single-use, but the time bound is belt-and-suspenders).
+    const ts = Number.parseInt(timestamp, 10);
+    if (!Number.isFinite(ts))
+        return false;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (Math.abs(nowSeconds - ts) > getReplayWindowSeconds())
+        return false;
+    const expected = createHmac('sha256', apiKey)
+        .update(timestamp + token)
+        .digest('hex');
+    return safeEqualHex(expected, signature.toLowerCase());
+};
+/**
+ * Builds the {@link InboundEmailAttachment} list from Mailgun's
+ * form-encoded `attachment-N` and `attachment-count` fields.
+ *
+ * Mailgun in form-only mode encodes each attachment as JSON in the
+ * `attachment-N` field (`{"name","content-type","size","content"}`), where
+ * `content` is the base64-encoded payload. We map this onto the normalized
+ * shape and skip any entry that fails to parse.
+ *
+ * @param fields - Parsed form fields.
+ * @returns Array of attachments (empty when none are present).
+ */
+const parseFormAttachments = (fields) => {
+    const out = [];
+    const countRaw = fields['attachment-count'];
+    const count = Number.parseInt(countRaw ?? '0', 10);
+    if (!Number.isFinite(count) || count <= 0)
+        return out;
+    for (let i = 1; i <= count; i += 1) {
+        const raw = fields[`attachment-${String(i)}`];
+        if (!raw)
+            continue;
+        let parsed;
+        try {
+            const candidate = JSON.parse(raw);
+            if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
+                parsed = candidate;
+            }
+        }
+        catch (_error) {
+            // Mailgun sent a malformed attachment JSON field — skip this entry rather
+            // than aborting the whole parse; other attachments and the email body are
+            // still valid.
+            continue;
+        }
+        if (!parsed)
+            continue;
+        const name = typeof parsed.name === 'string' ? parsed.name : `attachment-${String(i)}`;
+        const contentType = typeof parsed['content-type'] === 'string'
+            ? parsed['content-type']
+            : 'application/octet-stream';
+        const sizeRaw = parsed.size;
+        const sizeBytes = typeof sizeRaw === 'number' ? sizeRaw : undefined;
+        const contentRaw = parsed.content;
+        const contentBase64 = typeof contentRaw === 'string'
+            ? // Mailgun documents the `content` as already base64-encoded.
+                contentRaw
+            : '';
+        const contentId = typeof parsed['content-id'] === 'string' ? parsed['content-id'] : undefined;
+        const attachment = {
+            name,
+            contentType,
+            contentBase64,
+        };
+        if (sizeBytes !== undefined)
+            attachment.sizeBytes = sizeBytes;
+        if (contentId !== undefined)
+            attachment.contentId = contentId;
+        out.push(attachment);
+    }
+    return out;
+};
+/**
+ * Derives a stable fallback identifier for an inbound email that has no
+ * `Message-Id` (some senders omit it). Hashes the sender, the ORIGINAL
+ * message's `Date` header, and the subject — deliberately NOT the webhook
+ * delivery `timestamp`/`token` fields, which Mailgun regenerates on every
+ * retry of the SAME message. A retry-stable input keeps retries of an
+ * id-less message hashing to the same id, so the core contract's "used for
+ * deduplication when the same webhook is retried" still holds (see
+ * integration-audit-findings.md → [email] doc-drift).
+ *
+ * @param from - The normalized sender address.
+ * @param dateHeader - The original message's `Date` header, if present in
+ *   `message-headers` (absent for form-only, non-MIME deliveries).
+ * @param subject - The normalized subject line.
+ * @returns A `mailgun-`-prefixed, deterministic fallback id.
+ */
+const deriveStableFallbackId = (from, dateHeader, subject) => {
+    const digest = createHash('sha256')
+        .update(`${from}${dateHeader ?? ''}${subject}`)
+        .digest('hex');
+    return `mailgun-${digest.slice(0, 32)}`;
+};
+/**
+ * Parses a Mailgun Routes inbound webhook payload into a normalized
+ * {@link InboundEmail}.
+ *
+ * Mailgun POSTs `application/x-www-form-urlencoded` data with keys such as
+ * `From`, `To`, `Cc`, `subject`, `body-plain`, `body-html`, `Message-Id`,
+ * `In-Reply-To`, `References`, `attachment-count`, `attachment-N`, plus
+ * the signing triple. We only extract domain-relevant fields here;
+ * verification is done separately by {@link verifySignature}.
+ *
+ * When `Message-Id` is absent, `id` falls back to
+ * {@link deriveStableFallbackId} rather than the per-request signing
+ * `token` — see that function's docs for why.
+ *
+ * @param _headers - HTTP headers (unused — Mailgun puts everything in the body).
+ * @param body - The raw form-encoded body, a string, or an already-parsed object.
+ * @returns The normalized inbound email.
+ */
+export const parseWebhookPayload = async (_headers, body) => {
+    const fields = parseFormBody(body);
+    const messageHeaders = parseMailgunMessageHeaders(fields['message-headers']);
+    const messageId = unwrapMessageId(fields['Message-Id'] ?? fields['message-id']);
+    const inReplyTo = unwrapMessageId(fields['In-Reply-To'] ?? fields['in-reply-to']);
+    const references = splitReferences(fields.References ?? fields.references).map((ref) => {
+        const unwrapped = unwrapMessageId(ref);
+        return unwrapped ?? ref;
+    });
+    const timestampRaw = fields.timestamp;
+    const timestampSeconds = Number.parseInt(timestampRaw ?? '', 10);
+    const receivedAt = Number.isFinite(timestampSeconds)
+        ? new Date(timestampSeconds * 1000)
+        : new Date();
+    const from = fields.From ?? fields.from ?? fields.sender ?? '';
+    const subject = fields.Subject ?? fields.subject ?? '';
+    const dateHeaderRaw = messageHeaders.date;
+    const dateHeader = Array.isArray(dateHeaderRaw) ? dateHeaderRaw[0] : dateHeaderRaw;
+    const email = {
+        id: messageId ?? deriveStableFallbackId(from, dateHeader, subject),
+        from,
+        to: splitAddressList(fields.To ?? fields.to ?? fields.recipient),
+        subject,
+        headers: messageHeaders,
+        receivedAt,
+    };
+    const cc = splitAddressList(fields.Cc ?? fields.cc);
+    if (cc.length > 0)
+        email.cc = cc;
+    const textBody = fields['body-plain'];
+    if (textBody !== undefined)
+        email.textBody = textBody;
+    const htmlBody = fields['body-html'];
+    if (htmlBody !== undefined)
+        email.htmlBody = htmlBody;
+    const attachments = parseFormAttachments(fields);
+    if (attachments.length > 0)
+        email.attachments = attachments;
+    if (messageId)
+        email.messageId = messageId;
+    if (inReplyTo)
+        email.inReplyTo = inReplyTo;
+    if (references.length > 0)
+        email.references = references;
+    return email;
+};
+/**
+ * Decodes a base64 string into a Node `Buffer`. Defined inline so the
+ * provider does not pull in extra dependencies for a one-line operation.
+ *
+ * @param value - The base64 string.
+ * @returns The decoded buffer.
+ */
+const base64ToBuffer = (value) => Buffer.from(value, 'base64');
+/**
+ * Dispatches an outbound reply through the bonded `@molecule/api-emails`
+ * transport. Mailgun's outbound API is already exposed via
+ * `@molecule/api-emails-mailgun`, so we compose rather than reimplement.
+ *
+ * The reply's `In-Reply-To` and `References` headers are populated from
+ * the original message when present, so threading works in the recipient's
+ * mail client.
+ *
+ * @param email - The original inbound email being replied to.
+ * @param reply - The reply payload.
+ * @returns The reply dispatch result.
+ */
+export const replyTo = async (email, reply) => {
+    const fromAddress = reply.from ?? (email.to.length > 0 ? email.to[0] : undefined);
+    if (!fromAddress) {
+        throw new Error('Cannot dispatch inbound reply: no `from` address was supplied and the original email has no recipient to fall back to.');
+    }
+    const subject = reply.subject ?? `Re: ${email.subject}`;
+    // Build threading headers from the original message so the recipient's
+    // mail client groups the reply into the existing thread. We pass them
+    // alongside the normalized EmailMessage shape via a structural cast —
+    // every concrete EmailTransport (nodemailer, SES, etc.) honours a
+    // `headers` field, and the cast keeps the core EmailMessage type lean.
+    const threadingHeaders = {};
+    if (email.messageId) {
+        threadingHeaders['In-Reply-To'] = `<${email.messageId}>`;
+        const refs = email.references ? [...email.references] : [];
+        refs.push(email.messageId);
+        threadingHeaders.References = refs.map((id) => `<${id}>`).join(' ');
+    }
+    const headers = {
+        ...threadingHeaders,
+        ...(reply.headers ?? {}),
+    };
+    const message = {
+        from: fromAddress,
+        to: email.from,
+        subject,
+        ...(reply.textBody !== undefined ? { text: reply.textBody } : {}),
+        ...(reply.htmlBody !== undefined ? { html: reply.htmlBody } : {}),
+        ...(reply.attachments && reply.attachments.length > 0
+            ? {
+                attachments: reply.attachments.map((a) => ({
+                    filename: a.name,
+                    content: base64ToBuffer(a.contentBase64),
+                    contentType: a.contentType,
+                    ...(a.contentId !== undefined ? { cid: a.contentId } : {}),
+                })),
+            }
+            : {}),
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
+    };
+    const result = await sendMail(message);
+    return {
+        id: result.messageId ?? '',
+    };
+};
+/**
+ * Indicates that this provider supports outbound reply dispatch via
+ * {@link replyTo}. The reply path requires the outbound
+ * `@molecule/api-emails` bond to be wired with a transport — typically
+ * `@molecule/api-emails-mailgun`.
+ *
+ * @returns Always `true`.
+ */
+export const supportsReply = () => true;
+/**
+ * The Mailgun Routes inbound-email provider implementing the
+ * {@link InboundEmailProvider} interface.
+ */
+export const provider = {
+    parseWebhookPayload,
+    verifySignature,
+    replyTo,
+    supportsReply,
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/dist/secrets.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mailgun secret definitions (inbound routes) — self-registered at import
+ * time so the runtime secrets registry (`@molecule/api-secrets`) can drive
+ * boot-time configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key (MAILGUN_API_KEY/MAILGUN_DOMAIN with the outbound
+ * bond) register byte-identical definitions and registration order never
+ * matters.
+ *
+ * @module
+ */
+import type { SecretDefinition } from '@molecule/api-secrets';
+/** Secret definitions required by the Mailgun inbound-email bond. */
+export declare const mailgunInboundSecretDefinitions: SecretDefinition[];
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,qEAAqE;AACrE,eAAO,MAAM,+BAA+B,EAAE,gBAAgB,EAuB7D,CAAA"}

package/dist/secrets.js

@@ -0,0 +1,38 @@
+/**
+ * Mailgun secret definitions (inbound routes) — self-registered at import
+ * time so the runtime secrets registry (`@molecule/api-secrets`) can drive
+ * boot-time configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key (MAILGUN_API_KEY/MAILGUN_DOMAIN with the outbound
+ * bond) register byte-identical definitions and registration order never
+ * matters.
+ *
+ * @module
+ */
+import { registerSecrets } from '@molecule/api-secrets';
+/** Secret definitions required by the Mailgun inbound-email bond. */
+export const mailgunInboundSecretDefinitions = [
+    {
+        key: 'MAILGUN_API_KEY',
+        description: 'Mailgun API key — Mailgun dashboard → Settings → API Security → create/copy a sending API key.',
+        helpUrl: 'https://app.mailgun.com/settings/api_security',
+        required: true,
+    },
+    {
+        key: 'MAILGUN_DOMAIN',
+        description: 'Mailgun sending domain — Add and verify a sending domain in Mailgun (sandbox domains work for testing to authorized recipients).',
+        helpUrl: 'https://app.mailgun.com/mg/sending/domains',
+        required: true,
+        example: 'mg.example.com',
+    },
+    {
+        key: 'MAILGUN_INBOUND_REPLAY_WINDOW_SECONDS',
+        description: 'Mailgun inbound replay window — Max age (seconds) of accepted inbound webhook signatures — replay protection; the default is fine.',
+        required: false,
+        example: '300',
+    },
+];
+registerSecrets(mailgunInboundSecretDefinitions);
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,qEAAqE;AACrE,MAAM,CAAC,MAAM,+BAA+B,GAAuB;IACjE;QACE,GAAG,EAAE,iBAAiB;QACtB,WAAW,EACT,gGAAgG;QAClG,OAAO,EAAE,+CAA+C;QACxD,QAAQ,EAAE,IAAI;KACf;IACD;QACE,GAAG,EAAE,gBAAgB;QACrB,WAAW,EACT,kIAAkI;QACpI,OAAO,EAAE,4CAA4C;QACrD,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,gBAAgB;KAC1B;IACD;QACE,GAAG,EAAE,uCAAuC;QAC5C,WAAW,EACT,oIAAoI;QACtI,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,KAAK;KACf;CACF,CAAA;AAED,eAAe,CAAC,+BAA+B,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Type definitions for the Mailgun Routes inbound-emails provider.
+ *
+ * @module
+ */
+export type { InboundEmail, InboundEmailAttachment, InboundEmailProvider, InboundEmailReply, InboundEmailReplyResult, } from '@molecule/api-emails-inbound';
+declare global {
+    namespace NodeJS {
+        /**
+         * Process Env interface — Mailgun Routes shares the same credentials as
+         * the outbound `@molecule/api-emails-mailgun` bond. The HMAC signing key
+         * used to verify inbound webhooks is the Mailgun API key.
+         */
+        interface ProcessEnv {
+            /**
+             * Mailgun API key. Used as the HMAC-SHA256 signing key when verifying
+             * inbound webhook signatures, and as the auth token when dispatching
+             * outbound replies.
+             */
+            MAILGUN_API_KEY?: string;
+            /**
+             * Mailgun sending domain. Used as the default `From:` domain when
+             * dispatching outbound replies.
+             */
+            MAILGUN_DOMAIN?: string;
+            /**
+             * Maximum age in seconds for an inbound webhook timestamp before the
+             * provider rejects it as a replay. Defaults to `300` (5 minutes) when
+             * unset.
+             */
+            MAILGUN_INBOUND_REPLAY_WINDOW_SECONDS?: string;
+        }
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,YAAY,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,8BAA8B,CAAA;AAErC,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,MAAM,CAAC;QACf;;;;WAIG;QACH,UAAiB,UAAU;YACzB;;;;eAIG;YACH,eAAe,CAAC,EAAE,MAAM,CAAA;YAExB;;;eAGG;YACH,cAAc,CAAC,EAAE,MAAM,CAAA;YAEvB;;;;eAIG;YACH,qCAAqC,CAAC,EAAE,MAAM,CAAA;SAC/C;KACF;CACF"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the Mailgun Routes inbound-emails provider.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/utilities.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Internal utilities for the Mailgun Routes inbound-emails provider.
+ *
+ * Kept out of `provider.ts` so the parsing helpers can be unit-tested in
+ * isolation without touching the bond singleton.
+ *
+ * @module
+ */
+import { Buffer } from 'node:buffer';
+/**
+ * Default replay window for inbound webhook timestamps, in seconds.
+ *
+ * Mailgun signs every inbound POST with `timestamp`, `token`, and
+ * `signature`. Tokens are single-use, but to defend against replay we also
+ * reject any payload whose `timestamp` is older than this window.
+ */
+export declare const DEFAULT_REPLAY_WINDOW_SECONDS = 300;
+/**
+ * Coerces an HTTP header value (which may be `string`, `string[]`, or
+ * `undefined`) to a single string. Multi-value headers are joined with
+ * `, ` per RFC 9110 §5.2.
+ *
+ * @param value - The header value to coerce.
+ * @returns The header value as a single string, or `undefined` when the
+ *   header was not present.
+ */
+export declare const headerToString: (value: string | string[] | undefined) => string | undefined;
+/**
+ * Returns the value of `headers[name]` (case-insensitive) coerced to a
+ * single string.
+ *
+ * @param headers - The headers object.
+ * @param name - The header name (case-insensitive).
+ * @returns The header value as a single string, or `undefined` if absent.
+ */
+export declare const getHeader: (headers: Record<string, string | string[] | undefined>, name: string) => string | undefined;
+/**
+ * Coerces the request body into a UTF-8 string. Buffers are decoded as
+ * UTF-8 (Mailgun POSTs `application/x-www-form-urlencoded` ASCII), strings
+ * are returned as-is.
+ *
+ * @param body - The raw body.
+ * @returns The body as a UTF-8 string.
+ */
+export declare const bodyToString: (body: Buffer | string) => string;
+/**
+ * Parses a `application/x-www-form-urlencoded` body into a flat
+ * `Record<string, string>`. Fields that appear more than once keep their
+ * first value (Mailgun does not duplicate fields).
+ *
+ * Accepts either a raw form-encoded string or an already-parsed object
+ * (Express's `body-parser` middleware gives us the latter when a JSON
+ * route accidentally captures the webhook). The pre-parsed-object branch
+ * coerces every value to a string for consistent downstream parsing.
+ *
+ * @param body - Raw body or pre-parsed form object.
+ * @returns Flat record of form fields.
+ */
+export declare const parseFormBody: (body: Buffer | string | Record<string, unknown>) => Record<string, string>;
+/**
+ * Splits a Mailgun recipient list (comma-separated mailbox list, possibly
+ * with display names like `'Alice <a@x>, "Bob, Jr." <b@y>'`) into trimmed
+ * RFC 5322 mailbox strings.
+ *
+ * Mailgun forwards the original `To:` and `Cc:` headers verbatim, so the
+ * implementation needs to respect quoted-string commas.
+ *
+ * @param value - The raw header value.
+ * @returns Array of trimmed mailbox strings (empty when `value` is empty).
+ */
+export declare const splitAddressList: (value: string | undefined) => string[];
+/**
+ * Splits a `References:` header (whitespace-separated `<message-id>`
+ * tokens) into individual values, including the angle brackets.
+ *
+ * @param value - The raw header value.
+ * @returns Array of message-id tokens (with angle brackets) or empty.
+ */
+export declare const splitReferences: (value: string | undefined) => string[];
+/**
+ * Recovers a normalized headers map from Mailgun's `message-headers` form
+ * field (a JSON-encoded array of `[name, value]` tuples, e.g.
+ * `[["Received","by ..."],["From","alice@example.com"]]`).
+ *
+ * Field names are lowercased; multi-value headers are returned as arrays.
+ * Falls back to an empty record when the field is absent or invalid JSON.
+ *
+ * @param raw - The raw `message-headers` form field value.
+ * @returns Normalized headers map.
+ */
+export declare const parseMailgunMessageHeaders: (raw: string | undefined) => Record<string, string | string[]>;
+/**
+ * Strips surrounding angle brackets from a `Message-ID` value.
+ *
+ * @param value - The raw value (with or without angle brackets).
+ * @returns The value without angle brackets, or `undefined` if input was empty.
+ */
+export declare const unwrapMessageId: (value: string | undefined) => string | undefined;
+//# sourceMappingURL=utilities.d.ts.map

package/dist/utilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAA;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,KAAG,MAAM,GAAG,SAG9E,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GACpB,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtD,MAAM,MAAM,KACX,MAAM,GAAG,SAQX,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,GAAG,MAAM,KAAG,MAEpD,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9C,MAAM,CAAC,MAAM,EAAE,MAAM,CAiBvB,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,EAgClE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,EAMjE,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B,GACrC,KAAK,MAAM,GAAG,SAAS,KACtB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CA6BlC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAKpE,CAAA"}

package/dist/utilities.js

@@ -0,0 +1,213 @@
+/**
+ * Internal utilities for the Mailgun Routes inbound-emails provider.
+ *
+ * Kept out of `provider.ts` so the parsing helpers can be unit-tested in
+ * isolation without touching the bond singleton.
+ *
+ * @module
+ */
+import { Buffer } from 'node:buffer';
+/**
+ * Default replay window for inbound webhook timestamps, in seconds.
+ *
+ * Mailgun signs every inbound POST with `timestamp`, `token`, and
+ * `signature`. Tokens are single-use, but to defend against replay we also
+ * reject any payload whose `timestamp` is older than this window.
+ */
+export const DEFAULT_REPLAY_WINDOW_SECONDS = 300;
+/**
+ * Coerces an HTTP header value (which may be `string`, `string[]`, or
+ * `undefined`) to a single string. Multi-value headers are joined with
+ * `, ` per RFC 9110 §5.2.
+ *
+ * @param value - The header value to coerce.
+ * @returns The header value as a single string, or `undefined` when the
+ *   header was not present.
+ */
+export const headerToString = (value) => {
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value.join(', ') : value;
+};
+/**
+ * Returns the value of `headers[name]` (case-insensitive) coerced to a
+ * single string.
+ *
+ * @param headers - The headers object.
+ * @param name - The header name (case-insensitive).
+ * @returns The header value as a single string, or `undefined` if absent.
+ */
+export const getHeader = (headers, name) => {
+    const target = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === target) {
+            return headerToString(headers[key]);
+        }
+    }
+    return undefined;
+};
+/**
+ * Coerces the request body into a UTF-8 string. Buffers are decoded as
+ * UTF-8 (Mailgun POSTs `application/x-www-form-urlencoded` ASCII), strings
+ * are returned as-is.
+ *
+ * @param body - The raw body.
+ * @returns The body as a UTF-8 string.
+ */
+export const bodyToString = (body) => {
+    return Buffer.isBuffer(body) ? body.toString('utf8') : body;
+};
+/**
+ * Parses a `application/x-www-form-urlencoded` body into a flat
+ * `Record<string, string>`. Fields that appear more than once keep their
+ * first value (Mailgun does not duplicate fields).
+ *
+ * Accepts either a raw form-encoded string or an already-parsed object
+ * (Express's `body-parser` middleware gives us the latter when a JSON
+ * route accidentally captures the webhook). The pre-parsed-object branch
+ * coerces every value to a string for consistent downstream parsing.
+ *
+ * @param body - Raw body or pre-parsed form object.
+ * @returns Flat record of form fields.
+ */
+export const parseFormBody = (body) => {
+    if (typeof body === 'string' || Buffer.isBuffer(body)) {
+        const params = new URLSearchParams(bodyToString(body));
+        const out = {};
+        for (const [key, value] of params.entries()) {
+            if (!(key in out))
+                out[key] = value;
+        }
+        return out;
+    }
+    // Already-parsed object: coerce every leaf to string.
+    const out = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (value === undefined || value === null)
+            continue;
+        out[key] = typeof value === 'string' ? value : String(value);
+    }
+    return out;
+};
+/**
+ * Splits a Mailgun recipient list (comma-separated mailbox list, possibly
+ * with display names like `'Alice <a@x>, "Bob, Jr." <b@y>'`) into trimmed
+ * RFC 5322 mailbox strings.
+ *
+ * Mailgun forwards the original `To:` and `Cc:` headers verbatim, so the
+ * implementation needs to respect quoted-string commas.
+ *
+ * @param value - The raw header value.
+ * @returns Array of trimmed mailbox strings (empty when `value` is empty).
+ */
+export const splitAddressList = (value) => {
+    if (!value)
+        return [];
+    const out = [];
+    let depth = 0;
+    let inQuotes = false;
+    let current = '';
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (ch === '"' && value[i - 1] !== '\\') {
+            inQuotes = !inQuotes;
+            current += ch;
+            continue;
+        }
+        if (!inQuotes) {
+            if (ch === '<')
+                depth += 1;
+            else if (ch === '>')
+                depth = Math.max(0, depth - 1);
+            else if (ch === ',' && depth === 0) {
+                const trimmed = current.trim();
+                if (trimmed)
+                    out.push(trimmed);
+                current = '';
+                continue;
+            }
+        }
+        current += ch;
+    }
+    const trimmed = current.trim();
+    if (trimmed)
+        out.push(trimmed);
+    return out;
+};
+/**
+ * Splits a `References:` header (whitespace-separated `<message-id>`
+ * tokens) into individual values, including the angle brackets.
+ *
+ * @param value - The raw header value.
+ * @returns Array of message-id tokens (with angle brackets) or empty.
+ */
+export const splitReferences = (value) => {
+    if (!value)
+        return [];
+    return value
+        .split(/\s+/u)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+};
+/**
+ * Recovers a normalized headers map from Mailgun's `message-headers` form
+ * field (a JSON-encoded array of `[name, value]` tuples, e.g.
+ * `[["Received","by ..."],["From","alice@example.com"]]`).
+ *
+ * Field names are lowercased; multi-value headers are returned as arrays.
+ * Falls back to an empty record when the field is absent or invalid JSON.
+ *
+ * @param raw - The raw `message-headers` form field value.
+ * @returns Normalized headers map.
+ */
+export const parseMailgunMessageHeaders = (raw) => {
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (_error) {
+        // Intentional noop: invalid JSON in message-headers is a Mailgun data
+        // anomaly; falling back to an empty record is safe because callers treat
+        // a missing headers map as degraded-but-recoverable.
+        return {};
+    }
+    if (!Array.isArray(parsed))
+        return {};
+    const out = {};
+    for (const entry of parsed) {
+        if (!Array.isArray(entry) || entry.length < 2)
+            continue;
+        const [nameRaw, valueRaw] = entry;
+        if (typeof nameRaw !== 'string' || typeof valueRaw !== 'string')
+            continue;
+        const name = nameRaw.toLowerCase();
+        const existing = out[name];
+        if (existing === undefined) {
+            out[name] = valueRaw;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(valueRaw);
+        }
+        else {
+            out[name] = [existing, valueRaw];
+        }
+    }
+    return out;
+};
+/**
+ * Strips surrounding angle brackets from a `Message-ID` value.
+ *
+ * @param value - The raw value (with or without angle brackets).
+ * @returns The value without angle brackets, or `undefined` if input was empty.
+ */
+export const unwrapMessageId = (value) => {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.replace(/^<|>$/gu, '');
+};
+//# sourceMappingURL=utilities.js.map

package/dist/utilities.js.map

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@molecule/api-emails-inbound-mailgun",
+  "version": "1.0.0",
+  "description": "Mailgun Routes inbound email provider — parses inbound email webhook payloads into normalized InboundEmail.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "emails",
+    "inbound",
+    "mailgun",
+    "routes",
+    "webhook"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@molecule/api-emails": "1.0.0",
+    "@molecule/api-emails-inbound": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/api-emails": "^1.0.0",
+    "@molecule/api-emails-inbound": "^1.0.0",
+    "@molecule/api-secrets": "^1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/emails-inbound/mailgun"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/emails-inbound/mailgun",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}