@primitivedotdev/sdk 1.18.0 → 1.20.0

package/dist/{errors-BTHBQqJa.d.ts → errors-DAHv2kWU.d.ts}

@@ -1,4 +1,4 @@
-import { I as WebhookAttachment, d as EmailAuth, f as EmailReceivedEvent, u as EmailAnalysis } from "./types-DVjBmOg0.js";
+import { F as ValidateEmailAuthResult, I as WebhookAttachment, d as EmailAuth, f as EmailReceivedEvent, u as EmailAnalysis } from "./types-DVjBmOg0.js";
 import { ErrorObject } from "ajv";
 
 //#region src/webhook/received-email.d.ts
@@ -35,6 +35,179 @@ declare function buildForwardSubject(subject: string | null | undefined): string
 declare function formatAddress(address: ReceivedEmailAddress): string;
 declare function parseHeaderAddress(value: string | null | undefined): ReceivedEmailAddress | null;
 //#endregion
+//#region src/webhook/auth.d.ts
+/**
+ * Validate email authentication and compute a verdict.
+ *
+ * This function analyzes SPF, DKIM, and DMARC results to determine
+ * whether an email is likely authentic ("legit"), potentially spoofed
+ * ("suspicious"), or indeterminate ("unknown").
+ *
+ * ## Verdict Logic
+ *
+ * **Legit (high confidence):**
+ * - DMARC pass with DKIM alignment (cryptographic proof of authenticity)
+ *
+ * **Legit (medium confidence):**
+ * - DMARC pass with SPF alignment only (no DKIM)
+ *   - Note: SPF can break through forwarding, but DMARC pass is still meaningful
+ *
+ * **Suspicious (high confidence):**
+ * - DMARC fail when domain has `reject` or `quarantine` policy
+ *   - The domain owner explicitly says to distrust failing emails
+ * - SPF explicitly fails (IP not authorized by sender)
+ *
+ * **Suspicious (low confidence):**
+ * - DMARC fail when domain has `none` policy (monitoring mode)
+ * - No DMARC record but SPF/DKIM fail
+ *
+ * **Unknown:**
+ * - No DMARC record and no clear pass/fail
+ * - Temporary errors during authentication
+ * - No authentication data available
+ *
+ * A `legit` verdict means the email authenticated as its own From
+ * domain, not as any particular domain you trust. For authorization
+ * decisions, pair the verdict with a domain anchor via
+ * {@link isTrustedSender} instead of checking the verdict alone.
+ *
+ * @param auth - Email authentication results from the webhook
+ * @returns Verdict, confidence level, and explanatory reasons
+ *
+ * @example
+ * ```typescript
+ * const result = validateEmailAuth({
+ *   spf: 'pass',
+ *   dmarc: 'pass',
+ *   dmarcPolicy: 'reject',
+ *   dmarcFromDomain: 'example.com',
+ *   dmarcSpfAligned: true,
+ *   dmarcDkimAligned: true,
+ *   dmarcSpfStrict: false,
+ *   dmarcDkimStrict: false,
+ *   dkimSignatures: [{
+ *     domain: 'example.com',
+ *     selector: 'default',
+ *     result: 'pass',
+ *     aligned: true,
+ *     keyBits: 2048,
+ *     algo: 'rsa-sha256',
+ *   }],
+ * });
+ *
+ * // result.verdict === 'legit'
+ * // result.confidence === 'high'
+ * // result.reasons === ['DMARC passed with DKIM alignment']
+ * ```
+ */
+declare function validateEmailAuth(auth: EmailAuth): ValidateEmailAuthResult;
+//#endregion
+//#region src/webhook/trust.d.ts
+/**
+ * Why an email was or was not trusted. Stable machine-readable codes,
+ * ordered here by the sequence in which the checks run:
+ *
+ * - `trusted`: every check passed.
+ * - `auth-missing`: the event carries no usable `email.auth` object.
+ * - `auth-suspicious`: `validateEmailAuth` returned a `suspicious`
+ *   verdict (DMARC/SPF failure signals).
+ * - `dmarc-temperror`: DMARC evaluation hit a temporary DNS error. The
+ *   only retryable reason; the same email may verify cleanly once DNS
+ *   recovers.
+ * - `auth-unknown`: authenticity could not be determined and the cause
+ *   is not transient (most commonly the sender domain publishes no
+ *   DMARC record, or evaluation hit a permanent error).
+ * - `dmarc-domain-mismatch`: the email authenticated, but the domain
+ *   DMARC evaluated (the RFC 5322 From domain seen by the server) is
+ *   not the expected domain.
+ * - `from-header-multiple-addresses`: the From header lists more than
+ *   one address, which is ambiguous as an identity.
+ * - `from-header-invalid`: the From header is missing, malformed, uses
+ *   group syntax, or fails address validation.
+ * - `from-domain-mismatch`: the parsed From address's domain is not the
+ *   expected domain.
+ * - `sender-mismatch`: `options.sender` was given and the parsed From
+ *   address is a different address.
+ */
+type TrustReason = "trusted" | "auth-missing" | "auth-suspicious" | "dmarc-temperror" | "auth-unknown" | "dmarc-domain-mismatch" | "from-header-multiple-addresses" | "from-header-invalid" | "from-domain-mismatch" | "sender-mismatch";
+interface TrustedSenderOptions {
+  /**
+   * The domain the email must be authenticated as (the RFC 5322 From
+   * domain). Matched exactly, case-insensitively: mail from a subdomain
+   * of `domain` does not match. Pass the subdomain itself to accept it.
+   */
+  domain: string;
+  /**
+   * Optional exact sender to require, as a bare address
+   * (`user@example.com`). Compared case-insensitively against the
+   * parsed From address. Note that DMARC authenticates the domain, not
+   * the local part: the domain owner's infrastructure controls which
+   * local parts it signs mail for.
+   */
+  sender?: string;
+}
+interface TrustedSenderResult {
+  /** True when the email is authenticated as the expected domain (and sender, if given). */
+  trusted: boolean;
+  /**
+   * True only for transient failures (`dmarc-temperror`). Callers that
+   * respond with a 5xx let webhook redelivery retry the same email
+   * after DNS recovers. All other untrusted reasons are permanent for
+   * this email.
+   */
+  retryable: boolean;
+  /** Machine-readable code for the first check that failed, or `trusted`. */
+  reason: TrustReason;
+  /** The underlying `validateEmailAuth` result, for logging and diagnostics. */
+  auth: ValidateEmailAuthResult;
+}
+/**
+ * Check whether an inbound email is authenticated as an expected domain
+ * (and optionally an exact sender address).
+ *
+ * `trusted` is true only when ALL of the following hold:
+ *
+ * 1. `validateEmailAuth(event.email.auth)` returns a `legit` verdict.
+ * 2. `event.email.auth.dmarcFromDomain` (the domain the server's DMARC
+ *    evaluation ran against) equals `options.domain`.
+ * 3. The From header strict-parses to exactly one valid address whose
+ *    domain equals `options.domain`.
+ * 4. When `options.sender` is given, the parsed From address equals it
+ *    exactly (case-insensitive).
+ *
+ * ## Why the extra checks beyond the verdict
+ *
+ * The verdict alone says an email was authenticated, not which domain
+ * it was authenticated as: a fully authenticated email from an
+ * attacker-controlled domain is `legit`. Anchoring `dmarcFromDomain`
+ * closes that. The strict From parse defends the remaining gaps:
+ *
+ * - Naively regexing the raw From header is unsafe. A header like
+ *   `From: "trusted@example.com" <x@evil.com>` plants an allowlisted
+ *   address in the display name while DMARC evaluates (and passes for)
+ *   `evil.com`. The strict parser extracts only the real addr-spec and
+ *   rejects multi-address and group forms outright.
+ * - `normalizeReceivedEmail().sender` is NOT a safe anchor for
+ *   authorization: it uses a lenient parser and falls back to the SMTP
+ *   envelope sender (`smtp.mail_from`), which the sender fully
+ *   controls. The same goes for Reply-To (`replyTarget`). This function
+ *   never consults either.
+ * - An `unknown` verdict is not one thing: a DMARC temperror is
+ *   transient (surfaced as `retryable: true`, respond 5xx and let
+ *   webhook redelivery retry), while "no DMARC record" is permanent
+ *   for the email and surfaced as non-retryable.
+ *
+ * Never throws for malformed event content; malformed input yields an
+ * untrusted result with a reason. Throws `TypeError` only for invalid
+ * `options` (programmer error).
+ *
+ * @param event - The verified `email.received` webhook event
+ * @param options - Expected domain and optional exact sender
+ * @returns Trust decision with a stable reason code and the underlying
+ *   auth result
+ */
+declare function isTrustedSender(event: EmailReceivedEvent, options: TrustedSenderOptions): TrustedSenderResult;
+//#endregion
 //#region src/webhook/errors.d.ts
 /**
  * Verification error definitions.
@@ -242,4 +415,4 @@ declare class RawEmailDecodeError extends PrimitiveWebhookError {
   constructor(code: RawEmailDecodeErrorCode, message?: string);
 }
 //#endregion
-export { buildForwardSubject as _, RawEmailDecodeErrorCode as a, normalizeReceivedEmail as b, WebhookPayloadError as c, WebhookValidationErrorCode as d, WebhookVerificationError as f, ReceivedEmailThread as g, ReceivedEmailAddress as h, RawEmailDecodeError as i, WebhookPayloadErrorCode as l, ReceivedEmail as m, PrimitiveWebhookError as n, VERIFICATION_ERRORS as o, WebhookVerificationErrorCode as p, RAW_EMAIL_ERRORS as r, WebhookErrorCode as s, PAYLOAD_ERRORS as t, WebhookValidationError as u, buildReplySubject as v, parseHeaderAddress as x, formatAddress as y };
+export { buildReplySubject as C, parseHeaderAddress as E, buildForwardSubject as S, normalizeReceivedEmail as T, isTrustedSender as _, RawEmailDecodeErrorCode as a, ReceivedEmailAddress as b, WebhookPayloadError as c, WebhookValidationErrorCode as d, WebhookVerificationError as f, TrustedSenderResult as g, TrustedSenderOptions as h, RawEmailDecodeError as i, WebhookPayloadErrorCode as l, TrustReason as m, PrimitiveWebhookError as n, VERIFICATION_ERRORS as o, WebhookVerificationErrorCode as p, RAW_EMAIL_ERRORS as r, WebhookErrorCode as s, PAYLOAD_ERRORS as t, WebhookValidationError as u, validateEmailAuth as v, formatAddress as w, ReceivedEmailThread as x, ReceivedEmail as y };

package/dist/{index-D2nlv8DS.d.ts → index-DJeUuGUn.d.ts}

@@ -1,5 +1,5 @@
-import { F as ValidateEmailAuthResult, L as WebhookEvent, d as EmailAuth, f as EmailReceivedEvent } from "./types-DVjBmOg0.js";
-import { m as ReceivedEmail, u as WebhookValidationError } from "./errors-BTHBQqJa.js";
+import { L as WebhookEvent, f as EmailReceivedEvent } from "./types-DVjBmOg0.js";
+import { u as WebhookValidationError, y as ReceivedEmail } from "./errors-DAHv2kWU.js";
 
 //#region src/validation.d.ts
 interface ValidationSuccess<T> {
@@ -1380,68 +1380,6 @@ declare const emailReceivedEventJsonSchema: {
   };
 };
 //#endregion
-//#region src/webhook/auth.d.ts
-/**
- * Validate email authentication and compute a verdict.
- *
- * This function analyzes SPF, DKIM, and DMARC results to determine
- * whether an email is likely authentic ("legit"), potentially spoofed
- * ("suspicious"), or indeterminate ("unknown").
- *
- * ## Verdict Logic
- *
- * **Legit (high confidence):**
- * - DMARC pass with DKIM alignment (cryptographic proof of authenticity)
- *
- * **Legit (medium confidence):**
- * - DMARC pass with SPF alignment only (no DKIM)
- *   - Note: SPF can break through forwarding, but DMARC pass is still meaningful
- *
- * **Suspicious (high confidence):**
- * - DMARC fail when domain has `reject` or `quarantine` policy
- *   - The domain owner explicitly says to distrust failing emails
- * - SPF explicitly fails (IP not authorized by sender)
- *
- * **Suspicious (low confidence):**
- * - DMARC fail when domain has `none` policy (monitoring mode)
- * - No DMARC record but SPF/DKIM fail
- *
- * **Unknown:**
- * - No DMARC record and no clear pass/fail
- * - Temporary errors during authentication
- * - No authentication data available
- *
- * @param auth - Email authentication results from the webhook
- * @returns Verdict, confidence level, and explanatory reasons
- *
- * @example
- * ```typescript
- * const result = validateEmailAuth({
- *   spf: 'pass',
- *   dmarc: 'pass',
- *   dmarcPolicy: 'reject',
- *   dmarcFromDomain: 'example.com',
- *   dmarcSpfAligned: true,
- *   dmarcDkimAligned: true,
- *   dmarcSpfStrict: false,
- *   dmarcDkimStrict: false,
- *   dkimSignatures: [{
- *     domain: 'example.com',
- *     selector: 'default',
- *     result: 'pass',
- *     aligned: true,
- *     keyBits: 2048,
- *     algo: 'rsa-sha256',
- *   }],
- * });
- *
- * // result.verdict === 'legit'
- * // result.confidence === 'high'
- * // result.reasons === ['DMARC passed with DKIM alignment']
- * ```
- */
-declare function validateEmailAuth(auth: EmailAuth): ValidateEmailAuthResult;
-//#endregion
 //#region src/webhook/version.d.ts
 /**
  * Webhook API Version
@@ -1726,4 +1664,4 @@ declare function decodeRawEmail(event: EmailReceivedEvent, options?: DecodeRawEm
  */
 declare function verifyRawEmailDownload(downloaded: Buffer | ArrayBuffer | Uint8Array, event: EmailReceivedEvent): Buffer;
 //#endregion
