@crossauth/backend 0.0.2

package/dist/authenticators/totpauth.d.ts

@@ -0,0 +1,117 @@
+import { User, Key, UserSecretsInputFields, UserInputFields } from '@crossauth/common';
+import { Authenticator, AuthenticationParameters, AuthenticationOptions } from '../auth.ts';
+
+/**
+ * Authenticator for Time-Based One-Time Passwords (TOTP), eg
+ * Google Authenticator
+ */
+export declare class TotpAuthenticator extends Authenticator {
+    private appName;
+    /**
+     * Constructor
+     * @param appName this forms part of the QR code that users scan into
+     *                their authenticator app.  The name will appear in their app
+     * @param options See {@link AuthenticationOptions}.
+     */
+    constructor(appName: string, options?: AuthenticationOptions);
+    /**
+     * Used by the OAuth password_mfa grant type.
+     */
+    mfaType(): "none" | "oob" | "otp";
+    /**
+     * Used by the OAuth password_mfa grant type.
+     */
+    mfaChannel(): "none" | "email" | "sms";
+    private createSecret;
+    private getSecretFromSession;
+    /**
+     * Creates a shared secret and returns it, along with image data for the QR
+     * code to display.
+     * @param user the `username` is expected to be present.  All other fields
+     *             are ignored.
+     * @returns `userData` containing `username`, `totpsecret`, `factor2` and
+     *          `qr`.
+     *          `sessionData` containing the same except `qr`.
+     */
+    prepareConfiguration(user: UserInputFields): Promise<{
+        userData: {
+            [key: string]: any;
+        };
+        sessionData: {
+            [key: string]: any;
+        };
+    } | undefined>;
+    /**
+     * For cases when the 2FA page was closed without completing.  Returns the
+     * same data as `prepareConfiguration`, without generating a new secret.
+     * @param username user to return this for
+     * @param sessionKey the session key, which should cantain the
+     *                   `sessionData` from `prepareConfiguration`,
+     * @returns `userData` containing `totpsecret`, `factor2` and `qr`.
+     *          `secrets` containing `totpsecret`.
+     *          `newSessionData` containing the same except `qr`.
+     */
+    reprepareConfiguration(username: string, sessionKey: Key): Promise<{
+        userData: {
+            [key: string]: any;
+        };
+        secrets: Partial<UserSecretsInputFields>;
+        newSessionData: {
+            [key: string]: any;
+        } | undefined;
+    } | undefined>;
+    /**
+     * Authenticates the user using the saved TOTP parameters and the passed
+     * code.
+     * @param _user ignored
+     * @param secrets should contain `totpsecret` that was saved in the session
+     *                data.
+     * @param params should contain `otp`.
+     */
+    authenticateUser(_user: UserInputFields | undefined, secrets: UserSecretsInputFields, params: AuthenticationParameters): Promise<void>;
+    /**
+     * Creates and returns a `totpsecret`
+     *
+     * `allowEmptySecrets` is ignored.
+     *
+     * @param username the user to create these for
+     * @param _params ignored
+     * @param _repeatParams  ignored
+     * @returns the `totpsecret` field will be populated.
+     */
+    createPersistentSecrets(username: string, _params: AuthenticationParameters, _repeatParams?: AuthenticationParameters): Promise<Partial<UserSecretsInputFields>>;
+    /**
+     * Does nothing for this class
+     */
+    createOneTimeSecrets(_user: User): Promise<Partial<UserSecretsInputFields>>;
+    /**
+     * @returns true - this class can create users
+     */
+    canCreateUser(): boolean;
+    /**
+     * @returns true - this class can update users
+     */
+    canUpdateUser(): boolean;
+    /**
+     * @returns false - users cannot update secrets
+     */
+    canUpdateSecrets(): boolean;
+    /**
+     * @returns `totpsecret`
+     */
+    secretNames(): string[];
+    /**
+     * @returns `totpsecret`
+     */
+    transientSecretNames(): string[];
+    /**
+     * Does nothing for this class
+     */
+    validateSecrets(_params: AuthenticationParameters): string[];
+    /**
+     * @returns false - if email verification is enabled, it should be used
+     * for this class
+     */
+    skipEmailVerificationOnSignup(): boolean;
+}
+//# sourceMappingURL=totpauth.d.ts.map

