auth-vir 1.3.2 → 2.0.0

package/src/auth.ts

@@ -1,10 +1,20 @@
+import {type PartialWithUndefined} from '@augment-vir/common';
+import {type FullDate, type UtcTimezone} from 'date-vir';
 import {
+    AuthCookieName,
     clearAuthCookie,
     type CookieParams,
     extractCookieJwt,
     generateAuthCookie,
 } from './cookie.js';
-import {csrfTokenHeaderName, generateCsrfToken} from './csrf-token.js';
+import {
+    extractCsrfTokenHeader,
+    generateCsrfToken,
+    parseCsrfToken,
+    storeCsrfToken,
+    wipeCurrentCsrfToken,
+} from './csrf-token.js';
+import {AuthHeaderName} from './headers.js';
 import {type ParseJwtParams} from './jwt/jwt.js';
 
 /**
@@ -30,6 +40,32 @@ function readHeader(headers: HeaderContainer, headerName: string): string | unde
     }
 }
 
+/**
+ * Output from {@link extractUserIdFromRequestHeaders}.
+ *
+ * @category Internal
+ */
+export type UserIdResult<UserId extends string | number> = {
+    userId: UserId;
+    jwtExpiration: FullDate<UtcTimezone>;
+    cookieName: string;
+};
+
+function readCsrfTokenHeader(
+    headers: HeaderContainer,
+    overrides: PartialWithUndefined<{
+        csrfHeaderName: string;
+    }>,
+): string | undefined {
+    const rawCsrfToken = readHeader(headers, overrides.csrfHeaderName || AuthHeaderName.CsrfToken);
+
+    if (!rawCsrfToken) {
+        return undefined;
+    }
+
+    return parseCsrfToken(rawCsrfToken).csrfToken?.token || rawCsrfToken;
+}
+
 /**
  * Extract the user id from a request by checking both the request cookie and CSRF token. This is
  * used by host (backend) code to help verify a request. After extracting the user id using this,
@@ -38,13 +74,16 @@ function readHeader(headers: HeaderContainer, headerName: string): string | unde
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export async function extractUserIdFromRequestHeaders(
+export async function extractUserIdFromRequestHeaders<UserId extends string | number>(
     headers: HeaderContainer,
     jwtParams: Readonly<ParseJwtParams>,
-    cookieName?: string | undefined,
-): Promise<string | undefined> {
+    cookieName: string = AuthCookieName.Auth,
+    overrides: PartialWithUndefined<{
+        csrfHeaderName: string;
+    }> = {},
+): Promise<Readonly<UserIdResult<UserId>> | undefined> {
     try {
-        const csrfToken = readHeader(headers, csrfTokenHeaderName);
+        const csrfToken = readCsrfTokenHeader(headers, overrides);
         const cookie = readHeader(headers, 'cookie');
 
         if (!cookie || !csrfToken) {
@@ -53,11 +92,15 @@ export async function extractUserIdFromRequestHeaders(
 
         const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
 
-        if (!jwt || jwt.csrfToken !== csrfToken) {
+        if (!jwt || jwt.data.csrfToken !== csrfToken) {
             return undefined;
         }
 
-        return jwt.userId;
+        return {
+            userId: jwt.data.userId as UserId,
+            jwtExpiration: jwt.jwtExpiration,
+            cookieName,
+        };
     } catch {
         return undefined;
     }
@@ -69,12 +112,13 @@ export async function extractUserIdFromRequestHeaders(
  * circumstances where you cannot rely on client-side JavaScript to insert the CSRF token.
  *
  * @deprecated Prefer {@link extractUserIdFromRequestHeaders} instead: it is more secure.
+ * @category Auth : Host
  */
