@mxraven/mail 0.1.0

package/dist/webhook/index.d.ts

@@ -0,0 +1,411 @@
+//#region src/webhook/payload.d.ts
+/**
+ * mxRaven webhook payload shapes.
+ */
+/** Identifies the shape of a decoded webhook payload. */
+export declare const eventType: {
+  /** A `DELIVER_WEBHOOK` delivery carrying a complete inbound message. */
+  readonly inboundEmail: "inbound_email";
+  /** A `NOTIFY_WEBHOOK` delivery carrying the status of an object-storage write. */
+  readonly storageStatus: "s3_egress_status";
+  /**
+   * A `NOTIFY_WEBHOOK` delivery carrying the status of an SMTP delivery.
+   *
+   * The SMTP producer does not send an `event_type` field, so this value is
+   * assigned by {@link decode}.
+   */
+  readonly deliveryStatus: "delivery_status";
+};
+/** Identifies the shape of a decoded webhook payload. */
+type EventType = (typeof eventType)[keyof typeof eventType];
+/** The lifecycle state reported by a delivery-status webhook. */
+export declare const statusOutcome: {
+  /** A delivery attempt started. */
+  readonly attempted: "attempted";
+  /** The destination accepted the message. */
+  readonly delivered: "delivered";
+  /** The destination temporarily rejected the message. */
+  readonly deferred: "deferred";
+  /** Delivery failed permanently. */
+  readonly failed: "failed";
+  /** The delivery deadline passed before success. */
+  readonly expired: "expired";
+  /** Delivery was skipped by a suppression rule. It is reported for SMTP deliveries only. */
+  readonly suppressed: "suppressed";
+};
+/** The lifecycle state reported by a delivery-status webhook. */
+type StatusOutcome = (typeof statusOutcome)[keyof typeof statusOutcome];
+/**
+ * The final routing action recorded for an inbound message.
+ *
+ * Values are the mxRaven worker enum names.
+ */
+export declare const terminalAction: {
+  /** Deliver through a dedicated IP pool. */
+  readonly deliverDedicated: "TERMINAL_ACTION_TYPE_DELIVER_DEDICATED";
+  /** Relay through the configured smarthost. */
+  readonly smarthostRelay: "TERMINAL_ACTION_TYPE_SMARTHOST_RELAY";
+  /** Deliver to a webhook endpoint. */
+  readonly deliverWebhook: "TERMINAL_ACTION_TYPE_DELIVER_WEBHOOK";
+  /** Forward the message to an SMTP destination. */
+  readonly smtpForward: "TERMINAL_ACTION_TYPE_SMTP_FORWARD";
+  /** Relay the message to another MX. */
+  readonly relay: "TERMINAL_ACTION_TYPE_RELAY";
+  /** Store the message in object storage. */
+  readonly s3Store: "TERMINAL_ACTION_TYPE_S3_STORE";
+  /** Send an automatic reply. */
+  readonly autoReply: "TERMINAL_ACTION_TYPE_AUTO_REPLY";
+  /** Accept and discard the message. */
+  readonly drop: "TERMINAL_ACTION_TYPE_DROP";
+  /** Reject the message. */
+  readonly reject: "TERMINAL_ACTION_TYPE_REJECT";
+  /** Deliver the message normally. */
+  readonly deliver: "TERMINAL_ACTION_TYPE_DELIVER";
+  /** Handle a DSN at an SRS return address. */
+  readonly srsReturn: "TERMINAL_ACTION_TYPE_SRS_RETURN";
+  /** Generate a local DSN. */
+  readonly localDsn: "TERMINAL_ACTION_TYPE_LOCAL_DSN";
+};
+/** The final routing action recorded for an inbound message. */
+type TerminalAction = (typeof terminalAction)[keyof typeof terminalAction];
+/** A decoded webhook delivery. */
+type Event = {
+  readonly type: typeof eventType.inboundEmail;
+  readonly inboundEmail: InboundEmail;
+} | {
+  readonly type: typeof eventType.deliveryStatus;
+  readonly deliveryStatus: DeliveryStatus;
+} | {
+  readonly type: typeof eventType.storageStatus;
+  readonly storageStatus: StorageStatus;
+};
+/** The final routing outcome for an inbound message. */
+interface RoutingDecision {
+  /** The final terminal action. Values are the mxRaven worker enum names. */
+  readonly terminal_action: TerminalAction;
+  /** The rule that selected the terminal action, when one matched. */
+  readonly matched_rule_id?: string;
+  /** Whether the listener default was used because no rule produced a terminal action. */
+  readonly used_listener_default: boolean;
+}
+/** Spam and malware scan results. */
+interface Verdicts {
+  /** The scanner action description. */
+  readonly action: string;
+  /** The spam score that was assigned. */
+  readonly score: number;
+  /** The threshold the message was compared against. */
+  readonly required_score: number;
+  /** Whether the message was classified as spam. */
+  readonly is_spam: boolean;
+  /** Whether malware was detected. */
+  readonly has_malware: boolean;
+  /** The detected malware signatures. */
+  readonly malware_names: readonly string[];
+  /** Whether scanning was skipped. */
+  readonly is_skipped: boolean;
+  /** The scanner error, when scanning failed. */
+  readonly error: string;
+}
+/** The SMTP envelope of a message. */
+interface WebhookEnvelope {
+  /** The envelope sender. It may be empty for a null reverse-path. */
+  readonly mail_from: string;
+  /** The envelope recipients. */
+  readonly rcpt_to: readonly string[];
+}
+/** A summary of the parsed message headers. */
+interface MessageSummary {
+  /** The decoded Subject header. */
+  readonly subject?: string;
+  /** The decoded From mailboxes. */
+  readonly from?: readonly string[];
+  /** The decoded To mailboxes. */
+  readonly to?: readonly string[];
+  /** The decoded Cc mailboxes. */
+  readonly cc?: readonly string[];
+  /** The Message-ID header. */
+  readonly message_id?: string;
+  /** The raw Date header. */
+  readonly date?: string;
+}
+/** One message header occurrence. */
+interface HeaderField {
+  /** The header field name. */
+  readonly name: string;
+  /** The header field value. */
+  readonly value: string;
+}
+/**
+ * Time-limited access to the raw RFC 822 message.
+ *
+ * Use {@link fetchRawEmail} to download the content.
+ */
+interface RawEmail {
+  /** The message download URL. */
+  readonly url: string;
+  /** The authorization scheme, normally `Bearer`. */
+  readonly token_type?: string;
+  /** The bearer token for the download URL. Treat it as a secret and do not log it. */
+  readonly access_token: string;
+  /** The Unix time, in seconds, when the token expires. */
+  readonly expires_at_utc?: number;
+  /** The raw message size. */
+  readonly size_bytes?: number;
+  /** The lowercase hex SHA-256 of the raw message bytes. */
+  readonly sha256_hex?: string;
+  /** The parsed message media type. */
+  readonly content_type?: string;
+}
+/** The `DELIVER_WEBHOOK` payload. */
+interface InboundEmail {
+  /** Always `inbound_email`. */
+  readonly event_type: string;
+  /** The delivery task identifier, stable across retries. */
+  readonly task_id: string;
+  /** The owning tenant. */
+  readonly tenant_id: string;
+  /** The listener that accepted the message. */
+  readonly listener_id: string;
+  /** The delivery attempt number, starting at 1. */
+  readonly attempt: number;
+  /** The Unix time, in seconds, when mxRaven accepted the message. */
+  readonly accepted_at_utc: number;
+  /** The Unix time, in seconds, when this delivery was built. */
+  readonly occurred_at_utc: number;
+  /** The final routing outcome. */
+  readonly routing_decision: RoutingDecision;
+  /** The spam and malware scan results, when scanning ran. */
+  readonly verdicts?: Verdicts;
+  /** The SMTP envelope. */
+  readonly envelope: WebhookEnvelope;
+  /** The parsed message header summary. */
+  readonly message: MessageSummary;
+  /** Every message header in the order received. */
+  readonly headers: readonly HeaderField[];
+  /** Time-limited access to the raw RFC 822 message. */
+  readonly raw_email: RawEmail;
+}
+/** The SMTP `NOTIFY_WEBHOOK` payload. */
+interface DeliveryStatus {
+  /** The delivery task identifier, stable across attempts. */
+  readonly task_id: string;
+  /** The owning tenant. */
+  readonly tenant_id: string;
+  /** The source listener. */
+  readonly listener_id: string;
+  /** The delivery outcome. */
+  readonly status: StatusOutcome;
+  /** The delivery attempt number, starting at 1. */
+  readonly attempt: number;
+  /** The Unix time, in seconds, when mxRaven accepted the message. */
+  readonly accepted_at_utc: number;
+  /** The Unix time, in seconds, when this status was built. */
+  readonly occurred_at_utc: number;
+  /** The egress source address, when known. */
+  readonly source_ip?: string;
+  /** The recipient domain. */
+  readonly destination_domain?: string;
+  /** The remote MTA hostname, when known. */
+  readonly remote_host?: string;
+  /** The remote SMTP reply code. */
+  readonly smtp_code?: number;
+  /** The RFC 3463 enhanced status code. */
+  readonly enhanced_status_code?: string;
+  /** The remote reply text, truncated to 512 bytes. */
+  readonly remote_response?: string;
+  /** The Unix time, in seconds, of the next attempt for a deferred status. */
+  readonly next_retry_at_utc?: number;
+  /** Links a generated DSN back to its original task. */
+  readonly correlation_task_id?: string;
+}
+/** The object-storage `NOTIFY_WEBHOOK` payload. */
+interface StorageStatus {
+  /** Always `s3_egress_status`. */
+  readonly event_type: string;
+  /** The storage task identifier. */
+  readonly task_id?: string;
+  /** The owning tenant. */
+  readonly tenant_id?: string;
+  /** The source listener. */
+  readonly listener_id?: string;
+  /** The storage outcome. */
+  readonly status: StatusOutcome;
+  /** The delivery attempt number, starting at 1. */
+  readonly attempt: number;
+  /** The Unix time, in seconds, when mxRaven accepted the message. */
+  readonly accepted_at_utc?: number;
+  /** The Unix time, in seconds, when this status was built. */
+  readonly occurred_at_utc: number;
+  /** The storage integration identifier. */
+  readonly storage_ref?: string;
+  /** The destination bucket. */
+  readonly bucket_name?: string;
+  /** The stored object key. */
+  readonly object_key?: string;
+  /** The storage endpoint host. */
+  readonly endpoint_host?: string;
+  /** The storage provider response status. */
+  readonly status_code?: number;
+  /** The storage provider error code. */
+  readonly error_code?: string;
+  /** The failure description, truncated to 512 bytes. */
+  readonly message?: string;
+  /** The Unix time, in seconds, of the next attempt for a deferred status. */
+  readonly next_retry_at_utc?: number;
+}
+//#endregion
+//#region src/webhook/decode.d.ts
+/**
+ * Decodes a webhook payload.
+ *
+ * Dispatching is based on the payload's `event_type` field. SMTP delivery
+ * statuses do not carry an `event_type`, so a body with a `status` field and no
+ * recognized event type is decoded as a delivery status.
+ *
+ * @param body - The raw JSON payload bytes, or a decoded string.
+ * @returns The decoded event.
+ * @throws `Error` When the body is not valid JSON or the payload is
+ * unrecognized.
+ *
+ * @public
+ */
+export declare function decode(body: Uint8Array | string): Event;
+//#endregion
+//#region src/webhook/errors.d.ts
+/**
+ * A webhook signature did not match the request.
+ *
+ * @public
+ */
+export declare class InvalidSignatureError extends Error {
+  /**
+   * @param message - A human-readable description.
+   */
+  constructor(message?: string);
+}
+//#endregion
+//#region src/webhook/raw.d.ts
+/** A minimal `fetch`-compatible function. @public */
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Options for {@link fetchRawEmail}. */
+interface FetchRawEmailOptions {
+  /** Cancels the download. */
+  readonly signal?: AbortSignal;
+  /** The `fetch` implementation to use. Defaults to the global `fetch`. */
+  readonly fetch?: FetchLike;
+}
+/**
+ * Downloads the raw RFC 822 message referenced by a `DELIVER_WEBHOOK` payload.
+ *
+ * The payload's short-lived bearer token is sent in the `Authorization` header,
+ * and the downloaded bytes are verified against the declared size and SHA-256
+ * digest. Treat `raw_email.access_token` as a secret and do not log it.
+ *
+ * @param raw - The `raw_email` object from an inbound-email payload.
+ * @param options - An optional cancellation signal and `fetch` implementation.
+ * @returns The exact message bytes.
+ * @throws `Error` When the URL or token is empty, the response is unsuccessful,
+ * or the downloaded bytes fail the size or digest check.
+ *
+ * @example
+ * ```ts
+ * const bytes = await fetchRawEmail(event.inboundEmail.rawEmail, { signal });
+ * ```
+ *
+ * @public
+ */
+export declare function fetchRawEmail(raw: RawEmail, options?: FetchRawEmailOptions): Promise<Uint8Array>;
+//#endregion
+//#region src/webhook/verifier.d.ts
+/**
+ * The mxRaven signature headers.
+ *
+ * HTTP header names are case-insensitive; these constants carry the canonical
+ * spelling used by mxRaven.
+ */
+export declare const webhookHeaders: {
+  /** The delivery ID, which is the delivery task ID. */
+  readonly webhookId: "X-MxRaven-Webhook-ID";
+  /** The Unix signing time in seconds. */
+  readonly timestamp: "X-MxRaven-Timestamp";
+  /** The `sha256=<hex>` HMAC. */
+  readonly signature: "X-MxRaven-Signature";
+  /** The signing key ID. */
+  readonly signatureKid: "X-MxRaven-Signature-Kid";
+};
+/** Options for a {@link Verifier}. */
+interface VerifierOptions {
+  /** The signing secret, used as literal bytes and not decoded. */
+  readonly secret?: string;
+  /** Per-key secrets for key rotation, keyed by signing key ID. */
+  readonly keys?: ReadonlyMap<string, string>;
+  /** The maximum accepted clock skew in milliseconds. Defaults to 5 minutes; `0` disables the check. */
+  readonly tolerance?: number;
+  /** The maximum request body size in bytes. Defaults to 1 MiB. */
+  readonly maxBodyBytes?: number;
+}
+/** Per-call options for verification. */
+interface VerifyOptions {
+  /** Cancels the body read. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Verifies the signature of an mxRaven webhook request.
+ *
+ * A verifier is safe for concurrent use once constructed. Configure it with a
+ * signing secret or with per-key secrets for rotation.
+ *
+ * @example
+ * ```ts
+ * const secret = process.env.MXRAVEN_WEBHOOK_SECRET;
+ * if (secret === undefined || secret === "") {
+ *   throw new Error("MXRAVEN_WEBHOOK_SECRET is required");
+ * }
+ *
+ * const verifier = new Verifier({ secret });
+ * const event = await verifier.verifyAndDecode(request);
+ * ```
+ *
+ * @public
+ */
+export declare class Verifier {
+  private readonly secret;
+  private readonly keys;
+  private readonly tolerance;
+  private readonly maxBodyBytes;
+  /**
+   * @param options - The signing secret and verification limits.
+   * @throws `Error` When no secret is provided or an option is invalid.
+   */
+  constructor(options?: VerifierOptions);
+  /**
+   * Verifies a request's signature.
+   *
+   * The body is read from a clone, so the caller can still read the original
+   * request body afterwards.
+   *
+   * @param request - The incoming request.
+   * @param options - An optional cancellation signal.
+   * @throws {@link InvalidSignatureError} When the signature does not match.
+   * @throws `Error` When required headers are missing, the timestamp is stale,
+   * or the body exceeds the configured limit.
+   */
+  verify(request: Request, options?: VerifyOptions): Promise<void>;
+  /**
+   * Verifies a request and decodes its payload.
+   *
+   * @param request - The incoming request.
+   * @param options - An optional cancellation signal.
+   * @returns The decoded event.
+   * @throws {@link InvalidSignatureError} When the signature does not match.
+   * @throws `Error` When verification or decoding fails.
+   */
+  verifyAndDecode(request: Request, options?: VerifyOptions): Promise<Event>;
+  private readBody;
+  private check;
+  private secretFor;
+}
+//#endregion
+export type { DeliveryStatus, Event, EventType, FetchLike, FetchRawEmailOptions, HeaderField, InboundEmail, MessageSummary, RawEmail, RoutingDecision, StatusOutcome, StorageStatus, TerminalAction, Verdicts, VerifierOptions, VerifyOptions, WebhookEnvelope };
+//# sourceMappingURL=index.d.ts.map

package/dist/webhook/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/webhook/payload.ts","../../src/webhook/decode.ts","../../src/webhook/errors.ts","../../src/webhook/raw.ts","../../src/webhook/verifier.ts"],"mappings":";;;;;qBAKa;;;;;;;;;;;;;;KAeD,oBAAoB,wBAAwB;;qBAG3C;;;;;;;;;;;;;;;KAgBD,wBAAwB,4BAA4B;;;;;;qBAOnD;;;;;;;;;;;;;;;;;;;;;;;;;;;KA4BD,yBAAyB,6BAA6B;;KAGtD;WACG,aAAa,UAAU;WAAuB,cAAc;;WAC5D,aAAa,UAAU;WAAyB,gBAAgB;;WAChE,aAAa,UAAU;WAAwB,eAAe;;;UAG5D;;WAEN,iBAAiB;;WAEjB;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIM;;WAEN;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIM;;WAEN;;WAEA;;;;;;;UAQM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA,kBAAkB;;WAElB,WAAW;;WAEX,UAAU;;WAEV,SAAS;;WAET,kBAAkB;;WAElB,WAAW;;;UAIL;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;UAIM;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA,QAAQ;;WAER;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;;;;;;;;;;;;;;;;;wBC7OK,OAAO,MAAM,sBAAsB;;;;;;;;qBCrBtC,8BAA8B;;;;EAI7B,YAAA;;;;;KCIF,aAAa,aAAa,OAAO,gBAAgB,QAAQ;;UAGpD;;WAEN,SAAS;;WAET,QAAQ;;;;;;;;;;;;;;;;;;;;;;wBAuBG,cACpB,KAAK,UACL,UAAS,uBACR,QAAQ;;;;;;;;;qBC5BE;;;;;;;;;;;UAYI;;WAEN;;WAEA,OAAO;;WAEP;;WAEA;;;UAIM;;WAEN,SAAS;;;;;;;;;;;;;;;;;;;;;qBAyBP;mBACM;mBACA;mBACA;mBACA;;;;;EAML,YAAA,UAAS;;;;;;;;;;;;;EA+Cf,OAAO,SAAS,SAAS,UAAS,gBAAqB;;;;;;;;;;EAcvD,gBAAgB,SAAS,SAAS,UAAS,gBAAqB,QAAQ;UAMhE;UAKN;UA+CA"}