auth-vir 3.1.2 → 5.0.0

package/src/cookie.ts

@@ -1,13 +1,11 @@
 import {check} from '@augment-vir/assert';
-import {escapeStringForRegExp, safeMatch, type PartialWithUndefined} from '@augment-vir/common';
 import {
-    calculateRelativeDate,
-    convertDuration,
-    getNowInUtcTimezone,
-    type AnyDuration,
-    type FullDate,
-    type UtcTimezone,
-} from 'date-vir';
+    escapeStringForRegExp,
+    safeMatch,
+    type PartialWithUndefined,
+    type SelectFrom,
+} 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, type ParsedJwt} from './jwt/jwt.js';
@@ -18,11 +16,13 @@ import {createUserJwt, parseUserJwt, type JwtUserData} from './jwt/user-jwt.js';
  *
  * @category Internal
  */
-export enum AuthCookieName {
+export enum AuthCookie {
     /** Used for a full user login auth. */
     Auth = 'auth',
     /** Use for a temporary "just signed up" auth. */
     SignUp = 'sign-up',
+    /** Used for storing the CSRF token. Not `HttpOnly` so that frontend JS can read it. */
+    Csrf = 'auth-vir-csrf',
 }
 
 /**
@@ -49,8 +49,13 @@ export type CookieParams = {
      * client, etc.
      */
     jwtParams: Readonly<CreateJwtParams>;
-    cookieName?: string;
 } & PartialWithUndefined<{
+    /**
+     * Which auth cookie name to use.
+     *
+     * @default AuthCookie.Auth
+     */
+    authCookie: AuthCookie;
     /**
      * Is set to `true` (which should only be done in development environments), the cookie will be
      * allowed in insecure requests (non HTTPS requests).
@@ -60,15 +65,32 @@ export type CookieParams = {
     isDev: boolean;
 }>;
 
-/**
- * Output from {@link generateAuthCookie}.
- *
- * @category Internal
- */
-export type GenerateAuthCookieResult = {
-    cookie: string;
-    expiration: FullDate<UtcTimezone>;
-};
+function generateSetCookie({
+    name,
+    value,
+    httpOnly,
+    cookieConfig,
+}: {
+    name: string;
+    value: string;
+    httpOnly: boolean;
+    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>> &
+        PartialWithUndefined<SelectFrom<CookieParams, {cookieDuration: true}>>;
+}): string {
+    return generateCookie({
+        [name]: value,
+        Domain: parseUrl(cookieConfig.hostOrigin).hostname,
+        HttpOnly: httpOnly,
+        Path: '/',
+        SameSite: 'Strict',
+        'MAX-AGE': cookieConfig.cookieDuration
+            ? convertDuration(cookieConfig.cookieDuration, {
+                  seconds: true,
+              }).seconds
+            : 0,
+        Secure: !cookieConfig.isDev,
+    });
+}
 
 /**
  * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
@@ -78,26 +100,41 @@ export type GenerateAuthCookieResult = {
 export async function generateAuthCookie(
     userJwtData: Readonly<JwtUserData>,
     cookieConfig: Readonly<CookieParams>,
-): Promise<GenerateAuthCookieResult> {
-    const expiration = calculateRelativeDate(getNowInUtcTimezone(), cookieConfig.cookieDuration);
+): Promise<string> {
+    return generateSetCookie({
+        name: cookieConfig.authCookie || AuthCookie.Auth,
+        value: await createUserJwt(userJwtData, cookieConfig.jwtParams),
+        httpOnly: true,
+        cookieConfig,
+    });
+}
 
-    return {
-        cookie: 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,
-        }),
-        expiration,
-    };
+/**
+ * Generate a CSRF token cookie. This cookie is intentionally not `HttpOnly` so that frontend
+ * JavaScript can read it and inject the value as a request header for double-submit verification.
+ *
+ * The CSRF cookie uses a fixed 400-day MAX-AGE rather than matching the auth cookie duration. 400
+ * days is the cross-browser safe maximum (Chrome caps cookie lifetimes at 400 days; other browsers
+ * accept it as-is). The CSRF token is only meaningful when paired with a valid JWT, so it doesn't
+ * need its own expiration management. It gets regenerated on every fresh login.
+ *
+ * @category Internal
+ */
+export function generateCsrfCookie(
+    csrfToken: string,
+    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>>,
+): string {
+    return generateSetCookie({
+        name: AuthCookie.Csrf,
+        value: csrfToken,
+        httpOnly: false,
+        cookieConfig: {
+            ...cookieConfig,
+            cookieDuration: {
+                days: 400,
+            },
+        },
+    });
 }
 
 /**
@@ -106,16 +143,30 @@ export async function generateAuthCookie(
  * @category Internal
  */
 export function clearAuthCookie(
-    cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>,
+    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>> &
+        PartialWithUndefined<{authCookie: AuthCookie}>,
 ) {
-    return generateCookie({
-        [cookieConfig.cookieName || 'auth']: 'redacted',
-        Domain: parseUrl(cookieConfig.hostOrigin).hostname,
-        HttpOnly: true,
-        Path: '/',
-        SameSite: 'Strict',
-        'MAX-AGE': 0,
-        Secure: !cookieConfig.isDev,
+    return generateSetCookie({
+        name: cookieConfig.authCookie || AuthCookie.Auth,
+        value: 'redacted',
+        httpOnly: true,
+        cookieConfig,
+    });
+}
+
+/**
+ * Generate a cookie value that will clear the CSRF token cookie. Use this when signing out.
+ *
+ * @category Internal
+ */
+export function clearCsrfCookie(
+    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>>,
+) {
+    return generateSetCookie({
+        name: AuthCookie.Csrf,
+        value: 'redacted',
+        httpOnly: false,
+        cookieConfig,
     });
 }
 
@@ -158,7 +209,7 @@ export function generateCookie(
 export async function extractCookieJwt(
     rawCookie: string,
     jwtParams: Readonly<ParseJwtParams>,
-    cookieName: string = AuthCookieName.Auth,
+    cookieName: AuthCookie,
 ): Promise<undefined | ParsedJwt<JwtUserData>> {
     const cookieRegExp = new RegExp(`${escapeStringForRegExp(cookieName)}=[^;]+(?:;|$)`);
 

package/src/csrf-token.ts

@@ -1,75 +1,15 @@
-import {
-    randomString,
-    wrapInTry,
-    type PartialWithUndefined,
-    type SelectFrom,
-} from '@augment-vir/common';
-import {
-    calculateRelativeDate,
-    fullDateShape,
-    getNowInUtcTimezone,
-    isDateAfter,
-    type AnyDuration,
-} from 'date-vir';
-import {defineShape, parseJsonWithShape} from 'object-shape-tester';
+import {check} from '@augment-vir/assert';
+import {escapeStringForRegExp, randomString, safeMatch} from '@augment-vir/common';
 import {type RequireExactlyOne} from 'type-fest';
-import {getDefaultCsrfTokenStore, type CsrfTokenStore} from './csrf-token-store.js';
+import {AuthCookie} from './cookie.js';
 
 /**
- * Shape definition for {@link CsrfToken}.
+ * Generates a random, cryptographically secure CSRF token string.
  *
  * @category Internal
  */
-export const csrfTokenShape = defineShape({
-    token: '',
-    expiration: fullDateShape,
-});
-
-/**
- * A cryptographically CSRF token with expiration date.
- *
- * @category Internal
- */
-export type CsrfToken = typeof csrfTokenShape.runtimeType;
-
-/**
- * Default allowed clock skew for CSRF token expiration checks. Accounts for differences between
- * server and client clocks when checking token expiration.
- *
- * @category Internal
- * @default {minutes: 5}
- */
-export const defaultAllowedClockSkew: Readonly<AnyDuration> = {
-    minutes: 5,
-};
-
-/**
- * Generates a random, cryptographically secure CSRF token.
- *
- * @category Internal
- */
-export function generateCsrfToken(
-    /** How long the CSRF token is valid for. */
-    duration: Readonly<AnyDuration>,
-): CsrfToken {
-    return {
-        token: randomString(256),
-        expiration: calculateRelativeDate(getNowInUtcTimezone(), duration),
-    };
-}
-
-/**
- * CSRF token failure reasons for {@link GetCsrfTokenResult}.
- *
- * @category Internal
- */
-export enum CsrfTokenFailureReason {
-    /** No CSRF token was found. */
-    DoesNotExist = 'does-not-exist',
-    /** A CSRF token was found but parsing it failed. */
-    ParseFailed = 'parse-failed',
-    /** A CSRF token was found and parsed but is expired. */
-    Expired = 'expired',
+export function generateCsrfToken(): string {
+    return randomString(256);
 }
 
 /**
@@ -91,181 +31,31 @@ export type CsrfHeaderNameOption = RequireExactlyOne<{
  * @category Auth : Client
  * @category Auth : Host
  */
-export function resolveCsrfHeaderName(option: Readonly<CsrfHeaderNameOption>): string {
-    if ('csrfHeaderName' in option && option.csrfHeaderName) {
-        return option.csrfHeaderName;
+export function resolveCsrfHeaderName(options: Readonly<CsrfHeaderNameOption>): string {
+    if ('csrfHeaderName' in options && options.csrfHeaderName) {
+        return options.csrfHeaderName;
     } else {
         return [
-            option.csrfHeaderPrefix,
+            options.csrfHeaderPrefix,
             'auth-vir',
             'csrf-token',
-        ].join('-');
-    }
-}
-
-/**
- * Output from {@link getCurrentCsrfToken}.
- *
- * @category Internal
- */
-export type GetCsrfTokenResult = RequireExactlyOne<{
-    csrfToken: Readonly<CsrfToken>;
-    failure: CsrfTokenFailureReason;
-}>;
-
-/**
- * Extract the CSRF token header from a response.
- *
- * @category Auth : Client
- */
-export function extractCsrfTokenHeader(
-    response: Readonly<PartialWithUndefined<SelectFrom<Response, {headers: true}>>>,
-    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>,
-    options?: PartialWithUndefined<{
-        /**
-         * Allowed clock skew tolerance for CSRF token expiration checks.
-         *
-         * @default {minutes: 5}
-         */
-        allowedClockSkew: Readonly<AnyDuration>;
-    }>,
-): Readonly<GetCsrfTokenResult> {
-    const csrfTokenHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
-
-    const rawCsrfToken = response.headers?.get(csrfTokenHeaderName);
-
-    return parseCsrfToken(rawCsrfToken, options);
-}
-
-/**
- * Stores the given CSRF token into IndexedDB.
- *
- * @category Auth : Client
- */
-export async function storeCsrfToken(
-    csrfToken: Readonly<CsrfToken>,
-    options: Readonly<CsrfHeaderNameOption> &
-        PartialWithUndefined<{
-            /**
-             * Allows mocking or overriding the default CSRF token store.
-             *
-             * @default getDefaultCsrfTokenStore()
-             */
-            csrfTokenStore: CsrfTokenStore;
-        }>,
-): Promise<void> {
-    await (options.csrfTokenStore || (await getDefaultCsrfTokenStore())).setCsrfToken(
-        JSON.stringify(csrfToken),
-    );
-}
-
-/**
- * Parse a raw CSRF token JSON string.
- *
- * @category Internal
- */
-export function parseCsrfToken(
-    value: string | undefined | null,
-    options?: PartialWithUndefined<{
-        /**
-         * Allowed clock skew tolerance for CSRF token expiration checks. Accounts for differences
-         * between server and client clocks.
-         *
-         * @default {minutes: 5}
-         */
-        allowedClockSkew: Readonly<AnyDuration>;
-    }>,
-): Readonly<GetCsrfTokenResult> {
-    if (!value) {
-        return {
-            failure: CsrfTokenFailureReason.DoesNotExist,
-        };
-    }
-
-    const csrfToken: CsrfToken | undefined = wrapInTry(
-        () =>
-            parseJsonWithShape(value, csrfTokenShape, {
-                /** For forwards / backwards compatibility. */
-                allowExtraKeys: true,
-            }),
-        {
-            fallbackValue: undefined,
-        },
-    );
-
-    if (!csrfToken) {
-        return {
-            failure: CsrfTokenFailureReason.ParseFailed,
-        };
+        ]
+            .filter(check.isTruthy)
+            .join('-');
     }
-
-    const effectiveExpiration = calculateRelativeDate(
-        csrfToken.expiration,
-        options?.allowedClockSkew || defaultAllowedClockSkew,
-    );
-
-    if (
-        isDateAfter({
-            fullDate: getNowInUtcTimezone(),
-            relativeTo: effectiveExpiration,
-        })
-    ) {
-        return {
-            failure: CsrfTokenFailureReason.Expired,
-        };
-    }
-
-    return {
-        csrfToken,
-    };
-}
-
-/**
- * Used in client (frontend) code to retrieve the current CSRF token in order to send it with
- * requests to the host (backend).
- *
- * @category Auth : Client
- */
-export async function getCurrentCsrfToken(
-    options: Readonly<CsrfHeaderNameOption> &
-        PartialWithUndefined<{
-            /**
-             * Allows mocking or overriding the default CSRF token store.
-             *
-             * @default getDefaultCsrfTokenStore()
-             */
-            csrfTokenStore: CsrfTokenStore;
-            /**
-             * Allowed clock skew tolerance for CSRF token expiration checks.
-             *
-             * @default {minutes: 5}
-             */
-            allowedClockSkew: Readonly<AnyDuration>;
-        }>,
-): Promise<Readonly<GetCsrfTokenResult>> {
-    const rawCsrfToken: string | undefined =
-        (await (options.csrfTokenStore || (await getDefaultCsrfTokenStore())).getCsrfToken()) ||
-        undefined;
-
-    return parseCsrfToken(rawCsrfToken, options);
 }
 
 /**
- * Wipes the current stored CSRF token. This should be used by client (frontend) code to react to a
- * session timeout.
+ * Used in client (frontend) code to retrieve the current CSRF token from the browser cookie in
+ * order to send it with requests to the host (backend).
  *
  * @category Auth : Client
  */
-export async function wipeCurrentCsrfToken(
-    options: Readonly<CsrfHeaderNameOption> &
-        PartialWithUndefined<{
-            /**
-             * Allows mocking or overriding the default CSRF token store.
-             *
-             * @default getDefaultCsrfTokenStore()
-             */
-            csrfTokenStore: CsrfTokenStore;
-        }>,
-): Promise<void> {
-    await (options.csrfTokenStore || (await getDefaultCsrfTokenStore())).deleteCsrfToken();
+export function getCurrentCsrfToken(): string | undefined {
+    const cookieRegExp = new RegExp(`${escapeStringForRegExp(AuthCookie.Csrf)}=([^;]+)`);
+    const [
+        ,
+        value,
+    ] = safeMatch(globalThis.document.cookie, cookieRegExp);
+    return value || undefined;
 }

package/src/index.ts

@@ -3,11 +3,9 @@ export * from './auth-client/frontend-auth.client.js';
 export * from './auth-client/is-session-refresh-ready.js';
 export * from './auth.js';
 export * from './cookie.js';
-export * from './csrf-token-store.js';
 export * from './csrf-token.js';
 export * from './hash.js';
 export * from './headers.js';
 export * from './jwt/jwt-keys.js';
 export * from './jwt/jwt.js';
 export * from './jwt/user-jwt.js';
-export * from './mock-csrf-token-store.js';

package/src/jwt/jwt.ts

@@ -1,5 +1,5 @@
 import {assertWrap, check} from '@augment-vir/assert';
-import {type AnyObject, type PartialWithUndefined} from '@augment-vir/common';
+import {type AnyObject, type PartialWithUndefined, type SelectFrom} from '@augment-vir/common';
 import {
     type AnyDuration,
     calculateRelativeDate,
@@ -13,7 +13,6 @@ import {
     type UtcTimezone,
 } from 'date-vir';
 import {EncryptJWT, jwtDecrypt, jwtVerify, SignJWT} from 'jose';
-import {defaultAllowedClockSkew} from '../csrf-token.js';
 import {type JwtKeys} from './jwt-keys.js';
 
 const encryptionProtectedHeader = {
@@ -24,6 +23,17 @@ const signingProtectedHeader = {
     alg: 'HS512',
 };
 
+/**
+ * Default allowed clock skew for JWT expiration checks. Accounts for differences between server and
+ * client clocks.
+ *
+ * @category Internal
+ * @default {minutes: 5}
+ */
+export const defaultAllowedClockSkew: Readonly<AnyDuration> = {
+    minutes: 5,
+};
+
 /**
  * Params for {@link createJwt}.
  *
@@ -148,7 +158,9 @@ export async function createJwt<JwtData extends AnyObject = AnyObject>(
  *
  * @category Internal
  */
-export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience' | 'jwtKeys'>> &
+export type ParseJwtParams = Readonly<
+    SelectFrom<CreateJwtParams, {issuer: true; audience: true; jwtKeys: true}>
+> &
     PartialWithUndefined<{
         /**
          * Allowed clock skew tolerance for JWT expiration and timestamp checks. Accounts for

package/dist/csrf-token-store.d.ts

@@ -1,21 +0,0 @@
-/**
- * The interface used for overriding the default CSRF token store in storage functions.
- *
- * @category Internal
- */
-export type CsrfTokenStore = {
-    /** Retrieves the stored CSRF token, if any. */
-    getCsrfToken(): Promise<string | undefined>;
-    /** Stores a CSRF token. */
-    setCsrfToken(value: string): Promise<void>;
-    /** Deletes the stored CSRF token. */
-    deleteCsrfToken(): Promise<void>;
-};
-/**
- * The default {@link LocalDbClient} instance used for storing CSRF tokens. This uses a dedicated
- * store name to avoid collisions with other storage. Lazily initialized to avoid crashes in Node.js
- * environments where IndexedDB is not available.
- *
- * @category Internal
- */
-export declare function getDefaultCsrfTokenStore(): Promise<CsrfTokenStore>;

package/dist/csrf-token-store.js

@@ -1,35 +0,0 @@
-import { LocalDbClient } from 'local-db-client';
-import { defineShape } from 'object-shape-tester';
-const csrfTokenDbShapes = {
-    csrfToken: defineShape(''),
-};
-async function createDefaultCsrfTokenStore() {
-    const client = await LocalDbClient.createClient(csrfTokenDbShapes, {
-        storeName: 'auth-vir-csrf',
-    });
-    return {
-        async getCsrfToken() {
-            return (await client.load.csrfToken()) || undefined;
-        },
-        async setCsrfToken(value) {
-            await client.set.csrfToken(value);
-        },
-        async deleteCsrfToken() {
-            await client.delete.csrfToken();
-        },
-    };
-}
-/**
- * The default {@link LocalDbClient} instance used for storing CSRF tokens. This uses a dedicated
- * store name to avoid collisions with other storage. Lazily initialized to avoid crashes in Node.js
- * environments where IndexedDB is not available.
- *
- * @category Internal
- */
-export async function getDefaultCsrfTokenStore() {
-    if (!cachedStorePromise) {
-        cachedStorePromise = createDefaultCsrfTokenStore();
-    }
-    return cachedStorePromise;
-}
-let cachedStorePromise;

package/dist/mock-csrf-token-store.d.ts

@@ -1,64 +0,0 @@
-import { type CsrfTokenStore } from './csrf-token-store.js';
-/**
- * `accessRecord` type for {@link createMockLocalStorage}'s output.
- *
- * @category Internal
- */
-export type MockLocalStorageAccessRecord = {
-    getItem: string[];
-    removeItem: string[];
-    setItem: {
-        key: string;
-        value: string;
-    }[];
-    key: number[];
-};
-/**
- * Create an empty `accessRecord` object, this is to be used in conjunction with
- * {@link createMockLocalStorage}.
- *
- * @category Mock
- */
-export declare function createEmptyMockLocalStorageAccessRecord(): MockLocalStorageAccessRecord;
-/**
- * Create a LocalStorage mock.
- *
- * @category Mock
- */
-export declare function createMockLocalStorage(
-/** Set values in here to initialize the mocked localStorage data store contents. */
-init?: Record<string, string>): {
-    localStorage: Storage;
-    store: Record<string, string>;
-    accessRecord: MockLocalStorageAccessRecord;
-};
-/**
- * `accessRecord` type for {@link createMockCsrfTokenStore}'s output.
- *
- * @category Internal
- */
-export type MockCsrfTokenStoreAccessRecord = {
-    getCsrfToken: number;
-    setCsrfToken: string[];
-    deleteCsrfToken: number;
-};
-/**
- * Create an empty `accessRecord` object, this is to be used in conjunction with
- * {@link createMockCsrfTokenStore}.
- *
- * @category Mock
- */
-export declare function createEmptyMockCsrfTokenStoreAccessRecord(): MockCsrfTokenStoreAccessRecord;
-/**
- * Create a mock {@link CsrfTokenStore} backed by a simple in-memory object, for use in tests.
- *
- * @category Mock
- */
-export declare function createMockCsrfTokenStore(
-/** Set an initial value to initialize the mocked store contents. */
-init?: string | undefined): {
-    csrfTokenStore: CsrfTokenStore;
-    /** The current value held in the mock store. */
-    readonly storedValue: string | undefined;
-    accessRecord: MockCsrfTokenStoreAccessRecord;
-};