@c9up/goldstone 0.0.0-stage → 0.1.0

package/dist/inbound/context.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What an inbound handler needs from the HTTP request, structurally — a
+ * Ream `HttpContext` fits, and so does a plain object in a test.
+ */
+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 declare class MemoryReplayGuard implements ReplayGuard {
+    #private;
+    constructor(capacity?: number);
+    claim(token: string, ttlSeconds: number): boolean;
+    release(token: string): void;
+}
+/** A body field as a single string, or `undefined`. */
+export declare function field(body: unknown, name: string): string | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/inbound/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/inbound/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,eAAe;IAC/B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC;IACtC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE;QACR;;;WAGG;QACH,IAAI,IAAI,OAAO,CAAC;KAChB,CAAC;IACF,QAAQ,EAAE,eAAe,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,6EAA6E;IAC7E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,+EAA+E;AAC/E,qBAAa,iBAAkB,YAAW,WAAW;;gBAIxC,QAAQ,SAAU;IAI9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO;IAejD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAmB5B;AAED,uDAAuD;AACvD,wBAAgB,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMrE"}

package/dist/inbound/context.js

@@ -0,0 +1,56 @@
+/**
+ * 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";
+/** One process's tokens, each kept for its TTL, at most `capacity` of them. */
+export class MemoryReplayGuard {
+    #capacity;
+    #tokens = new Map();
+    constructor(capacity = 100_000) {
+        this.#capacity = capacity;
+    }
+    claim(token, ttlSeconds) {
+        // 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) {
+        this.#tokens.delete(token);
+    }
+    #store(token, ttlSeconds) {
+        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, name) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const value = Reflect.get(body, name);
+    if (typeof value === "string")
+        return value;
+    // A field sent twice arrives as a list: ambiguous, refused.
+    return undefined;
+}
+//# sourceMappingURL=context.js.map

package/dist/inbound/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/inbound/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAkC9C,+EAA+E;AAC/E,MAAM,OAAO,iBAAiB;IACpB,SAAS,CAAS;IAClB,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE7C,YAAY,QAAQ,GAAG,OAAO;QAC7B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,KAAa,EAAE,UAAkB;QACtC,kEAAkE;QAClE,oCAAoC;QACpC,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,cAAc,CACvB,6BAA6B,EAC7B,wEAAwE,MAAM,CAAC,UAAU,CAAC,EAAE,CAC5F,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE;YAAE,OAAO,KAAK,CAAC;QAC5D,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC;IACb,CAAC;IAED,OAAO,CAAC,KAAa;QACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,KAAa,EAAE,UAAkB;QACvC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACzC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACzC,IAAI,KAAK,IAAI,GAAG;oBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5C,CAAC;YACD,0DAA0D;YAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;gBAC1C,IAAI,MAAM,CAAC,IAAI;oBAAE,MAAM;gBACvB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC;QACF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC;IACzD,CAAC;CACD;AAED,uDAAuD;AACvD,MAAM,UAAU,KAAK,CAAC,IAAa,EAAE,IAAY;IAChD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAChE,MAAM,KAAK,GAAY,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,4DAA4D;IAC5D,OAAO,SAAS,CAAC;AAClB,CAAC"}