-export { PRIMITIVE_SIGNATURE_HEADER as A, safeValidateEmailReceivedEvent as B, StandardWebhooksSignResult as C, LEGACY_CONFIRMED_HEADER as D, verifyStandardWebhooksSignature as E, GenerateDownloadTokenOptions as F, VerifyDownloadTokenOptions as I, VerifyDownloadTokenResult as L, VerifyOptions as M, signWebhookPayload as N, LEGACY_SIGNATURE_HEADER as O, verifyWebhookSignature as P, generateDownloadToken as R, STANDARD_WEBHOOK_TIMESTAMP_HEADER as S, signStandardWebhooksPayload as T, validateEmailReceivedEvent as V, WEBHOOK_VERSION as _, WebhookHeaders as a, STANDARD_WEBHOOK_ID_HEADER as b, getDownloadTimeRemaining as c, handleWebhookEvent as d, isDownloadExpired as f, verifyRawEmailDownload as g, receive as h, WEBHOOK_EVENT_HEADER as i, SignResult as j, PRIMITIVE_CONFIRMED_HEADER as k, getEventHeader as l, parseWebhookEvent as m, HandleWebhookOptions as n, confirmedHeaders as o, isRawIncluded as p, ReceiveRequestOptions as r, decodeRawEmail as s, DecodeRawEmailOptions as t, handleWebhook as u, validateEmailAuth as v, StandardWebhooksVerifyOptions as w, STANDARD_WEBHOOK_SIGNATURE_HEADER as x, emailReceivedEventJsonSchema as y, verifyDownloadToken as z };
+export { SignResult as A, validateEmailReceivedEvent as B, StandardWebhooksVerifyOptions as C, LEGACY_SIGNATURE_HEADER as D, LEGACY_CONFIRMED_HEADER as E, VerifyDownloadTokenOptions as F, VerifyDownloadTokenResult as I, generateDownloadToken as L, signWebhookPayload as M, verifyWebhookSignature as N, PRIMITIVE_CONFIRMED_HEADER as O, GenerateDownloadTokenOptions as P, verifyDownloadToken as R, StandardWebhooksSignResult as S, verifyStandardWebhooksSignature as T, WEBHOOK_VERSION as _, WebhookHeaders as a, STANDARD_WEBHOOK_SIGNATURE_HEADER as b, getDownloadTimeRemaining as c, handleWebhookEvent as d, isDownloadExpired as f, verifyRawEmailDownload as g, receive as h, WEBHOOK_EVENT_HEADER as i, VerifyOptions as j, PRIMITIVE_SIGNATURE_HEADER as k, getEventHeader as l, parseWebhookEvent as m, HandleWebhookOptions as n, confirmedHeaders as o, isRawIncluded as p, ReceiveRequestOptions as r, decodeRawEmail as s, DecodeRawEmailOptions as t, handleWebhook as u, emailReceivedEventJsonSchema as v, signStandardWebhooksPayload as w, STANDARD_WEBHOOK_TIMESTAMP_HEADER as x, STANDARD_WEBHOOK_ID_HEADER as y, safeValidateEmailReceivedEvent as z };