auth-vir 3.0.1 → 3.1.1

package/dist/csrf-token.d.ts

@@ -1,6 +1,7 @@
 import { type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
 import { type AnyDuration } from 'date-vir';
 import { type RequireExactlyOne } from 'type-fest';
+import { type CsrfTokenStore } from './csrf-token-store.js';
 /**
  * Shape definition for {@link CsrfToken}.
  *
@@ -100,18 +101,18 @@ export declare function extractCsrfTokenHeader(response: Readonly<PartialWithUnd
     allowedClockSkew: Readonly<AnyDuration>;
 }>): Readonly<GetCsrfTokenResult>;
 /**
- * Stores the given CSRF token into local storage.
+ * Stores the given CSRF token into IndexedDB.
  *
  * @category Auth : Client
  */
 export declare function storeCsrfToken(csrfToken: Readonly<CsrfToken>, options: Readonly<CsrfHeaderNameOption> & PartialWithUndefined<{
     /**
-     * Allows mocking or overriding the global `localStorage`.
+     * Allows mocking or overriding the default CSRF token store.
      *
-     * @default globalThis.localStorage
+     * @default getDefaultCsrfTokenStore()
      */
-    localStorage: Pick<Storage, 'setItem' | 'removeItem'>;
-}>): void;
+    csrfTokenStore: CsrfTokenStore;
+}>): Promise<void>;
 /**
  * Parse a raw CSRF token JSON string.
  *
@@ -134,29 +135,29 @@ export declare function parseCsrfToken(value: string | undefined | null, options
  */
 export declare function getCurrentCsrfToken(options: Readonly<CsrfHeaderNameOption> & PartialWithUndefined<{
     /**
-     * Allows mocking or overriding the global `localStorage`.
+     * Allows mocking or overriding the default CSRF token store.
      *
-     * @default globalThis.localStorage
+     * @default getDefaultCsrfTokenStore()
      */
-    localStorage: Pick<Storage, 'getItem'>;
+    csrfTokenStore: CsrfTokenStore;
     /**
      * Allowed clock skew tolerance for CSRF token expiration checks.
      *
      * @default {minutes: 5}
      */
     allowedClockSkew: Readonly<AnyDuration>;
-}>): Readonly<GetCsrfTokenResult>;
+}>): Promise<Readonly<GetCsrfTokenResult>>;
 /**
- * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
- * user or react to a session timeout.
+ * Wipes the current stored CSRF token. This should be used by client (frontend) code to react to a
+ * session timeout.
  *
  * @category Auth : Client
  */
 export declare function wipeCurrentCsrfToken(options: Readonly<CsrfHeaderNameOption> & PartialWithUndefined<{
     /**
-     * Allows mocking or overriding the global `localStorage`.
+     * Allows mocking or overriding the default CSRF token store.
      *
-     * @default globalThis.localStorage
+     * @default getDefaultCsrfTokenStore()
      */
-    localStorage: Pick<Storage, 'removeItem'>;
-}>): void;
+    csrfTokenStore: CsrfTokenStore;
+}>): Promise<void>;

package/dist/csrf-token.js