package/dist/inbound/mailgun.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 type { AuthenticateOptions } from "../authenticity.js";
+import { type Limits, type ParseOptions, type ReceivedMessage } from "../ReceivedMessage.js";
+import { type InboundHttpContext, 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>;
+export declare function createMailgunInboundHandler(options: MailgunInboundOptions): Handler;
+export {};
+//# sourceMappingURL=mailgun.d.ts.map

package/dist/inbound/mailgun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailgun.d.ts","sourceRoot":"","sources":["../../src/inbound/mailgun.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,OAAO,EACN,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,eAAe,EAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEN,KAAK,kBAAkB,EAEvB,KAAK,WAAW,EAChB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,WAAW;IAC3B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACrC,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC;IACpE;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC;IAClE,qFAAqF;IACrF,aAAa,CAAC,EAAE,YAAY,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED,KAAK,OAAO,GAAG,CACd,GAAG,EAAE,kBAAkB,EACvB,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KACtB,OAAO,CAAC,IAAI,CAAC,CAAC;AAqBnB,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,qBAAqB,GAC5B,OAAO,CAwGT"}

package/dist/inbound/mailgun.js

@@ -0,0 +1,132 @@
+/**
+ * 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 { GoldstoneError } from "../errors.js";
+import { readMessage, } from "../ReceivedMessage.js";
+import { field, MemoryReplayGuard, } from "./context.js";
+function expectedSignature(signingKey, timestamp, token) {
+    return createHmac("sha256", signingKey)
+        .update(timestamp + token)
+        .digest();
+}
+/** Constant time; a malformed hex string is simply not equal. */
+function sameSignature(expected, given) {
+    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) {
+    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, mime, ctx) {
+        let message;
+        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({});
+    }
+}
+//# sourceMappingURL=mailgun.js.map

package/dist/inbound/mailgun.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+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";
+//# 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,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,WAAW,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,SAAS,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,UAAU,EACV,cAAc,EACd,4BAA4B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EACN,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,iBAAiB,EACjB,KAAK,WAAW,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,2BAA2B,EAC3B,KAAK,WAAW,EAChB,KAAK,qBAAqB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,OAAO,EACP,KAAK,cAAc,EACnB,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACN,KAAK,UAAU,EACf,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,OAAO,IAAI,OAAO,EACvB,KAAK,YAAY,EACjB,YAAY,EACZ,KAAK,WAAW,EAChB,eAAe,EACf,WAAW,GACX,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+import "./augmentations.js";
+export { authenticate, } from "./authenticity.js";
+export { defineConfig, } from "./config.js";
+export { fromEngine, GoldstoneError, GoldstoneNativeRequiredError, } from "./errors.js";
+export { InboxManager } from "./InboxManager.js";
+export { MemoryReplayGuard, } from "./inbound/context.js";
+export { createMailgunInboundHandler, } from "./inbound/mailgun.js";
+export { Mailbox, reconnectDelay, } from "./Mailbox.js";
+export { isNativeAvailable } from "./native.js";
+export { parseMessage, ReceivedMessage, readMessage, } from "./ReceivedMessage.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,OAAO,oBAAoB,CAAC;AAE5B,OAAO,EAIN,YAAY,GAGZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,YAAY,GAKZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,UAAU,EACV,cAAc,EACd,4BAA4B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAGN,iBAAiB,GAEjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,2BAA2B,GAG3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACN,OAAO,EAEP,cAAc,GAGd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAMN,YAAY,EAEZ,eAAe,EACf,WAAW,GACX,MAAM,sBAAsB,CAAC"}

package/dist/native/generated.d.ts

@@ -0,0 +1,106 @@
+/** 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>;
+//# sourceMappingURL=generated.d.ts.map

package/dist/native/generated.d.ts.map

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

package/dist/native/generated.js

@@ -0,0 +1,7 @@
+// 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.
+export {};
+//# sourceMappingURL=generated.js.map

package/dist/native/generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.js","sourceRoot":"","sources":["../../src/native/generated.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,0EAA0E;AAC1E,qEAAqE;AACrE,4DAA4D"}

package/dist/native.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+/** What this package calls, as the Rust declares it (`pnpm build:napi-types`). */
+declare const NATIVE_CALLS: readonly ["parseMessage", "readMessage", "authenticateMessage"];
+type NativeGoldstone = Pick<typeof import("./native/generated.js"), (typeof NATIVE_CALLS)[number]>;
+export declare function isNativeAvailable(): boolean;
+/**
+ * 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 declare function snapshot(raw: Uint8Array): Buffer;
+/** The engine, or a refusal explaining how to get one. */
+export declare function engine(): NativeGoldstone;
+export {};
+//# sourceMappingURL=native.d.ts.map