package/dist/authenticators/totpauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"totpauth.d.ts","sourceRoot":"","sources":["../../src/authenticators/totpauth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACR,IAAI,EACJ,GAAG,EACH,sBAAsB,EACtB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI/C,OAAO,EACH,aAAa,EACb,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGnD;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;IAEhD,OAAO,CAAC,OAAO,CAAU;IAEzB;;;;;OAKG;gBACS,OAAO,EAAG,MAAM,EAAE,OAAO,CAAC,EAAG,qBAAqB;IAK9D;;OAEG;IACH,OAAO,IAAK,MAAM,GAAG,KAAK,GAAG,KAAK;IAElC;;OAEG;IACH,UAAU,IAAK,MAAM,GAAG,OAAO,GAAG,KAAK;YAEzB,YAAY;YAiBZ,oBAAoB;IAsBlC;;;;;;;;OAQG;IACG,oBAAoB,CAAC,IAAI,EAAG,eAAe,GAC7C,OAAO,CAAC;QACJ,QAAQ,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;SAAE,CAAC;QACjC,WAAW,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;SAAE,CAAA;KAClC,GAAC,SAAS,CAAC;IAqBpB;;;;;;;;;OASG;IACG,sBAAsB,CAAC,QAAQ,EAAG,MAAM,EAAE,UAAU,EAAG,GAAG,GAC5D,OAAO,CAAC;QACJ,QAAQ,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;SAAE,CAAC;QACjC,OAAO,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;QACzC,cAAc,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;SAAE,GAAG,SAAS,CAAA;KACjD,GAAC,SAAS,CAAC;IAUpB;;;;;;;OAOG;IACG,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,EACrD,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,wBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC;IAajB;;;;;;;;;OASG;IACG,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAC1C,OAAO,EAAE,wBAAwB,EACjC,aAAa,CAAC,EAAE,wBAAwB,GACxC,OAAO,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAK5C;;OAEG;IACG,oBAAoB,CAAC,KAAK,EAAG,IAAI,GACnC,OAAO,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAI5C;;OAEG;IACH,aAAa,IAAK,OAAO;IAKzB;;OAEG;IACH,aAAa,IAAK,OAAO;IAIzB;;OAEG;IACH,gBAAgB,IAAK,OAAO;IAI5B;;OAEG;IACH,WAAW,IAAK,MAAM,EAAE;IAIxB;;OAEG;IACH,oBAAoB,IAAK,MAAM,EAAE;IAIjC;;OAEG;IACH,eAAe,CAAC,OAAO,EAAG,wBAAwB,GAAI,MAAM,EAAE;IAI9D;;;OAGG;IACH,6BAA6B,IAAK,OAAO;CAG5C"}

package/dist/authenticators/twilioauth.d.ts

@@ -0,0 +1,29 @@
+import { SmsAuthenticator, SmsAuthenticatorOptions } from './smsauth';
+
+/**
+ * This authenticator creates a one-time code and sends it in an sms using
+ * Twilio
+ */
+export declare class TwilioAuthenticator extends SmsAuthenticator {
+    private accountSid;
+    private authToken;
+    /**
+     * Constructor
+     *
+     * To call this, you must have `TWILIO_ACCOUNT_SID` and
+     * `TWILIO_AUTH_TOKEN` environment variables set.
+     *
+     * @param options see {@link SmsAuthenticatorOptions}
+     * @throws {@link @crossauth/common!CrossauthError} with
+     *         {@link @crossauth/common!ErrorCode} of `Configuration`.
+     */
+    constructor(options?: SmsAuthenticatorOptions);
+    /**
+     * Uses Twilio to send an SMS
+     * @param to number to send SMS to (starting with `+`)
+     * @param body text to send
+     * @returns the send message ID
+     */
+    protected sendSms(to: string, body: string): Promise<string>;
+}
+//# sourceMappingURL=twilioauth.d.ts.map

