@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/esm/comms/email/mime.js

@@ -0,0 +1,218 @@
+/**
+ * @module integrations/comms/email/mime
+ * @summary RFC 5322/MIME message building and address handling for the Email service.
+ * @description Builds a complete raw MIME message from an
+ * {@link EmailMessageInput}: UTF-8 headers are RFC 2047 base64-word encoded
+ * ({@link encodeHeader}), recipient lists are comma-split and trimmed
+ * ({@link parseAddressList}), and the body becomes a
+ * `text/plain`/`text/html` `multipart/alternative` (when both are present),
+ * a single part otherwise — wrapped in `multipart/mixed` with base64
+ * attachments when any are supplied. Boundary markers and the `Message-ID`
+ * carry a random UUID per message.
+ *
+ * Every address, attachment filename, and content type is validated against
+ * conservative allowlists ({@link assertEmailAddress} and friends) before it is
+ * written into a header, so workflow input can never inject MIME headers or
+ * SMTP commands. All validation and structural failures (missing recipient,
+ * forbidden control characters, non-mailbox addresses, unsafe filenames or
+ * content types) throw decaf `BadRequestError`s.
+ */
+import { randomUUID } from "node:crypto";
+import { BadRequestError } from "@decaf-ts/db-decorators";
+const ASCII_HEADER = /^[\x20-\x7E]*$/;
+/**
+ * Characters that must never appear in an address, attachment filename, or
+ * content type: CR/LF (header and SMTP-command injection), NUL, and any other
+ * C0/C1 control character.
+ */
+// eslint-disable-next-line no-control-regex -- matching control characters is the purpose of this allowlist
+const FORBIDDEN_CONTROL = /[\x00-\x1F\x7F-\x9F]/;
+/**
+ * Conservative mailbox allowlist: a dot-atom local part followed by a
+ * dot-separated domain. Display names are deliberately not accepted because
+ * the envelope (`MAIL FROM`/`RCPT TO`) and the MIME headers share the same
+ * validated value.
+ */
+const EMAIL_ADDRESS = /^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/;
+/**
+ * Allowlisted MIME content type: `type/subtype` plus optional
+ * `; parameter=value` pairs whose values are tokens or quoted strings without
+ * control characters, quotes, or backslashes.
+ */
+const CONTENT_TYPE = /^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+(?:\s*;\s*[A-Za-z0-9-]+=(?:"[^"\\\r\n]*"|[A-Za-z0-9!#$&^_.+-]+))*$/;
+/**
+ * Rejects any value carrying CR/LF, NUL, or another control character.
+ *
+ * @param value - Value about to be written into a header, SMTP command, or MIME part.
+ * @param field - Human-readable field name used in the error message.
+ * @throws {BadRequestError} when the value contains a forbidden control character.
+ */
+function rejectControlCharacters(value, field) {
+    if (FORBIDDEN_CONTROL.test(value)) {
+        throw new BadRequestError(`Email ${field} contains a forbidden control character`);
+    }
+}
+/**
+ * Validates a mailbox address against the allowlist and returns it trimmed.
+ *
+ * @param value - Candidate address.
+ * @param field - Human-readable field name used in the error message.
+ * @returns The trimmed, validated mailbox address.
+ * @throws {BadRequestError} when the address contains control characters or is not a bare mailbox.
+ */
+export function assertEmailAddress(value, field = "address") {
+    rejectControlCharacters(value, field);
+    const address = value.trim();
+    if (!EMAIL_ADDRESS.test(address)) {
+        throw new BadRequestError(`Email ${field} is not a valid mailbox address`);
+    }
+    return address;
+}
+/**
+ * Validates an attachment filename for safe inclusion in a quoted MIME header.
+ *
+ * @param value - Candidate filename.
+ * @throws {BadRequestError} when the filename carries control characters, a quote, or a backslash.
+ */
+function assertAttachmentFilename(value) {
+    rejectControlCharacters(value, "attachment filename");
+    if (/["\\]/.test(value)) {
+        throw new BadRequestError("Email attachment filename contains a forbidden character");
+    }
+}
+/**
+ * Validates an attachment content type against the MIME allowlist.
+ *
+ * @param value - Declared content type.
+ * @throws {BadRequestError} when the value is not an allowlisted `type/subtype` with safe parameters.
+ */
+function assertContentType(value) {
+    rejectControlCharacters(value, "attachment content type");
+    if (!CONTENT_TYPE.test(value.trim())) {
+        throw new BadRequestError("Email attachment content type is not an allowed MIME type");
+    }
+}
+/**
+ * @description Encodes a MIME header value safely
+ * @summary Pure-ASCII values pass through; anything else becomes an RFC 2047
+ * `=?UTF-8?B?...?=` encoded word.
+ * @param value - Raw header value
+ * @returns The header value safe for raw message transport
+ */
+export function encodeHeader(value) {
+    if (ASCII_HEADER.test(value))
+        return value;
+    return `=?UTF-8?B?${Buffer.from(value, "utf8").toString("base64")}?=`;
+}
+/**
+ * @description Normalizes a recipient input into an allowlisted address list
+ * @summary Splits comma-separated strings, trims entries, drops empties, and
+ * validates every remaining entry as a bare mailbox address. Values carrying
+ * CR/LF, NUL, or other control characters are rejected outright so workflow
+ * input can never inject MIME headers or SMTP envelope commands.
+ * @param value - Single address, comma-separated string, array, or `undefined`
+ * @returns The trimmed, validated list of addresses
+ * @throws {BadRequestError} when an entry is not a valid mailbox address
+ */
+export function parseAddressList(value) {
+    if (!value)
+        return [];
+    const values = Array.isArray(value) ? value : [value];
+    return values
+        .flatMap((entry) => entry.split(","))
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0)
+        .map((entry) => assertEmailAddress(entry, "recipient"));
+}
+function base64Lines(value) {
+    return Buffer.from(value, "utf8")
+        .toString("base64")
+        .replace(/(.{76})/g, "$1\r\n");
+}
+function textPart(contentType, value) {
+    return `Content-Type: ${contentType}; charset=utf-8\r\nContent-Transfer-Encoding: base64\r\n\r\n${base64Lines(value)}`;
+}
+function bodyEntity(input) {
+    if (input.text !== undefined && input.html !== undefined) {
+        const boundary = `alt-${randomUUID()}`;
+        return [
+            `Content-Type: multipart/alternative; boundary="${boundary}"`,
+            "",
+            `--${boundary}`,
+            textPart("text/plain", input.text),
+            `--${boundary}`,
+            textPart("text/html", input.html),
+            `--${boundary}--`,
+        ].join("\r\n");
+    }
+    if (input.html !== undefined) {
+        return textPart("text/html", input.html);
+    }
+    return textPart("text/plain", input.text ?? "");
+}
+function attachmentPart(attachment) {
+    const content = attachment.encoding === "utf8"
+        ? base64Lines(attachment.content)
+        : attachment.content.replace(/\r?\n/g, "");
+    const contentType = attachment.contentType ?? "application/octet-stream";
+    assertAttachmentFilename(attachment.filename);
+    assertContentType(contentType);
+    return [
+        `Content-Type: ${contentType}; name="${encodeHeader(attachment.filename)}"`,
+        "Content-Transfer-Encoding: base64",
+        `Content-Disposition: attachment; filename="${encodeHeader(attachment.filename)}"`,
+        "",
+        content,
+    ].join("\r\n");
+}
+function entity(input) {
+    const attachments = input.attachments ?? [];
+    if (attachments.length === 0)
+        return bodyEntity(input);
+    const boundary = `mix-${randomUUID()}`;
+    const parts = [bodyEntity(input), ...attachments.map(attachmentPart)];
+    return `Content-Type: multipart/mixed; boundary="${boundary}"\r\n\r\n${parts
+        .map((part) => `--${boundary}\r\n${part}`)
+        .join("\r\n")}\r\n--${boundary}--`;
+}
+/**
+ * @description Builds the complete raw MIME message
+ * @summary Generates the `Message-ID`, resolves recipients (throwing when
+ * none remain), emits the standard headers, and assembles the body entity
+ * (alternative text/HTML parts, plus attachments when present).
+ * @param input - Message input
+ * @returns The built message with raw text, sender, recipients, and `Message-ID`
+ * @throws {BadRequestError} when the message has no recipient or any address,
+ *   attachment filename, or content type fails validation
+ */
+export function buildEmail(input) {
+    const messageId = `<${randomUUID()}@as-graph>`;
+    const from = assertEmailAddress(input.from, "sender");
+    const to = parseAddressList(input.to);
+    const cc = parseAddressList(input.cc);
+    const bcc = parseAddressList(input.bcc);
+    const recipients = [...to, ...cc, ...bcc];
+    if (recipients.length === 0) {
+        throw new BadRequestError("Email message requires at least one recipient");
+    }
+    const replyTo = input.replyTo
+        ? assertEmailAddress(input.replyTo, "reply-to")
+        : undefined;
+    const headers = [
+        `From: ${from}`,
+        `To: ${to.join(", ")}`,
+        ...(cc.length ? [`Cc: ${cc.join(", ")}`] : []),
+        `Subject: ${encodeHeader(input.subject)}`,
+        ...(replyTo ? [`Reply-To: ${replyTo}`] : []),
+        `Date: ${new Date().toUTCString()}`,
+        `Message-ID: ${messageId}`,
+        "MIME-Version: 1.0",
+    ].join("\r\n");
+    return {
+        raw: `${headers}\r\n${entity(input)}`,
+        from,
+        recipients,
+        messageId,
+    };
+}
+//# sourceMappingURL=mime.js.map

package/lib/esm/comms/email/mime.js.map

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

package/lib/esm/comms/email/smtp.js

@@ -0,0 +1,166 @@
+/**
+ * @module integrations/comms/email/smtp
+ * @summary SMTP client used by the Email service for direct SMTP delivery.
+ * @description Delegates the SMTP protocol to the optional `nodemailer`
+ * library (the same library n8n uses) instead of hand-rolling the wire
+ * protocol: the transport performs EHLO, STARTTLS/implicit TLS, AUTH LOGIN,
+ * and the `MAIL FROM`/`RCPT TO`/`DATA` transaction for a pre-built raw MIME
+ * message. The public {@link SmtpClient} surface is unchanged. Envelope
+ * addresses are validated through {@link assertEmailAddress} (decaf
+ * `BadRequestError`s) before they reach any SMTP command, and credentials are
+ * never sent over a plaintext session unless `SmtpConfig.allowPlaintextAuth`
+ * opts in.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+import { assertEmailAddress } from "./mime.js";
+/**
+ * @description SMTP client for raw MIME delivery
+ * @summary Connects and authenticates through a nodemailer SMTP transport
+ * (implicit TLS on `secure`, STARTTLS otherwise), then delivers a pre-built
+ * message with the envelope sender/recipients and the raw RFC 5322 source.
+ * Credentials are never sent over a plaintext session unless
+ * `allowPlaintextAuth` is set, and every envelope address is validated before
+ * it reaches the transport.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/smtp
+ * @example
+ * ```ts
+ * import { SmtpClient, buildEmail } from "@decaf-ts/integrations/comms/email";
+ *
+ * const client = new SmtpClient({
+ *   host: "smtp.example.com",
+ *   port: 587,
+ *   username: "noreply@example.com",
+ *   password: process.env.SMTP_PASSWORD,
+ * });
+ * await client.connect();
+ * const mail = buildEmail({
+ *   from: "noreply@example.com",
+ *   to: ["ops@example.com"],
+ *   subject: "Nightly report",
+ *   text: "All systems nominal.",
+ * });
+ * await client.send(mail.from, mail.recipients, mail.raw);
+ * await client.close();
+ * ```
+ */
+export class SmtpClient {
+    /**
+     * @description Creates an SMTP client
+     * @summary Stores the config; the nodemailer transport is only created and
+     * verified by {@link SmtpClient.connect}.
+     * @param config - Server address, optional credentials, and TLS/timeout options
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    transportOptions() {
+        const secure = this.config.secure ?? false;
+        const hasCredentials = Boolean(this.config.username && this.config.password);
+        const timeout = this.config.timeout ?? 30000;
+        return {
+            host: this.config.host,
+            port: this.config.port ?? (secure ? 465 : 587),
+            secure,
+            name: this.config.clientHostname ?? "as-graph",
+            requireTLS: !secure && hasCredentials && !this.config.allowPlaintextAuth,
+            auth: hasCredentials
+                ? {
+                    user: this.config.username,
+                    pass: this.config.password,
+                    method: "LOGIN",
+                }
+                : undefined,
+            tls: this.config.allowUnauthorizedCerts
+                ? { rejectUnauthorized: false }
+                : undefined,
+            connectionTimeout: timeout,
+            greetingTimeout: timeout,
+            socketTimeout: timeout,
+        };
+    }
+    transportError(prefix, error) {
+        if (error instanceof InternalError)
+            return error;
+        return new InternalError(`${prefix}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    /**
+     * @description Opens the SMTP session
+     * @summary Lazily loads the optional `nodemailer` peer, builds the SMTP
+     * transport for the configured host/credentials, and verifies it
+     * (`EHLO` + TLS upgrade + `AUTH LOGIN` when credentials are configured).
+     * Authentication fails closed: with credentials configured and no encrypted
+     * session, the transport requires STARTTLS and verification fails unless
+     * `allowPlaintextAuth` was set on the config.
+     * @throws {InternalError} when `nodemailer` is not installed, or on
+     * connection, TLS, or auth failures
+     */
+    async connect() {
+        if (this.transporter)
+            return;
+        const moduleName = "nodemailer";
+        let module;
+        try {
+            module = (await import(moduleName));
+        }
+        catch {
+            throw new InternalError("SMTP delivery requires the optional 'nodemailer' package; install it to use this surface");
+        }
+        if (typeof module.createTransport !== "function") {
+            throw new InternalError("The optional 'nodemailer' package did not export createTransport");
+        }
+        const transporter = module.createTransport(this.transportOptions(), {
+            disableFileAccess: true,
+            disableUrlAccess: true,
+        });
+        try {
+            await transporter.verify();
+        }
+        catch (error) {
+            transporter.close();
+            throw this.transportError("SMTP connection failed", error);
+        }
+        this.transporter = transporter;
+    }
+    /**
+     * @description Delivers a raw message over the established session
+     * @summary Validates the envelope, then hands the sender, recipients, and
+     * raw RFC 5322 source to nodemailer's `sendMail` (the transport performs
+     * queueing, dot-stuffing, and CRLF normalization).
+     * @param from - Envelope sender address
+     * @param recipients - Envelope recipient addresses
+     * @param raw - Raw RFC 5322 message text
+     * @throws {InternalError} when not connected or the server rejects delivery
+     * @throws {BadRequestError} when the envelope sender or a recipient is not an allowlisted mailbox
+     */
+    async send(from, recipients, raw) {
+        if (!this.transporter) {
+            throw new InternalError("SMTP client is not connected");
+        }
+        const sender = assertEmailAddress(from, "envelope sender");
+        const envelopes = recipients.map((recipient) => assertEmailAddress(recipient, "envelope recipient"));
+        const message = {
+            envelope: { from: sender, to: envelopes },
+            raw,
+        };
+        try {
+            await this.transporter.sendMail(message);
+        }
+        catch (error) {
+            throw this.transportError("SMTP delivery failed", error);
+        }
+    }
+    /**
+     * @description Closes the session gracefully
+     * @summary Closes the nodemailer transport, ignoring shutdown failures.
+     */
+    async close() {
+        try {
+            this.transporter?.close();
+        }
+        finally {
+            this.transporter = undefined;
+        }
+    }
+}
+//# sourceMappingURL=smtp.js.map

package/lib/esm/comms/email/smtp.js.map

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

package/lib/esm/comms/environment.js

@@ -0,0 +1,59 @@
+import { LoggedEnvironment } from "@decaf-ts/logging";
+/**
+ * @description Accumulated comms environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `CommsEnvironmentShape` contract. Comms services read their provider slice
+ * (e.g. `CommsEnvironment.comms.slack`) inside `configFromEnvironment()` and
+ * translate it into an `HttpApiServiceConfig`-derived config. Credentials come
+ * from environment variables; for as-graph node usage those are provided as
+ * `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { SlackService } from "@decaf-ts/integrations/comms/slack";
+ *
+ * // with comms.slack.token / comms.slack.baseUrl configured in the environment
+ * const slack = new SlackService();
+ * await slack.initialize();
+ * ```
+ * @constant {LoggedEnvironment} CommsEnvironment
+ * @memberOf module:integrations/comms/environment
+ */
+export const CommsEnvironment = LoggedEnvironment.accumulate({
+    comms: {
+        slack: {
+            token: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        telegram: {
+            token: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        teams: {
+            token: "",
+            webhookUrl: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        email: {
+            provider: "",
+            host: "",
+            port: undefined,
+            secure: undefined,
+            username: "",
+            password: "",
+            from: "",
+            token: "",
+            graphBaseUrl: "",
+            timeout: undefined,
+        },
+        gmail: {
+            token: "",
+            userId: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+    },
+});
+//# sourceMappingURL=environment.js.map

package/lib/esm/comms/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../../src/comms/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AA+DtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,CAAC,UAAU,CAAC;IAC3D,KAAK,EAAE;QACL,KAAK,EAAE;YACL,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;QACD,QAAQ,EAAE;YACR,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;QACD,KAAK,EAAE;YACL,KAAK,EAAE,EAAE;YACT,UAAU,EAAE,EAAE;YACd,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;QACD,KAAK,EAAE;YACL,QAAQ,EAAE,EAAE;YACZ,IAAI,EAAE,EAAE;YACR,IAAI,EAAE,SAA8B;YACpC,MAAM,EAAE,SAA+B;YACvC,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,EAAE;YACZ,IAAI,EAAE,EAAE;YACR,KAAK,EAAE,EAAE;YACT,YAAY,EAAE,EAAE;YAChB,OAAO,EAAE,SAA8B;SACxC;QACD,KAAK,EAAE;YACL,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAA8B;SACxC;KACF;CACuB,CAAC,CAAC"}