auth-vir 2.7.2 → 3.0.1

package/src/cookie.ts

@@ -1,6 +1,13 @@
 import {check} from '@augment-vir/assert';
-import {safeMatch, type PartialWithUndefined} from '@augment-vir/common';
-import {convertDuration, type AnyDuration} from 'date-vir';
+import {escapeStringForRegExp, safeMatch, type PartialWithUndefined} from '@augment-vir/common';
+import {
+    calculateRelativeDate,
+    convertDuration,
+    getNowInUtcTimezone,
+    type AnyDuration,
+    type FullDate,
+    type UtcTimezone,
+} 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';
@@ -53,6 +60,16 @@ export type CookieParams = {
     isDev: boolean;
 }>;
 
+/**
+ * Output from {@link generateAuthCookie}.
+ *
+ * @category Internal
+ */
+export type GenerateAuthCookieResult = {
+    cookie: string;
+    expiration: FullDate<UtcTimezone>;
+};
+
 /**
  * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
  *
@@ -61,19 +78,24 @@ export type CookieParams = {
 export async function generateAuthCookie(
     userJwtData: Readonly<JwtUserData>,
     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,
-    });
+): Promise<GenerateAuthCookieResult> {
+    const expiration = calculateRelativeDate(getNowInUtcTimezone(), cookieConfig.cookieDuration);
+
+    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,
+    };
 }
 
 /**
@@ -136,7 +158,7 @@ export async function extractCookieJwt(
     jwtParams: Readonly<ParseJwtParams>,
     cookieName: string = AuthCookieName.Auth,
 ): Promise<undefined | ParsedJwt<JwtUserData>> {
-    const cookieRegExp = new RegExp(`${cookieName}=[^;]+(?:;|$)`);
+    const cookieRegExp = new RegExp(`${escapeStringForRegExp(cookieName)}=[^;]+(?:;|$)`);
 
     const [cookieValue] = safeMatch(rawCookie, cookieRegExp);
 

package/src/csrf-token.ts

@@ -13,8 +13,6 @@ import {
 } from 'date-vir';
 import {defineShape, parseJsonWithShape} from 'object-shape-tester';
 import {type RequireExactlyOne} from 'type-fest';
-import {AuthHeaderName} from './headers.js';
-import {authLog} from './log.js';
 
 /**
  * Shape definition for {@link CsrfToken}.
@@ -33,6 +31,15 @@ export const csrfTokenShape = defineShape({
  */
 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.
  *
@@ -62,6 +69,37 @@ export enum CsrfTokenFailureReason {
     Expired = 'expired',
 }
 
