...
", +}); -A single Mail `mail@example.de` with a name `NAME` can be encoded in the -following ways: +await client.close(); +``` -1. `"name@example.de"` -2. `"Hello World
", + internalTag: "newsletter", + priority: "low", }); ``` -## Pool, Worker -> This is unstable API may change! This requires deno to run in unstable mode. +## Other exports -Adds 2 new classes `SMTPWorker` and `SMTPWorkerPool` (for constructor options see code for now). This creates a SMTP client (or multiple) that get automaticly killed if the connection is not used for around 60s. +We export our implementation of an quotedPrintable encoder. There might be some +use cases where you need it. The api of the function is considered stable! -## TLS issues -When getting TLS errors make shure: -1. you use the correct port (mostly 25, 587, 465) -2. the server supports STARTTLS when using `client.connect` -3. the server supports TLS when using `client.connectTLS` -4. Use the command `openssl s_client -debug -starttls smtp -crlf -connect your-host.de:587` or `openssl s_client -debug -crlf -connect your-host.de:587` and get the used cipher this should be a cipher with "forward secrecy". Check the status of the cipher on https://ciphersuite.info/cs/ . If the cipher is not STRONG this is an issue with your mail provider so you have to contact them to fix it. -5. Feel free to create issues if you are ok with that share the port and host so a proper debug can be done. -6. We can only support TLS where Deno supports it and Deno uses rustls wich explicitly not implemented some "weak" ciphers. +## Stable api +All api exported by `/mod.ts` is considered stable. But as the `pool` need the +`--unstable` flag by Deno this has to be considered unstable. But we don't +expect any breaking changes there - but if deno changes sytax etc. a new deno +release can break it! -### Non SpecCompliant SMTP-Server -There are some SMTP-Server that don't follow the spec to 100%. This can result in unexpected errors in denomailer. If this happens (for example in https://github.com/EC-Nordbund/denomailer/blob/03a66a6f9a4b5f349ea35856f5903fb45fd0cc5f/smtp.ts#L376 the server sends a 250) please create an issue. We will try and do the following: +Changes to them will only be made if a new major is released. -1. Check if it is not an error in denomailer -2. Try to fix it at the SMTP-Server side (create an issue if the server is an opensource project etc.) -3. We will add a ***temporary*** workaround by changing denomailer. This will include log messages telling the developer (if the workaround is used) that denomailer used the workaround wich can be removed at any time. +## Contribute +Feel free to contribute by: +1. creating issues for bugs and feature requests (note that you have to use the + bug template to get support) +2. contribute code but keep in mind + - for small changes you can just create a PR + - for bigger changes please create an issue before! This will help to reduce + time creating PR that are not merged. + - if you fix a bug please add a test that fails before your fix +3. contribute tests, fix typos, ... +## TLS issues + +When getting TLS errors make sure: + +1. you use the correct port (mostly 25, 587, 465) +2. the server supports STARTTLS when using `connection.tls = false` +3. the server supports TLS when using `connection.tls = true` +4. Use the command + `openssl s_client -debug -starttls smtp -crlf -connect your-host.de:587` or + `openssl s_client -debug -crlf -connect your-host.de:587` and get the used + cipher this should be a cipher with "forward secrecy". Check the status of + the cipher on https://ciphersuite.info/cs/ . If the cipher is not STRONG this + is an issue with your mail provider so you have to contact them to fix it. +5. Feel free to create issues if you are ok with that share the port and host so + a proper debug can be done. +6. We can only support TLS where Deno supports it and Deno uses rustls wich + explicitly not implemented some "weak" ciphers. + +## Non SpecCompliant SMTP-Server + +There are some SMTP-Server that don't follow the spec to 100%. This can result +in unexpected errors in denomailer. If this happens (for example in +https://github.com/EC-Nordbund/denomailer/blob/03a66a6f9a4b5f349ea35856f5903fb45fd0cc5f/smtp.ts#L376 +the server sends a 250) please create an issue. We will try and do the +following: + +1. Check if it is not an error in denomailer +2. Try to fix it at the SMTP-Server side (create an issue if the server is an + opensource project etc.) +3. We will add a _**temporary**_ workaround by changing denomailer. This will + include log messages telling the developer (if the workaround is used) that + denomailer used the workaround wich can be removed at any time. + +## Breaking changes + +### v0.x -> v1.0 + +1. Import `SMTPClient` not `SmtpClient` +2. Change the constructor options (include the options used with + `client.connect` or `client.connectTLS` (add `tls = true` in the second + case)) +3. Remove `client.connect` and `client.connectTLS` calls +4. filterMail option was removed in favor of new preprocessor option +5. The `client.send` method did not have any breaking changes. +6. Some internal fields where removed from `SMTPClient` only use `send` and + `close`! But in 99% of project these where not used diff --git a/SECURITY.md b/SECURITY.md index 60bcebc..1a96881 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,12 +6,17 @@ We provide security updates currently for these version. | Version | Supported | | ------- | ------------------ | -| > 0.10.x | :white_check_mark: | +| 1.x | :white_check_mark: | +| 0.x | :white_check_mark: | -We will provide security updates after 1.0 only for the latest version of that major. -We will deprecate major versions so you should always upgrade! Note that major versions will contains breaking changes so we will add security updates for at least 1 older major so you have time to upgrade. But note that we will deprecate these versions too! +We will provide security updates after 1.0 only for the latest version of that +major. We will deprecate major versions so you should always upgrade! Note that +major versions will contains breaking changes so we will add security updates +for at least 1 older major so you have time to upgrade. But note that we will +deprecate these versions too! ## Reporting a Vulnerability -If you find a Vulnerability or a potential Vulnerability please send a mail to `app@ec-nordbund.de` and explain the problem. -This don't has to be a full exploit! +If you find a Vulnerability or a potential Vulnerability please send a mail to +`app@ec-nordbund.de` and explain the problem. This don't has to be a full +exploit! diff --git a/client/basic/client.ts b/client/basic/client.ts new file mode 100644 index 0000000..fada1d0 --- /dev/null +++ b/client/basic/client.ts @@ -0,0 +1,379 @@ +import type { ResolvedSendConfig } from "../../config/mail/mod.ts"; +import { ResolvedClientOptions } from "../../config/client.ts"; +import { SMTPConnection } from "./connection.ts"; + +const CommandCode = { + READY: 220, + AUTHO_SUCCESS: 235, + OK: 250, + BEGIN_DATA: 354, + FAIL: 554, +}; + +class QUE { + running = false; + #que: (() => void)[] = []; + idle: Promise...
", + * }); + * + * await client.close(); + * ``` + */ +export class SMTPHandler { + #internalClient: SMTPWorker | SMTPWorkerPool | SMTPClient; + #clientConfig: ResolvedClientOptions; + + /** + * create a new SMTPClient + * + * ```ts + * const client = new SMTPClient({ + * connection: { + * hostname: "smtp.example.com", + * port: 465, + * tls: true, + * auth: { + * username: "example", + * password: "password", + * }, + * }, + * pool: { + * size: 2, + * timeout: 60000 + * }, + * client: { + * warning: 'log', + * preprocessors: [filterBurnerMails] + * }, + * debug: { + * log: false, + * allowUnsecure: false, + * encodeLB: false, + * noStartTLS: false + * } + * }); + * + * ``` + * + * @param config client config + */ + constructor(config: ClientOptions) { + const resolvedConfig = resolveClientOptions(config); + + resolvedConfig.client.preprocessors.push(validateConfig); + + this.#clientConfig = resolvedConfig; + + if (resolvedConfig.debug.log) { + console.log("used resolved config"); + console.log(".debug"); + console.table(resolvedConfig.debug); + console.log(".connection"); + console.table({ + ...resolvedConfig.connection, + ...resolvedConfig.connection.auth + ? { auth: JSON.stringify(resolvedConfig.connection.auth) } + : {}, + }); + console.log(".pool"); + console.table(resolvedConfig.pool); + } + + const Client = resolvedConfig.pool + ? (resolvedConfig.pool.size > 1 ? SMTPWorkerPool : SMTPWorker) + : SMTPClient; + + this.#internalClient = new Client(resolvedConfig); + } + + /** + * Sends a E-Mail with the correspondig config. + * ```ts + * client.send({ + * to: 'abc@example.com', + * cc: [ + * 'abc@example.com', + * 'abcHello World
', + * internalTag: 'newsletter', + * priority: 'low' + * }) + * ``` + * @param config Email config + * @returns nothing (for now as this might change in the future!) + */ + send(config: SendConfig): PromiseBuild succeed!
-${new Date()}
- - - `, -}); - -await client.close(); diff --git a/test/e2e/basic.test.ts b/test/e2e/basic.test.ts new file mode 100644 index 0000000..19e9787 --- /dev/null +++ b/test/e2e/basic.test.ts @@ -0,0 +1,139 @@ +import { clearEmails, getEmails } from "../fake-smtp.ts"; +import { assertEquals } from "https://deno.land/std@0.136.0/testing/asserts.ts"; +import { SMTPClient } from "../../mod.ts"; + +function wait(to = 10000) { + return new Promise((res) => setTimeout(res, to)); +} + +Deno.test("test simplest mail", async () => { + await clearEmails(); + + const client = new SMTPClient({ + debug: { + allowUnsecure: true, + // log: true, + noStartTLS: true, + }, + connection: { + hostname: "localhost", + port: 1025, + tls: false, + }, + }); + + await client.send({ + from: "me@denomailer.example", + to: "you@denomailer.example", + subject: "testing", + content: "test", + }); + + const mails = await getEmails(); + assertEquals(mails.length, 1); + await client.close(); +}); + +Deno.test("test simplest mail with pool", async () => { + await clearEmails(); + + const client = new SMTPClient({ + debug: { + allowUnsecure: true, + // log: true, + noStartTLS: true, + }, + connection: { + hostname: "localhost", + port: 1025, + tls: false, + }, + pool: true, + }); + + await client.send({ + from: "me@denomailer.example", + to: "you@denomailer.example", + subject: "testing", + content: "test", + }); + + await wait(2000); + + const mails = await getEmails(); + assertEquals(mails.length, 1); + await client.close(); +}); + +Deno.test("test subject", async () => { + await clearEmails(); + + const client = new SMTPClient({ + debug: { + allowUnsecure: true, + // log: true, + noStartTLS: true, + }, + connection: { + hostname: "localhost", + port: 1025, + tls: false, + }, + }); + + const subject = Math.random().toString(); + + await client.send({ + from: "me@denomailer.example", + to: "you@denomailer.example", + subject, + content: "test", + }); + + await wait(2000); + + const mails = await getEmails(); + assertEquals(mails.length, 1); + assertEquals(mails[0].subject, subject); + await client.close(); +}); + +Deno.test("test html", async () => { + await clearEmails(); + + const client = new SMTPClient({ + debug: { + allowUnsecure: true, + // log: true, + noStartTLS: true, + }, + connection: { + hostname: "localhost", + port: 1025, + tls: false, + }, + }); + + const testSet = [ + "asdjhhj
", + "kljfskjlsfs", + "
dkjasjd",
+ // TODO add some long testsets with linebreaks etc.
+ ];
+
+ for (const html of testSet) {
+ await clearEmails();
+ await client.send({
+ from: "me@denomailer.example",
+ to: "you@denomailer.example",
+ subject: "testing",
+ content: "test",
+ html,
+ });
+
+ const mails = await getEmails();
+ assertEquals(mails.length, 1);
+ assertEquals(mails[0].html.toString().trim(), html);
+ }
+ await client.close();
+});
diff --git a/test/fake-smtp.ts b/test/fake-smtp.ts
new file mode 100644
index 0000000..2b83ac2
--- /dev/null
+++ b/test/fake-smtp.ts
@@ -0,0 +1,30 @@
+interface MailAdresses {
+ value: { address: string; name: string }[];
+ html: string;
+ text: string;
+}
+
+export function getEmails(): Promise<
+ {
+ // deno-lint-ignore no-explicit-any
+ attachments: any[];
+ headerLines: { key: string; line: string }[];
+ text: string;
+ textAsHtml: string;
+ subject: string;
+ date: string;
+ to: MailAdresses;
+ from: MailAdresses;
+ html: false | string;
+ }[]
+> {
+ return fetch("http://localhost:1080/api/emails", {
+ method: "get",
+ }).then((v) => v.json());
+}
+
+export function clearEmails() {
+ return fetch("http://localhost:1080/api/emails", { method: "delete" }).then(
+ (v) => v.arrayBuffer(),
+ );
+}
diff --git a/test_deps.ts b/test_deps.ts
deleted file mode 100644
index 08a217d..0000000
--- a/test_deps.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { config as configEnv } from "https://deno.land/std@0.130.0/dotenv/mod.ts";
diff --git a/tests/test_parse.ts b/tests/test_parse.ts
deleted file mode 100644
index 42cc1ff..0000000
--- a/tests/test_parse.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { assertEquals } from "https://deno.land/std@0.130.0/testing/asserts.ts";
-
-function parseAddress(email: string): [string, string] {
- const m = email.match(/(.*)\s<(.*)>/);
- return m?.length === 3 ? [`<${m[2]}>`, email] : [`<${email}>`, `<${email}>`];
-}
-
-Deno.test("parse adresses (MAIL FROM, RCPT TO and DATA commands)", () => {
- const [e1, e2] = parseAddress("Deno Land