kitcn 0.22.1 → 0.24.0

package/dist/ratelimit/index.js

@@ -1,6 +1,6 @@
 import { u as requireMutationCtx } from "../api-entry-N3nBOlI2.js";
-import { _ as CRPCError } from "../builder-Dwy6D2QA.js";
-import { t as definePlugin } from "../middleware-qzHEHaDy.js";
+import { _ as CRPCError } from "../builder-CsxVc5xC.js";
+import { t as definePlugin } from "../middleware-DUd1Sj39.js";
 import { v } from "convex/values";
 import { mutationGeneric, queryGeneric } from "convex/server";
 
@@ -422,94 +422,6 @@ function createReadDedupeCache() {
 	};
 }
 
-//#endregion
-//#region src/ratelimit/core/deny-list.ts
-const DEFAULT_BLOCK_MS = 6e4;
-const THRESHOLD_BLOCK_MS = 1440 * 60 * 1e3;
-const protectionState = /* @__PURE__ */ new Map();
-function getState(prefix) {
-	let state = protectionState.get(prefix);
-	if (!state) {
-		state = {
-			hits: /* @__PURE__ */ new Map(),
-			blockedUntil: /* @__PURE__ */ new Map()
-		};
-		protectionState.set(prefix, state);
-	}
-	return state;
-}
-function pickDeniedValue(options) {
-	const members = getMembers(options.identifier, options.request);
-	const state = getState(options.prefix);
-	for (const member of members) {
-		const until = state.blockedUntil.get(member.value);
-		if (until && until > Date.now()) return member.value;
-		if (until && until <= Date.now()) state.blockedUntil.delete(member.value);
-	}
-	if (!options.lists) return;
-	const listMatchers = [
-		{
-			values: options.lists.identifiers,
-			kind: "identifier"
-		},
-		{
-			values: options.lists.ips,
-			kind: "ip"
-		},
-		{
-			values: options.lists.userAgents,
-			kind: "userAgent"
-		},
-		{
-			values: options.lists.countries,
-			kind: "country"
-		}
-	];
-	for (const matcher of listMatchers) {
-		if (!matcher.values || matcher.values.length === 0) continue;
-		const valueSet = new Set(matcher.values);
-		const hit = members.find((member) => member.kind === matcher.kind && valueSet.has(member.value));
-		if (hit) {
-			state.blockedUntil.set(hit.value, Date.now() + DEFAULT_BLOCK_MS);
-			return hit.value;
-		}
-	}
-}
-function recordRatelimitFailure(options) {
-	const members = getMembers(options.identifier, options.request);
-	const state = getState(options.prefix);
-	for (const member of members) {
-		const next = (state.hits.get(member.value) ?? 0) + 1;
-		state.hits.set(member.value, next);
-		if (next >= options.threshold) state.blockedUntil.set(member.value, Date.now() + THRESHOLD_BLOCK_MS);
-	}
-}
-function clearProtection(prefix, identifier) {
-	const state = getState(prefix);
-	state.hits.delete(identifier);
-	state.blockedUntil.delete(identifier);
-}
-function getMembers(identifier, request) {
-	return [
-		{
-			kind: "identifier",
-			value: identifier
-		},
-		{
-			kind: "ip",
-			value: request?.ip
-		},
-		{
-			kind: "userAgent",
-			value: request?.userAgent
-		},
-		{
-			kind: "country",
-			value: request?.country
-		}
-	].filter((member) => Boolean(member.value));
-}
-
 //#endregion
 //#region src/ratelimit/store/convex-store.ts
 const RATE_LIMIT_STATE_TABLE = "ratelimitState";
@@ -584,6 +496,20 @@ var ConvexRatelimitStore = class ConvexRatelimitStore {
 			this.invalidateAll(name, key);
 		});
 	}
