auth-vir 4.0.0 → 5.0.0

package/src/auth.ts

@@ -1,20 +1,15 @@
-import {type PartialWithUndefined} from '@augment-vir/common';
+import {type SelectFrom} from '@augment-vir/common';
 import {type FullDate, type UtcTimezone} from 'date-vir';
 import {
-    AuthCookieName,
+    AuthCookie,
     clearAuthCookie,
+    clearCsrfCookie,
     type CookieParams,
     extractCookieJwt,
     generateAuthCookie,
+    generateCsrfCookie,
 } from './cookie.js';
-import {type CsrfTokenStore} from './csrf-token-store.js';
-import {
-    type CsrfHeaderNameOption,
-    extractCsrfTokenHeader,
-    generateCsrfToken,
-    resolveCsrfHeaderName,
-    storeCsrfToken,
-} from './csrf-token.js';
+import {type CsrfHeaderNameOption, generateCsrfToken, resolveCsrfHeaderName} from './csrf-token.js';
 import {type ParseJwtParams} from './jwt/jwt.js';
 import {type JwtUserData} from './jwt/user-jwt.js';
 
@@ -51,7 +46,7 @@ export type UserIdResult<UserId extends string | number> = {
     jwtExpiration: FullDate<UtcTimezone>;
     /** When the JWT was issued (`iat` claim). */
     jwtIssuedAt: FullDate<UtcTimezone>;
-    cookieName: string;
+    cookieName: AuthCookie;
     /** The CSRF token embedded in the JWT. */
     csrfToken: string;
     /**
@@ -80,7 +75,7 @@ export async function extractUserIdFromRequestHeaders<UserId extends string | nu
     headers: HeaderContainer,
     jwtParams: Readonly<ParseJwtParams>,
     csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>,
-    cookieName: string = AuthCookieName.Auth,
+    cookieName: AuthCookie = AuthCookie.Auth,
 ): Promise<Readonly<UserIdResult<UserId>> | undefined> {
     try {
         const csrfToken = readCsrfTokenHeader(headers, csrfHeaderNameOption);
@@ -120,7 +115,7 @@ export async function extractUserIdFromRequestHeaders<UserId extends string | nu
 export async function insecureExtractUserIdFromCookieAlone<UserId extends string | number>(
     headers: HeaderContainer,
     jwtParams: Readonly<ParseJwtParams>,
-    cookieName: string = AuthCookieName.Auth,
+    cookieName: AuthCookie,
 ): Promise<Readonly<UserIdResult<UserId>> | undefined> {
     try {
         const cookie = readHeader(headers, 'cookie');
@@ -149,7 +144,9 @@ export async function insecureExtractUserIdFromCookieAlone<UserId extends string
 }
 
 /**
- * Used by host (backend) code to set headers on a response object.
+ * Used by host (backend) code to set headers on a response object. Sets both the auth JWT cookie
+ * and the CSRF token cookie. The CSRF cookie is not `HttpOnly` so that frontend JavaScript can read
+ * it and inject the value as a request header.
  *
  * @category Auth : Host
  */
@@ -157,17 +154,15 @@ export async function generateSuccessfulLoginHeaders(
     /** The id from your database of the user you're authenticating. */
     userId: string | number,
     cookieConfig: Readonly<CookieParams>,
-    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>,
     /**
      * The timestamp (in seconds) when the session originally started. If not provided, the current
      * time will be used (for new sessions).
      */
     sessionStartedAt?: number | undefined,
-): Promise<Record<string, string>> {
+): Promise<Record<string, string[]>> {
     const csrfToken = generateCsrfToken();
-    const csrfHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
 
-    const {cookie} = await generateAuthCookie(
+    const authCookie = await generateAuthCookie(
         {
             csrfToken,
             userId,
@@ -176,9 +171,13 @@ export async function generateSuccessfulLoginHeaders(
         cookieConfig,
     );
 
+    const csrfCookie = generateCsrfCookie(csrfToken, cookieConfig);
+
     return {
-        'set-cookie': cookie,
-        [csrfHeaderName]: csrfToken,
+        'set-cookie': [
+            authCookie,
+            csrfCookie,
+        ],
     };
 }
 
@@ -189,43 +188,12 @@ export async function generateSuccessfulLoginHeaders(
  * @category Auth : Host
  */
 export function generateLogoutHeaders(
-    cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>,
-): Record<string, string> {
+    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>>,
+): Record<string, string[]> {
     return {
-        'set-cookie': clearAuthCookie(cookieConfig),
+        'set-cookie': [
+            clearAuthCookie(cookieConfig),
+            clearCsrfCookie(cookieConfig),
+        ],
     };
 }
-
-/**
- * Store auth data on a client (frontend) after receiving an auth response from the host (backend).
- * Specifically, this stores the CSRF token into IndexedDB (which doesn't need to be a secret).
- * Alternatively, if the given response failed, this will wipe the existing (if any) stored CSRF
- * token.
- *
- * @category Auth : Client
- * @throws Error if no CSRF token header is found.
- */
-export async function handleAuthResponse(
-    response: Readonly<Pick<Response, 'ok' | 'headers'>>,
-    options: Readonly<CsrfHeaderNameOption> &
-        PartialWithUndefined<{
-            /**
-             * Allows mocking or overriding the default CSRF token store.
-             *
-             * @default getDefaultCsrfTokenStore()
-             */
-            csrfTokenStore: CsrfTokenStore;
-        }>,
-): Promise<void> {
-    if (!response.ok) {
-        return;
-    }
-
-    const csrfToken = extractCsrfTokenHeader(response, options);
-
-    if (!csrfToken) {
-        throw new Error('Did not receive any CSRF token.');
-    }
-
-    await storeCsrfToken(csrfToken, options);
-}

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,18 +1,7 @@
-import {randomString, type PartialWithUndefined, type SelectFrom} from '@augment-vir/common';
-import {type AnyDuration} from 'date-vir';
+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';
-
-/**
- * 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,
-};
+import {AuthCookie} from './cookie.js';
 
 /**
  * Generates a random, cryptographically secure CSRF token string.
@@ -42,91 +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('-');
+        ]
+            .filter(check.isTruthy)
+            .join('-');
     }
 }
 
 /**
- * Extract the CSRF token header from a response.
- *
- * @category Auth : Client
- */
-export function extractCsrfTokenHeader(
-    response: Readonly<PartialWithUndefined<SelectFrom<Response, {headers: true}>>>,
-    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>,
-): string | undefined {
-    const csrfTokenHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
-
-    return response.headers?.get(csrfTokenHeaderName) || undefined;
-}
-
-/**
- * Stores the given CSRF token into IndexedDB.
- *
- * @category Auth : Client
- */
-export async function storeCsrfToken(
-    csrfToken: string,
-    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(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;
-        }>,
-): Promise<string | undefined> {
-    return (
-        (await (options.csrfTokenStore || (await getDefaultCsrfTokenStore())).getCsrfToken()) ||
-        undefined
-    );
-}
-
-/**
- * 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;
-};