@crossauth/backend 0.0.2

package/dist/emailtokens.d.ts

@@ -0,0 +1,178 @@
+import { UserStorage, KeyStorage } from './storage';
+import { User } from '@crossauth/common';
+
+export interface TokenEmailerOptions {
+    /** The site url, used to create a link, eg "https://mysite.com:3000".  No default - required parameter */
+    siteUrl?: string;
+    /** The prefix between the site url and the email verification/password reset link.  Default "/" */
+    prefix?: string;
+    /** The directory containing views (by default, Nunjucks templates) */
+    views?: string;
+    /** Template file containing page for producing the text version of the email verification email body */
+    emailVerificationTextBody?: string;
+    /** Template file containing page for producing the HTML version of the email verification email body */
+    emailVerificationHtmlBody?: string;
+    /** Subject for the the email verification email */
+    emailVerificationSubject?: string;
+    /** Template file containing page for producing the text version of the password reset email body */
+    passwordResetTextBody?: string;
+    /** Template file containing page for producing the HTML version of the password reset email body */
+    passwordResetHtmlBody?: string;
+    /** Subject for the the password reset email */
+    passwordResetSubject?: string;
+    /** Sender for emails */
+    emailFrom?: string;
+    /** Hostname of the SMTP server.  No default - required parameter */
+    smtpHost?: string;
+    /** Port the SMTP server is running on.  Default 25 */
+    smtpPort?: number;
+    /** Whether or not TLS is used by the SMTP server.  Default false */
+    smtpUseTls?: boolean;
+    /** Username for connecting to SMTP servger.  Default undefined */
+    smtpUsername?: string;
+    /** Password for connecting to SMTP servger.  Default undefined */
+    smtpPassword?: string;
+    /** Number of seconds befire email verification tokens should expire.  Default 1 day */
+    verifyEmailExpires?: number;
+    /** Number of seconds befire password reset tokens should expire.  Default 1 day */
+    passwordResetExpires?: number;
+    /** if passed, use this instead of the default nunjucks renderer */
+    render?: (template: string, data: {
+        [key: string]: any;
+    }) => string;
+}
+/**
+ * Sends password reset and email verification tokens to an email addredss
+ */
+export declare class TokenEmailer {
+    private userStorage;
+    private keyStorage;
+    private views;
+    private siteUrl?;
+    private prefix?;
+    private emailVerificationTextBody?;
+    private emailVerificationHtmlBody?;
+    private emailVerificationSubject;
+    private passwordResetTextBody?;
+    private passwordResetHtmlBody?;
+    private passwordResetSubject;
+    private emailFrom;
+    private smtpHost;
+    private smtpPort;
+    private smtpUseTls?;
+    private smtpUsername?;
+    private smtpPassword?;
+    private verifyEmailExpires;
+    private passwordResetExpires;
+    private render?;
+    /**
+     * Construct a new EmailVerifier.
+     *
+     * This emails tokens for email verification and password reset
+     *
+     * @param userStorage : where to retrieve and update user details
+     * @param keyStorage : where to store email verification tokens
+     * @param options see {@link TokenEmailerOptions}
+     */
+    constructor(userStorage: UserStorage, keyStorage: KeyStorage, options?: TokenEmailerOptions);
+    private createEmailer;
+    /**
+     * Produces a hash of the given email verification token with the
+     * correct prefix for inserting into storage.
+     */
+    static hashEmailVerificationToken(token: string): string;
+    /**
+     * Produces a hash of the given password reset token with the
+     * correct prefix for inserting into storage.
+     */
+    static hashPasswordResetToken(token: string): string;
+    private createAndSaveEmailVerificationToken;
+    /**
+     * Separated out for unit testing/mocking purposes
+     */
+    private _sendEmailVerificationToken;
+    /**
+     * Send an email verification email using the Nunjucks templates.
+     *
+     * The email address to send it to will be taken from the user's record in
+     * user storage.  It will
+     * first be validated, throwing a {@link @crossauth/common!CrossauthError}
+     * with {@link @crossauth/common!ErrorCode} of
+     * `InvalidEmail` if it is not valid..
+     *
+     * @param userid userid to send it for
+     * @param newEmail if this is a token to verify email for account
+     *        activation, leave this empty.
+     *        If it is for changing an email, this will be the field it is
+     *        being changed do.
+     * @param extraData : these extra variables will be passed to the Nunjucks
+     *        templates
+     */
+    sendEmailVerificationToken(userid: string | number, newEmail?: string, extraData?: {
+        [key: string]: any;
+    }): Promise<void>;
+    /**
+     * Validates an email verification token.
+     *
+     * The following must match:
+     *     * expiry date in the key storage record must be less than current time
+     *     * userid in the token must match the userid in the key storage
+     *     * email address in user storage must match the email in the key.  If there is no email address,
+     *       the username field is set if it is in email format.
+     *     * expiry time in the key storage must match the expiry time in the key
+     *
+     * Looks the token up in key storage and verifies it matches and has not expired.
+     * @param token the token to validate
+     * @returns the userid of the user the token is for and the email
+     *          address the user is validating
+     */
+    verifyEmailVerificationToken(token: string): Promise<{
+        userid: string | number;
+        newEmail: string;
+    }>;
+    deleteEmailVerificationToken(token: string): Promise<void>;
+    private createAndSavePasswordResetToken;
+    /**
+     * Validates a password reset token
+     *
+     * The following must match:
+     *     * expiry date in the key storage record must be less than current time
+     *     * userid in the token must match the userid in the key storage
+     *     * the email in the token matches either the email or username field in user storage
+     *     * the password in user storage must match the password in the key
+     *     * expiry time in the key storage must match the expiry time in the key
+     * Looks the token up in key storage and verifies it matches and has not expired.  Also verifies
+     * the user exists and password has not changed in the meantime.
+     * @param token the token to validate
+     * @returns the user that the token is for
+     */
+    verifyPasswordResetToken(token: string): Promise<User>;
+    /**
+     * Separated out for unit testing/mocking purposes
+     */
+    private _sendPasswordResetToken;
+    /**
+     * Send a password reset token email using the Nunjucks templates
+     * @param userid userid to send it for
+     * @param extraData : these extra variables will be passed to the Nunjucks
+     *        templates
+     */
+    sendPasswordResetToken(userid: string | number, extraData?: {
+        [key: string]: any;
+    }): Promise<void>;
+    /**
+     * Returns true if the given email has a valid format, false otherwise.
+     * @param email the email to validate
+     * @returns true or false
+     */
+    static isEmailValid(email: string): boolean;
+    /**
+     * Returns if the given email has a valid format.  Throws a
+     * {@link @crossauth/common!CrossauthError} with
+     * {@link @crossauth/common!ErrorCode} `InvalidEmail` otherwise.
+     *
+     * @param email the email to validate
+     */
+    static validateEmail(email: string | undefined): void;
+}
+//# sourceMappingURL=emailtokens.d.ts.map