package/dist/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,kFAAkF;AAClF,QAAA,MAAM,YAAY,iEAIR,CAAC;AAEX,KAAK,eAAe,GAAG,IAAI,CAC1B,cAAc,uBAAuB,CAAC,EACtC,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAC7B,CAAC;AAWF,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAEhD;AAED,0DAA0D;AAC1D,wBAAgB,MAAM,IAAI,eAAe,CASxC"}

package/dist/native.js

@@ -0,0 +1,45 @@
+/**
+ * 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",
+];
+/** The same three calls, checked at load: a stale binary loads just as well. */
+function isNativeGoldstone(value) {
+    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() {
+    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) {
+    return Buffer.from(raw);
+}
+/** The engine, or a refusal explaining how to get one. */
+export function engine() {
+    if (native === undefined) {
+        throw new GoldstoneNativeRequiredError(loadError === undefined
+            ? vendorUnavailableReason()
+            : `failed to load (${loadError instanceof Error ? loadError.message : String(loadError)})`);
+    }
+    return native;
+}
+//# sourceMappingURL=native.js.map

package/dist/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../src/native.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACN,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,IAAI,uBAAuB,GAC5C,MAAM,0BAA0B,CAAC;AAElC,kFAAkF;AAClF,MAAM,YAAY,GAAG;IACpB,cAAc;IACd,aAAa;IACb,qBAAqB;CACZ,CAAC;AAOX,gFAAgF;AAChF,SAAS,iBAAiB,CAAC,KAAc;IACxC,OAAO,YAAY,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,OAAO,GAAG,gBAAgB,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;AAClE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;AAE7D,MAAM,UAAU,iBAAiB;IAChC,OAAO,MAAM,KAAK,SAAS,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAe;IACvC,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,MAAM;IACrB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,4BAA4B,CACrC,SAAS,KAAK,SAAS;YACtB,CAAC,CAAC,uBAAuB,EAAE;YAC3B,CAAC,CAAC,mBAAmB,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAC3F,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/services/main.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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";
+/** Seat the instance — called by GoldstoneProvider, or by an app wiring its own. */
+export declare function setInbox(inbox: InboxManager): void;
+/** The seated instance, if there is one. */
+export declare function getInbox(): InboxManager | undefined;
+/** Drop the instance IF it is still the one passed in (ownership guard). */
+export declare function clearInbox(inbox: InboxManager): void;
+declare const inbox: InboxManager;
+export default inbox;
+//# sourceMappingURL=main.d.ts.map

package/dist/services/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAElD;AAED,4CAA4C;AAC5C,wBAAgB,QAAQ,IAAI,YAAY,GAAG,SAAS,CAEnD;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAEpD;AAED,QAAA,MAAM,KAAK,EAAE,YAgBX,CAAC;AAEH,eAAe,KAAK,CAAC"}

package/dist/services/main.js

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+let instance;
+/** Seat the instance — called by GoldstoneProvider, or by an app wiring its own. */
+export function setInbox(inbox) {
+    instance = inbox;
+}
+/** The seated instance, if there is one. */
+export function getInbox() {
+    return instance;
+}
+/** Drop the instance IF it is still the one passed in (ownership guard). */
+export function clearInbox(inbox) {
+    if (instance === inbox)
+        instance = undefined;
+}
+const inbox = 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;
+//# sourceMappingURL=main.js.map

package/dist/services/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,IAAI,QAAkC,CAAC;AAEvC,oFAAoF;AACpF,MAAM,UAAU,QAAQ,CAAC,KAAmB;IAC3C,QAAQ,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,QAAQ;IACvB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAC,KAAmB;IAC7C,IAAI,QAAQ,KAAK,KAAK;QAAE,QAAQ,GAAG,SAAS,CAAC;AAC9C,CAAC;AAED,MAAM,KAAK,GAAiB,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;IAC1D,GAAG,CAAC,OAAO,EAAE,QAAQ;QACpB,uEAAuE;QACvE,uEAAuE;QACvE,gDAAgD;QAChD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;YACzD,OAAO,SAAS,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACd,mGAAmG,CACnG,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACxD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,KAAK,CAAC"}