+	async deleteStatesBefore(before, limit) {
+		return this.withSetupGuidance(async () => {
+			const db = this.getWriter();
+			const rows = await db.query(RATE_LIMIT_STATE_TABLE).withIndex("by_ts", (q) => q.lt("ts", before)).take(limit + 1);
+			const selected = rows.slice(0, limit);
+			for (const row of selected) await db.delete(RATE_LIMIT_STATE_TABLE, row._id);
+			this.dedupe.clear();
+			this.listDedupe.clear();
+			return {
+				deleted: selected.length,
+				hasMore: rows.length > limit
+			};
+		});
+	}
 	async getDynamicLimit(prefix) {
 		return this.withSetupGuidance(async () => {
 			const db = this.getReader();
@@ -663,6 +589,227 @@ function withMissingTableGuidance(error) {
 	return new Error(`${missingTableGuidance} Original error: ${message}`, { cause: error instanceof Error ? error : void 0 });
 }
 
+//#endregion
+//#region src/ratelimit/maintenance.ts
+const DEFAULT_CLEANUP_LIMIT = 100;
+const MAX_CLEANUP_LIMIT = 1e3;
+/** Deletes one on-demand batch of state older than the caller-owned cutoff. */
+async function cleanupRatelimitState(db, options) {
+	if (!Number.isFinite(options.before)) throw new Error("before must be a finite timestamp");
+	const limit = options.limit ?? DEFAULT_CLEANUP_LIMIT;
+	if (!Number.isInteger(limit) || limit < 1 || limit > MAX_CLEANUP_LIMIT) throw new Error(`limit must be an integer from 1 to ${MAX_CLEANUP_LIMIT}`);
+	return new ConvexRatelimitStore(db).deleteStatesBefore(options.before, limit);
+}
+
+//#endregion
+//#region src/ratelimit/core/deny-list.ts
+const DEFAULT_BLOCK_MS = 6e4;
+const THRESHOLD_BLOCK_MS = 1440 * 60 * 1e3;
+/**
+* Only failures inside this rolling window count toward the threshold. Without
+* decay `hits` is an all-time counter, so any shared
+* NAT/carrier IP eventually accumulates `denyListThreshold` lifetime failures
+* and blocks every user behind it.
+*/
+const HITS_WINDOW_MS = 600 * 1e3;
+/**
+* Hard ceiling on tracked members per prefix. `userAgent` is an
+* attacker-forgeable header, so without a cap one source can plant an unbounded
+* number of permanent entries in this module-scope map.
+*/
+const MAX_TRACKED_MEMBERS = 4096;
+/** Bound timestamp storage even when applications configure a high threshold. */
+const MAX_TRACKED_HITS = 65536;
+/** Ceiling on a stored key so attacker-chosen value length cannot inflate cost. */
+const MAX_MEMBER_KEY_LENGTH = 128;
+/**
+* Sweeping expired entries is O(tracked members), so it runs on an interval
+* rather than per denial — the hot path under a flood is the denial path.
+* Correctness does not depend on it: an expired hit already reads as absent.
+*/
+const PRUNE_INTERVAL_MS = 3e4;
+const protectionState = /* @__PURE__ */ new Map();
+function getState(prefix) {
+	let state = protectionState.get(prefix);
+	if (!state) {
+		state = {
+			hitCount: 0,
+			members: /* @__PURE__ */ new Map(),
+			nextPruneAt: 0
+		};
+		protectionState.set(prefix, state);
+	}
+	return state;
+}
+/**
+* Storage key for a member value. Overlong values are truncated and tagged with
+* their length and hash, so a long forged header cannot inflate retained state
+* or share protection state with another value that has the same prefix.
+*/
+function memberKey(value) {
+	if (value.length <= MAX_MEMBER_KEY_LENGTH) return value;
+	return `${value.slice(0, MAX_MEMBER_KEY_LENGTH)}#${value.length}:${hashMember(value)}`;
+}
+function hashMember(value) {
+	let hash = 14695981039346656037n;
+	for (let index = 0; index < value.length; index++) {
+		hash ^= BigInt(value.charCodeAt(index));
+		hash = BigInt.asUintN(64, hash * 1099511628211n);
+	}
+	return hash.toString(16).padStart(16, "0");
+}
+function pruneExpired(state, now) {
+	const cutoff = now - HITS_WINDOW_MS;
+	for (const [key, member] of state.members) {
+		const retainedHits = member.hits.filter((hitAt) => hitAt > cutoff);
+		state.hitCount -= member.hits.length - retainedHits.length;
+		member.hits = retainedHits;
+		if (member.blockedUntil !== void 0 && member.blockedUntil <= now) member.blockedUntil = void 0;
+		if (member.hits.length === 0 && member.blockedUntil === void 0) state.members.delete(key);
+	}
+}
+function evictLeastRecentHitOnly(state) {
+	for (const [key, member] of state.members) {
+		if (member.blockedUntil !== void 0) continue;
+		state.hitCount -= member.hits.length;
+		member.hits = [];
+		state.members.delete(key);
+		return true;
+	}
+	return false;
+}
+function evictLeastRecentMember(state) {
+	for (const [key, member] of state.members) {
+		state.hitCount -= member.hits.length;
+		member.hits = [];
+		state.members.delete(key);
+		return;
+	}
+}
+function getMember(state, key) {
+	const existing = state.members.get(key);
+	if (existing) {
+		state.members.delete(key);
+		state.members.set(key, existing);
+		return existing;
+	}
+	if (state.members.size >= MAX_TRACKED_MEMBERS && !evictLeastRecentHitOnly(state)) evictLeastRecentMember(state);
+	const member = { hits: [] };
+	state.members.set(key, member);
+	return member;
+}
+function recordHit(state, key, threshold, now) {
+	const member = getMember(state, key);
+	const cutoff = now - HITS_WINDOW_MS;
+	const retainedHits = member.hits.filter((hitAt) => hitAt > cutoff);
+	state.hitCount -= member.hits.length - retainedHits.length;
+	member.hits = retainedHits;
+	while (state.hitCount >= MAX_TRACKED_HITS && evictLeastRecentHitOnly(state));
+	if (!state.members.has(key)) state.members.set(key, member);
+	member.hits.push(now);
+	state.hitCount += 1;
+	if (member.hits.length >= threshold) {
+		member.blockedUntil = now + THRESHOLD_BLOCK_MS;
+		state.hitCount -= member.hits.length;
+		member.hits = [];
+	}
+}
+function pickDeniedValue(options) {
+	const members = getMembers(options.identifier, options.request);
+	const state = getState(options.prefix);
+	const now = Date.now();
+	if (now >= state.nextPruneAt) {
+		pruneExpired(state, now);
+		state.nextPruneAt = now + PRUNE_INTERVAL_MS;
+	}
+	for (const member of members) {
+		const key = memberKey(member.value);
+		const tracked = state.members.get(key);
+		if (tracked?.blockedUntil && tracked.blockedUntil > now) {
+			state.members.delete(key);
+			state.members.set(key, tracked);
+			return member.value;
+		}
+		if (tracked?.blockedUntil && tracked.blockedUntil <= now) {
+			tracked.blockedUntil = void 0;
+			if (tracked.hits.length === 0) state.members.delete(key);
+		}
+	}
+	if (!options.lists) return;
+	const listMatchers = [
+		{
+			values: options.lists.identifiers,
+			kind: "identifier"
+		},
+		{
+			values: options.lists.ips,
+			kind: "ip"
+		},
+		{
+			values: options.lists.userAgents,
+			kind: "userAgent"
+		},
+		{
+			values: options.lists.countries,
+			kind: "country"
+		}
+	];
+	for (const matcher of listMatchers) {
+		if (!matcher.values || matcher.values.length === 0) continue;
+		const valueSet = new Set(matcher.values);
+		const hit = members.find((member) => member.kind === matcher.kind && valueSet.has(member.value));
+		if (hit) {
+			const tracked = getMember(state, memberKey(hit.value));
+			tracked.blockedUntil = now + DEFAULT_BLOCK_MS;
+			state.hitCount -= tracked.hits.length;
+			tracked.hits = [];
+			return hit.value;
+		}
+	}
+}
+function recordRatelimitFailure(options) {
+	const members = getMembers(options.identifier, options.request);
+	const state = getState(options.prefix);
+	const now = Date.now();
+	if (now >= state.nextPruneAt) {
+		pruneExpired(state, now);
+		state.nextPruneAt = now + PRUNE_INTERVAL_MS;
+	}
+	for (const member of members) recordHit(state, memberKey(member.value), options.threshold, now);
+}
+/**
+* Clears the identifier only. Widening this to every request member would let
+* an attacker reset their own ip/userAgent counters with a single success, or
+* clear a victim's counter by forging their user-agent.
+*/
+function clearProtection(prefix, identifier) {
+	const state = getState(prefix);
+	const key = memberKey(identifier);
+	const member = state.members.get(key);
+	state.hitCount -= member?.hits.length ?? 0;
+	state.members.delete(key);
+}
+function getMembers(identifier, request) {
+	return [
+		{
+			kind: "identifier",
+			value: identifier
+		},
+		{
+			kind: "ip",
+			value: request?.ip
+		},
+		{
+			kind: "userAgent",
+			value: request?.userAgent
+		},
+		{
+			kind: "country",
+			value: request?.country
+		}
+	].filter((member) => Boolean(member.value));
+}
+
 //#endregion
 //#region src/ratelimit/ratelimit.ts
 const DEFAULT_PREFIX = "kitcn/ratelimit";
@@ -859,7 +1006,7 @@ var Ratelimit = class Ratelimit {
 		return new Ratelimit({
 			...this.config,
 			db,
-			ephemeralCache: this.blockCacheSource
+			ephemeralCache: this.blockCacheSource ?? false
 		});
 	}
 	async evaluate(identifier, request, consume) {
@@ -1143,18 +1290,21 @@ const RatelimitPlugin = definePlugin("ratelimit", ({ options }) => {
 		meta
 	});
 	const tier = await options.getTier(user);
-	const identifier = await options.getIdentifier({
+	const requestArgs = {
 		ctx,
 		meta,
 		user,
-		bucket
+		bucket,
+		tier
+	};
+	const signals = await options.getSignals(requestArgs);
+	const identifier = await options.getIdentifier({
+		...requestArgs,
+		signals
 	});
 	const args = {
-		ctx,
-		meta,
-		user,
-		bucket,
-		tier,
+		...requestArgs,
+		signals,
 		identifier
 	};
 	if (!(await new Ratelimit({
@@ -1163,8 +1313,12 @@ const RatelimitPlugin = definePlugin("ratelimit", ({ options }) => {
 		limiter: resolveBucketLimiter(options, bucket, tier),
 		failureMode: options.failureMode,
 		enableProtection: options.enableProtection,
-		denyListThreshold: options.denyListThreshold
-	}).limit(identifier, await options.getSignals(args))).success) throw new CRPCError({
+		denyListThreshold: options.denyListThreshold,
+		denyList: options.denyList,
+		dynamicLimits: options.dynamicLimits,
+		timeout: options.timeout,
+		ephemeralCache: options.ephemeralCache
+	}).limit(identifier, signals)).success) throw new CRPCError({
 		code: "TOO_MANY_REQUESTS",
 		message: await resolveMessage(options, args)
 	});
@@ -1180,4 +1334,4 @@ const DAY = 24 * HOUR;
 const WEEK = 7 * DAY;
 
 //#endregion
-export { DAY, HOUR, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, RatelimitPlugin, SECOND, WEEK, applyDynamicLimit, calculateRatelimit, fixedWindow, slidingWindow, snapshotToState, toMs, tokenBucket };
+export { DAY, HOUR, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, RatelimitPlugin, SECOND, WEEK, applyDynamicLimit, calculateRatelimit, cleanupRatelimitState, fixedWindow, slidingWindow, snapshotToState, toMs, tokenBucket };

package/dist/react/index.d.ts

@@ -416,6 +416,12 @@ interface CRPCHttpRouter<TRecord extends HttpRouterRecord> {
 }
 //#endregion
 //#region src/crpc/http-types.d.ts
+/** Exact cache key for one route + args, as stored in the QueryClient */
+type HttpQueryKey = readonly ['httpQuery', string, unknown];
+/** Route-wide prefix key that matches every args variant of one route */
+type HttpQueryPrefixKey = readonly ['httpQuery', string];
+/** Mutation key for HTTP endpoints */
+type HttpMutationKey = readonly ['httpMutation', string];
 /** Error codes that can be returned from HTTP endpoints */
 type HttpErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'METHOD_NOT_SUPPORTED' | 'CONFLICT' | 'UNPROCESSABLE_CONTENT' | 'TOO_MANY_REQUESTS' | 'INTERNAL_SERVER_ERROR' | 'UNKNOWN';
 /** HTTP client error */
@@ -692,9 +698,6 @@ type InferHttpClientArgs<T> = T extends HttpProcedure<infer TInput, infer _TOutp
 }> : HttpInputArgs;
 /** Infer output type from HttpProcedure */
 type InferHttpOutput<T> = T extends HttpProcedure<infer _TInput, infer TOutput, infer _TParams, infer _TQuery> ? TOutput extends UnsetMarker ? unknown : TOutput extends z.ZodTypeAny ? z.infer<TOutput> : unknown : unknown;
-/** Query key with args (3-element) or prefix key without args (2-element) for invalidation */
-type HttpQueryKey = readonly ['httpQuery', string, unknown] | readonly ['httpQuery', string];
-type HttpMutationKey = readonly ['httpMutation', string];
 type ReservedQueryOptions$1 = 'queryKey' | 'queryFn';
 type ReservedMutationOptions$1 = 'mutationFn';
 /** Query options for GET HTTP endpoints - compatible with both useQuery and useSuspenseQuery */
@@ -713,8 +716,8 @@ type HttpMutationOptions<T extends HttpProcedure> = DistributiveOmit<HttpMutatio
  * - mutationOptions: For one-time actions like exports (useMutation)
  */
 type DecorateHttpQuery<T extends HttpProcedure> = {
-  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get query key for QueryClient methods (with args = exact match, without = prefix) */
-  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter for QueryClient methods (e.g., invalidateQueries) */
+  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get the exact cache key these args are stored under (getQueryData/setQueryData) */
+  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter matching every args variant (e.g., invalidateQueries) */
   queryFilter: (args?: InferHttpClientArgs<T>, filters?: DistributiveOmit<QueryFilters, 'queryKey'>) => QueryFilters; /** Mutation options for GET endpoints (exports, downloads - no caching) */
   mutationOptions: (opts?: HttpMutationOptions<T>) => HttpMutationOptsReturn<T>; /** Get mutation key for QueryClient methods */
   mutationKey: () => HttpMutationKey;
@@ -1151,4 +1154,4 @@ declare function useUploadMutationOptions<TGenerateUrlMutation extends FunctionR
  */
 declare function createVanillaCRPCProxy<TApi extends Record<string, unknown>>(api: TApi, meta: CallerMeta, convexClient: ConvexReactClient$1, transformer?: DataTransformerOptions): VanillaCRPCClient<TApi>;
 //#endregion
-export { AUTH_SESSION_SYNC_GRACE_MS, AuthMutationError, AuthProvider, AuthStore, AuthStoreState, Authenticated, CRPCHttpOptions, ConvexAuthBridge, ConvexAuthRecovery, ConvexAuthRecoveryError, ConvexAuthRecoveryErrorCode, ConvexAuthRecoveryOptions, ConvexAuthRecoveryStatus, ConvexProvider, ConvexProviderWithAuth, ConvexQueryClient, ConvexQueryClientOptions, ConvexQueryClientSingletonOptions, ConvexReactClient, CreateCRPCContextOptions, FetchAccessTokenContext, FetchAccessTokenFn, HttpCRPCClient, HttpCRPCClientFromRouter, type HttpClientOptions, type HttpFormValue, type HttpInputArgs, HttpMutationKey, HttpProxyOptions, HttpQueryKey, HttpRouteInfo, HttpRouteMap, MaybeAuthenticated, MaybeUnauthenticated, PaginationState, PaginationStatus, Unauthenticated, UseInfiniteQueryResult, VanillaHttpCRPCClient, VanillaHttpCRPCClientFromRouter, createAuthMutations, createCRPCContext, createCRPCOptionsProxy, createHttpProxy, createVanillaCRPCProxy, decodeJwtExp, getConvexQueryClientSingleton, getQueryClientSingleton, isAuthMutationError, isSessionSyncGraceActive, useAuth, useAuthGuard, useAuthState, useAuthStore, useAuthValue, useConvex, useConvexActionOptions, useConvexActionQueryOptions, useSafeConvexAuth as useConvexAuth, useSafeConvexAuth, useConvexAuthBridge, useConvexAuthRecovery, useConvexInfiniteQueryOptions, useConvexMutationOptions, useConvexQueryClient, useConvexQueryOptions, useFetchAccessToken, useFnMeta, useInfiniteQuery, useIsAuth, useMaybeAuth, useMeta, useUploadMutationOptions };
+export { AUTH_SESSION_SYNC_GRACE_MS, AuthMutationError, AuthProvider, AuthStore, AuthStoreState, Authenticated, CRPCHttpOptions, ConvexAuthBridge, ConvexAuthRecovery, ConvexAuthRecoveryError, ConvexAuthRecoveryErrorCode, ConvexAuthRecoveryOptions, ConvexAuthRecoveryStatus, ConvexProvider, ConvexProviderWithAuth, ConvexQueryClient, ConvexQueryClientOptions, ConvexQueryClientSingletonOptions, ConvexReactClient, CreateCRPCContextOptions, FetchAccessTokenContext, FetchAccessTokenFn, HttpCRPCClient, HttpCRPCClientFromRouter, type HttpClientOptions, type HttpFormValue, type HttpInputArgs, type HttpMutationKey, HttpProxyOptions, type HttpQueryKey, type HttpQueryPrefixKey, HttpRouteInfo, HttpRouteMap, MaybeAuthenticated, MaybeUnauthenticated, PaginationState, PaginationStatus, Unauthenticated, UseInfiniteQueryResult, VanillaHttpCRPCClient, VanillaHttpCRPCClientFromRouter, createAuthMutations, createCRPCContext, createCRPCOptionsProxy, createHttpProxy, createVanillaCRPCProxy, decodeJwtExp, getConvexQueryClientSingleton, getQueryClientSingleton, isAuthMutationError, isSessionSyncGraceActive, useAuth, useAuthGuard, useAuthState, useAuthStore, useAuthValue, useConvex, useConvexActionOptions, useConvexActionQueryOptions, useSafeConvexAuth as useConvexAuth, useSafeConvexAuth, useConvexAuthBridge, useConvexAuthRecovery, useConvexInfiniteQueryOptions, useConvexMutationOptions, useConvexQueryClient, useConvexQueryOptions, useFetchAccessToken, useFnMeta, useInfiniteQuery, useIsAuth, useMaybeAuth, useMeta, useUploadMutationOptions };

package/dist/react/index.js

@@ -126,6 +126,38 @@ function getFunctionMeta(path, source) {
 
 //#endregion
 //#region src/crpc/http-types.ts
+/**
+* Build the exact cache key for an HTTP route.
+*
+* Missing args normalize to `{}` so the RSC prefetch, the browser observer, and
+* a hand-written `getQueryData` call all hash to the same key. Every producer
+* of an `httpQuery` cache key goes through here.
+*/
+function buildHttpQueryKey(routeKey, args) {
+	return [
+		"httpQuery",
+		routeKey,
+		args ?? {}
+	];
+}
+/**
+* Build the route-wide prefix key.
+*
+* Filters match on prefix, so this matches every args variant of the route.
+* Not a cache key: nothing is ever stored under it.
+*/
+function buildHttpQueryPrefixKey(routeKey) {
+	return ["httpQuery", routeKey];
+}
+/**
+* Freshness window for `crpc.http.*` routes, in milliseconds.
+*
+* HTTP routes are a pull model with no push channel, so hydrated data needs a
+* real freshness window or the browser refetches it on mount. The RSC
+* QueryClient reads the same constant, so the server dedupe window and the
+* client freshness window cannot drift apart.
+*/
+const HTTP_DEFAULT_STALE_TIME = 3e4;
 /** HTTP client error */
 var HttpClientError = class extends Error {
 	name = "HttpClientError";
@@ -278,6 +310,7 @@ const DATE_CODEC_TAG = "$date";
 */
 const dateWireCodec = {
 	tag: DATE_CODEC_TAG,
+	objectsOnly: true,
 	isType: (value) => value instanceof Date,
 	encode: (value) => value.getTime(),
 	decode: (value) => {
@@ -286,6 +319,40 @@ const dateWireCodec = {
 	}
 };
 /**
+* One value per primitive `typeof` result, plus the values the object fast path
+* would otherwise skip.
+*/
+const PRIMITIVE_PROBES = [
+	void 0,
+	null,
+	"",
+	0,
+	NaN,
+	false,
+	0n,
+	Symbol("kitcn.codec.probe"),
+	() => void 0
+];
+/**
+* Falsify an `objectsOnly` declaration against representative primitives.
+*
+* Sampling cannot prove a predicate object-only, so it never *infers* the
+* capability - it only rejects the misdeclarations it can catch
+* (`typeof value === 'bigint'`, `value === null`, ...) before they silently
+* drop a value's wire encoding. A codec that throws on a probe owns that.
+*/
+const assertObjectsOnly = (codec) => {
+	for (const probe of PRIMITIVE_PROBES) {
+		let claimed = false;
+		try {
+			claimed = codec.isType(probe);
+		} catch {
+			continue;
+		}
+		if (claimed) throw new Error(`Wire codec '${codec.tag}' declares objectsOnly, but isType() claims ${probe === null ? "null" : typeof probe}. Drop objectsOnly so the codec keeps receiving non-object values.`);
+	}
+};
+/**
 * Build a recursive tagged transformer from codecs.
 */
 const createTaggedTransformer = (codecs) => {
@@ -293,9 +360,12 @@ const createTaggedTransformer = (codecs) => {
 	for (const codec of codecs) {
 		if (!codec.tag.startsWith("$")) throw new Error(`Invalid wire codec tag '${codec.tag}'. Tags must start with '$'.`);
 		if (codecByTag.has(codec.tag)) throw new Error(`Duplicate wire codec tag '${codec.tag}'.`);
+		if (codec.objectsOnly) assertObjectsOnly(codec);
 		codecByTag.set(codec.tag, codec);
 	}
+	const skipNonObjects = codecs.every((codec) => codec.objectsOnly === true);
 	const serialize = (value) => {
+		if (skipNonObjects && (value === null || typeof value !== "object")) return value;
 		for (const codec of codecs) if (codec.isType(value)) return {
 			[CODEC_MARKER_KEY]: CODEC_MARKER_VALUE,
 			[CODEC_TAG_KEY]: codec.tag,
@@ -329,6 +399,7 @@ const createTaggedTransformer = (codecs) => {
 		return value;
 	};
 	const deserialize = (value) => {
+		if (value === null || typeof value !== "object") return value;
 		if (Array.isArray(value)) {
 			let result;
 			for (let index = 0; index < value.length; index += 1) {
@@ -394,16 +465,20 @@ const normalizeCustomTransformer = (transformer) => {
 * - deserialize: default(Date) -> user
 */
 const composeWithDefault = (transformer) => {
-	if (!transformer) return defaultCRPCTransformer;
+	if (!transformer || transformer === defaultCRPCTransformer) return defaultCRPCTransformer;
 	return {
 		serialize: (value) => defaultCRPCTransformer.serialize(transformer.serialize(value)),
 		deserialize: (value) => transformer.deserialize(defaultCRPCTransformer.deserialize(value))
 	};
 };
 const transformerCache = /* @__PURE__ */ new WeakMap();
+transformerCache.set(DEFAULT_COMBINED_TRANSFORMER, DEFAULT_COMBINED_TRANSFORMER);
 /**
 * Normalize transformer config to split input/output shape.
 * User transformers are additive and always composed with default Date handling.
+*
+* Idempotent: passing a transformer this function already resolved returns it
+* unchanged.
 */
 const getTransformer = (transformer) => {
 	if (!transformer) return DEFAULT_COMBINED_TRANSFORMER;
@@ -416,6 +491,7 @@ const getTransformer = (transformer) => {
 		output: composeWithDefault(custom?.output)
 	};
 	transformerCache.set(cacheKey, resolved);
+	transformerCache.set(resolved, resolved);
 	return resolved;
 };
 /**
@@ -480,12 +556,9 @@ function createRecursiveHttpProxy(opts, path = []) {
 			if (!route) throw new Error(`Unknown HTTP procedure: ${routeKey}`);
 			if (route.method !== "GET") throw new Error(`queryOptions is only available for GET endpoints, got ${route.method} for ${routeKey}`);
 			return (args, queryOpts) => ({
+				staleTime: HTTP_DEFAULT_STALE_TIME,
 				...queryOpts,
-				queryKey: [
-					"httpQuery",
-					routeKey,
-					args
-				],
+				queryKey: buildHttpQueryKey(routeKey, args),
 				queryFn: async () => {
 					try {
 						return await executeHttpRequest({
@@ -504,22 +577,12 @@ function createRecursiveHttpProxy(opts, path = []) {
 				}
 			});
 		}
-		if (prop === "queryKey") return (args) => {
-			return args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0) ? [
-				"httpQuery",
-				routeKey,
-				args
-			] : ["httpQuery", routeKey];
-		};
+		if (prop === "queryKey") return (args) => buildHttpQueryKey(routeKey, args);
 		if (prop === "queryFilter") return (args, filters) => {
 			const hasArgs = args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0);
 			return {
 				...filters,
-				queryKey: hasArgs ? [
-					"httpQuery",
-					routeKey,
-					args
-				] : ["httpQuery", routeKey]
+				queryKey: hasArgs ? buildHttpQueryKey(routeKey, args) : buildHttpQueryPrefixKey(routeKey)
 			};
 		};
 		if (prop === "mutationOptions") {

package/dist/rsc/index.d.ts

@@ -1,7 +1,7 @@
 import { n as DeepPartial, o as Simplify, r as DistributiveOmit } from "../types-DF2cg_w0.js";
-import { C as HttpProcedure, d as CRPCHttpRouter, j as DataTransformerOptions, p as HttpRouterRecord } from "../http-types-zsMHb_QN.js";
+import { L as DataTransformerOptions, _ as CRPCHttpRouter, c as HttpQueryKey, k as HttpProcedure, o as HttpMutationKey, y as HttpRouterRecord } from "../http-types-DXOgaerG.js";
 import { g as UnsetMarker } from "../types-CnTpHR1F.js";
-import { A as HttpInputArgs, C as ReservedMutationOptions$1, S as ReservedInfiniteQueryOptions, T as StaticQueryOptsParam, _ as IsPaginated, b as PaginatedFnMeta, c as ConvexMutationKey, d as ConvexQueryMeta, f as EmptyObject, g as InfiniteQueryInput, l as ConvexQueryHookOptions, m as FUNC_REF_SYMBOL, o as ConvexActionKey, p as ExtractPaginatedItem, s as ConvexInfiniteQueryMeta, u as ConvexQueryKey, w as ReservedQueryOptions$1, y as MutationVariables } from "../types-jNTcza_a.js";
+import { A as HttpInputArgs, C as ReservedMutationOptions$1, S as ReservedInfiniteQueryOptions, T as StaticQueryOptsParam, _ as IsPaginated, b as PaginatedFnMeta, c as ConvexMutationKey, d as ConvexQueryMeta, f as EmptyObject, g as InfiniteQueryInput, l as ConvexQueryHookOptions, m as FUNC_REF_SYMBOL, o as ConvexActionKey, p as ExtractPaginatedItem, s as ConvexInfiniteQueryMeta, u as ConvexQueryKey, w as ReservedQueryOptions$1, y as MutationVariables } from "../types-BHR7ZKKD.js";
 import { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
 import { z } from "zod";
 import { DefaultError, QueryFilters, SkipToken, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
@@ -137,9 +137,6 @@ type InferHttpClientArgs<T> = T extends HttpProcedure<infer TInput, infer _TOutp
 }> : HttpInputArgs;
 /** Infer output type from HttpProcedure */
 type InferHttpOutput<T> = T extends HttpProcedure<infer _TInput, infer TOutput, infer _TParams, infer _TQuery> ? TOutput extends UnsetMarker ? unknown : TOutput extends z.ZodTypeAny ? z.infer<TOutput> : unknown : unknown;
-/** Query key with args (3-element) or prefix key without args (2-element) for invalidation */
-type HttpQueryKey = readonly ['httpQuery', string, unknown] | readonly ['httpQuery', string];
-type HttpMutationKey = readonly ['httpMutation', string];
 type ReservedQueryOptions = 'queryKey' | 'queryFn';
 type ReservedMutationOptions = 'mutationFn';
 /** Query options for GET HTTP endpoints - compatible with both useQuery and useSuspenseQuery */
@@ -158,8 +155,8 @@ type HttpMutationOptions<T extends HttpProcedure> = DistributiveOmit<HttpMutatio
  * - mutationOptions: For one-time actions like exports (useMutation)
  */
 type DecorateHttpQuery<T extends HttpProcedure> = {
-  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get query key for QueryClient methods (with args = exact match, without = prefix) */
-  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter for QueryClient methods (e.g., invalidateQueries) */
+  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get the exact cache key these args are stored under (getQueryData/setQueryData) */
+  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter matching every args variant (e.g., invalidateQueries) */
   queryFilter: (args?: InferHttpClientArgs<T>, filters?: DistributiveOmit<QueryFilters, 'queryKey'>) => QueryFilters; /** Mutation options for GET endpoints (exports, downloads - no caching) */
   mutationOptions: (opts?: HttpMutationOptions<T>) => HttpMutationOptsReturn<T>; /** Get mutation key for QueryClient methods */
   mutationKey: () => HttpMutationKey;