package/dist/emailtokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailtokens.d.ts","sourceRoot":"","sources":["../src/emailtokens.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAKpD,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAK9C,MAAM,WAAW,mBAAmB;IAEhC,0GAA0G;IAC1G,OAAO,CAAC,EAAG,MAAM,CAAC;IAElB,mGAAmG;IACnG,MAAM,CAAC,EAAG,MAAM,CAAC;IAEjB,sEAAsE;IACtE,KAAK,CAAC,EAAG,MAAM,CAAC;IAEhB,wGAAwG;IACxG,yBAAyB,CAAC,EAAG,MAAM,CAAC;IAEpC,wGAAwG;IACxG,yBAAyB,CAAC,EAAG,MAAM,CAAC;IAEpC,mDAAmD;IACnD,wBAAwB,CAAC,EAAG,MAAM,CAAC;IAEnC,oGAAoG;IACpG,qBAAqB,CAAC,EAAG,MAAM,CAAC;IAEhC,oGAAoG;IACpG,qBAAqB,CAAC,EAAG,MAAM,CAAC;IAEhC,+CAA+C;IAC/C,oBAAoB,CAAC,EAAG,MAAM,CAAC;IAE/B,wBAAwB;IACxB,SAAS,CAAC,EAAG,MAAM,CAAC;IAEpB,oEAAoE;IACpE,QAAQ,CAAC,EAAG,MAAM,CAAC;IAEnB,sDAAsD;IACtD,QAAQ,CAAC,EAAG,MAAM,CAAC;IAEnB,oEAAoE;IACpE,UAAU,CAAC,EAAG,OAAO,CAAC;IAEtB,kEAAkE;IAClE,YAAY,CAAC,EAAG,MAAM,CAAC;IAEvB,kEAAkE;IAClE,YAAY,CAAC,EAAG,MAAM,CAAC;IAEvB,uFAAuF;IACvF,kBAAkB,CAAC,EAAG,MAAM,CAAC;IAE7B,mFAAmF;IACnF,oBAAoB,CAAC,EAAG,MAAM,CAAC;IAE/B,mEAAmE;IACnE,MAAM,CAAC,EAAG,CAAC,QAAQ,EAAG,MAAM,EAAE,IAAI,EAAG;QAAC,CAAC,GAAG,EAAC,MAAM,GAAE,GAAG,CAAA;KAAC,KAAK,MAAM,CAAC;CACtE;AAED;;GAEG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAgB;IAC/B,OAAO,CAAC,yBAAyB,CAAC,CAA4C;IAC9E,OAAO,CAAC,yBAAyB,CAAC,CAAU;IAC5C,OAAO,CAAC,wBAAwB,CAAuC;IACvE,OAAO,CAAC,qBAAqB,CAAC,CAAwC;IACtE,OAAO,CAAC,qBAAqB,CAAC,CAAU;IACxC,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,UAAU,CAAC,CAAkB;IACrC,OAAO,CAAC,YAAY,CAAC,CAAU;IAC/B,OAAO,CAAC,YAAY,CAAC,CAAU;IAC/B,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,oBAAoB,CAAqB;IACjD,OAAO,CAAC,MAAM,CAAC,CACQ;IACvB;;;;;;;;OAQG;gBACS,WAAW,EAAG,WAAW,EACzB,UAAU,EAAG,UAAU,EACvB,OAAO,GAAG,mBAAwB;IA6B9C,OAAO,CAAC,aAAa;IAYrB;;;OAGG;IACH,MAAM,CAAC,0BAA0B,CAAC,KAAK,EAAG,MAAM,GAAI,MAAM;IAI1D;;;OAGG;IACH,MAAM,CAAC,sBAAsB,CAAC,KAAK,EAAG,MAAM,GAAI,MAAM;YAIxC,mCAAmC;IAqBjD;;OAEG;YACW,2BAA2B;IA4BzC;;;;;;;;;;;;;;;;OAgBG;IACG,0BAA0B,CAAC,MAAM,EAAG,MAAM,GAAG,MAAM,EACxB,QAAQ,GAAG,MAAS,EACpB,SAAS,GAAG;QAAC,CAAC,GAAG,EAAC,MAAM,GAAE,GAAG,CAAA;KAAM,GAAI,OAAO,CAAC,IAAI,CAAC;IA4BrF;;;;;;;;;;;;;;OAcG;IACG,4BAA4B,CAAC,KAAK,EAAG,MAAM,GAC7C,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,GAAC,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAAC;IA4BhD,4BAA4B,CAAC,KAAK,EAAG,MAAM;YAWnC,+BAA+B;IAoB7C;;;;;;;;;;;;;OAaG;IACG,wBAAwB,CAAC,KAAK,EAAG,MAAM,GAAI,OAAO,CAAC,IAAI,CAAC;IAgB9D;;OAEG;YACW,uBAAuB;IAgCrC;;;;;OAKG;IACG,sBAAsB,CAAC,MAAM,EAAG,MAAM,GAAG,MAAM,EACjD,SAAS,GAAG;QAAC,CAAC,GAAG,EAAC,MAAM,GAAE,GAAG,CAAA;KAAM,GAAI,OAAO,CAAC,IAAI,CAAC;IAyBxD;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAG,MAAM,GAAI,OAAO;IAS7C;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAG,MAAM,GAAC,SAAS;CAIhD"}