@better-auth/api-key 1.7.0-beta.1 → 1.7.0-beta.10

package/dist/index.mjs

@@ -1,5 +1,6 @@
-import { n as API_KEY_ERROR_CODES, t as PACKAGE_VERSION } from "./version-Cgx_4P2P.mjs";
+import { n as API_KEY_ERROR_CODES, t as PACKAGE_VERSION } from "./version--lF5Z0S8.mjs";
 import { createAuthEndpoint, createAuthMiddleware } from "@better-auth/core/api";
+import { getIP } from "@better-auth/core/utils/ip";
 import { base64Url } from "@better-auth/utils/base64";
 import { createHash } from "@better-auth/utils/hash";
 import { BetterAuthError } from "better-auth";
@@ -10,11 +11,11 @@ import { APIError as APIError$1 } from "@better-auth/core/error";
 import { generateId } from "@better-auth/core/utils/id";
 import { safeJSONParse } from "@better-auth/core/utils/json";
 import * as z from "zod";
-import { isDevelopment, isTest } from "@better-auth/core/env";
-import { isValidIP, normalizeIP } from "@better-auth/core/utils/ip";
+import { mapConcurrent } from "@better-auth/core/utils/async";
 import { role } from "better-auth/plugins/access";
 import { parseJSON } from "better-auth/client";
 //#region src/adapter.ts
+const STORAGE_CONCURRENCY = 10;
 /**
 * Parses double-stringified metadata synchronously without updating the database.
 * Use this for reading metadata, then call migrateLegacyMetadataInBackground for DB updates.
@@ -165,49 +166,79 @@ async function getApiKeyByIdFromStorage(ctx, id, storage) {
 	return deserializeApiKey(await storage.get(key));
 }
 /**
-* Store API key in secondary storage
+* 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 tracked = (refListLocks.get(refKey) ?? Promise.resolve()).then(task, task).finally(() => {
+		if (refListLocks.get(refKey) === tracked) refListLocks.delete(refKey);
+	});
+	refListLocks.set(refKey, tracked);
+	return tracked;
+}
+/**
+* Read-modify-write the ref list:
+* used only when the list is the source of truth.
 */
