@visulima/email 1.0.0-alpha.9 → 1.0.0

package/dist/crypto/index.d.ts

@@ -1,4 +1,304 @@
-export { createDkimSigner, DkimSigner } from "./dkim-signer.d.ts";
-export { createSmimeEncrypter, SmimeEncrypter } from "./smime-encrypter.d.ts";
-export { createSmimeSigner, SmimeSigner } from "./smime-signer.d.ts";
-export type { DkimOptions, EmailEncrypter, EmailSigner, SmimeEncryptOptions, SmimeSignOptions } from "./types.d.ts";
+import { KeyObject } from 'node:crypto';
+import { E as EmailOptions } from "../packem_shared/types.d-ejzh-xBP.js";
+import { D as DkimOptions, E as EmailSigner, S as SmimeEncryptOptions, a as EmailEncrypter, b as SmimeSignOptions } from "../packem_shared/types.d-BId55FW2.js";
+import 'node:buffer';
+/**
+* The signature algorithm for the ARC headers. RSA per RFC 8617, Ed25519 per RFC 8463.
+*/
+type ArcAlgorithm = "ed25519-sha256" | "rsa-sha256";
+/**
+* Options for {@link signArc}.
+*/
+interface ArcSealOptions {
+  /**
+  * Signature algorithm (`a=`). `rsa-sha256` (default) or `ed25519-sha256` (RFC 8463).
+  * @default "rsa-sha256"
+  */
+  algorithm?: ArcAlgorithm;
+  /**
+  * The `Authentication-Results` value to chain (authserv-id plus method results),
+  * e.g. `example.com; spf=pass smtp.mailfrom=...; dkim=pass header.d=...`.
+  */
+  authenticationResults: string;
+  /**
+  * Chain validation status for the seal (`cv`). For an originating sealer (instance 1) this is
+  * always `none`.
+  * @default "none"
+  */
+  cv?: "fail" | "none" | "pass";
+  /**
+  * The signing domain (`d`).
+  */
+  domainName: string;
+  /**
+  * Lower-cased header names covered by the ARC-Message-Signature (`h`).
+  * @default from, to, cc, subject, date, message-id, mime-version
+  */
+  headersToSign?: string[];
+  /**
+  * The ARC instance number (`i`). Only `1` (originating sealer) is supported.
+  * @default 1
+  */
+  instance?: number;
+  /**
+  * The DKIM/ARC key selector (`s`).
+  */
+  keySelector: string;
+  /**
+  * Passphrase for an encrypted private key.
+  */
+  passphrase?: string;
+  /**
+  * Private key (PEM string, or a `file://` path). RSA or Ed25519 to match `algorithm`.
+  */
+  privateKey: string;
+  /**
+  * Signature timestamp (`t`) in unix seconds. Defaults to now.
+  */
+  timestamp?: number;
+}
+/**
+* The three ARC header fields produced for one instance.
+*/
+interface ArcHeaderSet {
+  "ARC-Authentication-Results": string;
+  "ARC-Message-Signature": string;
+  "ARC-Seal": string;
+}
+/**
+* Options for {@link verifyArc}.
+*/
+interface ArcVerifyOptions {
+  /**
+  * The ARC/DKIM public key for the signing domain+selector — a PEM string or a `KeyObject`. Look it
+  * up at `<selector>._domainkey.<d>` (the `p=` tag), decoded to SPKI.
+  */
+  publicKey: KeyObject | string;
+}
+/**
+* The outcome of {@link verifyArc}.
+*/
+interface ArcVerifyResult {
+  /**
+  * Per-component verification: the ARC-Message-Signature, the ARC-Seal, and the body hash.
+  */
+  components: {
+    ams: boolean;
+    bodyHash: boolean;
+    seal: boolean;
+  };
+  /**
+  * The chain-validation status (`cv`) from the ARC-Seal.
+  */
+  cv?: string;
+  /**
+  * A machine-readable reason when `valid` is `false`.
+  */
+  reason?: string;
+  /**
+  * Whether the whole instance verified (signature + seal + body hash).
+  */
+  valid: boolean;
+}
+/**
+* Computes the exact byte string that the ARC-Message-Signature `b=` value signs.
+*
+* Exposed so ARC verifiers (and tests) can re-derive the signing input.
+* @param email The email being sealed.
+* @param options The seal options.
+* @returns The AMS header (without the `b=` value) and the data signed.
+*/
+declare const arcMessageSignatureBase: (email: EmailOptions, options: ArcSealOptions) => {
+  header: string;
+  signBase: string;
+};
+/**
+* Computes the exact byte string that the ARC-Seal `b=` value signs (for an originating, i=1 seal).
+*
+* Exposed so ARC verifiers (and tests) can re-derive the signing input.
+* @param aarValue The ARC-Authentication-Results value.
+* @param amsValue The full ARC-Message-Signature value (including its `b=` signature).
+* @param options The signing domain, selector, instance, timestamp and chain-validation status.
+* @returns The ARC-Seal header (without the `b=` value) and the data signed.
+*/
+declare const arcSealBase: (aarValue: string, amsValue: string, options: ArcSealOptions) => {
+  header: string;
+  signBase: string;
+};
+/**
+* Seals a message with an ARC (Authenticated Received Chain, RFC 8617) header set for an originating
+* sealer (instance `i=1`).
+*
+* Adds `ARC-Authentication-Results`, `ARC-Message-Signature`, and `ARC-Seal` headers. Use this when
+* your service forwards mail and wants downstream receivers to trust the authentication results you
+* observed. Supports RSA (default) and Ed25519 (`algorithm: "ed25519-sha256"`, RFC 8463) keys.
+*
+* IMPORTANT: the body hash (`bh=`) is computed over `text` + "\n\n" + `html` with relaxed
+* canonicalization — the same simplification as the DKIM signer. For a third-party ARC verifier to
+* accept the seal, the body actually transmitted on the wire must canonicalize to this same value, so
+* apply ARC at the point where the MIME body is finalized (or feed in the exact rendered body).
+* @param email The email to seal.
+* @param options The seal options. See {@link ArcSealOptions}.
+* @returns The email with the ARC header set added, and the raw {@link ArcHeaderSet}.
+* @throws {Error} When the private key cannot be loaded or signing fails.
+*/
+declare const signArc: (email: EmailOptions, options: ArcSealOptions) => Promise<{
+  email: EmailOptions;
+  headers: ArcHeaderSet;
+}>;
+/**
+* Verifies an originating (i=1) ARC header set against the signing domain's public key.
+*
+* Re-derives the AMS and ARC-Seal signing inputs from `email` + the supplied ARC headers, recomputes
+* the body hash, and checks all three. The public key must be the one published for the seal's
+* `s=`/`d=` (the DKIM-style `&lt;selector>._domainkey.&lt;domain>` TXT `p=` value).
+* @param email The message that was sealed (same fields used when signing).
+* @param headers The ARC header set (or any record containing the three `ARC-*` headers).
+* @param options Verification options. See {@link ArcVerifyOptions}.
+* @returns The verification result. See {@link ArcVerifyResult}.
+*/
+declare const verifyArc: (email: EmailOptions, headers: ArcHeaderSet | Record<string, string>, options: ArcVerifyOptions) => ArcVerifyResult;
+/**
+* DKIM signer implementation
+*/
+declare class DkimSigner implements EmailSigner {
+  /**
+  * Sanitizes a display name for use in quoted email headers per RFC 5322.
+  * Removes/replaces CR, LF, tabs with space, escapes backslashes and quotes,
+  * and strips non-printable control characters.
+  * @param name The display name to sanitize.
+  * @returns The sanitized display name, or empty string if nothing remains.
+  */
+  private static sanitizeDisplayName;
+  /**
+  * Formats an email address for use in email headers.
+  * @param address The email address object to format.
+  * @param address.email The email address string.
+  * @param address.name Optional display name for the email address.
+  * @returns The formatted email address string in RFC 5322 format.
+  */
+  private static formatAddress;
+  /**
+  * Formats email addresses for headers.
+  * @param addresses The email address(es) to format (single or array).
+  * @returns The formatted email addresses string (comma-separated if multiple).
+  */
+  private static formatAddresses;
+  private readonly options;
+  /**
+  * Creates a new DKIM signer.
+  * @param options DKIM signing options.
+  */
+  constructor(options: DkimOptions);
+  /**
+  * Signs an email message with DKIM.
+  * @param email The email options to sign.
+  * @returns The email options with DKIM signature header added.
+  * @throws {Error} When signing fails (e.g., invalid private key).
+  */
+  sign(email: EmailOptions): Promise<EmailOptions>;
+}
+/**
+* Creates a DKIM signer instance.
+* @param options DKIM signing options.
+* @returns A new DkimSigner instance.
+*/
+declare const createDkimSigner: (options: DkimOptions) => DkimSigner;
+/**
+* S/MIME encrypter implementation using PKIjs
+* Note: Requires pkijs and asn1js for S/MIME operations
+* Uses Node.js crypto for all cryptographic operations
+*/
+declare class SmimeEncrypter implements EmailEncrypter {
+  /**
+  * Collects and normalizes all recipients (to, cc, bcc) from email options.
+  * Normalizes each to an array, extracts email addresses, and deduplicates.
+  * @param email The email options containing recipients.
+  * @returns An array of unique email addresses (strings).
+  */
+  private static collectRecipients;
+  /**
+  * Formats an email address for use in email headers.
+  * @param address The email address to format (string or EmailAddress object).
+  * @returns The formatted email address string in RFC 5322 format.
+  */
+  private static formatAddress;
+  /**
+  * Formats email addresses for use in email headers.
+  * @param addresses The email addresses to format (single or array, string or EmailAddress objects).
+  * @returns The formatted email addresses string (comma-separated if multiple).
+  */
+  private static formatAddresses;
+  private readonly options;
+  /**
+  * Creates a new S/MIME encrypter.
+  * @param options S/MIME encryption options.
+  */
+  constructor(options: SmimeEncryptOptions);
+  /**
+  * Encrypts an email message with S/MIME.
+  * @param email The email options to encrypt.
+  * @returns The encrypted email options.
+  * @throws {Error} When encryption fails (e.g., invalid certificate).
+  */
+  encrypt(email: EmailOptions): Promise<EmailOptions>;
+  /**
+  * Builds the email message string from email options.
+  * @param email The email options to build the message from.
+  * @returns The formatted email message as a string.
+  */
+  private buildMessage;
+}
+/**
+* Creates a new S/MIME encrypter instance.
+* @param options The S/MIME encryption options.
+* @returns A new SmimeEncrypter instance ready to encrypt emails.
+*/
+declare const createSmimeEncrypter: (options: SmimeEncryptOptions) => SmimeEncrypter;
+/**
+* S/MIME signer implementation using PKIjs
+* Note: Requires pkijs and asn1js for S/MIME operations
+* Uses Node.js crypto for all cryptographic operations
+*/
+declare class SmimeSigner implements EmailSigner {
+  /**
+  * Formats an email address for use in email headers.
+  * @param address The email address object to format.
+  * @param address.email The email address string.
+  * @param address.name Optional display name for the email address.
+  * @returns The formatted email address string in RFC 5322 format.
+  */
+  private static formatAddress;
+  private readonly options;
+  /**
+  * Creates a new S/MIME signer.
+  * @param options S/MIME signing options.
+  */
+  constructor(options: SmimeSignOptions);
+  /**
+  * Signs an email message with S/MIME.
+  * @param email The email options to sign.
+  * @returns The email options with S/MIME signature.
+  * @throws {Error} When signing fails (e.g., invalid certificate/key).
+  */
+  sign(email: EmailOptions): Promise<EmailOptions>;
+  /**
+  * Builds the email message string from email options.
+  * @param email The email options to build the message from.
+  * @returns The formatted email message as a string.
+  */
+  private buildMessage;
+  /**
+  * Formats email addresses for use in email headers.
+  * @param addresses The email addresses to format (single or array).
+  * @returns The formatted email addresses string (comma-separated if multiple).
+  */
+  private formatAddresses;
+}
+/**
+* Creates a new S/MIME signer instance.
+* @param options The S/MIME signing options.
+* @returns A new SmimeSigner instance ready to sign emails.
+*/
+declare const createSmimeSigner: (options: SmimeSignOptions) => SmimeSigner;
+export { type ArcAlgorithm, type ArcHeaderSet, type ArcSealOptions, type ArcVerifyOptions, type ArcVerifyResult, type DkimOptions, DkimSigner, type EmailEncrypter, type EmailSigner, type SmimeEncryptOptions, SmimeEncrypter, type SmimeSignOptions, SmimeSigner, arcMessageSignatureBase, arcSealBase, createDkimSigner, createSmimeEncrypter, createSmimeSigner, signArc, verifyArc };

