@passkeykit/server 3.1.0 → 3.1.1

package/dist/esm/stores.js

@@ -8,6 +8,41 @@ import { readFile, writeFile } from 'fs/promises';
 import { mkdirSync, existsSync } from 'fs';
 import { dirname } from 'path';
 // ============================================================
+// Async Mutex — serializes read-modify-write file operations
+// ============================================================
+/**
+ * @ai_context Prevents async interleaving of read-modify-write file operations
+ * without blocking the Node.js event loop.
+ *
+ * Each file store instance owns its own AsyncMutex. When a method acquires the
+ * lock, all other callers queue behind it until the holder releases. This turns
+ * concurrent `load() → mutate → persist()` sequences into a serial pipeline,
+ * eliminating the lost-update race condition.
+ */
+class AsyncMutex {
+    queue = [];
+    locked = false;
+    acquire() {
+        if (!this.locked) {
+            this.locked = true;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.queue.push(resolve);
+        });
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            // Hand the lock directly to the next waiter (stays locked)
+            next();
+        }
+        else {
+            this.locked = false;
+        }
+    }
+}
+// ============================================================
 // In-Memory Stores (good for development and single-process)
 // ============================================================
 export class MemoryChallengeStore {
@@ -54,10 +89,12 @@ export class MemoryCredentialStore {
  * File-based challenge store. Challenges are stored in a JSON file.
  * Auto-cleans expired challenges on every operation.
  *
- * Not suitable for multi-process servers (race conditions on file writes).
+ * Uses an internal async mutex to serialize concurrent read-modify-write
+ * operations within the same process. Not suitable for multi-process servers.
  */
 export class FileChallengeStore {
     filePath;
+    mutex = new AsyncMutex();
     constructor(filePath) {
         this.filePath = filePath;
         const dir = dirname(filePath);
@@ -86,27 +123,45 @@ export class FileChallengeStore {
         await writeFile(this.filePath, JSON.stringify(data, null, 2));
     }
     async save(key, challenge) {
-        const data = await this.load();
-        data[key] = challenge;
-        await this.persist(data);
+        await this.mutex.acquire();
+        try {
+            const data = await this.load();
+            data[key] = challenge;
+            await this.persist(data);
+        }
+        finally {
+            this.mutex.release();
+        }
     }
     async consume(key) {
-        const data = await this.load();
-        const challenge = data[key];
-        if (!challenge)
-            return null;
-        delete data[key];
-        await this.persist(data);
-        if (Date.now() > challenge.expiresAt)
-            return null;
-        return challenge;
+        await this.mutex.acquire();
+        try {
+            const data = await this.load();
+            const challenge = data[key];
+            if (!challenge)
+                return null;
+            delete data[key];
+            await this.persist(data);
+            if (Date.now() > challenge.expiresAt)
+                return null;
+            return challenge;
+        }
+        finally {
+            this.mutex.release();
+        }
     }
 }
 /**
  * File-based credential store. Credentials stored in a JSON array file.
+ *
+ * Uses an internal async mutex to serialize concurrent read-modify-write
+ * operations within the same process. Read-only operations (getByUserId,
+ * getByCredentialId) also acquire the lock to prevent reading a
+ * partially-written file from a concurrent persist().
  */
 export class FileCredentialStore {
     filePath;
+    mutex = new AsyncMutex();
     constructor(filePath) {
         this.filePath = filePath;
         const dir = dirname(filePath);
@@ -128,26 +183,56 @@ export class FileCredentialStore {
         await writeFile(this.filePath, JSON.stringify(data, null, 2));
     }
     async save(credential) {
-        const data = await this.load();
-        data.push(credential);
-        await this.persist(data);
+        await this.mutex.acquire();
+        try {
+            const data = await this.load();
+            data.push(credential);
+            await this.persist(data);
+        }
+        finally {
+            this.mutex.release();
+        }
     }
     async getByUserId(userId) {
-        return (await this.load()).filter(c => c.userId === userId);
+        await this.mutex.acquire();
+        try {
+            return (await this.load()).filter(c => c.userId === userId);
+        }
+        finally {
+            this.mutex.release();
+        }
     }
     async getByCredentialId(credentialId) {
-        return (await this.load()).find(c => c.credentialId === credentialId) ?? null;
+        await this.mutex.acquire();
+        try {
+            return (await this.load()).find(c => c.credentialId === credentialId) ?? null;
+        }
+        finally {
+            this.mutex.release();
+        }
     }
     async updateCounter(credentialId, newCounter) {
-        const data = await this.load();
-        const cred = data.find(c => c.credentialId === credentialId);
-        if (cred) {
-            cred.counter = newCounter;
-            await this.persist(data);
+        await this.mutex.acquire();
+        try {
+            const data = await this.load();
+            const cred = data.find(c => c.credentialId === credentialId);
+            if (cred) {
+                cred.counter = newCounter;
+                await this.persist(data);
+            }
+        }
+        finally {
+            this.mutex.release();
         }
     }
     async delete(credentialId) {
-        const data = (await this.load()).filter(c => c.credentialId !== credentialId);
-        await this.persist(data);
+        await this.mutex.acquire();
+        try {
+            const data = (await this.load()).filter(c => c.credentialId !== credentialId);
+            await this.persist(data);
+        }
+        finally {
+            this.mutex.release();
+        }
     }
 }

package/dist/stores.d.ts

@@ -22,10 +22,12 @@ export declare class MemoryCredentialStore implements CredentialStore {
  * File-based challenge store. Challenges are stored in a JSON file.
  * Auto-cleans expired challenges on every operation.
  *
- * Not suitable for multi-process servers (race conditions on file writes).
+ * Uses an internal async mutex to serialize concurrent read-modify-write
+ * operations within the same process. Not suitable for multi-process servers.
  */
 export declare class FileChallengeStore implements ChallengeStore {
     private filePath;
+    private mutex;
     constructor(filePath: string);
     private load;
     private persist;
@@ -34,9 +36,15 @@ export declare class FileChallengeStore implements ChallengeStore {
 }
 /**
  * File-based credential store. Credentials stored in a JSON array file.
+ *
+ * Uses an internal async mutex to serialize concurrent read-modify-write
+ * operations within the same process. Read-only operations (getByUserId,
+ * getByCredentialId) also acquire the lock to prevent reading a
+ * partially-written file from a concurrent persist().
  */
 export declare class FileCredentialStore implements CredentialStore {
     private filePath;
+    private mutex;
     constructor(filePath: string);
     private load;
     private persist;

package/dist/stores.js

@@ -11,6 +11,41 @@ const promises_1 = require("fs/promises");
 const fs_1 = require("fs");
 const path_1 = require("path");
 // ============================================================
+// Async Mutex — serializes read-modify-write file operations
+// ============================================================
+/**
+ * @ai_context Prevents async interleaving of read-modify-write file operations
+ * without blocking the Node.js event loop.
+ *
+ * Each file store instance owns its own AsyncMutex. When a method acquires the
+ * lock, all other callers queue behind it until the holder releases. This turns
+ * concurrent `load() → mutate → persist()` sequences into a serial pipeline,
+ * eliminating the lost-update race condition.
+ */
+class AsyncMutex {
+    queue = [];
+    locked = false;
+    acquire() {
+        if (!this.locked) {
+            this.locked = true;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.queue.push(resolve);
+        });
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next) {
+            // Hand the lock directly to the next waiter (stays locked)
+            next();
+        }
+        else {
+            this.locked = false;
+        }
+    }
+}
+// ============================================================
 // In-Memory Stores (good for development and single-process)
 // ============================================================
 class MemoryChallengeStore {
@@ -59,10 +94,12 @@ exports.MemoryCredentialStore = MemoryCredentialStore;
  * File-based challenge store. Challenges are stored in a JSON file.
  * Auto-cleans expired challenges on every operation.
  *
- * Not suitable for multi-process servers (race conditions on file writes).
+ * Uses an internal async mutex to serialize concurrent read-modify-write
+ * operations within the same process. Not suitable for multi-process servers.
  */
 class FileChallengeStore {
     filePath;
+    mutex = new AsyncMutex();
     constructor(filePath) {
         this.filePath = filePath;
         const dir = (0, path_1.dirname)(filePath);
@@ -91,28 +128,46 @@ class FileChallengeStore {
         await (0, promises_1.writeFile)(this.filePath, JSON.stringify(data, null, 2));
     }
     async save(key, challenge) {
-        const data = await this.load();
-        data[key] = challenge;
-        await this.persist(data);
+        await this.mutex.acquire();
+        try {
+            const data = await this.load();
+            data[key] = challenge;
+            await this.persist(data);
+        }
+        finally {
+            this.mutex.release();
+        }
     }
     async consume(key) {
-        const data = await this.load();
-        const challenge = data[key];
-        if (!challenge)
-            return null;
-        delete data[key];
-        await this.persist(data);
-        if (Date.now() > challenge.expiresAt)
-            return null;
-        return challenge;
+        await this.mutex.acquire();
+        try {
+            const data = await this.load();
+            const challenge = data[key];
+            if (!challenge)
+                return null;
+            delete data[key];
+            await this.persist(data);
+            if (Date.now() > challenge.expiresAt)
+                return null;
+            return challenge;
+        }
+        finally {
+            this.mutex.release();
+        }
     }
 }
 exports.FileChallengeStore = FileChallengeStore;
 /**
  * File-based credential store. Credentials stored in a JSON array file.
+ *
+ * Uses an internal async mutex to serialize concurrent read-modify-write
+ * operations within the same process. Read-only operations (getByUserId,
+ * getByCredentialId) also acquire the lock to prevent reading a
+ * partially-written file from a concurrent persist().
  */
 class FileCredentialStore {
     filePath;
+    mutex = new AsyncMutex();
     constructor(filePath) {
         this.filePath = filePath;
         const dir = (0, path_1.dirname)(filePath);
@@ -134,27 +189,57 @@ class FileCredentialStore {
         await (0, promises_1.writeFile)(this.filePath, JSON.stringify(data, null, 2));
     }
     async save(credential) {
-        const data = await this.load();
-        data.push(credential);
-        await this.persist(data);
+        await this.mutex.acquire();
+        try {
+            const data = await this.load();
+            data.push(credential);
+            await this.persist(data);
+        }
+        finally {
+            this.mutex.release();
+        }
     }
     async getByUserId(userId) {
-        return (await this.load()).filter(c => c.userId === userId);
+        await this.mutex.acquire();
+        try {
+            return (await this.load()).filter(c => c.userId === userId);
+        }
+        finally {
+            this.mutex.release();
+        }
     }
     async getByCredentialId(credentialId) {
-        return (await this.load()).find(c => c.credentialId === credentialId) ?? null;
+        await this.mutex.acquire();
+        try {
+            return (await this.load()).find(c => c.credentialId === credentialId) ?? null;
+        }
+        finally {
+            this.mutex.release();
+        }
     }
     async updateCounter(credentialId, newCounter) {
-        const data = await this.load();
-        const cred = data.find(c => c.credentialId === credentialId);
-        if (cred) {
-            cred.counter = newCounter;
-            await this.persist(data);
+        await this.mutex.acquire();
+        try {
+            const data = await this.load();
+            const cred = data.find(c => c.credentialId === credentialId);
+            if (cred) {
+                cred.counter = newCounter;
+                await this.persist(data);
+            }
+        }
+        finally {
+            this.mutex.release();
         }
     }
     async delete(credentialId) {
-        const data = (await this.load()).filter(c => c.credentialId !== credentialId);
-        await this.persist(data);
+        await this.mutex.acquire();
+        try {
+            const data = (await this.load()).filter(c => c.credentialId !== credentialId);
+            await this.persist(data);
+        }
+        finally {
+            this.mutex.release();
+        }
     }
 }
 exports.FileCredentialStore = FileCredentialStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passkeykit/server",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Server-side WebAuthn passkey verification — stateless or stateful, pure JS, works on serverless",
   "main": "dist/index.js",
   "module": "dist/esm/index.js",