@better-auth/api-key 1.6.15 → 1.6.17

package/dist/client.mjs

@@ -1,4 +1,4 @@
-import { n as API_KEY_ERROR_CODES, t as PACKAGE_VERSION } from "./version-brpjhtFx.mjs";
+import { n as API_KEY_ERROR_CODES, t as PACKAGE_VERSION } from "./version-ZL7h_G4d.mjs";
 //#region src/client.ts
 const apiKeyClient = () => {
 	return {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as API_KEY_ERROR_CODES, t as PACKAGE_VERSION } from "./version-brpjhtFx.mjs";
+import { n as API_KEY_ERROR_CODES, t as PACKAGE_VERSION } from "./version-ZL7h_G4d.mjs";
 import { createAuthEndpoint, createAuthMiddleware } from "@better-auth/core/api";
 import { base64Url } from "@better-auth/utils/base64";
 import { createHash } from "@better-auth/utils/hash";
@@ -167,21 +167,47 @@ async function getApiKeyByIdFromStorage(ctx, id, storage) {
 	return deserializeApiKey(await storage.get(key));
 }
 /**
+* Serializes reference-list mutations per `refKey` within a single process.
+* Each new mutation chains onto the previous one for the same key, so the
+* read/modify/write below never interleaves with another mutation of the same
+* list. This closes the lost-update race in secondary-storage-only mode, where
+* the serialized list is the source of truth for listing.
+*
+* Limitation: the lock is in-process only. Across multiple server instances
+* sharing one secondary storage, concurrent writers can still lose updates.
+* Secondary storage with `fallbackToDatabase` avoids this by treating the list
+* as an invalidate-only cache with the database as the source of truth.
+* FIXME(api-key-reflist-durable): on `next`, drop the source-of-truth reference
+* list entirely and make the database authoritative for listing, removing this
+* in-process lock.
+*/
+const refListLocks = /* @__PURE__ */ new Map();
+function withRefListLock(refKey, task) {
+	const run = (refListLocks.get(refKey) ?? Promise.resolve()).then(task, task);
+	const tracked = run.finally(() => {
+		if (refListLocks.get(refKey) === tracked) refListLocks.delete(refKey);
+	});
+	refListLocks.set(refKey, tracked);
+	return run;
+}
+/**
 * Read-modify-write the ref list:
 * used only when the list is the source of truth.
 */
 async function modifyRefList(storage, refKey, modify) {
-	const refListData = await storage.get(refKey);
-	let keyIds = [];
-	if (refListData && typeof refListData === "string") try {
-		keyIds = JSON.parse(refListData);
-	} catch {
-		keyIds = [];
-	}
-	else if (Array.isArray(refListData)) keyIds = refListData;
-	const next = modify(keyIds);
-	if (next.length === 0) await storage.delete(refKey);
-	else await storage.set(refKey, JSON.stringify(next));
+	await withRefListLock(refKey, async () => {
+		const refListData = await storage.get(refKey);
+		let keyIds = [];
+		if (refListData && typeof refListData === "string") try {
+			keyIds = JSON.parse(refListData);
+		} catch {
+			keyIds = [];
+		}
+		else if (Array.isArray(refListData)) keyIds = refListData;
+		const next = modify(keyIds);
+		if (next.length === 0) await storage.delete(refKey);
+		else await storage.set(refKey, JSON.stringify(next));
+	});
 }
 async function setApiKeyInStorage(_ctx, apiKey, storage, ttl, opts) {
 	const serialized = serializeApiKey(apiKey);
@@ -720,7 +746,7 @@ function createApiKey({ defaultKeyGenerator, configurations, schema, deleteAllEx
 		const { configId, name, expiresIn, prefix, remaining, metadata, refillAmount, refillInterval, permissions, rateLimitMax, rateLimitTimeWindow, rateLimitEnabled } = ctx.body;
 		const opts = resolveConfiguration(ctx.context, configurations, configId);
 		const keyGenerator = opts.customKeyGenerator || defaultKeyGenerator;
-		const session = await getSessionFromCtx(ctx);
+		const session = await getSessionFromCtx(ctx, { disableCookieCache: true });
 		const isClientRequest = ctx.request || ctx.headers;
 		if (isClientRequest && (refillAmount !== void 0 || refillInterval !== void 0 || rateLimitMax !== void 0 || rateLimitTimeWindow !== void 0 || rateLimitEnabled !== void 0 || permissions !== void 0 || remaining !== null)) throw APIError$1.from("BAD_REQUEST", API_KEY_ERROR_CODES.SERVER_ONLY_PROPERTY);
 		if (ctx.request && ctx.body.userId !== void 0) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.UNAUTHORIZED_SESSION);
@@ -852,7 +878,7 @@ function createApiKey({ defaultKeyGenerator, configurations, schema, deleteAllEx
 //#endregion
 //#region src/routes/delete-all-expired-api-keys.ts
 function deleteAllExpiredApiKeysEndpoint({ deleteAllExpiredApiKeys }) {
-	return createAuthEndpoint({ method: "POST" }, async (ctx) => {
+	return createAuthEndpoint.serverOnly({ method: "POST" }, async (ctx) => {
 		try {
 			await deleteAllExpiredApiKeys(ctx.context, true);
 		} catch (error) {
@@ -1467,7 +1493,7 @@ function updateApiKey({ configurations, schema, deleteAllExpiredApiKeys }) {
 		} }
 	}, async (ctx) => {
 		const { configId, keyId, expiresIn, enabled, metadata, refillAmount, refillInterval, remaining, name, permissions, rateLimitEnabled, rateLimitTimeWindow, rateLimitMax } = ctx.body;
-		const session = await getSessionFromCtx(ctx);
+		const session = await getSessionFromCtx(ctx, { disableCookieCache: true });
 		const authRequired = ctx.request || ctx.headers;
 		const user = authRequired && !session ? null : session?.user || { id: ctx.body.userId };
 		if (!user?.id) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.UNAUTHORIZED_SESSION);
@@ -1565,75 +1591,54 @@ function updateApiKey({ configurations, schema, deleteAllExpiredApiKeys }) {
 //#endregion
 //#region src/rate-limit.ts
 /**
-* Determines if a request is allowed based on rate limiting parameters.
-*
-* @returns An object indicating whether the request is allowed and, if not,
-*          a message and updated ApiKey data.
+* Decides how the current request affects the per-key rate-limit counter, based
+* on the read-in-memory ApiKey. The verify route applies the result atomically;
+* this function performs no writes.
 */
-function isRateLimited(apiKey, opts) {
+function evaluateRateLimit(apiKey, opts) {
 	const now = /* @__PURE__ */ new Date();
 	const lastRequest = apiKey.lastRequest;
 	const rateLimitTimeWindow = apiKey.rateLimitTimeWindow;
 	const rateLimitMax = apiKey.rateLimitMax;
-	let requestCount = apiKey.requestCount;
 	if (opts.rateLimit.enabled === false) return {
-		success: true,
-		message: null,
-		update: { lastRequest: now },
-		tryAgainIn: null
+		type: "skip",
+		lastRequest: now
 	};
 	if (apiKey.rateLimitEnabled === false) return {
-		success: true,
-		message: null,
-		update: { lastRequest: now },
-		tryAgainIn: null
+		type: "skip",
+		lastRequest: now
 	};
 	if (rateLimitTimeWindow === null || rateLimitMax === null) return {
-		success: true,
-		message: null,
-		update: null,
-		tryAgainIn: null
+		type: "skip",
+		lastRequest: null
 	};
 	if (lastRequest === null) return {
-		success: true,
-		message: null,
-		update: {
-			lastRequest: now,
-			requestCount: 1
-		},
-		tryAgainIn: null
+		type: "start",
+		now
 	};
 	const timeSinceLastRequest = now.getTime() - new Date(lastRequest).getTime();
 	if (timeSinceLastRequest > rateLimitTimeWindow) return {
-		success: true,
-		message: null,
-		update: {
-			lastRequest: now,
-			requestCount: 1
-		},
-		tryAgainIn: null
+		type: "reset",
+		now,
+		windowStart: new Date(now.getTime() - rateLimitTimeWindow)
 	};
-	if (requestCount >= rateLimitMax) return {
-		success: false,
+	if (apiKey.requestCount >= rateLimitMax) return {
+		type: "deny",
 		message: API_KEY_ERROR_CODES.RATE_LIMIT_EXCEEDED.message,
-		update: null,
 		tryAgainIn: Math.ceil(rateLimitTimeWindow - timeSinceLastRequest)
 	};
-	requestCount++;
 	return {
-		success: true,
-		message: null,
-		tryAgainIn: null,
-		update: {
-			lastRequest: now,
-			requestCount
-		}
+		type: "increment",
+		now,
+		max: rateLimitMax,
+		windowStart: new Date(now.getTime() - rateLimitTimeWindow)
 	};
 }
 //#endregion
 //#region src/routes/verify-api-key.ts
 async function validateApiKey({ key, ctx, lookupOpts, configurations, schema, permissions, expectedConfigId, runCustomValidator }) {
-	const apiKey = await getApiKey$1(ctx, lookupOpts.disableKeyHashing ? key : await defaultKeyHasher(key), lookupOpts);
+	const hashedKey = lookupOpts.disableKeyHashing ? key : await defaultKeyHasher(key);
+	const apiKey = await getApiKey$1(ctx, hashedKey, lookupOpts);
 	if (!apiKey) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.INVALID_API_KEY);
 	if (expectedConfigId !== void 0 && !configIdMatches(apiKey.configId, expectedConfigId)) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.INVALID_API_KEY);
 	const opts = resolveConfiguration(ctx.context, configurations, apiKey.configId);
@@ -1677,8 +1682,6 @@ async function validateApiKey({ key, ctx, lookupOpts, configurations, schema, pe
 		if (!apiKeyPermissions) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.KEY_NOT_FOUND);
 		if (!role(apiKeyPermissions).authorize(permissions).success) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.KEY_NOT_FOUND);
 	}
-	let remaining = apiKey.remaining;
-	let lastRefillAt = apiKey.lastRefillAt;
 	if (apiKey.remaining === 0 && apiKey.refillAmount === null) {
 		const deleteExhaustedKey = async () => {
 			if (opts.storage === "secondary-storage" && opts.fallbackToDatabase) {
@@ -1704,78 +1707,257 @@ async function validateApiKey({ key, ctx, lookupOpts, configurations, schema, pe
 		}));
 		else await deleteExhaustedKey();
 		throw APIError$1.from("TOO_MANY_REQUESTS", API_KEY_ERROR_CODES.USAGE_EXCEEDED);
-	} else if (remaining !== null) {
-		const now = Date.now();
-		const refillInterval = apiKey.refillInterval;
-		const refillAmount = apiKey.refillAmount;
-		const lastTime = new Date(lastRefillAt ?? apiKey.createdAt).getTime();
-		if (refillInterval && refillAmount) {
-			if (now - lastTime > refillInterval) {
-				remaining = refillAmount;
-				lastRefillAt = /* @__PURE__ */ new Date();
-			}
+	}
+	return {
+		apiKey: opts.storage === "database" || opts.storage === "secondary-storage" && opts.fallbackToDatabase ? await claimUsageInDatabase({
+			ctx,
+			apiKey,
+			opts,
+			hashedKey
+		}) : await claimUsageInSecondaryStorage({
+			ctx,
+			apiKey,
+			opts,
+			hashedKey
+		}),
+		opts
+	};
+}
+/**
+* Atomically consume quota and a rate-limit slot against the database row, the
+* source of truth for `database` and `secondary-storage` + `fallbackToDatabase`
+* modes. Each guarded `incrementOne` only mutates the row while the guard still
+* holds, so concurrent verifications cannot drive `remaining` below zero or push
+* `requestCount` past the configured max. The cache (when present) is refreshed
+* from the resulting row.
+*/
+async function claimUsageInDatabase({ ctx, apiKey, opts, hashedKey }) {
+	let row = apiKey;
+	if (apiKey.remaining !== null) row = await consumeRemaining(ctx, apiKey);
+	row = await consumeRateLimit(ctx, row, opts);
+	const finalRow = await ctx.context.adapter.update({
+		model: API_KEY_TABLE_NAME,
+		where: [{
+			field: "id",
+			value: row.id
+		}],
+		update: { updatedAt: /* @__PURE__ */ new Date() }
+	});
+	if (!finalRow) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.INVALID_API_KEY);
+	if (opts.storage === "secondary-storage" && opts.fallbackToDatabase) await setApiKey(ctx, finalRow, opts);
+	return finalRow;
+}
+/**
+* Guarded quota consumption. When a refill is due, exactly one verification wins
+* the refill (compare-and-swap on the observed `lastRefillAt`); any concurrent
+* verification falls through to the plain guarded decrement against the refilled
+* value. The decrement only applies while `remaining > 0`, so it can never go
+* negative. Returns the updated row; throws when the quota is exhausted.
+*/
+async function consumeRemaining(ctx, apiKey) {
+	const now = /* @__PURE__ */ new Date();
+	const { refillInterval, refillAmount } = apiKey;
+	if (refillInterval && refillAmount) {
+		const lastTime = new Date(apiKey.lastRefillAt ?? apiKey.createdAt).getTime();
+		if (now.getTime() - lastTime > refillInterval) {
+			const refilled = await ctx.context.adapter.incrementOne({
+				model: API_KEY_TABLE_NAME,
+				where: [{
+					field: "id",
+					value: apiKey.id
+				}, {
+					field: "lastRefillAt",
+					value: apiKey.lastRefillAt
+				}],
+				increment: {},
+				set: {
+					remaining: refillAmount - 1,
+					lastRefillAt: now
+				}
+			});
+			if (refilled) return refilled;
 		}
-		if (remaining === 0) throw APIError$1.from("TOO_MANY_REQUESTS", API_KEY_ERROR_CODES.USAGE_EXCEEDED);
-		else remaining--;
 	}
-	const { message, success, update, tryAgainIn } = isRateLimited(apiKey, opts);
-	if (success === false) throw new APIError$1("TOO_MANY_REQUESTS", {
-		message: message ?? void 0,
+	const decremented = await ctx.context.adapter.incrementOne({
+		model: API_KEY_TABLE_NAME,
+		where: [{
+			field: "id",
+			value: apiKey.id
+		}, {
+			field: "remaining",
+			operator: "gt",
+			value: 0
+		}],
+		increment: { remaining: -1 }
+	});
+	if (!decremented) throw APIError$1.from("TOO_MANY_REQUESTS", API_KEY_ERROR_CODES.USAGE_EXCEEDED);
+	return decremented;
+}
+/**
+* Guarded rate-limit consumption. The common in-window path increments
+* `requestCount` only while it is below the max (compare-and-swap), so a burst
+* of concurrent verifications can never exceed the limit. Window resets and the
+* first request in a window are guarded conditional sets; a request that loses
+* every guard within an active window is rejected. Returns the updated row, or
+* the unchanged row when rate limiting does not apply.
+*/
+async function consumeRateLimit(ctx, apiKey, opts) {
+	const decision = evaluateRateLimit(apiKey, opts);
+	if (decision.type === "deny") throw new APIError$1("TOO_MANY_REQUESTS", {
+		message: decision.message,
 		code: "RATE_LIMITED",
-		details: { tryAgainIn }
+		details: { tryAgainIn: decision.tryAgainIn }
 	});
-	const updated = {
-		...apiKey,
-		...update,
-		remaining,
-		lastRefillAt,
-		updatedAt: /* @__PURE__ */ new Date()
-	};
-	const performUpdate = async () => {
-		if (opts.storage === "database") return ctx.context.adapter.update({
-			model: API_KEY_TABLE_NAME,
+	if (decision.type === "skip") {
+		if (decision.lastRequest === null) return apiKey;
+		return await ctx.context.adapter.update({
+			model: "apikey",
 			where: [{
 				field: "id",
 				value: apiKey.id
 			}],
-			update: {
-				...updated,
-				id: void 0
-			}
-		});
-		else if (opts.storage === "secondary-storage" && opts.fallbackToDatabase) {
-			const dbUpdated = await ctx.context.adapter.update({
-				model: API_KEY_TABLE_NAME,
-				where: [{
+			update: { lastRequest: decision.lastRequest }
+		}) ?? apiKey;
+	}
+	if (decision.type === "increment") {
+		const incremented = await ctx.context.adapter.incrementOne({
+			model: API_KEY_TABLE_NAME,
+			where: [
+				{
 					field: "id",
 					value: apiKey.id
-				}],
-				update: {
-					...updated,
-					id: void 0
+				},
+				{
+					field: "lastRequest",
+					operator: "gt",
+					value: decision.windowStart
+				},
+				{
+					field: "requestCount",
+					operator: "lt",
+					value: decision.max
 				}
-			});
-			if (dbUpdated) await setApiKey(ctx, dbUpdated, opts);
-			return dbUpdated;
-		} else {
-			await setApiKey(ctx, updated, opts);
-			return updated;
+			],
+			increment: { requestCount: 1 },
+			set: { lastRequest: decision.now }
+		});
+		if (incremented) return incremented;
+		const fresh = await ctx.context.adapter.findOne({
+			model: API_KEY_TABLE_NAME,
+			where: [{
+				field: "id",
+				value: apiKey.id
+			}]
+		});
+		if (!fresh) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.INVALID_API_KEY);
+		return consumeRateLimit(ctx, fresh, opts);
+	}
+	const windowGuard = decision.type === "reset" ? {
+		field: "lastRequest",
+		operator: "lte",
+		value: decision.windowStart
+	} : {
+		field: "lastRequest",
+		operator: "eq",
+		value: null
+	};
+	const started = await ctx.context.adapter.incrementOne({
+		model: API_KEY_TABLE_NAME,
+		where: [{
+			field: "id",
+			value: apiKey.id
+		}, windowGuard],
+		increment: {},
+		set: {
+			requestCount: 1,
+			lastRequest: decision.now
+		}
+	});
+	if (started) return started;
+	const fresh = await ctx.context.adapter.findOne({
+		model: API_KEY_TABLE_NAME,
+		where: [{
+			field: "id",
+			value: apiKey.id
+		}]
+	});
+	if (!fresh) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.INVALID_API_KEY);
+	return consumeRateLimit(ctx, fresh, opts);
+}
+/**
+* Secondary-storage-only mode has no database row to guard, so quota and
+* rate-limit consumption stays a read-modify-write merge over the serialized
+* key. This is the residual non-atomic path; strict enforcement requires the
+* database (use `fallbackToDatabase`) or an atomic secondary-storage primitive.
+* FIXME(api-key-secondary-atomic): back this with SecondaryStorage.increment on
+* `next` so secondary-storage-only mode enforces quota and rate limits atomically.
+*/
+async function claimUsageInSecondaryStorage({ ctx, apiKey, opts, hashedKey }) {
+	let remaining = apiKey.remaining;
+	let lastRefillAt = apiKey.lastRefillAt;
+	if (remaining !== null) {
+		const now = Date.now();
+		const { refillInterval, refillAmount } = apiKey;
+		const lastTime = new Date(lastRefillAt ?? apiKey.createdAt).getTime();
+		if (refillInterval && refillAmount && now - lastTime > refillInterval) {
+			remaining = refillAmount;
+			lastRefillAt = /* @__PURE__ */ new Date();
 		}
+		if (remaining === 0) throw APIError$1.from("TOO_MANY_REQUESTS", API_KEY_ERROR_CODES.USAGE_EXCEEDED);
+		remaining--;
+	}
+	const mutations = {
+		...applyRateLimitToSnapshot(apiKey, opts),
+		remaining,
+		lastRefillAt,
+		updatedAt: /* @__PURE__ */ new Date()
+	};
+	const performUpdate = async () => {
+		const fresh = await getApiKey$1(ctx, hashedKey, opts);
+		if (!fresh) return null;
+		const merged = {
+			...fresh,
+			...mutations
+		};
+		await setApiKey(ctx, merged, opts);
+		return merged;
 	};
-	let newApiKey = null;
 	if (opts.deferUpdates) {
 		ctx.context.runInBackground(performUpdate().catch((error) => {
 			ctx.context.logger.error("Failed to update API key:", error);
 		}));
-		newApiKey = updated;
-	} else {
-		newApiKey = await performUpdate();
-		if (!newApiKey) throw APIError$1.from("INTERNAL_SERVER_ERROR", API_KEY_ERROR_CODES.FAILED_TO_UPDATE_API_KEY);
+		return {
+			...apiKey,
+			...mutations
+		};
+	}
+	const updated = await performUpdate();
+	if (!updated) throw APIError$1.from("INTERNAL_SERVER_ERROR", API_KEY_ERROR_CODES.FAILED_TO_UPDATE_API_KEY);
+	return updated;
+}
+/**
+* Translate a rate-limit decision into a counter snapshot for the
+* secondary-storage merge write. Denials throw before any write.
+*/
+function applyRateLimitToSnapshot(apiKey, opts) {
+	const decision = evaluateRateLimit(apiKey, opts);
+	switch (decision.type) {
+		case "deny": throw new APIError$1("TOO_MANY_REQUESTS", {
+			message: decision.message,
+			code: "RATE_LIMITED",
+			details: { tryAgainIn: decision.tryAgainIn }
+		});
+		case "skip": return decision.lastRequest === null ? {} : { lastRequest: decision.lastRequest };
+		case "start":
+		case "reset": return {
+			lastRequest: decision.now,
+			requestCount: 1
+		};
+		case "increment": return {
+			lastRequest: decision.now,
+			requestCount: apiKey.requestCount + 1
+		};
 	}
-	return {
-		apiKey: newApiKey,
-		opts
-	};
 }
 const verifyApiKeyBodySchema = z.object({
 	configId: z.string().meta({ description: "Configuration ID to scope verification to. When omitted, the key is validated against its own configuration." }).optional(),
@@ -1783,7 +1965,7 @@ const verifyApiKeyBodySchema = z.object({
 	permissions: z.record(z.string(), z.array(z.string())).meta({ description: "The permissions to verify." }).optional()
 });
 function verifyApiKey({ configurations, schema, deleteAllExpiredApiKeys }) {
-	return createAuthEndpoint({
+	return createAuthEndpoint.serverOnly({
 		method: "POST",
 		body: verifyApiKeyBodySchema
 	}, async (ctx) => {

package/dist/{version-brpjhtFx.mjs → version-ZL7h_G4d.mjs}

@@ -35,6 +35,6 @@ const API_KEY_ERROR_CODES = defineErrorCodes({
 });
 //#endregion
 //#region src/version.ts
-const PACKAGE_VERSION = "1.6.15";
+const PACKAGE_VERSION = "1.6.17";
 //#endregion
 export { API_KEY_ERROR_CODES as n, PACKAGE_VERSION as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/api-key",
-  "version": "1.6.15",
+  "version": "1.6.17",
   "description": "API Key plugin for Better Auth.",
   "type": "module",
   "license": "MIT",
@@ -61,14 +61,14 @@
   },
   "devDependencies": {
     "tsdown": "0.21.1",
-    "@better-auth/core": "1.6.15",
-    "better-auth": "1.6.15"
+    "@better-auth/core": "1.6.17",
+    "better-auth": "1.6.17"
   },
   "peerDependencies": {
     "@better-auth/utils": "0.4.1",
-    "better-call": "1.3.5",
-    "@better-auth/core": "^1.6.15",
-    "better-auth": "^1.6.15"
+    "better-call": "1.3.6",
+    "@better-auth/core": "^1.6.17",
+    "better-auth": "^1.6.17"
   },
   "scripts": {
     "build": "tsdown",