auth-vir 2.7.2 → 3.0.1

package/dist/csrf-token.js

@@ -1,8 +1,6 @@
 import { randomString, wrapInTry, } from '@augment-vir/common';
 import { calculateRelativeDate, fullDateShape, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
 import { defineShape, parseJsonWithShape } from 'object-shape-tester';
-import { AuthHeaderName } from './headers.js';
-import { authLog } from './log.js';
 /**
  * Shape definition for {@link CsrfToken}.
  *
@@ -12,6 +10,14 @@ export const csrfTokenShape = defineShape({
     token: '',
     expiration: fullDateShape,
 });
+/**
+ * Default allowed clock skew for CSRF token expiration checks. Accounts for differences between
+ * server and client clocks when checking token expiration.
+ *
+ * @category Internal
+ * @default {minutes: 5}
+ */
+export const defaultAllowedClockSkew = { minutes: 5 };
 /**
  * Generates a random, cryptographically secure CSRF token.
  *
@@ -39,30 +45,48 @@ export var CsrfTokenFailureReason;
     /** A CSRF token was found and parsed but is expired. */
     CsrfTokenFailureReason["Expired"] = "expired";
 })(CsrfTokenFailureReason || (CsrfTokenFailureReason = {}));
+/**
+ * Resolves a {@link CsrfHeaderNameOption} to the actual header name string.
+ *
+ * @category Auth : Client
+ * @category Auth : Host
+ */
+export function resolveCsrfHeaderName(option) {
+    if ('csrfHeaderName' in option && option.csrfHeaderName) {
+        return option.csrfHeaderName;
+    }
+    else {
+        return [
+            option.csrfHeaderPrefix,
+            'auth-vir',
+            'csrf-token',
+        ].join('-');
+    }
+}
 /**
  * Extract the CSRF token header from a response.
  *
  * @category Auth : Client
  */
