auth-vir 0.0.4 → 1.1.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/auth.d.ts

@@ -1,4 +1,4 @@
-import { type CookieParams } from './cookie.js';
+import { clearAuthCookie, type CookieParams } from './cookie.js';
 import { type ParseJwtParams } from './jwt.js';
 /**
  * All possible headers container types supported by {@link extractUserIdFromRequestHeaders}.
@@ -20,12 +20,22 @@ export declare function extractUserIdFromRequestHeaders(headers: HeaderContainer
  *
  * @category Auth : Host
  */
-export declare function generateSuccessfulLoginHeaders(userId: string, 
+export declare function generateSuccessfulLoginHeaders(
 /** The id from your database of the user you're authenticating. */
-cookieConfig: Readonly<CookieParams>): Promise<{
+userId: string, cookieConfig: Readonly<CookieParams>): Promise<{
     'set-cookie': string;
     "csrf-token": string;
 }>;
+/**
+ * Used by host (backend) code to set headers on a response object when the user has logged out or
+ * failed to authorize.
+ *
+ * @category Auth : Host
+ */
+export declare function generateLogoutHeaders(...params: Parameters<typeof clearAuthCookie>): {
+    'set-cookie': string;
+    "csrf-token": string;
+};
 /**
  * Store auth data on a client (frontend) after receiving an auth response from the host (backend).
  * Specifically, this stores the CSRF token into local storage (which doesn't need to be a secret).

package/dist/auth.js

@@ -1,4 +1,4 @@
-import { extractCookieJwt, generateCookie } from './cookie.js';
+import { clearAuthCookie, extractCookieJwt, generateAuthCookie, } from './cookie.js';
 import { csrfTokenHeaderName, generateCsrfToken } from './csrf-token.js';
 function readHeader(headers, headerName) {
     if (headers instanceof Headers) {
@@ -47,18 +47,30 @@ export async function extractUserIdFromRequestHeaders(headers, jwtParams) {
  *
  * @category Auth : Host
  */
-export async function generateSuccessfulLoginHeaders(userId, 
+export async function generateSuccessfulLoginHeaders(
 /** The id from your database of the user you're authenticating. */
-cookieConfig) {
+userId, cookieConfig) {
     const csrfToken = generateCsrfToken();
     return {
-        'set-cookie': await generateCookie({
+        'set-cookie': await generateAuthCookie({
             csrfToken,
             userId,
         }, cookieConfig),
         [csrfTokenHeaderName]: csrfToken,
     };
 }
+/**
+ * Used by host (backend) code to set headers on a response object when the user has logged out or
+ * failed to authorize.
+ *
+ * @category Auth : Host
+ */
+export function generateLogoutHeaders(...params) {
+    return {
+        'set-cookie': clearAuthCookie(...params),
+        [csrfTokenHeaderName]: 'redacted',
+    };
+}
 /**
  * Store auth data on a client (frontend) after receiving an auth response from the host (backend).
  * Specifically, this stores the CSRF token into local storage (which doesn't need to be a secret).

package/dist/cookie.d.ts

@@ -1,9 +1,10 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
 import { type AnyDuration } from 'date-vir';
+import { type Primitive } from 'type-fest';
 import { type CreateJwtParams, type ParseJwtParams } from './jwt.js';
 import { type UserJwtData } from './user-jwt.js';
 /**
- * Parameters for {@link generateCookie}.
+ * Parameters for {@link generateAuthCookie}.
  *
  * @category Internal
  */
@@ -26,6 +27,7 @@ export type CookieParams = {
      * client, etc.
      */
     jwtParams: Readonly<CreateJwtParams>;
+    cookieName?: string;
 } & PartialWithUndefined<{
     /**
      * Is set to `true` (which should only be done in development environments), the cookie will be
@@ -40,7 +42,19 @@ export type CookieParams = {
  *
  * @category Internal
  */
-export declare function generateCookie(userJwtData: Readonly<UserJwtData>, cookieConfig: Readonly<CookieParams>): Promise<string>;
+export declare function generateAuthCookie(userJwtData: Readonly<UserJwtData>, cookieConfig: Readonly<CookieParams>): Promise<string>;
+/**
+ * Generate a cookie value that will clear the previous auth cookie. Use this when signing out.
+ *
+ * @category Internal
+ */
+export declare function clearAuthCookie(cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>): string;
+/**
+ * Generate a cookie string from a raw set of parameters.
+ *
+ * @category Internal
+ */
+export declare function generateCookie(params: Readonly<Record<string, Exclude<Primitive, symbol>>>): string;
 /**
  * Extract an auth cookie from a cookie string. Used in host (backend) code.
  *

package/dist/cookie.js

@@ -8,16 +8,54 @@ import { createUserJwt, parseUserJwt } from './user-jwt.js';
  *
  * @category Internal
  */
-export async function generateCookie(userJwtData, cookieConfig) {
-    return [
-        `auth=${await createUserJwt(userJwtData, cookieConfig.jwtParams)}`,
-        `Domain=${parseUrl(cookieConfig.hostOrigin).hostname}`,
-        'HttpOnly',
-        'Path=/',
-        'SameSite=Strict',
-        `MAX-AGE=${convertDuration(cookieConfig.cookieDuration, { seconds: true }).seconds}`,
-        cookieConfig.isDev ? '' : 'Secure',
-    ]
+export async function generateAuthCookie(userJwtData, cookieConfig) {
+    return generateCookie({
+        [cookieConfig.cookieName || 'auth']: await createUserJwt(userJwtData, cookieConfig.jwtParams),
+        Domain: parseUrl(cookieConfig.hostOrigin).hostname,
+        HttpOnly: true,
+        Path: '/',
+        SameSite: 'Strict',
+        'MAX-AGE': convertDuration(cookieConfig.cookieDuration, { seconds: true }).seconds,
+        Secure: !cookieConfig.isDev,
+    });
+}
+/**
+ * Generate a cookie value that will clear the previous auth cookie. Use this when signing out.
+ *
+ * @category Internal
+ */
+export function clearAuthCookie(cookieConfig) {
+    return generateCookie({
+        [cookieConfig.cookieName || 'auth']: 'redacted',
+        Domain: parseUrl(cookieConfig.hostOrigin).hostname,
+        HttpOnly: true,
+        Path: '/',
+        SameSite: 'Strict',
+        'MAX-AGE': 0,
+        Secure: !cookieConfig.isDev,
+    });
+}
+/**
+ * Generate a cookie string from a raw set of parameters.
+ *
+ * @category Internal
+ */
+export function generateCookie(params) {
+    return Object.entries(params)
+        .map(([key, value,]) => {
+        if (value == undefined || value === false) {
+            return undefined;
+        }
+        else if (value === '' || value === true) {
+            return key;
+        }
+        else {
+            return [
+                key,
+                value,
+            ].join('=');
+        }
+    })
         .filter(check.isTruthy)
         .join('; ');
 }

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "0.0.4",
+    "version": "1.1.0",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",
@@ -46,6 +46,7 @@
         "hash-wasm": "^4.12.0",
         "jose": "^6.0.11",
         "object-shape-tester": "^5.1.5",
+        "type-fest": "^4.41.0",
         "url-vir": "^2.1.3"
     },
     "devDependencies": {

package/src/auth.ts

@@ -1,4 +1,9 @@
-import {type CookieParams, extractCookieJwt, generateCookie} from './cookie.js';
+import {
+    clearAuthCookie,
+    type CookieParams,
+    extractCookieJwt,
+    generateAuthCookie,
+} from './cookie.js';
 import {csrfTokenHeaderName, generateCsrfToken} from './csrf-token.js';
 import {type ParseJwtParams} from './jwt.js';
 
@@ -63,14 +68,14 @@ export async function extractUserIdFromRequestHeaders(
  * @category Auth : Host
  */
 export async function generateSuccessfulLoginHeaders(
-    userId: string,
     /** The id from your database of the user you're authenticating. */
+    userId: string,
     cookieConfig: Readonly<CookieParams>,
 ) {
     const csrfToken = generateCsrfToken();
 
     return {
-        'set-cookie': await generateCookie(
+        'set-cookie': await generateAuthCookie(
             {
                 csrfToken,
                 userId,
@@ -81,6 +86,19 @@ export async function generateSuccessfulLoginHeaders(
     };
 }
 
+/**
+ * Used by host (backend) code to set headers on a response object when the user has logged out or
+ * failed to authorize.
+ *
+ * @category Auth : Host
+ */
+export function generateLogoutHeaders(...params: Parameters<typeof clearAuthCookie>) {
+    return {
+        'set-cookie': clearAuthCookie(...params),
+        [csrfTokenHeaderName]: 'redacted',
+    };
+}
+
 /**
  * Store auth data on a client (frontend) after receiving an auth response from the host (backend).
  * Specifically, this stores the CSRF token into local storage (which doesn't need to be a secret).

package/src/cookie.ts

@@ -1,12 +1,13 @@
 import {check} from '@augment-vir/assert';
 import {safeMatch, type PartialWithUndefined} from '@augment-vir/common';
 import {convertDuration, type AnyDuration} from 'date-vir';
+import {type Primitive} from 'type-fest';
 import {parseUrl} from 'url-vir';
 import {type CreateJwtParams, type ParseJwtParams} from './jwt.js';
 import {createUserJwt, parseUserJwt, type UserJwtData} from './user-jwt.js';
 
 /**
- * Parameters for {@link generateCookie}.
+ * Parameters for {@link generateAuthCookie}.
  *
  * @category Internal
  */
@@ -29,6 +30,7 @@ export type CookieParams = {
      * client, etc.
      */
     jwtParams: Readonly<CreateJwtParams>;
+    cookieName?: string;
 } & PartialWithUndefined<{
     /**
      * Is set to `true` (which should only be done in development environments), the cookie will be
@@ -44,19 +46,69 @@ export type CookieParams = {
  *
  * @category Internal
  */
-export async function generateCookie(
+export async function generateAuthCookie(
     userJwtData: Readonly<UserJwtData>,
     cookieConfig: Readonly<CookieParams>,
+): Promise<string> {
+    return generateCookie({
+        [cookieConfig.cookieName || 'auth']: await createUserJwt(
+            userJwtData,
+            cookieConfig.jwtParams,
+        ),
+        Domain: parseUrl(cookieConfig.hostOrigin).hostname,
+        HttpOnly: true,
+        Path: '/',
+        SameSite: 'Strict',
+        'MAX-AGE': convertDuration(cookieConfig.cookieDuration, {seconds: true}).seconds,
+        Secure: !cookieConfig.isDev,
+    });
+}
+
+/**
+ * Generate a cookie value that will clear the previous auth cookie. Use this when signing out.
+ *
+ * @category Internal
+ */
+export function clearAuthCookie(
+    cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>,
 ) {
-    return [
-        `auth=${await createUserJwt(userJwtData, cookieConfig.jwtParams)}`,
-        `Domain=${parseUrl(cookieConfig.hostOrigin).hostname}`,
-        'HttpOnly',
-        'Path=/',
-        'SameSite=Strict',
-        `MAX-AGE=${convertDuration(cookieConfig.cookieDuration, {seconds: true}).seconds}`,
-        cookieConfig.isDev ? '' : 'Secure',
-    ]
+    return generateCookie({
+        [cookieConfig.cookieName || 'auth']: 'redacted',
+        Domain: parseUrl(cookieConfig.hostOrigin).hostname,
+        HttpOnly: true,
+        Path: '/',
+        SameSite: 'Strict',
+        'MAX-AGE': 0,
+        Secure: !cookieConfig.isDev,
+    });
+}
+
+/**
+ * Generate a cookie string from a raw set of parameters.
+ *
+ * @category Internal
+ */
+export function generateCookie(
+    params: Readonly<Record<string, Exclude<Primitive, symbol>>>,
+): string {
+    return Object.entries(params)
+        .map(
+            ([
+                key,
+                value,
+            ]): string | undefined => {
+                if (value == undefined || value === false) {
+                    return undefined;
+                } else if (value === '' || value === true) {
+                    return key;
+                } else {
+                    return [
+                        key,
+                        value,
+                    ].join('=');
+                }
+            },
+        )
         .filter(check.isTruthy)
         .join('; ');
 }

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,
     });