auth-vir 0.0.3 → 1.0.0

package/README.md

@@ -24,12 +24,7 @@ npm i auth-vir
     /** When a user creates or resets their password, hash it before storing it in your database. */
 
     const hashedPassword = await hashPassword('user input password');
-
-    if (!hashedPassword) {
-        /** This happens if the user password is too long for the bcrypt algorithm. */
-        throw new Error('Password too long.');
-    }
-    /** Now store `hashedPassword` in your database. */
+    /** Store `hashedPassword` in your database. */
     ```
 
 -   Compare a stored password hash for login checking:

package/dist/hash.d.ts

@@ -1,20 +1,27 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type IArgon2Options } from 'hash-wasm';
 /**
- * Hashes a password using the bcrypt algorithm so passwords don't need to be stored in plain text.
- * The output of this function is safe to store in a database for future credential comparisons.
+ * Default value for {@link HashPasswordOptions}.
  *
- * @category Auth : Host
- * @returns `undefined` if the password is too long (and would be truncated by the bcrypt hashing
- *   algorithm). Otherwise, the hashed output.
- * @see https://wikipedia.org/wiki/Bcrypt
+ * @category Internal
  */
-export declare function hashPassword(password: string): Promise<undefined | string>;
+export declare const defaultHashOptions: HashPasswordOptions;
 /**
- * Checks if the given string will be truncated when passed through {@link hashPassword}. Passwords
- * longer than this should not be accepted.
+ * Options for {@link hashPassword}.
  *
  * @category Internal
  */
-export declare function willHashTruncate(input: string): boolean;
+export type HashPasswordOptions = PartialWithUndefined<Omit<IArgon2Options, 'outputType' | 'salt' | 'password' | 'secret'>>;
+/**
+ * Hashes a password using the Argon2id algorithm so passwords don't need to be stored in plain
+ * text. The output of this function is safe to store in a database for future credential
+ * comparisons.
+ *
+ * @category Auth : Host
+ * @returns The hashed password.
+ * @see https://en.wikipedia.org/wiki/Argon2
+ */
+export declare function hashPassword(password: string, options?: HashPasswordOptions): Promise<string>;
 /**
  * A utility that provides more accurate string byte size than doing `string.length`.
  *
@@ -22,7 +29,7 @@ export declare function willHashTruncate(input: string): boolean;
  */
 export declare function getByteLength(input: string): number;
 /**
- * Checks if the given password is a match by comparing it to its previously computed and stored
+ * Checks if the given password is a match by comparing it to the previously computed and stored
  * hash.
  *
  * @category Auth : Host

package/dist/hash.js

@@ -1,33 +1,32 @@
-import { bcrypt, bcryptVerify } from 'hash-wasm';
+import { mergeDefinedProperties, } from '@augment-vir/common';
+import { argon2id, argon2Verify } from 'hash-wasm';
 /**
- * Hashes a password using the bcrypt algorithm so passwords don't need to be stored in plain text.
- * The output of this function is safe to store in a database for future credential comparisons.
+ * Default value for {@link HashPasswordOptions}.
  *
- * @category Auth : Host
- * @returns `undefined` if the password is too long (and would be truncated by the bcrypt hashing
- *   algorithm). Otherwise, the hashed output.
- * @see https://wikipedia.org/wiki/Bcrypt
+ * @category Internal
  */
-export async function hashPassword(password) {
-    if (willHashTruncate(password)) {
-        return undefined;
-    }
-    const salt = new Uint8Array(16);
-    globalThis.crypto.getRandomValues(salt);
-    return await bcrypt({
-        costFactor: 10,
-        password: password.normalize(),
-        salt,
-    });
-}
+export const defaultHashOptions = {
+    hashLength: 32,
+    iterations: 256,
+    memorySize: 512,
+    parallelism: 1,
+};
 /**
- * Checks if the given string will be truncated when passed through {@link hashPassword}. Passwords
- * longer than this should not be accepted.
+ * Hashes a password using the Argon2id algorithm so passwords don't need to be stored in plain
+ * text. The output of this function is safe to store in a database for future credential
+ * comparisons.
  *
- * @category Internal
+ * @category Auth : Host
+ * @returns The hashed password.
+ * @see https://en.wikipedia.org/wiki/Argon2
  */
-export function willHashTruncate(input) {
-    return getByteLength(input) > 72;
+export async function hashPassword(password, options = {}) {
+    const salt = globalThis.crypto.getRandomValues(new Uint8Array(16));
+    return await argon2id(mergeDefinedProperties(defaultHashOptions, options, {
+        outputType: 'encoded',
+        password: password.normalize(),
+        salt,
+    }));
 }
 /**
  * A utility that provides more accurate string byte size than doing `string.length`.
@@ -38,13 +37,13 @@ export function getByteLength(input) {
     return new Blob([input]).size;
 }
 /**
- * Checks if the given password is a match by comparing it to its previously computed and stored
+ * Checks if the given password is a match by comparing it to the previously computed and stored
  * hash.
  *
  * @category Auth : Host
  */
 export async function doesPasswordMatchHash({ password, hash, }) {
-    return await bcryptVerify({
+    return await argon2Verify({
         hash,
         password,
     });

package/dist/jwt-keys.script.js

@@ -1,2 +1,3 @@
+import { stringifyWithJson5 } from '@augment-vir/common';
 import { generateNewJwtKeys } from './jwt-keys.js';
-console.info(await generateNewJwtKeys());
+console.info(stringifyWithJson5(await generateNewJwtKeys()));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "0.0.3",
+    "version": "1.0.0",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",

package/src/hash.ts

@@ -1,37 +1,53 @@
-import {bcrypt, bcryptVerify} from 'hash-wasm';
+import {
+    type AnyObject,
+    mergeDefinedProperties,
+    type PartialWithUndefined,
+} from '@augment-vir/common';
+import {argon2id, argon2Verify, type IArgon2Options} from 'hash-wasm';
 
 /**
- * Hashes a password using the bcrypt algorithm so passwords don't need to be stored in plain text.
- * The output of this function is safe to store in a database for future credential comparisons.
+ * Default value for {@link HashPasswordOptions}.
  *
- * @category Auth : Host
- * @returns `undefined` if the password is too long (and would be truncated by the bcrypt hashing
- *   algorithm). Otherwise, the hashed output.
- * @see https://wikipedia.org/wiki/Bcrypt
+ * @category Internal
  */
-export async function hashPassword(password: string): Promise<undefined | string> {
-    if (willHashTruncate(password)) {
-        return undefined;
-    }
-
-    const salt = new Uint8Array(16);
-    globalThis.crypto.getRandomValues(salt);
-
-    return await bcrypt({
-        costFactor: 10,
-        password: password.normalize(),
-        salt,
-    });
-}
+export const defaultHashOptions: HashPasswordOptions = {
+    hashLength: 32,
+    iterations: 256,
+    memorySize: 512,
+    parallelism: 1,
+};
 
 /**
- * Checks if the given string will be truncated when passed through {@link hashPassword}. Passwords
- * longer than this should not be accepted.
+ * Options for {@link hashPassword}.
  *
  * @category Internal
  */
-export function willHashTruncate(input: string): boolean {
-    return getByteLength(input) > 72;
+export type HashPasswordOptions = PartialWithUndefined<
+    Omit<IArgon2Options, 'outputType' | 'salt' | 'password' | 'secret'>
+>;
+
+/**
+ * Hashes a password using the Argon2id algorithm so passwords don't need to be stored in plain
+ * text. The output of this function is safe to store in a database for future credential
+ * comparisons.
+ *
+ * @category Auth : Host
+ * @returns The hashed password.
+ * @see https://en.wikipedia.org/wiki/Argon2
+ */
+export async function hashPassword(
+    password: string,
+    options: HashPasswordOptions = {},
+): Promise<string> {
+    const salt = globalThis.crypto.getRandomValues(new Uint8Array(16));
+
+    return await argon2id(
+        mergeDefinedProperties<AnyObject>(defaultHashOptions, options, {
+            outputType: 'encoded',
+            password: password.normalize(),
+            salt,
+        }) as IArgon2Options,
+    );
 }
 
 /**
@@ -44,7 +60,7 @@ export function getByteLength(input: string): number {
 }
 
 /**
- * Checks if the given password is a match by comparing it to its previously computed and stored
+ * Checks if the given password is a match by comparing it to the previously computed and stored
  * hash.
  *
  * @category Auth : Host
@@ -58,7 +74,7 @@ export async function doesPasswordMatchHash({
     /** The stored password hash for that user. */
     hash: string;
 }): Promise<boolean> {
-    return await bcryptVerify({
+    return await argon2Verify({
         hash,
         password,
     });

package/src/jwt-keys.script.ts

@@ -1,3 +1,4 @@
+import {stringifyWithJson5} from '@augment-vir/common';
 import {generateNewJwtKeys} from './jwt-keys.js';
 
-console.info(await generateNewJwtKeys());
+console.info(stringifyWithJson5(await generateNewJwtKeys()));