@@ -1,6 +1,7 @@
 import { randomString, wrapInTry, } from '@augment-vir/common';
 import { calculateRelativeDate, fullDateShape, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
 import { defineShape, parseJsonWithShape } from 'object-shape-tester';
+import { getDefaultCsrfTokenStore } from './csrf-token-store.js';
 /**
  * Shape definition for {@link CsrfToken}.
  *
@@ -17,7 +18,9 @@ export const csrfTokenShape = defineShape({
  * @category Internal
  * @default {minutes: 5}
  */
-export const defaultAllowedClockSkew = { minutes: 5 };
+export const defaultAllowedClockSkew = {
+    minutes: 5,
+};
 /**
  * Generates a random, cryptographically secure CSRF token.
  *
@@ -74,12 +77,12 @@ export function extractCsrfTokenHeader(response, csrfHeaderNameOption, options)
     return parseCsrfToken(rawCsrfToken, options);
 }
 /**
- * Stores the given CSRF token into local storage.
+ * Stores the given CSRF token into IndexedDB.
  *
  * @category Auth : Client
  */
-export function storeCsrfToken(csrfToken, options) {
-    (options.localStorage || globalThis.localStorage).setItem(resolveCsrfHeaderName(options), JSON.stringify(csrfToken));
+export async function storeCsrfToken(csrfToken, options) {
+    await (options.csrfTokenStore || (await getDefaultCsrfTokenStore())).setCsrfToken(JSON.stringify(csrfToken));
 }
 /**
  * Parse a raw CSRF token JSON string.
@@ -122,17 +125,17 @@ export function parseCsrfToken(value, options) {
  *
  * @category Auth : Client
  */
-export function getCurrentCsrfToken(options) {
-    const rawCsrfToken = (options.localStorage || globalThis.localStorage).getItem(resolveCsrfHeaderName(options)) ||
+export async function getCurrentCsrfToken(options) {
+    const rawCsrfToken = (await (options.csrfTokenStore || (await getDefaultCsrfTokenStore())).getCsrfToken()) ||
         undefined;
     return parseCsrfToken(rawCsrfToken, options);
 }
 /**
- * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
- * user or react to a session timeout.
+ * Wipes the current stored CSRF token. This should be used by client (frontend) code to react to a
+ * session timeout.
  *
  * @category Auth : Client
  */
-export function wipeCurrentCsrfToken(options) {
-    return (options.localStorage || globalThis.localStorage).removeItem(resolveCsrfHeaderName(options));
+export async function wipeCurrentCsrfToken(options) {
+    await (options.csrfTokenStore || (await getDefaultCsrfTokenStore())).deleteCsrfToken();
 }

package/dist/generated/internal/class.js

@@ -22,8 +22,8 @@ const config = {
             "fromEnvVar": null
         },
         "config": {
-            "engineType": "client",
-            "moduleFormat": "esm"
+            "moduleFormat": "esm",
+            "engineType": "client"
         },
         "binaryTargets": [
             {

package/dist/index.d.ts

@@ -3,10 +3,11 @@ 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-local-storage.js';
+export * from './mock-csrf-token-store.js';

package/dist/index.js

@@ -3,10 +3,11 @@ 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-local-storage.js';
+export * from './mock-csrf-token-store.js';

package/dist/jwt/jwt.js

@@ -2,8 +2,13 @@ import { assertWrap, check } from '@augment-vir/assert';
 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' };
+const encryptionProtectedHeader = {
+    alg: 'dir',
+    enc: 'A256GCM',
+};
+const signingProtectedHeader = {
+    alg: 'HS512',
+};
 /**
  * JWT uses seconds since the epoch per RFC 7519, whereas `toTimestamp` uses milliseconds.
  *
@@ -28,7 +33,9 @@ export function parseJwtTimestamp(seconds) {
 export async function createJwt(
 /** The data to be included in the JWT. */
 data, params) {
-    const rawJwt = new SignJWT({ data })
+    const rawJwt = new SignJWT({
+        data,
+    })
         .setProtectedHeader(signingProtectedHeader)
         .setIssuedAt(params.issuedAt
         ? toJwtTimestamp(createFullDateInUserTimezone(params.issuedAt))
@@ -40,7 +47,9 @@ data, params) {
         rawJwt.setNotBefore(toJwtTimestamp(createFullDateInUserTimezone(params.notValidUntil)));
     }
     const signedJwt = await rawJwt.sign(params.jwtKeys.signingKey);
-    return await new EncryptJWT({ jwt: signedJwt })
+    return await new EncryptJWT({
+        jwt: signedJwt,
+    })
         .setProtectedHeader(encryptionProtectedHeader)
         .encrypt(params.jwtKeys.encryptionKey);
 }
@@ -58,7 +67,9 @@ 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 clockToleranceSeconds = convertDuration(params.allowedClockSkew || defaultAllowedClockSkew, {
+        seconds: true,
+    }).seconds;
     const verifiedJwt = await jwtVerify(decryptedJwt.payload.jwt, params.jwtKeys.signingKey, {
         issuer: params.issuer,
         audience: params.audience,

package/dist/jwt/user-jwt.js

@@ -19,7 +19,9 @@ export const userJwtDataShape = defineShape({
      * enforce the max session duration. If not present, the session is considered to have started
      * when the JWT was issued.
      */
-    sessionStartedAt: optionalShape(0, { alsoUndefined: true }),
+    sessionStartedAt: optionalShape(0, {
+        alsoUndefined: true,
+    }),
 });
 /**
  * Creates a new signed and encrypted {@link JwtUserData} when a client (frontend) successfully

package/dist/mock-csrf-token-store.d.ts

@@ -0,0 +1,64 @@
+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;
+};

package/dist/mock-csrf-token-store.js

@@ -0,0 +1,107 @@
+/**
+ * Create an empty `accessRecord` object, this is to be used in conjunction with
+ * {@link createMockLocalStorage}.
+ *
+ * @category Mock
+ */
+export function createEmptyMockLocalStorageAccessRecord() {
+    return {
+        getItem: [],
+        removeItem: [],
+        setItem: [],
+        key: [],
+    };
+}
+/**
+ * Create a LocalStorage mock.
+ *
+ * @category Mock
+ */
+export function createMockLocalStorage(
+/** Set values in here to initialize the mocked localStorage data store contents. */
+init = {}) {
+    const store = init;
+    const accessRecord = createEmptyMockLocalStorageAccessRecord();
+    const mockLocalStorage = {
+        clear() {
+            Object.keys(store).forEach((key) => {
+                delete store[key];
+            });
+        },
+        getItem(key) {
+            accessRecord.getItem.push(key);
+            return store[key] ?? null;
+        },
+        get length() {
+            return Object.keys(store).length;
+        },
+        key(index) {
+            accessRecord.key.push(index);
+            return Object.keys(store)[index] ?? null;
+        },
+        removeItem(key) {
+            accessRecord.removeItem.push(key);
+            delete store[key];
+        },
+        setItem(key, value) {
+            accessRecord.setItem.push({
+                key,
+                value,
+            });
+            store[key] = value;
+        },
+    };
+    return {
+        localStorage: mockLocalStorage,
+        store,
+        accessRecord,
+    };
+}
+/**
+ * Create an empty `accessRecord` object, this is to be used in conjunction with
+ * {@link createMockCsrfTokenStore}.
+ *
+ * @category Mock
+ */
+export function createEmptyMockCsrfTokenStoreAccessRecord() {
+    return {
+        getCsrfToken: 0,
+        setCsrfToken: [],
+        deleteCsrfToken: 0,
+    };
+}
+/**
+ * Create a mock {@link CsrfTokenStore} backed by a simple in-memory object, for use in tests.
+ *
+ * @category Mock
+ */
+export function createMockCsrfTokenStore(
+/** Set an initial value to initialize the mocked store contents. */
+init) {
+    let storedValue = init;
+    const accessRecord = createEmptyMockCsrfTokenStoreAccessRecord();
+    const csrfTokenStore = {
+        getCsrfToken() {
+            accessRecord.getCsrfToken++;
+            return Promise.resolve(storedValue);
+        },
+        setCsrfToken(value) {
+            accessRecord.setCsrfToken.push(value);
+            storedValue = value;
+            return Promise.resolve();
+        },
+        deleteCsrfToken() {
+            accessRecord.deleteCsrfToken++;
+            storedValue = undefined;
+            return Promise.resolve();
+        },
+    };
+    return {
+        csrfTokenStore,
+        /** The current value held in the mock store. */
+        get storedValue() {
+            return storedValue;
+        },
+        accessRecord,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "3.0.1",
+    "version": "3.1.1",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",
@@ -41,20 +41,21 @@
         "test:web": "virmator test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.65.0",
-        "@augment-vir/common": "^31.65.0",
-        "date-vir": "^8.1.1",
+        "@augment-vir/assert": "^31.68.1",
+        "@augment-vir/common": "^31.68.1",
+        "date-vir": "^8.2.1",
         "detect-activity": "^1.0.0",
         "hash-wasm": "^4.12.0",
-        "jose": "^6.1.3",
+        "jose": "^6.2.1",
+        "local-db-client": "^1.0.0",
         "object-shape-tester": "^6.11.0",
         "type-fest": "^5.4.4",
         "url-vir": "^2.1.7"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.65.0",
+        "@augment-vir/test": "^31.68.1",
         "@prisma/client": "^6.19.2",
-        "@types/node": "^25.3.0",
+        "@types/node": "^25.3.3",
         "@web/dev-server-esbuild": "^1.0.5",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",