package/dist/authenticators/twilioauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilioauth.d.ts","sourceRoot":"","sources":["../../src/authenticators/twilioauth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAG3E;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB;IAErD,OAAO,CAAC,UAAU,CAAU;IAC5B,OAAO,CAAC,SAAS,CAAU;IAE3B;;;;;;;;;OASG;gBACS,OAAO,GAAG,uBAA4B;IAUlD;;;;;OAKG;cACa,OAAO,CAAC,EAAE,EAAG,MAAM,EAAE,IAAI,EAAG,MAAM,GAAI,OAAO,CAAC,MAAM,CAAC;CAkBxE"}

package/dist/cookieauth.d.ts

@@ -0,0 +1,269 @@
+import { User, Key } from '@crossauth/common';
+import { UserStorage, KeyStorage, UserStorageGetOptions } from './storage';
+import { TokenEmailerOptions } from './emailtokens.ts';
+import { CookieSerializeOptions } from 'cookie';
+
+/**
+ * Optional parameters when setting cookies,
+ *
+ * These match the HTTP cookie parameters of the same name.
+ */
+export interface CookieOptions {
+    domain?: string;
+    expires?: Date;
+    maxAge?: number;
+    httpOnly?: boolean;
+    path?: string;
+    secure?: boolean;
+    sameSite?: boolean | "lax" | "strict" | "none" | undefined;
+}
+export declare function toCookieSerializeOptions(options: CookieOptions): CookieSerializeOptions & {
+    path: string;
+};
+/**
+ * Object encapsulating a cookie name, value and options.
+ */
+export interface Cookie {
+    name: string;
+    value: string;
+    options: CookieOptions;
+}
+/**
+ * Options for double-submit csrf tokens
+ */
+export interface DoubleSubmitCsrfTokenOptions extends CookieOptions {
+    /** Name of cookie.  Defaults to "CSRFTOKEN" */
+    cookieName?: string;
+    /** Name of header.  Defaults to X-CROSSAUTH-CSRF */
+    headerName?: string;
+    /** The app secret used to sign the cookie */
+    secret?: string;
+}
+/**
+ * Class for creating and validating CSRF tokens according to the double-submit cookie pattern.
+ *
+ * CSRF token is send as a cookie plus either a header or a hidden form field.
+ */
+export declare class DoubleSubmitCsrfToken {
+    /** name of the CRSF HTTP header */
+    readonly headerName: string;
+    /** Name of the CSRF Cookie */
+    readonly cookieName: string;
+    readonly domain: string | undefined;
+    readonly httpOnly: boolean;
+    readonly path: string;
+    readonly secure: boolean;
+    readonly sameSite: boolean | "lax" | "strict" | "none" | undefined;
+    private secret;
+    /**
+     * Constructor.
+     *
+     * @param options configurable options.  See {@link DoubleSubmitCsrfTokenOptions}.  The
+     *                expires and maxAge options are ignored (cookies are session-only).
+     */
+    constructor(options?: DoubleSubmitCsrfTokenOptions);
+    /**
+     * Creates a session key and saves in storage
+     *
+     * Date created is the current date/time on the server.
+     *
+     * @returns a random CSRF token.
+     */
+    createCsrfToken(): string;
+    /**
+     * Returns a {@link Cookie } object with the given session key.
+     *
+     * This class is compatible, for example, with Express.
+     *
+     * @param token the value of the csrf token, with signature
+     * @returns a {@link Cookie } object,
+     */
+    makeCsrfCookie(token: string): Cookie;
+    makeCsrfFormOrHeaderToken(token: string): string;
+    unsignCookie(cookieValue: string): string;
+    /**
+     * Takes a session ID and creates a string representation of the cookie (value of the HTTP `Cookie` header).
+     *
+     * @param cookieValue the value to put in the cookie
+     * @returns a string representation of the cookie and options.
+     */
+    makeCsrfCookieString(cookieValue: string): string;
+    private maskCsrfToken;
+    private unmaskCsrfToken;
+    /**
+     * Validates the passed CSRF token.
+     *
+     * To be valid:
+     *     * The signature in the cookie must match the token in the cookie
+     *     * The token in the cookie must matched the value in the form or header after unmasking
+     *
+     * @param cookieValue the CSRDF cookie value to validate.
+     * @param formOrHeaderValue the value from the csrfToken form header or the X-CROSSAUTH-CSRF header.
+     * @throws {@link @crossauth/common!CrossauthError} with {@link @crossauth/common!ErrorCode} of `InvalidKey`
+     */
+    validateDoubleSubmitCsrfToken(cookieValue: string, formOrHeaderValue: string): void;
+    /**
+     * Validates the passed CSRF cookie (doesn't check it matches the token, just that the cookie is valid).
+     *
+     * To be valid:
+     *     * The signature in the cookie must match the token in the cookie
+     *     * The token in the cookie must matched the value in the form or header after unmasking
+     *
+     * @param cookieValue the CSRF cookie value to validate.
+     * @throws {@link @crossauth/common!CrossauthError} with {@link @crossauth/common!ErrorCode} of `InvalidKey`
+     */
+    validateCsrfCookie(cookieValue: string): any;
+}
+/**
+ * Options for double-submit csrf tokens
+ */
+export interface SessionCookieOptions extends CookieOptions, TokenEmailerOptions {
+    /**
+     * If user login is enabled, you must provide the user storage class
+     */
+    userStorage?: UserStorage;
+    /** Name of cookie.  Defaults to "CSRFTOKEN" */
+    cookieName?: string;
+    /** If true, session IDs are stored in hashed form in the key storage.  Default false. */
+    hashSessionId?: boolean;
+    /** If non zero, sessions will time out after this number of seconds have elapsed without activity.  Default 0 (no timeout) */
+    idleTimeout?: number;
+    /** If true, sessions cookies will be persisted between browser sessions.  Default true */
+    persist?: boolean;
+    /** App secret  */
+    secret?: string;
+    /**
+     * This will be called with the session key to filter sessions
+     * before returning.  Function should return true if the session is valid or false otherwise.
+     */
+    filterFunction?: (sessionKey: Key) => boolean;
+}
+/**
+ * Class for session management using a session id cookie.
+ */
+export declare class SessionCookie {
+    private userStorage?;
+    private keyStorage;
+    /** This is set from input options.  Number of seconds before an
+     * idle session will time out
+     */
+    readonly idleTimeout: number;
+    private persist;
+    private filterFunction?;
+    /** Name of the CSRF Cookie, set from input options */
+    readonly cookieName: string;
+    readonly maxAge: number;
+    readonly domain: string | undefined;
+    readonly httpOnly: boolean;
+    readonly path: string;
+    readonly secure: boolean;
+    readonly sameSite: boolean | "lax" | "strict" | "none" | undefined;
+    private secret;
+    /**
+     * Constructor.
+     *
+     * @param keyStorage where to put session IDs
+     * @param options configurable options.  See {@link SessionCookieOptions}.  The
+     *                expires option is ignored (cookies are session-only).
+     */
+    constructor(keyStorage: KeyStorage, options?: SessionCookieOptions);
+    private expiry;
+    /**
+     * Returns a hash of a session ID, with the session ID prefix for storing
+     * in the storage table.
+     * @param sessionId the session ID to hash
+     * @returns a base64-url-encoded string that can go into the storage
+     */
+    static hashSessionId(sessionId: string): string;
+    /**
+     * Creates a session key and saves in storage
+     *
+     * Date created is the current date/time on the server.
+     *
+     * In the unlikely event of the key already existing, it is retried up to 10 times before throwing
+     * an error with ErrorCode.KeyExists
+     *
+     * @param userid the user ID to store with the session key.
+     * @param extraFields Any fields in here will also be added to the session
+     *        record
+     * @returns the new session key
+     * @throws {@link @crossauth/common!CrossauthError} with
+     *         {@link @crossauth/common!ErrorCode} `KeyExists` if maximum
+     *          attempts exceeded trying to create a unique session id
+     */
+    createSessionKey(userid: string | number | undefined, extraFields?: {
+        [key: string]: any;
+    }): Promise<Key>;
+    /**
+     * Returns a {@link Cookie } object with the given session key.
+     *
+     * This class is compatible, for example, with Express.
+     *
+     * @param sessionKey the value of the session key
+     * @param persist if passed, overrides the persistSessionId setting
+     * @returns a {@link Cookie } object,
+     */
+    makeCookie(sessionKey: Key, persist?: boolean): Cookie;
+    /**
+     * Takes a session ID and creates a string representation of the cookie
+     * (value of the HTTP `Cookie` header).
+     *
+     * @param cookie the cookie vlaues to make a string from
+     * @returns a string representation of the cookie and options.
+     */
+    makeCookieString(cookie: Cookie): string;
+    /**
+     * Updates a session record in storage
+     * @param sessionKey the fields to update.  `value` must be set, and
+     *        will not be updated.  All other defined fields will be updated.
+     * @throws {@link @crossauth/common!CrossauthError} if the session does
+     *         not exist.
+     */
+    updateSessionKey(sessionKey: Partial<Key>): Promise<void>;
+    /**
+     * Unsigns a cookie and returns the original value.
+     * @param cookieValue the signed cookie value
+     * @returns the unsigned value
+     * @throws {@link @crossauth/common!CrossauthError} if the signature
+     *         is invalid.
+     */
+    unsignCookie(cookieValue: string): string;
+    /**
+     * Returns the user matching the given session key in session storage, or throws an exception.
+     *
+     * Looks the user up in the {@link UserStorage} instance passed to the constructor.
+     *
+     * Undefined will also fail is CookieAuthOptions.filterFunction is defined and returns false,
+     *
+     * @param sessionId the value in the session cookie
+     * @param options See {@link UserStorageGetOptions}
+     * @returns a {@link @crossauth/common!User } object, with the password hash removed, and the {@link @crossauth/common!Key } with the unhashed
+     *          sessionId
+     * @throws a {@link @crossauth/common!CrossauthError } with {@link @crossauth/common!ErrorCode } set to `InvalidSessionId` or `Expired`.
+     */
+    getUserForSessionId(sessionId: string, options?: UserStorageGetOptions): Promise<{
+        user: User | undefined;
+        key: Key;
+    }>;
+    /**
+     * Returns the user matching the given session key in session storage, or throws an exception.
+     *
+     * Looks the user up in the {@link UserStorage} instance passed to the constructor.
+     *
+     * Undefined will also fail is CookieAuthOptions.filterFunction is defined and returns false,
+     *
+     * @param sessionId the unsigned value of the session cookie
+     * @returns a {@link User } object, with the password hash removed.
+     * @throws a {@link @crossauth/common!CrossauthError } with
+     *         {@link @crossauth/common!ErrorCode } set to `InvalidSessionId`,
+     *         `Expired` or `UserNotExist`.
+     */
+    getSessionKey(sessionId: string): Promise<Key>;
+    /**
+     * Deletes all keys for the given user
+     * @param userid the user to delete keys for
+     * @param except if defined, don't delete this key
+     */
+    deleteAllForUser(userid: string | number, except: string | undefined): Promise<void>;
+}
+//# sourceMappingURL=cookieauth.d.ts.map