-async function setApiKeyInStorage(ctx, apiKey, storage, ttl) {
+async function modifyRefList(storage, refKey, modify) {
+	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);
-	const hashedKey = apiKey.key;
-	const id = apiKey.id;
-	await storage.set(getStorageKeyByHashedKey(hashedKey), serialized, ttl);
-	await storage.set(getStorageKeyById(id), serialized, ttl);
 	const refKey = getStorageKeyByReferenceId(apiKey.referenceId);
-	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;
-	if (!keyIds.includes(id)) {
-		keyIds.push(id);
-		await storage.set(refKey, JSON.stringify(keyIds));
+	if (opts.fallbackToDatabase) {
+		await Promise.all([
+			storage.set(getStorageKeyByHashedKey(apiKey.key), serialized, ttl),
+			storage.set(getStorageKeyById(apiKey.id), serialized, ttl),
+			storage.delete(refKey)
+		]);
+		return;
 	}
+	await Promise.all([storage.set(getStorageKeyByHashedKey(apiKey.key), serialized, ttl), storage.set(getStorageKeyById(apiKey.id), serialized, ttl)]);
+	await modifyRefList(storage, refKey, (ids) => ids.includes(apiKey.id) ? ids : [...ids, apiKey.id]);
 }
 /**
 * Delete API key from secondary storage
 */
-async function deleteApiKeyFromStorage(ctx, apiKey, storage) {
-	const hashedKey = apiKey.key;
-	const id = apiKey.id;
-	const referenceId = apiKey.referenceId;
-	await storage.delete(getStorageKeyByHashedKey(hashedKey));
-	await storage.delete(getStorageKeyById(id));
-	const refKey = getStorageKeyByReferenceId(referenceId);
-	const refListData = await storage.get(refKey);
-	let keyIds = [];
-	if (refListData && typeof refListData === "string") try {
-		keyIds = JSON.parse(refListData);
-	} catch {
-		keyIds = [];
+async function deleteApiKeyFromStorage(ctx, apiKey, storage, opts) {
+	const refKey = getStorageKeyByReferenceId(apiKey.referenceId);
+	if (opts.fallbackToDatabase) {
+		await Promise.all([
+			storage.delete(getStorageKeyByHashedKey(apiKey.key)),
+			storage.delete(getStorageKeyById(apiKey.id)),
+			storage.delete(refKey)
+		]);
+		return;
 	}
-	else if (Array.isArray(refListData)) keyIds = refListData;
-	const filteredIds = keyIds.filter((keyId) => keyId !== id);
-	if (filteredIds.length === 0) await storage.delete(refKey);
-	else await storage.set(refKey, JSON.stringify(filteredIds));
+	await Promise.all([
+		storage.delete(getStorageKeyByHashedKey(apiKey.key)),
+		storage.delete(getStorageKeyById(apiKey.id)),
+		modifyRefList(storage, refKey, (ids) => ids.filter((keyId) => keyId !== apiKey.id))
+	]);
 }
 /**
 * Unified getter for API keys with support for all storage modes
@@ -233,7 +264,7 @@ async function getApiKey$1(ctx, hashedKey, opts) {
 				value: hashedKey
 			}]
 		});
-		if (dbKey && storage) await setApiKeyInStorage(ctx, dbKey, storage, calculateTTL(dbKey));
+		if (dbKey && storage) await setApiKeyInStorage(ctx, dbKey, storage, calculateTTL(dbKey), opts);
 		return dbKey;
 	}
 	if (opts.storage === "secondary-storage") {
@@ -272,7 +303,7 @@ async function getApiKeyById(ctx, id, opts) {
 				value: id
 			}]
 		});
-		if (dbKey && storage) await setApiKeyInStorage(ctx, dbKey, storage, calculateTTL(dbKey));
+		if (dbKey && storage) await setApiKeyInStorage(ctx, dbKey, storage, calculateTTL(dbKey), opts);
 		return dbKey;
 	}
 	if (opts.storage === "secondary-storage") {
@@ -296,7 +327,7 @@ async function setApiKey(ctx, apiKey, opts) {
 	if (opts.storage === "database") return;
 	if (opts.storage === "secondary-storage") {
 		if (!storage) throw new Error("Secondary storage is required when storage mode is 'secondary-storage'");
-		await setApiKeyInStorage(ctx, apiKey, storage, ttl);
+		await setApiKeyInStorage(ctx, apiKey, storage, ttl, opts);
 		return;
 	}
 }
@@ -308,7 +339,7 @@ async function deleteApiKey$1(ctx, apiKey, opts) {
 	if (opts.storage === "database") return;
 	if (opts.storage === "secondary-storage") {
 		if (!storage) throw new Error("Secondary storage is required when storage mode is 'secondary-storage'");
-		await deleteApiKeyFromStorage(ctx, apiKey, storage);
+		await deleteApiKeyFromStorage(ctx, apiKey, storage, opts);
 		return;
 	}
 }
@@ -378,11 +409,7 @@ async function listApiKeys$1(ctx, referenceId, opts, paginationOpts) {
 			}
 			else if (Array.isArray(refListData)) keyIds = refListData;
 			if (keyIds.length > 0) {
-				const apiKeys = [];
-				for (const id of keyIds) {
-					const apiKey = await getApiKeyByIdFromStorage(ctx, id, storage);
-					if (apiKey) apiKeys.push(apiKey);
-				}
+				const apiKeys = (await mapConcurrent(keyIds, (id) => getApiKeyByIdFromStorage(ctx, id, storage), { concurrency: STORAGE_CONCURRENCY })).filter((key) => key !== null && key !== void 0);
 				return {
 					apiKeys: applySortingAndPagination(apiKeys, sortBy, sortDirection, limit, offset),
 					total: apiKeys.length
@@ -409,11 +436,8 @@ async function listApiKeys$1(ctx, referenceId, opts, paginationOpts) {
 			}]
 		})]);
 		if (storage && dbKeys.length > 0) {
-			const keyIds = [];
-			for (const apiKey of dbKeys) {
-				await setApiKeyInStorage(ctx, apiKey, storage, calculateTTL(apiKey));
-				keyIds.push(apiKey.id);
-			}
+			await mapConcurrent(dbKeys, (apiKey) => setApiKeyInStorage(ctx, apiKey, storage, calculateTTL(apiKey), opts), { concurrency: STORAGE_CONCURRENCY });
+			const keyIds = dbKeys.map((apiKey) => apiKey.id);
 			await storage.set(refKey, JSON.stringify(keyIds));
 		}
 		return {
@@ -442,11 +466,7 @@ async function listApiKeys$1(ctx, referenceId, opts, paginationOpts) {
 			apiKeys: [],
 			total: 0
 		};
-		const apiKeys = [];
-		for (const id of keyIds) {
-			const apiKey = await getApiKeyByIdFromStorage(ctx, id, storage);
-			if (apiKey) apiKeys.push(apiKey);
-		}
+		const apiKeys = (await mapConcurrent(keyIds, (id) => getApiKeyByIdFromStorage(ctx, id, storage), { concurrency: STORAGE_CONCURRENCY })).filter((key) => key !== null && key !== void 0);
 		return {
 			apiKeys: applySortingAndPagination(apiKeys, sortBy, sortDirection, limit, offset),
 			total: apiKeys.length
@@ -555,21 +575,6 @@ const getDate = (span, unit = "ms") => {
 function isAPIError(error) {
 	return error instanceof APIError || error instanceof APIError$1 || error?.name === "APIError";
 }
-const LOCALHOST_IP = "127.0.0.1";
-function getIp(req, options) {
-	if (options.advanced?.ipAddress?.disableIpTracking) return null;
-	const headers = "headers" in req ? req.headers : req;
-	const ipHeaders = options.advanced?.ipAddress?.ipAddressHeaders || ["x-forwarded-for"];
-	for (const key of ipHeaders) {
-		const value = "get" in headers ? headers.get(key) : headers[key];
-		if (typeof value === "string") {
-			const ip = value.split(",")[0].trim();
-			if (isValidIP(ip)) return normalizeIP(ip, { ipv6Subnet: options.advanced?.ipAddress?.ipv6Subnet });
-		}
-	}
-	if (isTest() || isDevelopment()) return LOCALHOST_IP;
-	return null;
-}
 //#endregion
 //#region src/routes/create-api-key.ts
 const createApiKeyBodySchema = z.object({
@@ -724,7 +729,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);
@@ -856,7 +861,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) {
@@ -1285,18 +1290,16 @@ function listApiKeys({ configurations, schema, deleteAllExpiredApiKeys }) {
 				const storageKey = getStorageIdentifier(config);
 				if (!storageGroups.has(storageKey)) storageGroups.set(storageKey, config);
 			}
+			const groupResults = await Promise.all([...storageGroups.values()].map((opts) => listApiKeys$1(ctx, referenceId, opts, {
+				limit: void 0,
+				offset: void 0,
+				sortBy: ctx.query?.sortBy,
+				sortDirection: ctx.query?.sortDirection
+			})));
 			const seenIds = /* @__PURE__ */ new Set();
-			for (const opts of storageGroups.values()) {
-				const { apiKeys } = await listApiKeys$1(ctx, referenceId, opts, {
-					limit: void 0,
-					offset: void 0,
-					sortBy: ctx.query?.sortBy,
-					sortDirection: ctx.query?.sortDirection
-				});
-				for (const key of apiKeys) if (!seenIds.has(key.id)) {
-					seenIds.add(key.id);
-					allApiKeys.push(key);
-				}
+			for (const { apiKeys } of groupResults) for (const key of apiKeys) if (!seenIds.has(key.id)) {
+				seenIds.add(key.id);
+				allApiKeys.push(key);
 			}
 		}
 		let filteredApiKeys = allApiKeys.filter((key) => {
@@ -1473,7 +1476,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);
@@ -1571,76 +1574,63 @@ 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({ hashedKey, ctx, opts, schema, permissions }) {
-	const apiKey = await getApiKey$1(ctx, hashedKey, opts);
+async function validateApiKey({ key, ctx, lookupOpts, configurations, schema, permissions, expectedConfigId, runCustomValidator }) {
+	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);
+	if (runCustomValidator && opts.customAPIKeyValidator) {
+		if (!await opts.customAPIKeyValidator({
+			ctx,
+			key
+		})) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.KEY_NOT_FOUND);
+	}
 	if (apiKey.enabled === false) throw APIError$1.from("UNAUTHORIZED", API_KEY_ERROR_CODES.KEY_DISABLED);
 	if (apiKey.expiresAt) {
 		if (Date.now() > new Date(apiKey.expiresAt).getTime()) {
@@ -1675,8 +1665,6 @@ async function validateApiKey({ hashedKey, ctx, opts, schema, permissions }) {
 		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) {
@@ -1702,89 +1690,271 @@ async function validateApiKey({ hashedKey, ctx, opts, schema, permissions }) {
 		}));
 		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("UNAUTHORIZED", {
-		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 newApiKey;
 }
 const verifyApiKeyBodySchema = z.object({
-	configId: z.string().meta({ description: "The configuration ID to use for verification. If not provided, the default configuration will be used." }).optional(),
+	configId: z.string().meta({ description: "Configuration ID to scope verification to. When omitted, the key is validated against its own configuration." }).optional(),
 	key: z.string().meta({ description: "The key to verify" }),
 	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) => {
 		const { configId, key } = ctx.body;
 		const lookupOpts = resolveConfiguration(ctx.context, configurations, configId);
-		if (lookupOpts.customAPIKeyValidator) {
+		if (configId !== void 0 && lookupOpts.customAPIKeyValidator) {
 			if (!await lookupOpts.customAPIKeyValidator({
 				ctx,
 				key
@@ -1797,17 +1967,22 @@ function verifyApiKey({ configurations, schema, deleteAllExpiredApiKeys }) {
 				key: null
 			});
 		}
-		const hashed = lookupOpts.disableKeyHashing ? key : await defaultKeyHasher(key);
 		let apiKey = null;
+		let opts;
 		try {
-			apiKey = await validateApiKey({
-				hashedKey: hashed,
+			const result = await validateApiKey({
+				key,
 				permissions: ctx.body.permissions,
 				ctx,
-				opts: lookupOpts,
-				schema
+				lookupOpts,
+				configurations,
+				schema,
+				expectedConfigId: configId,
+				runCustomValidator: configId === void 0
 			});
-			if ((apiKey ? resolveConfiguration(ctx.context, configurations, apiKey.configId) : lookupOpts).deferUpdates) ctx.context.runInBackground(deleteAllExpiredApiKeys(ctx.context).catch((err) => {
+			apiKey = result.apiKey;
+			opts = result.opts;
+			if (opts.deferUpdates) ctx.context.runInBackground(deleteAllExpiredApiKeys(ctx.context).catch((err) => {
 				ctx.context.logger.error("Failed to delete expired API keys:", err);
 			}));
 		} catch (error) {
@@ -1834,7 +2009,6 @@ function verifyApiKey({ configurations, schema, deleteAllExpiredApiKeys }) {
 			key: 1,
 			permissions: void 0
 		};
-		const opts = apiKey ? resolveConfiguration(ctx.context, configurations, apiKey.configId) : lookupOpts;
 		let migratedMetadata = null;
 		if (apiKey) migratedMetadata = await migrateDoubleStringifiedMetadata(ctx, apiKey, opts);
 		returningApiKey.permissions = returningApiKey.permissions ? safeJSONParse(returningApiKey.permissions) : null;
@@ -2163,11 +2337,13 @@ function apiKey(_configurations, _options) {
 						key
 					})) throw APIError.from("FORBIDDEN", API_KEY_ERROR_CODES.INVALID_API_KEY);
 				}
-				const apiKey = await validateApiKey({
-					hashedKey: config.disableKeyHashing ? key : await defaultKeyHasher(key),
+				const { apiKey } = await validateApiKey({
+					key,
 					ctx,
-					opts: config,
-					schema
+					lookupOpts: config,
+					configurations,
+					schema,
+					expectedConfigId: config.configId
 				});
 				const cleanupTask = deleteAllExpiredApiKeys(ctx.context).catch((err) => {
 					ctx.context.logger.error("Failed to delete expired API keys:", err);
@@ -2189,7 +2365,7 @@ function apiKey(_configurations, _options) {
 						token: key,
 						userId: apiKey.referenceId,
 						userAgent: ctx.request?.headers.get("user-agent") ?? null,
-						ipAddress: ctx.request ? getIp(ctx.request, ctx.context.options) : null,
+						ipAddress: ctx.request ? getIP(ctx.request, ctx.context.options) : null,
 						createdAt: /* @__PURE__ */ new Date(),
 						updatedAt: /* @__PURE__ */ new Date(),
 						expiresAt: apiKey.expiresAt || getDate(ctx.context.options.session?.expiresIn || 3600 * 24 * 7, "ms")