auth-vir 5.0.1 → 5.0.2

package/dist/auth.d.ts

@@ -1,74 +0,0 @@
-import { type SelectFrom } from '@augment-vir/common';
-import { type FullDate, type UtcTimezone } from 'date-vir';
-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';
-/**
- * All possible headers container types supported by {@link extractUserIdFromRequestHeaders}.
- *
- * @category Internal
- */
-export type HeaderContainer = Record<string, string[] | undefined | string | number> | Headers;
-/**
- * Output from {@link extractUserIdFromRequestHeaders}.
- *
- * @category Internal
- */
-export type UserIdResult<UserId extends string | number> = {
-    userId: UserId;
-    jwtExpiration: FullDate<UtcTimezone>;
-    /** When the JWT was issued (`iat` claim). */
-    jwtIssuedAt: FullDate<UtcTimezone>;
-    cookieName: AuthCookie;
-    /** The CSRF token embedded in the JWT. */
-    csrfToken: string;
-    /**
-     * Unix timestamp (in milliseconds) when the session was originally started. Used to enforce max
-     * session duration.
-     */
-    sessionStartedAt: JwtUserData['sessionStartedAt'];
-};
-/**
- * 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,
- * you should compare it to users stored in your database.
- *
- * @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?: 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
- * 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 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. 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>, 
-/**
- * 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[]>>;
-/**
- * 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<SelectFrom<CookieParams, {
-    hostOrigin: true;
-    isDev: true;
-}>>): Record<string, string[]>;

package/dist/auth.js

@@ -1,128 +0,0 @@
-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;
-    }
-    else {
-        const value = headers[headerName];
-        if (value == undefined) {
-            return undefined;
-        }
-        else if (Array.isArray(value)) {
-            return value[0];
-        }
-        else {
-            return String(value);
-        }
-    }
-}
-function readCsrfTokenHeader(headers, csrfHeaderNameOption) {
-    return readHeader(headers, resolveCsrfHeaderName(csrfHeaderNameOption));
-}
-/**
- * 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,
- * you should compare it to users stored in your database.
- *
- * @category Auth : Host
- * @returns The extracted user id or `undefined` if no valid auth headers exist.
- */
-export async function extractUserIdFromRequestHeaders(headers, jwtParams, csrfHeaderNameOption, cookieName = AuthCookie.Auth) {
-    try {
-        const csrfToken = readCsrfTokenHeader(headers, csrfHeaderNameOption);
-        const cookie = readHeader(headers, 'cookie');
-        if (!cookie || !csrfToken) {
-            return undefined;
-        }
-        const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
-        if (!jwt || jwt.data.csrfToken !== csrfToken) {
-            return undefined;
-        }
-        return {
-            userId: jwt.data.userId,
-            jwtExpiration: jwt.jwtExpiration,
-            jwtIssuedAt: jwt.jwtIssuedAt,
-            cookieName,
-            csrfToken: jwt.data.csrfToken,
-            sessionStartedAt: jwt.data.sessionStartedAt,
-        };
-    }
-    catch {
-        return 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
- * 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 insecureExtractUserIdFromCookieAlone(headers, jwtParams, cookieName) {
-    try {
-        const cookie = readHeader(headers, 'cookie');
-        if (!cookie) {
-            return undefined;
-        }
-        const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
-        if (!jwt) {
-            return undefined;
-        }
-        return {
-            userId: jwt.data.userId,
-            jwtExpiration: jwt.jwtExpiration,
-            jwtIssuedAt: jwt.jwtIssuedAt,
-            cookieName,
-            csrfToken: jwt.data.csrfToken,
-            sessionStartedAt: jwt.data.sessionStartedAt,
-        };
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * 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, 
-/**
- * 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 authCookie = await generateAuthCookie({
-        csrfToken,
-        userId,
-        sessionStartedAt: sessionStartedAt ?? Date.now(),
-    }, cookieConfig);
-    const csrfCookie = generateCsrfCookie(csrfToken, cookieConfig);
-    return {
-        'set-cookie': [
-            authCookie,
-            csrfCookie,
-        ],
-    };
-}
-/**
- * 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 function generateLogoutHeaders(cookieConfig) {
-    return {
-        'set-cookie': [
-            clearAuthCookie(cookieConfig),
-            clearCsrfCookie(cookieConfig),
-        ],
-    };
-}

package/dist/cookie.d.ts

@@ -1,111 +0,0 @@
-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';
-/**
- * Cookie header names supported by default.
- *
- * @category Internal
- */
-export declare 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"
-}
-/**
- * Parameters for {@link generateAuthCookie}.
- *
- * @category Internal
- */
-export type CookieParams = {
-    /**
-     * The origin of the host (backend) service that cookies will be included in all requests to.
-     * This should be restricted to just your host (backend) origin for security purposes.
-     *
-     * @example 'https://www.example.com'
-     */
-    hostOrigin: string;
-    /**
-     * The max duration of this cookie. Or, in other words, the max user session duration before
-     * they're logged out.
-     */
-    cookieDuration: AnyDuration;
-    /**
-     * All JWT parameters required for generating the encrypted JWT that will be embedded in the
-     * Cookie. Note that all JWT keys contained herein should never shared with any frontend,
-     * client, etc.
-     */
-    jwtParams: Readonly<CreateJwtParams>;
-} & 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).
-     *
-     * @default false
-     */
-    isDev: boolean;
-}>;
-/**
- * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
- *
- * @category Internal
- */
-export declare function generateAuthCookie(userJwtData: Readonly<JwtUserData>, cookieConfig: Readonly<CookieParams>): Promise<string>;
-/**
- * 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 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<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.
- *
- * @category Internal
- */
-export declare function generateCookie(params: Readonly<Record<string, Exclude<Primitive, symbol>>>): string;
-/**
- * Extract an auth cookie from a cookie string. Used in host (backend) code.
- *
- * @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: AuthCookie): Promise<undefined | ParsedJwt<JwtUserData>>;

package/dist/cookie.js

@@ -1,137 +0,0 @@
-import { check } from '@augment-vir/assert';
-import { escapeStringForRegExp, safeMatch, } from '@augment-vir/common';
-import { convertDuration } from 'date-vir';
-import { parseUrl } from 'url-vir';
-import { createUserJwt, parseUserJwt } from './jwt/user-jwt.js';
-/**
- * Cookie header names supported by default.
- *
- * @category Internal
- */
-export var AuthCookie;
-(function (AuthCookie) {
-    /** Used for a full user login auth. */
-    AuthCookie["Auth"] = "auth";
-    /** Use for a temporary "just signed up" auth. */
-    AuthCookie["SignUp"] = "sign-up";
-    /** Used for storing the CSRF token. Not `HttpOnly` so that frontend JS can read it. */
-    AuthCookie["Csrf"] = "auth-vir-csrf";
-})(AuthCookie || (AuthCookie = {}));
-function generateSetCookie({ name, value, httpOnly, cookieConfig, }) {
-    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.
- *
- * @category Internal
- */
-export async function generateAuthCookie(userJwtData, cookieConfig) {
-    return generateSetCookie({
-        name: cookieConfig.authCookie || AuthCookie.Auth,
-        value: await createUserJwt(userJwtData, cookieConfig.jwtParams),
-        httpOnly: true,
-        cookieConfig,
-    });
-}
-/**
- * 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, cookieConfig) {
-    return generateSetCookie({
-        name: AuthCookie.Csrf,
-        value: csrfToken,
-        httpOnly: false,
-        cookieConfig: {
-            ...cookieConfig,
-            cookieDuration: {
-                days: 400,
-            },
-        },
-    });
-}
-/**
- * Generate a cookie value that will clear the previous auth cookie. Use this when signing out.
- *
- * @category Internal
- */
-export function clearAuthCookie(cookieConfig) {
-    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) {
-    return generateSetCookie({
-        name: AuthCookie.Csrf,
-        value: 'redacted',
-        httpOnly: false,
-        cookieConfig,
-    });
-}
-/**
- * Generate a cookie string from a raw set of parameters.
- *
- * @category Internal
- */
-export function generateCookie(params) {
-    return Object.entries(params)
-        .map(([key, value,]) => {
-        if (value == undefined || value === false) {
-            return undefined;
-        }
-        else if (value === '' || value === true) {
-            return key;
-        }
-        else {
-            return [
-                key,
-                value,
-            ].join('=');
-        }
-    })
-        .filter(check.isTruthy)
-        .join('; ');
-}
-/**
- * Extract an auth cookie from a cookie string. Used in host (backend) code.
- *
- * @category Internal
- * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
- */
-export async function extractCookieJwt(rawCookie, jwtParams, cookieName) {
-    const cookieRegExp = new RegExp(`${escapeStringForRegExp(cookieName)}=[^;]+(?:;|$)`);
-    const [cookieValue] = safeMatch(rawCookie, cookieRegExp);
-    if (!cookieValue) {
-        return undefined;
-    }
-    const rawJwt = cookieValue.replace(`${cookieName}=`, '').replace(';', '');
-    const jwt = await parseUserJwt(rawJwt, jwtParams);
-    return jwt;
-}

package/dist/csrf-token.d.ts

@@ -1,33 +0,0 @@
-import { type RequireExactlyOne } from 'type-fest';
-/**
- * Generates a random, cryptographically secure CSRF token string.
- *
- * @category Internal
- */
-export declare function generateCsrfToken(): string;
-/**
- * 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 declare function resolveCsrfHeaderName(options: Readonly<CsrfHeaderNameOption>): string;
-/**
- * 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 declare function getCurrentCsrfToken(): string | undefined;

package/dist/csrf-token.js

@@ -1,42 +0,0 @@
-import { check } from '@augment-vir/assert';
-import { escapeStringForRegExp, randomString, safeMatch } from '@augment-vir/common';
-import { AuthCookie } from './cookie.js';
-/**
- * Generates a random, cryptographically secure CSRF token string.
- *
- * @category Internal
- */
-export function generateCsrfToken() {
-    return randomString(256);
-}
-/**
- * Resolves a {@link CsrfHeaderNameOption} to the actual header name string.
- *
- * @category Auth : Client
- * @category Auth : Host
- */
-export function resolveCsrfHeaderName(options) {
-    if ('csrfHeaderName' in options && options.csrfHeaderName) {
-        return options.csrfHeaderName;
-    }
-    else {
-        return [
-            options.csrfHeaderPrefix,
-            'auth-vir',
-            'csrf-token',
-        ]
-            .filter(check.isTruthy)
-            .join('-');
-    }
-}
-/**
- * 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 function getCurrentCsrfToken() {
-    const cookieRegExp = new RegExp(`${escapeStringForRegExp(AuthCookie.Csrf)}=([^;]+)`);
-    const [, value,] = safeMatch(globalThis.document.cookie, cookieRegExp);
-    return value || undefined;
-}

package/dist/generated/browser.d.ts

@@ -1,9 +0,0 @@
-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/dist/generated/browser.js

@@ -1,17 +0,0 @@
-/* !!! This is code generated by Prisma. Do not edit directly. !!! */
-/* eslint-disable */
-// biome-ignore-all lint: generated file
-// @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';

package/dist/generated/client.d.ts

@@ -1,26 +0,0 @@
-import * as runtime from "@prisma/client/runtime/client";
-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 declare const PrismaClient: $Class.PrismaClientConstructor;
-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;

package/dist/generated/client.js

@@ -1,32 +0,0 @@
-/* !!! This is code generated by Prisma. Do not edit directly. !!! */
-/* eslint-disable */
-// biome-ignore-all lint: generated file
-// @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 path from 'node:path';
-import { fileURLToPath } from 'node:url';
-globalThis['__dirname'] = path.dirname(fileURLToPath(import.meta.url));
-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 { Prisma };