+/**
+ * Options for specifying the CSRF token header name.
+ *
+ * @category Auth : Client
+ * @category Auth : Host
+ */
+export type CsrfHeaderNameOption = RequireExactlyOne<{
+    /** Prefix used to generate the header name: `${prefix}-auth-vir-csrf-token`. */
+    csrfHeaderPrefix: string;
+    /** Overrides the entire CSRF header name. */
+    csrfHeaderName: string;
+}>;
+
+/**
+ * Resolves a {@link CsrfHeaderNameOption} to the actual header name string.
+ *
+ * @category Auth : Client
+ * @category Auth : Host
+ */
+export function resolveCsrfHeaderName(option: Readonly<CsrfHeaderNameOption>): string {
+    if ('csrfHeaderName' in option && option.csrfHeaderName) {
+        return option.csrfHeaderName;
+    } else {
+        return [
+            option.csrfHeaderPrefix,
+            'auth-vir',
+            'csrf-token',
+        ].join('-');
+    }
+}
+
 /**
  * Output from {@link getCurrentCsrfToken}.
  *
@@ -79,15 +117,21 @@ export type GetCsrfTokenResult = RequireExactlyOne<{
  */
 export function extractCsrfTokenHeader(
     response: Readonly<PartialWithUndefined<SelectFrom<Response, {headers: true}>>>,
-    overrides: PartialWithUndefined<{
-        csrfHeaderName: string;
-    }> = {},
+    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>,
+    options?: PartialWithUndefined<{
+        /**
+         * Allowed clock skew tolerance for CSRF token expiration checks.
+         *
+         * @default {minutes: 5}
+         */
+        allowedClockSkew: Readonly<AnyDuration>;
+    }>,
 ): Readonly<GetCsrfTokenResult> {
-    const csrfTokenHeaderName = overrides.csrfHeaderName || AuthHeaderName.CsrfToken;
+    const csrfTokenHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
 
     const rawCsrfToken = response.headers?.get(csrfTokenHeaderName);
 
-    return parseCsrfToken(rawCsrfToken);
+    return parseCsrfToken(rawCsrfToken, options);
 }
 
 /**
@@ -97,19 +141,18 @@ export function extractCsrfTokenHeader(
  */
 export function storeCsrfToken(
     csrfToken: Readonly<CsrfToken>,
-    overrides: PartialWithUndefined<{
-        /**
-         * Allows mocking or overriding the global `localStorage`.
-         *
-         * @default globalThis.localStorage
-         */
-        localStorage: Pick<Storage, 'setItem' | 'removeItem'>;
-        /** Override the default CSRF token header name. */
-        csrfHeaderName: string;
-    }> = {},
+    options: Readonly<CsrfHeaderNameOption> &
+        PartialWithUndefined<{
+            /**
+             * Allows mocking or overriding the global `localStorage`.
+             *
+             * @default globalThis.localStorage
+             */
+            localStorage: Pick<Storage, 'setItem' | 'removeItem'>;
+        }>,
 ) {
-    (overrides.localStorage || globalThis.localStorage).setItem(
-        overrides.csrfHeaderName || AuthHeaderName.CsrfToken,
+    (options.localStorage || globalThis.localStorage).setItem(
+        resolveCsrfHeaderName(options),
         JSON.stringify(csrfToken),
     );
 }
@@ -119,7 +162,18 @@ export function storeCsrfToken(
  *
  * @category Internal
  */
-export function parseCsrfToken(value: string | undefined | null): Readonly<GetCsrfTokenResult> {
+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,
@@ -143,10 +197,15 @@ export function parseCsrfToken(value: string | undefined | null): Readonly<GetCs
         };
     }
 
+    const effectiveExpiration = calculateRelativeDate(
+        csrfToken.expiration,
+        options?.allowedClockSkew || defaultAllowedClockSkew,
+    );
+
     if (
         isDateAfter({
             fullDate: getNowInUtcTimezone(),
-            relativeTo: csrfToken.expiration,
+            relativeTo: effectiveExpiration,
         })
     ) {
         return {
@@ -166,23 +225,27 @@ export function parseCsrfToken(value: string | undefined | null): Readonly<GetCs
  * @category Auth : Client
  */
 export function getCurrentCsrfToken(
-    overrides: PartialWithUndefined<{
-        /**
-         * Allows mocking or overriding the global `localStorage`.
-         *
-         * @default globalThis.localStorage
-         */
-        localStorage: Pick<Storage, 'getItem'>;
-        /** Override the default CSRF token header name. */
-        csrfHeaderName: string;
-    }> = {},
+    options: Readonly<CsrfHeaderNameOption> &
+        PartialWithUndefined<{
+            /**
+             * Allows mocking or overriding the global `localStorage`.
+             *
+             * @default globalThis.localStorage
+             */
+            localStorage: Pick<Storage, 'getItem'>;
+            /**
+             * Allowed clock skew tolerance for CSRF token expiration checks.
+             *
+             * @default {minutes: 5}
+             */
+            allowedClockSkew: Readonly<AnyDuration>;
+        }>,
 ): Readonly<GetCsrfTokenResult> {
     const rawCsrfToken: string | undefined =
-        (overrides.localStorage || globalThis.localStorage).getItem(
-            overrides.csrfHeaderName || AuthHeaderName.CsrfToken,
-        ) || undefined;
+        (options.localStorage || globalThis.localStorage).getItem(resolveCsrfHeaderName(options)) ||
+        undefined;
 
-    return parseCsrfToken(rawCsrfToken);
+    return parseCsrfToken(rawCsrfToken, options);
 }
 
 /**
@@ -192,19 +255,17 @@ export function getCurrentCsrfToken(
  * @category Auth : Client
  */
 export function wipeCurrentCsrfToken(
-    overrides: PartialWithUndefined<{
-        /**
-         * Allows mocking or overriding the global `localStorage`.
-         *
-         * @default globalThis.localStorage
-         */
-        localStorage: Pick<Storage, 'removeItem'>;
-        /** Override the default CSRF token header name. */
-        csrfHeaderName: string;
-    }> = {},
+    options: Readonly<CsrfHeaderNameOption> &
+        PartialWithUndefined<{
+            /**
+             * Allows mocking or overriding the global `localStorage`.
+             *
+             * @default globalThis.localStorage
+             */
+            localStorage: Pick<Storage, 'removeItem'>;
+        }>,
 ) {
-    authLog('auth-vir: wipeCurrentCsrfToken called', new Error().stack);
-    return (overrides.localStorage || globalThis.localStorage).removeItem(
-        overrides.csrfHeaderName || AuthHeaderName.CsrfToken,
+    return (options.localStorage || globalThis.localStorage).removeItem(
+        resolveCsrfHeaderName(options),
     );
 }

package/src/hash.ts

@@ -1,3 +1,4 @@
+import {assertWrap} from '@augment-vir/assert';
 import {
     type AnyObject,
     mergeDefinedProperties,
@@ -12,8 +13,8 @@ import {argon2id, argon2Verify, type IArgon2Options} from 'hash-wasm';
  */
 export const defaultHashOptions: HashPasswordOptions = {
     hashLength: 32,
-    iterations: 256,
-    memorySize: 512,
+    iterations: 2,
+    memorySize: 19_456,
     parallelism: 1,
 };
 
@@ -41,13 +42,15 @@ export async function hashPassword(
 ): Promise<string> {
     const salt = globalThis.crypto.getRandomValues(new Uint8Array(16));
 
-    return await argon2id(
+    const hash = await argon2id(
         mergeDefinedProperties<AnyObject>(defaultHashOptions, options, {
             outputType: 'encoded',
             password: password.normalize(),
             salt,
         }) as IArgon2Options,
     );
+
+    return assertWrap.isTruthy(hash);
 }
 
 /**
@@ -76,6 +79,6 @@ export async function doesPasswordMatchHash({
 }): Promise<boolean> {
     return await argon2Verify({
         hash,
-        password,
+        password: password.normalize(),
     });
 }

package/src/headers.ts

@@ -6,7 +6,6 @@ import {check} from '@augment-vir/assert';
  * @category Internal
  */
 export enum AuthHeaderName {
-    CsrfToken = 'csrf-token',
     AssumedUser = 'assumed-user',
     /**
      * Used to track if the current user is signed in only with a sign-up cookie, which prevents us

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './auth-client/backend-auth.client.js';
 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.js';
@@ -8,5 +9,4 @@ export * from './headers.js';
 export * from './jwt/jwt-keys.js';
 export * from './jwt/jwt.js';
 export * from './jwt/user-jwt.js';
-export * from './log.js';
 export * from './mock-local-storage.js';

package/src/jwt/jwt.ts

@@ -3,6 +3,7 @@ import {type AnyObject, type PartialWithUndefined} from '@augment-vir/common';
 import {
     type AnyDuration,
     calculateRelativeDate,
+    convertDuration,
     createFullDateInUserTimezone,
     createUtcFullDate,
     type DateLike,
@@ -12,6 +13,7 @@ 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 = {alg: 'dir', enc: 'A256GCM'};
@@ -137,7 +139,16 @@ export async function createJwt<JwtData extends AnyObject = AnyObject>(
  *
  * @category Internal
  */
-export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience' | 'jwtKeys'>>;
+export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience' | 'jwtKeys'>> &
+    PartialWithUndefined<{
+        /**
+         * Allowed clock skew tolerance for JWT expiration and timestamp checks. Accounts for
+         * differences between server and client clocks.
+         *
+         * @default {minutes: 5}
+         */
+        allowedClockSkew: Readonly<AnyDuration>;
+    }>;
 
 /**
  * A fully parsed JWT with embedded data.
@@ -147,6 +158,8 @@ export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience
 export type ParsedJwt<JwtData extends AnyObject> = {
     data: JwtData;
     jwtExpiration: FullDate<UtcTimezone>;
+    /** When the JWT was issued (`iat` claim). */
+    jwtIssuedAt: FullDate<UtcTimezone>;
 };
 
 /**
@@ -167,6 +180,11 @@ export async function parseJwt<JwtData extends AnyObject = AnyObject>(
         throw new TypeError('Decrypted jwt is not a string.');
     }
 
+    const clockToleranceSeconds = convertDuration(
+        params.allowedClockSkew || defaultAllowedClockSkew,
+        {seconds: true},
+    ).seconds;
+
     const verifiedJwt = await jwtVerify(decryptedJwt.payload.jwt, params.jwtKeys.signingKey, {
         issuer: params.issuer,
         audience: params.audience,
@@ -175,9 +193,13 @@ export async function parseJwt<JwtData extends AnyObject = AnyObject>(
             'aud',
             'iss',
         ],
+        clockTolerance: clockToleranceSeconds,
     });
 
-    if (!verifiedJwt.payload.iat || verifiedJwt.payload.iat * 1000 > Date.now()) {
+    if (
+        !verifiedJwt.payload.iat ||
+        verifiedJwt.payload.iat * 1000 > Date.now() + clockToleranceSeconds * 1000
+    ) {
         throw new Error('"iat" claim timestamp check failed');
     }
 
@@ -187,15 +209,18 @@ export async function parseJwt<JwtData extends AnyObject = AnyObject>(
         throw new Error('Invalid signing protected header.');
     }
 
+    const issuedAtSeconds = assertWrap.isDefined(verifiedJwt.payload.iat, 'JWT has no issued at.');
     const expirationSeconds = assertWrap.isDefined(
         verifiedJwt.payload.exp,
         'JWT has no expiration.',
     );
 
+    const jwtIssuedAt: FullDate<UtcTimezone> = parseJwtTimestamp(issuedAtSeconds);
     const jwtExpiration: FullDate<UtcTimezone> = parseJwtTimestamp(expirationSeconds);
 
     return {
         data: data as JwtData,
         jwtExpiration,
+        jwtIssuedAt,
     };
 }

package/src/jwt/user-jwt.ts

@@ -62,7 +62,7 @@ export async function parseUserJwt(
     encryptedJwt: string,
     params: Readonly<ParseJwtParams>,
 ): Promise<ParsedJwt<JwtUserData> | undefined> {
-    const {data, jwtExpiration} = await parseJwt(encryptedJwt, params);
+    const {data, jwtExpiration, jwtIssuedAt} = await parseJwt(encryptedJwt, params);
 
     if (!checkValidShape(data, userJwtDataShape)) {
         throw new TypeError('Verified jwt has wrong data.');
@@ -71,5 +71,6 @@ export async function parseUserJwt(
     return {
         data,
         jwtExpiration,
+        jwtIssuedAt,
     };
 }

package/dist/log.d.ts

@@ -1,12 +0,0 @@
-/**
- * Send logs to the console for debugging.
- *
- * @category Internal
- */
-export declare function authLog(...params: any[]): void;
-/**
- * Set to `false` to disable logging.
- *
- * @category Internal
- */
-export declare function setShouldLogAuth(value: boolean): void;

package/dist/log.js

@@ -1,20 +0,0 @@
-/**
- * Send logs to the console for debugging.
- *
- * @category Internal
- */
-export function authLog(...params) {
-    if (!shouldLogAuth) {
-        return;
-    }
-    console.info(...params);
-}
-let shouldLogAuth = true;
-/**
- * Set to `false` to disable logging.
- *
- * @category Internal
- */
-export function setShouldLogAuth(value) {
-    shouldLogAuth = value;
-}

package/src/log.ts

@@ -1,22 +0,0 @@
-/**
- * Send logs to the console for debugging.
- *
- * @category Internal
- */
-export function authLog(...params: any[]) {
-    if (!shouldLogAuth) {
-        return;
-    }
-    console.info(...params);
-}
-
-let shouldLogAuth = true;
-
-/**
- * Set to `false` to disable logging.
- *
- * @category Internal
- */
-export function setShouldLogAuth(value: boolean) {
-    shouldLogAuth = value;
-}