package/dist/crypto/index.js

@@ -1 +1 @@
-import{DkimSigner as m,createDkimSigner as i}from"../packem_shared/DkimSigner-pFd4c3fZ.js";import{SmimeEncrypter as S,createSmimeEncrypter as n}from"../packem_shared/SmimeEncrypter-CBevU534.js";import{SmimeSigner as c,createSmimeSigner as p}from"../packem_shared/SmimeSigner-CObA4jzT.js";export{m as DkimSigner,S as SmimeEncrypter,c as SmimeSigner,i as createDkimSigner,n as createSmimeEncrypter,p as createSmimeSigner};
+import{arcMessageSignatureBase as m,arcSealBase as i,signArc as a,verifyArc as t}from"../packem_shared/arcMessageSignatureBase-BY4j0TxM.js";import{DkimSigner as c,createDkimSigner as n}from"../packem_shared/DkimSigner-BuSbnos1.js";import{SmimeEncrypter as g,createSmimeEncrypter as p}from"../packem_shared/SmimeEncrypter-C7usORKF.js";import{SmimeSigner as s,createSmimeSigner as x}from"../packem_shared/SmimeSigner-DgAApLPS.js";export{c as DkimSigner,g as SmimeEncrypter,s as SmimeSigner,m as arcMessageSignatureBase,i as arcSealBase,n as createDkimSigner,p as createSmimeEncrypter,x as createSmimeSigner,a as signArc,t as verifyArc};

