diff --git a/smtp-server/index.d.ts b/smtp-server/index.d.ts new file mode 100644 index 0000000000..09d11b5477 --- /dev/null +++ b/smtp-server/index.d.ts @@ -0,0 +1,382 @@ +// Type definitions for smtp-server v1.15.0 +// Project: https://github.com/andris9/smtp-server +// Definitions by: markisme +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +export class SMTPServer { + constructor(options: SMTPServerOptions); + close(callback: (err?: Error) => any): any; + listen(...args: any[]): void; + onAuth(auth: Authentication, session: Session, callback: any): any; + onClose(callback: (err?: Error) => any): any; + onConnect(session: Session, callback: (err?: Error) => any): any; + onData(stream: any, session: Session, callback: (err?: Error) => any): any; + onMailFrom(address: Address, session: Session, callback: (err?: Error) => any): any; + onRcptTo(address: Address, session: Session, callback: (err?: Error) => any): any; +} + +export interface SMTPServerOptions { + /** + * if true, the connection will use TLS. The default is false. + * If the server doesn't start in TLS mode, + * it is still possible to upgrade clear text socket to + * TLS socket with the STARTTLS command (unless you disable support for it). + * If secure is true, additional tls options for tls. + * createServer can be added directly onto this options object. + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + secure?: boolean; + key?: any; + cert?: any; + ca?: any; + /** + * optional hostname of the server, + * used for identifying to the client (defaults to os.hostname()) + * + * @type {string} + * @memberOf SMTPServerOptions + */ + name?: string; + /** + * optional greeting message. + * This message is appended to the default ESMTP response. + * + * @type {string} + * @memberOf SMTPServerOptions + */ + banner?: string; + /** + * optional maximum allowed message size in bytes, + * see details:https://github.com/andris9/smtp-server#using-size-extension + * + * @type {number} + * @memberOf SMTPServerOptions + */ + size?: number; + /** + * optional array of allowed authentication methods, defaults to ['PLAIN', 'LOGIN']. + * Only the methods listed in this array are allowed, + * so if you set it to ['XOAUTH2'] then PLAIN and LOGIN are not available. + * Use ['PLAIN', 'LOGIN', 'XOAUTH2'] to allow all three. + * Authentication is only allowed in secure mode + * (either the server is started with secure: true option or STARTTLS command is used) + * + * @type {string[]} + * @memberOf SMTPServerOptions + */ + authMethods?: string[]; + /** + * allow authentication, but do not require it + * + * @type {*} + * @memberOf SMTPServerOptions + */ + authOptional?: any; + /** + * optional array of disabled commands (see all supported commands here). + * For example if you want to disable authentication, + * use ['AUTH'] as this value. + * If you want to allow authentication in clear text, set it to ['STARTTLS']. + * + * @type {*} + * @memberOf SMTPServerOptions + */ + disabledCommands?: string[]; + /** + * optional boolean, if set to true then allow using STARTTLS + * but do not advertise or require it. It only makes sense + * when creating integration test servers for testing the scenario + * where you want to try STARTTLS even when it is not advertised + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + hideSTARTTLS?: boolean; + /** + * optional boolean, if set to true then does not show PIPELINING in feature list + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + hidePIPELINING?: boolean; + /** + * optional boolean, if set to true then does not show 8BITMIME in features list + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + hide8BITMIME?: boolean; + /** + * optional boolean, if set to true then does not show SMTPUTF8 in features list + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + hideSMTPUTF8?: boolean; + /** + * optional boolean, if set to true allows authentication even if connection is not secured first + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + allowInsecureAuth?: boolean; + /** + * optional boolean, if set to true then does not try to reverse resolve client hostname + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + disableReverseLookup?: boolean; + /** + * optional Map or an object of TLS options for SNI where servername is the key. Overrided by SNICallback. + * + * @type {Object} + * @memberOf SMTPServerOptions + */ + sniOptions?: Object; + /** + * optional bunyan compatible logger instance. + * If set to true then logs to console. + * If value is not set or is false then nothing is logged + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + logger?: boolean; + /** + * sets the maximum number of concurrently connected clients, defaults to Infinity + * + * @type {number} + * @memberOf SMTPServerOptions + */ + maxClients?: number;//defaults to Infinity + /** + * boolean, if set to true expects to be behind a proxy that emits a + * PROXY header{http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt} (version 1 only) + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + useProxy?: boolean; + /** + * boolean, if set to true, enables usage of + * XCLIENT{http://www.postfix.org/XCLIENT_README.html} extension to override connection properties. + * See session.xClient (Map object) for the details provided by the client + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + useXClient?: boolean; + /** + * boolean, if set to true, enables usage of XFORWARD{http://www.postfix.org/XFORWARD_README.html} extension. + * See session.xForward (Map object) for the details provided by the client + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + useXForward?: boolean; + /** + * boolean, if set to true use LMTP protocol instead of SMTP + * + * @type {boolean} + * @memberOf SMTPServerOptions + */ + lmtp?: boolean; + /** + * How many milliseconds of inactivity to allow before disconnecting the client (defaults to 1 minute) + * + * @type {number} + * @memberOf SMTPServerOptions + */ + socketTimeout?: number;//millisceonds + /** + * How many millisceonds to wait before disconnecting pending + * connections once server.close() has been called (defaults to 30 seconds) + * + * @type {number} + * @memberOf SMTPServerOptions + */ + closeTimeout?: number;//millisceonds + /** + * The callback to handle authentications (see details https://github.com/andris9/smtp-server#handling-authentication) + * + * + * @memberOf SMTPServerOptions + */ + onAuth?: (auth: Authentication, session: Session, callback: (err?: Error, response?: AuthenticationResponse) => any) => any; + /** + * The callback to handle the client connection. (see details https://github.com/andris9/smtp-server#validating-client-connection) + * + * + * @memberOf SMTPServerOptions + */ + onConnect?: (session: Session, callback: (err?: Error) => any) => any; + /** + * the callback to validate MAIL FROM commands (see details https://github.com/andris9/smtp-server#validating-sender-addresses) + * + * + * @memberOf SMTPServerOptions + */ + onMailFrom?: (address: Address, session: Session, callback: (err?: Error) => any) => any; + /** + * The callback to validate RCPT TO commands (see details https://github.com/andris9/smtp-server#validating-recipient-addresses) + * + * + * @memberOf SMTPServerOptions + */ + onRcptTo?: (address: Address, session: Session, callback: (err?: Error) => any) => any; + /** + * the callback to handle incoming messages (see details https://github.com/andris9/smtp-server#processing-incoming-message) + * + * + * @memberOf SMTPServerOptions + */ + onData?: (stream: any, session: Session, callback: (err?: Error) => any) => any; + /** + * the callback that informs about closed client connection + * + * + * @memberOf SMTPServerOptions + */ + onClose?: (session: Session) => any; +} + +export interface Authentication { + /** + * indicates the authentication method used, 'PLAIN', 'LOGIN' or 'XOAUTH2' + * + * @type {string} + * @memberOf Authentication + */ + method: "PLAIN" | "LOGIN" | "XOAUTH2";//'PLAIN', 'LOGIN' or 'XOAUTH2' + /** + * the username of the user + * + * @type {string} + * @memberOf Authentication + */ + username?: string; + /** + * the password if LOGIN or PLAIN was used + * + * @type {string} + * @memberOf Authentication + */ + password?: string; + /** + * the OAuth2 bearer access token if 'XOAUTH2' was used as the authentication method + * + * @type {string} + * @memberOf Authentication + */ + accessToken?: string; + /** + * a function for validating CRAM-MD5 challenge responses. + * Takes the password of the user as an argument and returns true if the response matches the password + * + * + * @memberOf Authentication + */ + validatePassword: (password: string) => boolean; +} + +export interface AuthenticationResponse { + /** + * can be any value - if this is set then the user is considered logged in + * and this value is used later with the session data to identify the user. + * If this value is empty, then the authentication is considered failed + * + * @type {*} + * @memberOf AuthenticationResponse + */ + user: any; + /** + * an object to return if XOAUTH2 authentication failed (do not set the error object in this case). + * This value is serialized to JSON and base64 encoded automatically, so you can just return the object + * + * @type {{}} + * @memberOf AuthenticationResponse + */ + data?: {}; +} + +export interface Session { + /** + * random string identificator generated when the client connected + * + * @type {string} + * @memberOf Session + */ + id: string; + /** + * the IP address for the connected client + * + * @type {Address} + * @memberOf Session + */ + remoteAddress: Address; + /** + * reverse resolved hostname for remoteAddress + * + * @type {string} + * @memberOf Session + */ + clientHostname: string; + /** + * the opening SMTP command (HELO/EHLO/LHLO) + * + * @type {string} + * @memberOf Session + */ + openingCommand: string; + /** + * hostname the client provided with HELO/EHLO call + * + * @type {string} + * @memberOf Session + */ + hostNameApearsAs: string; + /** + * Envelope Object + * + * @type {Envelope} + * @memberOf Session + */ + envelope: Envelope; +} + +export interface Envelope { + /** + * includes an address object or is set to false + * + * @type {Address} + * @memberOf Envelope + */ + mailFrom: Address; + /** + * includes an array of address objects + * + * @type {Address[]} + * @memberOf Envelope + */ + rcptTo: Address[]; +} + +export interface Address { + /** + * the address provided with the MAIL FROM or RCPT TO command + * + * @type {string} + * @memberOf Address + */ + address: string; + /** + * an object with additional arguments (all key names are uppercase) + * + * @type {Object} + * @memberOf Address + */ + args: Object; +} diff --git a/smtp-server/smtp-server-tests.ts b/smtp-server/smtp-server-tests.ts new file mode 100644 index 0000000000..70a7797790 --- /dev/null +++ b/smtp-server/smtp-server-tests.ts @@ -0,0 +1,12 @@ +import { SMTPServer, SMTPServerOptions } from './'; + +function SMTPServerConnectTest() { + let options: SMTPServerOptions = { + secure: false, + }; + let server = new SMTPServer(options); + server.listen(2323); +} + +SMTPServerConnectTest(); + diff --git a/smtp-server/tsconfig.json b/smtp-server/tsconfig.json new file mode 100644 index 0000000000..e2a03d1d7f --- /dev/null +++ b/smtp-server/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "module": "commonjs", + "target": "es6", + "noImplicitAny": true, + "strictNullChecks": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "smtp-server-tests.ts" + ] +}