@molecule/api-emails-inbound-ses 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-ses` 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-ses 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,2GAA2G;QACzG,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AWS SES inbound-email provider for molecule.dev.
+ *
+ * Implements `@molecule/api-emails-inbound`'s `InboundEmailProvider`
+ * interface against AWS SES Inbound's SNS-delivery format. Validates SNS
+ * notification signatures by fetching the publisher cert from a
+ * `*.amazonaws.com`-allowlisted URL, parses the SES `mail` + `content`
+ * fields, and decodes the embedded RFC 822 message via `mailparser`.
+ *
+ * Outbound replies compose onto the bonded `@molecule/api-emails`
+ * transport (typically `@molecule/api-emails-ses`) — this package does not
+ * reimplement SMTP / SES SendEmail.
+ *
+ * @remarks
+ * The (uncached) signing-certificate fetch is bounded to a 5 second
+ * timeout — a hanging/slow `SigningCertURL` endpoint fails fast into a
+ * `false` verification result instead of stalling the webhook handler for
+ * `fetch`'s much longer default. Once a cert is fetched it is cached
+ * in-process, so this only affects the first verification against a given
+ * `SigningCertURL`.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider } from '@molecule/api-emails-inbound'
+ * import { provider as sesInbound } from '@molecule/api-emails-inbound-ses'
+ *
+ * setProvider(sesInbound)
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+export * from './utilities.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,37 @@
+/**
+ * AWS SES inbound-email provider for molecule.dev.
+ *
+ * Implements `@molecule/api-emails-inbound`'s `InboundEmailProvider`
+ * interface against AWS SES Inbound's SNS-delivery format. Validates SNS
+ * notification signatures by fetching the publisher cert from a
+ * `*.amazonaws.com`-allowlisted URL, parses the SES `mail` + `content`
+ * fields, and decodes the embedded RFC 822 message via `mailparser`.
+ *
+ * Outbound replies compose onto the bonded `@molecule/api-emails`
+ * transport (typically `@molecule/api-emails-ses`) — this package does not
+ * reimplement SMTP / SES SendEmail.
+ *
+ * @remarks
+ * The (uncached) signing-certificate fetch is bounded to a 5 second
+ * timeout — a hanging/slow `SigningCertURL` endpoint fails fast into a
+ * `false` verification result instead of stalling the webhook handler for
+ * `fetch`'s much longer default. Once a cert is fetched it is cached
+ * in-process, so this only affects the first verification against a given
+ * `SigningCertURL`.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider } from '@molecule/api-emails-inbound'
+ * import { provider as sesInbound } from '@molecule/api-emails-inbound-ses'
+ *
+ * setProvider(sesInbound)
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+export * from './utilities.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,92 @@
+/**
+ * AWS SES inbound-email provider implementation.
+ *
+ * SES Inbound parses received mail upstream and either delivers the message
+ * to S3 or publishes a notification (with the parsed `mail` metadata and
+ * optional base64-encoded raw RFC 822 `content`) to an SNS topic. This
+ * bond handles the SNS-notification path: an HTTPS endpoint subscribed to
+ * the topic receives JSON, validates the SNS signature, and parses the
+ * embedded `content` (RFC 822) into a normalized `InboundEmail`.
+ *
+ * Outbound replies compose onto the bonded `@molecule/api-emails`
+ * transport (typically `@molecule/api-emails-ses`); we never reimplement
+ * SMTP / SES SendEmail here.
+ *
+ * @see https://docs.aws.amazon.com/ses/latest/dg/receiving-email-notifications.html
+ * @see https://docs.aws.amazon.com/sns/latest/dg/sns-verify-signature-of-message.html
+ *
+ * @module
+ */
+import { Buffer } from 'node:buffer';
+import './secrets.js';
+import type { InboundEmail, InboundEmailProvider, InboundEmailReply, InboundEmailReplyResult } from '@molecule/api-emails-inbound';
+/**
+ * Resets the cached signing certificates. Exposed for tests.
+ */
+export declare const _resetSigningCertCache: () => void;
+/**
+ * Verifies the signature of an SNS notification payload. Implements the
+ * AWS SNS signature-verification flow:
+ *
+ * 1. Parse the JSON body.
+ * 2. Reject if `SigningCertURL` is not from an allowlisted host.
+ * 3. Fetch the X.509 certificate from `SigningCertURL`.
+ * 4. Build the canonical string per AWS docs (field order varies by
+ *    `Type`).
+ * 5. Verify the base64-decoded `Signature` against the canonical string
+ *    using SHA1 (`SignatureVersion === '1'`) or SHA256
+ *    (`SignatureVersion === '2'`).
+ * 6. When `AWS_SES_INBOUND_TOPIC_ARN` is set, also verify the payload's
+ *    `TopicArn` matches.
+ *
+ * Errors NEVER leak signing material; failures simply return `false`.
+ *
+ * @param _headers - HTTP headers (unused — SNS signs the body).
+ * @param body - Raw HTTP request body (JSON).
+ * @returns `true` when the signature is valid, `false` otherwise.
+ */
+export declare const verifySignature: (_headers: Record<string, string | string[] | undefined>, body: Buffer | string) => Promise<boolean>;
+/**
+ * Parses an SNS notification carrying an SES inbound-email payload into a
+ * normalized {@link InboundEmail}.
+ *
+ * When the SES `Message.content` field is present, it is base64-decoded
+ * and parsed as RFC 822 via `mailparser`. When `content` is absent
+ * (header-only notifications), we synthesize an `InboundEmail` from the
+ * SES `mail` metadata so the caller can still log/dedupe the message.
+ *
+ * SubscriptionConfirmation messages are returned as a synthetic
+ * `InboundEmail` whose `subject` is `'__sns:SubscriptionConfirmation'` and
+ * whose `headers['x-sns-subscribe-url']` carries the confirmation URL —
+ * applications inspect this so they can subscribe out-of-band.
+ *
+ * @param _headers - HTTP headers (unused).
+ * @param body - Raw HTTP body (SNS JSON).
+ * @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. The reply's `In-Reply-To` and `References` headers are
+ * populated from the original message when present.
+ *
+ * @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-ses`.
+ *
+ * @returns Always `true`.
+ */
+export declare const supportsReply: () => boolean;
+/**
+ * The AWS SES 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;;;;;;;;;;;;;;;;;;GAkBG;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;AA+BrC;;GAEG;AACH,eAAO,MAAM,sBAAsB,QAAO,IAEzC,CAAA;AAqDD;;;;;;;;;;;;;;;;;;;;GAoBG;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,CAqDjB,CAAA;AAuCD;;;;;;;;;;;;;;;;;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,CA6EtB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAClB,OAAO,YAAY,EACnB,OAAO,iBAAiB,KACvB,OAAO,CAAC,uBAAuB,CA+CjC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,QAAO,OAAe,CAAA;AAEhD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAE,oBAKtB,CAAA"}