auth-vir 4.0.0 → 5.0.0

package/README.md

@@ -73,6 +73,7 @@ Here's a full example of how to use all host / server / backend side auth functi
 ```TypeScript
 import {type ClientRequest, type ServerResponse} from 'node:http';
 import {
+    AuthCookie,
     doesPasswordMatchHash,
     extractUserIdFromRequestHeaders,
     generateNewJwtKeys,
@@ -114,8 +115,15 @@ export async function handleLogin(
         throw new Error('Credentials mismatch.');
     }
 
-    const authHeaders = await generateSuccessfulLoginHeaders(user.id, cookieParams, csrfOption);
-    response.setHeaders(new Headers(authHeaders));
+    const authHeaders = await generateSuccessfulLoginHeaders(user.id, cookieParams);
+    Object.entries(authHeaders).forEach(
+        ([
+            key,
+            value,
+        ]) => {
+            response.setHeader(key, value);
+        },
+    );
 }
 
 /**
@@ -130,8 +138,15 @@ export async function createUser(
 ) {
     const newUser = await createUserInDatabase(userRequestData);
 
-    const authHeaders = await generateSuccessfulLoginHeaders(newUser.id, cookieParams, csrfOption);
-    response.setHeaders(new Headers(authHeaders));
+    const authHeaders = await generateSuccessfulLoginHeaders(newUser.id, cookieParams);
+    Object.entries(authHeaders).forEach(
+        ([
+            key,
+            value,
+        ]) => {
+            response.setHeader(key, value);
+        },
+    );
 }
 
 /**
@@ -141,7 +156,12 @@ export async function createUser(
  */
 export async function getAuthenticatedUser(request: ClientRequest) {
     const userId = (
-        await extractUserIdFromRequestHeaders<MyUserId>(request.getHeaders(), jwtParams, csrfOption)
+        await extractUserIdFromRequestHeaders<MyUserId>(
+            request.getHeaders(),
+            jwtParams,
+            csrfOption,
+            AuthCookie.Auth,
+        )
     )?.userId;
     const user = userId ? findUserInDatabaseById(userId) : undefined;
 
@@ -260,13 +280,7 @@ Here's a full example of how to use all the client / frontend side auth function
 
 ```TypeScript
 import {HttpStatus} from '@augment-vir/common';
-import {
-    type CsrfHeaderNameOption,
-    getCurrentCsrfToken,
-    handleAuthResponse,
-    resolveCsrfHeaderName,
-    wipeCurrentCsrfToken,
-} from 'auth-vir';
+import {type CsrfHeaderNameOption, getCurrentCsrfToken, resolveCsrfHeaderName} from 'auth-vir';
 
 /**
  * The CSRF header prefix for this app. Either `csrfHeaderPrefix` or `csrfHeaderName` must be
@@ -281,7 +295,7 @@ export async function sendLoginRequest(
     userLoginData: {username: string; password: string},
     loginUrl: string,
 ) {
-    if (await getCurrentCsrfToken(csrfOption)) {
+    if (getCurrentCsrfToken()) {
         throw new Error('Already logged in.');
     }
 
@@ -291,7 +305,7 @@ export async function sendLoginRequest(
         credentials: 'include',
     });
 
-    await handleAuthResponse(response, csrfOption);
+    /** The CSRF token cookie is automatically stored by the browser from the Set-Cookie header. */
 
     return response;
 }
@@ -302,7 +316,7 @@ export async function sendAuthenticatedRequest(
     requestInit: Omit<RequestInit, 'headers'> = {},
     headers: Record<string, string> = {},
 ) {
-    const csrfToken = await getCurrentCsrfToken(csrfOption);
+    const csrfToken = getCurrentCsrfToken();
 
     if (!csrfToken) {
         throw new Error('Not authenticated.');
@@ -317,22 +331,21 @@ export async function sendAuthenticatedRequest(
         },
     });
 
-    /**
-     * This indicates the user is no longer authorized and thus needs to login again. (This likely
-     * means that their session timed out or they clicked a "log out" button onr your website in
-     * another tab.)
-     */
     if (response.status === HttpStatus.Unauthorized) {
-        await wipeCurrentCsrfToken(csrfOption);
         throw new Error(`User no longer logged in.`);
     } else {
         return response;
     }
 }
 