package/dist/deliverability/dmarc-report.d.ts

@@ -0,0 +1,95 @@
+/**
+* A DKIM/SPF auth result inside a DMARC aggregate record.
+*/
+interface DmarcAuthResult {
+  domain?: string;
+  result?: string;
+}
+/**
+* One `<record>` row of a DMARC aggregate report.
+*/
+interface DmarcRecordRow {
+  /**
+  * The per-mechanism auth results.
+  */
+  authResults: {
+    dkim: DmarcAuthResult[];
+    spf: DmarcAuthResult[];
+  };
+  /**
+  * Number of messages this row represents.
+  */
+  count: number;
+  /**
+  * The policy disposition applied (`none` / `quarantine` / `reject`).
+  */
+  disposition?: string;
+  /**
+  * The DKIM alignment result (`pass` / `fail`).
+  */
+  dkim?: string;
+  /**
+  * The `From:` header domain.
+  */
+  headerFrom?: string;
+  /**
+  * The source IP that sent the messages.
+  */
+  sourceIp?: string;
+  /**
+  * The SPF alignment result (`pass` / `fail`).
+  */
+  spf?: string;
+}
+/**
+* A parsed DMARC aggregate (RUA) report.
+*/
+interface DmarcAggregateReport {
+  /**
+  * Report window start (`date_range.begin`, unix seconds as a string).
+  */
+  dateRangeBegin?: string;
+  /**
+  * Report window end (`date_range.end`, unix seconds as a string).
+  */
+  dateRangeEnd?: string;
+  /**
+  * The reporter's contact email.
+  */
+  email?: string;
+  /**
+  * The reporting organization.
+  */
+  organizationName?: string;
+  /**
+  * The published policy the report was evaluated against.
+  */
+  policyPublished?: {
+    adkim?: string;
+    aspf?: string;
+    domain?: string;
+    p?: string;
+    pct?: number;
+    sp?: string;
+  };
+  /**
+  * The per-source rows.
+  */
+  records: DmarcRecordRow[];
+  /**
+  * The unique report id.
+  */
+  reportId?: string;
+}
+/**
+* Parses a DMARC aggregate (RUA) report XML document into a structured object.
+*
+* Reports arrive gzipped/zipped — decompress to the XML string first. `fast-xml-parser` is an optional
+* peer dependency (`pnpm add fast-xml-parser`), loaded only via this `./deliverability/dmarc-report`
+* entry point so the rest of the deliverability tooling stays dependency-free.
+* @param xml The DMARC aggregate report XML.
+* @returns The parsed report. See {@link DmarcAggregateReport}.
+* @throws {EmailError} When `fast-xml-parser` is not installed or the XML cannot be parsed.
+*/
+declare const parseDmarcReport: (xml: string) => Promise<DmarcAggregateReport>;
+export { type DmarcAggregateReport, type DmarcAuthResult, type DmarcRecordRow, parseDmarcReport };