-export function extractCsrfTokenHeader(response, overrides = {}) {
-    const csrfTokenHeaderName = overrides.csrfHeaderName || AuthHeaderName.CsrfToken;
+export function extractCsrfTokenHeader(response, csrfHeaderNameOption, options) {
+    const csrfTokenHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
     const rawCsrfToken = response.headers?.get(csrfTokenHeaderName);
-    return parseCsrfToken(rawCsrfToken);
+    return parseCsrfToken(rawCsrfToken, options);
 }
 /**
  * Stores the given CSRF token into local storage.
  *
  * @category Auth : Client
  */
-export function storeCsrfToken(csrfToken, overrides = {}) {
-    (overrides.localStorage || globalThis.localStorage).setItem(overrides.csrfHeaderName || AuthHeaderName.CsrfToken, JSON.stringify(csrfToken));
+export function storeCsrfToken(csrfToken, options) {
+    (options.localStorage || globalThis.localStorage).setItem(resolveCsrfHeaderName(options), JSON.stringify(csrfToken));
 }
 /**
  * Parse a raw CSRF token JSON string.
  *
  * @category Internal
  */
-export function parseCsrfToken(value) {
+export function parseCsrfToken(value, options) {
     if (!value) {
         return {
             failure: CsrfTokenFailureReason.DoesNotExist,
@@ -79,9 +103,10 @@ export function parseCsrfToken(value) {
             failure: CsrfTokenFailureReason.ParseFailed,
         };
     }
+    const effectiveExpiration = calculateRelativeDate(csrfToken.expiration, options?.allowedClockSkew || defaultAllowedClockSkew);
     if (isDateAfter({
         fullDate: getNowInUtcTimezone(),
-        relativeTo: csrfToken.expiration,
+        relativeTo: effectiveExpiration,
     })) {
         return {
             failure: CsrfTokenFailureReason.Expired,
@@ -97,9 +122,10 @@ export function parseCsrfToken(value) {
  *
  * @category Auth : Client
  */
-export function getCurrentCsrfToken(overrides = {}) {
-    const rawCsrfToken = (overrides.localStorage || globalThis.localStorage).getItem(overrides.csrfHeaderName || AuthHeaderName.CsrfToken) || undefined;
-    return parseCsrfToken(rawCsrfToken);
+export function getCurrentCsrfToken(options) {
+    const rawCsrfToken = (options.localStorage || globalThis.localStorage).getItem(resolveCsrfHeaderName(options)) ||
+        undefined;
+    return parseCsrfToken(rawCsrfToken, options);
 }
 /**
  * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
@@ -107,7 +133,6 @@ export function getCurrentCsrfToken(overrides = {}) {
  *
  * @category Auth : Client
  */
-export function wipeCurrentCsrfToken(overrides = {}) {
-    authLog('auth-vir: wipeCurrentCsrfToken called', new Error().stack);
-    return (overrides.localStorage || globalThis.localStorage).removeItem(overrides.csrfHeaderName || AuthHeaderName.CsrfToken);
+export function wipeCurrentCsrfToken(options) {
+    return (options.localStorage || globalThis.localStorage).removeItem(resolveCsrfHeaderName(options));
 }

package/dist/hash.js

@@ -1,3 +1,4 @@
+import { assertWrap } from '@augment-vir/assert';
 import { mergeDefinedProperties, } from '@augment-vir/common';
 import { argon2id, argon2Verify } from 'hash-wasm';
 /**
@@ -7,8 +8,8 @@ import { argon2id, argon2Verify } from 'hash-wasm';
  */
 export const defaultHashOptions = {
     hashLength: 32,
-    iterations: 256,
-    memorySize: 512,
+    iterations: 2,
+    memorySize: 19_456,
     parallelism: 1,
 };
 /**
@@ -22,11 +23,12 @@ export const defaultHashOptions = {
  */
 export async function hashPassword(password, options = {}) {
     const salt = globalThis.crypto.getRandomValues(new Uint8Array(16));
-    return await argon2id(mergeDefinedProperties(defaultHashOptions, options, {
+    const hash = await argon2id(mergeDefinedProperties(defaultHashOptions, options, {
         outputType: 'encoded',
         password: password.normalize(),
         salt,
     }));
+    return assertWrap.isTruthy(hash);
 }
 /**
  * A utility that provides more accurate string byte size than doing `string.length`.
@@ -45,6 +47,6 @@ export function getByteLength(input) {
 export async function doesPasswordMatchHash({ password, hash, }) {
     return await argon2Verify({
         hash,
-        password,
+        password: password.normalize(),
     });
 }

package/dist/headers.d.ts

@@ -4,7 +4,6 @@
  * @category Internal
  */
 export declare enum AuthHeaderName {
-    CsrfToken = "csrf-token",
     AssumedUser = "assumed-user",
     /**
      * Used to track if the current user is signed in only with a sign-up cookie, which prevents us

package/dist/headers.js

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

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './auth-client/backend-auth.client.js';
 export * from './auth-client/frontend-auth.client.js';
+export * from './auth-client/is-session-refresh-ready.js';
 export * from './auth.js';
 export * from './cookie.js';
 export * from './csrf-token.js';
@@ -8,5 +9,4 @@ export * from './headers.js';
 export * from './jwt/jwt-keys.js';
 export * from './jwt/jwt.js';
 export * from './jwt/user-jwt.js';
-export * from './log.js';
 export * from './mock-local-storage.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './auth-client/backend-auth.client.js';
 export * from './auth-client/frontend-auth.client.js';
+export * from './auth-client/is-session-refresh-ready.js';
 export * from './auth.js';
 export * from './cookie.js';
 export * from './csrf-token.js';
@@ -8,5 +9,4 @@ export * from './headers.js';
 export * from './jwt/jwt-keys.js';
 export * from './jwt/jwt.js';
 export * from './jwt/user-jwt.js';
-export * from './log.js';
 export * from './mock-local-storage.js';

package/dist/jwt/jwt.d.ts

@@ -85,7 +85,15 @@ data: JwtData, params: Readonly<CreateJwtParams>): Promise<string>;
  *
  * @category Internal
  */
-export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience' | 'jwtKeys'>>;
+export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience' | 'jwtKeys'>> & PartialWithUndefined<{
+    /**
+     * Allowed clock skew tolerance for JWT expiration and timestamp checks. Accounts for
+     * differences between server and client clocks.
+     *
+     * @default {minutes: 5}
+     */
+    allowedClockSkew: Readonly<AnyDuration>;
+}>;
 /**
  * A fully parsed JWT with embedded data.
  *
@@ -94,6 +102,8 @@ export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience
 export type ParsedJwt<JwtData extends AnyObject> = {
     data: JwtData;
     jwtExpiration: FullDate<UtcTimezone>;
+    /** When the JWT was issued (`iat` claim). */
+    jwtIssuedAt: FullDate<UtcTimezone>;
 };
 /**
  * Parse and extract all data from an encrypted and signed JWT.

package/dist/jwt/jwt.js

@@ -1,6 +1,7 @@
 import { assertWrap, check } from '@augment-vir/assert';
-import { calculateRelativeDate, createFullDateInUserTimezone, createUtcFullDate, getNowInUtcTimezone, toTimestamp, } from 'date-vir';
+import { calculateRelativeDate, convertDuration, createFullDateInUserTimezone, createUtcFullDate, getNowInUtcTimezone, toTimestamp, } from 'date-vir';
 import { EncryptJWT, jwtDecrypt, jwtVerify, SignJWT } from 'jose';
+import { defaultAllowedClockSkew } from '../csrf-token.js';
 const encryptionProtectedHeader = { alg: 'dir', enc: 'A256GCM' };
 const signingProtectedHeader = { alg: 'HS512' };
 /**
@@ -57,6 +58,7 @@ export async function parseJwt(encryptedJwt, params) {
     else if (!check.isString(decryptedJwt.payload.jwt)) {
         throw new TypeError('Decrypted jwt is not a string.');
     }
+    const clockToleranceSeconds = convertDuration(params.allowedClockSkew || defaultAllowedClockSkew, { seconds: true }).seconds;
     const verifiedJwt = await jwtVerify(decryptedJwt.payload.jwt, params.jwtKeys.signingKey, {
         issuer: params.issuer,
         audience: params.audience,
@@ -65,18 +67,23 @@ export async function parseJwt(encryptedJwt, params) {
             'aud',
             'iss',
         ],
+        clockTolerance: clockToleranceSeconds,
     });
-    if (!verifiedJwt.payload.iat || verifiedJwt.payload.iat * 1000 > Date.now()) {
+    if (!verifiedJwt.payload.iat ||
+        verifiedJwt.payload.iat * 1000 > Date.now() + clockToleranceSeconds * 1000) {
         throw new Error('"iat" claim timestamp check failed');
     }
     const data = verifiedJwt.payload.data;
     if (!check.deepEquals(verifiedJwt.protectedHeader, signingProtectedHeader)) {
         throw new Error('Invalid signing protected header.');
     }
+    const issuedAtSeconds = assertWrap.isDefined(verifiedJwt.payload.iat, 'JWT has no issued at.');
     const expirationSeconds = assertWrap.isDefined(verifiedJwt.payload.exp, 'JWT has no expiration.');
+    const jwtIssuedAt = parseJwtTimestamp(issuedAtSeconds);
     const jwtExpiration = parseJwtTimestamp(expirationSeconds);
     return {
         data: data,
         jwtExpiration,
+        jwtIssuedAt,
     };
 }

package/dist/jwt/user-jwt.js

@@ -39,12 +39,13 @@ export async function createUserJwt(data, params) {
  * @category Internal
  */
 export async function parseUserJwt(encryptedJwt, params) {
-    const { data, jwtExpiration } = await parseJwt(encryptedJwt, params);
+    const { data, jwtExpiration, jwtIssuedAt } = await parseJwt(encryptedJwt, params);
     if (!checkValidShape(data, userJwtDataShape)) {
         throw new TypeError('Verified jwt has wrong data.');
     }
     return {
         data,
         jwtExpiration,
+        jwtIssuedAt,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "2.7.2",
+    "version": "3.0.1",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",
@@ -34,7 +34,6 @@
         "compile": "virmator compile",
         "docs": "virmator docs",
         "init": "node -e \"require('fs').rmSync('src/generated', { recursive: true, force: true })\" && prisma generate --no-hints --schema test-files/schema.prisma",
-        "start": "virmator frontend",
         "test": "runstorm --names web,node, \"npm run test:web\" \"npm run test:node\"",
         "test:docs": "virmator docs check",
         "test:node": "virmator test node 'src/**/*.test.node.ts'",
@@ -42,21 +41,21 @@
         "test:web": "virmator test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.59.2",
-        "@augment-vir/common": "^31.59.2",
-        "date-vir": "^8.1.0",
-        "detect-activity": "^0.0.1",
+        "@augment-vir/assert": "^31.65.0",
+        "@augment-vir/common": "^31.65.0",
+        "date-vir": "^8.1.1",
+        "detect-activity": "^1.0.0",
         "hash-wasm": "^4.12.0",
         "jose": "^6.1.3",
         "object-shape-tester": "^6.11.0",
-        "type-fest": "^5.4.1",
+        "type-fest": "^5.4.4",
         "url-vir": "^2.1.7"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.59.2",
+        "@augment-vir/test": "^31.65.0",
         "@prisma/client": "^6.19.2",
-        "@types/node": "^24.9.1",
-        "@web/dev-server-esbuild": "^1.0.4",
+        "@types/node": "^25.3.0",
+        "@web/dev-server-esbuild": "^1.0.5",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.1",
@@ -64,7 +63,8 @@
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
         "prisma-vir": "^2.3.3",
-        "typedoc": "^0.28.16"
+        "typedoc": "^0.28.17",
+        "typescript": "^5.9.3"
     },
     "engines": {
         "node": ">=22"