-/** Call this when the user explicitly clicks a "log out" button. */
-export async function logout() {
-    await wipeCurrentCsrfToken(csrfOption);
+/**
+ * Call this when the user explicitly clicks a "log out" button. The backend clears the auth and
+ * CSRF cookies via Set-Cookie headers.
+ */
+export async function logout(logoutUrl: string) {
+    await sendAuthenticatedRequest(logoutUrl, {
+        method: 'post',
+    });
 }
 ```
 

package/dist/auth-client/backend-auth.client.d.ts

@@ -217,7 +217,7 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
         userId: UserId;
         cookieParams: Readonly<CookieParams>;
         existingUserIdResult: Readonly<UserIdResult<UserId>>;
-    }): Promise<Record<string, string>>;
+    }): Promise<Record<string, string | string[]>>;
     /** Use these headers to log a user in. */
     createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }: {
         userId: UserId;

package/dist/auth-client/backend-auth.client.js

@@ -1,10 +1,10 @@
 import { ensureArray, } from '@augment-vir/common';
 import { calculateRelativeDate, createUtcFullDate, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
 import { extractUserIdFromRequestHeaders, generateLogoutHeaders, generateSuccessfulLoginHeaders, insecureExtractUserIdFromCookieAlone, } from '../auth.js';
-import { AuthCookieName, generateAuthCookie } from '../cookie.js';
-import { defaultAllowedClockSkew, resolveCsrfHeaderName, } from '../csrf-token.js';
+import { AuthCookie, generateAuthCookie, generateCsrfCookie } from '../cookie.js';
 import { AuthHeaderName, mergeHeaderValues } from '../headers.js';
 import { parseJwtKeys } from '../jwt/jwt-keys.js';
+import { defaultAllowedClockSkew } from '../jwt/jwt.js';
 import { isSessionRefreshReady } from './is-session-refresh-ready.js';
 const defaultSessionIdleTimeout = {
     minutes: 20,
@@ -55,7 +55,7 @@ export class BackendAuthClient {
             hostOrigin: serviceOrigin || this.config.serviceOrigin,
             jwtParams: await this.getJwtParams(),
             isDev: this.config.isDev,
-            cookieName: isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
+            authCookie: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
         };
     }
     /** Calls the provided `getUserFromDatabase` config. */
@@ -133,20 +133,22 @@ export class BackendAuthClient {
             sessionRefreshStartTime,
         });
         if (isRefreshReady) {
-            const isSignUpCookie = userIdResult.cookieName === AuthCookieName.SignUp;
+            const isSignUpCookie = userIdResult.cookieName === AuthCookie.SignUp;
             const cookieParams = await this.getCookieParams({
                 isSignUpCookie,
                 requestHeaders,
             });
-            const csrfHeaderName = resolveCsrfHeaderName(this.config.csrf);
-            const { cookie } = await generateAuthCookie({
+            const authCookie = await generateAuthCookie({
                 csrfToken: userIdResult.csrfToken,
                 userId: userIdResult.userId,
                 sessionStartedAt: userIdResult.sessionStartedAt || Date.now(),
             }, cookieParams);
+            const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, cookieParams);
             return {
-                'set-cookie': cookie,
-                [csrfHeaderName]: userIdResult.csrfToken,
+                'set-cookie': [
+                    authCookie,
+                    csrfCookie,
+                ],
             };
         }
         else {
@@ -184,7 +186,7 @@ export class BackendAuthClient {
     }
     /** Securely extract a user from their request headers. */
     async getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }) {
-        const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth);
+        const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth);
         if (!userIdResult) {
             this.logForUser({
                 user: undefined,
@@ -215,14 +217,28 @@ export class BackendAuthClient {
             requestHeaders,
             user,
         });
-        const cookieRefreshHeaders = (await this.createCookieRefreshHeaders({
-            userIdResult,
-            requestHeaders,
-        })) || {};
+        const cookieRefreshHeaders = allowUserAuthRefresh
+            ? await this.createCookieRefreshHeaders({
+                userIdResult,
+                requestHeaders,
+            })
+            : undefined;
+        /**
+         * Always include the CSRF cookie so it gets re-established if the browser clears it. When
+         * session refresh fires, its headers already include a CSRF cookie.
+         */
+        const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
+            hostOrigin: (await this.config.generateServiceOrigin?.({
+                requestHeaders,
+            })) || this.config.serviceOrigin,
+            isDev: this.config.isDev,
+        });
         return {
             user: assumedUser || user,
             isAssumed: !!assumedUser,
-            responseHeaders: allowUserAuthRefresh ? cookieRefreshHeaders : {},
+            responseHeaders: {
+                'set-cookie': mergeHeaderValues(cookieRefreshHeaders?.['set-cookie'], csrfCookie),
+            },
         };
     }
     /**
@@ -270,18 +286,22 @@ export class BackendAuthClient {
      * generating a new one.
      */
     async refreshLoginHeaders({ userId, cookieParams, existingUserIdResult, }) {
-        const { cookie } = await generateAuthCookie({
+        const authCookie = await generateAuthCookie({
             csrfToken: existingUserIdResult.csrfToken,
             userId,
             sessionStartedAt: existingUserIdResult.sessionStartedAt,
         }, cookieParams);
+        const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, cookieParams);
         return {
-            'set-cookie': cookie,
+            'set-cookie': [
+                authCookie,
+                csrfCookie,
+            ],
         };
     }
     /** Use these headers to log a user in. */
     async createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }) {
-        const oppositeCookieName = isSignUpCookie ? AuthCookieName.Auth : AuthCookieName.SignUp;
+        const oppositeCookieName = isSignUpCookie ? AuthCookie.Auth : AuthCookie.SignUp;
         const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${oppositeCookieName}=`);
         const discardOppositeCookieHeaders = hasExistingOppositeCookie
             ? generateLogoutHeaders(await this.getCookieParams({
@@ -289,7 +309,7 @@ export class BackendAuthClient {
                 requestHeaders,
             }))
             : undefined;
-        const existingUserIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth);
+        const existingUserIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth);
         const cookieParams = await this.getCookieParams({
             isSignUpCookie,
             requestHeaders,
@@ -300,7 +320,7 @@ export class BackendAuthClient {
                 cookieParams,
                 existingUserIdResult,
             })
-            : await generateSuccessfulLoginHeaders(userId, cookieParams, this.config.csrf);
+            : await generateSuccessfulLoginHeaders(userId, cookieParams);
         return {
             ...newCookieHeaders,
             'set-cookie': mergeHeaderValues(newCookieHeaders['set-cookie'], discardOppositeCookieHeaders?.['set-cookie']),
@@ -334,7 +354,7 @@ export class BackendAuthClient {
      */
     async getInsecureUser({ requestHeaders, allowUserAuthRefresh, }) {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
-        const userIdResult = await insecureExtractUserIdFromCookieAlone(requestHeaders, await this.getJwtParams(), AuthCookieName.Auth);
+        const userIdResult = await insecureExtractUserIdFromCookieAlone(requestHeaders, await this.getJwtParams(), AuthCookie.Auth);
         if (!userIdResult) {
             this.logForUser({
                 user: undefined,

package/dist/auth-client/frontend-auth.client.d.ts

@@ -1,7 +1,6 @@
 import { type createBlockingInterval, type JsonCompatibleObject, type MaybePromise, type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
 import { type AnyDuration } from 'date-vir';
 import { type EmptyObject } from 'type-fest';
-import { type CsrfTokenStore } from '../csrf-token-store.js';
 import { type CsrfHeaderNameOption } from '../csrf-token.js';
 /**
  * Config for {@link FrontendAuthClient}.
@@ -50,8 +49,11 @@ export type FrontendAuthClientConfig = Readonly<{
      */
     assumedUserHeaderName: string;
     overrides: PartialWithUndefined<{
-        localStorage: Pick<Storage, 'setItem' | 'removeItem' | 'getItem'>;
-        csrfTokenStore: CsrfTokenStore;
+        localStorage: SelectFrom<Storage, {
+            setItem: true;
+            removeItem: true;
+            getItem: true;
+        }>;
     }>;
 }>;
 /**
@@ -72,8 +74,6 @@ export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatible
      * interval).
      */
     destroy(): void;
-    /** Wraps {@link getCurrentCsrfToken} to retrieve the stored CSRF token string. */
-    getCurrentCsrfToken(): Promise<string | undefined>;
     /**
      * Assume the given user. Pass `undefined` to wipe the currently assumed user.
      *
@@ -88,17 +88,16 @@ export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatible
      * `@augment-vir/common`](https://electrovir.github.io/augment-vir/functions/mergeDeep.html) to
      * combine them with these.
      */
-    createAuthenticatedRequestInit(): Promise<RequestInit>;
+    createAuthenticatedRequestInit(): RequestInit;
     /** Wipes the current user auth. */
     logout(): Promise<void>;
     /**
-     * Use to handle a login response. Automatically stores the CSRF token.
+     * Use to handle a login response. The CSRF token cookie is automatically stored by the browser
+     * from the `Set-Cookie` response header.
      *
      * @throws Error if the login response failed.
-     * @throws Error if the login response has an invalid CSRF token.
      */
     handleLoginResponse(response: Readonly<SelectFrom<Response, {
-        headers: true;
         ok: true;
     }>>): Promise<void>;
     /**

package/dist/auth-client/frontend-auth.client.js

@@ -1,6 +1,6 @@
 import { HttpStatus, } from '@augment-vir/common';
 import { listenToActivity } from 'detect-activity';
-import { extractCsrfTokenHeader, getCurrentCsrfToken, resolveCsrfHeaderName, storeCsrfToken, } from '../csrf-token.js';
+import { getCurrentCsrfToken, resolveCsrfHeaderName, } from '../csrf-token.js';
 import { AuthHeaderName } from '../headers.js';
 /**
  * An auth client for sending and validating client requests to a backend. This should only be used
@@ -41,13 +41,6 @@ export class FrontendAuthClient {
         this.userCheckInterval?.clearInterval();
         this.removeActivityListener?.();
     }
-    /** Wraps {@link getCurrentCsrfToken} to retrieve the stored CSRF token string. */
-    async getCurrentCsrfToken() {
-        return await getCurrentCsrfToken({
-            ...this.config.csrf,
-            csrfTokenStore: this.config.overrides?.csrfTokenStore,
-        });
-    }
     /**
      * Assume the given user. Pass `undefined` to wipe the currently assumed user.
      *
@@ -85,8 +78,8 @@ export class FrontendAuthClient {
      * `@augment-vir/common`](https://electrovir.github.io/augment-vir/functions/mergeDeep.html) to
      * combine them with these.
      */
-    async createAuthenticatedRequestInit() {
-        const csrfToken = await this.getCurrentCsrfToken();
+    createAuthenticatedRequestInit() {
+        const csrfToken = getCurrentCsrfToken();
         const assumedUser = this.getAssumedUser();
         const headers = {
             ...(csrfToken
@@ -110,25 +103,16 @@ export class FrontendAuthClient {
         await this.config.authClearedCallback?.();
     }
     /**
-     * Use to handle a login response. Automatically stores the CSRF token.
+     * Use to handle a login response. The CSRF token cookie is automatically stored by the browser
+     * from the `Set-Cookie` response header.
      *
      * @throws Error if the login response failed.
-     * @throws Error if the login response has an invalid CSRF token.
      */
     async handleLoginResponse(response) {
         if (!response.ok) {
             await this.logout();
             throw new Error('Login response failed.');
         }
-        const csrfToken = extractCsrfTokenHeader(response, this.config.csrf);
-        if (!csrfToken) {
-            await this.logout();
-            throw new Error('Did not receive any CSRF token.');
-        }
-        await storeCsrfToken(csrfToken, {
-            ...this.config.csrf,
-            csrfTokenStore: this.config.overrides?.csrfTokenStore,
-        });
     }
     /**
      * Use to verify _all_ responses received from the backend. Immediately logs the user out once

package/dist/auth.d.ts

@@ -1,7 +1,6 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
+import { type SelectFrom } from '@augment-vir/common';
 import { type FullDate, type UtcTimezone } from 'date-vir';
-import { type CookieParams } from './cookie.js';
-import { type CsrfTokenStore } from './csrf-token-store.js';
+import { AuthCookie, type CookieParams } from './cookie.js';
 import { type CsrfHeaderNameOption } from './csrf-token.js';
 import { type ParseJwtParams } from './jwt/jwt.js';
 import { type JwtUserData } from './jwt/user-jwt.js';
@@ -21,7 +20,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;
     /**
@@ -38,7 +37,7 @@ export type UserIdResult<UserId extends string | number> = {
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export declare function extractUserIdFromRequestHeaders<UserId extends string | number>(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>, cookieName?: string): Promise<Readonly<UserIdResult<UserId>> | undefined>;
+export declare function extractUserIdFromRequestHeaders<UserId extends string | number>(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>, cookieName?: AuthCookie): Promise<Readonly<UserIdResult<UserId>> | undefined>;
 /**
  * Extract a user id from just the cookie, without CSRF token validation. This is _less secure_ than
  * {@link extractUserIdFromRequestHeaders} as a result. This should only be used in rare
@@ -47,41 +46,29 @@ export declare function extractUserIdFromRequestHeaders<UserId extends string |
  * @deprecated Prefer {@link extractUserIdFromRequestHeaders} instead: it is more secure.
  * @category Auth : Host
  */
-export declare function insecureExtractUserIdFromCookieAlone<UserId extends string | number>(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, cookieName?: string): Promise<Readonly<UserIdResult<UserId>> | undefined>;
+export declare function insecureExtractUserIdFromCookieAlone<UserId extends string | number>(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, cookieName: AuthCookie): Promise<Readonly<UserIdResult<UserId>> | undefined>;
 /**
- * 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
  */
 export declare function generateSuccessfulLoginHeaders(
 /** The id from your database of the user you're authenticating. */
-userId: string | number, cookieConfig: Readonly<CookieParams>, csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>, 
+userId: string | number, cookieConfig: Readonly<CookieParams>, 
 /**
  * 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>>;
+sessionStartedAt?: number | undefined): Promise<Record<string, 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(cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>): Record<string, string>;
-/**
- * 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 declare 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>;
+export declare function generateLogoutHeaders(cookieConfig: Readonly<SelectFrom<CookieParams, {
+    hostOrigin: true;
+    isDev: true;
+}>>): Record<string, string[]>;

package/dist/auth.js

@@ -1,5 +1,5 @@
-import { AuthCookieName, clearAuthCookie, extractCookieJwt, generateAuthCookie, } from './cookie.js';
-import { extractCsrfTokenHeader, generateCsrfToken, resolveCsrfHeaderName, storeCsrfToken, } from './csrf-token.js';
+import { AuthCookie, clearAuthCookie, clearCsrfCookie, extractCookieJwt, generateAuthCookie, generateCsrfCookie, } from './cookie.js';
+import { generateCsrfToken, resolveCsrfHeaderName } from './csrf-token.js';
 function readHeader(headers, headerName) {
     if (headers instanceof Headers) {
         return headers.get(headerName) || undefined;
@@ -28,7 +28,7 @@ function readCsrfTokenHeader(headers, csrfHeaderNameOption) {
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export async function extractUserIdFromRequestHeaders(headers, jwtParams, csrfHeaderNameOption, cookieName = AuthCookieName.Auth) {
+export async function extractUserIdFromRequestHeaders(headers, jwtParams, csrfHeaderNameOption, cookieName = AuthCookie.Auth) {
     try {
         const csrfToken = readCsrfTokenHeader(headers, csrfHeaderNameOption);
         const cookie = readHeader(headers, 'cookie');
@@ -60,7 +60,7 @@ export async function extractUserIdFromRequestHeaders(headers, jwtParams, csrfHe
  * @deprecated Prefer {@link extractUserIdFromRequestHeaders} instead: it is more secure.
  * @category Auth : Host
  */
-export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, cookieName = AuthCookieName.Auth) {
+export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, cookieName) {
     try {
         const cookie = readHeader(headers, 'cookie');
         if (!cookie) {
@@ -84,28 +84,32 @@ export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, c
     }
 }
 /**
- * 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
  */
 export async function generateSuccessfulLoginHeaders(
 /** The id from your database of the user you're authenticating. */
-userId, cookieConfig, csrfHeaderNameOption, 
+userId, cookieConfig, 
 /**
  * The timestamp (in seconds) when the session originally started. If not provided, the current
  * time will be used (for new sessions).
  */
 sessionStartedAt) {
     const csrfToken = generateCsrfToken();
-    const csrfHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
-    const { cookie } = await generateAuthCookie({
+    const authCookie = await generateAuthCookie({
         csrfToken,
         userId,
         sessionStartedAt: sessionStartedAt ?? Date.now(),
     }, cookieConfig);
+    const csrfCookie = generateCsrfCookie(csrfToken, cookieConfig);
     return {
-        'set-cookie': cookie,
-        [csrfHeaderName]: csrfToken,
+        'set-cookie': [
+            authCookie,
+            csrfCookie,
+        ],
     };
 }
 /**
@@ -116,25 +120,9 @@ sessionStartedAt) {
  */
 export function generateLogoutHeaders(cookieConfig) {
     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, options) {
-    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/dist/cookie.d.ts

@@ -1,5 +1,5 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
-import { type AnyDuration, type FullDate, type UtcTimezone } from 'date-vir';
+import { type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
+import { type AnyDuration } from 'date-vir';
 import { type Primitive } from 'type-fest';
 import { type CreateJwtParams, type ParseJwtParams, type ParsedJwt } from './jwt/jwt.js';
 import { type JwtUserData } from './jwt/user-jwt.js';
@@ -8,11 +8,13 @@ import { type JwtUserData } from './jwt/user-jwt.js';
  *
  * @category Internal
  */
-export declare enum AuthCookieName {
+export declare enum AuthCookie {
     /** Used for a full user login auth. */
     Auth = "auth",
     /** Use for a temporary "just signed up" auth. */
-    SignUp = "sign-up"
+    SignUp = "sign-up",
+    /** Used for storing the CSRF token. Not `HttpOnly` so that frontend JS can read it. */
+    Csrf = "auth-vir-csrf"
 }
 /**
  * Parameters for {@link generateAuthCookie}.
@@ -38,8 +40,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).
@@ -49,26 +56,46 @@ export type CookieParams = {
     isDev: boolean;
 }>;
 /**
- * Output from {@link generateAuthCookie}.
+ * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
  *
  * @category Internal
  */
-export type GenerateAuthCookieResult = {
-    cookie: string;
-    expiration: FullDate<UtcTimezone>;
-};
+export declare function generateAuthCookie(userJwtData: Readonly<JwtUserData>, cookieConfig: Readonly<CookieParams>): Promise<string>;
 /**
- * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
+ * 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 declare function generateAuthCookie(userJwtData: Readonly<JwtUserData>, cookieConfig: Readonly<CookieParams>): Promise<GenerateAuthCookieResult>;
+export declare function generateCsrfCookie(csrfToken: string, cookieConfig: Readonly<SelectFrom<CookieParams, {
+    hostOrigin: true;
+    isDev: true;
+}>>): 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;
+export declare function clearAuthCookie(cookieConfig: Readonly<SelectFrom<CookieParams, {
+    hostOrigin: true;
+    isDev: true;
+}>> & PartialWithUndefined<{
+    authCookie: AuthCookie;
+}>): string;
+/**
+ * Generate a cookie value that will clear the CSRF token cookie. Use this when signing out.
+ *
+ * @category Internal
+ */
+export declare function clearCsrfCookie(cookieConfig: Readonly<SelectFrom<CookieParams, {
+    hostOrigin: true;
+    isDev: true;
+}>>): string;
 /**
  * Generate a cookie string from a raw set of parameters.
  *
@@ -81,4 +108,4 @@ export declare function generateCookie(params: Readonly<Record<string, Exclude<P
  * @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>, cookieName?: string): Promise<undefined | ParsedJwt<JwtUserData>>;
+export declare function extractCookieJwt(rawCookie: string, jwtParams: Readonly<ParseJwtParams>, cookieName: AuthCookie): Promise<undefined | ParsedJwt<JwtUserData>>;