package/dist/cookieauth.d.ts.map

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

package/dist/crypto.d.ts

@@ -0,0 +1,196 @@
+/// <reference types="node" />
+/**
+ * An object that contains all components of a hashed password.  Hashing is done with PBKDF2
+ */
+export interface PasswordHash {
+    /** The actual hashed password in Base64 format */
+    hashedPassword: string;
+    /** The random salt used to create the hashed password */
+    salt: string;
+    /** Number of iterations for PBKDF2*/
+    iterations: number;
+    /** If true, secret (application secret) is also used to hash the password*/
+    useSecret: boolean;
+    /** The key length parameter passed to PBKDF2 - hash will be this number of characters long */
+    keyLen: number;
+    /** The digest algorithm to use, eg `sha512` */
+    digest: string;
+}
+/**
+ * Option parameters for {@link Crypto.passwordHash}
+ */
+export interface HashOptions {
+    /** A salt to prepend to the message before hashing */
+    salt?: string;
+    /** Whether to Base64-URL-encode the result */
+    encode?: boolean;
+    /** A secret to append to the salt when hashing, or undefined for no secret */
+    secret?: string;
+    /** Number of PBKDF2 iterations */
+    iterations?: number;
+    /** Length (before Base64-encoding) of the PBKDF2 key being generated */
+    keyLen?: number;
+    /** PBKDF2 digest method */
+    digest?: string;
+}
+/**
+ * Provides cryptographic functions
+ */
+export declare class Crypto {
+    /**
+     * Returns true if the plaintext password, when hashed, equals the one in the hash, using
+     * it's hasher settings
+     * @param plaintext the plaintext password
+     * @param encodedHash the previously-hashed version
+     * @param secret if `useHash`in `encodedHash` is true, uses as a pepper for the hasher
+     * @returns true if they are equal, false otherwise
+     */
+    static passwordsEqual(plaintext: string, encodedHash: string, secret?: string): Promise<boolean>;
+    /**
+     * Decodes a string from base64 to UTF-89
+     * @param encoded base64-encoded text
+     * @returns URF-8 text
+     */
+    static base64Decode(encoded: string): string;
+    /**
+     * Base64-encodes UTF-8 text
+     * @param text UTF-8 text
+     * @returns Base64 text
+     */
+    static base64Encode(text: string): string;
+    /**
+     * Splits a hashed password into its component parts.  Return it as a {@link PasswordHash }.
+     *
+     * The format of the hash should be
+     * ```
+     * digest:keyLen:iterations:useSecret:salt:hashedPassword
+     * ```
+     * The hashed password part is the Base64 encoding of the PBKDF2 password.
+     * @param hash the hassed password to decode.  See above for format
+     * @returns {@link PasswordHash} object containing the deecoded hash components
+     */
+    static decodePasswordHash(hash: string): PasswordHash;
+    /**
+     * Encodes a hashed password into the string format it is stored as.
+     *
+     * See {@link decodePasswordHash } for the format it is stored in.
+     *
+     * @param hashedPassword the Base64-encoded PBKDF2 hash of the password
+     * @param salt the salt used for the password.
+     * @param useSecret whether or not to use the application secret as part
+     *        of the hash.
+     * @param iterations the number of PBKDF2 iterations
+     * @param keyLen the key length PBKDF2 parameter - results in a hashed password this length, before Base64,
+     * @param digest The digest algorithm, eg `pbkdf2`
+     * @returns a string encode the above parameters.
+     */
+    static encodePasswordHash(hashedPassword: string, salt: string, useSecret: boolean, iterations: number, keyLen: number, digest: string): string;
+    /**
+     * Creates a random salt
+     * @returns random salt as a base64 encoded string
+     */
+    static randomSalt(): string;
+    /**
+     * Creates a random string encoded as in base64url
+     * @param length length of the string to create
+     * @returns the random value as a string.  Number of bytes will be greater as it is base64 encoded.
+     */
+    static randomValue(length: number): string;
+    static Base32: string[];
+    /**
+     * Creates a random base-23 string
+     * @param length length of the string to create
+     * @returns the random value as a string.  Number of bytes will be greater as it is base64 encoded.
+     */
+    static randomBase32(length: number, dashEvery?: number): string;
+    /**
+     * Creates a UUID
+     */
+    static uuid(): string;
+    /**
+     * Standard hash using SHA256 (not PBKDF2 or HMAC)
+     *
+     * @param plaintext text to hash
+     * @returns the string containing the hash
+     */
+    static hash(plaintext: string): string;
+    /**
+     * Standard hash using SHA256 (not PBKDF2 or HMAC)
+     *
+     * @param plaintext text to hash
+     * @returns the string containing the hash
+     */
+    static sha256(plaintext: string): string;
+    /**
+     * Hashes a password and returns it as a base64 or base64url encoded string
+     * @param plaintext password to hash
+     * @param options
+     *        - `salt`: salt to use.  Make a random one if not passed
+     *        - `secret`: optional application secret password to apply as a pepper
+     *        - `encode`: if true, returns the full string as it should be stored in the database.
+     * @returns the string containing the hash and the values to decode it
+     */
+    static passwordHash(plaintext: string, options?: HashOptions): Promise<string>;
+    /**
+     * For creating non-JWT tokens (eg password reset tokens.)  The
+     * hash is of a JSON containing the payload, timestamp and optionally
+     * a salt.
+     * @param payload the payload to hash
+     * @param salt optional salt (use if the payload is small)
+     * @param timestamp time the token will expire
+     * @returns a Base64-URL-encoded string that can be hashed.
+     */
+    static signableToken(payload: {
+        [key: string]: any;
+    }, salt?: string, timestamp?: number): string;
+    /**
+     * Signs a JSON payload by creating a hash, using a secret and
+     * optionally also a salt and timestamp
+     *
+     * @param payload object to sign (will be stringified as a JSON)
+     * @param secret secret key, which must be a string
+     * @param salt optionally, a salt to concatenate with the payload (must be a string)
+     * @param timestamp optionally, a timestamp to include in the signed date as a Unix date
+     * @returns Base64-url encoded hash
+     */
+    static sign(payload: {
+        [key: string]: any;
+    } | string, secret: string, salt?: string, timestamp?: number): string;
+    /**
+     * Validates a signature and, if valid, return the unstringified payload
+     * @param signedMessage signed message (base64-url encoded)
+     * @param secret secret key, which must be a string
+     * @param expiry if set, validation will fail if the timestamp in the payload is after this date
+     * @returns if signature is valid, the payload as an object
+     * @throws {@link @crossauth/common!CrossauthError} with
+     *         {@link @crossauth/common!ErrorCode} of `InvalidKey` if signature
+     *         is invalid or has expired.
+     */
+    static unsign(signedMessage: string, secret: string, expiry?: number): {
+        [key: string]: any;
+    };
+    /**
+     * XOR's two arrays of base64url-encoded strings
+     * @param value to XOR
+     * @param mask mask to XOR it with
+     * @return an XOR'r string
+     */
+    static xor(value: string, mask: string): string;
+    /**
+     * Symmetric encryption using a key that must be a string
+     *
+     * @param plaintext Text to encrypt
+     * @param keyString the symmetric key
+     * @returns Encrypted text Base64-url encoded.
+     */
+    static symmetricEncrypt(plaintext: string, keyString: string, iv?: Buffer | undefined): string;
+    /**
+     * Symmetric decryption using a key that must be a string
+     *
+     * @param ciphertext Base64-url encoded ciphertext
+     * @param keyString the symmetric key
+     * @returns Decrypted text
+     */
+    static symmetricDecrypt(ciphertext: string, keyString: string): string;
+}
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

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