package/dist/deliverability/dmarc-report.js

@@ -0,0 +1 @@
+import l from"../packem_shared/EmailError-B-sEf3bp.js";const g=a=>a==null?[]:Array.isArray(a)?a:[a],e=a=>{if(typeof a=="string")return a;if(typeof a=="number"||typeof a=="boolean")return String(a)},c=a=>{const r=e(a);if(r===void 0)return;const s=Number(r);return Number.isNaN(s)?void 0:s},f=a=>g(a).map(r=>({domain:e(r.domain),result:e(r.result)})),h=async a=>{let r;try{({XMLParser:r}=await import("fast-xml-parser"))}catch(t){throw t instanceof Error&&(t.code==="ERR_MODULE_NOT_FOUND"||t.message.includes("Cannot find module")||t.message.includes("Cannot find package"))?new l("deliverability","fast-xml-parser is not installed. Please install it: pnpm add fast-xml-parser",{cause:t}):new l("deliverability",`Failed to load fast-xml-parser: ${t.message}`,{cause:t})}let s;try{s=new r({ignoreAttributes:!0,parseTagValue:!1}).parse(a)}catch(t){throw new l("deliverability",`Failed to parse DMARC report: ${t.message}`,{cause:t})}const n=s.feedback??{},o=n.report_metadata??{},m=o.date_range??{},i=n.policy_published??{},y=g(n.record).map(t=>{const d=t.row??{},p=d.policy_evaluated??{},b=t.identifiers??{},u=t.auth_results??{};return{authResults:{dkim:f(u.dkim),spf:f(u.spf)},count:c(d.count)??0,disposition:e(p.disposition),dkim:e(p.dkim),headerFrom:e(b.header_from),sourceIp:e(d.source_ip),spf:e(p.spf)}});return{dateRangeBegin:e(m.begin),dateRangeEnd:e(m.end),email:e(o.email),organizationName:e(o.org_name),policyPublished:{adkim:e(i.adkim),aspf:e(i.aspf),domain:e(i.domain),p:e(i.p),pct:c(i.pct),sp:e(i.sp)},records:y,reportId:e(o.report_id)}};export{h as parseDmarcReport};