auth-vir 1.0.0 → 1.2.0

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}.
@@ -14,18 +14,28 @@ export type HeaderContainer = Record<string, string[] | undefined | string | num
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export declare function extractUserIdFromRequestHeaders(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>): Promise<string | undefined>;
+export declare function extractUserIdFromRequestHeaders(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, cookieName?: string | undefined): Promise<string | undefined>;
 /**
  * Used by host (backend) code to set headers on a response object.
  *
  * @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) {
@@ -25,14 +25,14 @@ function readHeader(headers, headerName) {
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export async function extractUserIdFromRequestHeaders(headers, jwtParams) {
+export async function extractUserIdFromRequestHeaders(headers, jwtParams, cookieName) {
     try {
         const csrfToken = readHeader(headers, csrfTokenHeaderName);
         const cookie = readHeader(headers, 'cookie');
         if (!cookie || !csrfToken) {
             return undefined;
         }
-        const jwt = await extractCookieJwt(cookie, jwtParams);
+        const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
         if (!jwt || jwt.csrfToken !== csrfToken) {
             return undefined;
         }
@@ -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,11 +42,23 @@ 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.
  *
  * @category Internal
  * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
  */
-export declare function extractCookieJwt(rawCookie: string, jwtParams: Readonly<ParseJwtParams>): Promise<undefined | UserJwtData>;
+export declare function extractCookieJwt(rawCookie: string, jwtParams: Readonly<ParseJwtParams>, cookieName?: string): Promise<undefined | UserJwtData>;

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('; ');
 }
@@ -27,8 +65,9 @@ export async function generateCookie(userJwtData, cookieConfig) {
  * @category Internal
  * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
  */
-export async function extractCookieJwt(rawCookie, jwtParams) {
-    const [auth] = safeMatch(rawCookie, /auth=[^;]+(?:;|$)/);
+export async function extractCookieJwt(rawCookie, jwtParams, cookieName = 'auth') {
+    const cookieRegExp = new RegExp(`${cookieName}=[^;]+(?:;|$)`);
+    const [auth] = safeMatch(rawCookie, cookieRegExp);
     if (!auth) {
         return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "1.0.0",
+    "version": "1.2.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';
 
@@ -36,6 +41,7 @@ function readHeader(headers: HeaderContainer, headerName: string): string | unde
 export async function extractUserIdFromRequestHeaders(
     headers: HeaderContainer,
     jwtParams: Readonly<ParseJwtParams>,
+    cookieName?: string | undefined,
 ): Promise<string | undefined> {
     try {
         const csrfToken = readHeader(headers, csrfTokenHeaderName);
@@ -45,7 +51,7 @@ export async function extractUserIdFromRequestHeaders(
             return undefined;
         }
 
-        const jwt = await extractCookieJwt(cookie, jwtParams);
+        const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
 
         if (!jwt || jwt.csrfToken !== csrfToken) {
             return undefined;
@@ -63,14 +69,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 +87,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('; ');
 }
@@ -70,8 +122,11 @@ export async function generateCookie(
 export async function extractCookieJwt(
     rawCookie: string,
     jwtParams: Readonly<ParseJwtParams>,
+    cookieName: string = 'auth',
 ): Promise<undefined | UserJwtData> {
-    const [auth] = safeMatch(rawCookie, /auth=[^;]+(?:;|$)/);
+    const cookieRegExp = new RegExp(`${cookieName}=[^;]+(?:;|$)`);
+
+    const [auth] = safeMatch(rawCookie, cookieRegExp);
 
     if (!auth) {
         return undefined;