-export async function extractUserIdFromCookieAlone(
+export async function insecureExtractUserIdFromCookieAlone<UserId extends string | number>(
     headers: HeaderContainer,
     jwtParams: Readonly<ParseJwtParams>,
-    cookieName?: string | undefined,
-): Promise<string | undefined> {
+    cookieName: string = AuthCookieName.Auth,
+): Promise<Readonly<UserIdResult<UserId>> | undefined> {
     try {
         const cookie = readHeader(headers, 'cookie');
 
@@ -88,7 +132,11 @@ export async function extractUserIdFromCookieAlone(
             return undefined;
         }
 
-        return jwt.userId;
+        return {
+            userId: jwt.data.userId as UserId,
+            jwtExpiration: jwt.jwtExpiration,
+            cookieName,
+        };
     } catch {
         return undefined;
     }
@@ -99,23 +147,35 @@ export async function extractUserIdFromCookieAlone(
  *
  * @category Auth : Host
  */
-export async function generateSuccessfulLoginHeaders(
+export async function generateSuccessfulLoginHeaders<
+    CsrfHeaderName extends string = AuthHeaderName.CsrfToken,
+>(
     /** The id from your database of the user you're authenticating. */
-    userId: string,
+    userId: string | number,
     cookieConfig: Readonly<CookieParams>,
-) {
-    const csrfToken = generateCsrfToken();
+    overrides: PartialWithUndefined<{
+        csrfHeaderName: CsrfHeaderName;
+    }> = {},
+): Promise<
+    {
+        'set-cookie': string;
+    } & Record<CsrfHeaderName, string>
+> {
+    const csrfToken = generateCsrfToken(cookieConfig.cookieDuration);
+    const csrfHeaderName = (overrides.csrfHeaderName || AuthHeaderName.CsrfToken) as CsrfHeaderName;
 
     return {
         'set-cookie': await generateAuthCookie(
             {
-                csrfToken,
+                csrfToken: csrfToken.token,
                 userId,
             },
             cookieConfig,
         ),
-        [csrfTokenHeaderName]: csrfToken,
-    };
+        [csrfHeaderName]: JSON.stringify(csrfToken),
+    } as {
+        'set-cookie': string;
+    } & Record<CsrfHeaderName, string>;
 }
 
 /**
@@ -124,11 +184,22 @@ export async function generateSuccessfulLoginHeaders(
  *
  * @category Auth : Host
  */
-export function generateLogoutHeaders(...params: Parameters<typeof clearAuthCookie>) {
+export function generateLogoutHeaders<CsrfHeaderName extends string = AuthHeaderName.CsrfToken>(
+    cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>,
+    overrides: PartialWithUndefined<{
+        csrfHeaderName: CsrfHeaderName;
+    }> = {},
+): {
+    'set-cookie': string;
+} & Record<CsrfHeaderName, string> {
+    const csrfHeaderName = (overrides.csrfHeaderName || AuthHeaderName.CsrfToken) as CsrfHeaderName;
+
     return {
-        'set-cookie': clearAuthCookie(...params),
-        [csrfTokenHeaderName]: 'redacted',
-    };
+        'set-cookie': clearAuthCookie(cookieConfig),
+        [csrfHeaderName]: 'redacted',
+    } as {
+        'set-cookie': string;
+    } & Record<CsrfHeaderName, string>;
 }
 
 /**
@@ -142,77 +213,28 @@ export function generateLogoutHeaders(...params: Parameters<typeof clearAuthCook
  */
 export function handleAuthResponse(
     response: Readonly<Pick<Response, 'ok' | 'headers'>>,
-    overrides: {
+    overrides: PartialWithUndefined<{
         /**
          * Allows mocking or overriding the global `localStorage`.
          *
          * @default globalThis.localStorage
          */
-        localStorage?: Pick<Storage, 'setItem' | 'removeItem'>;
+        localStorage: Pick<Storage, 'setItem' | 'removeItem'>;
         /** Override the default CSRF token header name. */
-        csrfHeaderName?: string;
-    } = {},
+        csrfHeaderName: string;
+    }> = {},
 ) {
     if (!response.ok) {
         wipeCurrentCsrfToken(overrides);
         return;
     }
-    const headerName = overrides.csrfHeaderName || csrfTokenHeaderName;
 
-    const csrfToken = response.headers.get(headerName);
+    const {csrfToken} = extractCsrfTokenHeader(response, overrides);
 
     if (!csrfToken) {
         wipeCurrentCsrfToken(overrides);
         throw new Error('Did not receive any CSRF token.');
     }
 
-    (overrides.localStorage || globalThis.localStorage).setItem(headerName, 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 function getCurrentCsrfToken(
-    overrides: {
-        /**
-         * Allows mocking or overriding the global `localStorage`.
-         *
-         * @default globalThis.localStorage
-         */
-        localStorage?: Pick<Storage, 'getItem'>;
-        /** Override the default CSRF token header name. */
-        csrfHeaderName?: string;
-    } = {},
-): string | undefined {
-    return (
-        (overrides.localStorage || globalThis.localStorage).getItem(
-            overrides.csrfHeaderName || csrfTokenHeaderName,
-        ) || undefined
-    );
-}
-
-/**
- * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
- * user or react to a session timeout.
- *
- * @category Auth : Client
- */
-export function wipeCurrentCsrfToken(
-    overrides: {
-        /**
-         * Allows mocking or overriding the global `localStorage`.
-         *
-         * @default globalThis.localStorage
-         */
-        localStorage?: Pick<Storage, 'removeItem'>;
-        /** Override the default CSRF token header name. */
-        csrfHeaderName?: string;
-    } = {},
-) {
-    return (overrides.localStorage || globalThis.localStorage).removeItem(
-        overrides.csrfHeaderName || csrfTokenHeaderName,
-    );
+    storeCsrfToken(csrfToken, overrides);
 }

package/src/cookie.ts

@@ -3,8 +3,20 @@ 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/jwt.js';
-import {createUserJwt, parseUserJwt, type UserJwtData} from './jwt/user-jwt.js';
+import {type CreateJwtParams, type ParseJwtParams, type ParsedJwt} from './jwt/jwt.js';
+import {createUserJwt, parseUserJwt, type JwtUserData} from './jwt/user-jwt.js';
+
+/**
+ * Cookie header names supported by default.
+ *
+ * @category Internal
+ */
+export enum AuthCookieName {
+    /** Used for a full user login auth. */
+    Auth = 'auth',
+    /** Use for a temporary "just signed up" auth. */
+    SignUp = 'sign-up',
+}
 
 /**
  * Parameters for {@link generateAuthCookie}.
@@ -47,7 +59,7 @@ export type CookieParams = {
  * @category Internal
  */
 export async function generateAuthCookie(
-    userJwtData: Readonly<UserJwtData>,
+    userJwtData: Readonly<JwtUserData>,
     cookieConfig: Readonly<CookieParams>,
 ): Promise<string> {
     return generateCookie({
@@ -122,17 +134,17 @@ export function generateCookie(
 export async function extractCookieJwt(
     rawCookie: string,
     jwtParams: Readonly<ParseJwtParams>,
-    cookieName: string = 'auth',
-): Promise<undefined | UserJwtData> {
+    cookieName: string = AuthCookieName.Auth,
+): Promise<undefined | ParsedJwt<JwtUserData>> {
     const cookieRegExp = new RegExp(`${cookieName}=[^;]+(?:;|$)`);
 
-    const [auth] = safeMatch(rawCookie, cookieRegExp);
+    const [cookieValue] = safeMatch(rawCookie, cookieRegExp);
 
-    if (!auth) {
+    if (!cookieValue) {
         return undefined;
     }
 
-    const rawJwt = auth.replace(`${cookieName}=`, '').replace(';', '');
+    const rawJwt = cookieValue.replace(`${cookieName}=`, '').replace(';', '');
 
     const jwt = await parseUserJwt(rawJwt, jwtParams);
 

package/src/csrf-token.ts

@@ -1,17 +1,208 @@
-import {randomString} from '@augment-vir/common';
+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 {type RequireExactlyOne} from 'type-fest';
+import {AuthHeaderName} from './headers.js';
 
 /**
- * Name of the header attached to responses that stores the CSRF token value.
+ * Shape definition for {@link CsrfToken}.
  *
  * @category Internal
  */
-export const csrfTokenHeaderName = 'csrf-token';
+export const csrfTokenShape = defineShape({
+    token: '',
+    expiration: fullDateShape,
+});
+
+/**
+ * A cryptographically CSRF token with expiration date.
+ *
+ * @category Internal
+ */
+export type CsrfToken = typeof csrfTokenShape.runtimeType;
 
 /**
  * Generates a random, cryptographically secure CSRF token.
  *
  * @category Internal
  */
-export function generateCsrfToken(): string {
-    return randomString(256);
+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',
+}
+
+/**
+ * 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<SelectFrom<Response, {headers: true}>>,
+    overrides: PartialWithUndefined<{
+        csrfHeaderName: string;
+    }> = {},
+): Readonly<GetCsrfTokenResult> {
+    const csrfTokenHeaderName = overrides.csrfHeaderName || AuthHeaderName.CsrfToken;
+
+    const rawCsrfToken = response.headers.get(csrfTokenHeaderName);
+
+    return parseCsrfToken(rawCsrfToken);
+}
+
+/**
+ * Stores the given CSRF token into local storage.
+ *
+ * @category Auth : Client
+ */
+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;
+    }> = {},
+) {
+    (overrides.localStorage || globalThis.localStorage).setItem(
+        overrides.csrfHeaderName || AuthHeaderName.CsrfToken,
+        JSON.stringify(csrfToken),
+    );
+}
+
+/**
+ * Parse a raw CSRF token JSON string.
+ *
+ * @category Internal
+ */
+export function parseCsrfToken(value: string | undefined | null): 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,
+        };
+    }
+
+    if (
+        isDateAfter({
+            fullDate: getNowInUtcTimezone(),
+            relativeTo: csrfToken.expiration,
+        })
+    ) {
+        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 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;
+    }> = {},
+): Readonly<GetCsrfTokenResult> {
+    const rawCsrfToken: string | undefined =
+        (overrides.localStorage || globalThis.localStorage).getItem(
+            overrides.csrfHeaderName || AuthHeaderName.CsrfToken,
+        ) || undefined;
+
+    return parseCsrfToken(rawCsrfToken);
+}
+
+/**
+ * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
+ * user or react to a session timeout.
+ *
+ * @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;
+    }> = {},
+) {
+    return (overrides.localStorage || globalThis.localStorage).removeItem(
+        overrides.csrfHeaderName || AuthHeaderName.CsrfToken,
+    );
 }

package/src/generated/browser.ts

@@ -0,0 +1,23 @@
+
+/* !!! This is code generated by Prisma. Do not edit directly. !!! */
+/* eslint-disable */
+// @ts-nocheck 
+/*
+ * This file should be your main import to use Prisma-related types and utilities in a browser. 
+ * Use it to get access to models, enums, and input types.
+ * 
+ * This file does not contain a `PrismaClient` class, nor several other helpers that are intended as server-side only.
+ * See `client.ts` for the standard, server-side entry point.
+ *
+ * 🟢 You can import this file directly.
+ */
+
+import * as Prisma from './internal/prismaNamespaceBrowser.js'
+export { Prisma }
+export * as $Enums from './enums.js'
+export * from './enums.js';
+/**
+ * Model User
+ * 
+ */
+export type User = Prisma.UserModel

package/src/generated/client.ts

@@ -0,0 +1,47 @@
+
+/* !!! This is code generated by Prisma. Do not edit directly. !!! */
+/* eslint-disable */
+// @ts-nocheck 
+/*
+ * This file should be your main import to use Prisma. Through it you get access to all the models, enums, and input types.
+ * If you're looking for something you can import in the client-side of your application, please refer to the `browser.ts` file instead.
+ * 
+ * 🟢 You can import this file directly.
+ */
+
+import * as process from 'node:process'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+globalThis['__dirname'] = path.dirname(fileURLToPath(import.meta.url))
+
+import * as runtime from "@prisma/client/runtime/client"
+import * as $Enums from "./enums.js"
+import * as $Class from "./internal/class.js"
+import * as Prisma from "./internal/prismaNamespace.js"
+
+export * as $Enums from './enums.js'
+export * from "./enums.js"
+/**
+ * ## Prisma Client
+ * 
+ * Type-safe database client for TypeScript
+ * @example
+ * ```
+ * const prisma = new PrismaClient()
+ * // Fetch zero or more Users
+ * const users = await prisma.user.findMany()
+ * ```
+ * 
+ * Read more in our [docs](https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-client).
+ */
+export const PrismaClient = $Class.getPrismaClientClass(__dirname)
+export type PrismaClient<LogOpts extends Prisma.LogLevel = never, OmitOpts extends Prisma.PrismaClientOptions["omit"] = Prisma.PrismaClientOptions["omit"], ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = $Class.PrismaClient<LogOpts, OmitOpts, ExtArgs>
+export { Prisma }
+
+
+
+/**
+ * Model User
+ * 
+ */
+export type User = Prisma.UserModel